@godxjp/ui 28.9.0 → 28.12.0

package/agent/components/SplitPane.json

@@ -0,0 +1,66 @@
+{
+  "example": "import { SplitPane } from \"@godxjp/ui/layout\";\n\n<SplitPane aside={<DetailPanel />} asideWidth=\"sm\">\n  <MainContent />\n</SplitPane>\n\n// Collapsible rail — closing with `null` does NOT remount <MessageList />.\n<SplitPane asideLabel=\"Thread\" aside={threadOpen ? <Thread /> : null}>\n  <MessageList />\n</SplitPane>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "SplitPane",
+  "props": [
+    {
+      "description": "Main (left) content.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Aside (trailing) panel content. `null` means CLOSED: no `<aside>` element is rendered, the grid drops to one full-width column and the gap goes with it. Closing through this prop — instead of dropping SplitPane at the call site — keeps `children` mounted, because the wrappers stay in place and the main column keeps its position in the React tree.",
+      "name": "aside",
+      "required": true,
+      "type": "ReactNode | null"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Width preset for the aside rail: sm 20rem, md 22rem, lg 30rem. `lg` is for a rail that carries a panel rather than a list, and it holds off splitting until the pane is 64rem wide so the main column stays the wider of the two.",
+      "name": "asideWidth",
+      "type": "\"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Accessible name for the `<aside>` complementary landmark. Required when more than one complementary landmark shares the document, so a screen-reader landmark list says which rail is which.",
+      "name": "asideLabel",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Take the remaining height of the parent instead of growing with the content. Default false keeps the pane content-height, which is right inside a scrolling page. Set it for an app-shell surface whose columns own their own scrolling — a chat transcript with a pinned composer, a full-height table beside a detail rail: the pane and both columns get a DEFINITE height, so overflow inside a column scrolls that column instead of pushing the page taller. The parent still decides how much height there is to fill: inside a flex column, give the wrapper `flex: 1; min-height: 0`.",
+      "name": "fill",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "ResponsiveGrid — use when you need more than two columns, or when both columns must have equal or percentage-based widths rather than a fixed-rem aside. SplitPane always gives main a `1fr` and aside a fixed rem width.",
+    "PageContainer — use as the outer scaffold that provides page padding and vertical rhythm; nest SplitPane inside PageContainer, not the other way around.",
+    "Sheet — use when the detail/context panel should slide in as an overlay (drawer) rather than sitting permanently beside the main content. Prefer Sheet on mobile or when the aside content is secondary and on-demand.",
+    "Flex direction='col' — use when content is purely vertical (single column, sequential sections). SplitPane is the right pick only when a persistent side panel is needed at the same hierarchy level as the main content."
+  ],
+  "rules": [
+    24
+  ],
+  "storyPath": "layout/SplitPane.stories.tsx",
+  "tagline": "Two-column layout with a main content area and a fixed-width aside panel.",
+  "usage": [
+    "DO: pass all right-panel content via the `aside` prop — it renders inside a semantic `<aside>` element at a fixed rem width (sm=20rem, md=22rem). The `children` prop fills the main `1fr` column. Both accept any ReactNode.",
+    "DO: reach for `fill` when the pane is an app-shell surface rather than a block in a scrolling page — a chat transcript whose composer stays pinned to the bottom, a full-height table beside a detail rail. It is the supported way to say \"be as tall as what is left\"; a consumer that instead styles the pane's wrapper divs from outside (`[&>*]`, `[&>*>*]`) is targeting this component's internal DOM by position and will break the day another wrapper appears.",
+    "DO: choose `asideWidth=\"sm\"` for compact detail panels (filters, quick stats, key-value summaries) and the default `asideWidth=\"md\"` for richer panels (forms, timelines, long metadata lists).",
+    "DO: wrap SplitPane inside `PageContainer` or `PageContainer.Inset` — SplitPane provides no page padding of its own. It is a grid primitive, not a page scaffold.",
+    "DO: close a collapsible rail with `aside={null}` — a Slack-style thread, a Linear-style detail panel — rather than swapping `<SplitPane aside={<Thread />}>{page}</SplitPane>` for a bare `{page}`. Both look the same on screen; only the prop keeps `children` mounted. The conditional swap changes the DEPTH of `{page}` in the React tree, so React remounts it: measured in a consumer as a message list jumping from scrollTop 400 to the bottom the instant a thread opened, losing the reader's place and any component state below it.",
+    "DON'T: leave `SplitPane` mounted with an empty `aside={<div />}` to avoid that remount — an empty aside still reserves its rail, leaving a blank 20-30rem column. `aside={null}` removes the element AND the column (the pane sets `data-aside=\"closed\"` on itself, so the collapse is one CSS rule, not a call-site width override).",
+    "DON'T: expect two columns below 48rem OF THE PANE'S OWN WIDTH (64rem for `asideWidth=\"lg\"`). The split is a CSS container query on the pane, not a viewport media query, so a narrow embedded pane on a large screen correctly stays single-column and a wide pane on a small screen still splits. Below the threshold it stacks (main on top, aside below); for layouts that must stay side-by-side at any width use CSS Grid or `ResponsiveGrid`.",
+    "DON'T: add a CSS `overflow: hidden` or fixed height on the SplitPane wrapper; both columns carry `min-width: 0` to handle overflow correctly, and the grid uses `minmax(0, 1fr)` — adding external constraints will break the overflow contract.",
+    "DON'T: hand-roll a two-column div layout with flexbox or CSS Grid when SplitPane already ships — that duplicates the responsive breakpoint logic and the semantic `<aside>` element."
+  ],
+  "useCases": [
+    "Invoice / transaction detail page: list of records in `children` (DataTable), selected-record detail panel in `aside` (Descriptions + Timeline).",
+    "Accounting ledger drill-down: account list on the left, chart-of-accounts metadata or running balance breakdown on the right using `asideWidth=\"sm\"`.",
+    "Document review workflow: PDF or rich-text viewer in `children`, approval form or annotation panel in `aside`.",
+    "Settings page with a category list or Steps navigator in `children` and a live preview or summary card in `aside`.",
+    "Kanban or task board where the main area holds the board columns and the aside shows the focused task detail without navigating away."
+  ]
+}

package/agent/components/StatCard.json

@@ -0,0 +1,83 @@
+{
+  "example": "import { StatCard } from \"@godxjp/ui/data-display\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n// ✅ StatCard sits directly in the grid — it draws its own card + border.\n<ResponsiveGrid columns={3}>\n  <StatCard label=\"総会員数\" value=\"12,450\" hint=\"先月比 +3%\" />\n  <StatCard label=\"月次売上\" value=\"¥8,200,000\" delta=\"+12%\" />\n  <StatCard label=\"利用率\" value=\"68.4%\" />\n</ResponsiveGrid>\n\n// ❌ Double border — do NOT wrap StatCard in a Card:\n// <Card><CardContent><StatCard label=\"x\" value=\"1\" /></CardContent></Card>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "StatCard",
+  "props": [
+    {
+      "description": "Metric name.",
+      "name": "label",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Metric value (string/number/ReactNode).",
+      "name": "value",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Secondary context below the value.",
+      "name": "hint",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Optional leading icon rendered as a tinted medallion above the metric. Decorative (aria-hidden) — the label carries the meaning. Tint via the --stat-card-icon-{background,foreground} tokens (default a soft brand-primary wash).",
+      "name": "icon",
+      "type": "LucideIcon"
+    },
+    {
+      "description": "Compact trend text beside the value. Sign-aware tone (+ green / - red).",
+      "name": "delta",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"stacked\"",
+      "description": "stacked = label over value; inline = label left / value right.",
+      "name": "layout",
+      "type": "\"stacked\" | \"inline\""
+    },
+    {
+      "description": "Align the metric group.",
+      "name": "align",
+      "type": "\"start\" | \"end\""
+    },
+    {
+      "defaultValue": "false",
+      "description": "Flip delta tone semantics for metrics where lower is better (cost, error rate): '-' renders green, '+' renders red.",
+      "name": "inverse",
+      "type": "boolean"
+    },
+    {
+      "description": "Semantic 3px leading-edge rail (forwarded to the underlying Card) — flags a KPI that needs attention (e.g. attention = backlog with a deadline, destructive = overdue).",
+      "name": "accent",
+      "type": "\"primary\" | \"success\" | \"warning\" | \"info\" | \"attention\" | \"destructive\""
+    }
+  ],
+  "related": [
+    "ResponsiveGrid — required layout wrapper for StatCard grids; controls column count and responsive breakpoints. Always pair them together.",
+    "SkeletonStat — exact loading placeholder shaped like a StatCard tile; swap in while KPI data is fetching, then replace with the real StatCard.",
+    "Descriptions — use instead when displaying multiple label/value metadata pairs on a detail page (not headline KPIs); Descriptions is not card-bordered and does not show delta/hint slots.",
+    "Card + CardContent — use when you need a general-purpose content container with a header, footer, or arbitrary body; do NOT wrap StatCard inside these.",
+    "LineChart / BarChart / PieChart (@godxjp/ui/charts) — when the trend or composition BEHIND a KPI matters, pair the StatCard headline number with a chart in the same dashboard grid: StatCard states the figure, the chart shows its shape over time or its breakdown."
+  ],
+  "rules": [],
+  "storyPath": "data-display/StatCard.stories.tsx",
+  "tagline": "KPI tile. ⚠️ StatCard IS ALREADY a bordered Card — render it DIRECTLY in ResponsiveGrid. NEVER wrap it in <Card>/<CardContent> (that double-borders it → looks too thick). Use `accent` for a semantic leading-edge rail on a KPI needing attention.",
+  "usage": [
+    "DO place StatCard directly as a child of ResponsiveGrid — it renders its own bordered Card shell internally, so no wrapping <Card> or <CardContent> is needed or allowed. Wrapping creates a double border.",
+    "DO pass `delta` as a sign-prefixed string (e.g. '+12%' or '-3%') to get automatic color tone: '+' renders text-success, '-' renders text-destructive. For metrics where a negative delta is good (e.g. cost reduction, error rate), pass `inverse` so the tone is flipped correctly.",
+    "DO use `hint` for secondary context (e.g. '先月比 +3%', 'last 30 days'). In the default `stacked` layout hint renders below the value; in `inline` layout it renders beside the label.",
+    "DO use `accent` (not a className border) for the semantic leading-edge rail — `attention` for a non-destructive backlog needing action, `destructive` only for overdue/exceeded states. Most tiles in a grid stay rail-less; an all-accented grid says nothing.",
+    "DO NOT hand-roll a KPI tile using a plain <Card><CardContent>. StatCard is the correct primitive and token-aligns the label/value/hint/delta slots automatically.",
+    "WHILE data is loading, replace each StatCard with a <SkeletonStat /> at the same grid position — never render an empty value string or a spinner inside StatCard itself."
+  ],
+  "useCases": [
+    "Dashboard KPI row: monthly revenue, invoice count, overdue balance, and collection rate displayed side-by-side in a ResponsiveGrid with delta trend vs previous period.",
+    "Accounting summary header: total debits, total credits, and net balance for a journal entry list page, each with a hint showing the date range in scope.",
+    "Coupon/membership admin overview: active members, live coupons, monthly redemptions, and total discount amount — the canonical example in the catalog.",
+    "Inline variant for a narrow sidebar or detail panel where space is constrained: label on the left, large value on the right (layout='inline'), e.g. contract value next to a deal record.",
+    "Cost or error-rate metrics where a falling number is positive: pass `inverse` so a '-15%' delta shows green, preventing misleading red-for-good UI.",
+    "Loading state for any KPI grid: render the same ResponsiveGrid columns filled with <SkeletonStat /> components while the query is in-flight, then replace with StatCard tiles once data resolves."
+  ]
+}

package/agent/components/Steps.json

@@ -0,0 +1,95 @@
+{
+  "example": "import { Steps } from \"@godxjp/ui/navigation\";\n\n<Steps value={1} items={[{ title: \"申請\" }, { title: \"審査中\" }, { title: \"完了\" }]} />",
+  "group": "navigation",
+  "importPath": "@godxjp/ui/navigation",
+  "name": "Steps",
+  "props": [
+    {
+      "description": "Array of { title, subtitle?, description?, icon?, status? }.",
+      "name": "items",
+      "type": "StepItemProp[]"
+    },
+    {
+      "defaultValue": "0",
+      "description": "Active step index (0-based).",
+      "name": "value",
+      "type": "number"
+    },
+    {
+      "defaultValue": "0",
+      "description": "Base offset for the first rendered step index.",
+      "name": "defaultValue",
+      "type": "number"
+    },
+    {
+      "defaultValue": "\"horizontal\"",
+      "description": "Layout direction.",
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\""
+    },
+    {
+      "description": "Status of the CURRENT step (drives the active step colour).",
+      "name": "status",
+      "type": "\"wait\" | \"process\" | \"finish\" | \"error\""
+    },
+    {
+      "description": "Render full markers, compact dots, a numbered inline auth progress row, or Ant Design's `navigation` bar — slab steps with a chevron between them (the default hairline connector is switched off there so it is not drawn through the glyph). `dot` IS antd's `progressDot`; antd 6.6.2 deprecates that prop in favour of exactly this value.",
+      "name": "type",
+      "type": "\"default\" | \"dot\" | \"inline\" | \"navigation\""
+    },
+    {
+      "description": "Ant Design `percent` — completion of the CURRENT (`process`) step only, 0–100 (out-of-range values are clamped). Draws a determinate arc around that step's marker and exposes it as a real `progressbar` with aria-valuenow/min/max. Ignored by `type=\"inline\"`, which has no marker to draw into.",
+      "name": "percent",
+      "type": "number"
+    },
+    {
+      "description": "Step size.",
+      "name": "size",
+      "type": "\"md\" | \"sm\""
+    },
+    {
+      "description": "Lay step titles beside or below the step icons.",
+      "name": "titlePlacement",
+      "type": "\"horizontal\" | \"vertical\""
+    },
+    {
+      "defaultValue": "\"chevron\"",
+      "description": "`chevron` (›) is the breadcrumb-flavoured original; `arrow` (→) is the canonical hosted-identity progression marker — a chevron reads \"drill into\", an arrow reads \"then\", which is what a step row means. Both flip under dir=\"rtl\". Ignored by every other `type`.",
+      "name": "separator",
+      "type": "\"chevron\" | \"arrow\""
+    },
+    {
+      "description": "Fires with the clicked step index (0-based).",
+      "name": "onValueChange",
+      "type": "(value: number) => void"
+    }
+  ],
+  "related": [
+    "Timeline — use Timeline (from @godxjp/ui) when you need a chronological event log with timestamps and variable content per entry; use Steps when the number of stages is fixed and forward-progress is the semantic.",
+    "Tabs / Tabs — use Tabs when each section has its own rendered panel and users switch freely between them; use Steps when stages are ordered and the indicator communicates completion state rather than just selection.",
+    "Progress — use Progress for a single continuous percentage (file upload, quota fill); use Steps for discrete named stages with individual pass/fail status.",
+    "Breadcrumb — use Breadcrumb for hierarchical location within a page tree; use Steps for sequential workflow progress where order and completion matter."
+  ],
+  "rules": [],
+  "storyPath": "navigation/Steps.stories.tsx",
+  "tagline": "Multi-step progress indicator — horizontal or vertical, default or dot style.",
+  "usage": [
+    "DO: Pass all steps via the `items` array (each `{ title, subtitle?, description?, icon?, status?, disabled? }`) — Steps is a single-component API with no child sub-components to compose manually.",
+    "DO: Control the active step with `value` (0-based index). For async operations, set the top-level `status` prop (`'process'|'error'|'finish'`) to override the current step's icon — e.g. `status='error'` turns the active step red without touching `items`.",
+    "DO: Use per-item `status` to pin individual steps independently of `value` (e.g. a skipped or already-errored step). Per-item `status` takes precedence over the derived status from `value`.",
+    "DO: Use type='inline' for compact hosted-auth/device progress. It retains process/finish/error/wait and aria-current semantics without the tall icon rail; never rebuild the row from Text and arrows in a consumer.",
+    "DO: Pick the inline progression marker with `separator` (`\"arrow\"` for the canonical hosted-identity row, `\"chevron\"` for the default), and express the step-number emphasis through `--steps-inline-index-{color,font-weight}` + `--steps-inline-separator-color` in the service theme. The canonical treatment is an accent TINT at normal weight; the library default is bold at the inherited colour. Both are one token away — never fork `.ui-steps-inline-index` in app CSS.",
+    "DON'T: Use Steps for navigation that needs URL routing or tab-switching — it has no built-in panel rendering. Pair it with your own conditional panel or a `Tabs`/`Tabs` body; Steps only renders the indicator bar.",
+    "DON'T: Wire `onValueChange` unless you actually support non-linear navigation. `onValueChange` makes every non-disabled step clickable (rendered as `<button>`); omitting it makes all steps non-interactive (`cursor-default`). Never set `disabled` on an item without also providing `onValueChange`, or the prop is meaningless.",
+    "A11y: The `<ol>` is given `aria-label='Progress'` automatically. Individual steps render as `<button type='button'>` when `onValueChange` is present — ensure each `item.title` is descriptive enough to serve as the button label; avoid icon-only steps without a visible title.",
+    "DO: Put a `data-testid` (or an `id`, or any other DOM attribute) straight on `<Steps>` — the rest of an `<ol>`'s attributes ride through to the list element. NEVER bind a test to `.ui-steps-list` or to a `[data-status]` on an item: those are internal names this package renames without notice, and a suite that binds to them breaks on an upgrade that changed nothing about the component's contract. A caller-supplied `aria-label` also wins over the localized default.",
+    "NOTE: `type` on Steps is the MARKER APPEARANCE (`default` | `dot` | `inline` | `navigation`), not an `<ol>`'s numbering style — the native attribute of that name is deliberately not forwarded."
+  ],
+  "useCases": [
+    "Multi-step form wizard (entity onboarding, invoice creation): render Steps above a form, drive `current` from local state, advance on validated submit — use `status='error'` on the current step when server validation fails.",
+    "Async background job tracker: display steps for a long-running import/export pipeline; poll job status and map job phases to `StepStatusProp` values (`'process'` with spinner for in-flight, `'finish'` for done, `'error'` for failed).",
+    "Document approval workflow (accounting, contracts): map approval stages (Draft → Review → Approved → Archived) to `items` with per-item `status` reflecting the real state from the server — use `orientation='vertical'` for a sidebar timeline feel.",
+    "Onboarding checklist sidebar: `orientation='vertical'` + `type='dot'` + `size='sm'` for a compact sidebar progress guide alongside a multi-section settings page.",
+    "Non-linear step navigation (e.g. revisit a previous step to correct data): provide `onValueChange` and leave only future steps `disabled`; past and current steps become clickable buttons."
+  ]
+}

package/agent/components/Swatch.json

@@ -0,0 +1,41 @@
+{
+  "example": "import { Swatch } from \"@godxjp/ui/data-display\";\nimport { Text } from \"@godxjp/ui/general\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n<Flex align=\"center\" gap=\"sm\">\n  <Swatch color={brand.primary_color} aria-label={`プライマリカラー: ${brand.primary_color}`} />\n  <Text weight=\"medium\">{brand.name}</Text>\n</Flex>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Swatch",
+  "props": [
+    {
+      "description": "The colour to show, as any CSS colour value (#7C3AED, rgb(…), oklch(…)). It is DATA, the same axis as Badge's `color`: a value a person picked in a settings screen, so it arrives as a prop and never enters a stylesheet. A colour that MEANS something (success, overdue) is not this prop — use Badge `tone` or Legend, which name the meaning.",
+      "name": "color",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "The sample's accessible NAME, and the reason a swatch can be shown with no visible label: say what the colour is for AND what it is, e.g. `プライマリカラー: #7C3AED`. With it the mark is role=img and announces that sentence; WITHOUT it the mark is aria-hidden, which is correct only when a visible line beside it already states the colour. Colour is never the sole carrier of meaning either way (WCAG 1.4.1).",
+      "name": "aria-label",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Legend — the KEY for a colour-coded surface: closed semantic tones, each with required words. Swatch is one sample of an arbitrary value and takes its name from aria-label.",
+    "ColorPicker — the INPUT for the same value. Swatch displays; ColorPicker chooses.",
+    "Badge — a chip that labels a thing (and can carry the entity's own `color` as a wash). Swatch is the colour itself, with no chip around it."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Swatch.stories.tsx",
+  "tagline": "A READ-ONLY sample of ONE colour a person chose — a brand's primary_color, a calendar category, a tag tint. The colour is a VALUE on the element, never a token in a stylesheet.",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`: `import { Swatch } from \"@godxjp/ui/data-display\";`",
+    "DO give it an aria-label whenever it is the only thing on screen saying what the colour is, and omit the label when the row's own text already says it — a swatch that repeats its neighbour announces the same thing twice.",
+    "DO let the hairline do its job: it is built in so a white or near-white value is still a visible sample on a white card, and it survives forced-colors (the colour IS the content here, so it is not repainted).",
+    "DON'T reach for it for a STATUS colour. success/warning/overdue are meanings, and a meaning belongs on Badge `tone` or in a Legend, which spell the meaning out in words.",
+    "DON'T render a disabled ColorPicker to display a colour — that is an input that looks broken. ColorPicker is for CHOOSING the value; Swatch is for showing it.",
+    "DON'T size it with a className. The mark's size, radius and hairline are the --swatch-* tokens, so a theme retunes every sample at once."
+  ],
+  "useCases": [
+    "An organisation's brand card: primary_color and secondary_color beside the organisation name, read-only, with the hex in the accessible name.",
+    "A list of calendar categories, label colours or tags where each row's own text already names the colour and the mark is purely visual.",
+    "A settings screen showing the colour currently saved, next to the ColorPicker that changes it.",
+    "A table cell whose column is 'colour' — one sample per row, named by the row header."
+  ]
+}

package/agent/components/Switch.json

@@ -0,0 +1,81 @@
+{
+  "example": "import { Field, Switch } from \"@godxjp/ui/data-entry\";\n\n// Field, not a hand-rolled row: it owns the label-to-control id wiring, the description slot and\n// the row rhythm. A <div className=\"flex items-center gap-2\"> around a bare <Label> loses all three.\n<Field id=\"stackable\" label=\"他クーポンとの併用を許可\" description=\"会計時に自動で合算されます\">\n  <Switch id=\"stackable\" checked={stackable} onCheckedChange={setStackable} />\n</Field>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Switch",
+  "props": [
+    {
+      "defaultValue": "false",
+      "description": "antd `loading` — the toggle is mid-flight: a spinner replaces the thumb glyph and the control refuses the change. It reports `aria-busy`/`aria-disabled` rather than `disabled`, so a keyboard user's focus is not thrown to the next field the instant they flip a switch that saves over the network.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `checkedChildren` — content shown INSIDE the track while on (`有効`, `ON`, a glyph). Rendered aria-hidden: `role=switch` + `aria-checked` already say on/off.",
+      "name": "checkedChildren",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `unCheckedChildren` — the same, shown while off.",
+      "name": "unCheckedChildren",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Controlled checked state.",
+      "name": "checked",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Uncontrolled initial state. Switch keeps its own state from here, so an uncontrolled toggle works without Field.",
+      "name": "defaultChecked",
+      "type": "boolean"
+    },
+    {
+      "description": "Fires when toggled.",
+      "name": "onCheckedChange",
+      "type": "(checked: boolean) => void"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Thumb size — 'sm' for dense rows.",
+      "name": "size",
+      "type": "\"sm\" | \"md\""
+    },
+    {
+      "description": "Links to a <Label htmlFor>.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disable the toggle.",
+      "name": "disabled",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Field — use this instead of a bare Switch whenever the toggle needs a visible label, a description, a pressable help affordance (`labelAddon`) or a validation message (`error`, which wires aria-invalid / aria-errormessage / aria-describedby for you, gh#812). Native submission is the Switch's own job: give it `name` and it renders the hidden input itself.",
+    "Checkbox — use Checkbox (or CheckboxGroup) when the user is selecting one or more items from a set, or when the binary choice semantically means 'agree/select' rather than 'enable/disable'. Switch implies an immediate, persistent state change; Checkbox implies a form choice.",
+    "Field — use for a binary or small-set choice rendered as radio-style cards with rich descriptions, when the visual weight of a toggle is insufficient for the decision importance.",
+    "RadioGroup — use when the user must choose exactly one option from 2–4 mutually exclusive values; Switch is only appropriate for a single on/off boolean."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/Switch.stories.tsx",
+  "tagline": "Toggle switch (bare), on react-aria-components. For a labelled row use Field. `role=\"switch\"` is the real `<input>`; the painted track is the `<label>` around it, and that is where `data-state`/`data-size` live.",
+  "usage": [
+    "DO use Switch (bare) only when you are building a custom inline toggle without a visible label — e.g., a DataTable row action column. Always pair it with a <Label htmlFor={id}> placed adjacent in the DOM; never leave it label-less for screen readers.",
+    "DO pass `name` when the toggle must submit: Switch itself renders `<input type=\"hidden\" name value=\"1|0\">` beside the control, so a native <form> carries the value with no extra wiring. (The old advice here — that a bare Switch drops `name` — was never true of this component.)",
+    "DO use the `size` prop ('sm' | 'md') to control thumb size. 'sm' is appropriate in dense DataTable rows or filter bars; omit it (defaults to 'md') everywhere else.",
+    "DO wire controlled state: pass both `checked` and `onCheckedChange` together. For uncontrolled use pass `defaultChecked` (or neither) — Switch holds that state itself; Field is not required for it.",
+    "DON'T hand-roll a <div> + <label> wrapper with bare Switch to get a labelled field — that is exactly what Field provides, including aria-describedby, aria-invalid, error/helper text, and the hidden input. Reach for Field instead.",
+    "DO link the switch to its label via matching `id` on Switch and `htmlFor` on Label. Without this pairing, clicking the label text does not toggle the switch and the a11y association is broken."
+  ],
+  "useCases": [
+    "Inline toggle in a DataTable action cell (e.g., 'Active' column) where the label is already provided by the column header and no form submission is involved.",
+    "Settings panel where a React state boolean is toggled immediately via an optimistic API call — no <form> submit, so Field's hidden input is unnecessary.",
+    "Custom compound component where you compose Switch + Label yourself and need to put your own aria-* or data-* attributes on the control.",
+    "Filter toolbar toggle (e.g., 'Show archived') rendered inline next to other filter controls, using size='sm' for density parity with adjacent inputs.",
+    "Preview/demo UI where the switch controls a local display state (dark-mode preview, feature flag preview) with no server persistence."
+  ]
+}

package/agent/components/Table.json

@@ -0,0 +1,112 @@
+{
+  "example": "import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from \"@godxjp/ui/data-display\";\n\n<Table>\n  <TableHeader><TableRow><TableHead>項目</TableHead><TableHead numeric>金額</TableHead></TableRow></TableHeader>\n  <TableBody>\n    <TableRow><TableCell>送料</TableCell><TableCell numeric>¥500</TableCell></TableRow>\n    <TableRow><TableCell indent={1}>うち離島加算</TableCell><TableCell numeric>¥200</TableCell></TableRow>\n    <TableRow><TableCell flush colSpan={2}><ShippingBreakdown /></TableCell></TableRow>\n  </TableBody>\n</Table>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Table",
+  "props": [
+    {
+      "description": "PER-INSTANCE column measures for preset=\"action-collection\", in place of re-pointing its --table-action-collection-* knobs from a consumer stylesheet. Those knobs are global by design, and that is the problem: two collections on one screen do not share a column budget — a console that widened `actions` globally so a Japanese status badge would stop breaking to one character per line (an SC 1.4.10 reflow failure) collapsed a sibling table's name column to ~15px in the same change. Emitted as inline custom properties, the same contract Flex `width` uses for a call-site measurement, leaving data-column-widths on the DOM so each escape stays countable.",
+      "name": "columnWidths",
+      "type": "{ actions?: string; actionsCompact?: string; metaCompact?: string; minInlineSizeCompact?: string }"
+    },
+    {
+      "description": "On TableHead/TableCell: logical text alignment.",
+      "name": "align",
+      "type": "\"start\" | \"center\" | \"end\""
+    },
+    {
+      "description": "On TableHead/TableCell: tabular figures and end alignment; explicit align wins.",
+      "name": "numeric",
+      "type": "boolean"
+    },
+    {
+      "description": "On TableHead/TableCell: allow text to wrap.",
+      "name": "wrap",
+      "type": "boolean"
+    },
+    {
+      "description": "On TableHead/TableCell: column measure; numbers mean CSS pixels.",
+      "name": "width",
+      "type": "WidthProp"
+    },
+    {
+      "description": "TableHeader / TableBody composition.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Extra classes on the table element.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "Whether Table owns its own horizontal-scroll region (default true). Leave true for a standalone table so a table wider than its container scrolls in a keyboard-reachable wrapper. Set false only when an ancestor already provides the scroll region (DataTable does) to avoid a redundant nested scroller + duplicate keyboard tab stop.",
+      "name": "scrollable",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Draw the full cell GRID: an outer frame plus vertical rules between columns (the horizontal row rules already come from TableRow). Reach for it whenever the table carries rowSpan/colSpan merged cells — without column rules the merge relationships are unreadable. Colour comes from --table-border-color (default --border). Default false emits nothing.",
+      "name": "bordered",
+      "type": "boolean"
+    },
+    {
+      "description": "Zebra rows: every EVEN LOGICAL body row paints --table-row-striped-background (default --muted at 0.8 alpha — every text role on it stays at AA). Mark a hand-composed detail row `<TableRow data-expanded-row=\"\">` and it is skipped when counting and wears its record's stripe. OMIT to inherit the theme default (`--table-row-striped-alpha`, 0% unless the service set it); `true` emits data-striped=\"\" (100%), `false` emits data-striped=\"false\" (0%) for this table only.",
+      "name": "striped",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Named collection contract. \"default\" emits no attribute and keeps the plain table. \"action-collection\" is the canonical dense approval/action queue: the desktop INTRINSIC column widths (which make a five-column queue wider than its card and force a horizontal scroll at 390) are replaced by table-layout: fixed plus the token-owned column PRIORITY measures (--table-action-collection-*), and cells wrap. Mark each column with `priority` on its TableHead AND its TableCell. Semantics are untouched — no display change, no role rewriting, no card transformation — so header association, aria-sort and screen-reader table navigation are identical at 390 and 1440.",
+      "name": "preset",
+      "type": "\"default\" | \"action-collection\""
+    },
+    {
+      "defaultValue": "\"sm\"",
+      "description": "Step at which preset=\"action-collection\" switches to the compact priority measures, measured against the TABLE'S OWN container (a container query), not the viewport — a table inside a master rail collapses before the page does. Ignored while preset is \"default\".",
+      "name": "collapseBelow",
+      "type": "\"sm\" | \"md\" | \"lg\" | \"xl\""
+    },
+    {
+      "description": "Accessible name for the horizontal-scroll REGION — the tabindex=\"0\" wrapper a keyboard user lands on to scroll a table wider than its container — NOT for the <table> element (pass aria-label for that; it still reaches the table). OPTIONAL: left out, the region takes the localized dataTable.scrollRegion default (\"Scrollable table\"), so no consumer has to invent a name for every table. Pass a plain string when the page can say WHICH table; a non-string node cannot be an aria-label and falls back to the default. The wrapper carries role=\"group\" (not \"region\" — a named region is a LANDMARK, and several tables on one page would then collide under axe landmark-unique) and is emitted ONLY while the region actually has overflow to reach, measured at runtime: a table that fits adds no tab stop, no role and no name. (gh#817)",
+      "name": "label",
+      "type": "LabelProp"
+    }
+  ],
+  "related": [
+    "DataTable — choose DataTable for any data array that needs sorting, filtering, pagination, row selection, bulk actions, or density toggle. DataTable internally renders Table primitives, so switching up is non-breaking. Default to DataTable for all admin list pages.",
+    "SkeletonTable — use as a loading placeholder before a Table or DataTable mounts. Drop it in the `skeleton` slot of DataState, or render it directly while data is fetching. Do not show a Table with empty rows as a loading state.",
+    "Descriptions — choose Descriptions when content is label→value pairs (two columns, no repeated rows of the same type). Table is better when every row shares the same typed columns.",
+    "DataState — when your Table's data comes from `useQuery`, wrap it in DataState to handle loading/error/empty states declaratively instead of writing conditional logic around the Table yourself."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Table.stories.tsx",
+  "subParts": [
+    "TableBody",
+    "TableCell",
+    "TableHead",
+    "TableHeader",
+    "TableRow"
+  ],
+  "tagline": "Primitive table shell (Table/TableHeader/TableBody/TableRow/TableHead/TableCell). Prefer DataTable for admin lists; use these for custom one-off tables.",
+  "usage": [
+    "DO compose all six sub-parts in order: wrap with `<Table>`, then `<TableHeader>` containing `<TableRow><TableHead>…</TableRow>`, then `<TableBody>` containing one or more `<TableRow><TableCell>…` rows. Skipping any layer (e.g. bare `<th>` inside `<Table>`) bypasses the design tokens and hover/border styles.",
+    "DO use `TableHead` (not `TableCell`) for header cells — it renders `<th>` with `data-slot=\"table-head\"` and the `--table-row-height` CSS variable for consistent header sizing across the design system. `TableCell` renders `<td>` with `data-slot=\"table-cell\"` and is for body rows only.",
+    "DO use `numeric` on TableHead/TableCell for tabular end-aligned numbers; `align=\"start|center|end\"` overrides alignment, `wrap` allows multi-line text, and `width` sets a CSS column measure. These props replace alignment and width classes.",
+    "DO use `striped` on dense list tables so a row is easy to follow across its columns; to turn it on for EVERY Table and DataTable at once, set `:root { --table-row-striped-alpha: 100%; }` in the theme rather than passing the prop everywhere (`striped={false}` opts one table out). A detail row under a record is `<TableRow data-expanded-row=\"\">` so the stripe counts records, not DOM rows — never stripe with `:nth-child` page CSS or row utilities.",
+    "DO NOT hand-roll empty-state handling inside a Table composition. When data can be empty, switch to `DataTable` (which has a built-in empty state) or wrap the `<Table>` with a conditional that renders `<EmptyState>` — never leave a table with only a header and zero rows.",
+    "DO NOT use Table for lists that need sorting, filtering, pagination, or row selection — those features are only in `DataTable`. Table is intentionally stateless: it owns no TanStack Table instance, no column definitions, and no toolbar.",
+    "DO reach for `preset=\"action-collection\"` for a dense approval / action queue (requester · target · reason · requested date · row actions) that must stay readable at 390px, and mark every column with `priority` on BOTH its `TableHead` and its `TableCell`: `primary` (the row subject), `secondary` (its target), `meta` (a timestamp/id), `actions` (the row-action affordance, whose measure is reserved first so it can never be pushed off-screen). Leave the free-text column unmarked — it takes the remaining space. For text actions such as 対応する, set ColumnDef.width (or TableHead width) to reserve the label measure; leave a content column fluid. The default actions token is sized for icon actions. Do not add a hidden column or page-local breakpoint to make a table fit. The IDENTICAL preset exists on `DataTable` (`preset` + `collapseBelow` on the table, `priority` on the `ColumnDef`) sharing these same tokens — use DataTable when the queue is data-driven and needs sorting/selection/pagination, and reach for the raw `Table` only for a hand-authored queue.",
+    "DO reach for `<TableCell flush>` when the cell's CONTENT owns its inset — an expanded detail panel under a row (`<TableCell flush colSpan={n}>`), a nested table, a full-bleed media strip. It drops the cell's own padding so the child spans the whole cell; without it the panel is indented by `--table-cell-space-x` and the only route was a `p-0` utility, which no service theme can reach.",
+    "DO express hierarchy with `<TableCell indent={depth}>` — a grouped table's detail rows under their subtotal header, or a tree row under its parent. The measure is `--table-cell-space-x + depth x --table-cell-indent-space-step`, so level 0 sits on the column's own text axis and a service retunes (or flattens) the step in one token. Never hand-roll `style={{ paddingInlineStart }}` at the call site — that is a per-page constant no theme can reach, and it breaks in RTL unless you remember the logical property.",
+    "DO place `<Table>` inside a `<CardContent flush>` (or `p-0` card) when embedding in a Card, so the built-in `overflow-auto` wrapper sits flush to the card edges. Wrapping with plain `<CardContent>` adds padding that clips the horizontal scroll shadow."
+  ],
+  "useCases": [
+    "Invoice line-item breakdowns — a fixed, read-only list of product/quantity/unit-price/total rows where columns are predefined and will never need sort or filter controls.",
+    "Summary/comparison tables inside a detail panel or Dialog, such as showing two payment plans side-by-side, where the structure is hand-authored and not driven by a data array.",
+    "Print or PDF-export views where a minimal, stateless `<table>` element with predictable markup is required and DataTable's JS-driven features would interfere with server-side rendering or CSS print rules.",
+    "Embedded sub-tables inside a DataTable expanded row (the inner table uses Table primitives because nesting a full DataTable instance inside another is unsupported).",
+    "Static reference tables in documentation, onboarding, or settings pages — e.g. a permission matrix or feature comparison — where every cell is literal JSX content, not from a data array."
+  ]
+}