@godxjp/ui 28.13.0 → 30.0.0

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",

package/agent/components.json

@@ -1016,7 +1016,7 @@
     ]
   },
   {
-    "example": "import { AppShell, Sidebar } from \"@godxjp/ui/layout\";\nimport { LayoutDashboard, Users } from \"lucide-react\";\nimport { router } from \"@inertiajs/react\";\n\nconst sidebar = (\n  <Sidebar\n    activeId=\"/dashboard\"\n    onSelect={(id) => router.visit(id)}\n    sections={[{ items: [\n      { id: \"/dashboard\", label: \"ダッシュボード\", icon: LayoutDashboard },\n      { id: \"/users\", label: \"ユーザー\", icon: Users },\n    ] }]}\n    product={{ name: \"JOVY CRM\", role: \"本部\", color: \"var(--color-primary)\" }}\n  />\n);\n\nexport function CrmLayout({ children }: { content: React.ReactNode }) {\n  return <AppShell sidebar={sidebar}>{children}</AppShell>;\n}",
+    "example": "import { AppShell, Sidebar } from \"@godxjp/ui/layout\";\nimport { LayoutDashboard, Users } from \"lucide-react\";\nimport { router } from \"@inertiajs/react\";\n\nconst sidebar = (\n  <Sidebar\n    activeId=\"/dashboard\"\n    onSelect={(id) => router.visit(id)}\n    sections={[{ items: [\n      { id: \"/dashboard\", label: \"ダッシュボード\", icon: LayoutDashboard },\n      { id: \"/users\", label: \"ユーザー\", icon: Users },\n    ] }]}\n    product={{ name: \"JOVY CRM\", role: \"本部\", color: \"var(--color-primary)\" }}\n  />\n);\n\nexport function CrmLayout({ children }: { children: React.ReactNode }) {\n  return <AppShell sidebar={sidebar}>{children}</AppShell>;\n}",
     "group": "layout",
     "importPath": "@godxjp/ui/layout",
     "name": "AppShell",
@@ -1422,7 +1422,7 @@
     ]
   },
   {
-    "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",
@@ -1609,6 +1609,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.",
@@ -1693,7 +1694,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",
@@ -1765,7 +1767,7 @@
     ]
   },
   {
-    "example": "import { MasterDetail } from \"@godxjp/ui/layout\";\n\n// Canonical: fluid list + fixed 320px detail rail (stacks below 40rem).\n<MasterDetail\n  masterLabel=\"Teams\"\n  detailLabel=\"Selected team\"\n  detailId=\"team-detail\"\n  master={<TeamTable onRowClick={select} detailId=\"team-detail\" />}\n>\n  <TeamDetail team={selected} />\n</MasterDetail>\n\n// Leading navigator rail instead.\n<MasterDetail rail=\"master\" railWidth=\"compact\" masterLabel=\"Categories\">\n  <SettingsForm />\n</MasterDetail>\n\n// A long real collection: bound the master so it scrolls in place and the detail\n// stays near the top of a stacked mobile page.\n<MasterDetail masterViewport=\"compact\" masterLabel=\"Members\" detailLabel=\"Selected member\">\n  <MemberDetail member={selected} />\n</MasterDetail>",
+    "example": "import { MasterDetail } from \"@godxjp/ui/layout\";\n\n// Canonical: fluid list + fixed 320px detail rail (stacks below 40rem).\n<MasterDetail\n  masterLabel=\"Teams\"\n  detailLabel=\"Selected team\"\n  detailId=\"team-detail\"\n  master={<TeamTable onRowClick={select} detailId=\"team-detail\" />}\n>\n  <TeamDetail team={selected} />\n</MasterDetail>\n\n// Leading navigator rail instead.\n<MasterDetail\n  rail=\"master\"\n  railWidth=\"compact\"\n  masterLabel=\"Categories\"\n  master={<CategoryNav activeId={activeCategory} onSelect={setActiveCategory} />}\n>\n  <SettingsForm />\n</MasterDetail>\n\n// A long real collection: bound the master so it scrolls in place and the detail\n// stays near the top of a stacked mobile page.\n<MasterDetail\n  masterViewport=\"compact\"\n  masterLabel=\"Members\"\n  detailLabel=\"Selected member\"\n  master={<MemberList onRowClick={select} />}\n>\n  <MemberDetail member={selected} />\n</MasterDetail>",
     "group": "layout",
     "importPath": "@godxjp/ui/layout",
     "name": "MasterDetail",
@@ -3290,7 +3292,7 @@
     "absorbed": [
       "DataGrid"
     ],
-    "example": "import { useState } from \"react\";\nimport { Badge, DataTable, type ColumnDef } from \"@godxjp/ui/data-display\";\nimport { EmptyState } from \"@godxjp/ui/data-display\";\n\ntype Invoice = {\n  id: string;\n  customer: string;\n  amount: number;\n  status: \"paid\" | \"pending\" | \"overdue\";\n};\n\nconst columns: ColumnDef<Invoice>[] = [\n  { key: \"id\", header: \"Invoice #\", width: \"w-32\" },\n  { key: \"customer\", header: \"Customer\" },\n  {\n    key: \"status\",\n    header: \"Status\",\n    render: (row) => (\n      <Badge\n        variant={\n          row.status === \"paid\" ? \"success\" : row.status === \"overdue\" ? \"destructive\" : \"secondary\"\n        }\n      >\n        {row.status}\n      </Badge>\n    ),\n  },\n  { key: \"amount\", header: \"Amount\", align: \"right\", sortable: true },\n];\n\nexport default function InvoiceList({\n  invoices,\n  loading,\n}: {\n  invoices: Invoice[];\n  loading: boolean;\n}) {\n  const [selected, setSelected] = useState<Set<string>>(new Set());\n  const [sort, setSort] = useState<{ key: string; direction: \"asc\" | \"desc\" } | undefined>();\n\n  return (\n    <DataTable\n      data={invoices}\n      columns={columns}\n      getRowId={(row) => row.id}\n      selectable\n      selected={selected}\n      onSelectChange={setSelected}\n      sort={sort}\n      onSortChange={setSort}\n      loading={loading}\n      empty={\n        <EmptyState\n          title=\"No invoices found\"\n          description=\"Adjust your filters or create a new invoice.\"\n        />\n      }\n    >\n      <DataTable.Toolbar>\n        <DataTable.BulkActions>\n          <button type=\"button\" onClick={() => setSelected(new Set())}>\n            Mark paid\n          </button>\n        </DataTable.BulkActions>\n        <DataTable.DensityToggle />\n      </DataTable.Toolbar>\n    </DataTable>\n  );\n}",
+    "example": "import { useState } from \"react\";\nimport { Badge, DataTable, type ColumnDef } from \"@godxjp/ui/data-display\";\nimport { EmptyState } from \"@godxjp/ui/data-display\";\n\ntype Invoice = {\n  id: string;\n  customer: string;\n  amount: number;\n  status: \"paid\" | \"pending\" | \"overdue\";\n};\n\nconst columns: ColumnDef<Invoice>[] = [\n  { key: \"id\", header: \"Invoice #\", width: \"w-32\" },\n  { key: \"customer\", header: \"Customer\" },\n  {\n    key: \"status\",\n    header: \"Status\",\n    render: (row) => (\n      <Badge\n        tone={\n          row.status === \"paid\" ? \"success\" : row.status === \"overdue\" ? \"destructive\" : \"warning\"\n        }\n      >\n        {row.status}\n      </Badge>\n    ),\n  },\n  { key: \"amount\", header: \"Amount\", align: \"right\", sortable: true },\n];\n\nexport default function InvoiceList({\n  invoices,\n  loading,\n}: {\n  invoices: Invoice[];\n  loading: boolean;\n}) {\n  const [selected, setSelected] = useState<Set<string>>(new Set());\n  const [sort, setSort] = useState<{ key: string; direction: \"asc\" | \"desc\" } | undefined>();\n\n  return (\n    <DataTable\n      data={invoices}\n      columns={columns}\n      getRowId={(row) => row.id}\n      selectable\n      selected={selected}\n      onSelectChange={setSelected}\n      sort={sort}\n      onSortChange={setSort}\n      loading={loading}\n      empty={\n        <EmptyState\n          title=\"No invoices found\"\n          description=\"Adjust your filters or create a new invoice.\"\n        />\n      }\n    >\n      <DataTable.Toolbar>\n        <DataTable.BulkActions>\n          <button type=\"button\" onClick={() => setSelected(new Set())}>\n            Mark paid\n          </button>\n        </DataTable.BulkActions>\n        <DataTable.DensityToggle />\n      </DataTable.Toolbar>\n    </DataTable>\n  );\n}",
     "group": "data-display",
     "importPath": "@godxjp/ui/data-display",
     "name": "DataTable",
@@ -3374,13 +3376,13 @@
       },
       {
         "defaultValue": "'default'",
-        "description": "Named collection contract — the SAME preset the Table primitive owns, forwarded to the table DataTable renders. 'default' emits NO attribute and matches no selector, so an existing DataTable is byte-identical. 'action-collection' is the canonical dense approval/action queue: below collapseBelow the desktop INTRINSIC column widths give way to the token-owned column-PRIORITY measures (--table-action-collection-*) under table-layout: fixed, cells wrap, and the bordered surface drops its --table-surface-min-inline-size floor — so requester · target · reason · requested date · row actions all stay inside a 390px frame with no horizontal scroll. Mark each column with `priority` on its ColumnDef. Semantics are untouched (no display change, no role rewriting, no card swap), so header association, aria-sort and screen-reader table navigation are identical at 390 and 1440. Measured: table 1182 / 766 / 388px at 1440 / 1024 / 390, document scrollWidth === clientWidth at every width, LTR and RTL.",
+        "description": "Named collection contract — the SAME preset the Table primitive owns, forwarded to the table DataTable renders. 'default' emits NO attribute and matches no selector, so an existing DataTable is byte-identical. 'action-collection' is the canonical dense approval/action queue: below collapseBelow the desktop INTRINSIC column widths give way to the token-owned column-PRIORITY measures (--table-action-collection-*) under table-layout: fixed, cells wrap, and the bordered surface drops its --table-surface-min-inline-size floor — so requester · target · reason · requested date · row actions all stay inside a 390px frame with no horizontal scroll. Mark each column with `priority` on its ColumnDef. Semantics are untouched (no display change, no role rewriting, no card swap), so header association, aria-sort and screen-reader table navigation are identical at 390 and 1440. Measured: table 1182 / 766 / 388px at 1440 / 1024 / 390, document scrollWidth === clientWidth at every width, LTR and RTL. 'stacked-record-collection' is the other direction, for a WIDE, HETEROGENEOUS record set that has no sensible narrow column measure: below collapseBelow the <thead> hides and every <tr> becomes a bordered key-value card (--table-stacked-collection-*). Each cell then carries its column's header inline above the value, DERIVED from the same ColumnDef.header the <th> uses — so the card cannot drift from the table, and a column with a deliberately empty header names itself with ariaLabel (gh#864). The labels are aria-hidden: the real <th> is still in the DOM and remains the accessible-name source, so screen-reader table navigation is unchanged at every width. Reach for this instead of building a parallel Card tree beside the table; two trees for one dataset means two sets of labels to keep in sync.",
         "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 on sm 40rem · md 48rem · lg 64rem · xl 80rem), 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 on sm 40rem · md 48rem · lg 64rem · xl 80rem), not the viewport — a table inside a master rail collapses before the page does, and the same table folds by the width it is GIVEN. Ignored while preset is 'default'.",
         "name": "collapseBelow",
         "type": "'sm' | 'md' | 'lg' | 'xl'"
       },
