@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/banner/Banner.stories.tsx

@@ -483,14 +483,18 @@ const ContentGuidelinesTemplate = () => (
 export const Default: Story = withDescription(
   {
     args: {
-      level: BANNER_LEVEL.NEUTRAL,
-      text: "You are viewing last year's data. Switch to the current academic year to make changes.",
+      level: BANNER_LEVEL.WARNING,
+      title: 'Reporting period closing soon',
+      text: 'The census submission deadline is Friday 17 April at 5pm.',
+      buttonText: 'Review exclusions',
+      buttonOnClick: fn(),
     },
     render: args => <Banner {...args} />,
   },
   [
     'The interactive canvas story — every prop is wired to the **Controls** panel below.',
-    'Use the controls to explore all four levels, toggle `hideIcon`, add a `title`, provide `buttonText`,',
+    'The canonical Banner structure: icon + title + body + CTA button.',
+    'Use the controls to explore all four levels, toggle `hideIcon`, change `title`, `text`, `buttonText`,',
     'and override the default `icon`. Start by changing `level` to see the colour scheme shift.',
   ].join(' '),
 );

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

@@ -1,55 +1,485 @@
 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 { fn } from 'storybook/test';
 import { Card } from './Card';
 
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`Card` is a surface component for grouping related content into a visually distinct container.',
+  'It comes in two modes: **static** (read-only content display) and **interactive** (clickable, with',
+  '`role="button"` semantics, keyboard support, and a chevron/arrow icon).',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Grouping a summary of related data that belongs together visually (attendance overview, pupil profile, KPI)',
+  '- As a navigational element that takes the user to a detail view — use the interactive variant with `onClick`',
+  '- When you need a consistent bordered surface that responds to the design system\'s spacing and colour tokens',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| A simple key–value summary | [`Row`](?path=/docs/components-row--docs) inside a `Section` |',
+  '| A list of selectable items | `RadioGroup` or a selection list pattern |',
+  '| Full-page layout regions | Semantic HTML (`<section>`, `<article>`) with appropriate headings |',
+  '| Buttons or links inside a clickable card | Do not — nest no interactive elements inside an interactive card |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Interactive cards require an accessible name.**',
+  '`onClick` makes the card a `role="button"` element. Without `aria-label` or `aria-labelledby`,',
+  'the component throws in development and logs an error in production. Always provide one.',
+  '',
+  '```tsx',
+  '// ✅ Correct — aria-label provided',
+  '<Card onClick={handleClick} aria-label="View Alice Johnson\'s attendance record">',
+  '  ...',
+  '</Card>',
+  '',
+  '// ✅ Correct — aria-labelledby pointing to a heading inside the card',
+  '<Card onClick={handleClick} aria-labelledby="card-heading-alice">',
+  '  <h3 id="card-heading-alice">Alice Johnson</h3>',
+  '  ...',
+  '</Card>',
+  '',
+  '// ❌ Wrong — no accessible name on an interactive card',
+  '<Card onClick={handleClick}>...</Card>',
+  '```',
+  '',
+  '**`disabled` only has effect when `onClick` is also provided.**',
+  'Passing `disabled` to a static card (no `onClick`) is a no-op. The disabled state sets `aria-disabled={true}`',
+  'and suppresses click/keyboard handling — it does NOT remove the card from the tab order (use `tabIndex={-1}`',
+  'via `className` overrides if needed).',
+  '',
+  '**Never put interactive elements inside a clickable card.**',
+  'Nesting `<Button>`, `<a>`, `<input>` etc. inside an interactive card creates nested interactives — a WCAG 2.1',
+  'failure (1.3.1). If your card content needs buttons, use a static card.',
+  '',
+  '**The chevron/arrow icon is managed automatically.**',
+  'Clickable cards render a `chevron-right` icon that swaps to `arrow-right` on hover. Do not render your',
+  'own navigation icon inside the card — it will be duplicated.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Interactive cards receive `role="button"` and `tabIndex={0}` automatically.',
+  '- Enter and Space trigger the `onClick` handler via keyboard.',
+  '- `aria-label` or `aria-labelledby` is **required** on interactive cards (throws in dev without it).',
+  '- For static cards, an accessible label is recommended for screen reader context but not enforced.',
+  '- `aria-disabled={true}` is set on disabled interactive cards — assistive technology announces the',
+  '  disabled state while the element remains in the tab order.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Card } from '@arbor-education/design-system.components';",
+  "import type { CardProps } from '@arbor-education/design-system.components';",
+  '',
+  '// Or via namespace:',
+  'type MyCardProps = Card.Props;',
+  'type MyInteractiveProps = Card.InteractiveProps;',
+  'type MyAccessibleNameProps = Card.AccessibleNameProps;',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Section](?path=/docs/components-section--docs) · [Row](?path=/docs/components-row--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — toggle `disabled` or switch `spacing` to see the card update in real time.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function CardDocsPage() {
+  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 meta = {
   title: 'Components/Card',
   component: Card,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: CardDocsPage },
+  },
+  argTypes: {
+    'spacing': {
+      control: { type: 'radio' },
+      options: ['default', 'dense'],
+      description: 'Padding variant. `"dense"` uses `--spacing-small` for compact layouts.',
+      table: {
+        type: { summary: "'default' | 'dense'" },
+        defaultValue: { summary: "'default'" },
+      },
+    },
+    'disabled': {
+      control: 'boolean',
+      description: 'Disables an interactive card — sets `aria-disabled={true}` and suppresses click/keyboard handling. Has no effect on static cards (no `onClick`).',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: '**Required on interactive cards** (unless `aria-labelledby` is provided). The accessible name announced by screen readers as the button label.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'aria-labelledby': {
+      control: false,
+      description: 'ID of a visible element (typically a heading inside the card) whose text becomes the accessible name. Use as an alternative to `aria-label` when the card already contains a heading.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'onClick': {
+      control: false,
+      description: 'Click handler. Providing this prop switches the card to **interactive mode** — it gains `role="button"`, `tabIndex={0}`, and a chevron/arrow icon. Requires `aria-label` or `aria-labelledby`.',
+      table: {
+        type: { summary: '(e: MouseEvent<HTMLElement>) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'onKeyDown': {
+      control: false,
+      description: 'Optional keydown handler called after the built-in Enter/Space handling. Only fires when the card is interactive and not disabled.',
+      table: {
+        type: { summary: '(e: KeyboardEvent<HTMLElement>) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'children': {
+      control: false,
+      description: 'Content rendered inside the card body.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    'className': {
+      control: false,
+      description: 'Additional CSS class names on the root `<figure>` element.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+  },
 } satisfies Meta<typeof Card>;
 
-type Story = StoryObj<typeof meta>;
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+
+const SampleContent = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+    <p className="ds-text ds-text--heading-small" style={{ margin: 0 }}>Attendance summary</p>
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      View the latest attendance and behaviour insights for this cohort.
+    </p>
+  </div>
+);
+
+const WithAriaLabelledByTemplate = () => (
+  <div style={{ maxWidth: '400px' }}>
+    <Card
+      onClick={fn()}
+      aria-labelledby="card-story-heading"
+    >
+      <p
+        id="card-story-heading"
+        className="ds-text ds-text--heading-small"
+        style={{ margin: 0 }}
+      >
+        Pupil progress report
+      </p>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Summer term 2024 — 8 pupils flagged for review.
+      </p>
+    </Card>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      'aria-label': 'Attendance summary',
+      'onClick': fn(),
+      'spacing': 'default',
+      'disabled': false,
+    },
+    render: args => (
+      <div style={{ maxWidth: '400px' }}>
+        <Card {...args}>
+          <SampleContent />
+        </Card>
+      </div>
+    ),
+  },
+  'An interactive card — `onClick` is provided so the card has `role="button"` and shows a chevron icon. Toggle `disabled` in the **Controls** panel to see the disabled state. Switch `spacing` to `"dense"` for the compact variant.',
+);
+
+export const Static: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Card } from '@arbor-education/design-system.components';
 
-const sampleCardContent = (
-  <>
-    <h3>Attendance summary</h3>
-    <p>View the latest attendance and behaviour insights for this cohort.</p>
-  </>
+function StaticCardExample() {
+  return (
+    <Card aria-label="Attendance summary" style={{ maxWidth: '400px' }}>
+      <p>Attendance summary</p>
+      <p>View the latest attendance and behaviour insights for this cohort.</p>
+    </Card>
+  );
+}
+
+export default StaticCardExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <Card aria-label="Attendance summary">
+          <SampleContent />
+        </Card>
+      </div>
+    ),
+  },
+  'A static card — no `onClick` provided. No `role`, no `tabIndex`, no chevron icon. Use for displaying content that is not navigational.',
 );
 
