npm package: @quable/ui
Description: A TypeScript React component library with Material-UI integration and custom styling
Author: Quable Team
Latest version: 0.0.22

# @quable/ui

A modern TypeScript React component library built on top of MUI v5 with a consistent look-and-feel and sensible defaults.

## Features

- 🚀 TypeScript types included
- ⚛️ React 18 and 19 compatible
- 🎨 MUI v5 theming out-of-the-box
- 💅 Prebuilt CSS with SCSS-based styles in source
- 📦 ESM-first with CJS fallback for Node bundlers
- 🧪 Storybook and Jest test setup

## Installation

🤝 We prefer pnpm but feel free to use npm, yarn, bun, or whatever package manager you like:

```bash
pnpm add @quable/ui
```

Additional peer dependencies

The library depends on several peer packages. Most are required by the library (install them in your host application). The Froala editor is optional and only needed if you use the `RichTextEditor` component.

Install required peers:

```bash
# UI & core
pnpm add @mui/material@^5 @emotion/react @emotion/styled @mui/icons-material@^5

# MUI extras
pnpm add @mui/x-data-grid-pro@^6 @mui/x-date-pickers-pro@^6

# Utilities & common extras
pnpm add moment react-arborist react-beautiful-dnd @types/react-beautiful-dnd react-dropzone react-i18next react-sortable-hoc react-toastify
```

Optional (only if you use RichTextEditor):

```bash
pnpm add froala-editor react-froala-wysiwyg
```

## Usage

1) Import the theme provider and styles in your app entry:

```tsx
import { ThemeContextProvider } from '@quable/ui/theme'

import '@quable/ui/theme/index.css'
import '@quable/ui/index.css'
```

2) Wrap your app with the ThemeContextProvider to get the exact theme:

```tsx
import { ThemeContextProvider } from '@quable/ui/theme'
import { Button } from '@quable/ui'

import '@quable/ui/theme/index.css'
import '@quable/ui/index.css'

export function App() {
  return (
    <ThemeContextProvider>
      <Button color="primary">Click me!</Button>
    </ThemeContextProvider>
  )
}
```

3) Import and use components as named imports:

```tsx
import { Button, TextField, Autocomplete } from '@quable/ui'

export function MyComponent() {
  return (
    <div>
      <TextField label="Name" />
      <Button>Submit</Button>
    </div>
  )
}
```

## Theming

The library ships with a multi-theme system. Each theme targets a specific IbexaOne business unit and exposes its own `ThemeProvider` component and CSS bundle.

### Available themes

| Import path                   | Provider                   | Brand             |
|-------------------------------|----------------------------|-------------------|
| `@quable/ui/themes/quable`    | `QuableThemeProvider`      | IbexaOne / Quable |
| `@quable/ui/themes/actito`    | `ActitoThemeProvider`      | IbexaOne / Actito |
| `@quable/ui/themes/raptor`    | `RaptorThemeProvider`      | IbexaOne / Raptor |
| `@quable/ui/themes/qualifio`  | `QualifioThemeProvider`    | IbexaOne / Qualifio |
| `@quable/ui/themes/cohesivo`  | `CohesivoThemeProvider`    | IbexaOne / Cohesivo |
| `@quable/ui/themes/ibexaop`   | `IbexaOPThemeProvider`     | IbexaOne / IbexaOP |

> **Backward compatibility** — The legacy `@quable/ui/theme` entry point (the original Quable theme) is still available and unchanged. Existing apps that import from `@quable/ui/theme` require no migration.

### Using a brand theme

Each theme provides a dedicated provider and its own CSS bundle. Load both on the page where you want the theme to apply:

```tsx
import { ActitoThemeProvider } from '@quable/ui/themes/actito'
import '@quable/ui/themes/actito/index.css' // brand CSS variables
import '@quable/ui/index.css'               // component styles (shared)

export function ActitoPage() {
  return (
    <ActitoThemeProvider>
      <MyPageContent />
    </ActitoThemeProvider>
  )
}
```

### Per-page theming

Because each theme's CSS bundle is self-contained, different pages in the same app can load different themes independently:

```tsx
// pages/ActitoPage.tsx
import { ActitoThemeProvider } from '@quable/ui/themes/actito'
import '@quable/ui/themes/actito/index.css'

// pages/RaptorPage.tsx
import { RaptorThemeProvider } from '@quable/ui/themes/raptor'
import '@quable/ui/themes/raptor/index.css'
```

> **Note** — Theme CSS bundles set CSS custom properties on `:root`. Only one theme's CSS should be active at a time per page. When using lazy-loaded routes each page loads its own theme bundle naturally.

### All themes barrel

You can also import everything from the single barrel if you need to reference multiple themes at once:

```tsx
import {
  QuableThemeProvider,
  ActitoThemeProvider,
  type ThemeName
} from '@quable/ui/themes'
```

## Available components (selection)

- Actions: Button
- Forms: Autocomplete, Checkbox, Chip, ChoiceList, ColorPicker, DateField, DateRangePicker, DropZone, InlineError, Label, ListItems, NumberField, PasswordField, Radio, RichTextEditor, Select, Switch, TextArea, TextField, TimeField, ToggleButtonGroup
- Table: TransferListInput

📖 **Explore them all in our live Storybook documentation:** https://quable-ui-storybook.web.app/

## Special Component Documentation

Some components require additional setup or have specific considerations:

- **[RichTextEditor](./src/components/forms/RichTextEditor/README.md)** - Comprehensive guide for using the rich text editor, including SSR setup for Next.js

## Peer dependencies

Ensure the following are installed in your host app:

**Required:**
- react >= 18.0.0 < 20.0.0
- react-dom >= 18.0.0 < 20.0.0
- @mui/material >= 5.18.0 < 8.0.0
- @emotion/react ^11.14.0
- @emotion/styled ^11.14.0
- @mui/icons-material ^5.18.0

**Optional (depending on components used):**
- @mui/x-data-grid-pro ^6.20.4
- @mui/x-date-pickers-pro ^6.20.2
- @types/react-beautiful-dnd ^13.1.8
- froala-editor ^4.6.2
- moment ^2.30.1
- react-arborist ^3.4.3
- react-beautiful-dnd ^13.1.1
- react-dropzone ^14.3.8
- react-froala-wysiwyg ^4.6.2
- react-i18next >= 11.0.0 < 16.0.0
- react-sortable-hoc ^2.0.0
- react-toastify ^11.0.5

## Project scripts

```bash
# Install dependencies
pnpm install

# Storybook (component docs & playground)
pnpm storybook

# Run tests
pnpm test

# Build the library (dist/)
pnpm build

# Lint & format
pnpm lint
pnpm format
```

## Packaging

- ESM entry: `index.js`
- CJS entry: `index.cjs`
- Types: `index.d.ts`
- Legacy theme provider (backward compat): `@quable/ui/theme`
- IbexaOne brand themes: `@quable/ui/themes/{brand}`
- Styles: `@quable/ui/theme/index.css` and `@quable/ui/index.css`

## License

MIT © Quable Team