@tailor-platform/app-shell 1.19.0 → 1.20.0

package/skills/app-shell-patterns/references/components/sidebar-layout.md

@@ -48,12 +48,13 @@ This gives you:
 
 ### Common props
 
-| Prop          | Type              | Default                            | Description                                                                                                  |
-| ------------- | ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `sidebar`     | `React.ReactNode` | `<SidebarLayout.DefaultSidebar />` | Replaces the entire sidebar region.                                                                          |
-| `defaultOpen` | `boolean`         | `true`                             | Whether the sidebar starts expanded on desktop.                                                              |
-| `collapsible` | `boolean`         | `true`                             | Whether the sidebar can be collapsed. When `false`, toggle controls are hidden and `defaultOpen` is ignored. |
-| `topBar`      | `React.ReactNode` | -                                  | Full-width bar above both the sidebar and the content region.                                                |
+| Prop               | Type                                                         | Default                            | Description                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sidebar`          | `React.ReactNode`                                            | `<SidebarLayout.DefaultSidebar />` | Replaces the entire sidebar region.                                                                                                                |
+| `defaultOpen`      | `boolean`                                                    | `true`                             | Whether the sidebar starts expanded on desktop. Ignored in `"fixed"` and `"resize"` modes.                                                         |
+| `sidebarBehaviour` | `"fixed" \| "collapse" \| "resize" \| "collapse-and-resize"` | `"collapse-and-resize"`            | Selects the permitted desktop operations. Mobile/tablet drawer access is independent of this setting.                                              |
+| `collapsible`      | `boolean`                                                    | -                                  | Deprecated compatibility prop: explicit `false` maps to `"fixed"` and explicit `true` to `"collapse"`. Cannot be combined with `sidebarBehaviour`. |
+| `topBar`           | `React.ReactNode`                                            | -                                  | Full-width bar above both the sidebar and the content region.                                                                                      |
 
 ### Default content mode
 
@@ -74,6 +75,61 @@ Use this when you need to compose your own columns beside the sidebar.
 
 `body` is mutually exclusive with `header` and `children`, because it replaces the region those props normally describe.
 
+## Resizing the sidebar
+
+`sidebarBehaviour` selects the desktop operations. It defaults to `"collapse-and-resize"`:
+
+| Mode                    | Collapse | Resize |
+| ----------------------- | -------- | ------ |
+| `"fixed"`               | No       | No     |
+| `"collapse"`            | Yes      | No     |
+| `"resize"`              | No       | Yes    |
+| `"collapse-and-resize"` | Yes      | Yes    |
+
+```tsx
+<SidebarLayout />; // Both operations are enabled by default
+<SidebarLayout sidebarBehaviour="fixed" />;
+<SidebarLayout sidebarBehaviour="collapse" />;
+<SidebarLayout sidebarBehaviour="resize" />;
+<SidebarLayout sidebarBehaviour="collapse-and-resize" />;
+```
+
+`"fixed"` and `"resize"` always keep the desktop sidebar expanded, ignore `defaultOpen`, and make `useAppShellSidebar().setOpen()` inert. They hide desktop collapse controls and do not intercept the desktop toggle shortcut. `"collapse"` has toggle controls but no resize handle.
+
+All modes keep the layout's normal mobile/tablet drawer and icon-rail overlay presentation. The trigger, `toggle()`, and shortcut can still open the full menu when desktop collapsing is disabled. These responsive visibility states are independent of desktop expansion.
+
+### Deprecated `collapsible`
+
+The existing boolean remains supported but is deprecated. Explicit `false` maps to `"fixed"`; explicit `true` maps to `"collapse"`. Omitting both props uses the new `"collapse-and-resize"` default. TypeScript rejects specifying both props together.
+
+```tsx
+// Before
+<SidebarLayout collapsible={false} />;
+
+// After
+<SidebarLayout sidebarBehaviour="fixed" />;
+```
+
+This intentionally changes the responsive presentation of legacy `collapsible={false}`: it no longer forces a fixed sidebar on mobile/tablet. It keeps desktop fixed while using the normal responsive drawer/overlay. A completely custom `sidebar` still owns its own presentation and sizing.
+
+### Resize interaction
+
+The initial width is 256px. In `"resize"` and `"collapse-and-resize"` modes, the whole outer edge of the expanded desktop sidebar is a resize handle. Hovering it shows the resize cursor and a small pill beside the border that follows the pointer. Drag the edge, or focus the handle and use Left/Right arrows (16px steps), Home, or End (480px). Double-click restores the default 256px width.
+
+In `"resize"` mode, dragging follows the pointer and clamps to 192–480px without collapse resistance. Home and Left at the minimum keep the sidebar at 192px; double-clicking at 256px does not collapse it.
+
+In `"collapse-and-resize"` mode, Home or Left at the minimum collapses the sidebar, and double-clicking at 256px collapses it. The collapsed desktop sidebar keeps its handle. Double-clicking it or using Enter/Space restores 256px; a single pointer click does nothing.
+
+In `"collapse-and-resize"` mode, dragging uses a position-based resistance curve, not a delayed CSS transition. Between the collapsed width and the minimum expanded width (192px), most of the interval uses a 25% movement gain: moving the pointer 10px moves the edge only 2.5px. In the final quarter near the opposite boundary, a smooth position-based blend catches up to the pointer. The edge stops when the pointer stops; it does not catch up over time. At 192px and above it follows the pointer 1:1, up to 480px. Shrinking through the same range resists toward the collapsed position. It collapses slightly early, when the pointer enters the final 20% of that interval, with the curve already meeting the collapsed width at that point. The same pointer stays captured across both transitions, without a jump to 256px.
+
+With collapsing enabled, releasing inside the resistance range settles back to the current mode's boundary (collapsed width or 192px).
+
+Live drag pixels are applied through CSS custom properties rather than React state on every pointer movement. React commits the width at mode changes and when the gesture ends; ARIA values stay current during dragging. Width changes still require browser layout because the content column resizes live.
+
+Width is not persisted across remounts or reloads. The icon rail keeps its existing collapsed width. Mobile drawers and tablet overlays keep their existing widths and do not show handles.
+
+This applies to the built-in sidebar primitives, including `SidebarLayout.DefaultSidebar`. An arbitrary custom `sidebar` element still owns its own sizing.
+
 ## Extending the built-in header
 
 The supported "small customization" path is to pass `SidebarLayout.DefaultHeader` into the `header` slot and fill its `actions` cluster.
@@ -162,26 +218,33 @@ Use `body` when the stock content column is too restrictive and you need your ow
 
 ## Reading and controlling the sidebar
 
-Use `useAppShellSidebar()` to read and control the sidebar state instead of observing internal DOM attributes or clicking the trigger through the DOM.
+Use `useAppShellSidebar()` to read and control the sidebar state instead of observing internal DOM attributes or clicking the trigger through the DOM. It also exposes the effective `sidebarBehaviour`, already normalized from either public prop, so custom sidebars do not need to handle the deprecated boolean themselves.
+
+`open` and `setOpen()` describe desktop expansion. Drawer visibility is separate: `toggle()` selects the mobile drawer, tablet overlay, or desktop state according to the viewport. The four existing hook fields (`open`, `isMobile`, `setOpen`, and `toggle`) remain available.
 
 ```tsx
 import { useAppShellSidebar } from "@tailor-platform/app-shell";
 
 function CustomHeader() {
-  const { open, isMobile, toggle } = useAppShellSidebar();
+  const { sidebarBehaviour, open, isMobile, toggle } = useAppShellSidebar();
 
   return (
     <div className="flex items-center justify-between border-b px-4 py-3">
       <button type="button" onClick={toggle}>
-        {open ? "Hide navigation" : "Show navigation"}
+        Toggle navigation
       </button>
-      <span>{isMobile ? "Mobile" : "Desktop"}</span>
+      <span>
+        {sidebarBehaviour}: {open ? "Desktop expanded" : "Desktop collapsed"}
+      </span>
+      <span>{isMobile ? "Mobile" : "Non-mobile"}</span>
     </div>
   );
 }
 ```
 
-Outside `SidebarLayout`, the hook returns a safe fallback (`open: true`, `isMobile: false`, no-op setters) rather than throwing.
+Outside `SidebarLayout`, the hook returns a safe fallback (`sidebarBehaviour: "fixed"`, `open: true`, `isMobile: false`, no-op actions) rather than throwing. This fallback describes the absence of a managed sidebar; it is not the layout's default mode.
+
+The desktop capabilities can be derived from the reported mode: `"collapse"` and `"collapse-and-resize"` permit collapse, while `"resize"` and `"collapse-and-resize"` permit resizing. Reading this setting does not automatically add resize behavior to arbitrary custom markup.
 
 ## Reusing the built-in breadcrumb
 

package/skills/app-shell-patterns/references/components/sidebar-section.md

@@ -90,14 +90,14 @@ const labels = defineI18nLabels({
 - The items belong under a parent with its own icon (or landing page via `to`)
 - You need nesting
 
-| Feature             | SidebarSection    | SidebarGroup              |
-| ------------------- | ----------------- | ------------------------- |
-| **Collapsible**     | ❌ No             | ✅ Yes                    |
-| **Heading is link** | ❌ No             | Optional (`to` prop)      |
-| **Icon**            | ❌ No             | Optional                  |
-| **Child styling**   | Same as top level | Indented submenu          |
-| **Icon rail**       | Heading hidden    | Group icon opens a flyout |
-| **Nesting**         | Not intended      | Can contain groups        |
+| Feature             | SidebarSection    | SidebarGroup                                       |
+| ------------------- | ----------------- | -------------------------------------------------- |
+| **Collapsible**     | ❌ No             | ✅ Yes                                             |
+| **Heading is link** | ❌ No             | Optional (`to` prop)                               |
+| **Icon**            | ❌ No             | Optional                                           |
+| **Child styling**   | Same as top level | Indented submenu                                   |
+| **Icon rail**       | Heading hidden    | Group icon opens a flyout (hover, or tap on touch) |
+| **Nesting**         | Not intended      | Can contain groups                                 |
 
 ## Accessibility
 

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

@@ -41,7 +41,7 @@ function BasicUsage() {
 | Sub-component | Description                                                    |
 | ------------- | -------------------------------------------------------------- |
 | `Tabs.Root`   | Manages tab selection state                                    |
-| `Tabs.List`   | Groups the individual tab buttons                              |
+| `Tabs.List`   | Groups the individual tab buttons on one scrolling row         |
 | `Tabs.Tab`    | An interactive tab button that toggles the corresponding panel |
 | `Tabs.Panel`  | A panel displayed when the corresponding tab is active         |
 
@@ -61,7 +61,9 @@ function BasicUsage() {
 
 ### Tabs.List Props
 
-Accepts `className` and all standard HTML `<div>` props.
+Accepts `className` and all standard HTML `<div>` props except `render`. The
+HTML props apply to the `tablist` element, which is also the scroll container;
+`className` applies to the visual track inside it (see [Overflow](#overflow)).
 
 ### Tabs.Tab Props
 
@@ -96,6 +98,34 @@ const [activeTab, setActiveTab] = useState("overview");
 </Tabs.Root>;
 ```
 
