@arbor-education/design-system.components 0.22.0 → 0.23.1

package/src/components/filterBar/FilterBar.stories.tsx

@@ -0,0 +1,1199 @@
+import {
+  Controls,
+  Heading as DocHeading,
+  Primary as DocPrimary,
+  Markdown,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from 'Components/button/Button';
+import { FormField } from 'Components/formField/FormField';
+import { Modal } from 'Components/modal/Modal';
+import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { fn } from 'storybook/test';
+import { FilterBar } from './FilterBar.js';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`FilterBar` is a dumb compound component for composing filter, sort, and group triggers with a',
+  'shared applied-item summary. It gives product code a consistent shell for toolbar buttons and',
+  'active tags, while the consuming screen owns selected state, modal or slideover wiring, removal',
+  'behaviour, and focus handoff into the opened surface.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Reporting and analysis pages that need filter, sort, and grouping controls in one predictable row',
+  '- Views where users benefit from seeing applied criteria as editable tags directly beside the triggers',
+  '- Flows that open a dialog, modal, slideover, or popover to manage the underlying criteria',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| You only need a passive summary of selected items | [`Tag`](?path=/docs/components-tag--docs) or a local summary pattern |',
+  '| You only have one control with no shared active-state summary | [`Button`](?path=/docs/components-button--docs) plus local content |',
+  '| The user edits criteria inline without a separate surface | Inline form fields or a dedicated toolbar layout |',
+  '| Applied values are read-only status labels, not editable criteria | [`Tag`](?path=/docs/components-tag--docs) or [`Pill`](?path=/docs/components-pill--docs) |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Label the toolbar.** `FilterBar.Toolbar` renders `role="toolbar"`, so it needs an accessible name',
+  'via `aria-label` or `aria-labelledby`. A generic parent region label is not a substitute for the',
+  'toolbar label itself.',
+  '',
+  '**Mirror popup semantics on the real trigger.** When a toolbar button opens a dialog,',
+  'slideover, listbox, or menu, pass the native button attributes that describe that relationship:',
+  '`aria-controls`, `aria-expanded`, and the correct `aria-haspopup` value for the popup type.',
+  'Applied tags currently support `ariaControls` and `ariaExpanded` for the same popup relationship.',
+  '',
+  '**Hand focus to the relevant field after opening.** `FilterBar` does not manage focus for you.',
+  'If a user clicks `Year group` or an applied `Year group: Year 10` tag, move focus into the matching',
+  'field once the modal or slideover has mounted. `fieldId` on `FilterBar.TagItem` is there to make',
+  'that handoff easy. When the editor surface is a `Modal`, give it a `contentId` and mirror that value',
+  'through `aria-controls` on the related buttons or tags so the relationship stays explicit.',
+  '',
+  '**Counts are summaries, not the source of truth.** Product code should derive them from the real',
+  'applied state. Counts above `99` render visually as `99+`, but the generated accessible label keeps',
+  'the full number.',
+  '',
+  '**Overflow only becomes interactive when you wire it.** `FilterBar.ActiveList` delegates to `TagList`.',
+  'With `collapseOverflow` enabled, the `+N more` summary becomes a focusable tag only when',
+  '`onOverflowClick` is provided.',
+  '',
+  '**Choose one active-list pattern per instance.** Pass `items` for the common data-driven case, or',
+  'compose custom `FilterBar.Tag` children when you need bespoke markup. Avoid mixing both patterns in',
+  'the same production instance.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Put an accessible name on the overall `FilterBar` region when it helps users understand the control set in context',
+  '- Put a separate accessible name on `FilterBar.Toolbar` because it renders `role="toolbar"`',
+  '- Use `aria-haspopup="dialog"` when a toolbar button opens a modal, `aria-haspopup="listbox"` for a listbox, and `aria-haspopup="menu"` for a menu',
+  '- Keep `aria-controls` and `aria-expanded` in sync on both toolbar buttons and applied tags when they reopen the same surface',
+  '- If an applied tag opens an editor, its `actionLabel` should describe both the criterion and the current value',
+  '- If a tag is removable, provide a specific `removeLabel` so screen readers announce the exact action',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { FilterBar, type FilterBarTagItem, type FilterBarType } from '@arbor-education/design-system.components';",
+  '',
+  'function AttendanceFilters(props: FilterBar.Props) {',
+  '  return <FilterBar {...props} />;',
+  '}',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `FilterBar.Props` | Root wrapper props |',
+  '| `FilterBar.ToolbarProps` | Toolbar wrapper props |',
+  '| `FilterBar.ButtonProps` | Trigger button props |',
+  '| `FilterBar.ActiveListProps` | Applied-item summary props |',
+  '| `FilterBar.TagProps` | Manually composed tag props |',
+  '| `FilterBar.TagItem` | Data shape for `ActiveList.items` |',
+  '| `FilterBarType` | Union of `filter`, `sort`, and `group` |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Tag](?path=/docs/components-tag--docs) · [Modal](?path=/docs/components-modals-modal--docs) · [Button](?path=/docs/components-button--docs) · [FormField](?path=/docs/components-formfield--docs)',
+].join('\n');
+
+const PROPS_INTRO = [
+  'The preview below is wired to the **Controls** panel for the most common root, toolbar, button-count,',
+  'and active-list options. Because `FilterBar` is a compound component, the public API for',
+  '`FilterBar.Toolbar`, `FilterBar.Button`, `FilterBar.ActiveList`, and `FilterBar.Tag` is documented',
+  'in the manual tables below.',
+].join(' ');
+
+const TOOLBAR_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | Toolbar contents, usually one or more `FilterBar.Button` instances |',
+  '| `className` | `string` | — | Additional CSS classes on the toolbar wrapper |',
+  '| `aria-label` / `aria-labelledby` | native div attrs | — | Accessible name for the `role="toolbar"` element. Strongly recommended |',
+  '| `...HTMLAttributes<HTMLDivElement>` | native div attrs | — | Standard div attributes are forwarded to the toolbar wrapper |',
+].join('\n');
+
+const BUTTON_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `type` | `` `filter` \\| `sort` \\| `group` `` | — | **Required.** Chooses the default label, icon, and count announcement text |',
+  '| `label` | `string` | inferred from `type` | Override the visible button label |',
+  '| `count` | `number \\| null` | — | Shows a badge when `> 0`. The badge caps visually at `99+`, but the accessible label keeps the full number |',
+  '| `icon` | `IconName` | inferred from `type` | Override the default icon for that trigger type |',
+  '| `htmlType` | `` `button` \\| `submit` \\| `reset` `` | `button` | Native button `type` attribute |',
+  '| `aria-label` | `string` | generated from label + count | Override the accessible name when the default sentence is not specific enough |',
+  '| `aria-controls` / `aria-expanded` / `aria-haspopup` | native button attrs | — | Add these when the trigger opens a dialog, listbox, menu, or similar popup surface |',
+  '| `disabled`, `onClick`, and other button props | native button attrs | — | Standard button attributes are forwarded to the underlying `Button` component |',
+].join('\n');
+
+const ACTIVE_LIST_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `items` | `readonly FilterBar.TagItem[]` | — | Data-driven applied tags. This is the standard production pattern |',
+  '| `children` | `ReactNode` | — | Manual composition fallback, typically one or more `FilterBar.Tag` children |',
+  '| `className` | `string` | — | Additional CSS classes on the list wrapper |',
+  '| `ariaLabel` | `string` | `"Active filters, sorting, and grouping"` | Accessible name for the underlying list of applied items |',
+  '| `emptyState` | `ReactNode` | — | Content shown when there are no `items` and no `children` |',
+  '| `returnFocusRef` | `RefObject<HTMLElement \\| null>` | — | Fallback focus target used when a removal leaves no interactive tags to focus |',
+  '| `wrap` | `boolean` | `false` | Allows items to wrap onto multiple lines |',
+  '| `collapseOverflow` | `boolean` | `true` | Collapses hidden tags behind a `+N more` summary when `wrap` is `false` |',
+  '| `overflowActionLabel` | `string` | `"Show more applied items"` | Accessible name for the overflow summary when it is clickable |',
+  '| `onOverflowClick` | `MouseEventHandler<HTMLButtonElement>` | — | Makes the overflow summary interactive. Use it to open the managing surface |',
+  '| `overflowAriaControls` / `overflowAriaExpanded` | native button attrs | — | Tie the overflow summary to the dialog or popup it opens |',
+].join('\n');
+
+const TAG_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `type` | `` `filter` \\| `sort` \\| `group` `` | — | **Required.** Sets the default icon and action language |',
+  '| `label` | `string` | — | **Required.** Criterion label, e.g. `Year group` |',
+  '| `value` | `ReactNode` | — | **Required.** Current applied value, e.g. `Year 10` |',
+  '| `id` | `string` | derived from `fieldId` or label | Stable identifier for list rendering and event payloads |',
+  '| `fieldId` | `string` | — | Optional DOM id for the field that should receive focus after opening an editor |',
+  '| `icon` | `IconName` | inferred from `type` | Override the default icon |',
+  '| `children` | `ReactNode` | generated label + value layout | Supply custom tag content when the default `Label: Value` layout is not enough |',
+  '| `actionLabel` | `string` | generated from type + label + value | Accessible name for the primary tag action |',
+  '| `removeLabel` | `string` | Tag default | Accessible name for the remove button when `onRemove` is provided |',
+  '| `ariaControls` / `ariaExpanded` | native button attrs | — | Tie the primary tag action to the editor it opens |',
+  '| `disabled` | `boolean` | `false` | Disables both the primary action and the remove button |',
+  '| `onClick` | `(item, event) => void` | — | Fired when the primary tag action is activated |',
+  '| `onRemove` | `(item) => void` | — | Fired when the remove button is activated |',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Story helpers
+// ---------------------------------------------------------------------------
+
+type FilterBarStoryArgs = FilterBar.Props & {
+  toolbarLabel: string;
+  activeListLabel: string;
+  filterCount: number;
+  sortCount: number;
+  groupCount: number;
+  wrap: boolean;
+  collapseOverflow: boolean;
+  overflowActionLabel: string;
+};
+
+const STORY_SHELL_STYLE: CSSProperties = {
+  width: '100%',
+  maxWidth: 'min(100%, 72rem)',
+  padding: 'var(--spacing-large)',
+  boxSizing: 'border-box',
+};
+
+const NARROW_STORY_SHELL_STYLE: CSSProperties = {
+  width: '100%',
+  maxWidth: 'min(100%, 34rem)',
+  padding: 'var(--spacing-large)',
+  boxSizing: 'border-box',
+};
+
+const MODAL_BODY_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 'var(--spacing-medium)',
+};
+
+const MODAL_TEXT_STYLE: CSSProperties = {
+  margin: 0,
+  color: 'var(--color-grey-700)',
+};
+
+const StoryShell = ({
+  children,
+  narrow = false,
+}: {
+  children: ReactNode;
+  narrow?: boolean;
+}) => <div style={narrow ? NARROW_STORY_SHELL_STYLE : STORY_SHELL_STYLE}>{children}</div>;
+
+const onOpenFilter = fn();
+const onOpenSort = fn();
+const onOpenGroup = fn();
+const onOpenAppliedItem = fn();
+const onRemoveAppliedItem = fn();
+const onShowOverflow = fn();
+
+const APPLIED_ITEM_SEEDS: ReadonlyArray<{
+  id: string;
+  type: FilterBar.Type;
+  label: string;
+  value: string;
+  fieldId: string;
+}> = [
+  {
+    id: 'year-group',
+    type: 'filter',
+    label: 'Year group',
+    value: 'Year 10',
+    fieldId: 'attendance-filter-year-group',
+  },
+  {
+    id: 'attendance-band',
+    type: 'filter',
+    label: 'Attendance band',
+    value: 'Below 90%',
+    fieldId: 'attendance-filter-band',
+  },
+  {
+    id: 'date-range',
+    type: 'filter',
+    label: 'Date range',
+    value: 'Spring term',
+    fieldId: 'attendance-filter-date-range',
+  },
+  {
+    id: 'sort-order',
+    type: 'sort',
+    label: 'Sort order',
+    value: 'Priority first',
+    fieldId: 'attendance-sort-order',
+  },
+  {
+    id: 'group-by',
+    type: 'group',
+    label: 'Group by',
+    value: 'Tutor group',
+    fieldId: 'attendance-group-by',
+  },
+];
+
+const INITIAL_MODAL_FIELD_VALUES = APPLIED_ITEM_SEEDS.reduce<Record<string, string>>((acc, item) => {
+  acc[item.fieldId] = item.value;
+  return acc;
+}, {});
+
+const OVERFLOW_ITEM_SEEDS: ReadonlyArray<{
+  id: string;
+  type: FilterBar.Type;
+  label: string;
+  value: string;
+  fieldId: string;
+}> = [
+  ...APPLIED_ITEM_SEEDS,
+  {
+    id: 'intervention',
+    type: 'filter',
+    label: 'Intervention',
+    value: 'Attendance plan',
+    fieldId: 'attendance-filter-intervention',
+  },
+  {
+    id: 'reviewer',
+    type: 'filter',
+    label: 'Reviewer',
+    value: 'Heads of year',
+    fieldId: 'attendance-filter-reviewer',
+  },
+  {
+    id: 'status',
+    type: 'filter',
+    label: 'Status',
+    value: 'Open cases',
+    fieldId: 'attendance-filter-status',
+  },
+];
+
+const buildAppliedItems = (
+  seeds: ReadonlyArray<{
+    id: string;
+    type: FilterBar.Type;
+    label: string;
+    value: string;
+    fieldId: string;
+  }>,
+): FilterBar.TagItem[] =>
+  seeds.map(item => ({
+    ...item,
+    actionLabel: `Open ${item.type} ${item.label}: ${item.value}`,
+    removeLabel: `Remove ${item.label.toLowerCase()} ${item.type}`,
+    onClick: (clickedItem, event) => onOpenAppliedItem(clickedItem, event),
+    onRemove: clickedItem => onRemoveAppliedItem(clickedItem),
+  }));
+
+const DEFAULT_ITEMS = buildAppliedItems(APPLIED_ITEM_SEEDS);
+const OVERFLOW_ITEMS = buildAppliedItems(OVERFLOW_ITEM_SEEDS);
+
+const PANEL_FIELD_IDS: Record<FilterBar.Type, string> = {
+  filter: 'attendance-filter-year-group',
+  sort: 'attendance-sort-order',
+  group: 'attendance-group-by',
+};
+
+const PANEL_TITLES: Record<FilterBar.Type, string> = {
+  filter: 'Filters',
+  sort: 'Sorting',
+  group: 'Grouping',
+};
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function FilterBarDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>FilterBar.Toolbar props</DocHeading>
+      <Markdown>{TOOLBAR_PROPS}</Markdown>
+      <DocHeading>FilterBar.Button props</DocHeading>
+      <Markdown>{BUTTON_PROPS}</Markdown>
+      <DocHeading>FilterBar.ActiveList props</DocHeading>
+      <Markdown>{ACTIVE_LIST_PROPS}</Markdown>
+      <DocHeading>FilterBar.Tag props</DocHeading>
+      <Markdown>{TAG_PROPS}</Markdown>
+      <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/FilterBar',
+  component: FilterBar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: FilterBarDocsPage,
+    },
+  },
+  argTypes: {
+    'aria-label': {
+      control: 'text',
+      description: 'Accessible name for the outer `FilterBar` region.',
+      table: {
+        category: 'FilterBar',
+        type: { summary: 'string' },
+      },
+    },
+    'className': {
+      control: false,
+      description: 'Additional CSS classes applied to the root element.',
+      table: {
+        category: 'FilterBar',
+        type: { summary: 'string' },
+      },
+    },
+    'children': {
+      control: false,
+      table: {
+        disable: true,
+      },
+    },
+    'toolbarLabel': {
+      control: 'text',
+      description: 'Accessible name passed to `FilterBar.Toolbar` (`role="toolbar"`).',
+      table: {
+        category: 'FilterBar.Toolbar',
+        type: { summary: 'string' },
+      },
+    },
+    'activeListLabel': {
+      control: 'text',
+      description: 'Accessible name passed to `FilterBar.ActiveList`.',
+      table: {
+        category: 'FilterBar.ActiveList',
+        type: { summary: 'string' },
+      },
+    },
+    'filterCount': {
+      control: { type: 'number', min: 0, max: 250 },
+      description: 'Applied filter count shown on the Filter trigger badge.',
+      table: {
+        category: 'FilterBar.Button',
+        type: { summary: 'number' },
+      },
+    },
+    'sortCount': {
+      control: { type: 'number', min: 0, max: 250 },
+      description: 'Applied sort count shown on the Sort trigger badge.',
+      table: {
+        category: 'FilterBar.Button',
+        type: { summary: 'number' },
+      },
+    },
+    'groupCount': {
+      control: { type: 'number', min: 0, max: 250 },
+      description: 'Applied group count shown on the Group trigger badge.',
+      table: {
+        category: 'FilterBar.Button',
+        type: { summary: 'number' },
+      },
+    },
+    'wrap': {
+      control: 'boolean',
+      description: 'Allows the applied-item summary to wrap onto multiple lines.',
+      table: {
+        category: 'FilterBar.ActiveList',
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'collapseOverflow': {
+      control: 'boolean',
+      description: 'Collapses hidden tags behind a `+N more` summary when `wrap` is `false`.',
+      table: {
+        category: 'FilterBar.ActiveList',
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+      },
+    },
+    'overflowActionLabel': {
+      control: 'text',
+      description: 'Accessible label for the overflow summary when it is clickable.',
+      table: {
+        category: 'FilterBar.ActiveList',
+        type: { summary: 'string' },
+      },
+    },
+  },
+} satisfies Meta<FilterBarStoryArgs>;
+
+export default meta;
+type Story = StoryObj<FilterBarStoryArgs>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const DefaultTemplate = ({
+  toolbarLabel,
+  activeListLabel,
+  filterCount,
+  sortCount,
+  groupCount,
+  wrap,
+  collapseOverflow,
+  overflowActionLabel,
+  ...rootProps
+}: FilterBarStoryArgs) => (
+  <StoryShell>
+    <FilterBar {...rootProps}>
+      <FilterBar.Toolbar aria-label={toolbarLabel}>
+        <FilterBar.Button type="filter" count={filterCount} onClick={onOpenFilter} />
+        <FilterBar.Button type="sort" count={sortCount} onClick={onOpenSort} />
+        <FilterBar.Button type="group" count={groupCount} onClick={onOpenGroup} />
+      </FilterBar.Toolbar>
+      <FilterBar.ActiveList
+        items={DEFAULT_ITEMS}
+        ariaLabel={activeListLabel}
+        wrap={wrap}
+        collapseOverflow={collapseOverflow}
+        overflowActionLabel={overflowActionLabel}
+        onOverflowClick={onShowOverflow}
+      />
+    </FilterBar>
+  </StoryShell>
+);
+
+const ModalWiringTemplate = () => {
+  const [open, setOpen] = useState(false);
+  const [activeType, setActiveType] = useState<FilterBar.Type>('filter');
+  const [pendingFocusFieldId, setPendingFocusFieldId] = useState<string>(PANEL_FIELD_IDS.filter);
+  const [fieldValues, setFieldValues] = useState<Record<string, string>>(() => ({ ...INITIAL_MODAL_FIELD_VALUES }));
+  const firstToolbarButtonRef = useRef<HTMLButtonElement>(null);
+  const modalId = 'attendance-filter-bar-modal';
+
+  const openModal = (type: FilterBar.Type, fieldId = PANEL_FIELD_IDS[type]) => {
+    setActiveType(type);
+    setPendingFocusFieldId(fieldId);
+    setOpen(true);
+  };
+
+  useEffect(() => {
+    if (!open) return;
+
+    const frame = requestAnimationFrame(() => {
+      document.getElementById(pendingFocusFieldId)?.focus();
+    });
+
+    return () => cancelAnimationFrame(frame);
+  }, [open, pendingFocusFieldId]);
+
+  const updateFieldValue = (fieldId: string, value: string) => {
+    setFieldValues(prev => ({
+      ...prev,
+      [fieldId]: value,
+    }));
+  };
+
+  const counts = APPLIED_ITEM_SEEDS.reduce<Record<FilterBar.Type, number>>((acc, item) => {
+    if (fieldValues[item.fieldId]?.trim()) {
+      acc[item.type] += 1;
+    }
+    return acc;
+  }, {
+    filter: 0,
+    sort: 0,
+    group: 0,
+  });
+
+  const items: FilterBar.TagItem[] = APPLIED_ITEM_SEEDS.flatMap((item) => {
+    const value = fieldValues[item.fieldId]?.trim();
+    if (!value) return [];
+
+    return [{
+      ...item,
+      value,
+      ariaControls: modalId,
+      ariaExpanded: open && activeType === item.type,
+      actionLabel: `Open ${item.type} ${item.label}: ${value}`,
+      removeLabel: `Remove ${item.label.toLowerCase()} ${item.type}`,
+      onClick: clickedItem => openModal(clickedItem.type, clickedItem.fieldId ?? PANEL_FIELD_IDS[clickedItem.type]),
+      onRemove: (removedItem) => {
+        if (!removedItem.fieldId) return;
+        updateFieldValue(removedItem.fieldId, '');
+      },
+    }];
+  });
+
+  const handleApplyChanges = () => {
+    setOpen(false);
+  };
+
+  return (
+    <>
+      <StoryShell>
+        <FilterBar aria-label="Attendance view controls">
+          <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+            <FilterBar.Button
+              type="filter"
+              count={counts.filter}
+              ref={firstToolbarButtonRef}
+              aria-controls={modalId}
+              aria-expanded={open && activeType === 'filter'}
+              aria-haspopup="dialog"
+              onClick={() => openModal('filter')}
+            />
+            <FilterBar.Button
+              type="sort"
+              count={counts.sort}
+              aria-controls={modalId}
+              aria-expanded={open && activeType === 'sort'}
+              aria-haspopup="dialog"
+              onClick={() => openModal('sort')}
+            />
+            <FilterBar.Button
+              type="group"
+              count={counts.group}
+              aria-controls={modalId}
+              aria-expanded={open && activeType === 'group'}
+              aria-haspopup="dialog"
+              onClick={() => openModal('group')}
+            />
+          </FilterBar.Toolbar>
+          <FilterBar.ActiveList
+            ariaLabel="Applied attendance filters, sorting, and grouping"
+            items={items}
+            returnFocusRef={firstToolbarButtonRef}
+            onOverflowClick={() => openModal('filter')}
+            overflowActionLabel="Show all applied attendance items"
+            overflowAriaControls={modalId}
+            overflowAriaExpanded={open}
+          />
+        </FilterBar>
+      </StoryShell>
+
+      <Modal open={open} closeHandler={() => setOpen(false)} contentId={modalId} title="Attendance view controls">
+        <Modal.Body>
+          <div style={MODAL_BODY_STYLE}>
+            <p style={MODAL_TEXT_STYLE}>
+              Update the attendance view settings below. Opening this dialog from a toolbar button or
+              applied tag moves focus to the related field so the next action is immediate. If you
+              remove every applied tag from its close button, focus returns to the first toolbar
+              button so keyboard users keep a reliable home position.
+            </p>
+            <p style={MODAL_TEXT_STYLE}>
+              Active panel:
+              {' '}
+              <strong>{PANEL_TITLES[activeType]}</strong>
+            </p>
+            <FormField
+              label="Year group"
+              id={PANEL_FIELD_IDS.filter}
+              inputType="text"
+              inputProps={{
+                value: fieldValues[PANEL_FIELD_IDS.filter] ?? '',
+                onChange: event => updateFieldValue(PANEL_FIELD_IDS.filter, event.target.value),
+                placeholder: 'e.g. Year 10',
+              }}
+            />
+            <FormField
+              label="Attendance band"
+              id="attendance-filter-band"
+              inputType="text"
+              inputProps={{
+                value: fieldValues['attendance-filter-band'] ?? '',
+                onChange: event => updateFieldValue('attendance-filter-band', event.target.value),
+                placeholder: 'e.g. Below 90%',
+              }}
+            />
+            <FormField
+              label="Date range"
+              id="attendance-filter-date-range"
+              inputType="text"
+              inputProps={{
+                value: fieldValues['attendance-filter-date-range'] ?? '',
+                onChange: event => updateFieldValue('attendance-filter-date-range', event.target.value),
+                placeholder: 'e.g. Spring term',
+              }}
+            />
+            <FormField
+              label="Sort order"
+              id={PANEL_FIELD_IDS.sort}
+              inputType="text"
+              inputProps={{
+                value: fieldValues[PANEL_FIELD_IDS.sort] ?? '',
+                onChange: event => updateFieldValue(PANEL_FIELD_IDS.sort, event.target.value),
+                placeholder: 'e.g. Priority first',
+              }}
+            />
+            <FormField
+              label="Group by"
+              id={PANEL_FIELD_IDS.group}
+              inputType="text"
+              inputProps={{
+                value: fieldValues[PANEL_FIELD_IDS.group] ?? '',
+                onChange: event => updateFieldValue(PANEL_FIELD_IDS.group, event.target.value),
+                placeholder: 'e.g. Tutor group',
+              }}
+            />
+          </div>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={handleApplyChanges}>
+            Apply changes
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      'aria-label': 'Attendance view controls',
+      'toolbarLabel': 'Filter, sort, and group controls',
+      'activeListLabel': 'Applied attendance filters, sorting, and grouping',
+      'filterCount': 3,
+      'sortCount': 1,
+      'groupCount': 1,
+      'wrap': false,
+      'collapseOverflow': true,
+      'overflowActionLabel': 'Show more applied items',
+    },
+    render: args => <DefaultTemplate {...args} />,
+  },
+  [
+    'The controls-friendly reference composition. The root label, toolbar label, trigger counts, and',
+    'key active-list behaviours are all wired to the Controls panel, while the applied tags stay as a',
+    'realistic Arbor-style data set.',
+  ].join(' '),
+);
+
+export const HighCounts: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FilterBar, type FilterBarTagItem } from '@arbor-education/design-system.components';
+
+const items: FilterBarTagItem[] = [
+  { id: 'year-group', type: 'filter', label: 'Year group', value: 'Year 10' },
+  { id: 'attendance-band', type: 'filter', label: 'Attendance band', value: 'Below 90%' },
+  { id: 'date-range', type: 'filter', label: 'Date range', value: 'Spring term' },
+  { id: 'sort-order', type: 'sort', label: 'Sort order', value: 'Priority first' },
+  { id: 'group-by', type: 'group', label: 'Group by', value: 'Tutor group' },
+];
+
+function HighCountsExample() {
+  return (
+    <div style={{ width: '100%', maxWidth: 'min(100%, 72rem)', padding: 'var(--spacing-large)', boxSizing: 'border-box' }}>
+      <FilterBar aria-label="Attendance view controls">
+        <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+          <FilterBar.Button type="filter" count={142} onClick={() => {}} />
+          <FilterBar.Button type="sort" count={103} onClick={() => {}} />
+          <FilterBar.Button type="group" count={12} onClick={() => {}} />
+        </FilterBar.Toolbar>
+        <FilterBar.ActiveList items={items} ariaLabel="Applied attendance filters, sorting, and grouping" />
+      </FilterBar>
+    </div>
+  );
+}
+export default HighCountsExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <StoryShell>
+        <FilterBar aria-label="Attendance view controls">
+          <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+            <FilterBar.Button type="filter" count={142} onClick={onOpenFilter} />
+            <FilterBar.Button type="sort" count={103} onClick={onOpenSort} />
+            <FilterBar.Button type="group" count={12} onClick={onOpenGroup} />
+          </FilterBar.Toolbar>
+          <FilterBar.ActiveList
+            items={DEFAULT_ITEMS}
+            ariaLabel="Applied attendance filters, sorting, and grouping"
+          />
+        </FilterBar>
+      </StoryShell>
+    ),
+  },
+  [
+    'Counts above `99` render as `99+` visually, but the generated button label still announces the',
+    'true total. Use this pattern for dense reporting views where badge counts may be much larger than',
+    'the number of visible tags.',
+  ].join(' '),
+);
+
+export const ModalWiring: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useEffect, useRef, useState } from 'react';
+import {
+  Button,
+  FilterBar,
+  FormField,
+  Modal,
+  type FilterBarTagItem,
+  type FilterBarType,
+} from '@arbor-education/design-system.components';
+
+const modalId = 'attendance-filter-bar-modal';
+
+const panelFieldIds: Record<FilterBarType, string> = {
+  filter: 'attendance-filter-year-group',
+  sort: 'attendance-sort-order',
+  group: 'attendance-group-by',
+};
+
+const PANEL_TITLES: Record<FilterBarType, string> = {
+  filter: 'Filters',
+  sort: 'Sorting',
+  group: 'Grouping',
+};
+
+const seedItems: FilterBarTagItem[] = [
+  {
+    id: 'year-group',
+    type: 'filter',
+    label: 'Year group',
+    value: 'Year 10',
+    fieldId: 'attendance-filter-year-group',
+  },
+  {
+    id: 'attendance-band',
+    type: 'filter',
+    label: 'Attendance band',
+    value: 'Below 90%',
+    fieldId: 'attendance-filter-band',
+  },
+  {
+    id: 'date-range',
+    type: 'filter',
+    label: 'Date range',
+    value: 'Spring term',
+    fieldId: 'attendance-filter-date-range',
+  },
+  {
+    id: 'sort-order',
+    type: 'sort',
+    label: 'Sort order',
+    value: 'Priority first',
+    fieldId: 'attendance-sort-order',
+  },
+  {
+    id: 'group-by',
+    type: 'group',
+    label: 'Group by',
+    value: 'Tutor group',
+    fieldId: 'attendance-group-by',
+  },
+];
+
+const initialFieldValues = seedItems.reduce<Record<string, string>>((acc, item) => {
+  acc[item.fieldId!] = item.value;
+  return acc;
+}, {});
+
+function FilterBarModalWiringExample() {
+  const [open, setOpen] = useState(false);
+  const [activeType, setActiveType] = useState<FilterBarType>('filter');
+  const [pendingFocusFieldId, setPendingFocusFieldId] = useState(panelFieldIds.filter);
+  const [fieldValues, setFieldValues] = useState<Record<string, string>>(() => ({ ...initialFieldValues }));
+  const firstToolbarButtonRef = useRef<HTMLButtonElement>(null);
+
+  const openModal = (type: FilterBarType, fieldId = panelFieldIds[type]) => {
+    setActiveType(type);
+    setPendingFocusFieldId(fieldId);
+    setOpen(true);
+  };
+
+  useEffect(() => {
+    if (!open) return;
+
+    const frame = requestAnimationFrame(() => {
+      document.getElementById(pendingFocusFieldId)?.focus();
+    });
+
+    return () => cancelAnimationFrame(frame);
+  }, [open, pendingFocusFieldId]);
+
+  const updateFieldValue = (fieldId: string, value: string) => {
+    setFieldValues(prev => ({
+      ...prev,
+      [fieldId]: value,
+    }));
+  };
+
+  const counts = seedItems.reduce<Record<FilterBarType, number>>((acc, item) => {
+    if (fieldValues[item.fieldId!]?.trim()) {
+      acc[item.type] += 1;
+    }
+    return acc;
+  }, {
+    filter: 0,
+    sort: 0,
+    group: 0,
+  });
+
+  const items = seedItems.flatMap((item) => {
+    const value = fieldValues[item.fieldId!]?.trim();
+    if (!value) return [];
+
+    return [{
+      ...item,
+      value,
+      ariaControls: modalId,
+      ariaExpanded: open && activeType === item.type,
+      actionLabel: \`Open \${item.type} \${item.label}: \${value}\`,
+      onClick: (clickedItem: FilterBarTagItem) =>
+        openModal(clickedItem.type, clickedItem.fieldId ?? panelFieldIds[clickedItem.type]),
+      onRemove: (removedItem: FilterBarTagItem) => {
+        if (!removedItem.fieldId) return;
+        updateFieldValue(removedItem.fieldId, '');
+      },
+    }];
+  });
+
+  const handleApplyChanges = () => {
+    setOpen(false);
+  };
+
+  return (
+    <>
+      <FilterBar aria-label="Attendance view controls">
+        <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+          <FilterBar.Button
+            type="filter"
+            count={counts.filter}
+            ref={firstToolbarButtonRef}
+            aria-controls={modalId}
+            aria-expanded={open && activeType === 'filter'}
+            aria-haspopup="dialog"
+            onClick={() => openModal('filter')}
+          />
+          <FilterBar.Button
+            type="sort"
+            count={counts.sort}
+            aria-controls={modalId}
+            aria-expanded={open && activeType === 'sort'}
+            aria-haspopup="dialog"
+            onClick={() => openModal('sort')}
+          />
+          <FilterBar.Button
+            type="group"
+            count={counts.group}
+            aria-controls={modalId}
+            aria-expanded={open && activeType === 'group'}
+            aria-haspopup="dialog"
+            onClick={() => openModal('group')}
+          />
+        </FilterBar.Toolbar>
+
+        <FilterBar.ActiveList
+          items={items}
+          ariaLabel="Applied attendance filters, sorting, and grouping"
+          returnFocusRef={firstToolbarButtonRef}
+          onOverflowClick={() => openModal('filter')}
+          overflowActionLabel="Show all applied attendance items"
+          overflowAriaControls={modalId}
+          overflowAriaExpanded={open}
+        />
+      </FilterBar>
+
+      <Modal open={open} closeHandler={() => setOpen(false)} contentId={modalId} title="Attendance view controls">
+        <Modal.Body>
+          <p style={{ marginBottom: 'var(--spacing-large)' }}>
+            Update the attendance view settings below. Opening this dialog from a toolbar button or
+            applied tag moves focus to the related field so the next action is immediate. If you
+            remove every applied tag from its close button, focus returns to the first toolbar
+            button so keyboard users keep a reliable home position.
+          </p>
+          <p style={{ marginBottom: 'var(--spacing-large)' }}>
+            Active panel: <strong>{PANEL_TITLES[activeType]}</strong>
+          </p>
+          <FormField
+            label="Year group"
+            id="attendance-filter-year-group"
+            inputType="text"
+            inputProps={{
+              value: fieldValues['attendance-filter-year-group'] ?? '',
+              onChange: event => updateFieldValue('attendance-filter-year-group', event.target.value),
+              placeholder: 'e.g. Year 10',
+            }}
+          />
+          <FormField
+            label="Attendance band"
+            id="attendance-filter-band"
+            inputType="text"
+            inputProps={{
+              value: fieldValues['attendance-filter-band'] ?? '',
+              onChange: event => updateFieldValue('attendance-filter-band', event.target.value),
+              placeholder: 'e.g. Below 90%',
+            }}
+          />
+          <FormField
+            label="Date range"
+            id="attendance-filter-date-range"
+            inputType="text"
+            inputProps={{
+              value: fieldValues['attendance-filter-date-range'] ?? '',
+              onChange: event => updateFieldValue('attendance-filter-date-range', event.target.value),
+              placeholder: 'e.g. Spring term',
+            }}
+          />
+          <FormField
+            label="Sort order"
+            id="attendance-sort-order"
+            inputType="text"
+            inputProps={{
+              value: fieldValues['attendance-sort-order'] ?? '',
+              onChange: event => updateFieldValue('attendance-sort-order', event.target.value),
+              placeholder: 'e.g. Priority first',
+            }}
+          />
+          <FormField
+            label="Group by"
+            id="attendance-group-by"
+            inputType="text"
+            inputProps={{
+              value: fieldValues['attendance-group-by'] ?? '',
+              onChange: event => updateFieldValue('attendance-group-by', event.target.value),
+              placeholder: 'e.g. Tutor group',
+            }}
+          />
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+          <Button variant="primary" onClick={handleApplyChanges}>Apply changes</Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}
+export default FilterBarModalWiringExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => <ModalWiringTemplate />,
+  },
+  [
+    'The recommended production wiring when toolbar buttons and applied tags reopen the same dialog.',
+    'Notice the matching `aria-controls`, `aria-expanded`, and `aria-haspopup="dialog"` attributes,',
+    'plus the post-open focus handoff into the field represented by the clicked trigger.',
+    'This example also shows `returnFocusRef`: arrow onto the tag remove buttons and remove tags',
+    'sequentially until none remain, and focus returns to the `Filter` button.',
+  ].join(' '),
+);
+
+export const Overflow: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FilterBar, type FilterBarTagItem } from '@arbor-education/design-system.components';
+
+const items: FilterBarTagItem[] = [
+  { id: 'year-group', type: 'filter', label: 'Year group', value: 'Year 10' },
+  { id: 'attendance-band', type: 'filter', label: 'Attendance band', value: 'Below 90%' },
+  { id: 'date-range', type: 'filter', label: 'Date range', value: 'Spring term' },
+  { id: 'sort-order', type: 'sort', label: 'Sort order', value: 'Priority first' },
+  { id: 'group-by', type: 'group', label: 'Group by', value: 'Tutor group' },
+  { id: 'intervention', type: 'filter', label: 'Intervention', value: 'Attendance plan' },
+  { id: 'reviewer', type: 'filter', label: 'Reviewer', value: 'Heads of year' },
+  { id: 'status', type: 'filter', label: 'Status', value: 'Open cases' },
+];
+
+function OverflowExample() {
+  return (
+    <div style={{ width: '100%', maxWidth: 'min(100%, 34rem)', padding: 'var(--spacing-large)', boxSizing: 'border-box' }}>
+      <FilterBar aria-label="Attendance view controls">
+        <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+          <FilterBar.Button type="filter" count={6} onClick={() => {}} />
+          <FilterBar.Button type="sort" count={1} onClick={() => {}} />
+          <FilterBar.Button type="group" count={1} onClick={() => {}} />
+        </FilterBar.Toolbar>
+        <FilterBar.ActiveList
+          items={items}
+          ariaLabel="Applied attendance filters, sorting, and grouping"
+          collapseOverflow
+          overflowActionLabel="Show all applied attendance items"
+          onOverflowClick={() => {}}
+        />
+      </FilterBar>
+    </div>
+  );
+}
+export default OverflowExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <StoryShell narrow>
+        <FilterBar aria-label="Attendance view controls">
+          <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+            <FilterBar.Button type="filter" count={6} onClick={onOpenFilter} />
+            <FilterBar.Button type="sort" count={1} onClick={onOpenSort} />
+            <FilterBar.Button type="group" count={1} onClick={onOpenGroup} />
+          </FilterBar.Toolbar>
+          <FilterBar.ActiveList
+            items={OVERFLOW_ITEMS}
+            ariaLabel="Applied attendance filters, sorting, and grouping"
+            collapseOverflow
+            overflowActionLabel="Show all applied attendance items"
+            onOverflowClick={onShowOverflow}
+          />
+        </FilterBar>
+      </StoryShell>
+    ),
+  },
+  [
+    'A constrained container showing the single-row overflow behaviour. Hidden tags collapse behind a',
+    'focusable `+N more` summary when `onOverflowClick` is provided, making it suitable for reopening a',
+    'full filter-management surface.',
+  ].join(' '),
+);
+
+export const Empty: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FilterBar } from '@arbor-education/design-system.components';
+
+function EmptyFilterBarExample() {
+  return (
+    <div style={{ width: '100%', maxWidth: 'min(100%, 72rem)', padding: 'var(--spacing-large)', boxSizing: 'border-box' }}>
+      <FilterBar aria-label="Attendance view controls">
+        <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+          <FilterBar.Button type="filter" onClick={() => {}} />
+          <FilterBar.Button type="sort" onClick={() => {}} />
+          <FilterBar.Button type="group" onClick={() => {}} />
+        </FilterBar.Toolbar>
+        <FilterBar.ActiveList emptyState="No filters, sorting, or grouping applied." />
+      </FilterBar>
+    </div>
+  );
+}
+export default EmptyFilterBarExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <StoryShell>
+        <FilterBar aria-label="Attendance view controls">
+          <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+            <FilterBar.Button type="filter" onClick={onOpenFilter} />
+            <FilterBar.Button type="sort" onClick={onOpenSort} />
+            <FilterBar.Button type="group" onClick={onOpenGroup} />
+          </FilterBar.Toolbar>
+          <FilterBar.ActiveList emptyState="No filters, sorting, or grouping applied." />
+        </FilterBar>
+      </StoryShell>
+    ),
+  },
+  [
+    'The no-selection state. Use a clear empty-state sentence so users understand that nothing is',
+    'currently applied, rather than assuming the summary area failed to render.',
+  ].join(' '),
+);