@tailor-platform/app-shell 1.11.0 → 1.13.0

package/dist/vite-plugin.js

@@ -1,4 +1,2 @@
-import { appShellRoutes as p } from "@tailor-platform/app-shell-vite-plugin";
-export {
-  p as appShellRoutes
-};
+import { appShellRoutes as e } from "@tailor-platform/app-shell-vite-plugin";
+export { e as appShellRoutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -37,16 +37,20 @@
     "./vite-plugin": {
       "types": "./dist/vite-plugin.d.ts",
       "default": "./dist/vite-plugin.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@base-ui/react": "^1.6.0",
+    "@base-ui/react": "1.6.0",
     "@internationalized/date": "3.12.2",
     "@standard-schema/spec": "^1.1.0",
-    "@tailor-platform/auth-public-client": "^0.5.1",
+    "@tailor-platform/auth-public-client": "^0.6.1",
     "change-case": "^5.4.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -60,27 +64,29 @@
     "@tailor-platform/app-shell-vite-plugin": "0.2.3"
   },
   "devDependencies": {
-    "@tailwindcss/postcss": "^4.3.0",
-    "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.3",
-    "@types/encoding-japanese": "^2.2.1",
+    "@fontsource-variable/noto-sans-jp": "5.3.0",
+    "@microsoft/api-extractor": "7.58.12",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.6",
+    "@types/encoding-japanese": "2.2.1",
     "@types/node": "^25.9.5",
-    "@types/papaparse": "^5.5.2",
+    "@types/papaparse": "5.5.2",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@vitejs/plugin-react": "^5.2.0",
-    "happy-dom": "^20.9.0",
-    "postcss": "^8.5.26",
+    "@vitejs/plugin-react": "^6.1.0",
+    "@vitest/coverage-v8": "4.1.10",
+    "happy-dom": "20.9.0",
+    "postcss": "8.5.26",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "tailwindcss": "^4.2.4",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.2",
-    "vite-plugin-dts": "^4.5.0",
-    "vite-plugin-externalize-deps": "^0.10.0",
-    "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^4.1.6"
+    "react-hook-form": "7.71.2",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "1.4.0",
+    "typescript": "5.9.3",
+    "vite": "^8.2.2",
+    "vite-plugin-dts": "5.0.3",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "react": ">=19.2.7",
@@ -89,6 +95,8 @@
   "scripts": {
     "dev": "vite build --watch --mode development",
     "build": "vite build",
+    "check-dts": "node scripts/check-dts.mjs",
+    "vendor:fonts": "node scripts/sync-noto-fonts.mjs",
     "lint": "oxlint -c .oxlintrc.jsonc",
     "test": "vitest run",
     "type-check": "tsc --incremental"

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

@@ -1,6 +1,6 @@
 ---
 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 — or when choosing the right AppShell component, layout, or design token for a UI."
+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."
 ---
 
 # App-Shell Patterns
@@ -19,6 +19,12 @@ These are the foundational rules that underpin all patterns. All patterns build
 | [design-system.md](references/fundamental/design-system.md) | design-system reference |
 | [graphql.md](references/fundamental/graphql.md)             | graphql reference       |
 
+## Migrations
+
+[`migrations.md`](references/migrations.md) lists every change that requires editing the consuming app, newest first — what breaks, how to detect it, and what to change.
+
+Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, theming, or dark mode looks wrong after a version bump. These breakages are silent: the build succeeds and nothing warns, so the cause is not discoverable from the error output. The package ships no CHANGELOG, so this file is the only migration record available locally.
+
 ## Available Patterns
 
 ### detail
@@ -29,12 +35,13 @@ These are the foundational rules that underpin all patterns. All patterns build
 
 ### form
 
-| Slug                                                          | Name             | Description                                                                       |
-| ------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
-| [`form/modal`](references/patterns/form-modal.md)             | Modal Form       | Default form pattern for Create/Edit — keeps user in context on the parent screen |
-| [`form/sectioned`](references/patterns/form-sectioned.md)     | Sectioned Form   | Complex form with 15+ fields organized into named fieldset sections               |
-| [`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              |
+| Slug                                                          | Name             | Description                                                                                                              |
+| ------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| [`form/composer`](references/patterns/form-composer.md)       | Composer         | Free-text composer — a multi-line input above a trailing action row, for notes, replies, and comments submitted in place |
+| [`form/modal`](references/patterns/form-modal.md)             | Modal Form       | Default form pattern for Create/Edit — keeps user in context on the parent screen                                        |
+| [`form/sectioned`](references/patterns/form-sectioned.md)     | Sectioned Form   | Complex form with 15+ fields organized into named fieldset sections                                                      |
+| [`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                                                     |
 
 ### interaction
 

package/skills/app-shell-patterns/references/fundamental/components.md

@@ -194,6 +194,13 @@ import { Button, Link } from '@tailor-platform/app-shell';
 **API:** `to`, `replace`, `state`, etc. — same as `react-router`.
 **Used in patterns:** all (navigation).
 
+### `NavLink`
+
+**Import:** `import { NavLink } from '@tailor-platform/app-shell'`
+**Purpose:** `Link` that knows when it is active — for nav menus and tab bars.
+**API:** `to`, plus `className` / `style` / `children` as render functions receiving `{ isActive, isPending }`.
+**Used in patterns:** navigation shells.
+
 ### `Dialog`
 
 > Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/dialog.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/dialog.md)
@@ -250,7 +257,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
 
 **Used in patterns:** `list/*` (filter sheet variant).
 
-**Notes:** Size the panel with **`contentClassName`** (often `astw:*` utilities). Rules → **`design-system.md`** §5.
+**Notes:** Size the panel with `Sheet.Content`'s **`size`** prop (`"sm" | "md" | "lg" | "xl" | "full"`, default `"sm"`) — not a width utility. `astw:` rules → **`design-system.md`** §5.
 
 ### `Menu`
 
@@ -378,7 +385,7 @@ Plus `badgeVariants` CVA for custom-styled siblings.
 
 **Notes:**
 
-- **Inside a card?** Pass `containerClassName="astw:px-6"` on `Table.Root` for the horizontal inset, and either drop `Card.Content` (bare list form) or pass `Card.Content className="astw:px-0"` (header+content form). Skipping the `containerClassName` lands the first column flush against the card edge. See the `Card` entry for the two canonical forms and a DON'T example. Dense cell typography (**`text-body-sm`**, **`text-mono`**) → **`design-system.md`** §4 Typography.
+- **Inside a card?** Pass `containerClassName="astw:px-6"` on `Table.Root` for the horizontal inset, and either drop `Card.Content` (bare list form) or pass `Card.Content className="astw:px-0"` (header+content form). Skipping the `containerClassName` lands the first column flush against the card edge. See the `Card` entry for the two canonical forms and a DON'T example. Dense cell typography (**`text-sm`**, **`tabular-nums`** for figures, **`font-mono`** for identifiers) → **`design-system.md`** §4 Typography.
 - **Whole row is clickable.** Use `<Table.Row onClick={() => navigate(detailPath)} className="astw:cursor-pointer">`. For keyboard and screen-reader users, also wrap the primary identifier cell content in `<Link>` (so the row is reachable via Tab; `Table.Row` is a `<tr>` and cannot itself be a Link — wrapping a `<tr>` in `<a>` is invalid HTML). **No per-row "View" / "Open" / "→" buttons.** Per-row `Menu` (overflow `…`) is the only allowed per-row action surface and is reserved for non-navigation actions like Archive, Duplicate.
 
 ### `DataTable`
@@ -387,7 +394,7 @@ Plus `badgeVariants` CVA for custom-styled siblings.
 
 **Import:** compound namespace + helpers from `'@tailor-platform/app-shell'`, e.g. `DataTable`, `useDataTable`, `useCollectionVariables`, `createColumnHelper`, and types such as `Column`, `UseDataTableReturn`.
 
-**Purpose:** Production list screens over GraphQL **connections**. Owns toolbar filter chips (**`DataTable.Filters`** from column `filter` configs), header sort, **`DataTable.Pagination`** (cursor-first; First/Last when `total` is provided), loading skeleton/error row, **`onClickRow`**, **`rowActions`** (kebab column), **`onSelectionChange`** (checkbox column), **column pinning** (`pin: "left" | "right"`) and built-in **column settings** (`<DataTable.Toolbar columnSettings>` — user show/hide + reorder + pin, persisted per-user via **`tableId`**).
+**Purpose:** Production list screens over GraphQL **connections**. Owns toolbar filter chips (**`DataTable.Filters`** from column `filter` configs), header sort, **`DataTable.Pagination`** (cursor-first; First/Last when `total` is provided), loading skeleton/error row, **`onClickRow`**, **`rowActions`** (kebab column), **`onSelectionChange`** (checkbox column), **expandable rows** (**`rowExpansion`** — a chevron column plus a full-width detail panel per row; `render` with optional `canExpand` / `getLabel`, and `expandedIds` + `onChange` for controlled mode), **column pinning** (`pin: "left" | "right"`) and built-in **column settings** (`<DataTable.Toolbar columnSettings>` — user show/hide + reorder + pin, persisted per-user via **`tableId`**).
 
 **Primitives:** Builds on low-level **`Table`**; do not reinvent pagination/filters manually unless the dataset is trivial.
 
@@ -643,6 +650,26 @@ const table = useDataTable({
 **API:** `InputProps` — extends native `<input>` props.
 **Used in patterns:** all `form/*`.
 
+### `Textarea`
+
+> Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/textarea.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/textarea.md)
+
+**Import:** `import { Textarea } from '@tailor-platform/app-shell'`
+**Purpose:** Multi-line text input. Maps to spec field types: `text`, long-form `string`. Use instead of `Input` whenever the value is prose (notes, descriptions, replies, reasons).
+**API:** `TextareaProps` — Base UI's field control (`value`, `defaultValue`, `onChange`, `onValueChange`, `disabled`, `required`, `readOnly`, `name`, aria-\*) rendered as a `<textarea>`, plus `rows`. `cols` / `wrap` are not accepted — the control is `w-full`, so neither can take effect.
+**Sizing:** no fixed height — `rows` sets the visible line count and the user can drag it taller. `min-h-16` is a hard floor, so `rows` only takes effect from 3 up. Width is the parent's job: the control is `w-full`, and `cols` is not accepted because it could never win against that. Do **not** reach for `Input` and a height override; `Input` is locked to `h-9`, and an `astw:h-*` override from a consuming app resolves to nothing unless that exact utility was compiled into the package CSS.
+**Field integration:** drops straight into `Field.Root` for label/description/error wiring exactly like `Input` and `Checkbox` — no bespoke `error` prop.
+**Example:**
+
+```tsx
+<Field.Root name="reason">
+  <Field.Label>Reason</Field.Label>
+  <Textarea rows={4} placeholder="Why is this being rejected?" />
+</Field.Root>
+```
+
+**Used in patterns:** `form/composer`, `form/*` (long-text fields).
+
 ### `Checkbox`
 
 **Import:** `import { Checkbox } from '@tailor-platform/app-shell'`
@@ -730,6 +757,32 @@ Types for authoring guard functions used by `WithGuard` and `appShellPageProps.g
 **Purpose:** Re-exported from `react-router`. Use the AppShell barrel — never import from `react-router` directly.
 **Used in patterns:** all (navigation, route params, query state).
 
+### `useMatch`, `useResolvedPath`, `useNavigation`
+
+**Import:** `import { useMatch, useResolvedPath, useNavigation } from '@tailor-platform/app-shell'`
+**Purpose:** `useMatch` tests a pattern against the current location (active states); `useResolvedPath` resolves a relative path; `useNavigation` exposes the in-flight navigation for pending UI.
+**Used in patterns:** navigation shells, list→detail transitions.
+
+### `useBlocker`, `useBeforeUnload`
+
+**Import:** `import { useBlocker, useBeforeUnload } from '@tailor-platform/app-shell'`
+**Purpose:** Guard navigation away from unsaved work — `useBlocker` for in-app navigation, `useBeforeUnload` for closing or reloading the tab.
+**Used in patterns:** form-heavy screens.
+
+### Types
+
+**Import:** `import type { Location, NavigateFunction, NavigateOptions, To, Params, PathMatch, LinkProps, NavLinkProps, Navigation, Blocker, BlockerFunction } from '@tailor-platform/app-shell'`
+**Purpose:** The React Router types that go with the hooks above, so app code never imports types from `react-router` either.
+
+### Not exported
+
+`createBrowserRouter`, `RouterProvider`, `MemoryRouter`, `Routes`, `Route` — AppShell builds the router; a second one nested inside it breaks navigation. `useLoaderData`, `Form`, `useSubmit`, `useFetcher`, `useActionData` — AppShell does not wire up React Router's data layer. Load data in the page component or the app's data layer.
+
+### Testing
+
+**Import:** `import { AppShell, TestRouter } from '@tailor-platform/app-shell/testing'`
+**Purpose:** Test routing without a `react-router` dependency. `AppShell` from this entry also accepts `memory` / `initialEntries`, for mounting a page at a fixed URL; `TestRouter` gives a single component router context, and takes `path` when that component reads the route (`useParams` is `{}` without it).
+
 ### `createTypedPaths`
 
 **Import:** `import { createTypedPaths } from '@tailor-platform/app-shell'`