@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/RadioGroup.json

@@ -0,0 +1,91 @@
+{
+  "example": "import { RadioGroup } from \"@godxjp/ui/data-entry\";\n\n<RadioGroup value={trigger} onValueChange={setTrigger} orientation=\"horizontal\" options={[\n  { label: \"初回購入\", value: \"first_purchase\" },\n  { label: \"誕生日\", value: \"birthday\" },\n]} />",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "RadioGroup",
+  "props": [
+    {
+      "defaultValue": "\"default\"",
+      "description": "antd `optionType` — how each choice is DRAWN. `default` is a radio dot beside its label; `button` welds the choices into one segmented bar. The role stays `radiogroup`/`radio` either way: this is paint, never semantics, so a screen reader hears the same group in both.",
+      "name": "optionType",
+      "type": "\"default\" | \"button\""
+    },
+    {
+      "defaultValue": "\"outline\"",
+      "description": "antd `buttonStyle` — fill of the SELECTED choice while `optionType=\"button\"`. Inert on the default option type.",
+      "name": "buttonStyle",
+      "type": "\"outline\" | \"solid\""
+    },
+    {
+      "description": "Id của nhóm; `FormField` tự truyền xuống để nối nhãn ↔ control.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Controlled selected value.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Fires on selection change.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Declarative list: { label, value, disabled?, description? }.",
+      "name": "options",
+      "type": "ChoiceOptionProp[]"
+    },
+    {
+      "defaultValue": "\"vertical\"",
+      "description": "Layout direction.",
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\""
+    },
+    {
+      "description": "Uncontrolled initial selected value.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Disable the whole group.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Form field name for native submission.",
+      "name": "name",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "CheckboxGroup — use when the user may select zero or more values simultaneously (multi-select); RadioGroup enforces exactly one selection. Both share the same options array shape and orientation prop.",
+    "Select — use when there are 5 or more options or the option list is dynamic/searchable; RadioGroup is preferred for 2-4 fixed visible choices where scanning all options at once matters.",
+    "Field — use when there are exactly two states that map to on/off (boolean); RadioGroup is the right pick when the two-or-more options are semantically distinct named values, not a toggle.",
+    "Field — the low-level label+description wrapper that RadioGroup uses internally for each item. Use it directly only when manually composing Radio.Item children inside Radio.Group; never hand-roll a label alongside a bare Radio.Item without it."
+  ],
+  "rules": [
+    23
+  ],
+  "storyPath": "data-entry/RadioGroup.stories.tsx",
+  "subParts": [
+    "RadioGroupRoot"
+  ],
+  "tagline": "Radio group accepting an options array or RadioItem children.",
+  "usage": [
+    "DO use the `options` prop for the data-driven path: pass `{ label, value, disabled?, description? }[]` and RadioGroup renders every option as a correctly labelled Field automatically — never hand-roll Radio.Item + Label pairs in a loop yourself.",
+    "DO provide `name` whenever the group lives inside an HTML form: Radix renders a hidden `<input name={name}>` carrying the selected string value, making the field natively form-submittable without a separate hidden input.",
+    "DO use controlled mode (`value` + `onValueChange`) for any form managed by useForm or a state manager. Use `defaultValue` only for truly uncontrolled UI where you never need to read the value in code.",
+    "DO NOT reach for children / manual composition unless the options list is dynamic-JSX (e.g. each item needs a custom rendered label with an icon). When you do compose children manually, wrap each Radio.Item in a Field — rendering a bare Radio.Item without Field skips the label and breaks a11y.",
+    "DO NOT use RadioGroup when the user may select zero or multiple items — that is CheckboxGroup. RadioGroup enforces exactly one selection at all times (or none before first interaction when uncontrolled).",
+    "A11y: the root emits `role=radiogroup`; each item is a real `<input type=\"radio\">` (implicit `role=radio`) and is keyboard-navigable with arrow keys. Never suppress `name` on the Root when inside a form — without it the input is unnamed and won't submit. Name an item with `<Label htmlFor>` (or `Field`) BESIDE it, never by wrapping it: the control already sits inside its own `<label>`, and a second one nested outside leaves it nameless."
+  ],
+  "useCases": [
+    "Selecting a single billing cycle (monthly / quarterly / annual) in an invoice or subscription settings form where all 2-4 options must be visible at once.",
+    "Choosing a report output format (PDF / CSV / Excel) before triggering an async export job — keeps all options scannable without opening a dropdown.",
+    "Picking a transaction type (income / expense / transfer) on an accounting entry form where the choice changes which subsequent fields are shown.",
+    "Selecting a sync trigger mode (first purchase / birthday / manual) in a campaign or automation settings panel — matches the catalog example exactly.",
+    "Filtering a compact inline control (horizontal orientation) such as date granularity (day / week / month) inside a dashboard filter bar where a full Select dropdown would be over-engineered.",
+    "Choosing an approval status (pending / approved / rejected) on an admin detail sheet where all states must be visible so reviewers can compare them without interaction."
+  ]
+}

package/agent/components/RangeTimeline.json

@@ -0,0 +1,80 @@
+{
+  "docPath": "docs/data-display/timeline.tsx",
+  "example": "<RangeTimeline label=\"Schedule\" columns={[{ label: \"Week\", units: 7 }]} rows={[{ id: \"task\", label: \"Task\", start: 0, end: 6, startLabel: \"Start: day 1\", endLabel: \"End: day 7\" }]} />",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "RangeTimeline",
+  "props": [
+    {
+      "description": "Localized accessible name for the scrollable schedule.",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Positive unit counts determine proportional column widths. Column count determines the minimum canvas width, so coarse grouping zooms out. `muted: true` tints that column down the whole body (a weekend, a holiday, a closed period) with `--range-timeline-muted-column-background` (default `hsl(var(--muted))`, the header surface; body text keeps 14.25:1 / 12.4:1 and `--muted-foreground` 5.2:1 / 5.47:1 on it).",
+      "name": "columns",
+      "required": true,
+      "type": "{ label: string; units: number; muted?: boolean }[]"
+    },
+    {
+      "description": "Optional grouped axis labels above the ticks, for example months above days. Counts use the same units as columns and cover the same range.",
+      "name": "bands",
+      "type": "{ label: string; units: number }[]"
+    },
+    {
+      "description": "Each row has id, label, inclusive start/end unit offsets, and localized startLabel/endLabel including current values. Optional `depth` (0 = top level) nests rows: pass them flat and depth-first (a parent, then its descendants); a row is a parent when the row after it is deeper. The component indents the label cell by `--range-timeline-indent-width` per level (logical padding, so RTL indents from the right; the label column keeps its width) and gives each parent a disclosure button. With no `depth > 0` anywhere the markup is unchanged.",
+      "name": "rows",
+      "required": true,
+      "type": "RangeTimelineRow[]"
+    },
+    {
+      "description": "Optional current unit marker.",
+      "name": "today",
+      "type": "number | null"
+    },
+    {
+      "description": "Committed endpoint movement in units. Omit for read-only. Dates remain consumer data; do not replace true anchors with clipped positions.",
+      "name": "onRangeChange",
+      "type": "(id: string, edge: \"start\" | \"end\", delta: number) => void"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Rule the body as a Gantt grid: a line between every row (label column and track), a line under the header and between band and tick rows, and a vertical line per column down the whole body, exactly under its header column edge for unequal `units` too. ON BY DEFAULT, like `Calendar bordered`. The lines are one decorative layer (aria-hidden, pointer-events none) behind the bars. TWO TIERS, and they are different knobs: the INSIDE grid is `--range-timeline-grid-color`, default `hsl(var(--border))` (L* 93.80 / 1.149:1 on the card in light, L* 20.76 / 1.270:1 in dark) at `--range-timeline-grid-width` (hairline); the OUTER FRAME and the label-column divider are `--range-timeline-border-color`, default `var(--border)` — the same tier, so the grid can never read heavier than the box around it or than a DataTable row rule. It was `hsl(var(--input) / 0.5)` (L* 78.67 / 1.738:1) through 27.6.0 and was reported darker than every card and table in the system (gh#730); set `--range-timeline-grid-color: hsl(var(--input) / 0.5)` to get that weight back. `bordered={false}` restores header-only ruling; muted columns still paint.",
+      "name": "bordered",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Width of ONE axis unit — the canonical density vocabulary, the same three steps `DataTable density` takes. `default` is the shipped 56px/day, so no existing Gantt moves; `compact` is 42px/day (a 31-day axis needs 1558px instead of 1992px — measured, the widest two-digit day label across ja/en/ar/fa/hi/th/bn numbering systems is 19.86px in a 24px content box, so the tick still fits); `comfortable` is 70px/day. It moves the COLUMN WIDTH ONLY — row height, bar height and the label column are identical at every step, so a compact Gantt is the same schedule with more days on screen, not a smaller one. Re-points `--range-timeline-unit-width` on the element; retune a step with `--range-timeline-unit-width-{compact,default,comfortable}`. Unrelated to `PageContainer density` / `AppProvider density`, which rescale the whole page through `--scaling`.",
+      "name": "density",
+      "type": "\"compact\" | \"default\" | \"comfortable\""
+    },
+    {
+      "description": "Controlled ids of the EXPANDED parent rows (same spelling as `Tree expandedValues`). A folded parent removes every descendant row — label AND bar — from the DOM and the accessibility tree; the body grid, row rules and today marker stay aligned.",
+      "name": "expandedValues",
+      "type": "readonly string[]"
+    },
+    {
+      "description": "Uncontrolled initial expanded parents. Omitted: every parent starts expanded (unlike `Tree`, whose branches start closed), so adding `depth` never hides a row.",
+      "name": "defaultExpandedValues",
+      "type": "readonly string[]"
+    },
+    {
+      "description": "Fires with the next expanded parent ids when a disclosure is toggled, for controlled and uncontrolled timelines alike.",
+      "name": "onExpandedValuesChange",
+      "type": "(values: string[]) => void"
+    }
+  ],
+  "rules": [],
+  "storyPath": "data-display/timeline.tsx",
+  "tagline": "Horizontal intervals with token-owned geometry and optional endpoint editing.",
+  "usage": [
+    "Provide a precise non-drag editor in each row label when enabling changes. Clipped endpoints and short intervals omit grips; labels and their editors remain available.",
+    "An interval wholly outside the columns shows a localized direction indicator at that edge of its row: a chevron plus \"before\" at the inline-start edge, \"after\" plus a chevron at the inline-end edge; the chevrons mirror under RTL.",
+    "Mark non-working columns with `columns[].muted` rather than tinting cells yourself; retint the grid through `--range-timeline-grid-color` / `--range-timeline-muted-column-background`, never page CSS.",
+    "Need more days on one screen? Pass `density=\"compact\"` — do NOT declare `--range-timeline-unit-width` in an app stylesheet. Tick and band labels are CENTRED on their column by the component; a band clipped by the range (a month the axis starts inside) centres its label on the VISIBLE part, since that is the box the band owns.",
+    "Use TimelineGrid for time-of-day columns; RangeTimeline is a horizontal range axis.",
+    "Nested Gantt (parent/child work items): pass the server's depth-first rows with `depth` on each (`{ id, label, start, end, startLabel, endLabel, depth }`), and fold with `expandedValues` / `onExpandedValuesChange` (or `defaultExpandedValues`). Never fake an indent inside `label` — the component owns the indent, the disclosure button (named from `rangeTimeline.childRows` + the row label, `aria-expanded`) and the `list` / `listitem` + `aria-level` / `aria-setsize` / `aria-posinset` structure."
+  ]
+}

package/agent/components/Rating.json

@@ -0,0 +1,92 @@
+{
+  "example": "import { Rating } from \"@godxjp/ui/data-entry\";\n\n<Rating name=\"score\" defaultValue={4} onValueChange={(v) => console.log(v)} />",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Rating",
+  "props": [
+    {
+      "defaultValue": "5",
+      "description": "antd `count` — number of symbols. This library's older `max` still works; `count` wins when both are given.",
+      "name": "count",
+      "type": "number"
+    },
+    {
+      "defaultValue": "false",
+      "description": "antd `allowHalf` — a symbol can be half-filled, so the scale steps by 0.5 (keyboard included). It adds a hit area per symbol WITHOUT doubling the radios: a half is a position inside a step, and ten radios announced for a five-star scale would misstate the scale.",
+      "name": "allowHalf",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "antd `allowClear` — choosing the chosen value clears it to 0. antd defaults this ON; it is OFF here, because a rating in a business form is usually required and a silent reset on a second click reads as a lost answer.",
+      "name": "allowClear",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `character` — what a symbol IS. A node for every symbol, or a function of the 1-based index for a scale whose symbols differ (A/B/C, 松竹梅).",
+      "name": "character",
+      "type": "React.ReactNode | ((index: number) => React.ReactNode)"
+    },
+    {
+      "description": "antd `tooltips` — a label per step, in order. Folded into each symbol's ACCESSIBLE NAME rather than shown only on hover: a `title` is invisible to a keyboard and to touch, and saying what '3 of 5' means is the whole point of the prop.",
+      "name": "tooltips",
+      "type": "readonly string[]"
+    },
+    {
+      "description": "Controlled rating (1..max).",
+      "name": "value",
+      "type": "number"
+    },
+    {
+      "defaultValue": "0",
+      "description": "Uncontrolled initial rating.",
+      "name": "defaultValue",
+      "type": "number"
+    },
+    {
+      "description": "Rating callback.",
+      "name": "onValueChange",
+      "type": "(value: number) => void"
+    },
+    {
+      "defaultValue": "5",
+      "description": "Number of stars.",
+      "name": "max",
+      "type": "number"
+    },
+    {
+      "description": "Display-only (e.g. an average score).",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "Hidden input name for native form submission.",
+      "name": "name",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "RadioGroup (non-star single choice)",
+    "Slider (continuous 0-100 value)"
+  ],
+  "rules": [
+    3,
+    6,
+    23
+  ],
+  "storyPath": "data-entry/Rating.stories.tsx",
+  "tagline": "Star-rating input (radiogroup) — controlled via value/onValueChange, form-submittable via name, supports readOnly display.",
+  "usage": [
+    "DO theme the stars with `--rating-star-filled-color` (default `var(--warning)`) and `--rating-star-empty-color` (default `var(--muted-foreground)`, at `--rating-star-empty-alpha` 0.45) — HSL components, set on :root or a scoped [data-tenant] (gh#694). NEVER override `.ui-rating-star-filled`: it is an internal class. Unset, the stars paint exactly as before.",
+    "DO use readOnly to DISPLAY a score (e.g. product average); interactive (default) for collecting a rating.",
+    "DO pass `name` to submit the value in a plain form.",
+    "DON'T render raw star icons for input — this handles keyboard (radiogroup), hover preview, and a11y.",
+    "NOTE a long scale WRAPS rather than overflowing. At `max={10}` the row needs ~276px of hit area and a 320px viewport offers ~212 inside a card, so the stars fall onto a second line instead of being painted where no one can reach them. Don't add `flex-nowrap` or a fixed width to force one line; use a smaller `max` if a single row matters."
+  ],
+  "useCases": [
+    "Product / vendor review input",
+    "Display an average score (readOnly)",
+    "Feedback / CSAT survey",
+    "Priority or quality scoring in admin"
+  ]
+}

package/agent/components/ResizablePanel.json

@@ -0,0 +1,69 @@
+{
+  "example": "import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from \"@godxjp/ui/layout\";\n\n<ResizablePanelGroup orientation=\"horizontal\">\n  <ResizablePanel id=\"list\" defaultSize=\"35%\" minSize=\"20%\">Panel A</ResizablePanel>\n  <ResizableHandle />\n  <ResizablePanel id=\"detail\" defaultSize=\"65%\" minSize=\"40%\">Panel B</ResizablePanel>\n</ResizablePanelGroup>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "ResizablePanel",
+  "props": [
+    {
+      "defaultValue": "\"horizontal\"",
+      "description": "ResizablePanelGroup prop — axis the panels are laid out / resized along (horizontal = side-by-side).",
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\""
+    },
+    {
+      "description": "ResizablePanel identifier — required for collapse/expand control and for layout persistence.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "For a percentage of the group pass a string like \"35%\" — `defaultSize={35}` means 35px (a sliver), not 35%.",
+      "name": "defaultSize",
+      "type": "string | number"
+    },
+    {
+      "description": "ResizablePanel minimum size — drag can't shrink below this. Same unit rule: \"20%\" for percent, bare number = px.",
+      "name": "minSize",
+      "type": "string | number"
+    },
+    {
+      "description": "ResizablePanel maximum size. \"60%\" for percent, bare number = px.",
+      "name": "maxSize",
+      "type": "string | number"
+    },
+    {
+      "defaultValue": "false",
+      "description": "ResizablePanel — allow the panel to collapse to collapsedSize when dragged below minSize. Pair with onResize to react to collapse.",
+      "name": "collapsible",
+      "type": "boolean"
+    },
+    {
+      "description": "ResizablePanel — fires while/after the panel is resized (e.g. to persist layout).",
+      "name": "onResize",
+      "type": "(size: PanelSize, id, prevSize) => void"
+    }
+  ],
+  "rules": [
+    3,
+    6
+  ],
+  "storyPath": "layout/ResizablePanel.stories.tsx",
+  "subParts": [
+    "ResizableHandle",
+    "ResizablePanelGroup"
+  ],
+  "tagline": "Resizable panel group/child/handle primitives from react-resizable-panels.",
+  "usage": [
+    "DO put the layout on `<ResizablePanelGroup orientation=\"horizontal|vertical\">`, the resizable regions in `<ResizablePanel>`, and a `<ResizableHandle>` BETWEEN every adjacent pair — a group of N panels needs N-1 handles or there is nothing to drag.",
+    "DO express `defaultSize`/`minSize`/`maxSize` as PERCENTAGE STRINGS like `defaultSize=\"35%\"` (react-resizable-panels v4: a bare number is PIXELS, so `defaultSize={35}` renders a 35px sliver, NOT 35% — pass the string). Don't fight sizing with a fixed `w-[280px]` className on the panel.",
+    "DON'T reach for ResizablePanel when the split is fixed and never user-adjustable — use a plain `Flex`/`ResponsiveGrid`, or `SplitPane` for a simple two-pane layout. Resizable is for *user-draggable* boundaries only.",
+    "DO give each panel a stable `id` and use `collapsible` + `collapsedSize` for a side panel the user can fully tuck away (e.g. a filters rail), reacting via `onResize`.",
+    "DON'T hand-roll a draggable divider with mouse-move listeners — the primitive handles pointer + keyboard resizing, ARIA separator semantics, and min/max clamping. Always render `<ResizableHandle>`, never a bare styled `<div>`.",
+    "DON'T add your own `overflow: auto` wrapper inside a panel: the panel IS the scroll container. Let it own the scrolling and it also manages keyboard reachability — when a panel scrolls but holds nothing focusable, ResizablePanel gives it `tabindex=0` so keyboard users can still reach the clipped content (WCAG 2.1.1); a panel whose content is focusable is left alone, so no redundant tab stop appears. Your own nested scroller gets neither."
+  ],
+  "useCases": [
+    "Master–detail admin layout: a draggable list pane on the left and a detail/preview pane on the right (e.g. 仕訳一覧 | 仕訳詳細).",
+    "Collapsible filters or navigation rail beside a data table that operators can widen for long labels or tuck away to maximize the table.",
+    "Stacked vertical split (orientation='vertical') such as a results table over a live JSON/log preview in a data-import tool.",
+    "Three-pane workbench (nav | content | inspector) where each boundary is independently draggable and layout is persisted via id + onResize."
+  ]
+}

package/agent/components/ResponsiveGrid.json

@@ -0,0 +1,77 @@
+{
+  "example": "import { ResponsiveGrid } from \"@godxjp/ui/layout\";\nimport { StatCard } from \"@godxjp/ui/data-display\";\n\n<ResponsiveGrid columns={4}>\n  <StatCard label=\"総会員数\" value=\"12,400\" />\n  <StatCard label=\"公開中クーポン\" value=\"8\" />\n  <StatCard label=\"月間利用数\" value=\"3,210\" />\n  <StatCard label=\"割引総額\" value=\"¥480,000\" />\n</ResponsiveGrid>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "ResponsiveGrid",
+  "props": [
+    {
+      "description": "Measured inset escape; stamped data-pad-raw.",
+      "name": "padRaw",
+      "type": "PadRawProp"
+    },
+    {
+      "description": "Token inset, scalar or logical sides.",
+      "name": "pad",
+      "type": "PadProp"
+    },
+    {
+      "defaultValue": "\"rows\"",
+      "description": "Rows adapt to container width. Columns keep a horizontal collection in order with token-owned column width; compose inside ScrollArea orientation=\"horizontal\". Column flow ignores columns and preset geometry.",
+      "name": "flow",
+      "type": "\"rows\" | \"columns\""
+    },
+    {
+      "description": "antd `Row align`, spelled with Flex's FlexAlignProp values (antd `top` → \"start\"). \"stretch\" makes every cell as tall as the tallest one. Omitted, flow=\"columns\" keeps \"start\" and flow=\"rows\" keeps the grid's natural stretch.",
+      "name": "align",
+      "type": "\"start\" | \"stretch\""
+    },
+    {
+      "defaultValue": "4",
+      "description": "Numeric desktop target, or container column counts. Base defaults to 1; omitted object steps inherit upward. Use { base: 2, sm: 4 } for compact metric tiles.",
+      "name": "columns",
+      "type": "number | { base?: number; sm?: number; md?: number; lg?: number }"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Token gap between cells, the same steps as Flex. \"none\" is a DELIBERATE zero for tiles that must read as one continuous surface (a segmented bar, a seamless tile strip) — not a way to opt out of the token scale.",
+      "name": "gap",
+      "type": "\"none\" | \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\""
+    },
+    {
+      "description": "Grid items — typically Card or StatCard.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "Flex — use Flex (direction col or row) for sequential blocks of mixed-width content (forms, description lists, button rows). Use ResponsiveGrid only when you want equal-width, auto-reflowing tile columns.",
+    "SplitPane — use SplitPane for a fixed two-panel side-by-side layout with a defined primary/secondary ratio that does NOT collapse to stacked tiles. Use ResponsiveGrid when you want automatic column count collapse on narrow screens.",
+    "StatCard — the canonical direct child of ResponsiveGrid for KPI tiles. StatCard is self-contained (draws its own bordered card); never wrap it in Card/CardContent when placing it inside ResponsiveGrid.",
+    "SkeletonStat — the loading-state sibling of StatCard, used as a drop-in placeholder child of ResponsiveGrid with the same columns count while KPI data is in flight."
+  ],
+  "rules": [
+    24,
+    40
+  ],
+  "storyPath": "layout/ResponsiveGrid.stories.tsx",
+  "tagline": "Container-responsive card grid with configurable base, sm, md and lg columns.",
+  "usage": [
+    "ResponsiveGrid.Item span={2} owns a responsive column span; an object {base:1,lg:2} sets explicit steps, clamped to the parent columns.",
+    "KANBAN LANES: <ScrollArea orientation=\"horizontal\"><ResponsiveGrid flow=\"columns\" align=\"stretch\">{lanes.map(lane => <Card onDragOver onDrop>…<Card draggable>…</Card></Card>)}</ResponsiveGrid></ScrollArea>. align=\"stretch\" keeps an empty lane as tall as the fullest one, so it stays a full-height drop target; a Select inside a draggable card does not enlarge the drag image.",
+    "DO place StatCard tiles directly as immediate children — StatCard IS already a bordered card; never wrap it in an extra <Card><CardContent>. The canonical pattern is <ResponsiveGrid columns={4}><StatCard .../><StatCard .../></ResponsiveGrid>.",
+    "DO use columns={2|3|4} to declare the target desktop column count — the grid collapses automatically to 1 column on narrow containers (mobile-first via CSS container queries), via 2-column intermediate at ≥640px, then full target count at ≥1024px. Use columns={{ base: 2, sm: 4 }} for two mobile columns and four wider-container columns; no consumer CSS is needed.",
+    "DO NOT place a DataTable inside a ResponsiveGrid column beside a card or chart. DataTable must occupy its own full-width row in a Card with CardContent flush. Nesting a multi-column table in a grid column squeezes CJK text to one character per line (see rule 37).",
+    "DO use ResponsiveGrid for page-level spacing — it applies the correct gap token (--space-stack-md) automatically. Never add raw gap-* / p-* / space-* utilities to the page layout around tiles; compose spacing through this component instead (rule 40).",
+    "DO render SkeletonStat children in place of StatCard tiles while KPIs are loading — same columns prop, same count as the real tiles. Switch to real StatCard once data resolves.",
+    "The grid uses CSS container queries, not viewport media queries — it responds to its containing block width, not the window. Ensure the container is not artificially constrained (e.g. inside a narrow SplitPane column) or column expansion will never trigger."
+  ],
+  "useCases": [
+    "Dashboard KPI row: rendering 3–4 StatCard tiles (revenue, member count, active invoices, overdue amount) that reflow to a 2-column stacked grid on tablet and a single column on mobile.",
+    "Summary header above a list page: a 2-column grid of two StatCard totals (e.g. total payable vs total paid) sitting above a Toolbar and DataTable.",
+    "Accounting period overview: 4 StatCard tiles (opening balance, total debits, total credits, closing balance) that collapse gracefully on narrow viewports without any custom CSS.",
+    "Loading state for a KPI row: identical <ResponsiveGrid columns={4}> wrapping four <SkeletonStat /> placeholders rendered while async data is in flight, swapped for real StatCard tiles once resolved.",
+    "Settings or profile summary cards: 2- or 3-column grid of Card+CardContent blocks (not StatCard) showing categorized read-only data groups before a detail form below.",
+    "Entity comparison panel: a columns={3} grid comparing three legal entities side-by-side with a Card+CardContent per entity, which collapses to 2-up on tablet and stacks on mobile."
+  ]
+}

package/agent/components/Reveal.json

@@ -0,0 +1,70 @@
+{
+  "example": "import { Reveal } from \"@godxjp/ui/general\";\nimport { Card, CardContent } from \"@godxjp/ui/data-display\";\n\n// single entrance\n<Reveal>\n  <Card><CardContent>…</CardContent></Card>\n</Reveal>\n\n// staggered column\n{items.map((item, i) => (\n  <Reveal key={item.id} delay={Math.min(i + 1, 6) as 1 | 2 | 3 | 4 | 5 | 6}>\n    <Card><CardContent>{item.label}</CardContent></Card>\n  </Reveal>\n))}\n\n// scroll reveal — same component, the trigger moved to the viewport\n<Reveal on=\"view\">\n  <Card><CardContent>…</CardContent></Card>\n</Reveal>\n\n// wait until a quarter of the section is visible, and replay on every re-entry\n<Reveal on=\"view\" amount={0.25} once={false}>\n  <Card><CardContent>…</CardContent></Card>\n</Reveal>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Reveal",
+  "props": [
+    {
+      "description": "Content to reveal on enter.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "0",
+      "description": "Stagger ordinal — an INDEX into the motion ladder, never a raw ms. Each step adds one `--reveal-stagger-step` of delay so a column of reveals cascades. 0 = enter immediately.",
+      "name": "delay",
+      "type": "0 | 1 | 2 | 3 | 4 | 5 | 6"
+    },
+    {
+      "defaultValue": "\"mount\"",
+      "description": "What STARTS the entrance. `mount` is the historical behaviour (plays as soon as the element renders), so existing call sites are unchanged. `view` holds the entrance until the element reaches the viewport. A trigger, not a second component — same keyframes, same tokens, same reduced-motion contract, which is why there is no `ScrollReveal` here.",
+      "name": "on",
+      "type": "\"mount\" | \"view\""
+    },
+    {
+      "defaultValue": "true",
+      "description": "on=\"view\" only. Reveal once and never re-hide. Default `true` because a Reveal is a ONE-SHOT entrance under either trigger — this keeps `view` semantically identical to `mount`. (Motion's useInView, where the prop comes from, defaults it to `false`; that is the neutral reading for a general-purpose observer, not for an entrance primitive.) `false` replays the entrance on every re-entry.",
+      "name": "once",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"some\"",
+      "description": "on=\"view\" only. How much of the element must be visible before it reveals — Motion's `amount`, name and type unchanged, mapped to IntersectionObserver `threshold` the same way (`some` → 0, `all` → 1, a number passes through). `all` is clamped to the most the element's own box can attain inside the viewport, because the ratio is measured against the TARGET's box: without the clamp a section taller than the viewport could never reach 1 and would stay hidden forever.",
+      "name": "amount",
+      "type": "\"some\" | \"all\" | number"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Merge the reveal onto the single child element (no wrapper <div>) — use when an extra box would break a grid/flex layout. Under `on=\"view\"` the observed box is that child's own.",
+      "name": "asChild",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "AuthShell — pairs with Reveal for the auth card entrance; AuthShell delegates all motion to Reveal.",
+    "Card — the most common thing to wrap in <Reveal> (dashboard cards, auth card, settings sections).",
+    "ResponsiveGrid — combine with `<Reveal delay={n}>` (or `asChild`) per grid item for a staggered grid reveal."
+  ],
+  "rules": [],
+  "storyPath": "general/Reveal.stories.tsx",
+  "tagline": "The official entrance-motion primitive (staggered fade-up) — reads DS motion tokens and honours prefers-reduced-motion, replacing hand-rolled @keyframes + .app-reveal/.d1..d6 classes.",
+  "usage": [
+    "DO use <Reveal> INSTEAD of hand-rolling `@keyframes auth-fade-up` + `.app-reveal` + `.d1..d6` in a consumer global.css — that repeats literal durations/delays and violates the tokens-only rule. Reveal reads `--duration-slow` / `--ease-emphasized` / `--reveal-distance` / `--reveal-stagger-step`.",
+    "DO use `on=\"view\"` for a scroll reveal INSTEAD of adding a scroll listener or a second component. It is the same primitive with the trigger moved; the library deliberately ships no ScrollReveal/AnimateOnScroll, and no animation runtime.",
+    "DO NOT gate your own visibility on an observer. `on=\"view\"` never does: the stylesheet's resting state is the finished, fully visible one, and only a mounted component holding a live IntersectionObserver writes the hidden state. A server render, jsdom, a browser without the API, and `prefers-reduced-motion: reduce` (under which NO observer is attached at all) therefore all show the content.",
+    "DO reach for `amount` rather than a margin when a reveal should wait — the default `\"some\"` fires on the first visible pixel (threshold 0), which is the earliest and never reads as late. There is deliberately no `margin`/`rootMargin` prop: it accepts px/% only, so it could not read a design token.",
+    "DO stagger a list/column by passing an increasing `delay` (1, 2, 3…) to successive siblings — the ordinal maps to `--reveal-stagger-step`, so a service retunes the cascade rhythm from one token.",
+    "DO pass `asChild` when wrapping an element that must keep its own box in a grid/flex row (the reveal merges onto that element instead of adding a <div>).",
+    "DO rely on the built-in reduced-motion behaviour — under `prefers-reduced-motion: reduce` the animation is dropped and content renders in its final, fully-visible position with no layout shift. Never gate visibility on the animation.",
+    "DO NOT set a raw ms delay or a literal translate distance — the whole point is that `delay` is a controlled ordinal and the distance/duration come from tokens."
+  ],
+  "useCases": [
+    "Auth card entrance: `<AuthShell><Reveal><Card/></Reveal></AuthShell>` — the sign-in card fades up on load, respecting reduced-motion.",
+    "Staggered dashboard: map stat cards with `<Reveal delay={i + 1}>` so the row cascades in.",
+    "Section reveal on a settings/detail page — wrap each Card in <Reveal> for a calm entrance without hand-written CSS.",
+    "asChild on a grid item: `<Reveal asChild delay={2}><ResponsiveGrid.Item/></Reveal>` keeps the grid cell intact while animating it in.",
+    "Long marketing/landing page: `<Reveal on=\"view\">` per section so each band enters as the reader reaches it, instead of all of them firing above the fold on load.",
+    "A long feed or report where only the first screen should animate on load: `<Reveal on=\"view\" amount={0.25}>` — a quarter visible before the entrance starts."
+  ]
+}

package/agent/components/ScrollArea.json

@@ -0,0 +1,104 @@
+{
+  "example": "import { Card, CardContent, ScrollArea } from \"@godxjp/ui/data-display\";\nimport { Text } from \"@godxjp/ui/general\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n// Vertical-only (default). The FRAME is a Card, not a rounded-md border — a hand-rolled surface\n// freezes the radius and the border colour at the call site, where no theme can reach them. The\n// bounded height stays a class because it is a measurement of this SCREEN, not a shape of the\n// component.\n<Card>\n  <CardContent flush>\n    <ScrollArea className=\"h-64\">\n      <Flex direction=\"col\" gap=\"sm\" pad={4}>\n        {entries.map((entry) => (\n          <Text key={entry.id} size=\"sm\">{entry.label}</Text>\n        ))}\n      </Flex>\n    </ScrollArea>\n  </CardContent>\n</Card>\n\n// Horizontal + vertical (e.g. wide Cascader columns). Use border-e, never border-r: a physical\n// edge puts the rule on the wrong side under RTL.\n<ScrollArea className=\"w-full\" orientation=\"both\">\n  <Flex className=\"max-h-[min(280px,50vh)]\">\n    {columns.map((col, i) => (\n      <ul key={i} className=\"min-w-36 border-e last:border-e-0\">\n        {col.map((item) => <li key={item.value}>{item.label}</li>)}\n      </ul>\n    ))}\n  </Flex>\n</ScrollArea>\n\n// Live stream — pinned to the newest post, never yanked while reading history\nconst viewport = React.useRef<HTMLDivElement>(null);\nconst [atNewest, setAtNewest] = React.useState(true);\n\n<Card>\n  <CardContent flush>\n    <ScrollArea\n      anchor=\"bottom\"\n      viewportRef={viewport}\n      onAnchoredChange={setAtNewest}\n      className=\"h-64\"\n    >\n      <Flex direction=\"col\" pad={{ inline: 3 }}>\n        {posts.map((post) => <PostRow key={post.id} post={post} />)}\n      </Flex>\n    </ScrollArea>\n  </CardContent>\n</Card>\n<Button\n  type=\"button\"\n  disabled={atNewest}\n  onClick={() => {\n    const node = viewport.current;\n    if (node) node.scrollTop = node.scrollHeight;\n  }}\n>\n  {t(\"chat.jumpToNewest\")}\n</Button>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "ScrollArea",
+  "props": [
+    {
+      "description": "Extra classes applied to the root element. Must include a height constraint (h-*, max-h-*) — without one, the viewport expands to fit its content and no scrollbar is rendered.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "description": "The content to make scrollable. Wrap it in a single element so the Viewport can measure its full size correctly.",
+      "name": "children",
+      "required": true,
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Rides through to the element as a plain attribute. Rarely needed: the element inherits the page's direction, and the component stamps NO direction of its own (the Radix root used to stamp `ltr`, which reset the inline axis for everything inside it on an RTL page).",
+      "name": "dir",
+      "type": "\"ltr\" | \"rtl\""
+    },
+    {
+      "defaultValue": "\"vertical\"",
+      "description": "Axes that scroll — this IS the element's `overflow`, so an axis you do not ask for is `hidden` and its content is CLIPPED, not merely missing a bar. Use 'horizontal' for a strip of non-shrinking columns (a board, a lane of cards) — the element keeps its tab stop so the strip stays keyboard-scrollable, and the consumer writes no overflow class of its own. Pair it with a width constraint, exactly as the vertical case needs a height one. 'both' is the replacement for the pre-v23 shape of a vertical area that also mounted <ScrollBar orientation=\"horizontal\" />.",
+      "name": "orientation",
+      "type": "\"vertical\" | \"horizontal\" | \"both\""
+    },
+    {
+      "description": "Ref to the element that actually SCROLLS. Since v23 that is the component's own element, so `ref` and `viewportRef` hand back the SAME node (before v23 `ref` pointed at an overflow:hidden root that never scrolled). Use it to read scrollTop/scrollHeight, call scrollTo(), restore a saved position or drive a 'jump to newest' button. `[data-radix-scroll-area-viewport]` no longer exists anywhere — query `[data-slot=\"scroll-area-viewport\"]` only if you truly cannot hold a ref.",
+      "name": "viewportRef",
+      "type": "React.Ref<HTMLDivElement>"
+    },
+    {
+      "defaultValue": "\"auto\"",
+      "description": "Whether the bar is ALWAYS drawn or left to the platform. `auto` styles whatever bar the platform decides to draw — and on macOS/iPadOS with the system default \"Show scroll bars: when scrolling\" that is an OVERLAY bar, present only while the reader is already scrolling, so a wide area does not look scrollable at rest (measured: clientWidth 727 of scrollWidth 3476, nothing occupying layout). `always` forces a classic bar that occupies layout, from the same `--scroll-area-*` tokens. Reach for it where the affordance IS the information (a wide table, a roster, a board); leave it `auto` for a chat stream.",
+      "name": "scrollbar",
+      "type": "\"auto\" | \"always\""
+    },
+    {
+      "defaultValue": "\"none\"",
+      "description": "Edge the viewport sticks to as its content grows. 'none' leaves the scroll offset entirely alone (today's behaviour).",
+      "name": "anchor",
+      "type": "\"none\" | \"bottom\""
+    },
+    {
+      "defaultValue": "--scroll-area-anchor-offset (3rem)",
+      "description": "Distance in px from the bottom edge inside which the reader still counts as 'following' for anchor=\"bottom\". Read from the --scroll-area-anchor-offset token at mount, so a theme moves it globally; this prop overrides it per instance. Size it to the row height the service renders (a dense log line vs a chat bubble with an avatar).",
+      "name": "anchorOffset",
+      "type": "number"
+    },
+    {
+      "description": "Fires when the pinned state flips — false when the reader scrolls away from the bottom, true when they return inside anchorOffset. Render a real focusable 'jump to newest' Button from it: anchoring must never be the only route back to new content.",
+      "name": "onAnchoredChange",
+      "type": "(anchored: boolean) => void"
+    },
+    {
+      "defaultValue": "the localized \"Scrollable region\"",
+      "description": "Accessible name for the scroll REGION — the tabindex=\"0\" element a keyboard user lands on to scroll content bigger than the box. Optional: left out it takes the localized dataDisplay.scrollArea.region default, so no consumer has to invent a name merely to stop shipping an anonymous focus stop (gh#821). Pass a plain string when the screen can say WHICH region ('Activity log'); a non-string node cannot be an aria-label and falls back to the default. The role, the name and the stop are all emitted only while there IS overflow on the axes `orientation` opens.",
+      "name": "label",
+      "type": "React.ReactNode"
+    }
+  ],
+  "related": [
+    "DataTable — use DataTable (not ScrollArea) when data is tabular and needs sorting/selection; DataTable manages its own overflow internally.",
+    "Collapsible — use Collapsible to show/hide a section; pair with ScrollArea when the revealed content can itself overflow.",
+    "Card/CardContent — when the card body should scroll, put ScrollArea inside CardContent rather than applying overflow directly to CardContent."
+  ],
+  "rules": [
+    2,
+    3,
+    24,
+    31
+  ],
+  "storyPath": "data-display/ScrollArea.stories.tsx",
+  "subParts": [
+    "ScrollBar"
+  ],
+  "tagline": "A native scrolling box (no Radix since v23): one `overflow: auto` element whose scrollbar is styled from --scroll-area-* tokens. Always set an explicit height/max-height, or nothing overflows and no scrollbar appears. Owns the scrolling element, so it also owns reaching it (viewportRef) and bottom anchoring for a live stream (anchor).",
+  "usage": [
+    "DO set an explicit height or max-height on ScrollArea via className (e.g. `className=\"h-64\"` or `className=\"max-h-[min(300px,50vh)]\"`). Without a height constraint the viewport grows to fit content and the scrollbar is never rendered.",
+    "DO wrap content in a single child element inside ScrollArea — the Viewport observes its single child's size to decide whether overflow exists.",
+    "DO open a second axis with `orientation=\"both\"`. `ScrollBar` still exports but RENDERS NOTHING — before v23 mounting it was what enabled an axis; now `orientation` is the only thing that does, so a leftover `<ScrollBar orientation=\"horizontal\" />` silently leaves that axis `hidden`.",
+    "DO reach for ScrollArea rather than your own `overflow-auto` div: it is the same native scrolling, plus the token-styled scrollbar, the keyboard tab stop the axe rule wants, and bottom anchoring. A bare overflow div gets none of that and each call site re-decides the scrollbar's look.",
+    "DON'T put ScrollArea inside a flex parent without giving it a `flex-1` or fixed size — it will collapse to zero height and appear broken.",
+    "For horizontal-only scrolling use `orientation=\"horizontal\"` with a width constraint; the content is allowed to grow past the box on that axis, so a row of non-shrinking columns overflows instead of squashing.",
+    "DO use `viewportRef` (or plain `ref`) when you need the scrolling element, never a `querySelector` for an internal attribute — `[data-radix-scroll-area-viewport]` is gone with Radix, and any selector matches the wrong node the moment two ScrollAreas nest.",
+    "DO build a live stream (chat, log tail, streaming response, activity feed) with `anchor=\"bottom\"` instead of writing `viewport.scrollTop = viewport.scrollHeight` in an effect. That naive version is the BUG, not the feature: it yanks a reader who has scrolled up back to the bottom on every arriving message (WCAG 3.2.5).",
+    "DO pair `anchor=\"bottom\"` with `onAnchoredChange` and a real Button (\"jump to newest\"). A keyboard user who has scrolled up needs a focusable route back to new content — the anchor alone is a pointer affordance.",
+    "DON'T remove the viewport's `tabIndex={0}`, and don't wrap the scrolling content in something that swallows arrow keys: the region must stay keyboard-scrollable (WCAG 2.1.1 / axe scrollable-region-focusable). The component measures its own overflow and emits the stop only while there is something to scroll, so you never have to withhold it yourself.",
+    "DO pass `label` on a scroll area the screen can NAME ('Activity log', 'Board'). The stop the keyboard user lands on carries role=\"group\" plus that name; without one it still announces the localized 'Scrollable region', never the anonymous stop it used to be (gh#821). `group`, not a landmark `region` — several named regions on one page collide under axe landmark-unique.",
+    "DON'T add an `aria-live` region to the ScrollArea to announce arriving items — a live region on a scroll container re-announces on reflow. Announce from your own small status region next to it.",
+    "Retune the stickiness once per service with the `--scroll-area-anchor-offset` token rather than passing `anchorOffset` on every instance."
+  ],
+  "useCases": [
+    "Long dropdown lists inside Popovers or Selects where the list height must be capped (e.g. TreeSelect, Cascader columns, Combobox options).",
+    "Sidebar navigation panels or filter drawers whose content can exceed viewport height.",
+    "Transfer-list panels with a fixed height that must scroll through a large item list.",
+    "Cascader multi-column layouts where both axes may overflow (orientation=\"both\").",
+    "Detail panels or audit-log timelines inside a fixed-height Card that should not stretch the page.",
+    "Code or JSON viewers with a fixed max-height needing both axes scrollable.",
+    "Live message streams and log tails: `anchor=\"bottom\"` pins to the newest item while the reader is at the bottom, freezes when they scroll up to read history, and preserves their position when a page of older history is prepended."
+  ]
+}