@tailor-platform/app-shell 1.18.0 → 1.20.0

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

@@ -0,0 +1,342 @@
+---
+title: Tree
+description: Browse, pick one, or tick many items in a hierarchy — inline with Tree, or in a search dialog with TreePicker
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/tree.docs.outline.md — do not edit by hand. -->
+
+# Tree
+
+`Tree` shows your own hierarchical items (accounts with sub-accounts, warehouses with bins, categories with products) as an ARIA tree. It can be a plain browser, a single-select for master–detail views, or a multi-select checkbox form control.
+
+The tree is the primitive, so it has no search box of its own. For the common "search, pick, then add" flow, **`TreePicker`** is a checkbox tree in a dialog with search, Cancel, and an "Add N items" button, the same split as `DateField` and `DatePicker`.
+
+Trees are single-column. If you need a hierarchy with real columns (sorting, pinning, wide data), that's a tree grid, which belongs with the data table rather than here.
+
+## Import
+
+```tsx
+import { Tree, TreePicker } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+Pass your own items and say how to read them with `mapItem`, as with `Select` and `Combobox`. `children` points at your own child array, and an item with no children is a leaf.
+
+```tsx
+type Account = { code: string; name: string; children?: Account[] };
+
+<Tree
+  aria-label="Chart of accounts"
+  className="h-96"
+  items={accounts}
+  mapItem={(account) => ({
+    key: account.code,
+    label: `${account.code} ${account.name}`,
+    children: account.children,
+  })}
+  onAction={(account) => navigate(`/accounts/${account.code}`)}
+/>;
+```
+
+### Item types
+
+`Tree` takes its item type from `items`, so you don't pass one. The case that needs a type is a tree whose levels are different types, like categories holding products: type `items` as the union of every level, so `mapItem` can hand back either level's children.
+
+```tsx
+type CatalogNode = Category | Product;
+
+const categories: CatalogNode[] = loadCategories();
+```
+
+Typed as `Category[]`, the item type is just `Category`, and `children: category.products` is a type error. Annotating `mapItem`'s parameter as the union works too.
+
+### Keys
+
+A `key` is the item's identity across the whole tree. The same key in two places is one item, so a product listed in two collections ticks in both places at once.
+
+When codes repeat with different meanings, like bin `A1` in two warehouses, compose a unique key. `mapItem` receives the item's `parents` for exactly this.
+
+A key can't be a parent in one place and a leaf in another. One key is one item, and an item can't both have children and not, so those rows can't tick consistently. The tree logs a console warning naming any such keys.
+
+```tsx
+const isWarehouse = (node: Warehouse | Bin): node is Warehouse => "bins" in node;
+
+mapItem={(item, { parents }) =>
+  isWarehouse(item)
+    ? { key: item.id, label: item.name, children: item.bins }
+    : { key: `${parents.find(isWarehouse)?.id}/${item.code}`, label: item.code }
+}
+```
+
+`parents` has the same union type as `items`, so the example narrows it with a type guard rather than a cast (`parents[0] as Warehouse`). A cast tells TypeScript to trust you, and throws at runtime if there's no warehouse above. The guard has TypeScript check it, so that case stays visible (`?.id`) and you decide how to handle it.
+
+## Selection modes
+
+`selectionMode` sets what clicking and Space do to a row.
+
+| Mode               | What a row does                                                           | State                    |
+| ------------------ | ------------------------------------------------------------------------- | ------------------------ |
+| `"none"` (default) | Clicking a leaf runs `onAction`, and clicking a parent opens or closes it | –                        |
+| `"single"`         | One row is selected at a time, parents included                           | `selectedKey`            |
+| `"checkbox"`       | Rows have checkboxes, and the tree is a multi-select form control         | `value` (a list of keys) |
+
+Enter runs `onAction(item, key)` on any enabled row, in every mode. The props are a union on `selectionMode`, so `value` or `name` without `selectionMode="checkbox"` is a type error rather than silently ignored.
+
+### Single
+
+```tsx
+const [selected, setSelected] = useState<string | null>(null);
+
+<Tree
+  {...props}
+  selectionMode="single"
+  selectedKey={selected}
+  onSelectedKeyChange={(key) => setSelected(key)}
+/>;
+```
+
+Selecting a closed parent opens it. Its caret closes it again, so selecting an open parent never hides what you were looking at.
+
+The selected row is always revealed: when it starts out inside closed groups, or `selectedKey` changes from outside to a hidden row, its ancestors open. A group the user closes afterwards stays closed, and the tab stop then sits on its nearest visible ancestor. Pass `revealSelected={false}` to leave groups as they are.
+
+### Checkbox
+
+```tsx
+const [skus, setSkus] = useState<string[]>([]);
+
+<Tree {...props} selectionMode="checkbox" value={skus} onValueChange={setSkus} />;
+```
+
+`onValueChange(value, { selected })` gives the new value plus the items it lists, as `{ key, item, parents }[]` in tree order. Keys in the value that aren't in `items` (not loaded yet, say) are kept as they were.
+
+## How ticking works
+
+`selectionStrategy` decides how ticking spreads and what ends up in the value. The default covers the most common case: parents are just containers, and the value lists leaves.
+
+Take a parent P with two leaves, A and B, starting from nothing ticked:
+
+| Value                | Tick P      | Tick A and B | Can P be ticked on its own? |
+| -------------------- | ----------- | ------------ | --------------------------- |
+| `"leaves"` (default) | `[A, B]`    | `[A, B]`     | No                          |
+| `"topmost"`          | `[P]`       | `[P]`        | No                          |
+| `"all"`              | `[P, A, B]` | `[P, A, B]`  | No                          |
+| `"cascade"`          | `[P, A, B]` | `[A, B]`     | Yes                         |
+| `"independent"`      | `[P]`       | `[A, B]`     | Yes                         |
+
+- **`"leaves"`, `"topmost"` and `"all"`** treat parents as containers. A parent's checkbox comes from its leaves, so unticking A after ticking P leaves P indeterminate. With `"topmost"`, `P` stands for everything beneath it.
+- **`"cascade"`** makes parents items in their own right. Ticking one ticks everything beneath it too, but unticking A leaves `[P, B]`, with P still ticked.
+- **`"independent"`** ticks every item on its own.
+
+```tsx
+// Everything in a warehouse comes back as the warehouse key, not every bin.
+<Tree {...props} selectionMode="checkbox" selectionStrategy="topmost" />
+
+// A parent purchase order can be approved without its child orders.
+<Tree {...props} selectionMode="checkbox" selectionStrategy="independent" />
+```
+
+Every combination round-trips: passing a value back in shows the same ticks. With `"leaves"`, `"topmost"` or `"all"`, a parent key in the value stands for every leaf beneath it, so `defaultValue={["wh-x"]}` ticks all of Warehouse X.
+
+## Rows
+
+The row shows the item's `label` by default. `renderItem` replaces it, and receives the row's state.
+
+```tsx
+renderItem={({ item, isLeaf }) =>
+  isLeaf ? (
+    <span className="flex w-full justify-between gap-3">
+      <span>{item.name}</span>
+      <span className="text-muted-foreground tabular-nums">{money(item.price)}</span>
+    </span>
+  ) : (
+    <strong>{item.name}</strong>
+  )
+}
+```
+
+| Row state       | Type      | Description                                                                                       |
+| --------------- | --------- | ------------------------------------------------------------------------------------------------- |
+| `item`          | `T`       | Your original item.                                                                               |
+| `key`           | `string`  | The item's key.                                                                                   |
+| `parents`       | `T[]`     | Ancestors, top level first.                                                                       |
+| `depth`         | `number`  | 0 for top-level rows.                                                                             |
+| `isLeaf`        | `boolean` | The item has no children.                                                                         |
+| `checked`       | `boolean` | Checkbox mode: the row is ticked. Where parents are containers, every enabled leaf beneath it is. |
+| `indeterminate` | `boolean` | Checkbox mode, where parents are containers: some, but not all, enabled leaves beneath it are.    |
+| `selected`      | `boolean` | Single mode: the row is the selected one.                                                         |
+| `expanded`      | `boolean` | The parent is open.                                                                               |
+| `disabled`      | `boolean` | The item, an ancestor, or the whole tree is disabled.                                             |
+
+## Filtering
+
+`filter` narrows the tree to matching items plus their ancestors, and opens the groups they're in. It receives the item with its `label` and `parents`. A parent that matches with no matching children keeps all of them, so it can still be opened.
+
+```tsx
+const [query, setQuery] = useState("");
+const filter = useMemo(
+  () => (query ? (_: Account, { label }: { label: string }) => label.includes(query) : undefined),
+  [query],
+);
+
+<Input value={query} onChange={(event) => setQuery(event.target.value)} />
+<Tree {...props} filter={filter} />
+```
+
+Groups a filter opened can still be closed. They stay closed until the matches change, so an inline `filter` recreated on every render won't reopen them.
+
+In checkbox mode, ticking a group while filtering acts on what's visible: it ticks the group's matching leaves, not the hidden ones. The group's checkbox still reflects the whole group, so it shows as partly ticked until every leaf beneath it is. Press it again to clear the visible matches.
+
+## Forms
+
+In checkbox mode, `Tree` works like `Select` and the other form controls: as a plain form field, inside `Field.Root`, and with React Hook Form.
+
+```tsx
+<form action={saveCount}>
+  <Field.Root name="bins">
+    <Field.Label>Bins to count</Field.Label>
+    <Tree {...props} selectionMode="checkbox" required />
+    <Field.Description>Pick at least one bin.</Field.Description>
+  </Field.Root>
+  <Button type="submit">Start count</Button>
+</form>
+```
+
+- **Submitting:** `name` (or the `Field.Root`'s name) renders one hidden input per value key, so the server reads `formData.getAll("bins")`. `itemToStringValue(item, { parents })` changes the submitted string.
+- **`required`** blocks submission until at least one item is ticked.
+- **Inside `Field.Root`**, `Field.Label` names the tree, `Field.Description` and `Field.Error` are announced with it, and an invalid field sets `data-invalid` on the root.
+- **`disabled`** (or a disabled `Field.Root`) locks the whole tree and leaves it out of submission.
+- **`onBlur`** fires once focus leaves the tree, not between rows. React Hook Form uses it to mark the field touched.
+- **Enter** runs `onAction`, or submits the owning form when there's no `onAction`, like Enter in a text input.
+
+Only checkbox mode is a form control. In `"none"` and `"single"` modes the tree doesn't register with `Field`.
+
+## Disabled items
+
+Return `disabled: true` from `mapItem` to lock an item. A disabled parent locks everything beneath it, and `disabled` on the tree locks every row. A locked row can't be ticked or selected, and Enter doesn't run `onAction` on it. A disabled item that's already ticked stays ticked.
+
+```tsx
+mapItem={(bin) => ({ key: bin.code, label: bin.code, disabled: bin.status === "counting" })}
+```
+
+How a parent behaves next to disabled children depends on whether it's a container or an item:
+
+| Mode                                         | Ticking a parent                                                                    | A parent whose children are all disabled     |
+| -------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- |
+| Checkbox, `"leaves"` / `"topmost"` / `"all"` | Skips disabled leaves. It counts as ticked once every _enabled_ leaf beneath it is. | Locked, since there's nothing it could tick. |
+| Checkbox, `"cascade"`                        | Ticks itself and every enabled item beneath it.                                     | Usable. Ticking it ticks only itself.        |
+| Checkbox, `"independent"`                    | Ticks only itself.                                                                  | Usable.                                      |
+| `"single"` and `"none"` selection modes      | –                                                                                   | Usable: it can be selected or run.           |
+
+## TreePicker
+
+A checkbox tree in a dialog, with search. It takes the same item, row and ticking props as `Tree`, plus the search and commit props. Each open starts empty, and `onCommit` receives the value's items in tree order. Ticking a group while searching ticks its matching items, as described under [Filtering](#filtering).
+
+```tsx
+const isProduct = (item: Category | Product): item is Product => "sku" in item;
+
+<TreePicker
+  open={open}
+  onOpenChange={setOpen}
+  title="Add items from catalogue"
+  items={categories}
+  mapItem={mapCatalogItem}
+  renderItem={renderCatalogItem}
+  matchesSearch={(item, query) => item.name.toLowerCase().includes(query.toLowerCase())}
+  onCommit={(picked) => addToOrder(picked.flatMap(({ item }) => (isProduct(item) ? [item] : [])))}
+/>;
+```
+
+`onCommit`'s items have the union type too, so narrow them with a type guard rather than casting to `Product`. With the default `"leaves"` only products come back, but a guard keeps that true if you later switch to `"topmost"` or `"all"`, which can return categories.
+
+## Props
+
+### Shared (Tree and TreePicker)
+
+| Prop         | Type                                                             | Default            | Description                                                                |
+| ------------ | ---------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------- |
+| `items`      | `ReadonlyArray<T>`                                               | required           | Your top-level items.                                                      |
+| `mapItem`    | `(item: T, { parents }) => { key, label, children?, disabled? }` | required           | Reads an item's key, label, children and disabled state.                   |
+| `renderItem` | `(row) => ReactNode`                                             | the item's `label` | The row's content.                                                         |
+| `emptyText`  | `ReactNode`                                                      | "No items."        | Shown when there's nothing to show ("No matching items." while filtering). |
+
+### Tree
+
+| Prop                             | Type                                       | Default  | Description                                                             |
+| -------------------------------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------- |
+| `selectionMode`                  | `"none" \| "single" \| "checkbox"`         | `"none"` | What clicking and Space do to a row.                                    |
+| `onAction`                       | `(item: T, key: string) => void`           | –        | Enter on a row. In `"none"` mode, a click on a leaf too.                |
+| `filter`                         | `(item: T, { label, parents }) => boolean` | –        | Shows only matches and their ancestors.                                 |
+| `disabled`                       | `boolean`                                  | `false`  | Locks every row, and in checkbox mode leaves it out of form submission. |
+| `aria-label` / `aria-labelledby` | `string`                                   | –        | Names the tree, when there's no `Field.Label`.                          |
+| `className`                      | `string`                                   | –        | Merged onto the root. Give it a height for long trees.                  |
+
+With `selectionMode="single"`:
+
+| Prop                                 | Type                             | Default | Description                                            |
+| ------------------------------------ | -------------------------------- | ------- | ------------------------------------------------------ |
+| `selectedKey` / `defaultSelectedKey` | `string \| null`                 | `null`  | Controlled / initial selected row.                     |
+| `onSelectedKeyChange`                | `(key: string, item: T) => void` | –       | Fires when the user selects a row.                     |
+| `revealSelected`                     | `boolean`                        | `true`  | Opens the selected row\'s ancestors when it\'s hidden. |
+
+With `selectionMode="checkbox"`:
+
+| Prop                         | Type                                                           | Default    | Description                                                                              |
+| ---------------------------- | -------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
+| `value` / `defaultValue`     | `string[]`                                                     | –          | Controlled / initial value: the ticked keys.                                             |
+| `onValueChange`              | `(value, { selected }) => void`                                | –          | Every change, plus the items the value lists.                                            |
+| `selectionStrategy`          | `"leaves" \| "topmost" \| "all" \| "cascade" \| "independent"` | `"leaves"` | How ticking works and what the value lists. See [How ticking works](#how-ticking-works). |
+| `name` / `form`              | `string`                                                       | –          | Hidden inputs for native form submission. `Field.Root`'s name wins.                      |
+| `itemToStringValue`          | `(item, { parents }) => string`                                | the key    | The string each hidden input carries.                                                    |
+| `required`                   | `boolean`                                                      | `false`    | At least one item must be ticked.                                                        |
+| `id` / `inputRef` / `onBlur` | –                                                              | –          | Form control id, the hidden proxy input, and blur from the whole tree.                   |
+
+### TreePicker
+
+| Prop                | Type                                                               | Default          | Description                                                         |
+| ------------------- | ------------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------- |
+| `open`              | `boolean`                                                          | required         | Controls dialog visibility.                                         |
+| `onOpenChange`      | `(open: boolean) => void`                                          | required         | Fires on every user-driven open or close, including after a commit. |
+| `onCommit`          | `(selected: TreeSelectedItem<T>[]) => void`                        | required         | Receives the value's items in tree order.                           |
+| `selectionStrategy` | as on `Tree`                                                       | `"leaves"`       | How ticking works while picking.                                    |
+| `matchesSearch`     | `(item: T, query: string, context: { label, parents }) => boolean` | match on `label` | Search predicate. An item is kept when it or a descendant matches.  |
+| `filterSlot`        | `ReactNode`                                                        | –                | Beside the search input, e.g. a category filter.                    |
+| `searchPlaceholder` | `string`                                                           | `"Search"`       | Search input placeholder.                                           |
+| `title`             | `ReactNode`                                                        | `"Select items"` | Dialog title. Also labels the tree for assistive tech.              |
+| `ctaLabel`          | `(count: number) => ReactNode`                                     | `"Add N items"`  | Primary button label.                                               |
+| `className`         | `string`                                                           | –                | Merged onto the dialog panel.                                       |
+
+The default labels are localised (English and Japanese) through the app's locale, like DataTable's. Passing a label prop overrides it.
+
+## Behaviour
+
+**Keyboard.** The tree is a `role="tree"` with roving focus. Arrow Up / Down move between visible rows, Arrow Right opens a closed parent or steps into it, Arrow Left closes or steps out to the parent, and Home / End jump to the ends. Space selects or ticks the focused row, and Enter runs `onAction` (in the picker, it commits).
+
+**Mouse.** In checkbox mode, clicking a group row opens or closes it and its checkbox ticks everything inside, while clicking an item row ticks it. In single mode, clicking selects. In `"none"` mode, clicking a leaf runs `onAction`.
+
+**Picker search.** Matches stay visible with their ancestors opened. Escape clears the search first, and a second Escape closes the dialog. Enter in the search box or in a `filterSlot` control (a menu or select) is left to that control.
+
+**Picker height.** The picker keeps one height and the list scrolls inside it, so opening or closing a group never resizes the dialog or moves what's on screen.
+
+## Loading an async catalogue
+
+There's deliberately no async variant yet: filtering and auto-expanding need the whole tree up front. Fetch once before or on open, and drive `emptyText` from your own loading flag. Keys in `value` for items that haven't loaded yet are kept, so a controlled selection survives the load.
+
+```tsx
+const { data, isLoading } = useCatalogQuery();
+
+<TreePicker
+  open={open}
+  onOpenChange={setOpen}
+  items={data ?? []}
+  mapItem={mapCatalogItem}
+  emptyText={isLoading ? "Loading catalogue…" : undefined}
+  onCommit={handleCommit}
+/>;
+```
+
+## Related
+
+- [Combobox](./combobox.md) — inline single or multi select for flat option lists
+- [Select](./select.md) — dropdown select, with the same `items` + `mapItem` pattern
+- [Dialog](./dialog.md) — the modal shell `TreePicker` composes

package/skills/app-shell-patterns/references/components/with-guard.md

@@ -18,14 +18,14 @@ import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";
 ## Basic Usage
 
 ```tsx
