@arbor-education/design-system.components 0.25.9 → 1.0.0

package/src/components/sideNavigation/SideNavigation.stories.tsx

@@ -0,0 +1,578 @@
+import {
+  Controls,
+  Heading as DocHeading,
+  Primary as DocPrimary,
+  Markdown,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
+import { useState } from 'react';
+import { Sidebar } from '../sidebar/Sidebar.js';
+import { SidebarItem } from '../sidebar/SidebarItem.js';
+import { SideNavigation } from './SideNavigation.js';
+import type { SideNavigationNode, SideNavigationRenderLinkArgs } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'SideNavigation is a labelled navigation panel — the companion to the separate icon-only `Sidebar` rail.',
+  'Where `Sidebar` is a slim column of icon-only top-level destinations, `SideNavigation` is the fuller panel',
+  'that shows readable labels, nested groups, and per-item "favourite" stars.',
+  '',
+  'SideNavigation supports two mutually exclusive APIs:',
+  '',
+  '1. **Data-driven** — pass an `items` array of `SideNavigation.Node` objects and let the component render the tree.',
+  '2. **Composable** — build the tree yourself from `SideNavigation.Title`, `SideNavigation.Group`, and',
+  '   `SideNavigation.Item` as JSX children.',
+  '',
+  '> **`items` and `children` are mutually exclusive.** If both are passed, `items` silently wins and `children`',
+  '> is dropped entirely — no warning, no error.',
+  '',
+  '> **Built on [Radix UI Tooltip](https://www.radix-ui.com/primitives/docs/components/tooltip).**',
+  '> The whole tree is wrapped in a `Tooltip.Provider` internally so the favourite-star buttons can show their',
+  '> tooltips without any extra setup.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Persistent navigation with readable labels** — school registers, reports, settings sub-pages',
+  '- **Grouped destinations** — related links nested under a collapsible, labelled group',
+  '- **Favouritable destinations** — let users pin frequently-used pages for quick access',
+  '- **Alongside the icon-only `Sidebar` rail** — as the detail panel that opens once a rail item is selected',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Switching between views of the *same* page content | [`Tabs`](?path=/docs/components-tabs--docs) |',
+  '| Compact, on-demand action menu | [`Dropdown`](?path=/docs/components-dropdown--docs) |',
+  '| Top-level icon-only rail with a handful of destinations | [`Sidebar`](?path=/docs/components-sidebar--docs) |',
+  '| A single flat list with no grouping or favouriting | A plain `<nav>` with a `<ul>` may be simpler |',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`items` and `children` are mutually exclusive.** Passing both means `children` is silently discarded in',
+  'favour of `items` — there is no runtime warning. Pick one API per instance.',
+  '',
+  '**`itemId` is required and load-bearing.** It drives `data-testid="side-navigation-item-{itemId}"` on the',
+  'list item, and `data-testid="side-navigation-item-favourite-{itemId}"` on the favourite button when',
+  '`canFavourite` is set.',
+  '',
+  '**`canFavourite: true` requires `favouriteTooltip`** via a TypeScript discriminated union — the compiler',
+  'enforces this before you ever open a browser.',
+  '',
+  '**Favourite clicks never bubble to the parent link/button.** `SideNavigationItemFavourite` calls',
+  '`stopPropagation` and `preventDefault` internally, so favouriting an item never triggers navigation.',
+  '',
+  '**`aria-current="page"` applies on both link and button item variants** when `current` is true — it is not',
+  'a link-only affordance.',
+  '',
+  '**`renderLink` is root-level only.** It is configured once on `<SideNavigation>` and threaded to every',
+  'descendant item via context. There is no per-item override.',
+  '',
+  '**Groups can be controlled or uncontrolled.** Pass `expanded` + `onExpandedChange` for controlled state,',
+  'or `defaultExpanded` (default `false`) for uncontrolled.',
+  '',
+  '**Known limitation — nested indentation does not deepen per level.** The CSS rule for items inside a group',
+  'reasserts the *same* `padding-left` value as a top-level item, rather than adding to it — an item nested two',
+  'groups deep sits at the same indent as an item nested one group deep. See the NestedIndentationLimitation',
+  'story for a faithful demonstration; do not attempt to "fix" this locally with inline padding.',
+  '',
+  '**The current-item highlight uses base brand tokens, not semantic ones.** `--color-brand-050`/',
+  '`--color-brand-800` is a proper AA-safe pairing, but this design system does not yet have a semantic',
+  '"selected" token family to reach for instead.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The root renders a `<nav aria-label>` (default `"Side navigation"`) — override with a meaningful value',
+  '  when a page has more than one nav landmark',
+  '- Groups render `aria-expanded` + `aria-controls` on the toggle button, with a genuinely `aria-hidden`',
+  '  child list when collapsed',
+  '- The favourite button exposes `aria-pressed` and uses `favouriteTooltip` as its `aria-label` — the tooltip',
+  '  text doubles as the sole accessible name for the icon-only button',
+  '- `aria-current="page"` marks the active destination on both link and button item variants',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { SideNavigation } from '@arbor-education/design-system.components';",
+  '',
+  'function MyPanel(props: SideNavigation.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `SideNavigation.Props` | Root component props |',
+  '| `SideNavigation.GroupProps` | `SideNavigation.Group` props |',
+  '| `SideNavigation.ItemProps` | `SideNavigation.Item` props |',
+  '| `SideNavigation.TitleProps` | `SideNavigation.Title` props |',
+  '| `SideNavigation.Node` | Data-driven `items` array element (item or group) |',
+  '| `SideNavigation.ItemNode` | Data-driven leaf item node |',
+  '| `SideNavigation.GroupNode` | Data-driven group node |',
+  '| `SideNavigation.RenderLinkArgs` | Shape passed to a `renderLink` function |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Sidebar](?path=/docs/components-sidebar--docs) — the companion icon-only navigation rail SideNavigation',
+  'typically sits alongside · [Tooltip](?path=/docs/components-tooltip--docs) — powers the favourite button\'s',
+  'tooltip internally',
+].join('\n');
+
+function SideNavigationDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+const meta = {
+  title: 'Components/SideNavigation',
+  component: SideNavigation,
+  parameters: {
+    layout: 'padded',
+    docs: { page: SideNavigationDocsPage },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible label for the `<nav>` landmark.',
+      table: { type: { summary: 'string' }, defaultValue: { summary: '"Side navigation"' } },
+    },
+    items: {
+      control: false,
+      description: [
+        'Data-driven tree of `SideNavigationNode` objects (item and group nodes).',
+        'Mutually exclusive with `children` — if both are supplied, `items` wins and `children` is silently dropped.',
+      ].join(' '),
+      table: { type: { summary: 'SideNavigationNode[]' } },
+    },
+    renderLink: {
+      control: false,
+      description: [
+        'Render-prop for swapping the internal `<a>` for a router-aware Link component.',
+        'Configured once at the root and shared by every descendant item via context — there is no per-item override.',
+      ].join(' '),
+      table: { type: { summary: '(args: SideNavigationRenderLinkArgs) => React.ReactElement' } },
+    },
+    children: {
+      control: false,
+      description: [
+        'Composable JSX tree built from `SideNavigation.Title`, `SideNavigation.Group`, and `SideNavigation.Item`.',
+        'Mutually exclusive with `items`.',
+      ].join(' '),
+      table: { type: { summary: 'ReactNode' } },
+    },
+  },
+} satisfies Meta<typeof SideNavigation>;
+
+export default meta;
+type Story = StoryObj<typeof SideNavigation>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Shared data
+// ---------------------------------------------------------------------------
+
+const dataDrivenItems: SideNavigationNode[] = [
+  { type: 'item', id: 'daily-attendance', label: 'Daily Attendance', href: '#daily-attendance', current: true },
+  { type: 'item', id: 'covid-dashboard', label: 'Covid-19 Dashboard', href: '#covid-dashboard' },
+  { type: 'item', id: 'latecomers', label: 'Latecomers', href: '#latecomers' },
+  { type: 'item', id: 'quick-follow-up', label: 'Quick Follow-Up', href: '#quick-follow-up' },
+];
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const DefaultTemplate = () => (
+  <SideNavigation>
+    <SideNavigation.Title>Attendance</SideNavigation.Title>
+    <SideNavigation.Item itemId="daily-attendance" href="#daily-attendance" current>
+      Daily Attendance
+    </SideNavigation.Item>
+    <SideNavigation.Item itemId="covid-dashboard" href="#covid-dashboard">
+      Covid-19 Dashboard
+    </SideNavigation.Item>
+    <SideNavigation.Item itemId="latecomers" href="#latecomers">
+      Latecomers
+    </SideNavigation.Item>
+    <SideNavigation.Item itemId="quick-follow-up" href="#quick-follow-up">
+      Quick Follow-Up
+    </SideNavigation.Item>
+  </SideNavigation>
+);
+
+const DataDrivenTemplate = () => (
+  <SideNavigation ariaLabel="Attendance" items={dataDrivenItems} />
+);
+
+const WithGroupsTemplate = () => (
+  <SideNavigation>
+    <SideNavigation.Title>Registers &amp; Attendance</SideNavigation.Title>
+    <SideNavigation.Group label="Registers" defaultExpanded>
+      <SideNavigation.Item itemId="daily-attendance" href="#daily-attendance" current>
+        Daily Attendance
+      </SideNavigation.Item>
+      <SideNavigation.Item itemId="covid-dashboard" href="#covid-dashboard">
+        Covid-19 Dashboard
+      </SideNavigation.Item>
+    </SideNavigation.Group>
+    <SideNavigation.Group label="Absentees">
+      <SideNavigation.Item itemId="latecomers" href="#latecomers">
+        Latecomers
+      </SideNavigation.Item>
+      <SideNavigation.Item itemId="statistics" href="#statistics">
+        Statistics
+      </SideNavigation.Item>
+    </SideNavigation.Group>
+  </SideNavigation>
+);
+
+const ControlledGroupExpansionTemplate = () => {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+      <Button variant="secondary" size="S" onClick={() => setExpanded(prev => !prev)}>
+        {expanded ? 'Collapse "Absentees" externally' : 'Expand "Absentees" externally'}
+      </Button>
+      <SideNavigation>
+        <SideNavigation.Title>Registers &amp; Attendance</SideNavigation.Title>
+        <SideNavigation.Group label="Absentees" expanded={expanded} onExpandedChange={setExpanded}>
+          <SideNavigation.Item itemId="latecomers" href="#latecomers">
+            Latecomers
+          </SideNavigation.Item>
+          <SideNavigation.Item itemId="statistics" href="#statistics">
+            Statistics
+          </SideNavigation.Item>
+        </SideNavigation.Group>
+      </SideNavigation>
+    </div>
+  );
+};
+
+const interactiveNavItems = [
+  { id: 'daily-attendance', label: 'Daily Attendance' },
+  { id: 'covid-dashboard', label: 'Covid-19 Dashboard' },
+  { id: 'latecomers', label: 'Latecomers' },
+  { id: 'statistics', label: 'Statistics' },
+];
+
+const InteractiveCurrentItemTemplate = () => {
+  const [activeItemId, setActiveItemId] = useState('daily-attendance');
+
+  return (
+    <SideNavigation>
+      <SideNavigation.Title>Registers</SideNavigation.Title>
+      {interactiveNavItems.map(item => (
+        <SideNavigation.Item
+          key={item.id}
+          itemId={item.id}
+          linkElement="button"
+          current={activeItemId === item.id}
+          linkElementProps={{ onClick: () => setActiveItemId(item.id) }}
+        >
+          {item.label}
+        </SideNavigation.Item>
+      ))}
+    </SideNavigation>
+  );
+};
+
+const FavouritableItemsTemplate = () => {
+  const [favourites, setFavourites] = useState<Record<string, boolean>>({
+    'daily-attendance': true,
+    'covid-dashboard': false,
+    'latecomers': false,
+  });
+
+  const toggleFavourite = (id: string) => {
+    setFavourites(prev => ({ ...prev, [id]: !prev[id] }));
+  };
+
+  return (
+    <SideNavigation>
+      <SideNavigation.Title>Registers</SideNavigation.Title>
+      <SideNavigation.Item
+        itemId="daily-attendance"
+        href="#daily-attendance"
+        canFavourite
+        isPressed={favourites['daily-attendance']}
+        favouriteTooltip={favourites['daily-attendance'] ? 'Remove from favourites' : 'Add to favourites'}
+        onFavouriteClick={() => toggleFavourite('daily-attendance')}
+      >
+        Daily Attendance
+      </SideNavigation.Item>
+      <SideNavigation.Item
+        itemId="covid-dashboard"
+        href="#covid-dashboard"
+        canFavourite
+        isPressed={favourites['covid-dashboard']}
+        favouriteTooltip={favourites['covid-dashboard'] ? 'Remove from favourites' : 'Add to favourites'}
+        onFavouriteClick={() => toggleFavourite('covid-dashboard')}
+      >
+        Covid-19 Dashboard
+      </SideNavigation.Item>
+      <SideNavigation.Item
+        itemId="latecomers"
+        href="#latecomers"
+        canFavourite
+        isPressed={favourites.latecomers}
+        favouriteTooltip={favourites.latecomers ? 'Remove from favourites' : 'Add to favourites'}
+        onFavouriteClick={() => toggleFavourite('latecomers')}
+      >
+        Latecomers
+      </SideNavigation.Item>
+    </SideNavigation>
+  );
+};
+
+const MixedLinkAndButtonItemsTemplate = () => (
+  <SideNavigation>
+    <SideNavigation.Title>My Account</SideNavigation.Title>
+    <SideNavigation.Item itemId="settings" href="#settings" current>
+      Settings
+    </SideNavigation.Item>
+    <SideNavigation.Item itemId="quick-follow-up" href="#quick-follow-up">
+      Quick Follow-Up
+    </SideNavigation.Item>
+    <SideNavigation.Item
+      itemId="log-out"
+      linkElement="button"
+      linkElementProps={{ onClick: () => {} }}
+    >
+      Log out
+    </SideNavigation.Item>
+  </SideNavigation>
+);
+
+function MockRouterLink(args: SideNavigationRenderLinkArgs) {
+  const { href, className, children, ariaCurrent, onClick, linkProps, linkElementProps } = args;
+  return (
+    <a
+      href={href}
+      className={className}
+      aria-current={ariaCurrent}
+      onClick={onClick}
+      data-mock-router-link="true"
+      {...linkProps}
+      {...linkElementProps}
+    >
+      {children}
+    </a>
+  );
+}
+
+const RenderLinkIntegrationTemplate = () => (
+  <SideNavigation renderLink={args => <MockRouterLink {...args} />}>
+    <SideNavigation.Title>Registers</SideNavigation.Title>
+    <SideNavigation.Item itemId="daily-attendance" href="#daily-attendance" current>
+      Daily Attendance
+    </SideNavigation.Item>
+    <SideNavigation.Item itemId="covid-dashboard" href="#covid-dashboard">
+      Covid-19 Dashboard
+    </SideNavigation.Item>
+  </SideNavigation>
+);
+
+const NestedIndentationLimitationTemplate = () => (
+  <SideNavigation>
+    <SideNavigation.Title>Registers</SideNavigation.Title>
+    <SideNavigation.Group label="Registers" defaultExpanded>
+      <SideNavigation.Item itemId="daily-attendance" href="#daily-attendance">
+        Daily Attendance (nested one level)
+      </SideNavigation.Item>
+      <SideNavigation.Group label="Absentees" defaultExpanded>
+        <SideNavigation.Item itemId="latecomers" href="#latecomers">
+          Latecomers (nested two levels)
+        </SideNavigation.Item>
+        <SideNavigation.Item itemId="statistics" href="#statistics">
+          Statistics (nested two levels)
+        </SideNavigation.Item>
+      </SideNavigation.Group>
+    </SideNavigation.Group>
+  </SideNavigation>
+);
+
+const WithSidebarRailTemplate = () => (
+  <div style={{ display: 'flex', gap: 'var(--spacing-large)' }}>
+    <Sidebar ariaLabel="Primary navigation">
+      <SidebarItem href="#attendance" aria-label="Attendance" selected>
+        <Icon name="date" size={24} />
+      </SidebarItem>
+      <SidebarItem href="#settings" aria-label="Settings">
+        <Icon name="settings" size={24} />
+      </SidebarItem>
+    </Sidebar>
+    {/* SideNavigation sizes itself via `--sidebar-nav-panel-width` — no wrapper width needed. */}
+    <SideNavigation>
+      <SideNavigation.Title>Attendance</SideNavigation.Title>
+      <SideNavigation.Item itemId="daily-attendance" href="#daily-attendance" current>
+        Daily Attendance
+      </SideNavigation.Item>
+      <SideNavigation.Item itemId="covid-dashboard" href="#covid-dashboard">
+        Covid-19 Dashboard
+      </SideNavigation.Item>
+      <SideNavigation.Item itemId="latecomers" href="#latecomers">
+        Latecomers
+      </SideNavigation.Item>
+    </SideNavigation>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  { render: DefaultTemplate },
+  'The composable JSX API: build the tree by hand from `SideNavigation.Title` and `SideNavigation.Item`. Reach for this when hand-authoring a navigation panel directly in a page component.',
+);
+
+export const DataDriven: Story = withDescription(
+  {
+    render: DataDrivenTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SideNavigation } from '@arbor-education/design-system.components';
+
+const items: SideNavigation.Node[] = [
+  { type: 'item', id: 'daily-attendance', label: 'Daily Attendance', href: '#daily-attendance', current: true },
+  { type: 'item', id: 'covid-dashboard', label: 'Covid-19 Dashboard', href: '#covid-dashboard' },
+  { type: 'item', id: 'latecomers', label: 'Latecomers', href: '#latecomers' },
+  { type: 'item', id: 'quick-follow-up', label: 'Quick Follow-Up', href: '#quick-follow-up' },
+];
+
+function DataDrivenExample() {
+  return <SideNavigation ariaLabel="Attendance" items={items} />;
+}
+export default DataDrivenExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The same visual result as Default, built from a data-driven `items` array of `SideNavigation.Node` objects instead of hand-written JSX. Ideal when your navigation tree comes from config, a CMS, or is generated at runtime.',
+);
+
+export const WithGroups: Story = withDescription(
+  { render: WithGroupsTemplate, parameters: { controls: { disable: true } } },
+  'Group related destinations under a collapsible, labelled group with `SideNavigation.Group`. "Registers" is expanded by default (`defaultExpanded`); "Absentees" starts collapsed — click its label to expand it.',
+);
+
+export const ControlledGroupExpansion: Story = withDescription(
+  { render: ControlledGroupExpansionTemplate, parameters: { controls: { disable: true } } },
+  'A group can be fully controlled by passing both `expanded` and `onExpandedChange` instead of `defaultExpanded`. The external button proves this genuinely mirrors outside state — clicking the group\'s own label still works too, via `onExpandedChange`.',
+);
+
+export const InteractiveCurrentItem: Story = withDescription(
+  { render: InteractiveCurrentItemTemplate, parameters: { controls: { disable: true } } },
+  'Click any item to see `current` (and the `aria-current="page"` it drives) move with it — simulating real navigation selection without needing a router in Storybook. `linkElement="button"` is used here specifically so clicking stays on this page.',
+);
+
+export const FavouritableItems: Story = withDescription(
+  { render: FavouritableItemsTemplate, parameters: { controls: { disable: true } } },
+  'Setting `canFavourite` requires `favouriteTooltip` at compile time via a TypeScript discriminated union. Clicking the star calls `onFavouriteClick` without ever triggering the item\'s own link/button navigation — the click is stopped and prevented internally.',
+);
+
+export const MixedLinkAndButtonItems: Story = withDescription(
+  { render: MixedLinkAndButtonItemsTemplate, parameters: { controls: { disable: true } } },
+  'A realistic navigation panel combining `href`-based items that genuinely navigate with a `linkElement="button"` item for an action like "Log out" that should never be a link. Both variants share the same visual styling and support `current`/`aria-current`.',
+);
+
+export const RenderLinkIntegration: Story = withDescription(
+  {
+    render: RenderLinkIntegrationTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SideNavigation } from '@arbor-education/design-system.components';
+
+// Stand-in for a router's Link component (e.g. React Router's <Link>).
+function MockRouterLink({ href, className, children, ariaCurrent, onClick, linkProps, linkElementProps }: SideNavigation.RenderLinkArgs) {
+  return (
+    <a href={href} className={className} aria-current={ariaCurrent} onClick={onClick} {...linkProps} {...linkElementProps}>
+      {children}
+    </a>
+  );
+}
+
+function RenderLinkIntegrationExample() {
+  return (
+    <SideNavigation renderLink={args => <MockRouterLink {...args} />}>
+      <SideNavigation.Title>Registers</SideNavigation.Title>
+      <SideNavigation.Item itemId="daily-attendance" href="#daily-attendance" current>
+        Daily Attendance
+      </SideNavigation.Item>
+      <SideNavigation.Item itemId="covid-dashboard" href="#covid-dashboard">
+        Covid-19 Dashboard
+      </SideNavigation.Item>
+    </SideNavigation>
+  );
+}
+export default RenderLinkIntegrationExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  '`renderLink` is set once, at the root, and every descendant item uses it via context — there is no per-item override. In a real app, pass your router\'s `<Link>` component here instead of the `MockRouterLink` stand-in shown in this story.',
+);
+
+export const NestedIndentationLimitation: Story = withDescription(
+  { render: NestedIndentationLimitationTemplate, parameters: { controls: { disable: true } } },
+  '**Known limitation, documented honestly rather than hidden:** the styling for an item link inside a group reasserts the exact same `padding-left` as a top-level item link — it does not accumulate per nesting level. "Latecomers", nested two groups deep, sits at the same indent as "Daily Attendance", nested one group deep. This is a genuine limitation of the current CSS, not a mistake in this story — do not fix it locally with inline padding, as that would only mask the underlying rule.',
+);
+
+export const WithSidebarRail: Story = withDescription(
+  { render: WithSidebarRailTemplate, parameters: { controls: { disable: true } } },
+  'The realistic paired layout: the icon-only `Sidebar` rail alongside a fuller, labelled `SideNavigation` panel. `SideNavigation` is styled as a panel by default — width (`--sidebar-nav-panel-width`), gap, and overflow are all built in, so no wrapper styling is needed here.',
+);

