@godxjp/ui 28.9.0 → 28.10.0

package/agent/components/Separator.json

@@ -0,0 +1,86 @@
+{
+  "example": "import { formatDate } from \"@godxjp/ui/datetime\";\nimport { Separator } from \"@godxjp/ui/layout\";\n\n// Plain section rule — decorative, nothing announced.\n<Separator />\n\n// Day divider: the label is the calendar boundary, formatted on the active locale.\n<Separator label={formatDate(\"2026-08-22\", { kind: \"long\" })} labelAlign=\"start\" />\n\n// Unread watermark: content, not decoration — announced once as the separator's name.\n<Separator label={t(\"chat.newMessages\")} tone=\"primary\" />",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "Separator",
+  "props": [
+    {
+      "description": "Hide from viewport breakpoint.",
+      "name": "hideFrom",
+      "type": "BreakpointProp"
+    },
+    {
+      "description": "Hide below viewport breakpoint.",
+      "name": "hideBelow",
+      "type": "BreakpointProp"
+    },
+    {
+      "description": "Block spacing on the token scale.",
+      "name": "space",
+      "type": "GapProp"
+    },
+    {
+      "description": "Label typography step.",
+      "name": "labelSize",
+      "type": "\"2xs\" | \"xs\" | \"sm\" | \"md\""
+    },
+    {
+      "defaultValue": "\"horizontal\"",
+      "description": "Divider direction.",
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\""
+    },
+    {
+      "description": "Localized text that interrupts the rule — the rule splits into two halves around it. Horizontal only (ignored with a dev warning when vertical). A string, not a node, because it becomes the separator's ACCESSIBLE NAME. Omit for a plain rule.",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "defaultValue": "\"center\"",
+      "description": "Where the label sits on the rule. `center` is the classic conjunction; `start` is the Slack/Mattermost stream convention. Logical — it flips under dir=\"rtl\".",
+      "name": "labelAlign",
+      "type": "\"start\" | \"center\" | \"end\""
+    },
+    {
+      "defaultValue": "\"default\"",
+      "description": "Semantic emphasis of the label AND the rule together (never colour-only). `default` is the quiet chrome; use a role for an attention rule such as an unread watermark.",
+      "name": "tone",
+      "type": "\"default\" | \"muted\" | \"primary\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"inherit\""
+    },
+    {
+      "defaultValue": "true (false when `label` is set)",
+      "description": "Whether the separator is decorative for assistive tech. A `label` flips the default to false so the rule becomes a real role=\"separator\" named by the label.",
+      "name": "decorative",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "Flex direction='col' — use for vertical spacing without a visible rule.",
+    "AuthDivider — the auth-scoped preset over `Separator label` (it only re-points the --separator-* knobs at the --auth-shell-divider-* layer)."
+  ],
+  "rules": [
+    2,
+    3,
+    44,
+    45
+  ],
+  "storyPath": "layout/Separator.stories.tsx",
+  "tagline": "Tokenized horizontal or vertical rule, optionally INTERRUPTED by a localized label (day divider, unread watermark, auth conjunction).",
+  "usage": [
+    "DO use Separator for section dividers instead of raw border divs.",
+    "DO set orientation='vertical' only when the parent gives it a stable height.",
+    "DO use `label` for a message stream's day divider or a \"new messages\" unread watermark — it is the generic primitive AuthDivider was being misused for. Never hand-roll a <div> grid of two <span> rules.",
+    "DO format a day divider's date with the package's Intl/CLDR date subsystem (`formatDate(iso, { kind: \"long\" })` from @godxjp/ui/datetime) on the active locale — never hand-build the string.",
+    "DO pass `label` as a t() string. It becomes the separator's accessible name, and the visible node is aria-hidden so it is announced EXACTLY once.",
+    "DON'T set `decorative` on a labelled rule unless you mean it: role=\"none\" cannot carry a name, so the rule stops being announced as a milestone.",
+    "DON'T reach for AuthDivider outside an auth form — it is the auth-scoped preset over this and drags the --auth-shell-divider-* micro-scale with it.",
+    "DON'T bake the rule weight, the label gap/inset or the label type ramp into page CSS — they are --separator-* component tokens (rules #44/#45); retune them from theme.css."
+  ],
+  "useCases": [
+    "Separating toolbar groups",
+    "Dividing stacked page sections",
+    "Vertical split between metadata groups",
+    "A message stream's calendar-boundary day divider",
+    "A \"new messages\" unread watermark above the first unread post"
+  ]
+}

package/agent/components/ServiceCatalogCta.json

@@ -0,0 +1,46 @@
+{
+  "example": "import { ServiceCatalogCta } from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\n\n<ServiceCatalogCta\n  title={t(\"addFromCatalog\")}\n  action={\n    <Button asChild variant=\"outline\">\n      <a href={catalogUrl}>{t(\"viewCatalog\")}</a>\n    </Button>\n  }\n/>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "ServiceCatalogCta",
+  "props": [
+    {
+      "defaultValue": "Plus",
+      "description": "Decorative glyph above the title, rendered aria-hidden. Override only when the route is not an add/browse action.",
+      "name": "icon",
+      "type": "LucideIcon"
+    },
+    {
+      "description": "Localized invitation, e.g. the label of the catalog route this tile opens.",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "The real navigation control — normally a Button, or Button asChild wrapping the catalog link. The tile itself is not clickable.",
+      "name": "action",
+      "required": true,
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "ServiceLauncherCard — the real service tile this one accompanies; it carries status, metadata and the launch action.",
+    "ServiceLauncherCardSkeleton — the loading placeholder for the launcher tiles, documented under ServiceLauncherCard.",
+    "EmptyState — the zero-state primitive to reach for when the grid has NO services at all; this CTA is a companion to existing tiles, not an empty state."
+  ],
+  "rules": [
+    40
+  ],
+  "storyPath": "data-display/ServiceLauncherCard.stories.tsx",
+  "tagline": "Dashed companion tile that closes a launcher grid with the real catalog/add route — same Card geometry as ServiceLauncherCard, no status or metadata.",
+  "usage": [
+    "DO render it as the LAST child of the same ResponsiveGrid that holds the ServiceLauncherCards, so it inherits the 3→2→1 ladder and lines up with the tiles it follows.",
+    "DO give it a route that already exists. It is an invitation to a real catalog/add screen; a tile whose action goes nowhere reads as a broken service.",
+    "DON'T use it as an empty state for a grid that has no services — an empty launcher grid needs Empty, which explains the absence, not a CTA that implies there is something to add.",
+    "DON'T rebuild it as a Card with a dashed border and utility padding: the dashed surface, the medallion and the internal rhythm are token-owned (--card-service-launcher-*), same as the launcher tile."
+  ],
+  "useCases": [
+    "Closing tile of an organization console launcher grid, linking to the service catalog.",
+    "Add-a-service affordance beside the subscribed applications an admin already has."
+  ]
+}

package/agent/components/ServiceLauncherCard.json

@@ -0,0 +1,86 @@
+{
+  "example": "import { Clock } from \"lucide-react\";\nimport {\n  ServiceCatalogCta,\n  ServiceLauncherCard,\n  ServiceLauncherCardSkeleton,\n} from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n// ResponsiveGrid owns the canonical 3 → 2 → 1 ladder; the page writes no tracks.\n<ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }}>\n  {loading\n    ? services.map((s) => <ServiceLauncherCardSkeleton key={s.id} label={t(\"loadingService\")} />)\n    : services.map((s) => (\n        <ServiceLauncherCard\n          key={s.id}\n          icon={Clock}\n          title={s.name}\n          statusLabel={s.accessLabel}\n          statusTone={s.accessTone}\n          description={s.description}\n          metadata={s.hostnameAndPlan}\n          disabledReason={s.blockedReason}\n          action={\n            <Button asChild={s.canLaunch} disabled={!s.canLaunch}>\n              {s.canLaunch ? <a href={s.launchUrl}>{t(\"launch\")}</a> : t(\"launch\")}\n            </Button>\n          }\n        />\n      ))}\n  <ServiceCatalogCta\n    title={t(\"addFromCatalog\")}\n    action={<Button variant=\"outline\">{t(\"viewCatalog\")}</Button>}\n  />\n</ResponsiveGrid>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "ServiceLauncherCard",
+  "props": [
+    {
+      "description": "Decorative service glyph rendered in the canonical semantic icon surface.",
+      "name": "icon",
+      "required": true,
+      "type": "LucideIcon"
+    },
+    {
+      "description": "Real downstream service display name.",
+      "name": "title",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "2",
+      "description": "Semantic heading level; visual styling remains token-owned.",
+      "name": "titleLevel",
+      "type": "1 | 2 | 3 | 4"
+    },
+    {
+      "description": "Consumer-provided access/readiness label. The component never infers status.",
+      "name": "statusLabel",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"neutral\"",
+      "description": "Semantic tone corresponding to the real statusLabel.",
+      "name": "statusTone",
+      "type": "\"success\" | \"warning\" | \"destructive\" | \"info\" | \"neutral\" | \"muted\""
+    },
+    {
+      "description": "Localized service summary.",
+      "name": "description",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Compact mono metadata such as real hostname and subscribed plan.",
+      "name": "metadata",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Real launch/detail action, normally a Button or Button asChild link.",
+      "name": "action",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Localized prose reason accompanying a disabled/unavailable action. Rendered ABOVE the action (so assistive tech meets the explanation before the disabled control) and marks the tile data-unavailable, which mutes the medallion via --card-service-launcher-unavailable-icon-*. It never disables the action itself — that stays the consumer's Button prop.",
+      "name": "disabledReason",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "ServiceLauncherCardSkeleton — shape-matched initial loading placeholder (required `label`, aria-busy, no live region).",
+    "ServiceCatalogCta — dashed companion tile for an existing catalog/add route.",
+    "ResponsiveGrid — OWNS the 3→2→1 layout around launcher tiles; the launcher never ships grid tracks of its own.",
+    "Card — general-purpose surface; use ServiceLauncherCard instead for this established composite."
+  ],
+  "rules": [
+    40
+  ],
+  "storyPath": "data-display/ServiceLauncherCard.stories.tsx",
+  "subParts": [
+    "ServiceLauncherCardSkeleton"
+  ],
+  "tagline": "Token-owned downstream-service launcher tile with semantic icon, status, metadata, action, disabled reason, matching skeleton, and companion catalog CTA.",
+  "usage": [
+    "DO provide status, hostname, plan, access state and action from the product's real API contract. ServiceLauncherCard deliberately performs no entitlement or URL inference — it has no href/entitlement/available prop at all.",
+    "DO own the layout with ResponsiveGrid columns={{ sm: 1, md: 2, lg: 3 }} — the canonical 3→2→1 launcher grid. ResponsiveGrid queries its OWN container (40/48/64rem), so never hand-write grid-template-columns or a media query in the page. The shorthand columns={3} also works but widens to 2 columns earlier (40rem).",
+    "DO render ServiceLauncherCard directly as a grid child; it already owns its Card shell, its 36px medallion (--control-height-lg tier) and the canonical internal rhythm.",
+    "DO replace it with ServiceLauncherCardSkeleton while loading (it carries a required `label` and aria-busy, and deliberately opens no live region). Use ServiceCatalogCta as the peer tile only when a real catalog/add route exists.",
+    "DO keep `metadata` to machine identifiers (hostname · plan) — it is the only mono line. Sentences belong in `description` / `disabledReason`.",
+    "DON'T recreate launcher geometry with page-local CSS, utility padding, grid tracks, or a hand-built Card hierarchy. Retune it with the --card-service-launcher-* tokens instead.",
+    "DON'T show LIVE, a hostname, subscribed plan, or launch action merely because a service is active in the global catalog."
+  ],
+  "useCases": [
+    "Organization console launcher showing subscribed downstream applications with a real SSO launch action.",
+    "Service picker where unavailable apps remain visible with a disabled action and permission/subscription reason.",
+    "Responsive 3→2→1 launcher grid with a final ServiceCatalogCta tile linked to an existing catalog route."
+  ]
+}

package/agent/components/ServiceRolePanel.json

@@ -0,0 +1,83 @@
+{
+  "docPath": "layout/service-role-panel.tsx",
+  "example": "import { PermissionMatrix } from \"@godxjp/ui/data-display\";\nimport { ServiceRolePanel } from \"@godxjp/ui/layout\";\n\n<ServiceRolePanel\n  roles={roles}\n  value={selectedRoleId}\n  onValueChange={setSelectedRoleId}\n  onDeleteRole={(roleId) => deleteRole.mutate(roleId)}\n>\n  {(role) =>\n    role && <PermissionMatrix roles={[role]} permissions={permissions} grants={grants} readOnly={role.locked} />\n  }\n</ServiceRolePanel>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "ServiceRolePanel",
+  "props": [
+    {
+      "description": "Giá trị có kiểm soát: id vai trò đang chọn.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Id vai trò khởi tạo khi không kiểm soát.",
+      "name": "defaultValue",
+      "type": "string"
+    },
+    {
+      "description": "Phát khi vai trò đổi.",
+      "name": "onValueChange",
+      "type": "(roleId: string) => void"
+    },
+    {
+      "description": "The role collection — consumer domain data. `locked` = system role: lock badge, never deletable. memberCount is CLDR-pluralized.",
+      "name": "roles",
+      "required": true,
+      "type": "{ id: string; name: string; description?: string; memberCount?: number; locked?: boolean }[]"
+    },
+    {
+      "description": "Controlled selection triad; defaults to the first role.",
+      "name": "value / defaultValue / onValueChange",
+      "type": "string / (roleId: string) => void"
+    },
+    {
+      "description": "The detail surface. A render function receives the selected role — typically renders a PermissionMatrix + role metadata.",
+      "name": "children",
+      "type": "ReactNode | (role) => ReactNode"
+    },
+    {
+      "description": "Its PRESENCE arms a per-role delete affordance behind the built-in destructive AlertDialog; it fires only after the user confirms. Locked roles never offer it.",
+      "name": "onDeleteRole",
+      "type": "(roleId: string) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Hide every mutating affordance.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "description": "The #216 lifecycle vocabulary (precedence loading → denied → error → empty), same semantics as DataTable/PermissionMatrix.",
+      "name": "loading / denied / error / empty / onRetry",
+      "type": "boolean | ReactNode / handler"
+    },
+    {
+      "description": "Forwarded to MasterDetail (localized region labels by default). Never re-derive tracks or breakpoints in the app.",
+      "name": "railWidth / masterViewport / collapseBelow / masterLabel / detailLabel",
+      "type": "MasterDetail geometry + region labels"
+    }
+  ],
+  "related": [
+    "MasterDetail — the geometry underneath; use it directly for non-role collections.",
+    "PermissionMatrix — the canonical detail body for a selected role.",
+    "AlertDialog — the confirm primitive the panel embeds; use directly for other destructive flows."
+  ],
+  "rules": [
+    24,
+    40
+  ],
+  "storyPath": "layout/ServiceRolePanel.stories.tsx",
+  "tagline": "Geometry (1440/1024 two-track, 390 stacked) is MasterDetail's tokens.",
+  "usage": [
+    "DO compose the detail from real primitives — the panel deliberately owns NO detail layout; PermissionMatrix + Descriptions is the typical body.",
+    "DO rely on the built-in AlertDialog for deletion — never wire a bare onClick delete; the confirm gate is the contract.",
+    "DO pass masterViewport=\"compact\" for long role collections so the rail scrolls inside its region after stacking.",
+    "DO NOT nest interactive controls in a role row — the select button and the delete button are SIBLINGS by design; keep any custom row content non-interactive."
+  ],
+  "useCases": [
+    "Service detail → roles tab: role list rail + permission matrix detail.",
+    "Org role management screen with locked system roles and confirmed deletion.",
+    "Read-only role browser for auditors (readOnly)."
+  ]
+}

package/agent/components/Sheet.json

@@ -0,0 +1,85 @@
+{
+  "example": "import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle } from \"@godxjp/ui/feedback\";\nimport { Button } from \"@godxjp/ui/general\";\n\n<Sheet open={open} onOpenChange={setOpen}>\n  <SheetTrigger asChild><Button variant=\"outline\" size=\"sm\">絞り込み</Button></SheetTrigger>\n  <SheetContent side=\"right\">\n    <SheetHeader><SheetTitle>フィルター設定</SheetTitle></SheetHeader>\n    {/* filter fields */}\n  </SheetContent>\n</Sheet>",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "Sheet",
+  "props": [
+    {
+      "description": "Controlled open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state change handler.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    },
+    {
+      "defaultValue": "true",
+      "description": "On Sheet (root). `false` renders a NON-MODAL sheet (WAI-ARIA APG allows non-modal dialogs): the page behind stays interactive and in the accessibility tree (no inert/aria-hidden), no scroll lock, no scrim, an outside press does NOT close it, and there is no `aria-modal`. The panel keeps role=dialog + its title as name, and the same side placement, width, responsive presentation and tokens. Focus moves into it on open, Tab can leave it, Escape closes it while focus is inside, and focus returns to the trigger on close (only if focus was still inside). Same contract as Dialog `modal={false}`. gh#701.",
+      "name": "modal",
+      "type": "boolean"
+    },
+    {
+      "description": "On SheetContent (side left/right): desired panel width (number→px). Default w-3/4 sm:max-w-md.",
+      "name": "width",
+      "type": "number | string"
+    },
+    {
+      "defaultValue": "\"side\"",
+      "description": "On SheetContent: the responsive drawer / detail-panel contract. \"side\" (default) always renders the physical `side` you named. \"auto\" renders the desktop side panel above --sheet-responsive-breakpoint-width (48rem/768px) and the mobile BOTTOM sheet at/below it, capped by --sheet-bottom-max-height (85dvh). \"bottom\" pins the bottom-sheet presentation.",
+      "name": "responsive",
+      "type": "\"auto\" | \"side\" | \"bottom\""
+    },
+    {
+      "description": "On SheetHeader (Ant-style): title (→ SheetTitle, accessible name), subtitle (→ SheetDescription), right-aligned extra actions, and a soft semantic `tone` background band. Children still supported.",
+      "name": "title / subtitle / extra / tone",
+      "type": "ReactNode / ReactNode / ReactNode / ToneProp"
+    }
+  ],
+  "related": [
+    "Dialog — use Dialog (centered modal) when the action is destructive, requires full user focus, or needs a confirm/alertdialog (mode='confirm'). Use Sheet when the user benefits from seeing the page content behind the slide-over (filters, detail peek, quick-edit).",
+    "Toolbar/ToolbarGroup — use Toolbar for inline persistent filter controls above a DataTable (no overlay). Use Sheet when the filter set is large (>4 controls) or on mobile where inline controls collapse poorly.",
+    "Popover — use Popover for lightweight, anchor-positioned context menus or single-control overlays (date picker, color picker). Use Sheet when the panel has a header, multiple fields, or footer actions that need a dedicated panel.",
+    "SplitPane — use SplitPane for a persistent side-by-side layout where both panes are always visible. Use Sheet when the secondary panel is transient and should overlay the primary content."
+  ],
+  "rules": [
+    3
+  ],
+  "storyPath": "feedback/Sheet.stories.tsx",
+  "subParts": [
+    "SheetBody",
+    "SheetClose",
+    "SheetContent",
+    "SheetDescription",
+    "SheetFooter",
+    "SheetHeader",
+    "SheetOverlay",
+    "SheetPortal",
+    "SheetTitle",
+    "SheetTrigger"
+  ],
+  "tagline": "Side-panel drawer / responsive detail panel (Radix Dialog). Parts: Sheet/SheetTrigger/SheetContent(side=right|left|top|bottom, responsive=auto|side|bottom)/SheetHeader/SheetBody/SheetTitle/SheetFooter.",
+  "usage": [
+    "DO build the panel with SheetHeader (pass `title`/`subtitle`/`extra`/`tone` OR children) > SheetBody (scrollable, ring-safe) > SheetFooter (pinned). SheetTitle is required for a11y — the `title` prop renders it for you. Never skip the title.",
+    "DO set `width` on SheetContent for a wider/narrower panel (e.g. width={480}); it caps at the viewport so small screens still get a full-width panel.",
+    "DO use responsive=\"auto\" for a record detail panel / drawer that must be a desktop side panel and a mobile bottom sheet — ONE <Sheet>, no page-local media query. The breakpoint is the --sheet-responsive-breakpoint-width token, so a service moves the line once for every overlay. `width` is ignored while the bottom presentation is active (a bottom sheet is full-bleed).",
+    "DON'T hardcode an overlay breakpoint in app code (useMediaQuery(\"(max-width: 390px)\")). If a composite must swap a desktop surface for a mobile sheet (a Popover→Sheet switcher, for example), call the exported useSheetResponsiveMode(\"auto\") hook so it reads the same themeable token.",
+    "DO use all named sub-parts in order: Sheet (root) > SheetTrigger (opener) > SheetContent (panel) > SheetHeader > SheetTitle (required for a11y — maps to Radix DialogPrimitive.Title, announced as the accessible name) > optional SheetDescription > body content > SheetFooter. Never skip SheetTitle inside an open SheetContent.",
+    "DO control state explicitly with open + onOpenChange on Sheet root when you need to close programmatically (e.g. after form submit). Uncontrolled (no props) works for simple trigger-only cases but gives you no hook to reset form state on close.",
+    "DO use SheetTrigger asChild to wrap a Button or other interactive element — this avoids a nested <button> in the DOM. Never render a raw <button> as a direct child of SheetTrigger.",
+    "DO wrap a long/scrolling body in SheetBody (between SheetHeader and a pinned SheetFooter). It is the ring-safe scroll slot: a hand-rolled <div className='overflow-y-auto'> clips the 3px focus ring of a full-width Input/Select at the scroll edges — SheetBody insets the content so the ring never clips.",
+    "DO use SheetFooter (renders at the bottom via mt-auto, symmetric 16/24 padding, full-bleed top border) for primary/cancel action Buttons. Never float action Buttons inside the body — they will not stick to the panel bottom.",
+    "DON'T set showCloseButton={false} on SheetContent unless you provide your own SheetClose element; omitting both leaves users with no keyboard-accessible close path and breaks a11y.",
+    "DO set `modal={false}` on Sheet when the user must keep working on the page behind the open panel (edit a list while a detail panel stays open). Control `open` yourself: an outside press no longer closes it, so keep the ✕ or a footer close action. Escape closes it only while focus is inside the panel.",
+    "DON'T put a Sheet inside a Dialog (nested Radix portals conflict). If you need a slide-over triggered from within a modal, close the Dialog first, then open the Sheet."
+  ],
+  "useCases": [
+    "Filter/search panel: slide in from the right with filter FormFields (Select, `DatePicker range`, CheckboxGroup) that affect a DataTable — preferred over a Dialog because filters do not require confirmation and benefit from seeing the table behind the overlay.",
+    "Quick-edit drawer: open an entity's editable fields (e.g. invoice line items, account settings) without navigating away, with Save/Cancel in SheetFooter — use side='right' and keep the main page visible as context.",
+    "Detail peek panel: show read-only Descriptions / Timeline of a selected record (e.g. a journal entry or invoice) from a DataTable row click, using side='right' with showCloseButton={true}. Add responsive='auto' so the same panel becomes a bottom sheet on a phone instead of a 100%-wide slab.",
+    "Non-modal side panel: `modal={false}` keeps a list behind the sheet editable while the panel stays open (change order lines while their running total stays visible in the panel).",
+    "Mobile-first navigation drawer: side='left' sheet acting as a slide-in nav menu on small viewports when the AppShell Sidebar is hidden — triggered by a hamburger Button.",
+    "Step-by-step wizard side panel: multi-step form (Steps component inside SheetContent) for onboarding or import flows where full-page navigation would lose list context."
+  ]
+}

package/agent/components/Sidebar.json

@@ -0,0 +1,118 @@
+{
+  "example": "\n{`import { useState } from \"react\";\nimport { LayoutDashboard, FileText, Users, Shield, CreditCard, BookOpen } from \"lucide-react\";\nimport { Link } from \"react-router-dom\";\nimport { AppShell, createSidebarLink } from \"@godxjp/ui/layout\";\nimport { Sidebar, type SidebarSection } from \"@godxjp/ui/layout\";\nimport { Topbar, TopbarItem } from \"@godxjp/ui/layout\";\n\n// The WHOLE router integration: pass the element type, the library composes every row\n// (icon · label · badge · active · collapsed rail). Inertia: inertiaSidebarLink(Link) from\n// \"@godxjp/ui/inertia\". Next.js: createSidebarLink(Link).\nconst NavLink = createSidebarLink(Link, \"to\");\n\nconst sections: SidebarSection[] = [\n  {\n    label: \"Accounting\",\n    items: [\n      { id: \"dashboard\", label: \"Dashboard\", icon: LayoutDashboard, href: \"/dashboard\" },\n      {\n        id: \"ledger\",\n        label: \"Ledger\",\n        icon: BookOpen,\n        children: [\n          { id: \"journal\", label: \"Journal\", icon: FileText, href: \"/ledger/journal\" },\n          { id: \"chart-of-accounts\", label: \"Chart of Accounts\", icon: CreditCard, href: \"/ledger/coa\" },\n        ],\n      },\n    ],\n  },\n  {\n    label: \"Administration\",\n    items: [\n      { id: \"users\", label: \"Users\", icon: Users, href: \"/users\" },\n      { id: \"roles\", label: \"Roles\", icon: Shield, href: \"/roles\", disabled: true },\n    ],\n  },\n];\n\nexport default function Shell() {\n  const [activeId, setActiveId] = useState(\"dashboard\");\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <AppShell\n      sidebarCollapsed={collapsed}\n      sidebar={\n        <Sidebar\n          activeId={activeId}\n          collapsed={collapsed}\n          onSelect={setActiveId}\n          sections={sections}\n          linkComponent={NavLink}\n          product={{ name: \"CoreBooks\", role: \"Admin Console\", color: \"hsl(var(--primary))\" }}\n          onProductClick={() => {/* open entity switcher */}}\n          footer={\n            <div className=\"text-muted-foreground text-xs\">\n              <div className=\"text-foreground font-medium\">Satoshi Yamamoto</div>\n              <div>Online · Tokyo branch</div>\n            </div>\n          }\n        />\n      }\n      topbar={\n        <Topbar\n          start={\n            <>\n              {/* A bar cell is a TopbarItem, never a Button: a Button in a bar is a\n                  --control-height pill floating in a taller strip, with its own hover\n                  fill and its own focus ring. */}\n              <TopbarItem aria-label=\"メニュー\" onClick={() => setCollapsed((c) => !c)}>\n                <PanelLeft />\n              </TopbarItem>\n              <Logo mark=\"godx\" label=\"CoreBooks\" />\n            </>\n          }\n          end={<TopbarItem aria-label=\"検索\" onClick={() => {}}><Search /></TopbarItem>}\n        />\n      }\n    >\n      {/* page content */}\n    </AppShell>\n  );\n}`}\n",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "Sidebar",
+  "props": [
+    {
+      "description": "Tên khả truy cập của landmark điều hướng. Bắt buộc khi một tài liệu có nhiều hơn một `<nav>`.",
+      "name": "ariaLabel",
+      "type": "string"
+    },
+    {
+      "description": "The id of the currently active nav item. For group items, the parent is automatically highlighted when any descendant id matches.",
+      "name": "activeId",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Ordered list of nav sections. Each section has an optional string label and a required items array of SidebarItemProp. A row's count pill is `item.badge` (CONTENT ONLY — a number, a string, \"9+\"; never a <Badge> element, which would nest a pill inside the pill the row already draws) and its emphasis is `item.badgeTone`: \"neutral\" (default, the quiet unread pill) or \"destructive\" (the count is addressed to the user — an @mention, a DM, a failure waiting on them). A row's TRAILING GLYPH is a different slot: `item.trailingIcon` takes the COMPONENT (like `item.icon`, not an element) and renders a bare 16px mark at the row's inline end — the ⌃⌄ of a workspace switcher, a → on a row that leaves the app — with no pill, no background and no radius, hidden on the collapsed rail exactly like the badge.",
+      "name": "sections",
+      "required": true,
+      "type": "SidebarSectionProp[]"
+    },
+    {
+      "description": "Called with the item id when a leaf nav item is clicked. Not called for group triggers or disabled items.",
+      "name": "onSelect",
+      "type": "(id: string) => void"
+    },
+    {
+      "defaultValue": "false",
+      "description": "When true, renders the icon-only collapsed rail. Labels become Tooltips on hover; group items open a portaled flyout popover on click. Section labels are hidden.",
+      "name": "collapsed",
+      "type": "boolean"
+    },
+    {
+      "description": "Renders a product/app chip at the top of the sidebar (name, optional role subtitle, optional color swatch). Mutually exclusive with brand — brand takes precedence.",
+      "name": "product",
+      "type": "SidebarProductProp"
+    },
+    {
+      "description": "Click handler for the product chip button. Use to open an entity/workspace switcher sheet or dropdown.",
+      "name": "onProductClick",
+      "type": "() => void"
+    },
+    {
+      "description": "Custom brand slot rendered above the nav scroll area. When provided, the product chip is not rendered. PASS A FUNCTION and it is called with the EFFECTIVE collapsed value, which is what a plain node cannot see: AppShell reuses this same Sidebar for the mobile drawer and the drawer un-collapses the rows, so a lockup built from the consumer's own `collapsed` boolean renders glyph-only inside a full-width drawer. The workaround consumers reach for — a second hand-built Sidebar passed as AppShell's `mobileNav` — is exactly the override that switches off `railInDrawer`, silently dropping the `navRail` from mobile. This slot is APP scope (the product lockup); a PLATFORM switch does not go here.",
+      "name": "brand",
+      "type": "ReactNode | ((collapsed: boolean) => ReactNode)"
+    },
+    {
+      "description": "Slot pinned to the bottom of the sidebar below the scrollable nav area. Commonly used for user identity, online status, or a mode switch. PASS A FUNCTION for the same reason brand takes one, and it is the same reason twice: both slots sit INSIDE the collapsible rail, so both need the EFFECTIVE collapsed value, which a node built outside the component cannot see. Reading your own `collapsed` boolean renders a glyph-only footer inside AppShell's full-width drawer (the drawer un-collapses the rail); building a second Sidebar for AppShell's `mobileNav` is exactly the override that switches railInDrawer off; doing neither leaves the expanded footer to reflow inside a 64px rail (measured: a two-line identity block went 255x66 docked to 63x111 collapsed, wrapping the name over three lines). A plain ReactNode still works unchanged.",
+      "name": "footer",
+      "type": "ReactNode | ((collapsed: boolean) => ReactNode)"
+    },
+    {
+      "description": "THE framework-router contract. Supply only the link ELEMENT TYPE; the library keeps composing every row — icon slot, label, badge, data-active/aria-current, the icon-only collapsed rail and its tooltip name — and passes it to the link as SidebarLinkProp children. Applied to every row that carries an href: top-level leaves, submenu children, collapsed-rail leaves and collapsed flyout entries. Build it with createSidebarLink(Link, 'to') for React Router / TanStack, createSidebarLink(Link) or inertiaSidebarLink(Link) from @godxjp/ui/inertia for Inertia / Next.js.",
+      "name": "linkComponent",
+      "type": "SidebarLinkComponentProp"
+    },
+    {
+      "description": "DEPRECATED — use linkComponent, or asChild on SidebarItem. Legacy escape hatch that left row CONTENT to the caller, which is how a <Link>{item.label}</Link> silently dropped every icon and badge in production. Still supported and still wins over linkComponent; rowProps now also carries the library-composed children, so spreading rowProps (or rendering rowProps.children) restores the canonical row.",
+      "name": "renderItem",
+      "type": "(item: SidebarItemData, rowProps: SidebarRenderItemProp) => ReactNode"
+    },
+    {
+      "description": "Override the nav landmark's accessible name (defaults to a localized \"Main navigation\"). Required when more than one Sidebar renders at once (e.g. a docked sidebar + its mobile-drawer twin) — two nav landmarks sharing one name/role fail landmark-unique.",
+      "name": "aria-label",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "AppShell — the shell that hosts Sidebar in its sidebar slot and owns the sidebarCollapsed layout grid; always compose Sidebar inside AppShell, not standalone in a page.",
+    "Topbar — the horizontal bar that renders the collapse toggle (onToggleCollapsed) and its collapsed prop must mirror the sidebar's collapsed state.",
+    "PageContainer — used for page-level title/subtitle/extra/breadcrumb inside AppShell's children slot, not inside Sidebar."
+  ],
+  "rules": [
+    3,
+    6,
+    23,
+    31
+  ],
+  "storyPath": "layout/Sidebar.preview.tsx",
+  "subParts": [
+    "SidebarHeader",
+    "SidebarItem",
+    "SidebarSection"
+  ],
+  "tagline": "Data-driven vertical nav rail with collapsible submenu groups and a collapsed icon-only mode — never build nav manually with raw buttons.",
+  "usage": [
+    "DO: Define all nav items as a SidebarSectionProp[] data structure and pass it to sections — never hand-roll nav buttons alongside or instead of the Sidebar.",
+    "DO: Add children: SidebarItemProp[] to any SidebarItemProp to create a collapsible submenu group. The group auto-opens and highlights when activeId matches any descendant. The SAME field drives NavList (gh#815), so one grouped settings nav is one NavList and one <nav> landmark.",
+    "DO: Mirror the collapsed boolean between AppShell's sidebarCollapsed prop and Sidebar's collapsed prop — they must stay in sync so the shell layout grid adjusts correctly.",
+    "DO: Use the footer prop for user info or status — it is pinned below the scroll area and does not scroll away. Pass a FUNCTION `(collapsed) => node` whenever that content has to shrink on the rail: it is called with the EFFECTIVE collapsed value, so ONE Sidebar serves both the docked rail and AppShell's drawer. Returning null for a surface draws no footer chrome at all (no top border, no padding).",
+    "DO: Put a row's trailing disclosure mark in `item.trailingIcon`, never in `item.badge`. `badge` wraps whatever it is given in the `.sb-badge` count capsule — a chevron passed there measures 36x24 with a 24x24 SVG inside, beside a 16x16 leading icon in the same 32px row. `trailingIcon` takes the component (`trailingIcon: ChevronsUpDown`) and the rail pins it to the leading icon's 16px box with no surface of its own.",
+    "DO: Give every navigable item an `item.href` and let the library render it. A plain `href` becomes a real <a> (context-menu open-in-new-tab, middle-click); with `linkComponent` that same href drives your framework router's <Link>. Either way the link IS the row and the ONLY interactive element (no nested <button>). Never put a <button>/<a> inside a default row.",
+    "DO: Wire a framework router with `linkComponent` — `createSidebarLink(Link, 'to')` (React Router / TanStack), `createSidebarLink(Link)` (Next.js), or `inertiaSidebarLink(Link)` from `@godxjp/ui/inertia`. That is the WHOLE integration: you pass the element type, the library composes the row. It threads through leaves, submenu children, the collapsed rail and the collapsed flyout. When you compose rows by hand, the same contract is `<SidebarItem item={item} asChild><RouterLink to=… /></SidebarItem>` — write NO children; the library injects the icon, label and badge. (`RouterLink` here is YOUR router's link component; this library now exports a `Link` of its own — antd's Typography.Link — which takes `href`, not `to`.)",
+    "DON'T: Use `renderItem` in new code — it is DEPRECATED. It hands you a className + active state and leaves the row CONTENT to you, so `renderItem={(item) => <RouterLink href={…}>{item.label}</RouterLink>}` renders a row with NO icon and NO badge. That is the exact production regression that motivated `linkComponent`. If you must keep it, render `rowProps.children` (the library-composed row) instead of hand-writing `.sb-icon` / `.sb-label` spans, which are internal class names and not a public contract.",
+    "DO: Rely on route-synchronized group expansion — a group OPENS automatically whenever `activeId` moves to one of its children (e.g. after a deep-link navigation), revealing the newly-active child; users can still collapse/expand manually.",
+    "DO: Theme the nav ICON and the row/label SEPARATELY with tokens — the icon reads `--sidebar-nav-icon-foreground` (+ `-hover-`/`-active-`/`-disabled-` variants) and the row/label reads `--sidebar-nav-item-foreground` (+ `-hover-`/`-disabled-`). Resting defaults are unchanged (both = `hsl(var(--muted-foreground))`, hover = `hsl(var(--foreground))`; the ACTIVE row is its own group, see below), so setting `--sidebar-nav-icon-foreground: hsl(var(--foreground))` in your theme is all it takes to get canonical darker 16px icons beside muted labels. NEVER write a page-local `.sb-nav-item svg { color: … }` rule and never re-tint `--muted-foreground` globally to fix sidebar icons.",
+    "DO: Give every RAIL item an `icon`. It is OPTIONAL on SidebarItemProp (gh#815 — NavList has no collapsed rail and routinely mixes rows), but the canonical rail collapses to icon-only, so a row without one renders an EMPTY 16px slot: the geometry and the label column survive, and the collapsed rail reads as a hole.",
+    "DO: Distinguish an UNREAD count from one ADDRESSED TO THE USER with `item.badgeTone` — 'neutral' (the default, the pill unchanged) versus 'destructive' for an @mention, a direct message or a failure awaiting them. It emits `data-tone=\"destructive\"` on the existing `.sb-badge` and swaps two colour tokens (`--sidebar-badge-destructive-background` / `-foreground`); the pill's min-width, radius, inline pad and font size are shared by both tones, so mention rows and unread rows stay aligned in the same column. Retune all four `--sidebar-badge-*` knobs in your theme rather than styling the pill.",
+    "DON'T: Reach for `item.badge` to place a GLYPH (a chevron, an arrow, a status dot). That slot is a COUNT capsule — 9999px radius, `hsl(var(--secondary))` fill, sized for digits — and it does not pin the SVG, so a lucide glyph renders at its 24px default inside a 36x24 grey pill. The row's trailing glyph slot is `item.trailingIcon`.",
+    "DON'T: Put a `<Badge>` (or anything else that draws its own pill) inside `item.badge` to colour a count — the row ALREADY wraps whatever you pass in a `.sb-badge` pill, so you get two nested pills with two borders (measured: a 37.11x19.14 `.sb-badge` wrapping a 25.11x19.14 `<Badge>`). Pass the CONTENT only (`badge: 3`, `badge: '9+'`) and say what it MEANS with `badgeTone`.",
+    "DON'T: Change icon SIZE or row geometry through these colour knobs — icon size stays `--sidebar-nav-icon-size` (16px) and row geometry stays `--sidebar-nav-item-height` / `--sidebar-nav-item-gap` / `--sidebar-nav-item-padding-x`. The active row's fill/label keep `--sidebar-item-active-background` / `--sidebar-item-active-foreground` — and since gh#651 BOTH nav depths default to the brand, not to neutral grey: the level-1 fill is `--primary` composited at `--sidebar-item-active-background-alpha` (12%, capped at 16% — above that the label drops under WCAG 2.2 SC 1.4.3) and the label is `hsl(var(--primary))` at level 1 and level 2 alike. If your theme was setting `--sidebar-item-active-background: hsl(var(--primary) / 0.12)` and `--sidebar-item-active-foreground: hsl(var(--primary))` to get that look, DELETE the block — it is the default now. The level-2 label knob used to be spelled `--sidebar-item-active-color`; that name is gone with no alias.",
+    "DON'T: Manage collapse state inside the Sidebar — it is stateless. Hoist the boolean to your shell/page state and pass it down via both AppShell.sidebarCollapsed and Sidebar.collapsed.",
+    "DON'T: Nest children more than one level deep — only top-level items can have children; grandchild items are not rendered.",
+    "DON'T: Put a PLATFORM switch in the sidebar — not an `OrgSwitcher`, not an app switcher, neither as a row nor stacked into `brand` under the product lockup. The sidebar is APP scope (this app's own sections); which organization or which app you are in survives changing app and belongs to `AppShell`'s `navRail` or to the topbar. Stacking a second lockup under the first also gives the sidebar header a different height from the topbar, which is the visible symptom people report as \"the two sides do not line up\".",
+    "DON'T: Build a second Sidebar by hand for `AppShell.mobileNav` just to un-collapse it — the drawer already un-collapses the rows on its own (`NavSurface`), and `brand` takes a function so the lockup follows too. An explicit `mobileNav` also turns off the drawer's rail strip, so a `navRail` you passed stops appearing on mobile."
+  ],
+  "useCases": [
+    "Admin application shell nav with grouped sections (e.g. Operations / Fulfillment / Administration) where the sidebar can be collapsed to an icon rail for more content space.",
+    "Accounting app with a collapsible 'Ledger' group containing Journal, Chart of Accounts, and Period Close sub-pages — activeId reflects the current sub-page and the group stays open automatically.",
+    "Multi-tenant SaaS where onProductClick opens an entity/legal-entity switcher sheet and product.role shows the active tenant name beneath the product logo.",
+    "Any app using AppShell where navigation must degrade gracefully to an icon-only rail on narrow viewports or via a user toggle in the Topbar.",
+    "Apps with infrequent-access admin pages (Users, Roles, Password) grouped in a dedicated section that appears below primary operations sections.",
+    "A chat / messaging rail listing channels, where most rows carry a neutral unread count and only the channels that @mentioned the user carry `badgeTone: 'destructive'` — the rail answers \"does anything need me personally?\" at a glance, without a second pill or a hand-styled dot."
+  ]
+}

package/agent/components/Skeleton.json

@@ -0,0 +1,57 @@
+{
+  "example": "import { Skeleton } from \"@godxjp/ui/feedback\";\n\n<Skeleton className=\"h-6 w-48\" />\n\n// The same component is the antd namespace:\n<Skeleton.Button size=\"sm\" />",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "Skeleton",
+  "props": [
+    {
+      "description": "Size and layout classes for the block.",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Swap the resting pulse for a travelling sheen (Ant Design's `active`). The block already pulses without it — `active` picks the louder of the two motions, it does not turn motion on. Both stop under prefers-reduced-motion.",
+      "name": "active",
+      "type": "boolean"
+    },
+    {
+      "description": "Pass `false` to render `children` INSTEAD of the placeholder, so a call site can swap without a ternary. Omitting it keeps the placeholder (Ant Design's `loading || !('loading' in props)`).",
+      "name": "loading",
+      "type": "boolean"
+    }
+  ],
+  "related": [
+    "SkeletonArticle",
+    "SkeletonRows",
+    "SkeletonTable",
+    "SkeletonStat",
+    "SkeletonButton",
+    "SkeletonInput",
+    "SkeletonAvatar",
+    "SkeletonNode",
+    "SkeletonImage",
+    "Activity — the ambient 'working…' mark. Skeleton is a SHAPE standing in for content that has not arrived; Activity is motion beside content that is already there."
+  ],
+  "rules": [
+    3,
+    31
+  ],
+  "storyPath": "feedback/Skeleton.stories.tsx",
+  "subParts": [
+    "SkeletonDetail",
+    "SkeletonStat"
+  ],
+  "tagline": "Base pulsing skeleton block, and the namespace the shaped presets hang off (Skeleton.Avatar / .Button / .Input / .Node / .Image / .Article).",
+  "usage": [
+    "DO use Skeleton for a custom block when SkeletonRows/Table/Stat/Article do not match the final layout.",
+    "DO reach for a shaped preset before sizing a bare block by hand: SkeletonButton, SkeletonInput, SkeletonAvatar, SkeletonNode and SkeletonImage already carry the box of the control they stand in for, from the --control-height tier.",
+    "DON'T use a spinner overlay for skeletonable page content.",
+    "DON'T reuse Skeleton as an ambient 'something is happening' mark — it hard-codes aria-busy + aria-live because it means CONTENT IS LOADING. Use Activity for ambient motion."
+  ],
+  "useCases": [
+    "Single loading line",
+    "Custom card media placeholder",
+    "Inline metadata placeholder"
+  ]
+}