@arbor-education/design-system.components 0.13.0 → 0.14.0

package/dist/components/dropdown/Dropdown.stories.js

@@ -1,30 +1,782 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading, Markdown, Primary, Stories, Subheading, Subtitle, Title } from '@storybook/addon-docs/blocks';
+import { useState } from 'react';
 import { Dropdown } from './Dropdown';
 import { Button } from '../button/Button';
+import { Icon } from '../icon/Icon';
+// ---------------------------------------------------------------------------
+// Sub-component prop tables (Storybook cannot auto-generate ArgTypes for
+// components whose props come from external Radix UI types)
+// ---------------------------------------------------------------------------
+const TRIGGER_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`children\` | \`React.ReactElement\` | — | The trigger element. Must be a React element (\`<Button>\`, \`<a>\`, custom components) — \`asChild\` is applied internally. Plain text or Fragments are not supported. Also pass \`disabled\` to the child element so it gets the correct visual and ARIA state. |
+| \`disabled\` | \`boolean\` | \`false\` | Prevents the dropdown from opening. |
+`.trim();
+const CONTENT_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`children\` | \`React.ReactNode\` | — | The menu content — \`Dropdown.Item\`, \`Dropdown.SelectItem\`, \`Dropdown.Separator\`, and \`Dropdown.Group\` elements. |
+| \`contentProps\` | \`DropdownMenuContentProps\` | — | Passed to the Radix \`DropdownMenu.Content\`. Key values: \`align\` (\`'start' \\| 'center' \\| 'end'\`, default \`'start'\`), \`side\` (\`'top' \\| 'right' \\| 'bottom' \\| 'left'\`, default \`'bottom'\`), \`sideOffset\` (gap in px), \`avoidCollisions\` (auto-flip when clipped, default \`true\`). |
+| \`portalProps\` | \`DropdownMenuPortalProps\` | — | Passed to the Radix \`DropdownMenu.Portal\`. Rarely needed — content already renders via \`PopupParentContext\`. |
+| \`className\` | \`string\` | \`''\` | Additional CSS class for the content panel. |
+`.trim();
+const ITEM_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`children\` | \`React.ReactNode\` | — | Item label. Can include icons — they align automatically via the item's flex layout. Use \`size={16}\` on icons to match line height. |
+| \`onSelect\` | \`(event: Event) => void\` | — | Called when the item is activated (click or keyboard). The dropdown closes after selection by default. |
+| \`disabled\` | \`boolean\` | \`false\` | Renders at 50% opacity with \`aria-disabled="true"\` and \`pointer-events: none\`. Still visible to screen readers. |
+| \`textValue\` | \`string\` | — | Optional string for typeahead matching. Use when \`children\` is not a plain string (e.g. it includes icons). |
+| \`className\` | \`string\` | \`''\` | Additional CSS class. |
+`.trim();
+const SELECT_ITEM_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`selected\` | \`boolean\` | — | **Required.** Controlled checked state. When \`true\`, a checkmark icon is shown on the right. |
+| \`onSelectChange\` | \`(selected: boolean) => void\` | — | **Required.** Called when the item is toggled. Receives the new checked state. |
+| \`closeAfterSelection\` | \`boolean\` | \`true\` | When \`false\`, the dropdown stays open after selection — essential for multi-select menus. Pass \`false\` on every \`SelectItem\` in a multi-select menu. |
+| \`disabled\` | \`boolean\` | \`false\` | Renders the item disabled. |
+| \`children\` | \`React.ReactNode\` | — | Item label. |
+| \`textValue\` | \`string\` | — | Optional string for typeahead matching. |
+`.trim();
+const GROUP_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`children\` | \`React.ReactNode\` | — | The items in this group. Renders with \`role="group"\` for screen reader announcements. Combine with \`Dropdown.Separator\` for a visible divider. |
+| \`className\` | \`string\` | \`''\` | Additional CSS class. |
+`.trim();
+const SEPARATOR_PROPS = `
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| \`className\` | \`string\` | \`''\` | Additional CSS class. The separator renders as a zero-config horizontal rule with no configurable content. |
+`.trim();
+const DESCRIPTION_INTRO = [
+    'A **non-blocking popup menu** built on [Radix UI\'s DropdownMenu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) primitive.',
+    '`modal={false}` is hardcoded — the background is never blocked, letting users continue interacting with the rest of the page while the menu is open.',
+].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.';
+const USAGE_GUIDANCE = [
+    '## When to use',
+    '',
+    '- **Quick contextual actions** — a row of records in a table that each need an "Actions" menu (edit, archive, delete)',
+    '- **Filter panels** — letting a teacher select which year groups to display in an attendance report without losing their place',
+    '- **Column visibility toggles** — showing/hiding columns in a data grid, e.g. the custom column menu in Arbor\'s assessment tracker',
+    '- **Date-range pickers** — anchored to a filter chip so the picker appears near the trigger (see the attendance date filter)',
+    '- **Multi-select checkboxes** — choosing which guardian contacts to include in a bulk message without navigating away',
+    '',
+    '## When NOT to use',
+    '',
+    '| Instead of Dropdown... | Use... | Why |',
+    '|---|---|---|',
+    '| Data-driven option lists | `SelectDropdown` | Handles fetch state, search, and controlled value binding |',
+    '| Colour picking | `ColourPickerDropdown` | Specialised colour grid UI |',
+    '| Workflows needing focus lock | `Modal` | Blocking, centred, keyboard-trapped dialog |',
+    '| Side-panel editing | `Slideover` | Slides from the right edge, larger content area |',
+    '',
+    '## Compound component API',
+    '',
+    '```tsx',
+    '<Dropdown>',
+    '  <Dropdown.Trigger>',
+    '    <Button variant="dropdown">Actions</Button>',
+    '  </Dropdown.Trigger>',
+    '  <Dropdown.Content>',
+    '    <Dropdown.Item onSelect={fn}>View profile</Dropdown.Item>',
+    '    <Dropdown.Separator />',
+    '    <Dropdown.Group>',
+    '      <Dropdown.SelectItem selected={checked} onSelectChange={setChecked}>',
+    '        Year 7',
+    '      </Dropdown.SelectItem>',
+    '    </Dropdown.Group>',
+    '  </Dropdown.Content>',
+    '</Dropdown>',
+    '```',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '## Critical usage notes',
+    '',
+    '- **`Dropdown.Trigger` uses `asChild`** — the child element *becomes* the trigger. It must be a',
+    '  `React.ReactElement` (not a string, not a Fragment). `<Button>`, `<a>`, custom components — all fine.',
+    '  Plain text — not fine.',
+    '- **`closeAfterSelection` defaults to `true`** on `Dropdown.SelectItem`. For multi-select patterns where',
+    '  the dropdown should stay open, pass `closeAfterSelection={false}` on **every** `SelectItem`.',
+    '- **Content portals** — `Dropdown.Content` renders outside the normal DOM flow via `PopupParentContext`.',
+    '  Never use `overflow: hidden` or `position: relative` on story wrappers.',
+    '- **Controlled vs uncontrolled** — pass `open` + `onOpenChange` to control state externally, or omit both',
+    '  to let Radix manage it internally.',
+    '',
+    '> **Built on [Radix UI DropdownMenu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu).** Sub-component',
+    '> props like `contentProps` and `portalProps` are passed directly to the underlying Radix primitives — see the',
+    '> [Radix DropdownMenu docs](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) for the full API',
+    '> (alignment, collision detection, animation callbacks, etc.).',
+    '',
+    '## Accessibility',
+    '',
+    '- **Keyboard navigation**: `ArrowDown` / `ArrowUp` moves between items; `Enter` / `Space` activates the',
+    '  focused item; `Escape` closes; typeahead jumps to the first item matching the typed character.',
+    '- **ARIA roles**: the menu panel has `role="menu"`; regular items have `role="menuitem"`; select items',
+    '  have `role="menuitemcheckbox"`.',
+    '- **Screen reader announcements**: Radix announces the checked/unchecked state of `SelectItem`',
+    '  automatically via `aria-checked`.',
+    '- **Trigger**: Radix sets `aria-expanded` on the trigger automatically.',
+    '- **Disabled items**: rendered with `aria-disabled="true"` and `pointer-events: none` — still readable by',
+    '  screen readers but cannot be activated.',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[SelectDropdown](?path=/docs/components-formfield-inputs-selectdropdown--docs) · [ColourPickerDropdown](?path=/docs/components-formfield-inputs-colourpickerdropdown--docs) · [Modal](?path=/docs/components-modals-modal--docs) · [SlideoverManager](?path=/docs/components-slideovermanager--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+function DropdownDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(Heading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(Primary, {}), _jsx(Heading, { children: "Props reference" }), _jsx(Subheading, { children: "Root props (Dropdown)" }), _jsx(Controls, {}), _jsx(Subheading, { children: "Dropdown.Trigger props" }), _jsx(Markdown, { children: TRIGGER_PROPS }), _jsx(Subheading, { children: "Dropdown.Content props" }), _jsx(Markdown, { children: CONTENT_PROPS }), _jsx(Subheading, { children: "Dropdown.Item props" }), _jsx(Markdown, { children: ITEM_PROPS }), _jsx(Subheading, { children: "Dropdown.SelectItem props" }), _jsx(Markdown, { children: SELECT_ITEM_PROPS }), _jsx(Subheading, { children: "Dropdown.Group props" }), _jsx(Markdown, { children: GROUP_PROPS }), _jsx(Subheading, { children: "Dropdown.Separator props" }), _jsx(Markdown, { children: SEPARATOR_PROPS }), _jsx(Heading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(Heading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(Heading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
 const meta = {
     title: 'Components/Dropdown',
     component: Dropdown,
-};
-export const Default = {
-    args: {
-        children: [
-            _jsxs(_Fragment, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { type: "primary", children: "Click me!" }) }), _jsx(Dropdown.Content, { children: _jsx("div", { children: "Content" }) })] }),
-        ],
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'centered',
+        docs: {
+            page: DropdownDocsPage,
+        },
+    },
+    argTypes: {
+        open: {
+            control: 'boolean',
+            description: 'Controlled open state. Pair with `onOpenChange` to drive the dropdown externally. Omit for uncontrolled usage.',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        defaultOpen: {
+            control: 'boolean',
+            description: 'Initial open state for uncontrolled mode. Do not combine with `open`.',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        onOpenChange: {
+            description: 'Callback fired when the open state changes. Receives the new boolean state.',
+            table: {
+                type: { summary: '(open: boolean) => void' },
+            },
+        },
+        dir: {
+            control: 'select',
+            options: ['ltr', 'rtl'],
+            description: 'Text reading direction. Inherits from the document direction if omitted.',
+            table: {
+                type: { summary: "'ltr' | 'rtl'" },
+                defaultValue: { summary: 'ltr' },
+            },
+        },
+        children: {
+            description: 'The compound component tree. Must include `Dropdown.Trigger` and `Dropdown.Content`. Sub-component props (`Dropdown.Item`, `Dropdown.SelectItem`, etc.) are documented in the individual stories below.',
+            control: false,
+            table: {
+                type: { summary: 'ReactNode' },
+            },
+        },
     },
 };
-export const DropdownWithItems = {
-    args: {
-        children: [
-            _jsxs(_Fragment, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { type: "primary", children: "Click me!" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { onClick: () => { console.log('Item 1'); }, children: "Item 1" }), _jsx(Dropdown.Item, { onClick: () => { console.log('Item 2'); }, children: "Item 2" }), _jsx(Dropdown.Item, { onClick: () => { console.log('Item 3'); }, children: "Item 3" })] })] }),
-        ],
+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 } },
     },