@@ -4232,7 +4234,7 @@
     ]
   },
   {
-    "example": "import { Card, CardContent, CardHeader, CardTitle, ListRow, Badge } from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { Smartphone } from \"lucide-react\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n// The three scenarios below are three CARDS on one page, so they are wrapped in a Flex — the gap\n// between sibling cards belongs to the stack, never to the cards (audit: sibling-cards-need-flex).\n<Flex direction=\"col\" gap=\"lg\">\n<Card>\n  <CardHeader>\n    <CardTitle>アクティブなセッション</CardTitle>\n  </CardHeader>\n  <CardContent flush>\n    <ListRow\n      leading={<Smartphone aria-hidden=\"true\" className=\"size-4\" />}\n      title=\"iPhone 15 · Tokyo\"\n      description=\"最終アクセス 2分前\"\n      trailing={<Badge status=\"active\" />}\n    />\n    <ListRow\n      leading={<Smartphone aria-hidden=\"true\" className=\"size-4\" />}\n      title=\"MacBook Pro · Osaka\"\n      description=\"最終アクセス 3日前\"\n      trailing={<Button size=\"xs\" variant=\"outline\">ログアウト</Button>}\n    />\n  </CardContent>\n</Card>\n\n// Notifications — unread dot + emphasized surface, wrapping title, two inline actions\n<Card>\n  <CardContent flush>\n    <ListRow\n      unread\n      align=\"start\"\n      overflow=\"wrap\"\n      title=\"組織「グローバル・トランスフォーメーション推進本部」への招待が届いています\"\n      description=\"2026-07-30 09:12 JST\"\n      trailing={\n        <>\n          <Button size=\"xs\" variant=\"ghost\">既読にする</Button>\n          <Button size=\"xs\" variant=\"outline\">開く</Button>\n        </>\n      }\n    />\n    <ListRow unread={false} align=\"start\" overflow=\"wrap\" title=\"請求書が発行されました\" description=\"2026-07-28 18:40 JST\" />\n  </CardContent>\n</Card>\n\n// A list of LINKS — `as=\"li\"` gives the list item, `asChild` gives the whole-row link,\n// and the item carries the divider. Never wrap the row in your own <li>, and never reach for a\n// raw <ul>: `marker=\"none\"` is the semantic list container (no bullet, no indent, gap token).\n<Card>\n  <CardContent flush>\n    <Flex as=\"ul\" marker=\"none\" direction=\"col\" gap=\"none\">\n      {projects.map((project) => (\n        <ListRow key={project.key} as=\"li\" asChild title={project.name} description={project.key}>\n          <Link href={`/projects/${project.key}`} />\n        </ListRow>\n      ))}\n    </Flex>\n  </CardContent>\n</Card>\n</Flex>",
+    "example": "import { Card, CardContent, CardHeader, CardTitle, ListRow, Badge } from \"@godxjp/ui/data-display\";\nimport { Button } from \"@godxjp/ui/general\";\nimport { Smartphone } from \"lucide-react\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n// The three scenarios below are three CARDS on one page, so they are wrapped in a Flex — the gap\n// between sibling cards belongs to the stack, never to the cards (audit: sibling-cards-need-flex).\n<Flex direction=\"col\" gap=\"lg\">\n<Card>\n  <CardHeader>\n    <CardTitle>アクティブなセッション</CardTitle>\n  </CardHeader>\n  <CardContent flush>\n    <ListRow\n      leading={<Smartphone aria-hidden=\"true\" className=\"size-4\" />}\n      title=\"iPhone 15 · Tokyo\"\n      description=\"最終アクセス 2分前\"\n      trailing={<Badge status=\"active\" />}\n    />\n    <ListRow\n      leading={<Smartphone aria-hidden=\"true\" className=\"size-4\" />}\n      title=\"MacBook Pro · Osaka\"\n      description=\"最終アクセス 3日前\"\n      trailing={<Button size=\"xs\" variant=\"outline\">ログアウト</Button>}\n    />\n  </CardContent>\n</Card>\n\n// Notifications — unread dot + emphasized surface, wrapping title, two inline actions\n<Card>\n  <CardContent flush>\n    <ListRow\n      unread\n      align=\"start\"\n      overflow=\"wrap\"\n      title=\"組織「グローバル・トランスフォーメーション推進本部」への招待が届いています\"\n      description=\"2026-07-30 09:12 JST\"\n      trailing={\n        <>\n          <Button size=\"xs\" variant=\"ghost\">既読にする</Button>\n          <Button size=\"xs\" variant=\"outline\">開く</Button>\n        </>\n      }\n    />\n    <ListRow unread={false} align=\"start\" overflow=\"wrap\" title=\"請求書が発行されました\" description=\"2026-07-28 18:40 JST\" />\n  </CardContent>\n</Card>\n\n{/* A list of LINKS — `as=\"li\"` gives the list item, `asChild` gives the whole-row link, and the\n   item carries the divider. Never wrap the row in your own li, and never reach for a raw ul:\n   `marker=\"none\"` is the semantic list container (no bullet, no indent, gap token). */}\n<Card>\n  <CardContent flush>\n    <Flex as=\"ul\" marker=\"none\" direction=\"col\" gap=\"none\">\n      {projects.map((project) => (\n        <ListRow key={project.key} as=\"li\" asChild title={project.name} description={project.key}>\n          <Link href={`/projects/${project.key}`} />\n        </ListRow>\n      ))}\n    </Flex>\n  </CardContent>\n</Card>\n</Flex>",
     "group": "data-display",
     "importPath": "@godxjp/ui/data-display",
     "name": "ListRow",
@@ -5046,15 +5048,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\""
       },
