@arbor-education/design-system.components 0.25.3 → 0.25.5

package/dist/components/breadcrumbs/Breadcrumbs.stories.js

@@ -0,0 +1,681 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { Breadcrumbs } from './Breadcrumbs.js';
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'Breadcrumbs render a navigation trail that shows users where they are within',
+    'the application hierarchy. Items can be plain links, dropdown menus for branching',
+    'at a level, or an ellipsis for collapsing deep trails. An automatic copy-to-clipboard',
+    'button appears on the final (active) item.',
+].join(' ');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- To orient users within a multi-level navigation hierarchy (e.g. Home → Students → Year 11 → Attendance).',
+    '- When users need a quick way to navigate back to any ancestor page.',
+    '- When the current page sits more than one level deep in the application.',
+    '- When you want to give users a copyable trail for sharing context — the copy button is automatic.',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Situation | Use instead |',
+    '|---|---|',
+    '| The page is at the top level (no parent) | No breadcrumb needed |',
+    '| Navigation hierarchy changes via user action on the same URL | [`Tabs`](?path=/docs/components-tabs--docs) |',
+    '| The trail contains only one item | Omit the breadcrumb |',
+    '| Step-by-step wizard progress | Stepper component |',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical usage patterns',
+    '',
+    '**Active item renders as `<a aria-current="page">` (non-navigable)**',
+    '',
+    'The last item always renders as an anchor with `aria-current="page"`. Its `href` is intentionally',
+    'discarded — the current page anchor is non-navigable to avoid the no-op of navigating to the',
+    'current page.',
+    '',
+    '**Copy button is automatic**',
+    '',
+    '`BreadcrumbCopyButton` renders automatically after the last non-ellipsis item. By default it',
+    'concatenates non-ellipsis `item.label` values with " > ". When the trail is collapsed (contains',
+    'an ellipsis), pass `copyText` with the full path so hidden items are included in the copy.',
+    'When `navigator.clipboard` is unavailable (non-HTTPS contexts), the button is a silent no-op.',
+    '',
+    '**`breadcrumbLabel` and WCAG**',
+    '',
+    'The `breadcrumbLabel` prop sets `aria-label` on the `<nav>` wrapper. When a page contains',
+    'more than one `<nav>` landmark, every nav must have a distinct accessible name. Always supply',
+    '`breadcrumbLabel="Breadcrumb"` to avoid a WCAG 2.4.1 failure.',
+    '',
+    '**Ellipsis expand pattern**',
+    '',
+    'Set `onClick` on the ellipsis item in the `items` array — the component forwards it to the',
+    'underlying button. Manage the visible `items` in component state, swapping the collapsed list',
+    '(containing the ellipsis item with `onClick`) for the full list when the user clicks.',
+    'See the **Expandable ellipsis** story for the exact pattern.',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- The `<nav>` landmark is labelled via `breadcrumbLabel` → `aria-label`.',
+    '- The `<ol>` communicates order and count to screen readers.',
+    '- The active (last) item carries `aria-current="page"` automatically.',
+    '- Separators (`/`) are wrapped in `aria-hidden="true"` — invisible to assistive technology.',
+    '- The copy button tooltip ("Copy breadcrumb path" / "Breadcrumb path copied") is its accessible label.',
+    '- Dropdown items use a Radix UI-powered popover with full keyboard navigation.',
+    '- The ellipsis `item.label` must be descriptive — e.g. "Show hidden pages", not "...".',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `Breadcrumbs.Props` | Full props for the `<Breadcrumbs>` component |',
+    '| `Breadcrumbs.LinkProps` | Props for `Breadcrumbs.Link` sub-component |',
+    '| `Breadcrumbs.EllipsisProps` | Props for `Breadcrumbs.Ellipsis` sub-component |',
+    '| `Breadcrumbs.DropdownProps` | Props for `Breadcrumbs.Dropdown` sub-component |',
+    '| `Breadcrumbs.CopyButtonProps` | Props for `Breadcrumbs.CopyButton` sub-component |',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[Dropdown](?path=/docs/components-dropdown--docs) · [Tooltip / TooltipWrapper](?path=/docs/components-tooltip-tooltipwrapper--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 BreadcrumbsDocsPage() {
+    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/Breadcrumbs',
+    component: Breadcrumbs,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: { page: BreadcrumbsDocsPage },
+    },
+    argTypes: {
+        items: {
+            control: 'object',
+            description: [
+                'Array of `BreadcrumbItem` objects that define the trail.',
+                'Each item has: `label` (string, required — also used as the clipboard copy text),',
+                '`href` (string, optional — used for all items except the last, which is always non-navigable regardless of whether `href` is set),',
+                '`dropdownOptions` (array of `BreadcrumbItem`, optional — renders a dropdown trigger; items may themselves have `dropdownOptions` for nested menus),',
+                '`isEllipsis` (boolean, optional — renders an icon-only ellipsis button),',
+                '`onClick` (function, optional — forwarded to the ellipsis button; use to expand a collapsed trail).',
+            ].join(' '),
+            table: { type: { summary: 'BreadcrumbItem[]' } },
+        },
+        breadcrumbLabel: {
+            control: 'text',
+            description: [
+                'Sets `aria-label` on the wrapping `<nav>` landmark. Required.',
+                'When a page contains more than one `<nav>` element, every nav must have a distinct accessible name.',
+                'Use `"Breadcrumb"` as the conventional value.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        copyText: {
+            control: 'text',
+            description: [
+                'Overrides the string written to the clipboard when the copy button is clicked.',
+                'Use this when the visible `items` array is collapsed (contains an ellipsis) and',
+                'the copy should reflect the full navigation path rather than only the visible labels.',
+                'Defaults to non-ellipsis item labels joined with " > ".',
+            ].join(' '),
+            table: { type: { summary: 'string' }, defaultValue: { summary: 'non-ellipsis labels joined with " > "' } },
+        },
+        className: {
+            control: false,
+            description: 'Additional CSS class names applied to the `<nav>` container.',
+            table: { type: { summary: 'string' } },
+        },
+    },
+};
+export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: {
+            ...story.parameters?.docs,
+            description: {
+                story: description,
+            },
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// Template components for stateful and composed stories.
+// ---------------------------------------------------------------------------
+const FULL_ITEMS = [
+    { label: 'Home', href: '/' },
+    { label: 'Students', href: '/students' },
+    { label: 'Year 11', href: '/students/year-11' },
+    { label: 'Class 11B', href: '/students/year-11/11b' },
+    { label: 'Attendance', href: '/students/year-11/11b/attendance' },
+    { label: 'Weekly summary' },
+];
+const FULL_COPY_TEXT = FULL_ITEMS.map(item => item.label).join(' > ');
+const ExpandableEllipsisTemplate = () => {
+    const [expanded, setExpanded] = useState(false);
+    const items = expanded
+        ? FULL_ITEMS
+        : [
+            FULL_ITEMS[0],
+            { label: 'Show hidden pages', isEllipsis: true, onClick: () => setExpanded(true) },
+            FULL_ITEMS[FULL_ITEMS.length - 2],
+            FULL_ITEMS[FULL_ITEMS.length - 1],
+        ];
+    return _jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: items, copyText: FULL_COPY_TEXT });
+};
+const EllipsisAsLastItemTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+    }, children: [_jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-xsmall)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-destructive-600)' }, children: "No copy button \u2014 last item is ellipsis (avoid this)" }), _jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+                        { label: 'Home', href: '/' },
+                        { label: 'Students', href: '/students' },
+                        { label: 'Show more pages', isEllipsis: true },
+                    ] })] }), _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 'var(--spacing-xsmall)',
+            }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-success-600)' }, children: "Copy button present \u2014 last item is the active page (correct)" }), _jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+                        { label: 'Home', href: '/' },
+                        { label: 'Students', href: '/students' },
+                        { label: 'Attendance' },
+                    ] })] })] }));
+const WithBreadcrumbLabelTemplate = () => (_jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+        { label: 'Home', href: '/' },
+        { label: 'Settings', href: '/settings' },
+        { label: 'Notifications' },
+    ] }));
+const ActiveItemTemplate = () => (_jsxs("div", { style: {
+        padding: 'var(--spacing-xlarge)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-xsmall)',
+    }, children: [_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["The last item has", ' ', _jsx("code", { children: "href=\"/behaviour/sanctions\"" }), ' ', "in the items array, but the active item is always non-navigable \u2014 inspect the DOM and you will find", ' ', _jsx("code", { children: "<a aria-current=\"page\">" }), ' ', "with no href. This prevents the current-page no-op navigation."] }), _jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+                { label: 'Home', href: '/' },
+                { label: 'Behaviour', href: '/behaviour' },
+                { label: 'Sanctions log', href: '/behaviour/sanctions' },
+            ] })] }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    args: {
+        items: [
+            { label: 'Home', href: '/' },
+            { label: 'Students', href: '/students' },
+            { label: 'Year 11', href: '/students/year-11' },
+            { label: 'Attendance', href: '/students/year-11/attendance' },
+            { label: 'Weekly summary' },
+        ],
+        breadcrumbLabel: 'Breadcrumb',
+    },
+    render: args => _jsx(Breadcrumbs, { ...args }),
+}, [
+    'The interactive canvas — every prop is wired to the Controls panel.',
+    'Adjust `items` to change the trail. The last item always renders as the active page',
+    '(`<a aria-current="page">` without an href), regardless of whether the item has an `href`.',
+].join(' '));
+export const TwoItems = withDescription({
+    render: () => (_jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [{ label: 'Home', href: '/' }, { label: 'Dashboard' }] })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function TwoItemsBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        { label: 'Dashboard' },
+      ]}
+    />
+  );
+}
+export default TwoItemsBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, 'The minimum meaningful trail: one parent link and the active page. The copy button appears automatically on the active item.');
+export const LongTrail = withDescription({
+    render: () => (_jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+            { label: 'Home', href: '/' },
+            { label: 'Students', href: '/students' },
+            { label: 'Year 11', href: '/students/year-11' },
+            { label: 'Class 11B', href: '/students/year-11/11b' },
+            { label: 'Attendance', href: '/students/year-11/11b/attendance' },
+            {
+                label: 'Term reports',
+                href: '/students/year-11/11b/attendance/term-reports',
+            },
+            { label: 'Autumn term 2024' },
+        ] })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function LongTrailBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        { label: 'Students', href: '/students' },
+        { label: 'Year 11', href: '/students/year-11' },
+        { label: 'Class 11B', href: '/students/year-11/11b' },
+        { label: 'Attendance', href: '/students/year-11/11b/attendance' },
+        { label: 'Term reports', href: '/students/year-11/11b/attendance/term-reports' },
+        { label: 'Autumn term 2024' },
+      ]}
+    />
+  );
+}
+export default LongTrailBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, 'A seven-item trail demonstrating depth and line-wrapping. All intermediate items render as links; the final item is the active page.');
+export const WithDropdown = withDescription({
+    render: () => (_jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+            { label: 'Home', href: '/' },
+            {
+                label: 'Students',
+                href: '/students',
+                dropdownOptions: [
+                    { label: 'All students', href: '/students' },
+                    { label: 'Year 10', href: '/students/year-10' },
+                    { label: 'Year 11', href: '/students/year-11' },
+                    { label: 'Year 12', href: '/students/year-12' },
+                ],
+            },
+            { label: 'Behaviour' },
+        ] })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function WithDropdownBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        {
+          label: 'Students',
+          href: '/students',
+          dropdownOptions: [
+            { label: 'All students', href: '/students' },
+            { label: 'Year 10', href: '/students/year-10' },
+            { label: 'Year 11', href: '/students/year-11' },
+            { label: 'Year 12', href: '/students/year-12' },
+          ],
+        },
+        { label: 'Behaviour' },
+      ]}
+    />
+  );
+}
+export default WithDropdownBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'When an item has `dropdownOptions`, it renders as a dropdown trigger (chevron icon).',
+    'Clicking opens a Radix UI-powered popover with the supplied links.',
+    'The popover portals to the document body — do not place `overflow: hidden` on any ancestor container.',
+].join(' '));
+export const MultipleDropdowns = withDescription({
+    render: () => (_jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+            { label: 'Home', href: '/' },
+            {
+                label: 'Students',
+                href: '/students',
+                dropdownOptions: [
+                    { label: 'All students', href: '/students' },
+                    { label: 'Year 10', href: '/students/year-10' },
+                    { label: 'Year 11', href: '/students/year-11' },
+                ],
+            },
+            {
+                label: 'Attendance',
+                href: '/students/year-11/attendance',
+                dropdownOptions: [
+                    {
+                        label: 'Daily register',
+                        href: '/students/year-11/attendance/daily',
+                    },
+                    {
+                        label: 'Weekly summary',
+                        href: '/students/year-11/attendance/weekly',
+                    },
+                    {
+                        label: 'Term report',
+                        href: '/students/year-11/attendance/term',
+                    },
+                ],
+            },
+            { label: 'Registration' },
+        ] })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function MultipleDropdownsBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        {
+          label: 'Students',
+          href: '/students',
+          dropdownOptions: [
+            { label: 'All students', href: '/students' },
+            { label: 'Year 10', href: '/students/year-10' },
+            { label: 'Year 11', href: '/students/year-11' },
+          ],
+        },
+        {
+          label: 'Attendance',
+          href: '/students/year-11/attendance',
+          dropdownOptions: [
+            { label: 'Daily register', href: '/students/year-11/attendance/daily' },
+            { label: 'Weekly summary', href: '/students/year-11/attendance/weekly' },
+            { label: 'Term report', href: '/students/year-11/attendance/term' },
+          ],
+        },
+        { label: 'Registration' },
+      ]}
+    />
+  );
+}
+export default MultipleDropdownsBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, 'Two intermediate items each have their own independent dropdown. Each opens a separate Radix UI popover.');
+export const WithEllipsis = withDescription({
+    render: () => (_jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+            { label: 'Home', href: '/' },
+            { label: 'Show hidden pages', isEllipsis: true },
+            { label: 'Year 11', href: '/students/year-11' },
+            { label: 'Attendance' },
+        ] })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function WithEllipsisBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        { label: 'Show hidden pages', isEllipsis: true },
+        { label: 'Year 11', href: '/students/year-11' },
+        { label: 'Attendance' },
+      ]}
+    />
+  );
+}
+export default WithEllipsisBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'An ellipsis item (`isEllipsis: true`) renders as an icon-only button.',
+    'The `item.label` value ("Show hidden pages") becomes the accessible button label — make it descriptive.',
+    'This static example has no click handler. See **Expandable ellipsis** for the interactive version.',
+].join(' '));
+export const ExpandableEllipsis = withDescription({
+    render: ExpandableEllipsisTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+type BreadcrumbItem = Breadcrumbs.Props['items'][number];
+
+const FULL_ITEMS: BreadcrumbItem[] = [
+  { label: 'Home', href: '/' },
+  { label: 'Students', href: '/students' },
+  { label: 'Year 11', href: '/students/year-11' },
+  { label: 'Class 11B', href: '/students/year-11/11b' },
+  { label: 'Attendance', href: '/students/year-11/11b/attendance' },
+  { label: 'Weekly summary' },
+];
+
+function ExpandableEllipsisBreadcrumb() {
+  const [expanded, setExpanded] = useState(false);
+
+  const items = expanded
+    ? FULL_ITEMS
+    : [
+        FULL_ITEMS[0],
+        { label: 'Show hidden pages', isEllipsis: true, onClick: () => setExpanded(true) },
+        FULL_ITEMS[FULL_ITEMS.length - 2],
+        FULL_ITEMS[FULL_ITEMS.length - 1],
+      ];
+
+  const copyText = FULL_ITEMS.map(item => item.label).join(' > ');
+
+  return <Breadcrumbs breadcrumbLabel="Breadcrumb" items={items} copyText={copyText} />;
+}
+export default ExpandableEllipsisBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'Click the ellipsis button to expand the full trail.',
+    'Set `onClick` on the ellipsis item and manage the visible `items` array in state —',
+    'swap the collapsed list for the full list on click.',
+    'The `item.label` on the ellipsis becomes its accessible button label, so make it descriptive.',
+].join(' '));
+export const WithDropdownAndEllipsis = withDescription({
+    render: () => (_jsx(Breadcrumbs, { breadcrumbLabel: "Breadcrumb", items: [
+            { label: 'Home', href: '/' },
+            { label: 'Show hidden pages', isEllipsis: true },
+            {
+                label: 'Year 11',
+                href: '/students/year-11',
+                dropdownOptions: [
+                    { label: 'Year 9', href: '/students/year-9' },
+                    { label: 'Year 10', href: '/students/year-10' },
+                    { label: 'Year 11', href: '/students/year-11' },
+                    { label: 'Year 12', href: '/students/year-12' },
+                ],
+            },
+            { label: 'Reports' },
+        ] })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function WithDropdownAndEllipsisBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        { label: 'Show hidden pages', isEllipsis: true },
+        {
+          label: 'Year 11',
+          href: '/students/year-11',
+          dropdownOptions: [
+            { label: 'Year 9', href: '/students/year-9' },
+            { label: 'Year 10', href: '/students/year-10' },
+            { label: 'Year 11', href: '/students/year-11' },
+            { label: 'Year 12', href: '/students/year-12' },
+          ],
+        },
+        { label: 'Reports' },
+      ]}
+    />
+  );
+}
+export default WithDropdownAndEllipsisBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, 'Ellipsis and dropdown items can appear together. The ellipsis collapses hidden ancestors; the dropdown exposes sibling pages at a given level.');
+export const EllipsisAsLastItem = withDescription({
+    render: EllipsisAsLastItemTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+// When isEllipsis is true on the last item, the copy button is suppressed.
+// Avoid placing an ellipsis last — always put the active page last.
+function EllipsisAsLastItemBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        { label: 'Students', href: '/students' },
+        { label: 'Show more pages', isEllipsis: true },
+      ]}
+    />
+  );
+}
+export default EllipsisAsLastItemBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'When `isEllipsis: true` is set on the last item, the copy button is suppressed.',
+    'This is current behaviour — avoid placing an ellipsis last; use it only for collapsed intermediate items.',
+].join(' '));
+export const WithBreadcrumbLabel = withDescription({
+    render: WithBreadcrumbLabelTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+// Always supply breadcrumbLabel when the page contains more than one <nav>.
+function WithBreadcrumbLabelBreadcrumb() {
+  return (
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        { label: 'Settings', href: '/settings' },
+        { label: 'Notifications' },
+      ]}
+    />
+  );
+}
+export default WithBreadcrumbLabelBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, '`breadcrumbLabel` is required. When a page contains more than one `<nav>` landmark, each needs a distinct `aria-label`. "Breadcrumb" is the conventional value.');
+export const ActiveItemAriaCurrent = withDescription({
+    render: ActiveItemTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Breadcrumbs } from '@arbor-education/design-system.components';
+
+function ActiveItemBreadcrumb() {
+  return (
+    // The last item renders as <a aria-current="page"> with no href.
+    // The href from the items array is intentionally discarded for active items.
+    <Breadcrumbs
+      breadcrumbLabel="Breadcrumb"
+      items={[
+        { label: 'Home', href: '/' },
+        { label: 'Behaviour', href: '/behaviour' },
+        { label: 'Sanctions log', href: '/behaviour/sanctions' },
+      ]}
+    />
+  );
+}
+export default ActiveItemBreadcrumb;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'The last item has `href="/behaviour/sanctions"` in the items array, but the active item is always non-navigable.',
+    'Inspect the DOM and you will find `<a aria-current="page">` — no `href`. This prevents the no-op of',
+    'navigating to the current page.',
+].join(' '));
+//# sourceMappingURL=Breadcrumbs.stories.js.map