+});
+// ---------------------------------------------------------------------------
+// Stateful template components (named components avoid hooks-in-callbacks lint issues)
+// ---------------------------------------------------------------------------
+const ControlledOpenTemplate = () => {
+    const [open, setOpen] = useState(false);
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-large)', padding: 'var(--spacing-xlarge)' }, children: [_jsxs("p", { style: { margin: 0, fontSize: '0.875rem', color: 'var(--color-grey-600)' }, children: ["Dropdown is currently:", ' ', _jsx("strong", { children: open ? 'open' : 'closed' })] }), _jsxs(Dropdown, { open: open, onOpenChange: setOpen, children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "primary", children: "Controlled trigger" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { onSelect: () => setOpen(false), children: "View student profile" }), _jsx(Dropdown.Item, { onSelect: () => setOpen(false), children: "Edit assessment details" }), _jsx(Dropdown.Item, { onSelect: () => setOpen(false), children: "Send message to parents" })] })] })] }));
+};
+const WithSelectItemsTemplate = () => {
+    const [viewSelected, setViewSelected] = useState(false);
+    const [editSelected, setEditSelected] = useState(true);
+    const [exportSelected, setExportSelected] = useState(false);
+    return (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "dropdown", children: "Column options" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.SelectItem, { selected: viewSelected, onSelectChange: setViewSelected, children: "View student profile" }), _jsx(Dropdown.SelectItem, { selected: editSelected, onSelectChange: setEditSelected, children: "Edit assessment details" }), _jsx(Dropdown.SelectItem, { selected: exportSelected, onSelectChange: setExportSelected, children: "Export to CSV" })] })] }) }));
+};
+const MultiSelectPersistentTemplate = () => {
+    const [year7, setYear7] = useState(true);
+    const [year8, setYear8] = useState(false);
+    const [year9, setYear9] = useState(true);
+    const [year10, setYear10] = useState(false);
+    const [year11, setYear11] = useState(false);
+    const selectedCount = [year7, year8, year9, year10, year11].filter(Boolean).length;
+    return (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsxs(Button, { variant: "dropdown", children: ["Year groups", selectedCount > 0 ? ` (${selectedCount})` : ''] }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.SelectItem, { selected: year7, onSelectChange: setYear7, closeAfterSelection: false, children: "Year 7" }), _jsx(Dropdown.SelectItem, { selected: year8, onSelectChange: setYear8, closeAfterSelection: false, children: "Year 8" }), _jsx(Dropdown.SelectItem, { selected: year9, onSelectChange: setYear9, closeAfterSelection: false, children: "Year 9" }), _jsx(Dropdown.SelectItem, { selected: year10, onSelectChange: setYear10, closeAfterSelection: false, children: "Year 10" }), _jsx(Dropdown.SelectItem, { selected: year11, onSelectChange: setYear11, closeAfterSelection: false, children: "Year 11" })] })] }) }));
 };
