@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/sidebar-primary.md

@@ -0,0 +1,360 @@
+# SidebarPrimary
+
+> The app-level navigation rail. A set of composable parts (header, content, footer, sections, menu, menu items, extras) that reflows between an expanded (256px) and a collapsed (48px icon rail) state. Menu items carry a `selected` variant for the current route; trailing extras add a shortcut, external-link, or tag affordance. The product logo is consumer-slotted into the header.
+
+**Status:** ready · **Category:** navigation · **Since:** v0.7.0
+
+## Import
+
+```tsx
+import { SidebarPrimary, SidebarPrimaryHeader, SidebarPrimaryContent, SidebarPrimaryFooter, SidebarPrimarySection, SidebarPrimaryMenu, SidebarPrimaryMenuItem, SidebarPrimaryMenuItemExtras } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<SidebarPrimary expanded={expanded} onExpandedChange={setExpanded}>
+  <SidebarPrimaryHeader logo={<ProductLogo />} collapsedLogo={<ProductMark />} />
+  <SidebarPrimaryContent>
+    <SidebarPrimarySection>
+      <SidebarPrimaryMenu>
+        <SidebarPrimaryMenuItem render={<Link to="/assets" />} icon={<BoxIcon />} selected>
+          Assets
+        </SidebarPrimaryMenuItem>
+        <SidebarPrimaryMenuItem
+          href="/clients"
+          icon={<UsersIcon />}
+          extras={<SidebarPrimaryMenuItemExtras variant="shortcut" shortcut="⌘K" />}
+        >
+          Clients
+        </SidebarPrimaryMenuItem>
+      </SidebarPrimaryMenu>
+    </SidebarPrimarySection>
+  </SidebarPrimaryContent>
+  <SidebarPrimaryFooter>
+    <SidebarPrimaryMenu>
+      <SidebarPrimaryMenuItem href="/help" icon={<CircleHelpIcon />}>
+        Help
+      </SidebarPrimaryMenuItem>
+    </SidebarPrimaryMenu>
+  </SidebarPrimaryFooter>
+</SidebarPrimary>
+```
+
+The app-level navigation rail — the persistent left-hand shell that lists the
+product's top-level destinations. Built as composable parts so the rail's
+structure stays explicit in markup, with an expanded (full-width) and a
+collapsed (icon-only) state.
+
+## When to Use
+
+- The primary, app-wide navigation between top-level areas.
+- A persistent rail that can collapse to icons to reclaim horizontal space.
+- Grouped destinations (sections) with a pinned footer (help, collapse, …).
+
+## When NOT to Use
+
+- **Contextual, second-level navigation** within a section — use
+  SidebarSecondary.
+- **In-page section links** — use an anchor/table-of-contents.
+- **A popover menu of actions** — use a Menu/Dropdown.
+- **Breadcrumb-style location** — use Breadcrumb.
+
+## Parts
+
+| Part                            | Element                              | Role                                              |
+| ------------------------------- | ------------------------------------ | ------------------------------------------------- |
+| `SidebarPrimary`                | `<nav>`                              | Navigation landmark; owns the expanded state      |
+| `SidebarPrimaryHeader`          | `<div>`                              | Consumer logo slot; sizes on expanded/collapsed   |
+| `SidebarPrimaryContent`         | `<div>`                              | Scrollable region of sections                     |
+| `SidebarPrimaryFooter`          | `<div>`                              | Pinned footer menu with a top divider             |
+| `SidebarPrimarySection`         | `<div>`                              | A group of menu items (divider between groups)    |
+| `SidebarPrimaryMenu`            | `<ul>`                               | List that owns the inter-item gap                 |
+| `SidebarPrimaryMenuItem`        | `<li><a>` (polymorphic via `render`) | A nav row: icon + label + optional extras         |
+| `SidebarPrimaryMenuItemExtras`  | `<span>`                             | Trailing shortcut / external-link / tag           |
+| `SidebarPrimaryCollapseTrigger` | `<li><button>`                       | Footer "Collapse menu" button; toggles `expanded` |
+
+## Quick Examples
+
+### React
+
+```tsx
+import {
+  SidebarPrimary,
+  SidebarPrimaryHeader,
+  SidebarPrimaryContent,
+  SidebarPrimaryFooter,
+  SidebarPrimarySection,
+  SidebarPrimaryMenu,
+  SidebarPrimaryMenuItem,
+  SidebarPrimaryMenuItemExtras,
+} from '@acronis-platform/ui-react';
+import {
+  BoxIcon,
+  UsersIcon,
+  CircleHelpIcon,
+} from '@acronis-platform/icons-react/stroke-mono';
+
+function AppRail() {
+  const [expanded, setExpanded] = useState(true);
+  return (
+    <SidebarPrimary expanded={expanded} onExpandedChange={setExpanded}>
+      <SidebarPrimaryHeader>
+        <ProductLogo />
+      </SidebarPrimaryHeader>
+      <SidebarPrimaryContent>
+        <SidebarPrimarySection>
+          <SidebarPrimaryMenu>
+            <SidebarPrimaryMenuItem href="/assets" icon={<BoxIcon />} selected>
+              Assets
+            </SidebarPrimaryMenuItem>
+            <SidebarPrimaryMenuItem href="/clients" icon={<UsersIcon />}>
+              Clients
+              <SidebarPrimaryMenuItemExtras variant="shortcut" shortcut="⌘K" />
+            </SidebarPrimaryMenuItem>
+          </SidebarPrimaryMenu>
+        </SidebarPrimarySection>
+      </SidebarPrimaryContent>
+      <SidebarPrimaryFooter>
+        <SidebarPrimaryMenu>
+          <SidebarPrimaryMenuItem href="/help" icon={<CircleHelpIcon />}>
+            Help
+          </SidebarPrimaryMenuItem>
+        </SidebarPrimaryMenu>
+      </SidebarPrimaryFooter>
+    </SidebarPrimary>
+  );
+}
+```
+
+Render a menu item as a router link via the `render` prop:
+
+```tsx
+<SidebarPrimaryMenuItem render={<Link to="/assets" />} icon={<BoxIcon />}>
+  Assets
+</SidebarPrimaryMenuItem>
+```
+
+## Logo
+
+The product logo is a **consumer-provided child** of the header — the component
+does not ship a Logo part. The header just sizes whatever `img`/`svg` you slot
+in (32px collapsed, 48px expanded) and tints it via the logo-color token.
+
+## Spec Files
+
+| File               | Contents                                                          |
+| ------------------ | ----------------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link              |
+| `anatomy.yaml`     | Root, parts, layout, states                                       |
+| `api.yaml`         | Framework-agnostic contract + framework adapters                  |
+| `tokens.yaml`      | `--ui-sidebar-primary-*` token references                         |
+| `behavior.md`      | Given/When/Then behavior scenarios                                |
+| `accessibility.md` | ARIA roles, keyboard map, screen-reader and contrast requirements |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop on the root and on the menu-item part — replaces the rendered element with another component (e.g. a router `Link` in a menu item, or an `<aside>` wrapper on the root) while merging props and classes. React-only; other frameworks use their own polymorphism. |
+| `expanded` | `boolean` | `undefined` | no | Controlled rail width state (on the root). `true` = full width (256px), `false` = collapsed icon rail (48px). Drives `data-state`. |
+| `defaultExpanded` | `boolean` | `true` | no | Uncontrolled initial expanded state (on the root). |
+| `selected` | `boolean` | `false` | no | Marks a menu-item as the current route — applies the `selected` variant and sets `aria-current="page"`. |
+| `icon` | `ReactNode` | `undefined` | no | Leading 16px icon for a menu-item. |
+| `href` | `string` | `undefined` | no | Target URL of a menu-item link (passthrough on the `<a>`). |
+| `extras` | `ReactNode` | `undefined` | no | Trailing affordance slot on a menu-item (or the footer collapse trigger) — an `extras-variant` element. React: the `extras` prop on `SidebarPrimaryMenuItem` / `SidebarPrimaryCollapseTrigger`, rendered as a flex sibling of the label rather than composed as a child, so it gets its own row gap and isn't clipped by the label's `truncate`. |
+| `extras-variant` | `'tag' | 'externalLink' | 'shortcut' | 'tag-externalLink'` | — | yes | Which trailing affordance the extras part renders. React: the `variant` prop on `SidebarPrimaryMenuItemExtras`. (Distinct from the menu-item's selected/unselected cva variant, which is driven by the `selected` prop — named here without the bare `variant` key reserved for a root cva axis.) |
+| `shortcut` | `string` | `undefined` | no | Keyboard-shortcut text for the extras `shortcut` variant. |
+| `tag` | `ReactNode` | `undefined` | no | Tag content for the extras `tag` / `tag-externalLink` variants. |
+| `logo` | `ReactNode` | `undefined` | no | Header content shown while the rail is expanded (e.g. a full brand lockup). Pairs with `collapsed-logo` to swap distinct graphics per rail state instead of resizing one. React: the `logo` prop on `SidebarPrimaryHeader`. |
+| `collapsed-logo` | `ReactNode` | `undefined` | no | Header content shown while the rail is collapsed (e.g. a monogram mark). Falls back to `logo` when omitted. React: the `collapsedLogo` prop on `SidebarPrimaryHeader`. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `expanded-change` | `boolean` | Fires when the expanded state changes (e.g. via a consumer "collapse" control). React: `onExpandedChange`. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed rail. Author it from the parts: a header (with the consumer logo), a scrollable content region of sections each wrapping a menu of items, and a footer menu. |
+
+## Behavior
+
+### Structure
+
+#### Renders a navigation landmark
+
+**Given** a SidebarPrimary wrapping a header, content, and footer
+**When** the component renders
+**Then** the root is a `<nav>` with a distinguishing `aria-label` (default `"Primary"`)
+**And** each menu is a `<ul>` of `<li>` rows
+**And** menu items are links (`<a>`) by default
+
+#### Sections divide the menu
+
+**Given** more than one SidebarPrimarySection in the content
+**When** the rail renders
+**Then** the first section has no top divider
+**And** every following section carries a top border
+
+---
+
+### Selection
+
+#### Marks the current route
+
+**Given** a SidebarPrimaryMenuItem with `selected`
+**When** the rail renders
+**Then** the item applies the `selected` container/icon/label tokens
+**And** it carries `aria-current="page"`
+
+#### Unselected items
+
+**Given** a SidebarPrimaryMenuItem without `selected`
+**When** the rail renders
+**Then** the item applies the `unselected` tokens (transparent container at idle)
+**And** it does not carry `aria-current`
+
+---
+
+### Expand / collapse (rail width)
+
+#### Defaults to expanded
+
+**Given** a SidebarPrimary with no `expanded` / `defaultExpanded`
+**When** it renders
+**Then** the root has `data-state="expanded"` (256px width)
+
+#### Collapses to an icon rail
+
+**Given** `expanded={false}` (or a consumer toggles it via `onExpandedChange`)
+**When** it renders
+**Then** the root has `data-state="collapsed"` (48px width)
+**And** the header padding shrinks and the logo height drops
+**And** menu-item labels are visually hidden but kept in the DOM as `sr-only`
+**And** trailing extras are hidden
+
+---
+
+### Menu items
+
+#### Composes with a router link
+
+**Given** a SidebarPrimaryMenuItem with `render={<Link to="/assets" />}`
+**When** it renders
+**Then** the router `Link` is the rendered element
+**And** the menu-item classes and props are merged onto it
+**And** no extra `<a>` wrapper is produced
+
+#### Leads with an icon
+
+**Given** a SidebarPrimaryMenuItem with an `icon`
+**When** it renders
+**Then** the icon sits before the label, optically top-aligned (`icon-margin-t`)
+
+---
+
+### Extras
+
+#### Shortcut
+
+**Given** a SidebarPrimaryMenuItemExtras `variant="shortcut" shortcut="⌘K"`
+**When** the item renders expanded
+**Then** the shortcut text appears trailing the label
+
+#### External link
+
+**Given** a SidebarPrimaryMenuItemExtras `variant="externalLink"`
+**When** the item renders expanded
+**Then** a 16px external-link icon appears trailing the label
+
+#### Hidden when collapsed
+
+**Given** any extras inside a menu item
+**When** the rail is collapsed
+**Then** the extras cluster is hidden
+
+## Accessibility
+
+A list of navigation links presented as an app rail. It is a `navigation`
+landmark, **not** a `menu` / `menubar` widget — interaction is native tab order,
+not arrow-key roving.
+
+## ARIA Roles and Attributes
+
+### Root (`nav`)
+
+| Attribute    | Value                  | Reason                                                         |
+| ------------ | ---------------------- | -------------------------------------------------------------- |
+| `<nav>`      | —                      | Exposes the rail as a navigation landmark                      |
+| `aria-label` | `"Primary"` (default)  | Distinguishes it from other `nav` landmarks (override per app) |
+| `data-state` | `expanded`/`collapsed` | Reflects the width state; drives token switching               |
+
+### Menu / items
+
+- Each menu is an unordered list (`<ul>`) of `<li>` rows.
+- Each row renders a native `<a>` (or the element supplied via `render`, e.g. a
+  router `Link` or a `<button>`).
+- The selected row carries `aria-current="page"`.
+
+### Collapsed (icon rail)
+
+When the rail is collapsed, labels are **visually** hidden but remain in the DOM
+as `sr-only` text — so each icon-only row keeps an accessible name. Labels are
+never `display:none`. Trailing extras (shortcut / external-link / tag) are
+decorative trailing affordances and are hidden when collapsed.
+
+---
+
+## Keyboard Navigation
+
+| Key       | Element   | Action                           |
+| --------- | --------- | -------------------------------- |
+| Tab       | Menu item | Moves focus to the next item     |
+| Shift+Tab | Menu item | Moves focus to the previous item |
+| Enter     | Menu item | Activates / navigates            |
+
+There is no roving tabindex or arrow-key model — this is a list of links, not a
+`menu`/`menubar`. (Arrow-key roving would be a different component.)
+
+---
+
+## Focus
+
+A keyboard-focused menu item shows a visible focus ring using the shared
+`--ui-focus-brand` token (no dedicated sidebar focus token exists). The ring is
+inset so it stays inside the 48px collapsed rail.
+
+---
+
+## Screen Reader Requirements
+
+1. The navigation landmark is announced with its label.
+2. Each row announces its label as a link.
+3. The selected row announces `aria-current="page"`.
+4. In collapsed mode, rows still announce their (sr-only) label.
+
+---
+
+## Color and Contrast
+
+| Element                       | Minimum Ratio | Standard               |
+| ----------------------------- | ------------- | ---------------------- |
+| Menu-item label vs container  | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Menu-item icon vs container   | 3:1           | WCAG 1.4.11 (non-text) |
+| Selected container vs rail bg | 3:1           | WCAG 1.4.11            |
+| Focus indicator               | 3:1           | WCAG 1.4.11            |
+
+---
+
+## Testing Checklist
+
+- [ ] `<nav>` root with a distinguishing `aria-label`
+- [ ] Menus are `<ul>` of `<li>` rows; rows are links
+- [ ] Selected row has `aria-current="page"`; others do not
+- [ ] `data-state` reflects expanded/collapsed
+- [ ] Collapsed rows keep an accessible name (sr-only label, not removed)
+- [ ] All rows reachable via Tab; focus ring meets 3:1