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

package/src/components/icoText/IcoText.stories.tsx

@@ -1,47 +1,458 @@
 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 { IcoText } from './IcoText';
 
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`IcoText` is a compound layout component that pairs an icon in a left rail with a heading and/or paragraph.',
+  'It is the canonical icon-plus-text primitive in this design system — used internally by `ArticleCard`',
+  'and available for direct use in any context that needs an icon anchoring labelled content.',
+].join(' ');
+
+const ICON_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `name` | `IconName` | — | **Required.** The icon identifier |',
+  '| `size` | `12 \\| 16 \\| 24` | `24` | Icon size in pixels |',
+  '| `color` | `string` | — | Icon colour — use a CSS token e.g. `var(--color-grey-600)` |',
+  '| `screenReaderText` | `string` | — | Accessible label. Omit for decorative icons (icon becomes `aria-hidden`) |',
+  '| `className` | `string` | — | Additional CSS classes |',
+].join('\n');
+
+const HEADING_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | **Required.** Heading text |',
+  '| `...HTMLAttributes<h4>` | | | All standard heading element attributes forwarded |',
+].join('\n');
+
+const PARAGRAPH_PROPS = [
+  '| Prop | Type | Default | Description |',
+  '|---|---|---|---|',
+  '| `children` | `ReactNode` | — | **Required.** Paragraph text |',
+  '| `...HTMLAttributes<p>` | | | All standard paragraph element attributes forwarded |',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Pairing a meaningful icon with a short heading and/or description — attendance alerts, feature blurbs, help text',
+  '- Inside panels, list items, or cards where an icon anchors the content',
+  '- As the building block for `ArticleCard` icon-rail layouts',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Content inside a navigable card | [`ArticleCard`](?path=/docs/components-card-articlecard--docs) |',
+  '| Icon with no text | [`Icon`](?path=/docs/components-icon--docs) directly |',
+  '| Long-form prose | Semantic HTML `<p>` with a separate heading |',
+  '| Interactive element | Wrap `IcoText` inside a `Card` or `Button` — never add `onClick` to `IcoText` itself |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`IcoText.Icon` is automatically hoisted to the left rail** regardless of position in JSX.',
+  'The root inspects `children`, pulls out any `IcoText.Icon` elements into a flex-shrink-0 left column,',
+  'and places all other children (Heading, Paragraph) in the content column.',
+  '',
+  '```tsx',
+  '<IcoText>',
+  '  <IcoText.Icon name="guardians" />',
+  '  <IcoText.Heading>Year 9 Attendance</IcoText.Heading>',
+  '  <IcoText.Paragraph>28 pupils · 94.2% this term</IcoText.Paragraph>',
+  '</IcoText>',
+  '```',
+  '',
+  '**`IcoText.Heading` always renders as `<h4>`.** There is no `level` prop. Verify your document',
+  'heading hierarchy is correct before using `IcoText` as a standalone heading.',
+  '',
+  '**Omit `screenReaderText` for decorative icons.** The icon is rendered with `aria-hidden="true"`',
+  'when `screenReaderText` is absent. The heading or surrounding text should carry the accessible meaning.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Decorative icons (no `screenReaderText`): `aria-hidden="true"` — screen readers skip them',
+  '- Meaningful icons: provide `screenReaderText` so the icon has an accessible label',
+  '- `IcoText.Heading` renders `<h4>` — verify your document heading hierarchy',
+  '- `IcoText.Paragraph` renders `<p>` — semantically appropriate for supporting text',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { IcoText } from '@arbor-education/design-system.components';",
+  "import type { IcoTextProps, IcoTextIconProps, IcoTextHeadingProps, IcoTextParagraphProps } from '@arbor-education/design-system.components';",
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[ArticleCard](?path=/docs/components-card-articlecard--docs) · [Icon](?path=/docs/components-icon--docs) · [Card](?path=/docs/components-card--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 IcoTextDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>IcoText.Icon props</DocHeading>
+      <Markdown>{ICON_PROPS}</Markdown>
+      <DocHeading>IcoText.Heading props</DocHeading>
+      <Markdown>{HEADING_PROPS}</Markdown>
+      <DocHeading>IcoText.Paragraph props</DocHeading>
+      <Markdown>{PARAGRAPH_PROPS}</Markdown>
+      <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/IcoText',
   component: IcoText,
+  tags: ['autodocs'],
   parameters: {
-    docs: {
-      description: {
-        component:
-          'Use `IcoText.Icon` as a direct child of `IcoText` so it is hoisted into the leading icon rail.',
-      },
+    layout: 'padded',
+    docs: { page: IcoTextDocsPage },
+  },
+  argTypes: {
+    className: {
+      control: false,
+      description: 'Additional CSS class names on the root `div.ds-ico-text` element.',
+      table: { type: { summary: 'string' } },
+    },
+    children: {
+      control: false,
+      description: 'Compose using `IcoText.Icon`, `IcoText.Heading`, and `IcoText.Paragraph` sub-components.',
+      table: { type: { summary: 'ReactNode' } },
     },
   },
 } satisfies Meta<typeof IcoText>;
 
-type Story = StoryObj<typeof meta>;
+export default meta;
+type Story = StoryObj<typeof IcoText>;
+
+// ---------------------------------------------------------------------------
+// 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 IconSizesTemplate = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+    {([12, 16, 24] as const).map(size => (
+      <div key={size}>
+        <p className="ds-text" style={{ margin: '0 0 var(--spacing-small)', color: 'var(--color-grey-600)' }}>
+          {`size={${size}}`}
+        </p>
+        <IcoText>
+          <IcoText.Icon name="guardians" size={size} />
+          <IcoText.Heading>Year 9 Attendance</IcoText.Heading>
+          <IcoText.Paragraph>28 pupils · 94.2% average this term</IcoText.Paragraph>
+        </IcoText>
+      </div>
+    ))}
+  </div>
+);
+
+const IconColorsTemplate = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xlarge)' }}>
+    {[
+      { color: 'var(--color-semantic-info-600)', label: 'Info — var(--color-semantic-info-600)' },
+      { color: 'var(--color-semantic-success-600)', label: 'Success — var(--color-semantic-success-600)' },
+      { color: 'var(--color-semantic-warning-600)', label: 'Warning — var(--color-semantic-warning-600)' },
+      { color: 'var(--color-semantic-destructive-600)', label: 'Destructive — var(--color-semantic-destructive-600)' },
+    ].map(({ color, label }) => (
+      <div key={color}>
+        <p className="ds-text" style={{ margin: '0 0 var(--spacing-small)', color: 'var(--color-grey-600)' }}>
+          {label}
+        </p>
+        <IcoText>
+          <IcoText.Icon name="triangle-alert" color={color} />
+          <IcoText.Heading>Attendance alert</IcoText.Heading>
+          <IcoText.Paragraph>3 pupils below 90% this half-term</IcoText.Paragraph>
+        </IcoText>
+      </div>
+    ))}
+  </div>
+);
+
+const MultipleParagraphsTemplate = () => (
+  <IcoText>
+    <IcoText.Icon name="date" />
+    <IcoText.Heading>Parents&apos; evening — Tuesday 14 May</IcoText.Heading>
+    <IcoText.Paragraph>4:00 pm – 7:00 pm · Main Hall</IcoText.Paragraph>
+    <IcoText.Paragraph>Appointments available every 10 minutes. Please arrive 5 minutes early.</IcoText.Paragraph>
+  </IcoText>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    render: () => (
+      <IcoText>
+        <IcoText.Icon name="guardians" />
+        <IcoText.Heading>Year 9 Attendance</IcoText.Heading>
+        <IcoText.Paragraph>28 pupils · 94.2% average this term</IcoText.Paragraph>
+      </IcoText>
+    ),
+  },
+  'The full canonical composition — `IcoText.Icon` in the left rail, `IcoText.Heading` and `IcoText.Paragraph` in the content column.',
+);
+
+export const HeadingOnly: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { IcoText } from '@arbor-education/design-system.components';
+
+function HeadingOnlyExample() {
+  return (
+    <IcoText>
+      <IcoText.Icon name="book-open" />
+      <IcoText.Heading>Assessment policy</IcoText.Heading>
+    </IcoText>
+  );
+}
+export default HeadingOnlyExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <IcoText>
+        <IcoText.Icon name="book-open" />
+        <IcoText.Heading>Assessment policy</IcoText.Heading>
+      </IcoText>
+    ),
+  },
+  'Icon + Heading with no Paragraph — the compact pattern for short navigational labels.',
+);
 