@@ -5101,7 +5108,7 @@
     ]
   },
   {
-    "example": "import { DataState } from \"@godxjp/ui/query\";\n\n<DataState query={membersQuery} skeleton={<SkeletonTable />} isEmpty={(d) => d.items.length === 0} empty={<EmptyState title=\"会員なし\" />}>\n  {(d) => <MemberTable items={d.items} />}\n</DataState>",
+    "example": "import { useQuery } from \"@tanstack/react-query\";\nimport { DataState } from \"@godxjp/ui/query\";\n\ntype MembersPage = { items: { id: string; name: string }[] };\n\n// T flows from the query, so `d` is MembersPage in BOTH callbacks. If you find yourself\n// annotating them, the query is untyped — fix that, never write `(d: any)`.\nconst membersQuery = useQuery<MembersPage>({ queryKey: [\"members\"], queryFn: fetchMembers });\n\n<DataState query={membersQuery} skeleton={<SkeletonTable />} isEmpty={(d) => d.items.length === 0} empty={<EmptyState title=\"会員なし\" />}>\n  {(d) => <MemberTable items={d.items} />}\n</DataState>",
     "group": "data-display",
     "importPath": "@godxjp/ui/query",
     "name": "DataState",
@@ -5180,7 +5187,7 @@
     ]
   },
   {
-    "example": "import { InfiniteQueryState, flattenItemPages } from \"@godxjp/ui/query\";\n\n<InfiniteQueryState query={q} skeleton={<SkeletonRows />} flatten={flattenItemPages} isEmpty={(it) => it.length === 0}>\n  {(items) => items.map((a) => <ActivityRow key={a.id} activity={a} />)}\n</InfiniteQueryState>",
+    "example": "import { useInfiniteQuery } from \"@tanstack/react-query\";\nimport { InfiniteQueryState, flattenItemPages } from \"@godxjp/ui/query\";\n\ntype Activity = { id: string; label: string };\n\n// `flattenItemPages` constrains the page to `{ items: TItem[] }`, so the query must be typed:\n// an untyped one makes the page `unknown`, which cannot satisfy that constraint.\nconst q = useInfiniteQuery<{ items: Activity[]; cursor?: string }>({\n  queryKey: [\"activity\"],\n  queryFn: fetchActivityPage,\n  initialPageParam: undefined,\n  getNextPageParam: (last) => last.cursor,\n});\n\n<InfiniteQueryState query={q} skeleton={<SkeletonRows />} flatten={flattenItemPages} isEmpty={(it) => it.length === 0}>\n  {(items) => items.map((a) => <ActivityRow key={a.id} activity={a} />)}\n</InfiniteQueryState>",
     "group": "data-display",
     "importPath": "@godxjp/ui/query",
     "name": "InfiniteQueryState",
@@ -5325,7 +5332,7 @@
     ]
   },
   {
-    "example": "import { FormField, Input } from \"@godxjp/ui/data-entry\";\n\n<FormField id=\"coupon-name\" label=\"クーポン名\" required error={errors.name} helper=\"最大50文字\">\n  <Input id=\"coupon-name\" placeholder=\"春の花粉症対策15%OFF\" value={name} onValueChange={(e) => setName(e.target.value)} />\n</FormField>",
+    "example": "import { FormField, Input } from \"@godxjp/ui/data-entry\";\n\n<FormField id=\"coupon-name\" label=\"クーポン名\" required error={errors.name} helper=\"最大50文字\">\n  <Input id=\"coupon-name\" placeholder=\"春の花粉症対策15%OFF\" value={name} onValueChange={(v) => setName(v)} />\n</FormField>",
     "group": "data-entry",
     "importPath": "@godxjp/ui/data-entry",
     "name": "FormField",
@@ -5513,7 +5520,7 @@
     ]
   },
   {
-    "example": "import { Input } from \"@godxjp/ui/data-entry\";\n\n<Input id=\"qty\" type=\"number\" placeholder=\"例: 500\" value={value} onValueChange={(e) => setValue(e.target.value)} />",
+    "example": "import { Input } from \"@godxjp/ui/data-entry\";\n\n<Input id=\"qty\" type=\"number\" placeholder=\"例: 500\" value={value} onValueChange={(v) => setValue(v)} />",
     "group": "data-entry",
     "importPath": "@godxjp/ui/data-entry",
     "name": "Input",
@@ -6268,6 +6275,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.",
@@ -8372,9 +8380,58 @@
     ]
   },
   {
-    "example": "import { formatDate } from \"@godxjp/ui/datetime\";\n\nformatDate(coupon.validFrom);                       // \"2026-05-01\"\nformatDate(order.createdAt, { kind: \"relative\" });  // \"3日前\"",
+    "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."
+    ]
+  },
+  {
+    "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/datetime",
     "name": "formatDate",
     "props": [
       {
@@ -8618,7 +8675,7 @@
     ]
   },
   {
-    "example": "{`import { Cascader } from \"@godxjp/ui/data-entry\";\n\nconst REGIONS = [\n  {\n    value: \"jp\",\n    label: \"日本\",\n    content: [\n      {\n        value: \"tokyo\",\n        label: \"東京都\",\n        content: [\n          { value: \"shinjuku\", label: \"新宿区\" },\n          { value: \"shibuya\", label: \"渋谷区\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"vn\",\n    label: \"Việt Nam\",\n    content: [\n      {\n        value: \"hcm\",\n        label: \"TP. Hồ Chí Minh\",\n        content: [\n          { value: \"q1\", label: \"Quận 1\" },\n          { value: \"q3\", label: \"Quận 3\" },\n        ],\n      },\n    ],\n  },\n];\n\n// Controlled single-path\nfunction RegionPicker() {\n  const [path, setPath] = React.useState<string[]>([]);\n\n  return (\n    <Cascader\n      options={REGIONS}\n      value={path}\n      onValueChange={(v) => setPath(v as string[])}\n      showSearch\n      placeholder=\"Select region…\"\n    />\n  );\n}\n\n// Multi-path (multiple selection)\nfunction MultiRegionPicker() {\n  const [paths, setPaths] = React.useState<string[][]>([]);\n\n  return (\n    <Cascader\n      options={REGIONS}\n      multiple\n      value={paths}\n      onValueChange={(v) => setPaths(v as string[][])}\n      showSearch\n    />\n  );\n}\n\n// With custom field names (data uses 'name'/'id'/'nodes')\n<Cascader\n  options={rawApiData}\n  fieldNames={{ label: \"name\", value: \"id\", content: \"nodes\" }}\n  defaultValue={[\"dept-1\", \"team-3\"]}\n/>\n\n// changeOnSelect: lets user pick a branch node (not only leaves)\n<Cascader\n  options={REGIONS}\n  changeOnSelect\n  onValueChange={(v) => console.log(\"path\", v)}\n/>\n`}",
+    "example": "{`import { Cascader } from \"@godxjp/ui/data-entry\";\n\nconst REGIONS = [\n  {\n    value: \"jp\",\n    label: \"日本\",\n    children: [\n      {\n        value: \"tokyo\",\n        label: \"東京都\",\n        children: [\n          { value: \"shinjuku\", label: \"新宿区\" },\n          { value: \"shibuya\", label: \"渋谷区\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"vn\",\n    label: \"Việt Nam\",\n    children: [\n      {\n        value: \"hcm\",\n        label: \"TP. Hồ Chí Minh\",\n        children: [\n          { value: \"q1\", label: \"Quận 1\" },\n          { value: \"q3\", label: \"Quận 3\" },\n        ],\n      },\n    ],\n  },\n];\n\n// Controlled single-path\nfunction RegionPicker() {\n  const [path, setPath] = React.useState<string[]>([]);\n\n  return (\n    <Cascader\n      options={REGIONS}\n      value={path}\n      onValueChange={(v) => setPath(v as string[])}\n      showSearch\n      placeholder=\"Select region…\"\n    />\n  );\n}\n\n// Multi-path (multiple selection)\nfunction MultiRegionPicker() {\n  const [paths, setPaths] = React.useState<string[][]>([]);\n\n  return (\n    <Cascader\n      options={REGIONS}\n      multiple\n      value={paths}\n      onValueChange={(v) => setPaths(v as string[][])}\n      showSearch\n    />\n  );\n}\n\n// With custom field names (data uses 'name'/'id'/'nodes')\n<Cascader\n  options={rawApiData}\n  fieldNames={{ label: \"name\", value: \"id\", children: \"nodes\" }}\n  defaultValue={[\"dept-1\", \"team-3\"]}\n/>\n\n// changeOnSelect: lets user pick a branch node (not only leaves)\n<Cascader\n  options={REGIONS}\n  changeOnSelect\n  onValueChange={(v) => console.log(\"path\", v)}\n/>\n`}",
     "group": "data-entry",
     "importPath": "@godxjp/ui/data-entry",
     "name": "Cascader",
@@ -8832,7 +8889,7 @@
     ]
   },
   {
-    "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",
@@ -9064,7 +9121,7 @@
     ]
   },
   {
-    "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",
@@ -9436,7 +9493,7 @@
     ]
   },
   {
-    "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",
@@ -12028,7 +12085,7 @@
     ]
   },
   {
-    "example": "import { PasswordInput, PasswordStrength } from \"@godxjp/ui/data-entry\";\n\nconst rules = [\"length\", \"upper\", \"lower\", \"number\", \"symbol\"] as const;\n\nexport default function PasswordBlock() {\n  const [value, setValue] = useState(\"\");\n  return (\n    <div className=\"ui-stack\">\n      <PasswordInput value={value} onChange={(event) => setValue(event.target.value)} />\n      <PasswordStrength value={value} rules={rules} />\n    </div>\n  );\n}",
+    "example": "import { PasswordInput, PasswordStrength } from \"@godxjp/ui/data-entry\";\n\nexport default function PasswordBlock() {\n  const [value, setValue] = useState(\"\");\n  return (\n    <div className=\"ui-stack\">\n      <PasswordInput value={value} onChange={(event) => setValue(event.target.value)} />\n      <PasswordStrength value={value} rules={[\"length\", \"upper\", \"lower\", \"number\", \"symbol\"]} />\n    </div>\n  );\n}",
     "group": "data-entry",
     "importPath": "@godxjp/ui/data-entry",
     "name": "PasswordStrength",
@@ -12866,7 +12923,7 @@
         "type": "ChartDatum[]"
       },
       {
-        "description": "Plotted series: { dataKey, label?, color? }. Colour defaults to the --chart-1..6 palette.",
+        "description": "Plotted series: { dataKey, label?, color?, fillColor? }. Colour defaults to the --chart-1..6 palette; fillColor is the AreaChart band only.",
         "name": "series",
         "required": true,
         "type": "ChartSeriesProp[]"
@@ -12922,12 +12979,28 @@
         "name": "numberFormat",
         "type": "Intl.NumberFormatOptions"
       },
