@godxjp/ui 28.12.0 → 29.0.0

package/agent/components/Select.json

@@ -371,6 +371,7 @@
   "usage": [
     "DO use the data-driven API (options/loadOptions) for straightforward selects — it handles grouping, search, async, and custom rendering automatically. Only reach for the compound API when you need to inject arbitrary content into the trigger or listbox.",
     "DO pass name= on the data-driven Select so the value is submitted with a native form or Inertia useForm. Without name= the value is React-only and will not appear in form data.",
+    "NAMING A SELECT WITH NO VISIBLE LABEL: put `aria-label` on `<Select>`, NOT on `<SelectTrigger>`. Both render the identical button attribute — Select forwards its name down through SelectFieldA11yContext and the trigger writes last — but only the root spelling also names the react-aria field, and a root that cannot see a name warns once per render (gh#869). Inside a FormField or Field, pass nothing: the label id reaches both levels on its own. `aria-labelledby` pointing at your own element works on either level and is the right spelling when a visible heading already names the control.",
     "READING THE SELECTED CODE FROM THE DOM: the trigger publishes `data-value` = the selected VALUE, alongside the `data-field` key it inherits from FormField. Use that in e2e tests and screen automation — the trigger's visible text is the option LABEL (東京本社), and the only other place the code lives is the aria-hidden, 1px-clipped native <select> react-aria renders so a native submit (and browser autofill) carries the value. `data-value` is absent while nothing is selected, and it tracks uncontrolled picks too.",
     "DO use loadOptions + selectedLabel together for async selects: selectedLabel prevents a flash of the raw id string while the first page loads.",
     "A Select is safe inside a draggable element (a Kanban card with draggable=true) and inside a `contain: paint` / `transform` app region: the aria-hidden native <select> fallback is held at its static position beside the trigger (position: absolute, 1px clipped), so the browser's drag image stays the card's own box instead of reaching to the region's corner (gh#708). No wrapper or consumer CSS is needed.",

package/agent/components/ServiceRolePanel.json

@@ -56,6 +56,11 @@
       "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"
+    },
+    {
+      "description": "DOM id on the panel root — the two-region MasterDetail wrapper, not the rail or the detail. It is the handle for a deep link onto the roles panel of a settings page, and for an E2E selector that must survive `masterLabel` being localized.",
+      "name": "id",
+      "type": "string"
     }
   ],
   "related": [

package/agent/components/Sidebar.json

@@ -1,5 +1,5 @@
 {
-  "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",
+  "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 SidebarSectionProp } 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: SidebarSectionProp[] = [\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",

package/agent/components/Switch.json

@@ -47,6 +47,12 @@
       "name": "id",
       "type": "string"
     },
+    {
+      "defaultValue": "false",
+      "description": "ANNOUNCES the requirement; it does not enforce it. react-aria's Switch omits `isRequired`, and a switch is never the target of native constraint validation in this library, so this writes `aria-required=\"true\"` onto the real input and stops there. The form layer (FormField / your schema) still owns whether an unflipped switch blocks submit — pairing this with nothing that validates is how a screen reader ends up promising a check the form never makes.",
+      "name": "required",
+      "type": "boolean"
+    },
     {
       "defaultValue": "false",
       "description": "Disable the toggle.",

package/agent/components/Table.json

@@ -56,15 +56,20 @@
       "name": "striped",
       "type": "boolean"
     },
+    {
+      "description": "On TableRow (gh#876): the row's STATE — a leading-edge rail plus a weak wash, the SAME six tones and meanings `DataTable rowTone` already paints. Writes `data-tone`, the attribute the paint is keyed on — `<TableRow data-tone=\"warning\">` still works unchanged, `tone` is just the typed, discoverable route to it. Never the only signal (WCAG 1.4.1): keep the reason in a cell (a Badge, a status column) and let the rail make that cell findable. DO NOT reach for a `bg-<status>/…` utility on a TableRow instead — that bypasses the token-owned wash and the theme can no longer retune it (gh#872).",
+      "name": "tone",
+      "type": "\"primary\" | \"success\" | \"warning\" | \"info\" | \"attention\" | \"destructive\""
+    },
     {
       "defaultValue": "\"default\"",
-      "description": "Named collection contract. \"default\" emits no attribute and keeps the plain table. \"action-collection\" is the canonical dense approval/action queue: the desktop INTRINSIC column widths (which make a five-column queue wider than its card and force a horizontal scroll at 390) are replaced by table-layout: fixed plus the token-owned column PRIORITY measures (--table-action-collection-*), and cells wrap. Mark each column with `priority` on its TableHead AND its TableCell. Semantics are untouched — no display change, no role rewriting, no card transformation — so header association, aria-sort and screen-reader table navigation are identical at 390 and 1440.",
+      "description": "Named collection contract. \"default\" emits no attribute and keeps the plain table. \"action-collection\" is the canonical dense approval/action queue: the desktop INTRINSIC column widths (which make a five-column queue wider than its card and force a horizontal scroll at 390) are replaced by table-layout: fixed plus the token-owned column PRIORITY measures (--table-action-collection-*), and cells wrap. Mark each column with `priority` on its TableHead AND its TableCell. Semantics are untouched — no display change, no role rewriting, no card transformation — so header association, aria-sort and screen-reader table navigation are identical at 390 and 1440. \"stacked-record-collection\" is the other direction, for a WIDE, HETEROGENEOUS record set with no sensible narrow column measure: below collapseBelow the <thead> hides and every <tr> becomes a bordered key-value card (--table-stacked-collection-*). Give each TableCell a `label` — its column header — because the <th> association it normally reads from is the thing that just went away; DataTable derives that label from ColumnDef.header for you (gh#864). The label is aria-hidden and the real <th> stays in the DOM, so the accessible name and table navigation are unchanged.",
       "name": "preset",
-      "type": "\"default\" | \"action-collection\""
+      "type": "\"default\" | \"action-collection\" | \"stacked-record-collection\""
     },
     {
       "defaultValue": "\"sm\"",
-      "description": "Step at which preset=\"action-collection\" switches to the compact priority measures, measured against the TABLE'S OWN container (a container query), not the viewport — a table inside a master rail collapses before the page does. Ignored while preset is \"default\".",
+      "description": "Step at which preset=\"action-collection\" switches to the compact priority measures, or preset=\"stacked-record-collection\" folds its rows into cards. Measured against the TABLE'S OWN container (a container query), not the viewport — a table inside a master rail collapses before the page does. Ignored while preset is \"default\".",
       "name": "collapseBelow",
       "type": "\"sm\" | \"md\" | \"lg\" | \"xl\""
     },

package/agent/components/Tabs.json

@@ -116,6 +116,16 @@
       "description": "Ant Design `onTabScroll`, fired whenever the trigger strip's own scrollport moves — a swipe, a wheel, or the component re-pinning the active trigger (antd reports its own re-pins too). LOGICAL VALUES instead of antd's `left | right | top | bottom`: two of those four are just the other axis of the same event, and upstream's pair is read off the sign of an inner transform, so in an RTL strip its `left` means the opposite of what it means in LTR. `start`/`end` say the same thing on whichever axis and in whichever direction the strip is written. Only fires for the `items` API, which is the path that owns the strip element.",
       "name": "onTabScroll",
       "type": "(info: { direction: \"start\" | \"end\" }) => void"
+    },
+    {
+      "description": "Class on the TRIGGER STRIP (`TabsList`) under the `items` API — the handle that composing the tree manually gives you as `<TabsList className>`. `className` reaches only the root, which holds the strip AND the panels, so anything meant for the bar alone belongs here. Almost always unnecessary: placement, size, centring and the card rail are props and `--tabs-*` tokens.",
+      "name": "listClassName",
+      "type": "string"
+    },
+    {
+      "description": "Class on EVERY panel (`TabsContent`) under the `items` API. It is written so it can WIN: the joined card body travels to CSS as `data-bodied` on the root rather than as a class, precisely so a consumer class on the panel is not fighting a utility the component already claimed (gh#762). Reach for the `bodied` prop and the `--tabs-panel-*` tokens first — this is for the geometry no token exposes.",
+      "name": "contentClassName",
+      "type": "string"
     }
   ],
   "related": [

package/agent/components/ThemeScope.json

@@ -0,0 +1,49 @@
+{
+  "example": "import { ThemeScope, tenantTheme } from \"@godxjp/ui/app\";\n\n// The customer's colour on one region — and on every overlay that region opens.\n<ThemeScope style={tenantTheme(customer.brandHex).vars} data-tenant={customer.slug}>\n  <Dialog>\n    <DialogTrigger asChild><Button>Review</Button></DialogTrigger>\n    <DialogContent><DialogTitle>Review</DialogTitle></DialogContent>\n  </Dialog>\n</ThemeScope>",
+  "group": "providers",
+  "importPath": "@godxjp/ui/app",
+  "name": "ThemeScope",
+  "props": [
+    {
+      "description": "The themed region. Overlays opened anywhere below it follow its tokens.",
+      "name": "children",
+      "required": true,
+      "type": "ReactNode"
+    },
+    {
+      "description": "Classes on the scope element — this is where `dark` goes when a REGION is dark rather than the whole page.",
+      "name": "className",
+      "required": false,
+      "type": "string"
+    },
+    {
+      "description": "DOM id of the scope element.",
+      "name": "id",
+      "required": false,
+      "type": "string"
+    }
+  ],
+  "related": [
+    "OverlayPortalProvider — the other half of the same statement: it decides WHERE an overlay lands, ThemeScope decides which TOKENS it inherits there. They compose; a ThemeScope inside one hosts itself in that container.",
+    "tenantTheme — the function that turns a customer hex into the declarations you put ON a ThemeScope (`style={tenantTheme(hex).vars}`). It computes the colours; ThemeScope is what carries them past the portal boundary.",
+    "AppProvider — page-level theme axes (theme/brand/density/fontSize). Use it for the whole app; ThemeScope is for one region that differs from it."
+  ],
+  "rules": [
+    5
+  ],
+  "storyPath": "app/ThemeScope.stories.tsx",
+  "tagline": "Makes a themed REGION reach the overlays it opens. Every overlay portals to document.body, so custom-property inheritance stops at the portal boundary and a tenant-themed region's Dialog, Select listbox, Popover and Toast paint the package defaults. Wrap the region in ThemeScope and they carry the region's tokens.",
+  "usage": [
+    "DO wrap the region, then theme it the way you already do — `style={tenantTheme(hex).vars}`, `data-tenant=\"acme\"`, `className=\"dark\"`, or a stylesheet rule that never mentions React. ThemeScope reads the COMPUTED tokens at its own element, so all of those paths behave identically; it has no theme prop and needs none.",
+    "DO nest it. An inner ThemeScope inside an outer one wins for the overlays opened below it, because its scope already inherits the outer's tokens and it diffs against the document root.",
+    "DO mount it inside an OverlayPortalProvider when you have one. It puts its host INSIDE that container, so a shadow-rooted app can be tenant-themed as well — the two providers compose rather than compete.",
+    "DON'T reach for `OverlayPortalProvider container={themedWrapper}` to solve this. It works until the wrapper sits inside an `overflow: hidden`, a `transform` or a `contain` ancestor, and then the region clips its own overlays — a colour bug traded for a layout bug that is harder to see. `container` stays for the shadow-DOM case it was built for.",
+    "DON'T expect it on a page with no scoped theme. With nothing themed it carries nothing, and with no ThemeScope at all every overlay behaves exactly as before.",
+    "DON'T assume a CLASS-keyed rule travels. What crosses the boundary is the custom-property delta — the tokens. A rule written as `.dark .my-thing { background: #111 }` in app CSS is not a token and does not follow the overlay."
+  ],
+  "useCases": [
+    "A multi-tenant screen where one region wears a customer's brand colour from `tenantTheme(hex)` — the button was already right, and this is what makes the dialog it opens right too.",
+    "A dark region on a light page (a preview pane, an editor canvas): `className=\"dark\"` on the region, and its Select listbox and Popover stay dark instead of flashing the page's light popover surface.",
+    "A `[data-tenant]` theme written entirely in the consumer's own stylesheet, with no React theming provider anywhere — the documented way to theme a region in this package, and the case the design was chosen to cover."
+  ]
+}

package/agent/components/TimeRangePicker.json

@@ -30,6 +30,11 @@
       "name": "allowEmpty",
       "type": "[boolean,boolean]"
     },