-export const WithIconAndParagraph: Story = {
-  render: args => (
-    <IcoText {...args}>
-      <IcoText.Icon name="eye" />
-      <IcoText.Heading>Article heading</IcoText.Heading>
-      <IcoText.Paragraph>Supporting text for an article card layout.</IcoText.Paragraph>
+export const WithoutIcon: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { IcoText } from '@arbor-education/design-system.components';
+
+function WithoutIconExample() {
+  return (
+    <IcoText>
+      <IcoText.Heading>Behaviour report</IcoText.Heading>
+      <IcoText.Paragraph>No incidents recorded this week. All targets met.</IcoText.Paragraph>
     </IcoText>
-  ),
-};
-
-export const TextOnly: Story = {
-  render: args => (
-    <IcoText {...args}>
-      <IcoText.Heading>Article heading</IcoText.Heading>
-      <IcoText.Paragraph>Supporting text with no leading icon.</IcoText.Paragraph>
+  );
+}
+export default WithoutIconExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <IcoText>
+        <IcoText.Heading>Behaviour report</IcoText.Heading>
+        <IcoText.Paragraph>No incidents recorded this week. All targets met.</IcoText.Paragraph>
+      </IcoText>
+    ),
+  },
+  'Heading + Paragraph with no icon. The left rail disappears cleanly — `IcoText.Icon` is entirely optional.',
+);
+
+export const IconWithScreenReaderText: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { IcoText } from '@arbor-education/design-system.components';
+
+function IconWithScreenReaderTextExample() {
+  return (
+    <IcoText>
+      <IcoText.Icon
+        name="triangle-alert"
+        color="var(--color-semantic-warning-600)"
+        screenReaderText="Warning"
+      />
+      <IcoText.Heading>Attendance below target</IcoText.Heading>
+      <IcoText.Paragraph>Alice Johnson — 78.4% this term. Intervention recommended.</IcoText.Paragraph>
     </IcoText>
-  ),
-};
-
-export const HeadingWithIcon: Story = {
-  render: args => (
-    <IcoText {...args}>
-      <IcoText.Icon name="eye" />
-      <IcoText.Heading>Heading only</IcoText.Heading>
+  );
+}
+export default IconWithScreenReaderTextExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <IcoText>
+        <IcoText.Icon name="triangle-alert" color="var(--color-semantic-warning-600)" screenReaderText="Warning" />
+        <IcoText.Heading>Attendance below target</IcoText.Heading>
+        <IcoText.Paragraph>Alice Johnson — 78.4% this term. Intervention recommended.</IcoText.Paragraph>
+      </IcoText>
+    ),
+  },
+  'When the icon carries meaning not conveyed by the heading text, provide `screenReaderText`. Without it the icon is `aria-hidden="true"`. Here the warning triangle conveys severity — screen readers announce "Warning, Attendance below target".',
+);
+
+export const IconSizes: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { IcoText } from '@arbor-education/design-system.components';
+
+function IconSizesExample() {
+  return (
+    <>
+      <IcoText>
+        <IcoText.Icon name="guardians" size={12} />
+        <IcoText.Heading>size 12</IcoText.Heading>
+        <IcoText.Paragraph>Use in very compact contexts</IcoText.Paragraph>
+      </IcoText>
+      <IcoText>
+        <IcoText.Icon name="guardians" size={16} />
+        <IcoText.Heading>size 16</IcoText.Heading>
+        <IcoText.Paragraph>Use in moderately compact contexts</IcoText.Paragraph>
+      </IcoText>
+      <IcoText>
+        <IcoText.Icon name="guardians" size={24} />
+        <IcoText.Heading>size 24 (default)</IcoText.Heading>
+        <IcoText.Paragraph>Standard — aligns best with h4 line-height</IcoText.Paragraph>
+      </IcoText>
+    </>
+  );
+}
+export default IconSizesExample;
+`.trim(),
+        },
+      },
+    },
+    render: IconSizesTemplate,
+  },
+  'All three supported icon sizes — 12, 16, and 24 (default). Use smaller sizes only in compact contexts such as table cells or dense lists. The `24` default aligns best with `IcoText.Heading`\'s h4 line-height.',
+);
+
+export const IconColors: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { IcoText } from '@arbor-education/design-system.components';
+
+function IconColorsExample() {
+  return (
+    <IcoText>
+      <IcoText.Icon name="triangle-alert" color="var(--color-semantic-warning-600)" />
+      <IcoText.Heading>Attendance alert</IcoText.Heading>
+      <IcoText.Paragraph>3 pupils below 90% this half-term</IcoText.Paragraph>
     </IcoText>
-  ),
-};
+  );
+}
+export default IconColorsExample;
+`.trim(),
+        },
+      },
+    },
+    render: IconColorsTemplate,
+  },
+  'The `color` prop on `IcoText.Icon` accepts any CSS value — always use design token variables, never hardcoded hex. Semantic tokens (`--color-semantic-*`) are most appropriate for status-indicating icons.',
+);
 
-export default meta;
+export const MultipleParagraphs: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { IcoText } from '@arbor-education/design-system.components';
+
+function MultipleParagraphsExample() {
+  return (
+    <IcoText>
+      <IcoText.Icon name="calendar" />
+      <IcoText.Heading>Parents' evening — Tuesday 14 May</IcoText.Heading>
+      <IcoText.Paragraph>4:00 pm – 7:00 pm · Main Hall</IcoText.Paragraph>
+      <IcoText.Paragraph>Appointments every 10 minutes. Please arrive 5 minutes early.</IcoText.Paragraph>
+    </IcoText>
+  );
+}
+export default MultipleParagraphsExample;
+`.trim(),
+        },
+      },
+    },
+    render: MultipleParagraphsTemplate,
+  },
+  'Multiple `IcoText.Paragraph` sub-components stack vertically in the content column. Use for supplementary detail lines below the primary heading.',
+);