@godxjp/ui 31.31.7 → 32.0.0

package/agent/components/AppLauncher.json

@@ -56,7 +56,7 @@
     },
     {
       "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.",
+      "description": "The BOX the trigger takes — the same split `AppSettingPicker menu={false}` 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\""
     },
@@ -93,7 +93,7 @@
     "TopbarItem — the bar cell the trigger is built from; use it directly for a one-off bar control."
   ],
   "rules": [],
-  "storyPath": "layout/AppLauncher.stories.tsx",
+  "storyPath": "layout/app-launcher.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.",

package/agent/components/AppProvider.json

@@ -5,10 +5,14 @@
   "name": "AppProvider",
   "props": [
     {
-      "defaultValue": "\"vi\"",
-      "description": "Initial locale.",
+      "description": "Initial locale when nothing is stored. Resolution, first match wins: this prop (when registered — `de-AT` is served by a registered `de`) → `<html lang>` (client only) → the preset's `defaultLocale` → `en`. Never `navigator.language` (the server cannot see it, so SSR would hydrate differently). An SSR host passes the request's locale here. v32: the default was `vi`.",
       "name": "defaultLocale",
-      "type": "\"ja\" | \"en\" | \"vi\""
+      "type": "string (BCP-47)"
+    },
+    {
+      "description": "Product defaults the host opts into — `import { godxPreset } from \"@godxjp/ui/themes/godx\"` (pair it with `@godxjp/ui/themes/godx.css` after the base stylesheet). Its `defaultLocale` and `timeZone` fill only what the props leave unset, its `brandMark` is what an `AuthIdentity` with no `brand` draws, and its `name` is written to `<html data-preset>`. Omit for the neutral defaults (ink primary, `en`, no product mark).",
+      "name": "preset",
+      "type": "AppPreset"
     },
     {
       "defaultValue": "\"browser\"",
@@ -72,31 +76,35 @@
     }
   ],
   "related": [
-    "LocalePicker — the language-selector control that reads/writes AppProvider locale context automatically when used as a zero-prop child. Prefer LocalePicker over calling setLocale from useAppContext() directly in UI.",
-    "TimezonePicker — the timezone-selector control; inherits `timezoneOptions` from AppProvider context when its own `options` prop is omitted. Both pickers require AppProvider to be in the tree unless controlled props are passed.",
+    "AppSettingPicker — `kind=\"locale\"` is the language selector that reads/writes AppProvider locale context automatically when used with no value props. Prefer it over calling setLocale from useAppContext() directly in UI.",
+    "AppSettingPicker `kind=\"timezone\"` — the timezone selector; inherits `timezoneOptions` from AppProvider context. Every kind needs AppProvider in the tree unless value + onValueChange are passed.",
     "formatDate — the MANDATORY date/time formatter that reads locale, timezone, timeFormat, and dateFormat from AppProvider context. Do NOT call date-fns or Intl.DateTimeFormat directly; formatDate is the single source of truth for display.",
-    "AppShell — the top-level application shell that composes AppProvider, AppShell, Sidebar, and Topbar into a single ready-to-use layout. If your project uses AppShell, AppProvider is already mounted inside it — do not add a second one.",
+    "AppShell — the authenticated layout (sidebar + topbar + main). It does NOT mount AppProvider: mount AppProvider once at the application root, ABOVE AppShell (and above any CenteredShell/MobileShell), so every shell and page reads the same context.",
     "OverlayPortalProvider — the other root-level provider, and the one to reach for when this library is mounted inside a SHADOW ROOT. Every overlay here (Popover, Dialog, Sheet, Tooltip, DropdownMenu, HoverCard) portals to `document.body` by default, which is correct on an ordinary page and wrong in a shadow root: the panel lands outside the tree carrying the stylesheet and renders with none of it — measured on an embedded bar as border 0, radius 0, a transparent background, and the anchor maths 40px off. `<OverlayPortalProvider container={shadowRoot}>` moves all of them at once; a per-component prop cannot, because a component that owns its own overlay (AppLauncher) is unreachable from the outside."
   ],
   "rules": [
     5
   ],
