@arbor-education/design-system.components 1.0.4 → 2.0.0

package/src/components/button/Button.test.tsx

@@ -1,5 +1,6 @@
 import { expect, test, describe, vi } from 'vitest';
 import { Button } from './Button.js';
+import { Icon } from 'Components/icon/Icon';
 import { render, screen, fireEvent } from '@testing-library/react';
 import '@testing-library/jest-dom/vitest';
 
@@ -9,29 +10,55 @@ describe('Button component', () => {
     expect(screen.getByText('Button Text')).toBeInTheDocument();
   });
 
-  test('renders button with a right icon', () => {
-    render(<Button iconRightName="info" iconRightScreenReaderText="the icon is here">Button Text</Button>);
+  test('renders button with an icon after the text', () => {
+    render(
+      <Button>
+        Button Text
+        <Icon name="info" screenReaderText="the icon is here" />
+      </Button>,
+    );
     expect(screen.getByText('the icon is here')).toBeInTheDocument();
     expect(screen.getByText('Button Text')).toBeInTheDocument();
   });
 
-  test('renders button with a left icon', () => {
-    render(<Button iconLeftName="info" iconLeftScreenReaderText="the icon is here">Button Text</Button>);
+  test('renders button with an icon before the text', () => {
+    render(
+      <Button>
+        <Icon name="info" screenReaderText="the icon is here" />
+        Button Text
+      </Button>,
+    );
     expect(screen.getByText('the icon is here')).toBeInTheDocument();
     expect(screen.getByText('Button Text')).toBeInTheDocument();
   });
 
-  test('renders button with a right icon and a left icon', () => {
-    render(<Button iconRightName="info" iconRightScreenReaderText="the right icon is here" iconLeftName="info" iconLeftScreenReaderText="the left icon is here">Button Text</Button>);
+  test('renders button with an icon before and after the text', () => {
+    render(
+      <Button>
+        <Icon name="info" screenReaderText="the left icon is here" />
+        Button Text
+        <Icon name="info" screenReaderText="the right icon is here" />
+      </Button>,
+    );
     expect(screen.getByText('the right icon is here')).toBeInTheDocument();
     expect(screen.getByText('the left icon is here')).toBeInTheDocument();
     expect(screen.getByText('Button Text')).toBeInTheDocument();
   });
 
-  test('applies icon only style if no children are provided', () => {
-    render(<Button iconRightName="info" iconRightScreenReaderText="the icon is here" />);
+  test('applies round style when isRound is set', () => {
+    render(
+      <Button isRound>
+        <Icon name="info" screenReaderText="the icon is here" />
+      </Button>,
+    );
     const button = screen.getByText('the icon is here').closest('button');
-    expect(button).toHaveClass('ds-button--icon-only');
+    expect(button).toHaveClass('ds-button--round');
+  });
+
+  test('does not apply round style by default', () => {
+    render(<Button>Button Text</Button>);
+    const button = screen.getByText('Button Text').closest('button');
+    expect(button).not.toHaveClass('ds-button--round');
   });
 
   test('applies primary style by default', () => {

package/src/components/button/Button.tsx

@@ -1,7 +1,5 @@
 import classNames from 'classnames';
 import React, { forwardRef, type ButtonHTMLAttributes, type PropsWithChildren } from 'react';
-import type { IconName } from 'Components/icon/allowedIcons';
-import { Icon } from 'Components/icon/Icon';
 
 export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'primary-destructive' | 'secondary-destructive' | 'text-link' | 'dropdown';
 
@@ -13,15 +11,12 @@ export type ButtonProps = {
   children?: React.ReactNode;
   className?: string;
   error?: boolean;
-  [key: string]: unknown;
+  [key: `data-${string}`]: unknown;
   hasHorizontalPadding?: boolean;
-  iconRightName?: IconName;
-  iconRightScreenReaderText?: string;
-  iconLeftName?: IconName;
-  iconLeftScreenReaderText?: string;
+  isRound?: boolean;
   borderless?: boolean;
   onClick?: (event: React.MouseEvent<HTMLButtonElement>, ...otherArgs: unknown[]) => void;
-} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type' | 'onClick'>;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'>;
 
 export const Button = forwardRef<HTMLButtonElement, PropsWithChildren<ButtonProps>>((props: ButtonProps, ref) => {
   const {
@@ -32,10 +27,7 @@ export const Button = forwardRef<HTMLButtonElement, PropsWithChildren<ButtonProp
     disabled = false,
     className = '',
     hasHorizontalPadding = true,
-    iconRightName,
-    iconRightScreenReaderText,
-    iconLeftName,
-    iconLeftScreenReaderText,
+    isRound = false,
     borderless = false,
     error = false,
     ...rest
@@ -49,7 +41,7 @@ export const Button = forwardRef<HTMLButtonElement, PropsWithChildren<ButtonProp
         {
           'ds-button--error': error,
           'ds-button--no-horizontal-padding': !hasHorizontalPadding,
-          'ds-button--icon-only': !children && (iconRightName || iconLeftName),
+          'ds-button--round': isRound,
           'ds-button--borderless': borderless,
         },
         className,
@@ -59,9 +51,7 @@ export const Button = forwardRef<HTMLButtonElement, PropsWithChildren<ButtonProp
       ref={ref}
       {...rest}
     >
-      {iconLeftName && <Icon name={iconLeftName} size={16} screenReaderText={iconLeftScreenReaderText || iconLeftName} />}
-      {children ? <span className="ds-button__content">{children}</span> : children}
-      {iconRightName && <Icon name={iconRightName} size={16} screenReaderText={iconRightScreenReaderText || iconRightName} />}
+      {children}
     </button>
   );
 });

package/src/components/button/button.scss

@@ -25,20 +25,20 @@
   // Button sizes
   &--M {
     height: var(--size-medium);
-  }
 
-  &--icon-only.ds-button--M  {
-    padding: 0;
-    width: var(--size-medium);
+    &.ds-button--round {
+      padding: 0;
+      width: var(--size-medium);
+    }
   }
 
   &--S {
     height: var(--size-small);
-  }
 
-  &--icon-only.ds-button--S {
-    padding: 0;
-    width: var(--size-small);
+    &.ds-button--round {
+      padding: 0;
+      width: var(--size-small);
+    }
   }
 
   // Button text

package/src/components/datePicker/DatePicker.tsx

@@ -1,5 +1,6 @@
 import classNames from 'classnames';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import { TextInput } from 'Components/formField/inputs/text/TextInput';
 import { Popover } from 'radix-ui';
 import {
@@ -201,9 +202,10 @@ export const DatePicker = (props: DatePickerProps) => {
           <Button
             className="ds-date-picker__button"
             variant="text-link"
-            iconLeftName="date"
-            iconLeftScreenReaderText="Open date picker"
-          />
+            isRound
+          >
+            <Icon name="date" screenReaderText="Open date picker" />
+          </Button>
         </Popover.Trigger>
         <Popover.Portal container={popupParentRef.current}>
           <Popover.Content

package/src/components/dateTimePicker/DateTimePicker.tsx

@@ -1,5 +1,6 @@
 import classNames from 'classnames';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import type { ComboboxSearchType } from 'Components/combobox/types';
 import {
   formatDateTimeInputValue,
@@ -275,9 +276,10 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
           <Button
             className="ds-date-time-picker__button"
             variant="text-link"
-            iconLeftName="date"
-            iconLeftScreenReaderText="Open date and time picker"
-          />
+            isRound
+          >
+            <Icon name="date" screenReaderText="Open date and time picker" />
+          </Button>
         </Popover.Trigger>
         <Popover.Portal container={popupParentRef.current}>
           <Popover.Content

package/src/components/dropdown/Dropdown.stories.tsx

@@ -881,7 +881,9 @@ export const WithIcons: Story = withDescription(
       <div style={{ padding: 'var(--spacing-xlarge)' }}>
         <Dropdown>
           <Dropdown.Trigger>
-            <Button variant="secondary" iconRightName="3-dot" iconRightScreenReaderText="More actions" hasHorizontalPadding={false} />
+            <Button variant="secondary" isRound hasHorizontalPadding={false}>
+              <Icon name="3-dot" screenReaderText="More actions" />
+            </Button>
           </Dropdown.Trigger>
           <Dropdown.Content>
             <Dropdown.Item onSelect={() => console.log('view')}>
@@ -915,7 +917,9 @@ function IconItemsDropdown() {
   return (
     <Dropdown>
       <Dropdown.Trigger>
-        <Button variant="secondary" iconRightName="3-dot" iconRightScreenReaderText="More actions" hasHorizontalPadding={false} />
+        <Button variant="secondary" isRound hasHorizontalPadding={false}>
+          <Icon name="3-dot" screenReaderText="More actions" />
+        </Button>
       </Dropdown.Trigger>
       <Dropdown.Content>
         <Dropdown.Item onSelect={() => console.log('view')}>
@@ -945,7 +949,7 @@ export default IconItemsDropdown;`,
       },
     },
   },
-  'Icons inside `Dropdown.Item` children align automatically via the item\'s flex layout (`gap` + `align-items: center`). Use `size={16}` to match the item\'s line height. The trigger here uses an icon-only `Button` with `iconRightName="3-dot"` — the classic "more actions" kebab pattern used throughout Arbor\'s table rows. Always provide `iconRightScreenReaderText` so screen reader users know what the button does.',
+  'Icons inside `Dropdown.Item` children align automatically via the item\'s flex layout (`gap` + `align-items: center`). Use `size={16}` to match the item\'s line height. The trigger here uses an icon-only `Button` with `isRound` and a child `Icon` — the classic "more actions" kebab pattern used throughout Arbor\'s table rows. Always pass `screenReaderText` on that `Icon` so screen reader users know what the button does.',
 );
 
 export const WithDestructiveAction: Story = withDescription(

package/src/components/emptyState/EmptyState.stories.tsx

@@ -208,7 +208,8 @@ const TertiaryActionTemplate = () => (
     subHeading="Start by adding the content and data blocks you want to see here."
     orientation="vertical"
     actions={(
-      <Button type="button" variant="text-link" iconLeftName="plus">
+      <Button type="button" variant="text-link">
+        <Icon name="plus" />
         Add
       </Button>
     )}
@@ -353,7 +354,8 @@ function EmptyStateTertiaryActionExample() {
       subHeading="Start by adding the content and data blocks you want to see here."
       orientation="vertical"
       actions={
-        <Button type="button" variant="text-link" iconLeftName="plus">
+        <Button type="button" variant="text-link">
+          <Icon name="plus" />
           Add
         </Button>
       }

package/src/components/fileUpload/FileUpload.test.tsx

@@ -70,7 +70,7 @@ describe('FileUpload', () => {
         <FileUpload uploadedFiles={[{ ...baseFile, onDelete }]} uploadFiles={vi.fn()} />,
       );
 
-      await userEvent.click(screen.getByRole('button', { name: 'trash' }));
+      await userEvent.click(screen.getByRole('button', { name: 'Delete file' }));
       expect(onDelete).toHaveBeenCalledOnce();
     });
 
@@ -81,12 +81,12 @@ describe('FileUpload', () => {
           uploadFiles={vi.fn()}
         />,
       );
-      expect(screen.getByRole('button', { name: 'download' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Download file' })).toBeInTheDocument();
     });
 
     test('does not render download button when onDownload is not provided', () => {
       render(<FileUpload uploadedFiles={[baseFile]} uploadFiles={vi.fn()} />);
-      expect(screen.queryByRole('button', { name: 'download' })).not.toBeInTheDocument();
+      expect(screen.queryByRole('button', { name: 'Download file' })).not.toBeInTheDocument();
     });
 
     test('calls onDownload when download button is clicked', async () => {
@@ -98,7 +98,7 @@ describe('FileUpload', () => {
         />,
       );
 
-      await userEvent.click(screen.getByRole('button', { name: 'download' }));
+      await userEvent.click(screen.getByRole('button', { name: 'Download file' }));
       expect(onDownload).toHaveBeenCalledOnce();
     });
   });

package/src/components/fileUpload/FileUpload.tsx

@@ -111,16 +111,20 @@ export const FileUpload = (props: FileUploadProps) => {
                   {onDownload && (
                     <Button
                       variant="secondary"
-                      iconLeftName="download"
+                      isRound
                       onClick={onDownload}
-                    />
+                    >
+                      <Icon name="download" screenReaderText="Download file" />
+                    </Button>
                   )}
                   {onDelete && (
                     <Button
                       variant="secondary"
-                      iconLeftName="trash"
+                      isRound
                       onClick={onDelete}
-                    />
+                    >
+                      <Icon name="trash" screenReaderText="Delete file" />
+                    </Button>
                   )}
                 </span>
                 {typeof progressPercentage === 'number' && progressPercentage < 100

package/src/components/formField/inputs/colourPickerDropdown/ColourPickerDropdown.tsx

@@ -1,5 +1,6 @@
 import { Dropdown } from 'Components/dropdown/Dropdown';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import { Sketch } from '@uiw/react-color';
 import type { ColorResult } from '@uiw/color-convert';
 import { useEffect, useState } from 'react';
@@ -31,7 +32,7 @@ export const ColourPickerDropdown = ({ value = '#3cad51', onChange, hasError, di
       <input type="hidden" name={id} value={selectedColour} />
       <Dropdown>
         <Dropdown.Trigger disabled={disabled} className="ds-colour-picker-dropdown__trigger">
-          <Button variant="dropdown" iconRightName="chevron-down" error={hasError} id={id} aria-describedby={ariaDescribedBy} aria-invalid={ariaInvalid}>
+          <Button variant="dropdown" error={hasError} id={id} aria-describedby={ariaDescribedBy} aria-invalid={ariaInvalid}>
             <span className="sr-only">
               Toggle colour picker.
             </span>
@@ -42,6 +43,7 @@ export const ColourPickerDropdown = ({ value = '#3cad51', onChange, hasError, di
                 {selectedColour}
               </span>
             </div>
+            <Icon name="chevron-down" />
           </Button>
         </Dropdown.Trigger>
         <Dropdown.Content className="ds-colour-picker-dropdown__content">

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

@@ -4,6 +4,7 @@ import classNames from 'classnames';
 import { SelectDropdownItem, type SelectDropdownItemProps } from './items/item/SelectDropdownItem.js';
 import { Dropdown } from 'Components/dropdown/Dropdown';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 
 export type SelectDropdownInputProps = {
   'placeholder'?: string;
@@ -115,13 +116,13 @@ export const SelectDropdown = (props: SelectDropdownInputProps) => {
           <Button
             variant="dropdown"
             error={hasError}
-            iconRightName="chevron-down"
             id={id}
             aria-describedby={ariaDescribedBy}
             aria-invalid={ariaInvalid}
             className={classNames({ 'ds-select-dropdown--icon-click-only': iconClickOnly })}
           >
-            {renderedSelectContent}
+            <span className="ds-button__content">{renderedSelectContent}</span>
+            <Icon name="chevron-down" />
           </Button>
         </Dropdown.Trigger>
         <Dropdown.Content contentProps={{ onCloseAutoFocus }}>

package/src/components/grid/Grid.stories.tsx

@@ -13,6 +13,7 @@ import { Grid } from './Grid.js';
 import { Avatar } from 'Components/avatar/Avatar';
 import { Badge } from 'Components/badge/Badge';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import { DataViewCard } from 'Components/dataViewCard/DataViewCard';
 import { Heading } from 'Components/heading/Heading';
 import { KPICard } from 'Components/kpiCard/KPICard';
@@ -803,8 +804,14 @@ export const StudentProfilePage: Story = withDescription(
                 </div>
               </div>
               <div style={actionRowStyle}>
-                <Button variant="secondary" size="S" iconLeftName="pencil">Edit</Button>
-                <Button variant="secondary" size="S" iconLeftName="file">Print</Button>
+                <Button variant="secondary" size="S">
+                  <Icon name="pencil" />
+                  Edit
+                </Button>
+                <Button variant="secondary" size="S">
+                  <Icon name="file" />
+                  Print
+                </Button>
                 <Button variant="primary" size="S">Contact Home</Button>
               </div>
             </div>
@@ -911,7 +918,10 @@ export const AttendanceDashboard: Story = withDescription(
                 </div>
               </div>
               <div style={actionRowStyle}>
-                <Button variant="secondary" size="S" iconLeftName="download">Export</Button>
+                <Button variant="secondary" size="S">
+                  <Icon name="download" />
+                  Export
+                </Button>
                 <Button variant="primary" size="S">Generate Report</Button>
               </div>
             </div>
@@ -1024,7 +1034,10 @@ export const StaffDirectory: Story = withDescription(
                 <Heading level={1}>Staff Directory</Heading>
                 <Badge colour="blue">24 staff</Badge>
               </div>
-              <Button variant="primary" size="S" iconLeftName="plus">Add Staff Member</Button>
+              <Button variant="primary" size="S">
+                <Icon name="plus" />
+                Add Staff Member
+              </Button>
             </div>
           </Grid.Column>
         </Grid.Row>

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

@@ -10,6 +10,7 @@ import {
 } from '@storybook/addon-docs/blocks';
 import { Heading } from './Heading.js';
 import { Button } from 'Components/button/Button';
+import { Icon } from 'Components/icon/Icon';
 import { EditableText } from 'Components/editableText/EditableText';
 import { TooltipWrapper } from 'Components/tooltip/TooltipWrapper';
 
@@ -141,7 +142,7 @@ const DEVELOPER_NOTES = [
   '- **Keyboard order** — the DOM order is left container then right container, matching reading order and Tab sequence',
   '- **Icon-only buttons in the heading** require a `TooltipWrapper` with an accessible label. A tooltip',
   '  on hover alone is not sufficient — it must also appear on keyboard focus, and assistive technology',
-  '  must be able to read the label. Always pair `iconRightScreenReaderText` with `TooltipWrapper`.',
+  '  must be able to read the label. Always pair a `screenReaderText` on the child `Icon` with `TooltipWrapper`.',
   '- **`id` + `aria-labelledby`** — give the heading an `id` and reference it from an adjacent',
   '  `<section aria-labelledby="...">` to associate the landmark with its heading. Screen readers',
   '  announce the section name when the user enters the landmark region.',
@@ -339,9 +340,10 @@ const WithIconOnlyActionTemplate = () => (
           <Button
             variant="secondary"
             type="button"
-            iconRightName="download"
-            iconRightScreenReaderText="Download student records"
-          />
+            isRound
+          >
+            <Icon name="download" screenReaderText="Download student records" />
+          </Button>
         </TooltipWrapper>
       </Heading.InnerContainer>
     </Heading>
@@ -352,7 +354,8 @@ const WithBackControlLegacyTemplate = () => (
   <div style={{ padding: 'var(--spacing-xlarge)' }}>
     <Heading level={1}>
       <Heading.InnerContainer className="medium-spacing-gap">
-        <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+        <Button variant="tertiary" type="button">
+          <Icon name="chevron-left" />
           Back
         </Button>
         Attendance register
@@ -396,7 +399,8 @@ const WithEditableTitleAndMultipleActionsTemplate = () => (
   <div style={{ padding: 'var(--spacing-xlarge)' }}>
     <Heading level={1}>
       <Heading.InnerContainer className="medium-spacing-gap">
-        <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+        <Button variant="tertiary" type="button">
+          <Icon name="chevron-left" />
           Back
         </Button>
         <EditableText
@@ -578,7 +582,7 @@ export const WithIconOnlyAction: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Heading, Button, TooltipWrapper } from '@arbor-education/design-system.components';
+import { Heading, Button, Icon, TooltipWrapper } from '@arbor-education/design-system.components';
 
 <div style={{ padding: 'var(--spacing-xlarge)' }}>
   <Heading level={1}>
@@ -588,9 +592,10 @@ import { Heading, Button, TooltipWrapper } from '@arbor-education/design-system.
         <Button
           variant="secondary"
           type="button"
-          iconRightName="download"
-          iconRightScreenReaderText="Download student records"
-        />
+          isRound
+        >
+          <Icon name="download" screenReaderText="Download student records" />
+        </Button>
       </TooltipWrapper>
     </Heading.InnerContainer>
   </Heading>
@@ -604,8 +609,8 @@ import { Heading, Button, TooltipWrapper } from '@arbor-education/design-system.
     'Title left, an icon-only action button right. **Icon-only buttons in a heading require a `TooltipWrapper`**',
     '— hover tooltips alone are not sufficient. The tooltip must appear on keyboard focus too, and assistive',
     'technology must be able to read the label. Always pair `TooltipWrapper` with a descriptive',
-    '`iconRightScreenReaderText` prop on the button. This story uses both: `tooltipContent="Download student records"`',
-    'for sighted keyboard users and `iconRightScreenReaderText="Download student records"` for screen reader users.',
+    '`screenReaderText` on the child `Icon`. This story uses both: `tooltipContent="Download student records"`',
+    'for sighted keyboard users and `screenReaderText="Download student records"` for screen reader users.',
   ].join(' '),
 );
 
@@ -617,12 +622,13 @@ export const WithBackControlLegacy: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Heading, Button } from '@arbor-education/design-system.components';
+import { Heading, Button, Icon } from '@arbor-education/design-system.components';
 
 <div style={{ padding: 'var(--spacing-xlarge)' }}>
   <Heading level={1}>
     <Heading.InnerContainer className="medium-spacing-gap">
-      <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+      <Button variant="tertiary" type="button">
+        <Icon name="chevron-left" />
         Back
       </Button>
       Attendance register
@@ -709,12 +715,13 @@ export const WithEditableTitleAndMultipleActions: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Heading, Button, EditableText } from '@arbor-education/design-system.components';
+import { Heading, Button, Icon, EditableText } from '@arbor-education/design-system.components';
 
 <div style={{ padding: 'var(--spacing-xlarge)' }}>
   <Heading level={1}>
     <Heading.InnerContainer className="medium-spacing-gap">
-      <Button variant="tertiary" type="button" iconLeftName="chevron-left" iconLeftScreenReaderText="Go back">
+      <Button variant="tertiary" type="button">
+        <Icon name="chevron-left" />
         Back
       </Button>
       <EditableText text="Autumn term report" onEditSave={() => {}} />