@godxjp/ui 31.1.0 → 31.3.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.1.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 31.3.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,19 +47,19 @@ 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
    first; it exists because that is the mistake.
-2. `components/<Name>.json` — one file per component (1 KB–34 KB, median 6 KB), carrying its props,
+2. `components/<Name>.json` — one file per component (1 KB–35 KB, median 6 KB), carrying its props,
    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` — 2075 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
+   1761 `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.
@@ -145,7 +145,7 @@ has stopped following the brand.
 |---|---|---|---|
 | `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` |
+| `component` | 1761 | 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/DataTable.json

@@ -14,7 +14,7 @@
       "type": "T[]"
     },
     {
-      "description": "Lean column definitions (adapted to TanStack internally — `meta.lean` is the declared home for every custom column option, so `priority` needs no second TanStack channel). Each column: { key: string; header: ReactNode; ariaLabel?: string; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hideBelow?: 'sm'|'md'|'lg'|'xl' (same contract as Flex hideBelow — stamped as data-hide-below on th/td); hiddenOnMobile?: boolean (alias for hideBelow:'md'); enableHiding?: boolean; pin?: 'end'; priority?: 'primary'|'secondary'|'meta'|'actions' }. priority is the column-priority contract read by preset=\"action-collection\" — DataTable stamps it as data-priority on the <th> AND every <td> of the column, so the preset can allocate the narrow-frame measure; leave the free-text column unmarked (it takes the remaining space), and prefer priority over width under the preset because an explicit width utility wins the cascade and defeats the measure. If render is omitted, the raw value at row[key] is rendered as a string. sortable opts the column into the sort cycle (client-side by default, or server-side via sort+onSortChange). enableHiding (default true) lists the column in DataTable.ViewOptions; set false to keep a key/actions column always visible. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow — pin at most one column. ariaLabel gives a VISUALLY-EMPTY header (header='' — an action or selection column) a screen-reader name (e.g. 'Actions'/'Select'): it renders as an sr-only label inside the <th> so the column is never nameless (axe: empty-table-header). ANT DESIGN PARITY on the same column: fixed:'start'|'end' freezes the column against a scroll edge (logical, so it mirrors in RTL; the stacking offsets are MEASURED from the rendered header, so several adjacent frozen columns are correct at any width — pin:'end' is the older spelling of fixed:'end'). ellipsis holds the cell to one line and keeps the full value as its title (it also switches the table to table-layout: fixed, without which no ellipsis truncates anything). sorter is antd's richer `sortable`: true | (a, b) => number | { compare, multiple }, where multiple is the MULTI-column sort priority (highest sorts first). sortOrder / defaultSortOrder / sortDirections control and shape the cycle per column, and showSorterTooltip explains the next step. filters + onFilter + filteredValue / defaultFilteredValue / filterMultiple add a real filter menu to the header (filterMultiple: false makes it single-choice); omit onFilter for a server filter and drive it from the table's onFilterChange.",
+      "description": "Lean column definitions (adapted to TanStack internally — `meta.lean` is the declared home for every custom column option, so `priority` needs no second TanStack channel). Each column: { key: string; header: ReactNode; ariaLabel?: string; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hideBelow?: 'sm'|'md'|'lg'|'xl' (same contract as Flex hideBelow — stamped as data-hide-below on th/td); hiddenOnMobile?: boolean (alias for hideBelow:'md'); enableHiding?: boolean; pin?: 'end'; priority?: 'primary'|'secondary'|'meta'|'actions'; flush?: boolean }. flush (gh#1016 — the same word as TableCell flush / CardContent flush) drops the column's BODY cell padding so a self-padded row primitive owns the inset: a selectable list whose single column renders a `ListRow` writes `{ key: 'row', header: '', ariaLabel: …, flush: true, render: (m) => <ListRow asChild …><a/></ListRow> }` — the ListRow then sits 16px from the checkbox (not 32px) and the row is ListRow's own height; an unread ListRow in a flush cell paints `--list-row-unread-background` across the whole table row (checkbox cell included). The header keeps its padding, so the header label sits on the ListRow's inset. Never zero the cell with a className instead. priority is the column-priority contract read by preset=\"action-collection\" — DataTable stamps it as data-priority on the <th> AND every <td> of the column, so the preset can allocate the narrow-frame measure; leave the free-text column unmarked (it takes the remaining space), and prefer priority over width under the preset because an explicit width utility wins the cascade and defeats the measure. If render is omitted, the raw value at row[key] is rendered as a string. sortable opts the column into the sort cycle (client-side by default, or server-side via sort+onSortChange). enableHiding (default true) lists the column in DataTable.ViewOptions; set false to keep a key/actions column always visible. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow — pin at most one column. ariaLabel gives a VISUALLY-EMPTY header (header='' — an action or selection column) a screen-reader name (e.g. 'Actions'/'Select'): it renders as an sr-only label inside the <th> so the column is never nameless (axe: empty-table-header). ANT DESIGN PARITY on the same column: fixed:'start'|'end' freezes the column against a scroll edge (logical, so it mirrors in RTL; the stacking offsets are MEASURED from the rendered header, so several adjacent frozen columns are correct at any width — pin:'end' is the older spelling of fixed:'end'). ellipsis holds the cell to one line and keeps the full value as its title (it also switches the table to table-layout: fixed, without which no ellipsis truncates anything). sorter is antd's richer `sortable`: true | (a, b) => number | { compare, multiple }, where multiple is the MULTI-column sort priority (highest sorts first). sortOrder / defaultSortOrder / sortDirections control and shape the cycle per column, and showSorterTooltip explains the next step. filters + onFilter + filteredValue / defaultFilteredValue / filterMultiple add a real filter menu to the header (filterMultiple: false makes it single-choice); omit onFilter for a server filter and drive it from the table's onFilterChange.",
       "name": "columns",
       "required": true,
       "type": "ColumnDef<T>[]"

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/ListRow.json

@@ -75,6 +75,7 @@
   "usage": [
     "DO use ListRow for a SHORT (≈2–8 item) list of entities inside a Card where each row is one line with an action — account sessions, API keys, linked identities, passkeys. Stack rows in a `<Card><CardContent flush>` so the rows draw their own quiet dividers edge-to-edge.",
     "DON'T reach for DataTable here — it carries sorting/selection/pagination chrome that a 3-item list doesn't need. DON'T nest a Card per row either (card-in-card). ListRow is the in-between surface.",
+    "DO host ListRow in a DataTable column when the list needs ROW SELECTION (a mail/notification inbox with bulk actions) — DataTable is the only primitive that selects rows. Mark that column `flush: true` so the cell drops its own padding and the ListRow owns the inset (gh#1016); without it the cell padding stacks on the row's (a 32px dead gap after the checkbox, taller rows) and the unread band stops at the checkbox cell. DON'T zero the cell with a className.",
     "DO write a list of LINKS as `<Flex as=\"ul\" marker=\"none\" direction=\"col\" gap=\"none\">` + `<ListRow as=\"li\" asChild><Link/></ListRow>` — one call gives the list item, the whole-row link and the divider. DON'T wrap the row in your own `<li>` or `role=\"listitem\"` element to get list semantics back: the divider rule reads `:not(:last-child)` among the rows themselves, so a wrapper per row makes each one an only child and EVERY divider disappears — silently, which is why `ui-audit` now flags it as `no-hand-rolled-list`.",
     "DON'T hand-roll `<div className=\"flex items-center justify-between border-b py-3\">` — that is exactly the repeated pattern ListRow replaces (border/radius/padding are tokenized via `--list-row-*`).",
     "DO put the row's action in `trailing` (a `ghost`/`outline` Button, a DropdownMenu trigger, a Switch, or a status Badge). DO pass `as=\"li\"` when the rows live inside a semantic list, and build that list as `<Flex as=\"ul\" marker=\"none\">` — `ui-audit` flags a raw `<ul>`/`role=\"list\"` as `no-hand-rolled-list`.",

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

@@ -3380,7 +3380,7 @@
         "type": "T[]"
       },
       {
-        "description": "Lean column definitions (adapted to TanStack internally — `meta.lean` is the declared home for every custom column option, so `priority` needs no second TanStack channel). Each column: { key: string; header: ReactNode; ariaLabel?: string; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hideBelow?: 'sm'|'md'|'lg'|'xl' (same contract as Flex hideBelow — stamped as data-hide-below on th/td); hiddenOnMobile?: boolean (alias for hideBelow:'md'); enableHiding?: boolean; pin?: 'end'; priority?: 'primary'|'secondary'|'meta'|'actions' }. priority is the column-priority contract read by preset=\"action-collection\" — DataTable stamps it as data-priority on the <th> AND every <td> of the column, so the preset can allocate the narrow-frame measure; leave the free-text column unmarked (it takes the remaining space), and prefer priority over width under the preset because an explicit width utility wins the cascade and defeats the measure. If render is omitted, the raw value at row[key] is rendered as a string. sortable opts the column into the sort cycle (client-side by default, or server-side via sort+onSortChange). enableHiding (default true) lists the column in DataTable.ViewOptions; set false to keep a key/actions column always visible. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow — pin at most one column. ariaLabel gives a VISUALLY-EMPTY header (header='' — an action or selection column) a screen-reader name (e.g. 'Actions'/'Select'): it renders as an sr-only label inside the <th> so the column is never nameless (axe: empty-table-header). ANT DESIGN PARITY on the same column: fixed:'start'|'end' freezes the column against a scroll edge (logical, so it mirrors in RTL; the stacking offsets are MEASURED from the rendered header, so several adjacent frozen columns are correct at any width — pin:'end' is the older spelling of fixed:'end'). ellipsis holds the cell to one line and keeps the full value as its title (it also switches the table to table-layout: fixed, without which no ellipsis truncates anything). sorter is antd's richer `sortable`: true | (a, b) => number | { compare, multiple }, where multiple is the MULTI-column sort priority (highest sorts first). sortOrder / defaultSortOrder / sortDirections control and shape the cycle per column, and showSorterTooltip explains the next step. filters + onFilter + filteredValue / defaultFilteredValue / filterMultiple add a real filter menu to the header (filterMultiple: false makes it single-choice); omit onFilter for a server filter and drive it from the table's onFilterChange.",
+        "description": "Lean column definitions (adapted to TanStack internally — `meta.lean` is the declared home for every custom column option, so `priority` needs no second TanStack channel). Each column: { key: string; header: ReactNode; ariaLabel?: string; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hideBelow?: 'sm'|'md'|'lg'|'xl' (same contract as Flex hideBelow — stamped as data-hide-below on th/td); hiddenOnMobile?: boolean (alias for hideBelow:'md'); enableHiding?: boolean; pin?: 'end'; priority?: 'primary'|'secondary'|'meta'|'actions'; flush?: boolean }. flush (gh#1016 — the same word as TableCell flush / CardContent flush) drops the column's BODY cell padding so a self-padded row primitive owns the inset: a selectable list whose single column renders a `ListRow` writes `{ key: 'row', header: '', ariaLabel: …, flush: true, render: (m) => <ListRow asChild …><a/></ListRow> }` — the ListRow then sits 16px from the checkbox (not 32px) and the row is ListRow's own height; an unread ListRow in a flush cell paints `--list-row-unread-background` across the whole table row (checkbox cell included). The header keeps its padding, so the header label sits on the ListRow's inset. Never zero the cell with a className instead. priority is the column-priority contract read by preset=\"action-collection\" — DataTable stamps it as data-priority on the <th> AND every <td> of the column, so the preset can allocate the narrow-frame measure; leave the free-text column unmarked (it takes the remaining space), and prefer priority over width under the preset because an explicit width utility wins the cascade and defeats the measure. If render is omitted, the raw value at row[key] is rendered as a string. sortable opts the column into the sort cycle (client-side by default, or server-side via sort+onSortChange). enableHiding (default true) lists the column in DataTable.ViewOptions; set false to keep a key/actions column always visible. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow — pin at most one column. ariaLabel gives a VISUALLY-EMPTY header (header='' — an action or selection column) a screen-reader name (e.g. 'Actions'/'Select'): it renders as an sr-only label inside the <th> so the column is never nameless (axe: empty-table-header). ANT DESIGN PARITY on the same column: fixed:'start'|'end' freezes the column against a scroll edge (logical, so it mirrors in RTL; the stacking offsets are MEASURED from the rendered header, so several adjacent frozen columns are correct at any width — pin:'end' is the older spelling of fixed:'end'). ellipsis holds the cell to one line and keeps the full value as its title (it also switches the table to table-layout: fixed, without which no ellipsis truncates anything). sorter is antd's richer `sortable`: true | (a, b) => number | { compare, multiple }, where multiple is the MULTI-column sort priority (highest sorts first). sortOrder / defaultSortOrder / sortDirections control and shape the cycle per column, and showSorterTooltip explains the next step. filters + onFilter + filteredValue / defaultFilteredValue / filterMultiple add a real filter menu to the header (filterMultiple: false makes it single-choice); omit onFilter for a server filter and drive it from the table's onFilterChange.",
         "name": "columns",
         "required": true,
         "type": "ColumnDef<T>[]"
@@ -4386,6 +4386,7 @@
     "usage": [
       "DO use ListRow for a SHORT (≈2–8 item) list of entities inside a Card where each row is one line with an action — account sessions, API keys, linked identities, passkeys. Stack rows in a `<Card><CardContent flush>` so the rows draw their own quiet dividers edge-to-edge.",
       "DON'T reach for DataTable here — it carries sorting/selection/pagination chrome that a 3-item list doesn't need. DON'T nest a Card per row either (card-in-card). ListRow is the in-between surface.",
+      "DO host ListRow in a DataTable column when the list needs ROW SELECTION (a mail/notification inbox with bulk actions) — DataTable is the only primitive that selects rows. Mark that column `flush: true` so the cell drops its own padding and the ListRow owns the inset (gh#1016); without it the cell padding stacks on the row's (a 32px dead gap after the checkbox, taller rows) and the unread band stops at the checkbox cell. DON'T zero the cell with a className.",
       "DO write a list of LINKS as `<Flex as=\"ul\" marker=\"none\" direction=\"col\" gap=\"none\">` + `<ListRow as=\"li\" asChild><Link/></ListRow>` — one call gives the list item, the whole-row link and the divider. DON'T wrap the row in your own `<li>` or `role=\"listitem\"` element to get list semantics back: the divider rule reads `:not(:last-child)` among the rows themselves, so a wrapper per row makes each one an only child and EVERY divider disappears — silently, which is why `ui-audit` now flags it as `no-hand-rolled-list`.",
       "DON'T hand-roll `<div className=\"flex items-center justify-between border-b py-3\">` — that is exactly the repeated pattern ListRow replaces (border/radius/padding are tokenized via `--list-row-*`).",
       "DO put the row's action in `trailing` (a `ghost`/`outline` Button, a DropdownMenu trigger, a Switch, or a status Badge). DO pass `as=\"li\"` when the rows live inside a semantic list, and build that list as `<Flex as=\"ul\" marker=\"none\">` — `ui-audit` flags a raw `<ul>`/`role=\"list\"` as `no-hand-rolled-list`.",
@@ -5219,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"
       },
@@ -5255,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.",
@@ -5268,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",
@@ -5312,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."

package/agent/index.json

@@ -1,21 +1,21 @@
 {
   "counts": {
     "anti-ai-tells": 26,
-    "components": 175,
+    "components": 176,
     "patterns": 21,
     "rules": 50,
-    "tokens": 2074,
+    "tokens": 2075,
     "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"
     },
     {
       "file": "components/<Name>.json",
-      "note": "One file per component (1 KB–34 KB, median 6 KB), each carrying its importPath. This is the selective route: read the index, then fetch only what you need instead of the 1.2 MB blob.",
+      "note": "One file per component (1 KB–35 KB, median 6 KB), each carrying its importPath. This is the selective route: read the index, then fetch only what you need instead of the 1.2 MB blob.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/<Name>.json"
     },
     {
@@ -48,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.1.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v31.3.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": 1761,
       "foundation": 211,
       "semantic": 103
     },
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "31.1.0"
+  "version": "31.3.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.1.0.
+> A Japanese-enterprise React design system: 176 components, 2075 design tokens,
+> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 31.3.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@31.1.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@31.3.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/&lt;Name&gt;.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json): one file per component (1 KB–34 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-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), 103 `semantic` roles, 1761 `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.1.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v31.3.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

@@ -6983,6 +6983,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",

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-display/data-table.js

@@ -1296,7 +1296,8 @@ DataTable.Content = function DataTableContent() {
                                 ...fixedCellProps(col.key, fixedEdge(col)),
                                 ...columnHideBelowProps(col),
                                 style: columnCellStyle(col),
-                                className: cn(cellPadding, columnCellClass(col)),
+                                flush: col.flush,
+                                className: cn(!col.flush && cellPadding, columnCellClass(col)),
                                 children: rendered
                               },
                               col.key

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> & {

package/dist/components/feedback/alert.js

@@ -12,8 +12,11 @@ import {
 } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { humanError } from "../../lib/format.js";
+import { classifyQueryError } from "../../lib/query-error.js";
 import { Flex } from "../layout/flex.js";
 import { Button } from "../general/button.js";
+import { Text } from "../general/typography.js";
+import { useAuthExpiry } from "./auth-expiry.js";
 const AlertContext = React.createContext("default");
 const ASSERTIVE_TONES = /* @__PURE__ */ new Set(["destructive", "warning"]);
 const roleFor = (variant, tone) => {
@@ -121,24 +124,42 @@ function AlertQueryError({
   className
 }) {
   const { t } = useTranslation();
-  if (!category) {
+  const resolved = category ?? classifyQueryError(error).category;
+  const expiry = useAuthExpiry(resolved === "auth", error);
+  if (expiry?.status === "redirecting") {
+    return /* @__PURE__ */ jsx(
+      Text,
+      {
+        as: "p",
+        size: "sm",
+        tone: "muted",
+        role: "status",
+        "aria-live": "polite",
+        "data-slot": "alert-query-auth-pending",
+        className,
+        children: t("query.authExpiry.redirecting")
+      }
+    );
+  }
+  const authAction = expiry ? expiry.retry : onAuthAction;
+  if (!category && !expiry) {
     return /* @__PURE__ */ jsxs(Alert, { tone: "destructive", className, children: [
       /* @__PURE__ */ jsx(AlertTitle, { children: t("common.error") }),
       /* @__PURE__ */ jsx(AlertDescription, { children: humanError(error) }),
       onRetry && /* @__PURE__ */ jsx(RetryButton, { onRetry })
     ] });
   }
-  const tone = WARNING_CATEGORIES.has(category) ? "warning" : "destructive";
-  return /* @__PURE__ */ jsxs(Alert, { tone, className, children: [
-    /* @__PURE__ */ jsx(AlertTitle, { children: t(`query.error.title.${category}`) }),
-    /* @__PURE__ */ jsx(AlertDescription, { children: t(`query.error.description.${category}`) }),
-    category === "auth" && onAuthAction && /* @__PURE__ */ jsx(AlertActions, { children: /* @__PURE__ */ jsx(
+  const tone = resolved === "auth" ? "default" : WARNING_CATEGORIES.has(resolved) ? "warning" : "destructive";
+  return /* @__PURE__ */ jsxs(Alert, { tone, className, "data-query-category": resolved, children: [
+    /* @__PURE__ */ jsx(AlertTitle, { children: t(`query.error.title.${resolved}`) }),
+    /* @__PURE__ */ jsx(AlertDescription, { children: t(`query.error.description.${resolved}`) }),
+    resolved === "auth" && authAction && /* @__PURE__ */ jsx(AlertActions, { children: /* @__PURE__ */ jsx(
       Button,
       {
         variant: "outline",
         size: "sm",
         onClick: () => {
-          void onAuthAction();
+          void authAction();
         },
         children: /* @__PURE__ */ jsxs(Flex, { direction: "row", wrap: true, align: "center", gap: "xs", children: [
           /* @__PURE__ */ jsx(LogIn, { "aria-hidden": "true" }),
@@ -146,7 +167,7 @@ function AlertQueryError({
         ] })
       }
     ) }),
-    RETRYABLE_CATEGORIES.has(category) && onRetry && /* @__PURE__ */ jsx(RetryButton, { onRetry })
+    RETRYABLE_CATEGORIES.has(resolved) && onRetry && /* @__PURE__ */ jsx(RetryButton, { onRetry })
   ] });
 }
 const Alert = Object.assign(AlertBase, {

package/dist/components/feedback/auth-expiry.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+import type { AuthExpiryProviderProp } from "../../props/components/feedback.prop.js";
+export type { AuthExpiryProviderProp, AuthExpiryProviderProp as AuthExpiryProviderProps, } from "../../props/components/feedback.prop.js";
+/**
+ * `"redirecting"` — the handler has been invoked (or is about to be); render a neutral pending state.
+ * `"failed"` — the handler threw or rejected; fall back to the sign-in alert so the user is not left
+ * on an endless spinner.
+ */
+export type AuthExpiryStatus = "redirecting" | "failed";
+/**
+ * Central handling for an expired session (401 / invalid or expired token) — the SSO norm: the app
+ * sends the user back through the IdP, which returns immediately while the IdP session is alive, so
+ * no page-level error is ever painted.
+ *
+ * Every `DataState`, `InfiniteQueryState`, `AlertMutationFeedback` and `AlertQueryError` under this
+ * provider consults it. On an auth-class error it calls `onAuthExpired` **once** — any number of
+ * simultaneous 401s share one call — and renders a neutral pending state with a polite live region
+ * instead of an alert. The call is re-armed once every auth-errored view has gone (navigated away,
+ * or the queries recovered after a silent refresh), so a later expiry fires again.
+ */
+export declare function AuthExpiryProvider({ onAuthExpired, children }: AuthExpiryProviderProp): React.JSX.Element;
+/**
+ * Internal hook for the query surfaces. `active` = this view is currently showing an auth-class
+ * error. Returns `null` when there is no provider (the caller keeps its legacy alert), otherwise the
+ * status to render plus a `retry` for the fallback alert's sign-in button.
+ */
+export declare function useAuthExpiry(active: boolean, error: unknown): {
+    status: AuthExpiryStatus;
+    retry: () => void;
+} | null;