@godxjp/ui 31.2.0 → 31.4.0

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 31.2.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 31.4.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -47,7 +47,7 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
    filters" — start HERE, not at the components. Then fetch `patterns/<name>.json` for complete,
    copy-paste-ready code. A component index answers "does X exist"; it cannot answer "build Y".
-1. `components-index.json` — 46 KB, all 175 components as name + group +
+1. `components-index.json` — 47 KB, all 176 components as name + group +
    tagline. Read this when you already know the SHAPE you need. Each entry may carry `absorbed`:
    names that **do not exist** and map to it — `Combobox`, `Autocomplete`, `CountrySelect` and
    `SearchSelect` are all `Select`. If you are about to hand-roll something, search this field
@@ -56,10 +56,10 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 50 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2074 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 2080 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 211 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1760 `component` entries are per-part knobs; reach for one only when a role is
+   1765 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
@@ -144,8 +144,8 @@ has stopped following the brand.
 | `tier` | count | what it is | set it? |
 |---|---|---|---|
 | `foundation` | 211 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
-| `semantic` | 103 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 1760 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `semantic` | 104 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
+| `component` | 1765 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/AuthExpiryProvider.json

@@ -0,0 +1,40 @@
+{
+  "example": "import { AuthExpiryProvider } from \"@godxjp/ui/query\";\n\nexport function Providers({ children }: { children: React.ReactNode }) {\n  return (\n    <AuthExpiryProvider\n      onAuthExpired={() => {\n        const returnTo = encodeURIComponent(window.location.href);\n        window.location.assign(`/auth/login?return_to=${returnTo}`);\n      }}\n    >\n      {children}\n    </AuthExpiryProvider>\n  );\n}",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/query",
+  "name": "AuthExpiryProvider",
+  "props": [
+    {
+      "description": "Called ONCE per expiry — any number of simultaneous 401s share one call; re-armed after every auth-errored view has gone. Typically `window.location.assign(loginUrl(returnTo = location.href))`. Return a promise for a silent refresh (then invalidate queries); a throw/rejection brings back the sign-in alert, whose button calls this again.",
+      "name": "onAuthExpired",
+      "required": true,
+      "type": "(context: { error: unknown }) => void | Promise<void>"
+    },
+    {
+      "description": "The app.",
+      "name": "children",
+      "type": "ReactNode"
+    }
+  ],
+  "related": [
+    "DataState / InfiniteQueryState / AlertMutationFeedback / AlertQueryError — the surfaces that consult this provider.",
+    "classifyQueryError — decides what is auth-class (401, or a status-less 'unauthenticated / access token invalid / token expired' message).",
+    "ErrorSurface — the whole-page error surface; a session expiry is neither a page error nor an inline one."
+  ],
+  "rules": [],
+  "storyPath": "query/DataState.stories.tsx",
+  "tagline": "App-root handler for an expired session (401 / invalid or expired token): every DataState / InfiniteQueryState / AlertMutationFeedback / AlertQueryError calls it automatically, once, and shows a neutral pending state instead of an error alert. Also exported from @godxjp/ui.",
+  "usage": [
+    "DO: mount it ONCE near the root, inside the QueryClientProvider/AppProvider, and redirect to the IdP with the current URL as the return target. The IdP returns immediately while its own session is alive — the SSO norm (Google/Microsoft apps, OIDC SPA guidance): no page-level error for an expired session.",
+    "DO: expect the surfaces to keep their `skeleton` (DataState/InfiniteQueryState) or a small muted status line (AlertMutationFeedback/AlertQueryError) with `role=\"status\"` announcing 'redirecting to sign-in' — never a destructive alert.",
+    "DON'T: wire `onAuthError` on every DataState as the session strategy — that renders an alert and waits for a click. It is the no-provider fallback only.",
+    "DON'T: use it for 403 — forbidden is a permission state, not an expired session; it still renders the access-guidance alert.",
+    "DO: when there is no provider the 401 fallback is a neutral (tone=default, role=status) sign-in alert capped at `--query-auth-alert-max-inline-size` (36rem, `none` = full width) — backward compatible, but proportionate."
+  ],
+  "useCases": [
+    "An SSO app (GoDX ID / OIDC) whose access token expired while the tab was idle: the first 401 redirects to the IdP and back to the same URL, no error panel flashes.",
+    "A dashboard with five DataStates that all 401 in the same tick: exactly one redirect.",
+    "A form submit (`AlertMutationFeedback`) that 401s: a muted 'redirecting to sign-in' line instead of a red alert.",
+    "A silent token refresh: return a promise that refreshes and then `queryClient.invalidateQueries()`; the views recover from skeleton without ever showing an error."
+  ]
+}

package/agent/components/DataState.json

@@ -28,7 +28,7 @@
       "type": "boolean"
     },
     {
-      "description": "Recovery for 401 / expired-token errors: renew the session or sign in again. A 401 renders this action instead of Retry.",
+      "description": "Per-instance sign-in button for 401 / expired-token errors when NO `AuthExpiryProvider` is mounted (clicked by the user, never auto-invoked). Prefer `AuthExpiryProvider onAuthExpired` at the app root, which handles every 401 automatically and once (gh#1022).",
       "name": "onAuthError",
       "type": "() => void"
     },
@@ -64,6 +64,8 @@
     "DO: provide `empty` + `isEmpty` together when the data can legitimately return 0 items — e.g. `isEmpty={(d) => d.items.length === 0}` paired with `empty={<EmptyState title=\"…\" />}`. Omitting `empty` means an empty array still falls through to `children`, silently rendering a blank table.",
     "DON'T: wrap DataState in your own conditional — e.g. `{query.isSuccess && <DataState …>}`. DataState IS the conditional; the outer guard is redundant and breaks the retry/refetch skeleton.",
     "DON'T: use DataState for `useInfiniteQuery` results. The `query` prop type is `UseQueryResult<T>`, not `UseInfiniteQueryResult`. Use `InfiniteQueryState` (from `@godxjp/ui/query`) instead, which accepts `flatten` and renders a load-more footer.",
