@arbor-education/design-system.components 0.13.1 → 0.14.0

package/src/components/card/Card.stories.tsx

@@ -1,99 +1,55 @@
-import type { Meta } from '@storybook/react-vite';
-import { Card } from './Card';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { fn } from 'storybook/test';
+import { Card } from './Card';
 
-const meta: Meta<typeof Card> = {
+const meta = {
   title: 'Components/Card',
   component: Card,
-};
+} satisfies Meta<typeof Card>;
 
-export const CardWithTitleAndParagraph = {
-  args: {
-    title: 'Title of Card',
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    disabled: false,
-    onClick: fn(),
-    onKeyDown: fn(),
-  },
-};
+type Story = StoryObj<typeof meta>;
 
-export const CardWithTitleParagraphAndIcon = {
-  args: {
-    title: 'Title of Card',
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    icon: 'eye',
-    disabled: false,
-    onClick: fn(),
-    onKeyDown: fn(),
-  },
-};
-
-export const TheEverythingCard = {
-  args: {
-    title: 'Title of Card',
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    icon: 'eye',
-    disabled: false,
-    pillText: 'argle bargle',
-    pillColor: 'orange',
-    onClick: fn(),
-    onKeyDown: fn(),
-  },
-};
-
-export const CardWithTitleParagraphAndPill = {
-  args: {
-    title: 'Title of Card',
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    disabled: false,
-    pillText: 'argle bargle',
-    pillColor: 'orange',
-    onClick: fn(),
-    onKeyDown: fn(),
-  },
-};
-
-export const CardWithTitleAndIcon = {
-  args: {
-    title: 'Title of Card',
-    icon: 'eye',
-    disabled: false,
-    onClick: fn(),
-    onKeyDown: fn(),
-  },
-};
+const sampleCardContent = (
+  <>
+    <h3>Attendance summary</h3>
+    <p>View the latest attendance and behaviour insights for this cohort.</p>
+  </>
+);
 
