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

package/src/components/row/row.scss

@@ -0,0 +1,61 @@
+.ds-row {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-between;
+  align-items: center;
+  background-color: var(--section-list-row-default-color-background);
+  padding: var(--section-list-row-spacing-vertical) var(--section-list-row-spacing-horizontal);
+  border-radius: var(--section-list-row-radius);
+
+  .ds-row__icon-click {
+    flex-shrink: 0;
+    margin-left: var(--spacing-small);
+      stroke: var(--section-list-row-default-color-icon-arrow);
+    
+
+    &.ds-icon-arrow-right {
+      display: none;
+    }
+  }
+
+  &--clickable {
+    cursor: pointer;
+
+    &:hover {
+      background-color: var(--section-list-row-hover-hover-bg);
+    }
+  }
+
+  &:focus {
+    box-shadow: 0 0 0 3px var(--color-brand-300);
+    outline: none;
+  }
+
+  &:hover {
+    .ds-row__icon-click {
+        stroke: var(--section-list-row-hover-color-icon-arrow);
+      
+
+      &.ds-icon-chevron-right {
+        display: none;
+      }
+
+      &.ds-icon-arrow-right {
+        display: block;
+      }
+    }
+  }
+
+  &__label {
+    min-width: 190px;
+    font-weight: var(--font-weight-semi-bold);
+  }
+
+  &__value {
+    flex-grow: 1;
+  }
+
+  &__note {
+    font-style: italic;
+  }
+}

package/src/components/section/Section.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta } from '@storybook/react-vite';
 import { Section } from './Section';
+import { Row } from 'Components/row/Row';
 
 const meta: Meta<typeof Section> = {
   title: 'Components/Section',
@@ -31,4 +32,59 @@ export const NestedSections = {
   },
 };
 
+export const WithRows = {
+  args: {
+    title: 'Student Details',
+    children: [
+      <Row key={1} label="First Name" value="Jacob" />,
+      <Row key={2} label="Last Name" value="Black" />,
+      <Row key={3} label="Year Group" value="Year 10" note="2024/2025" />,
+      <Row key={4} label="Form Group" value="10A" />,
+    ],
+  },
+};
+
+export const WithClickableRows = {
+  args: {
+    title: 'Quick Links',
+    buttonText: 'Edit',
+    children: [
+      <Row key={1} label="Attendance" value="96%" note="Above target" onClick={() => { console.log('click!'); }} />,
+      <Row key={2} label="Behaviour" value="3 positive points" onClick={() => { console.log('click!'); }} />,
+      <Row key={3} label="Assessment" value="On track" note="Last updated 2 days ago" onClick={() => { console.log('click!'); }} />,
+    ],
+  },
+};
+
+export const CollapsibleWithRows = {
+  args: {
+    title: 'Contact Information',
+    collapsible: true,
+    children: [
+      <Row key={1} label="Email" value="jacob.black@forks.edu" />,
+      <Row key={2} label="Phone" value="01onal 555 0123" />,
+      <Row key={3} label="Address" value="La Push, Washington" note="Primary" />,
+    ],
+  },
+};
+
+export const NestedSectionsWithRows = {
+  args: {
+    title: 'Student Profile',
+    collapsible: true,
+    children: [
+      <Section key={1} title="Personal Details" collapsible>
+        <Row label="First Name" value="Jacob" />
+        <Row label="Last Name" value="Black" />
+        <Row label="Date of Birth" value="14/01/1990" note="Age 36" />
+      </Section>,
+      <Section key={2} title="Academic" collapsible>
+        <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!'); }} />
+      </Section>,
+    ],
+  },
+};
+
 export default meta;

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);
+}

package/src/components/table/cellRenderers/SelectDropdownCellRenderer.tsx

@@ -13,6 +13,13 @@ import { useComponentDidMount } from 'Utils/hooks/useComponentDidMount';
 type SelectDropdownCellRendererProps = CustomCellRendererProps
   & SelectDropdownInputProps;
 
+type SelectDropdownCellRendererOption = Omit<
+  SelectDropdownInputProps['options'][number],
+  'value'
+> & {
+  value: string | number;
+};
+
 export const SelectDropdownCellRenderer = (
   props: SelectDropdownCellRendererProps,
 ) => {
@@ -31,6 +38,12 @@ export const SelectDropdownCellRenderer = (
     alwaysShowPlaceholder = false,
   } = props;
 
+  const rawOptions: SelectDropdownCellRendererOption[] = options;
+  const normalisedOptions: SelectDropdownInputProps['options'] = rawOptions.map(option => ({
+    ...option,
+    value: String(option.value),
+  }));
+
   const valueStr = value != null && value !== '' ? String(value) : '';
   const initialSelectedValues = valueStr ? [valueStr] : [];
 
@@ -65,15 +78,18 @@ export const SelectDropdownCellRenderer = (
         aria-describedBy={ariaDescribedBy}
         aria-invalid={ariaInvalid}
         alwaysShowPlaceholder={alwaysShowPlaceholder}
-        options={options}
+        options={normalisedOptions}
         placeholder={placeholder}
         initialSelectedValues={initialSelectedValues}
         open={isOpen}
         onOpenChange={setIsOpen}
         multiple={false}
         onSelectionChange={(newValue) => {
-          if (column) {
-            node.setDataValue(column, newValue[0]);
+          if (column && newValue[0] != null) {
+            const selectedOption = rawOptions.find(
+              option => String(option.value) === newValue[0],
+            );
+            node.setDataValue(column, selectedOption?.value ?? newValue[0]);
           }
         }}
       />

package/src/components/tag/Tag.stories.tsx

@@ -1,16 +1,98 @@
-import type { Meta } from '@storybook/react-vite';
-import { Tag } from './Tag';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { fn } from '@storybook/test';
+import { Dot } from 'Components/dot/Dot';
+import { Icon } from 'Components/icon/Icon';
+import { Tag, type TagColor } from './Tag';
 
 const meta: Meta<typeof Tag> = {
   tags: ['autodocs'],
   title: 'Components/Tag',
   component: Tag,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Displays compact tag content with optional start/end slots and removable actions. Removable tags keep their remove button in the tab order by default; composite parents such as Combobox can pass `removeButtonTabIndex={-1}` for roving tab focus.',
+      },
+    },
+  },
 };
 
-export const Default = {
+export default meta;
+
+type Story = StoryObj<typeof Tag>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+export const Default: Story = withDescription({
+  args: { children: 'Tag content' },
+}, 'Shows the default neutral Tag with plain text content.');
+
+export const WithColour: Story = withDescription({
+  args: { children: 'Blue tag', color: 'blue' },
+}, 'Applies one of the semantic colour variants to the Tag.');
+
+export const Selected: Story = withDescription({
+  args: { children: 'Selected tag', color: 'blue', selected: true },
+}, 'Shows the selected treatment, which intentionally prioritises selection styling over the base colour variant.');
+
+export const WithDot: Story = withDescription({
   args: {
-    text: 'Tag content',
+    children: 'With dot',
+    slotStart: <Dot colour="purple" />,
   },
-};
+}, 'Uses `slotStart` to render a decorative dot before the label.');
 
-export default meta;
+export const WithIcon: Story = withDescription({
+  args: {
+    children: 'Alice Johnson',
+    slotStart: <Icon name="user" size={12} />,
+  },
+}, 'Uses `slotStart` to show an icon before the Tag label.');
+
+export const Removable: Story = withDescription({
+  args: {
+    children: 'Removable tag',
+    onRemove: fn(),
+    removeLabel: 'Remove removable tag',
+  },
+}, 'Demonstrates a removable Tag with the default close affordance and a custom accessible remove label. The remove button is tabbable by default.');
+
+export const RemovableWithIcon: Story = withDescription({
+  args: {
+    children: 'Alice Johnson',
+    slotStart: <Icon name="user" size={12} />,
+    onRemove: fn(),
+    removeLabel: 'Remove Alice Johnson',
+  },
+}, 'Combines a leading icon with the removable Tag interaction.');
+
+export const WithSlotEnd: Story = withDescription({
+  args: {
+    children: 'Custom end',
+    slotEnd: <Icon name="chevron-down" size={12} />,
+  },
+}, 'Uses `slotEnd` to render trailing custom content.');
+
+const allColours: TagColor[] = ['neutral', 'orange', 'blue', 'green', 'purple', 'teal', 'salmon', 'yellow'];
+
+export const AllColours: Story = withDescription({
+  render: () => (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+      {allColours.map(color => (
+        <Tag key={color} color={color}>{color}</Tag>
+      ))}
+    </div>
+  ),
+}, 'Displays every available Tag colour variant side by side.');

package/src/components/tag/Tag.test.tsx

@@ -1,65 +1,131 @@
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
-import { Tag } from './Tag';
+import userEvent from '@testing-library/user-event';
 import '@testing-library/jest-dom/vitest';
+import { Tag } from './Tag';
+import { Dot } from 'Components/dot/Dot';
 
 describe('Tag', () => {
-  test('Tag says hello', () => {
-    render(<Tag text="Hello I'm a Pill!" />);
-    expect(screen.getByText("Hello I'm a Pill!")).toBeInTheDocument();
+  test('renders children as text content', () => {
+    render(<Tag>Hello</Tag>);
+    expect(screen.getByText('Hello')).toBeInTheDocument();
+  });
+
+  test('has default color neutral', () => {
+    const { container } = render(<Tag>Neutral</Tag>);
+    expect(container.querySelector('.ds-tag')).toHaveClass('ds-tag--neutral');
+  });
+
+  test('applies custom color class', () => {
+    const { container } = render(<Tag color="blue">Blue</Tag>);
+    expect(container.querySelector('.ds-tag')).toHaveClass('ds-tag--blue');
   });
 
-  test('Tag has default color neutral', () => {
-    render(<Tag text="Hello I'm a Pill!" />);
-    expect(screen.getByText("Hello I'm a Pill!")).toHaveClass('ds-tag--neutral');
+  test('applies selected class when selected is true', () => {
+    const { container } = render(<Tag selected>Selected</Tag>);
+    expect(container.querySelector('.ds-tag')).toHaveClass('ds-tag--selected');
   });
 
-  test('Tag has custom color', () => {
-    render(<Tag text="Hello I'm a Pill!" color="blue" />);
-    expect(screen.getByText("Hello I'm a Pill!")).toHaveClass('ds-tag--blue');
+  describe('slotStart', () => {
+    test('renders slotStart content', () => {
+      const { container } = render(<Tag slotStart={<Dot colour="purple" />}>With dot</Tag>);
+      expect(container.querySelector('.ds-tag__slot-start .ds-dot--purple')).toBeInTheDocument();
+      expect(container.querySelector('.ds-tag__slot-start .ds-dot')).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    test('does not render slot-start wrapper when slotStart is not provided', () => {
+      const { container } = render(<Tag>No slot</Tag>);
+      expect(container.querySelector('.ds-tag__slot-start')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('slotEnd', () => {
+    test('renders slotEnd content', () => {
+      const { container } = render(<Tag slotEnd={<span>End</span>}>With end</Tag>);
+      expect(container.querySelector('.ds-tag__slot-end')).toHaveTextContent('End');
+    });
+
+    test('does not render slot-end wrapper when slotEnd is not provided', () => {
+      const { container } = render(<Tag>No slot</Tag>);
+      expect(container.querySelector('.ds-tag__slot-end')).not.toBeInTheDocument();
+    });
   });
 
-  describe('dot functionality', () => {
-    test('Tag does not render dot when dotColour is not provided', () => {
-      render(<Tag text="No dot here" />);
-      expect(screen.queryByLabelText(/dot/i)).not.toBeInTheDocument();
+  describe('onRemove', () => {
+    test('renders remove button when onRemove is provided', () => {
+      render(<Tag onRemove={() => {}}>Removable</Tag>);
+      expect(screen.getByRole('button', { name: 'Remove' })).toBeInTheDocument();
+    });
+
+    test('uses a custom remove label when provided', () => {
+      render(
+        <Tag onRemove={() => {}} removeLabel="Remove Alice Johnson">
+          Removable
+        </Tag>,
+      );
+      expect(screen.getByRole('button', { name: 'Remove Alice Johnson' })).toBeInTheDocument();
+    });
+
+    test('keeps the remove button in the tab order by default', () => {
+      render(<Tag onRemove={() => {}}>Removable</Tag>);
+      expect(screen.getByRole('button', { name: 'Remove' })).toHaveAttribute('tabindex', '0');
     });
 
-    test('Tag renders dot when dotColour is provided', () => {
-      render(<Tag text="Has dot" dotColour="purple" />);
-      expect(screen.getByLabelText('purple dot')).toBeInTheDocument();
+    test('allows composite parents to remove the button from the tab order', () => {
+      render(
+        <Tag onRemove={() => {}} removeButtonTabIndex={-1}>
+          Removable
+        </Tag>,
+      );
+      expect(screen.getByRole('button', { name: 'Remove' })).toHaveAttribute('tabindex', '-1');
     });
 
-    test('Tag dot has correct color class', () => {
-      render(<Tag text="Purple dot" dotColour="purple" />);
-      const dot = screen.getByLabelText('purple dot');
-      expect(dot).toHaveClass('ds-tag__dot');
-      expect(dot).toHaveClass('ds-tag__dot--purple');
+    test('does not render remove button when onRemove is not provided', () => {
+      render(<Tag>Static</Tag>);
+      expect(screen.queryByRole('button', { name: 'Remove' })).not.toBeInTheDocument();
     });
 
-    test('Tag dot renders with each available colour', () => {
-      const colours: Array<'purple' | 'salmon' | 'teal' | 'yellow' | 'green' | 'orange' | 'blue'> = [
-        'purple',
-        'salmon',
-        'teal',
-        'yellow',
-        'green',
-        'orange',
-        'blue',
-      ];
-
-      colours.forEach((colour) => {
-        const { unmount } = render(<Tag text={`${colour} dot`} dotColour={colour} />);
-        const dot = screen.getByLabelText(`${colour} dot`);
-        expect(dot).toHaveClass(`ds-tag__dot--${colour}`);
-        unmount();
-      });
+    test('fires onRemove callback when close button is clicked', async () => {
+      const onRemove = vi.fn();
+      render(<Tag onRemove={onRemove}>Removable</Tag>);
+
+      await userEvent.click(screen.getByRole('button', { name: 'Remove' }));
+      expect(onRemove).toHaveBeenCalledOnce();
+    });
+
+    test('stops event propagation on remove click', async () => {
+      const onRemove = vi.fn();
+      const outerClick = vi.fn();
+      render(
+        <div onClick={outerClick}>
+          <Tag onRemove={onRemove}>Removable</Tag>
+        </div>,
+      );
+
+      await userEvent.click(screen.getByRole('button', { name: 'Remove' }));
+      expect(onRemove).toHaveBeenCalledOnce();
+      expect(outerClick).not.toHaveBeenCalled();
     });
+  });
+
+  describe('combined slots', () => {
+    test('renders slotStart, children, slotEnd, and remove button in correct order', () => {
+      const { container } = render(
+        <Tag
+          slotStart={<span>S</span>}
+          slotEnd={<span>E</span>}
+          onRemove={() => {}}
+        >
+          Label
+        </Tag>,
+      );
 
-    test('Tag renders both dot and text correctly', () => {
-      render(<Tag text="Text with dot" dotColour="teal" />);
-      expect(screen.getByText('Text with dot')).toBeInTheDocument();
-      expect(screen.getByLabelText('teal dot')).toBeInTheDocument();
+      const tag = container.querySelector('.ds-tag')!;
+      const children = Array.from(tag.children);
+      expect(children[0]).toHaveClass('ds-tag__slot-start');
+      expect(children[1]).toHaveClass('ds-tag__label');
+      expect(children[2]).toHaveClass('ds-tag__slot-end');
+      expect(children[3]).toHaveClass('ds-tag__remove');
     });
   });
 });