+    "DO: mount `AuthExpiryProvider onAuthExpired={…}` once at the app root (SSO apps: redirect to the IdP with the current URL as return target). A 401 then never paints an alert: the handler runs automatically, once for any number of simultaneous 401s, and DataState keeps its `skeleton` with a polite live region announcing the redirect (gh#1022).",
+    "DON'T: rely on per-page `onAuthError` for session expiry — it is only a click-to-sign-in button in the fallback alert (no provider). An expired session is an app-wide concern, not a page error.",
     "DO: classify errors by cause. Use session renewal/sign-in for 401, access guidance for 403, contextual correction for domain errors, and opt into showRetry only for transient network/5xx errors.",
     "DO: pass prerequisite for enabled:false queries. Pending + fetchStatus idle is unstarted, not loading, and never renders a skeleton.",
     "DO: rely on the localized, cause-specific error message — the raw backend/token/stack text is never shown. For a domain-specific message (e.g. a 422 field error) pass a custom errorRenderer.",

package/agent/components/InfiniteQueryState.json

@@ -42,7 +42,7 @@
     "DO: Import from `@godxjp/ui/query` (not `@godxjp/ui`). Use the bundled `flattenItemPages` helper for any API that returns `{ items: T[] }` pages — it handles `undefined` data safely. Custom page shapes require a custom `flatten` function.",
     "DO: Always pass `skeleton` (e.g. `<SkeletonTable />` or `<SkeletonStat />`). It shows on initial `isPending`, on refetch-after-error, and whenever `data` is absent. Never show a blank area while loading.",
     "DO: Pass `empty` (an `<EmptyState>` node) to handle the zero-results case — without it the children render-prop is called with an empty array and you get a silent blank screen. Provide a custom `isEmpty` only when `TFlat` is not an array.",
-    "DO: Let errors remain cause-aware. Retry is automatic only for classified transient/network/5xx failures. Unknown errors do not get a blind retry unless `showRetry` or `onRetry` is explicitly supplied; 401 routes to `onAuthError`, and raw backend/token text is never rendered.",
+    "DO: Let errors remain cause-aware. Retry is automatic only for classified transient/network/5xx failures. Unknown errors do not get a blind retry unless `showRetry` or `onRetry` is explicitly supplied; a 401 is handled by the app-root `AuthExpiryProvider` (auto, once, skeleton + live region) or, without one, by the `onAuthError` sign-in button; raw backend/token text is never rendered.",
     "DON'T: Hand-roll a load-more button. The component renders a default centered outline Button when `hasNextPage` is true. Override only via `loadMore` (custom node) or `showLoadMore={false}` (hide entirely). Never call `query.fetchNextPage()` outside the component for pagination.",
     "DON'T: Use `InfiniteQueryState` for a `useQuery` result — it expects `UseInfiniteQueryResult` shape (`pages`, `hasNextPage`, `fetchNextPage`, `isFetchingNextPage`). For regular `useQuery` use `DataState` instead.",
     "DON'T: Confuse the two generics: `TPage` is the raw page shape from the API, `TFlat` is what `flatten` returns (usually `TItem[]`). The `children` render-prop receives `TFlat`, not `TPage`. Pass `isEmpty` if `TFlat` is not a plain array so empty detection works correctly."

package/agent/components/Tabs.json

@@ -24,6 +24,11 @@
       "name": "onValueChange",
       "type": "(value: string) => void"
     },
+    {
+      "description": "Strip-only mode (gh#1021): the tabs drive content OUTSIDE the strip. No tabpanel is rendered, and the selected tab's `aria-controls` points at this id, which is the consumer's own region (give it `role=\"region\"` and a name). Content there is never remounted on a tab switch, so a typed draft survives. With the compound form it applies to triggers without a declared `TabsContent` (a declared panel wins). A pure filter with NO region to point at is not a tab strip; use `Segmented`. The root's `aria-label`/`aria-labelledby` name the `role=\"tablist\"` (gh#1020), and a compound `TabsTrigger` takes `count`/`overflowCount`/`showZero`/`countLabel`, drawn exactly like `items[].count`.",
+      "name": "controls",
+      "type": "IdProp"
+    },
     {
       "defaultValue": "\"default\"",
       "description": "Trigger-strip appearance — this is Ant Design's `type` under the library's own `variant` vocabulary. `default` is the pill strip (antd has no equivalent). `line` is UNDERLINE-ONLY: the selected trigger gets no ring or card border at all — only the token-owned 2px primary bar (--tabs-indicator-{background,size,offset}) — so the `:focus-visible` keyboard ring stays visible and clearly distinct from selection. `card` gives each tab a boxed face on a rail (--tabs-card-*). `editable-card` is `card` plus the add button and per-tab remove shortcut, and needs `onEdit` to do anything. With `items`, the variant is forwarded to the list; when composing manually, pass the same value to `<TabsList variant=\"line\">`.",

package/agent/components-index.json

@@ -321,6 +321,11 @@
     "name": "DataState",
     "tagline": "TanStack Query lifecycle widget — skeleton / error / empty / success for one useQuery block. Import from @godxjp/ui/query."
   },
+  {
+    "group": "feedback",
+    "name": "AuthExpiryProvider",
+    "tagline": "App-root handler for an expired session (401 / invalid or expired token): every DataState / InfiniteQueryState / AlertMutationFeedback / AlertQueryError calls it automatically, once, and shows a neutral pending state instead of an error alert. Also exported from @godxjp/ui."
+  },
   {
     "group": "data-display",
     "name": "InfiniteQueryState",

package/agent/components.json

@@ -5220,7 +5220,7 @@
         "type": "boolean"
       },
       {
-        "description": "Recovery for 401 / expired-token errors: renew the session or sign in again. A 401 renders this action instead of Retry.",
+        "description": "Per-instance sign-in button for 401 / expired-token errors when NO `AuthExpiryProvider` is mounted (clicked by the user, never auto-invoked). Prefer `AuthExpiryProvider onAuthExpired` at the app root, which handles every 401 automatically and once (gh#1022).",
         "name": "onAuthError",
         "type": "() => void"
       },
