@arbor-education/design-system.components 0.6.0 → 0.8.0

package/src/components/combobox/useVisibleChips.ts

@@ -0,0 +1,100 @@
+import { useMemo } from 'react';
+
+type ComputeTriggerLayoutModelParams = {
+  containerWidth: number;
+  chipWidths: number[];
+  chipGap: number;
+  badgeWidth: number;
+  ellipsisWidth: number;
+  showBadge: boolean;
+  safetyBuffer?: number;
+};
+
+export type TriggerLayoutModel = {
+  visibleChipIndices: number[];
+  hiddenChipCount: number;
+  showBadge: boolean;
+  showEllipsis: boolean;
+  hasOverflow: boolean;
+};
+
+const fitCount = (
+  availableWidth: number,
+  chipWidths: number[],
+  chipGap: number,
+): number => {
+  if (availableWidth <= 0 || chipWidths.length === 0) return 0;
+
+  let used = 0;
+  let count = 0;
+  for (let i = 0; i < chipWidths.length; i += 1) {
+    const required = chipWidths[i]! + (i > 0 ? chipGap : 0);
+    if (used + required > availableWidth) break;
+    used += required;
+    count += 1;
+  }
+  return count;
+};
+
+export const computeTriggerLayoutModel = ({
+  containerWidth,
+  chipWidths,
+  chipGap,
+  badgeWidth,
+  ellipsisWidth,
+  showBadge,
+  safetyBuffer = 1,
+}: ComputeTriggerLayoutModelParams): TriggerLayoutModel => {
+  const selectedCount = chipWidths.length;
+  const shouldShowBadge = showBadge && selectedCount > 0;
+
+  if (selectedCount === 0 || containerWidth <= 0) {
+    return {
+      visibleChipIndices: [],
+      hiddenChipCount: 0,
+      showBadge: shouldShowBadge,
+      showEllipsis: false,
+      hasOverflow: false,
+    };
+  }
+
+  const badgeReserve = shouldShowBadge
+    ? badgeWidth + chipGap
+    : 0;
+
+  const availableWithoutEllipsis = Math.max(0, containerWidth - badgeReserve - safetyBuffer);
+  const countWithoutEllipsis = fitCount(availableWithoutEllipsis, chipWidths, chipGap);
+  const hasOverflow = countWithoutEllipsis < selectedCount;
+
+  const ellipsisReserve = hasOverflow
+    ? ellipsisWidth + chipGap
+    : 0;
+  const availableForChips = Math.max(0, containerWidth - badgeReserve - ellipsisReserve - safetyBuffer);
+  const visibleCount = fitCount(availableForChips, chipWidths, chipGap);
+
+  return {
+    visibleChipIndices: Array.from({ length: visibleCount }, (_, index) => index),
+    hiddenChipCount: Math.max(0, selectedCount - visibleCount),
+    showBadge: shouldShowBadge,
+    showEllipsis: visibleCount < selectedCount,
+    hasOverflow: visibleCount < selectedCount,
+  };
+};
+
+type UseVisibleChipsParams = ComputeTriggerLayoutModelParams;
+
+export const useVisibleChips = (params: UseVisibleChipsParams): TriggerLayoutModel =>
+  // Deps list each field instead of `[params]`: callers often pass a new `params` object every
+  // render; depending on object identity would rerun the layout every time even when values are unchanged.
+  useMemo(
+    () => computeTriggerLayoutModel(params),
+    [
+      params.badgeWidth,
+      params.chipGap,
+      params.chipWidths,
+      params.containerWidth,
+      params.ellipsisWidth,
+      params.safetyBuffer,
+      params.showBadge,
+    ],
+  );