+      {
+        "description": "Explicit [min, max] for the VALUE axis (y vertical, x on a horizontal bar). Omit to let the data set it. A non-zero baseline is a charting-ETHICS call: legitimate where the SHAPE is the message and zero is not a reference (price, temperature, an index, a latency percentile), misleading wherever the reader compares magnitudes — which is every bar chart.",
+        "name": "valueDomain",
+        "type": "[number, number]"
+      },
+      {
+        "description": "Explicit tick positions on the value axis, in data units. Values outside valueDomain are not drawn.",
+        "name": "valueTicks",
+        "type": "number[]"
+      },
       {
         "defaultValue": "false",
         "description": "Render smooth (monotone) lines instead of straight segments.",
         "name": "curved",
         "type": "boolean"
       },
+      {
+        "defaultValue": "false",
+        "description": "Draw a marker at every data point. Off by default — markers crowd a dense series.",
+        "name": "showDots",
+        "type": "boolean"
+      },
       {
         "description": "Message shown when `data` is empty (defaults to a localized 'no data').",
         "name": "emptyMessage",
@@ -12948,7 +13021,9 @@
       "DO install the `recharts` optional peer dependency in the consuming app — charts are the only part of @godxjp/ui that needs it, so apps without charts never pay for it.",
       "DO pass an i18n'd `label` — it is both the visible caption and the accessible name; the component also emits a screen-reader list of the plotted values (WCAG 1.1.1).",
       "DO pre-translate each series' `label`; pass `numberFormat` (e.g. { style: 'currency', currency: 'JPY' }) and the axis/tooltip numbers localize automatically via Intl.",
-      "DON'T hand-roll an SVG/canvas chart or drop raw recharts into a page — LineChart owns the colour tokens, locale formatting, empty state, and accessibility wiring."
+      "DON'T hand-roll an SVG/canvas chart or drop raw recharts into a page — LineChart owns the colour tokens, locale formatting, empty state, and accessibility wiring.",
+      "DO retune the line weight and the grid dash with the `--chart-series-stroke-width` / `--chart-grid-line-dash` theme tokens, globally or on a scoped [data-tenant] region. They are house style; there is no prop for them.",
+      "DON'T reach for `valueDomain` to make a flat trend look dramatic — cropping the axis magnifies every wobble and the reader cannot tell a 2% drift from a collapse. Crop only where zero is not a meaningful reference, and say the range."
     ],
     "useCases": [
       "Revenue / KPI trend over months in a dashboard.",
@@ -12969,7 +13044,7 @@
         "type": "ChartDatum[]"
       },
       {
-        "description": "Plotted series: { dataKey, label?, color? }.",
+        "description": "Plotted series: { dataKey, label?, color?, fillColor? }. `fillColor` paints the filled band independently of the line's `color`; it defaults to `color`.",
         "name": "series",
         "required": true,
         "type": "ChartSeriesProp[]"
@@ -13025,6 +13100,16 @@
         "name": "numberFormat",
         "type": "Intl.NumberFormatOptions"
       },