-export const StaticCard: Story = {
-  args: {
-    'aria-label': 'Static summary card',
+export const Interactive: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Card } from '@arbor-education/design-system.components';
+
+function InteractiveCardExample() {
+  return (
+    <Card
+      onClick={() => console.log('card clicked')}
+      aria-label="View attendance summary"
+      style={{ maxWidth: '400px' }}
+    >
+      <p>Attendance summary</p>
+      <p>View the latest attendance and behaviour insights for this cohort.</p>
+    </Card>
+  );
+}
+
+export default InteractiveCardExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <Card
+          onClick={fn()}
+          aria-label="View attendance summary"
+        >
+          <SampleContent />
+        </Card>
+      </div>
+    ),
   },
-  render: args => (
-    <Card {...args}>
-      {sampleCardContent}
+  'An interactive card with `onClick`. The card receives `role="button"` and `tabIndex={0}`. A `chevron-right` icon appears on the right; it swaps to `arrow-right` on hover. Keyboard: Enter or Space triggers the click.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Card } from '@arbor-education/design-system.components';
+
+function DisabledCardExample() {
+  return (
+    <Card
+      onClick={() => console.log('never fires')}
+      aria-label="View attendance summary"
+      disabled
+      style={{ maxWidth: '400px' }}
+    >
+      <p>Attendance summary</p>
+      <p>This card is temporarily unavailable.</p>
     </Card>
-  ),
-};
-
-export const ClickableCard: Story = {
-  args: {
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Clickable card',
-  },
-  render: args => (
-    <Card {...args}>
-      {sampleCardContent}
+  );
+}
+
+export default DisabledCardExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <Card
+          onClick={fn()}
+          aria-label="View attendance summary"
+          disabled
+        >
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+            <p className="ds-text ds-text--heading-small" style={{ margin: 0 }}>Attendance summary</p>
+            <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+              This card is temporarily unavailable.
+            </p>
+          </div>
+        </Card>
+      </div>
+    ),
+  },
+  '`disabled` on an interactive card — `aria-disabled={true}` is set and click/keyboard handling is suppressed. `onClick` is still required to activate the disabled visual state. The card remains in the tab order.',
+);
+
+export const Dense: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Card } from '@arbor-education/design-system.components';
+
+function DenseCardExample() {
+  return (
+    <Card
+      spacing="dense"
+      aria-label="Pupil count"
+      style={{ maxWidth: '280px' }}
+    >
+      <p>Total pupils</p>
+      <p>247</p>
     </Card>
-  ),
-};
+  );
+}
 
