npm package: @phygitallabs/core-ui
Description: A comprehensive React UI component library built with TypeScript, Ant Design, and styled-components. This unified package consolidates ui-nomion, nomion-ui, and ui-rich-editor into a single optimized library.
Latest version: 6.1.2

# @phygitallabs/core-ui

A comprehensive React UI component library built with TypeScript, Ant Design, and styled-components. This unified package consolidates ui-nomion, nomion-ui, and ui-rich-editor into a single optimized library.

## Features

- **34 Entry Points** - 29 production-ready components + utilities
- **Tree-Shakable** - Import only what you need with granular entry points
- **TypeScript First** - Fully typed components and APIs
- **Styled Components** - Flexible styling with theme support
- **Rich Text Editor** - Full WYSIWYG editor with Lexical
- **Dual Format** - ESM and CommonJS support
- **Accessible** - WCAG compliant components
- **Responsive** - Mobile-first design approach

## Installation

```bash
npm install @phygitallabs/core-ui
# or
pnpm add @phygitallabs/core-ui
# or
yarn add @phygitallabs/core-ui
```

### Peer Dependencies

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

## Quick Start

```tsx
import React from "react";
import { Button } from "@phygitallabs/core-ui/components/button";
import { TextField } from "@phygitallabs/core-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 "@phygitallabs/core-ui/components/button";
import { TextField } from "@phygitallabs/core-ui/components/text-field";
import { Modal } from "@phygitallabs/core-ui/components/modal";

// Form components
import { FormProvider, FormTextField, FormSelect } from "@phygitallabs/core-ui/components/form";

// Selectors
import { Radio, Checkbox, Toggle, DatePicker } from "@phygitallabs/core-ui/components/selector";

// Typography
import { Display, Heading, Body } from "@phygitallabs/core-ui/components/typography";

// Rich text editor
import { LexicalRichText } from "@phygitallabs/core-ui/components/rich-editor";

// Utilities
import { useModal } from "@phygitallabs/core-ui/hooks";
import { ModalProvider } from "@phygitallabs/core-ui/context";
import { colors } from "@phygitallabs/core-ui/theme";
```

### Alternative: Full Bundle

Import from the main entry (includes all components):

```tsx
import { Button, TextField, Modal } from "@phygitallabs/core-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

### Images

- **Image** - Optimized image component (styled-components)
- **ImageNomion** - CDN-optimized image component (Tailwind)

### Rich Text Editor

- **LexicalRichText** - Full WYSIWYG editor with toolbar

### Other

- **Button** - Customizable button component
- **Pagination** - Pagination controls
- **ColorPalette** - Color palette showcase

## Available Entry Points

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

### Rich Text Editor Example

```tsx
import React from "react";
import { LexicalRichText } from "@phygitallabs/core-ui/components/rich-editor";
import type { EditorStateChangePayload } from "@phygitallabs/core-ui/components/rich-editor";

function RichTextExample() {
  const handleChange = (payload: EditorStateChangePayload) => {
    console.log("Editor state:", payload);
  };

  return (
    <LexicalRichText
      initialState={undefined}
      onEditorStateChange={handleChange}
      toolbarConfigs={{
        hasImage: false,
        hasVideo: false,
        hasHeading: true,
        hasLink: true,
        hasList: true,
        hasAlignment: true,
        hasColor: true,
      }}
      editable={true}
    />
  );
}
```

### Modal Example

```tsx
import React from "react";
import { Modal } from "@phygitallabs/core-ui/components/modal";
import { Button } from "@phygitallabs/core-ui/components/button";
import { useModal } from "@phygitallabs/core-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 "@phygitallabs/core-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 "@phygitallabs/core-ui/components/message";
import { Button } from "@phygitallabs/core-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 "@phygitallabs/core-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 "@phygitallabs/core-ui/components/button";
import { TextField, type TextFieldVariant } from "@phygitallabs/core-ui/components/text-field";

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

## Migration Guide

### From pgl-nomion-ui

```tsx
// Before
import { Button } from "pgl-nomion-ui/components/button";

// After
import { Button } from "@phygitallabs/core-ui/components/button";
```

### From nomion-ui

```tsx
// Before
import { Image } from "nomion-ui";

// After
import { ImageNomion } from "@phygitallabs/core-ui/components/image-nomion";
```

### From nomion-rich-editor

```tsx
// Before
import { LexicalRichText } from "nomion-rich-editor";

// After
import { LexicalRichText } from "@phygitallabs/core-ui/components/rich-editor";
```

## Browser Support

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

## Contributing

See [EXPORTS.md](./EXPORTS.md) for complete export list and component details.

## License

Private package for internal use.

## Links

- [Export Reference](./EXPORTS.md)
- [Merge Summary](./MERGE_SUMMARY.md)
- [Storybook Documentation](./README-storybook.md)