@dito-uai/components 5.1.0-alpha.66 → 5.1.0-alpha.67

package/llms.md

@@ -0,0 +1,646 @@
+# @dito-uai/components — API reference for LLMs
+
+Package: `@dito-uai/components` (React 18, TypeScript, Tailwind CSS 3, Radix UI, `tailwind-variants`).
+
+## Installation and setup
+
+- **Peers:** `react`, `react-dom`, `zod`, `lucide-react`, `@dito-uai/icons`.
+- **CSS:** `import '@dito-uai/components/global.css'`.
+- **Tailwind:** preset in the package’s `tailwind-preset.ts`; set your app `content` to include files that import these components.
+
+## Design tokens (summary)
+
+- **Colors:** namespaces `neutral`, `brand`, `secondary`, `chart`, `notification` (`COLORS` object in the preset).
+- **Typography:** Poppins in the preset; use the `Text` component for DS type scale.
+- **Spacing:** 8px-based scale in the preset.
+
+## Common pitfalls
+
+1. **`Tabs`:** the package default export is named `Tabs` but the implementation is `TabsLayout`. Props: `TabsLayoutProps`, items: `TabItem[]` with `value`, `content`, `label?`, etc.
+2. **`Message`:** **imperative** API (`Message.success('...')`). You must mount `<MessageContainer />` at the root (e.g. app layout). Uses `react-toastify`.
+3. **`Tooltip`:** wrap the tree with `<TooltipProvider>` where tooltips are used (Radix).
+4. **`Toggle`:** the barrel **only** exports `Toggle` as the namespace from `toggle-group.tsx`: `Toggle.Group` and `Toggle.Item`. The standalone toggle from `toggle.tsx` is **not** re-exported from the package `index.ts`.
+5. **`Loading`:** `size`, `color`, and `fill` use **UPPERCASE** strings (`'NORMAL'`, `'GREEN'`, …), legacy API.
+6. **`Sheet`:** visibility prop is **`isVisible`**, not `visible`.
+7. **`GoToCard`:** polymorphic: `as?: 'button' | 'a' | React.ComponentType` with Link-style props (`to`, etc.) when `as` is a router component.
+8. **Radix:** many components extend Radix props; beyond the props listed below, standard HTML attributes and handlers are usually accepted.
+
+---
+
+## Alert
+
+**Import:** `import { Alert } from '@dito-uai/components'`
+
+**Props (`AlertProps`):** extends `HTMLAttributes<HTMLDivElement>`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `type` | `'success' \| 'warning' \| 'error' \| 'info'` | — | Sets color and icon |
+| `message` | `string \| ReactNode` | — | Main content |
+| `closable` | `boolean` | `false` | Close icon; dismisses on click |
+
+**Example:**
+
+```tsx
+<Alert type="success" message="Saved." />
+<Alert type="error" message="Error." closable />
+```
+
+---
+
+## Avatar
+
+**Import:** `import { Avatar } from '@dito-uai/components'`
+
+**Props (`AvatarProps`):** extends `ComponentPropsWithoutRef<'div'>`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `color` | `'default' \| 'indigo'` | `'default'` | |
+| `type` | `'icon' \| 'capitals' \| 'image'` | — | |
+| `size` | `'small' \| 'medium' \| 'large'` | — | |
+| `asChild` | `boolean` | — | Radix `Slot` |
+
+**Example:**
+
+```tsx
+<Avatar type="capitals" size="medium">AB</Avatar>
+```
+
+---
+
+## Badge
+
+**Import:** `import { Badge } from '@dito-uai/components'`
+
+**Props (`BadgeProps`):** extends `HTMLAttributes<HTMLSpanElement>`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `status` | `'info' \| 'attention' \| 'white'` | `'info'` | |
+| `size` | `'small' \| 'normal'` | `'normal'` | |
+| `type` | `'pill' \| 'dot'` | `'pill'` | |
+| `contrast` | `boolean` | — | High contrast |
+| `asChild` | `boolean` | — | |
+
+**Example:**
+
+```tsx
+<Badge status="info">New</Badge>
+<Badge type="dot" size="small" contrast />
+```
+
+---
+
+## Button
+
+**Import:** `import { Button } from '@dito-uai/components'`
+
+**Props (`ButtonProps`):** extends `ButtonHTMLAttributes<HTMLButtonElement>`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `appearance` | `'primary' \| 'secondary' \| 'tertiary' \| 'danger' \| 'link' \| 'table' \| 'ai' \| 'ai-outline'` | `'primary'` | |
+| `size` | `'medium' \| 'small'` | `'medium'` | |
+| `rounded` | `boolean` | `false` | `true` → pill |
+| `vertical` | `boolean` | `false` | Column layout (e.g. AI) |
+| `disabled` | `boolean` | — | |
+| `loading` | `boolean` | `false` | Spinner; hides label/icon |
+| `icon` | `React.ElementType` | — | Before label |
+| `asChild` | `boolean` | — | `Slot` |
+
+**Example:**
+
+```tsx
+<Button appearance="primary">Save</Button>
+<Button appearance="danger" loading icon={IconOutlineTrash}>Delete</Button>
+```
+
+---
+
+## Card
+
+**Import:** `import { Card } from '@dito-uai/components'`
+
+**Props (`CardProps`):** extends `HTMLAttributes<HTMLDivElement>` + `children`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `variant` | `'default' \| 'big' \| 'small'` | `'default'` | Border radius |
+| `direction` | `'col' \| 'row'` | `'col'` | |
+| `padding` | `'none' \| 'small' \| 'medium' \| 'big'` | `'none'` | |
+
+---
+
+## Checkbox
+
+**Import:** `import { Checkbox } from '@dito-uai/components'`
+
+**Props (`CheckboxProps`):** `ComponentPropsWithoutRef` of Radix Checkbox Root (`checked` may be `boolean | 'indeterminate'`, etc.).
+
+---
+
+## Chips
+
+**Import:** `import { Chips } from '@dito-uai/components'`
+
+**Props (`ChipsProps`):** extends `HTMLAttributes<HTMLDivElement>`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `text` | `string` | — | Required |
+| `size` | `'small' \| 'medium'` | `'medium'` | |
+| `active` | `boolean` | `false` | |
+| `icon` | `React.ElementType` | — | |
+| `value` | `string` | — | Passed to `onClose` |
+| `onClose` | `(value?: string) => void` | — | Shows close button |
+| `textClassName` | `string` | — | |
+| `asChild` | `boolean` | — | |
+
+---
+
+## Collapsible
+
+**Import:** `import { Collapsible } from '@dito-uai/components'`
+
+**API:** `Collapsible.Item`, `Collapsible.Trigger`, `Collapsible.Content`.
+
+- **`CollapsibleItemProps`:** Radix `Collapsible.Root` props.
+- **`CollapsibleTriggerProps`:** Radix `Collapsible.Trigger` props + `triggerClassName?: string`.
+- **`CollapsibleContentProps`:** Radix `Collapsible.Content` props.
+
+**Example:**
+
+```tsx
+<Collapsible.Item defaultOpen>
+  <Collapsible.Trigger>Open</Collapsible.Trigger>
+  <Collapsible.Content>Details</Collapsible.Content>
+</Collapsible.Item>
+```
+
+---
+
+## DropdownMenu
+
+**Import:**
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuRadioGroup,
+} from '@dito-uai/components';
+```
+
+**Root (`DropdownMenu`):** Radix Root props + `appearance?: 'default' | 'ai'`. Children inherit appearance via context.
+
+**`DropdownMenuContent`:** Radix Content + Portal + `sideOffset` (default `4`), `container`, `forceMount`, `appearance?`.
+
+**`DropdownMenuItem`, `DropdownMenuSubTrigger`, `DropdownMenuLabel`:** `inset?: boolean`, `appearance?`.
+
+**Others:** Radix re-exports with styled slots where applicable.
+
+---
+
+## GoToCard
+
+**Import:** `import { GoToCard } from '@dito-uai/components'`
+
+**Props (`GoToCardProps`):** polymorphic union.
+
+**Shared:**
+
+| Prop | Type | Default |
+|------|------|---------|
+| `title` | `ReactNode` | — |
+| `description` | `ReactNode` | — |
+| `icon` | `ReactNode` | — |
+| `iconClassName` | `string` | — |
+| `state` | `'default' \| 'incomplete' \| 'complete' \| 'error'` | `'default'` |
+| `size` | `'md' \| 'sm'` | `'md'` |
+| `disabled` | `boolean` | `false` |
+| `as` | `'button' \| 'a' \| ComponentType` | `'button'` |
+
+- **`as: 'a'`:** anchor props (`href`, etc.).
+- **`as: LinkComponent`:** `to?`, `replace?`, `state?`, etc. (React Router–compatible).
+
+---
+
+## Indicator
+
+**Import:** `import { Indicator } from '@dito-uai/components'`
+
+**Props (`IndicatorProps`):** extends `HTMLAttributes<HTMLDivElement>`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `value` | `string \| number` | — | Required |
+| `status` | `'positive' \| 'negative' \| 'neutral' \| 'info'` | — | |
+| `icon` | `'positive' \| 'neutral' \| 'negative'` | — | |
+| `usePercentageSymbol` | `boolean` | `true` | `%` suffix |
+
+---
+
+## InputDescription
+
+**Import:** `import { InputDescription } from '@dito-uai/components'`
+
+**Props (`InputDescriptionProps`):** extends `InputHTMLAttributes<HTMLInputElement>` (inherits `maxLength`, etc.).
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `text` | `string` | Help / error |
+| `counter` | `boolean` | With `maxLength` |
+| `invalid` | `boolean` | |
+| `valueLength` | `number` | For counter |
+
+---
+
+## Input
+
+**Import:** `import { Input, inputVariants } from '@dito-uai/components'`
+
+**Props (`InputProps`):** `InputHTMLAttributes` except `size`, `prefix`, `suffix`, `withAffix` (redefined).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `size` | `'small' \| 'medium'` | `'medium'` | |
+| `disabled` | `boolean` | — | |
+| `invalid` | `boolean` | — | |
+| `prefix` | `ReactNode` | — | Inside border |
+| `suffix` | `ReactNode` | — | |
+| `inputClassName` | `string` | — | Only on `<input>` |
+| `id`, `value`, `defaultValue` | — | — | |
+
+**`inputVariants`:** shared by `Search` and `Textarea`.
+
+---
+
+## Label
+
+**Import:** `import { Label } from '@dito-uai/components'`
+
+**Props (`LabelProps`):** extends `HTMLAttributes<HTMLSpanElement>` (outer wrapper).
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `text` | `string` | |
+| `htmlFor` | `string` | Associates with control `id` |
+| `suffix` | `React.ElementType` | Icon beside text |
+| `invalid` | `boolean` | |
+
+---
+
+## Loading
+
+**Import:** `import { Loading } from '@dito-uai/components'`
+
+**Props (`LoadingProps`):**
+
+| Prop | Type | Default |
+|------|------|---------|
+| `className` | `string` | — |
+| `size` | `'TINY' \| 'SMALL' \| 'NORMAL' \| 'LARGE' \| 'HUGE'` | `'NORMAL'` |
+| `color` | `'WHITE' \| 'RED' \| 'BLUE' \| 'GREEN' \| 'GRAY' \| 'INDIGO' \| 'TRANSPARENT'` | `'GREEN'` |
+| `fill` | same union as `color` | `'TRANSPARENT'` |
+
+**Note:** values are **UPPERCASE**.
+
+---
+
+## Message
+
+**Import:** `import { Message, MessageContainer, MessageType } from '@dito-uai/components'`
+
+**Setup:** `<MessageContainer />` at app root (default bottom-right, multi-container).
+
+**API:**
+
+- `Message.open(props: MessageProps)` — `type` defaults to `MessageType.INFO`
+- `Message.success(text, duration?)`
+- `Message.error(text, duration?)` — maps to danger type
+- `Message.info(text, duration?)`
+- `Message.warning(text, duration?)`
+- `Message.loading(text, duration?)`
+- `Message.dismiss(toastId?)`
+
+**`MessageProps` (for `open`):** `text`, `type?` (`MessageType`), `closable?` (default `false`), `duration?` (default `3000` or `false`), `containerId?`, `onClose?`, `onClick?`, + options from `ToastOptions` minus `type`.
+
+**`MessageType`:** `SUCCESS`, `INFO`, `WARNING`, `DANGER`, `LOADING`.
+
+**Example:**
+
+```tsx
+Message.success('Saved');
+Message.open({ type: MessageType.DANGER, text: 'Failed', closable: true, duration: false });
+```
+
+---
+
+## Popover
+
+**Import:** `import { Popover, PopoverTrigger, PopoverContent } from '@dito-uai/components'`
+
+**`PopoverContent`:** Radix Content with `align` (default `'center'`), `sideOffset` (default `4`), plus other Radix props.
+
+---
+
+## ProgressBar
+
+**Import:** `import { ProgressBar } from '@dito-uai/components'`
+
+**Props (`ProgressBarProps`):**
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `value` | `number` | 0–100 |
+| `barBg` | `string` | Tailwind classes for track |
+| `progressBg` | `string` | Tailwind classes for fill |
+
+---
+
+## Progress
+
+**Import:** `import { Progress } from '@dito-uai/components'`
+
+**Namespace:** `Progress.Indicator`, `Progress.Circle`, `Progress.Expanded`.
+
+**`ProgressIndicatorProps`:** `value: string | number`, `progressBar?: number`, `usePercentageSymbol?: boolean` (default `true`), `bg?: 'indigo' | 'white'`, + `HTMLAttributes`.
+
+**`CircleProps`:** `value: number`, `bg?`, `Icon?: ElementType`.
+
+**`ExpandedProps`:** `value: number`, `bg?`, `text: ReactNode | string`.
+
+---
+
+## Radio
+
+**Import:** `import { Radio } from '@dito-uai/components'`
+
+**API:** `Radio.Group`, `Radio.Item`, `Radio.Card`.
+
+- **`RadioGroupProps`:** Radix RadioGroup Root.
+- **`RadioItemProps`:** Radix RadioGroup Item.
+- **`RadioCardProps`:** extends Item: `title`, `description?`, `icon?`, `chipsProps?` (omit `size` on Chips — forced internally), `size?: 'md' | 'sm'`, `disabled?`.
+
+**Example:**
+
+```tsx
+<Radio.Group defaultValue="a">
+  <Radio.Item value="a" />
+  <Radio.Card value="b" title="Plan B" description="Details" />
+</Radio.Group>
+```
+
+---
+
+## Scope
+
+**Import:** `import { Scope } from '@dito-uai/components'`
+
+**API:** `Scope.Group`, `Scope.Item`. Group uses fixed `type="single"`.
+
+**`ScopeGroupProps`:** Radix ToggleGroup Root (no `type` in public API) + variants:
+
+| Prop | Type | Default |
+|------|------|---------|
+| `variant` | `'default' \| 'light' \| 'green' \| 'red'` | `'default'` |
+| `size` | `'default' \| 'small'` | `'default'` |
+| `disabled` | `boolean` | `false` |
+
+**`ScopeItemProps`:** Item props + `text: string`, `icon?`, `variant?`, `size?`, `disabled?`.
+
+---
+
+## Search
+
+**Import:** `import { Search } from '@dito-uai/components'`
+
+**Props (`SearchProps`):** `InputHTMLAttributes` + `inputVariants` (`size`, `disabled`, `invalid`) +
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `scope` | `{ options: { text: string; value: string }[]; selected?: string; onChange?: (v: string) => void }` | Left dropdown |
+
+---
+
+## SelectCard
+
+**Import:** `import { SelectCard } from '@dito-uai/components'`
+
+**API:** `SelectCard.Group`, `SelectCard.Card`.
+
+**`SelectCardGroupProps`:** Radix RadioGroup Root.
+
+**`SelectCardItemProps`:** (defined in module; not exported from barrel) Item + `title`, `description?`, `icon?`, `iconClassName?`, `size?: 'md' | 'sm'`, `disabled?`.
+
+**Type export from package:** `SelectCardGroupProps` only.
+
+---
+
+## Sheet
+
+**Import:** `import { Sheet } from '@dito-uai/components'`
+
+**Props (`SheetProps`):**
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `title` | `string` | Header |
+| `children` | `ReactNode` | |
+| `isVisible` | `boolean` | Syncs open state |
+| `CloseIcon` | `ElementType` | Close button |
+| `maxWidth` | `string` | CSS |
+| `onClose` | `(confirm: boolean) => void` | |
+
+**Note:** use **`isVisible`**, not `visible`.
+
+---
+
+## Skeleton
+
+**Import:** `import { Skeleton } from '@dito-uai/components'`
+
+**Props (`SkeletonProps`):**
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `appearance` | `'default' \| 'ai'` | `'default'` | |
+| `shape` | `'text' \| 'square' \| 'circle' \| 'rectangle'` | — | |
+| `loading` | `boolean` | — | If `false` and `children` exist, renders children |
+
+---
+
+## Status
+
+**Import:** `import { Status } from '@dito-uai/components'`
+
+**`Status`:** read-only pill. **Props (`StatusSimpleProps`):** `text: string`, `status?: 'success' | 'attention' | 'info' | 'error' | 'disabled'`.
+
+**`Status.Menu`:** status dropdown. **Props (`StatusMenuProps`):** `options: StatusOption[]`, `value: string`, `onChange?: (value: string) => void`, `status?`, + `HTMLAttributes`.
+
+**`StatusOption`:** `text`, `value`, `status?` (same union).
+
+**Example:**
+
+```tsx
+<Status text="Active" status="success" />
+<Status.Menu options={[{ text: 'OK', value: 'ok', status: 'success' }]} value="ok" onChange={set} />
+```
+
+---
+
+## Switch
+
+**Import:** `import { Switch } from '@dito-uai/components'`
+
+**Props (`SwitchProps`):** `HTMLAttributes<HTMLInputElement>` + `PropsWithChildren`
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `name` | `string` | Required (native checkbox) |
+| `disabled` | `boolean` | |
+| `checked` | `boolean` | |
+
+**Example:**
+
+```tsx
+<Switch name="alerts" checked={on} onChange={...}>Notifications</Switch>
+```
+
+---
+
+## Tabs
+
+**Import:** `import { Tabs } from '@dito-uai/components'`  
+**Types:** `TabsLayoutProps`, `TabItem`
+
+The exported component is the tab layout (internal implementation `TabsLayout`).
+
+**`TabsLayoutProps`:**
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `tabs` | `TabItem[]` | Each item: `value`, `content`, `label?`, `iconPrefix?`, `suffix?`, `disabled?`, `className?` |
+| `activeKey` | `string` | Controlled |
+| `defaultActiveKey` | `string` | Uncontrolled |
+| `className` | `string` | |
+| `onValueChange` | `(value: string) => void` | |
+| `onTabClick` | `(event, value?) => void` | |
+
+**Example:**
+
+```tsx
+<Tabs
+  defaultActiveKey="1"
+  tabs={[
+    { value: '1', label: 'Tab 1', content: <div /> },
+    { value: '2', label: 'Tab 2', content: <div /> },
+  ]}
+/>
+```
+
+---
+
+## Text
+
+**Import:** `import { Text } from '@dito-uai/components'`
+
+**Props (`TextProps`):** `HTMLAttributes<HTMLSpanElement>` + `children`.
+
+| Prop | Type | Default |
+|------|------|---------|
+| `size` | `'H1' \| 'H2' \| 'H3' \| 'large' \| 'base' \| 'small' \| 'overline'` | `'base'` |
+| `weight` | `'normal' \| 'medium' \| 'semibold'` | `'normal'` |
+
+---
+
+## Textarea
+
+**Import:** `import { Textarea } from '@dito-uai/components'`
+
+**Props (`TextareaProps`):** `TextareaHTMLAttributes` + `invalid?: boolean`.
+
+---
+
+## TipCard
+
+**Import:** `import { TipCard } from '@dito-uai/components'`
+
+**Props (`TipCardProps`):** `HTMLAttributes<HTMLDivElement>` +
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `message` | `string` | |
+| `helpLink` | `string` | URL |
+| `helpCenterTitle` | `string` | |
+| `date` | `string` | Optional |
+
+---
+
+## Toggle (group)
+
+**Import:** `import { Toggle, type ToggleGroupProps, type ToggleGroupItemProps } from '@dito-uai/components'`
+
+**Note:** here `Toggle` is **only** `{ Group, Item }` from `toggle-group.tsx`. Do not confuse with a standalone toggle.
+
+**`ToggleGroupProps`:** Radix ToggleGroup Root + `variant?: 'default'`, `size?: 'default'`.
+
+**`ToggleGroupItemProps`:** Radix Item + same variants (from context).
+
+**Example:**
+
+```tsx
+<Toggle.Group type="single" defaultValue="a">
+  <Toggle.Item value="a">A</Toggle.Item>
+  <Toggle.Item value="b">B</Toggle.Item>
+</Toggle.Group>
+```
+
+---
+
+## Tooltip
+
+**Import:** `import { Tooltip, TooltipProvider } from '@dito-uai/components'`
+
+**Props (`TooltipProps`):**
+
+| Prop | Type | Notes |
+|------|------|--------|
+| `title` | `string \| ReactNode` | Tooltip content |
+| `maxWidth` | `string` | Inner wrapper style |
+| `children` | `ReactNode` | Trigger |
+
+**Example:**
+
+```tsx
+<TooltipProvider>
+  <Tooltip title="Delete">
+    <button type="button"><Icon /></button>
+  </Tooltip>
+</TooltipProvider>
+```
+
+---
+
+## Internal (not exported from `index.ts`)
+
+- `src/ui/internal/dropdown-content.tsx` — used by `Search` and `Status.Menu` for option lists.
+
+---
+
+## Maintenance
+
+When the public API changes: update JSDoc in `src/ui/*.tsx`, exports in `src/index.ts`, and **this file** for LLM consumption in apps that install the package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dito-uai/components",
-  "version": "5.1.0-alpha.66",
+  "version": "5.1.0-alpha.67",
   "description": "Dito's design system component library, made in TSX",
   "license": "MIT",
   "repository": "git+https://github.com/ditointernet/dito-uai.git",
@@ -17,7 +17,8 @@
     "dist/",
     "./tailwind.config.ts",
     "./tailwind-preset.ts",
-    "./lib/colors-utils.ts"
+    "./lib/colors-utils.ts",
+    "./llms.md"
   ],
   "main": "dist/index.js",
   "module": "dist/index.mjs",