-export const DropdownWithSelectItems = {
+const MixedItemTypesTemplate = () => {
+    const [csvSelected, setCsvSelected] = useState(false);
+    const [pdfSelected, setPdfSelected] = useState(true);
+    return (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Record options" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('view'), children: "View student profile" }), _jsx(Dropdown.Item, { onSelect: () => console.log('edit'), children: "Edit assessment details" }), _jsx(Dropdown.Separator, {}), _jsx(Dropdown.SelectItem, { selected: csvSelected, onSelectChange: setCsvSelected, closeAfterSelection: false, children: "Export to CSV" }), _jsx(Dropdown.SelectItem, { selected: pdfSelected, onSelectChange: setPdfSelected, closeAfterSelection: false, children: "Export to PDF" }), _jsx(Dropdown.Separator, {}), _jsx(Dropdown.Item, { onSelect: () => console.log('archive'), children: "Archive record" })] })] }) }));
+};
+const SchoolContextExampleTemplate = () => {
+    const [year7, setYear7] = useState(true);
+    const [year8, setYear8] = useState(true);
+    const [year9, setYear9] = useState(false);
+    const [year10, setYear10] = useState(false);
+    const [year11, setYear11] = useState(false);
+    const [allYears, setAllYears] = useState(false);
+    const handleAllYears = (checked) => {
+        setAllYears(checked);
+        if (checked) {
+            setYear7(true);
+            setYear8(true);
+            setYear9(true);
+            setYear10(true);
+            setYear11(true);
+        }
+    };
+    const selectedYears = [
+        year7 && 'Year 7',
+        year8 && 'Year 8',
+        year9 && 'Year 9',
+        year10 && 'Year 10',
+        year11 && 'Year 11',
+    ].filter(Boolean);
+    const label = allYears
+        ? 'All year groups'
+        : selectedYears.length === 0
+            ? 'Select year groups'
+            : selectedYears.join(', ');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', padding: 'var(--spacing-xlarge)', minWidth: '280px' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0 }, children: "Attendance report filter" }), _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "dropdown", children: label }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.SelectItem, { selected: allYears, onSelectChange: handleAllYears, closeAfterSelection: false, children: "All year groups" }), _jsx(Dropdown.Separator, {}), _jsx(Dropdown.SelectItem, { selected: year7, onSelectChange: setYear7, closeAfterSelection: false, children: "Year 7" }), _jsx(Dropdown.SelectItem, { selected: year8, onSelectChange: setYear8, closeAfterSelection: false, children: "Year 8" }), _jsx(Dropdown.SelectItem, { selected: year9, onSelectChange: setYear9, closeAfterSelection: false, children: "Year 9" }), _jsx(Dropdown.SelectItem, { selected: year10, onSelectChange: setYear10, closeAfterSelection: false, children: "Year 10" }), _jsx(Dropdown.SelectItem, { selected: year11, onSelectChange: setYear11, closeAfterSelection: false, children: "Year 11" })] })] })] }));
+};
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
     args: {
-        children: [
-            _jsxs(_Fragment, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { type: "primary", children: "Click me!" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.SelectItem, { selected: true, onSelectChange: () => { console.log('Item 1'); }, children: "Item 1" }), _jsx(Dropdown.SelectItem, { selected: false, onSelectChange: () => { console.log('Item 2'); }, children: "Item 2" }), _jsx(Dropdown.SelectItem, { selected: false, onSelectChange: () => { console.log('Item 3'); }, children: "Item 3" })] })] }),
-        ],
+        defaultOpen: false,
+        dir: 'ltr',
     },
