@godxjp/ui 31.31.8 → 32.0.1

package/dist/components/ui/toggle.d.ts

@@ -1,86 +0,0 @@
-import * as React from "react";
-import { type VariantProps } from "class-variance-authority";
-declare const toggleVariants: (props?: ({
-    variant?: "default" | "outline" | "soft" | null | undefined;
-    size?: "lg" | "md" | "sm" | "xs" | null | undefined;
-    shape?: "default" | "pill" | "sharp" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
-/**
- * Not exported on its own — it is folded into `ToggleProp` and `ToggleGroupItemProp` so there is
- * one public name per component.
- */
-type ToggleCountFields = {
-    /**
-     * Optional numeric count rendered as a borderless counter pill after the label — the SAME
-     * vocabulary `Button` already defines, so a counted segmented toggle and a counted filter tab
-     * read identically. Formatted with `Intl.NumberFormat` in the active locale (never `String(n)`,
-     * never a hand-rolled thousands separator).
-     */
-    count?: number;
-    /** Cap for `count` — beyond it the pill shows `{overflowCount}+` (e.g. `99+`). */
-    overflowCount?: number;
-    /** Render the pill when `count` is 0. Default `true`, matching Button. */
-    showZero?: boolean;
-    /**
-     * Localized description of what the count MEANS, folded into the accessible name so the control
-     * never announces as a bare number ("👍 3" → "thumbs up, 3 reactions"). Supply it whenever the
-     * visible label is an icon or an emoji; with a text label the label itself already carries the
-     * meaning.
-     */
-    countLabel?: string;
-};
-/**
- * The repo's two-state vocabulary, kept VERBATIM from the Radix era. React Aria spells the same
- * four things `isSelected` / `defaultSelected` / `onChange` / `isDisabled`; the translation lives
- * inside this file so no consumer ever has to learn RAC's names.
- */
-type TogglePressedFields = {
-    /** Controlled pressed state — RAC `isSelected`. */
-    pressed?: boolean;
-    /** Uncontrolled initial pressed state — RAC `defaultSelected`. */
-    defaultPressed?: boolean;
-    /** Fired with the NEW pressed state — RAC `onChange`. */
-    onPressedChange?: (pressed: boolean) => void;
-};
-/**
- * Counter pill shared by `Toggle`, `ToggleGroupItem` and `Tabs` items. ACCESSIBLE NAME.
- *
- * `slot` names the hooks the pill emits (`data-slot="<slot>-count"` / `.ui-<slot>-count`) so a
- * third component can reuse the whole construction — the Intl formatting, the `overflowCount`
- * cap, and above all the `aria-hidden` + `sr-only` split that keeps «未対応12» out of the
- * accessible name (gh#734) — without a second counting API growing beside this one (gh#762).
- * It defaults to `toggle`, so every existing call emits the identical markup it always has.
- */
-declare function useCounterPill({ count, overflowCount, showZero, countLabel, ariaLabel, slot, }: ToggleCountFields & {
-    ariaLabel?: string;
-    slot?: string;
-}): {
-    pill: null;
-    resolvedAriaLabel: string | undefined;
-} | {
-    pill: React.JSX.Element;
-    resolvedAriaLabel: string | undefined;
-};
-/**
- * RAC's `filterDOMProps` forwards only `id`, `data-*`, the four labelling `aria-*` and the global
- * mouse/pointer events; `title`, `tabIndex` and the rarer DOM props are dropped silently, and
- * Radix forwarded ALL of them. `render` is RAC's own escape hatch: the raw props go on first, RAC's
- * merged ones second so its `type`/`disabled`/`aria-pressed`/handlers always win.
- *
- * Two exceptions, both of which Radix owned: `tabIndex` stays the caller's, and so does `id` —
- * inside a ToggleButtonGroup RAC spends `id` as the selection KEY and blanks the DOM attribute,
- * which would otherwise silently drop the id off every grouped item.
- */
-declare function restoreDomProps<P extends {
-    id?: string;
-    tabIndex?: number;
-}>(raw: P, domProps: React.JSX.IntrinsicElements["button"]): React.JSX.Element;
-export type ToggleProp = React.ComponentPropsWithoutRef<"button"> & TogglePressedFields & VariantProps<typeof toggleVariants> & ToggleCountFields;
-export type ToggleProps = ToggleProp;
-export declare const Toggle: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & TogglePressedFields & VariantProps<(props?: ({
-    variant?: "default" | "outline" | "soft" | null | undefined;
-    size?: "lg" | "md" | "sm" | "xs" | null | undefined;
-    shape?: "default" | "pill" | "sharp" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string> & ToggleCountFields & React.RefAttributes<HTMLButtonElement>>;
-export { toggleVariants, useCounterPill, restoreDomProps };
-export type { ToggleCountFields, TogglePressedFields };

package/dist/components/ui/toggle.js

@@ -1,156 +0,0 @@
-"use client";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import * as React from "react";
-import { ToggleButton } from "react-aria-components";
-import { cva } from "class-variance-authority";
-import { cn } from "../../lib/utils.js";
-import { useTranslation } from "../../i18n/use-translation.js";
-import { numberFormat } from "../../lib/intl-cache.js";
-const toggleVariants = cva("ui-toggle", {
-  variants: {
-    variant: {
-      default: "ui-toggle-default",
-      outline: "ui-toggle-outline",
-      // The REST FILL (gh#734). `default` is a 1px TRANSPARENT border and `outline` a hairline on
-      // `--background`, so neither draws a chip that reads as filled before it is pressed — which
-      // is why a consumer building a tag-filter panel reported its tags "look transparent" and
-      // fell back to `Button variant="secondary" shape="pill" aria-pressed`, a control that paints
-      // no pressed state at all. `soft` is antd `Tag`'s resting surface, on the SAME
-      // `hsl(var(--secondary))` fill `Badge variant="secondary"` and `Button variant="secondary"`
-      // already paint, so a chip, a badge and a button on one row are one family.
-      soft: "ui-toggle-soft"
-    },
-    size: {
-      // The fourth step of the shared control ladder (gh#716): 24px, `--control-height-xs`, the
-      // same tier `Button size="xs"` reads — so a 24px-dense row can carry a segmented control
-      // instead of someone hand-rolling one out of Buttons.
-      xs: "ui-toggle-xs",
-      sm: "ui-toggle-sm",
-      md: "ui-toggle-default-size",
-      lg: "ui-toggle-lg"
-    },
-    // Corner shape at parity with `Button` and `Badge` — the same three values mapped to the same
-    // two radius tokens, so `shape="pill"` means one thing across the library. `default` is empty
-    // on purpose: it leaves `.ui-toggle`'s own `--radius-md` in place instead of restating it,
-    // exactly as `badgeVariants` does.
-    shape: {
-      default: "",
-      pill: "rounded-[var(--radius-pill)]",
-      sharp: "rounded-[var(--radius-sharp)]"
-    }
-  },
-  defaultVariants: {
-    variant: "default",
-    size: "md",
-    shape: "default"
-  }
-});
-function useCounterPill({
-  count,
-  overflowCount = 99,
-  showZero = true,
-  countLabel,
-  ariaLabel,
-  slot = "toggle"
-}) {
-  const { locale } = useTranslation();
-  const visible = count != null && (count !== 0 || showZero);
-  const formatted = React.useMemo(() => {
-    if (count == null) return "";
-    const format = numberFormat(locale);
-    return count > overflowCount ? `${format.format(overflowCount)}+` : format.format(count);
-  }, [count, locale, overflowCount]);
-  if (!visible) {
-    return { pill: null, resolvedAriaLabel: ariaLabel };
-  }
-  const spoken = countLabel ? `${formatted} ${countLabel}` : formatted;
-  return {
-    pill: /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("span", { "data-slot": `${slot}-count`, className: `ui-${slot}-count`, "aria-hidden": "true", children: formatted }),
-      /* @__PURE__ */ jsx("span", { className: "sr-only", children: `, ${spoken}` })
-    ] }),
-    resolvedAriaLabel: ariaLabel == null ? ariaLabel : `${ariaLabel}, ${spoken}`
-  };
-}
-function usePressedState({ pressed, defaultPressed, onPressedChange }) {
-  const [uncontrolled, setUncontrolled] = React.useState(defaultPressed ?? false);
-  const isPressed = pressed ?? uncontrolled;
-  return {
-    isPressed,
-    onSelectionChange: (next) => {
-      if (pressed == null) {
-        setUncontrolled(next);
-      }
-      onPressedChange?.(next);
-    }
-  };
-}
-function restoreDomProps(raw, domProps) {
-  return /* @__PURE__ */ jsx(
-    "button",
-    {
-      ...raw,
-      ...domProps,
-      id: raw.id ?? domProps.id,
-      tabIndex: raw.tabIndex ?? domProps.tabIndex
-    }
-  );
-}
-const Toggle = React.forwardRef(
-  ({
-    className,
-    variant,
-    size,
-    shape,
-    count,
-    overflowCount,
-    showZero,
-    countLabel,
-    children,
-    "aria-label": ariaLabel,
-    pressed,
-    defaultPressed,
-    onPressedChange,
-    disabled,
-    ...props
-  }, ref) => {
-    const { pill, resolvedAriaLabel } = useCounterPill({
-      count,
-      overflowCount,
-      showZero,
-      countLabel,
-      ariaLabel
-    });
-    const { isPressed, onSelectionChange } = usePressedState({
-      pressed,
-      defaultPressed,
-      onPressedChange
-    });
-    return /* @__PURE__ */ jsxs(
-      ToggleButton,
-      {
-        ref,
-        "data-slot": "toggle",
-        "data-state": isPressed ? "on" : "off",
-        "aria-label": resolvedAriaLabel,
-        className: cn(toggleVariants({ variant, size, shape }), className),
-        ...props,
-        isSelected: isPressed,
-        onChange: onSelectionChange,
-        isDisabled: disabled,
-        render: (domProps) => restoreDomProps(props, domProps),
-        children: [
-          children,
-          pill
-        ]
-      }
-    );
-  }
-);
-Toggle.displayName = "Toggle";
-export {
-  Toggle,
-  restoreDomProps,
-  toggleVariants,
-  useCounterPill
-};

package/docs/CANONICAL-CONTRACTS.md

@@ -1,206 +0,0 @@
-# Canonical contracts — the answer to "does @godxjp/ui have an X?"
-
-A consumer design spec names a component (`PageHeader`, `Banner`, `SocialLinks`, `OrganizationChoiceList`, `ServiceRolePanel`, `BranchScopePicker`, `PermissionMatrix`, `FilterBar`).
-
----
-
-## 1. `PageHeader` — **`PageContainer`'s embedded header IS the DXS PageHeader** (gh#255)
-
-```ts
-import { PageContainer, type PageContainerProps } from "@godxjp/ui/layout";
-```
-
-There is **no standalone `PageHeader` export**. The canonical page title band — breadcrumbs · `<h1>` · subtitle · status/meta (`status`) · actions (`extra`) — lives on **one renderer**: `PageContainer`'s embedded header, with `headerLayout` (`stack` | `responsive-inline`), `breadcrumbLabel` (the landmark-unique override), `measure` and `headerLoading` (skeleton title band + `aria-busy`, keeping the `<h1>` in the document with an sr-only name so the heading outline never disappears mid-load).
-
-**Why one renderer rather than a lifted export.** The band's geometry is token-owned (`.ui-page-header`, `--page-header-status-gap`, the placeholder measures) and every page mounts it through `PageContainer`, so a second mount point would be a second `<h1>` waiting to happen. A title band outside a full page shell (a Sheet detail, a `MasterDetail` pane, a tab body) is a COMPOSITION of `Breadcrumb` + heading text + `Flex` at section level — it should NOT be an `<h1>`.
-
-| Situation                                    | Use                                                                       |
-| -------------------------------------------- | ------------------------------------------------------------------------- |
-| The surface **is a page**                    | `PageContainer` (`title`/`subtitle`/`status`/`extra`/`breadcrumb`)        |
-| A title band **inside** a pane/sheet/tab     | Compose at section level — never a second `<h1>` / `PageContainer` header |
-| The user **may not see the resource at all** | `ErrorSurface` — never a header that leaks the resource's name            |
-
-`denied` / `error` are deliberately **not** states of the band — see the table above.
-
----
-
-## 2. `Banner` — **EXPORTED** as the page-level `Alert` (gh#255)
-
-```ts
-import { Banner, type BannerProps } from "@godxjp/ui/feedback";
-```
-
-Same tones, same icon defaults, same assertive/polite role split, same actions grid, same dismiss control. `Banner.Title` **is** `AlertTitle` — the same element, not a parallel family.
-
-It is an alias, not a second implementation, for the same reason `FilterBar` is an alias of `Toolbar`: a banner and an inline alert are one object at two measures, and duplicating the tone mapping and dismiss behaviour is exactly what the no-duplication rule forbids.
-
-| Scope of the message                                                  | Use                                         |
-| --------------------------------------------------------------------- | ------------------------------------------- |
-| The page or the whole app (maintenance, trial expiry, read-only mode) | `Banner` above the header, or in `AppShell` |
-| One section / card / form                                             | `Alert` inside that section                 |
-| One field                                                             | `FormField` `error`                         |
-| Transient ("saved")                                                   | `toast()`                                   |
-| The user may not see the page at all                                  | `ErrorSurface`                              |
-
-Retheme through tokens, never a wrapper class: `--banner-radius`, `--banner-border-width`, `--banner-border-block-end-width`, `--banner-space-block`, `--banner-space-inline`, `--banner-dismiss-space-offset`. Never stack two banners.
-
----
-
-## 3. `AuthShell preset="registration"` — **EXPORTED** (gh#256)
-
-```tsx
-<AuthShell variant="canonical" preset="registration" brand={…} footer={…}>
-```
-
-The 360px sign-up measure with a 15px inline gutter at 390px — the same page rhythm as `preset="login"`, so sign-in → sign-up never jumps on a phone. It carries the full password form **and** the pending-email confirmation state with no consumer geometry CSS.
-
-Two things make it structurally distinct from every other preset, and both are load-bearing:
-
-1. **It is the only START-aligned preset.** A sign-up card is the tallest surface in the hosted-identity set (name · email · password · confirm · strength · consent · submit · providers). A vertically _centred_ tall card overflows **above the scroll origin** on a short viewport, putting its first field permanently out of reach. 2. **It is the only preset with its own footer-clearance knob**, so the legal/consent footer never sits flush against the submit button at the end of a long scroll.
-
-Geometry knobs: `--auth-shell-registration-{card-max-width, main-padding-block-start, main-padding-block-start-mobile, main-padding-inline, main-padding-inline-mobile, main-padding-block-end, main-padding-block-end-mobile, card-stack-gap}`.
-
-Worked screen: `docs/layout/auth-shell-registration.tsx`.
-
----
-
-## 4. `SocialLinks` — **COMPOSE** (gh#256)
-
-There is no `SocialLinks` component, and none is planned.
-
-```tsx
-<AuthDivider label="または" />
-<Flex direction="col" gap="sm">
-  {providers.map((p) => (
-    <Button key={p.id} variant="outline" disabled={submitting} onClick={p.start}>
-      <p.Icon aria-hidden="true" />
-      {p.label}
-    </Button>
-  ))}
-</Flex>
-```
-
-**Why.** It owns no behaviour: each provider is a plain action the app points at its own OAuth start URL. A framework component would have to invent _which_ providers a product offers, in what order, and what consent they imply — product decisions the package must not make. `disabled` and `loading` are the `Button`'s own props; there is no provider-specific API to learn.
-
----
-
-## 5. `OrganizationChoiceList` — **COMPOSE** (gh#256)
-
-```tsx
-<Card>
-  <CardHeader>…</CardHeader>
-  <CardContent flush>
-    <ul>
-      {orgs.map((org) => (
-        <ListRow
-          as="li"
-          key={org.id}
-          leading={<Avatar>…</Avatar>}
-          title={org.name}
-          description={org.role}
-          trailing={
-            <Button variant="ghost" size="sm">
-              選択
-            </Button>
-          }
-        />
-      ))}
-    </ul>
-  </CardContent>
-</Card>
-```
-
-`CardContent flush` is what produces shared row dividers instead of a card outline per row.
-
-States — all existing exports, no bespoke markup:
-
-| State             | Use                                                      |
-| ----------------- | -------------------------------------------------------- |
-| loading           | `Skeleton` rows at the settled row height                |
-| empty             | `EmptyState`                                             |
-| error             | `Alert tone="destructive"` + a retry action              |
-| permission-denied | `Alert tone="warning"` (section) / `ErrorSurface` (page) |
-| disabled row      | the row's own `Button disabled`                          |
-
-Worked screens: `docs/layout/auth-shell-context.tsx`, `docs/layout/auth-shell-registration.tsx`.
-
----
-
-## 6. `ServiceRolePanel` · `BranchScopePicker` · `PermissionMatrix` — **EXPORTED** (gh#257)
-
-All three compositions were promoted to public exports — the composition-first Gate 0 verdict was revisited when consumers kept re-authoring the same states and geometry:
-
-```ts
-import { ServiceRolePanel } from "@godxjp/ui/layout";
-import { BranchScopePicker } from "@godxjp/ui/data-entry";
-import { PermissionMatrix } from "@godxjp/ui/data-display";
-```
-
-```ts
-import {
-  grantKey,
-  hasGrant,
-  rolesDifferOnPermission,
-  visibleRows,
-  countGrants,
-  countDifferences,
-} from "@godxjp/ui/lib/permission-grid";
-```
-
-Layout the role list beside the editor with `MasterDetail` — it owns the tracks, the gap and the stacking threshold as tokens, so the page carries no `grid-template-columns` and no media query at 1440 / 1024 / 390. Destructive changes go through `AlertDialog variant="destructive"` (add `challenge` for type-to-confirm).
-
-Worked screens: `docs/layout/service-role-panel.tsx`, `docs/data-entry/branch-scope-picker.tsx`, `docs/data-display/permission-matrix.tsx`, `docs/showcase/permission-matrix.tsx`.
-
----
-
-## 7. `FilterBar` — **EXPORTED, and now typed** (gh#258)
-
-`FilterBar` / `FilterBarGroup` remain the public domain-neutral names for the `Toolbar` primitives.
-
-```tsx
-<FilterBar
-  search={{ value: q, onValueChange: setQ, placeholder: "Search records" }}
-  filters={[
-    {
-      value: "status",
-      label: "状態",
-      options: STATUS_OPTIONS,
-      selected: status,
-      onSelectedChange: setStatus,
-    },
-  ]}
-  chips={applied.map((f) => ({ value: f.value, label: f.label }))}
-  onChipRemove={lift}
-  resultCount={rows.length}
-  onClear={clearAll}
-  hasActiveFilters={applied.length > 0}
-  actions={
-    <Button variant="outline" size="sm">
-      エクスポート
-    </Button>
-  }
-/>
-```
-
-**Order is the contract.** DOM order is tab order, and the **bar** decides it, not each page:
-
-```
-search → typed filters → children (custom composition filters) → reset → actions
-  → applied-chips row → result-count / error line
-```
-
-Reset sits before `actions` deliberately, so "clear filters" never lands at the end of the row beside an unrelated primary action.
-
-What each prop buys that a plain child did not:
-
-- **`search`** — the canonical `SearchInput` at one token-owned measure (`--filter-bar-search-width`) across every list page, full-width below the 640px step. Controlled through the `value`/`defaultValue`/`onValueChange` triad; `onSearch` mirrors the debounced-term callback. - **`filters`** — labelled, domain-neutral `Select` filters whose visible `label` is the control's real `<label htmlFor>` (WCAG 2.5.3 / 1.3.1), at the `--filter-bar-filter-width` measure. - **`chips`** — the chip lifecycle: a labelled row, a remove control named after _that specific_ filter (a row of buttons all called "Remove" is unusable from a screen-reader's control list), and no row at all when nothing is applied. Remove = `onChipRemove(value)`; clear-all = `onClear`. - **`resultCount`** — a polite live region formatted with `Intl.NumberFormat` + CLDR plurals.
-
-The bar still owns **no filter state**. `search`/`filters`/`chips` are rendered consumer data, `resultCount` is a number you computed. It owns placement, measure, ordering, keyboard order and announcement — nothing else.
-
-Worked screen: `docs/navigation/filter-bar.tsx`.
-
----
-
-## Adding to this document
-
-Any future "does the package have an X?" answer belongs here, with: the Gate 0 verdict, the public-route question, and — for a composition — the exact primitives, the token knobs, and the state table. If the honest answer is "the consumer cannot reach it publicly", that is a package gap: fix the library, never patch the consumer app.

package/docs/COMPONENTS.md

@@ -1,163 +0,0 @@
-# Component Catalog
-
-All components consume prop types from `src/props/components/`. Preview: `pnpm preview`.
-
----
-
-## Layout
-
-### AppShell / Sidebar / Topbar
-
-**Prop types:** `AppShellProp`, `SidebarProp`, `TopbarProp` **Import:** `@godxjp/ui/layout`
-
-Slot-based app chrome for admin products:
-
-```tsx
-<AppShell
-  sidebar={<Sidebar sections={sections} activeId="dashboard" />}
-  topbar={<Topbar start={<Logo mark="godx" label={product.name} />} />}
->
-  <PageContainer title="Dashboard">...</PageContainer>
-</AppShell>
-```
-
-Do not rebuild sidebar or topbar chrome inside product previews or apps. Compose the shell slots, then put product content in the `children` slot.
-
-### PageContainer
-
-**Prop type:** `PageContainerProp` **Import:** `@godxjp/ui/layout`
-
-| Prop            | Vocabulary        | Required          |
-| --------------- | ----------------- | ----------------- |
-| `title`         | `TitleProp`       | ✅                |
-| `subtitle`      | `SubtitleProp`    |                   |
-| `extra`         | `ExtraProp`       |                   |
-| `footer`        | `FooterProp`      |                   |
-| `breadcrumb`    | `BreadcrumbProp`  |                   |
-| `headerLoading` | local (`boolean`) | default `false`   |
-| `density`       | `PageDensityProp` | default `default` |
-| `children`      | `ChildrenProp`    |                   |
-
-Every admin page **must** use PageContainer.
-
-## Mobile-first
-
-All UI is **mobile-first**: base layout targets ~320–428px viewport; `sm` (640px+) adds horizontal layouts. See `packages/ui/src/tokens/base.css` and `.ui-page-*` in `src/styles/index.css`. Preview defaults to mobile viewport.
-
-### Flex
-
-Default `direction="row"`; use `direction="col"` for vertical rhythm.
-
-| Component | Prop       | Key props                                                                                                           |
-| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
-| `Flex`    | `FlexProp` | `direction: "row" \| "col"`, `gap: GapProp`, `gapRaw`, `pad`, `padRaw`, `fill`, `width`, `align`, `justify`, `wrap` |
-
-`fill` / `width` are the `fixed | elastic | fixed` row: `width` pins a column (number = px, and
-leaves `data-width-raw` on the DOM so the measurement stays countable), `fill` takes what is left
-and sets `min-inline-size: 0` so a truncating child ellipses instead of widening the row.
-
----
-
-## Foundation
-
-### Button
-
-**Prop type:** `ButtonProp` **Import:** `@godxjp/ui/general`
-
-| Prop       | Vocabulary          |
-| ---------- | ------------------- |
-| `variant`  | `ButtonVariantProp` |
-| `size`     | `ButtonSizeProp`    |
-| `asChild`  | `AsChildProp`       |
-| `disabled` | `DisabledProp`      |
-| `onClick`  | `OnClickProp`       |
-
----
-
-## Data Entry
-
-| Component     | Prop type         | Key props                                          |
-| ------------- | ----------------- | -------------------------------------------------- |
-| `Input`       | `InputProp`       | extends native input                               |
-| `Textarea`    | `TextareaProp`    | extends native textarea                            |
-| `FormField`   | `FormFieldProp`   | `id`, `label`, `required`, `helper`, `error`       |
-| `SearchInput` | `SearchInputProp` | `onSearchChange: OnSearchChangeProp`               |
-| `Checkbox`    | `CheckboxProp`    | Checkbox (RAC); `Checkbox.Group` với `options`     |
-| `Radio`       | `RadioGroupProp`  | `Radio.Group` single-select; `Radio.Root` compound |
-
----
-
-## Data Display
-
-| Component      | Prop type          | Key props                                 |
-| -------------- | ------------------ | ----------------------------------------- |
-| `EmptyState`   | `EmptyStateProp`   | `icon`, `title`, `description`, `action`  |
-| `DataTable`    | `DataTableProp<T>` | `columns`, `density: TableDensityProp`    |
-| `Descriptions` | `DescriptionsProp` | `items[]`                                 |
-| `Badge`        | `BadgeProp`        | `status`, `tone: ToneProp`                |
-| `Badge`        | `BadgeProp`        | shadcn badge variants                     |
-| `Progress`     | `ProgressProp`     | `value` (meter) \| `segments` (breakdown) |
-| `Legend`       | `LegendProp`       | `items[]` — the key for a tone            |
-| `Popover`      | Radix primitives   | floating content panel                    |
-| `ScrollArea`   | Radix primitives   | scrollable regions                        |
-| `Collapsible`  | Radix primitives   | expand/collapse sections                  |
-
----
-
-## Feedback
-
-| Component   | Prop type           | Key props                                                                    |
-| ----------- | ------------------- | ---------------------------------------------------------------------------- |
-| `Alert`     | `AlertProp`         | `tone` (colour), `variant` (measure), slots, `onDismiss`, `Alert.QueryError` |
-| `Banner`    | `BannerProp`        | page-level `Alert` (`variant="banner"`); same tones/slots/dismiss            |
-| `Dialog`    | `DialogConfirmProp` | `mode: form \| confirm`, `Dialog.Confirm` preset                             |
-| `Sheet`     | Radix primitives    | slide-in panel (mobile filters, detail flyouts)                              |
-| `Skeleton*` | `SkeletonRowsProp`  | loading placeholders                                                         |
-
----
-
-## Query
-
-Async data lifecycle helpers (TanStack Query). **Not visual components.**
-
-| Component               | Prop type                   | Key props                                                                               |
-| ----------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
-| `DataState`             | `DataStateProp<T>`          | `query`, `skeleton`, `empty`, `isEmpty`, `showRetry`, `onRetry`, render-prop `children` |
-| `AlertMutationFeedback` | `AlertMutationFeedbackProp` | `mutation`, `onRetry`, `pending` — inline `useMutation` error                           |
-| `InfiniteQueryState`    | `InfiniteQueryStateProp`    | `flatten`, `loadMore`, `showLoadMore` — infinite scroll / timeline                      |
-| `PrefetchLink`          | `PrefetchLinkProp`          | `queryKey`, `queryFn`, `prefetchOn`, `staleTime`                                        |
-
-Import: `@godxjp/ui/query` (re-exported from `@godxjp/ui/admin`).
-
-**`DataState`** — one `useQuery` = one content block (list, detail). Not whole page when filters stay visible.
-
-**`InfiniteQueryState`** — `useInfiniteQuery` + Load more. CRM timeline, activity feeds. Offset pagination lists → `DataState` + `DataTable.Pagination`.
-
-**`PrefetchLink`** — hover/focus prefetch before navigate to detail.
-
-**`AlertMutationFeedback`** — blocking mutation errors (simulator). Small saves → toast.
-
-**`ButtonRefetch`** — `PageContainer extra` refresh pattern (MediaListPage).
-
-**`Alert.QueryError`** — manual error when not using DataState (audit results region).
-
-Auto retry: `useQuery({ retry, retryDelay })`. Manual retry: default `refetch()`.
-
----
-
-## Navigation
-
-| Component        | Prop type          | Key props                                                                                                                      |
-| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| `FilterBar`      | `ToolbarProp`      | typed model: `search`, `filters`, `chips`, `onChipRemove`, `resultCount`, `actions`, `loading`, `disabled`, `error`, `onClear` |
-| `FilterBarGroup` | `ToolbarGroupProp` | `label: LabelProp`, `controlId: IdProp`                                                                                        |
-| `Toolbar`        | `ToolbarProp`      | back-compat alias of `FilterBar`                                                                                               |
-| `ToolbarGroup`   | `ToolbarGroupProp` | back-compat alias of `FilterBarGroup`                                                                                          |
-| `Tabs`           | Radix primitives   | —                                                                                                                              |
-| `DropdownMenu`   | Radix primitives   | —                                                                                                                              |
-
----
-
-## Adding a new component
-
-1. Check `PROPS-REGISTRY.md` — concept may already exist 2. Add vocabulary types if needed → `src/props/vocabulary/` 3.