-export const DenseCard: Story = {
-  args: {
-    'aria-label': 'Dense card',
-    'spacing': 'dense',
+export default DenseCardExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <Card spacing="dense" aria-label="Pupil count">
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+            <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>Total pupils</p>
+            <p className="ds-text ds-text--heading-large" style={{ margin: 0 }}>247</p>
+          </div>
+        </Card>
+      </div>
+    ),
   },
-  render: args => (
-    <Card {...args}>
-      {sampleCardContent}
+  '`spacing="dense"` replaces the default padding with `--spacing-small`. Use for compact KPI tiles or data-dense layouts where the default padding feels too spacious.',
+);
+
+export const WithAriaLabelledBy: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Card } from '@arbor-education/design-system.components';
+
+function WithAriaLabelledByExample() {
+  return (
+    <Card
+      onClick={() => console.log('card clicked')}
+      aria-labelledby="card-heading"
+      style={{ maxWidth: '400px' }}
+    >
+      <p id="card-heading">Pupil progress report</p>
+      <p>Summer term 2024 — 8 pupils flagged for review.</p>
     </Card>
-  ),
-};
+  );
+}
 
-export default meta;
+export default WithAriaLabelledByExample;
+`.trim(),
+        },
+      },
+    },
+    render: WithAriaLabelledByTemplate,
+  },
+  'Using `aria-labelledby` instead of `aria-label` — the card\'s accessible name is derived from the heading already visible in the content. Prefer this pattern when the card has a heading, to avoid repeating the same text in both `aria-label` and the heading.',
+);