@arbor-education/design-system.components 0.6.0 → 0.7.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');
     });
   });
 });

package/src/components/tag/Tag.tsx

@@ -1,4 +1,5 @@
 import classNames from 'classnames';
+import { Icon } from 'Components/icon/Icon';
 
 export type TagColor = 'neutral'
   | 'orange'
@@ -9,26 +10,49 @@ export type TagColor = 'neutral'
   | 'salmon'
   | 'yellow';
 
-export type DotColour = 'purple' | 'salmon' | 'teal' | 'yellow' | 'green' | 'orange' | 'blue';
-
-type TagProps = {
-  text: string;
+export type TagProps = {
+  children: React.ReactNode;
   color?: TagColor;
-  dotColour?: DotColour;
+  selected?: boolean;
+  slotStart?: React.ReactNode;
+  slotEnd?: React.ReactNode;
+  onRemove?: () => void;
+  removeLabel?: string;
+  removeButtonTabIndex?: 0 | -1;
 };
 
-export const Tag = ({ text, color = 'neutral', dotColour }: TagProps) => {
+export const Tag = ({
+  children,
+  color = 'neutral',
+  selected = false,
+  slotStart,
+  slotEnd,
+  onRemove,
+  removeLabel = 'Remove',
+  removeButtonTabIndex = 0,
+}: TagProps): React.JSX.Element => {
   return (
-    <span
-      className={classNames('ds-tag', `ds-tag--${color}`)}
+    <span className={classNames('ds-tag', `ds-tag--${color}`, {
+      'ds-tag--selected': selected,
+    })}
     >
-      {dotColour && (
-        <span
-          aria-label={`${dotColour} dot`}
-          className={classNames('ds-tag__dot', `ds-tag__dot--${dotColour}`)}
-        />
+      {slotStart && <span className="ds-tag__slot-start">{slotStart}</span>}
+      <span className="ds-tag__label">{children}</span>
+      {slotEnd && <span className="ds-tag__slot-end">{slotEnd}</span>}
+      {onRemove && (
+        <button
+          type="button"
+          className="ds-tag__remove"
+          aria-label={removeLabel}
+          onClick={(e) => {
+            e.stopPropagation();
+            onRemove();
+          }}
+          tabIndex={removeButtonTabIndex}
+        >
+          <Icon name="x" size={12} />
+        </button>
       )}
-      {text}
     </span>
   );
 };

package/src/components/tag/tag.scss

@@ -1,21 +1,24 @@
 .ds-tag {
-  display: flex;
-  padding: var(--tag-spacing-vertical) var(--tag-spacing-horizontal);
+  display: inline-flex;
+  padding: 0 var(--tag-spacing-horizontal);
   align-items: center;
   gap: var(--tag-spacing-gap-horizontal);
   border-radius: var(--tag-radius);
+  border: var(--border-weight) solid transparent;
+  box-sizing: border-box;
   flex-grow: 0;
   width: fit-content;
-
-  /* typography/body/p1-reg */
+  white-space: nowrap;
+  max-width: 100%;
+  height: var(--tag-height);
   font-style: normal;
-  line-height: 150%; /* 19.5px */
+  line-height: 150%;
 
   &--neutral {
     color: var(--tag-neutral-color-text);
     background: var(--tag-neutral-color-background);
   }
-  
+
   &--orange {
     color: var(--tag-category-orange-color-text);
     background: var(--tag-category-orange-color-background);
@@ -50,38 +53,50 @@
     color: var(--tag-category-yellow-color-text);
     background: var(--tag-category-yellow-color-background);
   }
-}
 
-.ds-tag__dot {
-  width: 10px;
-  height: 10px;
-  border-radius: 50%;
-
-  &--purple {
-    background-color: var(--color-extended-colours-purple-500);
+  &--selected {
+    background: var(--tag-selected-color-background);
+    color: var(--tag-neutral-color-text);
+    border-color: var(--tag-selected-color-border);
   }
 
-  &--salmon {
-    background-color: var(--color-extended-colours-salmon-500);
-  }
+}
 
-  &--teal {
-    background-color: var(--color-extended-colours-teal-500);
-  }
+.ds-tag__slot-start {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
 
-  &--yellow {
-    background-color: var(--color-extended-colours-yellow-500);
-  }
+.ds-tag__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
 
-  &--green {
-    background-color: var(--color-extended-colours-green-500);
-  }
+.ds-tag__slot-end {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
 
-  &--orange {
-    background-color: var(--color-extended-colours-orange-500);
+.ds-tag__remove {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  padding: 0;
+  cursor: pointer;
+  color: inherit;
+  border-radius: 50%;
+  flex-shrink: 0;
+
+  &:hover {
+    background-color: var(--color-grey-200);
   }
 
-  &--blue {
-    background-color: var(--color-extended-colours-blue-500);
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
   }
 }