@godxjp/ui 28.9.0 → 28.10.0

package/agent/components/MobileShell.json

@@ -0,0 +1,73 @@
+{
+  "example": "import { Flex, MobileShell } from \"@godxjp/ui/layout\";\nimport { Button, Heading, Text } from \"@godxjp/ui/general\";\nimport { Inbox, Package, ScanLine, Truck } from \"lucide-react\";\n\nexport function HandyInbound() {\n  return (\n    <MobileShell\n      statusBar={<Text size=\"sm\" tabular>9:41</Text>}\n      header={\n        <Flex align=\"center\" justify=\"between\" gap=\"xs\" className=\"w-full\">\n          <Heading level={3} as=\"h1\">入庫</Heading>\n          <Button variant=\"ghost\" size=\"sm\">選択</Button>\n        </Flex>\n      }\n      actions={\n        <Button className=\"flex-[2]\">\n          <ScanLine aria-hidden=\"true\" />\n          スキャン\n        </Button>\n      }\n      tabBar={\n        <>\n          <Button variant=\"ghost\" aria-current=\"page\" className=\"h-full flex-col rounded-none\">\n            <Inbox aria-hidden=\"true\" />\n            <Text size=\"2xs\">入庫</Text>\n          </Button>\n          <Button variant=\"ghost\" className=\"h-full flex-col rounded-none\">\n            <Package aria-hidden=\"true\" />\n            <Text size=\"2xs\">梱包</Text>\n          </Button>\n          <Button variant=\"ghost\" className=\"h-full flex-col rounded-none\">\n            <Truck aria-hidden=\"true\" />\n            <Text size=\"2xs\">出庫</Text>\n          </Button>\n        </>\n      }\n    >\n      <Flex direction=\"col\" gap=\"sm\">\n        <Text>洗顔フォーム</Text>\n        <Text>日焼け止め</Text>\n      </Flex>\n    </MobileShell>\n  );\n}",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "MobileShell",
+  "props": [
+    {
+      "description": "The scrolling screen body — the ONLY scroll container in the shell and its only elastic band. Everything else is fixed chrome, so a long list scrolls under a stationary app bar and tab bar instead of taking them off screen with it.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "App bar (banner) pinned to the top: the screen title plus its inline actions. Absorbs the top safe-area inset when there is no statusBar. Omit → no banner. For a screen MODE (multi-select, search, edit) swap the whole node rather than stacking a second strip under it — replacing the bar's contents is the platform pattern on iOS and Android alike.",
+      "name": "header",
+      "type": "ReactNode"
+    },
+    {
+      "description": "The band that sits IN the OS status-bar strip above the app bar — the carrier/clock row of a display-mode:standalone PWA, or the simulated one in a device-frame preview. It owns the top safe-area inset when present. Omit it in an ordinary browser tab, where the OS already paints that strip and the header takes the inset instead.",
+      "name": "statusBar",
+      "type": "ReactNode"
+    },
+    {
+      "description": "The sticky action bar pinned above the tab bar — the screen's primary verb (Scan, Save, Hand over) and at most one secondary. It sits OUTSIDE the scroll region, so it is always reachable with no `position: sticky` and no scroll-padding hack, and it takes the home-indicator inset whenever no tabBar follows it.",
+      "name": "actions",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Bottom tab bar (navigation) — the app's top-level destinations. Children TILE: equal width, no seam, no page gutter, so you never hand-roll a grid with a column count. Always the last band, so it owns the home-indicator inset.",
+      "name": "tabBar",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "\"viewport\"",
+      "description": "Where the shell's one-screen height comes from. \"viewport\" (default) is the real app: exactly 100dvh, so the DOCUMENT never scrolls and the tab bar cannot slide away under a collapsing URL bar. \"fill\" fills a BOUNDED parent instead — a device-frame preview, or a phone view embedded in a wider page — where a viewport-tall root would overflow its frame. Nothing else differs between the two.",
+      "name": "height",
+      "type": "\"viewport\" | \"fill\""
+    },
+    {
+      "defaultValue": "\"fill\"",
+      "description": "How wide the shell is allowed to get. \"fill\" (default) takes the whole inline size it is given — a real handheld, where that IS the phone. \"phone\" caps it at --mobile-shell-max-inline-size (430px, the widest current handheld logical width) and centres the column: the SAME situation height=\"fill\" already names on the other axis, a handheld screen rendered on a viewport wider than a handheld. Measured at 1280px before this axis existed: max-inline-size none, shell 1232px wide, a four-destination tab bar spread across the whole screen.",
+      "name": "width",
+      "type": "\"fill\" | \"phone\""
+    }
+  ],
+  "related": [
+    "AppShell — the authenticated shell WITH a sidebar rail and a mobile drawer at the 900px step. Use it for an admin console that happens to be viewed on a phone; use MobileShell when the phone IS the product.",
+    "CenteredShell — the authenticated no-sidebar shell whose main scrolls the PAGE. MobileShell is its handheld counterpart: same 'no rail' shape, opposite scroll contract.",
+    "AuthShell — the unauthenticated root. A login screen inside a handheld app still belongs to AuthShell, not MobileShell.",
+    "Sheet — `side=\"bottom\"` is the handheld modal: scanners, pickers and forms open from the bottom over MobileShell rather than navigating away."
+  ],
+  "rules": [
+    23,
+    24,
+    45
+  ],
+  "storyPath": "layout/MobileShell.stories.tsx",
+  "tagline": "Handheld app shell (gh#354) — status band · app bar · the ONE scroll region · sticky action bar · bottom tab bar, with device safe-area insets and a document that never scrolls.",
+  "usage": [
+    "DO use MobileShell for a HANDHELD app screen — a warehouse/handy terminal, a driver app, a field-work PWA. It is the fourth root shell: AppShell (needs a sidebar) · AuthShell (unauthenticated card) · CenteredShell (authenticated scrolling document) · MobileShell (a phone app that does NOT scroll its document).",
+    "DO let `children` be the only thing that scrolls. Put the primary verb in `actions` and navigation in `tabBar` — both sit outside the scroll region, so neither needs `position: sticky`, a z-index, or bottom padding to clear the other.",
+    "DO NOT compose one out of <Card> + `ui-card-inset*` + `overflow-y-auto` (what docs/showcase/case6 did before gh#354). That reproduces the look and neither behaviour that matters on a device: the document still scrolls, and nothing pads out of env(safe-area-inset-*), so the notch covers the app bar and the home indicator covers the primary button.",
+    "DO swap the `header` node for a screen MODE (select mode, search mode) instead of stacking a second contextual strip below it — one bar to read, and the platform pattern on both iOS and Android.",
+    "DO use `height=\"fill\"` ONLY when the shell is inside a bounded parent (a device-frame preview). In a real app leave it at \"viewport\": that is what keeps the document from scrolling.",
+    "DO NOT nest MobileShell inside AppShell / AuthShell / CenteredShell (or the reverse) — it is a ROOT shell. Retune the page gutter and the three band heights from the theme (--mobile-shell-inset-inline, --mobile-shell-header-bar-height, --mobile-shell-tab-bar-height, --mobile-shell-status-bar-height); never fork .ui-mobile-shell-* CSS."
+  ],
+  "useCases": [
+    "Warehouse handheld (代理店ハンディ): a status band, an app bar with a select-mode text action, a scrolling item list, a dominant Scan button in `actions`, and a three-destination `tabBar` (inbound · packing · outbound). See the case6-agency-handy showcase.",
+    "Driver / delivery app: route list in the scroll region, 'Arrived' as the single `actions` verb, tabs for today · history · profile.",
+    "Field-inspection PWA installed to the home screen: `statusBar` paints the standalone strip, `header` carries the site name, and the form scrolls under both.",
+    "A phone view embedded in a desktop device-frame preview: the same composition with `height=\"fill\"` inside a fixed-size frame."
+  ]
+}

