@tailor-platform/app-shell 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -47,21 +47,21 @@
     "access": "public"
   },
   "dependencies": {
-    "@base-ui/react": "1.6.0",
+    "@base-ui/react": "1.8.0",
     "@internationalized/date": "3.12.2",
     "@standard-schema/spec": "^1.1.0",
     "@tailor-platform/auth-public-client": "^0.6.1",
+    "@tailor-platform/vite-plugin-app-shell": "0.3.0",
     "change-case": "^5.4.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "encoding-japanese": "^2.2.0",
-    "lucide-react": "^1.8.0",
+    "lucide-react": "1.8.0",
     "openai": "6.45.0",
     "papaparse": "^5.5.3",
     "react-router": "^8.3.0",
     "sonner": "^2.0.7",
-    "tailwind-merge": "^3.6.0",
-    "@tailor-platform/vite-plugin-app-shell": "0.3.0"
+    "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {
     "@fontsource-variable/noto-sans-jp": "5.3.0",
@@ -70,14 +70,14 @@
     "@testing-library/react": "16.3.3",
     "@testing-library/user-event": "14.6.7",
     "@types/encoding-japanese": "2.2.1",
-    "@types/node": "^25.9.5",
+    "@types/node": "^25.9.6",
     "@types/papaparse": "5.5.2",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@vitejs/plugin-react": "^6.1.0",
     "@vitest/coverage-v8": "4.1.10",
     "happy-dom": "20.9.0",
-    "postcss": "8.5.26",
+    "postcss": "8.5.28",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-hook-form": "7.71.2",

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

@@ -27,18 +27,14 @@ Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, themi
 
 ## Available Pages
 
-A page is the shape of a whole screen — the outer choice, made before picking patterns for the parts inside it. Where a pattern is one recipe, a page compares the layouts a screen could take and says when each applies. Match the screen first, then use the patterns the entry cites for the pieces within it.
-
+A page is the shape of a whole screen — the outer choice, made before picking patterns for the parts inside it. Where a pattern is one recipe, a page fixes the layout of a whole screen and says what belongs in each part of it. Match the screen first, then use the patterns the entry cites for the pieces within it.
 
+| Slug                                   | Name        | Description                                                                                                        |
+| -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| [`detail`](references/pages/detail.md) | Detail Page | The screen for a single record — its summary, its contents, the records around it, and the actions available on it |
 
 ## Available Patterns
 
-### detail
-
-| Slug                                                                          | Name                     | Description                                                           |
-| ----------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
-| [`detail/hero-with-actions`](references/patterns/detail-hero-with-actions.md) | Hero With Actions Detail | Single-record detail view with workflow actions and activity timeline |
-
 ### form
 
 | Slug                                                          | Name             | Description                                                                                                              |
@@ -66,16 +62,17 @@ 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. Match constraints to an entry slug from the tables above
-3. Read the entry's detailed spec: `references/<category>/<slug>.md` (relative to this file)
-4. Read fundamental references for component APIs, design tokens, and GraphQL conventions: `references/fundamental/`
-5. Implement using ONLY the imports listed in the entry's `requiredImports`
+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 fundamental references for component APIs, design tokens, and GraphQL conventions: `references/fundamental/`
+6. Implement using ONLY the imports listed in the entry's `requiredImports` — for a page, the `requiredImports` of the pattern it sent you to
 
 ## Rules
 
 - ALWAYS cite the entry slug in a comment at the top of the file:
-  `/* pattern: list/dense-scan */`
-- NEVER mix patterns in a single page component
+  `/* pattern: list/dense-scan */`. Cite the pattern you implemented, even when a page entry sent you to it.
+- NEVER mix two patterns that solve the same problem in one component — one part, one recipe. Composing patterns for _different_ parts of a screen is expected, and the screen's page entry says which.
 - ALWAYS use AppShell components — do NOT use raw HTML or third-party UI libraries
 - If no entry matches, compose directly from fundamental references
 

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

@@ -9,7 +9,7 @@
 | This file (`components.md`)                                                                                       | `design-system.md`                                                                                |
 | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | **Imports**, compound structure, hooks, canonical **composition** (`Card` + `Table`, `DataTable`, `Dialog`, etc.) | **Tokens**, theme imports, typography/spacing/radius/elevation **tables**, breakpoints **intent** |
-| JSX examples tied to ERP patterns (`patterns/*`)                                                                  | **`astw:`** rules — only on AppShell `*ClassName` props; plain utilities on **your** elements     |
+| JSX examples tied to ERP patterns (`patterns/*`)                                                                  | **AppShell styling boundary** — plain utilities and no internal `astw:` prefix                    |
 | Prop summaries + links to upstream `docs/components/*.md`                                                         | **Visual conformance**: no magic colors/px on custom markup, motion, dark mode                    |
 
 **Rule of thumb:** “Which component / prop?” → **here.** “Which token / spacing step / elevation?” → **`design-system.md`** §§4–6.
@@ -105,7 +105,7 @@ import { Button, Layout, Tabs } from "@tailor-platform/app-shell";
 </Layout>
 ```
 
-**Notes:** Children that aren't `Layout.Header` or `Layout.Column` are filtered out. Column gap overrides (`<Layout className="astw:gap-6" />`) → **`design-system.md`** §5 (`astw:` rules).
+**Notes:** Children that aren't `Layout.Header` or `Layout.Column` are filtered out. Set column gaps with `<Layout gap={6} />` (supported steps: 4, 6, 8).
 
 **Used in patterns:** every page pattern (`list/*`, `detail/*`, `form/*`).
 
@@ -257,7 +257,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
 
 **Used in patterns:** `list/*` (filter sheet variant).
 
-**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.
+**Notes:** Size the panel with `Sheet.Content`'s **`size`** prop (`"sm" | "md" | "lg" | "xl" | "full"`, default `"sm"`) — not a width utility.
 
 ### `Menu`
 
@@ -355,7 +355,7 @@ Plus `badgeVariants` CVA for custom-styled siblings.
 
 **Import:** `import { Table } from '@tailor-platform/app-shell'`
 **Purpose:** Semantic data table with scrollable container.
-**API:** Compound — `Table.Root`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`. `Table.Root` accepts `containerClassName` for the outer wrapper, `className` for the inner `<table>`. `Table.Head` and `Table.Cell` accept **`align`** (`"left" | "center" | "right"`, default `"left"`) — prefer this over ad-hoc `className="astw:text-right"` and pair the same alignment on the head and its column's cells (right for numeric/money, center for compact status/icon columns).
+**API:** Compound — `Table.Root`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`. `Table.Root` accepts `containerClassName` for the outer wrapper, `className` for the inner `<table>`. `Table.Head` and `Table.Cell` accept **`align`** (`"left" | "center" | "right"`, default `"left"`) — prefer this over ad-hoc `className="text-right"` and pair the same alignment on the head and its column's cells (right for numeric/money, center for compact status/icon columns).
 **Example:**
 
 ```tsx
@@ -385,8 +385,8 @@ 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-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.
+- **Inside a card?** Zero the card's horizontal padding — drop `Card.Content` (bare list form) or pass `Card.Content className="px-0!"` (header+content form) — and leave the table container's padding alone. `Table.Head` / `Table.Cell` carry their own `first:pl-6` / `last:pr-6`, so a `containerClassName="px-6"` double-pads and the first column lands 24px right of the card title. 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="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`
 
@@ -461,13 +461,13 @@ const table = useDataTable({
 
 **Notes:**
 
-- **Tables inside a card need TWO co-requisite geometry changes** (token-backed spacing rationale → **`design-system.md`** §4 Spacing): (a) Card stops imposing horizontal padding — drop `Card.Content` for the bare form, or pass `Card.Content className="astw:px-0"` for the header+content form. (b) `Table.Root` provides the inset itself via `containerClassName="astw:px-6"`. Skipping (b) lands the first column flush against the card edge — `Table.Cell`'s intrinsic `astw:first:pl-6` does NOT render reliably in this composition.
+- **A table inside a card needs ONE geometry change, not two** (token-backed spacing rationale → **`design-system.md`** §4 Spacing): the card stops imposing horizontal padding. Drop `Card.Content` for the bare form, or pass `Card.Content className="px-0!"` for the header+content form. That is all. `Table.Head` and `Table.Cell` already carry an intrinsic `first:pl-6` / `last:pr-6`, which supplies the inset on its own — so the table container must add **none**. Padding on the container stacks on top of the cell's own and pushes the first column 24px past the card title.
 
 **Bare table-in-card (list pages, no card-level title):**
 
 ```tsx
 <Card.Root>
-  <Table.Root containerClassName="astw:px-6">{/* … */}</Table.Root>
+  <Table.Root>{/* … */}</Table.Root>
 </Card.Root>
 ```
 
@@ -476,18 +476,19 @@ const table = useDataTable({
 ```tsx
 <Card.Root>
   <Card.Header title="Line items" />
