@arbor-education/design-system.components 0.23.2 → 0.24.0

package/src/components/sidebarNav/SidebarNav.stories.tsx

@@ -0,0 +1,484 @@
+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 { useMemo, useState } from 'react';
+import { fn } from 'storybook/test';
+import { SidebarNav } from './SidebarNav.js';
+import type { SidebarNavNode, SidebarNavRailEntry } from './types.js';
+
+const DESCRIPTION_INTRO = [
+  'SidebarNav is a two-part navigation pattern: a fixed icon rail for global shortcuts and an expandable',
+  'panel for hierarchical section links. Place a `<Separator />` after the burger to divide the panel toggle',
+  'from the rest of the rail icons.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Application shell navigation** — persistent rail icons (home, favourites, calendar) plus contextual section nav',
+  '- **MIS module navigation** — attendance, students, or reporting areas with grouped links',
+  '- **Favourites on leaf links** — `canFavourite` on panel items for user-pinned pages',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Horizontal top-level product nav | [`Menubar`](?path=/docs/components-menubar--docs) or app header patterns |',
+  '| Single flat list of links | [`Tabs`](?path=/docs/components-tabs--docs) or plain links |',
+  '| Account / settings menu | [`Dropdown`](?path=/docs/components-dropdown--docs) |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Rail layout',
+  '',
+  'The rail is a single vertical column. Compose **`Trigger` → `SidebarNav.Separator` → `RailList`** (icon rows).',
+  'Insert additional `<SidebarNav.Separator />` siblings between `RailList` blocks when Figma shows a break',
+  '(e.g. main shortcuts, emergency alert, help). `RailItem` and `RailSlot` each render their own',
+  '`<li>` row wrapper — do not add `ds-sidebar-nav__*` layout classes in consumer code. Use `RailSlot` for other',
+  'custom rail rows inside `RailList`.',
+  '',
+  'The rail `<nav>` defaults to `aria-label="Sidebar rail"`; the panel links nav defaults to `"Sidebar links"`.',
+  'Override via `ariaLabel` on `SidebarNav.Rail` or `SidebarNav.PanelNav` when needed.',
+  '',
+  '### Config-driven API',
+  '',
+  'Pass `railItems` as an ordered array of item configs and `{ type: \'separator\', id }` entries. Use',
+  '`opensPanel: true` on the burger item to render the panel trigger. Use `renderItem` for custom rail rows.',
+  '',
+  '### Favourites',
+  '',
+  'Panel leaf items support `canFavourite`, `isPressed`, `onFavouriteClick`, and required `favouriteTooltip` when',
+  '`canFavourite` is true (sets `aria-label` and shows a tooltip on hover/focus). The favourite `<button>` is a',
+  'sibling of the link (not inside the `<a>`), with `aria-pressed` reflecting state. Persistence is the',
+  'consumer\'s responsibility.',
+  '',
+  'The panel toggle (`SidebarNav.Trigger`) always shows tooltip **Show/hide sub navigation** (override via `tooltip` prop).',
+  '',
+  '### `renderLink`',
+  '',
+  'Provide `renderLink` at the root to integrate with your router. Panel items also support `linkElement="button"`',
+  'with `linkElementProps` for SPA actions without a URL. Data-driven items accept `href` and/or `onClick`.',
+  'Top-level `onClick` takes precedence over `linkElementProps.onClick` when both are set.',
+  'When `renderLink` is set, both `linkProps` and `linkElementProps` are forwarded in the args — spread them onto your router link (same order as the default `<a>`: `linkProps` then `linkElementProps`).',
+  'Also spread `ariaLabel`, `ariaCurrent`, and `onClick` from the args as appropriate.',
+  '',
+  'Pass `railItems={[]}` to render an intentionally empty data-driven rail. Omit `railItems` to compose the rail with JSX children.',
+  '',
+  'For data-driven rail items, pass `iconColor` as a design-token CSS value (e.g. `var(--icons-icon-default)` or `var(--color-semantic-warning-600)`), not hardcoded hex.',
+  '',
+  'The root provider passes shared state (panel open/closed, `renderLink`) to rail and panel subcomponents.',
+  '',
+  '---',
+  '',
+  '### Test IDs',
+  '',
+  '| Element | `data-testid` |',
+  '|---|---|',
+  '| Root | `sidebar-nav` |',
+  '| Rail | `sidebar-nav-rail` |',
+  '| Panel / trigger | `sidebar-nav-panel`, `sidebar-nav-panel-trigger`, `sidebar-nav-panel-trigger-{id}` |',
+  '| Rail item | `sidebar-nav-rail-item-{id}` |',
+  '| Rail separator | `sidebar-nav-rail-separator-{id}` |',
+  '| Panel item / favourite | `sidebar-nav-panel-item-{itemId}`, `sidebar-nav-panel-item-favourite-{itemId}` — `itemId` is required on composable `SidebarNav.Item` |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Dropdown](?path=/docs/components-dropdown--docs) · [Tooltip](?path=/docs/components-tooltip--docs) ·',
+  '[Badge](?path=/docs/components-badge--docs) · [Separator](?path=/docs/components-separator--docs) ·',
+  '[IconText](?path=/docs/components-icontext--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel where applicable.';
+
+function SidebarNavDocsPage() {
+  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/SidebarNav',
+  component: SidebarNav,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: SidebarNavDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  args: {
+    onExpandedChange: fn(),
+  },
+  argTypes: {
+    defaultExpanded: {
+      control: 'boolean',
+      description: 'Initial panel open state when uncontrolled.',
+      table: { defaultValue: { summary: 'true' } },
+    },
+    children: { control: false },
+    railItems: { control: false },
+    panelNavItems: { control: false },
+    renderLink: { control: false },
+  },
+} satisfies Meta<typeof SidebarNav>;
+
+export default meta;
+type Story = StoryObj<typeof SidebarNav>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: { story: description },
+    },
+  },
+});
+
+const storyWrapperStyle = { height: 640 };
+
+const basePanelNavItems: SidebarNavNode[] = [
+  {
+    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,
+        canFavourite: true as const,
+        isPressed: false,
+        favouriteTooltip: 'Add to favourites',
+      },
+      { 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' },
+    ],
+  },
+];
+
+const figmaRailItems: SidebarNavRailEntry[] = [
+  {
+    id: 'burger',
+    label: 'Show/hide sub navigation',
+    iconName: 'menu',
+    opensPanel: true,
+  },
+  { type: 'separator', id: 'after-burger' },
+  { id: 'favourites', label: 'Favourites', iconName: 'favourite-outline', href: '/favourites' },
+  {
+    id: 'notifications',
+    label: 'Notifications',
+    iconName: 'message-square-more',
+    href: '/notifications',
+    badgeContent: <Badge size="sm" colour="salmon">6</Badge>,
+  },
+  { id: 'calendar', label: 'My Calendar', iconName: 'date', href: '/calendar' },
+  { type: 'separator', id: 'before-emergency' },
+  {
+    id: 'emergency',
+    label: 'Emergency Alerts',
+    iconName: 'triangle-alert',
+    href: '/emergency',
+  },
+  { type: 'separator', id: 'before-help' },
+  {
+    id: 'help',
+    label: 'Help & Learn with Arbor',
+    iconName: 'circle-help',
+    href: '/help',
+  },
+];
+
+const SidebarNavShell = ({ children }: { children: React.ReactNode }) => (
+  <div style={storyWrapperStyle}>{children}</div>
+);
+
+/** Figma rail: burger → separator → shortcuts → separator → emergency → separator → help. */
+const FigmaRailComposition = () => (
+  <>
+    <SidebarNav.Trigger>
+      <Icon name="menu" size={24} />
+    </SidebarNav.Trigger>
+    <SidebarNav.Separator id="after-burger" />
+    <SidebarNav.RailList>
+      <SidebarNav.RailItem href="/favourites" aria-label="Favourites">
+        <Icon name="favourite-outline" size={24} />
+      </SidebarNav.RailItem>
+      <SidebarNav.RailItem href="/notifications" aria-label="Notifications">
+        <Icon name="message-square-more" size={24} />
+        <Badge size="sm" colour="salmon">6</Badge>
+      </SidebarNav.RailItem>
+      <SidebarNav.RailItem href="/calendar" aria-label="My Calendar">
+        <Icon name="date" size={24} />
+      </SidebarNav.RailItem>
+    </SidebarNav.RailList>
+    <SidebarNav.Separator id="before-emergency" />
+    <SidebarNav.RailList>
+      <SidebarNav.RailItem href="/emergency" aria-label="Emergency Alerts">
+        <Icon name="triangle-alert" size={24} />
+      </SidebarNav.RailItem>
+    </SidebarNav.RailList>
+    <SidebarNav.Separator id="before-help" />
+    <SidebarNav.RailList>
+      <SidebarNav.RailItem href="/help" aria-label="Help & Learn with Arbor">
+        <Icon name="circle-help" size={24} />
+      </SidebarNav.RailItem>
+    </SidebarNav.RailList>
+  </>
+);
+
+const DefaultTemplate = () => (
+  <SidebarNavShell>
+    <SidebarNav>
+      <SidebarNav.Rail>
+        <FigmaRailComposition />
+      </SidebarNav.Rail>
+      <SidebarNav.Panel>
+        <SidebarNav.Title>Attendance</SidebarNav.Title>
+        <SidebarNav.PanelNav items={basePanelNavItems} />
+      </SidebarNav.Panel>
+    </SidebarNav>
+  </SidebarNavShell>
+);
+
+const CollapsedPanelTemplate = () => (
+  <SidebarNavShell>
+    <SidebarNav defaultExpanded={false}>
+      <SidebarNav.Rail>
+        <SidebarNav.Trigger>
+          <Icon name="menu" size={24} />
+        </SidebarNav.Trigger>
+        <SidebarNav.Separator id="after-burger" />
+        <SidebarNav.RailList>
+          <SidebarNav.RailItem href="/favourites" aria-label="Favourites">
+            <Icon name="favourite-outline" size={24} />
+          </SidebarNav.RailItem>
+        </SidebarNav.RailList>
+      </SidebarNav.Rail>
+      <SidebarNav.Panel>
+        <SidebarNav.Title>Attendance</SidebarNav.Title>
+        <SidebarNav.PanelNav items={[]} />
+      </SidebarNav.Panel>
+    </SidebarNav>
+  </SidebarNavShell>
+);
+
+const ConfigDrivenTemplate = () => (
+  <SidebarNavShell>
+    <SidebarNav
+      railItems={figmaRailItems}
+      panelTitle="Attendance"
+      panelNavItems={basePanelNavItems}
+    />
+  </SidebarNavShell>
+);
+
+const WithFavouritesTemplate = () => {
+  const [favourites, setFavourites] = useState<Record<string, boolean>>({ daily: true });
+
+  const toggle = (id: string) => {
+    setFavourites(prev => ({ ...prev, [id]: !prev[id] }));
+  };
+
+  return (
+    <SidebarNavShell>
+      <SidebarNav>
+        <SidebarNav.Rail>
+          <SidebarNav.Trigger>
+            <Icon name="menu" size={24} />
+          </SidebarNav.Trigger>
+          <SidebarNav.Separator id="after-burger" />
+        </SidebarNav.Rail>
+        <SidebarNav.Panel>
+          <SidebarNav.Title>Attendance</SidebarNav.Title>
+          <SidebarNav.PanelNav>
+            <SidebarNav.Item
+              href="/daily"
+              itemId="daily"
+              current
+              canFavourite
+              isPressed={Boolean(favourites.daily)}
+              favouriteTooltip={favourites.daily ? 'Remove from favourites' : 'Add to favourites'}
+              onFavouriteClick={() => toggle('daily')}
+            >
+              Daily Attendance
+            </SidebarNav.Item>
+            <SidebarNav.Item href="/quick" itemId="quick">
+              Quick Follow-Up
+            </SidebarNav.Item>
+          </SidebarNav.PanelNav>
+        </SidebarNav.Panel>
+      </SidebarNav>
+    </SidebarNavShell>
+  );
+};
+
+const ConfigDrivenWithFavouritesTemplate = () => {
+  const [favourites, setFavourites] = useState<Record<string, boolean>>({ daily: true });
+
+  const panelNavItems = useMemo(
+    (): SidebarNavNode[] => basePanelNavItems.map(node => (
+      node.type === 'group'
+        ? {
+            ...node,
+            children: node.children.map((child) => {
+              if (child.id !== 'daily') {
+                return child;
+              }
+
+              return {
+                ...child,
+                canFavourite: true as const,
+                isPressed: Boolean(favourites.daily),
+                favouriteTooltip: favourites.daily ? 'Remove from favourites' : 'Add to favourites',
+                onFavouriteClick: () => setFavourites(prev => ({ ...prev, daily: !prev.daily })),
+              };
+            }),
+          }
+        : node
+    )),
+    [favourites.daily],
+  );
+
+  return (
+    <SidebarNavShell>
+      <SidebarNav
+        railItems={figmaRailItems}
+        panelTitle="Attendance"
+        panelNavItems={panelNavItems}
+      />
+    </SidebarNavShell>
+  );
+};
+
+const WithRenderLinkTemplate = () => (
+  <SidebarNavShell>
+    <SidebarNav
+      renderLink={({
+        href,
+        className,
+        children,
+        ariaCurrent,
+        ariaLabel,
+        onClick,
+        linkProps,
+        linkElementProps,
+      }) => (
+        <a
+          href={href}
+          className={className}
+          aria-current={ariaCurrent}
+          aria-label={ariaLabel}
+          data-router-link="true"
+          onClick={onClick ?? (e => e.preventDefault())}
+          {...linkProps}
+          {...linkElementProps}
+        >
+          {children}
+        </a>
+      )}
+    >
+      <SidebarNav.Rail>
+        <SidebarNav.Trigger>
+          <Icon name="menu" size={24} />
+        </SidebarNav.Trigger>
+        <SidebarNav.Separator id="after-burger" />
+      </SidebarNav.Rail>
+      <SidebarNav.Panel>
+        <SidebarNav.PanelNav
+          items={[{ type: 'item', id: 'home', label: 'Home', href: '/' }]}
+        />
+      </SidebarNav.Panel>
+    </SidebarNav>
+  </SidebarNavShell>
+);
+
+export const Default: Story = withDescription(
+  {
+    render: DefaultTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Composed rail: `Trigger`, separators between `RailList` sections (favourites/notifications/calendar, emergency, help). Panel uses `Trigger` ↔ `Panel` via context (`aria-controls` / `aria-expanded`).',
+);
+
+export const CollapsedPanel: Story = withDescription(
+  {
+    render: CollapsedPanelTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Panel hidden by default (`defaultExpanded={false}`). Use the burger trigger to open the panel.',
+);
+
+export const ConfigDriven: Story = withDescription(
+  {
+    render: ConfigDrivenTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Same Figma rail order via `railItems` (burger, `{ type: \'separator\' }` entries, then icons). Compare with **Default** for the composed `RailList` + `Separator` pattern.',
+);
+
+export const WithFavourites: Story = withDescription(
+  {
+    render: WithFavouritesTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Composable panel items with `canFavourite`, `isPressed`, and `onFavouriteClick`. State is mocked in the story — wire to your store or API in MIS.',
+);
+
+export const ConfigDrivenWithFavourites: Story = withDescription(
+  {
+    render: ConfigDrivenWithFavouritesTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Config-driven rail (`figmaRailItems`) and `panelNavItems` with favourite props merged from local state.',
+);
+
+export const WithRenderLink: Story = withDescription(
+  {
+    render: WithRenderLinkTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  'Root `renderLink` replaces default `<a>` elements for router integration.',
+);