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

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

@@ -1,484 +0,0 @@
-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.',
-);