@godxjp/ui 18.9.0 → 18.11.0

package/dist/props/components/layout.prop.d.ts

@@ -1,7 +1,7 @@
 /** Layout component prop types — @see docs/COMPONENTS.md#layout */
 import type * as React from "react";
 import type { ComponentType, ReactNode, SVGProps } from "react";
-import type { BreadcrumbProp, TitleProp, SubtitleProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, BreakpointProp, GapProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp } from "../vocabulary/index.js";
+import type { BreadcrumbProp, TitleProp, SubtitleProp, StatusProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, BreakpointProp, GapProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp } from "../vocabulary/index.js";
 import type { EmptyStateToneProp } from "./data-display.prop.js";
 /**
  * Arrangement of the page header's title band and its `extra` slot below the 640px step.
@@ -24,54 +24,27 @@ export type PageContainerPresetProp = "default" | "admin-collection";
  * fluid at the compact gutter.
  */
 export type PageContainerMeasureProp = "default" | "narrow" | "medium";
-/**
- * @see PageHeader — the canonical page title band, extracted from PageContainer so a consumer can
- * mount the SAME token-owned geometry outside a full page shell (a Sheet detail, a MasterDetail
- * pane, a tab body) instead of re-authoring `.ui-page-header` CSS locally (gh#255).
- */
-export type PageHeaderProp = {
+/** @see PageContainer */
+export type PageContainerProp = {
     title: TitleProp;
     subtitle?: SubtitleProp;
     /**
-     * Status / meta band rendered INLINE with the title (a `Badge` tone, an ID, a timestamp).
-     * Omitted → the title band emits its historical single-`<h1>` DOM, so no existing page moves.
-     */
-    meta?: ReactNode;
-    /** Trailing action region — buttons, a search field, an overflow menu. */
-    extra?: ExtraProp;
-    breadcrumb?: BreadcrumbProp;
-    /**
-     * Override the breadcrumb `<nav>` landmark's accessible name. Defaults to a localized
-     * "Breadcrumb". Needed when more than one header (each with its own `breadcrumb`) renders on the
-     * same page/view — two `<nav>` landmarks sharing one name/role fail axe's `landmark-unique`
-     * (WCAG 2.4.1 / 1.3.1).
-     */
-    breadcrumbLabel?: string;
-    /** Kebab/DOM-style alias of `breadcrumbLabel` (same landmark-unique override). */
-    breadcrumbAriaLabel?: string;
-    linkComponent?: React.ElementType;
-    /**
-     * How the title band and `extra` share the header row below the 640px step. Defaults to
-     * `stack`. @see PageContainerHeaderLayoutProp
+     * Status/meta band rendered beside the title inside the heading — StatusBadge, environment
+     * tag, "updated …" meta text. Geometry is token-owned (`--page-header-status-gap`): the band
+     * sits on the title line and WRAPS under it on compact viewports, so a consumer never
+     * hand-lays a badge next to an `<h1>`. Part of the canonical page-header contract
+     * (godxjp-ui#255): PageContainer's embedded header IS the DXS `PageHeader` — breadcrumbs
+     * (`breadcrumb`), title, subtitle, status/meta (this), actions (`extra`) and responsive
+     * overflow (`headerLayout` / `measure`) all live on this one renderer.
      */
-    layout?: PageContainerHeaderLayoutProp;
+    status?: StatusProp;
     /**
-     * Pending state for the title band while the page's own data resolves. Renders the title/subtitle
-     * /meta as `Skeleton` placeholders and marks the header `aria-busy`, keeping the `<h1>` in the
-     * document with an accessible name (an empty heading is an axe violation) so the page's heading
-     * outline never disappears mid-load. Breadcrumbs and `extra` are NOT skeletonised — they come
-     * from the route, not the record.
+     * Pending state for the title band while the page's own record resolves. Renders the
+     * title/subtitle as `ui-skeleton-block` placeholders and marks the header `aria-busy`, keeping
+     * the `<h1>` in the document with an sr-only accessible name (an empty heading is an axe
+     * violation) so the page's heading outline never disappears mid-load. Breadcrumbs and `extra`
+     * are NOT skeletonised — they come from the route, not the record.
      */
-    loading?: boolean;
-    className?: ClassNameProp;
-};
-/** @see PageContainer */
-export type PageContainerProp = {
-    title: TitleProp;
-    subtitle?: SubtitleProp;
-    /** Status / meta band rendered inline with the title. @see PageHeaderProp.meta */
-    meta?: ReactNode;
-    /** Skeletonise the title band while the page record loads. @see PageHeaderProp.loading */
     headerLoading?: boolean;
     extra?: ExtraProp;
     footer?: FooterProp;
@@ -276,8 +249,8 @@ export type AuthShellProp = {
     /**
      * Named flow MEASURE — the page geometry contract for one canonical hosted-identity flow: the
      * auth card's max-width plus the desktop and mobile page gutters, all owned by component tokens
-     * (`--auth-shell-{login,device,context,recovery}-*`). Selecting a preset replaces every
-     * consumer-side geometry override.
+     * (`--auth-shell-{login,registration,device,context,recovery}-*`). Selecting a preset replaces
+     * every consumer-side geometry override.
      *
      * - `"default"` (default) — the shell's own measure; nothing changes.
      * - `"login"` — SCR-001's 360px card at x=540/332/15 and y=363/363/353 for the canonical
@@ -286,13 +259,14 @@ export type AuthShellProp = {
      *   position without truncating or inventing requester data. Pass AuthIdentity, Card and
      *   AuthFooter as direct children (an anchor may wrap AuthIdentity).
      * - `"registration"` — the 360px sign-up measure with a 15px inline gutter at 390px (the same
-     *   page rhythm as `"login"`, so sign-in → sign-up never jumps on a phone). The ONLY preset whose
-     *   column is START-aligned: a registration card is the tallest surface in the hosted-identity
-     *   set (name · email · password · confirm · strength · consent · submit · providers), and a
+     *   page rhythm as `"login"`, so sign-in → sign-up never jumps on a phone). START-aligned like
+     *   login, because a registration card is the tallest surface in the hosted-identity set
+     *   (name · email · password · confirm · strength · consent · submit · providers) and a
      *   vertically centred tall card overflows ABOVE the scroll origin on a short viewport, putting
-     *   its first field out of reach. It is also the only preset with a footer-clearance knob of its
-     *   own, so the legal/consent footer never sits flush against the submit button. Carries the full
-     *   password form and the pending-email confirmation state with no consumer geometry CSS.
+     *   its first field out of reach — start-aligned, a long form simply scrolls. It is also the
+     *   only preset with a footer-clearance knob of its own, so the legal/consent footer never sits
+     *   flush against the submit button. Carries the full password form and the pending-email
+     *   confirmation state with no consumer geometry CSS.
      * - `"device-authorization"` — 380px card measure with a 5px inline page gutter at a 390px
      *   viewport (canonical device-grant artboard).
      * - `"context-selection"` — 25rem card measure on desktop/tablet, edge-to-edge on mobile, and a
@@ -814,3 +788,58 @@ export type LegalDocumentShellProp = {
     id?: IdProp;
     className?: ClassNameProp;
 };
+/** @see ServiceRolePanel — one role in the master rail. Domain data is consumer-supplied. */
+export type ServiceRoleItemProp = {
+    /** Stable role id (the selection value). */
+    id: string;
+    /** Human role name (also used in accessible labels, so a plain string). */
+    name: string;
+    /** Secondary line under the role name. */
+    description?: string;
+    /** Member count caption, pluralized via CLDR. */
+    memberCount?: number;
+    /** A locked (system) role shows a lock badge and never offers deletion. */
+    locked?: boolean;
+};
+/** @see ServiceRolePanel */
+export type ServiceRolePanelProp = {
+    /** The roles in the master collection, in render order. */
+    roles: readonly ServiceRoleItemProp[];
+    /** Controlled selected role id. */
+    value?: string;
+    /** Uncontrolled initial selected role id. Defaults to the first role. */
+    defaultValue?: string;
+    /** Selection change handler. */
+    onValueChange?: (roleId: string) => void;
+    /**
+     * Detail surface for the current selection. A render function receives the selected role
+     * (or `undefined` when nothing is selected); a plain node is rendered as-is.
+     */
+    children?: ReactNode | ((role: ServiceRoleItemProp | undefined) => ReactNode);
+    /**
+     * Confirmed-deletion handler. Its PRESENCE adds a delete affordance per non-locked role behind
+     * the built-in destructive `AlertDialog`; the handler fires only AFTER the user confirms.
+     */
+    onDeleteRole?: (roleId: string) => void;
+    /** Hide every mutating affordance (locked view). */
+    readOnly?: boolean;
+    /** Show the loading skeleton instead of the panel. Precedence: loading → denied → error → empty. */
+    loading?: boolean;
+    /** Custom empty content when `roles` is empty; defaults to a localized EmptyState. */
+    empty?: ReactNode;
+    /** Failure state: `true` = built-in localized message, any other node replaces it. */
+    error?: ReactNode;
+    /** Permission-denied state — refused, not failed. Takes precedence over `error`. */
+    denied?: ReactNode;
+    /** Retry handler for the built-in `error` state; omit to hide the retry action. */
+    onRetry?: () => void;
+    /** Accessible names for the two regions (localized defaults otherwise). */
+    masterLabel?: string;
+    detailLabel?: string;
+    /** Forwarded MasterDetail geometry. */
+    railWidth?: MasterDetailRailWidthProp;
+    masterViewport?: MasterDetailMasterViewportProp;
+    collapseBelow?: BreakpointProp | false;
+    id?: IdProp;
+    className?: ClassNameProp;
+};

package/dist/props/components/navigation.prop.d.ts

@@ -1,6 +1,7 @@
 /** Navigation component prop types — @see docs/COMPONENTS.md#navigation */
 import type * as React from "react";
-import type { ChildrenProp, ClassNameProp, DisabledProp, HasActiveFiltersProp, IdProp, LabelProp, OnClearFiltersProp, StickyProp } from "../vocabulary/index.js";
+import type { ActionsProp, ChildrenProp, ClassNameProp, DisabledProp, ErrorProp, HasActiveFiltersProp, IdProp, LabelProp, OnClearFiltersProp, PendingProp, PlaceholderProp, StickyProp } from "../vocabulary/index.js";
+import type { SearchSelectOptionProp } from "./data-entry.prop.js";
 /**
  * How a {@link ToolbarProp} strip resolves more filters than fit one row (#216).
  * `wrap` (default) stacks on narrow viewports then wraps onto extra rows; `scroll` keeps ONE
@@ -8,61 +9,60 @@ import type { ChildrenProp, ClassNameProp, DisabledProp, HasActiveFiltersProp, I
  */
 export type FilterBarOverflowProp = "wrap" | "scroll";
 /**
- * One APPLIED filter, rendered as a removable chip under the control row (#258).
- *
- * The chip is the visible record of a filter that is already in effect — it is NOT the control that
- * sets it. `label` is caller-localized text (the bar never interprets or formats domain values);
- * omit `onRemove` for a chip the user may not lift (a scope locked by the route or by permission),
- * and the chip renders as a static token with no dead button.
+ * Typed search slot of the FilterBar model (gh#258). Renders the canonical SearchInput as the
+ * FIRST control of the strip, with a token-owned consistent width (`--filter-bar-search-width`,
+ * full-width below 640px). Controlled by consumer data via the `value`/`defaultValue`/
+ * `onValueChange` triad; `onSearch` mirrors SearchInput's debounced-term callback.
+ */
+export type FilterBarSearchProp = {
+    value?: string;
+    defaultValue?: string;
+    /** Fires on EVERY keystroke — required to keep a controlled `value` responsive. */
+    onValueChange?: (query: string) => void;
+    /** Fires with the DEBOUNCED term. Omit it when filtering is driven off `onValueChange`. */
+    onSearch?: (query: string) => void;
+    placeholder?: string;
+    /** Visible label above the search field. Omit for the placeholder-only compact form. */
+    label?: React.ReactNode;
+    /** Accessible name when no visible `label` is given (defaults to the localized "Search"). */
+    ariaLabel?: string;
+    id?: IdProp;
+    disabled?: DisabledProp;
+};
+/**
+ * One typed filter of the FilterBar model (gh#258): a labelled, domain-neutral Select whose
+ * options and selection are consumer data. `value` is the filter's stable identity (never shown);
+ * the visible `label` is rendered as the control's real `<label htmlFor>` (WCAG 2.5.3 / 1.3.1).
+ * Selection is controlled via `selected`/`defaultSelected`/`onSelectedChange` — the standard
+ * triad, renamed so the filter's own identity `value` stays unambiguous.
+ */
+export type FilterBarFilterProp = {
+    /** Stable filter identity (drives the control id + React key). */
+    value: string;
+    label: LabelProp;
+    options: SearchSelectOptionProp[];
+    selected?: string;
+    defaultSelected?: string;
+    onSelectedChange?: (selected: string) => void;
+    placeholder?: PlaceholderProp;
+    disabled?: DisabledProp;
+};
+/**
+ * One applied-filter chip of the FilterBar model (gh#258). Chips are pure consumer data — the
+ * lifecycle is: ADD by including the chip in `chips`, REMOVE via `onChipRemove(value)` (the ×
+ * button), CLEAR-ALL via the bar's `onClear`. `label` should be a string when possible so the
+ * remove button's accessible name can quote it; otherwise `value` is quoted instead.
  */
 export type FilterBarChipProp = {
-    /** Stable identity — also the argument passed back to {@link ToolbarProp.onChipRemove}. */
-    id: string;
-    /** Already-localized chip text, e.g. "状態: 未払い". */
-    label: string;
-    /**
-     * Per-chip removal. Omit for a chip the user cannot lift; the bar then renders no remove control
-     * rather than a disabled one, so nothing focusable is dead.
-     */
-    onRemove?: () => void;
+    /** Stable chip identity, passed to `onChipRemove`. */
+    value: string;
+    label: React.ReactNode;
+    disabled?: DisabledProp;
 };
 /** @see Toolbar */
 export type ToolbarProp = {
     onClear?: OnClearFiltersProp;
     hasActiveFilters?: HasActiveFiltersProp;
-    /**
-     * The search control (#258). A slot, not a rendered input: the bar owns its MEASURE
-     * (`--filter-bar-search-width`) and its position at the START of the row, while the caller
-     * still chooses the real primitive (`SearchInput`, or a `Select showSearch` for scoped search)
-     * and owns its debounce and value. Passing the control as a child instead is what produced the
-     * inconsistent search widths the issue was filed against.
-     */
-    search?: ChildrenProp;
-    /**
-     * Applied filters as removable chips (#258). The bar owns the CHIP LIFECYCLE — chips render
-     * below the control row, each with an accessible remove control, and the row disappears entirely
-     * when the array is empty (never an empty reserved strip). It owns no state: removing a chip
-     * calls back and the caller re-renders the array.
-     */
-    chips?: readonly FilterBarChipProp[];
-    /**
-     * Called with the chip's `id` when its remove control is activated. Fires in addition to that
-     * chip's own `onRemove`, so a caller may handle removal per chip, centrally, or both.
-     */
-    onChipRemove?: (id: string) => void;
-    /**
-     * Number of records the current filters resolve to (#258). Rendered in a POLITE LIVE REGION and
-     * formatted with `Intl.NumberFormat` + CLDR plurals for the active locale — which is the point:
-     * a sighted user sees the table change, and this is what tells everyone else that filtering
-     * happened. Omit when the count is unknown or still loading.
-     */
-    resultCount?: number;
-    /**
-     * Trailing action region (#258) — export, column settings, a saved-view menu. Rendered AFTER the
-     * reset control, so "clear filters" never sits at the end of the row beside an unrelated primary
-     * action. The bar owns the ordering; the caller owns the controls.
-     */
-    actions?: ChildrenProp;
     /**
      * Pin the strip to the top of its scroll container while the list scrolls beneath it
      * (list-page filter bars, #197). Opt-in — default `false` keeps the toolbar quiet. Tune
@@ -76,8 +76,35 @@ export type ToolbarProp = {
      * Tune the scrollbar gutter with the `--filter-bar-scroll-padding-y` theme knob.
      */
     overflow?: FilterBarOverflowProp;
+    /**
+     * Typed model (gh#258) — search slot. When ANY model prop (`search`/`filters`/`chips`/
+     * `onChipRemove`/`actions`/`resultCount`/`loading`/`disabled`/`error`) is present the bar renders
+     * the canonical model layout: strip (search → filters → children → reset → actions) → chips row →
+     * result-count/error line, with token-owned widths and stacking. Without any of them the bar
+     * stays the plain children-composition toolbar — existing markup is unchanged.
+     */
+    search?: FilterBarSearchProp;
+    /** Typed model — labelled Select filters rendered after the search slot, in array order. */
+    filters?: FilterBarFilterProp[];
+    /** Typed model — applied-filter chips (consumer data; add = include, remove = `onChipRemove`). */
+    chips?: FilterBarChipProp[];
+    /** Remove ONE chip by its `value`. Required for chips to render their × remove button. */
+    onChipRemove?: (value: string) => void;
+    /** Typed model — trailing action slot (e.g. a primary "Add" Button), parked at the inline end. */
+    actions?: ActionsProp;
+    /**
+     * Typed model — localized, pluralized result count ("{count} results") announced politely via a
+     * `role="status"` line under the strip. `0` is the rendered empty state, not "hidden".
+     */
+    resultCount?: number;
+    /** Typed model — marks the strip `aria-busy` while results are being (re)fetched. */
+    loading?: PendingProp;
+    /** Typed model — disables every model-rendered control (search, filters, reset, chip removes). */
+    disabled?: DisabledProp;
+    /** Typed model — consumer error content, announced via `role="alert"` in place of the count. */
+    error?: ErrorProp;
     className?: ClassNameProp;
-    children: ChildrenProp;
+    children?: ChildrenProp;
 };
 /** @see ToolbarGroup */
 export type ToolbarGroupProp = {