@@ -5256,6 +5256,8 @@
       "DO: provide `empty` + `isEmpty` together when the data can legitimately return 0 items — e.g. `isEmpty={(d) => d.items.length === 0}` paired with `empty={<EmptyState title=\"…\" />}`. Omitting `empty` means an empty array still falls through to `children`, silently rendering a blank table.",
       "DON'T: wrap DataState in your own conditional — e.g. `{query.isSuccess && <DataState …>}`. DataState IS the conditional; the outer guard is redundant and breaks the retry/refetch skeleton.",
       "DON'T: use DataState for `useInfiniteQuery` results. The `query` prop type is `UseQueryResult<T>`, not `UseInfiniteQueryResult`. Use `InfiniteQueryState` (from `@godxjp/ui/query`) instead, which accepts `flatten` and renders a load-more footer.",
+      "DO: mount `AuthExpiryProvider onAuthExpired={…}` once at the app root (SSO apps: redirect to the IdP with the current URL as return target). A 401 then never paints an alert: the handler runs automatically, once for any number of simultaneous 401s, and DataState keeps its `skeleton` with a polite live region announcing the redirect (gh#1022).",
+      "DON'T: rely on per-page `onAuthError` for session expiry — it is only a click-to-sign-in button in the fallback alert (no provider). An expired session is an app-wide concern, not a page error.",
       "DO: classify errors by cause. Use session renewal/sign-in for 401, access guidance for 403, contextual correction for domain errors, and opt into showRetry only for transient network/5xx errors.",
       "DO: pass prerequisite for enabled:false queries. Pending + fetchStatus idle is unstarted, not loading, and never renders a skeleton.",
       "DO: rely on the localized, cause-specific error message — the raw backend/token/stack text is never shown. For a domain-specific message (e.g. a 422 field error) pass a custom errorRenderer.",
@@ -5269,6 +5271,46 @@
       "Any page using `useQuery` where the empty state and loading state are visually different — DataState enforces the correct visual for each phase without scattered `if` statements across the component tree."
     ]
   },
+  {
+    "example": "import { AuthExpiryProvider } from \"@godxjp/ui/query\";\n\nexport function Providers({ children }: { children: React.ReactNode }) {\n  return (\n    <AuthExpiryProvider\n      onAuthExpired={() => {\n        const returnTo = encodeURIComponent(window.location.href);\n        window.location.assign(`/auth/login?return_to=${returnTo}`);\n      }}\n    >\n      {children}\n    </AuthExpiryProvider>\n  );\n}",
+    "group": "feedback",
+    "importPath": "@godxjp/ui/query",
+    "name": "AuthExpiryProvider",
+    "props": [
+      {
+        "description": "Called ONCE per expiry — any number of simultaneous 401s share one call; re-armed after every auth-errored view has gone. Typically `window.location.assign(loginUrl(returnTo = location.href))`. Return a promise for a silent refresh (then invalidate queries); a throw/rejection brings back the sign-in alert, whose button calls this again.",
+        "name": "onAuthExpired",
+        "required": true,
+        "type": "(context: { error: unknown }) => void | Promise<void>"
+      },
+      {
+        "description": "The app.",
+        "name": "children",
+        "type": "ReactNode"
+      }
+    ],
+    "related": [
+      "DataState / InfiniteQueryState / AlertMutationFeedback / AlertQueryError — the surfaces that consult this provider.",
+      "classifyQueryError — decides what is auth-class (401, or a status-less 'unauthenticated / access token invalid / token expired' message).",
+      "ErrorSurface — the whole-page error surface; a session expiry is neither a page error nor an inline one."
+    ],
+    "rules": [],
+    "storyPath": "query/DataState.stories.tsx",
+    "tagline": "App-root handler for an expired session (401 / invalid or expired token): every DataState / InfiniteQueryState / AlertMutationFeedback / AlertQueryError calls it automatically, once, and shows a neutral pending state instead of an error alert. Also exported from @godxjp/ui.",
+    "usage": [
+      "DO: mount it ONCE near the root, inside the QueryClientProvider/AppProvider, and redirect to the IdP with the current URL as the return target. The IdP returns immediately while its own session is alive — the SSO norm (Google/Microsoft apps, OIDC SPA guidance): no page-level error for an expired session.",
+      "DO: expect the surfaces to keep their `skeleton` (DataState/InfiniteQueryState) or a small muted status line (AlertMutationFeedback/AlertQueryError) with `role=\"status\"` announcing 'redirecting to sign-in' — never a destructive alert.",
+      "DON'T: wire `onAuthError` on every DataState as the session strategy — that renders an alert and waits for a click. It is the no-provider fallback only.",
+      "DON'T: use it for 403 — forbidden is a permission state, not an expired session; it still renders the access-guidance alert.",
+      "DO: when there is no provider the 401 fallback is a neutral (tone=default, role=status) sign-in alert capped at `--query-auth-alert-max-inline-size` (36rem, `none` = full width) — backward compatible, but proportionate."
+    ],
+    "useCases": [
+      "An SSO app (GoDX ID / OIDC) whose access token expired while the tab was idle: the first 401 redirects to the IdP and back to the same URL, no error panel flashes.",
+      "A dashboard with five DataStates that all 401 in the same tick: exactly one redirect.",
+      "A form submit (`AlertMutationFeedback`) that 401s: a muted 'redirecting to sign-in' line instead of a red alert.",
+      "A silent token refresh: return a promise that refreshes and then `queryClient.invalidateQueries()`; the views recover from skeleton without ever showing an error."
+    ]
+  },
   {
     "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",
@@ -5313,7 +5355,7 @@
       "DO: Import from `@godxjp/ui/query` (not `@godxjp/ui`). Use the bundled `flattenItemPages` helper for any API that returns `{ items: T[] }` pages — it handles `undefined` data safely. Custom page shapes require a custom `flatten` function.",
       "DO: Always pass `skeleton` (e.g. `<SkeletonTable />` or `<SkeletonStat />`). It shows on initial `isPending`, on refetch-after-error, and whenever `data` is absent. Never show a blank area while loading.",
       "DO: Pass `empty` (an `<EmptyState>` node) to handle the zero-results case — without it the children render-prop is called with an empty array and you get a silent blank screen. Provide a custom `isEmpty` only when `TFlat` is not an array.",
-      "DO: Let errors remain cause-aware. Retry is automatic only for classified transient/network/5xx failures. Unknown errors do not get a blind retry unless `showRetry` or `onRetry` is explicitly supplied; 401 routes to `onAuthError`, and raw backend/token text is never rendered.",
+      "DO: Let errors remain cause-aware. Retry is automatic only for classified transient/network/5xx failures. Unknown errors do not get a blind retry unless `showRetry` or `onRetry` is explicitly supplied; a 401 is handled by the app-root `AuthExpiryProvider` (auto, once, skeleton + live region) or, without one, by the `onAuthError` sign-in button; raw backend/token text is never rendered.",
       "DON'T: Hand-roll a load-more button. The component renders a default centered outline Button when `hasNextPage` is true. Override only via `loadMore` (custom node) or `showLoadMore={false}` (hide entirely). Never call `query.fetchNextPage()` outside the component for pagination.",
       "DON'T: Use `InfiniteQueryState` for a `useQuery` result — it expects `UseInfiniteQueryResult` shape (`pages`, `hasNextPage`, `fetchNextPage`, `isFetchingNextPage`). For regular `useQuery` use `DataState` instead.",
       "DON'T: Confuse the two generics: `TPage` is the raw page shape from the API, `TFlat` is what `flatten` returns (usually `TItem[]`). The `children` render-prop receives `TFlat`, not `TPage`. Pass `isEmpty` if `TFlat` is not a plain array so empty detection works correctly."
@@ -7838,6 +7880,11 @@
         "name": "onValueChange",
         "type": "(value: string) => void"
       },
