@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/tabs/Tabs.stories.tsx

@@ -1,21 +1,189 @@
+import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
 import { Tabs } from './Tabs';
 
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`Tabs` renders a tab strip — a `<ul role="tablist">` containing `Tabs.Item` elements.',
+  '`Tabs` is **purely presentational**: it does not manage which tab is active.',
+  'You control the `active` state on each `Tabs.Item` and listen for clicks via `tabElementProps.onClick`.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Page-level navigation** — switching between major sections of a page (Overview, Details, Settings)',
+  '- **Content filtering** — toggling between views of the same data (e.g. List / Calendar / Map)',
+  '- **Step indicators** — showing progress through a multi-section form (read-only, non-interactive)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| More than ~7 tabs — the strip becomes hard to scan | Consider a sidebar nav or `Dropdown` |',
+  '| Showing/hiding content in an accordion pattern | [`Section`](?path=/docs/components-section--docs) with `collapsible` |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Controlling active state',
+  '',
+  '`Tabs` does **not** manage active state. Wire it yourself:',
+  '',
+  '```tsx',
+  "import { Tabs } from '@arbor-education/design-system.components';",
+  "import { useState } from 'react';",
+  '',
+  'function PupilTabs() {',
+  "  const [active, setActive] = useState('overview');",
+  '',
+  '  return (',
+  '    <Tabs>',
+  "      <Tabs.Item active={active === 'overview'} tabElementProps={{ onClick: () => setActive('overview') }}>",
+  '        Overview',
+  '      </Tabs.Item>',
+  "      <Tabs.Item active={active === 'details'} tabElementProps={{ onClick: () => setActive('details') }}>",
+  '        Details',
+  '      </Tabs.Item>',
+  "      <Tabs.Item active={active === 'assessment'} tabElementProps={{ onClick: () => setActive('assessment') }}>",
+  '        Assessment',
+  '      </Tabs.Item>',
+  '    </Tabs>',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### Link tabs (router navigation)',
+  '',
+  'Use `tabElement="link"` when tabs navigate to different routes.',
+  'The inner element renders as `<a>` — pass your href via `tabElementProps`:',
+  '',
+  '```tsx',
+  '<Tabs>',
+  '  <Tabs.Item tabElement="link" tabElementProps={{ href: "/pupils/overview" }} active>',
+  '    Overview',
+  '  </Tabs.Item>',
+  '  <Tabs.Item tabElement="link" tabElementProps={{ href: "/pupils/details" }}>',
+  '    Details',
+  '  </Tabs.Item>',
+  '</Tabs>',
+  '```',
+  '',
+  'For React Router, wrap `TabsItem` in `<NavLink>` as the `tabElementProps` does not accept a',
+  '`component` override — use the `<Link>` component to wrap or pass `href` for standard anchors.',
+  '',
+  '---',
+  '',
+  '### Sub-component props',
+  '',
+  '#### `Tabs`',
+  '',
+  'Accepts all `HTMLAttributes<HTMLUListElement>` plus `children`.',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | `Tabs.Item` elements |',
+  '| `className` | `string` | — | Extra CSS class on the `<ul>` |',
+  '',
+  '#### `Tabs.Item`',
+  '',
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `active` | `boolean` | `false` | Marks this tab as selected — sets `aria-selected` and active styles |',
+  '| `tabElement` | `"button" \\| "link"` | `"button"` | Inner element type. `"button"` for JS-controlled tabs; `"link"` for anchor/router navigation |',
+  '| `tabElementProps` | `ButtonHTMLAttributes` or `AnchorHTMLAttributes` | — | Props forwarded to the inner `<button>` or `<a>`. Use `onClick` for state control; `href` for links |',
+  '| `iconName` | `keyof allowedIcons` | — | Optional icon rendered before the label text (16 px) |',
+  '| `children` | `ReactNode` | — | Tab label text |',
+  '| `className` | `string` | — | Extra CSS class on the `<li>` wrapper |',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- `Tabs` renders `role="tablist"` on the `<ul>`',
+  '- Each `Tabs.Item` renders `role="presentation"` on the `<li>` and `role="tab"` + `aria-selected` on the inner element',
+  '- Arrow key navigation within the tab list is provided by the browser for `role="tab"` elements',
+  '- `Tabs`/`TabsItem` only render the **tab strip** — tab panel content is your responsibility.',
+  '  Associate each panel with its tab using `aria-controls` on the tab and `role="tabpanel"` + `aria-labelledby` on the panel',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Section](?path=/docs/components-section--docs) · [Dropdown](?path=/docs/components-dropdown--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 TabsDocsPage() {
+  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/Tabs',
   component: Tabs,
+  tags: ['autodocs'],
   parameters: {
     layout: 'padded',
+    docs: {
+      page: TabsDocsPage,
+    },
   },
-  tags: ['autodocs'],
   argTypes: {
     children: {
       control: false,
-      description: 'Tab items to display',
+      description: '`Tabs.Item` elements that make up the tab strip.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
     },
     className: {
       control: 'text',
-      description: 'Additional CSS classes',
+      description: 'Extra CSS class applied to the `<ul>` element.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
   },
 } satisfies Meta<typeof Tabs>;
@@ -23,70 +191,382 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Basic tabs with buttons
-export const Default: Story = {
-  args: {
-    children: (
-      <>
-        <Tabs.Item active>Overview</Tabs.Item>
-        <Tabs.Item>Details</Tabs.Item>
-        <Tabs.Item>Settings</Tabs.Item>
-      </>
-    ),
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Omit<Story, 'args'>, description: string): Story => ({
+  ...(story as Story),
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
   },
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const DefaultTemplate = () => {
+  const [active, setActive] = useState('overview');
+  return (
+    <Tabs>
+      <Tabs.Item active={active === 'overview'} tabElementProps={{ onClick: () => setActive('overview') }}>
+        Overview
+      </Tabs.Item>
+      <Tabs.Item active={active === 'details'} tabElementProps={{ onClick: () => setActive('details') }}>
+        Details
+      </Tabs.Item>
+      <Tabs.Item active={active === 'assessment'} tabElementProps={{ onClick: () => setActive('assessment') }}>
+        Assessment
+      </Tabs.Item>
+      <Tabs.Item active={active === 'attendance'} tabElementProps={{ onClick: () => setActive('attendance') }}>
+        Attendance
+      </Tabs.Item>
+    </Tabs>
+  );
 };
 
-// Tabs with links
-export const WithLinks: Story = {
-  args: {
-    children: (
-      <>
-        <Tabs.Item tabElement="link" tabElementProps={{ href: '#overview' }} active>
-          Overview
-        </Tabs.Item>
-        <Tabs.Item tabElement="link" tabElementProps={{ href: '#details' }}>
-          Details
-        </Tabs.Item>
-        <Tabs.Item tabElement="link" tabElementProps={{ href: '#settings' }}>
-          Settings
-        </Tabs.Item>
-      </>
-    ),
-  },
+const WithIconsTemplate = () => {
+  const [active, setActive] = useState('profile');
+  return (
+    <Tabs>
+      <Tabs.Item
+        iconName="user"
+        active={active === 'profile'}
+        tabElementProps={{ onClick: () => setActive('profile') }}
+      >
+        Profile
+      </Tabs.Item>
+      <Tabs.Item
+        iconName="date"
+        active={active === 'timetable'}
+        tabElementProps={{ onClick: () => setActive('timetable') }}
+      >
+        Timetable
+      </Tabs.Item>
+      <Tabs.Item
+        iconName="chart-column-increasing"
+        active={active === 'results'}
+        tabElementProps={{ onClick: () => setActive('results') }}
+      >
+        Results
+      </Tabs.Item>
+      <Tabs.Item
+        iconName="settings"
+        active={active === 'settings'}
+        tabElementProps={{ onClick: () => setActive('settings') }}
+      >
+        Settings
+      </Tabs.Item>
+    </Tabs>
+  );
 };
 
-// Mixed tabs (buttons and links)
-export const Mixed: Story = {
-  args: {
-    children: (
-      <>
-        <Tabs.Item active>Home</Tabs.Item>
-        <Tabs.Item tabElement="link" tabElementProps={{ href: '#about' }}>
-          About
+const WithLinkTabsTemplate = () => (
+  <Tabs>
+    <Tabs.Item tabElement="link" tabElementProps={{ href: '#overview' }} active>
+      Overview
+    </Tabs.Item>
+    <Tabs.Item tabElement="link" tabElementProps={{ href: '#details' }}>
+      Details
+    </Tabs.Item>
+    <Tabs.Item tabElement="link" tabElementProps={{ href: '#assessment' }}>
+      Assessment
+    </Tabs.Item>
+    <Tabs.Item tabElement="link" tabElementProps={{ href: '#attendance' }}>
+      Attendance
+    </Tabs.Item>
+  </Tabs>
+);
+
+const WithManyTabsTemplate = () => {
+  const [active, setActive] = useState('autumn');
+  const terms = ['Autumn 1', 'Autumn 2', 'Spring 1', 'Spring 2', 'Summer 1', 'Summer 2'];
+  return (
+    <Tabs>
+      {terms.map(term => (
+        <Tabs.Item
+          key={term}
+          active={active === term}
+          tabElementProps={{ onClick: () => setActive(term) }}
+        >
+          {term}
         </Tabs.Item>
-        <Tabs.Item>Contact</Tabs.Item>
-        <Tabs.Item tabElement="link" tabElementProps={{ href: '#help' }}>
-          Help
+      ))}
+    </Tabs>
+  );
+};
+
+const MixedTabsTemplate = () => {
+  const [active, setActive] = useState('overview');
+  return (
+    <Tabs>
+      <Tabs.Item active={active === 'overview'} tabElementProps={{ onClick: () => setActive('overview') }}>
+        Overview
+      </Tabs.Item>
+      <Tabs.Item active={active === 'details'} tabElementProps={{ onClick: () => setActive('details') }}>
+        Details
+      </Tabs.Item>
+      <Tabs.Item tabElement="link" tabElementProps={{ href: '#help' }}>
+        Help
+      </Tabs.Item>
+    </Tabs>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    render: DefaultTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tabs } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+function PupilTabs() {
+  const [active, setActive] = useState('overview');
+
+  return (
+    <Tabs>
+      <Tabs.Item
+        active={active === 'overview'}
+        tabElementProps={{ onClick: () => setActive('overview') }}
+      >
+        Overview
+      </Tabs.Item>
+      <Tabs.Item
+        active={active === 'details'}
+        tabElementProps={{ onClick: () => setActive('details') }}
+      >
+        Details
+      </Tabs.Item>
+      <Tabs.Item
+        active={active === 'assessment'}
+        tabElementProps={{ onClick: () => setActive('assessment') }}
+      >
+        Assessment
+      </Tabs.Item>
+      <Tabs.Item
+        active={active === 'attendance'}
+        tabElementProps={{ onClick: () => setActive('attendance') }}
+      >
+        Attendance
+      </Tabs.Item>
+    </Tabs>
+  );
+}
+export default PupilTabs;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`Tabs` does **not** manage which tab is active — that is your responsibility.',
+    'Control `active` on each `Tabs.Item` and listen for clicks via `tabElementProps.onClick`.',
+    'Click the tabs to see the active state switch.',
+  ].join(' '),
+);
+
+export const WithIcons: Story = withDescription(
+  {
+    render: WithIconsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tabs } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+function PupilTabsWithIcons() {
+  const [active, setActive] = useState('profile');
+
+  return (
+    <Tabs>
+      <Tabs.Item
+        iconName="user"
+        active={active === 'profile'}
+        tabElementProps={{ onClick: () => setActive('profile') }}
+      >
+        Profile
+      </Tabs.Item>
+      <Tabs.Item
+        iconName="date"
+        active={active === 'timetable'}
+        tabElementProps={{ onClick: () => setActive('timetable') }}
+      >
+        Timetable
+      </Tabs.Item>
+      <Tabs.Item
+        iconName="chart-column-increasing"
+        active={active === 'results'}
+        tabElementProps={{ onClick: () => setActive('results') }}
+      >
+        Results
+      </Tabs.Item>
+    </Tabs>
+  );
+}
+export default PupilTabsWithIcons;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Add an icon before the tab label with the `iconName` prop.',
+    'Icons render at 16 px and use any name from the icon library.',
+    'Keep labels short when using icons — the icon + text combination can make tabs wide.',
+  ].join(' '),
+);
+
+export const WithLinkTabs: Story = withDescription(
+  {
+    render: WithLinkTabsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tabs } from '@arbor-education/design-system.components';
+
+// Use tabElement="link" when tabs navigate to different URLs.
+// The inner element renders as <a> — pass href via tabElementProps.
+function PupilLinkTabs() {
+  return (
+    <Tabs>
+      <Tabs.Item tabElement="link" tabElementProps={{ href: '/pupils/overview' }} active>
+        Overview
+      </Tabs.Item>
+      <Tabs.Item tabElement="link" tabElementProps={{ href: '/pupils/details' }}>
+        Details
+      </Tabs.Item>
+      <Tabs.Item tabElement="link" tabElementProps={{ href: '/pupils/assessment' }}>
+        Assessment
+      </Tabs.Item>
+      <Tabs.Item tabElement="link" tabElementProps={{ href: '/pupils/attendance' }}>
+        Attendance
+      </Tabs.Item>
+    </Tabs>
+  );
+}
+export default PupilLinkTabs;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Use `tabElement="link"` when each tab navigates to a different URL.',
+    'The inner element renders as `<a>` — pass `href` (and any other anchor attributes) via `tabElementProps`.',
+    'Set `active` on the tab that matches the current route.',
+  ].join(' '),
+);
+
+export const WithManyTabs: Story = withDescription(
+  {
+    render: WithManyTabsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tabs } from '@arbor-education/design-system.components';
+import { useState } from 'react';
+
+function TermTabs() {
+  const [active, setActive] = useState('Autumn 1');
+  const terms = ['Autumn 1', 'Autumn 2', 'Spring 1', 'Spring 2', 'Summer 1', 'Summer 2'];
+
+  return (
+    <Tabs>
+      {terms.map(term => (
+        <Tabs.Item
+          key={term}
+          active={active === term}
+          tabElementProps={{ onClick: () => setActive(term) }}
+        >
+          {term}
         </Tabs.Item>
-      </>
-    ),
+      ))}
+    </Tabs>
+  );
+}
+export default TermTabs;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'Tabs wrap onto multiple lines when there are more tabs than the strip can fit.',
+    'If you have more than ~7 tabs, consider whether a `Dropdown` or sidebar navigation',
+    'would be easier to scan. Dynamic lists of tabs (e.g. academic terms) are a good use case',
+    'for rendering `Tabs.Item` from an array.',
+  ].join(' '),
+);
+
+export const MixedButtonAndLink: Story = withDescription(
+  {
+    render: MixedTabsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Tabs } from '@arbor-education/design-system.components';
+import { useState } from 'react';
 
-// Many tabs
-export const ManyTabs: Story = {
-  args: {
-    children: (
-      <>
-        <Tabs.Item active iconName="list">Tab 1</Tabs.Item>
-        <Tabs.Item iconName="list">Tab 2</Tabs.Item>
-        <Tabs.Item iconName="list">Tab 3</Tabs.Item>
-        <Tabs.Item iconName="list">Tab 4</Tabs.Item>
-        <Tabs.Item iconName="list">Tab 5</Tabs.Item>
-        <Tabs.Item iconName="list">Tab 6</Tabs.Item>
-        <Tabs.Item iconName="list">Tab 7</Tabs.Item>
-        <Tabs.Item iconName="list">Tab 8</Tabs.Item>
-      </>
-    ),
+function PupilTabsMixed() {
+  const [active, setActive] = useState('overview');
+
+  return (
+    <Tabs>
+      <Tabs.Item
+        active={active === 'overview'}
+        tabElementProps={{ onClick: () => setActive('overview') }}
+      >
+        Overview
+      </Tabs.Item>
+      <Tabs.Item
+        active={active === 'details'}
+        tabElementProps={{ onClick: () => setActive('details') }}
+      >
+        Details
+      </Tabs.Item>
+      <Tabs.Item tabElement="link" tabElementProps={{ href: '/help' }}>
+        Help
+      </Tabs.Item>
+    </Tabs>
+  );
+}
+export default PupilTabsMixed;
+`.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'You can mix `button` and `link` tabs in the same strip.',
+    'Use `tabElement="button"` (default) for JS-controlled tabs and `tabElement="link"` for any tab that',
+    'navigates to an external URL or a help page — without disrupting the active state of the in-page tabs.',
+  ].join(' '),
+);