npm package: @phygitallabs/portal-ui
Description: A comprehensive React UI component library built with TypeScript, Ant Design, and styled-components.
Latest version: 1.0.0

# pgl-nomion-ui

A comprehensive React UI component library built with TypeScript, Ant Design, and styled-components.

## Features

- 🎨 **27+ Production-Ready Components** - Buttons, Forms, Tables, Modals, and more
- 📦 **Tree-Shakable** - Import only what you need with multiple entry points
- 🎯 **TypeScript First** - Fully typed components and APIs
- 🎭 **Styled Components** - Flexible styling with theme support
- ♿ **Accessible** - WCAG compliant components
- 🔄 **Dual Format** - ESM and CommonJS support
- 📱 **Responsive** - Mobile-first design approach

## Installation

```bash
npm install pgl-nomion-ui
# or
pnpm add pgl-nomion-ui
# or
yarn add pgl-nomion-ui
```

### Peer Dependencies

```bash
npm install react react-dom styled-components
```

## Quick Start

```tsx
import React from 'react';
import { Button } from 'pgl-nomion-ui/components/button';
import { TextField } from 'pgl-nomion-ui/components/text-field';

function App() {
  return (
    <div>
      <TextField placeholder="Enter your name" />
      <Button variant="primary">Submit</Button>
    </div>
  );
}
```

## Import Strategies

### Recommended: Component Entry Points

For optimal bundle size, import components from their specific entry points:

```tsx
// Individual components
import { Button } from 'pgl-nomion-ui/components/button';
import { TextField } from 'pgl-nomion-ui/components/text-field';
import { Modal } from 'pgl-nomion-ui/components/modal';

// Form components
import {
  FormProvider,
  FormTextField,
  FormSelect
} from 'pgl-nomion-ui/components/form';

// Selectors
import {
  Radio,
  Checkbox,
  Toggle,
  DatePicker
} from 'pgl-nomion-ui/components/selector';

// Typography
import { Display, Heading, Body } from 'pgl-nomion-ui/components/typography';

// Utilities
import { useModal } from 'pgl-nomion-ui/hooks';
import { ModalProvider } from 'pgl-nomion-ui/context';
import { colors } from 'pgl-nomion-ui/theme';
```

### Alternative: Full Bundle

Import from the main entry (includes all components):

```tsx
import { Button, TextField, Modal } from 'pgl-nomion-ui';
```

⚠️ **Note**: This imports the entire library. Use entry points for better tree-shaking.

## Available Components

### Layout & Navigation
- **Sidebar** - Collapsible navigation sidebar
- **Menu** - Navigation menu component
- **Tabs** - Tabbed content interface

### Data Display
- **Table** - Feature-rich data table with sorting and pagination
- **List** - Styled list component
- **Collapse** - Expandable/collapsible content panels
- **Steps** - Step-by-step process indicator
- **Badge** - Status badges and labels
- **Label** - Text labels with variants

### Form Components
- **TextField** - Text input with variants
- **TextArea** - Multi-line text input
- **SearchBar** - Search input component
- **Select** - Dropdown select component
- **Radio** - Radio button and radio group
- **Checkbox** - Checkbox and checkbox group
- **Toggle** - Toggle switch
- **DatePicker** - Date selection component
- **TimePicker** - Time selection component
- **Stepper** - Numeric stepper input
- **Upload** - File upload component

### Form Integration (React Hook Form)
- **FormProvider** - Form context provider
- **FormTextField** - Integrated text field
- **FormTextArea** - Integrated text area
- **FormSelect** - Integrated select
- **FormRadio** - Integrated radio group
- **FormCheckbox** - Integrated checkbox
- **FormToggle** - Integrated toggle
- **FormUpload** - Integrated file upload
- **FormLexicalInput** - Rich text editor
- **FormColorInput** - Color picker

### Feedback
- **Modal** - Dialog/modal component
- **Drawer** - Slide-out drawer panel
- **Popover** - Popover overlay
- **Tooltip** - Tooltip component
- **Toast** - Toast notifications (via `toast` function)
- **Toaster** - Toast container component
- **Spin** - Loading spinner
- **Skeleton** - Loading skeleton placeholder

### Typography
- **Display** - Display text (largest heading)
- **Heading** - Heading variants (H1-H5)
- **Body** - Body text with sizes

### Other
- **Button** - Customizable button component
- **Image** - Optimized image component
- **Pagination** - Pagination controls
- **ColorPalette** - Color palette showcase

## Available Entry Points