+      {
+        "description": "Strip-only mode (gh#1021): the tabs drive content OUTSIDE the strip. No tabpanel is rendered, and the selected tab's `aria-controls` points at this id, which is the consumer's own region (give it `role=\"region\"` and a name). Content there is never remounted on a tab switch, so a typed draft survives. With the compound form it applies to triggers without a declared `TabsContent` (a declared panel wins). A pure filter with NO region to point at is not a tab strip; use `Segmented`. The root's `aria-label`/`aria-labelledby` name the `role=\"tablist\"` (gh#1020), and a compound `TabsTrigger` takes `count`/`overflowCount`/`showZero`/`countLabel`, drawn exactly like `items[].count`.",
+        "name": "controls",
+        "type": "IdProp"
+      },
       {
         "defaultValue": "\"default\"",
         "description": "Trigger-strip appearance — this is Ant Design's `type` under the library's own `variant` vocabulary. `default` is the pill strip (antd has no equivalent). `line` is UNDERLINE-ONLY: the selected trigger gets no ring or card border at all — only the token-owned 2px primary bar (--tabs-indicator-{background,size,offset}) — so the `:focus-visible` keyboard ring stays visible and clearly distinct from selection. `card` gives each tab a boxed face on a rail (--tabs-card-*). `editable-card` is `card` plus the add button and per-tab remove shortcut, and needs `onEdit` to do anything. With `items`, the variant is forwarded to the list; when composing manually, pass the same value to `<TabsList variant=\"line\">`.",

package/agent/index.json

@@ -1,16 +1,16 @@
 {
   "counts": {
     "anti-ai-tells": 26,
-    "components": 175,
+    "components": 176,
     "patterns": 21,
     "rules": 50,
-    "tokens": 2074,
+    "tokens": 2080,
     "vocabulary": 14
   },
   "files": [
     {
       "file": "components-index.json",
-      "note": "46 KB — name + group + tagline for all 175. FETCH THIS FIRST, then fetch only the components you chose.",
+      "note": "47 KB — name + group + tagline for all 176. FETCH THIS FIRST, then fetch only the components you chose.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json"
     },
     {
@@ -48,19 +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/v31.2.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v31.4.0/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": 1760,
+      "component": 1765,
       "foundation": 211,
-      "semantic": 103
+      "semantic": 104
     },
     "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": "31.2.0"
+  "version": "31.4.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 175 components, 2074 design tokens,
-> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 31.2.0.
+> A Japanese-enterprise React design system: 176 components, 2080 design tokens,
+> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 31.4.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@31.2.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@31.4.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -15,10 +15,10 @@ that can only fetch URLs.
 ## Catalog
 
 - [patterns-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/patterns-index.json): 21 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): 46 KB — all 175 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): 47 KB — all 176 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–35 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.2 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` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 103 `semantic` roles, 1760 `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` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 104 `semantic` roles, 1765 `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): 50 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 26 shapes that make generated UI look generated, each with its fix.
@@ -26,7 +26,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/v31.2.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v31.4.0/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/patterns/async-data-state.json

@@ -4,7 +4,7 @@
     "data-state",
     "query-states"
   ],
