@godxjp/ui 31.31.7 → 32.0.0

package/docs/layout/error-surface/examples/system-500.tsx

@@ -1,47 +0,0 @@
-import { Button, Logo, Text } from "@godxjp/ui/general";
-import { ErrorSurface } from "@godxjp/ui/layout";
-import { RotateCcw } from "lucide-react";
-
-/**
- * 500 — `mode="system"`. The app itself is the thing that failed, so there is no authenticated shell
- * to preserve (the session, the nav data and the user menu may all be unavailable). Here the surface
- * DOES own the whole page: it renders `CenteredShell align="center"` itself, which flips
- * `--centered-shell-column-offset-block` to `auto` so the column centres in the `100dvh` shell at
- * 1440 / 1024 / 390 with NO consumer `min-h-dvh`, flex CSS, media query or `className`. Auto block
- * offsets collapse when the content is taller than the viewport, so a long localized message
- * scrolls from the top instead of being clipped.
- *
- * That is the whole difference between the two modes, and it is why `mode` is not cosmetic: in
- * `application` mode the surface returns a body and inherits geometry, in `system` mode it IS the
- * page and owns geometry.
- *
- * `width` defaults to the `sm` (~32rem) system-surface tier; the description's own measure is owned
- * by `--empty-state-description-max-width`. `titleLevel` defaults to `1` in system mode, because a
- * system page has no page `h1` above it — the error title IS the document's heading.
- *
- * `brand` and `footer` are system-mode-only slots (a `Logo` above the status code, the page
- * contentinfo below). Drop both for a bare surface.
- */
-export default function Demo() {
-  return (
-    <ErrorSurface
-      mode="system"
-      status={500}
-      brand={<Logo glyph="G" />}
-      title="問題が発生しました"
-      description="予期しないエラーが発生しました。担当チームに通知済みです。時間をおいて再度お試しください。"
-      requestId="01J9Z0M7Q2K5S7WQ3T5N8V2H4B"
-      footer={
-        <Text size="xs" tone="muted">
-          2026 GodX
-        </Text>
-      }
-      action={
-        <Button>
-          <RotateCcw />
-          再読み込み
-        </Button>
-      }
-    />
-  );
-}

package/docs/layout/error-surface/examples/system-503.tsx

@@ -1,48 +0,0 @@
-import { Button, Logo, Text } from "@godxjp/ui/general";
-import { ErrorSurface } from "@godxjp/ui/layout";
-import { RotateCcw } from "lucide-react";
-
-/**
- * 503 — `mode="system"` with the optional MAINTENANCE slot. Same viewport-centred geometry as 500;
- * the tone defaults to `warning` rather than `destructive` because the outage is planned and finite.
- *
- * `maintenance` is TIMING DATA, not a string you format. Pass ISO-8601 instants plus an IANA zone
- * and the surface runs `Intl.DateTimeFormat(locale, …).formatRange()` (CLDR) for the active locale,
- * so ja / en / vi each read natively and the visible text is paired with a machine-readable
- * `<time dateTime>`. A hand-built `"18:00 - 20:00 JST"` cannot localize and is the anti-pattern this
- * slot exists to remove. Omit `end` for an open-ended outage — a single instant is shown.
- *
- * `progress` (0–100) adds a labelled `Progress` meter, announced as "メンテナンス進捗 40%" via
- * `Intl.NumberFormat` percent style — never colour-only. It is deliberately SERVER-SENT: computing
- * "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. Omit it for an outage with no published
- * progress; omit `maintenance` entirely for an unplanned 503.
- */
-export default function Demo() {
-  return (
-    <ErrorSurface
-      mode="system"
-      status={503}
-      brand={<Logo glyph="G" />}
-      title="サービスを一時的にご利用いただけません"
-      description="計画メンテナンスを実施しています。終了予定時刻を過ぎてから再度お試しください。"
-      maintenance={{
-        start: "2026-08-02T18:00:00Z",
-        end: "2026-08-02T20:00:00Z",
-        timeZone: "Asia/Tokyo",
-        progress: 40,
-      }}
-      footer={
-        <Text size="xs" tone="muted">
-          2026 GodX
-        </Text>
-      }
-      action={
-        <Button>
-          <RotateCcw />
-          再読み込み
-        </Button>
-      }
-    />
-  );
-}

