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

package/src/components/articleCard/ArticleCard.stories.tsx

@@ -1,132 +1,545 @@
 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 { ArticleCard } from './ArticleCard';
 
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`ArticleCard` is a card variant for article and content listings. It combines an optional icon (in a left rail),',
+  'a heading, a paragraph, and an optional tag badge into a consistently-structured card.',
+  'Two interaction modes are supported: **linked** (the heading becomes a navigable `<a>`) and',
+  '**interactive shell** (the entire card is a click target via `onClick`).',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Displaying a navigable item in a list or grid — a help article, report, policy document, or resource link',
+  '- When each card represents one destination and needs an icon, heading, and optional description',
+  '- Use `href` (linked mode) when navigation follows a standard URL; use `onClick` (shell mode) when navigation is programmatic',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Displaying a metric or statistic | [`KPICard`](?path=/docs/components-card-kpicard--docs) |',
+  '| Full control over interior layout | [`Card`](?path=/docs/components-card--docs) directly |',
+  '| Icon + text without a card shell | [`IcoText`](?path=/docs/components-icotext--docs) |',
+  '| Selecting from a list (radio/checkbox semantics) | `RadioGroup` or selection list pattern |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Three mutually exclusive modes:**',
+  '',
+  '| Mode | When | Behaviour |',
+  '|---|---|---|',
+  '| **Linked** | `href` + `title` + `!disabled` | Title renders as `<a>` with full-card overlay |',
+  '| **Interactive shell** | `onClick` provided | Card gets `role="button"` and chevron icon |',
+  '| **Static** | Neither `href` nor `onClick` | Plain content display, no interaction |',
+  '',
+  '`href` and `onClick` are mutually exclusive — TypeScript enforces this via a discriminated union.',
+  '',
+  '**`disabled` suppresses the link in linked mode.** When `href` + `title` + `disabled=true` are all',
+  'present, no `<a>` element is rendered — the title appears as plain text. This is the most common gotcha.',
+  '',
+  '**`tagColor` without `tagText` does nothing.** The Tag only renders when `tagText` has a value.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- **Linked mode**: the `<a>` wrapping `title` is the accessible link target.',
+  '  If the title text is not self-descriptive, use `aria-label` to override the accessible name.',
+  '- **Shell mode**: `aria-label` or `aria-labelledby` is required when `onClick` is provided.',
+  '- **Decorative icons**: omit `iconScreenReaderText` — the icon is `aria-hidden="true"` automatically.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { ArticleCard } from '@arbor-education/design-system.components';",
+  "import type { ArticleCardProps } from '@arbor-education/design-system.components';",
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Card](?path=/docs/components-card--docs) · [KPICard](?path=/docs/components-card-kpicard--docs) · [IcoText](?path=/docs/components-icotext--docs) · [Tag](?path=/docs/components-tag--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.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function ArticleCardDocsPage() {
+  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/ArticleCard',
   component: ArticleCard,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: ArticleCardDocsPage },
+  },
+  argTypes: {
+    'title': {
+      control: 'text',
+      description: 'Card heading. In linked mode (`href` provided) this becomes the `<a>` element.',
+      table: { type: { summary: 'ReactNode' } },
+    },
+    'paragraph': {
+      control: 'text',
+      description: 'Body text rendered below the heading. Accepts `ReactNode` — can include inline links.',
+      table: { type: { summary: 'ReactNode' } },
+    },
+    'icon': {
+      control: { type: 'select' },
+      options: [undefined, 'eye', 'guardians', 'date', 'book-open', 'file', 'settings', 'info', 'triangle-alert'],
+      description: 'Icon displayed in the left rail via `IcoText.Icon`. Omit for icon-free layout.',
+      table: { type: { summary: 'IconName' } },
+    },
+    'iconColor': {
+      control: 'text',
+      description: 'Colour applied to the icon. Use a CSS token, e.g. `var(--color-semantic-info-600)`.',
+      table: { type: { summary: 'string' } },
+    },
+    'iconScreenReaderText': {
+      control: 'text',
+      description: 'Accessible label for the icon. Omit for decorative icons — they become `aria-hidden` automatically.',
+      table: { type: { summary: 'string' } },
+    },
+    'tagText': {
+      control: 'text',
+      description: 'Renders a `Tag` badge. Has no effect when empty.',
+      table: { type: { summary: 'string' } },
+    },
+    'tagColor': {
+      control: { type: 'select' },
+      options: [undefined, 'neutral', 'orange', 'blue', 'green', 'purple', 'teal', 'salmon', 'yellow'],
+      description: 'Colour variant for the `Tag` badge.',
+      table: { type: { summary: "'neutral' | 'orange' | 'blue' | 'green' | 'purple' | 'teal' | 'salmon' | 'yellow'" } },
+    },
+    'disabled': {
+      control: 'boolean',
+      description: 'Disables all interaction. In linked mode, suppresses the `<a>` even when `href` is provided.',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    'onClick': {
+      control: false,
+      description: 'Click handler. Mutually exclusive with `href`. Makes the entire card interactive (`role="button"`).',
+      table: { type: { summary: '(e: MouseEvent<HTMLElement>) => void' } },
+    },
+    'aria-label': {
+      control: 'text',
+      description: 'Accessible name. Required on interactive shell cards (when `onClick` is provided).',
+      table: { type: { summary: 'string' } },
+    },
+    'href': {
+      control: 'text',
+      description: 'URL. Mutually exclusive with `onClick`. When provided with `title` + `!disabled`, the title renders as a navigable `<a>`.',
+      table: { type: { summary: 'string' } },
+    },
+    'className': {
+      control: false,
+      description: 'Additional CSS class names on the root element.',
+      table: { type: { summary: 'string' } },
+    },
+  },
 } satisfies Meta<typeof ArticleCard>;
 
