banhaten 0.1.2 → 0.1.3

package/docs/design-system/components/steps.md

@@ -0,0 +1,63 @@
+# Steps
+
+Steps show progress through a sequential task. The implementation follows the Figma nodes `HorizontalSteps` (`570:2780`), `VerticalSteps` (`567:76719`), `VerticalStepItem` (`567:5342`), and `HorizontalStepItem` (`569:78346`).
+
+## API
+
+```tsx
+<Steps
+  direction="horizontal"
+  indicator="icon"
+  dir="ltr"
+  items={[
+    { label: "Label", caption: "Caption", supportText: "Support" },
+    { label: "Label", caption: "Caption", supportText: "Support" },
+  ]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `direction` | `horizontal`, `vertical` | `horizontal` |
+| `indicator` | `icon`, `number` | `icon` |
+| `alignment` | `leading`, `trailing` | `leading` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `items` | `StepItem[]` | six default steps |
+
+## Pixel Rules
+
+- Step markers are `28px` circles using `--bg-inverse` with white icon or semibold number text.
+- Connector lines are `1px` using `--border-default`.
+- Horizontal items are `240px` wide in standalone mode and flex equally inside `HorizontalSteps`.
+- Horizontal item content uses `15px / 24px` medium labels and `14px / 20px` captions.
+- Vertical items are `400px` wide with a `24px` gap between marker rail and content.
+- Vertical item labels use `17px / 28px`; support text and captions use `15px / 24px`.
+- Vertical slot content is `76px` tall with the purple subtle background and dashed purple border.
+- Action buttons are `36px` tall with the design-system primary and secondary treatment.
+- RTL mirrors marker placement, text alignment, support text order, and horizontal connector direction.
+
+## Install
+
+```bash
+npx banhaten add steps
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/steps-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs steps` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/steps.css`, `components/expanded/Steps.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.

package/docs/design-system/components/table.md

@@ -0,0 +1,397 @@
+# Table
+
+The table component family includes `Table` and `DataTable`.
+
+`Table` is the composable data surface. It owns layout, headers, row states, selection, sortable header affordances, and RTL mirroring. Cells are filled by table item variants, so new content can be added without creating one-off row layouts.
+
+`DataTable` is the dataset workflow wrapper. It composes the existing Banhaten `Table`, `Toolbar`, `Pagination`, and `Spinner` components to provide search, filters, sorting, selection summary, bulk actions, pagination, and empty/loading/error states.
+
+Figma references:
+
+- `Table Example`, node `449:2354`
+- `Table item 1.2`, node `438:41157`
+
+## Structure
+
+```tsx
+<Table
+  dir="ltr"
+  columns={columns}
+  rows={rows}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+/>
+
+<DataTable
+  title="Component Operations"
+  description="Track component readiness across design-system work."
+  columns={columns}
+  rows={rows}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+  search={{ label: "Search projects", placeholder: "Search projects..." }}
+  filters={filters}
+  pagination={{ pageSize: 10 }}
+/>
+```
+
+The table is composed from these parts:
+
+- `Table`: scroll container and semantic table/grid root.
+- `TableHeader`: one header row with sortable header cells.
+- `TableRow`: one data row with `default`, `selected`, and `disabled` states plus native hover styling.
+- `TableCell`: the layout shell for any table item.
+- `TableItem`: the content variant rendered inside a cell.
+- `DataTable`: composed workflow shell for search, filters, actions, pagination, and table states.
+
+Use semantic `<table>` markup when the table is mostly read-only data. Use an ARIA grid only when the product needs cell-level keyboard navigation. Interactive content inside cells, such as checkboxes, toggles, and actions, must remain real controls.
+
+## Layout
+
+The Figma sample is `1024px` wide, but the implementation should be responsive. Fixed columns keep their design widths and the primary text column fills the remaining space.
+
+```ts
+const exampleColumns = [
+  { id: "select", width: 40, kind: "selection" },
+  { id: "project", header: "Project Name", width: "fill", sortable: true },
+  { id: "leader", header: "Project Leader", width: 203, sortable: true },
+  { id: "status", header: "Status", width: 147, sortable: true },
+  { id: "progress", header: "Progress", width: 160, sortable: true },
+  { id: "deadline", header: "Deadline", width: 155, sortable: true },
+  { id: "actions", width: 44, kind: "actions" },
+];
+```
+
+RTL tables reverse the visual column order and align cell content to the end. The selection cell moves to the far right, and the action cell moves to the far left. The row data order should not change.
+
+## Sizing
+
+| Area | Size | LTR height | RTL height |
+| --- | --- | ---: | ---: |
+| Header row | `sm` | `44px` | `44px` |
+| Body row | `sm` | `48px` | `44px` |
+| Body row | `lg` | `56px` | `56px` |
+
+Cell padding is `8px` on the inline axis. Inline content gap is `6px`; header label and sort icon gap is `4px`. The base checkbox and action columns use fixed dimensions so hover, selected, and icon states do not shift the table.
+
+## States
+
+| State | Treatment |
+| --- | --- |
+| `default` | Default background with a subtle bottom divider. |
+| Native hover | Ghost hover background across the full row. |
+| `selected` | Selected row background and checked selection control. |
+| `disabled` | Disabled content color and no row actions. |
+
+The selected checkbox uses the brand or checkbox fill and a white check icon. Header checkbox supports checked, unchecked, and indeterminate states.
+
+## Token Mapping
+
+The Figma nodes use names such as `interactive/table/header`, `interactive/ghost/hover`, and `bg/neutral/soft`. In this documentation set, map those to the semantic token contract:
+
+| Figma intent | Design-system token |
+| --- | --- |
+| Table header background | `background.muted` |
+| Row hover background | `background.hover` |
+| Row selected background | `background.selected` |
+| Row divider | `border.subtle` |
+| Body text | `content.default` |
+| Header text and secondary labels | `content.subtle` |
+| Checkbox active fill | `background.brand` |
+| Progress track | `background.muted` |
+| Progress fill | `background.success` or component success fill |
+| Row height | `density.tableRowHeight` |
+| Control radius | `shape.control` |
+| Avatar, badge, and progress radius | `shape.badge` |
+
+Do not hard-code preset-specific values in the table. Appearance presets may change density, radius, borders, and hover treatment while preserving the same component API.
+
+## Column API
+
+Use semantic names in code even if the Figma variant labels are title-cased.
+
+```ts
+type TableDirection = "ltr" | "rtl";
+type TableSize = "sm" | "lg";
+type TableRowState = "default" | "selected" | "disabled";
+
+type TableColumn<Row> = {
+  id: string;
+  header?: string;
+  width?: number | "fill";
+  minWidth?: number;
+  align?: "start" | "center" | "end";
+  sortable?: boolean;
+  sortValue?: (row: Row) => TableSortValue;
+  searchValue?: (row: Row) => string;
+  kind?: "data" | "selection" | "actions";
+  item?: TableItemFactory<Row>;
+  renderCell?: (row: Row) => React.ReactNode;
+};
+
+type TableItemFactory<Row> = (row: Row) => TableItem;
+type TableSortValue = string | number | boolean | Date | null | undefined;
+type TableSortState = { columnId: string; direction: "asc" | "desc" } | null;
+```
+
+Use `item` for standard content variants and `renderCell` only for custom product-specific cells. Custom cells still render inside `TableCell`, so spacing, alignment, row height, truncation, RTL behavior, and disabled state stay consistent.
+
+Use `sortValue` when the visible cell content should sort by an underlying value, such as dates, percentages, status rank, or formatted numbers. Use `searchValue` when the cell should contribute searchable text that is different from the visible content.
+
+## Table Items
+
+The item catalog in Figma supports these cell content variants. Code may normalize visual variants into semantic item types; for example, `baseLeading`, `baseRegular`, and `subtle` all map to the `text` item with different `weight` and `tone` values.
+
+| Figma item type | Use for | Notes |
+| --- | --- | --- |
+| `checkbox` | Row selection | Fixed selection column. |
+| `baseLeading` | Primary label | Medium body label. |
+| `baseRegular` | Standard body text | Regular body label. |
+| `subtle` | Secondary text | Uses subtle content color. |
+| `avatarText` | Person, owner, assignee | Avatar plus label; `lg` may include caption. |
+| `rating` | Star rating | Five 20px stars with full, half, and empty states. |
+| `progress` | Percent completion | 8px track, percent label, mirrored fill in RTL. |
+| `toggle` | Binary row setting | 32px switch in `sm`; preserve native button semantics. |
+| `badges` | Status and categorical chips | Supports multiple badges and overflow count. |
+| `onlyAvatar` | Compact person cell | Single avatar centered or aligned by column. |
+| `avatarStack` | Team or group membership | Overlapped 20px avatars, optional count and add button. |
+| `tags` | Neutral labels | Bordered tags with compact 24px height. |
+| `file` | Attachment indicator | Icon-only file cell. |
+| `brandLogoText` | Brand or account identity | Logo plus label. |
+| `payment` | Payment method | Payment icon plus optional label. |
+| `image` | Thumbnail item | Image thumbnail plus label. |
+| `action` | Single row menu | Icon button, usually overflow menu. |
+| `actionGroup` | Multiple row actions | View, edit, delete group; reverse order in RTL. |
+
+```ts
+type TableItem =
+  | { type: "checkbox"; checked: boolean; indeterminate?: boolean }
+  | { type: "text"; tone?: "default" | "subtle"; weight?: "regular" | "medium"; value: string }
+  | { type: "avatarText"; name: string; caption?: string; src?: string; status?: "top" | "bottom" }
+  | { type: "rating"; value: number; max?: 5 }
+  | { type: "progress"; value: number; label?: string; tone?: "success" | "brand" }
+  | { type: "toggle"; checked: boolean; disabled?: boolean }
+  | { type: "badges"; items: BadgeItem[]; maxVisible?: number }
+  | { type: "onlyAvatar"; src?: string; alt: string }
+  | { type: "avatarStack"; avatars: AvatarItem[]; count?: number; canAdd?: boolean }
+  | { type: "tags"; items: string[]; maxVisible?: number }
+  | { type: "file"; label?: string }
+  | { type: "brandLogoText"; label: string; logoSrc?: string }
+  | { type: "payment"; brand: "maestro" | "mastercard" | "visa" | string; label?: string }
+  | { type: "image"; label: string; src: string }
+  | { type: "action"; label: string; icon: "more"; onAction: () => void }
+  | { type: "actionGroup"; actions: TableAction[] };
+
+type BadgeItem = {
+  label: string;
+  tone?: "blue" | "fuchsia" | "amber" | "neutral" | "success" | "warning" | "danger";
+  dot?: boolean;
+};
+
+type AvatarItem = {
+  src?: string;
+  alt: string;
+};
+
+type TableAction = {
+  label: string;
+  icon: "view" | "edit" | "delete" | "more";
+  onAction: () => void;
+};
+```
+
+The item union intentionally describes content, not layout. `TableCell` decides padding, alignment, truncation, and RTL mirroring.
+
+## Adding Items
+
+Add a new table item by defining it on a column. The row supplies content values; the column controls presentation.
+
+```tsx
+const columns: TableColumn<Project>[] = [
+  {
+    id: "project",
+    header: "Project Name",
+    width: "fill",
+    sortable: true,
+    item: (project) => ({
+      type: "text",
+      value: project.name,
+      weight: "regular",
+    }),
+  },
+  {
+    id: "leader",
+    header: "Project Leader",
+    width: 203,
+    sortable: true,
+    item: (project) => ({
+      type: "avatarText",
+      name: project.leader.name,
+      src: project.leader.avatarUrl,
+    }),
+  },
+  {
+    id: "status",
+    header: "Status",
+    width: 147,
+    sortable: true,
+    item: (project) => ({
+      type: "badges",
+      items: [{ label: project.status, tone: "blue", dot: true }],
+    }),
+  },
+  {
+    id: "progress",
+    header: "Progress",
+    width: 160,
+    sortable: true,
+    item: (project) => ({
+      type: "progress",
+      value: project.progress,
+      label: `${project.progress}%`,
+      tone: "success",
+    }),
+  },
+  {
+    id: "deadline",
+    header: "Deadline",
+    width: 155,
+    sortable: true,
+    item: (project) => ({
+      type: "text",
+      value: project.deadlineLabel,
+    }),
+  },
+  {
+    id: "actions",
+    width: 44,
+    kind: "actions",
+    item: (project) => ({
+      type: "action",
+      label: `Open actions for ${project.name}`,
+      icon: "more",
+      onAction: () => openProjectActions(project.id),
+    }),
+  },
+];
+```
+
+For a custom item, first check whether the content can be represented by the existing union. Add a new item type only when the content appears in more than one table or needs shared behavior such as keyboard handling, truncation, or overflow.
+
+## Header Behavior
+
+Sortable headers render the label plus the expand-up-down icon. When sorted, the header cell sets `aria-sort` to `ascending` or `descending`; otherwise it uses `none`. Header controls must have a clear label such as `Sort by Project Name`.
+
+`Table` accepts `sort` and `onSortChange` when the host owns sorting. `DataTable` can own sorting internally with `defaultSort`, or operate as a controlled component with `sort` and `onSortChange`.
+
+The select-all checkbox announces:
+
+- unchecked when no visible rows are selected;
+- checked when all visible rows are selected;
+- indeterminate when some visible rows are selected.
+
+## Data Table
+
+Use `DataTable` when the product needs the complete dataset browsing workflow instead of only rows and columns.
+
+```tsx
+const filters = [
+  {
+    id: "review",
+    label: "Status",
+    value: "Review",
+    active: statusFilter === "Review",
+    onAction: () => setStatusFilter("Review"),
+    predicate: (row) => row.status === "Review",
+  },
+];
+
+<DataTable
+  actions={[{ label: "Export", variant: "soft" }]}
+  bulkActions={[{ label: "Archive", variant: "outline" }]}
+  columns={columns}
+  defaultSort={{ columnId: "project", direction: "asc" }}
+  emptyState={{
+    title: "No matching projects",
+    description: "Try another search or return to all statuses.",
+  }}
+  filters={filters}
+  pagination={{ pageSize: 10 }}
+  rows={rows}
+  search={{ label: "Search projects", placeholder: "Search projects..." }}
+/>
+```
+
+`DataTable` applies active filter predicates, searches row text from `getRowSearchText`, column `searchValue`, or table item text, sorts by column `sortValue` or table item value, and paginates the resulting rows. Set `pagination={false}` for unpaginated datasets.
+
+## Accessibility
+
+- Preserve native controls for checkbox, toggle, buttons, and menu triggers.
+- Use `aria-selected` on selected rows.
+- Provide labels for icon-only actions.
+- Keep focus outlines visible through `border.focus`.
+- Truncate long text visually, but keep the full value available through `title` or an accessible label when useful.
+- Do not put multiple unrelated buttons into one unlabeled cell; group row actions with a clear accessible name.
+
+## Usage
+
+```tsx
+<Table
+  dir="ltr"
+  columns={columns}
+  rows={projects}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+/>
+
+<Table
+  dir="rtl"
+  columns={columns}
+  rows={projects}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+/>
+```
+
+## Preset Impact
+
+- `default`: normal row density, quiet header background, modest control radius.
+- `rounded`: slightly taller rows, softer hover treatment, larger badges and control radius.
+- `sharp`: denser rows, stronger dividers, square or near-square controls.
+
+## Implementation Notes
+
+- Use Remix icons for Figma icon matches: `expand-up-down-line`, `more-fill`, `check-fill`, `eye-line`, `pencil-line`, and `delete-bin-line`.
+- Progress bars are `8px` high and pill-shaped. In RTL, the filled segment grows from the right.
+- Badges are `24px` tall, pill-shaped, and use `11px / 14px` medium text.
+- Tags are `24px` tall with a 1px border and `13px / 20px` medium text.
+- Avatar-only and avatar-stack cells use 20px avatars in compact rows and 32px avatars where the `lg` item variant calls for it.
+- Action buttons are fixed `28px` in `sm` rows and `32px` in `lg` rows.
+
+## Install
+
+```bash
+npx banhaten add table
+```
+
+## API
+
+Public exports: `Table`, `DataTable`.
+
+Use the live registry docs for the generated API table and source-backed examples.
+
+## Examples
+
+Primary registry example: `examples/expanded/table-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs table` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/table.css`, `components/expanded/Table.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.

package/docs/design-system/components/tabs.md

@@ -0,0 +1,52 @@
+# Tabs
+
+Tabs is a Radix-backed local navigation primitive with underline, segmented, and rounded treatments across size, full-width behavior, controlled state, LTR, and RTL.
+
+## API
+
+```tsx
+<Tabs
+  ariaLabel="Project sections"
+  items={["Overview", "Activity", "Settings"]}
+  variant="underline"
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `underline`, `segment`, `rounded` |
+| `size` | `md`, `sm`, `xs` |
+| `fullWidth` | `boolean` |
+| `activeIndex`, `defaultActiveIndex` | controlled or uncontrolled index |
+| `onActiveIndexChange` | selected-index callback |
+
+## Token Contract
+
+Tabs uses Banhaten tab CSS variables for sizes, spacing, border, radius, active indicators, surfaces, and content states.
+
+## RTL
+
+Tabs accepts `dir="rtl"` and mirrors layout through inherited direction. Labels should remain short enough for each treatment and viewport.
+
+## Accessibility
+
+Tabs uses Radix Tabs so keyboard behavior, roving focus, activation mode, trigger state, and panel relationships come from the primitive.
+
+## Install
+
+```bash
+npx banhaten add tabs
+```
+
+## Examples
+
+Primary registry example: `examples/tabs-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs tabs` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `keyboard`: Radix receives dir so arrow-key navigation follows the document direction.
+- `textDirection`: Trigger labels use dir="auto" by default for Arabic and English tab labels.
+- `spacing`: Uses inherited direction and logical inline spacing so underline, segmented, and rounded treatments mirror naturally.