| Entry Point | Exports |
|------------|---------|
| `pgl-nomion-ui` | All components (full bundle) |
| `pgl-nomion-ui/components/button` | Button |
| `pgl-nomion-ui/components/typography` | Display, Heading, Body |
| `pgl-nomion-ui/components/text-field` | TextField |
| `pgl-nomion-ui/components/text-area` | TextArea |
| `pgl-nomion-ui/components/search-bar` | SearchBar |
| `pgl-nomion-ui/components/table` | Table |
| `pgl-nomion-ui/components/selector` | Radio, RadioGroup, Checkbox, CheckboxGroup, Toggle, Stepper, Select, DatePicker, TimePicker |
| `pgl-nomion-ui/components/form` | FormProvider, FormTextField, FormTextArea, FormCheckbox, FormRadio, FormSelect, FormToggle, FormUpload, FormLexicalInput, FormColorInput |
| `pgl-nomion-ui/components/message` | toast, Toaster |
| `pgl-nomion-ui/components/modal` | Modal |
| `pgl-nomion-ui/components/drawer` | Drawer |
| `pgl-nomion-ui/components/popover` | Popover |
| `pgl-nomion-ui/components/tooltip` | Tooltip, TooltipOption |
| `pgl-nomion-ui/components/tabs` | Tabs, TabPane, createTab |
| `pgl-nomion-ui/components/sidebar` | Sidebar |
| `pgl-nomion-ui/components/menu` | Menu |
| `pgl-nomion-ui/components/upload` | Upload |
| `pgl-nomion-ui/components/skeleton` | Skeleton |
| `pgl-nomion-ui/components/spin` | Spin |
| `pgl-nomion-ui/components/image` | Image |
| `pgl-nomion-ui/components/steps` | Steps |
| `pgl-nomion-ui/components/label` | Label |
| `pgl-nomion-ui/components/badge` | Badge |
| `pgl-nomion-ui/components/pagination` | Pagination |
| `pgl-nomion-ui/components/collapse` | Collapse |
| `pgl-nomion-ui/components/list` | List |
| `pgl-nomion-ui/components/color-palette` | ColorPalette |
| `pgl-nomion-ui/hooks` | All custom hooks |
| `pgl-nomion-ui/context` | ModalProvider |
| `pgl-nomion-ui/theme` | colors, semanticColors, design tokens |
| `pgl-nomion-ui/icons` | Icon components |

## Usage Examples

### Form Example with React Hook Form

```tsx
import React from 'react';
import { useForm } from 'react-hook-form';
import {
  FormProvider,
  FormTextField,
  FormSelect
} from 'pgl-nomion-ui/components/form';
import { Button } from 'pgl-nomion-ui/components/button';
import { toast } from 'pgl-nomion-ui/components/message';

function ContactForm() {
  const methods = useForm();

  const onSubmit = (data) => {
    console.log(data);
    toast.success('Form submitted!');
  };

  return (
    <FormProvider methods={methods} onSubmit={onSubmit}>
      <FormTextField
        name="name"
        title="Name"
        required
        placeholder="Enter your name"
      />

      <FormTextField
        name="email"
        title="Email"
        type="email"
        required
        placeholder="your@email.com"
      />

      <FormSelect
        name="country"
        title="Country"
        options={[
          { label: 'USA', value: 'us' },
          { label: 'UK', value: 'uk' },
        ]}
      />

      <Button type="submit">Submit</Button>
    </FormProvider>
  );
}
```

### Modal Example

```tsx
import React from 'react';
import { Modal } from 'pgl-nomion-ui/components/modal';
import { Button } from 'pgl-nomion-ui/components/button';
import { useModal } from 'pgl-nomion-ui/hooks';

function ModalExample() {
  const { isOpen, open, close } = useModal();

  return (
    <>
      <Button onClick={open}>Open Modal</Button>

      <Modal
        isOpen={isOpen}
        onClose={close}
        title="Confirm Action"
      >
        <p>Are you sure you want to proceed?</p>
        <Button onClick={close}>Cancel</Button>
        <Button variant="primary" onClick={() => {
          // Do something
          close();
        }}>
          Confirm
        </Button>
      </Modal>
    </>
  );
}
```

### Table Example

```tsx
import React from 'react';
import { Table } from 'pgl-nomion-ui/components/table';

function DataTable() {
  const columns = [
    { title: 'Name', dataIndex: 'name', key: 'name' },
    { title: 'Age', dataIndex: 'age', key: 'age' },
    { title: 'Email', dataIndex: 'email', key: 'email' },
  ];

  const data = [
    { key: '1', name: 'John Doe', age: 32, email: 'john@example.com' },
    { key: '2', name: 'Jane Smith', age: 28, email: 'jane@example.com' },
  ];

  return <Table columns={columns} dataSource={data} />;
}
```

### Toast Notifications

```tsx
import React from 'react';
import { toast, Toaster } from 'pgl-nomion-ui/components/message';
import { Button } from 'pgl-nomion-ui/components/button';

function App() {
  return (
    <>
      <Toaster />
      <Button onClick={() => toast.success('Success!')}>
        Show Success
      </Button>
      <Button onClick={() => toast.error('Error occurred')}>
        Show Error
      </Button>
    </>
  );
}
```

## Theme Customization

Access design tokens and colors:

```tsx
import { colors, semanticColors } from 'pgl-nomion-ui/theme';

const MyComponent = styled.div`
  background-color: ${colors['primary-blue-500']};
  color: ${semanticColors['content-primary']};
`;
```

## TypeScript Support

All components are fully typed. Import types alongside components:

```tsx
import { Button, type ButtonProps } from 'pgl-nomion-ui/components/button';
import { TextField, type TextFieldVariant } from 'pgl-nomion-ui/components/text-field';

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

See [ui-nomion.md](./ui-nomion.md) for guidelines on contributing new components.

## License

Private package for internal use.

## Links

- [Component Guidelines](./ui-nomion.md)
- [Storybook Documentation](./README-storybook.md)
- [Example App](./example/README.md)