-  "storyPath": "app/AppProvider.stories.tsx",
+  "storyPath": "providers/app-provider.tsx",
+  "subParts": [
+    "AppPresetContext"
+  ],
   "tagline": "Root locale/timezone/date-time context — wrap the app ONCE. All pickers + formatDate read from it. Import from @godxjp/ui/app.",
   "usage": [
+    "`AppPresetContext` is the React context AppProvider's `preset` prop fills; read it with `useAppPreset()` (the active `AppPreset`, or undefined for the neutral defaults). Don't provide it yourself — pass `preset` to AppProvider.",
     "DO drive the four theme axes (theme / brand / density / fontSize) from AppProvider props ONLY — they are written to <html data-*> and read by every component via tokens. Never hand-set --font-size-base or .ui-density-* in app CSS; that bypasses persistence + the runtime switchers. For runtime switching mount `<AppSettingPicker kind=\"density\" | \"fontSize\" | \"theme\" | \"brand\" >` or call setDensity/setFontSize/setTheme/setBrand from useAppContext().",
-    "DO mount AppProvider ONCE at the application root (e.g. in app.tsx or the Inertia layout), wrapping ALL children — every godx-ui picker (LocalePicker, TimezonePicker, DateFormatPicker, TimeFormatPicker), every formatDate call, and the Toaster all rely on the single context it provides. Nesting two AppProviders creates split contexts; inner pickers silently read the wrong one.",
-    "DO NOT omit AppProvider and then try to use LocalePicker, TimezonePicker, or formatDate standalone — useAppContext() throws 'useAppContext must be used within <AppProvider>' at runtime. The only exception is using those pickers in fully controlled mode (value + onChange) which reads useOptionalAppContext() and returns null safely.",
+    "DO mount AppProvider ONCE at the application root (e.g. in app.tsx or the Inertia layout), wrapping ALL children — every `AppSettingPicker` (kind=\"locale\" / \"timezone\" / \"dateFormat\" / \"timeFormat\"), every formatDate call, and the Toaster all rely on the single context it provides. Nesting two AppProviders creates split contexts; inner pickers silently read the wrong one.",
+    "DO NOT omit AppProvider and then try to use AppSettingPicker or formatDate standalone — useAppContext() throws 'useAppContext must be used within <AppProvider>' at runtime. The only exception is using those pickers in fully controlled mode (value + onChange) which reads useOptionalAppContext() and returns null safely.",
     "DO use `persist={false}` on AppProvider for isolated tests and standalone settings forms where localStorage must not be read or written. With the default `persist={true}` the provider reads localStorage key `godxjp.app` on mount (after first render), so initial state may differ between SSR and client.",
     "DO NOT reach for `persist={false}` because the SERVER owns the locale — pass the axes the BROWSER owns instead: `persist={[\"theme\", \"brand\", \"density\", \"fontSize\", \"scaling\"]}`. Storage is read after the props, so a stored `locale` overrides the one the server just resolved; turning persistence off wholesale fixes that and silently takes the viewer's theme with it, which is how a hosted app shipped a theme toggle that reset on every reload.",
     "DO set `defaultTimezone='system'` together with `systemTimezone={serverTimezone}` when your backend knows the legal entity's canonical timezone (e.g. 'Asia/Ho_Chi_Minh'). Use `defaultTimezone='browser'` (the default) only when you want the user's browser clock. Do NOT pass a raw IANA string to `defaultTimezone` if the user may be in a different zone — use the named aliases.",
     "DO wire `onLocaleChange`, `onTimezoneChange`, `onTimeFormatChange`, `onDateFormatChange` to persist changes server-side (e.g. patch user profile via Inertia router) in addition to the automatic localStorage write. These callbacks fire after state is set, so the new value is already reflected in context.",
     "DO set `emitFieldNames` on AppProvider when the app is driven by screen automation (RPA) or posts native forms — every control under a FormField then carries a real `name` taken from the field key, and legacy automation that addressed controls by `name` keeps working after a rewrite. Leave it off (the default) otherwise: it changes what a native submit sends. The `data-field` attribute is emitted either way, so e2e selectors do not depend on this flag.",
-    "DO restrict the timezone dropdown by passing `timezoneOptions={APP_TIMEZONE_PRESET}` (an exported constant) to AppProvider — all TimezonePicker instances that omit their own `options` prop will inherit this restricted list automatically from context. Without it, TimezonePicker renders the full IANA list (~600 entries)."
+    "DO restrict the timezone dropdown by passing `timezoneOptions={APP_TIMEZONE_PRESET}` (an exported constant) to AppProvider — every `AppSettingPicker kind=\"timezone\"` inherits this restricted list from context. Without it the picker offers the full IANA list (~600 entries)."
   ],
   "useCases": [
     "App bootstrap in a multi-locale SaaS admin (ja/en/vi) — mount AppProvider at the root with the tenant's preferred locale and IANA timezone so every DataTable date column, every formatDate call, and every picker renders consistently in the user's locale without any per-component configuration.",
-    "User settings page — render LocalePicker, TimezonePicker, DateFormatPicker, and TimeFormatPicker as zero-prop children inside the existing AppProvider; each picker reads and writes context automatically. Wire `onLocaleChange` to an Inertia form submit to persist the change to the server profile.",
+    "User settings page — render `<AppSettingPicker kind=\"locale\" />`, `kind=\"timezone\"`, `kind=\"dateFormat\"` and `kind=\"timeFormat\"` inside the existing AppProvider; each reads and writes context automatically. Wire `onLocaleChange` to an Inertia form submit to persist the change to the server profile.",
     "Server-rendered Inertia app with SSR hydration — pass `defaultTimezone='system'` and `systemTimezone={sharedProps.timezone}` (injected via HandleInertiaRequests) so the initial render is timezone-deterministic and avoids hydration mismatches caused by browser-timezone detection.",
     "Multi-entity accounting dashboard — use `timezoneOptions` to restrict the picker to the legal entity's permissible zones (e.g. Southeast Asian IANA ids only), preventing users from accidentally switching to an out-of-scope timezone that would misrepresent transaction timestamps.",
     "Isolated preview / Storybook story — wrap a single component in `<AppProvider persist={false} defaultLocale='en'>` to give it a stable context without polluting localStorage between stories.",

package/agent/components/AppSettingPicker.json

@@ -6,13 +6,20 @@
     "DateFormatPicker",
     "TimeFormatPicker",
     "ThemePicker",
-    "DensityPicker"
+    "DensityPicker",
+    "AppSettingToggle"
   ],
   "example": "{`// Uncontrolled — AppProvider manages and persists every setting\nimport { AppProvider } from \"@godxjp/ui/app\";\nimport { AppSettingPicker } from \"@godxjp/ui/navigation\";\n\nexport function SettingsPanel() {\n  return (\n    <AppProvider defaultLocale=\"ja\" defaultTimezone=\"Asia/Tokyo\">\n      <AppSettingPicker kind=\"locale\" />\n      <AppSettingPicker kind=\"timezone\" />\n      <AppSettingPicker kind=\"dateFormat\" />\n      <AppSettingPicker kind=\"timeFormat\" />\n    </AppProvider>\n  );\n}\n\n// Controlled — no AppProvider required\nimport { useState } from \"react\";\nimport { AppSettingPicker } from \"@godxjp/ui/navigation\";\n\nexport function LocaleField() {\n  const [locale, setLocale] = useState(\"en\");\n  return <AppSettingPicker kind=\"locale\" value={locale} onValueChange={setLocale} />;\n}\n\n// Topbar locale switcher (globe) — a cell OF the bar, no CSS overrides\nimport { Topbar } from \"@godxjp/ui/layout\";\nimport { AppSettingPicker } from \"@godxjp/ui/navigation\";\n\nexport function TopbarLocale() {\n  // \"bar\" inside a Topbar slot; \"icon\" everywhere else.\n  return <Topbar end={<AppSettingPicker kind=\"locale\" appearance=\"bar\" />} />;\n}`}",
   "group": "navigation",
   "importPath": "@godxjp/ui/navigation",
   "name": "AppSettingPicker",
   "props": [
+    {
+      "defaultValue": "true",
+      "description": "true (default): open-then-choose from a menu. false: ONE button that steps the setting to its NEXT value on each tap and shows that value as its glyph (theme Sun/Moon/Monitor, density rows, fontSize A-marks, timeFormat text) — only for the closed, short kinds \"theme\" | \"density\" | \"fontSize\" | \"timeFormat\" (a 400-entry IANA list is a menu, not a cycle). Same binding contract and the same option order as the menu, read from the same constants. Its `appearance` is then \"bar\" (default — a full-height TopbarItem cell) | \"icon\" (a square ghost Button off-bar). The accessible name carries the setting AND the current value (\"Theme: Dark\"). v32 folded `AppSettingToggle` in here.",
+      "name": "menu",
+      "type": "boolean"
+    },
     {
       "description": "Which AppProvider setting this picker reads and writes. Determines the option list, icon, trigger width, and the context value/setter used. The theme-axis kinds (theme/brand/density/fontSize) write <html data-*>; brand's first option opts out (null → app token).",
       "name": "kind",
@@ -66,9 +73,14 @@
     6,
     23
   ],
-  "storyPath": "navigation/AppSettingPicker.stories.tsx",
+  "storyPath": "navigation/app-setting-picker.tsx",
   "tagline": "One provider-bound Select for a single AppProvider setting, chosen by `kind` (locale | timezone | dateFormat | timeFormat | theme | brand | density | fontSize) — covers locale/format AND the four theme axes. Throws if used without AppProvider AND without controlled value+onValueChange.",
   "usage": [
+    "CYCLE (menu={false}): DO: Reach for it in a top bar when the value set is closed and short — <AppSettingPicker menu={false} kind=\"theme\" /> is the light/dark/system switcher, and a dropdown for three values is a menu nobody wanted to open.",
+    "CYCLE (menu={false}): DO: Trust the accessible name — it always names BOTH the setting and the current value (\"Theme: Dark\"), because the glyph is the only visible state. Never override it with a kind-only aria-label.",
+    "CYCLE (menu={false}): DON'T: Set a height, a radius or a background on it in a bar. The bar cell shape is TopbarItem's, and any utility you add outranks @layer components and re-creates the floating-pill defect.",
+    "CYCLE (menu={false}): DON'T: Reach for it for locale, timezone, dateFormat or brand — those are not in `kind` on purpose. Use AppSettingPicker.",
+    "CYCLE (menu={false}): DON'T: Hand-roll a theme button with useAppContext + a Sun/Moon ternary — that loses the localized value-bearing name, the shared option order, and the bar-cell shape.",
     "DO: Mount inside <AppProvider> for zero-config use — the picker reads and writes the context value named by kind, no value/onValueChange needed.",
     "DO: Use controlled mode (value + onValueChange) when managing state outside AppProvider, e.g. a standalone settings form or a Storybook story. Both are required together in this mode.",
     "DO NOT: Render without AppProvider and without both controlled props — it throws 'AppSettingPicker requires <AppProvider> or controlled value + onValueChange'.",
@@ -78,6 +90,10 @@
     "DON'T hand-roll a locale/timezone/format Select — AppSettingPicker already composes Select + the right icon + translated, context-wired options. There is no separate LocalePicker/TimezonePicker/DateFormatPicker/TimeFormatPicker anymore; use kind."
   ],
   "useCases": [
+    "CYCLE (menu={false}): Topbar light/dark/system switcher: <AppSettingPicker menu={false} kind=\"theme\" /> in a Topbar `end` slot, beside the other TopbarItem cells.",
+    "CYCLE (menu={false}): Density or font-size step-through in an admin bar, for users who resize the grid all day: <AppSettingPicker menu={false} kind=\"density\" />.",
+    "CYCLE (menu={false}): Clock-format flip (24h/12h) next to a schedule view: <AppSettingPicker menu={false} kind=\"timeFormat\" /> — the only kind that shows its value as text, since no glyph can say \"24-hour\".",
+    "CYCLE (menu={false}): Settings row outside a bar: <AppSettingPicker menu={false} kind=\"theme\" appearance=\"icon\" /> beside its label.",
     "App-shell top-nav language switcher: <AppSettingPicker kind=\"locale\" /> under AppProvider, persisting to localStorage with no extra state.",
     "Topbar locale switcher (globe): <AppSettingPicker kind=\"locale\" appearance=\"bar\" /> in a Topbar `end` slot — a CELL of the bar: full bar height, squared to --topbar-item-radius, so its hover surface matches the TopbarItem beside it. appearance=\"icon\" is the same structural drops shaped as a CONTROL, for a toolbar or card header; in a taller bar it leaves a --control-height pill floating mid-strip and reads as a foreign control family. This line said \"icon\" while the prop doc said \"bar\", and a consumer duly shipped the pill.",
     "Auth-footer locale switch: <AppSettingPicker kind=\"locale\" appearance=\"labeled\" compact /> inside an <AuthFooter locale={…}> slot — the readable language name at the small control tier, hugging its value.",

package/agent/components/AppShell.json

@@ -127,15 +127,14 @@
     }
   ],
   "related": [
-    "AppShell — opinionated wrapper that composes AppShell + a frozen default Topbar in three props (menu, children, breadcrumb). Use AppShell for quick scaffolding when the default GodX product chip and no-op search/notification handlers are acceptable; switch to AppShell directly the moment you need a custom entity switcher, real onSearchOpen, user slot, or any topbar configuration.",
     "Sidebar — the canonical node to pass as AppShell's `sidebar` prop; owns activeId, collapsible submenu groups, collapsed icon-only mode, and section labels. Never hand-roll a nav list inside the sidebar slot.",
-    "Topbar — the structured topbar component to pass to AppShell's `topbar` prop when you need live product/project chip switchers, search, notifications, sidebar toggle, user avatar, or rightSlot extras. A custom `topbar` replaces the DEFAULT bar layout, so `topbarLeft`/`topbarRight` are ignored — but `logo` is not: the shell always renders it, and `topbarSpan` decides whether it lands in the bar or at the sidebar's head.",
+    "Topbar — the bar to pass to AppShell's `topbar` prop when it needs live controls: compose a switcher, search, notifications or the user avatar into its `start` / `center` / `end` slots. A custom `topbar` replaces the DEFAULT bar layout, so `topbarLeft`/`topbarRight` are ignored — but `logo` is not: the shell always renders it, and `topbarSpan` decides whether it lands in the bar or at the sidebar's head.",
     "PageContainer — the mandatory direct child inside AppShell's `children` for every page; provides title, subtitle, extra actions, breadcrumb, footer, variant (flush/narrow/ghost), and density. Never render raw content directly as AppShell's child without a PageContainer wrapper."
   ],
   "rules": [
     23
   ],