package/docs/design-system/components/tag.md

@@ -0,0 +1,78 @@
+# Tag
+
+Tags identify compact metadata, filters, or removable selections.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Tag` (`188:64712`). It supports every variant in the matrix: `simple`, `dot`, `flag`, `avatar`, and `icon`; `default`, `active`, and `disabled` states with native hover and focus-visible styling; `xs`, `md`, and `lg` sizes; optional close button; LTR and RTL.
+
+## API
+
+```tsx
+<Tag
+  type="simple"
+  size="md"
+  state="default"
+  showCloseButton={false}
+  dir="ltr"
+>
+  Label
+</Tag>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `type` | `simple`, `dot`, `flag`, `avatar`, `icon` | `simple` |
+| `size` | `xs`, `md`, `lg` | `md` |
+| `state` | `default`, `active`, `disabled` | `default` |
+| `showCloseButton` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `dir` | `ltr`, `rtl`, `auto` | `auto` |
+| `avatar` | `ReactNode` | initials placeholder |
+| `flag` | `ReactNode` | token-colored placeholder |
+| `icon` | `ReactNode` | plus icon |
+| `onClose` | close-button click handler | none |
+
+## Token Contract
+
+The component consumes semantic design-system tokens only:
+
+- Text and icons: `content.default`, `content.disabled`, `content.primary`, `content.onColor`, `content.muted`
+- Backgrounds: `background.default`, `background.hover`, `background.pressed`, `background.disabled`, `background.selected`, `background.danger`
+- Borders: `border.default`, `border.disabled`, `border.brand`, `border.focus`, `border.subtle`
+- Shape: `shape.control`, `shape.badge`, `shape.avatar`
+- Density: `density.controlHeight`, `density.controlPaddingX`
+
+## Pixel Rules
+
+- `xs` tags are `24px` tall and use body-xs medium text.
+- `md` tags are `28px` tall and use body-sm medium text.
+- `lg` tags are `36px` tall and use body-md medium text.
+- Simple tags use centered text and no leading slot.
+- Dot, flag, avatar, and icon tags use a `20px` leading slot.
+- Close buttons are `16px` with a `12px` icon.
+- Focused tags use a brand border plus an outside focus ring at reduced opacity.
+- Active tags use selected/brand treatment and a stronger brand border.
+- Disabled tags use disabled background, border, and content tokens.
+- RTL uses logical inline padding and inherited direction so leading media, label, and close button mirror naturally.
+
+## Install
+
+```bash
+npx banhaten add tag
+```
+
+## Examples
+
+Primary registry example: `examples/tag-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs tag` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical inline padding and inherited flex direction so the leading media, label, and close button mirror naturally.
+- `textDirection`: Text labels use dir="auto" for short Arabic and English tag labels.
+- `closeButton`: The close affordance is a 16px token-sized icon button using currentColor and the tag disabled state.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.