-type Story = StoryObj<typeof meta>;
+export default meta;
+type Story = StoryObj<typeof ArticleCard>;
 
-export const CardWithTitleAndParagraph: Story = {
-  args: {
-    'title': 'Title of Card',
-    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    'disabled': false,
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Clickable article card with title and paragraph',
-  },
-};
-
-export const CardWithTitleParagraphAndIcon: Story = {
-  args: {
-    'title': 'Title of Card',
-    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    'icon': 'eye',
-    'disabled': false,
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Clickable article card with title paragraph and icon',
-  },
-};
-
-export const TheEverythingCard: Story = {
-  args: {
-    'title': 'Title of Card',
-    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    'icon': 'eye',
-    'disabled': false,
-    'tagText': 'argle bargle',
-    'tagColor': 'orange',
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Clickable article card with all content',
+// ---------------------------------------------------------------------------
+// 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 } },
   },
-};
-
-export const CardWithTitleParagraphAndTag: Story = {
-  args: {
-    'title': 'Title of Card',
-    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    'disabled': false,
-    'tagText': 'argle bargle',
-    'tagColor': 'orange',
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Clickable article card with title paragraph and tag',
+});
+
+// ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+
+const LinkedDisabledTemplate = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', maxWidth: '400px' }}>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-small)', color: 'var(--color-grey-600)' }}>
+        Enabled — title renders as a link
+      </p>
+      <ArticleCard
+        href="/reports/attendance"
+        title="Autumn term attendance report"
+        paragraph="Published 14 Nov 2024 · Available to all staff"
+        icon="file"
+      />
+    </div>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-small)', color: 'var(--color-grey-600)' }}>
+        Disabled — link suppressed, title renders as plain text
+      </p>
+      <ArticleCard
+        href="/reports/attendance"
+        title="Autumn term attendance report"
+        paragraph="This report is not yet available."
+        icon="file"
+        disabled
+      />
+    </div>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      'title': 'Attendance overview',
+      'paragraph': 'View pupil attendance rates, trends, and intervention records for this academic year.',
+      'icon': 'guardians',
+      'disabled': false,
+      'onClick': fn(),
+      'aria-label': 'Attendance overview',
+    },
+    render: args => (
+      <div style={{ maxWidth: '400px' }}>
+        <ArticleCard {...args} />
+      </div>
+    ),
   },
