@godxjp/ui 31.31.8 → 32.0.0

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.

package/docs/DATETIME.md

@@ -1,78 +0,0 @@
-# formatDate — mandatory datetime display
-
-Package: `@godxjp/ui/datetime`
-
-## Import
-
-```tsx
-import { formatDate } from "@godxjp/ui/datetime";
-import { useDateTime } from "@godxjp/ui/app";
-```
-
-## Rules
-
-1. **Never** use `date-fns/format`, `toLocaleString`, or raw ISO slices for UI.
-2. **Always** wrap apps in `<AppProvider>` so defaults apply.
-3. **Optional** per-call `timezone` override — global prefs unchanged.
-
-## Defaults
-
-Omit `locale`, `timezone`, `timeFormat`, `dateFormat` → synced from AppProvider.
-
-## dateFormat presets
-
-| value | Pattern      | Default locale |
-| ----- | ------------ | -------------- |
-| `iso` | `yyyy-MM-dd` | —              |
-| `ymd` | `yyyy/MM/dd` | ja             |
-| `dmy` | `dd/MM/yyyy` | vi             |
-| `mdy` | `MM/dd/yyyy` | en             |
-
-`ymd` and `iso` are both year-first and are NOT interchangeable: a Japanese business document
-(請求書, 申請書) is written `2026/05/01`, never `2026-05-01`. `ja` defaulted to `iso` until a
-Japanese-first consumer shipped its own date formatter as an explicit stopgap purely to get the
-slashes — rule 1 above broken by this package's own default. Only the DEFAULT moved: a stored
-preference still wins, `defaultDateFormat` still pins any value, and `iso` is one option away in
-`<DateFormatPicker />`.
-
-Sent to backend as `x-date-format`. Pick with `<DateFormatPicker />`.
-
-## kind presets
-
-| kind       | Use                                      |
-| ---------- | ---------------------------------------- |
-| `auto`     | Default — detects date / time / datetime |
-| `datetime` | Audit logs, `created_at`                 |
-| `date`     | `"2026-05-01"` fields                    |
-| `calendar` | `Date` from DatePicker                   |
-| `time`     | `"14:30"` HH:mm                          |
-| `long`     | Detail headings (PPP)                    |
-| `relative` | Activity feeds                           |
-
-## ISO 8601 patterns
-
-Date order follows `dateFormat` from AppProvider (`iso` | `ymd` | `dmy` | `mdy`):
-
-- `iso`: `yyyy-MM-dd` + `yyyy-MM-dd HH:mm`
-- `ymd`: `yyyy/MM/dd` + `yyyy/MM/dd HH:mm`
-- `dmy`: `dd/MM/yyyy` + `dd/MM/yyyy HH:mm`
-- `mdy`: `MM/dd/yyyy` + `MM/dd/yyyy HH:mm`
-
-Time portion still follows `timeFormat` (24h vs 12h).
-
-## Examples
-
-```tsx
-formatDate("2026-05-01T14:30:00Z");
-formatDate("2026-05-01");
-formatDate("17:30", { kind: "time" });
-formatDate(pickedDate, { kind: "calendar" });
-formatDate(iso, { timezone: "Asia/Tokyo" });
-```
-
-## React
-
-```tsx
-const { format } = useDateTime();
-return <td>{format(row.createdAt)}</td>;
-```