@arbor-education/design-system.components 0.16.0 → 0.17.0

package/src/components/dataViewCard/DataViewCard.stories.tsx

@@ -0,0 +1,464 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { DataViewCard } from './DataViewCard';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'DataViewCard is a precomposed [`Card`](?path=/docs/components-card--docs) variant for displaying a person or entity',
+  'as a tile — an [`Avatar`](?path=/docs/components-avatar--docs) on the left, a [`Heading`](?path=/docs/components-heading--docs)',
+  'for the name, and a stack of key-value [`Row`](?path=/docs/components-row--docs)s separated by [`Separator`](?path=/docs/components-separator--docs)s.',
+  'Built for grids of records (e.g. browse-students, staff directories) where the whole tile navigates to a profile.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Browse views of people / records** — staff list, student list, contact directory',
+  '- **Tile-based navigation** — when clicking the whole card should drill into a detail view',
+  '- **Summary at a glance** — a heading plus 2–4 quick facts (year group, role, ID, etc.)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Free-form content (paragraphs, mixed media) | [`ArticleCard`](?path=/docs/components-articlecard--docs) |',
+  '| Single metric / KPI display | [`KPICard`](?path=/docs/components-kpicard--docs) |',
+  '| Long lists where row density matters | [`Table`](?path=/docs/components-table--docs) |',
+  '| Just an avatar with name and role | [`SingleUser`](?path=/docs/components-singleuser--docs) |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`aria-label` (or `aria-labelledby`) is REQUIRED when `onClick` is set.** The underlying `Card` renders',
+  '`role="button"` for clickable cards — a button without an accessible name is a WCAG 2.1 failure (4.1.2).',
+  '',
+  '**Rows are passed as data, not children.** The component owns the layout — you provide an array of',
+  '`{ label, value, note? }` objects and the component renders them as `Row`s with separators between.',
+  '',
+  '**Avatar is optional.** Omit the `avatar` prop entirely when you do not have an image (the layout collapses',
+  'cleanly to header-plus-rows). Pass full `Avatar.Props` for full control over `src`/`initials`/`size`/`alt`.',
+  '',
+  '**Header is `string` only.** Use the `aria-labelledby` pattern if you need richer markup for the accessible',
+  'name; otherwise pass the plain person/entity name as `header`.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Heading renders as a real `<h4>` — fits inside an `<h3>` section/page heading',
+  '- Whole card is keyboard activatable (`Enter` / `Space`) when `onClick` is set, via the `Card` shell',
+  '- `disabled` removes click handling and applies `aria-disabled="true"` — focus is preserved',
+  '- Always pair an `Avatar` with `alt` text describing who it represents (or empty `alt=""` if purely decorative)',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { DataViewCard } from '@arbor-education/design-system.components';",
+  '',
+  'function MyCard(props: DataViewCard.Props) { ... }',
+  'const rows: DataViewCard.RowData[] = [{ label: \'Year\', value: \'Year 8\' }];',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `DataViewCard.Props` | Full props interface |',
+  '| `DataViewCard.RowData` | Alias for `Row.Props` — accepts the full [`Row`](?path=/docs/components-row--docs) API (`label`, `value`, `note`, plus `onClick` / `className`) |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Card](?path=/docs/components-card--docs) · [ArticleCard](?path=/docs/components-articlecard--docs) · [KPICard](?path=/docs/components-kpicard--docs) · [Avatar](?path=/docs/components-avatar--docs) · [Row](?path=/docs/components-row--docs) · [Heading](?path=/docs/components-heading--docs) · [Separator](?path=/docs/components-separator--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+function DataViewCardDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const sampleRows = [
+  { label: 'Year', value: 'Year 13' },
+  { label: 'Form', value: 'Form 13DZ' },
+  { label: 'DOB', value: '20 May 1932' },
+];
+
+const AVATAR_BASE = 'https://i.pravatar.cc/150?img=';
+
+const meta = {
+  title: 'Components/Card/DataViewCard',
+  component: DataViewCard,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: DataViewCardDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    'header': {
+      control: 'text',
+      description: 'The card heading — rendered as an `<h4>`. Pass the person or entity name.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'avatar': {
+      control: 'object',
+      description: [
+        'Optional `Avatar.Props` — accepts `src`, `initials`, `alt`, and `size` (defaults to `extra-large`).',
+        'Omit the prop entirely to render the card without an avatar.',
+      ].join(' '),
+      table: {
+        type: { summary: 'Avatar.Props' },
+      },
+    },
+    'rows': {
+      control: 'object',
+      description: 'Array of `{ label, value, note? }` — each is rendered as a `Row`, separated by `Separator`s.',
+      table: {
+        type: { summary: 'DataViewCard.RowData[]' },
+      },
+    },
+    'disabled': {
+      control: 'boolean',
+      description: 'Disables click handling and applies `aria-disabled="true"`.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'onClick': {
+      control: false,
+      description: 'When set, the whole card becomes a `role="button"` and `aria-label` (or `aria-labelledby`) is required.',
+      table: {
+        type: { summary: '(e: MouseEvent<HTMLElement>) => void' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: 'Required when `onClick` is set (unless `aria-labelledby` is provided).',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'aria-labelledby': {
+      control: false,
+      description: 'Alternative to `aria-label` — point to a visible element\'s id when one exists.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'className': {
+      control: false,
+      description: 'Additional CSS class names on the underlying Card root.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+  },
+} satisfies Meta<typeof DataViewCard>;
+
+export default meta;
+type Story = StoryObj<typeof DataViewCard>;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const GridTemplate = () => (
+  <div
+    style={{
+      display: 'grid',
+      gap: 'var(--spacing-large)',
+      gridTemplateColumns: 'repeat(auto-fill, minmax(320px, 1fr))',
+    }}
+  >
+    <DataViewCard
+      aria-label="View Dorothy Zbornak"
+      avatar={{ src: `${AVATAR_BASE}47`, alt: 'Dorothy Zbornak' }}
+      header="Dorothy Zbornak"
+      onClick={() => {}}
+      rows={[
+        { label: 'Year', value: 'Year 13' },
+        { label: 'Form', value: 'Form 13DZ' },
+        { label: 'DOB', value: '20 May 1932' },
+      ]}
+    />
+    <DataViewCard
+      aria-label="View Rose Nylund"
+      avatar={{ src: `${AVATAR_BASE}5`, alt: 'Rose Nylund' }}
+      header="Rose Nylund"
+      onClick={() => {}}
+      rows={[
+        { label: 'Year', value: 'Year 12' },
+        { label: 'Form', value: 'Form 12RN' },
+        { label: 'DOB', value: '21 Jul 1928' },
+      ]}
+    />
+    <DataViewCard
+      aria-label="View Blanche Devereaux"
+      avatar={{ src: `${AVATAR_BASE}49`, alt: 'Blanche Devereaux' }}
+      header="Blanche Devereaux"
+      onClick={() => {}}
+      rows={[
+        { label: 'Year', value: 'Year 13' },
+        { label: 'Form', value: 'Form 13BD' },
+        { label: 'DOB', value: '17 Aug 1934' },
+      ]}
+    />
+    <DataViewCard
+      aria-label="View Sophia Petrillo"
+      avatar={{ initials: 'SP', alt: 'Sophia Petrillo' }}
+      header="Sophia Petrillo"
+      onClick={() => {}}
+      rows={[
+        { label: 'Year', value: 'Year 13' },
+        { label: 'Form', value: 'Form 13SP' },
+        { label: 'DOB', value: '17 Mar 1908' },
+      ]}
+    />
+    <DataViewCard
+      aria-label="View Bella Swan"
+      avatar={{ src: `${AVATAR_BASE}21`, alt: 'Bella Swan' }}
+      header="Bella Swan"
+      onClick={() => {}}
+      rows={[
+        { label: 'Year', value: 'Year 11' },
+        { label: 'Form', value: 'Form 11FH' },
+        { label: 'DOB', value: '13 Sep 1987' },
+      ]}
+    />
+    <DataViewCard
+      aria-label="View Jacob Black"
+      avatar={{ initials: 'JB', alt: 'Jacob Black' }}
+      header="Jacob Black"
+      onClick={() => {}}
+      rows={[
+        { label: 'Year', value: 'Year 11' },
+        { label: 'Form', value: 'Form 11LP' },
+        { label: 'DOB', value: '14 Jan 1990' },
+      ]}
+    />
+  </div>
+);
+
+const NoAvatarTemplate = () => (
+  <DataViewCard
+    aria-label="View record A1024"
+    header="Record A1024"
+    onClick={() => {}}
+    rows={[
+      { label: 'Type', value: 'Behaviour incident' },
+      { label: 'Reported', value: '14 Mar 2026' },
+      { label: 'Status', value: 'Open' },
+    ]}
+  />
+);
+
+const StaticTemplate = () => (
+  <DataViewCard
+    avatar={{ src: `${AVATAR_BASE}58`, alt: 'Edward Cullen' }}
+    header="Edward Cullen"
+    rows={[
+      { label: 'Year', value: 'Year 11' },
+      { label: 'Form', value: 'Form 11FH' },
+      { label: 'DOB', value: '20 Jun 1901' },
+    ]}
+  />
+);
+
+const DisabledTemplate = () => (
+  <DataViewCard
+    aria-label="View Alice Cullen"
+    avatar={{ src: `${AVATAR_BASE}25`, alt: 'Alice Cullen' }}
+    disabled
+    header="Alice Cullen"
+    onClick={() => {}}
+    rows={[
+      { label: 'Year', value: 'Year 12' },
+      { label: 'Form', value: 'Form 12FH' },
+      { label: 'DOB', value: '06 Jan 1901' },
+    ]}
+  />
+);
+
+const WithNoteTemplate = () => (
+  <DataViewCard
+    aria-label="View Blanche Devereaux"
+    avatar={{ src: `${AVATAR_BASE}49`, alt: 'Blanche Devereaux' }}
+    header="Blanche Devereaux"
+    onClick={() => {}}
+    rows={[
+      { label: 'Year', value: 'Year 13', note: 'Glamour studies major' },
+      { label: 'Form', value: 'Form 13BD', note: 'Tutor: Ms Petrillo' },
+      { label: 'DOB', value: '17 Aug 1934' },
+    ]}
+  />
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      'aria-label': 'View Dorothy Zbornak',
+      'avatar': { src: `${AVATAR_BASE}47`, alt: 'Dorothy Zbornak' },
+      'header': 'Dorothy Zbornak',
+      'onClick': () => {},
+      'rows': sampleRows,
+    },
+    render: args => <DataViewCard {...args} />,
+  },
+  [
+    'The interactive canvas — every prop is wired to the Controls panel below.',
+    'Tweak the `rows` array, swap the `avatar` for `{ src: \'…\' }` to test imagery, or remove `onClick` to flip the card to a static figure.',
+  ].join(' '),
+);
+
+export const Grid: Story = withDescription(
+  {
+    render: GridTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DataViewCard } from '@arbor-education/design-system.components';
+
+function StudentGrid() {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gap: 'var(--spacing-large)',
+        gridTemplateColumns: 'repeat(auto-fill, minmax(320px, 1fr))',
+      }}
+    >
+      <DataViewCard
+        aria-label="View Dorothy Zbornak"
+        avatar={{ src: 'https://i.pravatar.cc/150?img=47', alt: 'Dorothy Zbornak' }}
+        header="Dorothy Zbornak"
+        onClick={() => {}}
+        rows={[
+          { label: 'Year', value: 'Year 13' },
+          { label: 'Form', value: 'Form 13DZ' },
+          { label: 'DOB', value: '20 May 1932' },
+        ]}
+      />
+      {/* …more cards… */}
+    </div>
+  );
+}
+export default StudentGrid;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The canonical browse-students layout: a responsive CSS grid of clickable cards (`auto-fill, minmax(320px, 1fr)`).',
+    'Each card has a unique `aria-label` describing the record it links to.',
+  ].join(' '),
+);
+
+export const NoAvatar: Story = withDescription(
+  {
+    render: NoAvatarTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'When the record has no portrait or logo, simply omit the `avatar` prop —',
+    'the layout collapses to header-plus-rows without leaving an empty placeholder.',
+  ].join(' '),
+);
+
+export const Static: Story = withDescription(
+  {
+    render: StaticTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'Without an `onClick`, the card renders as a static `<figure>` with no `role="button"` and no chevron icon.',
+    'Use this when the card is a read-only summary alongside a separate action button.',
+  ].join(' '),
+);
+
+export const Disabled: Story = withDescription(
+  {
+    render: DisabledTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'The `disabled` prop suppresses click handling and sets `aria-disabled="true"` on the underlying Card.',
+    'The card still renders fully and remains focusable — only the click is suppressed.',
+  ].join(' '),
+);
+
+export const WithNote: Story = withDescription(
+  {
+    render: WithNoteTemplate,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'Each row supports an optional `note` (italicised by `Row`) for secondary context — e.g. tutor name, promotion date.',
+    'Leave it off when not needed; rows render at consistent height regardless.',
+  ].join(' '),
+);