-};
-
-export const CardWithTitleAndIcon: Story = {
-  args: {
-    'title': 'Title of Card',
-    'icon': 'eye',
-    'disabled': false,
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Clickable article card with title and icon',
+  'Interactive shell mode — `onClick` is provided so the whole card is a click target with `role="button"`. Toggle `disabled` in the Controls panel to see the dimmed state.',
+);
+
+export const Static: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArticleCard } from '@arbor-education/design-system.components';
+
+function StaticArticleCardExample() {
+  return (
+    <ArticleCard
+      title="Attendance overview"
+      paragraph="View pupil attendance rates and trends for this academic year."
+      icon="guardians"
+    />
+  );
+}
+export default StaticArticleCardExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <ArticleCard
+          title="Attendance overview"
+          paragraph="View pupil attendance rates and trends for this academic year."
+          icon="guardians"
+        />
+      </div>
+    ),
   },
-};
-
-export const CardWithParagraph: Story = {
-  args: {
-    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    'disabled': false,
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Clickable article card with paragraph',
+  'Static mode — no `href`, no `onClick`. The card renders as a plain surface with no role, no tab stop, and no chevron icon.',
+);
+
+export const WithTag: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArticleCard } from '@arbor-education/design-system.components';
+
+function WithTagExample() {
+  return (
+    <ArticleCard
+      title="Safeguarding policy"
+      paragraph="Updated September 2024 — mandatory reading for all staff."
+      icon="book-open"
+      tagText="Required"
+      tagColor="orange"
+    />
+  );
+}
+export default WithTagExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <ArticleCard
+          title="Safeguarding policy"
+          paragraph="Updated September 2024 — mandatory reading for all staff."
+          icon="book-open"
+          tagText="Required"
+          tagColor="orange"
+        />
+      </div>
+    ),
   },
-};
-
-export const ClickableDisabledCard: Story = {
-  args: {
-    'title': 'Title of Card',
-    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    'icon': 'eye',
-    'tagText': 'argle bargle',
-    'tagColor': 'orange',
-    'disabled': true,
-    'onClick': fn(),
-    'onKeyDown': fn(),
-    'aria-label': 'Disabled clickable article card',
+  'Adding `tagText` and `tagColor` renders a `Tag` badge. Use tags for status, category, or priority labels — e.g. "Required", "New", "Featured".',
+);
+
+export const FullComposition: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArticleCard } from '@arbor-education/design-system.components';
+
+function FullCompositionExample() {
+  return (
+    <ArticleCard
+      title="Spring term behaviour report"
+      paragraph="Incident trends, intervention outcomes, and recommendations for Year 10."
+      icon="triangle-alert"
+      iconColor="var(--color-semantic-warning-600)"
+      tagText="Pending review"
+      tagColor="yellow"
+      onClick={() => console.log('navigate to report')}
+      aria-label="Spring term behaviour report"
+    />
+  );
+}
+export default FullCompositionExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <ArticleCard
+          title="Spring term behaviour report"
+          paragraph="Incident trends, intervention outcomes, and recommendations for Year 10."
+          icon="triangle-alert"
+          iconColor="var(--color-semantic-warning-600)"
+          tagText="Pending review"
+          tagColor="yellow"
+          onClick={fn()}
+          aria-label="Spring term behaviour report"
+        />
+      </div>
+    ),
   },