package/agent/components/NavList.json

@@ -0,0 +1,63 @@
+{
+  "example": "<NavList\n  label=\"Settings\"\n  activeId={route}\n  linkComponent={Link}\n  items={[\n    // A GROUP: one NavList, one <nav>, however many groups (gh#815).\n    {\n      id: \"account\",\n      label: \"Account\",\n      icon: User,\n      children: [\n        { id: \"profile\", label: \"Profile\", href: \"/settings/profile\" },\n        { id: \"organization\", label: \"Organization\", href: \"/settings/organization\" },\n      ],\n    },\n    // A LEAF, at the same level. `icon` takes the COMPONENT, never an element, and is optional.\n    { id: \"appearance\", label: \"Appearance\", icon: Palette, href: \"/settings/appearance\" },\n  ]}\n/>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "NavList",
+  "props": [
+    {
+      "description": "Rows in reading order. Same shape as the rail's items, deliberately: one item vocabulary for both navigations. An item carrying `children` renders as a collapsible GROUP — the rail's own `.sb-nav-group`, opened by the route whenever a descendant is active (gh#815). `icon` is optional; a row without one keeps an empty 16px slot so the label column still aligns.",
+      "name": "items",
+      "required": true,
+      "type": "SidebarItemProp[]"
+    },
+    {
+      "description": "`id` of the current route. That row gets the active tokens and aria-current=\"page\".",
+      "name": "activeId",
+      "type": "string"
+    },
+    {
+      "description": "Accessible name for the <nav> landmark. Required because a page routinely holds more than one navigation (breadcrumb, rail, this one).",
+      "name": "label",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Router link component — identical contract to Sidebar.linkComponent. The library composes the row and passes it as children; the component only renders the <a>.",
+      "name": "linkComponent",
+      "type": "SidebarLinkComponentProp"
+    },
+    {
+      "description": "Reports the activated row's id, for consumers driving navigation themselves.",
+      "name": "onSelect",
+      "type": "(id: string) => void"
+    }
+  ],
+  "related": [
+    "Sidebar",
+    "MasterDetail",
+    "PageContainer"
+  ],
+  "rules": [
+    2,
+    3,
+    5,
+    6
+  ],
+  "storyPath": "layout/NavList.stories.tsx",
+  "tagline": "Vertical route navigation for INSIDE a page — the shape a settings nav takes. Renders the same `.sb-nav-item` rows as the Sidebar rail (icon column, label, badge, active tokens, `aria-current=\"page\"`) in a `<nav>` landmark, without the AppShell grid the rail depends on.",
+  "usage": [
+    "DO use NavList for a settings / account / preferences sub-navigation beside the pane it drives — typically as MasterDetail's `master`.",
+    "DO group with `item.children` — one NavList, one `<nav>` landmark, however many groups. Before gh#815 NavList dropped `children` silently (it type-checked, rendered one flat row, and the subtree vanished), so the workaround was one NavList per group wrapped in SidebarSection, i.e. N landmarks for one navigation. Don't write that any more.",
+    "DON'T repeat a group's icons on its children: a nested row draws the rail's dot marker instead of the 16px icon column, exactly like the rail's submenu. Icons belong on the rows that sit at the top level.",
+    "DON'T reach for Sidebar here: it is the app's primary rail and lays into AppShell's grid area, so nested in a page it has no grid to lay into.",
+    "DON'T hand-roll the rows out of Buttons with the current one encoded as a variant swap. That loses aria-current, loses the icon column the labels align to, and invents a different nav in every app.",
+    "DON'T use Tabs: each entry here is a separate ROUTE the router renders, not a panel this component owns. Tabs would mean faking tab state from the URL and never rendering a TabsContent.",
+    "DO pass `label` — the <nav> landmark needs a name to be distinguishable from the breadcrumb and the rail.",
+    "There is no collapsed state by design: a page-level navigation has no rail to collapse into. Only the shell rail collapses. (A GROUP still opens and closes — that is `item.children`, not the rail's collapsed mode.)"
+  ],
+  "useCases": [
+    "Settings page / settings nav / preferences nav: Account / Security / Notifications / Billing beside the selected settings form — grouped, in ONE <nav> landmark.",
+    "Settings screen: Profile / Appearance / Security beside the selected settings form.",
+    "Account area: a vertical route nav inside a PageContainer, driving the detail pane."
+  ]
+}

