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

package/src/components/sidebar/Sidebar.stories.tsx

@@ -0,0 +1,670 @@
+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 { Badge } from 'Components/badge/Badge';
+import { Icon } from 'Components/icon/Icon';
+import { Separator } from 'Components/separator/Separator';
+import { useState } from 'react';
+import { Sidebar } from './Sidebar.js';
+import { SidebarItem } from './SidebarItem.js';
+import { SideNavigation } from 'Components/sideNavigation/SideNavigation.js';
+import type { SideNavigationNode } from 'Components/sideNavigation/types.js';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Sidebar is the narrow icon rail that anchors an application\'s primary navigation.',
+  'It renders a semantic `<nav>` element containing `Sidebar.Item` entries and optionally',
+  'pairs with a `SideNavigation` panel beside it.',
+  '',
+  'Each `Sidebar.Item` renders as either a `<button>` (no `href`) or an `<a>` (with `href`),',
+  'with an icon centred in a square touch target. Hovering or focusing an item reveals a tooltip',
+  'to the right — each item wraps itself in its own `Tooltip`, so tooltips are fully self-contained',
+  'and need no provider from `Sidebar`.',
+  '',
+  '## Compound component API',
+  '',
+  '| Sub-component | Description |',
+  '|---|---|',
+  '| `<Sidebar />` | Root — renders a `<nav>`. |',
+  '| `<Sidebar.Item />` | Navigation item. No `href` → `<button>`; with `href` → `<a>`. |',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Application shell navigation** — persistent icon rail with tooltips for home, favourites, calendar, etc.',
+  '- **MIS module navigation** — rail icons paired with a `SideNavigation` panel for hierarchical links.',
+  '- **Any layout where navigation labels should be hidden by default** — icons only, labels on demand.',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Horizontal top-level product nav | `Menubar` or app header patterns |',
+  '| Navigation labels must always be visible | `SideNavigation` alone, or a nav with visible text links |',
+  '| Single flat list of links | `Tabs` or plain links |',
+  '| Account / settings dropdown menu | `Dropdown` |',
+  '| Inline or contextual page navigation | `SideNavigation` without the icon rail |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### `aria-label` on every `Sidebar.Item` is effectively required',
+  '',
+  'The `aria-label` prop on `Sidebar.Item` does **two jobs at once**: it is the accessible name of the',
+  'interactive element (announced by screen readers) **and** the text shown in the right-side tooltip.',
+  'Without it, screen reader users receive no meaningful label and the tooltip renders blank.',
+  '',
+  '```tsx',
+  '// ✅ Good',
+  '<Sidebar.Item aria-label="Daily Attendance" selected={active === \'attendance\'} onClick={...}>',
+  '  <Icon name="favourite-outline" size={24} />',
+  '</Sidebar.Item>',
+  '',
+  '// ❌ Bad — tooltip is empty, icon is inaccessible to screen readers',
+  '<Sidebar.Item selected={active === \'attendance\'} onClick={...}>',
+  '  <Icon name="favourite-outline" size={24} />',
+  '</Sidebar.Item>',
+  '```',
+  '',
+  '---',
+  '',
+  '### The `selected` prop does two things',
+  '',
+  '`selected={true}` simultaneously:',
+  '1. Applies `ds-sidebar__item--selected` (the selected visual style)',
+  '2. Sets `aria-current="true"` on the underlying `<button>` or `<a>`',
+  '',
+  'The attribute is always rendered — even `aria-current="false"` is present when `selected` is falsy.',
+  '**Do not manage `aria-current` separately** — the component handles it.',
+  '',
+  '---',
+  '',
+  '### Button vs link — decided by `href` alone',
+  '',
+  '- No `href` → `<button type="button">` — use for SPA actions, panel toggles, modals',
+  '- With `href` → `<a>` — use for real URL navigation',
+  '',
+  'Visual output is identical. The choice is purely semantic.',
+  '',
+  '---',
+  '',
+  '### Each item\'s tooltip is a self-contained provider',
+  '',
+  'Every `Sidebar.Item` wraps itself in its own `Tooltip`, each with its own Radix provider.',
+  'This means tooltips work with no setup from `Sidebar`, but Radix\'s shared skip-delay behaviour',
+  '(where subsequent tooltips open instantly after the first) does **not** apply across items —',
+  'each item\'s open delay is independent.',
+  '',
+  '---',
+  '',
+  '### Badge overlay',
+  '',
+  'A `Badge` child inside `Sidebar.Item` is automatically positioned absolutely in the top-right corner',
+  'by `sidebar.scss`. No extra styling needed:',
+  '',
+  '```tsx',
+  '<Sidebar.Item aria-label="Notifications — 6 unread" selected={false}>',
+  '  <Icon name="message-square-more" size={24} />',
+  '  <Badge size="sm" colour="salmon">6</Badge>',
+  '</Sidebar.Item>',
+  '```',
+  '',
+  'Include the count in `aria-label` so screen reader users also receive the notification total.',
+  '',
+  '---',
+  '',
+  '### Panel pattern',
+  '',
+  '`SideNavigation` is a separate companion component — **not** a sub-component of `Sidebar`. It is styled as',
+  'a panel by default (width, gap, and overflow are built in), so render it as a flex sibling of `Sidebar`:',
+  '',
+  '```tsx',
+  'const [panelOpen, setPanelOpen] = useState(true);',
+  '',
+  '<div style={{ display: \'flex\', height: \'100%\' }}>',
+  '  <Sidebar>',
+  '    <Sidebar.Item',
+  '      aria-label="Toggle navigation panel"',
+  '      selected={panelOpen}',
+  '      aria-expanded={panelOpen}',
+  '      aria-controls="side-panel"',
+  '      onClick={() => setPanelOpen(o => !o)}',
+  '    >',
+  '      <Icon name="menu" size={24} />',
+  '    </Sidebar.Item>',
+  '  </Sidebar>',
+  '  {panelOpen && (',
+  '    <div style={{ display: \'flex\', flexDirection: \'column\' }}>',
+  '      <SideNavigation.Title>Attendance</SideNavigation.Title>',
+  '      <SideNavigation id="side-panel" items={navItems} />',
+  '    </div>',
+  '  )}',
+  '</div>',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The `Sidebar` root renders a `<nav>` landmark. Set `ariaLabel` to a meaningful value when the',
+  '  page contains more than one `<nav>` (default is `"Sidebar"`)',
+  '- All items are natively focusable (`<button>` or `<a>`) — tab order follows DOM order',
+  '- The tooltip surfaces on both hover **and** keyboard focus — keyboard users see labels too',
+  '- Icons carry `aria-hidden="true"` automatically; `aria-label` on the item is the sole accessible name',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Sidebar, SidebarItem } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '---',
+  '',
+  '### Test IDs',
+  '',
+  '| Element | `data-testid` |',
+  '|---|---|',
+  '| Rail nav | `sidebar` |',
+  '| Individual item | pass `data-testid` directly to `<Sidebar.Item>` |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[SideNavigation](?path=/docs/components-sidenavigation--docs) — the hierarchical tree panel that pairs with the Sidebar rail',
+  '',
+  '[Separator](?path=/docs/components-separator--docs) · [Tooltip](?path=/docs/components-tooltip--docs) · [Badge](?path=/docs/components-badge--docs)',
+].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.';
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function SidebarDocsPage() {
+  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>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Components/Sidebar',
+  component: Sidebar,
+  parameters: {
+    layout: 'padded',
+    docs: { page: SidebarDocsPage },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    ariaLabel: {
+      control: 'text',
+      description: [
+        'Accessible label for the `<nav>` landmark.',
+        'Defaults to `"Sidebar"`. Provide a meaningful value when the page has more than one `<nav>`',
+        '— screen readers list nav landmarks by their label.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: '"Sidebar"' },
+      },
+    },
+    children: {
+      control: false,
+      description: 'Use `Sidebar.Item` and `Separator` as direct children.',
+      table: { type: { summary: 'ReactNode' } },
+    },
+  },
+} satisfies Meta<typeof Sidebar>;
+
+export default meta;
+type Story = StoryObj<typeof Sidebar>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Shared data
+// ---------------------------------------------------------------------------
+
+const storyWrapperStyle: React.CSSProperties = { display: 'flex', height: 640 };
+
+const basePanelNavItems: SideNavigationNode[] = [
+  {
+    type: 'group',
+    id: 'registers',
+    label: 'Registers',
+    defaultExpanded: true,
+    children: [
+      { type: 'item', id: 'covid', label: 'Covid-19 Dashboard', href: '/covid' },
+      { type: 'item', id: 'daily', label: 'Daily Attendance', href: '/daily', current: true },
+      { type: 'item', id: 'quick', label: 'Quick Follow-Up', href: '/quick' },
+    ],
+  },
+  {
+    type: 'group',
+    id: 'absentees',
+    label: 'Absentees',
+    children: [
+      { type: 'item', id: 'late', label: 'Latecomers', href: '/latecomers' },
+      { type: 'item', id: 'stats', label: 'Statistics', href: '/statistics' },
+    ],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const DefaultTemplate = () => {
+  const [active, setActive] = useState<string>('favourites');
+
+  return (
+    <div style={storyWrapperStyle}>
+      <Sidebar ariaLabel="App navigation">
+        <SidebarItem
+          aria-label="Favourites"
+          selected={active === 'favourites'}
+          onClick={() => setActive('favourites')}
+        >
+          <Icon name="favourite-outline" size={24} />
+        </SidebarItem>
+        <SidebarItem
+          aria-label="Notifications"
+          selected={active === 'notifications'}
+          onClick={() => setActive('notifications')}
+        >
+          <Icon name="message-square-more" size={24} />
+        </SidebarItem>
+        <SidebarItem
+          aria-label="My Calendar"
+          selected={active === 'calendar'}
+          onClick={() => setActive('calendar')}
+        >
+          <Icon name="date" size={24} />
+        </SidebarItem>
+      </Sidebar>
+    </div>
+  );
+};
+
+const WithSeparatorsTemplate = () => {
+  const [active, setActive] = useState<string>('favourites');
+
+  return (
+    <div style={storyWrapperStyle}>
+      <Sidebar ariaLabel="App navigation">
+        <SidebarItem
+          aria-label="Favourites"
+          selected={active === 'favourites'}
+          onClick={() => setActive('favourites')}
+        >
+          <Icon name="favourite-outline" size={24} />
+        </SidebarItem>
+        <SidebarItem
+          aria-label="Notifications"
+          selected={active === 'notifications'}
+          onClick={() => setActive('notifications')}
+        >
+          <Icon name="message-square-more" size={24} />
+        </SidebarItem>
+        <SidebarItem
+          aria-label="My Calendar"
+          selected={active === 'calendar'}
+          onClick={() => setActive('calendar')}
+        >
+          <Icon name="date" size={24} />
+        </SidebarItem>
+        <Separator orientation="horizontal" decorative />
+        <SidebarItem
+          aria-label="Emergency Alerts"
+          selected={active === 'emergency'}
+          onClick={() => setActive('emergency')}
+        >
+          <Icon name="triangle-alert" size={24} />
+        </SidebarItem>
+        <Separator orientation="horizontal" decorative />
+        <SidebarItem
+          aria-label="Help & Learn with Arbor"
+          selected={active === 'help'}
+          onClick={() => setActive('help')}
+        >
+          <Icon name="circle-help" size={24} />
+        </SidebarItem>
+      </Sidebar>
+    </div>
+  );
+};
+
+const WithBadgeTemplate = () => {
+  const [active, setActive] = useState<string>('favourites');
+
+  return (
+    <div style={storyWrapperStyle}>
+      <Sidebar ariaLabel="App navigation">
+        <SidebarItem
+          aria-label="Favourites"
+          selected={active === 'favourites'}
+          onClick={() => setActive('favourites')}
+        >
+          <Icon name="favourite-outline" size={24} />
+        </SidebarItem>
+        <SidebarItem
+          aria-label="Notifications — 6 unread"
+          selected={active === 'notifications'}
+          onClick={() => setActive('notifications')}
+        >
+          <Icon name="message-square-more" size={24} />
+          <Badge size="sm" colour="salmon">6</Badge>
+        </SidebarItem>
+        <SidebarItem
+          aria-label="Emergency Alerts — 2 active"
+          selected={active === 'emergency'}
+          onClick={() => setActive('emergency')}
+        >
+          <Icon name="triangle-alert" size={24} />
+          <Badge size="sm" colour="yellow">2</Badge>
+        </SidebarItem>
+        <SidebarItem
+          aria-label="My Calendar"
+          selected={active === 'calendar'}
+          onClick={() => setActive('calendar')}
+        >
+          <Icon name="date" size={24} />
+        </SidebarItem>
+      </Sidebar>
+    </div>
+  );
+};
+
+const WithPanelTemplate = () => {
+  const [open, setOpen] = useState(true);
+  const [active, setActive] = useState<string>('favourites');
+
+  return (
+    <div style={storyWrapperStyle}>
+      <Sidebar ariaLabel="App navigation">
+        <SidebarItem
+          aria-label="Toggle navigation panel"
+          onClick={() => setOpen(prev => !prev)}
+          selected={open}
+          aria-expanded={open}
+          aria-controls="story-panel"
+        >
+          <Icon name="menu" size={24} />
+        </SidebarItem>
+        <Separator orientation="horizontal" decorative />
+        <SidebarItem
+          aria-label="Favourites"
+          selected={active === 'favourites'}
+          onClick={() => setActive('favourites')}
+        >
+          <Icon name="favourite-outline" size={24} />
+        </SidebarItem>
+        <SidebarItem
+          aria-label="My Calendar"
+          selected={active === 'calendar'}
+          onClick={() => setActive('calendar')}
+        >
+          <Icon name="date" size={24} />
+        </SidebarItem>
+      </Sidebar>
+      {open && (
+        <div style={{ display: 'flex', flexDirection: 'column' }}>
+          <SideNavigation.Title>Attendance</SideNavigation.Title>
+          <SideNavigation id="story-panel" items={basePanelNavItems} />
+        </div>
+      )}
+    </div>
+  );
+};
+
+const WithLinksTemplate = () => (
+  <div style={storyWrapperStyle}>
+    <Sidebar ariaLabel="App navigation">
+      <SidebarItem href="/favourites" aria-label="Favourites">
+        <Icon name="favourite-outline" size={24} />
+      </SidebarItem>
+      <SidebarItem href="/calendar" aria-label="My Calendar" selected>
+        <Icon name="date" size={24} />
+      </SidebarItem>
+      <Separator orientation="horizontal" decorative />
+      <SidebarItem href="/help" aria-label="Help & Learn with Arbor">
+        <Icon name="circle-help" size={24} />
+      </SidebarItem>
+    </Sidebar>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  { render: DefaultTemplate, parameters: { controls: { disable: true } } },
+  'Button items with interactive active state — click any item to select it. The selected item receives the `ds-sidebar__item--selected` visual state and `aria-current="true"`.',
+);
+
+export const WithSeparators: Story = withDescription(
+  {
+    render: WithSeparatorsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Sidebar, SidebarItem, Separator, Icon } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+function WithSeparatorsExample() {
+  const [active, setActive] = useState('favourites');
+  return (
+    <Sidebar ariaLabel="App navigation">
+      {/* Primary nav group */}
+      <SidebarItem aria-label="Favourites" selected={active === 'favourites'} onClick={() => setActive('favourites')}>
+        <Icon name="favourite-outline" size={24} />
+      </SidebarItem>
+      <SidebarItem aria-label="Notifications" selected={active === 'notifications'} onClick={() => setActive('notifications')}>
+        <Icon name="message-square-more" size={24} />
+      </SidebarItem>
+      <SidebarItem aria-label="My Calendar" selected={active === 'calendar'} onClick={() => setActive('calendar')}>
+        <Icon name="date" size={24} />
+      </SidebarItem>
+      <Separator orientation="horizontal" decorative />
+      {/* Alert group */}
+      <SidebarItem aria-label="Emergency Alerts" selected={active === 'emergency'} onClick={() => setActive('emergency')}>
+        <Icon name="triangle-alert" size={24} />
+      </SidebarItem>
+      <Separator orientation="horizontal" decorative />
+      {/* Utility group */}
+      <SidebarItem aria-label="Help & Learn with Arbor" selected={active === 'help'} onClick={() => setActive('help')}>
+        <Icon name="circle-help" size={24} />
+      </SidebarItem>
+    </Sidebar>
+  );
+}
+export default WithSeparatorsExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Three groups divided by `<Separator orientation="horizontal" decorative />`. A common layout: primary nav / alerts / utility items. Click any item to see the active state.',
+);
+
+export const WithBadge: Story = withDescription(
+  {
+    render: WithBadgeTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Sidebar, SidebarItem, Badge, Icon } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+function WithBadgeExample() {
+  const [active, setActive] = useState('favourites');
+  return (
+    <Sidebar ariaLabel="App navigation">
+      <SidebarItem aria-label="Favourites" selected={active === 'favourites'} onClick={() => setActive('favourites')}>
+        <Icon name="favourite-outline" size={24} />
+      </SidebarItem>
+      {/*
+        Badge is automatically positioned top-right by sidebar.scss — no extra styling needed.
+        Include the count in aria-label so screen reader users also receive the total.
+      */}
+      <SidebarItem aria-label="Notifications — 6 unread" selected={active === 'notifications'} onClick={() => setActive('notifications')}>
+        <Icon name="message-square-more" size={24} />
+        <Badge size="sm" colour="salmon">6</Badge>
+      </SidebarItem>
+      <SidebarItem aria-label="Emergency Alerts — 2 active" selected={active === 'emergency'} onClick={() => setActive('emergency')}>
+        <Icon name="triangle-alert" size={24} />
+        <Badge size="sm" colour="yellow">2</Badge>
+      </SidebarItem>
+    </Sidebar>
+  );
+}
+export default WithBadgeExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'A `<Badge>` child inside `Sidebar.Item` is automatically positioned in the top-right corner by `sidebar.scss` — no wrapper or additional CSS needed. Include the count in `aria-label` so screen reader users also receive the notification total.',
+);
+
+export const WithPanel: Story = withDescription(
+  {
+    render: WithPanelTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Sidebar, SidebarItem, Separator, Icon, SideNavigation } from '@arbor-education/design-system.components';
+
+function WithPanelExample() {
+  const [open, setOpen] = useState(true);
+
+  return (
+    <div style={{ display: 'flex', height: '100%' }}>
+      <Sidebar ariaLabel="App navigation">
+        {/* aria-expanded and aria-controls wire the button to the panel for assistive technology */}
+        <SidebarItem
+          aria-label="Toggle navigation panel"
+          selected={open}
+          aria-expanded={open}
+          aria-controls="side-panel"
+          onClick={() => setOpen(o => !o)}
+        >
+          <Icon name="menu" size={24} />
+        </SidebarItem>
+        <Separator orientation="horizontal" decorative />
+        <SidebarItem aria-label="Favourites" selected={false}>
+          <Icon name="favourite-outline" size={24} />
+        </SidebarItem>
+      </Sidebar>
+
+      {/* SideNavigation is a separate companion component — not a sub-component of Sidebar. */}
+      {/* It is styled as a panel by default, so no extra wrapper class is needed. */}
+      {open && (
+        <div style={{ display: 'flex', flexDirection: 'column' }}>
+          <SideNavigation.Title>Attendance</SideNavigation.Title>
+          <SideNavigation id="side-panel" items={navItems} />
+        </div>
+      )}
+    </div>
+  );
+}
+export default WithPanelExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The burger `Sidebar.Item` toggles a `SideNavigation` panel that sits beside the rail as a flex sibling. `aria-expanded` and `aria-controls` wire the trigger to the panel for assistive technology. Click the menu icon to toggle.',
+);
+
+export const WithLinks: Story = withDescription(
+  {
+    render: WithLinksTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Sidebar, SidebarItem, Separator, Icon } from '@arbor-education/design-system.components';
+
+function WithLinksExample() {
+  return (
+    <Sidebar ariaLabel="App navigation">
+      {/* With href → renders <a>. Without href → renders <button>. Visual output is identical. */}
+      <SidebarItem href="/favourites" aria-label="Favourites">
+        <Icon name="favourite-outline" size={24} />
+      </SidebarItem>
+      <SidebarItem href="/calendar" aria-label="My Calendar" selected>
+        <Icon name="date" size={24} />
+      </SidebarItem>
+      <Separator orientation="horizontal" decorative />
+      <SidebarItem href="/help" aria-label="Help & Learn with Arbor">
+        <Icon name="circle-help" size={24} />
+      </SidebarItem>
+    </Sidebar>
+  );
+}
+export default WithLinksExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Pass `href` to render an `<a>` element instead of a `<button>`. Use links for real URL navigation; use buttons (no `href`) for SPA actions and panel toggles. The visual output is identical for both.',
+);