-  "code": "import { DataState, classifyQueryError } from \"@godxjp/ui/query\";\nimport { EmptyState } from \"@godxjp/ui/data-display\";\nimport { SkeletonTable } from \"@godxjp/ui/feedback\";\nimport { Building2, Inbox } from \"lucide-react\";\n\n// ONE primary state renders at a time; DataState makes them mutually exclusive:\n//   prerequisite → skeleton(loading) → data → empty → error   (never two at once).\n//\n// enabled:false is PREREQUISITE/idle, NOT loading. TanStack reports isPending while a query is\n// disabled, but fetchStatus stays \"idle\" (no request in flight) — DataState renders the prerequisite\n// slot, so a disabled query shows an instruction, NOT an endless skeleton.\n//   const query = useQuery({ queryKey: [\"members\", orgId], queryFn, enabled: Boolean(orgId) });\n//\n// A background refetch over EXISTING data keeps the content on screen (no skeleton flash) and\n// announces the busy state politely — stale/placeholder refresh is handled for you.\n//\n// Errors are classified by CAUSE, not blanket-retried:\n//   auth (401)         → onAuthError: renew session / sign in again  (NOT a retry)\n//   forbidden (403)    → permission message + access path            (no retry)\n//   notFound (404)     → contextual not-found                        (no retry)\n//   validation (400/422)→ corrective guidance                        (no retry)\n//   transient (408/429/5xx/network) → Retry offered automatically\n//   unknown            → neutral; opt into Retry via showRetry/onRetry only if it can help\nexport function MembersPanel({ query, orgId, onSignIn }: {\n  query: any; orgId?: string; onSignIn: () => void;\n}) {\n  return (\n    <DataState\n      query={query}\n      prerequisite={<EmptyState icon={Building2} variant=\"section\" title=\"組織を選択してください\"\n        description=\"メンバーを表示するには、上のセレクタで組織を選びます。\" />}\n      skeleton={<SkeletonTable rows={8} columns={4} />}\n      empty={<EmptyState icon={Inbox} variant=\"section\" title=\"メンバーがいません\"\n        description=\"この組織にはまだメンバーが登録されていません。\" />}\n      isEmpty={(data) => data.items.length === 0}\n      onAuthError={onSignIn}\n    >\n      {(data) => <MemberTable items={data.items} />}\n    </DataState>\n  );\n}\n\n// Need a bespoke error surface? Pass errorRenderer and branch on the classified category — the\n// default detail is always a localized message (never raw token / endpoint / stack text):\n//   errorRenderer={(error, retry) => {\n//     const { category } = classifyQueryError(error);\n//     if (category === \"auth\") return <SessionExpired onRenew={onSignIn} />;\n//     if (category === \"forbidden\") return <NoAccess />;\n//     if (category === \"transient\") return <Retryable onRetry={retry} />;\n//     return <GenericError />;\n//   }}\n// RULE: pagination/footer chrome NEVER renders outside the populated-data branch (see data-table-page).",
+  "code": "import { DataState, classifyQueryError } from \"@godxjp/ui/query\";\nimport { EmptyState } from \"@godxjp/ui/data-display\";\nimport { SkeletonTable } from \"@godxjp/ui/feedback\";\nimport { Building2, Inbox } from \"lucide-react\";\n\n// ONE primary state renders at a time; DataState makes them mutually exclusive:\n//   prerequisite → skeleton(loading) → data → empty → error   (never two at once).\n//\n// enabled:false is PREREQUISITE/idle, NOT loading. TanStack reports isPending while a query is\n// disabled, but fetchStatus stays \"idle\" (no request in flight) — DataState renders the prerequisite\n// slot, so a disabled query shows an instruction, NOT an endless skeleton.\n//   const query = useQuery({ queryKey: [\"members\", orgId], queryFn, enabled: Boolean(orgId) });\n//\n// A background refetch over EXISTING data keeps the content on screen (no skeleton flash) and\n// announces the busy state politely — stale/placeholder refresh is handled for you.\n//\n// Errors are classified by CAUSE, not blanket-retried:\n//   auth (401)         → handled app-wide by <AuthExpiryProvider onAuthExpired> at the root:\n//                        auto-redirect to sign-in ONCE, skeleton stays (NOT a retry, NOT an alert)\n//   forbidden (403)    → permission message + access path            (no retry)\n//   notFound (404)     → contextual not-found                        (no retry)\n//   validation (400/422)→ corrective guidance                        (no retry)\n//   transient (408/429/5xx/network) → Retry offered automatically\n//   unknown            → neutral; opt into Retry via showRetry/onRetry only if it can help\n// App root (once): <AuthExpiryProvider onAuthExpired={() => redirectToSignIn(location.href)}>\nexport function MembersPanel({ query, orgId }: { query: any; orgId?: string }) {\n  return (\n    <DataState\n      query={query}\n      prerequisite={<EmptyState icon={Building2} variant=\"section\" title=\"組織を選択してください\"\n        description=\"メンバーを表示するには、上のセレクタで組織を選びます。\" />}\n      skeleton={<SkeletonTable rows={8} columns={4} />}\n      empty={<EmptyState icon={Inbox} variant=\"section\" title=\"メンバーがいません\"\n        description=\"この組織にはまだメンバーが登録されていません。\" />}\n      isEmpty={(data) => data.items.length === 0}\n    >\n      {(data) => <MemberTable items={data.items} />}\n    </DataState>\n  );\n}\n\n// Need a bespoke error surface? Pass errorRenderer and branch on the classified category — the\n// default detail is always a localized message (never raw token / endpoint / stack text):\n//   errorRenderer={(error, retry) => {\n//     const { category } = classifyQueryError(error);\n//     if (category === \"forbidden\") return <NoAccess />;\n//     if (category === \"transient\") return <Retryable onRetry={retry} />;\n//     return <GenericError />;\n//   }}\n// RULE: pagination/footer chrome NEVER renders outside the populated-data branch (see data-table-page).",
   "name": "async-data-state",
   "tagline": "The full async state machine — ONE primary state at a time: prerequisite, disabled-vs-loading, stale refresh, populated, real-empty, and cause-aware error (401/403/404/422/transient) with correct recovery.",
   "tags": [

package/agent/patterns.json

@@ -182,7 +182,7 @@
       "data-state",
       "query-states"
     ],
