@tailor-platform/app-shell 1.18.0 → 1.20.0

package/skills/app-shell-patterns/references/components/date-picker.md

@@ -56,7 +56,7 @@ With a visible label + description:
   aria-labelledby="invoice-date-label"
   aria-describedby="invoice-date-help"
 />
-<p id="invoice-date-help">Format follows your locale</p>
+<Text.p id="invoice-date-help">Format follows your locale</Text.p>
 ```
 
 Inside `Field.Root`:
@@ -124,7 +124,7 @@ Use standard HTML + ARIA when rendering the field standalone:
   value={value}
   onChange={setValue}
 />
-{error && <p id="delivery-date-error">{error}</p>}
+{error && <Text.p id="delivery-date-error">{error}</Text.p>}
 ```
 
 Or let `Field.Root` wire the label, description, and error elements:

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

@@ -75,7 +75,7 @@ With `iconRail`, collapsing the sidebar keeps icons visible at every width:
 
 - on desktop, the sidebar collapses to a narrow persistent rail
 - on mobile, the rail stays visible and its toggle opens the full sidebar as a slide-in drawer
-- grouped items reveal child pages from the collapsed icon via a flyout popover
+- grouped items reveal child pages from the collapsed icon via a flyout popover: it opens on hover with a mouse, and on tap on a touch device (tap again, tap outside, or press `Escape` to close it). A group with its own page links to it from the flyout heading
 - items without children show their label in a tooltip
 
 [`GlobalHeaderLayout`](./global-header-layout.md) bakes this mode in through `GlobalHeaderLayout.DefaultSidebar`.
