@tailor-platform/app-shell 1.17.0 → 1.18.0

package/dist/vite-plugin.d.ts

@@ -56,37 +56,17 @@ declare namespace Root {
 }
 
 
-declare namespace Header {
-    var displayName: string;
-}
-
-
-declare namespace Body {
-    var displayName: string;
-}
-
-
-declare namespace Footer {
-    var displayName: string;
-}
-
-
-declare namespace Row {
-    var displayName: string;
-}
-
-
-declare namespace Head {
+declare namespace Title {
     var displayName: string;
 }
 
 
-declare namespace Cell {
+declare namespace Description {
     var displayName: string;
 }
 
 
-declare namespace Caption {
+declare namespace Provider {
     var displayName: string;
 }
 
@@ -101,12 +81,12 @@ declare namespace Header {
 }
 
 
-declare namespace Content {
+declare namespace ClearAll {
     var displayName: string;
 }
 
 
-declare namespace Root {
+declare namespace Sections {
     var displayName: string;
 }
 
@@ -116,12 +96,12 @@ declare namespace Trigger {
 }
 
 
-declare namespace Close {
+declare namespace Settings {
     var displayName: string;
 }
 
 
-declare namespace Content {
+declare namespace Root {
     var displayName: string;
 }
 
@@ -131,17 +111,7 @@ declare namespace Header {
 }
 
 
-declare namespace Footer {
-    var displayName: string;
-}
-
-
-declare namespace Title {
-    var displayName: string;
-}
-
-
-declare namespace Description {
+declare namespace Content {
     var displayName: string;
 }
 
@@ -151,122 +121,117 @@ declare namespace Root {
 }
 
 
-declare namespace Legend {
-    var displayName: string;
-}
-
-
-declare namespace ComboboxRoot {
+declare namespace Header {
     var displayName: string;
 }
 
 
-declare namespace ComboboxInput {
+declare namespace Body {
     var displayName: string;
 }
 
 
-declare namespace ComboboxTrigger {
+declare namespace Footer {
     var displayName: string;
 }
 
 
-declare namespace ComboboxInputGroup {
+declare namespace Row {
     var displayName: string;
 }
 
 
-declare namespace ComboboxContent {
+declare namespace Head {
     var displayName: string;
 }
 
 
-declare namespace ComboboxList {
+declare namespace Cell {
     var displayName: string;
 }
 
 
-declare namespace ComboboxItem {
+declare namespace Caption {
     var displayName: string;
 }
 
 
-declare namespace ComboboxEmpty {
+declare namespace Root {
     var displayName: string;
 }
 
 
-declare namespace ComboboxGroup {
+declare namespace Trigger {
     var displayName: string;
 }
 
 
-declare namespace ComboboxGroupLabel {
+declare namespace Close {
     var displayName: string;
 }
 
 
-declare namespace ComboboxClear {
+declare namespace Content {
     var displayName: string;
 }
 
 
-declare namespace ComboboxChips {
+declare namespace Header {
     var displayName: string;
 }
 
 
-declare namespace ComboboxChip {
+declare namespace Footer {
     var displayName: string;
 }
 
 
-declare namespace ComboboxChipRemove {
+declare namespace Title {
     var displayName: string;
 }
 
 
-declare namespace ComboboxValue {
+declare namespace Description {
     var displayName: string;
 }
 
 
-declare namespace ComboboxStatus {
+declare namespace Root {
     var displayName: string;
 }
 
 
-declare namespace ComboboxCollection {
+declare namespace Label {
     var displayName: string;
 }
 
 
-declare namespace Root {
+declare namespace Control {
     var displayName: string;
 }
 
 
-declare namespace Label {
+declare namespace Description {
     var displayName: string;
 }
 
 
-declare namespace Control {
+declare namespace Error {
     var displayName: string;
 }
 
 
-declare namespace Description {
+declare namespace Validity {
     var displayName: string;
 }
 
 
-declare namespace Error {
+declare namespace Root {
     var displayName: string;
 }
 
 
-declare namespace Validity {
+declare namespace Legend {
     var displayName: string;
 }
 
@@ -351,57 +316,57 @@ declare namespace Root {
 }
 
 
-declare namespace Row {
+declare namespace Trigger {
     var displayName: string;
 }
 
 
-declare namespace Group {
+declare namespace Close {
     var displayName: string;
 }
 
 
-declare namespace Separator {
+declare namespace Content {
     var displayName: string;
 }
 
 
-declare namespace Root {
+declare namespace Header {
     var displayName: string;
 }
 
 
-declare namespace Trigger {
+declare namespace Footer {
     var displayName: string;
 }
 
 
-declare namespace Close {
+declare namespace Title {
     var displayName: string;
 }
 
 
-declare namespace Content {
+declare namespace Description {
     var displayName: string;
 }
 
 
-declare namespace Header {
+declare namespace Root {
     var displayName: string;
 }
 
 
-declare namespace Footer {
+declare namespace List {
     var displayName: string;
 }
 
 
-declare namespace Title {
+declare namespace Tab {
     var displayName: string;
 }
 
 
-declare namespace Description {
+declare namespace Panel {
     var displayName: string;
 }
 
@@ -411,42 +376,57 @@ declare namespace Root {
 }
 
 
-declare namespace List {
+declare namespace Row {
     var displayName: string;
 }
 
 
-declare namespace Tab {
+declare namespace Group {
     var displayName: string;
 }
 
 
-declare namespace Panel {
+declare namespace Separator {
     var displayName: string;
 }
 
 
-declare namespace Root {
+declare namespace SelectRoot {
     var displayName: string;
 }
 
 
-declare namespace Title {
+declare namespace SelectTrigger {
     var displayName: string;
 }
 
 
-declare namespace Description {
+declare namespace SelectValue {
     var displayName: string;
 }
 
 
-declare namespace Trigger {
+declare namespace SelectContent {
     var displayName: string;
 }
 
 
-declare namespace Settings {
+declare namespace SelectItem {
+    var displayName: string;
+}
+
+
+declare namespace SelectGroup {
+    var displayName: string;
+}
+
+
+declare namespace SelectGroupLabel {
+    var displayName: string;
+}
+
+
+declare namespace SelectSeparator {
     var displayName: string;
 }
 
@@ -461,87 +441,97 @@ declare namespace Root {
 }
 
 
-declare namespace Header {
+declare namespace Trigger {
     var displayName: string;
 }
 
 
-declare namespace ClearAll {
+declare namespace Content {
     var displayName: string;
 }
 
 
-declare namespace Sections {
+declare namespace ComboboxRoot {
     var displayName: string;
 }
 
 
-declare namespace Provider {
+declare namespace ComboboxInput {
     var displayName: string;
 }
 
 
-declare namespace Root {
+declare namespace ComboboxTrigger {
     var displayName: string;
 }
 
 
-declare namespace Trigger {
+declare namespace ComboboxInputGroup {
     var displayName: string;
 }
 
 
-declare namespace Content {
+declare namespace ComboboxContent {
     var displayName: string;
 }
 
 
-declare namespace SelectRoot {
+declare namespace ComboboxList {
     var displayName: string;
 }
 
 
-declare namespace SelectTrigger {
+declare namespace ComboboxItem {
     var displayName: string;
 }
 
 
-declare namespace SelectValue {
+declare namespace ComboboxEmpty {
     var displayName: string;
 }
 
 
-declare namespace SelectContent {
+declare namespace ComboboxGroup {
     var displayName: string;
 }
 
 
-declare namespace SelectItem {
+declare namespace ComboboxGroupLabel {
     var displayName: string;
 }
 
 
-declare namespace SelectGroup {
+declare namespace ComboboxClear {
     var displayName: string;
 }
 
 
-declare namespace SelectGroupLabel {
+declare namespace ComboboxChips {
     var displayName: string;
 }
 
 
-declare namespace SelectSeparator {
+declare namespace ComboboxChip {
     var displayName: string;
 }
 
 
-declare namespace AutocompleteStandalone {
+declare namespace ComboboxChipRemove {
     var displayName: string;
 }
 
 
-declare namespace AutocompleteAsyncStandalone {
+declare namespace ComboboxValue {
+    var displayName: string;
+}
+
+
+declare namespace ComboboxStatus {
+    var displayName: string;
+}
+
+
+declare namespace ComboboxCollection {
     var displayName: string;
 }
 
@@ -616,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.17.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

@@ -76,6 +76,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 +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
 
@@ -134,6 +135,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 +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
 
@@ -177,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).