-  "storyPath": "layout/AppShell.stories.tsx",
+  "storyPath": "layout/app-shell.tsx",
   "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer.",
   "usage": [
     "useAppShellNavigationMode() returns drawer/docked at the same 56.25rem boundary as AppShell. The root also publishes data-navigation. Use this instead of a consumer media query.",
@@ -143,7 +142,7 @@
     "DO rely on AppShell's OWNED mobile drawer at or below 900px (NOT the Tailwind `lg` 1024px step — the shipped media query is `width <= 56.25rem`): it renders a hamburger trigger in the topbar and a focus-trapped Sheet (Esc + overlay close, focus returns to the trigger). `mobileNav` defaults to the `sidebar` node, so the same nav is reachable on mobile with no wiring — never hide the sidebar without providing this. Pass a tailored `mobileNav`, or `mobileNav={null}` only when navigation lives elsewhere (e.g. a bottom bar).",
     "DO set `responsiveNavigation=\"docked\"` only when the approved product contract retains its sidebar below 900px. AppShell keeps the same sidebar/footer/active navigation in a token-sized grid track and removes the redundant drawer trigger; never reproduce this with consumer media queries.",
     "DO let the drawer nav own its own inset: AppShell renders `mobileNav` in a Sheet body whose inline padding is the `--app-shell-mobile-nav-inset` token (near-zero by default) instead of the generic 24px sheet chrome inset, so a <Sidebar> in the drawer is not double-padded (its own --sidebar-nav-scroll-padding already insets each row). If a custom `mobileNav` node needs the full chrome inset, set `--app-shell-mobile-nav-inset: var(--space-6)` in the service theme — never patch the drawer with a `[data-slot='sheet-body']` selector in app CSS.",
-    "DO use the auto-built topbar rail (logo / topbarLeft / topbarRight) for simple shells. Pass a fully configured <Topbar> to the `topbar` prop when you need live handlers (entity switcher via productMenu, search, notifications, user avatar) — `topbarLeft`/`topbarRight` are then ignored (they are slots of the DEFAULT bar layout, and a custom `topbar` IS replacing that layout; a dev-mode warning names them). `logo` is NOT one of them: it is always rendered, because brand identity belongs to the frame rather than to the bar's contents. Two repos passed both for months and got no logo at all — no error, no warning, and a bar that still looked right because it had other content.",
+    "DO use the auto-built topbar rail (logo / topbarLeft / topbarRight) for simple shells. Pass a fully configured <Topbar start={…} center={…} end={…}> to the `topbar` prop when you need live controls (an entity switcher, search, notifications, the user avatar) — Topbar has those three slots and no per-control props — `topbarLeft`/`topbarRight` are then ignored (they are slots of the DEFAULT bar layout, and a custom `topbar` IS replacing that layout; a dev-mode warning names them). `logo` is NOT one of them: it is always rendered, because brand identity belongs to the frame rather than to the bar's contents. Two repos passed both for months and got no logo at all — no error, no warning, and a bar that still looked right because it had other content.",
     "DO pass `logo` and let the shell place it — do NOT put the lockup in `Sidebar`'s `brand` slot or hand-position it in a `Topbar` slot. THE TOP-LEFT CORNER BELONGS TO WHOEVER `topbarSpan` SAYS: under `content` the rail runs the full window height and the brand sits at the sidebar's head, aligned to that track; under `full` the bar runs edge to edge and the brand goes in the bar with the rest of the space-level chrome. Placing it yourself pins it to one of those answers, and the axis then moves the rest of the shell out from under it (measured on a shipped consumer: the logo floating in the content column at x=280, indented 24px past the rail it should have sat above).",
     "DO give a wide brand lockup a narrow-bar answer with `logoCompact` instead of cropping your own artwork in the app: `<AppShell topbarSpan=\"full\" logo={<FullLockup />} logoCompact={<MarkOnly />} />` swaps the NODE below the `sm` step, which is the only way to change a `viewBox` (no stylesheet can set an attribute). Without it the brand cell still gives room back — it is capped at --app-shell-brand-compact-max-inline-size below that step and cropped from the inline-end — where before it kept its intrinsic width at every viewport: measured with a 6:1 lockup at 390px, brand 143.7px, `.ui-topbar` 150.3px, `.ui-topbar-start` width 0 and the end cluster's last cell painting at x=384.8 on a 390px viewport (gh#728).",
     "DO build a chat / mail / IDE shell by omitting ALL FOUR bar slots (`topbar`, `topbarLeft`, `topbarRight`, `logo`) — a shell whose PAGE owns the top row. AppShell then renders no `<header class='app-topbar'>` and marks its root `data-topbar='none'`, so the bar's grid row collapses to zero and the page header IS the first row of chrome. Keeping an empty bar instead costs a fixed `--app-shell-bar-height` band plus its border and card background, stacking a second row of chrome (~48px + the page header) over exactly the region a transcript or an editor needs most. The mobile drawer survives: at or below 900px the header returns carrying the hamburger alone.",
@@ -164,6 +163,6 @@
     "App-level footer (e.g. version/build info, compliance notice): pass a <footer> node to AppShell's `footer` prop — it renders outside `<main>` so it stays pinned below the scroll area.",
     "Rapid prototype or internal tool where you want a branded shell with minimal topbar: skip the `topbar` prop entirely and use `logo`, `topbarLeft`, `topbarRight` to build the rail declaratively without instantiating <Topbar>.",
     "Breadcrumb-aware shell: pass a <Breadcrumb items={…}> node to AppShell's `breadcrumb` prop so the breadcrumb strip appears above all page content without each page having to render it separately.",
-    "Chat / mail / IDE shell: a channel rail in `sidebar`, no bar slots at all, and a <PageContainer fill toolbar={…} footer={<Composer/>} stickyFooter> as children — the page's own header is the top row and the shell reserves no band above it, while the 900px drawer still reaches the channel list."
+    "Chat / mail / IDE shell: a channel rail in `sidebar`, no bar slots at all, and a <PageContainer fill toolbar={…} footer={<ChatComposer />} stickyFooter> (ChatComposer from @godxjp/chat) as children — the page's own header is the top row and the shell reserves no band above it, while the 900px drawer still reaches the channel list."
   ]
 }

