@arbor-education/design-system.components 0.6.0 → 0.7.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/singleUser/SingleUser.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { SingleUser } from './SingleUser';
+
+const meta: Meta<typeof SingleUser> = {
+  title: 'Components/SingleUser',
+  component: SingleUser,
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SingleUser>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+const sampleSrc = 'https://i.pravatar.cc/150?img=12';
+
+export const WithImage: Story = withDescription({
+  args: {
+    label: 'Jordan Matthews',
+    src: sampleSrc,
+  },
+}, 'Displays `SingleUser` with an avatar image and the default small layout.');
+
+export const WithInitials: Story = withDescription({
+  args: {
+    label: 'Riley Chen',
+    initials: 'RC',
+  },
+}, 'Uses initials when no image source is provided.');
+
+export const Placeholder: Story = withDescription({
+  args: {
+    label: 'Invited user',
+  },
+}, 'Shows the placeholder avatar treatment when neither image nor initials are supplied.');
+
+export const MediumAvatar: Story = withDescription({
+  name: 'Size override (medium)',
+  args: {
+    label: 'Taylor Brooks',
+    initials: 'TB',
+    size: 'medium',
+  },
+}, 'Demonstrates overriding the default avatar size within the SingleUser pill.');
+
+export const LongLabel: Story = withDescription({
+  args: {
+    label: 'Dr. Alexandrina Constantinopolous-Worthington',
+    initials: 'AC',
+  },
+}, 'Exercises the component with a longer label so text wrapping and spacing can be reviewed.');

package/src/components/singleUser/SingleUser.test.tsx

@@ -0,0 +1,61 @@
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { SingleUser } from './SingleUser';
+
+describe('SingleUser', () => {
+  test('renders label text', () => {
+    render(
+      <SingleUser
+        label="Jamie Smith"
+        initials="JS"
+      />,
+    );
+    expect(screen.getByText('Jamie Smith')).toBeInTheDocument();
+  });
+
+  test('hides Avatar from screen readers', () => {
+    const { container } = render(
+      <SingleUser
+        label="Pat Lee"
+        initials="PL"
+      />,
+    );
+    const avatar = container.querySelector('.ds-avatar');
+    expect(avatar).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  test('defaults Avatar to small size', () => {
+    const { container } = render(
+      <SingleUser
+        label="Sam"
+        initials="S"
+      />,
+    );
+    expect(container.querySelector('.ds-avatar--small')).toBeInTheDocument();
+  });
+
+  test('allows size override', () => {
+    const { container } = render(
+      <SingleUser
+        label="Sam"
+        initials="S"
+        size="medium"
+      />,
+    );
+    expect(container.querySelector('.ds-avatar--medium')).toBeInTheDocument();
+  });
+
+  test('applies className to root and avatarClassName to Avatar', () => {
+    const { container } = render(
+      <SingleUser
+        label="User"
+        initials="U"
+        className="my-chip"
+        avatarClassName="my-avatar"
+      />,
+    );
+    expect(container.querySelector('.ds-single-user.my-chip')).toBeInTheDocument();
+    expect(container.querySelector('.ds-avatar.my-avatar')).toBeInTheDocument();
+  });
+});

package/src/components/singleUser/SingleUser.tsx

@@ -0,0 +1,45 @@
+import classNames from 'classnames';
+import { Avatar, type AvatarProps, type AvatarSize } from 'Components/avatar/Avatar';
+import React from 'react';
+
+export type SingleUserProps = {
+  label: string;
+  className?: string;
+  avatarClassName?: string;
+  size?: AvatarSize;
+} & Omit<AvatarProps, 'className' | 'alt' | 'size'>;
+
+export const SingleUser = React.forwardRef<HTMLSpanElement, SingleUserProps>(
+  (
+    {
+      label,
+      className,
+      avatarClassName,
+      size = 'small',
+      ...avatarProps
+    },
+    ref,
+  ) => {
+    return (
+      <span
+        ref={ref}
+        className={classNames('ds-single-user', className)}
+      >
+
+        <Avatar
+          {...avatarProps}
+          size={size}
+          aria-hidden="true"
+          alt=""
+          className={avatarClassName}
+        />
+
+        <span className="ds-single-user__label">
+          {label}
+        </span>
+      </span>
+    );
+  },
+);
+
+SingleUser.displayName = 'SingleUser';

package/src/components/singleUser/singleUser.scss

@@ -0,0 +1,14 @@
+.ds-single-user {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--single-user-spacing-gap);
+  padding-block: 0;
+  padding-inline: 0 var(--single-user-spacing-padding-inline-end);
+  border-radius: var(--single-user-radius);
+  border: var(--single-user-border-width) solid var(--single-user-color-border);
+  background-color: var(--single-user-color-background);
+  color: var(--single-user-color-text);
+  font-size: var(--single-user-font-size);
+  line-height: var(--line-height-tight);
+}