package/agent/components/NumberInput.json

@@ -0,0 +1,158 @@
+{
+  "example": "import { NumberInput } from \"@godxjp/ui/data-entry\";\n\n<NumberInput\n  value={qty}\n  onValueChange={setQty}\n  min={1}\n  max={99}\n  step={1}\n  prefix=\"¥\"\n  aria-label=\"数量\"\n/>",
+  "group": "data-entry",
+  "importPath": "@godxjp/ui/data-entry",
+  "name": "NumberInput",
+  "props": [
+    {
+      "description": "Validation state the field paints — Ant Design `status`. `error` also reports `aria-invalid`, so the red boundary and what a screen reader hears are one fact; `warning` paints only, because a warning is not a validity failure. antd's `success`/`validating` are not implemented: antd only draws them together with its `hasFeedback` icon slot, which FormField owns here.",
+      "name": "status",
+      "type": "\"error\" | \"warning\""
+    },
+    {
+      "defaultValue": "\"outlined\"",
+      "description": "Chrome level — Ant Design `variant`. `outlined` is the historical field; `filled` swaps the boundary for a tinted surface (dense forms); `borderless` drops both, for a field inside a box that already draws one. antd's fourth member `underlined` is deliberately absent — a single bottom rule is a Material convention and SmartHR, the JP authority here, draws every field as a full box.",
+      "name": "variant",
+      "type": "\"outlined\" | \"filled\" | \"borderless\""
+    },
+    {
+      "description": "antd `formatter` — how the committed number is DISPLAYED at rest (a unit, a separator, 円). Replaces the built-in `Intl.NumberFormat`; pair it with `parser` or the text cannot be read back.",
+      "name": "formatter",
+      "type": "(value: number | null) => string"
+    },
+    {
+      "description": "antd `parser` — the inverse of `formatter`. Without one, the built-in reader NFKC-folds 全角 digits, periods and minus signs to ASCII first, so a value typed on a Japanese keyboard survives blur.",
+      "name": "parser",
+      "type": "(display: string) => number | null"
+    },
+    {
+      "defaultValue": "true",
+      "description": "antd `keyboard` — ArrowUp/ArrowDown step the value (Shift = ×10).",
+      "name": "keyboard",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "antd `changeOnWheel` — a mouse wheel steps the value. Off by default and gated on FOCUS even when on, so scrolling past a long form cannot silently edit it.",
+      "name": "changeOnWheel",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "antd `controls` — draw the increment/decrement buttons. `false` keeps the spinbutton role and the arrow keys; it only stops drawing the two buttons.",
+      "name": "controls",
+      "type": "boolean"
+    },
+    {
+      "description": "Controlled value. `null` = empty field. Pair with `onValueChange`.",
+      "name": "value",
+      "type": "number | null"
+    },
+    {
+      "defaultValue": "null",
+      "description": "Uncontrolled initial value.",
+      "name": "defaultValue",
+      "type": "number | null"
+    },
+    {
+      "description": "Value change callback (vocabulary triad — NOT onChange). Receives `null` when the field is empty.",
+      "name": "onValueChange",
+      "type": "(value: number | null) => void"
+    },
+    {
+      "description": "Lower bound — clamps on commit and disables the decrement stepper at the floor.",
+      "name": "min",
+      "type": "number"
+    },
+    {
+      "description": "Upper bound — clamps on commit and disables the increment stepper at the ceiling.",
+      "name": "max",
+      "type": "number"
+    },
+    {
+      "defaultValue": "1",
+      "description": "Increment for the steppers + ArrowUp/ArrowDown (Shift = ×10).",
+      "name": "step",
+      "type": "number"
+    },
+    {
+      "description": "Committed decimal places. Inferred from `step` when omitted.",
+      "name": "precision",
+      "type": "number"
+    },
+    {
+      "description": "Disables typing and stepping.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Value is shown and selectable but not typeable or steppable.",
+      "name": "readOnly",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "\"md\"",
+      "description": "Control height tier (--control-height). Aligns with sibling controls on a row.",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "description": "Placeholder shown when empty.",
+      "name": "placeholder",
+      "type": "string"
+    },
+    {
+      "description": "Leading decorative affix inside the field (e.g. `¥`). aria-hidden.",
+      "name": "prefix",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Trailing decorative affix inside the field (e.g. `%`). aria-hidden.",
+      "name": "suffix",
+      "type": "React.ReactNode"
+    },
+    {
+      "description": "Form field name — submits its value natively.",
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "description": "Associates with a <label htmlFor> / FormField.",
+      "name": "id",
+      "type": "string"
+    },
+    {
+      "description": "Accessible name for the spinbutton when no visible FormField label is present.",
+      "name": "aria-label",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Input — the plain single-line field NumberInput composes; use Input directly only for free numeric text with no stepper/clamp need.",
+    "Slider — use instead when the user picks an approximate value within a range by dragging; NumberInput is for exact keyed entry.",
+    "FormField — compose NumberInput inside FormField (matching id) for label/helper/error a11y wiring.",
+    "TimePicker — the HH:mm time sibling; NumberInput is for plain numbers, TimePicker for clock times."
+  ],
+  "rules": [
+    3,
+    6
+  ],
+  "storyPath": "data-entry/NumberInput.stories.tsx",
+  "tagline": "WAI-ARIA spinbutton for localized numeric entry — composes the real Input (role=spinbutton, inputMode=decimal) with stacked increment/decrement step Buttons. Type freely, Arrow/Shift-Arrow step, value commits clamped to min/max + rounded to precision.",
+  "usage": [
+    "DO use NumberInput (not `<Input type='number'>`) whenever numeric entry wants steppers, min/max clamping, precision rounding, or a ¥/% affix — it is the canonical numeric primitive. Plain Input has no stepper and no clamp.",
+    "DO drive it controlled with `value` + `onValueChange` carrying `number | null` (the vocabulary triad — NOT `onChange`). `null` means the field is empty; never substitute 0 for empty.",
+    "DON'T pass `value` without `onValueChange` — like every controlled @godxjp/ui input it would freeze. Omit both for uncontrolled (use `defaultValue`).",
+    "DO set `step` to your increment and let `precision` (or the decimals of `step`) round the committed value: `step={0.25} precision={2}` gives quarter-step entry rounded to 2 places on blur/Enter.",
+    "DO set `min`/`max` for bounded quantities — the value clamps on commit and the matching stepper Button auto-disables at the bound. The steppers are tabIndex=-1 so they never pollute the keyboard tab order (Arrow keys cover keyboard stepping).",
+    "DON'T wrap it in a hand-rolled label/error markup — compose it inside FormField (matching `id`) for the aria wiring, exactly like Input.",
+    "DON'T format the value yourself for display — NumberInput formats at rest via Intl.NumberFormat in the active locale while keeping the raw value typeable on focus."
+  ],
+  "useCases": [
+    "Quantity / line-item steppers in order, invoice, or cart forms (min={1}, step={1}) where ± buttons and a floor are expected.",
+    "Price / amount fields with a currency affix (prefix='¥', step={10}) — the affix is decorative and the committed value stays a plain number.",
+    "Percentage / rate inputs bounded 0–100 (suffix='%', min={0} max={100}).",
+    "Decimal measurements — weight, dimensions, exchange rates (step={0.25}, precision={2}) needing rounded commit.",
+    "Any bounded numeric setting (timeouts, retry counts, page sizes) where a slider is too coarse and a free Input lacks clamping."
+  ]
+}

package/agent/components/OrgSwitcher.json

@@ -0,0 +1,89 @@
+{
+  "example": "import { OrgSwitcher } from \"@godxjp/ui/layout\";\nimport { Badge } from \"@godxjp/ui/data-display\";\n\n<OrgSwitcher\n  organizations={[\n    {\n      id: \"dxs\",\n      name: \"DXS Holdings\",\n      meta: t(\"org.role.owner\"),\n      badge: <Badge variant=\"secondary\">{t(\"org.plan.trial\")}</Badge>,\n      badgeLabel: t(\"org.plan.trial.sr\"),\n    },\n  ]}\n  value={organizationId}\n  onValueChange={setOrganizationId}\n  labels={labels}\n/>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "OrgSwitcher",
+  "props": [
+    {
+      "description": "Consumer-provided organization choices.",
+      "name": "organizations",
+      "required": true,
+      "type": "readonly OrgSwitcherOrganization[]"
+    },
+    {
+      "description": "Selected organization id.",
+      "name": "value",
+      "type": "string"
+    },
+    {
+      "description": "Selection callback; persistence remains consumer-owned.",
+      "name": "onValueChange",
+      "type": "(value: string) => void"
+    },
+    {
+      "description": "Localized trigger, search, state, and retry copy.",
+      "name": "labels",
+      "required": true,
+      "type": "OrgSwitcherLabels"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Compact trigger presentation.",
+      "name": "collapsed",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Disables the trigger.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Shows the loading state.",
+      "name": "loading",
+      "type": "boolean"
+    },
+    {
+      "description": "Consumer-supplied error state.",
+      "name": "error",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Consumer-owned retry callback.",
+      "name": "onRetry",
+      "type": "() => void"
+    },
+    {
+      "defaultValue": "\"auto\"",
+      "description": "Which SURFACE the panel opens on. \"auto\" (default) is a desktop popover above --sheet-responsive-breakpoint-width (48rem/768px) and a focus-trapped bottom Sheet at/below it. \"dialog\" is a centred modal above that breakpoint and the SAME Sheet below it — reach for it once a row carries more than a name (a role, a plan, a member count, a create-organization action): a popover is anchored to its trigger, clipped by the viewport and sized by --org-switcher-menu-width, while a dialog has a real title, a scrolling body and room for a footer, and takes full attention, which is the right trade when switching organization re-scopes everything on screen. \"popover\" and \"sheet\" pin one surface at every width, for deterministic embedded surfaces and component tests. \"auto\" and \"dialog\" are the two RESPONSIVE pairs and share their mobile half, because a centred modal on a phone is a Sheet with worse ergonomics. All four resolve the breakpoint through the shared useSheetResponsiveMode() hook, so moving that one token moves the line for every overlay. Width of the dialog surface is --org-switcher-dialog-width (26rem), separate from --dialog-width-default so re-tuning the picker does not re-tune every dialog.",
+      "name": "responsive",
+      "type": "\"auto\" | \"popover\" | \"sheet\" | \"dialog\""
+    },
+    {
+      "description": "Controlled open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "description": "Open-state callback.",
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void"
+    }
+  ],
+  "related": [
+    "AppShell (navRail) — WHERE this control goes when switching organization is constant: the rail is the docked platform-scope column, and its own prop doc is the authority on which of the three columns owns which scope. Pass the collapsed trigger; the rail is 3.5rem.",
+    "AppLauncher — the OTHER platform-scope control: which APP, not which ORGANIZATION. They compose (a launcher in the bar and a switcher in the rail is one coherent platform surface); neither replaces the other.",
+    "Sidebar — APP scope, and therefore NOT where this goes. Its `brand` slot is the app's own lockup; putting the organization switcher there mixes two scopes in one header."
+  ],
+  "rules": [],
+  "storyPath": "layout/OrgSwitcher.stories.tsx",
+  "tagline": "Searchable organization switcher with canonical trigger geometry, desktop popover, and mobile sheet.",
+  "usage": [
+    "Provide only organizations the current user may select; the component does not authorize or fetch tenants.",
+    "Keep persistence and navigation in `onValueChange`; use loading/error props for the real query state.",
+    "DO put a plan/status affordance in `organization.badge` (a <Badge>) instead of stuffing it into `meta` — the badge is end-aligned in the expanded trigger and in the menu row, and hidden in the collapsed rail. ALWAYS pair it with a localized `organization.badgeLabel`: the trigger's accessible name comes from `labels.trigger`, so the badge is announced as an aria-describedby DESCRIPTION and the raw node is marked presentational (WCAG 1.1.1). `badgeLabel` also becomes a search keyword.",
+    "DON'T wrap OrgSwitcher in your own media query to pick popover vs sheet — `responsive=\"auto\"` already reads the shared --sheet-responsive-breakpoint-width token.",
+    "DON'T put it in the SIDEBAR — not as a row, not in `Sidebar`'s `brand` slot, not stacked under the product lockup. Which organization you are in is PLATFORM scope: it survives changing app, while everything else in the sidebar is this app's own sections. Its two legal homes are `AppShell`'s `navRail` (a permanent 3.5rem column — the Slack shape, when switching is frequent enough to deserve the width) and the topbar (a `TopbarItem`-height control, with `topbarSpan=\"full\"` so the bar outranks the section beneath it). Stacking it under the sidebar's own logo also puts two lockups of different heights in one header, which is what visibly skews the sidebar's top edge against the topbar's."
+  ]
+}

package/agent/components/OverlayPortalProvider.json

@@ -0,0 +1,42 @@
+{
+  "example": "import { OverlayPortalProvider } from \"@godxjp/ui/app\";\n\n// The React root lives inside a shadow root, so every overlay must portal there too.\nconst shadowRoot = host.attachShadow({ mode: \"open\" });\n\n<OverlayPortalProvider container={shadowRoot}>\n  <AppProvider defaultLocale=\"ja\">{children}</AppProvider>\n</OverlayPortalProvider>",
+  "group": "providers",
+  "importPath": "@godxjp/ui/app",
+  "name": "OverlayPortalProvider",
+  "props": [
+    {
+      "description": "The element overlays render into — pass the shadow root, or any element inside it. `undefined` restores the document.body default, so a subtree can opt back out.",
+      "name": "container",
+      "required": true,
+      "type": "Element | undefined"
+    },
+    {
+      "description": "The subtree whose overlays are relocated.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "AppProvider — the other root-level provider (locale, timezone, theme axes). Both are mounted once at the root; neither replaces the other.",
+    "Popover — one of the overlays this provider relocates; its own `container` has no prop equivalent.",
+    "Dialog — likewise portals to document.body unless this provider names another container."
+  ],
+  "rules": [
+    5
+  ],
+  "storyPath": "app/OverlayPortalProvider.stories.tsx",
+  "tagline": "Moves EVERY overlay in this library (Popover, Dialog, Sheet, Tooltip, DropdownMenu, HoverCard, Select, Cascader) into a container you name — the one thing an app mounted inside a SHADOW ROOT cannot do with props.",
+  "usage": [
+    "DO mount it when this library is rendered inside a shadow root (an embedded bar, a widget injected into a host page, a Web Component wrapper). Overlays default to document.body, which is outside the tree carrying this library's stylesheet — measured on an embedded bar as border 0, radius 0, a transparent background and the anchor maths 40px off.",
+    "DO wrap the whole embedded subtree ONCE, the same way AppProvider is mounted once. Where overlays render is a fact about the tree, not about any one control, and a component that owns its own overlay (AppLauncher) has no prop a consumer could reach it through.",
+    "DO expect it to fix DISMISSAL and FOCUS too, not just paint: mounting it switches react-aria onto its shadow-DOM code paths, without which the click that opened an overlay reads as a click outside it (an embedded launchpad that opened and shut on one press) and a focus scope believes focus never entered the dialog.",
+    "DON'T mount it on an ordinary page. document.body is the right destination there, and the provider is not a styling knob — it changes nothing you would want changed outside a shadow root.",
+    "DON'T look for a per-overlay container prop instead. There is none by design; a consumer asked to remember six of them gets five right."
+  ],
+  "useCases": [
+    "A GoDX bar or launchpad injected into a third-party page inside a shadow root, where its Popover and DropdownMenu must stay styled and dismissable.",
+    "A Web Component wrapper around an app built with this library, mounting the React tree in its own shadow DOM.",
+    "A widget embedded in a host that happens to load this library too — the case where the default is not obviously broken, only subtly wrong, until the first host that does not load it."
+  ]
+}