@tailor-platform/app-shell 1.12.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -37,6 +37,10 @@
     "./vite-plugin": {
       "types": "./dist/vite-plugin.d.ts",
       "default": "./dist/vite-plugin.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "publishConfig": {
@@ -46,7 +50,7 @@
     "@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,26 +64,28 @@
     "@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",
+    "@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",
+    "react-hook-form": "7.71.2",
+    "tailwindcss": "^4.3.3",
+    "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",
+    "vite": "^8.2.2",
+    "vite-plugin-dts": "5.0.3",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
@@ -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

@@ -35,12 +35,13 @@ Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, themi
 
 ### 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)
@@ -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'`

package/skills/app-shell-patterns/references/fundamental/design-system.md

@@ -184,7 +184,7 @@ Hand-typing `padding: 13px` is a smell. Round to the nearest scale step; if noth
 
 ### Typography
 
-**AppShell defines no typography scale tokens.** There is no `text-h1`, `text-body`, or `text-caption`. The only typography token is `--font-sans` (Inter Variable) → `font-sans`, which the base layer already applies to `body`.
+**AppShell defines no typography scale tokens.** There is no `text-h1`, `text-body`, or `text-caption`. The only typography token is `--font-sans` (Inter Variable for Latin, Noto Sans JP Variable for Japanese) → `font-sans`, which the base layer already applies to `body`. Both are variable fonts, so every weight token is real in both scripts. Override the whole stack by setting `--app-shell-font-sans` on `:root`.
 
 Compose roles from stock Tailwind utilities. These pairings are what AppShell's own components use — match them so your screens sit consistently alongside the primitives:
 

package/skills/app-shell-patterns/references/patterns/form-composer.md

@@ -0,0 +1,142 @@
+---
+slug: pattern/form/composer
+name: Composer
+category: pattern
+subcategory: form
+description: Free-text composer — a multi-line input above a trailing action row, for notes, replies, and comments submitted in place
+requiredImports: [Card, Textarea, Button, Checkbox]
+tags: [composer, textarea, note, reply, comment, actions, discard, send]
+do:
+  - A free-text box the user fills and submits in place — add a note, reply on a thread, leave a comment, give a rejection reason
+  - The prose IS the interaction; any other controls only qualify how the text is submitted
+dont:
+  - The text is one field among many on a record form — use form/modal, form/single-page or form/sectioned with a Textarea field
+  - A chat input where Enter sends and there is no Discard — that is a different layout
+---
+
+# pattern/form/composer
+
+## When to Use
+
+- A free-text box the user fills and submits in place — add a note, reply on a thread, leave a comment, give a rejection reason
+- The prose IS the interaction; any other controls only qualify how the text is submitted
+
+## Layout
+
+```
++---------------------------------------------------------+
+| Card.Root / Card.Content                                 |
+|  +-----------------------------------------------------+ |
+|  | Textarea                                            | |
+|  |                                                     | |
+|  +-----------------------------------------------------+ |
+|  [ options slot … ]                  [Discard] [ Send ] |
++---------------------------------------------------------+
+```
+
+Two rows inside one `Card`:
+
+1. **Body** — a single `Textarea`, sized with `rows`. Tall enough to read as "write here", short enough that the action row stays on screen.
+2. **Action row** — one `flex items-center justify-between` line with a fixed right side and a free left side.
+
+## The action row
+
+This is the part the pattern actually fixes. Everything sits on **one line**, never stacked.
+
+**Right side — fixed.** Reading left to right: an optional `variant="ghost"` **Discard**, then exactly **one** primary submit. Nothing else goes here.
+
+- Discard clears the body; it does not close or navigate. Omit it when there is nothing to discard back to.
+- The submit is the view's single primary `Button` — never a second filled button beside it.
+- Both disable while `submitting`; the submit also disables on empty/whitespace-only input.
+- Swap the submit's label for a pending label while in flight ("Send" → "Sending…"). Do not swap in a spinner-only button — the label is what tells the user what is happening.
+
+**Left side — open.** Zero or more controls that qualify the submission, laid out `flex items-center gap-2` and allowed to shrink (`min-w-0`) so the buttons never get pushed off. Common occupants:
+
+- a `Checkbox` toggle — visibility, "internal note", "notify watchers" (the worked example below)
+- an attachment or template `Button` with `variant="ghost"`
+- a small `Select` — reply-as, channel, canned response
+
+Leave it empty and the buttons still sit correctly at the right; `justify-between` needs no placeholder element.
+
+## Page Implementation
+
+```tsx
+/* pattern: form/composer */
+import { useState } from "react";
+import { Button, Card, Checkbox, Textarea } from "@tailor-platform/app-shell";
+
+type Props = {
+  onSubmit: (body: string, internal: boolean) => void;
+  submitting?: boolean;
+};
+
+export default function Composer({ onSubmit, submitting = false }: Props) {
+  const [body, setBody] = useState("");
+  const [internal, setInternal] = useState(false);
+
+  return (
+    <Card.Root>
+      <Card.Content>
+        <div className="space-y-3">
+          <Textarea
+            aria-label="Reply"
+            value={body}
+            onChange={(e) => setBody(e.target.value)}
+            placeholder={internal ? "Internal context for teammates…" : "Reply to customer…"}
+            rows={4}
+          />
+          <div className="flex items-center justify-between gap-2">
+            {/* Options slot — 0..N controls that qualify the submission. An
+                internal-note toggle here; swap for an attachment button, a
+                visibility Select, a template picker, or drop it entirely. */}
+            <div className="flex min-w-0 items-center gap-2">
+              <Checkbox
+                label="Internal note (not sent to customer)"
+                checked={internal}
+                onCheckedChange={setInternal}
+              />
+            </div>
+            {/* Action slot — fixed shape: optional ghost Discard, then exactly
+                one primary submit. Never more than one primary. */}
+            <div className="flex shrink-0 gap-2">
+              <Button
+                variant="ghost"
+                onClick={() => setBody("")}
+                disabled={body.length === 0 || submitting}
+              >
+                Discard
+              </Button>
+              <Button
+                onClick={() => onSubmit(body, internal)}
+                disabled={body.trim().length === 0 || submitting}
+              >
+                {submitting ? "Sending…" : "Send"}
+              </Button>
+            </div>
+          </div>
+        </div>
+      </Card.Content>
+    </Card.Root>
+  );
+}
+```
+
+## Constraints
+
+- The body control is `Textarea`, never `Input` — `Input` is locked to `h-9` and clips prose to one 36px line.
+- Size the body with `rows` (3–5 is the usual range). Don't reach for an `astw:h-*` / `astw:min-h-*` override: `astw:` utilities only resolve if that exact class was compiled into the AppShell package CSS, so an arbitrary one written in a consuming app silently does nothing.
+- The `Textarea` needs an accessible name. There is usually no visible label in a composer, so pass `aria-label`; a placeholder is not a label.
+- One primary `Button` in the action row. Discard is `ghost`, and any left-side action is `ghost` too.
+- The action row is one row at every width — the left side shrinks, the buttons do not wrap under the body.
+- Disable the submit on empty or whitespace-only input, and disable both buttons while `submitting`.
+- Wrap the composer in `Card.Root` when it sits among other cards (a detail page, the end of a thread). A composer that is already inside a `Sheet` or `Dialog` body does not need its own card.
+
+## Anti-patterns
+
+- `Input` (or `Field.Control` with no override) for the body — a single-line box for multi-line text.
+- Discard rendered as `outline` or filled — it competes with the submit for the eye.
+- Submit and Discard both filled, or a third action added to the right side.
+- The action row stacked above the `Textarea`, or the buttons wrapped onto their own line — the composer stops reading as one unit.
+- A left-side toggle that silently changes what the submit does without changing the submit's own affordance — if "internal note" changes the destination, the placeholder (or the label) should say so.
+- Submit enabled on an empty body, so the user can post nothing.
+- A body so tall (`rows={12}`) that the action row falls below the fold — the composer stops reading as one unit.

package/skills/app-shell-patterns/references/patterns/form-single-page.md

@@ -4,7 +4,7 @@ name: Single Page Form
 category: pattern
 subcategory: form
 description: Routed full-page form for moderate field count (6-15) without natural sectioning
-requiredImports: [Layout, Form, Field, Fieldset, Input, Select, Button]
+requiredImports: [Layout, Form, Field, Fieldset, Input, Textarea, Select, Button]
 tags: [form, page, create, edit, routed]
 do:
   - A routed Create or Edit page that the design has explicitly called out (e.g. /orders/create)
@@ -26,7 +26,7 @@ dont:
 
 ```tsx
 /* pattern: form/single-page */
-import { Button, Layout, Input, Select, Field } from "@tailor-platform/app-shell";
+import { Button, Layout, Input, Textarea, Select, Field } from "@tailor-platform/app-shell";
 
 type Props = {
   onSave: (data: Record<string, string>) => void;
@@ -82,7 +82,7 @@ export default function SinglePageForm({ onSave, onCancel }: Props) {
           </Field.Root>
           <Field.Root name="description">
             <Field.Label>Description</Field.Label>
-            <Field.Control render={<Input />} />
+            <Textarea rows={4} />
           </Field.Root>
         </form>
       </Layout.Column>