-import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";
+import { WithGuard, pass, hidden, Text } from "@tailor-platform/app-shell";
 
 const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());
 
 function AdminPanel() {
   return (
     <div>
-      <h1>Dashboard</h1>
+      <Text.h1>Dashboard</Text.h1>
 
       <WithGuard guards={[isAdmin]}>
         <Button>Delete All Users</Button>
@@ -113,7 +113,7 @@ const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass()
 Show alternative content when guard fails:
 
 ```tsx
-<WithGuard guards={[isAdmin]} fallback={<p>You need admin access to view this.</p>}>
+<WithGuard guards={[isAdmin]} fallback={<Text.p>You need admin access to view this.</Text.p>}>
   <AdminPanel />
 </WithGuard>
 ```
@@ -212,8 +212,8 @@ const isPremium = ({ context }) =>
   guards={[isPremium]}
   fallback={
     <Card>
-      <h3>Premium Feature</h3>
-      <p>Upgrade to access advanced analytics.</p>
+      <Text.h3>Premium Feature</Text.h3>
+      <Text.p>Upgrade to access advanced analytics.</Text.p>
       <Button>Upgrade Now</Button>
     </Card>
   }

package/skills/app-shell-patterns/references/concepts/authentication.md

@@ -250,7 +250,7 @@ const AuthGate = () => {
   if (error) {
     return (
       <div>
-        <p>Sign-in failed: {error}</p>
+        <Text.p>Sign-in failed: {error}</Text.p>
         <button onClick={() => void login()}>Try again</button>
       </div>
     );

package/skills/app-shell-patterns/references/concepts/routing-navigation.md

@@ -131,7 +131,7 @@ Reach for `TestRouter` when the component under test is the subject; mount `AppS
 ## Example
 
 ```tsx
-import { useNavigate, useParams, useLocation, Link } from "@tailor-platform/app-shell";
+import { useNavigate, useParams, useLocation, Link, Text } from "@tailor-platform/app-shell";
 
 const MyComponent = () => {
   const navigate = useNavigate();
@@ -145,8 +145,8 @@ const MyComponent = () => {
 
   return (
     <div>
-      <p>Current path: {location.pathname}</p>
-      <p>Route param ID: {id}</p>
+      <Text.p>Current path: {location.pathname}</Text.p>
+      <Text.p>Route param ID: {id}</Text.p>
 
       {/* Client-side link */}
       <Link to="/products">View Products</Link>

package/skills/app-shell-patterns/references/concepts/sidebar-navigation.md

@@ -69,16 +69,18 @@ const App = () => (
 ### SidebarItem
 
 A navigation item that automatically resolves title and icon from resource definitions.
+Active internal sidebar links expose `aria-current="page"` on the link itself, including
+items with custom `render` content. Inactive and external links do not expose it.
 
 #### Props
 
-| Prop       | Type              | Required | Description                                                                     |
-| ---------- | ----------------- | -------- | ------------------------------------------------------------------------------- |
-| `to`       | `string`          | Yes      | Target URL. External URLs (http://...) are rendered as external links           |
-| `title`    | `LocalizedString` | No       | Override title (i18n supported). When omitted, auto-resolved from resource meta |
-| `icon`     | `ReactNode`       | No       | Override icon. When omitted, auto-resolved from resource meta                   |
-| `external` | `boolean`         | No       | Opens link in new tab with external link icon                                   |
-| `render`   | `function`        | No       | Custom render function for full UI control                                      |
+| Prop       | Type              | Required | Description                                                                                                                      |
+| ---------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `to`       | `string`          | Yes      | Target URL. External URLs (http://...) are rendered as external links                                                            |
+| `title`    | `LocalizedString` | No       | Override title (i18n supported). When omitted, auto-resolved from resource meta                                                  |
+| `icon`     | `ReactNode`       | No       | Override icon. When omitted, auto-resolved from resource meta; with no icon at all, the icon rail shows the title's first letter |
+| `external` | `boolean`         | No       | Opens link in new tab with external link icon                                                                                    |
+| `render`   | `function`        | No       | Custom render function for full UI control                                                                                       |
 
 #### Examples
 
@@ -124,13 +126,13 @@ A collapsible group for organizing navigation items.
 
 #### Props
 
-| Prop          | Type              | Required | Description                                    |
-| ------------- | ----------------- | -------- | ---------------------------------------------- |
-| `title`       | `LocalizedString` | Yes      | Group title (supports i18n)                    |
-| `icon`        | `ReactNode`       | No       | Group icon                                     |
-| `to`          | `string`          | No       | When specified, title becomes a clickable link |
-| `defaultOpen` | `boolean`         | No       | Initial expanded state. Default: `true`        |
-| `children`    | `ReactNode`       | Yes      | Child items (SidebarItem, SidebarGroup, etc.)  |
+| Prop          | Type              | Required | Description                                                            |
+| ------------- | ----------------- | -------- | ---------------------------------------------------------------------- |
+| `title`       | `LocalizedString` | Yes      | Group title (supports i18n)                                            |
+| `icon`        | `ReactNode`       | No       | Group icon. When omitted, the icon rail shows the title's first letter |
+| `to`          | `string`          | No       | When specified, title becomes a clickable link                         |
+| `defaultOpen` | `boolean`         | No       | Initial expanded state. Default: `true`                                |
+| `children`    | `ReactNode`       | Yes      | Child items (SidebarItem, SidebarGroup, etc.)                          |
 
 #### Examples
 

package/skills/app-shell-patterns/references/concepts/styling-theming.md

@@ -217,7 +217,13 @@ Each intent has eight roles. The intents are `info`, `success`, `warning`, `dang
 <span className="rounded-md bg-success-surface px-2 py-0.5 text-success-text">Paid</span>
 ```
 
-In the default palette, `text` on `surface` and `contrast` on `solid` and `solid-hover` are at least 4.5:1 for the four hue intents, in light and dark mode, on `--card` and `--background`. A unit test checks this from the shipped CSS. `text` on `surface-hover` is held at 4.2:1 by the same test; it is below 4.5:1 for `danger` and `success` in light mode. The test does not cover the `cream` and `bloom` palettes or the `neutral` intent.
+The hue roles have the same values in every shipped palette. `cream` and `bloom` change brand and surface colors, not status colors. The `neutral` roles follow the palette, because they read the system tokens.
+
+**Contrast.** AppShell's thresholds are 4.5:1 for text (WCAG 1.4.3) and 3:1 for non-text (WCAG 1.4.11). In every shipped palette (`default`, `cream`, `bloom`), in light and dark mode, on `--card` and `--background`, `text` on `surface` and `contrast` on `solid` and `solid-hover` are at least 4.5:1 for all five intents, `text` on `surface-hover` is at least 4.5:1 for `neutral`, and `danger` `solid` (the invalid-input border) is at least 3:1. A browser test checks this in Chromium against the built stylesheet. Known exceptions:
+
+- `text` on `surface-hover` is below 4.5:1 for `danger` and `success` in light mode. This is on purpose: a lighter step would make the tinted background hard to tell apart from the page, and the hover harder to see. The test holds it at 4.2:1 or more.
+- In `cream` and `bloom`, the main content area is transparent over the shell gradient. At the top of the `bloom` light gradient, `text` on `surface` is 4.49:1 for `success` and 4.48:1 for `danger`. Put status content on a card when it needs to pass.
+- `warning` `solid` and `indicator` are 2.15:1 against a light card. Use them with a label, not as the only sign of a state.
 
 Most `surface` and `border` values are translucent tints, so an opacity modifier compounds rather than replaces — `bg-info-surface/50` halves the tint's alpha instead of setting it to 50%. Some light-mode values are opaque instead of translucent: the `warning` surface, surface-hover and border, the `info` border and the `danger` surface-hover. They do not blend with a tinted parent. All dark-mode values are translucent.
 
@@ -227,7 +233,7 @@ Most `surface` and `border` values are translucent tints, so an opacity modifier
 
 `--sidebar`, `--sidebar-foreground`, `--sidebar-border`, `--sidebar-primary(-foreground)`, `--sidebar-accent(-foreground)`, `--sidebar-ring` → `bg-sidebar`, `text-sidebar-foreground`, and so on. These let a palette tint the shell independently of page content.
 
-`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series.
+`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series. They tell series apart and carry no status, so they are not semantic roles and have literal values.
 
 #### Alerts
 
@@ -283,7 +289,7 @@ There are 8 core roles and 2 relaxed body variants:
 | `heading-sm`      | `text-heading-sm`      | 14px / 20px        | 600    | Sub-section heading                             |
 | `body-md`         | `text-body-md`         | 14px / 20px        | 400    | Body copy, descriptions                         |
 | `body-sm`         | `text-body-sm`         | 12px / 16px        | 400    | Caption, timestamp, metadata                    |
-| `label-md`        | `text-label-md`        | 14px / 20px        | 500    | Field label, short UI text, figures in a table  |
+| `label-md`        | `text-label-md`        | 14px / 20px        | 500    | Field label, short UI text                      |
 | `label-sm`        | `text-label-sm`        | 12px / 16px        | 500    | Small label, badge text                         |
 | `code-sm`         | `text-code-sm`         | 12px / 18px        | 400    | ID and code. Use with `font-mono`               |
 | `body-md-relaxed` | `text-body-md-relaxed` | 14px / 24px        | 400    | Long text, such as a chat message or a document |
@@ -301,7 +307,7 @@ Pair a role with a color token from the Color section above. These pairings are
 | Body copy                         | `text-body-md`                                 |
 | Secondary copy, descriptions      | `text-body-md text-muted-foreground`           |
 | Caption, timestamp, metadata      | `text-body-sm text-muted-foreground`           |
-| Numeric value in a table or field | `text-label-md tabular-nums`                   |
+| Numeric value in a table or field | `text-body-md tabular-nums`                    |
 | ID, code                          | `font-mono text-code-sm text-muted-foreground` |
 
 <example-preview name="typography-roles"></example-preview>
@@ -404,20 +410,21 @@ function TypographyRoles() {
 }
 ```
 
+For headings, body copy, labels, and captions, use the [`Text`](../components/text.md) component. Do not style a bare `p`, `h1` to `h6`, or `span` with `text-sm`, `text-xs`, or `font-*`. The `prefer-text-components` rule in `@tailor-platform/eslint-plugin-app-shell` reports a size on these elements, and a weight, line height, or letter spacing that is set without a role. It is not in `recommended`, so enable it in your `oxlint.config.ts`. A form field label is [`Field.Label`](../components/form.md), which already has the `label-md` role. `Text` applies the same roles with a `variant` prop. It renders a default element for each role (`h2` for headings, `p` for body text, `span` for the others). To set the element, such as the heading level, use an element component (`Text.h1` to `Text.h6`, `Text.p`, `Text.span`, `Text.div`):
+
 ```tsx
-<h2 className="text-heading-md">Section</h2>
-<p className="text-body-md text-muted-foreground">Description copy</p>
-<span className="text-body-sm text-muted-foreground">Updated 2h ago</span>
+<Text.h3 variant="heading-md">Line items</Text.h3>
+<Text variant="body-md" className="text-muted-foreground">Description copy</Text>
+<Text variant="body-sm" className="text-muted-foreground">Updated 2h ago</Text>
 ```
 
-The [`Text`](../components/text.md) component applies the same roles with a `variant` prop. It renders a default element for each role (`h2` for headings, `p` for body text, `span` for the others), and its `render` prop sets the element, such as the heading level:
+Use the role utility when you style an element that you render yourself, such as a table header cell or a link:
 
 ```tsx
-<Text variant="heading-md" render={<h3 />}>Line items</Text>
-<Text variant="body-md" className="text-muted-foreground">Description copy</Text>
+<th className="text-label-md text-muted-foreground">Amount</th>
 ```
 
-On an `h1` to `h6` element, the `cream` and `bloom` palettes replace the role's line height and letter spacing, including `leading-none`; see "Change a role" below. AppShell's own components still use the stock utilities (`text-sm`, `font-medium`, and so on) today. They will move to the roles in later changes, so the two sets can appear side by side for now.
+On an `h1` to `h6` element, the `cream` and `bloom` palettes replace the role's line height and letter spacing, including `leading-none`; see "Change a role" below. AppShell's own components use the roles: content text renders with `Text`, and controls use the role utility.
 
 **Rules**
 
@@ -522,21 +529,22 @@ Always give motion a reduced-motion escape (`motion-reduce:transition-none`, or
 
 ### Z-index
 
-These exist as raw `:root` variables in the shipped base layer, but are **not** bridged into Tailwind — `z-sidebar` is not a class. Use the stock numeric utility, or reference the variable when you need it to track AppShell's layering:
+These exist as raw `:root` variables in the shipped base layer, but are **not** bridged into Tailwind — `z-nav` is not a class. Use the stock numeric utility, or reference the variable when you need it to track AppShell's layering:
+
+| Token        | Value | Use                                                   |
+| ------------ | ----- | ----------------------------------------------------- |
+| `--z-nav`    | 10    | persistent sidebar                                    |
+| `--z-portal` | 50    | menu, tooltip, popover, modal, sheet, dialog backdrop |
+| `--z-toast`  | 100   | toast, always above overlays                          |
 
-| Token              | Value | Use                           |
-| ------------------ | ----- | ----------------------------- |
-| `--z-sidebar`      | 10    | persistent sidebar            |
-| `--z-sidebar-rail` | 20    | sidebar collapsed rail        |
-| `--z-popup`        | 50    | menu, tooltip, popover        |
-| `--z-overlay`      | 50    | modal, sheet, dialog backdrop |
+The old names still resolve: `--z-sidebar` is an alias of `--z-nav`, and `--z-popup` and `--z-overlay` are aliases of `--z-portal`. They are deprecated and will be removed in the next major. `--z-sidebar-rail` (20) is a value inside the sidebar, not a layer.
 
 ```tsx
 <div className="z-50" />
-<div className="z-[var(--z-popup)]" />
+<div className="z-[var(--z-portal)]" />
 ```
 
-Never invent a z value — `z-index: 9999` is always wrong. Popups and overlays share `50` intentionally: sequencing comes from DOM order, not z escalation.
+Never invent a z value — `z-index: 9999` is always wrong. Popups and overlays share `50` intentionally: sequencing comes from DOM order, not z escalation. Every floating AppShell component (dialog, sheet, menu, select, combobox, tooltip, toast) renders through a portal to the end of `body`, and the layout root is `isolation: isolate`, so a z-index inside the page never reaches them. The toast is the one layer above the band: it is always visible over an open dialog or sheet.
 
 ### Icons
 

package/skills/app-shell-patterns/references/migrations.md

@@ -10,6 +10,7 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 
 | Version       | Change                                                                                                                       |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| 1.20.0        | [z-index tokens renamed; old names are aliases](#1200-z-index-tokens-renamed-old-names-are-aliases)                          |
 | 1.18.0        | [Destructive colours now resolve to the danger roles](#1180-destructive-colours-now-resolve-to-the-danger-roles)             |
 | 1.17.0        | [Status and alert tokens now resolve to the colour roles](#1170-status-and-alert-tokens-now-resolve-to-the-colour-roles)     |
 | 1.15.0        | [Base UI 1.8.0 breaks closed-`Select` and dialog-click tests](#1150-base-ui-180-breaks-closed-select-and-dialog-click-tests) |
@@ -23,6 +24,25 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 | 1.0.2         | [`Toaster` no longer accepts `richColors`](#102-toaster-no-longer-accepts-richcolors)                                        |
 | before 1.0    | [Pre-1.0 breaking changes](#before-10)                                                                                       |
 
+## 1.20.0: z-index tokens renamed; old names are aliases
+
+**Applies to:** apps whose theme overrides `--z-sidebar`, `--z-sidebar-rail`, `--z-popup` or `--z-overlay`, and apps that reference those names on their own elements.
+
+1.20.0 names the z-index tokens by layer: `--z-nav` (10), `--z-portal` (50) and `--z-toast` (100). The old names keep working: `--z-sidebar` is now `var(--z-nav)`, and `--z-popup` and `--z-overlay` are both `var(--z-portal)`. They are deprecated and will be removed in the next major. Nothing errors, and nothing moves. Two things change silently:
+
+- **Themes that override an old name no longer reach the components.** The sidebar reads `--z-nav`; dialogs, sheets, menus, selects, comboboxes and tooltips read `--z-portal`. An override of `--z-popup` or `--z-overlay` still changes `z-[var(--z-popup)]` on your own elements, but not AppShell's layers. There is one token for the whole portal band because popups and overlays share the value on purpose: the order inside the band is the order of opening, so a `Select` inside a `Dialog` is above it. Raising one above the other puts a `Select` or `Menu` opened inside a `Dialog` behind the dialog.
+- **`--z-sidebar-rail` is no longer read by AppShell.** The sidebar rail orders itself inside the sidebar. The variable is still declared (20) for elements of your own that reference it, and it leaves the documented table.
+
+How to detect it: search the app for `--z-sidebar`, `--z-popup` and `--z-overlay` in class names and in theme CSS. Open a `Dialog` with a `Select` inside it, a `Dialog` over a `Sheet`, and fire a toast over each after upgrading; the order should not change.
+
+What to change:
+
+- Replace `--z-sidebar` with `--z-nav`, and `--z-popup` and `--z-overlay` with `--z-portal`, in class names such as `z-[var(--z-portal)]` and in theme CSS.
+- In a theme that moves AppShell's layers, set `--z-nav`, `--z-portal` or `--z-toast` instead of the old names. Remove the old names from the theme.
+- Do not set `--z-sidebar-rail`; it no longer affects the rail.
+
+The tokens are documented in [Styling & theming](https://github.com/tailor-platform/app-shell/blob/main/docs/concepts/styling-theming.md#z-index). The decision record is `decisions/floating-ui-stacking.md`.
+
 ## 1.18.0: destructive colours now resolve to the danger roles
 
 **Applies to:** apps that show `Button variant="destructive"` in dark mode, apps that use `text-destructive`, `border-destructive` or `bg-destructive` on their own elements, and apps whose theme overrides `--destructive` or `--destructive-foreground`.
@@ -33,7 +53,7 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 - **`text-destructive` resolves to the solid.** In dark mode it changes from `#f87171` to `#dc2626`, which is 3.71:1 on the dark card, below 4.5:1 for text. Components shipped with AppShell now use `text-danger-text` for error text, and invalid borders and focus rings read `--danger-solid`. In dark mode the invalid border changes from `#f87171` to `#dc2626`.
 - **Themes that override `--destructive` no longer reach the components.** `Button`, invalid `Input`, `Textarea`, `Checkbox`, `Field` and `DateField` borders and rings, error text and the `CsvImporter` error cells read `--danger-*`. An override of `--destructive` still changes `bg-destructive` and `text-destructive` on your own elements, so the two reds can drift apart. The `cream` and `bloom` palettes no longer set `--destructive`; their values were the same as the default.
 
-How to detect it: search the app for `destructive` in class names and in theme CSS, including Theme Generator output that sets `--destructive`. Compare `Button variant="destructive"`, an invalid `Input` and an error message in light and dark mode after upgrading.
+How to detect it: search the app for `destructive` in class names and in theme CSS, including Theme Generator output that sets `--destructive`. In JS and TS files, the `no-deprecated-tokens` rule in `@tailor-platform/eslint-plugin-app-shell` reports these names and the role to use instead. The rule is available from version 0.2.0 of the plugin, and it does not read CSS files. Compare `Button variant="destructive"`, an invalid `Input` and an error message in light and dark mode after upgrading.
 
 What to change:
 
@@ -53,7 +73,7 @@ The roles are documented in [Styling & theming](https://github.com/tailor-platfo
 - **Component recolouring moves to the roles.** `Badge`, `Alert`, `CsvImporter` and `MetricCard` read the roles directly. A theme that overrides `--status-*` or `--alert-*` no longer changes these components; override `--{intent}-*` instead. `Badge` `error` / `subtle-error` and `Alert` `error` read `--danger-*`, so overriding `--destructive` no longer reaches them either. `Button variant="destructive"` and `text-destructive` still follow `--destructive`.
 - **`text-status-*` loses contrast in dark mode.** The `--status-*` values are now the step-9 fills, which are below 4.5:1 as text on the dark card.
 
-How to detect it: search the app for `status-`, `alert-` and theme overrides of `--status-`, `--alert-` and `--destructive`. Compare `Badge` and `Alert` in light and dark mode after upgrading.
+How to detect it: search the app for `status-`, `alert-` and theme overrides of `--status-`, `--alert-` and `--destructive`. In JS and TS files, the `no-deprecated-tokens` rule in `@tailor-platform/eslint-plugin-app-shell` reports these names and the role to use instead. The rule is available from version 0.2.0 of the plugin, and it does not read CSS files. Compare `Badge` and `Alert` in light and dark mode after upgrading.
 
 What to change: