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

package/src/components/badge/Badge.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Badge, type BadgeColour } from './Badge';
+
+const colours: BadgeColour[] = [
+  'purple',
+  'salmon',
+  'teal',
+  'yellow',
+  'green',
+  'orange',
+  'blue',
+];
+
+const meta: Meta<typeof Badge> = {
+  tags: ['autodocs'],
+  title: 'Components/Badge',
+  component: Badge,
+  argTypes: {
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    colour: { control: 'select', options: [undefined, ...colours] },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Badge>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+export const Count: Story = withDescription({
+  args: {
+    children: '3',
+  },
+}, 'Shows the default numeric Badge used for counts and status totals.');
+
+export const WithA11yLabel: Story = withDescription({
+  args: {
+    children: '3',
+    a11yLabel: '3 selected items',
+  },
+}, 'Adds an accessible label when the visual content alone is not descriptive enough.');
+
+export const Sizes: Story = withDescription({
+  render: () => (
+    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
+      <Badge size="sm">1</Badge>
+      <Badge size="md">2</Badge>
+      <Badge size="lg">3</Badge>
+    </div>
+  ),
+}, 'Compares the small, medium, and large Badge size variants.');
+
+export const Colours: Story = withDescription({
+  render: () => (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>
+      {colours.map(c => (
+        <Badge key={c} colour={c} size="md">
+          {c.slice(0, 1).toUpperCase()}
+        </Badge>
+      ))}
+    </div>
+  ),
+}, 'Displays each available Badge colour variant side by side.');

package/src/components/badge/Badge.test.tsx

@@ -0,0 +1,28 @@
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { describe, expect, test } from 'vitest';
+import { Badge } from './Badge';
+
+describe('Badge', () => {
+  test('renders children text when no a11yLabel is provided', () => {
+    render(<Badge>3</Badge>);
+    expect(screen.getByText('3')).toBeInTheDocument();
+  });
+
+  test('uses aria-label and hides visible children from assistive tech when a11yLabel is provided', () => {
+    render(<Badge a11yLabel="3 selected items">3</Badge>);
+    const badge = screen.getByLabelText('3 selected items');
+    expect(badge).toBeInTheDocument();
+    expect(screen.getByText('3')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  test('applies size and colour modifier classes', () => {
+    const { container } = render(
+      <Badge size="sm" colour="salmon">
+        2
+      </Badge>,
+    );
+    const el = container.firstChild as HTMLElement;
+    expect(el).toHaveClass('ds-badge--size-sm', 'ds-badge--salmon');
+  });
+});

package/src/components/badge/Badge.tsx

@@ -0,0 +1,35 @@
+import classNames from 'classnames';
+import type { DotColour } from 'Components/dot/Dot';
+
+export type BadgeSize = 'sm' | 'md' | 'lg';
+export type BadgeColour = DotColour;
+
+export type BadgeProps = {
+  children: React.ReactNode;
+  a11yLabel?: string;
+  className?: string;
+  size?: BadgeSize;
+  colour?: BadgeColour;
+};
+
+export const Badge = ({
+  children,
+  a11yLabel,
+  className,
+  size = 'md',
+  colour,
+}: BadgeProps): React.JSX.Element => {
+  return (
+    <span
+      className={classNames(
+        'ds-badge',
+        `ds-badge--size-${size}`,
+        colour && `ds-badge--${colour}`,
+        className,
+      )}
+      aria-label={a11yLabel}
+    >
+      {a11yLabel ? <span aria-hidden="true">{children}</span> : children}
+    </span>
+  );
+};

package/src/components/badge/badge.scss

@@ -0,0 +1,86 @@
+.ds-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  box-sizing: border-box;
+
+  --ds-badge-background: var(--color-grey-800);
+  --ds-badge-color: var(--color-mono-white);
+  --ds-badge-min-width: var(--badge-medium-size);
+  --ds-badge-height: var(--badge-medium-size);
+  --ds-badge-padding-inline: var(--badge-medium-spacing-horizontal);
+  --ds-badge-font-size: var(--badge-medium-font-size);
+  --ds-badge-font-weight: var(--badge-font-weight);
+  --ds-badge-line-height: 1;
+  --ds-badge-border-radius: var(--badge-medium-radius);
+
+  min-width: var(--ds-badge-min-width);
+  height: var(--ds-badge-height);
+  padding: 0 var(--ds-badge-padding-inline);
+  border-radius: var(--ds-badge-border-radius);
+  background: var(--ds-badge-background);
+  color: var(--ds-badge-color);
+  font-size: var(--ds-badge-font-size);
+  font-weight: var(--ds-badge-font-weight);
+  line-height: var(--ds-badge-line-height);
+
+  &--size-sm {
+    --ds-badge-min-width: var(--badge-small-size);
+    --ds-badge-height: var(--badge-small-size);
+    --ds-badge-padding-inline: var(--badge-small-spacing-horizontal);
+    --ds-badge-font-size: var(--badge-small-font-size);
+    --ds-badge-border-radius: var(--badge-small-radius);
+  }
+
+  &--size-md {
+    --ds-badge-min-width: var(--badge-medium-size);
+    --ds-badge-height: var(--badge-medium-size);
+    --ds-badge-padding-inline: var(--badge-medium-spacing-horizontal);
+    --ds-badge-font-size: var(--badge-medium-font-size);
+    --ds-badge-border-radius: var(--badge-medium-radius);
+  }
+
+  &--size-lg {
+    --ds-badge-min-width: var(--badge-large-size);
+    --ds-badge-height: var(--badge-large-size);
+    --ds-badge-padding-inline: var(--badge-large-spacing-horizontal);
+    --ds-badge-font-size: var(--badge-large-font-size);
+    --ds-badge-border-radius: var(--badge-large-radius);
+  }
+
+  &--purple {
+    --ds-badge-background: var(--color-extended-colours-purple-500);
+    --ds-badge-color: var(--color-extended-colours-purple-800);
+  }
+
+  &--salmon {
+    --ds-badge-background: var(--color-extended-colours-salmon-500);
+    --ds-badge-color: var(--color-mono-white);
+  }
+
+  &--teal {
+    --ds-badge-background: var(--color-extended-colours-teal-500);
+    --ds-badge-color: var(--color-extended-colours-teal-800);
+  }
+
+  &--yellow {
+    --ds-badge-background: var(--color-extended-colours-yellow-500);
+    --ds-badge-color: var(--color-extended-colours-yellow-800);
+  }
+
+  &--green {
+    --ds-badge-background: var(--color-extended-colours-green-500);
+    --ds-badge-color: var(--color-mono-white);
+  }
+
+  &--orange {
+    --ds-badge-background: var(--color-extended-colours-orange-500);
+    --ds-badge-color: var(--color-extended-colours-orange-800);
+  }
+
+  &--blue {
+    --ds-badge-background: var(--color-extended-colours-blue-500);
+    --ds-badge-color: var(--color-extended-colours-blue-800);
+  }
+}

package/src/components/card/Card.tsx

@@ -79,7 +79,7 @@ export const Card = ({
             </span>
           )}
           {paragraph && <p className="ds-card__paragraph">{paragraph}</p>}
-          {tagText && <Tag text={tagText} color={tagColor} />}
+          {tagText && <Tag color={tagColor}>{tagText}</Tag>}
         </div>
         {isCardClickable && (
           <>

package/src/components/combobox/Combobox.stories.tsx

@@ -0,0 +1,340 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useRef, useState } from 'react';
+import {
+  comboboxAsyncSearchOptions,
+  comboboxGroupedPeopleOptions,
+  comboboxPeopleOptions,
+} from '../../mocks/comboboxStoryOptions';
+import { Combobox } from './Combobox';
+import type { ComboboxOption, ComboboxProps } from './types';
+
+const meta: Meta<typeof Combobox> = {
+  title: 'Components/Combobox',
+  component: Combobox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Default usage is `<Combobox … />` with props such as `triggerVariant` and `multiple`. `Combobox.Trigger`, `Combobox.ButtonTrigger`, and `Combobox.Listbox` are composition escape hatches.',
+      },
+    },
+  },
+  argTypes: {
+    dropdownOnFocus: {
+      control: 'boolean',
+      description: 'When true, focusing the input opens the dropdown if there are items to show.',
+    },
+    showDropdownTrigger: {
+      control: 'boolean',
+      description: 'When true, shows the chevron trigger button.',
+    },
+    triggerVariant: {
+      control: 'inline-radio',
+      options: ['input', 'button'],
+      description: 'Choose trigger style: input-in-trigger or button-style summary trigger.',
+    },
+  },
+  decorators: [
+    Story => (
+      <div data-surface="base" data-colour-mode="light" className="bg-surface text-on-surface-default" style={{ padding: 32, maxWidth: 420 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Combobox>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+/** Enough rows to exceed `.ds-combobox__listbox` max-height so keyboard nav scrolls. */
+const manyScrollableOptions: ComboboxOption[] = Array.from({ length: 45 }, (_, i) => ({
+  value: `scroll-demo-${i + 1}`,
+  label: `Option ${i + 1}`,
+  iconName: 'user',
+}));
+
+export const ScrollableLongList: Story = withDescription({
+  args: {
+    options: manyScrollableOptions,
+    placeholder: 'Open the list and move with arrow keys…',
+  },
+}, 'Exercises a scrollable listbox with enough items to validate keyboard navigation and active-row scrolling.');
+
+export const ButtonTriggerSingleSelect: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    placeholder: 'Students',
+    triggerVariant: 'button',
+  },
+}, 'Shows the button-style trigger in single-select mode before the search input moves into the popover.');
+
+export const ButtonTriggerMultiSelect: Story = withDescription({
+  args: {
+    options: manyScrollableOptions,
+    defaultValue: ['scroll-demo-1', 'scroll-demo-2', 'scroll-demo-3'],
+    placeholder: 'Students',
+    multiple: true,
+    triggerVariant: 'button',
+  },
+}, 'Demonstrates the button trigger variant with multiple selected chips and the selection count badge.');
+
+export const SingleSelect: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    placeholder: 'Search people...',
+  },
+}, 'Basic single-select Combobox with built-in client-side prefix matching.');
+
+export const SubstringSearch: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    placeholder: 'Search people...',
+    searchType: 'substring',
+  },
+}, 'Switches the built-in matching mode from prefix search to substring search.');
+
+export const HighlightedMatches: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    placeholder: 'Search people...',
+    searchType: 'substring',
+    highlightStringMatches: true,
+  },
+}, 'Highlights the matched portions of each option while using substring filtering.');
+
+export const MultiSelect: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    multiple: true,
+    placeholder: 'Search people...',
+    showClearAll: true,
+  },
+}, 'Basic multi-select Combobox with removable chips and a clear-all action.');
+
+export const WithDefaultValue: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    multiple: true,
+    defaultValue: ['alice', 'bob', 'charlie'],
+    placeholder: 'Search people...',
+    showClearAll: true,
+  },
+}, 'Starts with preselected values so chip rendering and removal can be reviewed immediately.');
+
+export const WithGroups: Story = withDescription({
+  args: {
+    options: comboboxGroupedPeopleOptions,
+    multiple: true,
+    placeholder: 'Search people...',
+  },
+}, 'Shows grouped options in the dropdown while keeping the same multi-select interaction model.');
+
+export const Disabled: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    disabled: true,
+    defaultValue: ['alice'],
+    placeholder: 'Search people...',
+  },
+}, 'Displays the disabled state with an existing selected value.');
+
+export const HiddenTrigger: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    placeholder: 'Search people...',
+    showDropdownTrigger: false,
+  },
+}, 'Hides the chevron trigger while keeping focus, typing, and keyboard opening behavior.');
+
+export const ManualOpenOnFocus: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    placeholder: 'Search people...',
+    dropdownOnFocus: false,
+  },
+}, 'Disables focus-open so the list appears only after typing or explicit keyboard interaction.');
+
+export const CustomOptionLayout: Story = withDescription({
+  args: {
+    options: comboboxPeopleOptions,
+    placeholder: 'Search people...',
+    multiple: true,
+    renderOption: (option, selected) => (
+      <>
+        <span aria-hidden="true">
+          <input type="checkbox" checked={selected} readOnly tabIndex={-1} />
+        </span>
+        <span className="ds-combobox__option-label">{option.label}</span>
+      </>
+    ),
+  },
+}, 'Uses `renderOption` to swap the row content while the Combobox still owns selection and listbox behavior.');
+
+const delay = (ms: number) => new Promise<void>((resolve) => {
+  setTimeout(resolve, ms);
+});
+
+async function searchPeople(query: string): Promise<ComboboxOption[]> {
+  await delay(700);
+  const q = query.trim().toLowerCase();
+  if (!q) return comboboxAsyncSearchOptions;
+  return comboboxAsyncSearchOptions.filter(p => p.label.toLowerCase().includes(q));
+}
+
+type AsyncSearchTemplateProps = Pick<
+  ComboboxProps,
+  'allowCreate' | 'searchType' | 'highlightStringMatches'
+>;
+
+const AsyncSearchTemplate = ({
+  allowCreate = false,
+  searchType = 'substring',
+  highlightStringMatches = true,
+}: AsyncSearchTemplateProps) => {
+  const [options, setOptions] = useState<ComboboxOption[]>([]);
+  const [loading, setLoading] = useState(false);
+  const requestIdRef = useRef(0);
+
+  const handleSearch = (query: string) => {
+    const id = ++requestIdRef.current;
+    setLoading(true);
+    void searchPeople(query).then((next) => {
+      if (id !== requestIdRef.current) return;
+      setOptions(next);
+      setLoading(false);
+    });
+  };
+
+  return (
+    <Combobox
+      options={options}
+      multiple
+      placeholder="Type to search..."
+      loading={loading}
+      allowCreate={allowCreate}
+      searchType={searchType}
+      highlightStringMatches={highlightStringMatches}
+      onSearch={handleSearch}
+    />
+  );
+};
+
+export const AsyncSearch: Story = withDescription({
+  args: {
+    allowCreate: false,
+    searchType: 'substring',
+    highlightStringMatches: true,
+  },
+  render: args => (
+    <AsyncSearchTemplate
+      allowCreate={args.allowCreate}
+      searchType={args.searchType}
+      highlightStringMatches={args.highlightStringMatches}
+    />
+  ),
+}, 'Simulates async search results with local data so loading, filtering, and optional create flows can be reviewed.');
+
+const CreateNewTemplate = () => {
+  const [options, setOptions] = useState<ComboboxOption[]>(comboboxPeopleOptions);
+
+  const handleCreate = (name: string) => {
+    const newOpt: ComboboxOption = {
+      value: name.toLowerCase().replace(/\s/g, '-'),
+      label: name,
+      iconName: 'user',
+    };
+    setOptions(prev => [...prev, newOpt]);
+    return newOpt;
+  };
+
+  const handleDelete = (value: string) => {
+    setOptions(prev => prev.filter(opt => opt.value !== value));
+  };
+
+  return (
+    <Combobox
+      options={options}
+      multiple
+      placeholder="Search or create..."
+      allowCreate
+      onCreateNew={handleCreate}
+      onDeleteCreated={handleDelete}
+    />
+  );
+};
+
+export const CreateNew: Story = withDescription({
+  render: () => <CreateNewTemplate />,
+}, 'Demonstrates multi-select creation and deletion of user-added options.');
+
+const SingleSelectCreateTemplate = () => {
+  const [options, setOptions] = useState<ComboboxOption[]>(comboboxPeopleOptions);
+
+  const handleCreate = (name: string) => {
+    const newOpt: ComboboxOption = {
+      value: name.toLowerCase().replace(/\s/g, '-'),
+      label: name,
+      iconName: 'user',
+    };
+    setOptions(prev => [...prev, newOpt]);
+    return newOpt;
+  };
+
+  const handleDelete = (value: string) => {
+    setOptions(prev => prev.filter(opt => opt.value !== value));
+  };
+
+  return (
+    <Combobox
+      options={options}
+      placeholder="Search or create..."
+      allowCreate
+      onCreateNew={handleCreate}
+      onDeleteCreated={handleDelete}
+    />
+  );
+};
+
+export const SingleSelectCreate: Story = withDescription({
+  render: () => <SingleSelectCreateTemplate />,
+}, 'Shows single-select creation where a newly created option becomes the current value immediately.');
+
+export const CustomTagLabel: Story = withDescription({
+  args: {
+    options: [
+      { value: 'u1', label: 'Alice Johnson (Year 10, Class A)', tagLabel: 'Alice J.', iconName: 'user' },
+      { value: 'u2', label: 'Bob Smith (Year 11, Class B)', tagLabel: 'Bob S.', iconName: 'user' },
+      { value: 'u3', label: 'Charlie Brown (Year 10, Class A)', tagLabel: 'Charlie B.', iconName: 'user' },
+    ],
+    multiple: true,
+    placeholder: 'Search students...',
+    showClearAll: true,
+  },
+}, 'Uses `tagLabel` to shorten selected chip text while preserving fuller option labels in the dropdown.');
+
+export const WithDisabledOptions: Story = withDescription({
+  args: {
+    options: [
+      { value: 'alice', label: 'Alice Johnson', iconName: 'user' },
+      { value: 'bob', label: 'Bob Smith', iconName: 'user', disabled: true },
+      { value: 'charlie', label: 'Charlie Brown', iconName: 'user' },
+    ],
+    multiple: true,
+    placeholder: 'Search people...',
+  },
+}, 'Includes a disabled option to show how unavailable rows appear and behave inside the listbox.');