-  <Card.Content className="astw:px-0">
-    <Table.Root containerClassName="astw:px-6">{/* … */}</Table.Root>
+  <Card.Content className="px-0!">
+    <Table.Root>{/* … */}</Table.Root>
   </Card.Content>
 </Card.Root>
 ```
 
-**DON'T — first column lands flush against the card edge:**
+**DON'T — the first column sits 24px right of the card title:**
 
 ```tsx
 <Card.Root>
-  <Card.Content className="astw:px-0">
-    <Table.Root>{/* missing containerClassName="astw:px-6" */}</Table.Root>
+  <Card.Content className="px-0!">
+    {/* double-pads: the container's 24px adds to the cell's own first:pl-6 */}
+    <Table.Root containerClassName="px-6">{/* … */}</Table.Root>
   </Card.Content>
 </Card.Root>
 ```
@@ -565,26 +566,37 @@ const table = useDataTable({
 />
 ```
 
-**Used in patterns:** `detail/hero-with-actions` (body sections).
+**Used in:** `page/detail` (body sections).
 
 ### `ActionPanel`
 
 **Import:** `import { ActionPanel } from '@tailor-platform/app-shell'`
 **Purpose:** Right-rail panel listing workflow actions for a detail page (approve, reject, archive, etc.).
-**API:** `ActionPanelProps` — `title`, `actions` (array of `{ label, onSelect, variant?, disabled?, hidden? }`), `className`.
+**API:** `ActionPanelProps` — `title`, `actions`, `className`. Each action is `{ key, label, icon, onClick?, disabled?, loading?, variant? }`; `key`, `label` and `icon` are all **required**, the handler is `onClick` (not `onSelect`), and `variant` is `"default" | "destructive"`. There is no `hidden` — omit a row by not spreading it in. The row type is not exported on its own; annotate an array as `ActionPanelProps["actions"]`.
 **Example:**
 
 ```tsx
 <ActionPanel
   title="Actions"
   actions={[
-    { label: "Approve", variant: "default", onSelect: handleApprove },
-    { label: "Reject", variant: "destructive", onSelect: handleReject, disabled: !canReject },
+    { key: "approve", label: "Approve", icon: <Check />, onClick: handleApprove },
+    ...(canReject
+      ? [
+          {
+            key: "reject",
+            label: "Reject",
+            icon: <X />,
+            onClick: handleReject,
+            variant: "destructive" as const,
+            loading: rejecting,
+          },
+        ]
+      : []),
   ]}
 />
 ```
 