package/agent/components/AreaChart.json

@@ -106,7 +106,6 @@
     "BarChart — discrete category comparison."
   ],
   "rules": [],
-  "storyPath": "charts/AreaChart.stories.tsx",
   "tagline": "Magnitude over an ordered category axis — overlay or `stacked` areas, optional `curved` smoothing, localized formatting + text alternative. Data-visualization graph / plot.",
   "usage": [
     "DO import from the charts entry: `import { AreaChart } from \"@godxjp/ui/charts\";` (recharts optional peer required).",

package/agent/components/AspectRatio.json

@@ -24,8 +24,8 @@
     2,
     3
   ],
-  "storyPath": "layout/AspectRatio.stories.tsx",
-  "tagline": "Radix AspectRatio wrapper for stable media and preview frames.",
+  "storyPath": "layout/aspect-ratio.tsx",
+  "tagline": "Fixed-ratio box (CSS aspect-ratio) for stable media and preview frames.",
   "usage": [
     "DO use AspectRatio for media, maps, charts, or previews that must not jump during load.",
     "DON'T use it for unconstrained text content."

package/agent/components/Attachments.json

@@ -1,8 +1,8 @@
 {
   "docPath": "data-entry/attachments.tsx",
-  "example": "import { Attachments } from \"@godxjp/ui/data-entry\";\n\n<Attachments\n  items={files}\n  onChange={({ fileList }) => setFiles(fileList)}\n  overflow=\"scrollX\"\n  maxCount={5}\n/>",
+  "example": "import { Attachments } from \"@godxjp/chat\";\n\n<Attachments\n  items={files}\n  onChange={({ fileList }) => setFiles(fileList)}\n  overflow=\"scrollX\"\n  maxCount={5}\n/>",
   "group": "data-entry",
-  "importPath": "@godxjp/ui/data-entry",
+  "importPath": "@godxjp/chat",
   "name": "Attachments",
   "props": [
     {
@@ -87,7 +87,7 @@
     44,
     45
   ],
-  "storyPath": "data-entry/Attachments.stories.tsx",
+  "storyPath": "data-entry/attachments.tsx",
   "tagline": "The chat-surface attachment collection (Ant Design X Attachments): file cards, inline placeholder, optional full-screen drop target, and ref.select/ref.upload — inherits antd Upload props but names the list `items`.",
   "usage": [
     "DO keep antd field names on each item (`thumbUrl`, `originFileObj`, `uid`) — an Ant X call site should compile unchanged.",

package/agent/components/AuthAccountSummary.json

@@ -50,7 +50,7 @@
   "rules": [
     45
   ],
-  "storyPath": "layout/AuthAccountSummary.stories.tsx",
+  "storyPath": "layout/auth-account-summary.tsx",
   "tagline": "Compact signed-in account row for hosted auth: avatar fallback, authoritative email and switch action.",
   "usage": [
     "Pass only the authoritative signed-in email; AuthAccountSummary never fetches or invents identity data.",

package/agent/components/AuthDivider.json

@@ -23,7 +23,7 @@
     44,
     45
   ],
-  "storyPath": "layout/AuthDivider.stories.tsx",
+  "storyPath": "layout/auth-divider.tsx",
   "tagline": "The auth-scoped PRESET over `Separator label` — a localized conjunction between two equal rules.",
   "usage": [
     "DO use AuthDivider only INSIDE an auth form. It is a thin preset over `<Separator label>`: it re-points the --separator-* knobs at the --auth-shell-divider-* layer (the 11px auth micro-scale, the auth rule/label colours), so using it elsewhere drags auth geometry into an unrelated screen.",

package/agent/components/AuthExpiryProvider.json

@@ -22,7 +22,6 @@
     "ErrorSurface — the whole-page error surface; a session expiry is neither a page error nor an inline one."
   ],
   "rules": [],
-  "storyPath": "query/DataState.stories.tsx",
   "tagline": "App-root handler for an expired session (401 / invalid or expired token): every DataState / InfiniteQueryState / AlertMutationFeedback / AlertQueryError calls it automatically, once, and shows a neutral pending state instead of an error alert. Also exported from @godxjp/ui.",
   "usage": [
     "DO: mount it ONCE near the root, inside the QueryClientProvider/AppProvider, and redirect to the IdP with the current URL as the return target. The IdP returns immediately while its own session is alive — the SSO norm (Google/Microsoft apps, OIDC SPA guidance): no page-level error for an expired session.",

package/agent/components/AuthFooter.json

@@ -36,11 +36,11 @@
   "rules": [
     45
   ],
-  "storyPath": "layout/AuthFooter.stories.tsx",
+  "storyPath": "layout/auth-footer.tsx",
   "tagline": "Compact hosted-auth footer for consumer-owned product, legal, privacy, and locale content.",
   "usage": [
     "Pass real links and locale controls from the consumer; AuthFooter never invents navigation.",
-    "DO drop it into AuthShell's `footer` slot — that slot supplies the contentinfo landmark, so AuthFooter itself renders a plain div and can also sit inside an existing footer without nesting landmarks.",
+    "DO drop it into the auth CenteredShell's `footer` slot — that slot supplies the contentinfo landmark, so AuthFooter itself renders a plain div and can also sit inside an existing footer without nesting landmarks.",
     "AuthFooter owns ONLY the geometry: mono ramp, wrap, and a `·` separator between the slots that are actually PRESENT (omit `locale` and its separator disappears). Don't hand-write separators into the slot content.",
     "Public type: `AuthFooterProp` (alias `AuthFooterProps`) from `@godxjp/ui/layout` — registered in the prop registry, not a local interface.",
     "Retune the line through `--auth-footer-content-gap` / `--auth-footer-text-font-size`, never page CSS (rule #45)."

package/agent/components/AuthIdentity.json

@@ -11,7 +11,7 @@
       "type": "ReactNode"
     },
     {
-      "description": "Brand artwork in the MARK's place, for a service whose design ships a real lockup (mark + wordmark, sometimes a product suffix). Omit it and the canonical GoDX mark renders. data-slot, .ui-auth-identity spacing and the h1 are untouched, so swapping artwork never forks the block.",
+      "description": "Brand artwork in the MARK's place, for a service whose design ships a real lockup (mark + wordmark, sometimes a product suffix). Omitted → the active preset's `brandMark` (`<AppProvider preset={godxPreset}>` supplies the GoDX mark), otherwise NO mark: a neutral package draws no product's logo. `null` → no mark, preset or not. data-slot, .ui-auth-identity spacing and the h1 are untouched, so swapping artwork never forks the block.",
       "name": "brand",
       "type": "ReactNode"
     },
@@ -29,11 +29,11 @@
   "rules": [
     45
   ],
-  "storyPath": "layout/AuthIdentity.stories.tsx",
+  "storyPath": "layout/auth-identity.tsx",
   "tagline": "Hosted-auth identity heading with the shared mark (or the product's own lockup) and optional requesting-client context.",
   "usage": [
     "Only show `requester` when the consumer has authoritative client context.",
-    "It ALREADY renders the canonical brand-green GoDX mark (`Logo mark=\"godx\" tone=\"success\"`, independent of --primary) plus the page h1 — don't add a second Logo or heading above it.",
+    "It renders the page h1 plus a mark: the `brand` you pass, else the active preset's `brandMark`, else none (v32: the neutral default draws no product logo). Under `<AppProvider preset={godxPreset}>` (from `@godxjp/ui/themes/godx`, with `@godxjp/ui/themes/godx.css`) that is the brand-green GoDX mark — don't add a second Logo or heading above it.",
     "To show YOUR OWN lockup instead, pass it as `brand` — never wrap or rebuild the block. `brand` replaces the mark only, so the h1 stays; if your lockup already spells the product name, make `title` the SCREEN'S PURPOSE (\"Sign in\") rather than repeating the brand.",
     "DO keep `brand` non-interactive. The slot is DECORATIVE at every fill: the mark it replaces was always aria-hidden, and a real lockup is not a mark — `Logo mark=\"godx-lockup\" productSuffix=\"ID\"` exposes \"GoDX ID\" as real text, so left in the tree beside the h1 the block announces the product twice (measured: \"GoDXIDGoDX ID\"). aria-hidden is merged onto your element, and aria-hidden over a focusable child is a WCAG failure.",
     "Centring and rhythm are token-owned (`--auth-identity-gap` / `--auth-requester-*`); no page CSS (rule #45).",

package/agent/components/AuthStack.json

@@ -16,6 +16,6 @@
     }
   ],
   "rules": [],
-  "storyPath": "layout/AuthStack.stories.tsx",
+  "storyPath": "layout/auth-stack.tsx",
   "tagline": "Token-spaced vertical stack for direct sections inside a canonical auth card."
 }

package/agent/components/Avatar.json

@@ -22,16 +22,6 @@
       "name": "appearance",
       "type": "\"default\" | \"tinted\""
     },
-    {
-      "description": "Which side of the trigger the panel opens on. Defaults from `appearance` — a bar drops the grid below, anything else opens to the inline-end. State it when the chrome can be RE-DOCKED: `appearance` says the trigger is not in a bar but cannot say which way is out, and a rail pinned to the top edge still opens downward. Ignored by responsive=\"fullscreen\" and by the Sheet surface, which are not anchored to the trigger.",
-      "name": "side",
-      "type": "\"top\" | \"right\" | \"bottom\" | \"left\""
-    },
-    {
-      "description": "How the panel aligns to the trigger. Defaults from `appearance` — end in a bar, start otherwise. Same rule as `side`: state it only for chrome that knows its own orientation.",
-      "name": "align",
-      "type": "\"start\" | \"center\" | \"end\""
-    },
     {
       "description": "Realtime reachability, drawn as an indicator at the block-end/inline-end corner of the mark. Ships the dot, its geometry tokens and a localized sr-only label TOGETHER, so presence is never colour-only (WCAG 1.4.1): each value also has its own silhouette — online = filled disc (--success), away = half-filled (--warning), busy = filled + a horizontal do-not-disturb bar (--destructive), offline = hollow ring (--muted-foreground). OMIT the prop for an entity with no presence concept (an organization mark, a capability medallion): no node and no attribute are emitted. `presence=\"offline\"` is the DIFFERENT, positive statement \"known to be unreachable\" — the same distinction ListRow draws between an omitted and a `false` `unread`.",
       "name": "presence",
@@ -61,12 +51,12 @@
     3,
     35
   ],
-  "storyPath": "data-display/Avatar.stories.tsx",
+  "storyPath": "data-display/avatar.tsx",
   "subParts": [
     "AvatarFallback",
     "AvatarImage"
   ],
-  "tagline": "Radix Avatar wrapper with image and fallback slots for users, teams, and entities.",
+  "tagline": "Avatar mark with image and fallback slots for users, teams, and entities.",
   "usage": [
     "DO compose Avatar > AvatarImage + AvatarFallback so broken or missing images still show a readable fallback.",
     "DO pass `fit=\"contain\"` on AvatarImage for a logo or app icon that is wide, transparent or off-centre — the default `cover` crops to fill, right for a face (gh#1176). A full-bleed square icon (the GoDX service icon set) keeps the default.",

package/agent/components/Badge.json

@@ -70,7 +70,7 @@
   "rules": [
     35
   ],
-  "storyPath": "data-display/Badge.stories.tsx",
+  "storyPath": "data-display/badge.tsx",
   "subParts": [
     "StatusBadge"
   ],

package/agent/components/BarChart.json

@@ -101,7 +101,6 @@
     "DataTable — exact tabular figures."
   ],
   "rules": [],
-  "storyPath": "charts/BarChart.stories.tsx",
   "tagline": "Compare a value across categories — grouped or `stacked`, vertical or `horizontal`, with localized ticks/tooltips and a built-in text alternative. Data-visualization graph / plot / diagram.",
   "usage": [
     "DO import from the charts entry: `import { BarChart } from \"@godxjp/ui/charts\";` (recharts optional peer required).",

package/agent/components/BranchScopePicker.json

@@ -88,7 +88,7 @@
   "rules": [
     24
   ],
-  "storyPath": "data-entry/BranchScopePicker.stories.tsx",
+  "storyPath": "data-entry/branch-scope-picker.tsx",
   "tagline": "Canonical scope control: all branches vs an explicit subset.",
   "usage": [
     "DO treat scope as ONE form field: the single { mode, branchIds } value goes through FormField like any other control.",

package/agent/components/Breadcrumb.json

@@ -33,7 +33,7 @@
     "PrefetchLink — if ancestor breadcrumb segments should prefetch their destination query on hover/focus, consider pairing the `to` values with `PrefetchLink` in a custom breadcrumb or pre-warming the cache on mount; Breadcrumb's internal links are plain react-router-dom `<Link>` with no prefetch behaviour."
   ],
   "rules": [],
-  "storyPath": "layout/Breadcrumb.stories.tsx",
+  "storyPath": "navigation/breadcrumb.tsx",
   "tagline": "Standalone breadcrumb nav rendering an ordered trail of page segments.",
   "usage": [
     "DO import from `@godxjp/ui/layout` (not from a navigation or general sub-path) and pass a single `items` prop — an ordered array of `{ label, to? }` objects. No children, no sub-components, no render-prop API.",

package/agent/components/Button.json

@@ -48,7 +48,7 @@
     },
     {
       "defaultValue": "false",
-      "description": "Render as Radix Slot — merge props onto the child (<a>/<Link>).",
+      "description": "Render as the kit's Slot — merge props onto the child (<a>/<Link>).",
       "name": "asChild",
       "type": "boolean"
     },
@@ -106,11 +106,11 @@
   "rules": [
     23
   ],
-  "storyPath": "general/Button.stories.tsx",
+  "storyPath": "general/button/index.tsx",
   "subParts": [
     "ButtonRefetch"
   ],
-  "tagline": "Core button with variant + size presets, built on cva and Radix Slot (asChild).",
+  "tagline": "Core button with variant + size presets, built on cva with the kit's own Slot (asChild).",
   "usage": [
     "DO pick the right variant for intent: `default` (primary CTA, one per section), `destructive` (irreversible actions like delete/revoke), `outline` (secondary actions alongside a primary), `secondary` (less prominent actions), `ghost` (toolbar icon-only actions), `link` (inline text-style navigation without an underline by default).",
     "DO use icon-only sizes (`icon`, `icon-xs`, `icon-sm`, `icon-lg`) exclusively for buttons that contain only an SVG — these sizes set equal width/height. For text+icon buttons use `default|sm|lg|xs` sizes; icons inside are auto-sized to 1rem via `[&_svg:not([class*='size-'])]:size-4`.",

package/agent/components/Calendar.json

@@ -234,7 +234,7 @@
     6,
     23
   ],
-  "storyPath": "data-entry/Calendar.stories.tsx",
+  "storyPath": "data-entry/calendar.tsx",
   "subParts": [
     "DayButton"
   ],

package/agent/components/Card.json

@@ -75,7 +75,7 @@
     "DataState / InfiniteQueryState — use instead of Card when the content is a TanStack Query-driven list that needs automatic skeleton, empty, and error states; Card does not manage loading lifecycle."
   ],
   "rules": [],
-  "storyPath": "data-display/Card.stories.tsx",
+  "storyPath": "data-display/card/index.tsx",
   "subParts": [
     "CardAction",
     "CardCover",
@@ -98,7 +98,7 @@
     "DO use `tabList` for a tab strip that belongs to the CARD — antd's card-head tabs, ported name for name (gh#570): `tabList={[{ key, tab, disabled? }]}` plus `activeTabKey`/`defaultActiveTabKey`/`onTabChange`, with `extra` for antd's `tabBarExtraContent` and `tabProps` for everything else on the Tabs underneath. The strip renders INSIDE the card head, under the title, on the same surface and inside the same border, and the Card's children become the selected tab's body (wrap them in <CardContent>, or <CardContent flush> for an edge-to-edge DataTable). DON'T hand-roll it as a <Tabs> parked on the page above the card (the strip floats off the card and the two read as two objects) or as a <Card> repeated inside each tab (the shell is copied per view). A <Tabs> INSIDE <CardContent tight flush> is still correct for a strip that belongs to the BODY rather than to the card head.",
     "DO reach for `accentPlacement=\"perimeter\"` when the whole card needs attention, not one edge: `<Card accent=\"attention\" accentPlacement=\"perimeter\">` is the semantic-tone equivalent of `variant=\"featured\"` (which is brand-toned by definition). Never hand-roll it with `className=\"border-2 border-[--attention]\"` or a page-local `.card--attention` rule — the placement owns the border weight, the outer ring AND the slot-padding compensation, so text stays on the same column as an unaccented sibling.",
     "DON'T hand-roll a stat/KPI tile with <Card> + raw divs — use <StatCard> (label, value, hint, delta, layout, inverse props) which is already a Card internally with correct token-driven layout.",
-    "SPACING IS BORDER-AWARE & token-driven (theme via src/tokens/components/card.css, never hard-code padding on slots): `--card-space-inset` is the shared horizontal column every slot (header/content/footer) aligns to. A DIVIDED section — a `banded` header or a `separated` footer, i.e. one carrying a divider border — pads SYMMETRICALLY top+bottom from `--card-space-divided-y` (a band reads as its own region). A PLAIN header flows into the body instead: top `--card-space-shell-y`, no bottom, and the body supplies the gap via `--card-space-body-y`. THE TWO AXES ARE INDEPENDENT: `--card-space-inset` is inline-only, while `--card-space-shell-y` owns the BLOCK shell edges (plain-header top, `solo` body top, terminal slot bottom) and defaults to the inset — so a shell/theme can make a card SHORTER without narrowing its column by overriding `--card-space-shell-y` alone (this is how AuthShell's `--auth-shell-card-padding-block-compact` reaches CardContent). Never bridge it with a consumer selector on the card-content slot. Special case: `<CardContent flush>` zeroes BOTH of its block edges — for ANY full-bleed body, not only one containing a <Table>` gate left a flush file LIST floating 18px off its header while the flush table beside it sat at 0) — so the plain header above it supplies the gap from its own `--card-space-body-y` bottom padding instead. `tight` and `solo` still own that axis themselves. `--card-space-gap` is the in-slot stack gap (title↕description). Tune the band rhythm once at `--card-space-divided-y`; tune the accent stripe width at `--card-accent-rail-width` (default 6px)."
+    "SPACING IS BORDER-AWARE & token-driven (theme via src/tokens/components/card.css, never hard-code padding on slots): `--card-space-inset` is the shared horizontal column every slot (header/content/footer) aligns to. A DIVIDED section — a `banded` header or a `separated` footer, i.e. one carrying a divider border — pads SYMMETRICALLY top+bottom from `--card-space-divided-y` (a band reads as its own region). A PLAIN header flows into the body instead: top `--card-space-shell-y`, no bottom, and the body supplies the gap via `--card-space-body-y`. THE TWO AXES ARE INDEPENDENT: `--card-space-inset` is inline-only, while `--card-space-shell-y` owns the BLOCK shell edges (plain-header top, `solo` body top, terminal slot bottom) and defaults to the inset — so a shell/theme can make a card SHORTER without narrowing its column by overriding `--card-space-shell-y` alone (this is how the auth CenteredShell's `--auth-shell-card-padding-block-compact` reaches CardContent). Never bridge it with a consumer selector on the card-content slot. Special case: `<CardContent flush>` zeroes BOTH of its block edges — for ANY full-bleed body, not only one containing a <Table>` gate left a flush file LIST floating 18px off its header while the flush table beside it sat at 0) — so the plain header above it supplies the gap from its own `--card-space-body-y` bottom padding instead. `tight` and `solo` still own that axis themselves. `--card-space-gap` is the in-slot stack gap (title↕description). Tune the band rhythm once at `--card-space-divided-y`; tune the accent stripe width at `--card-accent-rail-width` (default 6px)."
   ],
   "useCases": [
     "Dashboard KPI summary row: wrap each metric in <StatCard> (or a plain <Card density=\"tight\"> with <CardContent>) to render a uniform grid of labeled value tiles with optional trend deltas.",

package/agent/components/CardBar.json

@@ -38,7 +38,6 @@
   "rules": [
     9
   ],
-  "storyPath": "data-display/Card.stories.tsx",
   "tagline": "Inline card toolbar with scoped inset and divider edges.",
   "usage": [
     "Compose inside Card. Unset border follows its position; explicit border prevents double rules in stacked bars."

package/agent/components/CardContent.json

@@ -30,7 +30,6 @@
     37,
     38
   ],
-  "storyPath": "data-display/Card.stories.tsx",
   "tagline": "Card body. flush = edge-to-edge (for DataTable/tabs); tight = no top gap; solo = no header above. NEVER put a Toolbar inside flush (it loses padding).",
   "usage": [
     "DO: Always wrap body content in <CardContent> — a bare <Card> has no internal padding, so any child placed directly inside it renders flush against the card edges.",

package/agent/components/Carousel.json

@@ -1,7 +1,7 @@
 {
-  "example": "import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, CarouselDots } from \"@godxjp/ui/data-display\";\n\n// CarouselDots reads the Embla api from context — no setApi wiring needed.\n<Carousel opts={{ loop: true }}>\n  <CarouselContent>\n    <CarouselItem>1</CarouselItem>\n    <CarouselItem>2</CarouselItem>\n  </CarouselContent>\n  <CarouselPrevious />\n  <CarouselNext />\n  <CarouselDots />\n</Carousel>",
+  "example": "import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, CarouselDots } from \"@godxjp/ui/lab\";\n\n// CarouselDots reads the Embla api from context — no setApi wiring needed.\n<Carousel opts={{ loop: true }}>\n  <CarouselContent>\n    <CarouselItem>1</CarouselItem>\n    <CarouselItem>2</CarouselItem>\n  </CarouselContent>\n  <CarouselPrevious />\n  <CarouselNext />\n  <CarouselDots />\n</Carousel>",
   "group": "data-display",
-  "importPath": "@godxjp/ui/data-display",
+  "importPath": "@godxjp/ui/lab",
   "name": "Carousel",
   "props": [
     {
@@ -24,7 +24,7 @@
     3,
     6
   ],
-  "storyPath": "data-display/Carousel.stories.tsx",
+  "storyPath": "data-display/carousel.tsx",
   "subParts": [
     "CarouselContent",
     "CarouselDots",
@@ -33,6 +33,7 @@
     "CarouselPrevious"
   ],
   "tagline": "Embla-backed carousel primitives: previous/next controls, CarouselDots indicators, and a context API.",
+  "tier": "lab",
   "usage": [
     "DO compose the full set: `<Carousel>` › `<CarouselContent>` › many `<CarouselItem>`, with `<CarouselPrevious>`/`<CarouselNext>` for arrows and `<CarouselDots>` for the indicator row. Don't render items outside `<CarouselContent>` — the track is the scroll container.",
     "DO use `<CarouselDots>` for the active-slide indicator instead of wiring `setApi` by hand — it reads `selectedIndex`/`scrollSnaps` from the Carousel context, renders one `aria-current` dot per snap, and auto-hides when there is ≤1 slide.",

package/agent/components/Cascader.json

@@ -193,7 +193,7 @@
     23,
     31
   ],
-  "storyPath": "data-entry/Cascader.stories.tsx",
+  "storyPath": "data-entry/cascader.tsx",
   "tagline": "Multi-level hierarchical path picker (Popover + cascading columns); value is always a string[] path, never a flat ID — passing a bare string breaks it.",
   "usage": [
     "DO pass a string[] path as value in single mode (e.g. ['country','region','city']). DON'T pass a flat string ID — the component treats value as an ordered path array and will render nothing if you pass a bare string.",