@godxjp/ui 28.9.0 → 28.10.0

package/agent/components/Affix.json

@@ -0,0 +1,78 @@
+{
+  "docPath": "layout/affix.tsx",
+  "example": "import { Affix } from \"@godxjp/ui/layout\";\nimport { Button, Text } from \"@godxjp/ui/general\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\nconst [pinned, setPinned] = useState(false);\n\n<Affix offsetBlockStart={64} onChange={setPinned}>\n  <Flex align=\"center\" justify=\"between\" gap=\"sm\">\n    <Text weight=\"medium\">{pinned ? \"Invoices\" : \"All invoices, 2026\"}</Text>\n    <Button size={pinned ? \"sm\" : \"md\"}>New invoice</Button>\n  </Flex>\n</Affix>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "Affix",
+  "props": [
+    {
+      "description": "What gets pinned. Must not itself be `position: absolute` (antd's note applies here for the same reason: the pin works by making this content `position: fixed`).",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "antd `offsetTop`, on its LOGICAL axis. Pixels from the scrollport's block-start edge at which it pins, and the distance it sits at once pinned. Overrides the `--affix-inset-block-start` token per instance; omit it to take the theme's. Default `0` (antd's) via that token.",
+      "name": "offsetBlockStart",
+      "type": "number"
+    },
+    {
+      "description": "antd `offsetBottom`, on its LOGICAL axis — the sticky FORM FOOTER rather than the sticky header. Passing it (and no `offsetBlockStart`) is what selects block-end pinning, exactly as in antd; block-start wins when both are given.",
+      "name": "offsetBlockEnd",
+      "type": "number"
+    },
+    {
+      "description": "antd `target`, default `() => window` — the scroll box to pin against, which need not be the nearest scrolling ancestor. Same lazy-getter shape `FloatButton.BackTop.target` uses here, and for the same reason: the element does not exist on the render that declares it.",
+      "name": "target",
+      "type": "() => Window | HTMLElement | null"
+    },
+    {
+      "description": "antd `onChange`. Fires on the pin TRANSITION and only on it — never on a scroll frame that did not change the state. Structural, not guarded: the value is React state, so the effect cannot run without it having flipped, and the mount is skipped.",
+      "name": "onChange",
+      "type": "(affixed: boolean) => void"
+    },
+    {
+      "description": "NOT props. antd's physical spellings, kept in the type so that arriving from antd's docs is a COMPILE ERROR naming `offsetBlockStart` / `offsetBlockEnd`, plus a development console.warn. See docs/DESIGN-AUTHORITY.md.",
+      "name": "offsetTop / offsetBottom",
+      "type": "never"
+    },
+    {
+      "description": "DOM id of the outer (in-flow) box.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Structural class on the outer box.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Anchor — takes an `AffixProp` subset as its own `affix` prop and pins its section nav with this.",
+    "PageContainer — `stickyFooter` / `footerReveal=\"onScroll\"` is the page-level answer; it shares the same `useIntersects` observer this uses.",
+    "FloatButton.BackTop — the other public scroll-position API, and where `target`'s lazy-getter shape comes from.",
+    "Topbar / AppShell — the app chrome an affixed bar usually sits UNDER; `--affix-inset-block-start` is how it clears it."
+  ],
+  "rules": [
+    2,
+    40,
+    44,
+    45
+  ],
+  "storyPath": "layout/Affix.stories.tsx",
+  "tagline": "Ant Design `Affix` (6.6.5): pin an element to its scrollport once the page scrolls past it, and REPORT that it is pinned. `position: sticky` pins and then says nothing, so a sticky header cannot shrink, swap its logo or raise its shadow; this one exposes the boolean as `data-affixed` for CSS and `onChange` for JavaScript, and holds the flow open with a MEASURED placeholder so the page does not jump by the bar's height at the moment it pins.",
+  "usage": [
+    "DO use it whenever the pinned state has to be VISIBLE — a header that condenses, a toolbar that gains a shadow over the rows sliding under it, a filter rail that swaps to a compact form. That state is the entire reason this exists; if you need none of it, plain `position: sticky` is lighter and correct.",
+    "DO style the pinned state off `[data-affixed]` on `data-slot=\"affix-content\"`, and transition on `--duration-fast` / `--ease-standard`. The condensed bar must still be there under `prefers-reduced-motion` — it snaps to the smaller size, it never fades out.",
+    "DO set the resting offset ONCE in your theme (`:root { --affix-inset-block-start: 4rem; }`) when every affixed bar in the product has to clear the same app header. `offsetBlockStart` is the per-instance override, not the place to repeat a global decision.",
+    "DO pass `target` when the page scrolls inside a pane rather than the document — an AppShell main region, a dialog body, a MasterDetail column.",
+    "DON'T put a `transform`, `filter` or `backdrop-filter` on an ancestor. That ancestor becomes the containing block for `position: fixed` and the bar pins to it instead of the scrollport. The same limitation applies to `position: sticky` and to antd's Affix; there is no fix inside the component.",
+    "DON'T give the children `position: absolute`, and DON'T expect a horizontally scrolling container to work — antd documents both, and both are true here.",
+    "DON'T hand-roll the placeholder. The height is MEASURED, so it is right at every width and after any re-wrap; a number written once in CSS is wrong at every other width, which is the page-jump bug this component exists to remove."
+  ],
+  "useCases": [
+    "A site or app header that condenses on scroll: the wordmark shrinks to a monogram and the bar loses half its height, driven by `data-affixed` alone.",
+    "A table toolbar (search, filters, bulk actions) that stays reachable over a thousand-row list and gains a shadow the moment it starts covering rows.",
+    "A form's action footer pinned to the bottom of a long form with `offsetBlockEnd`, released once the real end of the form scrolls into view.",
+    "The substrate under `Anchor affix` — antd specifies Anchor's own `affix` prop as `AffixProps`, so the two are one stack."
+  ]
+}

package/agent/components/Alert.json

@@ -0,0 +1,65 @@
+{
+  "example": "import { Alert, AlertTitle, AlertDescription } from \"@godxjp/ui/feedback\";\n\n<Alert tone=\"warning\">\n  <AlertTitle>3 件の打刻漏れがあります</AlertTitle>\n  <AlertDescription>本日中に確認してください。</AlertDescription>\n</Alert>",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "Alert",
+  "props": [
+    {
+      "defaultValue": "\"default\"",
+      "description": "STRUCTURAL axis, orthogonal to `tone` (which owns colour + icon): \"default\" is the inline rounded card; \"banner\" is the full-bleed attention strip — prefer the `Banner` export, which fixes this axis.",
+      "name": "variant",
+      "type": "\"default\" | \"banner\""
+    },
+    {
+      "description": "Renders an × dismiss button when provided.",
+      "name": "onDismiss",
+      "type": "() => void"
+    },
+    {
+      "description": "Override or hide (false) the icon.",
+      "name": "icon",
+      "type": "LucideIcon | false"
+    },
+    {
+      "description": "Semantic tone driving the colour + leading icon.",
+      "name": "tone",
+      "type": "\"success\" | \"warning\" | \"destructive\" | \"info\" | \"neutral\""
+    }
+  ],
+  "related": [
+    "Toaster — use for transient, auto-dismissing feedback ('Record saved', 'Deleted'). Alert is for persistent page-scoped banners; Toaster is for fire-and-forget notifications triggered by toast() from sonner.",
+    "AlertMutationFeedback — use when you want inline success/error feedback tightly coupled to a form mutation's state (renders inline below the submit button). Alert requires you to manage show/hide state yourself.",
+    "DataState — use for full query lifecycle (loading skeleton + empty state + error) inside a data-fetching section. Alert.QueryError is the error sub-component DataState uses internally; prefer DataState when you also need the loading/empty states.",
+    "EmptyState — use for the zero-data case inside a list or table section, not for errors or warnings. Alert is for status messages; EmptyState is for the absence of data."
+  ],
+  "rules": [],
+  "storyPath": "feedback/Alert.stories.tsx",
+  "subParts": [
+    "AlertActions",
+    "AlertBase",
+    "AlertContent",
+    "AlertDescription",
+    "AlertMutationFeedback",
+    "AlertQueryError",
+    "AlertTitle"
+  ],
+  "tagline": "Inline alert banner with variant-aware icon + optional dismiss. Parts: Alert/AlertTitle/AlertDescription/AlertActions/AlertQueryError.",
+  "usage": [
+    "ANATOMY (positions are fixed — never re-lay-them-out): Alert is ONE horizontal row — a SINGLE leading tone icon at the inline-start (top-aligned to the first text line, auto-selected by `tone`, never two icons), then the text body (Title/Description), then `<Alert.Actions>` in a trailing-RIGHT column (≥sm), and the dismiss × pinned to the TOP-RIGHT corner (rendered by `onDismiss`). DON'T stack these vertically, DON'T make the action a full-width bar under the text, DON'T center the × at the bottom, DON'T add a second icon — that hand-rolled vertical banner is the #1 Alert mistake.",
+    "DO compose text as `<Alert.Title>` + `<Alert.Description>` — they stack vertically inside the body (the Example below is canonical). When you add `<Alert.Actions>`, the body becomes a two-column grid (text | actions) at ≥sm; group multi-part text in `<Alert.Content>` so it occupies the text column as one block: `<Alert tone=\"destructive\"><Alert.Content><Alert.Title>Error</Alert.Title><Alert.Description>{msg}</Alert.Description></Alert.Content><Alert.Actions><Button …/></Alert.Actions></Alert>`.",
+    "DO use `Alert.QueryError` (alias `AlertQueryError`) for TanStack Query / API failure surfaces — it already renders humanError(error), an i18n title, and an optional Retry button. Never hand-roll that pattern.",
+    "`AlertMutationFeedback` props: `mutation`, `onRetry?`, `showRetry?` (default `true`), `pending?`, `ignoreValidationErrors?: boolean`, `className?`. `ignoreValidationErrors={true}` skips the alert for every error where `classifyQueryError(mutation.error).category === \"validation\"` (400/422). DEFAULT (omitted): skip a validation error only when rendered inside a `FormRoot`/`Form` whose `errors` bag holds at least one message (the fields show it, `<FormErrors />` shows unclaimed keys); outside such a form, or with an empty/absent bag, the alert renders. So DON'T hand-guard `{!isValidation && <AlertMutationFeedback …/>}` inside `FormRoot errors={…}` — a 422 is not drawn twice, and a 5xx still renders. Pass `ignoreValidationErrors={false}` to force the alert in such a form.",
+    "DON'T pass raw action elements directly as top-level children of `<Alert>` without wrapping them in `<Alert.Actions>` — the layout slot only activates correctly via the `data-slot=\"alert-actions\"` wrapper.",
+    "DON'T hand-roll a dismiss ✕ button — pass `onDismiss` to `<Alert>` and the component renders its own accessible dismiss button with `aria-label=\"Dismiss\"`. The `onDismiss` handler may return a Promise.",
+    "DON'T suppress the icon with `icon={false}` unless there is a deliberate design reason; the icon is the primary a11y cue for sighted users since the root already carries `role=\"alert\"` for screen readers.",
+    "DO NOT use `Alert` for transient ephemeral feedback (e.g. 'saved successfully'). Use `toast()` from sonner + `<Toaster>` for that. `Alert` is for persistent, page-scoped banners that stay visible until the user acts or dismisses."
+  ],
+  "useCases": [
+    "Page-level error banner after a form submission fails server-side validation — `tone=\"destructive\"` with `Alert.Title` summarising the error and `Alert.Description` listing field issues, paired with `onDismiss` so the user can clear it.",
+    "Inline warning at the top of an accounting invoice list when the OAuth token for the MF sync is about to expire — `tone=\"warning\"` with an `Alert.Actions` containing a 'Reconnect' Button.",
+    "Success confirmation banner rendered after a bulk-import job completes and the user returns to the list page — `tone=\"success\"` with `Alert.Description` showing the record count imported.",
+    "TanStack Query data-fetch failure inside a Card body — use `<Alert.QueryError error={error} onRetry={refetch} />` instead of writing a custom error state.",
+    "Informational notice at the top of a settings page when a feature is in beta or requires a plan upgrade — `tone=\"info\"` with a short description and an `Alert.Actions` 'Learn more' link.",
+    "Dismissible billing-overdue notice at the top of the dashboard — `tone=\"destructive\"` with `onDismiss` that sets a session flag so it does not reappear until the next login."
+  ]
+}

package/agent/components/AlertDialog.json

@@ -0,0 +1,109 @@
+{
+  "example": "import { AlertDialog } from \"@godxjp/ui/feedback\";\n\n<AlertDialog\n  open={open}\n  onOpenChange={setOpen}\n  title=\"Delete project\"\n  description=\"This action cannot be undone.\"\n  confirmLabel=\"Delete\"\n  cancelLabel=\"Cancel\"\n  onConfirm={async () => {\n    await deleteProject();\n    setOpen(false);\n  }}\n  variant=\"destructive\"\n/>",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "AlertDialog",
+  "props": [
+    {
+      "description": "Controlled open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state change handler.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "Accessible title/announcement for the alertdialog.",
+      "name": "title",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Optional supporting explanatory text.",
+      "name": "description",
+      "type": "string"
+    },
+    {
+      "description": "Primary action label (defaults to translated continue).",
+      "name": "confirmLabel",
+      "type": "string"
+    },
+    {
+      "description": "Dismiss action label (defaults to translated cancel).",
+      "name": "cancelLabel",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Variant passed through to the confirm button.",
+      "name": "variant",
+      "type": "\"default\" | \"destructive\""
+    },
+    {
+      "description": "Optional type-to-confirm phrase to prevent accidental confirm.",
+      "name": "confirmPhrase",
+      "type": "string"
+    },
+    {
+      "description": "Semantic alias of `confirmPhrase` — the exact token to type (e.g. an org slug) before confirm arms.",
+      "name": "challenge",
+      "type": "string"
+    },
+    {
+      "description": "Primary action handler.",
+      "name": "onConfirm",
+      "type": "() => Promise<void> | void"
+    },
+    {
+      "description": "Optional step-up re-auth (passkey/2FA) gate; must resolve truthy before `onConfirm` fires. Returning false keeps the dialog open and announces failure.",
+      "name": "stepUp",
+      "type": "() => Promise<boolean> | boolean"
+    },
+    {
+      "description": "Keep modal open after confirm when true.",
+      "name": "keepOpenOnConfirm",
+      "type": "boolean"
+    },
+    {
+      "description": "Disable actions while async work is running.",
+      "name": "pending",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Dialog — use for form-style and non-destructive modal flows, no confirm preset behavior.",
+    "AlertDialogRoot — the compound counterpart, and the OLDER way in. It still works and is not going away in this major, but a confirmation body the preset does not cover (a summary table, a diff, a required reason field) is now better written as `Dialog` with `variant=\"destructive\"`: same `role=\"alertdialog\"`, same non-dismissable scrim, freeform body, and `DialogBody` / `DialogClose` available — the two parts the `AlertDialog*` family never had (gh#567)."
+  ],
+  "rules": [
+    23,
+    3
+  ],
+  "storyPath": "feedback/AlertDialog.stories.tsx",
+  "subParts": [
+    "AlertDialogAction",
+    "AlertDialogCancel",
+    "AlertDialogContent",
+    "AlertDialogDescription",
+    "AlertDialogFooter",
+    "AlertDialogHeader",
+    "AlertDialogOverlay",
+    "AlertDialogPortal",
+    "AlertDialogTitle",
+    "AlertDialogTrigger"
+  ],
+  "tagline": "Canonical modal confirmation flow (destructive / high-stakes decisions). Preserves confirm semantics with `role=\"alertdialog\"` and built-in cancel/confirm handling.",
+  "usage": [
+    "Use `AlertDialog` for destructive/irreversible actions (delete, void, unpublish, archive, etc.).",
+    "Use `confirmPhrase`/`challenge` for high-friction operations (e.g. typing an org slug) to reduce accidental confirmation — both force the destructive shape: the destructive confirm button plus a leading status glyph beside the title, which is Ant Design `Modal.confirm` parity. The header surface stays UNTINTED — antd signals danger with the glyph and never tints a modal header (its soft `colorErrorBg` belongs to Alert/Tag/message). To tint the band anyway, set `DialogHeader tone` yourself; it is a separate seven-value axis the preset no longer imposes.",
+    "Pass `stepUp` for a passkey/2FA re-auth gate that must resolve truthy before `onConfirm` runs (refunds, org deletion).",
+    "Pass `keepOpenOnConfirm` when the confirm handler advances a multi-step flow and should not close immediately."
+  ],
+  "useCases": [
+    "Dangerous delete or irreversible workflow confirmation that should block the background UI.",
+    "Organization/resource deletion gated behind typing the exact slug (`challenge`).",
+    "Refunds or privileged actions requiring step-up re-authentication before they run.",
+    "Destructive batch operations that should remain modal and explicit until action is intentionally confirmed."
+  ]
+}

package/agent/components/AlertDialogRoot.json

@@ -0,0 +1,52 @@
+{
+  "example": "import {\n  AlertDialogRoot, AlertDialogTrigger, AlertDialogPortal, AlertDialogOverlay,\n  AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription,\n  AlertDialogFooter, AlertDialogAction, AlertDialogCancel,\n} from \"@godxjp/ui/feedback\";\nimport { Button } from \"@godxjp/ui/general\";\n\nfunction ConfirmSettlement() {\n  return (\n    <AlertDialogRoot>\n      <AlertDialogTrigger asChild><Button variant=\"outline\" size=\"sm\">支払を確定</Button></AlertDialogTrigger>\n      <AlertDialogPortal>\n        <AlertDialogOverlay />\n        <AlertDialogContent className=\"max-w-md\">\n          <AlertDialogHeader>\n            <AlertDialogTitle>2026年7月分の支払を確定しますか？</AlertDialogTitle>\n            <AlertDialogDescription>確定すると振込データが生成されます。</AlertDialogDescription>\n          </AlertDialogHeader>\n          {/* freeform impact summary goes here */}\n          <AlertDialogFooter>\n            <AlertDialogCancel>戻る</AlertDialogCancel>\n            <AlertDialogAction>確定する</AlertDialogAction>\n          </AlertDialogFooter>\n        </AlertDialogContent>\n      </AlertDialogPortal>\n    </AlertDialogRoot>\n  );\n}",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "AlertDialogRoot",
+  "props": [
+    {
+      "description": "Controlled open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Uncontrolled initial open state (use with AlertDialogTrigger).",
+      "name": "defaultOpen",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state change handler.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "description": "The trigger and the portalled alertdialog parts.",
+      "name": "children",
+      "type": "React.ReactNode"
+    }
+  ],
+  "related": [
+    "AlertDialog — the flat preset. Prefer it; it is the canonical destructive-confirm recipe and needs no compound markup.",
+    "Dialog — compound modal for form-style, non-destructive flows. `role=dialog`, dismissible on outside click.",
+    "AlertDialogHeader — the header band; `tone` tints only the background (default | success | warning | destructive | info | muted | neutral)."
+  ],
+  "rules": [
+    23,
+    3
+  ],
+  "storyPath": "feedback/AlertDialog.stories.tsx",
+  "tagline": "Compound alertdialog Root — the role=\"alertdialog\" mirror of Dialog's root. Wraps Radix AlertDialog.Root and supplies the context AlertDialogTitle/AlertDialogDescription/AlertDialogAction/AlertDialogCancel read. Parts: AlertDialogTrigger/AlertDialogPortal/AlertDialogOverlay/AlertDialogContent/AlertDialogHeader/AlertDialogFooter/AlertDialogTitle/AlertDialogDescription/AlertDialogAction/AlertDialogCancel.",
+  "usage": [
+    "Reach for the flat `AlertDialog` preset FIRST — it already covers title/description/confirm/cancel, the typed `challenge`, `stepUp` re-auth and `pending`. Use `AlertDialogRoot` only when the confirm body needs content the preset does not model (an impact summary, a diff, a nested list).",
+    "DO name it `AlertDialogRoot`, not `AlertDialog` — the `AlertDialog` export is the flat preset and takes a completely different (non-compound) prop API.",
+    "DO include `AlertDialogHeader` with `AlertDialogTitle` inside every `AlertDialogContent` — Radix requires an accessible title for `role=alertdialog`; omitting it warns in the console and breaks screen-reader announcement. `AlertDialogHeader` also takes the prop-driven `title`/`subtitle`/`extra`/`tone` form, where `subtitle` renders the `AlertDialogDescription`.",
+    "DO portal explicitly: `AlertDialogContent` does NOT self-portal (unlike `DialogContent`). Wrap it in `AlertDialogPortal` with a sibling `AlertDialogOverlay`, or the scrim and stacking context are wrong.",
+    "DO use `AlertDialogAction` / `AlertDialogCancel` for the footer buttons — they carry the button styling AND the Radix close semantics. Do not wrap them in `asChild` `<Button variant=…>`: the Root's button classes and the child's would both land on the element and the variant would not win.",
+    "DO NOT import `@radix-ui/react-alert-dialog` directly in a consumer app. Everything the compound needs is exported from `@godxjp/ui/feedback`."
+  ],
+  "useCases": [
+    "Confirm-with-impact-summary — a destructive confirmation that must show what will be affected (a list of 3 downstream jobs, a table of invoices) before the user commits. The flat preset only takes a string `description`.",
+    "Batch-close confirmation whose body renders a rich breakdown (counts, totals, per-tenant rows) alongside the standard confirm/cancel pair.",
+    "Any confirmation that must keep `role=alertdialog` semantics (focus trap, no dismiss-on-outside-click) but needs freeform children — use Dialog only when the flow is non-destructive."
+  ]
+}

package/agent/components/Anchor.json

@@ -0,0 +1,119 @@
+{
+  "docPath": "navigation/anchor.tsx",
+  "example": "import { Anchor } from \"@godxjp/ui/navigation\";\n\n<Anchor\n  offsetBlockStart={64}\n  targetOffsetBlockStart={88}\n  label=\"On this page\"\n  items={[\n    { key: \"overview\", href: \"#overview\", title: \"Overview\" },\n    {\n      key: \"pricing\",\n      href: \"#pricing\",\n      title: \"Pricing\",\n      children: [{ key: \"tiers\", href: \"#tiers\", title: \"Tiers\" }],\n    },\n    { key: \"faq\", href: \"#faq\", title: \"FAQ\" },\n  ]}\n  onValueChange={(href) => console.log(\"reading\", href)}\n/>",
+  "group": "navigation",
+  "importPath": "@godxjp/ui/navigation",
+  "name": "Anchor",
+  "props": [
+    {
+      "description": "antd `items`, in document order. Each is `{ key, href, title, target?, children?, replace?, targetOffsetBlockStart? }` — antd's AnchorItem, field for field, with its per-link `targetOffset` on the logical axis. `children` is ONE level of nesting and is dropped (with a warning) when `direction=\"horizontal\"`, as in antd.",
+      "name": "items",
+      "type": "AnchorItemProp[]"
+    },
+    {
+      "description": "antd `direction`, default `\"vertical\"`. Horizontal is one scrolling row: the ink rail moves along the block-end edge and nesting is not available.",
+      "name": "direction",
+      "type": "\"vertical\" | \"horizontal\""
+    },
+    {
+      "description": "antd `affix`, default `true` — literally antd's own `AffixProps` minus the fields Anchor supplies, which is why Affix is the dependency. `false` leaves the nav in the flow.",
+      "name": "affix",
+      "type": "boolean | Omit<AffixProp, 'offsetBlockStart' | 'offsetTop' | 'target' | 'children'>"
+    },
+    {
+      "description": "antd `bounds`, default `5`. Pixel tolerance added to the decision line.",
+      "name": "bounds",
+      "type": "number"
+    },
+    {
+      "description": "The active `href`, as the controlled triad. `onValueChange` is antd's `onChange` under this library's name, and it reports the link the SCROLL POSITION resolved (antd's own note) rather than what `getCurrentAnchor` substituted. antd's `onChange` is typed `never` and warns.",
+      "name": "value / defaultValue / onValueChange",
+      "type": "string / string / (href: string) => void"
+    },
+    {
+      "description": "antd `getCurrentAnchor` — the last word on the highlight, running INSIDE the resolution with no render round-trip. A controlled `value` outranks it.",
+      "name": "getCurrentAnchor",
+      "type": "(activeLink: string) => string"
+    },
+    {
+      "description": "antd `offsetTop`, on its LOGICAL axis: where the decision line sits, and the distance `Affix` pins the nav at. Default `0`.",
+      "name": "offsetBlockStart",
+      "type": "number"
+    },
+    {
+      "description": "antd `targetOffset`, on its LOGICAL axis: where a CLICKED section lands — the room a pinned header needs. Defaults to `offsetBlockStart`, and (as in antd) it moves the decision line too, so a click can never leave the entry it just selected unselected.",
+      "name": "targetOffsetBlockStart",
+      "type": "number"
+    },
+    {
+      "description": "antd `getContainer`, default `() => window` — the scroll box holding the sections.",
+      "name": "getContainer",
+      "type": "() => HTMLElement | Window"
+    },
+    {
+      "description": "antd `showInkInFixed`, default `false`. Draw the travelling ink even with `affix={false}`; the static rule is always drawn.",
+      "name": "showInkInFixed",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `replace`, default `false`. Replace the hash in history rather than pushing it; `items[].replace` overrides it per entry.",
+      "name": "replace",
+      "type": "boolean"
+    },
+    {
+      "description": "antd `onClick`, fired before the scroll. A modified click is never hijacked.",
+      "name": "onClick",
+      "type": "(event: React.MouseEvent<HTMLAnchorElement>, item: AnchorItemProp) => void"
+    },
+    {
+      "description": "Accessible name of the <nav> landmark. antd ships an unnamed <div>; a page routinely carries a breadcrumb, a rail and this, so a localized default (\"On this page\") applies when omitted.",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "NOT props. antd's spellings, kept in the type so arriving from antd's docs is a COMPILE ERROR naming `onValueChange` / `offsetBlockStart` / `targetOffsetBlockStart`, plus a development console.warn.",
+      "name": "onChange / offsetTop / targetOffset",
+      "type": "never"
+    },
+    {
+      "description": "DOM id of the <nav>.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Structural class on the <nav>.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Affix — the pin underneath it. antd specifies `Anchor.affix` as `AffixProps`, so the two ship as one stack.",
+    "NavList — ROUTE navigation inside a page; its `activeId` is the answer Anchor computes, for a different kind of destination.",
+    "LegalDocumentShell — carries its own built-in contents rail for the legal-document case; Anchor is the general one, for content the shell does not own.",
+    "Breadcrumb — where you ARE in the hierarchy (`aria-current=\"page\"`), not where you are on the page."
+  ],
+  "rules": [
+    2,
+    6,
+    40,
+    44,
+    45
+  ],
+  "storyPath": "navigation/Anchor.stories.tsx",
+  "tagline": "Ant Design `Anchor` (6.6.5): the in-page section navigation, and the only thing in this library that COMPUTES which section is current. `NavList activeId` takes that answer as a prop. Resolves by antd's rule — the last section whose edge has crossed a single decision line — which is a pure function of scroll position and therefore cannot flicker, suppresses itself during the programmatic scroll a click starts, reads the landing hash before any scroll event, and jumps rather than tweens under `prefers-reduced-motion`.",
+  "usage": [
+    "DO give every target a real `id` and point `href` at it as `#id`. The links are real anchors: middle-clickable, deep-linkable, and correct before JavaScript boots.",
+    "DO set `targetOffsetBlockStart` to the height of whatever is pinned above the content, or a clicked section lands under the header. Leave `offsetBlockStart` alone unless the DECISION LINE also needs moving; it follows `targetOffsetBlockStart` by default.",
+    "DO use `value` / `onValueChange` when the router owns the current section; use `getCurrentAnchor` only for antd's narrower job of rewriting the resolved link in place.",
+    "DON'T reach for NavList for this. NavList is ROUTE navigation — each row is a page the router renders, and its `activeId` is an answer you already have. Anchor's entries are fragments of the page being read, which is also why the current one is `aria-current=\"location\"` and not `\"page\"`.",
+    "DON'T use Tabs either: the sections are all on the page at once and scroll past each other, where a tab panel shows one at a time.",
+    "DON'T nest more than one level, and don't nest at all when horizontal — antd allows neither, and this warns rather than rendering a second row the ink rail cannot follow.",
+    "DON'T hand-roll the scrollspy with an IntersectionObserver band. A section taller than the band reports nothing, and with several short sections in the band at once the answer depends on scroll direction; both are why this measures against a line instead."
+  ],
+  "useCases": [
+    "A long settings or policy page whose sections a reader jumps between, with the current one always visible in the rail.",
+    "API or product documentation: the on-this-page rail beside the article, tracking the reader down the page.",
+    "A marketing landing page's section nav, pinned under the site header via `affix` and `offsetBlockStart`.",
+    "A horizontal section bar on a narrow viewport, where a vertical rail has no column to live in."
+  ]
+}

package/agent/components/AppLauncher.json

@@ -0,0 +1,95 @@
+{
+  "example": "import { AppLauncher, Topbar } from \"@godxjp/ui/layout\";\n\n<Topbar\n  start={brand}\n  end={\n    <AppLauncher\n      apps={[\n        { id: \"console\", name: t(\"app.console\"), href: \"/console\", icon: <BarChart3 />, current: true },\n        { id: \"billing\", name: t(\"app.billing\"), href: \"/billing\", icon: <Receipt /> },\n      ]}\n      groups={[{ label: t(\"app.more\"), apps: [{ id: \"support\", name: t(\"app.support\"), href: supportUrl, external: true }] }]}\n      linkComponent={inertiaSidebarLink(Link)}\n      labels={labels}\n    />\n  }\n/>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AppLauncher",
+  "props": [
+    {
+      "description": "Ungrouped app tiles, rendered first with no heading. Each is { id, name, href, icon?, current?, external? } and each tile is a REAL <a href> — pass only apps the viewer may open; there is no disabled tile.",
+      "name": "apps",
+      "required": true,
+      "type": "readonly AppLauncherApp[]"
+    },
+    {
+      "description": "Labelled sections rendered after `apps` — the \"more from …\" band. Each group is a named role=\"group\", not a heading, so the same markup is correct inside the popover and inside the Sheet.",
+      "name": "groups",
+      "type": "readonly AppLauncherGroup[]"
+    },
+    {
+      "description": "Localized trigger name, panel title, empty/loading/retry copy, and the optional `externalHint` announced on an external tile (WCAG 3.2.5). `trigger` is a plain string, not a function of the current app: the nine-dot button shows no current value.",
+      "name": "labels",
+      "required": true,
+      "type": "AppLauncherLabels"
+    },
+    {
+      "defaultValue": "3",
+      "description": "Grid column count, written inline to the `--app-launcher-columns` custom property. Omit it and `.ui-app-launcher-panel` keeps its own declaration of 3 — the default sits in the stylesheet, where a theme can reach it, rather than in a component token (the token NAME vocabulary has no word for a count).",
+      "name": "columns",
+      "type": "number"
+    },
+    {
+      "description": "Framework router link — the SAME contract `Sidebar` and `NavList` take, so `inertiaSidebarLink(Link)` / `createSidebarLink(Link, \"to\")` is reused verbatim. The launcher still composes the tile; `external` apps bypass it and render a plain anchor.",
+      "name": "linkComponent",
+      "type": "SidebarLinkComponentProp"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Shows the loading state; the trigger stays openable.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "Consumer-supplied error state.",
+      "name": "error",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Consumer-owned retry callback.",
+      "name": "onRetry",
+      "type": "() => void"
+    },
+    {
+      "defaultValue": "\"auto\"",
+      "description": "Presentation contract. \"auto\" resolves through the SHARED Sheet hook useSheetResponsiveMode(): desktop popover above --sheet-responsive-breakpoint-width (48rem/768px), focus-trapped bottom Sheet at/below it. \"fullscreen\" is the LAUNCHPAD — one full-viewport modal at every width, the page behind it blurred and the grid floating on that ground (macOS Launchpad / Windows Start), with the column count stepping 3·4·5·6 on the house container ladder. Reach for it in a PLATFORM start bar, where the launcher is the primary way to move between products; keep \"auto\" for a launcher inside one app's topbar, where the grid is a shortcut and the work behind it should stay visible.",
+      "name": "responsive",
+      "type": "\"auto\" | \"popover\" | \"sheet\" | \"fullscreen\""
+    },
+    {
+      "defaultValue": "\"bar\"",
+      "description": "The BOX the trigger takes — the same split AppSettingToggle draws, for the same reason. `bar` (default) is a TopbarItem: a cell as tall as the bar, whose hover IS the bar's surface. `icon` is a square ghost Button, for chrome that is NOT a bar — a nav rail (GoDX Dock puts it there), a card header, a toolbar. A TopbarItem outside a bar has nothing to bleed to: it stretches to a container that never set a band height, and its squared corners and full-bleed hover read as a broken cell rather than a control. The panel, the grid, the labels and the responsive contract are identical in both.",
+      "name": "appearance",
+      "type": "\"bar\" | \"icon\""
+    },
+    {
+      "description": "Controlled open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state callback.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    }
+  ],
+  "related": [
+    "ServiceLauncherCard — the PAGE-SIZED launcher tile (status, hostname, plan, action, locked reason) for a service-catalogue page, where choosing is a considered act. AppLauncher's tile is bar-sized: mark + name, the whole tile one link, because changing app is a reflex. Neither is built out of the other; a grid of ServiceLauncherCards inside a popover is the wrong component.",
+    "AppShell (navRail) — the SAME platform scope expressed as a docked column instead of a bar control. Pick ONE: the launcher for a platform with MANY apps where switching is occasional (Google Workspace), the rail for a single product where switching workspace is constant enough to deserve permanent screen width (Slack).",
+    "OrgSwitcher — the other platform-scope control: which ORGANIZATION you are in, not which app. They compose; they do not replace each other.",
+    "TopbarItem — the bar cell the trigger is built from; use it directly for a one-off bar control."
+  ],
+  "rules": [],
+  "storyPath": "layout/AppLauncher.stories.tsx",
+  "tagline": "Nine-dot topbar app grid — the platform-standard way to switch app (the Google Workspace shape).",
+  "usage": [
+    "DO drop it straight into a Topbar slot. It renders NO wrapper element, so the trigger is the slot's own flex child and `.ui-topbar-item { align-self: stretch }` reaches the bar's height.",
+    "DON'T hand-roll the trigger as `Button variant=\"ghost\"` IN A BAR. A Button in a bar is a --control-height pill floating in a taller strip, with its own hover fill and its own focus ring — the exact regression corrected in 20.0.0. In a bar the trigger is a `TopbarItem`, and that is what `appearance=\"bar\"` (the default) renders. OUTSIDE a bar the square ghost Button is correct, and `appearance=\"icon\"` renders it for you — still hand-roll nothing.",
+    "DO mark the app the viewer is inside with `current` — it becomes `aria-current=\"page\"`, which is what both the tint and the announcement key off.",
+    "DO set `external` on a destination outside this SPA. It renders a plain anchor with target/rel and skips `linkComponent`, because a client-side router link to another origin routes nowhere.",
+    "DON'T wrap it in your own media query to pick popover vs sheet — `responsive=\"auto\"` already reads the shared --sheet-responsive-breakpoint-width token.",
+    "`className`, `id` and every `data-*` land on the TRIGGER, so an end-to-end selector can hold it without depending on the localized accessible name."
+  ],
+  "useCases": [
+    "A platform with several apps (console, billing, chat, people) where the bar must offer all of them from every page.",
+    "Replacing a hand-rolled dropdown of product links in the topbar end slot."
+  ]
+}