-    "code": "import { DataState, classifyQueryError } from \"@godxjp/ui/query\";\nimport { EmptyState } from \"@godxjp/ui/data-display\";\nimport { SkeletonTable } from \"@godxjp/ui/feedback\";\nimport { Building2, Inbox } from \"lucide-react\";\n\n// ONE primary state renders at a time; DataState makes them mutually exclusive:\n//   prerequisite → skeleton(loading) → data → empty → error   (never two at once).\n//\n// enabled:false is PREREQUISITE/idle, NOT loading. TanStack reports isPending while a query is\n// disabled, but fetchStatus stays \"idle\" (no request in flight) — DataState renders the prerequisite\n// slot, so a disabled query shows an instruction, NOT an endless skeleton.\n//   const query = useQuery({ queryKey: [\"members\", orgId], queryFn, enabled: Boolean(orgId) });\n//\n// A background refetch over EXISTING data keeps the content on screen (no skeleton flash) and\n// announces the busy state politely — stale/placeholder refresh is handled for you.\n//\n// Errors are classified by CAUSE, not blanket-retried:\n//   auth (401)         → onAuthError: renew session / sign in again  (NOT a retry)\n//   forbidden (403)    → permission message + access path            (no retry)\n//   notFound (404)     → contextual not-found                        (no retry)\n//   validation (400/422)→ corrective guidance                        (no retry)\n//   transient (408/429/5xx/network) → Retry offered automatically\n//   unknown            → neutral; opt into Retry via showRetry/onRetry only if it can help\nexport function MembersPanel({ query, orgId, onSignIn }: {\n  query: any; orgId?: string; onSignIn: () => void;\n}) {\n  return (\n    <DataState\n      query={query}\n      prerequisite={<EmptyState icon={Building2} variant=\"section\" title=\"組織を選択してください\"\n        description=\"メンバーを表示するには、上のセレクタで組織を選びます。\" />}\n      skeleton={<SkeletonTable rows={8} columns={4} />}\n      empty={<EmptyState icon={Inbox} variant=\"section\" title=\"メンバーがいません\"\n        description=\"この組織にはまだメンバーが登録されていません。\" />}\n      isEmpty={(data) => data.items.length === 0}\n      onAuthError={onSignIn}\n    >\n      {(data) => <MemberTable items={data.items} />}\n    </DataState>\n  );\n}\n\n// Need a bespoke error surface? Pass errorRenderer and branch on the classified category — the\n// default detail is always a localized message (never raw token / endpoint / stack text):\n//   errorRenderer={(error, retry) => {\n//     const { category } = classifyQueryError(error);\n//     if (category === \"auth\") return <SessionExpired onRenew={onSignIn} />;\n//     if (category === \"forbidden\") return <NoAccess />;\n//     if (category === \"transient\") return <Retryable onRetry={retry} />;\n//     return <GenericError />;\n//   }}\n// RULE: pagination/footer chrome NEVER renders outside the populated-data branch (see data-table-page).",
+    "code": "import { DataState, classifyQueryError } from \"@godxjp/ui/query\";\nimport { EmptyState } from \"@godxjp/ui/data-display\";\nimport { SkeletonTable } from \"@godxjp/ui/feedback\";\nimport { Building2, Inbox } from \"lucide-react\";\n\n// ONE primary state renders at a time; DataState makes them mutually exclusive:\n//   prerequisite → skeleton(loading) → data → empty → error   (never two at once).\n//\n// enabled:false is PREREQUISITE/idle, NOT loading. TanStack reports isPending while a query is\n// disabled, but fetchStatus stays \"idle\" (no request in flight) — DataState renders the prerequisite\n// slot, so a disabled query shows an instruction, NOT an endless skeleton.\n//   const query = useQuery({ queryKey: [\"members\", orgId], queryFn, enabled: Boolean(orgId) });\n//\n// A background refetch over EXISTING data keeps the content on screen (no skeleton flash) and\n// announces the busy state politely — stale/placeholder refresh is handled for you.\n//\n// Errors are classified by CAUSE, not blanket-retried:\n//   auth (401)         → handled app-wide by <AuthExpiryProvider onAuthExpired> at the root:\n//                        auto-redirect to sign-in ONCE, skeleton stays (NOT a retry, NOT an alert)\n//   forbidden (403)    → permission message + access path            (no retry)\n//   notFound (404)     → contextual not-found                        (no retry)\n//   validation (400/422)→ corrective guidance                        (no retry)\n//   transient (408/429/5xx/network) → Retry offered automatically\n//   unknown            → neutral; opt into Retry via showRetry/onRetry only if it can help\n// App root (once): <AuthExpiryProvider onAuthExpired={() => redirectToSignIn(location.href)}>\nexport function MembersPanel({ query, orgId }: { query: any; orgId?: string }) {\n  return (\n    <DataState\n      query={query}\n      prerequisite={<EmptyState icon={Building2} variant=\"section\" title=\"組織を選択してください\"\n        description=\"メンバーを表示するには、上のセレクタで組織を選びます。\" />}\n      skeleton={<SkeletonTable rows={8} columns={4} />}\n      empty={<EmptyState icon={Inbox} variant=\"section\" title=\"メンバーがいません\"\n        description=\"この組織にはまだメンバーが登録されていません。\" />}\n      isEmpty={(data) => data.items.length === 0}\n    >\n      {(data) => <MemberTable items={data.items} />}\n    </DataState>\n  );\n}\n\n// Need a bespoke error surface? Pass errorRenderer and branch on the classified category — the\n// default detail is always a localized message (never raw token / endpoint / stack text):\n//   errorRenderer={(error, retry) => {\n//     const { category } = classifyQueryError(error);\n//     if (category === \"forbidden\") return <NoAccess />;\n//     if (category === \"transient\") return <Retryable onRetry={retry} />;\n//     return <GenericError />;\n//   }}\n// RULE: pagination/footer chrome NEVER renders outside the populated-data branch (see data-table-page).",
     "name": "async-data-state",
     "tagline": "The full async state machine — ONE primary state at a time: prerequisite, disabled-vs-loading, stale refresh, populated, real-empty, and cause-aware error (401/403/404/422/transient) with correct recovery.",
     "tags": [

package/agent/tokens.json

@@ -1625,6 +1625,12 @@
     "tier": "semantic",
     "value": "none"
   },
