@godxjp/ui 28.8.0 → 28.10.0

package/agent/components/InfiniteQueryState.json

@@ -0,0 +1,58 @@
+{
+  "example": "import { InfiniteQueryState, flattenItemPages } from \"@godxjp/ui/query\";\n\n<InfiniteQueryState query={q} skeleton={<SkeletonRows />} flatten={flattenItemPages} isEmpty={(it) => it.length === 0}>\n  {(items) => items.map((a) => <ActivityRow key={a.id} activity={a} />)}\n</InfiniteQueryState>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/query",
+  "name": "InfiniteQueryState",
+  "props": [
+    {
+      "description": "The useInfiniteQuery result.",
+      "name": "query",
+      "required": true,
+      "type": "UseInfiniteQueryResult"
+    },
+    {
+      "description": "Shown while initial load pends.",
+      "name": "skeleton",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Reduce pages to a flat list (use flattenItemPages helper).",
+      "name": "flatten",
+      "required": true,
+      "type": "(data) => TFlat"
+    },
+    {
+      "description": "Render with flat data + { fetchNextPage, hasNextPage, isFetchingNextPage }.",
+      "name": "children",
+      "required": true,
+      "type": "(flat, helpers) => ReactNode"
+    }
+  ],
+  "related": [
+    "DataState — use instead when the query is a plain `useQuery` (not infinite). Identical lifecycle surface (skeleton/empty/error/children) but expects a single page of data, not accumulated pages. Pick DataState for any paginated table where only one page is visible at a time.",
+    "DataTable — use for tabular data with server-side pagination where pages are swapped, not appended. DataTable manages its own pagination UI (cursor buttons); InfiniteQueryState is for append-only / infinite-scroll patterns.",
+    "SkeletonTable / SkeletonStat — pass as the `skeleton` prop to InfiniteQueryState; do not render them manually alongside InfiniteQueryState since the component controls when skeleton is visible.",
+    "ButtonRefetch — companion component for the page header refresh action wired to `query.refetch()`. Use alongside InfiniteQueryState when you want an explicit refresh control in addition to the built-in load-more footer."
+  ],
+  "rules": [],
+  "storyPath": "query/InfiniteQueryState.stories.tsx",
+  "tagline": "useInfiniteQuery widget — flatten pages, skeleton/empty/error, load-more footer. Import from @godxjp/ui/query.",
+  "usage": [
+    "DO: Import from `@godxjp/ui/query` (not `@godxjp/ui`). Use the bundled `flattenItemPages` helper for any API that returns `{ items: T[] }` pages — it handles `undefined` data safely. Custom page shapes require a custom `flatten` function.",
+    "DO: Always pass `skeleton` (e.g. `<SkeletonTable />` or `<SkeletonStat />`). It shows on initial `isPending`, on refetch-after-error, and whenever `data` is absent. Never show a blank area while loading.",
+    "DO: Pass `empty` (an `<EmptyState>` node) to handle the zero-results case — without it the children render-prop is called with an empty array and you get a silent blank screen. Provide a custom `isEmpty` only when `TFlat` is not an array.",
+    "DO: Let errors remain cause-aware. Retry is automatic only for classified transient/network/5xx failures. Unknown errors do not get a blind retry unless `showRetry` or `onRetry` is explicitly supplied; 401 routes to `onAuthError`, and raw backend/token text is never rendered.",
+    "DON'T: Hand-roll a load-more button. The component renders a default centered outline Button when `hasNextPage` is true. Override only via `loadMore` (custom node) or `showLoadMore={false}` (hide entirely). Never call `query.fetchNextPage()` outside the component for pagination.",
+    "DON'T: Use `InfiniteQueryState` for a `useQuery` result — it expects `UseInfiniteQueryResult` shape (`pages`, `hasNextPage`, `fetchNextPage`, `isFetchingNextPage`). For regular `useQuery` use `DataState` instead.",
+    "DON'T: Confuse the two generics: `TPage` is the raw page shape from the API, `TFlat` is what `flatten` returns (usually `TItem[]`). The `children` render-prop receives `TFlat`, not `TPage`. Pass `isEmpty` if `TFlat` is not a plain array so empty detection works correctly."
+  ],
+  "useCases": [
+    "Activity / audit-log feed that accumulates pages as the user scrolls down or clicks 'Load more' — the default footer button handles `fetchNextPage` automatically.",
+    "Invoice or transaction list with cursor-based pagination where total count is unknown and pages are appended rather than replaced (replacing pages is DataTable's job).",
+    "Notification inbox, comment thread, or journal entry list where new items are appended at the bottom and the user never pages backwards.",
+    "Search results with a 'Show more' button rather than numbered pages — pass `showLoadMore={true}` (default) and hide the button once `hasNextPage` is false without any extra state.",
+    "Admin dashboard 'recent events' widget backed by `useInfiniteQuery` — use `SkeletonTable` as `skeleton` and `<EmptyState title='No events yet' />` as `empty` so every state is handled.",
+    "Infinite-scroll implementation: receive the `helpers` argument in `children` (`{ fetchNextPage, hasNextPage, isFetchingNextPage }`) to wire a scroll sentinel (Intersection Observer) instead of the built-in button, while still benefiting from error/skeleton/empty lifecycle handling."
+  ]
+}