-};
-export default meta;
+    render: args => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { ...args, children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "primary", children: "Open menu" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { onSelect: () => { }, children: "View student profile" }), _jsx(Dropdown.Item, { onSelect: () => { }, children: "Edit assessment details" }), _jsx(Dropdown.Item, { onSelect: () => { }, children: "Archive record" })] })] }) })),
+}, 'The simplest possible Dropdown — a trigger button with action items. Click the button to open, click outside or press **Escape** to close. Notice how the page behind remains fully interactive — this is the `modal={false}` behaviour that distinguishes Dropdown from a blocking Modal. Use the **Controls** panel above to toggle `defaultOpen` or change the text direction.');
+export const WithItems = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Student actions" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('view'), children: "View student profile" }), _jsx(Dropdown.Item, { onSelect: () => console.log('edit'), children: "Edit assessment details" }), _jsx(Dropdown.Item, { onSelect: () => console.log('message'), children: "Send message to parents" }), _jsx(Dropdown.Item, { onSelect: () => console.log('export'), children: "Export to CSV" })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function StudentActionsDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Student actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item onSelect={() => console.log('view')}>View student profile</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('edit')}>Edit assessment details</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('message')}>Send message to parents</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('export')}>Export to CSV</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default StudentActionsDropdown;`,
+            },
+        },
+    },
+}, 'Standard action menu using `Dropdown.Item`. Each item fires its `onSelect` callback and closes the dropdown automatically. Use `Dropdown.Item` when the action is a one-shot command (navigate, trigger a workflow) rather than a toggle. Items support keyboard navigation — use `ArrowDown` / `ArrowUp` to move between them.');
+export const WithDisabledItems = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Student actions" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('view'), children: "View student profile" }), _jsx(Dropdown.Item, { disabled: true, onSelect: () => console.log('edit'), children: "Edit assessment details" }), _jsx(Dropdown.Item, { disabled: true, onSelect: () => console.log('message'), children: "Send message to parents" }), _jsx(Dropdown.Item, { onSelect: () => console.log('archive'), children: "Archive record" })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function DisabledItemsDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Student actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item onSelect={() => console.log('view')}>View student profile</Dropdown.Item>
+        <Dropdown.Item disabled onSelect={() => console.log('edit')}>
+          Edit assessment details
+        </Dropdown.Item>
+        <Dropdown.Item disabled onSelect={() => console.log('message')}>
+          Send message to parents
+        </Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('archive')}>Archive record</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default DisabledItemsDropdown;`,
+            },
+        },
+    },
+}, 'Items can be individually disabled with the `disabled` prop. Disabled items render at 50% opacity with `aria-disabled="true"` and `pointer-events: none` — they appear in the menu so users understand which actions exist, but cannot be activated. Use this when an action is contextually unavailable (e.g. "Edit assessment" disabled for locked marking periods).');
+export const ControlledOpen = withDescription({
+    render: ControlledOpenTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { useState } from 'react';
+import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function ControlledDropdown() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-large)' }}>
+      <p style={{ margin: 0 }}>
+        Dropdown is currently: <strong>{open ? 'open' : 'closed'}</strong>
+      </p>
+      <Dropdown open={open} onOpenChange={setOpen}>
+        <Dropdown.Trigger>
+          <Button variant="primary">Controlled trigger</Button>
+        </Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Item onSelect={() => setOpen(false)}>View student profile</Dropdown.Item>
+          <Dropdown.Item onSelect={() => setOpen(false)}>Edit assessment details</Dropdown.Item>
+          <Dropdown.Item onSelect={() => setOpen(false)}>Send message to parents</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown>
+    </div>
+  );
+}
+
+export default ControlledDropdown;`,
+            },
+        },
+    },
+}, "Pass `open` and `onOpenChange` to control the dropdown's open state from outside. The indicator above the button reflects the current state in real time. Use controlled mode when you need to programmatically open or close the menu (e.g. opening it in response to a keyboard shortcut, or closing it after an async action completes).");
+export const WithSelectItems = withDescription({
+    render: WithSelectItemsTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { useState } from 'react';
+import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function ColumnOptionsDropdown() {
+  const [viewSelected, setViewSelected] = useState(false);
+  const [editSelected, setEditSelected] = useState(true);
+  const [exportSelected, setExportSelected] = useState(false);
+
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="dropdown">Column options</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.SelectItem selected={viewSelected} onSelectChange={setViewSelected}>
+          View student profile
+        </Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={editSelected} onSelectChange={setEditSelected}>
+          Edit assessment details
+        </Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={exportSelected} onSelectChange={setExportSelected}>
+          Export to CSV
+        </Dropdown.SelectItem>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default ColumnOptionsDropdown;`,
+            },
+        },
+    },
+}, 'Use `Dropdown.SelectItem` when each item is a toggle rather than a one-shot action. Selected items display a checkmark icon on the right. By default `closeAfterSelection={true}`, so clicking an item checks it **and** closes the dropdown — ideal for single-selection patterns. To keep the dropdown open for multi-select, see the **MultiSelectPersistent** story.');
+export const MultiSelectPersistent = withDescription({
+    render: MultiSelectPersistentTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { useState } from 'react';
+import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function YearGroupFilter() {
+  const [year7, setYear7] = useState(true);
+  const [year8, setYear8] = useState(false);
+  const [year9, setYear9] = useState(true);
+  const [year10, setYear10] = useState(false);
+  const [year11, setYear11] = useState(false);
+
+  const selectedCount = [year7, year8, year9, year10, year11].filter(Boolean).length;
+
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="dropdown">
+          Year groups{selectedCount > 0 ? \` (\${selectedCount})\` : ''}
+        </Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        {/* closeAfterSelection={false} keeps the menu open for multi-select */}
+        <Dropdown.SelectItem selected={year7} onSelectChange={setYear7} closeAfterSelection={false}>Year 7</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year8} onSelectChange={setYear8} closeAfterSelection={false}>Year 8</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year9} onSelectChange={setYear9} closeAfterSelection={false}>Year 9</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year10} onSelectChange={setYear10} closeAfterSelection={false}>Year 10</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year11} onSelectChange={setYear11} closeAfterSelection={false}>Year 11</Dropdown.SelectItem>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default YearGroupFilter;`,
+            },
+        },
+    },
+}, "For multi-select filters, pass `closeAfterSelection={false}` on **every** `Dropdown.SelectItem` to keep the menu open between selections. The button label updates to show how many year groups are selected. This pattern is common on Arbor's attendance and progress reports where teachers want to filter by multiple year groups at once.");
+export const WithGroups = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Actions" }) }), _jsxs(Dropdown.Content, { children: [_jsxs(Dropdown.Group, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('message'), children: "Send message to parents" }), _jsx(Dropdown.Item, { onSelect: () => console.log('email'), children: "Send email to guardian" })] }), _jsxs(Dropdown.Group, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('export'), children: "Export to CSV" }), _jsx(Dropdown.Item, { onSelect: () => console.log('report'), children: "Generate report" })] }), _jsx(Dropdown.Group, { children: _jsx(Dropdown.Item, { onSelect: () => console.log('archive'), children: "Archive record" }) })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function GroupedActionsDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Group>
+          <Dropdown.Item onSelect={() => console.log('message')}>Send message to parents</Dropdown.Item>
+          <Dropdown.Item onSelect={() => console.log('email')}>Send email to guardian</Dropdown.Item>
+        </Dropdown.Group>
+        <Dropdown.Group>
+          <Dropdown.Item onSelect={() => console.log('export')}>Export to CSV</Dropdown.Item>
+          <Dropdown.Item onSelect={() => console.log('report')}>Generate report</Dropdown.Item>
+        </Dropdown.Group>
+        <Dropdown.Group>
+          <Dropdown.Item onSelect={() => console.log('archive')}>Archive record</Dropdown.Item>
+        </Dropdown.Group>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default GroupedActionsDropdown;`,
+            },
+        },
+    },
+}, '`Dropdown.Group` provides semantic grouping via `role="group"` — screen readers can announce group boundaries. No visual divider is rendered automatically; combine with `Dropdown.Separator` if you want visible separation (see **WithGroupsAndSeparators**). Use groups to organise related actions: Communication / Data & Reporting / Destructive actions.');
+export const WithGroupsAndSeparators = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Actions" }) }), _jsxs(Dropdown.Content, { children: [_jsxs(Dropdown.Group, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('message'), children: "Send message to parents" }), _jsx(Dropdown.Item, { onSelect: () => console.log('email'), children: "Send email to guardian" })] }), _jsx(Dropdown.Separator, {}), _jsxs(Dropdown.Group, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('export'), children: "Export to CSV" }), _jsx(Dropdown.Item, { onSelect: () => console.log('report'), children: "Generate report" })] }), _jsx(Dropdown.Separator, {}), _jsx(Dropdown.Group, { children: _jsx(Dropdown.Item, { onSelect: () => console.log('archive'), children: "Archive record" }) })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function GroupsWithSeparatorsDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Group>
+          <Dropdown.Item onSelect={() => console.log('message')}>Send message to parents</Dropdown.Item>
+          <Dropdown.Item onSelect={() => console.log('email')}>Send email to guardian</Dropdown.Item>
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Group>
+          <Dropdown.Item onSelect={() => console.log('export')}>Export to CSV</Dropdown.Item>
+          <Dropdown.Item onSelect={() => console.log('report')}>Generate report</Dropdown.Item>
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Group>
+          <Dropdown.Item onSelect={() => console.log('archive')}>Archive record</Dropdown.Item>
+        </Dropdown.Group>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default GroupsWithSeparatorsDropdown;`,
+            },
+        },
+    },
+}, "Combine `Dropdown.Group` (semantic) with `Dropdown.Separator` (visual) for the clearest information hierarchy. The separator is a zero-config horizontal rule — just drop it between groups. This pattern maps directly to Arbor's \"Communication / Data & Reporting / Actions\" grouping convention used on student and staff record pages.");
+export const MixedItemTypes = withDescription({
+    render: MixedItemTypesTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { useState } from 'react';
+import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function RecordOptionsDropdown() {
+  const [csvSelected, setCsvSelected] = useState(false);
+  const [pdfSelected, setPdfSelected] = useState(true);
+
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Record options</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        {/* One-shot actions */}
+        <Dropdown.Item onSelect={() => console.log('view')}>View student profile</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('edit')}>Edit assessment details</Dropdown.Item>
+        <Dropdown.Separator />
+        {/* Toggle actions — stay open for multi-select */}
+        <Dropdown.SelectItem selected={csvSelected} onSelectChange={setCsvSelected} closeAfterSelection={false}>
+          Export to CSV
+        </Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={pdfSelected} onSelectChange={setPdfSelected} closeAfterSelection={false}>
+          Export to PDF
+        </Dropdown.SelectItem>
+        <Dropdown.Separator />
+        <Dropdown.Item onSelect={() => console.log('archive')}>Archive record</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default RecordOptionsDropdown;`,
+            },
+        },
+    },
+}, 'You can mix `Dropdown.Item` (one-shot actions) and `Dropdown.SelectItem` (toggles) in the same content panel, separated by `Dropdown.Separator`. Here the top section has navigational actions, the middle has export format toggles (multi-select, stays open), and the bottom has a final action. This mirrors real Arbor pages where you might want both "go somewhere" and "configure how you export" in one menu.');
+export const WithIcons = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", iconRightName: "3-dot", iconRightScreenReaderText: "More actions", hasHorizontalPadding: false }) }), _jsxs(Dropdown.Content, { children: [_jsxs(Dropdown.Item, { onSelect: () => console.log('view'), children: [_jsx(Icon, { name: "user", size: 16 }), "View student profile"] }), _jsxs(Dropdown.Item, { onSelect: () => console.log('edit'), children: [_jsx(Icon, { name: "pencil", size: 16 }), "Edit assessment details"] }), _jsxs(Dropdown.Item, { onSelect: () => console.log('message'), children: [_jsx(Icon, { name: "mail", size: 16 }), "Send message to parents"] }), _jsx(Dropdown.Separator, {}), _jsxs(Dropdown.Item, { onSelect: () => console.log('delete'), children: [_jsx(Icon, { name: "trash", size: 16 }), "Delete permanently"] })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button, Icon } from '@arbor-education/design-system.components';
+
+function IconItemsDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary" iconRightName="3-dot" iconRightScreenReaderText="More actions" hasHorizontalPadding={false} />
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item onSelect={() => console.log('view')}>
+          <Icon name="user" size={16} />
+          View student profile
+        </Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('edit')}>
+          <Icon name="pencil" size={16} />
+          Edit assessment details
+        </Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('message')}>
+          <Icon name="mail" size={16} />
+          Send message to parents
+        </Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item onSelect={() => console.log('delete')}>
+          <Icon name="trash" size={16} />
+          Delete permanently
+        </Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default IconItemsDropdown;`,
+            },
+        },
+    },
+}, 'Icons inside `Dropdown.Item` children align automatically via the item\'s flex layout (`gap` + `align-items: center`). Use `size={16}` to match the item\'s line height. The trigger here uses an icon-only `Button` with `iconRightName="3-dot"` — the classic "more actions" kebab pattern used throughout Arbor\'s table rows. Always provide `iconRightScreenReaderText` so screen reader users know what the button does.');
+export const WithDestructiveAction = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Student actions" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { onSelect: () => console.log('view'), children: "View student profile" }), _jsx(Dropdown.Item, { onSelect: () => console.log('edit'), children: "Edit assessment details" }), _jsx(Dropdown.Item, { onSelect: () => console.log('archive'), children: "Archive record" }), _jsx(Dropdown.Separator, {}), _jsx(Dropdown.Item, { onSelect: () => console.log('delete'), children: _jsxs("span", { style: { color: 'var(--color-semantic-destructive-600)', display: 'flex', alignItems: 'center', gap: 'var(--spacing-xsmall)' }, children: [_jsx(Icon, { name: "trash", size: 16 }), "Delete permanently"] }) })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button, Icon } from '@arbor-education/design-system.components';
+
+function DestructiveActionDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Student actions</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item onSelect={() => console.log('view')}>View student profile</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('edit')}>Edit assessment details</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('archive')}>Archive record</Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item onSelect={() => console.log('delete')}>
+          <span style={{ color: 'var(--color-semantic-destructive-600)', display: 'flex', alignItems: 'center', gap: 'var(--spacing-xsmall)' }}>
+            <Icon name="trash" size={16} />
+            Delete permanently
+          </span>
+        </Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default DestructiveActionDropdown;`,
+            },
+        },
+    },
+}, 'Destructive actions (delete, revoke, expel) belong at the **bottom** of the menu, separated by a `Dropdown.Separator`, styled in the semantic destructive colour token `--color-semantic-destructive-600`. This placement and colour treatment reinforces that the action is irreversible. Consider whether a destructive Dropdown item should instead open a confirmation `Modal` before proceeding — for truly irreversible data changes, a Modal is always safer.');
+export const AlignEnd = withDescription({
+    render: () => (_jsx("div", { style: { display: 'flex', justifyContent: 'flex-end', width: '300px', padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Right-aligned trigger" }) }), _jsxs(Dropdown.Content, { contentProps: { align: 'end' }, children: [_jsx(Dropdown.Item, { onSelect: () => console.log('view'), children: "View student profile" }), _jsx(Dropdown.Item, { onSelect: () => console.log('edit'), children: "Edit assessment details" }), _jsx(Dropdown.Item, { onSelect: () => console.log('export'), children: "Export to CSV" })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function AlignEndDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Right-aligned trigger</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content contentProps={{ align: 'end' }}>
+        <Dropdown.Item onSelect={() => console.log('view')}>View student profile</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('edit')}>Edit assessment details</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('export')}>Export to CSV</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default AlignEndDropdown;`,
+            },
+        },
+    },
+}, "Pass `contentProps={{ align: 'end' }}` to anchor the content panel's right edge to the trigger's right edge. Use this when your trigger sits near the right side of the viewport (e.g. an \"Actions\" button in the last column of a table) so the menu doesn't overflow off-screen. Default is `align: 'start'` (left-anchored).");
+export const OpenUpward = withDescription({
+    render: () => (_jsx("div", { style: { display: 'flex', alignItems: 'flex-end', height: '240px', padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { children: _jsx(Button, { variant: "secondary", children: "Trigger near bottom" }) }), _jsxs(Dropdown.Content, { contentProps: { side: 'top' }, children: [_jsx(Dropdown.Item, { onSelect: () => console.log('view'), children: "View student profile" }), _jsx(Dropdown.Item, { onSelect: () => console.log('edit'), children: "Edit assessment details" }), _jsx(Dropdown.Item, { onSelect: () => console.log('export'), children: "Export to CSV" }), _jsx(Dropdown.Item, { onSelect: () => console.log('archive'), children: "Archive record" })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function OpenUpwardDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="secondary">Trigger near bottom</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content contentProps={{ side: 'top' }}>
+        <Dropdown.Item onSelect={() => console.log('view')}>View student profile</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('edit')}>Edit assessment details</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('export')}>Export to CSV</Dropdown.Item>
+        <Dropdown.Item onSelect={() => console.log('archive')}>Archive record</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default OpenUpwardDropdown;`,
+            },
+        },
+    },
+}, "Pass `contentProps={{ side: 'top' }}` to open the menu upward from the trigger. Use this when the trigger is near the bottom of the viewport and the menu would otherwise be clipped — for example, an actions button in the last row of a paginated table. Radix also supports `avoidCollisions={true}` (the default) which automatically flips the panel when there is insufficient space.");
+export const TriggerDisabled = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsxs(Dropdown, { children: [_jsx(Dropdown.Trigger, { disabled: true, children: _jsx(Button, { variant: "secondary", disabled: true, children: "Actions (unavailable)" }) }), _jsxs(Dropdown.Content, { children: [_jsx(Dropdown.Item, { children: "View student profile" }), _jsx(Dropdown.Item, { children: "Edit assessment details" })] })] }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function TriggerDisabledDropdown() {
+  return (
+    <Dropdown>
+      <Dropdown.Trigger disabled>
+        <Button variant="secondary" disabled>
+          Actions (unavailable)
+        </Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>View student profile</Dropdown.Item>
+        <Dropdown.Item>Edit assessment details</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default TriggerDisabledDropdown;`,
+            },
+        },
+    },
+}, 'Pass `disabled` on `Dropdown.Trigger` to prevent the dropdown from opening at all. Because `Trigger` uses `asChild`, you should **also** pass `disabled` to the child element (the `Button` here) so it receives the correct visual and ARIA disabled state. Use this when the entire set of actions is contextually unavailable, e.g. on a read-only record.');
+export const SchoolContextExample = withDescription({
+    render: SchoolContextExampleTemplate,
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `import { useState } from 'react';
+import { Dropdown, Button } from '@arbor-education/design-system.components';
+
+function AttendanceReportFilter() {
+  const [year7, setYear7] = useState(true);
+  const [year8, setYear8] = useState(true);
+  const [year9, setYear9] = useState(false);
+  const [year10, setYear10] = useState(false);
+  const [year11, setYear11] = useState(false);
+  const [allYears, setAllYears] = useState(false);
+
+  const handleAllYears = (checked: boolean) => {
+    setAllYears(checked);
+    if (checked) {
+      setYear7(true); setYear8(true); setYear9(true);
+      setYear10(true); setYear11(true);
+    }
+  };
+
+  const selectedYears = [
+    year7 && 'Year 7', year8 && 'Year 8', year9 && 'Year 9',
+    year10 && 'Year 10', year11 && 'Year 11',
+  ].filter(Boolean);
+
+  const label = allYears
+    ? 'All year groups'
+    : selectedYears.length === 0 ? 'Select year groups' : selectedYears.join(', ');
+
+  return (
+    <Dropdown>
+      <Dropdown.Trigger>
+        <Button variant="dropdown">{label}</Button>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.SelectItem selected={allYears} onSelectChange={handleAllYears} closeAfterSelection={false}>
+          All year groups
+        </Dropdown.SelectItem>
+        <Dropdown.Separator />
+        <Dropdown.SelectItem selected={year7} onSelectChange={setYear7} closeAfterSelection={false}>Year 7</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year8} onSelectChange={setYear8} closeAfterSelection={false}>Year 8</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year9} onSelectChange={setYear9} closeAfterSelection={false}>Year 9</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year10} onSelectChange={setYear10} closeAfterSelection={false}>Year 10</Dropdown.SelectItem>
+        <Dropdown.SelectItem selected={year11} onSelectChange={setYear11} closeAfterSelection={false}>Year 11</Dropdown.SelectItem>
+      </Dropdown.Content>
+    </Dropdown>
+  );
+}
+
+export default AttendanceReportFilter;`,
+            },
+        },
+    },
+}, 'A realistic Arbor attendance report filter demonstrating the full multi-select pattern. Selecting "All year groups" checks every year group simultaneously. The trigger label reflects the current selection. All items use `closeAfterSelection={false}` so teachers can pick multiple year groups in a single interaction. This is the canonical Arbor usage pattern for Dropdown-based filters.');
 //# sourceMappingURL=Dropdown.stories.js.map