+## Overflow
+
+Tabs stay on one row. When they are wider than the space available, the list
+scrolls sideways instead of wrapping or growing the page. The scrollbar is
+hidden: touch, a trackpad, Shift + mouse wheel, and the arrow keys scroll it,
+and the tab cut off at the edge shows that there is more. Base UI scrolls the
+active tab into view when the tabs mount, and scrolls the tab that the arrow
+keys, Home or End move focus to into view, so keyboard navigation never lands
+on a hidden tab. Nothing changes while the tabs fit.
+
+To make this work, the `tablist` element (`data-slot="tabs-list"`) is the
+scroll container, and the tabs sit in a visual track inside it
+(`data-slot="tabs-list-track"`) that carries the variant styles and your
+`className`. The scroll container has 4px of padding, a matching negative
+margin and the same `scroll-padding`, so the tabs' focus ring is not clipped
+and the list keeps its footprint. A `Tabs.List` placed next to inline content
+starts on its own line.
+
+Two cases are not scrolled into view automatically: a tab selected by changing
+a controlled `value` from outside (a deep link, for example), and a list that
+mounts while hidden, such as inside a closed dialog. Call
+`scrollIntoView({ inline: "nearest", block: "nearest" })` on the tab if you
+need either.
+
+Scrolling keeps every tab reachable, but it does not shorten the list. If a
+list regularly overflows at the widths your users have, prefer fewer tabs or
+another control, such as a `Select`, over relying on the scroll.
+
 ## Examples
 
 ### With Disabled Tab

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>