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

package/src/components/kpiCard/KPICard.stories.tsx

@@ -1,47 +1,492 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { KVPList } from 'Components/kvpList/KVPList';
-import { Progress } from 'Components/progress/Progress';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { fn } from 'storybook/test';
 import { KPICard } from './KPICard';
+import { Progress } from 'Components/progress/Progress';
+import { KVPList } from 'Components/kvpList/KVPList';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`KPICard` is a compact metric tile that surfaces a single key-performance indicator — a labelled value,',
+  'optionally expressed as a percentage, optionally followed by supplementary content.',
+  'It is built on `Card` with `spacing="dense"` and supports the same static/interactive modes.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Displaying a single headline figure — total pupils, attendance rate, behaviour incidents',
+  '- Dashboard or summary views where multiple KPIs sit side-by-side in a grid',
+  '- When the metric is navigational (click to drill down) — use the interactive variant with `onClick`',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Multiple related key–value pairs | [`KVPList`](?path=/docs/components-kvplist--docs) |',
+  '| Rich content card with text + image | [`ArticleCard`](?path=/docs/components-card-articlecard--docs) |',
+  '| Non-metric summary block | [`Card`](?path=/docs/components-card--docs) |',
+  '| A long label or multi-line value | `Card` with custom content |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`label` and `value` are required** — omitting either will produce a broken layout.',
+  'Both accept `ReactNode`, so you can render formatted numbers, icons, or short JSX.',
+  '',
+  '```tsx',
+  '<KPICard label="Total pupils" value={247} />',
+  '```',
+  '',
+  '**Interactive KPICards require an accessible name.**',
+  'When `onClick` is provided, the underlying `Card` requires either `aria-label` or `aria-labelledby`.',
+  'The component throws in development and logs a console error in production if neither is supplied.',
+  '',
+  '```tsx',
+  '// ✅ Correct',
+  '<KPICard',
+  '  label="Attendance"',
+  '  value={94.2}',
+  '  isPercentage',
+  '  onClick={handleClick}',
+  '  aria-label="View attendance details"',
+  '/>',
+  '',
+  '// ❌ Missing accessible name — throws in dev',
+  '<KPICard label="Attendance" value={94.2} onClick={handleClick} />',
+  '```',
+  '',
+  '**`isPercentage` appends `%` to the DOM via a `<span>`.** Do not include `%` in the `value` prop — it will be doubled.',
+  '',
+  '**`children` renders below the value row**, spanning the full card width.',
+  'Use it for trend indicators, progress bars, or supplementary `KVPList` data.',
+  '',
+  '**`disabled` only has effect when `onClick` is provided.**',
+  'Passing `disabled` to a static `KPICard` (no `onClick`) is a no-op.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Interactive cards receive `role="button"` and `tabIndex={0}` via the underlying `Card`',
+  '- Enter and Space trigger the `onClick` handler',
+  '- `aria-label` or `aria-labelledby` is **required** on interactive cards',
+  '- `aria-disabled={true}` is set on disabled interactive cards',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { KPICard } from '@arbor-education/design-system.components';",
+  "import type { KPICardProps } from '@arbor-education/design-system.components';",
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Card](?path=/docs/components-card--docs) · [ArticleCard](?path=/docs/components-card-articlecard--docs) · [KVPList](?path=/docs/components-kvplist--docs) · [Progress](?path=/docs/components-progress--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak `label`, `value`, `isPercentage`, or `disabled` to see the card update in real time.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function KPICardDocsPage() {
+  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/KPICard',
   component: KPICard,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: KPICardDocsPage },
+  },
+  argTypes: {
+    'label': {
+      control: 'text',
+      description: '**Required.** The metric label rendered above the value.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    'value': {
+      control: 'text',
+      description: '**Required.** The headline metric value. Do not include `%` — use `isPercentage` instead.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    'isPercentage': {
+      control: 'boolean',
+      description: 'Appends a `%` suffix (`<span class="ds-kpi-card__suffix">`) after the value. Do NOT include `%` in the `value` prop.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    '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' },
+      },
+    },
+    'onClick': {
+      control: false,
+      description: [
+        'Click handler. Providing this switches the card to **interactive mode** — it gains `role="button"`,',
+        '`tabIndex={0}`, and a chevron/arrow icon. Requires `aria-label` or `aria-labelledby`.',
+      ].join(' '),
+      table: {
+        type: { summary: '(e: MouseEvent<HTMLElement>) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: '**Required on interactive cards** (unless `aria-labelledby` is provided). Accessible name announced by screen readers.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'children': {
+      control: false,
+      description: 'Optional content rendered below the value row — use for progress bars, trend indicators, or supplementary `KVPList` data.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    'className': {
+      control: false,
+      description: 'Additional CSS class names on the root element.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+  },
 } satisfies Meta<typeof KPICard>;
 
-type Story = StoryObj<typeof meta>;
+export default meta;
+type Story = StoryObj<typeof KPICard>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
 
-export const Default: Story = {
-  args: {
-    label: 'KPI label text',
-    value: 'XX.X',
-    isPercentage: true,
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
   },
-  render: args => (
-    <KPICard {...args}>
-      <KVPList aria-label="Summary values">
-        <KVPList.Row orientation="horizontal">
-          <KVPList.Term>Bar label text</KVPList.Term>
-          <KVPList.Definition prominence="strong">XX.X</KVPList.Definition>
+});
+
+// ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+
+const WithChildrenTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <KPICard label="Attendance rate" value={94.2} isPercentage>
+      <KVPList>
+        <KVPList.Row>
+          <KVPList.Term>This week</KVPList.Term>
+          <KVPList.Definition>96.1%</KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row>
+          <KVPList.Term>Last week</KVPList.Term>
+          <KVPList.Definition>92.3%</KVPList.Definition>
         </KVPList.Row>
       </KVPList>
-      <KVPList aria-label="Progress values">
-        <KVPList.Row orientation="horizontal">
-          <KVPList.Term>Bar label text</KVPList.Term>
-          <KVPList.Definition prominence="neutral">X</KVPList.Definition>
-          <KVPList.Definition aria-hidden="true" isRow>
-            <Progress aria-label="Progress bar first" max={100} value={95} />
-          </KVPList.Definition>
+    </KPICard>
+  </div>
+);
+
+const WithProgressTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <KPICard label="Attendance rate" value={94.2} isPercentage>
+      <div style={{ marginTop: 'var(--spacing-small)' }}>
+        <Progress value={94.2} max={100} />
+      </div>
+    </KPICard>
+  </div>
+);
+
+const MultipleCardsTemplate = () => (
+  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 'var(--spacing-medium)' }}>
+    <KPICard label="Total pupils" value={247} />
+    <KPICard label="Attendance rate" value={94.2} isPercentage />
+    <KPICard label="Behaviour incidents" value={3} />
+    <KPICard label="Staff present" value={38} />
+    <KPICard label="Pupils on report" value={12} />
+    <KPICard label="Average mark" value={78} isPercentage />
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      label: 'Total pupils',
+      value: 247,
+      isPercentage: false,
+      disabled: false,
+    },
+    render: args => (
+      <div style={{ maxWidth: '320px' }}>
+        <KPICard {...args} />
+      </div>
+    ),
+  },
+  'The base KPICard — `label` and `value` are the only required props. Toggle `isPercentage` or `disabled` in **Controls**, or change the `label` and `value` text.',
+);
+
+export const AsPercentage: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KPICard } from '@arbor-education/design-system.components';
+
+function AsPercentageExample() {
+  return (
+    <KPICard
+      label="Attendance rate"
+      value={94.2}
+      isPercentage
+    />
+  );
+}
+export default AsPercentageExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '320px' }}>
+        <KPICard label="Attendance rate" value={94.2} isPercentage />
+      </div>
+    ),
+  },
+  '`isPercentage` appends a `%` suffix to the value. The `%` is rendered in a separate `<span>` — do NOT include it in the `value` prop or it will appear twice.',
+);
+
+export const WithChildren: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KPICard, KVPList } from '@arbor-education/design-system.components';
+
+function WithChildrenExample() {
+  return (
+    <KPICard label="Attendance rate" value={94.2} isPercentage>
+      <KVPList>
+        <KVPList.Row>
+          <KVPList.Term>This week</KVPList.Term>
+          <KVPList.Definition>96.1%</KVPList.Definition>
         </KVPList.Row>
-        <KVPList.Row orientation="horizontal">
-          <KVPList.Term>Bar label text</KVPList.Term>
-          <KVPList.Definition prominence="neutral">X</KVPList.Definition>
-          <KVPList.Definition aria-hidden="true" isRow>
-            <Progress aria-label="Progress bar second" max={100} value={95} />
-          </KVPList.Definition>
+        <KVPList.Row>
+          <KVPList.Term>Last week</KVPList.Term>
+          <KVPList.Definition>92.3%</KVPList.Definition>
         </KVPList.Row>
       </KVPList>
     </KPICard>
-  ),
-};
+  );
+}
+export default WithChildrenExample;
+`.trim(),
+        },
+      },
+    },
+    render: WithChildrenTemplate,
+  },
+  '`children` renders below the value row, spanning the full card width. Use it for trend breakdowns (`KVPList`), progress bars, or any supplementary metric context.',
+);
 
-export default meta;
+export const WithProgressBar: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KPICard, Progress } from '@arbor-education/design-system.components';
+
+function WithProgressBarExample() {
+  return (
+    <KPICard label="Attendance rate" value={94.2} isPercentage>
+      <Progress value={94.2} max={100} />
+    </KPICard>
+  );
+}
+export default WithProgressBarExample;
+`.trim(),
+        },
+      },
+    },
+    render: WithProgressTemplate,
+  },
+  'A `Progress` bar in `children` provides an at-a-glance visual indicator alongside the percentage value.',
+);
+
+export const Interactive: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KPICard } from '@arbor-education/design-system.components';
+
+function InteractiveExample() {
+  return (
+    <KPICard
+      label="Total pupils"
+      value={247}
+      onClick={() => console.log('navigate to pupils list')}
+      aria-label="View all pupils"
+    />
+  );
+}
+export default InteractiveExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '320px' }}>
+        <KPICard
+          label="Total pupils"
+          value={247}
+          onClick={fn()}
+          aria-label="View all pupils"
+        />
+      </div>
+    ),
+  },
+  'With `onClick`, the card becomes interactive — `role="button"`, `tabIndex={0}`, and a chevron/arrow icon appear. `aria-label` is required and must describe the navigation destination.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KPICard } from '@arbor-education/design-system.components';
+
+function DisabledExample() {
+  return (
+    <KPICard
+      label="Behaviour incidents"
+      value={3}
+      onClick={() => console.log('never fires')}
+      aria-label="View behaviour incidents"
+      disabled
+    />
+  );
+}
+export default DisabledExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '320px' }}>
+        <KPICard
+          label="Behaviour incidents"
+          value={3}
+          onClick={fn()}
+          aria-label="View behaviour incidents"
+          disabled
+        />
+      </div>
+    ),
+  },
+  '`disabled` on an interactive card — `aria-disabled={true}` is set and click/keyboard handling is suppressed. `onClick` must still be provided to activate the disabled visual state.',
+);
+
+export const MultipleCards: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KPICard } from '@arbor-education/design-system.components';
+
+function MultipleCardsExample() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 'var(--spacing-medium)' }}>
+      <KPICard label="Total pupils" value={247} />
+      <KPICard label="Attendance rate" value={94.2} isPercentage />
+      <KPICard label="Behaviour incidents" value={3} />
+    </div>
+  );
+}
+export default MultipleCardsExample;
+`.trim(),
+        },
+      },
+    },
+    render: MultipleCardsTemplate,
+  },
+  'Multiple `KPICard` tiles in a CSS grid — the typical dashboard layout. Each card is self-contained and can independently be static or interactive.',
+);