-**Used in patterns:** `detail/hero-with-actions`.
+**Used in:** `page/detail`.
 
 **Notes:**
 
@@ -595,7 +607,7 @@ const table = useDataTable({
 **Import:** `import { ActivityCard } from '@tailor-platform/app-shell'`
 **Purpose:** Timeline of events on a record (audit log, status changes, comments).
 **API:** Compound — `ActivityCard.Root`, `ActivityCard.Items` (generic over item type), plus `ActivityCardProps`, `ActivityCardItem`, `ActivityCardItemProps`. Items render with timestamp + actor + description.
-**Used in patterns:** `detail/hero-with-actions` (right column or bottom section).
+**Used in:** `page/detail` (right column, for revision history / audit trail).
 
 ### `Alert`
 
@@ -747,7 +759,7 @@ Multi-select submits an array.
 **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.
+**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 application must not use AppShell's internal `astw:` classes.
 **Field integration:** drops straight into `Field.Root` for label/description/error wiring exactly like `Input` and `Checkbox` — no bespoke `error` prop.
 **Example:**
 
@@ -792,6 +804,22 @@ Multi-select submits an array.
 
 ---
 
+## AI
+
+### `AIChat`
+
+> Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/ai-chat.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/ai-chat.md)
+
+**Import:** `import { AIChat } from '@tailor-platform/app-shell'`
+**Purpose:** Building blocks for an LLM assistant UI — a streaming conversation view over a composer, plus reasoning, tool-call, and citation parts. The root places three regions in a fixed order, `Layout`-style: `AIChat.Header` (optional) over `AIChat.Conversation` over `AIChat.Composer` (optional). Each region carries its own props; the root carries `status`.
+**API:** Root (`status`) + regions — `AIChat.Header` (`title`, `icon`, `actions`), `AIChat.Conversation` (`autoScroll`, transcript as children), `AIChat.Composer` (`onSubmit`, `onStop`, `value`/`defaultValue`/`onValueChange`, `placeholder`, `disabled`, `submitOnEnter`, `actions`) — + transcript parts: `AIChat.Message`, `.Response`, `.EmptyState`, `.Suggestions`/`.Suggestion`, `.Actions`/`.Action`, `.Reasoning`/`.ReasoningTrigger`/`.ReasoningContent`, `.ChainOfThought*`, `.Tool*`, `.Sources*`, `.History`.
+**Composer:** Body is `Textarea` over one action row per `form/composer`'s layout. Enter submits (IME-safe), Shift+Enter newlines, and `status` from `useAIChat()` drives the busy/Stop state.
+**Header:** a 48px strip (graphic + `text-sm font-semibold` title + right action slot) closed by a full-width rule; renders only when `title` or `actions` is set.
+**Renders no chrome:** no border or background of its own — wrap in `Card`, `Sheet`, or a `Layout.Column`, with `overflow-hidden` so the header rule stays inside rounded corners.
+**Used in patterns:** none yet — a component, not a catalogue pattern (platform-planning#1748).
+
+---
+
 ## Auth & access
 
 ### `AuthProvider`

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

@@ -1,6 +1,6 @@
 # Design System
 
-Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, the `astw:` prefix, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `components.md`; that split avoids duplicating tables and lengthy examples across both docs.
+Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `components.md`; that split avoids duplicating tables and lengthy examples across both docs.
 
 `@tailor-platform/app-shell` ships an opinionated design system as CSS variables, bridged into Tailwind v4's token namespace. Use it whether you are consuming AppShell components (most cases) or building a custom component to fill a gap.
 
@@ -302,23 +302,30 @@ Stock Tailwind breakpoints — AppShell does not change them.
 
 Two-column **behavior** (right rail stacks under `lg`): respect AppShell defaults — do not force side-by-side grids on narrow viewports. The `Layout` column width table lives in `components.md` → Layout; reuse those numbers instead of guessing rem values here.
 
-## 5. The `astw:` prefix
+## 4b. Links
 
-AppShell exposes **layout / sizing / overflow** escapes on some components via props like `containerClassName` and `className` on roots. Prefix those utilities with `astw:` so they apply to the wrapper AppShell controls.
+One treatment for every text link — inside `DescriptionCard`, in table rows,
+in cards:
 
-**Do not duplicate full component trees here.** Typical patterns (full `DataTable` composition, `Sheet` + footer, `Table.Root` + card insets) live in `components.md` with JSX you can copy.
+- **`text-primary` at rest, `hover:underline` only.** Colour carries the affordance; a resting underline is noise. Pair with `underline-offset-4`.
+- **Internal routes** use app-shell's `Link` (`to`), never a bare `<a href>`.
+- **External destinations** use `<a target="_blank" rel="noopener noreferrer">` with a lucide `ExternalLink` at `size-3` after the label. There is no dedicated component for this; that markup is the convention.
+- **Identifiers** (document numbers, SKUs) keep `font-mono` on top of the link style.
 
-Minimal illustration — the same rules apply to other `*ClassName` hooks:
+This is the treatment `DescriptionCard` already applies to its `type: "link"`
+fields — match it rather than inventing a second one.
+
+## 5. AppShell styling boundary
+
+`astw:` is AppShell's internal compiled CSS prefix. **Never write it in an application.** It is not a consumer customization API and arbitrary prefixed utilities may not exist in the shipped CSS.
+
+Use ordinary Tailwind utilities on your own markup. An explicitly documented layout hook, such as `Table.Root`'s `containerClassName`, also accepts ordinary utilities from the application's Tailwind build:
 
 ```tsx
-<Table.Root containerClassName="astw:px-6 astw:overflow-y-auto" />
+<Table.Root containerClassName="px-6 overflow-y-auto" />
 ```
 
-Rules:
-
-- `astw:` only on AppShell `*ClassName` / root `className` hooks each component exposes. Use **plain** Tailwind (`flex`, `gap-4`, `bg-background`, …) on **your** markup.
-- Stick to **layout** utilities (`flex`, `grid`, `max-h-*`, `min-h-0`, `overflow-*`, widths). Avoid painting over internal AppShell padding or colors via `astw:` — prefer an upstream prop or composition change.
-- Steps like `astw:p-4` still resolve through the scale — never arbitrary `astw:p-[13px]`.
+For an AppShell component's appearance, use its documented props, variants, or composition instead of styling over its internals.
 
 ## 6. When AppShell doesn't have a component you need
 
@@ -380,13 +387,13 @@ When a custom component proves reusable across 2+ apps, promote it upstream into
 
 ### Where to look
 
-| Concern                                             | File                               |
-| --------------------------------------------------- | ---------------------------------- |
-| Component imports, props, JSX composition           | **`components.md`**                |
-| Page / screen layout patterns                       | **`patterns/<type>/<slug>.md`**    |
-| Design tokens, `astw:` rules, custom UI conformance | **this file** (`design-system.md`) |
+| Concern                                                         | File                               |
+| --------------------------------------------------------------- | ---------------------------------- |
+| Component imports, props, JSX composition                       | **`components.md`**                |
+| Page / screen layout patterns                                   | **`patterns/<type>/<slug>.md`**    |
+| Design tokens, AppShell styling boundary, custom UI conformance | **this file** (`design-system.md`) |
 
-**`components.md`** holds long JSX compositions (e.g. **`DataTable`**, **card + `Table`**). **Do not copy those trees into this file** — link back here only for tokens and `astw:` policy.
+**`components.md`** holds long JSX compositions (e.g. **`DataTable`**, **card + `Table`**). **Do not copy those trees into this file** — link back here only for tokens and the AppShell styling boundary.
 
 `patterns/` is organised by page type: `patterns/list/`, `patterns/detail/`, `patterns/form/`, `patterns/interaction/`. Pick the slug matching the screen you're building.