@@ -94,7 +94,7 @@ When the app title and primary toggle live in a full-width top bar, hide the sid
 function UserProfile() {
   return (
     <div className="border-t p-4">
-      <p className="text-sm font-medium">Ada Lovelace</p>
+      <Text.p variant="label-md">Ada Lovelace</Text.p>
       <button type="button" className="mt-2 text-sm text-muted-foreground">
         Logout
       </button>

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

@@ -68,6 +68,14 @@ function BasicUsage() {
 
 Accepts `className` and all standard HTML `<div>` props.
 
+## Tall Content
+
+`Dialog.Content` is never taller than the viewport minus 2rem (16px above and below, the same margin as on the sides). When the content is taller, the whole dialog scrolls, including the title and the close button. `Escape` and a click on the backdrop still close it.
+
+On open, focus moves to the first control in the dialog. In a dialog that scrolls, this happens only when that control is in view at the top. When it is below the fold (for example, a footer button after a long body), the dialog itself takes focus instead, so it opens at the top rather than scrolled to that control. `Tab` then moves to the control. Pass `initialFocus` to choose the element yourself.
+
+To keep a header or footer in view while only the body scrolls, make `Dialog.Content` a flex column and give the body `min-h-0 flex-1 overflow-y-auto`. A `className` with its own `max-h-*` or `overflow-*` replaces the defaults.
+
 ### Dialog.Trigger / Dialog.Close Props
 
 Accept a `render` prop for custom element rendering (Base UI render pattern), plus standard button props.

package/skills/app-shell-patterns/references/components/filter-rail.md

@@ -154,9 +154,16 @@ By default the button appears where the rail would have been. To put it somewher
     </Layout.Column>
     <Layout.Column area="main">
       <DataTable.Root value={table}>
-        <DataTable.Toolbar>
-          <FilterRail.Trigger />
-        </DataTable.Toolbar>
+        <Toolbar.Root>
+          <Toolbar.Row justify="between" aria-label="Table controls">
+            <Toolbar.Group>
+              <FilterRail.Trigger />
+            </Toolbar.Group>
+            <Toolbar.Group>
+              <DataTable.ColumnSettings />
+            </Toolbar.Group>
+          </Toolbar.Row>
+        </Toolbar.Root>
         <DataTable.Table />
       </DataTable.Root>
     </Layout.Column>

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

@@ -100,14 +100,14 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Sub-components
 
-| Sub-component       | Description                                                                                   |
-| ------------------- | --------------------------------------------------------------------------------------------- |
-| `Field.Root`        | Context boundary for a single field. Manages validation state.                                |
-| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                            |
-| `Field.Control`     | Styled `<input>`. Can be omitted when using a Base UI-backed AppShell component as the input. |
-| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                         |
-| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                     |
-| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.             |
+| Sub-component       | Description                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `Field.Root`        | Context boundary for a single field. Manages validation state.                                                         |
+| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                                                     |
+| `Field.Control`     | Styled text `<input>`. `Select`, `Combobox`, and the other self-wired controls go directly under `Field.Root` instead. |
+| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                                                  |
+| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                                              |
+| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.                                      |
 
 ### Field.Root Props
 
@@ -134,7 +134,17 @@ A compound component that groups all parts of a form field and manages its valid
 
 ### Using Another AppShell Component as the Control
 
-`Field.Control` can be omitted when using a Base UI-backed AppShell component (e.g. `Select`, `Combobox`). The component registers itself with the `Field` context automatically, inheriting label association and validation state.
+`Field.Control` is a text input. It is the control for plain text-like fields, and you can pass it a native element such as `render={<textarea />}`. The controls in the last row of the table below go **directly under `Field.Root`**, as a sibling of `Field.Label`. Each one registers itself with the `Field` context, so it gets label association, `aria-describedby`, `disabled`, and validation state without `Field.Control`.
+
+| Control                                                                                                                                                 | Where it goes                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Plain text, email, number, password, … input                                                                                                            | `<Field.Control type="…" />`                      |
+| Native element (`<textarea>`, `<input type="…">`)                                                                                                       | `<Field.Control render={<textarea />} />`         |
+| `Select`, `Combobox`, `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker`, `DateRangePicker` (and their `.Async`), `Tree` (checkbox mode) | Directly under `Field.Root` — not `Field.Control` |
+
+`Input` is the exception. It is a plain `<input>` that does not connect to `Field.Root`, so inside a field use `<Field.Control />` in its place.
+
+Do not pass the self-wired controls to `Field.Control`'s `render` prop. They draw their own frame, so `<Field.Control render={<Select />} />` renders a second border around the select. `Field.Control` also passes them `<input>` props they don't take. `Field.Control` logs a console warning when it is given one of these controls directly as an element. A wrapper component or the function form of `render` is not detected.
 
 ```tsx
 const [country, setCountry] = React.useState<string | null>(null);

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

@@ -58,17 +58,40 @@ function App() {
 
 ## Props
 
-| Prop          | Type                                                            | Default                                 | Description                                                      |
-| ------------- | --------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
-| `header`      | `React.ReactNode`                                               | `<GlobalHeaderLayout.DefaultHeader />`  | Replaces the full-width app header.                              |
-| `sidebar`     | `React.ReactNode`                                               | `<GlobalHeaderLayout.DefaultSidebar />` | Replaces the primary sidebar.                                    |
-| `defaultOpen` | `boolean`                                                       | `true`                                  | Whether the sidebar starts expanded on desktop.                  |
-| `collapsible` | `boolean`                                                       | `true`                                  | Whether the sidebar can be collapsed.                            |
-| `children`    | `(props: { Outlet: () => React.ReactNode }) => React.ReactNode` | current route outlet                    | Custom content renderer for the stock content container.         |
-| `body`        | `React.ReactNode`                                               | -                                       | Escape hatch that replaces the entire region beside the sidebar. |
+| Prop               | Type                                                            | Default                                 | Description                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `header`           | `React.ReactNode`                                               | `<GlobalHeaderLayout.DefaultHeader />`  | Replaces the full-width app header.                                                                                                                |
+| `sidebar`          | `React.ReactNode`                                               | `<GlobalHeaderLayout.DefaultSidebar />` | Replaces the primary sidebar.                                                                                                                      |
+| `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 without restricting mobile/tablet drawer access.                                                          |
+| `collapsible`      | `boolean`                                                       | -                                       | Deprecated compatibility prop: explicit `false` maps to `"fixed"` and explicit `true` to `"collapse"`. Cannot be combined with `sidebarBehaviour`. |
+| `children`         | `(props: { Outlet: () => React.ReactNode }) => React.ReactNode` | current route outlet                    | Custom content renderer for the stock content container.                                                                                           |
+| `body`             | `React.ReactNode`                                               | -                                       | Escape hatch that replaces the entire region beside the sidebar.                                                                                   |
 
 `children` and `body` are mutually exclusive. Use `body` when you need to add your own side columns around the main content.
 
+## Resizing the sidebar
+
+`sidebarBehaviour` selects the desktop operations and defaults to `"collapse-and-resize"`. The four modes are shared with [`SidebarLayout`](./sidebar-layout.md#resizing-the-sidebar):
+
+```tsx
+<GlobalHeaderLayout />; // Both operations are enabled by default
+<GlobalHeaderLayout sidebarBehaviour="fixed" />; // Neither operation
+<GlobalHeaderLayout sidebarBehaviour="collapse" />; // Collapse only
+<GlobalHeaderLayout sidebarBehaviour="resize" />; // Resize only
+<GlobalHeaderLayout sidebarBehaviour="collapse-and-resize" />; // Both
+```
+
+`"fixed"` and `"resize"` keep desktop expanded, ignore `defaultOpen`, and make the hook's `setOpen()` action inert. `"fixed"` has no desktop interaction controls; `"resize"` has a resize handle but no collapse controls. `"collapse"` has collapse controls but no resize handle. Desktop toggle shortcuts are not intercepted when collapsing is disabled.
+
+Every mode keeps the layout's normal responsive icon rail and mobile/tablet overlay, so the trigger, `toggle()`, and shortcut can still open the full menu. Desktop expansion and responsive drawer visibility are independent.
+
+`collapsible` remains supported but deprecated. Explicit `false` maps to `"fixed"`, explicit `true` maps to `"collapse"`, and omitting both props uses the new default. TypeScript rejects specifying both props. Replace legacy `collapsible={false}` with `sidebarBehaviour="fixed"`; it keeps desktop fixed but intentionally no longer forces a fixed sidebar on mobile/tablet.
+
+The edge resize handle and keyboard resizing match [`SidebarLayout`](./sidebar-layout.md#resizing-the-sidebar). Resize-only mode clamps pointer and keyboard widths to 192–480px without collapse resistance, and double-click only resets to 256px. With `"collapse-and-resize"`, dragging uses resistance near the rail and can open, resize, and collapse in one gesture; double-clicking at 256px collapses, and double-click or keyboard expansion restores 256px. Width is not saved across reloads. Responsive overlay widths and the collapsed rail width are unchanged.
+
+Custom sidebars can read the effective, normalized `sidebarBehaviour` through [`useAppShellSidebar()`](./sidebar-layout.md#reading-and-controlling-the-sidebar). Its existing state and actions remain available; arbitrary custom markup still owns its presentation and sizing.
+
 ## Built-in parts
 
 `GlobalHeaderLayout` exposes the same composition pieces as `SidebarLayout`, plus the opinionated header and sidebar defaults:

package/skills/app-shell-patterns/references/components/item-list.md

@@ -0,0 +1,191 @@
+---
+title: ItemList
+description: Compact icon-and-label lists for consistent navigation inside and outside the Sidebar
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/item-list.docs.outline.md — do not edit by hand. -->
+
+# ItemList
+
+`ItemList` presents compact icon-and-label rows for navigation and actions. Use it for in-content navigation, tables of contents, or other lists that should share the Sidebar's list presentation without depending on its layout or providers.
+
+It does not require `AppShell`, a router, or a Sidebar provider. Resource metadata, translations, permissions, and active-route matching remain the caller's responsibility.
+
+## Import
+
+```tsx
+import { ItemList } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  const [view, setView] = useState("Overview");
+  return (
+    <>
+      <ItemList.Root aria-label="Workspace">
+        <ItemList.Item
+          icon={<Home />}
+          isActive={view === "Overview"}
+          onClick={() => setView("Overview")}
+        >
+          Overview
+        </ItemList.Item>
+        <ItemList.Separator />
+        <ItemList.Section title="Business">
+          <ItemList.Item icon={<ShoppingCart />} onClick={() => setView("Orders")}>
+            Orders
+          </ItemList.Item>
+          <ItemList.Group title="Products" icon={<Package />}>
+            <ItemList.Item onClick={() => setView("All products")}>All products</ItemList.Item>
+            <ItemList.Item onClick={() => setView("Categories")}>Categories</ItemList.Item>
+          </ItemList.Group>
+        </ItemList.Section>
+      </ItemList.Root>
+      <output>Current view: {view}</output>
+    </>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component        | Description                                                                      |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `ItemList.Root`      | A semantic `ul`; accepts standard list props                                     |
+| `ItemList.Item`      | A compact icon-and-label row containing a button or supplied interactive element |
+| `ItemList.Group`     | A collapsible, indented child list; open by default                              |
+| `ItemList.Section`   | A labeled, non-collapsible list whose items retain their normal indentation      |
+| `ItemList.Separator` | A decorative divider that remains a valid list child                             |
+
+## Items, Links, and Actions
+
+`ItemList.Item` is for links and actions, not static rows. It requires `onClick`, `render`, or both; omitting both is a type error, including for a disabled Item. With `onClick`, it renders a `button` with `type="button"` by default. Supply an anchor or application link through `render` for navigation.
+
+`render` replaces the interactive element inside the row, not the containing `li`. `children` supplies its label, and `icon` supplies an optional decorative leading icon. Standard button props, classes, attributes, and refs apply to the inner operation. A disabled Item is skipped by Tab and cancels clicks, including navigation through a supplied link.
+
+<example-preview name="links-and-actions"></example-preview>
+
+```tsx
+function LinksAndActions() {
+  const [checks, setChecks] = useState(0);
+  const handleCheckNotifications = () => {
+    setChecks((count) => count + 1);
+  };
+  return (
+    <>
+      <ItemList.Root aria-label="Quick access">
+        <ItemList.Item icon={<Home />} render={<a href="https://example.com/help" />}>
+          Help center
+        </ItemList.Item>
+        <ItemList.Item icon={<Bell />} onClick={handleCheckNotifications}>
+          Check notifications
+        </ItemList.Item>
+      </ItemList.Root>
+      <output>Notification checks: {checks}</output>
+    </>
+  );
+}
+```
+
+For application navigation, use `Link` or `NavLink` from `@tailor-platform/app-shell` inside an AppShell-managed page. Do not import routing APIs directly from `react-router` or create a separate router around the list. The routes in this example belong to the documentation app; use your application's route paths in your own pages.
+
+<example-preview name="app-shell-routing"></example-preview>
+
+```tsx
+function AppShellRouting() {
+  return (
+    <ItemList.Root aria-label="Documentation pages">
+      <ItemList.Item render={<Link to="/components/button" />}>Button documentation</ItemList.Item>
+      <ItemList.Item render={<NavLink to="/components/item-list" end />}>
+        ItemList documentation
+      </ItemList.Item>
+    </ItemList.Root>
+  );
+}
+```
+
+`NavLink` owns route matching and supplies `aria-current="page"` when matched; ItemList styles that attribute with the same emphasis as `isActive`. Use `end` when only the exact destination should be current. With a plain link, the caller supplies `aria-current="page"` when appropriate.
+
+`isActive` remains a boolean for explicit visual emphasis, including local actions. It does not imply `aria-current`, selection state, a `listbox` role, or `aria-selected`. ItemList does not perform route matching.
+
+### Item Props
+
+| Prop        | Type                                   | Default | Description                                                        |
+| ----------- | -------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `icon`      | `ReactNode`                            | —       | Optional decorative leading icon                                   |
+| `children`  | `ReactNode`                            | —       | Compact row label                                                  |
+| `render`    | `ReactElement`                         | —       | Replaces the inner button; required unless `onClick` is supplied   |
+| `onClick`   | `MouseEventHandler<HTMLButtonElement>` | —       | Action handler; required unless `render` is supplied               |
+| `isActive`  | `boolean`                              | `false` | Explicit visual emphasis without route matching or selection state |
+| `disabled`  | `boolean`                              | —       | Disables clicks and removes the operation from the tab order       |
+| `className` | `string`                               | —       | Classes applied to the inner operation                             |
+
+Other standard button props, such as `title` and ARIA attributes, are forwarded to the inner operation. Put link-specific props such as `href`, `target`, and `rel` on the element passed to `render`.
+
+Rows without an `icon` do not reserve icon space. To align a mixed list, explicitly pass `icon={<span />}` on a row that needs an empty icon slot. Lists with no icons keep their compact indentation.
+
+## Groups and Heading Hierarchies
+
+`expandOnClick` defaults to `true`: clicking a group's heading toggles its child list, whether or not `render` is supplied. `render` only replaces the heading's main operation; it does not determine the expansion behavior. `defaultOpen` defaults to `true`; set it to `false` to start collapsed. Groups can be nested.
+
+Set `expandOnClick={false}` to separate the heading's main operation from expansion. This requires `onClick` or `render` so the heading does not become an inert button. A separate button, named by the group title, expands and collapses the group. Use this for linked headings so navigation does not toggle the list.
+
+`onClick` applies only to the heading's main operation. Clicking a child Item or the separate expand button does not invoke it. `isActive` and `aria-current="page"` control emphasis on the main heading operation, not the separate expand button.
+
+For a table of contents, use a linked Group for a parent heading and Items for its child headings. Keep the list data aligned with the actual heading hierarchy and anchor IDs in the document.
+
+<example-preview name="linked-group"></example-preview>
+
+```tsx
+function LinkedGroup() {
+  return (
+    <ItemList.Root aria-label="Contents">
+      <ItemList.Group
+        title="Installing"
+        render={<a href="#installing" aria-label="Installing" />}
+        expandOnClick={false}
+      >
+        <ItemList.Item render={<a href="#configuration" aria-label="Configuration" />}>
+          Configuration
+        </ItemList.Item>
+      </ItemList.Group>
+    </ItemList.Root>
+  );
+}
+```
+
+### Group Props
+
+| Prop            | Type                                   | Default | Description                                                                                       |
+| --------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `title`         | `ReactNode`                            | —       | Accessible group label, including text and optional decorations                                   |
+| `icon`          | `ReactNode`                            | —       | Optional decorative leading icon                                                                  |
+| `render`        | `ReactElement`                         | —       | Replaces the main heading operation without changing expansion behavior                           |
+| `onClick`       | `MouseEventHandler<HTMLButtonElement>` | —       | Handler for the main heading operation only                                                       |
+| `expandOnClick` | `boolean`                              | `true`  | Toggle from the heading; `false` requires `onClick` or `render` and adds a separate expand button |
+| `isActive`      | `boolean`                              | `false` | Explicit visual emphasis for the heading operation                                                |
+| `defaultOpen`   | `boolean`                              | `true`  | Initial uncontrolled expanded state                                                               |
+| `children`      | `ReactNode`                            | —       | Nested Items, Groups, Sections, or Separators                                                     |
+
+Other standard `li` props, including `className`, apply to the containing group item, not its heading operation. `onClick` is the exception described above.
+
+A Group's rendered label names its heading operation, separate expand button, and child list. Keep meaningful text in a rich `title`; ReactNode content is not converted into a string. Meaningful details such as counts can be read with the label, while purely decorative elements should use `aria-hidden="true"`. An icon-only title needs screen-reader text. Do not put links or buttons inside the title, because the heading itself is interactive.
+
+## Sections and Separators
+
+Use `Group` for hierarchy and `Section` for flat classification. A Section accepts a resolved string `title` and `children`, keeps child rows at their normal indentation, and does not add an interactive heading. Other standard `li` props apply to its outer item.
+
+Neither Group nor Section requires wrapping its children in another `ItemList.Root`. Use `ItemList.Separator` between logical runs of items; it is decorative and renders a list item rather than an invalid direct `div` child of `ul`.
+
+## Styling and Accessibility
+
+- Keep labels concise; they truncate in narrow containers.
+- Use `aria-label` or `aria-labelledby` on Root when a list needs an accessible name.
+- Native links and buttons retain their keyboard interactions. Group buttons announce their expanded state and support Enter and Space.
+- Resolve translations before passing labels; ItemList does not translate them. Group titles can contain ReactNode content, while Section titles remain strings.
+- ItemList is an ordinary list, not a menu or selection widget. It does not provide arrow-key selection, search, reordering, or Sidebar icon-rail behavior.
+- Existing Sidebar components retain route metadata resolution, rail tooltips and flyouts, and drawer dismissal while sharing the underlying list presentation.

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

@@ -26,12 +26,12 @@ function BasicUsage() {
   return (
     <Layout>
       <Layout.Column>
-        <h2>Main Content</h2>
-        <p>Your main content goes here...</p>
+        <Text.h2>Main Content</Text.h2>
+        <Text.p>Your main content goes here...</Text.p>
       </Layout.Column>
       <Layout.Column>
-        <h2>Sidebar</h2>
-        <p>Additional info or actions...</p>
+        <Text.h2>Sidebar</Text.h2>
+        <Text.p>Additional info or actions...</Text.p>
       </Layout.Column>
     </Layout>
   );
@@ -230,7 +230,7 @@ If any `Layout.Column` has an `area` prop, all columns switch to area-based widt
     <nav>Sidebar</nav>
   </Layout.Column>
   <Layout.Column area="main">
-    <h2>Content</h2>
+    <Text.h2>Content</Text.h2>
   </Layout.Column>
 </Layout>
 ```
@@ -246,9 +246,16 @@ By default, `<Layout>` grows with its content and the AppShell content area scro
   <Layout.Header title="Products" />
   <Layout.Column>
     <DataTable.Root value={table}>
-      <DataTable.Toolbar>
-        <DataTable.Filters />
-      </DataTable.Toolbar>
+      <Toolbar.Root>
+        <Toolbar.Row justify="between" aria-label="Product table controls">
+          <Toolbar.Group>
+            <DataTable.Filters />
+          </Toolbar.Group>
+          <Toolbar.Group>
+            <DataTable.ColumnSettings />
+          </Toolbar.Group>
+        </Toolbar.Row>
+      </Toolbar.Root>
       <DataTable.Table />
       <DataTable.Footer>
         <DataTable.Pagination />
@@ -310,12 +317,12 @@ function OrderDetailPage() {
       </Layout.Column>
       <Layout.Column>
         <Card>
-          <h3>Quick Actions</h3>
+          <Text.h3>Quick Actions</Text.h3>
           <Button fullWidth>Mark as Shipped</Button>
           <Button fullWidth>Send Invoice</Button>
         </Card>
         <Card>
-          <h3>Order History</h3>
+          <Text.h3>Order History</Text.h3>
           <Timeline events={order.history} />
         </Card>
       </Layout.Column>
@@ -333,7 +340,7 @@ function Dashboard() {
       <Layout.Header title="Dashboard" />
       <Layout.Column>
         <Card>
-          <h3>Navigation</h3>
+          <Text.h3>Navigation</Text.h3>
           <nav>
             <a href="#overview">Overview</a>
             <a href="#sales">Sales</a>
@@ -343,17 +350,17 @@ function Dashboard() {
       </Layout.Column>
       <Layout.Column>
         <Card>
-          <h2>Sales Overview</h2>
+          <Text.h2>Sales Overview</Text.h2>
           <Chart data={salesData} />
         </Card>
         <Card>
-          <h2>Recent Orders</h2>
+          <Text.h2>Recent Orders</Text.h2>
           <OrdersTable orders={recentOrders} />
         </Card>
       </Layout.Column>
       <Layout.Column>
         <Card>
-          <h3>Activity Feed</h3>
+          <Text.h3>Activity Feed</Text.h3>
           <ActivityList activities={activities} />
         </Card>
       </Layout.Column>
@@ -381,7 +388,7 @@ function ProductEditor() {
       />
       <Layout.Column>
         <Card>
-          <h3>Product Details</h3>
+          <Text.h3>Product Details</Text.h3>
           <Input
             label="Name"
             value={product.name}
@@ -402,7 +409,7 @@ function ProductEditor() {
       </Layout.Column>
       <Layout.Column>
         <Card>
-          <h3>Preview</h3>
+          <Text.h3>Preview</Text.h3>
           <ProductCard product={product} />
         </Card>
       </Layout.Column>
@@ -439,7 +446,7 @@ function EditorPage() {
   <Layout.Header title="Settings" actions={[<Button key="save">Save Changes</Button>]} />
   <Layout.Column>
     <Card>
-      <h3>Account Settings</h3>
+      <Text.h3>Account Settings</Text.h3>
       <SettingsForm />
     </Card>
   </Layout.Column>

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

@@ -161,6 +161,14 @@ type SelectAsyncFetcher<T> = (options: { signal: AbortSignal }) => Promise<T[]>;
 
 If the fetcher throws or rejects, `Select.Async` renders a built-in inline error state in the dropdown — the `errorText` message plus a **Retry** button that re-runs the fetch — instead of the misleading empty state. Aborted requests (the dropdown closed before the fetch settled) are ignored, and announcements are de-duped per outage. Pass `onFetchError` to run a side effect (logging, toast) — it fires once per outage and re-arms after the next successful fetch.
 
+## Long Lists
+
+The list is at most 15rem tall and scrolls when there are more options. To change the height, compose with `Select.Parts` and pass a plain class with a trailing `!` to `Content`:
+
+```tsx
+<Select.Parts.Content className="max-h-96!">{/* items */}</Select.Parts.Content>
+```
+
 ## Low-level Primitives
 
 `Select.Parts` exposes the styled sub-components for fully custom compositions:
@@ -171,6 +179,16 @@ const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Se
 
 ## Form submission
 
+Inside a form, place `Select` directly under `Field.Root`, not inside `Field.Control`. `Select` draws
+its own trigger and registers with the field itself.
+
+```tsx
+<Field.Root name="country">
+  <Field.Label>Country</Field.Label>
+  <Select items={["Japan", "United States"]} placeholder="Select a country" />
+</Field.Root>
+```
+
 Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
 see [Form](./form.md). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
 or a server action.

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

@@ -32,13 +32,13 @@ import { Package } from "lucide-react";
 
 ## Props
 
-| Prop          | Type                        | Default      | Description                                    |
-| ------------- | --------------------------- | ------------ | ---------------------------------------------- |
-| `title`       | `string \| LocalizedString` | **Required** | Group title (supports i18n)                    |
-| `icon`        | `React.ReactNode`           | -            | Icon displayed next to title                   |
-| `to`          | `string`                    | -            | Makes title clickable (navigates to URL)       |
-| `defaultOpen` | `boolean`                   | `true`       | Initial expanded/collapsed state               |
-| `children`    | `React.ReactNode`           | **Required** | Child items (SidebarItem, nested groups, etc.) |
+| Prop          | Type                        | Default      | Description                                                                                                                                                          |
+| ------------- | --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string \| LocalizedString` | **Required** | Group title (supports i18n)                                                                                                                                          |
+| `icon`        | `React.ReactNode`           | -            | Icon displayed next to title                                                                                                                                         |
+| `to`          | `string`                    | -            | Makes title clickable (navigates to URL). In the icon rail on a touch device, tapping the group opens its flyout instead; the page is linked from the flyout heading |
+| `defaultOpen` | `boolean`                   | `true`       | Initial expanded/collapsed state                                                                                                                                     |
+| `children`    | `React.ReactNode`           | **Required** | Child items (SidebarItem, nested groups, etc.)                                                                                                                       |
 
 ## Features
 
@@ -168,6 +168,8 @@ import { Settings } from "lucide-react";
 
 Clicking "Settings" navigates to `/settings`, while child items navigate to their specific pages.
 
+In the collapsed icon rail, the group icon is the link on a mouse device, and its flyout opens on hover. On a touch device the icon opens the flyout on tap, and "Settings" is the link at the top of the flyout.
+
 ### Multiple Groups
 
 ```tsx