@rockshin/tao-ui 0.0.9 → 0.0.11

package/llms.txt

@@ -1,6 +1,6 @@
 # @rockshin/tao-ui
 
-> A modern React 19 component library with semantic DOM customization and OKLCH-based theming. Every component exposes `classNames`/`styles` props to target internal parts by semantic name, and inherits `size`/`disabled`/`variant` from a `TaoProvider` whose theme is derived from a small OKLCH seed token set.
+> A modern React 19 component library with semantic DOM customization and OKLCH-based theming.
 
 ## Install
 
@@ -8,61 +8,418 @@
 npm install @rockshin/tao-ui
 ```
 
-Peer dependencies: `react >=19`, `react-dom >=19`, `dayjs >=1.11` (only needed for `DatePicker`/`RangePicker`).
-Module format: ESM only. Types and CSS ship alongside the JS. **No manual CSS import required** — the package entry (`dist/index.js`) imports design tokens (`--tao-*`) and shared control states on load. This is preserved end-to-end via a `sideEffects` whitelist (`["**/*.css", "./dist/index.js", "./src/index.tsx"]`) so tree-shakers keep the CSS side effects while still eliminating unused component exports at the export granularity.
+Peer dependencies: `react >=19`, `react-dom >=19`, `dayjs >=1.11`.
+Import from the package root. The package entry imports tao-ui CSS side effects automatically.
 
-## Core concepts
+## Core Concepts
 
-- **TaoProvider**: wrap the app once. Provides `size` (`'small' | 'medium' | 'large'`), `disabled`, and `variant` (`'outlined' | 'filled' | 'borderless'`) defaults to all descendants, plus theme tokens. A local prop on a component overrides the provider value. Hook: `useTaoConfig()`.
-- **Theming**: a small seed token set (`TaoSeedToken`) is expanded into a full theme. Pure-CSS-computable values use `calc()`/`color-mix()` with OKLCH; non-linear values (radius steps, font-size log scale, control heights) are computed in JS and injected by `TaoProvider`. CSS variables are prefixed `--tao-*`; data attributes are `data-tao-*`.
-- **Semantic DOM**: every component takes optional `classNames?: SemanticClassNames<Part>` and `styles?: SemanticStyles<Part>`, where `Part` is a component-specific union (e.g. `'root' | 'header' | 'body'`, dotted for nested parts like `'header.cell'`). The top-level `className` prop merges into the `root` part. Helper `cx` is exported.
+- `TaoProvider` supplies size, disabled, variant, portal scope, and theme seed token defaults.
+- Components expose semantic DOM customization through `classNames` and `styles` props.
+- Theme tokens are CSS custom properties prefixed with `--tao-*`; use `tokenVar(name)` and `taoTokenNames` from the package root for typed token references.
+- `componentDocs` and `getComponentDoc(name)` expose machine-readable component metadata.
 
-## Usage
+## Component Groups
 
-```tsx
-import { TaoProvider, Input, Select, Switch } from '@rockshin/tao-ui';
+- Config: TaoProvider
+- Data Display: Collapsible, ScrollArea, Table, Tag
+- Data Entry: Checkbox, DatePicker, FormActions, FormField, FormSection, Input, InputNumber, Radio, RangePicker, Select, Switch, Textarea
+- Feedback: Drawer, Modal, Spinner
+- General: Button
+- Headless: HeadlessInputNumber
+- Layout: FormLayout, Splitter, Stack
+- Navigation: Breadcrumb, ContextMenu, Dropdown, Pagination, Tabs
 
-function App() {
-  return (
-    <TaoProvider size="medium">
-      <Input placeholder="Search" />
-      <Select options={[{ label: 'A', value: 'a' }]} />
-      <Switch defaultChecked />
-    </TaoProvider>
-  );
-}
+## Components
 