package/src/components/dataViewCard/DataViewCard.test.tsx

@@ -0,0 +1,127 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { describe, expect, test, vi } from 'vitest';
+import { DataViewCard } from './DataViewCard';
+
+const baseRows = [
+  { label: 'Year', value: 'Year 8' },
+  { label: 'Form', value: 'Form 8LR' },
+  { label: 'DOB', value: '29 Jan 2012' },
+];
+
+describe('DataViewCard', () => {
+  test('renders the header as an h4', () => {
+    render(<DataViewCard header="Christopher Longbottom" rows={baseRows} />);
+
+    expect(screen.getByRole('heading', { level: 4 })).toHaveTextContent('Christopher Longbottom');
+  });
+
+  test('renders every row label and value', () => {
+    render(<DataViewCard header="Christopher Longbottom" rows={baseRows} />);
+
+    baseRows.forEach((row) => {
+      expect(screen.getByText(row.label)).toBeInTheDocument();
+      expect(screen.getByText(row.value)).toBeInTheDocument();
+    });
+  });
+
+  test('renders a row note when provided', () => {
+    render(
+      <DataViewCard
+        header="Christopher Longbottom"
+        rows={[{ label: 'Year', value: 'Year 8', note: 'Promoted Sept 2024' }]}
+      />,
+    );
+
+    expect(screen.getByText('Promoted Sept 2024')).toBeInTheDocument();
+  });
+
+  test('renders an Avatar when avatar props are provided', () => {
+    const { container } = render(
+      <DataViewCard
+        avatar={{ initials: 'CL', alt: 'Christopher Longbottom avatar' }}
+        header="Christopher Longbottom"
+        rows={baseRows}
+      />,
+    );
+
+    expect(container.querySelector('.ds-avatar')).toBeInTheDocument();
+    expect(screen.getByText('CL')).toBeInTheDocument();
+  });
+
+  test('omits the Avatar when no avatar props are provided', () => {
+    const { container } = render(
+      <DataViewCard header="Christopher Longbottom" rows={baseRows} />,
+    );
+
+    expect(container.querySelector('.ds-avatar')).not.toBeInTheDocument();
+  });
+
+  test('uses the Card shell as a button when onClick is provided', () => {
+    const handleClick = vi.fn();
+
+    render(
+      <DataViewCard
+        aria-label="View Christopher Longbottom"
+        header="Christopher Longbottom"
+        onClick={handleClick}
+        rows={baseRows}
+      />,
+    );
+
+    const card = screen.getByRole('button', { name: 'View Christopher Longbottom' });
+    fireEvent.click(card);
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  test('renders as a static figure when not clickable', () => {
+    const { container } = render(
+      <DataViewCard header="Christopher Longbottom" rows={baseRows} />,
+    );
+
+    const card = container.querySelector('figure');
+
+    expect(card).toBeInTheDocument();
+    expect(card).not.toHaveAttribute('role', 'button');
+  });
+
+  test('does not invoke onClick when disabled', () => {
+    const handleClick = vi.fn();
+
+    render(
+      <DataViewCard
+        aria-label="View Christopher Longbottom"
+        disabled
+        header="Christopher Longbottom"
+        onClick={handleClick}
+        rows={baseRows}
+      />,
+    );
+
+    const card = screen.getByLabelText('View Christopher Longbottom');
+    fireEvent.click(card);
+
+    expect(handleClick).not.toHaveBeenCalled();
+    expect(card).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  test('renders no rows when an empty rows array is provided', () => {
+    render(<DataViewCard header="Christopher Longbottom" rows={[]} />);
+
+    expect(screen.getByRole('heading', { level: 4 })).toBeInTheDocument();
+    expect(screen.queryByText('Year')).not.toBeInTheDocument();
+  });
+
+  test('forwards a custom className to the underlying Card', () => {
+    const { container } = render(
+      <DataViewCard
+        className="custom-data-view-card"
+        header="Christopher Longbottom"
+        rows={baseRows}
+      />,
+    );
+
+    expect(container.querySelector('.custom-data-view-card')).toBeInTheDocument();
+  });
+});

package/src/components/dataViewCard/DataViewCard.tsx

@@ -0,0 +1,62 @@
+import classNames from 'classnames';
+import { Fragment } from 'react';
+import { Avatar } from 'Components/avatar/Avatar';
+import { Card, getCardInteractionProps } from 'Components/card/Card';
+import { Heading } from 'Components/heading/Heading';
+import { Row } from 'Components/row/Row';
+import { Separator } from 'Components/separator/Separator';
+
+export type DataViewCardRow = Row.Props;
+
+type DataViewCardBaseProps = {
+  className?: string;
+  header: string;
+  avatar?: Avatar.Props;
+  rows: DataViewCardRow[];
+  disabled?: boolean;
+};
+
+export type DataViewCardProps = DataViewCardBaseProps & Card.InteractionProps;
+
+export const DataViewCard = (props: DataViewCardProps): React.JSX.Element => {
+  const { className, header, avatar, rows, disabled = false } = props;
+
+  return (
+    <Card
+      {...getCardInteractionProps(props)}
+      className={classNames('ds-data-view-card__container', className)}
+      disabled={disabled}
+      spacing="default"
+    >
+      <article className="ds-data-view-card">
+        {avatar && (
+          <Avatar
+            size="extra-large"
+            {...avatar}
+            className={classNames(
+              'ds-data-view-card__avatar',
+              avatar.className,
+            )}
+          />
+        )}
+        <div className="ds-data-view-card__content">
+          <Heading level={4} className="ds-data-view-card__header">
+            {header}
+          </Heading>
+          <Separator />
+          {rows.map((row, index) => (
+            <Fragment key={`${row.label}-${index}`}>
+              <Row {...row} />
+              {index < rows.length - 1 && <Separator />}
+            </Fragment>
+          ))}
+        </div>
+      </article>
+    </Card>
+  );
+};
+
+export namespace DataViewCard {
+  export type Props = DataViewCardProps;
+  export type RowData = DataViewCardRow;
+}

package/src/components/dataViewCard/dataViewCard.scss

@@ -0,0 +1,25 @@
+.ds-data-view-card {
+  display: flex;
+  flex-direction: row;
+  align-items: flex-start;
+  gap: var(--card-spacing-gap-horizontal);
+  width: 100%;
+}
+
+.ds-data-view-card__avatar {
+  flex-shrink: 0;
+}
+
+.ds-data-view-card__content {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.ds-data-view-card__header {
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}