@arbor-education/design-system.components 0.24.2 → 0.25.0

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 && (

package/src/components/table/Table.test.tsx

@@ -2038,7 +2038,7 @@ describe('Table', () => {
       // second tab should focus the button bypassing the cell
       await userEvent.tab();
       expect(focusFirstFocusableElementSpy).toHaveBeenCalledTimes(1);
-      const button = screen.getByText('Im a lovely button');
+      const button = screen.getByRole('button', { name: 'Im a lovely button' });
       expect(button).toHaveFocus();
     });
   });

package/src/components/table/table.scss

@@ -15,6 +15,23 @@
   }
 
   &__select-dropdown {
+    max-width: 100%;
+    min-width: 0;
+
+    .ds-button--dropdown {
+      max-width: 100%;
+      min-width: 0;
+      flex-shrink: 1;
+
+      .ds-button__content {
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        min-width: 0;
+        flex: 1;
+      }
+    }
+
     &--fill-cell {
       display: flex;
       width: 100%;