@arbor-education/design-system.components 0.24.3 → 0.25.1

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

@@ -122,9 +122,15 @@ describe('FilterBar', () => {
     const rectSpy = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function mockRect(this: HTMLElement) {
       let width = 0;
 
-      if (this.classList.contains('ds-tag-list__viewport')) width = 220;
-      else if (this.classList.contains('ds-tag-list__item')) width = 84;
-      else if (this.classList.contains('ds-tag-list__overflow')) width = 76;
+      if (this.classList.contains('ds-tag-list__viewport')) {
+        width = 220;
+      }
+      else if (this.classList.contains('ds-tag-list__item')) {
+        width = 84;
+      }
+      else if (this.classList.contains('ds-tag-list__overflow')) {
+        width = 76;
+      }
 
       return {
         width,

package/src/components/filterBar/FilterBar.tsx

@@ -73,7 +73,9 @@ const FILTER_BAR_TYPE_ICONS: Record<FilterBarType, IconName> = {
 };
 
 const getVisibleCount = (count?: number | null): string | null => {
-  if (typeof count !== 'number' || count <= 0) return null;
+  if (typeof count !== 'number' || count <= 0) {
+    return null;
+  }
   return count > 99 ? '99+' : `${count}`;
 };
 
@@ -267,7 +269,9 @@ const FilterBarActiveList = ({
   }
 
   if (!children) {
-    if (!emptyState) return null;
+    if (!emptyState) {
+      return null;
+    }
     return <div className={classNames('ds-filter-bar__empty-state', className)}>{emptyState}</div>;
   }
 

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

@@ -320,9 +320,24 @@ export const Default: Story = {
   },
   render: args => (
     <Fieldset {...args}>
-      <CheckboxInput id="consent-trips" name="consent" label="Consent for school trips" onChange={() => {}} />
-      <CheckboxInput id="consent-photos" name="consent" label="Consent for photographs" onChange={() => {}} />
-      <CheckboxInput id="consent-data" name="consent" label="Consent for data sharing with partner schools" onChange={() => {}} />
+      <CheckboxInput
+        id="consent-trips"
+        name="consent"
+        label="Consent for school trips"
+        onChange={() => {}}
+      />
+      <CheckboxInput
+        id="consent-photos"
+        name="consent"
+        label="Consent for photographs"
+        onChange={() => {}}
+      />
+      <CheckboxInput
+        id="consent-data"
+        name="consent"
+        label="Consent for data sharing with partner schools"
+        onChange={() => {}}
+      />
     </Fieldset>
   ),
 };

package/src/components/formField/inputs/radio/RadioButtonGroup.tsx

@@ -1,6 +1,6 @@
 import type { ChangeEvent } from 'react';
 import { RadioButtonInput } from './RadioButtonInput.js';
-import { Fieldset, type FieldsetProps } from '../../fieldset/Fieldset.js';
+import { Fieldset, type FieldsetProps } from 'Components/formField/fieldset/Fieldset.js';
 
 export type RadioGroupOption = {
   id: string;

package/src/components/formField/inputs/selectDropdown/SelectDropdown.tsx

@@ -72,7 +72,9 @@ export const SelectDropdown = (props: SelectDropdownInputProps) => {
   const UNGROUPED_KEY = 'Ungrouped';
   const groupedOptions = options.reduce((acc, option) => {
     const key = option.group ?? UNGROUPED_KEY;
-    if (!acc[key]) acc[key] = [];
+    if (!acc[key]) {
+      acc[key] = [];
+    }
     acc[key].push(option);
     return acc;
   }, {} as Record<string, SelectDropdownItemProps[]>);

package/src/components/formField/inputs/textArea/TextArea.stories.tsx

@@ -353,11 +353,16 @@ const ControlledWithCharacterCountTemplate = () => {
   const isApproaching = remaining <= 100 && remaining > 0;
   const isAtLimit = remaining <= 0;
 
-  const countColour = isAtLimit
-    ? 'var(--color-semantic-destructive-600)'
-    : isApproaching
-      ? 'var(--color-semantic-caution-600)'
-      : 'var(--color-grey-600)';
+  let countColour: string;
+  if (isAtLimit) {
+    countColour = 'var(--color-semantic-destructive-600)';
+  }
+  else if (isApproaching) {
+    countColour = 'var(--color-semantic-caution-600)';
+  }
+  else {
+    countColour = 'var(--color-grey-600)';
+  }
 
   return (
     <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>

package/src/components/formField/inputs/time/TimeInput.test.tsx

@@ -8,7 +8,9 @@ describe('TimeInput', () => {
   beforeEach(() => {
     globalThis.ResizeObserver = class {
       observe() {}
+
       unobserve() {}
+
       disconnect() {}
     } as unknown as typeof ResizeObserver;
   });

package/src/components/formField/inputs/time/TimeInput.tsx

@@ -82,16 +82,16 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
 
   const focusAndSelectHours = useCallback(() => {
     const input = inputRef.current;
-    if (!input) return;
+    if (!input) {
+      return;
+    }
 
     input.focus();
 
     try {
       input.setSelectionRange(0, 2);
     }
-    catch {
-      // Some browsers do not expose selection APIs on time inputs.
-    }
+    catch { /* Some browsers do not expose selection APIs on time inputs. */ }
   }, []);
 
   const timeOptions = useMemo<ComboboxOption[]>(

package/src/components/heading/Heading.stories.tsx

@@ -368,7 +368,10 @@ const WithBackControlLegacyTemplate = () => (
 const WithEditableTitleTemplate = () => (
   <div style={{ padding: 'var(--spacing-xlarge)' }}>
     <Heading level={1}>
-      <EditableText text="Form 7B Registration" onEditSave={() => {}} />
+      <EditableText
+        text="Form 7B Registration"
+        onEditSave={() => {}}
+      />
     </Heading>
   </div>
 );
@@ -377,7 +380,10 @@ const WithEditableTitleAndActionTemplate = () => (
   <div style={{ padding: 'var(--spacing-xlarge)' }}>
     <Heading level={1}>
       <Heading.InnerContainer>
-        <EditableText text="Form 7B Registration" onEditSave={() => {}} />
+        <EditableText
+          text="Form 7B Registration"
+          onEditSave={() => {}}
+        />
       </Heading.InnerContainer>
       <Heading.InnerContainer>
         <Button variant="primary" type="button">Save changes</Button>
@@ -393,7 +399,10 @@ const WithEditableTitleAndMultipleActionsTemplate = () => (
         <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
           Back
         </Button>
-        <EditableText text="Autumn term report" onEditSave={() => {}} />
+        <EditableText
+          text="Autumn term report"
+          onEditSave={() => {}}
+        />
       </Heading.InnerContainer>
       <Heading.InnerContainer className="medium-spacing-gap">
         <Button variant="secondary" type="button">Export to CSV</Button>

package/src/components/modal/Modal.stories.tsx

@@ -548,11 +548,21 @@ const WithDropdownInsideModalTemplate = () => {
               <Button variant="dropdown">Select a teacher</Button>
             </Dropdown.Trigger>
             <Dropdown.Content>
-              <Dropdown.Item onSelect={() => {}}>Ms A. Johnson — English</Dropdown.Item>
-              <Dropdown.Item onSelect={() => {}}>Mr B. Patel — Mathematics</Dropdown.Item>
-              <Dropdown.Item onSelect={() => {}}>Mrs C. Williams — Science</Dropdown.Item>
-              <Dropdown.Item onSelect={() => {}}>Mr D. Thompson — History</Dropdown.Item>
-              <Dropdown.Item onSelect={() => {}}>Ms E. Okonkwo — Art</Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>
+                Ms A. Johnson — English
+              </Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>
+                Mr B. Patel — Mathematics
+              </Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>
+                Mrs C. Williams — Science
+              </Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>
+                Mr D. Thompson — History
+              </Dropdown.Item>
+              <Dropdown.Item onSelect={() => {}}>
+                Ms E. Okonkwo — Art
+              </Dropdown.Item>
             </Dropdown.Content>
           </Dropdown>
         </Modal.Body>

package/src/components/progress/Progress.stories.tsx

@@ -274,7 +274,9 @@ const InteractiveLoadingTemplate = (args: React.ComponentProps<typeof Progress>)
   const [running, setRunning] = useState(true);
 
   useEffect(() => {
-    if (!running) return;
+    if (!running) {
+      return;
+    }
     if (progress >= 100) {
       setRunning(false);
       return;

package/src/components/section/Section.stories.tsx

@@ -66,11 +66,11 @@ const DEVELOPER_NOTES = [
   '',
   '---',
   '',
-  '### Button props must all be provided together',
+  '### Pass all button props via `headerButtonProps`',
   '',
-  'The action button only renders when `buttonText` is provided.',
-  'When adding a button, always supply all four props together: `buttonText`, `buttonOnClick`, `buttonVariant`, and `buttonSize`.',
-  'If any are omitted, the `Button` component falls back to its own defaults, which may produce unexpected visual results.',
+  'The action button only renders when `headerButtonProps` is provided.',
+  'Pass a single `headerButtonProps` object containing at minimum `children` (button label) and `onClick`.',
+  'Always include `variant` and `size` to avoid relying on `Button` defaults, which may not look right in the heading context.',
   '',
   '---',
   '',
@@ -213,41 +213,16 @@ const meta: Meta<typeof Section> = {
         defaultValue: { summary: 'false' },
       },
     },
-    buttonText: {
+    headerButtonProps: {
       description: [
-        'Label for the action button rendered in the section heading.',
-        'Must be paired with `buttonOnClick`, `buttonVariant`, and `buttonSize`.',
+        'Props forwarded directly to the `Button` component rendered in the section heading.',
+        'Omit this prop entirely to render no button.',
+        'When provided, always include `children` (button label), `onClick`, `variant`, and `size`',
+        "to avoid unexpected visual results from `Button` defaults. Use `size: 'S'` to keep it lightweight alongside the title.",
       ].join(' '),
-      control: 'text',
-      table: {
-        type: { summary: 'string' },
-        defaultValue: { summary: 'undefined' },
-      },
-    },
-    buttonOnClick: {
-      description: 'Click handler for the heading action button.',
-      action: 'buttonOnClick',
       control: false,
       table: {
-        type: { summary: 'MouseEventHandler<HTMLButtonElement>' },
-        defaultValue: { summary: 'undefined' },
-      },
-    },
-    buttonVariant: {
-      description: 'Visual variant for the heading action button. Always supply when `buttonText` is set.',
-      control: 'select',
-      options: ['primary', 'secondary', 'tertiary', 'primary-destructive', 'secondary-destructive', 'tertiary-destructive', 'ghost'],
-      table: {
-        type: { summary: "'primary' | 'secondary' | 'tertiary' | 'primary-destructive' | 'secondary-destructive' | 'tertiary-destructive' | 'ghost'" },
-        defaultValue: { summary: 'undefined' },
-      },
-    },
-    buttonSize: {
-      description: "Size of the heading action button. Always supply when `buttonText` is set. Use `'S'` to keep it visually lightweight alongside the title.",
-      control: 'select',
-      options: ['S', 'M', 'L'],
-      table: {
-        type: { summary: "'S' | 'M' | 'L'" },
+        type: { summary: 'ButtonProps' },
         defaultValue: { summary: 'undefined' },
       },
     },
@@ -311,7 +286,7 @@ export const Default: Story = withDescription(
     },
     render: args => <Section {...args} />,
   },
-  'The default story is wired to the Controls panel. Toggle `collapsible` to add expand/collapse behaviour, or add `buttonText` (with the three companion props) to surface an action in the heading.',
+  'The default story is wired to the Controls panel. Toggle `collapsible` to add expand/collapse behaviour, or pass `headerButtonProps` to surface an action in the heading.',
 );
 
 export const WithHeadingLevel: Story = withDescription(
@@ -441,10 +416,13 @@ function PersonalDetailsSection() {
     <Section
       title="Personal Details"
       headingLevel={2}
-      buttonText="Edit"
-      buttonOnClick={() => openEditModal()}
-      buttonVariant="secondary"
-      buttonSize="S"
+      headerButtonProps={{
+        children: 'Edit',
+        iconLeftName: 'pencil',
+        onClick: () => openEditModal(),
+        variant: 'secondary',
+        size: 'S',
+      }}
     >
       <p>Section content here.</p>
     </Section>
@@ -459,26 +437,168 @@ export default PersonalDetailsSection;
       <Section
         title="Personal Details"
         headingLevel={2}
-        buttonText="Edit"
-        buttonOnClick={fn()}
-        buttonVariant="secondary"
-        buttonSize="S"
+        headerButtonProps={{
+          children: 'Edit',
+          iconLeftName: 'pencil',
+          onClick: fn(),
+          variant: 'secondary',
+          size: 'S',
+        }}
       >
         <p>
-          The action button appears in the heading row. Always provide all four button props together:
-          <code>buttonText</code>
-          ,
-          <code>buttonOnClick</code>
-          ,
-          <code>buttonVariant</code>
-          , and
-          <code>buttonSize</code>
-          .
+          The action button appears in the heading row. Use
+          <code>iconLeftName</code>
+          {' '}
+          or
+          <code>iconRightName</code>
+          {' '}
+          inside
+          <code>headerButtonProps</code>
+          {' '}
+          to add an icon alongside the label.
         </p>
       </Section>
     ),
   },
-  'Provide all four button props together to render an action button in the section heading. Use `buttonSize="S"` to keep it visually lightweight alongside the title.',
+  'Pass `headerButtonProps` to render an action button in the section heading. Icons can be added via `iconLeftName` or `iconRightName`. Use `size: "S"` to keep it visually lightweight alongside the title.',
+);
+
+export const WithActionButtonVariants: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Section } from '@arbor-education/design-system.components';
+
+// Icon on the left
+<Section title="Documents" headingLevel={2}
+  headerButtonProps={{ children: 'Upload', iconLeftName: 'upload', onClick: () => {}, variant: 'secondary', size: 'S' }}>
+  <p>...</p>
+</Section>
+
+// Icon on the right
+<Section title="External Link" headingLevel={2}
+  headerButtonProps={{ children: 'Open', iconRightName: 'external-link', onClick: () => {}, variant: 'tertiary', size: 'S' }}>
+  <p>...</p>
+</Section>
+
+// Icon-only (no children — button renders in icon-only mode)
+<Section title="Attachments" headingLevel={2}
+  headerButtonProps={{ iconLeftName: 'plus', iconLeftScreenReaderText: 'Add attachment', onClick: () => {}, variant: 'secondary', size: 'S' }}>
+  <p>...</p>
+</Section>
+
+// Destructive
+<Section title="Danger Zone" headingLevel={2}
+  headerButtonProps={{ children: 'Delete', iconLeftName: 'trash', onClick: () => {}, variant: 'primary-destructive', size: 'S' }}>
+  <p>...</p>
+</Section>
+
+// Disabled
+<Section title="Locked Section" headingLevel={2}
+  headerButtonProps={{ children: 'Edit', iconLeftName: 'pencil', onClick: () => {}, variant: 'secondary', size: 'S', disabled: true }}>
+  <p>...</p>
+</Section>
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <>
+        <Section
+          title="Documents"
+          headingLevel={2}
+          headerButtonProps={{
+            children: 'Upload',
+            iconLeftName: 'upload',
+            onClick: fn(),
+            variant: 'secondary',
+            size: 'S',
+          }}
+        >
+          <p>Left icon — icon precedes the label.</p>
+        </Section>
+        <Section
+          title="External Link"
+          headingLevel={2}
+          headerButtonProps={{
+            children: 'Open',
+            iconRightName: 'external-link',
+            onClick: fn(),
+            variant: 'tertiary',
+            size: 'S',
+          }}
+        >
+          <p>Right icon — icon follows the label.</p>
+        </Section>
+        <Section
+          title="Attachments"
+          headingLevel={2}
+          headerButtonProps={{
+            iconLeftName: 'plus',
+            iconLeftScreenReaderText: 'Add attachment',
+            onClick: fn(),
+            variant: 'secondary',
+            size: 'S',
+          }}
+        >
+          <p>
+            Icon-only — omit
+            <code>children</code>
+            {' '}
+            and the button renders in compact icon-only mode. Always supply
+            <code>iconLeftScreenReaderText</code>
+            {' '}
+            for accessibility.
+          </p>
+        </Section>
+        <Section
+          title="Danger Zone"
+          headingLevel={2}
+          headerButtonProps={{
+            children: 'Delete',
+            iconLeftName: 'trash',
+            onClick: fn(),
+            variant: 'primary-destructive',
+            size: 'S',
+          }}
+        >
+          <p>
+            Destructive variant — use
+            <code>primary-destructive</code>
+            {' '}
+            or
+            <code>secondary-destructive</code>
+            {' '}
+            for irreversible actions.
+          </p>
+        </Section>
+        <Section
+          title="Locked Section"
+          headingLevel={2}
+          headerButtonProps={{
+            children: 'Edit',
+            iconLeftName: 'pencil',
+            onClick: fn(),
+            variant: 'secondary',
+            size: 'S',
+            disabled: true,
+          }}
+        >
+          <p>
+            Disabled — pass
+            <code>disabled: true</code>
+            {' '}
+            to prevent interaction while keeping the button visible.
+          </p>
+        </Section>
+      </>
+    ),
+  },
+  'All `ButtonProps` are forwarded through `headerButtonProps`. This story covers the main edge cases: left icon, right icon, icon-only, destructive variant, and disabled state.',
 );
 
 export const Collapsible: Story = withDescription(
@@ -586,10 +706,12 @@ function ContactSection() {
       title="Contact Information"
       headingLevel={2}
       collapsible
-      buttonText="Add contact"
-      buttonOnClick={() => openAddContactModal()}
-      buttonVariant="secondary"
-      buttonSize="S"
+      headerButtonProps={{
+        children: 'Add contact',
+        onClick: () => openAddContactModal(),
+        variant: 'secondary',
+        size: 'S',
+      }}
     >
       <p>Contact details here.</p>
     </Section>
@@ -605,10 +727,12 @@ export default ContactSection;
         title="Contact Information"
         headingLevel={2}
         collapsible
-        buttonText="Add contact"
-        buttonOnClick={fn()}
-        buttonVariant="secondary"
-        buttonSize="S"
+        headerButtonProps={{
+          children: 'Add contact',
+          onClick: fn(),
+          variant: 'secondary',
+          size: 'S',
+        }}
       >
         <p>
           A section can be both collapsible
@@ -637,10 +761,12 @@ function PupilDetailSection() {
     <Section
       title="Personal Details"
       headingLevel={2}
-      buttonText="Edit"
-      buttonOnClick={() => openEditModal()}
-      buttonVariant="secondary"
-      buttonSize="S"
+      headerButtonProps={{
+        children: 'Edit',
+        onClick: () => openEditModal(),
+        variant: 'secondary',
+        size: 'S',
+      }}
     >
       <Row label="Full name" value="Amara Osei-Bonsu" />
       <Row label="Date of birth" value="14 March 2009" note="Age 16" />
@@ -659,10 +785,12 @@ export default PupilDetailSection;
       <Section
         title="Personal Details"
         headingLevel={2}
-        buttonText="Edit"
-        buttonOnClick={fn()}
-        buttonVariant="secondary"
-        buttonSize="S"
+        headerButtonProps={{
+          children: 'Edit',
+          onClick: fn(),
+          variant: 'secondary',
+          size: 'S',
+        }}
       >
         <Row label="Full name" value="Amara Osei-Bonsu" />
         <Row label="Date of birth" value="14 March 2009" note="Age 16" />

package/src/components/section/Section.test.tsx

@@ -43,10 +43,12 @@ describe('Section component', () => {
     render(
       <Section
         title="Test Section"
-        buttonText="Click Me"
-        buttonOnClick={mockButtonClick}
-        buttonVariant="primary"
-        buttonSize="M"
+        headerButtonProps={{
+          children: 'Click Me',
+          onClick: mockButtonClick,
+          variant: 'primary',
+          size: 'M',
+        }}
       >
         <p>Section content</p>
       </Section>,
@@ -239,15 +241,19 @@ describe('Section component', () => {
         <Section
           title="Parent Section"
           collapsible
-          buttonText="Parent Action"
-          buttonOnClick={parentButtonClick}
+          headerButtonProps={{
+            children: 'Parent Action',
+            onClick: parentButtonClick,
+          }}
           titleIconName="info"
         >
           <p>Parent content</p>
           <Section
             title="Child Section"
-            buttonText="Child Action"
-            buttonOnClick={childButtonClick}
+            headerButtonProps={{
+              children: 'Child Action',
+              onClick: childButtonClick,
+            }}
             titleIconName="file"
           >
             <p>Child content</p>

package/src/components/section/Section.tsx

@@ -1,9 +1,9 @@
 import classNames from 'classnames';
-import { Button, type ButtonSize, type ButtonVariant } from 'Components/button/Button';
+import { Button, type ButtonProps } from 'Components/button/Button';
 import { Heading, type HeadingLevel } from 'Components/heading/Heading';
 import type { IconName } from 'Components/icon/allowedIcons';
 import { Icon } from 'Components/icon/Icon';
-import { useState, type HTMLAttributes, type MouseEventHandler } from 'react';
+import { useState, type HTMLAttributes } from 'react';
 import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
 
 type SectionProps = {
@@ -14,10 +14,7 @@ type SectionProps = {
   titleIconScreenReaderText?: string;
   collapsible?: boolean;
   collapsed?: boolean;
-  buttonText?: string;
-  buttonOnClick?: MouseEventHandler<HTMLButtonElement>;
-  buttonVariant?: ButtonVariant;
-  buttonSize?: ButtonSize;
+  headerButtonProps?: ButtonProps;
 } & HTMLAttributes<HTMLElement>;
 
 export const Section = (props: SectionProps) => {
@@ -31,10 +28,7 @@ export const Section = (props: SectionProps) => {
     titleIconScreenReaderText,
     collapsible = false,
     collapsed: initialCollapsed = false,
-    buttonText,
-    buttonOnClick,
-    buttonVariant,
-    buttonSize,
+    headerButtonProps,
   } = props;
 
   const [collapsed, setCollapsed] = useState(initialCollapsed);
@@ -90,13 +84,11 @@ export const Section = (props: SectionProps) => {
           )}
         </Heading.InnerContainer>
         <Heading.InnerContainer>
-          {buttonText && (
+          {headerButtonProps && (
             <Button
-              onClick={buttonOnClick}
-              variant={buttonVariant}
-              size={buttonSize}
+              {...headerButtonProps}
             >
-              {buttonText}
+              {headerButtonProps.children}
             </Button>
           )}
           {collapsible && (