-// Style internal parts by semantic name:
-<Drawer classNames={{ root: 'd', header: 'd-h' }} styles={{ body: { padding: 24 } }} />
-```
+### Breadcrumb
+
+Renders the user location in a hierarchy of pages or views.
+
+- Category: Navigation
+- Exports: `Breadcrumb`
+- Source: `src/components/breadcrumb/breadcrumb.tsx`
+- Storybook: `stories/breadcrumb.stories.tsx`
+- Tests: `tests/breadcrumb/breadcrumb.test.tsx`
+- Semantic parts: `root`, `list`, `item`, `link`, `separator`
+
+Use Breadcrumb near the top of a page when users need to understand or move through nested context.
+
+### Button
+
+Triggers an immediate action such as submitting, saving, or opening a surface.
+
+- Category: General
+- Exports: `Button`
+- Source: `src/components/button/button.tsx`
+- Storybook: `stories/button.stories.tsx`
+- Tests: `tests/button/button.test.tsx`
+- Semantic parts: `root`
+
+Use Button for explicit actions. It inherits size, disabled, and variant defaults from TaoProvider.
+
+### Checkbox
+
+Selects one or more independent boolean options.
+
+- Category: Data Entry
+- Exports: `Checkbox`, `CheckboxGroup`
+- Source: `src/components/checkbox/checkbox.tsx`
+- Storybook: `stories/checkbox.stories.tsx`
+- Tests: `tests/checkbox/checkbox.test.tsx`
+- Semantic parts: `root`, `input`, `box`, `label`, `group`, `option`
+
+Use Checkbox for independent choices, or CheckboxGroup when users can select multiple options from a set.
+
+### Collapsible
+
+Shows and hides a region of content while keeping disclosure state accessible.
+
+- Category: Data Display
+- Exports: `Collapsible`
+- Source: `src/components/collapsible/collapsible.tsx`
+- Storybook: `stories/collapsible.stories.tsx`
+- Tests: `tests/collapsible/collapsible.test.tsx`
+- Semantic parts: `root`, `trigger`, `content`
+
+Use Collapsible to hide secondary details while preserving a lightweight page layout.
+
+### ContextMenu
+
+Displays contextual actions from a right click or long press interaction.
+
+- Category: Navigation
+- Exports: `ContextMenu`
+- Source: `src/components/context-menu/context-menu.tsx`
+- Storybook: `stories/context-menu.stories.tsx`
+- Tests: `tests/context-menu/context-menu.test.tsx`
+- Semantic parts: `root`, `trigger`, `content`, `item`, `separator`
+
+Use ContextMenu for secondary actions attached to an object or region.
+
+### DatePicker
+
+Lets users enter or choose a single date, with optional time selection.
+
+- Category: Data Entry
+- Exports: `DatePicker`
+- Source: `src/components/date-picker/date-picker.tsx`
+- Storybook: `stories/date-picker.stories.tsx`
+- Tests: `tests/date-picker/date-picker.test.tsx`, `tests/date-picker/use-calendar.test.ts`
+- Semantic parts: `root`, `input`, `popup`, `calendar`, `cell`, `footer`
+
+Use DatePicker when free text date input would be error-prone or when users benefit from calendar context.
+
+### Drawer
+
+Opens a side panel for related tasks without leaving the current page.
+
+- Category: Feedback
+- Exports: `Drawer`
+- Source: `src/components/drawer/drawer.tsx`
+- Storybook: `stories/drawer.stories.tsx`
+- Tests: `tests/drawer/drawer.test.tsx`
+- Semantic parts: `root`, `overlay`, `content`, `header`, `body`, `footer`, `close`
+
+Use Drawer for inspection, editing, or supporting workflows that should stay connected to the current page.
+
+### Dropdown
+
+Opens a menu of actions or navigation choices from a trigger.
+
+- Category: Navigation
+- Exports: `Dropdown`
+- Source: `src/components/dropdown/dropdown.tsx`
+- Storybook: `stories/dropdown.stories.tsx`
+- Tests: `tests/dropdown/dropdown.test.tsx`
+- Semantic parts: `root`, `trigger`, `content`, `item`, `group`, `divider`
+
+Use Dropdown for compact action sets that do not need to stay visible.
+
+### FormActions
+
+Lays out submit, cancel, and secondary actions for forms.
+
+- Category: Data Entry
+- Exports: `FormActions`
+- Source: `src/components/form-actions/form-actions.tsx`
+- Storybook: `stories/form.stories.tsx`
+- Tests: `tests/form-actions/form-actions.test.tsx`
+- Semantic parts: `root`
+
+Use FormActions at the end of a form or section to align the final actions consistently.
+
+### FormField
+
+Associates labels, help text, validation state, and controls.
+
+- Category: Data Entry
+- Exports: `FormField`
+- Source: `src/components/form-field/form-field.tsx`
+- Storybook: `stories/form.stories.tsx`
+- Tests: `tests/form-field/form-field.test.tsx`
+- Semantic parts: `root`, `label`, `control`, `description`, `error`
+
+Use FormField to provide accessible labeling and status text around a single control.
+
+### FormLayout
+
+Arranges form content with consistent label and control alignment.
+
+- Category: Layout
+- Exports: `FormLayout`
+- Source: `src/layouts/form-layout/form-layout.tsx`
+- Storybook: `stories/form-layout.stories.tsx`
+- Tests: `tests/layouts/form-layout/form-layout.test.tsx`
+
+Use FormLayout to keep dense forms aligned and predictable.
+
+### FormSection
+
+Groups related form fields with a title and optional description.
+
+- Category: Data Entry
+- Exports: `FormSection`
+- Source: `src/components/form-section/form-section.tsx`
+- Storybook: `stories/form.stories.tsx`
+- Tests: `tests/form-section/form-section.test.tsx`
+- Semantic parts: `root`, `header`, `title`, `description`, `content`
+
+Use FormSection to break long forms into scannable groups.
+
+### HeadlessInputNumber
+
+Headless numeric input primitives and hook for custom number entry experiences.
+
+- Category: Headless
+- Exports: `HeadlessInputNumber`, `NumberInput`, `useNumberInput`
+- Source: `src/number-input/number-input.tsx`
+- Storybook: `stories/headless-input-number.stories.tsx`
+- Tests: `tests/number-input/headless-input-number.test.tsx`, `tests/number-input/use-number-input.test.tsx`, `tests/number-input/format.test.ts`, `tests/number-input/validate.test.ts`
+
+Use the headless API when tao-ui styling is not appropriate but number formatting behavior should stay consistent.
+
+### Input
+
+Single-line text input for short freeform values.
+
+- Category: Data Entry
+- Exports: `Input`
+- Source: `src/components/input/input.tsx`
+- Storybook: `stories/input.stories.tsx`
+- Tests: `tests/input/input.test.tsx`
+- Semantic parts: `root`, `input`, `prefix`, `suffix`, `clear`
+
+Use Input for short text values such as names, filters, search terms, and identifiers.
+
+### InputNumber
+
+A styled numeric input built on tao-ui number formatting and validation behavior.
+
+- Category: Data Entry
+- Exports: `InputNumber`
+- Source: `src/components/input-number/input-number.tsx`
+- Storybook: `stories/input-number.stories.tsx`
+- Tests: `tests/input-number/input-number.test.tsx`
+- Semantic parts: `root`, `input`, `controls`, `increment`, `decrement`
+
+Use InputNumber for numeric values that need min, max, step, precision, or formatted display.
+
+### Modal
+
+Displays a focused dialog for decisions, forms, and interruptive information.
+
+- Category: Feedback
+- Exports: `Modal`
+- Source: `src/components/modal/modal.tsx`
+- Storybook: `stories/modal.stories.tsx`
+- Tests: `tests/modal/modal.test.tsx`
+- Semantic parts: `root`, `overlay`, `content`, `header`, `body`, `footer`, `close`
+
+Use Modal for focused tasks or decisions. Static helpers such as Modal.confirm mirror common confirmation flows.
+
+### Pagination
+
+Moves through paged data with current page and page-size controls.
+
+- Category: Navigation
+- Exports: `Pagination`
+- Source: `src/components/pagination/pagination.tsx`
+- Storybook: `stories/pagination.stories.tsx`
+- Tests: `tests/pagination/pagination.test.tsx`
+- Semantic parts: `root`, `item`, `prev`, `next`, `sizeChanger`
+
+Use Pagination when a collection is split into pages rather than infinitely loaded.
+
+### Radio
+
+Selects exactly one option from a mutually exclusive set.
+
+- Category: Data Entry
+- Exports: `Radio`, `RadioGroup`
+- Source: `src/components/radio/radio.tsx`
+- Storybook: `stories/radio.stories.tsx`
+- Tests: `tests/radio/radio.test.tsx`
+- Semantic parts: `root`, `input`, `indicator`, `label`, `group`, `option`
+
+Use RadioGroup when every option is visible and only one can be selected.
+
+### RangePicker
+
+Lets users select a start and end date as one range value.
+
+- Category: Data Entry
+- Exports: `RangePicker`
+- Source: `src/components/date-picker/range-picker.tsx`
+- Storybook: `stories/date-picker.stories.tsx`
+- Tests: `tests/date-picker/range-picker.test.tsx`, `tests/date-picker/use-calendar.test.ts`
+- Semantic parts: `root`, `input`, `popup`, `calendar`, `cell`, `footer`
+
+Use RangePicker for reporting windows, booking windows, and filters with start/end dates.
+
+### ScrollArea
+
+Provides a styled scroll container for overflow content.
+
+- Category: Data Display
+- Exports: `ScrollArea`
+- Source: `src/components/scroll-area/scroll-area.tsx`
+- Storybook: `stories/scroll-area.stories.tsx`
+- Tests: `tests/scroll-area/scroll-area.test.tsx`
+- Semantic parts: `root`, `viewport`, `scrollbar`, `thumb`
+
+Use ScrollArea when a fixed region needs overflow behavior without changing page scroll.
+
+### Select
+
+Chooses one value from a compact list of options.
+
+- Category: Data Entry
+- Exports: `Select`, `ChevronsUpDownIcon`
+- Source: `src/components/select/select.tsx`
+- Storybook: `stories/select.stories.tsx`
+- Tests: `tests/select/select.test.tsx`
+- Semantic parts: `root`, `trigger`, `value`, `content`, `item`, `empty`
+
+Use Select when choices are known but too numerous or secondary to show as radios.
+
+### Spinner
+
+Indicates indeterminate loading activity.
+
+- Category: Feedback
+- Exports: `Spinner`
+- Source: `src/components/spinner/spinner.tsx`
+- Storybook: `stories/spinner.stories.tsx`
+- Tests: `tests/spinner/spinner.test.tsx`
+- Semantic parts: `root`
+
+Use Spinner for short indeterminate waits when progress cannot be measured.
+
+### Splitter
+
+Creates resizable panes separated by draggable handles.
+
+- Category: Layout
+- Exports: `Splitter`
+- Source: `src/components/splitter/splitter.tsx`
+- Storybook: `stories/splitter.stories.tsx`
+- Tests: `tests/splitter/splitter.test.tsx`
+- Semantic parts: `root`, `panel`, `handle`
+
+Use Splitter for work surfaces where users need to allocate space between adjacent panes.
+
+### Stack
+
+Composes children in a flex row or column with consistent spacing.
+
+- Category: Layout
+- Exports: `Stack`
+- Source: `src/layouts/stack/stack.tsx`
+- Storybook: `stories/stack.stories.tsx`
+- Tests: `tests/layouts/stack/stack.test.tsx`
+
+Use Stack for simple one-dimensional layout and spacing.
+
+### Switch
+
+Toggles a setting on or off with immediate effect.
+
+- Category: Data Entry
+- Exports: `Switch`
+- Source: `src/components/switch/switch.tsx`
+- Storybook: `stories/switch.stories.tsx`
+- Tests: `tests/switch/switch.test.tsx`
+- Semantic parts: `root`, `thumb`, `label`
+
+Use Switch for settings that take effect immediately.
+
+### Table
+
+Displays structured row and column data with selection, sorting, filtering, and pagination hooks.
+
+- Category: Data Display
+- Exports: `Table`
+- Source: `src/components/table/table.tsx`
+- Storybook: `stories/table.stories.tsx`
+- Tests: `tests/table/table.test.tsx`
+- Semantic parts: `root`, `table`, `header`, `header.cell`, `body`, `row`, `cell`, `pagination`
+
+Use Table for dense, comparable records that benefit from aligned columns.
+
+### Tabs
+
+Switches between peer panels within the same page context.
+
+- Category: Navigation
+- Exports: `Tabs`
+- Source: `src/components/tabs/tabs.tsx`
+- Storybook: `stories/tabs.stories.tsx`
+- Tests: `tests/tabs/tabs.test.tsx`
+- Semantic parts: `root`, `list`, `tab`, `panel`
+
+Use Tabs to separate peer views without navigating away from the current task.
+
+### Tag
+
+Displays compact labels, statuses, categories, or checkable chips.
+
+- Category: Data Display
+- Exports: `Tag`, `CheckableTag`
+- Source: `src/components/tag/tag.tsx`
+- Storybook: `stories/tag.stories.tsx`
+- Tests: `tests/tag/tag.test.tsx`
+- Semantic parts: `root`, `icon`, `close`
+
+Use Tag for lightweight metadata or status markers. Use CheckableTag for compact filter choices.
+
+### TaoProvider
+
+Provides global component defaults, portal scoping, and theme seed token overrides.
 
-## Exported API
+- Category: Config
+- Exports: `TaoProvider`, `TaoPortalScope`
+- Source: `src/provider/tao-provider.tsx`
+- Storybook: `stories/provider.stories.tsx`
+- Tests: `tests/provider/tao-provider.test.tsx`
 
-Provider & utilities:
-- `TaoProvider`, `useTaoConfig`
-- Types: `TaoProviderProps`, `TaoThemeConfig`, `TaoSeedToken`, `TaoSize`, `TaoVariant`
-- `cx`, types `SemanticClassNames<Part>`, `SemanticStyles<Part>`
+Wrap an app or subtree with TaoProvider to set size, disabled, variant, and theme defaults.
 
-Components (each exports `<Name>Props` and, where applicable, `<Name>SemanticPart`):
-- General: `Button`
-- Layout: `Stack`, `FormLayout`, `Splitter` (+ `SplitterPanelProps`)
-- Navigation: `Tabs` (+ `TabItem`), `Pagination`, `Breadcrumb` (+ `BreadcrumbItemType`), `Dropdown` (+ `DropdownButtonProps`, `DropdownPlacement`, `DropdownTrigger`, and menu-config types `MenuProps`, `MenuItem`, `MenuItemType`, `MenuGroupType`, `MenuDividerType`), `ContextMenu`
-- Data Entry: `Input`, `Textarea` (+ `AutoSizeOptions`), `Select` (+ `SelectOption`), `Checkbox` / `CheckboxGroup` (+ `CheckboxOptionType`), `Radio` / `RadioGroup` (+ `RadioOptionType`), `Switch`, `DatePicker`, `RangePicker`, `FormField`, `FormSection`, `FormActions`
-- Data Display: `Table` (+ `TableColumn`, `TableRowSelection`, `TableFilterItem`, `TablePagination`, `SortOrder`, `SorterResult`), `Tag` / `CheckableTag` (+ `TagColor`, `TagVariant`), `ScrollArea` (+ `ScrollAreaType`), `Collapsible` (+ `CollapsibleTriggerProps`, `CollapsibleContentProps`)
-- Feedback: `Drawer` (+ `DrawerPlacement`, `DrawerSize`, `DrawerResizableConfig`), `Modal` (+ `ModalSemanticPart`; static helpers `Modal.confirm/info/success/error/warning`, hook `Modal.useModal()`, `Modal.destroyAll()`; types `ModalHookApi`, `ModalFuncProps`, `ModalFuncReturn`, `ModalFooterRender`, `ConfirmType`)
+### Textarea
 
-Headless:
-- `useNumberInput`, `NumberInput` (+ `NumberInputProps`, `UseNumberInputOptions`, `UseNumberInputReturn`, `FormatOptions`, `PadDecimalsOnBlur`)
+Multi-line text input with optional auto sizing.
 
-## Notes for code generation
+- Category: Data Entry
+- Exports: `Textarea`
+- Source: `src/components/textarea/textarea.tsx`
+- Storybook: `stories/textarea.stories.tsx`
+- Tests: `tests/textarea/textarea.test.tsx`
+- Semantic parts: `root`, `textarea`
 
-- Import everything from the package root `@rockshin/tao-ui`; there are no deep sub-path entry points.
-- Do not hand-write internal class names; customize via `classNames`/`styles` semantic parts.
-- Prefer setting `size`/`disabled`/`variant` on `TaoProvider` for app-wide defaults; override per-component only when needed.
-- `Modal` follows the antd pattern: render `<Modal open onCancel ...>` for controlled dialogs, or call `Modal.confirm({ title, onOk })` / `Modal.info|success|error|warning` for one-off dialogs. Inside components prefer `const [modal, contextHolder] = Modal.useModal()` (render `contextHolder`) so dialogs read the surrounding `TaoProvider` context.
-- Override theme by passing a partial seed to `TaoProvider`'s theme config rather than overriding `--tao-*` variables directly.
+Use Textarea for longer freeform content such as descriptions, notes, and comments.
 
-## Source
+## Notes For Code Generation
 
-- Repository: https://github.com/rickyshin93/tao-ui
-- License: MIT
+- Prefer root imports from `@rockshin/tao-ui`.
+- Customize internals through semantic `classNames` and `styles`, not private class names.
+- Prefer provider-level defaults for app-wide size, disabled, variant, and theme choices.
+- Use `Modal.useModal()` inside React components so dialogs inherit the surrounding provider context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rockshin/tao-ui",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "description": "A modern React 19 component library with semantic DOM customization and OKLCH-based theming.",
   "keywords": [
@@ -34,16 +34,19 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "component-manifest.json",
     "llms.txt"
   ],
   "scripts": {
     "build": "rslib",
     "build:storybook": "storybook build",
     "check": "biome check --write",
+    "check:components": "node scripts/check-component-sync.mjs",
     "dev": "rslib --watch",
     "doc": "rspress dev",
     "doc:build": "rspress build",
     "doc:preview": "rspress preview",
+    "docs:generate": "node scripts/generate-component-manifest.mjs",
     "format": "biome format --write",
     "release": "bun scripts/release.mjs",
     "storybook": "storybook dev",