package/src/components/dot/Dot.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Dot } from './Dot';
+
+const meta: Meta<typeof Dot> = {
+  tags: ['autodocs'],
+  title: 'Components/Dot',
+  component: Dot,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Dot>;
+
+export const Purple: Story = { args: { colour: 'purple' } };
+export const Salmon: Story = { args: { colour: 'salmon' } };
+export const Teal: Story = { args: { colour: 'teal' } };
+export const Yellow: Story = { args: { colour: 'yellow' } };
+export const Green: Story = { args: { colour: 'green' } };
+export const Orange: Story = { args: { colour: 'orange' } };
+export const Blue: Story = { args: { colour: 'blue' } };
+
+export const Labeled: Story = {
+  args: {
+    colour: 'purple',
+    label: 'Priority indicator',
+  },
+};
+
+export const AllColours: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+      <Dot colour="purple" />
+      <Dot colour="salmon" />
+      <Dot colour="teal" />
+      <Dot colour="yellow" />
+      <Dot colour="green" />
+      <Dot colour="orange" />
+      <Dot colour="blue" />
+    </div>
+  ),
+};

package/src/components/dot/Dot.test.tsx

@@ -0,0 +1,21 @@
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { describe, expect, test } from 'vitest';
+import { Dot } from './Dot';
+
+describe('Dot', () => {
+  test('renders a dot with an explicit label', () => {
+    const { container } = render(<Dot colour="purple" label="Priority indicator" />);
+
+    expect(screen.getByLabelText('Priority indicator')).toBeInTheDocument();
+    expect(container.firstChild).toHaveClass('ds-dot', 'ds-dot--purple');
+  });
+
+  test('is decorative when label is not provided', () => {
+    const { container } = render(<Dot colour="teal" />);
+
+    expect(screen.queryByLabelText('teal dot')).not.toBeInTheDocument();
+    expect(container.firstChild).toHaveAttribute('aria-hidden', 'true');
+    expect(container.firstChild).not.toHaveAttribute('aria-label');
+  });
+});

package/src/components/dot/Dot.tsx

@@ -0,0 +1,18 @@
+import classNames from 'classnames';
+
+export type DotColour = 'purple' | 'salmon' | 'teal' | 'yellow' | 'green' | 'orange' | 'blue';
+
+type DotProps = {
+  colour: DotColour;
+  label?: string;
+};
+
+export const Dot = ({ colour, label }: DotProps): React.JSX.Element => {
+  return (
+    <span
+      aria-hidden={label ? undefined : 'true'}
+      aria-label={label}
+      className={classNames('ds-dot', `ds-dot--${colour}`)}
+    />
+  );
+};

package/src/components/dot/dot.scss

@@ -0,0 +1,35 @@
+.ds-dot {
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  flex-shrink: 0;
+
+  &--purple {
+    background-color: var(--color-extended-colours-purple-500);
+  }
+
+  &--salmon {
+    background-color: var(--color-extended-colours-salmon-500);
+  }
+
+  &--teal {
+    background-color: var(--color-extended-colours-teal-500);
+  }
+
+  &--yellow {
+    background-color: var(--color-extended-colours-yellow-500);
+  }
+
+  &--green {
+    background-color: var(--color-extended-colours-green-500);
+  }
+
+  &--orange {
+    background-color: var(--color-extended-colours-orange-500);
+  }
+
+  &--blue {
+    background-color: var(--color-extended-colours-blue-500);
+  }
+}

package/src/components/formField/FormField.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { fn } from 'storybook/test';
 
