@arbor-education/design-system.components 3.2.0 → 3.3.0

package/src/components/editableText/EditableText.stories.tsx

@@ -341,7 +341,6 @@ const LongTextTemplate = () => {
 const EscapeToCancelTemplate = () => {
   const [text, setText] = useState('Mr. David Chen');
   const [savedText, setSavedText] = useState('Mr. David Chen');
-  const [cancelCount, setCancelCount] = useState(0);
 
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '480px' }}>
@@ -352,38 +351,22 @@ const EscapeToCancelTemplate = () => {
           setSavedText(val);
         }}
       />
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem' }}>
-        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: '0.875rem' }}>
-          Saved value: &quot;
-          {savedText}
-          &quot;
-        </p>
-        <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: '0.875rem' }}>
-          Escapes pressed:
-          {' '}
-          {cancelCount}
-        </p>
-      </div>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: '0.875rem' }}>
+        Saved value: &quot;
+        {savedText}
+        &quot;
+      </p>
       <p className="ds-text" style={{ margin: 0, fontSize: '0.875rem' }}>
         Try editing the text above, type something new, then press
         {' '}
         <kbd>Escape</kbd>
         {' '}
-        — the
-        original value is restored without calling
+        — the saved value above won&apos;t change, because
         {' '}
         <code>onEditSave</code>
-        .
+        {' '}
+        is never called.
       </p>
-      {/*
-        We track cancels by wrapping the component and watching for text changes
-        that don't match what we'd expect from a save — but EditableText does not
-        expose an onCancel callback. The counter below is illustrative only.
-        Reset the page to see the true saved state.
-      */}
-      <Button variant="secondary" onClick={() => setCancelCount(c => c + 1)}>
-        Simulate cancel count (manual)
-      </Button>
     </div>
   );
 };
@@ -424,12 +407,17 @@ import { useState } from 'react';
 const [text, setText] = useState(
   'Attendance requirements and absence notification procedures for all pupils enrolled in Year 10.',
 );
+const [lastSaved, setLastSaved] = useState(text);
 
 <EditableText
   text={text}
   multiline
-  onEditSave={setText}
+  onEditSave={(val) => {
+    setText(val);
+    setLastSaved(val);
+  }}
 />
+<p>Last saved: &quot;{lastSaved}&quot;</p>
           `.trim(),
         },
       },
@@ -573,7 +561,9 @@ const [text, setText] = useState(
   'Behaviour policy and expectations for all students during lesson time, including mobile phone usage and dress code requirements',
 );
 
-<EditableText text={text} onEditSave={setText} />
+<div style={{ maxWidth: '480px' }}>
+  <EditableText text={text} onEditSave={setText} />
+</div>
           `.trim(),
         },
       },
@@ -596,10 +586,17 @@ import { EditableText } from '@arbor-education/design-system.components';
 import { useState } from 'react';
 
 const [text, setText] = useState('Mr. David Chen');
+const [savedText, setSavedText] = useState('Mr. David Chen');
 
 // Pressing Escape while editing restores the pre-edit value
-// and does NOT call onEditSave — no network request is made.
-<EditableText text={text} onEditSave={setText} />
+// and does NOT call onEditSave — savedText never changes.
+<EditableText
+  text={text}
+  onEditSave={(val) => {
+    setText(val);
+    setSavedText(val);
+  }}
+/>
           `.trim(),
         },
       },

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

@@ -75,6 +75,12 @@ const DEVELOPER_NOTES = [
   'compose custom `FilterBar.Tag` children when you need bespoke markup. Avoid mixing both patterns in',
   'the same production instance.',
   '',
+  '**`label` is optional.** Omit it when the value alone is self-explanatory, such as a free-text',
+  'search term or a single unambiguous criterion. Without a `label`, the tag renders just the value',
+  '(no `Label:` prefix) and the generated `actionLabel` drops the label segment too, e.g. `Open filter',
+  'Interventions` instead of `Open filter Event Type: Interventions`. Most applied tags in a filter,',
+  'sort, or group list benefit from a label, so reach for this only when it would be redundant.',
+  '',
   '---',
   '',
   '### Accessibility',