package/docs/layout/error-surface/index.md

@@ -1,153 +0,0 @@
---- title: Overview ---
-
-# Error surface — 403 / 404 / 500 / 503
-
-`ErrorSurface` is a **package-owned, importable component** (`@godxjp/ui/layout`). It owns the four HTTP exception pages every application ships, including their responsive geometry, so no app re-implements them from a generic `Card` in the wrong shell.
-
-```tsx
-import { ErrorSurface } from "@godxjp/ui/layout";
-```
-
-## History — why this is a component (gh#221 → gh#251)
-
-#221 first shipped this surface as a **documentation-only composition pattern**: the
-Framework-Component Test was run, it was judged a composition, and the package shipped two shells,
-some tokens and a docs page instead of an export. That was wrong in outcome, and #251 is the proof:
-**a consumer cannot `import` a docs page.** A clean install of 18.5.0 exposed no `ErrorSurface`, so
-DXS Platform was still forced to compose `AuthShell` + a generic `Card` behind a consumer-local
-`.canonical-auth-card` — exactly what the API-first rule forbids. The consumer requirement settles
-the question: the surface ships as a real export.
-
-Two things that analysis got right are preserved verbatim in the component's design:
-
-- **A component cannot manufacture the application shell.** Nav sections, product identity and the user menu are consumer-owned data. So `mode="application"` does not build chrome — it defines _where the surface goes_ (see below), and the surface renders only its own block. - **Exactly one recovery action** stays structural — one slot, extras dropped.
-
-## `mode` is the shell contract, not a skin
-
-| `mode`          | Status    | What the component renders                                          | What you provide                                                     |
-| --------------- | --------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `"application"` | 403 · 404 | **Only the surface block.** No shell, no landmark, no page geometry | The `AppShell` (usually + `PageContainer`) the route already renders |
-| `"system"`      | 500 · 503 | **The whole page** — `CenteredShell align="center"` + the surface   | Nothing. No `min-h-dvh`, no flex-centring class, no media query      |
-
-> **`mode="application"` means "this is what you put in AppShell's children".** The session is
-> valid, so the sidebar, topbar and breadcrumb stay mounted and the user can navigate away. The
-> surface never reconstructs them.
->
-> **`mode="system"` means "the app itself failed".** Session and nav data may be gone, so the
-> surface owns the page. `AuthShell` is never an option: it is the UNAUTHENTICATED root and imposes
-> auth-card geometry.
-
-## API
-
-```tsx
-<ErrorSurface
-  mode="application" | "system"     // required — the shell contract above
-  status={403 | 404 | 500 | 503}    // required — drives the default icon + tone
-  title={t("errors.403.title")}     // required — consumer-owned copy
-  description={t("errors.403.body")}
-  action={<Button>{t("errors.backHome")}</Button>}  // required — EXACTLY ONE
-
-  // optional semantic metadata slots (each renders as a <dt>/<dd> pair)
-  requestId="01J9Z0M7Q2K5S7WQ3T5N8V2H4B"
-  permission="reports.view"
-  organization="Acme KK"
-  maintenance={{ start, end, timeZone, progress }}  // ISO-8601 + IANA + 0–100
-
-  // optional overrides / system-mode slots
-  icon={LifeBuoy} tone="warning" titleLevel={2}
-  brand={<Logo glyph="G" />} footer={<Text size="xs">2026 GodX</Text>} width="sm"
-  id className ref
-/>
-```
-
-- **`status` is the input, not a lookup you write.** It selects the icon (`ShieldAlert` 403 ·
-  `SearchX` 404 · `ServerCrash` 500 · `Wrench` 503) and the tone (`warning` 403/503 · `muted` 404 ·
-  `destructive` 500). Override either only for a truer product glyph, never to recolour a severity.
-- **`action` is exactly one.** A single slot is the enforcement; pass a fragment with two buttons
-  and only the first renders, with a development-time error. Support contact belongs in
-  `description`, not in a second CTA.
-- **`titleLevel` defaults per mode** — `2` in `application` (a `PageContainer` `h1` sits above),
-  `1` in `system` (the surface IS the page). Override only to fit a deeper outline.
-- **Product copy stays consumer-owned.** `title` / `description` / `action` come from the app's own
-  `t()`. The surface localizes only its OWN metadata labels ("Request ID", "Required permission",
-  "Organization", "Scheduled maintenance", "Maintenance progress").
-
-## Metadata slots — semantic, not sentences
-
-Each slot renders a real `<dt>`/`<dd>` pair inside a `<dl>`, so the label↔value relationship
-survives for a screen reader instead of collapsing into a colon in a paragraph. Omit them all and
-the list is not rendered at all.
-
-| Slot                    | Why it exists                                                                                                                                                                    |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `requestId`             | Support correlation id. Mono + tabular so it can be read out or copied accurately.                                                                                               |
-| `permission`            | The missing role (403). Distinguishes "you need a role" from a generic refusal.                                                                                                  |
-| `organization`          | The tenant the request was scoped to. Distinguishes a wrong-workspace 403 from a missing-role one.                                                                               |
-| `maintenance.start/end` | ISO-8601 instants + an IANA `timeZone`, formatted by `Intl.DateTimeFormat(...).formatRange()`. The visible text is CLDR; `<time dateTime>` keeps the machine-readable ISO value. |
-| `maintenance.progress`  | 0–100, rendered as a labelled `Progress` meter with an `Intl.NumberFormat` percent name — never colour-only.                                                                     |
-
-**Never hand-build a window** (`"18:00 - 20:00 JST"`): it cannot localize. **Never derive
-`progress` from the client clock**: SSR and hydration would disagree, and an exception page must be
-readable before hydration.
-
-## Accessibility
-
-- **Status code is announced as a phrase.** The visible digits are `aria-hidden`; an `sr-only`
-  sibling carries "HTTP status 403", because a bare "403" is read as the cardinal number
-  "four hundred three".
-- **Heading order stays valid** by default in both modes (see `titleLevel` above).
-- The single action is a real `Button`: standard visible focus ring, reachable by `Tab`, no
-  positive tabindex.
-- Verified at **0 axe violations** for all four statuses, in both shells, with metadata, and under
-  `dir="rtl"` (`src/components/layout/__tests__/error-surface.a11y.test.tsx`).
-
-## Package-owned geometry (1440 / 1024 / 390)
-
-No consumer `className`, media query or `min-h-dvh` is needed at any viewport.
-
-| Token                                   | Default                   | Owns                                                                                                                                                                   |
-| --------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--error-surface-max-width`             | `32rem`                   | Measure of the whole surface block, in BOTH modes — so a long ja/vi headline wraps readably even inside a wide `PageContainer`.                                        |
-| `--error-surface-gap`                   | `--space-3`               | Rhythm between status code, body, metadata list and progress meter.                                                                                                    |
-| `--error-surface-padding-block`         | `--space-10`              | Block padding at the desktop steps (1440 / 1024).                                                                                                                      |
-| `--error-surface-padding-block-compact` | `--space-6`               | Block padding below the narrow step (the 390 case).                                                                                                                    |
-| `--error-surface-meta-gap` / `-row-gap` | `--space-1` / `--space-2` | Metadata row rhythm and the label↔value gap inside one row.                                                                                                            |
-| `--error-surface-meta-border`           | `none`                    | Divider above the metadata block. **Quiet by default (rule #44)** — a service opts in with `1px solid hsl(var(--border))`.                                             |
-| `--error-surface-progress-max-width`    | `18rem`                   | Progress meter measure, so it reads as metadata rather than as the page's primary content.                                                                             |
-| `--centered-shell-column-offset-block`  | `0` (`auto` when centred) | `system` mode only. `align="center"` centres the column in the `100dvh` shell; auto offsets collapse when content overflows, so tall copy scrolls instead of clipping. |
-| `--empty-state-description-max-width`   | `28rem`                   | Description measure — retune per service/locale instead of forking `.ui-empty-state-description`.                                                                      |
-
-The narrow step is a **container query on the surface's own width**, not a viewport query (the
-SplitPane precedent, gh#165): the surface compacts correctly whether the squeeze came from a 390px
-phone or from an application shell with an expanded sidebar. Below the step, metadata rows stack
-label-over-value instead of wrapping into a ragged two-column shape.
-
-## SSR / Inertia exception pages
-
-The surface has **no state, no effects and no portals**, so it renders fully server-side. Inertia
-delivers every exception through one `Error` page component that receives the HTTP `status`
-(Laravel `Handler::render()` → `Inertia::render('Error', ['status' => …])`), which maps onto
-`ErrorSurface` with a single expression:
-
-````tsx
-// resources/js/Pages/Error.tsx
-import { Button, Logo } from "@godxjp/ui/general";
-import { ErrorSurface } from "@godxjp/ui/layout";
-import { Link, router } from "@inertiajs/react";
-
-export default function Error({ status, requestId, }: { status: 403 | 404 | 500 | 503; requestId?: string; }) { const { t } = useTranslation(); // the APP's i18n — @godxjp/ui never owns product copy const isSystem = status >= 500;
-
-return ( <ErrorSurface mode={isSystem ? "system" : "application"} status={status} title={t(`errors.${status}.title`)} description={t(`errors.${status}.description`)} requestId={requestId} {...(isSystem ? { brand: <Logo glyph="G" /> } : {})} action={ isSystem ? ( <Button onClick={() => router.reload()}>{t("errors.reload")}</Button> ) : ( <Button asChild> <Link href="/">{t("errors.backHome")}</Link> </Button> ) } /> ); }
-
-// Persistent layout ⇒ 403/404 keep the authenticated shell (the sidebar is not re-mounted, scroll // and drawer state survive); 500/503 render standalone, because the surface owns the page. Error.layout = (page: React.ReactNode) => page.props.status < 500 ? <AuthenticatedLayout>{page}</AuthenticatedLayout> : page; ```
-
-SSR notes:
-
-- Send the maintenance window as **ISO-8601 from the server** with an explicit `timeZone`. Relying on the server's local zone makes SSR and client output diverge and React logs a hydration mismatch. - A 500 page must not import the app's data providers/query client — the failure may be inside them. `ErrorSurface` needs no provider beyond the `AppProvider` that supplies the locale.
-
-## Anti-patterns
-
-## The composition underneath
-
-`ErrorSurface` composes real primitives (`EmptyState` · `Text` · `Progress` · `CenteredShell`) and adds no bespoke markup you could not inspect. For a status outside the supported four, compose the same body by hand — that composition is pinned by `src/components/layout/__tests__/error-surface-pattern.test.tsx`, so it cannot break from underneath.
-````

package/docs/layout/error-surface/index.tsx

@@ -1,239 +0,0 @@
-import { Card, CardContent, CardHeader, CardTitle } from "@godxjp/ui/data-display";
-import { Button, Logo } from "@godxjp/ui/general";
-import { ErrorSurface, Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
-import { LifeBuoy, RotateCcw } from "lucide-react";
-
-/**
- * ERROR SURFACE (403 · 404 · 500 · 503) — a real, importable component: `ErrorSurface`.
- *
- * `mode` is the SHELL CONTRACT, not a skin:
- *   application (403/404) → the BODY you place inside the AppShell the route already renders
- *   system      (500/503) → owns the page: CenteredShell align="center", package-owned geometry
- *
- * Every card below renders the surface in `application` mode, because a `system` surface is a full
- * `100dvh` page and would swallow this catalogue page — see the Examples for the two real screens.
- *
- * Structure of the surface: status code (compact, mono/tabular, announced as "HTTP status 403")
- * → icon · tone · title · description · EXACTLY ONE action → optional semantic metadata rows
- * (request id · required permission · organization · maintenance window + progress).
- */
-export default function Demo() {
-  return (
-    <PageContainer
-      title="Error surface"
-      subtitle="ErrorSurface · 403 / 404 / 500 / 503 · mode=application (AppShell body) vs mode=system (owns the page)"
-    >
-      <Flex direction="col" gap="lg">
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>status=403 · 権限なし（permission + organization）</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <ErrorSurface
-              mode="application"
-              status={403}
-              titleLevel={3}
-              title="このページへのアクセス権限がありません"
-              description="管理者にレポート閲覧ロールの付与を依頼してください。"
-              permission="reports.view"
-              organization="株式会社ゴッドエックス"
-              action={<Button>ダッシュボードへ戻る</Button>}
-            />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>status=404 · 未検出（メタデータなし）</CardTitle>
-          </CardHeader>
-          <CardContent>
-            {/* Every metadata slot omitted ⇒ the whole description list disappears. Metadata is
-                optional; the surface never renders an empty row or a dangling label. */}
-            <ErrorSurface
-              mode="application"
-              status={404}
-              titleLevel={3}
-              title="ページが見つかりません"
-              description="お探しのページは移動または削除された可能性があります。"
-              action={<Button>ダッシュボードへ戻る</Button>}
-            />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>status=500 · リクエスト ID 付き</CardTitle>
-          </CardHeader>
-          <CardContent>
-            {/* Shown here in application mode so the card can contain it. In a real 500 page this
-                is mode="system" and the surface owns the whole viewport. */}
-            <ErrorSurface
-              mode="application"
-              status={500}
-              titleLevel={3}
-              title="問題が発生しました"
-              description="予期しないエラーが発生しました。担当チームに通知済みです。"
-              requestId="01J9Z0M7Q2K5S7WQ3T5N8V2H4B"
-              action={
-                <Button>
-                  <RotateCcw />
-                  再読み込み
-                </Button>
-              }
-            />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>status=503 · メンテナンス時間帯 + 進捗</CardTitle>
-          </CardHeader>
-          <CardContent>
-            {/* ISO-8601 instants + an IANA zone in, Intl.DateTimeFormat.formatRange out. The
-                progress meter is server-sent (a client clock would break SSR hydration). */}
-            <ErrorSurface
-              mode="application"
-              status={503}
-              titleLevel={3}
-              title="サービスを一時的にご利用いただけません"
-              description="計画メンテナンスを実施しています。しばらくしてから再度お試しください。"
-              maintenance={{
-                start: "2026-08-02T18:00:00Z",
-                end: "2026-08-02T20:00:00Z",
-                timeZone: "Asia/Tokyo",
-                progress: 40,
-              }}
-              action={
-                <Button>
-                  <RotateCcw />
-                  再読み込み
-                </Button>
-              }
-            />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>icon / tone / brand の上書き</CardTitle>
-          </CardHeader>
-          <CardContent>
-            {/* icon and tone DEFAULT from the status (500 ⇒ ServerCrash + destructive). Override
-                them only when the product has a truer glyph for the failure — never to recolour a
-                status into a different severity. `brand` is system-mode only and is ignored here. */}
-            <ErrorSurface
-              mode="application"
-              status={500}
-              titleLevel={3}
-              icon={LifeBuoy}
-              tone="warning"
-              brand={<Logo glyph="G" />}
-              title="復旧作業中です"
-              description="サポートチームが対応しています。復旧までしばらくお待ちください。"
-              action={<Button variant="outline">ステータスページを見る</Button>}
-            />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>tone · セマンティックな重大度の 5 段階</CardTitle>
-          </CardHeader>
-          <CardContent>
-            {/* `tone` DEFAULTS from `status` (403/503 warning · 404 muted · 500 destructive). An
-                explicit tone is for the case where the product knows a TRUER severity than the
-                status code carries -- a planned window is informational, a resolved incident is a
-                success -- never to recolour one severity into another for decoration. All five
-                branches are rendered here so the whole axis is readable at rest. */}
-            <ResponsiveGrid columns={{ sm: 1, md: 3 }}>
-              <ErrorSurface
-                mode="application"
-                status={404}
-                tone="muted"
-                titleLevel={3}
-                title="ページが見つかりません"
-                description="リンクが古い可能性があります。中立な不在であり、障害ではありません。"
-                action={<Button variant="outline">ホームへ戻る</Button>}
-              />
-              <ErrorSurface
-                mode="application"
-                status={503}
-                tone="info"
-                titleLevel={3}
-                title="計画メンテナンスを実施しています"
-                description="事前告知済みの停止です。障害ではないため、警告ではなく情報として提示します。"
-                action={<Button variant="outline">ステータスページを見る</Button>}
-              />
-              <ErrorSurface
-                mode="application"
-                status={403}
-                tone="warning"
-                titleLevel={3}
-                title="この操作には承認が必要です"
-                description="権限を追加すれば同じ画面に戻れます。回復可能な状態です。"
-                action={<Button variant="outline">権限を申請する</Button>}
-              />
-              <ErrorSurface
-                mode="application"
-                status={500}
-                tone="destructive"
-                titleLevel={3}
-                title="問題が発生しました"
-                description="想定外の失敗です。利用者側の操作では回復できません。"
-                action={<Button variant="outline">再読み込み</Button>}
-              />
-              <ErrorSurface
-                mode="application"
-                status={503}
-                tone="success"
-                titleLevel={3}
-                title="復旧が完了しました"
-                description="最終確認を行っています。まもなく通常どおりご利用いただけます。"
-                action={<Button variant="outline">再読み込み</Button>}
-              />
-            </ResponsiveGrid>
-          </CardContent>
-        </Card>
-
-        {/* The same surface in ja / en / vi. The library-owned metadata LABELS ("Request ID") follow
-            the active app locale; the product copy is whatever the app's own t() returns. The
-            description measure is owned by --empty-state-description-max-width (28rem), and the
-            surface measure by --error-surface-max-width (32rem), so the longest locale wraps
-            instead of breaking the layout. */}
-        <Card>
-          <CardHeader>
-            <CardTitle level={2}>多言語オーバーフロー：ja / en / vi</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <ResponsiveGrid columns={{ sm: 1, md: 3 }}>
-              <ErrorSurface
-                mode="application"
-                status={503}
-                titleLevel={3}
-                title="サービスを一時的にご利用いただけません"
-                description="計画メンテナンスを実施しています。しばらくしてから再度お試しください。"
-                action={<Button variant="outline">再読み込み</Button>}
-              />
-              <ErrorSurface
-                mode="application"
-                status={503}
-                titleLevel={3}
-                title="Service temporarily unavailable"
-                description="We are performing scheduled maintenance right now. Please try again in a few minutes."
-                action={<Button variant="outline">Reload</Button>}
-              />
-              <ErrorSurface
-                mode="application"
-                status={503}
-                titleLevel={3}
-                title="Dịch vụ tạm thời không khả dụng"
-                description="Chúng tôi đang bảo trì theo lịch. Vui lòng thử lại sau ít phút nữa."
-                action={<Button variant="outline">Tải lại</Button>}
-              />
-            </ResponsiveGrid>
-          </CardContent>
-        </Card>
-      </Flex>
-    </PageContainer>
-  );
-}