+      {
+        "description": "Explicit [min, max] for the VALUE axis (y vertical, x on a horizontal bar). Omit to let the data set it. A non-zero baseline is a charting-ETHICS call: legitimate where the SHAPE is the message and zero is not a reference (price, temperature, an index, a latency percentile), misleading wherever the reader compares magnitudes — which is every bar chart.",
+        "name": "valueDomain",
+        "type": "[number, number]"
+      },
+      {
+        "description": "Explicit tick positions on the value axis, in data units. Values outside valueDomain are not drawn.",
+        "name": "valueTicks",
+        "type": "number[]"
+      },
       {
         "defaultValue": "false",
         "description": "Stack series into one bar instead of grouping side by side.",
@@ -13065,7 +13150,7 @@
     ]
   },
   {
-    "example": "import { CompactBarTrend } from \"@godxjp/ui/charts/compact-bar-trend\";\n\n<CompactBarTrend\n  label={t(\"dashboard.newOrganizations7d\")}\n  description={t(\"dashboard.newOrganizationsHint\")}\n  data={trend}\n  categoryKey=\"date\"\n  valueKey=\"count\"\n  emphasizedIndex={-1}\n  size=\"xs\"\n  footer={<Text size=\"xs\" tone=\"muted\">{t(\"dashboard.lastUpdated\", { at })}</Text>}\n/>",
+    "example": "import { CompactBarTrend } from \"@godxjp/ui/charts/compact-bar-trend\";\nimport { Text } from \"@godxjp/ui/general\";\n\n<CompactBarTrend\n  label={t(\"dashboard.newOrganizations7d\")}\n  description={t(\"dashboard.newOrganizationsHint\")}\n  data={trend}\n  categoryKey=\"date\"\n  valueKey=\"count\"\n  emphasizedIndex={-1}\n  size=\"xs\"\n  footer={<Text size=\"xs\" tone=\"muted\">{t(\"dashboard.lastUpdated\", { at: new Date().toISOString() })}</Text>}\n/>",
     "group": "data-display",
     "importPath": "@godxjp/ui/charts/compact-bar-trend",
     "name": "CompactBarTrend",
@@ -13240,12 +13325,28 @@
         "name": "stacked",
         "type": "boolean"
       },