@@ -106,7 +112,7 @@ const DEVELOPER_NOTES = [
   '| `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` |',
+  '| `FilterBarType` | Union of `filter`, `sort`, `group`, and `add` |',
 ].join('\n');
 
 const RELATED_COMPONENTS = [
@@ -134,7 +140,7 @@ const TOOLBAR_PROPS = [
 const BUTTON_PROPS = [
   '| Prop | Type | Default | Description |',
   '|---|---|---|---|',
-  '| `type` | `` `filter` \\| `sort` \\| `group` `` | — | **Required.** Chooses the default label, icon, and count announcement text |',
+  '| `type` | `` `filter` \\| `sort` \\| `group` \\| `add` `` | — | **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 |',
@@ -163,8 +169,8 @@ const ACTIVE_LIST_PROPS = [
 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` |',
+  '| `type` | `` `filter` \\| `sort` \\| `group` \\| `add` `` | — | **Required.** Sets the default icon and action language |',
+  '| `label` | `string` | — | Criterion label, e.g. `Year group`. Optional — omit it when the value alone is self-explanatory; the tag then renders just the value with no `Label:` prefix, and the generated `actionLabel` drops the label segment too |',
   '| `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 |',
@@ -188,6 +194,7 @@ type FilterBarStoryArgs = FilterBar.Props & {
   filterCount: number;
   sortCount: number;
   groupCount: number;
+  addCount: number;
   wrap: boolean;
   collapseOverflow: boolean;
   overflowActionLabel: string;
@@ -229,6 +236,7 @@ const StoryShell = ({
 const onOpenFilter = fn();
 const onOpenSort = fn();
 const onOpenGroup = fn();
+const onOpenAdd = fn();
 const onOpenAppliedItem = fn();
 const onRemoveAppliedItem = fn();
 const onShowOverflow = fn();
@@ -337,12 +345,14 @@ const PANEL_FIELD_IDS: Record<FilterBar.Type, string> = {
   filter: 'attendance-filter-year-group',
   sort: 'attendance-sort-order',
   group: 'attendance-group-by',
+  add: 'attendance-add-criteria',
 };
 
 const PANEL_TITLES: Record<FilterBar.Type, string> = {
   filter: 'Filters',
   sort: 'Sorting',
   group: 'Grouping',
+  add: 'Add criteria',
 };
 
 // ---------------------------------------------------------------------------
@@ -455,6 +465,14 @@ const meta = {
         type: { summary: 'number' },
       },
     },
+    'addCount': {
+      control: { type: 'number', min: 0, max: 250 },
+      description: 'Applied add count shown on the Add trigger badge.',
+      table: {
+        category: 'FilterBar.Button',
+        type: { summary: 'number' },
+      },
+    },
     'wrap': {
       control: 'boolean',
       description: 'Allows the applied-item summary to wrap onto multiple lines.',
@@ -514,6 +532,7 @@ const DefaultTemplate = ({
   filterCount,
   sortCount,
   groupCount,
+  addCount,
   wrap,
   collapseOverflow,
   overflowActionLabel,
@@ -525,6 +544,7 @@ const DefaultTemplate = ({
         <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.Button type="add" count={addCount} onClick={onOpenAdd} />
       </FilterBar.Toolbar>
       <FilterBar.ActiveList
         items={DEFAULT_ITEMS}
@@ -580,6 +600,7 @@ const ModalWiringTemplate = () => {
     filter: 0,
     sort: 0,
     group: 0,
+    add: 0,
   });
 
   const items: FilterBar.TagItem[] = APPLIED_ITEM_SEEDS.flatMap((item) => {
@@ -639,6 +660,14 @@ const ModalWiringTemplate = () => {
               aria-haspopup="dialog"
               onClick={() => openModal('group')}
             />
+            <FilterBar.Button
+              type="add"
+              count={counts.add}
+              aria-controls={modalId}
+              aria-expanded={open && activeType === 'add'}
+              aria-haspopup="dialog"
+              onClick={() => openModal('add')}
+            />
           </FilterBar.Toolbar>
           <FilterBar.ActiveList
             ariaLabel="Applied attendance filters, sorting, and grouping"
@@ -744,6 +773,7 @@ export const Default: Story = withDescription(
       'filterCount': 3,
       'sortCount': 1,
       'groupCount': 1,
+      'addCount': 0,
       'wrap': false,
       'collapseOverflow': true,
       'overflowActionLabel': 'Show more applied items',
@@ -783,6 +813,7 @@ function HighCountsExample() {
           <FilterBar.Button type="filter" count={142} onClick={() => {}} />
           <FilterBar.Button type="sort" count={103} onClick={() => {}} />
           <FilterBar.Button type="group" count={12} onClick={() => {}} />
+          <FilterBar.Button type="add" onClick={() => {}} />
         </FilterBar.Toolbar>
         <FilterBar.ActiveList items={items} ariaLabel="Applied attendance filters, sorting, and grouping" />
       </FilterBar>
@@ -801,6 +832,7 @@ export default HighCountsExample;
             <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.Button type="add" onClick={onOpenAdd} />
           </FilterBar.Toolbar>
           <FilterBar.ActiveList
             items={DEFAULT_ITEMS}
@@ -841,12 +873,14 @@ const panelFieldIds: Record<FilterBarType, string> = {
   filter: 'attendance-filter-year-group',
   sort: 'attendance-sort-order',
   group: 'attendance-group-by',
+  add: 'attendance-add-criteria',
 };
 
 const PANEL_TITLES: Record<FilterBarType, string> = {
   filter: 'Filters',
   sort: 'Sorting',
   group: 'Grouping',
+  add: 'Add criteria',
 };
 
 const seedItems: FilterBarTagItem[] = [
@@ -931,6 +965,7 @@ function FilterBarModalWiringExample() {
     filter: 0,
     sort: 0,
     group: 0,
+    add: 0,
   });
 
   const items = seedItems.flatMap((item) => {
@@ -985,6 +1020,14 @@ function FilterBarModalWiringExample() {
             aria-haspopup="dialog"
             onClick={() => openModal('group')}
           />
+          <FilterBar.Button
+            type="add"
+            count={counts.add}
+            aria-controls={modalId}
+            aria-expanded={open && activeType === 'add'}
+            aria-haspopup="dialog"
+            onClick={() => openModal('add')}
+          />
         </FilterBar.Toolbar>
 
         <FilterBar.ActiveList
@@ -1156,6 +1199,85 @@ export default OverflowExample;
   ].join(' '),
 );
 
+export const WithoutLabels: 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: 'search-term', type: 'filter', value: 'Jordan Casey' },
+  { id: 'year-group', type: 'filter', label: 'Year group', value: 'Year 10' },
+  { id: 'attendance-band', type: 'filter', label: 'Attendance band', value: 'Below 90%' },
+];
+
+function WithoutLabelsExample() {
+  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={3} onClick={() => {}} />
+        </FilterBar.Toolbar>
+        <FilterBar.ActiveList items={items} ariaLabel="Applied attendance filters" />
+      </FilterBar>
+    </div>
+  );
+}
+export default WithoutLabelsExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <StoryShell>
+        <FilterBar aria-label="Attendance view controls">
+          <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+            <FilterBar.Button type="filter" count={3} onClick={onOpenFilter} />
+          </FilterBar.Toolbar>
+          <FilterBar.ActiveList
+            items={[
+              {
+                id: 'search-term',
+                type: 'filter',
+                value: 'Jordan Casey',
+                onClick: onOpenAppliedItem,
+                onRemove: onRemoveAppliedItem,
+              },
+              {
+                id: 'year-group',
+                type: 'filter',
+                label: 'Year group',
+                value: 'Year 10',
+                onClick: onOpenAppliedItem,
+                onRemove: onRemoveAppliedItem,
+              },
+              {
+                id: 'attendance-band',
+                type: 'filter',
+                label: 'Attendance band',
+                value: 'Below 90%',
+                onClick: onOpenAppliedItem,
+                onRemove: onRemoveAppliedItem,
+              },
+            ]}
+            ariaLabel="Applied attendance filters"
+          />
+        </FilterBar>
+      </StoryShell>
+    ),
+  },
+  [
+    'Omit `label` when the value alone is self-explanatory, such as the free-text search term shown',
+    'first here. That tag renders as just `Jordan Casey` with a shorter generated action label',
+    '(`Open filter Jordan Casey` instead of `Open filter Search: Jordan Casey`), while the labelled',
+    'tags alongside it keep their `Label: Value` layout for comparison.',
+  ].join(' '),
+);
+
 export const Empty: Story = withDescription(
   {
     parameters: {

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

@@ -171,6 +171,57 @@ describe('FilterBar', () => {
     }
   });
 
+  test('renders active list tags without a label and omits the label segment from the content and action label', async () => {
+    const user = userEvent.setup();
+    const onItemClick = vi.fn();
+
+    render(
+      <FilterBar>
+        <FilterBar.ActiveList
+          items={[
+            {
+              id: 'search',
+              type: 'filter',
+              value: 'Interventions',
+              onClick: onItemClick,
+            },
+          ]}
+        />
+      </FilterBar>,
+    );
+
+    const tagButton = screen.getByRole('button', { name: 'Open filter Interventions' });
+    expect(tagButton).toBeInTheDocument();
+    expect(screen.queryByText(':')).not.toBeInTheDocument();
+
+    await user.click(tagButton);
+
+    expect(onItemClick).toHaveBeenCalledOnce();
+    const [clickedItem] = onItemClick.mock.calls[0] ?? [];
+    expect(clickedItem).toMatchObject({ id: 'search', type: 'filter', value: 'Interventions' });
+    expect(clickedItem?.label).toBeUndefined();
+  });
+
+  test('renders a manually composed FilterBar.Tag without a label', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+
+    render(
+      <FilterBar>
+        <FilterBar.ActiveList>
+          <FilterBar.Tag type="sort" value="Priority first" onClick={onClick} />
+        </FilterBar.ActiveList>
+      </FilterBar>,
+    );
+
+    const tagButton = screen.getByRole('button', { name: 'Open sort Priority first' });
+    expect(screen.getByText('Priority first')).toBeInTheDocument();
+    expect(screen.queryByText(':')).not.toBeInTheDocument();
+
+    await user.click(tagButton);
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
   test('returns focus to the first toolbar button after sequentially removing all tags from their remove buttons', async () => {
     const user = userEvent.setup();
 

package/src/components/filterBar/FilterBar.tsx

@@ -7,12 +7,12 @@ import { TagList } from 'Components/tagList/TagList';
 import classNames from 'classnames';
 import { Children, forwardRef, type ButtonHTMLAttributes, type HTMLAttributes, type MouseEventHandler, type RefObject } from 'react';
 
-export type FilterBarType = 'filter' | 'sort' | 'group';
+export type FilterBarType = 'filter' | 'sort' | 'group' | 'add';
 
 export type FilterBarTagItem = {
   id: string;
   type: FilterBarType;
-  label: string;
+  label?: string;
   value: React.ReactNode;
   fieldId?: string;
   icon?: IconName;
@@ -64,12 +64,14 @@ const FILTER_BAR_TYPE_LABELS: Record<FilterBarType, string> = {
   filter: 'Filter',
   sort: 'Sort',
   group: 'Group',
+  add: 'Add',
 };
 
 const FILTER_BAR_TYPE_ICONS: Record<FilterBarType, IconName> = {
   filter: 'sliders-horizontal',
   sort: 'sorting',
   group: 'list-tree',
+  add: 'circle-plus',
 };
 
 const getVisibleCount = (count?: number | null): string | null => {
@@ -87,17 +89,21 @@ const getButtonA11yLabel = (type: FilterBarType, label: string, count?: number |
   return `Open ${label.toLowerCase()}. ${count} ${type} item${count === 1 ? '' : 's'} applied`;
 };
 
-const getTagActionLabel = (item: FilterBarTagItem): string => `Open ${item.type} ${item.label}: ${item.value}`;
+const getTagActionLabel = (item: FilterBarTagItem): string => item.label ? `Open ${item.type} ${item.label}: ${item.value}` : `Open ${item.type} ${item.value}`;
 
-const FilterBarTagContent = ({ label, value }: Pick<FilterBarTagProps, 'label' | 'value'>) => (
-  <span className="ds-filter-bar__tag-content">
-    <span className="ds-filter-bar__tag-label">
-      {label}
-      :
+const FilterBarTagContent = ({ label, value }: Pick<FilterBarTagProps, 'label' | 'value'>) => {
+  return (
+    <span className="ds-filter-bar__tag-content">
+      {label && (
+        <span className="ds-filter-bar__tag-label">
+          {label}
+          :
+        </span>
+      )}
+      <span className="ds-filter-bar__tag-value">{value}</span>
     </span>
-    <span className="ds-filter-bar__tag-value">{value}</span>
-  </span>
-);
+  );
+};
 
 export const FilterBar = ({
   children,
@@ -193,7 +199,7 @@ const FilterBarTag = ({
   onRemove,
 }: FilterBarTagProps): React.JSX.Element => {
   const item: FilterBarTagItem = {
-    id: id ?? fieldId ?? `${type}-${label}`,
+    id: id ?? fieldId ?? `${type}-${label}-${value}`,
     type,
     label,
     value,

package/src/components/formField/fieldset/Fieldset.stories.tsx

@@ -658,7 +658,7 @@ export default function DisabledFieldset() {
 );
 
 export const DisabledWithCheckboxes: Story = withDescription(
-  'The most visually compelling demonstration of the `disabled` prop — all checkboxes are greyed out and non-interactive with a single `disabled` on the fieldset. This is how Arbor locks consent forms during a pending approval workflow.',
+  'The most visually compelling demonstration of the `disabled` prop — all checkboxes are greyed out and non-interactive with a single `disabled` on the fieldset. Checked state is preserved and rendered independently of the `disabled` attribute — note that the two already-checked boxes stay visually checked while disabled, showing consent decisions captured before the form was locked for review.',
   {
     parameters: {
       controls: { disable: true },
@@ -669,6 +669,8 @@ import { Fieldset, CheckboxInput } from '@arbor-education/design-system.componen
 
 export default function DisabledCheckboxesFieldset() {
   return (
+    // checked state survives independently of disabled — these two were
+    // already consented to before the form was locked for review
     <Fieldset legend="Consent and permissions" disabled>
       <CheckboxInput
         id="consent-trips-dis"
@@ -754,7 +756,7 @@ export default function DisabledRadioFieldset() {
         name="diet"
         value="halal"
         label="Halal"
-        defaultChecked
+        checked
       />
       <RadioButtonInput
         id="diet-vegetarian-dis"
@@ -788,7 +790,7 @@ export default function DisabledRadioFieldset() {
           name="diet"
           value="halal"
           label="Halal"
-          defaultChecked
+          checked
         />
         <RadioButtonInput
           id="diet-vegetarian-dis"

package/src/components/row/Row.stories.tsx

@@ -320,13 +320,11 @@ const MixedClickableAndStaticTemplate = () => (
     <Row
       label="SEN status"
       value="SEN Support"
-      note="Review due May 2026"
       onClick={() => {}}
     />
     <Row
       label="Attendance (YTD)"
       value="88.3%"
-      note="Below 90% threshold"
       onClick={() => {}}
     />
   </Section>
@@ -778,13 +776,11 @@ function PupilDetailSection() {
       <Row
         label="SEN status"
         value="SEN Support"
-        note="Review due May 2026"
         onClick={() => navigateToSENRecord()}
       />
       <Row
         label="Attendance (YTD)"
         value="88.3%"
-        note="Below 90% threshold"
         onClick={() => navigateToAttendance()}
       />
     </Section>
@@ -832,7 +828,7 @@ export default PersonalDetailsSection;
     },
     render: InSectionTemplate,
   },
-  'The canonical real-world usage: `Row` components as children of a `Section`. The `Section` provides the container heading and background; each `Row` handles the label/value layout. Most product uses of `Row` are inside a `Section`.',
+  'The canonical real-world usage: `Row` components as children of a `Section`. The `Section` provides the container heading and background; each `Row` handles the label/value layout. Most product uses of `Row` are inside a `Section` — one row demonstrates a linked value via `href` to show that pattern working inside a realistic panel too.',
 );
 
 export const LongContent: Story = withDescription(
@@ -857,7 +853,6 @@ function LongContentExample() {
         label="Pupil premium eligibility reason"
         value="Free school meals — ever 6"
         note="Verified by LA"
-        onClick={() => navigateToEligibilityDetail()}
       />
     </div>
   );
@@ -878,7 +873,6 @@ export default LongContentExample;
           label="Pupil premium eligibility reason"
           value="Free school meals — ever 6"
           note="Verified by LA"
-          onClick={fn()}
         />
       </div>
     ),
@@ -1102,16 +1096,28 @@ export const WithTooltip: Story = withDescription(
           code: `
 import { Row } from '@arbor-education/design-system.components';
 
-function ReadOnlyRow() {
+function ReadOnlyRows() {
   return (
-    <Row
-      label="UPN"
-      value="A823456789012"
-      tooltipText="Unique Pupil Number — assigned by the DfE and cannot be changed here"
-    />
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <Row
+        label="UPN"
+        value="A823456789012"
+        tooltipText="Unique Pupil Number — assigned by the DfE and cannot be changed here"
+      />
+      <Row
+        label="Admission number"
+        value="001847"
+        tooltipText="Set at admission — contact the office to request a change"
+      />
+      {/* No tooltipText — hovering this row shows nothing */}
+      <Row
+        label="Year group"
+        value="Year 9"
+      />
+    </div>
   );
 }
-export default ReadOnlyRow;
+export default ReadOnlyRows;
 `.trim(),
         },
       },