@godxjp/ui 33.10.1 → 33.12.1

package/agent/components.json

@@ -1323,7 +1323,7 @@
       23
     ],
     "storyPath": "layout/app-shell.tsx",
-    "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer.",
+    "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer. Keyboard focus in clipped chrome stays inset; the main scroll region shows an inset brand ring by default (--region-focus-ring-width).",
     "usage": [
       "DO put a sidebar collapse toggle IN the rail, not floating in the bar (ADR C10): the shell does not render one, so pass it through `Sidebar action={(collapsed) => <Button variant=\"ghost\" size=\"icon\" aria-label={t(\"toggleSidebar\")} aria-expanded={!collapsed} …/>}` (or the `footer` render-prop), which keeps it attached to the rail in both states. A toggle in `Topbar start` under `topbarSpan=\"full\"` lands beside the brand, detached from the rail it controls. The shell has no edge-mounted toggle (a control straddling the rail border); `Sidebar action` keeps it inside the rail head, which is the supported placement. Below the navigation boundary the drawer has its own trigger; render no collapse toggle there.",
       "useAppShellNavigationMode() returns drawer/docked at the same 56.25rem boundary as AppShell. The root also publishes data-navigation. Use this instead of a consumer media query.",
@@ -1689,6 +1689,11 @@
     "importPath": "@godxjp/ui/layout",
     "name": "Topbar",
     "props": [
+      {
+        "description": "Opt-in pinned shared-device identity: one TopbarItem truncate with Avatar in icon and a string name. Capped at --topbar-identity-max-inline-size (40%); --topbar-identity-min-text-inline-size reserves 3ch. Stays outside scroll/menu while primary cells retain their minima. Only other clusters follow overflow; children overrides all slots. Do not combine identity with hideBelow, labelHideBelow or iconHideFrom. At extreme widths choose overflow=\"menu\" to keep other controls reachable.",
+        "name": "identity",
+        "type": "ReactNode"
+      },
       {
         "description": "Instance inset using logical token steps.",
         "name": "pad",
@@ -1721,11 +1726,11 @@
         "defaultValue": "\"scroll\"",
         "description": "What a bar that does not fit does with the cells that do not fit (gh#728). scroll (default) lets the BAR scroll on the inline axis while the start and end clusters keep their cells whole — every cell stays in the DOM and in the accessibility tree, Tab reaches each one in order, and the browser scrolls a focused cell into view; the scrollbar is suppressed (a horizontal bar inside a 48px chrome row would eat the height that caused the deficit), so the pointer affordance is drag/wheel. clip is the pre-gh#728 behaviour: a cell past the cluster's edge is simply not painted — still focusable, still announced, invisible and unreachable by pointer. Independent of TopbarItem hideBelow, which REMOVES a cell at a step; this is only about what happens once there is no budget left.",
         "name": "overflow",
-        "type": "\"scroll\" | \"clip\""
+        "type": "\"scroll\" | \"clip\" | \"menu\""
       },
       {
         "defaultValue": "undefined",
-        "description": "Escape hatch — render fully custom bar content instead of the three slots. When set, `start`/`center`/`end` are ignored.",
+        "description": "Escape hatch — render fully custom bar content instead of the three slots. When set, `start`/`center`/`end`/`identity` are ignored.",
         "name": "children",
         "type": "ReactNode"
       },
@@ -1750,6 +1755,7 @@
     "storyPath": "layout/topbar.tsx",
     "tagline": "A PURE SLOT bar for the app shell — positions three clusters (start / center / end) and owns ONLY the bar layout. It bakes NO chrome: no product switcher, no search box, no notification bell, no language picker. The CONSUMER composes those from real primitives and drops them into a slot; whether a control is icon-only / labelled / bordered is that control's own config, never the shell's.",
     "usage": [
+      "For shared devices use identity={<TopbarItem truncate icon={<Avatar aria-hidden=\"true\"><AvatarFallback>DB</AvatarFallback></Avatar>}>{user.name}</TopbarItem>}, optionally wrapped in DropdownMenuTrigger asChild. Keep the locale picker icon-only with appearance=\"bar\" in end. The name stays visible and bounded; full string children become title and accessible text. AccountChip is a separate avatar/name/action row, not a full-height menu cell.",
       "DO use `TopbarSearch`, not a bare `SearchInput`, for the bar's search (ADR C02): a SearchInput in a slot shrinks with the cluster — measured at 390px in a consumer bar its text area was 0ch. TopbarSearch keeps at least 8ch from 40rem up and folds to a named search cell below it.",
       "DO align the bar's search with the content column (ADR C11) by composition: keep AppShell's default `topbarSpan=\"content\"` and put `TopbarSearch` FIRST in `start` — the bar then starts on the rail edge with the same inset as PageContainer, measured 0px apart at 1024/1280/1440. Under `topbarSpan=\"full\"` the bar starts at the window edge after the brand, so no keyline is shared; there, put the search in `end` deliberately rather than near a column it cannot meet.",
       "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.",
@@ -1775,6 +1781,12 @@
     "importPath": "@godxjp/ui/layout",
     "name": "TopbarItem",
     "props": [
+      {
+        "defaultValue": "false",
+        "description": "Same vocabulary as Text.truncate: allow the cell to shrink to its control minimum and ellipse only its label. Keeps the icon; overrides labelHideBelow. Full text remains accessible; string children supply title automatically (including asChild). Pass title explicitly for rich children. Use in Topbar identity for a bounded always-visible shared-device name; default phone accounts still use labelHideBelow=\"sm\".",
+        "name": "truncate",
+        "type": "boolean"
+      },
       {
         "description": "The cell's leading glyph, placed in a slot the CELL sizes (--topbar-icon-size). Prefer it over passing the glyph as a child whenever the glyph is wrapped: `.ui-topbar-item > svg` only reaches a DIRECT child, so a glyph inside a `<Flex hideBelow>` renders at lucide's intrinsic 24px — measured at 390px on an org-switcher cell, 1.5x the cell's step (gh#712). Decorative by convention (the cell's name comes from its own aria-label); pass <Icon as={…} size=… label=… /> here when the glyph needs a name or a different step. Rendered with asChild too (gh#726): the sized slot is inserted INSIDE the child element, ahead of that element's own children, and the child element (e.g. an <a>) stays the rendered root with every merged prop.",
         "name": "icon",
@@ -1836,7 +1848,7 @@
     "storyPath": "layout/topbar-item.tsx",
     "tagline": "ONE interactive cell of a Topbar slot — the account button, a settings or notifications trigger. Full bar height, the bar's own hover surface, and the focus mark hosted INSIDE the cell. Use it INSTEAD OF a Button in a Topbar slot: a Button there is a --control-height pill floating in a taller bar, with its own hover fill and a ring drawn around the pill.",
     "usage": [
-      "DO collapse the account cell to its avatar on a phone (ADR C04): `<DropdownMenuTrigger asChild><TopbarItem aria-label={t(\"account\")} icon={<Avatar>…</Avatar>} labelHideBelow=\"sm\">{name}</TopbarItem></DropdownMenuTrigger>` and repeat the name (and email) in the menu's `DropdownMenuLabel`. Measured at 390px: without `labelHideBelow` the name took 74px of a 390px bar; with it the cell is 48x47, named, and the name is read in the open menu.",
+      "By default collapse the account cell to its avatar on a phone (ADR C04); shared devices opt into Topbar identity + TopbarItem truncate instead: `<DropdownMenuTrigger asChild><TopbarItem aria-label={t(\"account\")} icon={<Avatar>…</Avatar>} labelHideBelow=\"sm\">{name}</TopbarItem></DropdownMenuTrigger>` and repeat the name (and email) in the menu's `DropdownMenuLabel`. Measured at 390px: without `labelHideBelow` the name took 74px of a 390px bar; with it the cell is 48x47, named, and the name is read in the open menu.",
       "DO put bar triggers in a Topbar slot as TopbarItem, not as Button — that is the difference between chrome and a control that landed in the chrome.",
       "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.",
@@ -3613,7 +3625,7 @@
       37
     ],
     "storyPath": "data-display/data-table/index.tsx",
-    "tagline": "The one TanStack-powered compound admin list — sticky header, sorting, global search, column visibility ('set view'), bulk selection, BOTH cursor and numbered pagination, density, and built-in empty/loading states. Keep the SIMPLE `data` + lean `columns` (ColumnDef) API for the common case; opt into the full grid chrome via the compound parts. Internally driven by @tanstack/react-table (a real dependency). Lives on @godxjp/ui/data-display only (it is NOT on the runtime-neutral root/admin barrel because it pulls TanStack).",
+    "tagline": "The one TanStack-powered compound admin list — sticky header, sorting, global search, column visibility ('set view'), bulk selection, BOTH cursor and numbered pagination, density, and built-in empty/loading states. Keep the SIMPLE `data` + lean `columns` (ColumnDef) API for the common case; opt into the full grid chrome via the compound parts. Internally driven by @tanstack/react-table (a real dependency). Lives on @godxjp/ui/data-display only (it is NOT on the runtime-neutral root/admin barrel because it pulls TanStack). Keyboard focus uses the shared inset ring in clipping surfaces; scrollports reveal partially clipped keyboard targets without changing their layout.",
     "usage": [
       "DO use `striped` on dense list tables (many columns, a row the eye must follow across the width). To stripe EVERY Table and DataTable in a service, set it ONCE in the theme — `:root { --table-row-striped-alpha: 100%; }` — instead of passing `striped` at each call site; `striped={false}` then opts one table out. Retint with `--table-row-striped-background`, never with a `rowClassName` utility or `:nth-child` page CSS (those count DOM rows, so an expanded detail row shifts every stripe after it).",
       "DO pass loading={isFetching} during data fetches — it renders a loading row in the table body and suppresses the empty state. Never show a spinner outside DataTable while the table is visible.",
@@ -5634,7 +5646,7 @@
       "TableHeader",
       "TableRow"
     ],
-    "tagline": "Primitive table shell (Table/TableHeader/TableBody/TableRow/TableHead/TableCell). Prefer DataTable for admin lists; use these for custom one-off tables.",
+    "tagline": "Primitive table shell (Table/TableHeader/TableBody/TableRow/TableHead/TableCell). Prefer DataTable for admin lists; use these for custom one-off tables. Keyboard focus uses the shared inset ring in clipping surfaces; scrollports reveal partially clipped keyboard targets without changing their layout.",
     "usage": [
       "DO compose all six sub-parts in order: wrap with `<Table>`, then `<TableHeader>` containing `<TableRow><TableHead>…</TableRow>`, then `<TableBody>` containing one or more `<TableRow><TableCell>…` rows. Skipping any layer (e.g. bare `<th>` inside `<Table>`) bypasses the design tokens and hover/border styles.",
       "DO use `TableHead` (not `TableCell`) for header cells — it renders `<th>` with `data-slot=\"table-head\"` and the `--table-row-height` CSS variable for consistent header sizing across the design system. `TableCell` renders `<td>` with `data-slot=\"table-cell\"` and is for body rows only.",
@@ -6221,6 +6233,7 @@
     "storyPath": "data-entry/input.tsx",
     "tagline": "Styled wrapper around native <input>; accepts all HTML input attributes. Pair with FormField for labelled fields.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged. The trailing slot is measured, so adjacent actions and counters reserve their combined width; allowClear still replaces trailingIcon/suffix.",
       "DO always wrap Input in FormField when the field needs a label, helper text, or validation error — FormField injects aria-describedby and aria-invalid onto Input automatically; never wire these attributes by hand.",
       "DO match the `id` prop on Input to the `id` prop on its parent FormField so that `htmlFor` linkage and the generated helper/error ids are consistent.",
       "DO use Input in controlled mode (`value` + `onChange`) for forms driven by Inertia's `useForm` or React state; uncontrolled usage (no `value`) is only acceptable for fire-and-forget inline edits where form state is not needed.",
@@ -6378,6 +6391,7 @@
     "storyPath": "data-entry/number-input.tsx",
     "tagline": "WAI-ARIA spinbutton for localized numeric entry — composes the real Input (role=spinbutton, inputMode=decimal) with stacked increment/decrement step Buttons. Type freely, Arrow/Shift-Arrow step, value commits clamped to min/max + rounded to precision.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged. The increment/decrement actions sit side by side on touch screens so each owns a non-overlapping target.",
       "DO use NumberInput (not `<Input type='number'>`) whenever numeric entry wants steppers, min/max clamping, precision rounding, or a ¥/% affix — it is the canonical numeric primitive. Plain Input has no stepper and no clamp.",
       "DO drive it controlled with `value` + `onValueChange` carrying `number | null` (the vocabulary triad — NOT `onChange`). `null` means the field is empty; never substitute 0 for empty.",
       "DON'T pass `value` without `onValueChange` — like every controlled @godxjp/ui input it would freeze. Omit both for uncontrolled (use `defaultValue`).",
@@ -6488,6 +6502,7 @@
     "storyPath": "data-entry/search-input.tsx",
     "tagline": "Debounced search box with a clear button. Fires onSearch (NOT onChange) after the debounce. Controlled (value) or uncontrolled (defaultValue).",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "DON'T drop a bare SearchInput into a Topbar slot — use `TopbarSearch` (layout), which passes every SearchInput prop through and folds to a search cell below 40rem instead of shrinking under 8ch (ADR C02).",
       "DO: listen to `onSearch`, not `onChange`. The component debounces internally (default 250 ms) and fires `onSearch(q)` after the delay — never wire your filter logic to `onChange` on SearchInput because it does not expose one.",
       "DO: choose controlled vs uncontrolled deliberately. Pass `value` + `onValueChange` together for controlled mode; optionally add `onSearch` for debounced effects (e.g. when search state lives in a URL param or shared parent). For local-only ephemeral search pass only `defaultValue` + `onSearch` — omitting `value` puts the component in uncontrolled mode.",
@@ -7028,6 +7043,7 @@
     ],
     "tagline": "Polymorphic single-select: pass options/loadOptions for the data-driven (Ant-style) API, or compose sub-parts manually — never use a raw <select>.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "FREE-TEXT TAGS WITH NO LIST (keywords, email recipients, labels typed from scratch): `<Select mode=\"tags\" open={false} value={tags} onValueChange={setTags} />` — the inline chip field. Use plain `mode=\"tags\"` (popup) only when there is a list of existing tags to pick from. There is no `TagInput` component.",
       "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.",
@@ -7995,6 +8011,7 @@
     "storyPath": "data-entry/date-picker.tsx",
     "tagline": "ONE date control: `picker` sets the granularity (day · week · month · quarter · year), `range` makes it a two-endpoint field, `multiple` a set. A real typeable input holds the value and submits ISO-8601 at the picker's own precision; the panel is the visual-only affordance.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "ONE component covers every date-shaped field. `picker` is the granularity axis, `range` and `multiple` are the cardinality axis, and they compose: `<DatePicker range picker=\"month\" />` is a month range.",
       "DO use `name` to make the field form-submittable — it emits ISO-8601 at the picker's own precision (`2026-03` for a month, `2026` for a year, `2026-03-01` for a day). No hidden input of your own is needed.",
       "DO wrap it in FormField like every other labelled control; FormField injects the id/aria wiring onto the input.",
@@ -8730,7 +8747,7 @@
       "PaginationNext",
       "PaginationPrevious"
     ],
-    "tagline": "Offset/page-based pagination bar. Sits below a table card.",
+    "tagline": "Offset/page-based pagination bar. Sits below a table card. Keyboard focus uses the shared inset ring in clipping surfaces; scrollports reveal partially clipped keyboard targets without changing their layout.",
     "usage": [
       "DO always control Pagination externally: store `value` (page) and `pageSize` in React state (or URL params), and update both in the `onValueChange(page, pageSize)` callback. Pagination is fully controlled — it has no internal state and will not move unless `value` changes.",
       "DO let Pagination hide itself for zero items and single pages (`hideOnSinglePage`, default true) — it is navigation between multiple result pages. Render it inside a table footer only in the DATA state: never during loading, empty, error, or an unmet prerequisite. Pass `hideOnSinglePage={false}` only when you still want the bar on one page to keep `showTotal` visible.",
@@ -9653,6 +9670,7 @@
     "storyPath": "data-entry/time-picker.tsx",
     "tagline": "Time combobox with hours, minutes, optional seconds, confirmation and 12-hour formatting. Native submission stays canonical 24-hour time.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "One trailing icon: empty shows calendar/clock; filled and clearable shows only ×; allowClear=false retains the picker icon. Click the input or ArrowDown to open a filled picker.",
       "DO give it a name in native forms. It submits HH:mm or HH:mm:ss, regardless of display format; the component manages any hidden canonical field.",
       "DO use the controlled pattern (`value` + `onValueChange`) in React-managed forms (e.g. useForm). For simple HTML forms without React state, omit `value` and use `defaultValue` for the uncontrolled pattern.",
@@ -9868,6 +9886,7 @@
     "storyPath": "data-entry/cascader.tsx",
     "tagline": "Multi-level hierarchical path picker (Popover + cascading columns); value is always a string[] path, never a flat ID — passing a bare string breaks it.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "DO pass a string[] path as value in single mode (e.g. ['country','region','city']). DON'T pass a flat string ID — the component treats value as an ordered path array and will render nothing if you pass a bare string.",
       "DO use value + onChange together for controlled mode, or defaultValue alone for uncontrolled. DON'T mix both — providing value without onChange makes the field read-only (the internal state won't update).",
       "DO set multiple={true} and pass value as string[][] (array of paths) for multi-selection. onChange receives string[][] in that mode. Mixing single-mode shape with multiple={true} silently produces no selection.",
@@ -10100,6 +10119,7 @@
     "storyPath": "data-entry/tree-select.tsx",
     "tagline": "Hierarchical tree picker in a Popover (single or multi-select with checkboxes) — `onValueChange` receives `string` in single mode and `string[]` in multi/checkable mode; never use a raw `<select>` for tree-structured data.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "DO pair with a `<label htmlFor={id}>` and pass the matching `id` prop so screen readers announce the control correctly. The underlying trigger is a `<Button role='combobox'>` — not a native `<select>` — so an explicit label is required.",
       "DO use `treeCheckable` (+ optionally `showCheckedStrategy`) for selecting multiple nodes with parent–child cascade; use `multiple` only when you want multi-select WITHOUT the checkbox cascade behaviour.",
       "DO use the static constants `TreeSelect.SHOW_CHILD`, `TreeSelect.SHOW_PARENT`, `TreeSelect.SHOW_ALL` (or the named exports `SHOW_CHILD`/`SHOW_PARENT`/`SHOW_ALL` from the same import path) instead of raw string literals for `showCheckedStrategy`.",
@@ -11654,7 +11674,7 @@
     "subParts": [
       "ScrollBar"
     ],
-    "tagline": "A native scrolling box (no scroll library since v23): one `overflow: auto` element whose scrollbar is styled from --scroll-area-* tokens. Always set an explicit height/max-height, or nothing overflows and no scrollbar appears. Owns the scrolling element, so it also owns reaching it (viewportRef) and bottom anchoring for a live stream (anchor).",
+    "tagline": "Keyboard focus on the scroll viewport and its descendants uses the shared inset brand ring (--focus-ring-inset-offset), without padding changes. A native scrolling box (no scroll library since v23): one `overflow: auto` element whose scrollbar is styled from --scroll-area-* tokens. Always set an explicit height/max-height, or nothing overflows and no scrollbar appears. Owns the scrolling element, so it also owns reaching it (viewportRef) and bottom anchoring for a live stream (anchor).",
     "usage": [
       "DO set an explicit height or max-height on ScrollArea via className (e.g. `className=\"h-64\"` or `className=\"max-h-[min(300px,50vh)]\"`). Without a height constraint the viewport grows to fit content and the scrollbar is never rendered.",
       "DO wrap content in a single child element inside ScrollArea — the Viewport observes its single child's size to decide whether overflow exists.",
@@ -12756,6 +12776,7 @@
     "storyPath": "data-entry/password-input.tsx",
     "tagline": "Input for passwords with a built-in show/hide eye toggle. Accepts all Input props except `type`.",
     "usage": [
+      "Coarse pointers: affix actions use --control-affix-touch-target-size (44px by default); text space is reserved separately. Fine-pointer geometry is unchanged.",
       "DO use for any password / secret field instead of `<Input type=\"password\">` so users get the show/hide affordance.",
       "DO pass `name` + `autoComplete=\"current-password\"|\"new-password\"` for correct form/password-manager behavior.",
       "DON'T add your own eye button — it's built in (and excluded from the tab order)."
@@ -13206,7 +13227,7 @@
       "ResizableHandle",
       "ResizablePanelGroup"
     ],
-    "tagline": "Resizable panel group/child/handle primitives from react-resizable-panels.",
+    "tagline": "Resizable panel group/child/handle primitives from react-resizable-panels. --resizable-handle-size sets separator thickness; ARIA orientation controls its axis. Handles use the shared inset focus ring, including empty handles.",
     "usage": [
       "DO put the layout on `<ResizablePanelGroup orientation=\"horizontal|vertical\">`, the resizable regions in `<ResizablePanel>`, and a `<ResizableHandle>` BETWEEN every adjacent pair — a group of N panels needs N-1 handles or there is nothing to drag.",
       "DO express `defaultSize`/`minSize`/`maxSize` as PERCENTAGE STRINGS like `defaultSize=\"35%\"` (react-resizable-panels v4: a bare number is PIXELS, so `defaultSize={35}` renders a 35px sliver, NOT 35% — pass the string). Don't fight sizing with a fixed `w-[280px]` className on the panel.",
@@ -16666,7 +16687,7 @@
       45
     ],
     "storyPath": "navigation/anchor.tsx",
-    "tagline": "Ant Design `Anchor` (6.6.5): the in-page section navigation, and the only thing in this library that COMPUTES which section is current. `NavList activeId` takes that answer as a prop. Resolves by antd's rule — the last section whose edge has crossed a single decision line — which is a pure function of scroll position and therefore cannot flicker, suppresses itself during the programmatic scroll a click starts, reads the landing hash before any scroll event, and jumps rather than tweens under `prefers-reduced-motion`.",
+    "tagline": "Ant Design `Anchor` (6.6.5): the in-page section navigation, and the only thing in this library that COMPUTES which section is current. `NavList activeId` takes that answer as a prop. Resolves by antd's rule — the last section whose edge has crossed a single decision line — which is a pure function of scroll position and therefore cannot flicker, suppresses itself during the programmatic scroll a click starts, reads the landing hash before any scroll event, and jumps rather than tweens under `prefers-reduced-motion`. Keyboard focus uses the shared inset ring in clipping surfaces; scrollports reveal partially clipped keyboard targets without changing their layout.",
     "tier": "lab",
     "usage": [
       "DO give every target a real `id` and point `href` at it as `#id`. The links are real anchors: middle-clickable, deep-linkable, and correct before JavaScript boots.",

package/agent/index.json

@@ -4,7 +4,7 @@
     "components": 169,
     "patterns": 28,
     "rules": 44,
-    "tokens": 2235,
+    "tokens": 2241,
     "vocabulary": 14
   },
   "design": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md",
@@ -16,7 +16,7 @@
     },
     {
       "file": "components-index.json",
-      "note": "52 KB — name + group + tagline for all 169. FETCH THIS FIRST, then fetch only the components you chose.",
+      "note": "53 KB — name + group + tagline for all 169. FETCH THIS FIRST, then fetch only the components you chose.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json"
     },
     {
@@ -54,19 +54,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/v33.10.1/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v33.12.1/agent/index.json"
   },
   "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",
   "tokenTiers": {
     "component": "per-part knobs, --{component}-{part}-{property}; usually leave these alone",
     "counts": {
-      "component": 1906,
-      "foundation": 216,
+      "component": 1910,
+      "foundation": 218,
       "semantic": 113
     },
     "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": "33.10.1"
+  "version": "33.12.1"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 169 components, 2235 design tokens,
-> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.10.1.
+> A Japanese-enterprise React design system: 169 components, 2241 design tokens,
+> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.12.1.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@33.10.1`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@33.12.1`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -16,10 +16,10 @@ that can only fetch URLs.
 ## Catalog
 
 - [patterns-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/patterns-index.json): 28 whole-task patterns (name, tagline, tags). Start here when the task is a TASK — "build a settings page" — then fetch `patterns/<name>.json` for complete code.
-- [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 52 KB — all 169 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
+- [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 53 KB — all 169 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
 - [components/&lt;Name&gt;.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json): one file per component (1 KB–37 KB, median 6 KB). Read the index, then fetch only the ones you chose — this is the selective route, and the reason you do not need the blob.
 - [components.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json): 1.3 MB — every entry in one file. Most URL fetchers truncate a response this size without saying so; prefer the per-component files.
-- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 216 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 1906 `component` knobs.
+- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 218 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 1910 `component` knobs.
 - [vocabulary.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json): the controlled prop vocabulary — which prop name means what, across every component.
 - [rules.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json): 44 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 35 shapes that make generated UI look generated, each with its fix.
@@ -27,7 +27,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v33.10.1/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v33.12.1/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/tokens.json

@@ -665,6 +665,18 @@
     "tier": "foundation",
     "value": "var(--focus-outline-offset)"
   },
+  {
+    "description": "Inside clipping surfaces, preserve the mark and gap without changing layout.",
+    "name": "--focus-ring-inset-offset",
+    "tier": "foundation",
+    "value": "calc(-1 * (var(--focus-ring-width) + var(--focus-outline-offset)))"
+  },
+  {
+    "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
+    "name": "--focus-ring-contained-offset",
+    "tier": "foundation",
+    "value": "initial"
+  },
   {
     "description": "Ring headroom for clipped chrome (`overflow-clip-margin` on the topbar family, gh#291). MUST stay a plain length consumed via a bare var(): Chromium rejects any calc() in overflow-clip-margin at parse time (even calc(2 * 2px)), silently dropping the declaration to 0. Value = max ring paint (3px open/focus) + rounding immunity: at 4px a flush-edge ring had only 1px of slack, which device-pixel rounding on non-retina (dpr 1) displays or fractional browser zoom could consume, shaving the ring's outer edge. 8px keeps ≥5px of slack under any rounding regime.",
     "name": "--focus-ring-clip-margin",
@@ -672,10 +684,10 @@
     "value": "8px"
   },
   {
-    "description": "REGION focus ring — the keyboard-scroll affordance on large scroll REGIONS (`.app-main`, gh#271/gh#276), separate from the control ring above. A control-strength 2px brand frame around the entire content area reads as a glitch to mouse-first users (`:focus-visible` promotes on any keypress after a click-focus), so the DEFAULT IS OFF — a deliberate, product-owner tradeoff against WCAG 2.4.7 for keyboard-scroll visibility. A service that needs the visible affordance opts in with ONE token: --region-focus-ring-width: var(--focus-ring-width); `--region-focus-ring-color` is declared `initial` (NOT a :root var binding — the freeze rule) and resolves to the live focus-ring hue at the element that paints it.",
+    "description": "Keyboard-scroll regions use an inset brand mark by default. Both the region weight and the global focus switch remain configurable.",
     "name": "--region-focus-ring-width",
     "tier": "foundation",
-    "value": "0"
+    "value": "var(--focus-ring-weight)"
   },
   {
     "description": "default = hsl(var(--focus-ring-color, var(--ring)))",
@@ -4067,6 +4079,12 @@
     "tier": "component",
     "value": "1.5rem"
   },
+  {
+    "description": "Shared coarse-pointer floor; independent of density and the desktop glyph size.",
+    "name": "--control-affix-touch-target-size",
+    "tier": "component",
+    "value": "var(--band-height-xl)"
+  },
   {
     "description": "gh#888 — φ tier freezes at :root; default = calc(var(--radius) / var(--radius-ratio) / var(--radius-ratio))",
     "name": "--control-affix-action-radius",
@@ -5139,7 +5157,7 @@
     "description": "SearchInput's text stops at the clear ✕'s 44px TARGET, not at its 24px box (gh#1148): edge inset + half the box (where the glyph's centre is) + half the target.",
     "name": "--search-input-end-padding",
     "tier": "component",
-    "value": "calc( var(--search-input-edge-inset) + var(--touch-target-min) / 2 + var(--band-height-xl) / 2 )"
+    "value": "calc( var(--search-input-edge-inset) + var(--touch-target-min) / 2 + var(--control-affix-touch-target-size) / 2 )"
   },
   {
     "description": "Control primitive tokens: heights, horizontal padding, adjacent control sizes.",
@@ -10055,6 +10073,12 @@
     "tier": "component",
     "value": "var(--space-2)"
   },
+  {
+    "description": "Room for the shared inset focus mark and gap, including handles without a grip.",
+    "name": "--resizable-handle-size",
+    "tier": "component",
+    "value": "var(--space-2)"
+  },
   {
     "description": "`thin` reproduces the old 10px rail closely on the platforms that draw a classic scrollbar; `auto` gives the full-width platform bar, which is what a touch/coarse-pointer console wants. Only `auto | thin | none` are valid — a length is not (that is the standard property's whole bargain, and the reason `--scroll-area-bar-size` could not survive as a rem).",
     "name": "--scroll-area-scrollbar-width",
@@ -10895,6 +10919,18 @@
     "tier": "component",
     "value": "var(--space-2)"
   },
+  {
+    "description": "Shared-device identity gets a bounded share, not the primary controls' width.",
+    "name": "--topbar-identity-max-inline-size",
+    "tier": "component",
+    "value": "40%"
+  },
+  {
+    "description": "Shell (sidebar / topbar / kbd) component tokens — small-by-design text knobs (rule #45/#46). A service re-tunes chrome text without moving the global scale.",
+    "name": "--topbar-identity-min-text-inline-size",
+    "tier": "component",
+    "value": "3ch"
+  },
   {
     "description": "THE GLASS BAR (gh#831) — the same two declarations two unrelated website showcases each hand-wrote on their own sticky header: a translucent page fill plus a backdrop blur. Both knobs are `initial`, i.e. QUIET by default in exactly the sense the paragraph above describes: a guaranteed-invalid value makes the whole declaration at the call site invalid-at-computed-value time, so `background-color` falls back to its own initial `transparent` and `backdrop-filter` to `none`. The shipped bar therefore paints nothing, creates no backdrop root, and is byte-identical to the pure slot bar it was. A service opts in with `--topbar-background-alpha: 85%` / `--topbar-backdrop-blur-size: 10px`. The TINT is NOT a knob: `.ui-topbar` reads `--background` directly at the call site, so a dark or tenant-scoped subtree re-tints the glass instead of inheriting :root's answer (docs/TOKENS.md · the `:root` freeze rule). Precedent for the blur name: --app-launcher-launchpad-backdrop-blur-size. default = none — the bar paints no fill",
     "name": "--topbar-background-alpha",

package/dist/components/data-display/data-table.js

@@ -1,5 +1,6 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { revealKeyboardFocus } from "../../lib/focus-reveal.js";
 import * as React from "react";
 import {
   columnFilteringFeature,
@@ -1000,6 +1001,7 @@ DataTable.Content = function DataTableContent() {
     "div",
     {
       ref: scrollRef,
+      onFocusCapture: revealKeyboardFocus,
       className: cn(
         "ui-data-table-scroll",
         hasPinEnd && "ui-data-table-has-pin-end",

package/dist/components/data-display/table.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { revealKeyboardFocus } from "../../lib/focus-reveal.js";
 import * as React from "react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { tableHeadHeightClass } from "../../lib/control-styles.js";
@@ -153,7 +154,9 @@ const Table = React.forwardRef(
         "div",
         {
           ref: scrollRef,
+          onFocusCapture: revealKeyboardFocus,
           className: cn(
+            "ui-table-scroll",
             scrollable ? "relative w-full overflow-auto" : "relative w-full",
             preset === "action-collection" && "ui-table-collection",
             preset === "stacked-record-collection" && "ui-table-stacked-collection"

package/dist/components/data-entry/input.js

@@ -72,6 +72,21 @@ const Input = React.forwardRef(
       },
       [ref]
     );
+    const setTrailingRef = React.useCallback((node) => {
+      if (!node) return;
+      const wrapper = node.parentElement;
+      const sync = () => wrapper.style.setProperty(
+        "--input-trailing-measured-size",
+        `${node.getBoundingClientRect().width}px`
+      );
+      sync();
+      const observer = typeof ResizeObserver === "undefined" ? void 0 : new ResizeObserver(sync);
+      observer?.observe(node);
+      return () => {
+        observer?.disconnect();
+        wrapper.style.removeProperty("--input-trailing-measured-size");
+      };
+    }, []);
     const [text, setText] = React.useState(() => String(value ?? defaultValue ?? ""));
     const hasText = text.length > 0;
     React.useEffect(() => {
@@ -167,7 +182,7 @@ const Input = React.forwardRef(
           ...appearance
         }
       ),
-      trailing != null || counter !== null ? /* @__PURE__ */ jsxs("span", { className: "ui-input-trailing", children: [
+      trailing != null || counter !== null ? /* @__PURE__ */ jsxs("span", { className: "ui-input-trailing", ref: setTrailingRef, children: [
         counter ? /* @__PURE__ */ jsx(
           "span",
           {

package/dist/components/data-entry/search-input.js

@@ -104,7 +104,7 @@ function SearchInput({
             // gh#1250 — while the key cap shows, the text stops before it instead of running under it.
             // gh#1285 — written FROM --search-input-end-padding (minus the ✕ slot it reserves, plus the
             // cap), so a theme that retunes that token still moves this padding (default: edge inset + 6ch, as before).
-            showShortcut ? "!pe-[calc(var(--search-input-end-padding)_-_var(--control-icon-size)_-_var(--control-gap)_+_6ch)]" : "!pe-[var(--search-input-end-padding)]",
+            showShortcut ? "!pe-[calc(var(--search-input-end-padding)_-_var(--control-icon-size)_-_var(--control-gap)_+_6ch)]" : void 0,
             inputClassName
           ),
           disabled

package/dist/components/layout/app-shell.js

@@ -1,5 +1,6 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { revealKeyboardFocus } from "../../lib/focus-reveal.js";
 import * as React from "react";
 import { Menu } from "lucide-react";
 import { useMediaQuery } from "../../lib/hooks.js";
@@ -80,10 +81,10 @@ function AppShell({
     /* @__PURE__ */ jsx("span", { className: "app-topbar-brand", "data-hide-below": logoCompactBelow, children: logo }),
     /* @__PURE__ */ jsx("span", { className: "app-topbar-brand", "data-hide-from": logoCompactBelow, children: logoCompact })
   ] });
-  const resolvedTopbar = topbar !== void 0 ? /* @__PURE__ */ jsxs("div", { className: "app-topbar-rail", children: [
+  const resolvedTopbar = topbar !== void 0 ? /* @__PURE__ */ jsxs("div", { onFocusCapture: revealKeyboardFocus, className: "app-topbar-rail", children: [
     !logoInRail && logo !== void 0 && /* @__PURE__ */ jsx("div", { className: "app-topbar-logo", children: brand }),
     /* @__PURE__ */ jsx("div", { className: "app-topbar-custom", children: topbar })
-  ] }) : /* @__PURE__ */ jsxs("div", { className: "app-topbar-rail", children: [
+  ] }) : /* @__PURE__ */ jsxs("div", { onFocusCapture: revealKeyboardFocus, className: "app-topbar-rail", children: [
     !logoInRail && logo !== void 0 && /* @__PURE__ */ jsx("div", { className: "app-topbar-logo", children: brand }),
     topbarLeft !== void 0 && /* @__PURE__ */ jsx("div", { className: "app-topbar-left", children: topbarLeft }),
     /* @__PURE__ */ jsx("div", { className: "app-topbar-spacer" }),
@@ -167,10 +168,19 @@ function AppShell({
           rail,
           bar
         ] }),
-        /* @__PURE__ */ jsxs("main", { className: "app-main", "aria-label": t("layout.appShell.mainLabel"), tabIndex: 0, children: [
-          breadcrumb !== void 0 && /* @__PURE__ */ jsx("div", { className: "app-breadcrumb", children: breadcrumb }),
-          children
-        ] }),
+        /* @__PURE__ */ jsxs(
+          "main",
+          {
+            onFocusCapture: revealKeyboardFocus,
+            className: "app-main",
+            "aria-label": t("layout.appShell.mainLabel"),
+            tabIndex: 0,
+            children: [
+              breadcrumb !== void 0 && /* @__PURE__ */ jsx("div", { className: "app-breadcrumb", children: breadcrumb }),
+              children
+            ]
+          }
+        ),
         footer !== void 0 && /* @__PURE__ */ jsx("footer", { className: "app-footer", "aria-label": t("layout.appShell.footerLabel"), children: footer })
       ]
     }

package/dist/components/layout/topbar-item.d.ts

@@ -15,6 +15,7 @@ export declare const TopbarItem: React.ForwardRefExoticComponent<Omit<React.Butt
     icon?: React.ReactNode;
     iconHideFrom?: import("../../props/index.js").BreakpointProp;
     labelHideBelow?: import("../../props/index.js").BreakpointProp;
+    truncate?: boolean;
     badge?: React.ReactNode;
     badgeTone?: import("../../props/components/layout.prop.js").SidebarBadgeToneProp;
     asChild?: boolean;

package/dist/components/layout/topbar-item.js

@@ -10,6 +10,7 @@ const TopbarItem = React.forwardRef(function TopbarItem2({
   icon,
   iconHideFrom,
   labelHideBelow,
+  truncate = false,
   badge,
   badgeTone,
   children,
@@ -26,13 +27,14 @@ const TopbarItem = React.forwardRef(function TopbarItem2({
       children: icon
     }
   ) : null;
-  const labelOf = (label) => labelHideBelow === void 0 || label === void 0 || label === null || label === false ? label : /* @__PURE__ */ jsx(
+  const labelOf = (label2) => !truncate && labelHideBelow === void 0 || label2 === void 0 || label2 === null || label2 === false ? label2 : /* @__PURE__ */ jsx(
     "span",
     {
+      dir: truncate ? "auto" : void 0,
       "data-slot": "topbar-item-label",
       className: "ui-topbar-item-label",
-      "data-hide-below": labelHideBelow,
-      children: label
+      "data-hide-below": truncate ? void 0 : labelHideBelow,
+      children: label2
     }
   );
   const badgeNode = showBadge ? /* @__PURE__ */ jsx(
@@ -44,18 +46,21 @@ const TopbarItem = React.forwardRef(function TopbarItem2({
       children: badge
     }
   ) : null;
-  const slotted = asChild && (iconNode !== null || labelHideBelow !== void 0 || badgeNode !== null) && React.isValidElement(children) ? React.cloneElement(
+  const slotted = asChild && (iconNode !== null || truncate || labelHideBelow !== void 0 || badgeNode !== null) && React.isValidElement(children) ? React.cloneElement(
     children,
     void 0,
     iconNode,
     labelOf(children.props.children),
     badgeNode
   ) : children;
+  const label = asChild && React.isValidElement(children) ? children.props.children : children;
   return /* @__PURE__ */ jsx(
     Comp,
     {
       ref,
       "data-slot": "topbar-item",
+      "data-truncate": truncate ? "true" : void 0,
+      title: truncate && typeof label === "string" ? label : void 0,
       "data-hide-below": hideBelow,
       className: cn("ui-topbar-item ui-focus-ring", className),
       type: asChild ? void 0 : type ?? "button",

package/dist/components/layout/topbar.d.ts

@@ -5,4 +5,4 @@ export type { TopbarProp, TopbarProp as TopbarProps } from "../../props/componen
  * Topbar — a PURE SLOT bar. It positions three clusters (`start` / `center` / `end`) and owns the
  * bar's flex layout; it does NOT bake any chrome.
  */
-export declare function Topbar({ start, center, end, className, children, height, overflow, pad, style, ...props }: TopbarProp): React.JSX.Element;
+export declare function Topbar({ start, center, end, identity, className, children, height, overflow, pad, style, onFocusCapture, ...props }: TopbarProp): React.JSX.Element;