package/agent/components/Input.json

@@ -0,0 +1,122 @@
+{
+  "example": "import { Input } from \"@godxjp/ui/data-entry\";\n\n<Input id=\"qty\" type=\"number\" placeholder=\"例: 500\" value={value} onValueChange={(e) => setValue(e.target.value)} />",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Input",
+  "props": [
+    {
+      "description": "Validation state the field paints — Ant Design `status`. `error` also reports `aria-invalid`, so the red boundary and what a screen reader hears are one fact; `warning` paints only, because a warning is not a validity failure. antd's `success`/`validating` are not implemented: antd only draws them together with its `hasFeedback` icon slot, which FormField owns here.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "defaultValue": "\"outlined\"",
+      "description": "Chrome level — Ant Design `variant`. `outlined` is the historical field; `filled` swaps the boundary for a tinted surface (dense forms); `borderless` drops both, for a field inside a box that already draws one. antd's fourth member `underlined` is deliberately absent — a single bottom rule is a Material convention and SmartHR, the JP authority here, draws every field as a full box.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\""
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Control height tier — reads the shared `--control-height` ladder.",
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "antd `prefix` — content pinned INSIDE the start of the field (¥, a unit, a glyph). Unlike `leadingIcon` it is not aria-hidden, because a unit is meaning and not decoration.",
+      "name": "prefix",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `suffix` — content pinned INSIDE the end of the field (%, 円). The clear ✕ replaces it while `allowClear` has a value, exactly as it replaces `trailingIcon`.",
+      "name": "suffix",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `addonBefore` — a LABEL segment welded OUTSIDE the field's box (`https://`, a currency). Outside is the whole distinction from `prefix`: an addon has its own surface and closes the field's corners on the joined side. For a GLYPH use `prefix` — one box, one border, no seam. antd deprecates both addons in favour of `Space.Compact` (verified in ant-design@master: a `@deprecated` tag and a dev-time warning, still rendering); this library keeps them, because it has no `Space` and `addonBefore` IS its joined control (gh#841).",
+      "name": "addonBefore",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "antd `addonAfter` — the same, welded to the end of the box (`.com`, a unit). Deprecated upstream alongside `addonBefore`, and kept here for the same reason.",
+      "name": "addonAfter",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Character counter — Ant Design `count`. Counts CODE POINTS by default, so one emoji and one 全角 kanji are each worth one. It REPORTS an overrun (`data-exceeded`) and never edits the value: antd's `exceedFormatter` truncates while the user types, which in Japanese cuts a live IME conversion in half.",
+      "name": "count",
+      "type": "{ max?: number; show?: boolean; formatter?: (info: { value: string; count: number; max?: number }) => React.ReactNode; strategy?: (value: string) => number }"
+    },
+    {
+      "description": "Associates with a <label htmlFor>.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"text\"",
+      "description": "Native input type.",
+      "name": "type",
+      "type": "string"
+    },
+    {
+      "description": "Placeholder.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "description": "Controlled value.",
+      "name": "value",
+      "type": "string | number"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Opt-in inline ✕ that clears the field while it holds text (works controlled + uncontrolled). Off by default, so existing inputs are unchanged.",
+      "name": "allowClear",
+      "type": "boolean"
+    },
+    {
+      "description": "Called after the field is cleared via the inline ✕ (requires `allowClear`).",
+      "name": "onClear",
+      "type": "() => void"
+    },
+    {
+      "description": "A leading affordance pinned inside the start of the field (e.g. a Mail / Lock / Search glyph) — purely decorative, rendered before the text. Sized to the control via tokens and offset with `ps-9` automatically; never hand-roll an absolutely-positioned icon over a plain Input.",
+      "name": "leadingIcon",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "A trailing affordance pinned inside the field (e.g. a calendar / clock popover trigger). ONE trailing icon shows at a time: when `allowClear` and the field holds a value the clear ✕ REPLACES this icon; otherwise this icon shows. Never both — this is how DatePicker/TimePicker render their open trigger.",
+      "name": "trailingIcon",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Immediate value callback; native onChange remains supported. Shared form bindings are emitted once.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    }
+  ],
+  "related": [
+    "PasswordInput — the password field. It owns the reveal toggle, the caps-lock hint and the autocomplete contract; a raw Input with type=password re-implements all three.",
+    "SearchInput — use instead of Input when the value drives a live filter or search query; SearchInput debounces internally, fires `onSearch` (not `onChange`), and provides a built-in clear button. Never put debounce logic on top of a plain Input.",
+    "Textarea — use instead of Input for multi-line text (notes, descriptions, memo fields). Input is strictly single-line.",
+    "FormField — always compose Input inside FormField when the field needs a visible label, helper hint, or validation error message; FormField handles all a11y wiring so Input stays a pure unstyled-but-styled primitive.",
+    "Select — use instead of Input when the value must come from a fixed or async option list; never render a plain Input and parse free text when the set of valid values is enumerable."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/Input.stories.tsx",
+  "tagline": "Styled wrapper around native <input>; accepts all HTML input attributes. Pair with FormField for labelled fields.",
+  "usage": [
+    "DO always wrap Input in FormField when the field needs a label, helper text, or validation error — FormField injects aria-describedby and aria-invalid onto Input automatically; never wire these attributes by hand.",
+    "DO match the `id` prop on Input to the `id` prop on its parent FormField so that `htmlFor` linkage and the generated helper/error ids are consistent.",
+    "DO use Input in controlled mode (`value` + `onChange`) for forms driven by Inertia's `useForm` or React state; uncontrolled usage (no `value`) is only acceptable for fire-and-forget inline edits where form state is not needed.",
+    "DON'T use a raw `<input>` element — Input adds the full token-based styling (border-input, focus ring, disabled/invalid states, file-slot styling) and the `data-slot='input'` marker that FormField relies on to inject aria attributes.",
+    "DON'T hand-roll an error border or red ring with className — Input reads `aria-invalid` (set by FormField) and applies `border-destructive` + `ring-destructive/20` automatically; adding manual destructive classes will conflict.",
+    "DON'T use Input for multi-line text — use Textarea; DON'T use it for filtered/debounced search — use SearchInput which fires `onSearch` after a debounce and includes a clear button."
+  ],
+  "useCases": [
+    "Single-line text fields in create/edit forms — invoice reference numbers, company names, contact emails, coupon codes, amounts typed as text (pair with `type='number'` for numeric entry).",
+    "Inline editable cells or quick-edit dialogs where a single short value needs to be changed (e.g. editing a journal entry memo or an account code) and full Select/DatePicker overhead is unnecessary.",
+    "File upload trigger when wrapped with `type='file'` — the file-slot classes style the native file button consistently without any extra wrapper.",
+    "Password entry fields (`type='password'`) in auth or settings screens, where the styled focus ring and disabled-state opacity are needed without building a custom control.",
+    "Numeric/currency input in accounting forms (`type='number'`, `inputMode='decimal'`) for quantities, exchange rates, or tax amounts where a free-form numeric entry is required rather than a slider or stepper."
+  ]
+}

package/agent/components/InputOTP.json

@@ -0,0 +1,106 @@
+{
+  "example": "import { InputOTP, InputOTPGroup, InputOTPSlot } from \"@godxjp/ui/data-entry\";\n\n<InputOTP maxLength={6}>\n  <InputOTPGroup>\n    <InputOTPSlot index={0} /><InputOTPSlot index={1} /><InputOTPSlot index={2} />\n    <InputOTPSlot index={3} /><InputOTPSlot index={4} /><InputOTPSlot index={5} />\n  </InputOTPGroup>\n</InputOTP>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "InputOTP",
+  "props": [
+    {
+      "description": "Initial uncontrolled code.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Canonical value callback, compatible with FormFieldControl.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Mask filled visual slots without changing the submitted code.",
+      "name": "mask",
+      "type": "boolean | string"
+    },
+    {
+      "description": "Normalize typed and pasted codes.",
+      "name": "formatter",
+      "type": "(value: string) => string"
+    },
+    {
+      "description": "Shared control height tier.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Validation appearance.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "description": "Shared field chrome.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\" | \"underlined\""
+    },
+    {
+      "description": "Refuse edits including paste.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "Number of slots (e.g. 6).",
+      "name": "maxLength",
+      "required": true,
+      "type": "number"
+    },
+    {
+      "description": "Controlled value.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Value callback (this is a true text input — onChange is the DOM-style value handler here).",
+      "name": "onChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Allowed-char regex (e.g. digits only).",
+      "name": "pattern",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"start\"",
+      "description": "Main-axis alignment of the whole code row (groups + separators) inside the field. `center` is the canonical auth challenge. Before this existed, every consumer wrapped the OTP in their own flex-centring div — do not. A service that wants all code fields centred sets `--otp-container-align` once instead.",
+      "name": "align",
+      "type": "\"start\" | \"center\" | \"end\""
+    }
+  ],
+  "related": [
+    "Input (a normal single text field)",
+    "PasswordInput (masked secret field)"
+  ],
+  "rules": [
+    3,
+    6
+  ],
+  "storyPath": "data-entry/InputOTP.stories.tsx",
+  "subParts": [
+    "InputOTPGroup",
+    "InputOTPSeparator",
+    "InputOTPSlot"
+  ],
+  "tagline": "One-time-code / 2FA input (input-otp) — N single-character slots that behave as one field. Compose InputOTP > InputOTPGroup > InputOTPSlot.",
+  "usage": [
+    "DO set `maxLength` to the code length and render that many InputOTPSlot with sequential `index`.",
+    "DO centre a challenge with `align=\"center\"` on InputOTP — never with a wrapper `<div className=\"flex justify-center\">`. The container is owned by input-otp, so a wrapper is the only thing a consumer CAN reach, which is exactly why the prop exists.",
+    "DO wrap slots in InputOTPGroup; use InputOTPSeparator between groups (e.g. 3 + 3).",
+    "For device codes, set `appearance='grouped'` on each InputOTPGroup to render one outline per group while preserving the single hidden input, paste, caret, keyboard and screen-reader behavior.",
+    "DON'T build N separate Inputs — this is ONE field with paste, arrow-key, and caret handling built in.",
+    "DO widen the slots with `--otp-slot-size` when a challenge row must fill a wide auth panel — it defaults to the live `--control-height` tier, so re-scoping `--control-height` on the card instead would also resize the submit button and every other input in it. Set a NAMED tier (`var(--control-height-lg)`), never an ad-hoc calc offset.",
+    "DO use `--otp-slot-inline-size` / `--otp-slot-block-size` when the code field is NOT square — a device-grant slot is taller than it is wide. They win over the `--otp-slot-size` shorthand and fall back to it, so setting neither keeps the square control tier. You rarely set them by hand inside `AuthShell preset=\"device-authorization\"`: that preset already owns its code-field measure.",
+    "DO drive the sign-in MFA challenge from FormField: `error` wires aria-invalid + aria-errormessage + a role=alert message onto the single field, and the slot borders turn destructive. State is never colour-only."
+  ],
+  "useCases": [
+    "2FA / OTP verification code",
+    "Email / SMS confirmation code",
+    "PIN entry",
+    "Invite / redemption code"
+  ]
+}

package/agent/components/Label.json

@@ -0,0 +1,43 @@
+{
+  "example": "import { Label } from \"@godxjp/ui/data-entry\";\n\n<Label htmlFor=\"stackable\">併用を許可</Label>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "Label",
+  "props": [
+    {
+      "description": "Id of the associated control.",
+      "name": "htmlFor",
+      "type": "string"
+    },
+    {
+      "description": "Label content.",
+      "name": "children",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "FormField — prefer this over a bare Label whenever the field needs helper text, an error message, or a required marker; FormField renders Label internally and wires aria-describedby/aria-invalid automatically.",
+    "Field — use for a Checkbox or Radio.Item that needs a visible label and optional description line; it renders Label internally — do NOT add a second Label around it.",
+    "Field — use instead of a bare Switch + Label pair when the control must submit a value via an HTML form name; Field owns the Label + hidden input composition.",
+    "Checkbox — the most common bare-Label partner; pair with Label via shared useId() id/htmlFor when Field's layout is too heavy."
+  ],
+  "rules": [],
+  "storyPath": "data-entry/Label.stories.tsx",
+  "tagline": "Styled Radix Label; use htmlFor to associate with a control.",
+  "usage": [
+    "DO: always pass `htmlFor` matching the `id` of the associated control — this is the entire purpose of the component. Without it, clicking the label text does NOT focus or toggle the control, breaking a11y and UX.",
+    "DO: import from `@godxjp/ui/data-entry` (not shadcn or Radix directly). The godx-ui Label extends Radix's LabelPrimitive with `data-slot=\"label\"`, `select-none`, and `group-data-[disabled]` opacity-50 — hand-rolling a `<label>` loses all of these.",
+    "DON'T: use Label as a standalone visible heading or section title. It is a form-control association primitive. For page/section headings use semantic HTML (`<h2>`, etc.) or a typography class instead.",
+    "DON'T: wrap Label around a control that is already labelled internally. FormField, Field, and CheckboxGroup all render Label internally — adding a second Label creates a duplicate association and redundant screen-reader announcement.",
+    "DO: pair Label with Checkbox or Switch when NOT using the compound wrapper (Field). In that case generate the shared id with `React.useId()` and pass it to both `id` on the control and `htmlFor` on Label.",
+    "PREFER FormField over a bare Label + control pair whenever you also need helper text, error messages, or `required` asterisk. FormField injects `aria-describedby` and `aria-invalid` automatically; a bare Label does not."
+  ],
+  "useCases": [
+    "Pairing with a standalone Checkbox when Field's two-line layout is unnecessary — e.g. a single 'Remember me' option in a login form.",
+    "Labelling a bare Switch (not Field) in a settings row where the switch is controlled by parent state and no HTML form name attribute is needed.",
+    "Adding a visible label to a custom or third-party control that accepts an `id` prop but isn't wrapped by FormField or Field.",
+    "Labelling a Textarea in a free-text form field when FormField's helper/error slots aren't needed, keeping the markup minimal.",
+    "Rendering an accessible label inside a table row where a FormField's block layout would break the inline/grid structure.",
+    "Adding a label to a DatePicker, TimePicker, or ColorPicker inside a simple layout that doesn't need the full FormField wrapper."
+  ]
+}

package/agent/components/LegalDocumentShell.json

@@ -0,0 +1,102 @@
+{
+  "example": "import { LegalDocumentShell, CenteredShell, Flex, Topbar } from \"@godxjp/ui/layout\";\nimport { Button, Text } from \"@godxjp/ui/general\";\nimport { useState } from \"react\";\n\nexport function TermsPage() {\n  const [activeSection, setActiveSection] = useState(\"acceptance\");\n\n  return (\n    <CenteredShell width=\"lg\" topbar={<Topbar start={<Brand />} />}>\n      <LegalDocumentShell\n        title=\"利用規約\"\n        version=\"2.4\"\n        effectiveDate=\"2026-04-01\"\n        summary=\"本規約は、当社が提供するサービスの利用条件を定めるものです。\"\n        contentsLabel=\"目次\"\n        activeSection={activeSection}\n        onActiveSectionChange={setActiveSection}\n        sections={[\n          { id: \"acceptance\", title: \"第1条(本規約への同意)\", content: <Text as=\"p\">…</Text> },\n          { id: \"accounts\", title: \"第2条(アカウントの管理)\", content: <Text as=\"p\">…</Text> },\n        ]}\n        documentNavigation={\n          <Flex direction=\"col\" gap=\"xs\" role=\"group\" aria-label=\"法的文書\">\n            <Button variant=\"secondary\" size=\"sm\" fullWidth aria-current=\"page\">利用規約</Button>\n            <Button variant=\"ghost\" size=\"sm\" fullWidth>プライバシーポリシー</Button>\n          </Flex>\n        }\n        footerAction={<Button size=\"sm\">同意する</Button>}\n      />\n    </CenteredShell>\n  );\n}",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "LegalDocumentShell",
+  "props": [
+    {
+      "description": "Document title — the <h1> that names the <article> (e.g. 'Terms of Service').",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "The document's sections in reading order. Drives BOTH the contents list and the body: `id` is the REAL anchor target (<section id> + href='#id'), `title` becomes the <h2> AND the contents label, `content` is the consumer-owned legal copy.",
+      "name": "sections",
+      "required": true,
+      "type": "{ id: string; title: string; content: ReactNode }[]"
+    },
+    {
+      "description": "Bare version identifier (e.g. '2.4'). Rendered as a localized 'Version {version}' — never pass a pre-localized sentence.",
+      "name": "version",
+      "type": "string"
+    },
+    {
+      "description": "ISO 8601 calendar date (yyyy-MM-dd) or a full ISO instant. Formatted with Intl.DateTimeFormat in the active locale and emitted inside <time dateTime={effectiveDate}>, so the machine-readable value is always the ISO input. NEVER pass a pre-formatted date string.",
+      "name": "effectiveDate",
+      "type": "string"
+    },
+    {
+      "description": "Short plain-language summary rendered under the metadata, above the contents.",
+      "name": "summary",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Accessible name + visible caption of the contents <nav>. Defaults to a localized 'Contents'. Override it when two documents share a view, so the two nav landmarks stay distinguishable (axe landmark-unique, WCAG 2.4.1).",
+      "name": "contentsLabel",
+      "type": "string"
+    },
+    {
+      "description": "Controlled active section id (the entry marked aria-current='location'). Pair with onActiveSectionChange; omit both for the uncontrolled form.",
+      "name": "activeSection",
+      "type": "string"
+    },
+    {
+      "description": "Uncontrolled initial active section id. Defaults to the first section.",
+      "name": "defaultActiveSection",
+      "type": "string"
+    },
+    {
+      "description": "Fires on contents-anchor activation, on an initial hash deep link, and continuously from the scroll spy as the reader moves through the document.",
+      "name": "onActiveSectionChange",
+      "type": "(sectionId: string) => void"
+    },
+    {
+      "description": "Rail slot above the contents list — a switcher across the legal set (Terms · Privacy · Cookies). Rendered as a plain wrapper, so the consumer owns its semantics.",
+      "name": "documentNavigation",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Slot below the last section — accept / download / print / contact actions.",
+      "name": "footerAction",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Root element id; also seeds the internal ids.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Root class override (rarely needed).",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "CenteredShell — the page shell to put a LegalDocumentShell inside (brand bar + centred column + footer). LegalDocumentShell is the document, not the page chrome; never nest two shells of the same kind.",
+    "SplitPane — a generic main + fixed aside. It gives similar GEOMETRY but owns no scroll-spy / hash / focus behaviour, so it is the wrong pick for a document with a table of contents.",
+    "PageContainer — for a titled section inside an app page; LegalDocumentShell already renders its own document header (h1 + version + effective date + summary).",
+    "Text / Heading — compose the section `content` from these; the shell only supplies the section heading (h2) and the body wrapper."
+  ],
+  "rules": [
+    23,
+    24
+  ],
+  "storyPath": "layout/LegalDocumentShell.stories.tsx",
+  "tagline": "Long-form legal/policy document surface (terms, privacy, DPA, cookie policy, SLA) — semantic article/nav/section landmarks, real anchors, a sticky table-of-contents rail, scroll-spy aria-current, hash deep links with a token-driven scroll offset and focus handoff. All legal text stays consumer-owned.",
+  "usage": [
+    "DO use LegalDocumentShell for ANY long-form legal/policy document — terms of service, privacy policy, DPA, cookie policy, SLA, EULA, security policy. It is the only primitive that owns the document behaviour: scroll-spy active section, hash deep links, scroll offset, focus handoff and reduced-motion scrolling.",
+    "DO pass `effectiveDate` as an ISO 8601 string ('2026-04-01'). The shell formats it with Intl.DateTimeFormat in the active locale and keeps the ISO value in <time dateTime>. A pre-formatted string ('April 1, 2026') is a bug — it will not localize.",
+    "DO keep ALL legal text in the consumer: the shell only receives `sections` (+ the `summary` / `documentNavigation` / `footerAction` slots). It never ships legal copy.",
+    "DO give every section a URL-safe, page-unique `id` — it is simultaneously the <section id>, the contents href, the deep-link target and the aria-current key.",
+    "DO NOT hand-roll this from CenteredShell + SplitPane + `.legal-*` CSS. The geometry is the easy half; the scroll spy, hash offset, focus handoff and aria-current wiring are what the shell exists to own, and no token can express them.",
+    "DO NOT add a consumer `className` for the measure, the rail width, the section rhythm or the dividers — every one of those is a --legal-document-* token. Dividers default to `none` (rule #44): opt in with `--legal-document-toc-border: 1px solid hsl(var(--border))`.",
+    "DO NOT expect a viewport media query: the shell owns its query container, so the one-column ⇄ two-column split (56rem) is decided by the SHELL's own width. Below it the contents are a STATIC compact block (never pinned on a phone); above it they are a sticky rail."
+  ],
+  "useCases": [
+    "Hosted legal terms/privacy screen (SCR-005): <CenteredShell width=\"lg\" topbar={<Topbar …/>}><LegalDocumentShell title=\"利用規約\" version=\"2.4\" effectiveDate=\"2026-04-01\" contentsLabel=\"目次\" sections={sections} activeSection={active} onActiveSectionChange={setActive} documentNavigation={<DocumentSwitcher/>} footerAction={<Button>同意する</Button>} /></CenteredShell>",
+    "In-app policy viewer inside a Dialog/Sheet during onboarding: the same `sections` with `footerAction` carrying the accept button; the shell stays single-column because its container is narrow.",
+    "Deep-linkable DPA / sub-processor document: link to /legal/dpa#data-retention — the shell selects, scrolls to (with the scroll offset) and focuses that section on arrival.",
+    "Multi-document legal set (Terms · Privacy · Cookies): render the switcher in `documentNavigation` so it sits above the contents in the sticky rail."
+  ]
+}

package/agent/components/Legend.json

@@ -0,0 +1,42 @@
+{
+  "example": "import { Legend } from \"@godxjp/ui/data-display\";\n\n<CardAction>\n  <Legend\n    items={[\n      { tone: \"destructive\", label: \"期限超過\" },\n      { tone: \"warning\", label: \"期限間近\" },\n      { tone: \"success\", label: \"対応済\" },\n    ]}\n  />\n</CardAction>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Legend",
+  "props": [
+    {
+      "description": "The keys, in the order the marks they explain appear. `label` is required and cannot be omitted: colour alone never carries meaning (WCAG 1.4.1), so a wordless key would be the exact failure the component prevents.",
+      "name": "items",
+      "required": true,
+      "type": "{ tone: \"default\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"muted\" | \"neutral\"; label: ReactNode }[]"
+    },
+    {
+      "description": "Root class. The swatch geometry lives in the --legend-* tokens, not here.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Progress — `segments` draws the breakdown this key explains; the two take the same tones.",
+    "Badge — a Badge labels ONE thing in place; a Legend explains a colour used across many marks.",
+    "Swatch — one read-only sample of an ARBITRARY colour (a brand's primary_color). Legend is a key over the closed semantic tones and always shows words; Swatch shows a value and takes its name from aria-label.",
+    "CardAction — the header slot a Legend usually sits in, so the key lands opposite the CardTitle."
+  ],
+  "rules": [],
+  "storyPath": "data-display/Legend.stories.tsx",
+  "tagline": "The KEY for a colour-coded surface: which tone means what, spelled out in words once — a square swatch per tone with its label.",
+  "usage": [
+    "DO import from `@godxjp/ui/data-display`: `import { Legend } from \"@godxjp/ui/data-display\";`",
+    "DO put it in the `CardAction` slot of the card whose bars or chart it explains, so the key sits on the same line as the card title and reads before the data.",
+    "DO feed it the same tone order as the marks it explains — a key whose order differs from the bars forces the reader to map three colours by hand.",
+    "DON'T build a key out of Badges. A Badge is a chip that reads as clickable and carries a tinted fill + border; a legend swatch is a SAMPLE of the exact colour the mark uses.",
+    "DON'T hand-roll a coloured square: `<span className=\"w-[10px] h-[10px] rounded-[2px] bg-[#c0392f]\" />` is blocked by ui-audit three ways at once (no-arbitrary-size, no-arbitrary-radius, no-arbitrary-hex). For a colour the USER chose — a brand colour, a tag tint — reach for `Swatch`, which takes that value as a prop.",
+    "DON'T give the swatch its own text or aria — it is aria-hidden on purpose, because it repeats the label beside it."
+  ],
+  "useCases": [
+    "The key above a set of `Progress` breakdown bars — 期限超過 / 期限間近 / 対応済 — so the three tones are named once for the whole card instead of on every row.",
+    "A chart card where the series colours need naming outside the chart's own runtime legend.",
+    "A status column in a dense table: name the tones once in the card header rather than repeating a Badge in every cell.",
+    "A calendar or heatmap whose cell tints encode a state (booked / held / free)."
+  ]
+}

package/agent/components/LineChart.json

@@ -0,0 +1,103 @@
+{
+  "example": "import { LineChart } from \"@godxjp/ui/charts\";\n\n<LineChart\n  label={t(\"dashboard.revenueTrend\")}\n  data={data}\n  categoryKey=\"month\"\n  series={[\n    { dataKey: \"plan\", label: t(\"metric.plan\") },\n    { dataKey: \"actual\", label: t(\"metric.actual\") },\n  ]}\n  numberFormat={{ style: \"currency\", currency: \"JPY\" }}\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/charts",
+  "name": "LineChart",
+  "props": [
+    {
+      "description": "Row data: one category per row with a numeric value per series.",
+      "name": "data",
+      "required": true,
+      "type": "ChartDatum[]"
+    },
+    {
+      "description": "Plotted series: { dataKey, label?, color? }. Colour defaults to the --chart-1..6 palette.",
+      "name": "series",
+      "required": true,
+      "type": "ChartSeriesProp[]"
+    },
+    {
+      "description": "Key into each datum holding the x-axis category label.",
+      "name": "categoryKey",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Accessible name + visible caption (role=img needs a name).",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Paint `label` as a visible caption. Set false when a CardTitle or section heading already says it — the caption stays in the DOM as sr-only, so role=img keeps its accessible name.",
+      "name": "showCaption",
+      "type": "boolean"
+    },
+    {
+      "description": "Extra context appended to the screen-reader description.",
+      "name": "description",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Canvas height preset. Ignored when `height` is set.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Explicit canvas height in px (overrides `size`).",
+      "name": "height",
+      "type": "number"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Show the series legend.",
+      "name": "showLegend",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Show the cartesian background grid.",
+      "name": "showGrid",
+      "type": "boolean"
+    },
+    {
+      "description": "Locale-aware formatting for axis ticks + tooltip values.",
+      "name": "numberFormat",
+      "type": "Intl.NumberFormatOptions"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Render smooth (monotone) lines instead of straight segments.",
+      "name": "curved",
+      "type": "boolean"
+    },
+    {
+      "description": "Message shown when `data` is empty (defaults to a localized 'no data').",
+      "name": "emptyMessage",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "AreaChart — use when the filled magnitude under the line matters (cumulative/stacked volume).",
+    "BarChart — use for discrete category comparison rather than a continuous trend.",
+    "DataTable — use when exact per-row figures matter more than the trend shape."
+  ],
+  "rules": [],
+  "storyPath": "charts/LineChart.stories.tsx",
+  "tagline": "Trends over an ordered category axis — one or more series, locale-formatted ticks/tooltips, screen-reader text alternative built in. Data-visualization graph / plot.",
+  "usage": [
+    "DO import from the tree-shaken charts entry: `import { LineChart } from \"@godxjp/ui/charts\";`. Importing any other subpath never pulls in recharts.",
+    "DO import only the chart a screen uses — `import { LineChart } from \"@godxjp/ui/charts/line-chart\";` — when the `./charts` barrel should not link the whole chart family. Without the `recharts` peer the build then fails ONCE, naming the package and the fix.",
+    "DO install the `recharts` optional peer dependency in the consuming app — charts are the only part of @godxjp/ui that needs it, so apps without charts never pay for it.",
+    "DO pass an i18n'd `label` — it is both the visible caption and the accessible name; the component also emits a screen-reader list of the plotted values (WCAG 1.1.1).",
+    "DO pre-translate each series' `label`; pass `numberFormat` (e.g. { style: 'currency', currency: 'JPY' }) and the axis/tooltip numbers localize automatically via Intl.",
+    "DON'T hand-roll an SVG/canvas chart or drop raw recharts into a page — LineChart owns the colour tokens, locale formatting, empty state, and accessibility wiring."
+  ],
+  "useCases": [
+    "Revenue / KPI trend over months in a dashboard.",
+    "Multi-series comparison (e.g. plan vs actual) across a time axis.",
+    "Any continuous metric where the shape of the trend is the message."
+  ]
+}

package/agent/components/Link.json

@@ -0,0 +1,41 @@
+{
+  "example": "import { Link } from \"@godxjp/ui/general\";\n\n<Link href=\"/docs/billing\">請求の設定</Link>\n<Link href=\"https://example.com\" target=\"_blank\">外部サイト</Link>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Link",
+  "props": [
+    {
+      "defaultValue": "\"a\"",
+      "description": "Rendered element.",
+      "name": "as",
+      "type": "\"a\" | \"span\""
+    },
+    {
+      "description": "Single-line truncation. antd allows only a boolean on `Link`, and that restriction is ported.",
+      "name": "ellipsis",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Text",
+    "Typography",
+    "Button",
+    "PrefetchLink"
+  ],
+  "rules": [
+    2,
+    6,
+    23
+  ],
+  "storyPath": "general/typography.tsx",
+  "tagline": "antd Typography.Link — an anchor that already carries this library's inline link affordance (underline on hover AND on keyboard focus), plus antd's rel guard for target=\"_blank\".",
+  "usage": [
+    "DO use `Link` when you want an anchor with the link affordance already on it. `<Text link>` is the same affordance for a run that is not an anchor, and `<Text asChild link>` is the shape a router link takes.",
+    "DON'T reach for `Button variant=\"link\"` inside running content: that is a CONTROL box (nowrap, a control height, inline padding), so in a table cell it neither wraps nor shares the cell's line box.",
+    "A `target=\"_blank\"` with no `rel` of its own is given `noopener noreferrer`, because the opened document otherwise keeps a live handle back into this one."
+  ],
+  "useCases": [
+    "A documentation link at the end of a helper line: `<Link href=\"/docs/billing\">請求の設定</Link>`.",
+    "An external link that must not leak the opener: `<Link href=\"https://example.com\" target=\"_blank\">外部サイト</Link>`."
+  ]
+}