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

package/dist/components/sidebar/Sidebar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.js","sourceRoot":"","sources":["../../../src/components/sidebar/Sidebar.tsx"],"names":[],"mappings":";AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAC;AAMtE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAmB,EAAE,EAAE;IAC7C,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IACtE,OAAO,CACL,4BACc,SAAS,EACrB,SAAS,EAAE,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC,iBAClC,SAAS,KACjB,IAAI,YAEP,QAAQ,GACL,CACP,CAAC;AACJ,CAAC,CAAC;AAEF,OAAO,CAAC,IAAI,GAAG,WAAW,CAAC"}

package/dist/components/sidebar/Sidebar.stories.d.ts

@@ -0,0 +1,48 @@
+import type { StoryObj } from '@storybook/react-vite';
+import { Sidebar } from './Sidebar.js';
+declare function SidebarDocsPage(): import("react/jsx-runtime").JSX.Element;
+declare const meta: {
+    title: string;
+    component: {
+        (props: import("./Sidebar.js").SidebarProps): import("react/jsx-runtime").JSX.Element;
+        Item: (props: import("./SidebarItem.js").SidebarItemProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    parameters: {
+        layout: string;
+        docs: {
+            page: typeof SidebarDocsPage;
+        };
+    };
+    tags: string[];
+    argTypes: {
+        ariaLabel: {
+            control: "text";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        children: {
+            control: false;
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+            };
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof Sidebar>;
+export declare const Default: Story;
+export declare const WithSeparators: Story;
+export declare const WithBadge: Story;
+export declare const WithPanel: Story;
+export declare const WithLinks: Story;
+//# sourceMappingURL=Sidebar.stories.d.ts.map

package/dist/components/sidebar/Sidebar.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.stories.d.ts","sourceRoot":"","sources":["../../../src/components/sidebar/Sidebar.stories.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAK5D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAwLvC,iBAAS,eAAe,4CAmBvB;AAMD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BsB,CAAC;AAEjC,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,OAAO,CAAC,CAAC;AAuOtC,eAAO,MAAM,OAAO,EAAE,KAGrB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,KA8C5B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KAyCvB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KAoDvB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KAmCvB,CAAC"}

package/dist/components/sidebar/Sidebar.stories.js

@@ -0,0 +1,444 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Primary as DocPrimary, Markdown, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { Badge } from '../badge/Badge.js';
+import { Icon } from '../icon/Icon.js';
+import { Separator } from '../separator/Separator.js';
+import { useState } from 'react';
+import { Sidebar } from './Sidebar.js';
+import { SidebarItem } from './SidebarItem.js';
+import { SideNavigation } from '../sideNavigation/SideNavigation.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 (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// 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' } },
+        },
+    },
+};
+export default meta;
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: { ...story.parameters?.docs, description: { story: description } },
+    },
+});
+// ---------------------------------------------------------------------------
+// Shared data
+// ---------------------------------------------------------------------------
+const storyWrapperStyle = { display: 'flex', height: 640 };
+const basePanelNavItems = [
+    {
+        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('favourites');
+    return (_jsx("div", { style: storyWrapperStyle, children: _jsxs(Sidebar, { ariaLabel: "App navigation", children: [_jsx(SidebarItem, { "aria-label": "Favourites", selected: active === 'favourites', onClick: () => setActive('favourites'), children: _jsx(Icon, { name: "favourite-outline", size: 24 }) }), _jsx(SidebarItem, { "aria-label": "Notifications", selected: active === 'notifications', onClick: () => setActive('notifications'), children: _jsx(Icon, { name: "message-square-more", size: 24 }) }), _jsx(SidebarItem, { "aria-label": "My Calendar", selected: active === 'calendar', onClick: () => setActive('calendar'), children: _jsx(Icon, { name: "date", size: 24 }) })] }) }));
+};
+const WithSeparatorsTemplate = () => {
+    const [active, setActive] = useState('favourites');
+    return (_jsx("div", { style: storyWrapperStyle, children: _jsxs(Sidebar, { ariaLabel: "App navigation", children: [_jsx(SidebarItem, { "aria-label": "Favourites", selected: active === 'favourites', onClick: () => setActive('favourites'), children: _jsx(Icon, { name: "favourite-outline", size: 24 }) }), _jsx(SidebarItem, { "aria-label": "Notifications", selected: active === 'notifications', onClick: () => setActive('notifications'), children: _jsx(Icon, { name: "message-square-more", size: 24 }) }), _jsx(SidebarItem, { "aria-label": "My Calendar", selected: active === 'calendar', onClick: () => setActive('calendar'), children: _jsx(Icon, { name: "date", size: 24 }) }), _jsx(Separator, { orientation: "horizontal", decorative: true }), _jsx(SidebarItem, { "aria-label": "Emergency Alerts", selected: active === 'emergency', onClick: () => setActive('emergency'), children: _jsx(Icon, { name: "triangle-alert", size: 24 }) }), _jsx(Separator, { orientation: "horizontal", decorative: true }), _jsx(SidebarItem, { "aria-label": "Help & Learn with Arbor", selected: active === 'help', onClick: () => setActive('help'), children: _jsx(Icon, { name: "circle-help", size: 24 }) })] }) }));
+};
+const WithBadgeTemplate = () => {
+    const [active, setActive] = useState('favourites');
+    return (_jsx("div", { style: storyWrapperStyle, children: _jsxs(Sidebar, { ariaLabel: "App navigation", children: [_jsx(SidebarItem, { "aria-label": "Favourites", selected: active === 'favourites', onClick: () => setActive('favourites'), children: _jsx(Icon, { name: "favourite-outline", size: 24 }) }), _jsxs(SidebarItem, { "aria-label": "Notifications \u2014 6 unread", selected: active === 'notifications', onClick: () => setActive('notifications'), children: [_jsx(Icon, { name: "message-square-more", size: 24 }), _jsx(Badge, { size: "sm", colour: "salmon", children: "6" })] }), _jsxs(SidebarItem, { "aria-label": "Emergency Alerts \u2014 2 active", selected: active === 'emergency', onClick: () => setActive('emergency'), children: [_jsx(Icon, { name: "triangle-alert", size: 24 }), _jsx(Badge, { size: "sm", colour: "yellow", children: "2" })] }), _jsx(SidebarItem, { "aria-label": "My Calendar", selected: active === 'calendar', onClick: () => setActive('calendar'), children: _jsx(Icon, { name: "date", size: 24 }) })] }) }));
+};
+const WithPanelTemplate = () => {
+    const [open, setOpen] = useState(true);
+    const [active, setActive] = useState('favourites');
+    return (_jsxs("div", { style: storyWrapperStyle, children: [_jsxs(Sidebar, { ariaLabel: "App navigation", children: [_jsx(SidebarItem, { "aria-label": "Toggle navigation panel", onClick: () => setOpen(prev => !prev), selected: open, "aria-expanded": open, "aria-controls": "story-panel", children: _jsx(Icon, { name: "menu", size: 24 }) }), _jsx(Separator, { orientation: "horizontal", decorative: true }), _jsx(SidebarItem, { "aria-label": "Favourites", selected: active === 'favourites', onClick: () => setActive('favourites'), children: _jsx(Icon, { name: "favourite-outline", size: 24 }) }), _jsx(SidebarItem, { "aria-label": "My Calendar", selected: active === 'calendar', onClick: () => setActive('calendar'), children: _jsx(Icon, { name: "date", size: 24 }) })] }), open && (_jsxs("div", { style: { display: 'flex', flexDirection: 'column' }, children: [_jsx(SideNavigation.Title, { children: "Attendance" }), _jsx(SideNavigation, { id: "story-panel", items: basePanelNavItems })] }))] }));
+};
+const WithLinksTemplate = () => (_jsx("div", { style: storyWrapperStyle, children: _jsxs(Sidebar, { ariaLabel: "App navigation", children: [_jsx(SidebarItem, { href: "/favourites", "aria-label": "Favourites", children: _jsx(Icon, { name: "favourite-outline", size: 24 }) }), _jsx(SidebarItem, { href: "/calendar", "aria-label": "My Calendar", selected: true, children: _jsx(Icon, { name: "date", size: 24 }) }), _jsx(Separator, { orientation: "horizontal", decorative: true }), _jsx(SidebarItem, { href: "/help", "aria-label": "Help & Learn with Arbor", children: _jsx(Icon, { name: "circle-help", size: 24 }) })] }) }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = 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 = 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 = 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 = 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 = 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.');
+//# sourceMappingURL=Sidebar.stories.js.map

package/dist/components/sidebar/Sidebar.stories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.stories.js","sourceRoot":"","sources":["../../../src/components/sidebar/Sidebar.stories.tsx"],"names":[],"mappings":"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"}

package/dist/components/sidebar/Sidebar.test.d.ts

@@ -0,0 +1,2 @@
+import '@testing-library/jest-dom/vitest';
+//# sourceMappingURL=Sidebar.test.d.ts.map

package/dist/components/sidebar/Sidebar.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.test.d.ts","sourceRoot":"","sources":["../../../src/components/sidebar/Sidebar.test.tsx"],"names":[],"mappings":"AAAA,OAAO,kCAAkC,CAAC"}

package/dist/components/sidebar/Sidebar.test.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Icon } from '../icon/Icon.js';
+import { Separator } from '../separator/Separator.js';
+import { describe, expect, test, vi } from 'vitest';
+import { Sidebar } from './Sidebar.js';
+import { SidebarItem } from './SidebarItem.js';
+describe('Sidebar', () => {
+    test('renders a nav element with default aria-label', () => {
+        render(_jsx(Sidebar, {}));
+        expect(screen.getByRole('navigation', { name: 'Sidebar' })).toBeInTheDocument();
+    });
+    test('renders a nav element with a custom ariaLabel', () => {
+        render(_jsx(Sidebar, { ariaLabel: "App navigation" }));
+        expect(screen.getByRole('navigation', { name: 'App navigation' })).toBeInTheDocument();
+    });
+    test('applies data-testid to the nav', () => {
+        render(_jsx(Sidebar, {}));
+        expect(screen.getByTestId('sidebar')).toBeInTheDocument();
+    });
+});
+describe('SidebarItem', () => {
+    test('renders an anchor when href is provided', () => {
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { href: "/home", "aria-label": "Home", children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        const link = screen.getByRole('link', { name: 'Home' });
+        expect(link).toBeInTheDocument();
+        expect(link).toHaveAttribute('href', '/home');
+    });
+    test('renders a button when no href is provided', () => {
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { "aria-label": "Menu", onClick: vi.fn(), children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        const button = screen.getByRole('button', { name: 'Menu' });
+        expect(button).toBeInTheDocument();
+        expect(button.tagName).toBe('BUTTON');
+    });
+    test('applies selected class and aria-current when current is true on a link', () => {
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { href: "/home", "aria-label": "Home", selected: true, children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        const link = screen.getByRole('link', { name: 'Home' });
+        expect(link).toHaveClass('ds-sidebar__item--selected');
+        expect(link).toHaveAttribute('aria-current', 'true');
+    });
+    test('applies selected class on a button when selected is true', () => {
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { "aria-label": "Menu", selected: true, onClick: vi.fn(), children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        const button = screen.getByRole('button', { name: 'Menu' });
+        expect(button).toHaveClass('ds-sidebar__item--selected');
+        expect(button).toHaveAttribute('aria-current', 'true');
+    });
+    test('does not apply selected class or aria-current when current is false', () => {
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { href: "/home", "aria-label": "Home", children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        const link = screen.getByRole('link', { name: 'Home' });
+        expect(link).not.toHaveClass('ds-sidebar__item--selected');
+        expect(link).toHaveAttribute('aria-current', 'false');
+    });
+    test('calls onClick when the button is clicked', async () => {
+        const onClick = vi.fn();
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { "aria-label": "Menu", onClick: onClick, children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        await userEvent.click(screen.getByRole('button', { name: 'Menu' }));
+        expect(onClick).toHaveBeenCalledOnce();
+    });
+    test('passes through extra HTML attributes to the button', () => {
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { "aria-label": "Toggle nav", "aria-expanded": false, "aria-controls": "nav-panel", onClick: vi.fn(), children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        const button = screen.getByRole('button', { name: 'Toggle nav' });
+        expect(button).toHaveAttribute('aria-expanded', 'false');
+        expect(button).toHaveAttribute('aria-controls', 'nav-panel');
+    });
+    test('applies data-testid to the rendered element', () => {
+        render(_jsx(Sidebar, { children: _jsx(SidebarItem, { href: "/home", "aria-label": "Home", "data-testid": "home-item", children: _jsx(Icon, { name: "menu", size: 24 }) }) }));
+        expect(screen.getByTestId('home-item')).toBeInTheDocument();
+    });
+});
+describe('Sidebar + SidebarItem + Separator composition', () => {
+    test('renders items and a separator together', () => {
+        render(_jsxs(Sidebar, { ariaLabel: "App navigation", children: [_jsx(SidebarItem, { href: "/home", "aria-label": "Home", children: _jsx(Icon, { name: "menu", size: 24 }) }), _jsx(Separator, { orientation: "horizontal", decorative: true }), _jsx(SidebarItem, { href: "/calendar", "aria-label": "Calendar", children: _jsx(Icon, { name: "date", size: 24 }) })] }));
+        expect(screen.getByRole('navigation', { name: 'App navigation' })).toBeInTheDocument();
+        expect(screen.getByRole('link', { name: 'Home' })).toBeInTheDocument();
+        expect(screen.getByRole('link', { name: 'Calendar' })).toBeInTheDocument();
+        expect(document.querySelector('.ds-separator')).toBeInTheDocument();
+    });
+});
+//# sourceMappingURL=Sidebar.test.js.map

package/dist/components/sidebar/Sidebar.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.test.js","sourceRoot":"","sources":["../../../src/components/sidebar/Sidebar.test.tsx"],"names":[],"mappings":";AAAA,OAAO,kCAAkC,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,SAAS,MAAM,6BAA6B,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;IACvB,IAAI,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,KAAC,OAAO,KAAG,CAAC,CAAC;QACpB,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IAClF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,KAAC,OAAO,IAAC,SAAS,EAAC,gBAAgB,GAAG,CAAC,CAAC;QAC/C,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACzF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,gCAAgC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,KAAC,OAAO,KAAG,CAAC,CAAC;QACpB,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,IAAI,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACnD,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,IAAC,IAAI,EAAC,OAAO,gBAAY,MAAM,YACzC,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,CAAC,iBAAiB,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACrD,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,kBAAY,MAAM,EAAC,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,YAC7C,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAClF,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,IAAC,IAAI,EAAC,OAAO,gBAAY,MAAM,EAAC,QAAQ,kBAClD,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,4BAA4B,CAAC,CAAC;QACvD,MAAM,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,0DAA0D,EAAE,GAAG,EAAE;QACpE,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,kBAAY,MAAM,EAAC,QAAQ,QAAC,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,YACtD,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,4BAA4B,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAC/E,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,IAAC,IAAI,EAAC,OAAO,gBAAY,MAAM,YACzC,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,4BAA4B,CAAC,CAAC;QAC3D,MAAM,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QACxB,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,kBAAY,MAAM,EAAC,OAAO,EAAE,OAAO,YAC7C,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QACpE,MAAM,CAAC,OAAO,CAAC,CAAC,oBAAoB,EAAE,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC9D,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,kBACC,YAAY,mBACR,KAAK,mBACN,WAAW,EACzB,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,YAEhB,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAClE,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACvD,MAAM,CACJ,KAAC,OAAO,cACN,KAAC,WAAW,IAAC,IAAI,EAAC,OAAO,gBAAY,MAAM,iBAAa,WAAW,YACjE,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,GACN,CACX,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,+CAA+C,EAAE,GAAG,EAAE;IAC7D,IAAI,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAClD,MAAM,CACJ,MAAC,OAAO,IAAC,SAAS,EAAC,gBAAgB,aACjC,KAAC,WAAW,IAAC,IAAI,EAAC,OAAO,gBAAY,MAAM,YACzC,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,EACd,KAAC,SAAS,IAAC,WAAW,EAAC,YAAY,EAAC,UAAU,SAAG,EACjD,KAAC,WAAW,IAAC,IAAI,EAAC,WAAW,gBAAY,UAAU,YACjD,KAAC,IAAI,IAAC,IAAI,EAAC,MAAM,EAAC,IAAI,EAAE,EAAE,GAAI,GAClB,IACN,CACX,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;QACvF,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;QACvE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;QAC3E,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACtE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/components/sidebar/SidebarItem.d.ts

@@ -0,0 +1,7 @@
+export type SidebarItemProps = {
+    'href'?: string;
+    'selected'?: boolean;
+    'data-testid'?: string;
+} & React.HTMLAttributes<HTMLElement>;
+export declare const SidebarItem: (props: SidebarItemProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SidebarItem.d.ts.map

package/dist/components/sidebar/SidebarItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SidebarItem.d.ts","sourceRoot":"","sources":["../../../src/components/sidebar/SidebarItem.tsx"],"names":[],"mappings":"AAGA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;AAEtC,eAAO,MAAM,WAAW,GAAI,OAAO,gBAAgB,4CAsDlD,CAAC"}