+    {
+      "description": "A PAIR, one per endpoint — TimePicker's single-string `placeholder` is omitted from this type on purpose, because a range has two empty fields and one string would label both of them the same. Route both through t().",
+      "name": "placeholder",
+      "type": "[string,string]"
+    },
     {
       "description": "Native names are name_from and name_to.",
       "name": "name",

package/agent/components/Topbar.json

@@ -68,6 +68,7 @@
     "DO compose the bar yourself: a brand mark (an `Avatar`) + sidebar toggle in `start`, a search trigger in `center`, settings pickers + notifications + user menu in `end`. The shell only positions; it never decides WHICH controls exist.",
     "DO build the sidebar toggle as a `TopbarItem` with a `PanelLeftClose`/`PanelLeftOpen` icon and your own `t()` aria-label, wired to AppShell's `sidebarCollapsed`. There is no baked toggle — but there IS a bar CELL, and it is not a Button: a Button in a slot is a --control-height pill floating in a taller bar, with its own hover fill and a ring drawn around the pill instead of the cell. The same holds for the notifications bell and the account trigger.",
     "DO put a locale/theme switcher in `end` using `AppSettingPicker` (or your own control) — icon-only vs labelled, bordered vs not, is THAT component's prop, not Topbar's. Topbar does not ship or force a language picker.",
+    "DON'T wrap two+ TopbarItems in a `<Flex>` to group them in one slot (gh#883) — the slot is already a flex line with its own gap, and a `<Flex>` wrapper collapses to 16px and takes every item inside it down with it. Use a fragment (`<>…</>`, no DOM node) or pass an array instead; see TopbarItem's own DON'T for the measured before/after.",
     "DON'T look for `product`/`project`/`onSearchOpen`/`onNotificationsOpen`/`collapsed` props — they were removed. A chrome control only exists if YOU put it in a slot, so there is never a dead dropdown / empty search with nothing behind it.",
     "DO render Topbar inside `AppShell`'s `topbar` slot (or any `<header>`). For a non-three-cluster layout, pass `children` and lay it out yourself.",
     "DO decide, explicitly, what happens to the `center` slot at 1100px and below. It is REMOVED there by default (`--topbar-center-compact-display: none`) so it cannot cover the start or end clusters when a 16rem sidebar is docked — which also means a global search trigger in `center` is gone on tablets AND phones. This default arrived in 18.6.0 and changed behaviour for consumers who touched nothing but their lockfile. If your center content already has a compact presentation (an icon-only search trigger), opt back in globally with `:root { --topbar-center-compact-display: flex; }`; if it does not, move the trigger into `end` for compact widths. Never re-create either behaviour with a page-local media query.",

package/agent/components/TopbarItem.json

@@ -69,7 +69,8 @@
     "DO wrap it in a DropdownMenuTrigger asChild for a user menu; the open state lights the cell via [data-state=open].",
     "DON'T set a height: the cell stretches to whatever the bar is (AppShell's grid row, --topbar-height, or the coarse-pointer bar), which is why there is no height knob.",
     "DO collapse a cell by breakpoint with its own props, never by hand-wrapping the glyph: `<TopbarItem asChild icon={<Target />} labelHideBelow=\"sm\"><a href=\"/goals\">Goals</a></TopbarItem>` replaces `<Flex hideFrom=\"sm\"><Icon as={Target} size=\"md\" /></Flex>` — icon-only below sm, the label still the accessible name. Add `iconHideFrom` for a label-only cell from a step up (gh#726).",
-    "DON'T reach for it outside a Topbar — a full-bleed cell needs a bar to bleed to. Use Button anywhere else."
+    "DON'T reach for it outside a Topbar — a full-bleed cell needs a bar to bleed to. Use Button anywhere else.",
+    "DON'T wrap two or more TopbarItems in a `<Flex>` to place them together in one slot (gh#883) — a `<Flex>` is a REAL element with `align-self: auto` by default, so it sits between the item and the slot, collapses to its own content height, and every item inside it stretches only to THAT (measured: a 47px bar down to 16px). The slot (`.ui-topbar-start`/`-center`/`-end`) is already a flex line with its own `gap`, so it needs no wrapper at all: put a JSX FRAGMENT `<>…</>` around the items (renders no DOM node, so each item is still the slot's DIRECT child) or pass an array — `end={[<TopbarItem key=\"notifications\" …/>, <TopbarItem key=\"account\" …/>]}` — either way every item keeps its own `align-self: stretch` reaching the real bar height. Reach for `<Flex>` there only when you deliberately want the group NOT full height (rare in a topbar)."
   ],
   "useCases": [
     "Account / user-menu trigger in the topbar end slot",

package/agent/components/Transfer.json

@@ -1,5 +1,5 @@
 {
-  "example": "import { useState } from \"react\";\nimport { Transfer } from \"@godxjp/ui/data-entry\";\n\nconst ALL_ACCOUNTS = [\n  { value: \"1010\", title: \"Cash\", description: \"Asset\" },\n  { value: \"1020\", title: \"Accounts Receivable\", description: \"Asset\" },\n  { value: \"2010\", title: \"Accounts Payable\", description: \"Liability\" },\n  { value: \"3010\", title: \"Revenue\", description: \"Income\" },\n  { value: \"4010\", title: \"Cost of Goods Sold\", description: \"Expense\", disabled: true },\n];\n\nexport function AccountMapping() {\n  const [targetKeys, setTargetKeys] = useState<string[]>([\"1010\"]);\n\n  return (\n    <Transfer\n      dataSource={ALL_ACCOUNTS}\n      targetKeys={targetKeys}\n      onValueChange={(nextKeys) => setTargetKeys(nextKeys)}\n      titles={[\"Available Accounts\", \"Mapped Accounts\"]}\n      showSearch\n    />\n  );\n}",
+  "example": "import { useState } from \"react\";\nimport { Transfer } from \"@godxjp/ui/data-entry\";\n\nconst ALL_ACCOUNTS = [\n  { key: \"1010\", title: \"Cash\", description: \"Asset\" },\n  { key: \"1020\", title: \"Accounts Receivable\", description: \"Asset\" },\n  { key: \"2010\", title: \"Accounts Payable\", description: \"Liability\" },\n  { key: \"3010\", title: \"Revenue\", description: \"Income\" },\n  { key: \"4010\", title: \"Cost of Goods Sold\", description: \"Expense\", disabled: true },\n];\n\nexport function AccountMapping() {\n  const [targetKeys, setTargetKeys] = useState<string[]>([\"1010\"]);\n\n  return (\n    <Transfer\n      dataSource={ALL_ACCOUNTS}\n      targetKeys={targetKeys}\n      onValueChange={(nextKeys) => setTargetKeys(nextKeys)}\n      titles={[\"Available Accounts\", \"Mapped Accounts\"]}\n      showSearch\n    />\n  );\n}",
   "group": "data-entry",
   "importPath": "@godxjp/ui/data-entry",
   "name": "Transfer",
@@ -94,6 +94,11 @@
       "name": "className",
       "type": "string"
     },
+    {
+      "description": "Lands on the `role=\"group\"` shuttle container, not on any one input — a two-pane shuttle has no single labelable control, so this is what a FormField label points at. FormField injects it; pass it yourself only for a bare Transfer.",
+      "name": "id",
+      "type": "string"
+    },
     {
       "description": "Controlled selection state as a tuple: index 0 = keys checked in the source panel, index 1 = keys checked in the target panel. Omit to use internal (uncontrolled) selection state. Must be paired with `onSelectChange` when provided.",
       "name": "selectedKeys",

package/agent/components/TreeSelect.json

@@ -1,5 +1,5 @@
 {
-  "example": "import { useState } from \"react\";\nimport { FormField, TreeSelect } from \"@godxjp/ui/data-entry\";\n\nconst accountTree = [\n  {\n    value: \"assets\",\n    label: \"Assets\",\n    content: [\n      { value: \"current-assets\", label: \"Current Assets\", content: [\n          { value: \"cash\", label: \"Cash\" },\n          { value: \"ar\", label: \"Accounts Receivable\" },\n        ],\n      },\n      { value: \"fixed-assets\", label: \"Fixed Assets\", content: [\n          { value: \"equipment\", label: \"Equipment\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"liabilities\",\n    label: \"Liabilities\",\n    content: [\n      { value: \"ap\", label: \"Accounts Payable\" },\n    ],\n  },\n];\n\n// Single-select (returns string | undefined)\nexport function AccountPicker() {\n  const [account, setAccount] = useState<string | undefined>();\n  return (\n    <FormField id=\"account-picker\" label=\"GL Account\">\n      <TreeSelect\n        id=\"account-picker\"\n        treeData={accountTree}\n        value={account}\n        onValueChange={(v) => setAccount(v as string | undefined)}\n        showSearch\n        treeDefaultExpandAll\n        placeholder=\"Select account…\"\n        allowClear\n      />\n    </FormField>\n  );\n}\n\n// Multi-select with checkboxes + cascade + SHOW_PARENT display\nexport function DepartmentFilter() {\n  const [selected, setSelected] = useState<string[]>([]);\n  return (\n    <TreeSelect\n      id=\"dept-filter\"\n      treeData={accountTree}\n      value={selected}\n      onValueChange={(v) => setSelected(v as string[])}\n      treeCheckable\n      showCheckedStrategy={TreeSelect.SHOW_PARENT}\n      showSearch\n      placeholder=\"Filter by department…\"\n    />\n  );\n}",
+  "example": "import { useState } from \"react\";\nimport { FormField, TreeSelect } from \"@godxjp/ui/data-entry\";\n\nconst accountTree = [\n  {\n    value: \"assets\",\n    label: \"Assets\",\n    children: [\n      { value: \"current-assets\", label: \"Current Assets\", children: [\n          { value: \"cash\", label: \"Cash\" },\n          { value: \"ar\", label: \"Accounts Receivable\" },\n        ],\n      },\n      { value: \"fixed-assets\", label: \"Fixed Assets\", children: [\n          { value: \"equipment\", label: \"Equipment\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"liabilities\",\n    label: \"Liabilities\",\n    children: [\n      { value: \"ap\", label: \"Accounts Payable\" },\n    ],\n  },\n];\n\n// Single-select (returns string | undefined)\nexport function AccountPicker() {\n  const [account, setAccount] = useState<string | undefined>();\n  return (\n    <FormField id=\"account-picker\" label=\"GL Account\">\n      <TreeSelect\n        id=\"account-picker\"\n        treeData={accountTree}\n        value={account}\n        onValueChange={(v) => setAccount(v as string | undefined)}\n        showSearch\n        treeDefaultExpandAll\n        placeholder=\"Select account…\"\n        allowClear\n      />\n    </FormField>\n  );\n}\n\n// Multi-select with checkboxes + cascade + SHOW_PARENT display\nexport function DepartmentFilter() {\n  const [selected, setSelected] = useState<string[]>([]);\n  return (\n    <TreeSelect\n      id=\"dept-filter\"\n      treeData={accountTree}\n      value={selected}\n      onValueChange={(v) => setSelected(v as string[])}\n      treeCheckable\n      showCheckedStrategy={TreeSelect.SHOW_PARENT}\n      showSearch\n      placeholder=\"Filter by department…\"\n    />\n  );\n}",
   "group": "data-entry",
   "importPath": "@godxjp/ui/data-entry",
   "name": "TreeSelect",

package/agent/components/Upload.json

@@ -67,6 +67,11 @@
       "name": "className",
       "type": "string"
     },
+    {
+      "description": "Lands on the native `<input type=\"file\">`, NOT on the wrapper — the hidden input is the semantic focus target, so this is what makes a `<label htmlFor>` (or FormField, which injects it) actually focus the picker. Putting it on the visible dropzone instead is the usual reason a label click does nothing.",
+      "name": "id",
+      "type": "string"
+    },
     {
       "description": "Custom button label for variant='button'. Falls back to the i18n 'Upload file' string.",
       "name": "children",

package/agent/components/UploadCropDialog.json

@@ -1,5 +1,5 @@
 {
-  "example": "{`import { useState } from \"react\";\nimport { UploadCropDialog } from \"@godxjp/ui/upload\"; // internal — prefer Upload variant=\"avatar-crop\" instead\n\nexport function AvatarField() {\n  const [cropFile, setCropFile] = useState<File | null>(null);\n\n  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {\n    const file = e.target.files?.[0] ?? null;\n    setCropFile(file);\n    e.target.value = \"\"; // reset so re-selecting same file fires onChange\n  };\n\n  const handleConfirm = (cropped: File) => {\n    // cropped is always image/jpeg 256×256\n    const form = new FormData();\n    form.append(\"avatar\", cropped);\n    fetch(\"/api/avatar\", { method: \"POST\", body: form });\n  };\n\n  return (\n    <>\n      <input type=\"file\" accept=\"image/*\" onValueChange={handleFileChange} />\n      <UploadCropDialog\n        open={cropFile !== null}\n        onOpenChange={(open) => { if (!open) setCropFile(null); }}\n        file={cropFile}\n        onConfirm={handleConfirm}\n      />\n    </>\n  );\n}`}",
+  "example": "{`import { useState } from \"react\";\nimport { UploadCropDialog } from \"@godxjp/ui/data-entry\"; // internal — prefer Upload variant=\"avatar-crop\" instead\n\nexport function AvatarField() {\n  const [cropFile, setCropFile] = useState<File | null>(null);\n\n  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {\n    const file = e.target.files?.[0] ?? null;\n    setCropFile(file);\n    e.target.value = \"\"; // reset so re-selecting same file fires onChange\n  };\n\n  const handleConfirm = (cropped: File) => {\n    // cropped is always image/jpeg 256×256\n    const form = new FormData();\n    form.append(\"avatar\", cropped);\n    fetch(\"/api/avatar\", { method: \"POST\", body: form });\n  };\n\n  return (\n    <>\n      <input type=\"file\" accept=\"image/*\" onChange={handleFileChange} />\n      <UploadCropDialog\n        open={cropFile !== null}\n        onOpenChange={(open) => { if (!open) setCropFile(null); }}\n        file={cropFile}\n        onConfirm={handleConfirm}\n      />\n    </>\n  );\n}`}",
   "group": "data-entry",
   "importPath": "@godxjp/ui/data-entry",
   "name": "UploadCropDialog",

package/agent/components/formatDate.json

@@ -1,7 +1,7 @@
 {
   "example": "import { formatDate } from \"@godxjp/ui/datetime\";\n\nformatDate(coupon.validFrom);                       // \"2026-05-01\"\nformatDate(order.createdAt, { kind: \"relative\" });  // \"3日前\"",
   "group": "providers",
-  "importPath": "@godxjp/ui/app",
+  "importPath": "@godxjp/ui/datetime",
   "name": "formatDate",
   "props": [
     {

package/agent/components-index.json

@@ -482,6 +482,11 @@
     "name": "OverlayPortalProvider",
     "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."
   },
+  {
+    "group": "providers",
+    "name": "ThemeScope",
+    "tagline": "Makes a themed REGION reach the overlays it opens. Every overlay portals to document.body, so custom-property inheritance stops at the portal boundary and a tenant-themed region's Dialog, Select listbox, Popover and Toast paint the package defaults. Wrap the region in ThemeScope and they carry the region's tokens."
+  },
   {
     "group": "providers",
     "name": "formatDate",