+import { comboboxPeopleOptions } from '../../mocks/comboboxStoryOptions';
 import { FormField } from './FormField';
 
 const meta: Meta<typeof FormField> = {
@@ -41,7 +42,7 @@ export const Default = {
     },
     'inputType': {
       control: 'select',
-      options: ['text', 'textarea', 'number', 'datePicker'],
+      options: ['text', 'textarea', 'number', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
       description: 'Input type',
     },
     'inputProps.size': {
@@ -130,6 +131,16 @@ export const FormExample: Story = {
           onSelectionChange: fn(),
         }}
       />
+      <FormField
+        id="assignee"
+        label="Assignee"
+        inputType="combobox"
+        inputProps={{
+          options: comboboxPeopleOptions,
+          placeholder: 'Search people...',
+          onValueChange: fn(),
+        }}
+      />
       <FormField
         id="date-of-birth"
         label="Date of Birth"
@@ -140,4 +151,22 @@ export const FormExample: Story = {
   ),
 };
 
+export const Combobox: Story = {
+  render: () => (
+    <div data-surface="base" data-colour-mode="light" className="bg-surface text-on-surface-default" style={{ padding: 32, maxWidth: 420 }}>
+      <FormField
+        id="form-field-combobox"
+        label="Assignee"
+        fieldDescription="Search and select a person."
+        inputType="combobox"
+        inputProps={{
+          options: comboboxPeopleOptions,
+          placeholder: 'Search people...',
+          onValueChange: fn(),
+        }}
+      />
+    </div>
+  ),
+};
+
 export default meta;

package/src/components/formField/FormField.test.tsx

@@ -62,4 +62,24 @@ describe('FormField component', () => {
     expect(screen.getByRole('textbox')).toBeInTheDocument();
     expect(screen.getByRole('button', { name: 'Open date picker' })).toBeInTheDocument();
   });
+
+  test('passes error state through to Combobox when errorText is provided', () => {
+    render(
+      <FormField
+        id="student-combobox"
+        label="Student"
+        inputType="combobox"
+        errorText="Choose a student"
+        inputProps={{
+          options: [{ value: 'alice', label: 'Alice Johnson' }],
+          placeholder: 'Search students',
+        }}
+      />,
+    );
+
+    const input = screen.getByRole('combobox', { name: 'Student' });
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+    expect(input.closest('.ds-combobox__trigger')).toHaveClass('ds-combobox__trigger--error');
+    expect(screen.getByText('Choose a student')).toBeInTheDocument();
+  });
 });

package/src/components/formField/FormField.tsx

@@ -1,12 +1,14 @@
 import classNames from 'classnames';
-import { Label } from './label/Label';
+import { Combobox } from 'Components/combobox/Combobox';
+import type { ComboboxProps } from 'Components/combobox/types';
+import { DatePicker, type DatePickerProps } from 'Components/datePicker/DatePicker';
 import { Icon } from '../icon/Icon';
-import { TextInput, type TextInputProps } from './inputs/text/TextInput';
-import { TextArea, type TextAreaProps } from './inputs/textArea/TextArea';
-import { NumberInput, type NumberInputProps } from './inputs/number/NumberInput';
 import { ColourPickerDropdown, type ColourPickerDropdownProps } from './inputs/colourPickerDropdown/ColourPickerDropdown';
+import { NumberInput, type NumberInputProps } from './inputs/number/NumberInput';
 import { SelectDropdown, type SelectDropdownInputProps } from './inputs/selectDropdown/SelectDropdown';
