@tailor-platform/app-shell 1.18.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/text.md

@@ -7,7 +7,7 @@ description: Text with a typography role, rendered as an element you choose
 
 # Text
 
-The `Text` component applies a [typography role](../concepts/styling-theming.md#typography) to its content. A role sets font size, line height, font weight, and letter spacing together. The role does not set the color, and it does not choose the HTML element. Use the `render` prop to choose the element (Base UI render pattern).
+The `Text` component applies a [typography role](../concepts/styling-theming.md#typography) to its content. A role sets font size, line height, font weight, and letter spacing together. The role does not set the color, and it does not choose the HTML element. To choose the element, use an element component such as `Text.h1` or `Text.p`, or use the `render` prop (Base UI render pattern) to compose with another component.
 
 ## Import
 
@@ -23,8 +23,8 @@ import { Text } from "@tailor-platform/app-shell";
 function BasicUsage() {
   return (
     <div className="flex flex-col gap-1">
-      <Text variant="heading-md">Purchase orders</Text>
-      <Text className="text-muted-foreground">Orders sent to suppliers this month.</Text>
+      <Text.h2>Purchase orders</Text.h2>
+      <Text.p className="text-muted-foreground">Orders sent to suppliers this month.</Text.p>
     </div>
   );
 }
@@ -36,18 +36,57 @@ _Generated from the type surface — first-party props only._
 
 ### TextProps
 
-| Prop       | Type                                                                                                                                                                | Default     | Description                                                                                                        |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
-| `ref?`     | `React.Ref<HTMLElement>`                                                                                                                                            | -           | Ref to the rendered element.                                                                                       |
-| `render?`  | `React.ReactElement`                                                                                                                                                | -           | Custom element to render as (Base UI render prop). Use it to set the heading level, for example `render={<h3 />}`. |
-| `variant?` | `"heading-lg" \| "heading-md" \| "heading-sm" \| "body-md" \| "body-sm" \| "label-md" \| "label-sm" \| "code-sm" \| "body-md-relaxed" \| "body-sm-relaxed" \| null` | `"body-md"` | Typography role. Sets font size, line height, font weight, and letter spacing together.                            |
+| Prop       | Type                                                                                                                                                                | Default     | Description                                                                                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref?`     | `React.Ref<HTMLElement>`                                                                                                                                            | -           | Ref to the rendered element.                                                                                                                                                             |
+| `render?`  | `React.ReactElement`                                                                                                                                                | -           | Custom element to render as (Base UI render prop). Use it to compose with another component. For a plain HTML element, use `Text.h1` to `Text.h6`, `Text.p`, `Text.span`, or `Text.div`. |
+| `variant?` | `"heading-lg" \| "heading-md" \| "heading-sm" \| "body-md" \| "body-sm" \| "label-md" \| "label-sm" \| "code-sm" \| "body-md-relaxed" \| "body-sm-relaxed" \| null` | `"body-md"` | Typography role. Sets font size, line height, font weight, and letter spacing together.                                                                                                  |
 
 ## Exports
 
-- `Text` — function
+- `Text` — const
 - `TextProps` — type
 
-All standard HTML attributes are also accepted. Put an attribute that belongs to one element, such as `htmlFor` on a `label`, on the `render` element:
+## Element Components
+
+`Text.h1` to `Text.h6`, `Text.p`, `Text.span`, and `Text.div` always render their named HTML element. Each one applies a default role, so you do not repeat `variant` for ordinary text:
+
+<example-preview name="element-components"></example-preview>
+
+```tsx
+function ElementComponents() {
+  return (
+    <div className="flex flex-col gap-1">
+      <Text.h3>Shipping address</Text.h3>
+      <Text.p className="text-muted-foreground">Orders ship from the main warehouse.</Text.p>
+      <Text.span className="tabular-nums">3 packages</Text.span>
+    </div>
+  );
+}
+```
+
+| Component           | Default `variant` |
+| ------------------- | ----------------- |
+| `Text.h1`           | `heading-lg`      |
+| `Text.h2`           | `heading-md`      |
+| `Text.h3`–`Text.h6` | `heading-sm`      |
+| `Text.p`            | `body-md`         |
+| `Text.span`         | `label-md`        |
+| `Text.div`          | `body-md`         |
+
+The element sets the meaning and `variant` sets the appearance. The default is only a starting point, and any role works on any element:
+
+```tsx
+<Text.h1 variant="heading-sm">A compact page title</Text.h1>
+<Text.h3 variant="heading-lg">A visually prominent subsection</Text.h3>
+<Text.span variant="body-sm">Updated recently</Text.span>
+```
+
+The element components take `variant`, `className`, the element's own attributes, and a ref typed for the element (`HTMLHeadingElement` for `Text.h2`). They do not take `render`. For any other element, or to compose with another component, use `Text` with `render`.
+
+## Using `render`
+
+All standard HTML attributes are also accepted by `Text`. Put an attribute that belongs to one element, such as `htmlFor` on a `label`, on the `render` element:
 
 ```tsx
 <Text variant="label-md" render={<label htmlFor="quantity" />}>
@@ -59,7 +98,7 @@ Some lint rules report this example; see [Lint](#lint).
 
 ## Roles
 
-`variant` takes one of the ten roles. Each role renders a default element when you do not pass `render`:
+`variant` takes one of the ten roles. On `Text`, each role renders a default element when you do not pass `render`:
 
 | `variant`         | Default element | Use                                             |
 | ----------------- | --------------- | ----------------------------------------------- |
@@ -70,7 +109,7 @@ Some lint rules report this example; see [Lint](#lint).
 | `body-sm`         | `p`             | Caption, timestamp, metadata                    |
 | `body-md-relaxed` | `p`             | Long text, such as a chat message or a document |
 | `body-sm-relaxed` | `p`             | Long text at the small size                     |
-| `label-md`        | `span`          | Field label, short UI text, figures in a table  |
+| `label-md`        | `span`          | Field label, short UI text                      |
 | `label-sm`        | `span`          | Small label, badge text                         |
 | `code-sm`         | `span`          | ID and code. `Text` adds `font-mono` for you    |
 
@@ -81,15 +120,9 @@ function Roles() {
   return (
     <div className="flex flex-col gap-3">
       {/* The headings render a div so that this specimen is not a document heading. */}
-      <Text variant="heading-lg" render={<div />}>
-        heading-lg: Purchase orders
-      </Text>
-      <Text variant="heading-md" render={<div />}>
-        heading-md: Line items
-      </Text>
-      <Text variant="heading-sm" render={<div />}>
-        heading-sm: Shipping address
-      </Text>
+      <Text.div variant="heading-lg">heading-lg: Purchase orders</Text.div>
+      <Text.div variant="heading-md">heading-md: Line items</Text.div>
+      <Text.div variant="heading-sm">heading-sm: Shipping address</Text.div>
       <Text variant="body-md">body-md: Orders sent to suppliers this month.</Text>
       <Text variant="body-sm">body-sm: Updated 2 hours ago</Text>
       <Text variant="label-md">label-md: Total amount</Text>
@@ -104,30 +137,28 @@ The sizes and line heights are in the [Typography section of the styling guide](
 
 ## Heading Level
 
-All three heading roles render `h2` by default. The heading level comes from the document structure, not from the visual size, so set it with `render`:
+On `Text`, all three heading roles render `h2` by default. The heading level comes from the document structure, not from the visual size, so set it with `Text.h1` to `Text.h6`:
 
 ```tsx
-<Text variant="heading-md" render={<h3 />}>
-  Line items
-</Text>
+<Text.h3 variant="heading-md">Line items</Text.h3>
 ```
 
-To use a heading role for text that is not a heading, render a `div` or a `span`:
+To use a heading role for text that is not a heading, use `Text.div` or `Text.span`:
 
 ```tsx
-<Text variant="heading-md" render={<div />}>
-  1,240 orders
-</Text>
+<Text.div variant="heading-md">1,240 orders</Text.div>
 ```
 
 ## Lint
 
-Some `jsx-a11y` rules check that an element has text inside it, for example `heading-has-content` for `<h3 />` and `label-has-associated-control` for `<label />`. These rules report the element in `render` as empty, because they do not see that `Text` passes its children to that element. If your app enables them, disable the rule on that line. ESLint and oxlint both read this comment:
+Some `jsx-a11y` rules check that an element has text inside it, for example `heading-has-content` for `<h3 />` and `label-has-associated-control` for `<label />`. These rules report the element in `render` as empty, because they do not see that `Text` passes its children to that element.
+
+For headings, use `Text.h1` to `Text.h6`. The rules do not report them. For other elements, such as `label`, use `render`, and if your app enables the rule, disable it on that line. ESLint and oxlint both read this comment:
 
 ```tsx
-// eslint-disable-next-line jsx-a11y/heading-has-content -- Text renders the children
-<Text variant="heading-md" render={<h3 />}>
-  Line items
+// eslint-disable-next-line jsx-a11y/label-has-associated-control -- Text renders the children
+<Text variant="label-md" render={<label htmlFor="quantity" />}>
+  Quantity
 </Text>
 ```
 
@@ -156,9 +187,9 @@ function ColorAndModifiers() {
 <Text variant="body-md" className="text-muted-foreground">
   Orders sent this month.
 </Text>
-<Text variant="heading-md" render={<h3 />} className="leading-none">
+<Text.h3 variant="heading-md" className="leading-none">
   Card title
-</Text>
+</Text.h3>
 <Text variant="label-md" className="tabular-nums">
   1,240.00
 </Text>
@@ -180,11 +211,17 @@ Each role is also a plain utility, for example `text-heading-md`. Use the utilit
 import { type TextProps } from "@tailor-platform/app-shell";
 ```
 
+The element components have no exported props type. Read it from the component:
+
+```tsx
+type SectionTitleProps = React.ComponentProps<typeof Text.h2>;
+```
+
 ## Accessibility
 
-- A heading role renders a real heading (`h2`) by default, so screen readers list it with the other headings. Set the level with `render` so the levels follow the page structure.
+- A heading role on `Text` renders a real heading (`h2`) by default, so screen readers list it with the other headings. Set the level with `Text.h1` to `Text.h6` so the levels follow the page structure.
 - Do not choose a heading level for its size. `Text` keeps the size and the level separate.
-- `body-*` roles render `p`. Inside another `p`, render a `span` instead (`<Text render={<span />}>`): the browser closes the outer `p` before the inner one, so React warns and server rendering fails to hydrate. Inside inline elements such as `button`, `label` or `span`, a `p` is invalid HTML too, so render a `span` there as well.
+- `body-*` roles render `p` on `Text`. Inside another `p`, use `Text.span` instead (`<Text.span variant="body-md">`): the browser closes the outer `p` before the inner one, so React warns and server rendering fails to hydrate. Inside inline elements such as `button`, `label` or `span`, a `p` is invalid HTML too, so render a `span` there as well.
 
 ## Palettes
 
@@ -195,4 +232,4 @@ The `cream` and `bloom` palettes set the line height and letter spacing of `h1`
 - [Card](./card.md) - The table above lists `heading-md` for card titles
 - [Layout](./layout.md) - The table above lists `heading-lg` for the page title
 
-AppShell's own components, including these two, still use the stock utilities. They will move to the roles in a later change.
+AppShell's own components, including these two, render their titles and descriptions with `Text`.