@godxjp/ui 18.5.0 → 18.7.0

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

@@ -1,7 +1,8 @@
 /** 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, AuthShellPresetProp, BreakpointProp, GapProp, ClassNameProp, ChildrenProp, IdProp } from "../vocabulary/index.js";
+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 { EmptyStateToneProp } from "./data-display.prop.js";
 /**
  * Arrangement of the page header's title band and its `extra` slot below the 640px step.
  * `stack` (default) is the historical arrangement — `extra` drops onto its own full-width line
@@ -9,10 +10,69 @@ import type { BreadcrumbProp, TitleProp, SubtitleProp, ExtraProp, FooterProp, Pa
  * `--page-header-extra-measure` measure, letting the title/subtitle wrap into what is left.
  */
 export type PageContainerHeaderLayoutProp = "stack" | "responsive-inline";
+/** Whole-page semantic composition owned by PageContainer. */
+export type PageContainerPresetProp = "default" | "admin-collection";
+/**
+ * Bounded page MEASURE — the shared inline cap applied to the page header AND body together, so
+ * the header `extra` action ends on the same edge as the body surface. Orthogonal to
+ * `PageContainerVariantProp` (chrome) and to `PageContainerHeaderLayoutProp`, so a quiet
+ * `variant="ghost"` feed can finally have a bounded measure too (gh#245 / gh#247).
+ *
+ * `default` applies NO cap — the page is fluid exactly as before. `narrow` / `medium` read the
+ * `--page-measure-{narrow,medium}` tokens (42rem / 48rem OUTER, i.e. 624px / 720px VISIBLE surface
+ * once the package-owned page gutters are subtracted). Both are maxes, so a compact viewport stays
+ * 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 = {
+    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
+     */
+    layout?: PageContainerHeaderLayoutProp;
+    /**
+     * 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.
+     */
+    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;
     breadcrumb?: BreadcrumbProp;