-};
-
-export const UnclickableCard: Story = {
-  args: {
-    title: 'Title of Card',
-    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
-    icon: 'eye',
-    tagText: 'argle bargle',
-    tagColor: 'orange',
+  'All content props combined — icon + iconColor + title + paragraph + tag + interactive shell. This is the richest production pattern.',
+);
+
+export const LinkedMode: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArticleCard } from '@arbor-education/design-system.components';
+
+function LinkedModeExample() {
+  return (
+    <ArticleCard
+      href="/policies/attendance"
+      title="Attendance policy"
+      paragraph="School attendance policy for 2024/25 — includes statutory guidance and thresholds."
+      icon="book-open"
+      tagText="Policy"
+      tagColor="blue"
+    />
+  );
+}
+export default LinkedModeExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <ArticleCard
+          href="/policies/attendance"
+          title="Attendance policy"
+          paragraph="School attendance policy for 2024/25 — includes statutory guidance and thresholds."
+          icon="book-open"
+          tagText="Policy"
+          tagColor="blue"
+        />
+      </div>
+    ),
   },
-};
+  'Linked mode — `href` + `title` present. The heading renders as `<a href>` with a CSS `::after` overlay making the whole card surface clickable. The card shell has no `role="button"`.',
+);
+
+export const InteractiveShell: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArticleCard } from '@arbor-education/design-system.components';
 
-export const TextOnly: Story = {
-  args: {
-    title: 'Text-only article card',
-    paragraph: 'A compact way to present article-style content in the shared shell.',
+function InteractiveShellExample() {
+  return (
+    <ArticleCard
+      onClick={() => console.log('card clicked')}
+      aria-label="Year 10 progress report"
+      title="Year 10 progress report"
+      paragraph="Mid-year review — targets, attainment, and next steps."
+      icon="eye"
+    />
+  );
+}
+export default InteractiveShellExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <ArticleCard
+          onClick={fn()}
+          aria-label="Year 10 progress report"
+          title="Year 10 progress report"
+          paragraph="Mid-year review — targets, attainment, and next steps."
+          icon="eye"
+        />
+      </div>
+    ),
   },
-};
-
-export const LinkedArticle: Story = {
-  args: {
-    title: 'Primary article link',
-    href: '/articles/primary-article-link',
-    paragraph: (
-      <>
-        Read the full article or visit the
-        {' '}
-        <a href="/authors/design-system">author page</a>
-        .
-      </>
+  'Interactive shell mode — `onClick` provided. The whole card gets `role="button"` and `tabIndex={0}`. Use when navigation is programmatic (e.g. React Router `navigate`) rather than a standard URL.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArticleCard } from '@arbor-education/design-system.components';
+
+function DisabledExample() {
+  return (
+    <ArticleCard
+      onClick={() => {}}
+      aria-label="Summer term report — not yet available"
+      title="Summer term report"
+      paragraph="This report will be available at the end of term."
+      icon="file"
+      disabled
+    />
+  );
+}
+export default DisabledExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '400px' }}>
+        <ArticleCard
+          onClick={fn()}
+          aria-label="Summer term report — not yet available"
+          title="Summer term report"
+          paragraph="This report will be available at the end of term."
+          icon="file"
+          disabled
+        />
+      </div>
     ),
-    icon: 'eye',
-    tagText: 'Featured',
-    tagColor: 'green',
   },
-};
+  '`disabled=true` dims the card and suppresses all interaction. In interactive shell mode, `onClick` does not fire. The card is removed from the tab order.',
+);
 
-export default meta;
+export const LinkedDisabled: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArticleCard } from '@arbor-education/design-system.components';
+
+function LinkedDisabledExample() {
+  // When disabled=true, hasPrimaryLink becomes false — no <a> is rendered.
+  // The title appears as plain text even though href is provided.
+  return (
+    <ArticleCard
+      href="/reports/attendance"
+      title="Autumn term attendance report"
+      paragraph="This report is not yet available."
+      icon="file"
+      disabled
+    />
+  );
+}
+export default LinkedDisabledExample;
+`.trim(),
+        },
+      },
+    },
+    render: LinkedDisabledTemplate,
+  },
+  '**The most common gotcha.** When `disabled={true}` is combined with `href`, the primary link is suppressed — no `<a>` element is rendered. The title appears as plain text. The story shows enabled vs disabled side-by-side — inspect the DOM to confirm.',
+);