-import { DatePicker, type DatePickerProps } from 'Components/datePicker/DatePicker';
+import { TextInput, type TextInputProps } from './inputs/text/TextInput';
+import { TextArea, type TextAreaProps } from './inputs/textArea/TextArea';
+import { Label } from './label/Label';
 
 type FormFieldProps = {
   className?: string;
@@ -23,6 +25,7 @@ type FormFieldProps = {
   | { inputType?: 'colourPicker'; inputProps?: ColourPickerDropdownProps }
   | { inputType?: 'selectDropdown'; inputProps?: SelectDropdownInputProps }
   | { inputType?: 'datePicker'; inputProps?: DatePickerProps }
+  | { inputType?: 'combobox'; inputProps?: ComboboxProps }
 );
 
 export const FormField = (props: FormFieldProps) => {
@@ -71,6 +74,9 @@ export const FormField = (props: FormFieldProps) => {
       {inputType === 'datePicker' && (
         <DatePicker {...sharedProps} {...(inputProps as DatePickerProps)} />
       )}
+      {inputType === 'combobox' && (
+        <Combobox {...sharedProps} {...(inputProps as ComboboxProps)} />
+      )}
       {((helperLinkText && helperLinkUrl) || errorText) && (
         <div className="ds-form-field__message">
           {errorText && (

package/src/components/formField/inputs/number/numberInput.scss

@@ -1,10 +1,13 @@
+// Match single-line text field height (ds-input--M), not textarea / padded blocks.
 .ds-number-input__container {
   display: flex;
-  flex-wrap: wrap;
+  flex-wrap: nowrap;
   justify-content: center;
-  align-items: center;
-  padding: var(--form-field-spacing-vertical) var(--form-field-spacing-padding-x);
-  gap: var(--form-field-spacing-horizontal) var(--form-field-spacing-vertical-gap);
+  align-items: stretch;
+  box-sizing: border-box;
+  height: var(--form-field-text-medium-height);
+  padding: 0 var(--form-field-spacing-horizontal);
+  gap: var(--form-field-spacing-horizontal);
   border-radius: var(--form-field-radius);
   border: var(--border-weight) solid var(--form-field-text-placeholder-color-border);
   background: var(--form-field-text-placeholder-color-background);
@@ -40,6 +43,9 @@
     text-align: center;
     border: none;
     flex: 1;
+    min-width: 0;
+    min-height: 0;
+    height: 100%;
     padding: 0;
     color: var(--form-field-text-default-color-text);
 
@@ -50,11 +56,13 @@
 
   .ds-number-input__spinner-button {
     display: flex;
+    flex-shrink: 0;
     border: none;
     cursor: pointer;
     background: none;
     justify-content: center;
     align-items: center;
+    align-self: center;
     width: var(--icon-size-medium);
     height: var(--icon-size-medium);
     color: var(--form-field-icon-default-color-icon);

package/src/components/icon/allowedIcons.tsx

@@ -55,6 +55,7 @@ import {
   Link,
   List,
   ListFilterPlus,
+  LoaderCircle,
   Lock,
   LockOpen,
   LogOut, type LucideProps,
@@ -155,6 +156,7 @@ export const allowedIcons = {
   'link': Link,
   'list-filter-plus': ListFilterPlus,
   'list': List,
+  'loader': LoaderCircle,
   'lock-open': LockOpen,
   'lock': Lock,
   'log-out': LogOut,

package/src/components/pill/pill.scss

@@ -1,17 +1,15 @@
 .ds-pill {
   display: flex;
-  padding: var(--tag-spacing-vertical) var(--tag-spacing-horizontal);
+  padding: var(--pill-spacing-vertical) var(--pill-spacing-horizontal);
   align-items: center;
-  gap: var(--tag-spacing-gap-horizontal);
-  border-radius: var(--tag-radius);
+  gap: var(--pill-spacing-gap-horizontal);
+  border-radius: var(--pill-radius);
   border: 1px solid var(--pill-single-filter-default-color-border);
   flex-grow: 0;
   width: fit-content;
   cursor: pointer;
-
-  /* typography/body/p1-reg */
   font-style: normal;
-  line-height: 150%; /* 19.5px */
+  line-height: 150%;
 
   &__inactive{
     background-color: var(--pill-single-filter-default-color-background);

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

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Row } from './Row';
+
+const meta: Meta<typeof Row> = {
+  title: 'Components/Row',
+  component: Row,
+};
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'Label Text',
+    value: 'Value',
+    note: 'Note',
+  },
+};
+
+export const LabelOnly: Story = {
+  args: {
+    label: 'Full Name',
+  },
+};
+
+export const LabelAndValue: Story = {
+  args: {
+    label: 'Email Address',
+    value: 'jacob.black@forks.edu',
+  },
+};
+
+export const WithNote: Story = {
+  args: {
+    label: 'Date of Birth',
+    value: '13/01/1990',
+    note: 'Age 36',
+  },
+};
+
+export const Clickable: Story = {
+  args: {
+    label: 'View Profile',
+    value: 'Jacob Black',
+    onClick: () => { console.log('click!'); },
+  },
+};
+
+export const ClickableWithNote: Story = {
+  args: {
+    label: 'Attendance Record',
+    value: '96%',
+    note: 'Last updated today',
+    onClick: () => { console.log('click!'); },
+  },
+};
+
+export const WithCustomClassName: Story = {
+  args: {
+    label: 'Custom Styled',
+    value: 'With extra class',
+    className: 'custom-row-class',
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    label: 'A very long label that might wrap depending on the container width',
+    value: 'A very long value that contains lots of information and might also need to wrap',
+    note: 'This is a longer note with additional context',
+  },
+};
+
+export const MultipleRows: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
+      <Row label="First Name" value="Jacob" />
+      <Row label="Last Name" value="Black" />
+      <Row label="Year Group" value="Year 10" note="2024/2025" />
+      <Row label="Form Group" value="10A" />
+      <Row label="Attendance" value="96%" note="Above target" onClick={() => { console.log('click!'); }} />
+    </div>
+  ),
+};
+
+export default meta;

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

@@ -0,0 +1,82 @@
+import { expect, test, describe, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Row } from './Row';
+import '@testing-library/jest-dom/vitest';
+
+describe('Row component', () => {
+  test('renders with label, value, and note', () => {
+    render(<Row label="Full Name" value="Jacob Black" note="Team Jacob forever" />);
+
+    expect(screen.getByText('Full Name')).toBeInTheDocument();
+    expect(screen.getByText('Jacob Black')).toBeInTheDocument();
+    expect(screen.getByText('Team Jacob forever')).toBeInTheDocument();
+  });
+
+  test('renders with only a label', () => {
+    render(<Row label="Just a label" />);
+
+    expect(screen.getByText('Just a label')).toBeInTheDocument();
+  });
+
+  test('renders with only a value', () => {
+    render(<Row value="Just a value" />);
+
+    expect(screen.getByText('Just a value')).toBeInTheDocument();
+  });
+
+  test('renders with only a note', () => {
+    render(<Row note="Just a note" />);
+
+    expect(screen.getByText('Just a note')).toBeInTheDocument();
+  });
+
+  test('renders empty row without crashing', () => {
+    const { container } = render(<Row />);
+
+    expect(container.querySelector('.ds-row')).toBeInTheDocument();
+  });
+
+  test('applies custom className', () => {
+    const { container } = render(<Row className="custom-row" />);
+
+    const row = container.querySelector('.ds-row');
+    expect(row).toHaveClass('ds-row', 'custom-row');
+  });
+
+  describe('click behaviour', () => {
+    test('calls onClick handler when clicked', () => {
+      const handleClick = vi.fn();
+      const { container } = render(<Row label="Clickable" onClick={handleClick} />);
+
+      const row = container.querySelector('.ds-row')!;
+      fireEvent.click(row);
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('renders chevron icons when onClick is provided', () => {
+      const { container } = render(<Row label="Clickable" onClick={vi.fn()} />);
+
+      const icon = container.querySelector('.ds-row__icon-click');
+      expect(icon).toBeInTheDocument();
+    });
+
+    test('does not render chevron icons when onClick is not provided', () => {
+      const { container } = render(<Row label="Not clickable" />);
+
+      const icon = container.querySelector('.ds-row__icon-click');
+      expect(icon).not.toBeInTheDocument();
+    });
+
+    test('passes click event to handler', () => {
+      const handleClick = vi.fn();
+      const { container } = render(<Row onClick={handleClick} />);
+
+      const row = container.querySelector('.ds-row')!;
+      fireEvent.click(row);
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+      expect(handleClick.mock.calls[0]?.[0]).toBeDefined();
+    });
+  });
+});

package/src/components/row/Row.tsx

@@ -0,0 +1,54 @@
+import classNames from 'classnames';
+import { Icon } from 'Components/icon/Icon';
+import type { MouseEvent, MouseEventHandler } from 'react';
+import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
+
+export type RowProps = {
+  className?: string;
+  label?: string;
+  value?: string;
+  note?: string;
+  onClick?: MouseEventHandler<HTMLDivElement>;
+};
+
+export const Row = (props: RowProps) => {
+  const {
+    className,
+    label,
+    value,
+    note,
+    onClick,
+  } = props;
+
+  const isClickable = !!onClick;
+
+  return (
+    <div
+      className={classNames(
+        'ds-row',
+        {
+          'ds-row--clickable': isClickable,
+        },
+        className,
+      )}
+      onClick={onClick}
+      onKeyDown={(e) => {
+        if (isClickable && [ENTER_KEY, SPACE_KEY].includes(e.key)) {
+          e.preventDefault();
+          onClick(e as unknown as MouseEvent<HTMLDivElement>);
+        }
+      }}
+      tabIndex={isClickable ? 0 : -1}
+    >
+      <span className="ds-row__label">{label}</span>
+      <span className="ds-row__value">{value}</span>
+      <span className="ds-row__note">{note}</span>
+      {isClickable && (
+        <>
+          <Icon name="chevron-right" className="ds-row__icon-click" size={16} />
+          <Icon name="arrow-right" className="ds-row__icon-click" size={16} />
+        </>
+      )}
+    </div>
+  );
+};