# @lunit/oui — Component Catalog

A scannable index of components for AI/developers. Each entry: **what it is · key props · example**.
The exact props are defined by each component's `*.types.ts` (source of truth). When you add a new component, add a line here too.

## Install & Setup

```bash
npm i --save @lunit/oui
```

Wrap your app root with `ThemeProvider` to inject the OUI theme so every component renders correctly.

```tsx
import { ThemeProvider, CssBaseline } from '@mui/material';
import { theme } from '@lunit/oui';

<ThemeProvider theme={theme}>
  <CssBaseline />
  <App />
</ThemeProvider>;
```

## Import paths

```ts
import { Button, Dialog, TextField } from '@lunit/oui'; // components
import { ArrowDoubleDown } from '@lunit/oui/icons'; // icons
import { theme, palette, typography, spacing } from '@lunit/oui'; // theme & tokens
```

❌ Do not import Button/TextField etc. directly from `@mui/material`. ✅ Prefer the equivalent `@lunit/oui` component.

---

## Components

### Input / Form

| Component                         | Purpose                                                  | Key props                                                                                                                                                         |
| --------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Button**                        | Trigger actions. Supports label/icon buttons and loading | `variant: 'contained' \| 'ghost' \| 'outlined'`, `color: 'primary' \| 'secondary' \| 'error'`, `size: 'small' \| 'medium' \| 'large'`, `label`, `icon`, `loading` |
| **TextField** / **BaseTextField** | Text input                                               | extends MUI TextField                                                                                                                                             |
| **Checkbox**                      | Checkbox                                                 | —                                                                                                                                                                 |
| **Radio**                         | Radio button                                             | —                                                                                                                                                                 |
| **Toggle**                        | on/off switch                                            | —                                                                                                                                                                 |
| **Dropdown**                      | Selection dropdown                                       | —                                                                                                                                                                 |
| **Autocomplete**                  | Multi-select chip input with clear button + loading      | `placeholder`, `error`, `helperText`, `loading`, `noOptionsText`, `onDelete`, `onClearButtonClick`                                                                |
| **DatePicker**                    | Date selection (based on `@mui/x-date-pickers`)          | —                                                                                                                                                                 |
| **FileDnDZone**                   | File drag-and-drop area                                  | —                                                                                                                                                                 |
| **UploadManager**                 | Upload progress/management UI                            | —                                                                                                                                                                 |

### Display / Layout

| Component              | Purpose                                         | Key props                                               |
| ---------------------- | ----------------------------------------------- | ------------------------------------------------------- |
| **Card**               | Content card container                          | `size: 'small' \| 'large'`                              |
| **Divider**            | Separator line                                  | `orientation: 'horizontal' \| 'vertical'`               |
| **Drawer**             | Side drawer with collapsed/expanded/wide widths | `open`, `wide`, `closedWidth`, `openWidth`, `wideWidth` |
| **Collapse**           | Expand/collapse transition wrapper              | extends MUI Collapse (`in`, `orientation`, `timeout`)   |
| **List**               | List                                            | `size: 'small' \| 'medium' \| 'large'`                  |
| **DataTable**          | Data table (based on `@mui/x-data-grid`)        | —                                                       |
| **EllipsisTypography** | Text with ellipsis (...) truncation             | —                                                       |
| **ProductLabel**       | Product label badge                             | —                                                       |
| **NoMatchContainer**   | Empty state (e.g. no search results)            | —                                                       |

### Feedback / Overlay

| Component            | Purpose                                          | Key props                                                |
| -------------------- | ------------------------------------------------ | -------------------------------------------------------- |
| **Alert**            | Inline notification (info/success/error/warning) | —                                                        |
| **Dialog**           | Modal dialog                                     | —                                                        |
| **Popover**          | Anchored overlay with tokenized paper styling    | extends MUI Popover (`open`, `anchorEl`, `anchorOrigin`) |
| **Tooltip**          | Tooltip                                          | `size: 'small' \| 'large'`, `placement`                  |
| **Progress**         | Progress indicator (Circular/Linear)             | `CircularProgress`: `size`, `circleColor`                |
| **LoadingIndicator** | Loading spinner                                  | —                                                        |
| **Chip**             | Chip/tag                                         | `preset` (ChipsPreset)                                   |

### Navigation / Structure

| Component       | Purpose                 | Key props                                                    |
| --------------- | ----------------------- | ------------------------------------------------------------ |
| **Menu**        | Menu                    | `size: 'small' \| 'medium'`                                  |
| **Pagination**  | Pagination              | `size: number`                                               |
| **Stepper**     | Step progress indicator | —                                                            |
| **TabbedPanel** | Tab panel               | `size: 'small' \| 'medium'`, `variant: 'normal' \| 'toggle'` |

### Utility

| Component          | Purpose                       |
| ------------------ | ----------------------------- |
| **ResizeObserver** | Size-change detection wrapper |

---

## Presentations (domain-specific components)

Exported together from `@lunit/oui`. Composite components for the oncology analysis domain.

`Accordion`, `AnalysisBar`, `FreeText`, `Histogram`, `HorizonDivider`, `ModelType`, `Preview`, `Score`, `Statistic`, `Threshold`, `ToggleControl`, `ToggleControlGroup`

---

## Usage examples

```tsx
import { Button, Dialog } from '@lunit/oui';

// basic button
<Button variant="contained" color="primary" size="medium" label="Save" onClick={save} />

// loading state
<Button variant="contained" loading label="Processing" />

// icon button
import { Close } from '@lunit/oui/icons';
<Button icon={<Close />} onClick={close} />
```

### Do / Don't

- ✅ Use only the union values defined above for variant/size/color.
- ✅ Use `theme.palette.*` / `theme.spacing()` tokens for color and spacing (→ [TOKENS.md](TOKENS.md)).
- ❌ Do not use the equivalent `@mui/material` component directly.
- ❌ Do not hardcode magic values like `#fff` or `16px` in `sx`.