@tailor-platform/app-shell 1.17.0 → 1.19.0

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`) | 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/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/select.md

@@ -171,6 +171,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

@@ -124,13 +124,13 @@ Titles support i18n with `defineI18nLabels`:
 import { defineI18nLabels } from "@tailor-platform/app-shell";
 
 const labels = defineI18nLabels({
-  products: {
-    en: "Products",
-    ja: "商品",
+  en: {
+    products: "Products",
+    settings: "Settings",
   },
-  settings: {
-    en: "Settings",
-    ja: "設定",
+  ja: {
+    products: "商品",
+    settings: "設定",
   },
 });
 

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

@@ -0,0 +1,235 @@
+---
+title: Text
+description: Text with a typography role, rendered as an element you choose
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/text.docs.outline.md — do not edit by hand. -->
+
+# 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. 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
+
+```tsx
+import { Text } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <div className="flex flex-col gap-1">
+      <Text.h2>Purchase orders</Text.h2>
+      <Text.p className="text-muted-foreground">Orders sent to suppliers this month.</Text.p>
+    </div>
+  );
+}
+```
+
+## Props
+
+_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 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` — const
+- `TextProps` — type
+
+## 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" />}>
+  Quantity
+</Text>
+```
+
+Some lint rules report this example; see [Lint](#lint).
+
+## Roles
+
+`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                                             |
+| ----------------- | --------------- | ----------------------------------------------- |
+| `heading-lg`      | `h2`            | Page title (`Layout.Header`)                    |
+| `heading-md`      | `h2`            | Section heading, card title                     |
+| `heading-sm`      | `h2`            | Sub-section heading                             |
+| `body-md`         | `p`             | Body copy, descriptions (default role)          |
+| `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                      |
+| `label-sm`        | `span`          | Small label, badge text                         |
+| `code-sm`         | `span`          | ID and code. `Text` adds `font-mono` for you    |
+
+<example-preview name="roles"></example-preview>
+
+```tsx
+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.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>
+      <Text variant="label-sm">label-sm: Draft</Text>
+      <Text variant="code-sm">code-sm: PO-2026-0001</Text>
+    </div>
+  );
+}
+```
+
+The sizes and line heights are in the [Typography section of the styling guide](../concepts/styling-theming.md#typography).
+
+## Heading Level
+
+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.h3 variant="heading-md">Line items</Text.h3>
+```
+
+To use a heading role for text that is not a heading, use `Text.div` or `Text.span`:
+
+```tsx
+<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.
+
+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/label-has-associated-control -- Text renders the children
+<Text variant="label-md" render={<label htmlFor="quantity" />}>
+  Quantity
+</Text>
+```
+
+## Color and Modifiers
+
+Set the color with a color token in `className`. Four modifiers may also be combined with a role: `leading-none` for single-line text, `tabular-nums`, `font-semibold` for emphasis, and `uppercase`.
+
+<example-preview name="color-and-modifiers"></example-preview>
+
+```tsx
+function ColorAndModifiers() {
+  return (
+    <div className="flex flex-col gap-3">
+      <Text variant="body-md" className="text-muted-foreground">
+        Orders sent this month.
+      </Text>
+      <Text variant="label-md" className="tabular-nums">
+        1,240.00
+      </Text>
+    </div>
+  );
+}
+```
+
+```tsx
+<Text variant="body-md" className="text-muted-foreground">
+  Orders sent this month.
+</Text>
+<Text.h3 variant="heading-md" className="leading-none">
+  Card title
+</Text.h3>
+<Text variant="label-md" className="tabular-nums">
+  1,240.00
+</Text>
+```
+
+Do not combine a role with other `leading-*`, `tracking-*`, or `text-*` size values. Pick a different `variant` instead. A `text-*` size class such as `text-sm` has no effect on `Text`: AppShell's stylesheet loads after yours, so the role's size wins.
+
+## Using Roles Without Text
+
+Each role is also a plain utility, for example `text-heading-md`. Use the utility when you style your own element and do not need `Text`:
+
+```tsx
+<th className="text-label-md text-muted-foreground">Amount</th>
+```
+
+## TypeScript
+
+```typescript
+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 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` 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
+
+The `cream` and `bloom` palettes set the line height and letter spacing of `h1` to `h6` elements. Under these palettes, a heading role on a heading element uses the palette values (line height 1.2, letter spacing `-0.03em`), including when you add `leading-none`. The same role on a `div` or `span` uses the role values. See the [Typography section of the styling guide](../concepts/styling-theming.md#typography).
+
+## Related Components
+
+- [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, render their titles and descriptions with `Text`.

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

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