package/src/components/sideNavigation/SideNavigation.test.tsx

@@ -0,0 +1,109 @@
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, test, vi } from 'vitest';
+import { SideNavigation } from './SideNavigation.js';
+import { SideNavigationItem } from './SideNavigationItem.js';
+
+describe('SideNavigation', () => {
+  test('renders a nav with the default ariaLabel', () => {
+    render(<SideNavigation items={[]} />);
+    expect(screen.getByRole('navigation', { name: 'Side navigation' })).toBeInTheDocument();
+  });
+
+  test('renders a nav with a custom ariaLabel', () => {
+    render(<SideNavigation ariaLabel="Attendance navigation" items={[]} />);
+    expect(screen.getByRole('navigation', { name: 'Attendance navigation' })).toBeInTheDocument();
+  });
+
+  test('renders composable children when items is omitted', () => {
+    render(
+      <SideNavigation>
+        <SideNavigationItem itemId="daily" href="/daily">Daily Attendance</SideNavigationItem>
+      </SideNavigation>,
+    );
+    expect(screen.getByRole('link', { name: 'Daily Attendance' })).toBeInTheDocument();
+  });
+
+  test('renders leaf items from the data-driven items prop', () => {
+    render(
+      <SideNavigation
+        items={[
+          { type: 'item', id: 'daily', label: 'Daily Attendance', href: '/daily' },
+        ]}
+      />,
+    );
+    expect(screen.getByRole('link', { name: 'Daily Attendance' })).toHaveAttribute('href', '/daily');
+  });
+
+  test('renders groups from the data-driven items prop and expands them on click', async () => {
+    render(
+      <SideNavigation
+        items={[
+          {
+            type: 'group',
+            id: 'registers',
+            label: 'Registers',
+            children: [
+              { type: 'item', id: 'daily', label: 'Daily Attendance', href: '/daily' },
+            ],
+          },
+        ]}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', { name: 'Registers' });
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    await userEvent.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    expect(screen.getByRole('link', { name: 'Daily Attendance' })).toBeInTheDocument();
+  });
+
+  test('renders nested groups from the data-driven items prop', () => {
+    render(
+      <SideNavigation
+        items={[
+          {
+            type: 'group',
+            id: 'a',
+            label: 'A',
+            defaultExpanded: true,
+            children: [
+              {
+                type: 'group',
+                id: 'b',
+                label: 'B',
+                defaultExpanded: true,
+                children: [
+                  { type: 'item', id: 'c', label: 'C', href: '/c' },
+                ],
+              },
+            ],
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'A' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'B' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'C' })).toBeInTheDocument();
+  });
+
+  test('applies renderLink to items produced from the items prop', () => {
+    const renderLink = vi.fn(({ href, className, children }) => (
+      <a href={href} className={className} data-custom-link="true">
+        {children}
+      </a>
+    ));
+
+    render(
+      <SideNavigation
+        renderLink={renderLink}
+        items={[{ type: 'item', id: 'daily', label: 'Daily Attendance', href: '/daily' }]}
+      />,
+    );
+
+    expect(screen.getByText('Daily Attendance').closest('a')).toHaveAttribute('data-custom-link', 'true');
+  });
+});