+      {
+        "description": "Explicit [min, max] for the VALUE axis (y vertical, x on a horizontal bar). Omit to let the data set it. A non-zero baseline is a charting-ETHICS call: legitimate where the SHAPE is the message and zero is not a reference (price, temperature, an index, a latency percentile), misleading wherever the reader compares magnitudes — which is every bar chart.",
+        "name": "valueDomain",
+        "type": "[number, number]"
+      },
+      {
+        "description": "Explicit tick positions on the value axis, in data units. Values outside valueDomain are not drawn.",
+        "name": "valueTicks",
+        "type": "number[]"
+      },
       {
         "defaultValue": "false",
         "description": "Render smooth (monotone) areas instead of straight segments.",
         "name": "curved",
         "type": "boolean"
       },
+      {
+        "defaultValue": "false",
+        "description": "Draw a marker at every data point. Off by default — markers crowd a dense series.",
+        "name": "showDots",
+        "type": "boolean"
+      },
       {
         "description": "Message shown when `data` is empty.",
         "name": "emptyMessage",
@@ -13263,7 +13364,9 @@
       "DO import from the charts entry: `import { AreaChart } from \"@godxjp/ui/charts\";` (recharts optional peer required).",
       "DO import only the chart a screen uses — `import { AreaChart } from \"@godxjp/ui/charts/area-chart\";` — when the `./charts` barrel should not link the whole chart family. Without the `recharts` peer the build then fails ONCE, naming the package and the fix.",
       "DO use `stacked` to show how parts accumulate into a total over time.",
-      "DON'T overlay more than 2-3 unstacked areas — fill opacity makes dense overlays unreadable; switch to LineChart."
+      "DON'T overlay more than 2-3 unstacked areas — fill opacity makes dense overlays unreadable; switch to LineChart.",
+      "DO split the band's hue from the line's with `series[].fillColor` when a brand specifies both (a dark line over a lighter wash). The band's DENSITY is the `--chart-area-fill-alpha` theme token, not a prop.",
+      "DON'T tune the band by dropping a page-local CSS rule on `.recharts-area-area` — `--chart-area-fill-alpha` is the supported knob and it follows a scoped [data-tenant] region."
     ],
     "useCases": [
       "Cumulative volume over time (e.g. total transactions per day).",
@@ -14096,7 +14199,7 @@
   },
   {
     "docPath": "data-display/permission-matrix.tsx",
-    "example": "import { Card, CardContent, PermissionMatrix } from \"@godxjp/ui/data-display\";\nimport { grantKey } from \"@godxjp/ui/lib/permission-grid\";\n\nconst grants = new Set(rolePermissions.map((rp) => grantKey(rp.roleId, rp.permissionId)));\n\n<Card>\n  <CardContent flush>\n    <PermissionMatrix\n      roles={roles}\n      permissions={permissions}\n      grants={grants}\n      onGrantChange={(roleId, permissionId, granted) => mutate({ roleId, permissionId, granted })}\n    />\n  </CardContent>\n</Card>",
+    "example": "import { Card, CardContent, PermissionMatrix } from \"@godxjp/ui/data-display\";\nimport { grantKey } from \"@godxjp/ui/lib/permission-grid\";\n\nconst grants = new Set<string>(rolePermissions.map((rp) => grantKey(rp.roleId, rp.permissionId)));\n\n<Card>\n  <CardContent flush>\n    <PermissionMatrix\n      roles={roles}\n      permissions={permissions}\n      grants={grants}\n      onGrantChange={(roleId, permissionId, granted) => mutate({ roleId, permissionId, granted })}\n    />\n  </CardContent>\n</Card>",
     "group": "data-display",
     "importPath": "@godxjp/ui/data-display",
     "name": "PermissionMatrix",
@@ -15393,7 +15496,7 @@
   },
   {
     "docPath": "layout/masonry.tsx",
-    "example": "import { Masonry } from \"@godxjp/ui/layout\";\nimport { Card, CardContent } from \"@godxjp/ui/data-display\";\nimport { Text } from \"@godxjp/ui/general\";\n\n<Masonry\n  columns={{ base: 1, sm: 2, lg: 3 }}\n  gap=\"md\"\n  items={notes.map((note) => ({ key: note.id, data: note }))}\n  itemRender={({ data }) => (\n    <Card>\n      <CardContent>\n        <Text>{data.body}</Text>\n      </CardContent>\n    </Card>\n  )}\n  onLayoutChange={(layout) => console.log(layout.length, \"tiles placed\")}\n/>",
+    "example": "import { Masonry } from \"@godxjp/ui/layout\";\nimport { Card, CardContent } from \"@godxjp/ui/data-display\";\nimport { Text } from \"@godxjp/ui/general\";\n\n// T flows from `items`, so `data` in itemRender is whatever you put there — give the\n// collection a shape and the render callback needs no annotation.\ntype Note = { id: string; body: string };\nconst notes: Note[] = useNotes();\n\n<Masonry\n  columns={{ base: 1, sm: 2, lg: 3 }}\n  gap=\"md\"\n  items={notes.map((note) => ({ key: note.id, data: note }))}\n  itemRender={({ data }) => (\n    <Card>\n      <CardContent>\n        <Text>{data?.body}</Text>\n      </CardContent>\n    </Card>\n  )}\n  onLayoutChange={(layout) => console.log(layout.length, \"tiles placed\")}\n/>",
     "group": "layout",
     "importPath": "@godxjp/ui/layout",
     "name": "Masonry",
@@ -15599,7 +15702,12 @@
         "type": "number"
       },
       {
-        "description": "antd `getContainer`, default `() => window` — the scroll box holding the sections.",
+        "description": "gh#890. The scroll box the sections are measured in AND `Affix` pins the nav against — one function, both halves. `Affix`'s own name and shape (`AffixTargetProp`), the same lazy getter `FloatButton.BackTop.target` already spells here. `null`, or an absent `target`, means the viewport. Wins over `getContainer` when both are given.",
+        "name": "target",
+        "type": "() => Window | HTMLElement | null"
+      },
+      {
+        "description": "antd `getContainer`, default `() => window` — the scroll box holding the sections. Superseded by `target` (gh#890), which mirrors `Affix`'s own spelling for the identical idea; kept live for a call site written before `target` existed.",
         "name": "getContainer",
         "type": "() => HTMLElement | Window"
       },

