@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/side-navigation.md

@@ -0,0 +1,440 @@
+<!-- index: ./index.md -->
+# side-navigation
+
+`data-ui="side-navigation"` · Vertical navigation with groups and counts.
+
+## Import
+
+```tsx
+import { SideNavigation, SideNavigationActions, SideNavigationCount, SideNavigationDefaultsProvider, SideNavigationDescription, SideNavigationDivider, SideNavigationEnd, SideNavigationGroup, SideNavigationIcon, SideNavigationItem, SideNavigationLabel, SideNavigationLink, SideNavigationList, SideNavigationSection, SideNavigationSectionLabel, SideNavigationSkeleton, SideNavigationTrigger } from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import {
+  SideNavigation,
+  SideNavigationCount,
+  SideNavigationItem,
+  SideNavigationLabel,
+  SideNavigationLink,
+  SideNavigationList,
+} from '@slotted/react/side-navigation';
+
+export default function SideNavigationBasic() {
+  return (
+    <SideNavigation aria-label="Main navigation" defaultValue="loads">
+      <SideNavigationList>
+        <SideNavigationItem value="dashboard">
+          <SideNavigationLink href="/dashboard">
+            <SideNavigationLabel>Dashboard</SideNavigationLabel>
+          </SideNavigationLink>
+        </SideNavigationItem>
+        <SideNavigationItem value="loads">
+          <SideNavigationLink href="/loads">
+            <SideNavigationLabel>Loads</SideNavigationLabel>
+            <SideNavigationCount>12</SideNavigationCount>
+          </SideNavigationLink>
+        </SideNavigationItem>
+      </SideNavigationList>
+    </SideNavigation>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | nav, or a div inside app-shell, or the element render returns | yes |
+| `section` | div | no |
+| `section-label` | div | no |
+| `list` | ul | yes |
+| `item` | li | yes |
+| `link` | a with an href, or a button without one, or the element render returns | no |
+| `trigger` | button | no |
+| `icon` | span | no |
+| `label` | span | yes |
+| `description` | span | no |
+| `end` | span | no |
+| `count` | span | no |
+| `indicator` | span | no |
+| `actions` | div | no |
+| `group` | ul | no |
+| `divider` | li role="separator" | no |
+| `skeleton` | li aria-hidden | no |
+| `flyout` | div, in the portal container | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| null` | — | SideNavigation | The current destination’s value. Present means the consumer owns it; a link that states current itself still wins |
+| `defaultValue` | `string \| null` | — | SideNavigation | The destination an uncontrolled column starts on, read once |
+| `expanded` | `readonly string[]` | — | SideNavigation | The set of open groups. Present means the consumer owns it |
+| `defaultExpanded` | `readonly string[]` | — | SideNavigation | The groups an uncontrolled column starts with open, read once |
+| `flyout` | `string \| null` | — | SideNavigation | The one group presented beside the rail. Present means the consumer owns it; it never writes into expanded |
+| `defaultFlyout` | `string \| null` | — | SideNavigation | The group an uncontrolled column starts with in the flyout, read once |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SideNavigation, SideNavigationDefaultsProvider | The row height. md reads the geometry app-shell publishes, with the control scale as the fallback; sm and lg read their own steps |
+| `mode` | `'auto' \| 'expanded' \| 'compact'` | auto | SideNavigation, SideNavigationDefaultsProvider | auto is a rail below compactAt pixels of the root’s own width and a labelled column above; the other two force one |
+| `truncate` | `'end' \| 'middle' \| 'none'` | end | SideNavigation, SideNavigationDefaultsProvider | Where a label that does not fit is cut. end is the stylesheet’s ellipsis; middle keeps the start and the tail; none wraps. A cut label opens the tooltip with the whole text |
+| `multiple` | `boolean` | true | SideNavigation, SideNavigationDefaultsProvider | Whether more than one group may be open at once. Off, opening one closes the rest |
+| `autoExpand` | `boolean` | true | SideNavigation, SideNavigationDefaultsProvider | Whether the ancestors of the current destination open by themselves, with the reason select |
+| `guides` | `boolean` | true | SideNavigation, SideNavigationDefaultsProvider | Whether a guide runs down each open group, under the parent’s mark or on its text edge |
+| `landmark` | `boolean` | true | SideNavigation, SideNavigationDefaultsProvider | Whether the root is a nav. Unstated, it is one on its own and a div inside app-shell, whose nav region is already the landmark |
+| `compactAt` | `number` | 96 | SideNavigation, SideNavigationDefaultsProvider | The width, in CSS pixels, under which mode="auto" is compact. The stylesheet’s own breakpoint is the same number |
+| `messages` | `Partial<SideNavigationMessages>` | — | SideNavigation | Words laid over the language in force: the landmark’s name when the consumer gives no aria-label (navigation) |
+| `value` | `string` | — | SideNavigationItem | The item’s identity: what value, expanded and flyout name it by. Reaches the DOM as data-value |
+| `disabled` | `boolean` | false | SideNavigationItem | The row refuses the press and keeps its href, its name and its place in the tab order; the trigger takes the native attribute |
+| `current` | `boolean` | — | SideNavigationLink | Stated on the row itself — what a router’s link writes — it wins over the root’s value |
+| `href` | `string` | — | SideNavigationLink | The destination. Without one the row is a button: a command in the column, never current |
+| `labelSize` | `number \| string` | 60% | SideNavigationSkeleton | How wide the label’s bar is drawn |
+| `render` | `(props) => ReactNode` | — | every part but indicator, skeleton and flyout | Substitutes the element and hands it every attribute: a router’s link as the row, a button for a command, a section as an aside |
+| `ref` | `Ref<SideNavigationHandle> on the root, Ref<HTMLElement> on every part` | — | every part | The root’s handle carries focus(), expand(value), collapse(value) and the root element; every other ref reaches the element itself |
+| `useSideNavigation()` | `() => SideNavigationContextValue` | — | inside SideNavigation | What the parts read: the axes, whether the column is compact, the three values and the requests that move them |
+| `useSideNavigationItem()` | `() => SideNavigationItemContextValue` | — | inside SideNavigationItem | What a row reads: its value, whether it is expanded, current or holds the current destination, its identifiers |
+| `SideNavigationDefaultsProvider` | `{ size, mode, truncate, multiple, autoExpand, guides, landmark, compactAt }` | — | a subtree | The decisions an application takes once. A column that states any of them itself still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange(value, request)` | `the destination’s value, and a request with previous, reason (pointer \| keyboard \| programmatic), source and cancel()` | Before the current destination moves, on a press of a link with an href. Cancelling refuses; the navigation itself is the anchor’s. |
+| `onExpandedChange(expanded, request)` | `the whole set of open values, and a request with reason (pointer \| keyboard \| select \| escape \| programmatic)` | Before a group opens or closes: a press on its trigger, Escape inside it, autoExpand reaching the current destination (select), or expand()/collapse() on the handle. |
+| `onFlyoutChange(flyout, request)` | `the value of the group shown beside the rail or null, and a request with reason (pointer \| keyboard \| select \| escape \| outsidePress \| blur \| resize \| programmatic)` | Before the flyout opens or closes: a trigger pressed in the rail, a link pressed inside it, Escape, a press outside, focus leaving it, or the rail widening. |
+| `onClick, onFocus, onKeyDown on every row` | `the element’s own events` | Whenever the a or button fires them. The consumer’s handler runs first, and preventDefault() in onClick refuses the family’s part. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `mode` | `auto`, `expanded`, `compact` | `auto` |
+| `multiple` | `true`, `false` | `true` |
+| `autoExpand` | `true`, `false` | `true` |
+| `guides` | `true`, `false` | `true` |
+| `landmark` | `true`, `false` | `true` |
+| `compactAt` | `96` | `96` |
+| `truncate` | `end`, `middle`, `none` | `end` |
+
+## Rules
+
+- The pattern is the WAI-ARIA APG’s Disclosure Navigation Menu with Top-Level Links (w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation-hybrid/), and no role is written: the DOM is nav > ul > li > (a \| button) + ul, so a reader hears a navigation landmark, a list of so many items, a link or a button, and a nested list. The tree role is refused on the APG’s own advice — it demands functionality a site’s navigation does not need.
+- Every link and trigger is in the page tab sequence and nothing here writes tabindex. The arrow keys, Home and End — optional in the pattern and adopted — walk the visible rows, into the flyout when it is open; Escape closes the group holding focus and lands on its trigger, as the pattern lists. A closed group is visibility: hidden, so its rows leave the tab sequence and the accessibility tree together.
+- A trigger carries aria-expanded and aria-controls, and its group aria-labelledby pointing at the row’s label; a trigger beside a link is named by that same label through aria-labelledby, so the hybrid row is heard as “Reports, link” then “Reports, button, collapsed”. Identifiers come from useId, so a server response and the first client render agree.
+- The current destination is aria-current="page" on the link and nowhere else. The parent of a destination the reader cannot see carries data-current for the stylesheet and no ARIA, because the destination is the thing that is current.
+- In the rail the label is clipped to a pixel rather than removed, so the link keeps its accessible name; a tooltip repeats it on hover, on visible focus and on press-and-hold. Under truncate a row whose label the binding measured as cut opens the same tooltip, and a middle cut writes the whole text as aria-label so the name is the name and not the cut.
+- A disabled destination is aria-disabled with its href kept: perceivable, focusable, and refused on press, so a reader can reach the row and hear why it is unavailable. A disabled trigger takes the native attribute. The item carries data-disabled and never aria-disabled, which ARIA 1.2 deprecates on listitem.
+
+## Tokens
+
+`--slotted-app-shell-row-font-size`, `--slotted-app-shell-row-gap`, `--slotted-app-shell-row-height`, `--slotted-app-shell-row-inset`, `--slotted-app-shell-row-line-height`, `--slotted-app-shell-row-mark`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-current-edge`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-radius-md`, `--slotted-shadow-md`, `--slotted-side-navigation-active-background`, `--slotted-side-navigation-color`, `--slotted-side-navigation-current-background`, `--slotted-side-navigation-current-color`, `--slotted-side-navigation-current-description-color`, `--slotted-side-navigation-current-edge`, `--slotted-side-navigation-description-color`, `--slotted-side-navigation-description-gap`, `--slotted-side-navigation-dot-color`, `--slotted-side-navigation-dot-size`, `--slotted-side-navigation-flyout-border-color`, `--slotted-side-navigation-flyout-measure`, `--slotted-side-navigation-flyout-min-measure`, `--slotted-side-navigation-flyout-radius`, `--slotted-side-navigation-flyout-shadow`, `--slotted-side-navigation-flyout-surface`, `--slotted-side-navigation-guide-color`, `--slotted-side-navigation-hover-background`, `--slotted-side-navigation-hover-color`, `--slotted-side-navigation-indent`, `--slotted-side-navigation-indent-step`, `--slotted-side-navigation-radius`, `--slotted-side-navigation-row-gap`, `--slotted-side-navigation-section-color`, `--slotted-side-navigation-section-gap`, `--slotted-side-navigation-section-label-gap`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-7`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+### Playground
+
+One column with every axis on it, driven by the controls below the canvas. Tab reaches every row; the arrows walk them.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation defaultValue="loads">
+  <SideNavigationList>
+    <SideNavigationItem value="dashboard">
+      <SideNavigationLink href="/dashboard">
+        <SideNavigationIcon>
+          <ChartNoAxesColumn />
+        </SideNavigationIcon>
+        <SideNavigationLabel>Dashboard</SideNavigationLabel>
+      </SideNavigationLink>
+    </SideNavigationItem>
+    <SideNavigationItem value="loads">
+      <SideNavigationLink href="/loads">
+        <SideNavigationIcon>
+          <Package />
+        </SideNavigationIcon>
+        <SideNavigationLabel>Loads</SideNavigationLabel>
+        <SideNavigationCount>12</SideNavigationCount>
+      </SideNavigationLink>
+    </SideNavigationItem>
+  </SideNavigationList>
+</SideNavigation>;
+```
+
+### Every part, drawn as its own name
+
+The frame with no product in it: each part the contract declares, labelled, so the family’s box can be told from the product’s content.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation>
+  <SideNavigationSection>
+    <SideNavigationSectionLabel>section-label</SideNavigationSectionLabel>
+    <SideNavigationList>
+      <SideNavigationItem value="row">
+        <SideNavigationLink href="/row">
+          <SideNavigationIcon>…</SideNavigationIcon>
+          <SideNavigationLabel>label</SideNavigationLabel>
+          <SideNavigationDescription>description</SideNavigationDescription>
+          <SideNavigationCount>12</SideNavigationCount>
+        </SideNavigationLink>
+        <SideNavigationActions>…</SideNavigationActions>
+      </SideNavigationItem>
+      <SideNavigationItem value="branch">
+        <SideNavigationTrigger>
+          <SideNavigationLabel>trigger</SideNavigationLabel>
+        </SideNavigationTrigger>
+        <SideNavigationGroup>…</SideNavigationGroup>
+      </SideNavigationItem>
+      <SideNavigationDivider />
+      <SideNavigationSkeleton />
+    </SideNavigationList>
+  </SideNavigationSection>
+</SideNavigation>;
+```
+
+### Groups that open and close
+
+A trigger is the whole row and its group opens on a track that grows to its own height; the chevron turns from along the line to down. Under multiple=false the sibling closes.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigationItem value="deliveries">
+  <SideNavigationTrigger>
+    <SideNavigationIcon>
+      <Truck />
+    </SideNavigationIcon>
+    <SideNavigationLabel>Deliveries</SideNavigationLabel>
+    <SideNavigationCount>38</SideNavigationCount>
+  </SideNavigationTrigger>
+  <SideNavigationGroup>
+    <SideNavigationItem value="today">
+      <SideNavigationLink href="/deliveries/today">
+        <SideNavigationLabel>Today</SideNavigationLabel>
+      </SideNavigationLink>
+    </SideNavigationItem>
+  </SideNavigationGroup>
+</SideNavigationItem>;
+```
+
+### A destination that is also a parent
+
+The APG hybrid row: the link navigates and a mark-only trigger beside it opens the children, named by the row’s label. Five levels deep, the indent below the marked level is a constant step.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigationItem value="reports">
+  <SideNavigationLink href="/reports">
+    <SideNavigationIcon>
+      <ChartNoAxesColumn />
+    </SideNavigationIcon>
+    <SideNavigationLabel>Reports</SideNavigationLabel>
+  </SideNavigationLink>
+  <SideNavigationTrigger />
+  <SideNavigationGroup>…</SideNavigationGroup>
+</SideNavigationItem>;
+```
+
+### Sections, a divider and a command
+
+Two titled sections under one root, a divider between rows that keeps the list a list, and a row that is a button — a command in the column, never current.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation>
+  <SideNavigationSection>
+    <SideNavigationSectionLabel>Operations</SideNavigationSectionLabel>
+    <SideNavigationList>…</SideNavigationList>
+  </SideNavigationSection>
+  <SideNavigationSection>
+    <SideNavigationSectionLabel>Administration</SideNavigationSectionLabel>
+    <SideNavigationList>
+      <SideNavigationDivider />
+      <SideNavigationItem value="new">
+        <SideNavigationLink onClick={() => openDialog()}>
+          <SideNavigationIcon>
+            <Plus />
+          </SideNavigationIcon>
+          <SideNavigationLabel>New load</SideNavigationLabel>
+        </SideNavigationLink>
+      </SideNavigationItem>
+    </SideNavigationList>
+  </SideNavigationSection>
+</SideNavigation>;
+```
+
+### Where the reader is
+
+value on the root names the destination and a press asks it to move; a link that states current itself wins. The parent of a hidden destination is marked until its group opens, and autoExpand opens it.
+
+Excerpt — not a complete module
+
+```tsx
+const [value, setValue] = useState<string | null>('orders');
+
+<SideNavigation value={value} onValueChange={(next) => setValue(next)}>
+  …
+</SideNavigation>;
+```
+
+### The rail
+
+Under mode="compact" — or under 96 pixels of its own width — every part but the mark leaves the eye; the label stays in the DOM, a tooltip repeats it, and a row with a count carries a dot.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation mode="compact" defaultValue="loads">
+  …
+</SideNavigation>;
+```
+
+### A group beside the rail
+
+In the rail, pressing a trigger without a link presents its group in a layer beside it. ArrowDown walks into it, Escape returns to the trigger, and focus leaving it closes it.
+
+Excerpt — not a complete module
+
+```tsx
+const [flyout, setFlyout] = useState<string | null>(null);
+
+<SideNavigation mode="compact" flyout={flyout} onFlyoutChange={setFlyout}>
+  …
+</SideNavigation>;
+```
+
+### Three row heights
+
+md reads the row geometry app-shell publishes, so a column in the shell stands on the shell’s own edges; sm and lg read the control scale, and all three move with density.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation size="sm">…</SideNavigation>;
+```
+
+### The states a row can be in
+
+Current, expanded, open, disabled, and the hover, press and focus every row answers. A disabled destination keeps its href and its name, and refuses the press.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigationItem disabled value="billing">
+  <SideNavigationLink href="/billing">
+    <SideNavigationIcon>
+      <CreditCard />
+    </SideNavigationIcon>
+    <SideNavigationLabel>Billing</SideNavigationLabel>
+    <SideNavigationDescription>Available on the Team plan</SideNavigationDescription>
+  </SideNavigationLink>
+</SideNavigationItem>;
+```
+
+### Content the family did not choose
+
+A long label cut at the end with its whole text in the tooltip; the same column cut in the middle, where setembro and outubro stay apart; a URL; a title in another script; and wrapping, on request.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation truncate="middle">…</SideNavigation>;
+```
+
+### A column still arriving
+
+Skeleton rows in the geometry of the rows they stand for, so nothing moves when the destinations land; the root carries aria-busy.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation aria-busy="true">
+  <SideNavigationList>
+    <SideNavigationSkeleton labelSize="55%" />
+    <SideNavigationSkeleton labelSize="70%" />
+    <SideNavigationSkeleton labelSize="45%" />
+  </SideNavigationList>
+</SideNavigation>;
+```
+
+### Inside the shell
+
+The column in app-shell’s nav region: a div rather than a second landmark, rows on the shell’s published geometry, and the rail read from the region’s own width when the shell collapses.
+
+Excerpt — not a complete module
+
+```tsx
+<AppShell>
+  <AppShellBanner>…</AppShellBanner>
+  <AppShellNav>
+    <AppShellNavBody>
+      <SideNavigation defaultValue="orders">…</SideNavigation>
+    </AppShellNavBody>
+  </AppShellNav>
+  <AppShellMain>…</AppShellMain>
+</AppShell>;
+```
+
+### Decided once for an application
+
+The provider carries the axes for every column under it — a product whose groups open one at a time, with no guides — and a column that states one itself still wins.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigationDefaultsProvider guides={false} multiple={false} truncate="middle">
+  <SideNavigation>…</SideNavigation>
+</SideNavigationDefaultsProvider>;
+```
+
+### Composed with what sits beside it
+
+A Badge in end for a count that carries a tone, an Avatar in icon for a person, a Kbd for a shortcut, and a router’s own link through render, which is where aria-current comes from.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigationLink render={(props) => <NavLink {...props} to="/loads" />}>
+  <SideNavigationIcon>
+    <Package />
+  </SideNavigationIcon>
+  <SideNavigationLabel>Loads</SideNavigationLabel>
+  <SideNavigationEnd>
+    <Badge tone="danger" size="sm">
+      3
+    </Badge>
+  </SideNavigationEnd>
+</SideNavigationLink>;
+```
+
+### The keyboard
+
+Tab reaches every row. ArrowDown and ArrowUp walk the visible rows, Home and End jump, Escape closes the group holding focus and lands on its trigger. The reason each request carries is shown.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation
+  onExpandedChange={(expanded, request) => log(request.reason)}
+  onValueChange={(value, request) => log(request.reason)}
+>
+  …
+</SideNavigation>;
+```
+
+### What a reader hears
+
+A navigation landmark holding a list; each branch a button with aria-expanded and aria-controls; each destination a link, one of them aria-current; a hybrid trigger named by its row.
+
+Excerpt — not a complete module
+
+```tsx
+<SideNavigation aria-label="Main navigation">…</SideNavigation>;
+```