@tailor-platform/app-shell 1.16.0 → 1.18.0

package/dist/vite-plugin.d.ts

@@ -41,12 +41,12 @@ declare namespace Root {
 }
 
 
-declare namespace Title {
+declare namespace Image {
     var displayName: string;
 }
 
 
-declare namespace Description {
+declare namespace Fallback {
     var displayName: string;
 }
 
@@ -56,17 +56,17 @@ declare namespace Root {
 }
 
 
-declare namespace List {
+declare namespace Title {
     var displayName: string;
 }
 
 
-declare namespace Tab {
+declare namespace Description {
     var displayName: string;
 }
 
 
-declare namespace Panel {
+declare namespace Provider {
     var displayName: string;
 }
 
@@ -76,12 +76,27 @@ declare namespace Root {
 }
 
 
-declare namespace Image {
+declare namespace Header {
     var displayName: string;
 }
 
 
-declare namespace Fallback {
+declare namespace ClearAll {
+    var displayName: string;
+}
+
+
+declare namespace Sections {
+    var displayName: string;
+}
+
+
+declare namespace Trigger {
+    var displayName: string;
+}
+
+
+declare namespace Settings {
     var displayName: string;
 }
 
@@ -96,47 +111,47 @@ declare namespace Header {
 }
 
 
-declare namespace Body {
+declare namespace Content {
     var displayName: string;
 }
 
 
-declare namespace Footer {
+declare namespace Root {
     var displayName: string;
 }
 
 
-declare namespace Row {
+declare namespace Header {
     var displayName: string;
 }
 
 
-declare namespace Head {
+declare namespace Body {
     var displayName: string;
 }
 
 
-declare namespace Cell {
+declare namespace Footer {
     var displayName: string;
 }
 
 
-declare namespace Caption {
+declare namespace Row {
     var displayName: string;
 }
 
 
-declare namespace Root {
+declare namespace Head {
     var displayName: string;
 }
 
 
-declare namespace Header {
+declare namespace Cell {
     var displayName: string;
 }
 
 
-declare namespace Content {
+declare namespace Caption {
     var displayName: string;
 }
 
@@ -341,6 +356,26 @@ declare namespace Root {
 }
 
 
+declare namespace List {
+    var displayName: string;
+}
+
+
+declare namespace Tab {
+    var displayName: string;
+}
+
+
+declare namespace Panel {
+    var displayName: string;
+}
+
+
+declare namespace Root {
+    var displayName: string;
+}
+
+
 declare namespace Row {
     var displayName: string;
 }
@@ -501,16 +536,6 @@ declare namespace ComboboxCollection {
 }
 
 
-declare namespace AutocompleteStandalone {
-    var displayName: string;
-}
-
-
-declare namespace AutocompleteAsyncStandalone {
-    var displayName: string;
-}
-
-
 declare namespace AutocompleteRoot {
     var displayName: string;
 }
@@ -581,6 +606,16 @@ declare namespace AutocompleteStatus {
 }
 
 
+declare namespace AutocompleteStandalone {
+    var displayName: string;
+}
+
+
+declare namespace AutocompleteAsyncStandalone {
+    var displayName: string;
+}
+
+
 declare namespace DataTableRoot {
     var displayName: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -77,7 +77,7 @@
     "@vitejs/plugin-react": "^6.1.0",
     "@vitest/coverage-v8": "4.1.11",
     "happy-dom": "20.14.5",
-    "postcss": "8.5.28",
+    "postcss": "8.5.30",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-hook-form": "7.71.2",

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

@@ -59,6 +59,7 @@ Every AppShell component, its API surface, and usage guidance. Read the entry fo
 | [DescriptionCard](references/components/description-card.md)            | Display structured key-value information in a responsive grid layout with automatic field rendering                                                |
 | [Dialog](references/components/dialog.md)                               | Modal dialog with a compound component API                                                                                                         |
 | [DocumentProgressCard](references/components/document-progress-card.md) | Generic card visualising a document's lifecycle state — optional percentage, stacked progress bar, and status legend                               |
+| [FilterRail](references/components/filter-rail.md)                      | An always-visible faceted filter rail with user layout settings, driven by the same CollectionControl as DataTable                                 |
 | [Form, Field, and Fieldset](references/components/form.md)              | Components for building validated forms with automatic accessibility wiring, validation state management, and optional React Hook Form integration |
 | [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                                 |
@@ -71,9 +72,11 @@ Every AppShell component, its API surface, and usage guidance. Read the entry fo
 | [SidebarGroup](references/components/sidebar-group.md)                  | Collapsible group component for organizing sidebar navigation items with icons and nested structure                                                |
 | [SidebarItem](references/components/sidebar-item.md)                    | Individual navigation item for customizing sidebar with icons, active states, and external links                                                   |
 | [SidebarLayout](references/components/sidebar-layout.md)                | Default AppShell layout with a built-in sidebar, content header, optional app-wide top bar, and an escape-hatch body slot                          |
+| [SidebarSection](references/components/sidebar-section.md)              | Static, non-collapsible heading for grouping flat sidebar navigation items                                                                         |
 | [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                                                             |
@@ -84,33 +87,33 @@ 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                                                                        |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| [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
 
@@ -132,13 +135,19 @@ 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                                                           |
-| ----------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------- |
-| [`interaction/confirm`](references/patterns/interaction-confirm.md)           | Confirm      | Confirmation dialog before destructive or irreversible actions        |
-| [`interaction/multi-select`](references/patterns/interaction-multi-select.md) | Multi Select | Floating bottom action bar for bulk operations on selected list rows  |
-| [`interaction/toast`](references/patterns/interaction-toast.md)               | Toast        | Lightweight feedback after mutations — success or error notifications |
+| Slug                                                                          | Name         | Description                                                                             |
+| ----------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------- |
+| [`interaction/confirm`](references/patterns/interaction-confirm.md)           | Confirm      | Confirmation dialog before destructive or irreversible actions                          |
+| [`interaction/multi-select`](references/patterns/interaction-multi-select.md) | Multi Select | Bulk operations on selected DataTable rows, from a bar that takes over the table footer |
+| [`interaction/toast`](references/patterns/interaction-toast.md)               | Toast        | Lightweight feedback after mutations — success or error notifications                   |
 
 ### list
 
@@ -149,11 +158,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
 
@@ -175,3 +185,4 @@ Full rationale in [`styling-theming`](references/concepts/styling-theming.md)
 - **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/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

@@ -70,8 +70,8 @@ defineModule({
 
 **meta.breadcrumbTitle**
 
-- **Type:** `string | ((segment: string) => string)`
-- **Description:** Custom breadcrumb segment title override
+- **Type:** `string | ((segment: string) => LocalizedString)`
+- **Description:** Custom breadcrumb segment title override. Pass `labels.t(key)` directly for localization: `breadcrumbTitle: labels.t("dashboard")`. Other callbacks receive the URL segment and may return a `LocalizedString`, resolved using the current locale. The existing `() => labels.t(key)` form remains supported; handwritten locale functions must be returned from an outer callback. When omitted, the breadcrumb uses the localized `meta.title`.
 
 ### `guards`
 
@@ -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({

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

@@ -65,8 +65,8 @@ defineResource({
 
 **meta.breadcrumbTitle**
 
-- **Type:** `string | ((segment: string) => string)`
-- **Description:** Custom breadcrumb segment title
+- **Type:** `string | ((segment: string) => LocalizedString)`
+- **Description:** Custom breadcrumb segment title. Pass `labels.t(key)` directly for localization: `breadcrumbTitle: labels.t("orders")`. Other callbacks receive the URL segment and may return a `LocalizedString`, for example `breadcrumbTitle: (segment) => labels.t("order", { id: segment })` for a dynamic label. AppShell resolves it using the current locale. The existing `() => labels.t(key)` form remains supported; handwritten locale functions must be returned from an outer callback. When omitted, the breadcrumb uses the localized `meta.title`.
 
 ### `subResources`