+  {
+    "description": "The widest share of the header row the actions (`extra`) keep on ONE row before they wrap (gh#1025); the title keeps the rest. `initial` — default 60% at the call site.",
+    "name": "--page-header-extra-max-measure",
+    "tier": "semantic",
+    "value": "initial"
+  },
   {
     "description": "PageContainer `toolbar` — the fixed chrome band between the header and the (scrolling) body. ALL THREE knobs are quiet by default (rule #44): background — `transparent`, i.e. the band shows the page ground exactly as it did before the knob existed. It is bound at `:root` and NOT `initial`, unlike the divider below, because the default is a plain CSS keyword rather than another role token: there is nothing for a scoped [data-tenant]/.dark override to re-resolve, so the `initial` + call-site-fallback dance would buy nothing and only hide the default from anyone reading this file. A service that wants the band to read as its own surface — the design that asked for this knob puts a chat channel's workflow rail on the card ground — sets `--page-toolbar-background: hsl(var(--card));` ONCE in its theme. Never `className=\"bg-card\"` at the call site: that is hand-laid page chrome, it paints only under `variant=\"flush\"` gutters correctly by accident, and it cannot be re-themed per tenant. pad-block 0 — the band's ONLY breathing room, and the only one it should ever have. The band is chrome, so it sits FLUSH against the header above and the body below (src/styles/layout.css cancels the container's --page-band-gap from the band itself); there is deliberately no outside space to tune, because a ruled, painted band floating in a void divides nothing. A service that opts into the background or the divider gives the band its inset HERE (`--page-toolbar-pad-block: var(--space-2)`) instead of padding the strip at the call site. Still 0 by default: a transparent band is not a surface and has no inside to breathe, and under `fill` every pixel of it comes straight off the scroll viewport the slot exists to protect. divider — declared `initial` so the CALL SITE can fall back to --page-header-divider (`var(--page-toolbar-divider, var(--page-header-divider))`). One theme declaration therefore rules the whole page chrome consistently, and a scoped [data-tenant]/.dark override of the header divider still reaches the band — a `:root` binding would freeze it at the :root value (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"). Set `--page-toolbar-divider: none` to silence just this band.",
     "name": "--page-toolbar-background",
@@ -6983,6 +6989,12 @@
     "tier": "component",
     "value": "var(--space-stack-sm)"
   },
+  {
+    "description": "The sign-in fallback a query surface paints for an expired session when no AuthExpiryProvider handles it (gh#1022). An expired session is an expected, recoverable condition, so it is capped at a reading measure instead of spanning the page body its DataState wraps. `none` restores the full-width alert.",
+    "name": "--query-auth-alert-max-inline-size",
+    "tier": "component",
+    "value": "36rem"
+  },
   {
     "description": "TOOLTIP — the transient label surface. Every constant here was a Tailwind literal baked into the component (`max-w-xs px-2 py-1 rounded-md text-xs shadow-md`), so a service could not retune tooltip density or measure without forking the component (rule #45). Defaults reproduce the previous look exactly, so adopting this changes nothing until a theme opts in.",
     "name": "--tooltip-max-width",
@@ -9378,7 +9390,7 @@
     "value": "initial"
   },
   {
-    "description": "Counter pill beside the label (gh#602). Geometry matches Button/Toggle count pills; colour does not. A Badge `secondary` fill is `--muted`, which is byte-identical to `--segmented-track-background`, so a consumer-nested Badge is 1.00:1 on unselected items. The pill therefore wears an opaque `--primary` / `--primary-foreground` pair that clears WCAG 2.2 SC 1.4.11 against both the recessed track (`--muted`) and the lifted slab (`--background`) in light and dark — measured in segmented-count-contrast.test.ts. antd has no `count` on SegmentedItemType; this knob exists because every faceted filter in the wild needs one and nesting Badge in `label` was the only API until now.",
+    "description": "Counter pill beside the label (gh#602). Geometry matches Button/Toggle count pills; COLOUR follows `Tabs` (gh#1019): resting = `--background` / `--muted-foreground`, byte-identical to a resting `.ui-tabs-count` on a CARD tab — the Tabs rule for a pill whose host surface is `--muted`, which the Segmented track is (a `--muted` pill there is 1.00:1, shape gone). The selected segment's pill = `--primary` / `--primary-foreground`, identical to the active tab's. gh#602 had painted EVERY pill primary — four identical blobs that dropped the one thing a count pill in a one-of-N control can say, \"this is the chosen one\". The resting number is held to SC 1.4.3 (≥ 4.5:1 in both themes, measured in segmented-count-tabs-convention-1019.test.ts); it is not the selection indicator, so its fill only has to stand off the track, not reach 3:1. antd has no `count` on SegmentedItemType; this knob exists because every faceted filter in the wild needs one and nesting Badge in `label` was the only API until now.",
     "name": "--segmented-count-min-width",
     "tier": "component",
     "value": "var(--button-count-min-width)"
@@ -9408,17 +9420,41 @@
     "value": "var(--space-1)"
   },
   {
-    "description": "Segmented (one-of-N control) component tokens. EVERY VALUE BELOW IS A PORT OF AN ESTABLISHED SEGMENTED SPEC, NOT A CHOICE. The geometry and the role assignments come from the widely-implemented enterprise Segmented control, transcribed as ratios rather than as pixels: track padding: the bold line width → 2px track background: the page's recessed neutral item colour: the label ink · hover / selected colour: the body ink item hover fill: the lighter neutral · item active fill: the heavier neutral item selected fill: the elevated surface label height = control height − track padding × 2 → 32 − 4 = 28 label padding-inline = control padding-x − border width → 12 − 1 = 11 icon gap = the small margin step / 2 → 6 THE ROLE PORTS ARE THE ONES `Tabs` ALREADY MADE. TabsList is `bg-muted` and an active TabsTrigger is `bg-background` + `shadow-sm` — the same track-and-slab pair, so a Segmented and a default Tabs strip read as one control family in both themes rather than two near-misses. That matters more than reproducing the source dark ramp literally: that ramp's dark track is BLACK with a lighter slab on it, while this palette's dark `--muted` sits above `--background`, so a literal port would invert the pairing relative to every Tabs strip on the same page. NOT ONE OF THEM READS THE BRAND SEED. The spec's own derivation produces identical Segmented values for its default seed and for this system's `#0071bd` — the control is neutral by construction, and the only brand ink it can carry is the focus mark, which styles/focus-ring.css owns. So the ports below are ROLE references (the same neutrals this system already names), never copied hex. The disabled state is the ONE place this departs. The source recolours to a disabled ink and changes nothing else; this system disables every control with the one `--disabled-opacity` knob, and a single library-wide answer outranks a per-component one. The other thing NOT ported is the sliding thumb: it exists to animate between items, and the implementations that have one remove the `-item-selected` class while it runs, which means the selected state lives in two places at once. A static selected slab reads identically at rest and cannot desynchronise.",
+    "description": "default = hsl(var(--background)) at the call site",
     "name": "--segmented-count-background",
     "tier": "component",
     "value": "initial"
   },
   {
-    "description": "Segmented (one-of-N control) component tokens. EVERY VALUE BELOW IS A PORT OF AN ESTABLISHED SEGMENTED SPEC, NOT A CHOICE. The geometry and the role assignments come from the widely-implemented enterprise Segmented control, transcribed as ratios rather than as pixels: track padding: the bold line width → 2px track background: the page's recessed neutral item colour: the label ink · hover / selected colour: the body ink item hover fill: the lighter neutral · item active fill: the heavier neutral item selected fill: the elevated surface label height = control height − track padding × 2 → 32 − 4 = 28 label padding-inline = control padding-x − border width → 12 − 1 = 11 icon gap = the small margin step / 2 → 6 THE ROLE PORTS ARE THE ONES `Tabs` ALREADY MADE. TabsList is `bg-muted` and an active TabsTrigger is `bg-background` + `shadow-sm` — the same track-and-slab pair, so a Segmented and a default Tabs strip read as one control family in both themes rather than two near-misses. That matters more than reproducing the source dark ramp literally: that ramp's dark track is BLACK with a lighter slab on it, while this palette's dark `--muted` sits above `--background`, so a literal port would invert the pairing relative to every Tabs strip on the same page. NOT ONE OF THEM READS THE BRAND SEED. The spec's own derivation produces identical Segmented values for its default seed and for this system's `#0071bd` — the control is neutral by construction, and the only brand ink it can carry is the focus mark, which styles/focus-ring.css owns. So the ports below are ROLE references (the same neutrals this system already names), never copied hex. The disabled state is the ONE place this departs. The source recolours to a disabled ink and changes nothing else; this system disables every control with the one `--disabled-opacity` knob, and a single library-wide answer outranks a per-component one. The other thing NOT ported is the sliding thumb: it exists to animate between items, and the implementations that have one remove the `-item-selected` class while it runs, which means the selected state lives in two places at once. A static selected slab reads identically at rest and cannot desynchronise.",
+    "description": "default = hsl(var(--muted-foreground)) at the call site",
     "name": "--segmented-count-color",
     "tier": "component",
     "value": "initial"
   },