@@ -28,6 +88,12 @@ export type PageContainerProp = {
     linkComponent?: React.ElementType;
     density?: PageDensityProp;
     variant?: PageContainerVariantProp;
+    /**
+     * Whole-page composition contract. `admin-collection` sets the header-to-toolbar rhythm,
+     * collection search measure, control height and table density once for the entire subtree.
+     * Geometry remains token-owned and service-themeable; no child needs a sizing override.
+     */
+    preset?: PageContainerPresetProp;
     /**
      * How the title band and `extra` share the header row below the 640px step. Defaults to
      * `stack` — the historical arrangement, where `extra` wraps onto its own full-width line under
@@ -36,6 +102,15 @@ export type PageContainerProp = {
      * `--page-header-extra-measure`. At >=640px both arrangements are identical.
      */
     headerLayout?: PageContainerHeaderLayoutProp;
+    /**
+     * Bounded page measure shared by the header and the body. Defaults to `default` — no cap, the
+     * historical fluid page. `narrow` (624px surface) / `medium` (720px surface) cap BOTH bands to
+     * one token-owned measure (`--page-measure-{narrow,medium}`), so a header action ends flush with
+     * the body surface instead of at the page edge. Orthogonal to `variant`, so `variant="ghost"`
+     * quiet chrome composes with a bounded measure (gh#245 / gh#247). Unlike `variant="narrow"`,
+     * which caps only the body.
+     */
+    measure?: PageContainerMeasureProp;
     /** Pin footer to viewport bottom on scroll — pairs well with `variant="narrow"`. */
     stickyFooter?: boolean;
     /**
@@ -68,6 +143,20 @@ export type FlexProp = React.HTMLAttributes<HTMLDivElement> & {
     align?: FlexAlignProp;
     justify?: FlexJustifyProp;
     wrap?: boolean;
+    /**
+     * Drop this region below a breakpoint step (`sm` 40rem · `md` 48rem · `lg` 64rem · `xl` 80rem).
+     * The ONE public way to make a layout region responsive without a page-local media query — a
+     * public header hides its anchor navigation below the tablet step with `hideBelow="md"` instead
+     * of a consumer `@media` rule (gh#252). Omit (the default) and no attribute is emitted, so no
+     * rule can match and the Flex is unchanged. The region is removed from the accessibility tree
+     * too, so keep its destinations reachable elsewhere at that width (a footer nav).
+     */
+    hideBelow?: BreakpointProp;
+    /**
+     * The inverse of `hideBelow` — drop this region FROM a breakpoint step upwards, i.e. keep it
+     * only on the narrow side (a compact-only affordance). Omit for no attribute and no rule.
+     */
+    hideFrom?: BreakpointProp;
 };
 export type ResponsiveGridColumnsProp = number | {
     sm?: number;
@@ -136,6 +225,17 @@ export type AppShellProp = {
     breadcrumb?: ReactNode;
     footer?: ReactNode;
     sidebarCollapsed?: boolean;
+    /**
+     * Responsive navigation strategy below the canonical 900px shell breakpoint.
+     *
+     * - `"drawer"` (default) hides the docked sidebar and exposes the accessible mobile Sheet.
+     * - `"docked"` keeps the sidebar grid track, footer/account region and active navigation in the
+     *   shell at narrow widths. The sidebar width remains owned by `--app-shell-sidebar-width`.
+     *
+     * Use `"docked"` only when the product's approved responsive contract explicitly retains the
+     * rail; it intentionally suppresses the redundant mobile drawer trigger.
+     */
+    responsiveNavigation?: "drawer" | "docked";
     /**
      * Navigation shown in the mobile drawer at the DXS 900px breakpoint, where the docked sidebar is
      * hidden. AppShell OWNS the drawer: it renders a hamburger trigger in the topbar and a focus-
@@ -176,10 +276,23 @@ 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-{device,context,recovery}-*`). Selecting a preset replaces every consumer-side
-     * `--auth-shell-card-max-width` override.
+     * (`--auth-shell-{login,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
+     *   1440x900, 1024x900 and 390x844 viewports. The identity occupies a package-owned anchor slot,
+     *   so standalone, one-line requester and wrapped two-line requester states keep the same card
+     *   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
+     *   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.
      * - `"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
@@ -190,7 +303,7 @@ export type AuthShellProp = {
      *   · passkey-failure), whose title and description sit INSIDE the bordered surface.
      *
      * Orthogonal to `variant`: presets are applied AFTER it, so `variant="canonical"` keeps owning
-     * control density and heading size while the preset re-measures the page.
+     * control density and heading size while the preset re-measures/anchors the page.
      */
     preset?: AuthShellPresetProp;
     /**
@@ -241,6 +354,20 @@ export type AuthIdentityProp = {
     requester?: ReactNode;
     className?: ClassNameProp;
 };
+/**
+ * @see AuthAccountSummary — compact signed-in identity row for hosted authentication surfaces.
+ * It owns avatar fallback, bidi-safe email truncation and the keyboard action geometry; the
+ * consumer owns the authoritative email, localized action label and navigation handler.
+ */
+export type AuthAccountSummaryProp = {
+    email: string;
+    avatarSrc?: string;
+    avatarFallback?: ReactNode;
+    actionLabel: ReactNode;
+    onAction: () => void;
+    disabled?: DisabledProp;
+    className?: ClassNameProp;
+};
 /**
  * @see CenteredShell — authenticated, no-sidebar, centred-column page shell (hosted-ID "My Page",
  * account / self-service, standalone settings). A padded top bar with real actions (banner) reusing
@@ -276,6 +403,119 @@ export type CenteredShellProp = {
      * a long localized message is never clipped.
      */
     align?: CenteredShellAlignProp;
+    /**
+     * Whole-page shell contract. `"default"` (the default) emits no attribute and keeps the shell's
+     * exact box. `"public-landing"` owns the PUBLIC landing geometry — one content measure shared by
+     * the header bar, the centred column and the footer, the section rhythm, the flat public-surface
+     * card chrome and the hero `h1` tier — from `--centered-shell-landing-*` tokens, so a landing
+     * composition (header · hero · sections · legal footer) needs no page-local CSS and no descendant
+     * selector against shell internals (gh#252).
+     */
+    preset?: CenteredShellPresetProp;
+    className?: ClassNameProp;
+};
+/**
+ * @see ErrorSurface — the optional maintenance / planned-outage timing slot (503, occasionally a
+ * planned 500).
+ *
+ * `start` / `end` are **ISO-8601 instants** and `timeZone` an **IANA** zone id: the surface formats
+ * them with `Intl.DateTimeFormat(locale, …).formatRange()` (CLDR), so ja / en / vi each read
+ * natively. NEVER pass a pre-formatted string like `"18:00 - 20:00 JST"` — it cannot localize, and
+ * the machine-readable value is what lands in `<time dateTime>`.
+ *
+ * `progress` is server-sent on purpose: deriving "how far through the window are we" from the
+ * client clock makes SSR and hydration disagree, and an exception page must be readable before
+ * hydration.
+ */
+export type ErrorSurfaceMaintenanceProp = {
+    /** Window start as an ISO-8601 instant (`2026-08-02T18:00:00Z`). Also the `<time dateTime>` value. */
+    start: string;
+    /** Window end as an ISO-8601 instant. Omit for an open-ended outage — a single instant is shown. */
+    end?: string;
+    /**
+     * IANA time zone id (`Asia/Tokyo`) the window is presented in. Omit to use the runtime zone —
+     * pass it explicitly whenever the page is server-rendered, or SSR and client output diverge.
+     */
+    timeZone?: string;
+    /**
+     * Completion of the maintenance window as a **percentage 0–100**, rendered as a labelled
+     * `Progress` meter. Server-sent (see above); omit for an outage with no published progress.
+     */
+    progress?: number;
+};
+/**
+ * @see ErrorSurface — the package-owned semantic exception surface for 403 / 404 / 500 / 503.
+ *
+ * The `mode` is the SHELL CONTRACT, not a skin:
+ * - `mode="application"` (403/404) renders the surface as the **body** you put inside the
+ *   `AppShell` the route already provides (normally within a `PageContainer`). It deliberately does
+ *   NOT reconstruct navigation chrome: the sidebar, topbar and user menu are consumer-owned data,
+ *   so the surface preserves the shell it is placed in instead of manufacturing a fake one.
+ * - `mode="system"` (500/503) owns the whole page: it renders `CenteredShell align="center"`, so
+ *   the viewport-centred geometry at 1440 / 1024 / 390 stays package-owned and a consumer never
+ *   writes `min-h-dvh`, a flex-centring class or a media query.
+ *
+ * `action` is **exactly one** recovery action, enforced structurally by a single slot (a second
+ * element is dropped with a development error). Support contact belongs in `description`, not in a
+ * second CTA.
+ *
+ * All product COPY stays consumer-owned (`title` / `description` / `action` come from the app's own
+ * `t()`); the surface owns only its own metadata labels, which it localizes itself.
+ */
+export type ErrorSurfaceProp = {
+    /** Where the surface lives — `application` = AppShell body (403/404), `system` = own page (500/503). */
+    mode: ErrorSurfaceModeProp;
+    /** HTTP status presented. Drives the default `icon`, `tone` and the rendered status code. */
+    status: ErrorSurfaceStatusProp;
+    /** Headline. Consumer-owned copy from the app's `t()` — the library ships no product text. */
+    title: TitleProp;
+    /** Supporting sentence under the title. Put support-contact guidance here, never in a 2nd CTA. */
+    description?: DescriptionProp;
+    /**
+     * The ONE recovery action (a `Button`, or a `Button asChild` wrapping a router `Link`). A single
+     * slot IS the enforcement: pass more than one element and only the first renders, with a
+     * development-time error.
+     */
+    action: ActionProp;
+    /** Override the status-derived icon (403 ShieldAlert · 404 SearchX · 500 ServerCrash · 503 Wrench). */
+    icon?: IconProp;
+    /** Override the status-derived tone (403/503 `warning` · 404 `muted` · 500 `destructive`). */
+    tone?: EmptyStateToneProp;
+    /**
+     * Semantic heading level of `title`. Defaults to `2` in `application` mode (a `PageContainer`
+     * `h1` sits above it) and `1` in `system` mode (the surface IS the page). Choose it to keep the
+     * outline valid, never for size.
+     */
+    titleLevel?: HeadingLevelProp;
+    /**
+     * Support correlation id for the failure, rendered as a monospace/tabular metadata row so it can
+     * be read out or copied accurately. Pass the bare id — the localized label is the surface's.
+     */
+    requestId?: string;
+    /**
+     * The permission / role the viewer is missing (403). Pass the bare permission name
+     * (`reports.view`) — the surface renders the localized "Required permission" label around it.
+     */
+    permission?: ReactNode;
+    /**
+     * The organization / tenant the failed request was scoped to. Disambiguates a 403 caused by
+     * being in the wrong workspace from one caused by a missing role.
+     */
+    organization?: ReactNode;
+    /** Optional planned-outage timing + progress (503). ISO-8601 + IANA, formatted with `Intl`. */
+    maintenance?: ErrorSurfaceMaintenanceProp;
+    /**
+     * `system` mode only — brand slot above the status code (a `Logo`). Ignored in `application`
+     * mode, where the shell already shows the product brand.
+     */
+    brand?: ReactNode;
+    /** `system` mode only — the page footer (contentinfo): copyright, status page, locale switch. */
+    footer?: FooterProp;
+    /**
+     * `system` mode only — measure of the centred column (`CenteredShell` width tier). Default `sm`.
+     */
+    width?: CenteredShellWidthProp;
+    id?: IdProp;
     className?: ClassNameProp;
 };
 /** @see Sidebar */

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

@@ -7,10 +7,62 @@ import type { ChildrenProp, ClassNameProp, DisabledProp, HasActiveFiltersProp, I
  * bounded row that scrolls inline, so a wide filter set never pushes the list below the fold.
  */
 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.
+ */
+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;
+};
 /** @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
@@ -85,7 +137,11 @@ export type StepsProp = {
     defaultValue?: number;
     status?: StepStatusProp;
     orientation?: "horizontal" | "vertical";
-    type?: "default" | "dot";
+    /**
+     * Marker appearance. `inline` renders the compact numbered auth/device progress row without the
+     * icon rail while preserving the same status and current-step semantics.
+     */
+    type?: "default" | "dot" | "inline";
     size?: "md" | "sm";
     titlePlacement?: "horizontal" | "vertical";
     onValueChange?: (value: number) => void;