package/agent/index.json

@@ -1,21 +1,21 @@
 {
   "counts": {
     "anti-ai-tells": 26,
-    "components": 170,
-    "patterns": 19,
-    "rules": 47,
-    "tokens": 1685,
+    "components": 171,
+    "patterns": 20,
+    "rules": 50,
+    "tokens": 2070,
     "vocabulary": 14
   },
   "files": [
     {
       "file": "components-index.json",
-      "note": "45 KB — name + group + tagline for all 170. FETCH THIS FIRST, then fetch only the components you chose.",
+      "note": "45 KB — name + group + tagline for all 171. FETCH THIS FIRST, then fetch only the components you chose.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json"
     },
     {
       "file": "components/<Name>.json",
-      "note": "One file per component (1 KB–33 KB, median 6 KB), each carrying its importPath. This is the selective route: read the index, then fetch only what you need instead of the 1.1 MB blob.",
+      "note": "One file per component (1 KB–34 KB, median 6 KB), each carrying its importPath. This is the selective route: read the index, then fetch only what you need instead of the 1.2 MB blob.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/<Name>.json"
     },
     {
@@ -48,9 +48,19 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v28.13.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v30.0.0/agent/index.json"
   },
-  "source": "mcp/src/data — the same data @godxjp/ui-mcp serves",
+  "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
-  "version": "28.13.0"
+  "tokenTiers": {
+    "component": "per-part knobs, --{component}-{part}-{property}; usually leave these alone",
+    "counts": {
+      "component": 1756,
+      "foundation": 211,
+      "semantic": 103
+    },
+    "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
+    "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
+  },
+  "version": "30.0.0"
 }