+  {
+    "description": "default = hsl(var(--primary)) at the call site",
+    "name": "--segmented-count-selected-background",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "default = 100% at the call site",
+    "name": "--segmented-count-selected-background-alpha",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "default = hsl(var(--primary-foreground)) at the call site",
+    "name": "--segmented-count-selected-color",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "default = var(--stroke-hairline) at the call site",
+    "name": "--segmented-count-forced-outline-width",
+    "tier": "component",
+    "value": "initial"
+  },
   {
     "description": "Rule weight, both orientations and both halves of a labelled rule. default = var(--stroke-hairline), resolved at the call site (gh#906)",
     "name": "--separator-rule-size",

package/dist/components/admin/index.d.ts

@@ -10,6 +10,8 @@ export { Field } from "../data-entry/field.js";
 export { Descriptions } from "../data-display/descriptions.js";
 export { SkeletonRows, SkeletonTable, SkeletonDetail, SkeletonStat } from "../feedback/skeleton.js";
 export { Alert, AlertTitle, AlertContent, AlertDescription, AlertActions, AlertQueryError, } from "../feedback/alert.js";
+export { AuthExpiryProvider } from "../feedback/auth-expiry.js";
+export type { AuthExpiryProviderProps } from "../feedback/auth-expiry.js";
 export { SearchInput } from "../data-entry/search-input.js";
 export { Upload, collectUploadCommitActions, createUploadItem, useUploadDraft, } from "../data-entry/upload.js";
 export { Cascader } from "../data-entry/cascader.js";

package/dist/components/admin/index.js

@@ -14,6 +14,7 @@ import {
   AlertActions,
   AlertQueryError
 } from "../feedback/alert.js";
+import { AuthExpiryProvider } from "../feedback/auth-expiry.js";
 import { SearchInput } from "../data-entry/search-input.js";
 import {
   Upload,
@@ -48,6 +49,7 @@ export {
   AlertDialog,
   AlertQueryError,
   AlertTitle,
+  AuthExpiryProvider,
   Badge,
   Cascader,
   Descriptions,

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

@@ -497,6 +497,7 @@ function Upload({
           disabled,
           onClick: openPicker,
           "aria-label": triggerAriaLabel,
+          className: "ui-upload-trigger",
           children: [
             /* @__PURE__ */ jsx(
               TriggerIcon,
@@ -553,7 +554,17 @@ function Upload({
       hiddenInput,
       liveRegion,
       rejection && /* @__PURE__ */ jsx("p", { role: "alert", className: "text-error-strong", children: rejection }),
-      /* @__PURE__ */ jsx(Button, { type: "button", disabled, variant: triggerVariant, onClick: openPicker, children: children ?? t("dataEntry.upload.addImage") }),
+      /* @__PURE__ */ jsx(
+        Button,
+        {
+          type: "button",
+          disabled,
+          variant: triggerVariant,
+          onClick: openPicker,
+          className: "ui-upload-trigger",
+          children: children ?? t("dataEntry.upload.addImage")
+        }
+      ),
       list
     ] });
   }

package/dist/components/feedback/alert.d.ts

@@ -35,6 +35,10 @@ export declare const AlertActions: React.ForwardRefExoticComponent<React.HTMLAtt
  *   offer Retry (`onRetry`); permission/not-found/validation offer neither by default.
  * - **Legacy mode** (no `category`, e.g. mutation/infinite feedback): shows the cleaned domain
  *   message (`humanError`) + optional Retry — form-submit corrective guidance stays visible.
+ * - **Under an `AuthExpiryProvider`** an auth-class error (either mode) is never painted as an
+ *   alert: the provider's `onAuthExpired` runs once and this renders a small polite status
+ *   ("redirecting to sign-in") instead. If the handler fails, the sign-in alert comes back with its
+ *   button wired to the provider (gh#1022).
  */
 export declare function AlertQueryError({ error, category, onRetry, onAuthAction, className, }: AlertQueryErrorProp): React.JSX.Element;
 export declare const Alert: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {