@tailor-platform/app-shell 1.17.0 → 1.19.0

package/skills/app-shell-patterns/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: app-shell-patterns
 description: "Best-practice UI patterns and correct component usage for building pages in apps that use @tailor-platform/app-shell. Use when: building or editing any screen, page, list, table, detail view, form, modal, dialog, wizard, or bulk/confirm/toast interaction in an app with @tailor-platform/app-shell installed — when choosing the right AppShell component, layout, or design token for a UI — or when upgrading @tailor-platform/app-shell, or diagnosing styling, theming, or dark-mode breakage that appeared after a version bump."
+metadata:
+  app-shell-version: "1.19.0"
 ---
 
 # App-Shell Patterns
@@ -9,6 +11,10 @@ description: "Best-practice UI patterns and correct component usage for building
 
 Select and implement the correct UI pattern using @tailor-platform/app-shell components.
 
+## Version
+
+This skill was generated from `@tailor-platform/app-shell` **1.19.0**. Before relying on it, compare that with the version installed in the app you're working on (resolve `@tailor-platform/app-shell/package.json` from that app, not the monorepo root). If they differ, this copy is stale: tell the user and suggest re-syncing it from the installed package's `skills/app-shell-patterns/` directory.
+
 ## Concepts
 
 Cross-cutting guides that underpin every screen — styling & theming and the token system, GraphQL data access, building custom components, plus auth and routing. Patterns and components build on these.
@@ -64,6 +70,7 @@ Every AppShell component, its API surface, and usage guidance. Read the entry fo
 | [GlobalHeaderLayout](references/components/global-header-layout.md)     | Opinionated layout with an app-wide header above the whole shell and a sidebar that collapses to a persistent icon rail                            |
 | [Grid](references/components/grid.md)                                   | Generic CSS-Grid layout primitive for equal or custom-width columns with responsive reflow, auto-fit, and spanning                                 |
 | [Input](references/components/input.md)                                 | Styled text input with consistent theming                                                                                                          |
+| [ItemList](references/components/item-list.md)                          | Compact icon-and-label lists for consistent navigation inside and outside the Sidebar                                                              |
 | [Layout](references/components/layout.md)                               | Responsive column layout component for organizing page content in 1, 2, or 3 columns                                                               |
 | [Menu](references/components/menu.md)                                   | Dropdown menu with a compound component API, supporting checkbox/radio items, groups, separators, and nested sub-menus                             |
 | [MetricCard](references/components/metric-card.md)                      | Compact card for dashboard KPI summaries with title, value, optional trend and description                                                         |
@@ -76,6 +83,7 @@ Every AppShell component, its API surface, and usage guidance. Read the entry fo
 | [Spinner](references/components/spinner.md)                             | Lightweight loading indicator component with accessible defaults and preset sizes                                                                  |
 | [Table](references/components/table.md)                                 | Semantic HTML table with pre-styled sub-components                                                                                                 |
 | [Tabs](references/components/tabs.md)                                   | Tab navigation with a compound component API                                                                                                       |
+| [Text](references/components/text.md)                                   | Text with a typography role, rendered as an element you choose                                                                                     |
 | [Textarea](references/components/textarea.md)                           | Styled multi-line text input sized by rows, with automatic Field / React Hook Form integration                                                     |
 | [Timeline](references/components/timeline.md)                           | Composable primitives for building time-based layouts with axis guides, row backgrounds, intervals, and dependency links                           |
 | [Toolbar](references/components/toolbar.md)                             | Full-width action bars with composable rows, grouped controls, and keyboard navigation                                                             |
@@ -86,33 +94,34 @@ Every AppShell component, its API surface, and usage guidance. Read the entry fo
 
 Hooks, factory functions, guards, and router utilities exported by AppShell.
 
-| Name                                                                                       | Description                                                                   |
-| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| [createAIGatewayClient](references/api/create-ai-gateway-client.md)                        | Create a low-level AI Gateway client that reuses AppShell authentication      |
-| [createTypedPaths](references/api/create-typed-paths.md)                                   | Generate type-safe route paths from file-based routing                        |
-| [defineI18nLabels](references/api/define-i18n-labels.md)                                   | Define internationalized labels for multi-language support                    |
-| [defineModule](references/api/define-module.md)                                            | Define a top-level module that appears in the main navigation                 |
-| [defineResource](references/api/define-resource.md)                                        | Define a nested resource (page) within a module                               |
-| [hidden](references/api/guards/hidden.md)                                                  | Guard function that denies access and returns 404 Not Found                   |
-| [Guards Overview](references/api/guards/overview.md)                                       | Access control system for routes and components using guard functions         |
-| [pass](references/api/guards/pass.md)                                                      | Guard function that allows access and continues to the next guard             |
-| [redirectTo](references/api/guards/redirect-to.md)                                         | Guard function that redirects to another page                                 |
-| [useLocation](references/api/router/use-location.md)                                       | Hook to access current location object with pathname, search, and state       |
-| [useNavigate](references/api/router/use-navigate.md)                                       | Hook for programmatic navigation between routes                               |
-| [useParams](references/api/router/use-params.md)                                           | Hook to access dynamic route parameters                                       |
-| [useAIChat](references/api/use-ai-chat.md)                                                 | Simple text-only chat hook for AI Gateway                                     |
-| [useAppShell](references/api/use-app-shell.md)                                             | Hook to access AppShell context data and configuration                        |
-| [useAppShellConfig](references/api/use-app-shell-config.md)                                | Hook to access AppShell configuration data                                    |
-| [useAppShellData](references/api/use-app-shell-data.md)                                    | Hook to access custom context data passed to AppShell                         |
-| [useAuth](references/api/use-auth.md)                                                      | Hook for accessing authentication state and methods                           |
-| [useOverrideBreadcrumb](references/api/use-override-breadcrumb.md)                         | Hook for dynamically overriding breadcrumb titles from within page components |
-| [usePageMeta](references/api/use-page-meta.md)                                             | Hook to resolve page metadata from route path                                 |
-| [useRegisterCommandPaletteActions](references/api/use-register-command-palette-actions.md) | Hook for registering contextual page actions into the CommandPalette          |
-| [useResolvedLocale](references/api/use-resolved-locale.md)                                 | Hook to access the full BCP-47 locale and language code from AppShell context |
-| [useRouteError](references/api/use-route-error.md)                                         | Hook to access error details in custom error boundaries                       |
-| [useTheme](references/api/use-theme.md)                                                    | Hook for accessing and controlling theme (light/dark mode)                    |
-| [useTimeZone](references/api/use-time-zone.md)                                             | Hook to access the configured IANA timezone from AppShell context             |
-| [useToast](references/api/use-toast.md)                                                    | Hook for displaying toast notifications                                       |
+| Name                                                                                       | Description                                                                                                                               |
+| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| [Value aggregations](references/api/aggregations.md)                                       | Reusable selector-based sum, average, minimum, maximum, and non-null count over row collections, with optional result-only transformation |
+| [createAIGatewayClient](references/api/create-ai-gateway-client.md)                        | Create a low-level AI Gateway client that reuses AppShell authentication                                                                  |
+| [createTypedPaths](references/api/create-typed-paths.md)                                   | Generate type-safe route paths from file-based routing                                                                                    |
+| [defineI18nLabels](references/api/define-i18n-labels.md)                                   | Type-safe locale-first labels for component text and localized navigation metadata                                                        |
+| [defineModule](references/api/define-module.md)                                            | Define a top-level module that appears in the main navigation                                                                             |
+| [defineResource](references/api/define-resource.md)                                        | Define a nested resource (page) within a module                                                                                           |
+| [hidden](references/api/guards/hidden.md)                                                  | Guard function that denies access and returns 404 Not Found                                                                               |
+| [Guards Overview](references/api/guards/overview.md)                                       | Access control system for routes and components using guard functions                                                                     |
+| [pass](references/api/guards/pass.md)                                                      | Guard function that allows access and continues to the next guard                                                                         |
+| [redirectTo](references/api/guards/redirect-to.md)                                         | Guard function that redirects to another page                                                                                             |
+| [useLocation](references/api/router/use-location.md)                                       | Hook to access current location object with pathname, search, and state                                                                   |
+| [useNavigate](references/api/router/use-navigate.md)                                       | Hook for programmatic navigation between routes                                                                                           |
+| [useParams](references/api/router/use-params.md)                                           | Hook to access dynamic route parameters                                                                                                   |
+| [useAIChat](references/api/use-ai-chat.md)                                                 | Simple text-only chat hook for AI Gateway                                                                                                 |
+| [useAppShell](references/api/use-app-shell.md)                                             | Hook to access AppShell context data and configuration                                                                                    |
+| [useAppShellConfig](references/api/use-app-shell-config.md)                                | Hook to access AppShell configuration data                                                                                                |
+| [useAppShellData](references/api/use-app-shell-data.md)                                    | Hook to access custom context data passed to AppShell                                                                                     |
+| [useAuth](references/api/use-auth.md)                                                      | Hook for accessing authentication state and methods                                                                                       |
+| [useOverrideBreadcrumb](references/api/use-override-breadcrumb.md)                         | Hook for dynamically overriding breadcrumb titles from within page components                                                             |
+| [usePageMeta](references/api/use-page-meta.md)                                             | Hook to resolve page metadata from route path                                                                                             |
+| [useRegisterCommandPaletteActions](references/api/use-register-command-palette-actions.md) | Hook for registering contextual page actions into the CommandPalette                                                                      |
+| [useResolvedLocale](references/api/use-resolved-locale.md)                                 | Hook to access the full BCP-47 locale and language code from AppShell context                                                             |
+| [useRouteError](references/api/use-route-error.md)                                         | Hook to access error details in custom error boundaries                                                                                   |
+| [useTheme](references/api/use-theme.md)                                                    | Hook for accessing and controlling theme (light/dark mode)                                                                                |
+| [useTimeZone](references/api/use-time-zone.md)                                             | Hook to access the configured IANA timezone from AppShell context                                                                         |
+| [useToast](references/api/use-toast.md)                                                    | Hook for displaying toast notifications                                                                                                   |
 
 ## Available Pages
 
@@ -134,6 +143,12 @@ A page is the shape of a whole screen — the outer choice, made before picking
 | [`form/single-page`](references/patterns/form-single-page.md) | Single Page Form | Routed full-page form for moderate field count (6-15) without natural sectioning                                         |
 | [`form/wizard`](references/patterns/form-wizard.md)           | Wizard Form      | Multi-stage create flow with 3-7 steps and per-step validation gates                                                     |
 
+### i18n
+
+| Slug                                                | Name        | Description                                                                                |
+| --------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
+| [`i18n/labels`](references/patterns/i18n-labels.md) | i18n Labels | Decide UI language before implementation and keep display labels separate from stable data |
+
 ### interaction
 
 | Slug                                                                          | Name         | Description                                                                             |
@@ -151,11 +166,12 @@ A page is the shape of a whole screen — the outer choice, made before picking
 ## How to Use
 
 1. Identify the user's intent (list, detail, form, interaction, screen composition, recipe)
-2. Building a whole screen? Match it to a **page** entry first and read that. A page fixes the screen's shape — its layout, what goes where, and in what order — before any of the parts inside it are chosen.
-3. Match each part you are building to a **pattern** entry slug from the tables above. A one-off recipe rather than a screen skips straight to this step.
-4. Read the entry's detailed spec: `references/<category>/<slug>.md` (relative to this file)
-5. Read the concept references for styling, design tokens, GraphQL, and custom components: `references/concepts/`; component and hook APIs live in `references/components/` and `references/api/`
-6. Implement using ONLY the imports listed in the entry's `requiredImports` — for a page, the `requiredImports` of the pattern it sent you to
+2. Before implementing screen text, read [`i18n/labels`](references/patterns/i18n-labels.md) and establish the app's UI language independently of the specification's language. Use feature label catalogs by default, unless the project explicitly opts out for a single-language app. The API reference is [`defineI18nLabels`](references/api/define-i18n-labels.md).
+3. Building a whole screen? Match it to a **page** entry first and read that. A page fixes the screen's shape — its layout, what goes where, and in what order — before any of the parts inside it are chosen.
+4. Match each part you are building to a **pattern** entry slug from the tables above. A one-off recipe rather than a screen skips straight to this step.
+5. Read the entry's detailed spec: `references/<category>/<slug>.md` (relative to this file)
+6. Read the concept references for styling, design tokens, GraphQL, and custom components: `references/concepts/`; component and hook APIs live in `references/components/` and `references/api/`
+7. Implement using ONLY the imports listed in the selected entries' `requiredImports` — for a page, use those of its patterns; for localization, include the `i18n/labels` entry
 
 ## Rules
 
@@ -171,9 +187,12 @@ Full rationale in [`styling-theming`](references/concepts/styling-theming.md)
 
 - **One primary action per view:** at most one primary/filled `Button`; everything else is `outline`/`secondary`/`ghost`.
 - **Status badges by semantic color:** a **filled** semantic variant for the record's primary/lifecycle status, **`outline-*`** for secondary statuses, **`subtle-*`** for tags; reserve brand `default` for non-status emphasis.
+- **Text uses `Text` and typography roles:** render headings, body copy, labels, and captions with [`Text`](references/components/text.md) and a `variant` (`heading-md`, `body-md`, `body-sm`, `label-md`, …) — never a bare `<p>`, `<h*>`, or `<span>` styled with size and weight utilities such as `text-lg font-semibold` or `text-sm`. Set the heading level with `Text.h1` to `Text.h6` (`<Text.h3 variant="heading-md">`), not by its size, and the color with a token in `className`. For other plain elements use `Text.p`, `Text.span` or `Text.div`; use `render` only to compose with another component. On an element you style yourself, such as a `th`, use the role utility (`text-label-md`). Pick the size with `variant`: a size class such as `text-sm` on `Text` has no effect. `Layout.Header` already renders the page title, and a form field label is [`Field.Label`](references/components/form.md), which already has the label role. Role table and color pairings: [`styling-theming`](references/concepts/styling-theming.md) → Typography.
+- **Status and feedback color by semantic role:** use a component variant first (`Badge`, `Alert`, `Button variant="destructive"`). On your own element, use the roles `{info|success|warning|danger|neutral}-{surface|border|solid|text|contrast|indicator}`, for example `bg-warning-surface text-warning-text border-warning-border`. Error text is `text-danger-text`. Never write the deprecated `--status-*`, `--alert-*` or `--destructive` tokens or their utilities (`bg-status-*`, `text-alert-*`, `bg-destructive`, `text-destructive`) in new code; the next major removes them. When you edit a screen that still uses them, replace them: `text-destructive` → `text-danger-text`, `bg-status-completed` → `bg-success-solid`, `bg-alert-warning-background` → `bg-warning-surface`. Full mapping: [`styling-theming`](references/concepts/styling-theming.md) → Semantic color roles.
 - **No duplicate actions:** an action lives in exactly one place — never repeat the same action in both `Layout.Header` and `ActionPanel`.
 - **Action placement:** primary CTA + status in `Layout.Header`; workflow actions in `ActionPanel`; back/navigation in the breadcrumb — never in `ActionPanel`.
 - **Metric tiles always go in a `Grid`** (`columns={{ initial: 1, md: 2, xl: 4 }}`) — never one-per-row.
 - **Forms default to `form/modal`** — only build a routed full-page form when the design explicitly calls for one.
 - **Forms use AppShell `Form` + `Field`**, submitting via `onFormSubmit` — never a bare `<form onSubmit>` with `FormData`. `onFormSubmit` reads registered `Field.Root`s, so every control (dropdowns included) just needs a wrapping `Field.Root name="…"` — no `name` on the control, no `useState`. React Hook Form is optional, consumer-installed, and only warranted for cross-field validation, field arrays, or a Zod resolver. Details in [`Form`](references/components/form.md) and the `form/*` patterns.
 - **Handle every state:** loading (skeleton), empty (labelled empty state), and error (inline + retry) — never ship only the happy path.
+- **Keep UI language consistent:** apply the chosen language to navigation, component text, accessibility labels, and feedback. Use the catalog's `useT()` for rendered strings and `labels.t()` for `LocalizedString` metadata; keep server codes and comparison values untranslated. See [`i18n/labels`](references/patterns/i18n-labels.md).

package/skills/app-shell-patterns/references/api/aggregations.md

@@ -0,0 +1,131 @@
+---
+title: Value aggregations
+description: Reusable selector-based sum, average, minimum, maximum, and non-null count over row collections, with optional result-only transformation
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/aggregations.docs.outline.md — do not edit by hand. -->
+
+# Value aggregations
+
+`aggregations` creates reusable callbacks that select values from a row collection and aggregate them. Each callback accepts `{ rows: readonly TRow[] }`; the module has no dependency on React, DataTable, or column definitions.
+
+```tsx
+import { aggregations, type Aggregation } from "@tailor-platform/app-shell";
+
+type Line = { quantity: number | null };
+
+const sum = aggregations.sum((row: Line) => row.quantity);
+sum({ rows: [{ quantity: 1 }, { quantity: 2 }, { quantity: null }] }); // 3
+sum({ rows: [{ quantity: 4 }, { quantity: 5 }] }); // 9: no previous aggregate state
+
+const summary: Aggregation<Line, string> = aggregations.sum(
+  (row: Line) => row.quantity,
+  (value) => (value === null ? "Unavailable" : `${value} units`),
+);
+summary({ rows: [{ quantity: 1 }, { quantity: 2 }] }); // "3 units"
+```
+
+## Operations
+
+| Factory                        | Result                                  | Empty or all-nullish selected values |
+| ------------------------------ | --------------------------------------- | ------------------------------------ |
+| `aggregations.sum(selector)`   | Sum of finite numbers                   | `0`                                  |
+| `aggregations.avg(selector)`   | Average of finite numbers               | `null`                               |
+| `aggregations.min(selector)`   | Minimum finite number                   | `null`                               |
+| `aggregations.max(selector)`   | Maximum finite number                   | `null`                               |
+| `aggregations.count(selector)` | Count of non-nullish values of any type | `0`                                  |
+
+A selector is required. It receives one row at a time and determines the values to aggregate. Numeric selectors must return `number | null | undefined`; count selectors may return any type. There is no automatic field lookup or connection to a column's `id`, `accessor`, or rendered content.
+
+Each factory returns an `Aggregation<TRow, TResult>` callback. Pass a read-only or mutable row array through `{ rows }`; aggregation does not mutate it or retain state between invocations. Selectors and transformers must be pure and must not mutate rows. Exceptions from either callback propagate to the caller.
+
+All operations skip selected `null` and `undefined` values. Numeric operations also validate selected values at runtime and return `null` for the entire result if any other value is not a finite JavaScript number, including numeric strings, booleans, dates, `NaN`, and infinities. They do not coerce values, compare dates or strings, or return a partial result. Average divides by the number of non-nullish numeric values, not the row count.
+
+Calculations use ordinary JavaScript numbers. A non-finite calculated result returns `null`; for average, this includes an intermediate sum overflow even when the mathematical average could be finite. These functions do not provide arbitrary-precision arithmetic.
+
+`count(selector)` counts selected `0`, `false`, and `""` as present values. It counts non-nullish values, not truthy values; use `rows.length` when every row should count.
+
+## Optional transformer
+
+Pass a second function to transform the final result:
+
+```tsx
+const averageText = aggregations.avg(
+  (row: Line) => row.quantity,
+  (value) => value?.toFixed(2) ?? "–",
+);
+averageText({ rows: [{ quantity: 1 }, { quantity: null }, { quantity: 2 }] }); // "1.50"
+
+const detailed = aggregations.sum(
+  (row: Line) => row.quantity,
+  (total) => ({ total, valid: total !== null }),
+);
+detailed({ rows: [{ quantity: 1 }, { quantity: 2 }] }); // { total: 3, valid: true }
+```
+
+The transformer is called exactly once per aggregation invocation, including for empty or invalid input. Numeric transformers receive `number | null`; count transformers receive `number`. Its return type becomes the callback's result type, and may be text, JSX, an object, or another value. The aggregation library does not interpret the transformed result.
+
+A transformer receives only the result, not rows, selected values, columns, or UI context. Filter `rows` before invoking the callback when the calculation needs a different input set.
+
+For detached callbacks, annotate the selector's row parameter as above so the row and transformed result types can both be inferred. Row types are not restricted to objects; for example, `aggregations.sum<number>((value) => value)({ rows: [1, 2] })` returns `3`.
+
+## Composing with business validation
+
+An aggregation is an ordinary callback, so a wrapper can validate the supplied rows before calling it. Keep business rules in the wrapper, numeric calculation in the aggregation, and result formatting in the transformer. The transformer is not an error handler: it receives `null` for invalid numeric results but has no row context or business-error details; selector exceptions still propagate.
+
+For example, reject mixed currencies before adding monetary amounts:
+
+```tsx
+type MoneyLine = { amount: number | null; currency: string };
+
+const sumAmount = aggregations.sum(
+  (row: MoneyLine) => row.amount,
+  (total) => (total === null ? "Invalid amount" : total.toLocaleString("en-US")),
+);
+
+const moneyFooter = (ctx: { rows: readonly MoneyLine[] }) => {
+  const currencies = new Set(
+    ctx.rows.filter((row) => row.amount != null).map((row) => row.currency),
+  );
+  if (currencies.size > 1) {
+    return `Mixed currencies: ${[...currencies].join(", ")}`;
+  }
+  return sumAmount(ctx);
+};
+
+moneyFooter({
+  rows: [
+    { amount: 1000, currency: "JPY" },
+    { amount: 500, currency: "JPY" },
+  ],
+}); // "1,500"
+moneyFooter({
+  rows: [
+    { amount: 1000, currency: "JPY" },
+    { amount: 500, currency: "USD" },
+  ],
+}); // "Mixed currencies: JPY, USD"
+```
+
+The guard ignores nullish amounts because they do not contribute to the sum. A rejected currency combination returns directly without evaluating the selector or transformer. Neither the wrapper nor the helper converts currencies or provides arbitrary-precision arithmetic.
+
+Pass `moneyFooter` directly as a column's `footer`. See the [runnable DataTable example](../components/data-table.md#composing-with-business-validation) to toggle mixed currencies and observe the composed behavior.
+
+## DataTable integration
+
+Pass an aggregation callback directly to a column footer. It is an ordinary footer renderer that reads the current `ctx.rows`; DataTable needs no aggregation-specific handling:
+
+```tsx
+import { aggregations, createColumnHelper } from "@tailor-platform/app-shell";
+
+const { column } = createColumnHelper<{ quantity: number | null }>();
+column({
+  id: "quantity",
+  type: "number",
+  footer: aggregations.sum((row) => row.quantity),
+});
+```
+
+Inline selectors infer the row type from the surrounding footer definition. The selector is the source of truth even when the column has an `accessor`; write the same calculation in the selector if the footer should aggregate a computed cell value.
+
+Use a transformer for simple footer text or JSX. DataTable only accepts callback results it can render; object-producing aggregations remain available for non-UI use. For the current-page scope, loading behavior, and custom renderers, see [DataTable column footers](../components/data-table.md#column-footers).

package/skills/app-shell-patterns/references/api/define-i18n-labels.md

@@ -1,143 +1,175 @@
 ---
 title: defineI18nLabels
-description: Define internationalized labels for multi-language support
+description: Type-safe locale-first labels for component text and localized navigation metadata
 ---
 
 <!-- GENERATED by docs-kit from docs-src/hooks/define-i18n-labels.docs.outline.md — do not edit by hand. -->
 
 # defineI18nLabels
 
-Creates internationalized labels that automatically resolve based on the current locale.
+Defines a label catalog and returns two resolvers: a React Hook for rendered text and a `LocalizedString` factory for AppShell configuration. No additional i18n package is required.
 
-## Signature
+## Define a Catalog
 
-```typescript
-function defineI18nLabels<T extends Record<string, Record<string, string>>>(
-  labels: T,
-): I18nLabels<T>;
-```
+Create the catalog once at module scope, not inside a component. The object is **locale-first**: `en` is the required base locale; each locale contains a flat map of label keys to strings or functions that return strings.
+
+```tsx
+// i18n-labels.ts
+import { defineI18nLabels } from "@tailor-platform/app-shell";
+
+export const labels = defineI18nLabels({
+  en: {
+    title: "Requests",
+    save: "Save",
+    greeting: ({ name }: { name: string }) => `Hello, ${name}!`,
+    itemCount: ({ count }: { count: number }) => (count === 1 ? "1 item" : `${count} items`),
+    "status.PENDING": "Pending",
+    unknownStatus: "Unknown status",
+  },
+  ja: {
+    title: "申請一覧",
+    save: "保存",
+    greeting: ({ name }: { name: string }) => `こんにちは、${name}さん！`,
+    itemCount: ({ count }: { count: number }) => `${count}件`,
+    "status.PENDING": "承認待ち",
+    unknownStatus: "不明な状態",
+  },
+});
 
-## Parameters
+export const useT = labels.useT;
+```
 
-### `labels`
+`useT` above is exported by **your catalog module**, not directly by `@tailor-platform/app-shell`. The component examples below use this shared setup; import `labels` and `useT` from `./i18n-labels` in application files.
 
-- **Type:** `Record<string, Record<string, string>>`
-- **Required:** Yes
-- **Description:** Object mapping label keys to locale-specific strings
+Label keys are flat strings, not nested objects. A dotted key such as `"status.PENDING"` is an ordinary flat string key.
 
 ## Return Value
 
-```typescript
-{
-  t: (key: keyof T) => LocalizedString;
+| Member                     | Returns                                | Use for                                                                                  |
+| -------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `labels.useT()`            | A resolver `t` that returns a `string` | Text rendered by a React component, string-valued props, toasts, and validation messages |
+| `t(key, props?)`           | `string`                               | A known label key, with required props for function-valued labels                        |
+| `t.dynamic(key, fallback)` | `string`                               | A runtime string key for a **static** label                                              |
+| `labels.t(key, props?)`    | `LocalizedString`                      | `meta.title`, `meta.breadcrumbTitle`, and props explicitly accepting `LocalizedString`   |
+
+`LocalizedString` is `string | ((locale: string) => string)`. `labels.t()` creates a locale callback, **not rendered text**. Do not put its result directly into JSX children or pass it to a prop that accepts only `string`.
+
+## In Components: `useT()`
+
+Call the Hook at the top level of a component under `AppShell`. The returned resolver reads the current AppShell locale.
+
+<example-preview name="in-components"></example-preview>
+
+```tsx
+function InComponents() {
+  const t = useT();
+
+  return <Button>{t("save")}</Button>;
 }
 ```
 
-## Usage
+Use the same resolver for string props such as `placeholder`, `aria-label`, or `Layout.Header`'s `title`, and inside event handlers for localized notifications. Do not call a Hook in an event handler; capture `t` during render.
 
-### Basic Labels
+## Function-valued Labels: Typed Props
 
-```typescript
-import { defineI18nLabels } from "@tailor-platform/app-shell";
+Use a function for a whole sentence containing runtime values. Its props are inferred from the English definition and checked for the other declared locales. Keep pluralization and word order inside each locale's function rather than concatenating translated fragments.
 
-const labels = defineI18nLabels({
-  dashboard: {
-    en: "Dashboard",
-    ja: "ダッシュボード",
-  },
-  products: {
-    en: "Products",
-    ja: "商品",
-  },
-  settings: {
-    en: "Settings",
-    ja: "設定",
-  },
-});
+<example-preview name="dynamic-labels"></example-preview>
 
-// Use in modules
-const dashboardModule = defineModule({
-  path: "dashboard",
-  meta: {
-    title: labels.t("dashboard"),
-  },
-  component: DashboardPage,
-});
+```tsx
+function DynamicLabels() {
+  const t = useT();
+
+  return (
+    <Layout>
+      <Layout.Header title={t("greeting", { name: "Alex" })} />
+      <Layout.Column>{t("itemCount", { count: 3 })}</Layout.Column>
+    </Layout>
+  );
+}
 ```
 
-### Multiple Locales
+Both `t("greeting", { name })` and `labels.t("greeting", { name })` require the correct props. When using `labels.t()` for metadata, props are bound **when `labels.t()` is called**, not fetched at render time. For a breadcrumb depending on a URL segment, see [Routing & Navigation](../concepts/routing-navigation.md#dynamic-breadcrumb-titles).
 
-```typescript
-const labels = defineI18nLabels({
-  welcome: {
-    en: "Welcome",
-    ja: "ようこそ",
-    es: "Bienvenido",
-    fr: "Bienvenue",
-  },
-});
-```
+## Runtime Keys: `t.dynamic()`
 
-### In Components
+`t.dynamic(key: string, fallback: string)` accepts a key constructed at runtime, for example from a server enum. Keep the enum stable and translate only its display label.
 
-```typescript
-function WelcomeMessage() {
-  const labels = defineI18nLabels({
-    greeting: {
-      en: "Hello",
-      ja: "こんにちは",
-    },
-  });
+<example-preview name="runtime-keys"></example-preview>
 
-  return <h1>{labels.t("greeting")}</h1>;
+```tsx
+function RuntimeKeys() {
+  const t = useT();
+  const status: string = "PENDING";
+
+  return <Badge variant="warning">{t.dynamic(`status.${status}`, t("unknownStatus"))}</Badge>;
 }
 ```
 
-### With SidebarGroup
+Resolution order:
+
+1. Look up the key in the current locale.
+2. If absent, look it up in `en`.
+3. If the resolved value is missing **or is a function**, return the supplied fallback unchanged.
 
-```typescript
-import { SidebarGroup } from "@tailor-platform/app-shell";
+The fallback is not translated automatically. Prefer another translated label, as above, instead of an English literal. `t.dynamic()` does not accept label props; use typed `t(key, props)` for function-valued labels. Prefer typed `t(key)` whenever the key is known at compile time.
 
-const labels = defineI18nLabels({
-  admin: {
-    en: "Administration",
-    ja: "管理",
+## Navigation Metadata: `labels.t()`
+
+Module and resource definitions are usually outside React components, so they cannot call Hooks. Pass the locale callback to AppShell, which resolves it using the active locale:
+
+```tsx
+import { defineModule } from "@tailor-platform/app-shell";
+import { labels } from "./i18n-labels";
+
+const requestModule = defineModule({
+  path: "requests",
+  meta: {
+    title: labels.t("title"),
+    breadcrumbTitle: labels.t("title"),
   },
+  component: InComponents,
+  resources: [],
 });
-
-<SidebarGroup title={labels.t("admin")}>
-  <SidebarItem to="/admin/users" />
-</SidebarGroup>
 ```
 
-## Setting Locale
+The same approach works for `defineResource().meta` and `SidebarGroup`, `SidebarSection`, and `SidebarItem` title overrides. For ordinary string-valued component props, use the Hook resolver instead.
 
-The active locale is controlled by the `locale` prop on `AppShell`:
+## Setting Locale and Fallbacks
 
-```typescript
-<AppShell locale="ja" modules={modules}>
+Choose the app's UI language explicitly when it is fixed:
+
+```tsx
+<AppShell locale="ja-JP" modules={[requestModule]}>
   <SidebarLayout />
 </AppShell>
 ```
 
-Supported locales: `en`, `ja`
+- AppShell normalizes a BCP-47 tag such as `ja-JP` to `ja` for label lookup. Use language keys such as `ja` in the catalog, not `ja-JP`.
+- If `locale` is omitted, AppShell uses the browser's preferred language. If browser locale information is unavailable or invalid, it uses `en`.
+- If a catalog has no definition for the selected language, labels fall back to `en`. A missing localized key also falls back to its English value at runtime.
+- Custom catalogs can define other languages such as `fr`; this does **not** translate AppShell's built-in UI. Its shared built-in catalog currently supplies English and Japanese, with English fallback for other languages.
+- For regional date and number formatting, use the full tag from [useResolvedLocale](./use-resolved-locale.md); label translation does not format dates, numbers, or time zones automatically.
 
-If not specified, auto-detects from browser settings.
+## TypeScript Contract
 
-## TypeScript
+With an ordinary inferred definition such as the catalog above:
 
-Full type safety:
+- `en` is required, even for an app whose selected UI language is Japanese.
+- Other explicitly declared locales must supply all base keys and compatible function props. Translation omissions become compile errors.
+- `t()` and `labels.t()` reject unknown keys, missing or wrongly typed function props, and props passed to static labels.
+- `t.dynamic()` deliberately accepts any string key; unknown keys are handled by its required fallback instead of compile-time validation.
 
-```typescript
-const labels = defineI18nLabels({
-  dashboard: { en: "Dashboard", ja: "ダッシュボード" },
-  products: { en: "Products", ja: "商品" },
-});
+These checks validate structure and call sites, not translation quality or language consistency.
 
-labels.t("dashboard"); // ✅ Valid
-labels.t("invalid"); // ❌ Type error
-```
+## Exports
+
+- `I18nLabels` — type
+- `defineI18nLabels` — const
 
 ## Related
 
-- [defineModule](./define-module.md) - Use labels in modules
+- [i18n Labels Pattern](../patterns/i18n-labels.md) — UI language decisions, key naming, file splitting, and server-originated text
+- [defineModule](./define-module.md) — localized navigation metadata
+- [defineResource](./define-resource.md) — localized resource metadata
+- [useResolvedLocale](./use-resolved-locale.md) — full locale for formatting

package/skills/app-shell-patterns/references/api/define-module.md

@@ -209,10 +209,8 @@ const productsModule = defineModule({
 import { defineI18nLabels } from "@tailor-platform/app-shell";
 
 const labels = defineI18nLabels({
-  dashboard: {
-    en: "Dashboard",
-    ja: "ダッシュボード",
-  },
+  en: { dashboard: "Dashboard" },
+  ja: { dashboard: "ダッシュボード" },
 });
 
 const dashboardModule = defineModule({