package/docs/design-system/components/textarea.md

@@ -0,0 +1,48 @@
+# Textarea
+
+Textarea is the multiline field primitive for comments, notes, descriptions, and tag-style text entry. It supports label, helper and error text, default and tags modes, placeholder, filled, disabled, and RTL states.
+
+## API
+
+```tsx
+<Textarea label="Comments" placeholder="Add context..." />
+<Textarea mode="tags" label="Tags" defaultValue="Design, System" />
+```
+
+| Prop | Values |
+| --- | --- |
+| `mode` | `default`, `tags` |
+| `state` | `placeholder`, `filled`, `disabled` |
+| `hasError` | `boolean` |
+| `label`, `helperText` | `ReactNode` |
+| `dir` | `ltr`, `rtl` |
+
+## Token Contract
+
+Textarea uses Banhaten field surface, text, label, helper, error, tag, spacing, border, radius, disabled, and focus tokens.
+
+## RTL
+
+Textarea uses `text-start`, inherited direction, and logical field layout. Labels, helper text, and tag chips mirror without physical left/right styling.
+
+## Accessibility
+
+Connect labels and helper/error text through component props. Use visible error text with `hasError` rather than color alone.
+
+## Install
+
+```bash
+npx banhaten add textarea
+```
+
+## Examples
+
+Primary registry example: `examples/textarea-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs textarea` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" so Arabic and English content align naturally.
+- `spacing`: Uses inherited direction and flex order so labels, helper icons, and tag chips mirror without physical left/right rules.