-export const CardWithParagraph = {
+export const StaticCard: Story = {
   args: {
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    disabled: false,
-    onClick: fn(),
-    onKeyDown: fn(),
+    'aria-label': 'Static summary card',
   },
+  render: args => (
+    <Card {...args}>
+      {sampleCardContent}
+    </Card>
+  ),
 };
 
-export const ClickableDisabledCard = {
+export const ClickableCard: Story = {
   args: {
-    title: 'Title of Card',
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    icon: 'eye',
-    disabled: true,
-    pillText: 'argle bargle',
-    pillColor: 'orange',
-    onClick: fn(),
-    onKeyDown: fn(),
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Clickable card',
   },
+  render: args => (
+    <Card {...args}>
+      {sampleCardContent}
+    </Card>
+  ),
 };
 
-export const UnclickableCard = {
+export const DenseCard: Story = {
   args: {
-    title: 'Title of Card',
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    icon: 'eye',
-    disabled: true,
-    pillText: 'argle bargle',
-    pillColor: 'orange',
+    'aria-label': 'Dense card',
+    'spacing': 'dense',
   },
+  render: args => (
+    <Card {...args}>
+      {sampleCardContent}
+    </Card>
+  ),
 };
 
 export default meta;

package/src/components/card/Card.test.tsx

@@ -4,222 +4,104 @@ import { render, screen, fireEvent } from '@testing-library/react';
 import { Card } from './Card';
 import '@testing-library/jest-dom/vitest';
 
-describe('Card Component', () => {
-  test('renders empty card without any props', () => {
-    render(<Card />);
-    const card = screen.getByRole('article');
-    expect(card).toBeInTheDocument();
-    expect(card).toHaveAttribute('aria-label', 'Card');
-  });
+describe('Card', () => {
+  test('renders children inside the card shell', () => {
+    const { container } = render(
+      <Card aria-label="Summary card">
+        <div>Custom content</div>
+      </Card>,
+    );
 
-  test('renders card with title', () => {
-    render(<Card title="Test Title" />);
-    expect(screen.getByRole('heading', { level: 4 })).toHaveTextContent('Test Title');
-    expect(screen.getByText('Test Title')).toHaveClass('ds-card__title');
-  });
+    const card = container.querySelector('figure');
 
-  test('renders card with paragraph', () => {
-    render(<Card paragraph="Test paragraph content" />);
-    expect(screen.getByText('Test paragraph content')).toBeInTheDocument();
-    expect(screen.getByText('Test paragraph content')).toHaveClass('ds-card__paragraph');
+    expect(card).toBeInTheDocument();
+    expect(card).toHaveAttribute('aria-label', 'Summary card');
+    expect(screen.getByText('Custom content')).toBeInTheDocument();
   });
 
-  test('renders card with both title and paragraph', () => {
-    render(<Card title="Test Title" paragraph="Test paragraph" />);
-    expect(screen.getByRole('heading', { level: 4 })).toHaveTextContent('Test Title');
-    expect(screen.getByText('Test paragraph')).toBeInTheDocument();
-  });
+  test('renders clickable affordances when interactive', () => {
+    const mockClick = vi.fn();
+    const { container } = render(
+      <Card onClick={mockClick} aria-label="Clickable card">
+        <div>Clickable content</div>
+      </Card>,
+    );
 
-  test('renders card with icon', () => {
-    const { container } = render(<Card icon="eye" />);
-    expect(container.querySelector('.ds-icon-eye')).toBeInTheDocument();
-  });
+    const card = screen.getByRole('button', { name: 'Clickable card' });
+    fireEvent.click(card);
 
-  test('renders card with pill', () => {
-    render(<Card tagText="Test Pill" tagColor="orange" />);
-    expect(screen.getByText('Test Pill')).toBeInTheDocument();
+    expect(mockClick).toHaveBeenCalledTimes(1);
+    expect(card).toHaveClass('ds-card__container--clickable');
+    expect(card).toHaveAttribute('tabIndex', '0');
+    expect(container.querySelector('.ds-icon-chevron-right')).toBeInTheDocument();
+    expect(container.querySelector('.ds-icon-arrow-right')).toBeInTheDocument();
   });
 
-  test('renders complete card with all props', () => {
+  test('does not render clickable affordances when disabled', () => {
     const mockClick = vi.fn();
-    const mockKeyDown = vi.fn();
-
     const { container } = render(
-      <Card
-        title="Complete Card"
-        paragraph="This is a complete card"
-        icon="eye"
-        iconColor="#blue"
-        tagText="Complete"
-        tagColor="green"
-        onClick={mockClick}
-        onKeyDown={mockKeyDown}
-      />,
+      <Card disabled onClick={mockClick} aria-label="Disabled card">
+        <div>Disabled content</div>
+      </Card>,
     );
 
-    expect(screen.getByText('Complete Card')).toBeInTheDocument();
-    expect(screen.getByText('This is a complete card')).toBeInTheDocument();
-    expect(container.querySelector('.ds-icon-eye')).toBeInTheDocument();
-    expect(screen.getByText('Complete')).toBeInTheDocument();
-  });
-
-  describe('Click interactions', () => {
-    test('calls onClick handler when card is clicked', () => {
-      const mockClick = vi.fn();
-      render(<Card title="Clickable Card" onClick={mockClick} />);
-
-      const card = screen.getByRole('article');
-      fireEvent.click(card);
-
-      expect(mockClick).toHaveBeenCalledTimes(1);
-    });
-
-    test('does not call onClick when card is disabled', () => {
-      const mockClick = vi.fn();
-      render(<Card title="Disabled Card" onClick={mockClick} disabled />);
-
-      const card = screen.getByRole('article');
-      fireEvent.click(card);
-
-      expect(mockClick).not.toHaveBeenCalled();
-    });
+    const card = screen.getByRole('button', { name: 'Disabled card' });
 
-    test('shows click arrow icon when card is clickable', () => {
-      const mockClick = vi.fn();
-      const { container } = render(<Card title="Clickable Card" onClick={mockClick} />);
+    expect(card).toHaveClass('ds-card__container--disabled');
+    expect(card).toHaveAttribute('aria-disabled', 'true');
+    expect(card).toHaveAttribute('role', 'button');
+    expect(card).toHaveAttribute('tabIndex', '0');
+    expect(container.querySelector('.ds-icon-chevron-right')).not.toBeInTheDocument();
 
-      expect(container.querySelector('.ds-icon-chevron-right')).toBeInTheDocument();
-    });
+    card.focus();
+    expect(card).toHaveFocus();
 
-    test('does not show click arrow icon when card is not clickable', () => {
-      const { container } = render(<Card title="Non-clickable Card" />);
+    fireEvent.click(card);
+    fireEvent.keyDown(card, { key: 'Enter' });
+    fireEvent.keyDown(card, { key: ' ' });
 
-      expect(container.querySelector('.ds-icon-chevron-right')).not.toBeInTheDocument();
-    });
-
-    test('does not show click arrow icon when card is disabled', () => {
-      const mockClick = vi.fn();
-      const { container } = render(<Card title="Disabled Card" onClick={mockClick} disabled />);
-
-      expect(container.querySelector('.ds-icon-chevron-right')).not.toBeInTheDocument();
-    });
+    expect(mockClick).not.toHaveBeenCalled();
   });
 
-  describe('Keyboard interactions', () => {
-    test('calls onKeyDown handler when key is pressed on clickable card', () => {
-      const mockKeyDown = vi.fn();
-      render(<Card title="Keyboard Card" onClick={vi.fn()} onKeyDown={mockKeyDown} />);
-
-      const card = screen.getByRole('article');
-      fireEvent.keyDown(card, { key: 'Enter' });
-
-      expect(mockKeyDown).toHaveBeenCalledTimes(1);
-    });
-
-    test('does not call onKeyDown when card is disabled', () => {
-      const mockKeyDown = vi.fn();
-      render(<Card title="Disabled Card" onClick={vi.fn()} onKeyDown={mockKeyDown} disabled />);
-
-      const card = screen.getByRole('article');
-      fireEvent.keyDown(card, { key: 'Enter' });
-
-      expect(mockKeyDown).not.toHaveBeenCalled();
-    });
+  test('calls onKeyDown and keyboard-activates the card on Enter', () => {
+    const mockClick = vi.fn();
+    const mockKeyDown = vi.fn();
 
-    test('does not call onKeyDown when card is not clickable', () => {
-      const mockKeyDown = vi.fn();
-      render(<Card title="Non-clickable Card" onKeyDown={mockKeyDown} />);
+    render(
+      <Card onClick={mockClick} onKeyDown={mockKeyDown} aria-label="Keyboard card">
+        <div>Keyboard content</div>
+      </Card>,
+    );
 
-      const card = screen.getByRole('article');
-      fireEvent.keyDown(card, { key: 'Enter' });
+    const card = screen.getByRole('button', { name: 'Keyboard card' });
+    fireEvent.keyDown(card, { key: 'Enter' });
 
-      expect(mockKeyDown).not.toHaveBeenCalled();
-    });
+    expect(mockKeyDown).toHaveBeenCalledTimes(1);
+    expect(mockClick).toHaveBeenCalledTimes(1);
   });
 
-  describe('CSS classes and accessibility', () => {
-    test('applies clickable class when onClick is provided and not disabled', () => {
-      const mockClick = vi.fn();
-      render(<Card onClick={mockClick} />);
-
-      const card = screen.getByRole('article');
-      expect(card).toHaveClass('ds-card__container--clickable');
-    });
-
-    test('applies disabled class when disabled', () => {
-      render(<Card disabled />);
-
-      const card = screen.getByRole('article');
-      expect(card).toHaveClass('ds-card__container--disabled');
-    });
-
-    test('does not apply clickable class when disabled', () => {
-      const mockClick = vi.fn();
-      render(<Card onClick={mockClick} disabled />);
-
-      const card = screen.getByRole('article');
-      expect(card).not.toHaveClass('ds-card__container--clickable');
-      expect(card).toHaveClass('ds-card__container--disabled');
-    });
-
-    test('sets correct tabIndex for clickable card', () => {
-      const mockClick = vi.fn();
-      render(<Card onClick={mockClick} />);
-
-      const card = screen.getByRole('article');
-      expect(card).toHaveAttribute('tabIndex', '0');
-    });
-
-    test('sets correct tabIndex for non-clickable card', () => {
-      render(<Card />);
-
-      const card = screen.getByRole('article');
-      expect(card).toHaveAttribute('tabIndex', '-1');
-    });
-
-    test('sets correct tabIndex for disabled card', () => {
-      const mockClick = vi.fn();
-      render(<Card onClick={mockClick} disabled />);
-
-      const card = screen.getByRole('article');
-      expect(card).toHaveAttribute('tabIndex', '-1');
-    });
-
-    test('has correct aria-label', () => {
-      render(<Card />);
+  test('passes through aria-labelledby', () => {
+    const { container } = render(
+      <>
+        <h2 id="card-heading">Linked heading</h2>
+        <Card aria-labelledby="card-heading">
+          <div>Linked content</div>
+        </Card>
+      </>,
+    );
 
-      const card = screen.getByRole('article');
-      expect(card).toHaveAttribute('aria-label', 'Card');
-    });
+    const card = container.querySelector('figure');
+    expect(card).toHaveAttribute('aria-labelledby', 'card-heading');
   });
 
-  describe('Event handler edge cases', () => {
-    test('handles onClick without onKeyDown', () => {
-      const mockClick = vi.fn();
-      render(<Card title="Click only" onClick={mockClick} />);
-
-      const card = screen.getByRole('article');
-      fireEvent.click(card);
-
-      expect(mockClick).toHaveBeenCalledTimes(1);
-    });
-
-    test('handles onKeyDown without onClick', () => {
-      const mockKeyDown = vi.fn();
-      render(<Card title="KeyDown only" onKeyDown={mockKeyDown} />);
-
-      const card = screen.getByRole('article');
-      fireEvent.keyDown(card, { key: 'Enter' });
-
-      // Should not be called because card is not clickable (no onClick)
-      expect(mockKeyDown).not.toHaveBeenCalled();
-    });
-
-    test('does not throw error when clicking card without handlers', () => {
-      render(<Card title="No handlers" />);
+  test('applies dense spacing when requested', () => {
+    const { container } = render(
+      <Card spacing="dense">
+        <div>Dense content</div>
+      </Card>,
+    );
 
-      const card = screen.getByRole('article');
-      expect(() => fireEvent.click(card)).not.toThrow();
-    });
+    const card = container.querySelector('figure');
+    expect(card).toHaveClass('ds-card__container--dense');
   });
 });

package/src/components/card/Card.tsx

@@ -1,86 +1,142 @@
 import classNames from 'classnames';
-
 import { Icon } from '../icon/Icon';
-import { allowedIcons } from '../icon/allowedIcons';
-import { Tag, type TagColor } from 'Components/tag/Tag';
-
-type CardProps = {
-  title?: string;
-  paragraph?: string;
-  icon?: keyof typeof allowedIcons;
-  iconColor?: string;
+
+type CardBaseProps = {
+  children?: React.ReactNode;
+  className?: string;
   disabled?: boolean;
-  tagText?: string;
-  tagColor?: TagColor;
-  onClick?: (e: React.MouseEvent<HTMLElement>) => void;
+  spacing?: 'default' | 'dense';
+};
+
+type CardAccessibleNameProps
+  = | {
+    'aria-label': string;
+    'aria-labelledby'?: string;
+  }
+  | {
+    'aria-label'?: string;
+    'aria-labelledby': string;
+  };
+
+type CardInteractiveProps = CardAccessibleNameProps & {
+  onClick: (e: React.MouseEvent<HTMLElement>) => void;
   onKeyDown?: (e: React.KeyboardEvent<HTMLElement>) => void;
-  iconScreenReaderText?: string;
 };
 
-export const Card = ({
-  title,
-  paragraph,
-  icon,
-  iconColor,
-  iconScreenReaderText,
-  onClick,
-  onKeyDown,
-  disabled,
-  tagText,
-  tagColor,
-}: CardProps) => {
-  const handleClick = (e: React.MouseEvent<HTMLElement>) => {
-    if (onClick) {
-      onClick(e);
-    }
+type CardStaticProps = {
+  'onClick'?: undefined;
+  'onKeyDown'?: (e: React.KeyboardEvent<HTMLElement>) => void;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+};
+
+type CardInteractionProps = CardInteractiveProps | CardStaticProps;
+
+type CardResolvedInteractionProps
+  = | {
+    'onClick': (e: React.MouseEvent<HTMLElement>) => void;
+    'onKeyDown'?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    'aria-label': string;
+  }
+  | {
+    'onClick': (e: React.MouseEvent<HTMLElement>) => void;
+    'onKeyDown'?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    'aria-labelledby': string;
+  }
+  | {
+    'onClick'?: undefined;
+    'onKeyDown'?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
   };
 
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLElement>) => {
-    if (onKeyDown) {
-      onKeyDown(e);
+export type CardProps = CardBaseProps & CardInteractionProps;
+
+export const getCardInteractionProps = (props: CardInteractionProps): CardResolvedInteractionProps => {
+  if (props.onClick === undefined) {
+    return {
+      'onKeyDown': props.onKeyDown,
+      'aria-label': props['aria-label'],
+      'aria-labelledby': props['aria-labelledby'],
+    };
+  }
+
+  if (props['aria-label'] !== undefined) {
+    return {
+      'onClick': props.onClick,
+      'onKeyDown': props.onKeyDown,
+      'aria-label': props['aria-label'],
+    };
+  }
+
+  if (props['aria-labelledby'] === undefined) {
+    if (process.env.NODE_ENV !== 'production') {
+      throw new Error('Interactive Card requires aria-label or aria-labelledby.');
     }
+
+    console.error('Interactive Card requires aria-label or aria-labelledby.');
+
+    return {
+      onClick: props.onClick,
+      onKeyDown: props.onKeyDown,
+    } as CardResolvedInteractionProps;
+  }
+
+  return {
+    'onClick': props.onClick,
+    'onKeyDown': props.onKeyDown,
+    'aria-labelledby': props['aria-labelledby'],
   };
+};
 
-  const isCardClickable = onClick && !disabled;
+export const Card = ({
+  children,
+  className,
+  onClick,
+  onKeyDown,
+  disabled = false,
+  spacing = 'default',
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+}: CardProps): React.JSX.Element => {
+  const isCardInteractive = Boolean(onClick);
+  const isCardClickable = isCardInteractive && !disabled;
 
   return (
-    <article
-      className={classNames('ds-card__container', {
+    <figure
+      className={classNames('ds-card__container', className, {
         'ds-card__container--clickable': isCardClickable,
         'ds-card__container--disabled': disabled,
+        'ds-card__container--dense': spacing === 'dense',
       })}
       onClick={(e) => {
         if (isCardClickable) {
-          handleClick(e);
+          onClick?.(e);
         }
       }}
       onKeyDown={(e) => {
+        if (!isCardInteractive) return;
+
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+
+          if (isCardClickable) {
+            e.currentTarget.click();
+          }
+        }
+
         if (isCardClickable) {
-          handleKeyDown(e);
+          onKeyDown?.(e);
         }
       }}
-      aria-label="Card"
-      tabIndex={isCardClickable ? 0 : -1}
+      aria-disabled={isCardInteractive && disabled ? true : undefined}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      role={isCardInteractive ? 'button' : undefined}
+      tabIndex={isCardInteractive ? 0 : undefined}
     >
       <div className="ds-card__content">
-        {icon && (
-          <Icon
-            name={icon}
-            className="ds-card__icon-left"
-            screenReaderText={iconScreenReaderText}
-            color={iconColor}
-            size={24}
-          />
-        )}
-        <div className="ds-card__text">
-          {title && (
-            <span className="ds-card__title-container">
-              {title && <h4 className="ds-card__title">{title}</h4>}
-            </span>
-          )}
-          {paragraph && <p className="ds-card__paragraph">{paragraph}</p>}
-          {tagText && <Tag color={tagColor}>{tagText}</Tag>}
-        </div>
+        <div className="ds-card__body">{children}</div>
         {isCardClickable && (
           <>
             <Icon
@@ -96,10 +152,13 @@ export const Card = ({
           </>
         )}
       </div>
-    </article>
+    </figure>
   );
 };
 
 export namespace Card {
   export type Props = CardProps;
+  export type AccessibleNameProps = CardAccessibleNameProps;
+  export type InteractiveProps = CardInteractiveProps;
+  export type InteractionProps = CardInteractionProps;
 }