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

package/src/components/formField/label/Label.stories.tsx

@@ -1,15 +1,324 @@
-import type { Meta } from '@storybook/react-vite';
+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 { TextInput } from 'Components/formField/inputs/text/TextInput';
 import { Label } from './Label';
 
-const meta: Meta<typeof Label> = {
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Label renders a styled `<label>` element for form controls. It applies the design system\'s label',
+  'typography — bold weight, the semantic label colour, and a bottom margin that separates it from the',
+  'input below.',
+  '',
+  'In most cases you do not use Label directly:',
+  '[`FormField`](?path=/docs/components-formfield--docs) renders it automatically when you pass a `label`',
+  'prop. Use Label directly only when building a custom layout that cannot use FormField.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Custom form layouts** — when `FormField` does not fit your layout but you still need a correctly',
+  '  styled label',
+  '- **Labelling non-standard controls** — e.g. a custom rich-text editor, a map control, or a file',
+  '  upload zone',
+  '- **Wrapping pattern** — when no `htmlFor` target `id` is available, wrap the control inside',
+  '  `<Label>` so the browser infers the association automatically',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Standard input with a label | [`FormField`](?path=/docs/components-formfield--docs) — it renders Label automatically |',
+  '| Decorative, non-form text | `<p className="ds-text">` or a heading element |',
+  '| Required field indicator | Add `" *"` to the label `children` — Label has no built-in required prop |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Always pass `htmlFor`.** The `htmlFor` prop maps to the HTML `for` attribute, creating an accessible',
+  'association between the label and its input. Screen readers announce the label text when the input',
+  'receives focus. Without it, the label and input are visually close but semantically disconnected.',
+  '',
+  '**`htmlFor` value must match the input\'s `id`.** If the input has `id="pupil-name"`, set',
+  '`htmlFor="pupil-name"` on the Label. A mismatch silently breaks the association without any error.',
+  '',
+  '**Reduced margin when followed by a description.** The SCSS uses `:has(+ .ds-form-field__description)`',
+  'to automatically reduce `margin-bottom` when a sibling description element immediately follows the',
+  'label. This is handled internally by `FormField` — only relevant when composing a custom layout with',
+  'Label and a description element.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Always associate Label with its control via `htmlFor` / `id` pairing',
+  '- Do not rely on visual proximity alone — screen readers use the DOM association, not layout position',
+  '- The `<label>` element is `display: block` — it always occupies its own line',
+  '- Clicking or touching a correctly associated label focuses the input — this enlarges the tap target',
+  '',
+  '---',
+  '',
+  '### Design tokens used',
+  '',
+  '| Token | Usage |',
+  '|---|---|',
+  '| `--form-field-label-color-text` | Label text colour |',
+  '| `--type-body-bold-weight` | Bold font weight |',
+  '| `--form-field-spacing-vertical` | Bottom margin (default) |',
+  '| `--form-field-spacing-vertical-gap` | Bottom margin (reduced, when description follows) |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[FormField](?path=/docs/components-formfield--docs) · [TextInput](?path=/docs/components-formfield-inputs-textinput--docs) · [Fieldset](?path=/docs/components-formfield-fieldset--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 LabelDocsPage() {
+  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/FormField/Inputs/Label',
   component: Label,
-};
-
-export const Default = {
-  args: {
-    children: 'Label',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: LabelDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      control: 'text',
+      description: 'The label text content.',
+      table: {
+        type: { summary: 'ReactNode' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    htmlFor: {
+      control: 'text',
+      description: [
+        'The `id` of the form control this label describes.',
+        'Maps to the HTML `for` attribute. Required for an accessible label-input association.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      control: 'text',
+      description: 'Additional CSS class names appended to `ds-label`. Use sparingly.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
   },
-};
+} satisfies Meta<typeof Label>;
 
 export default meta;
+type Story = StoryObj<typeof Label>;
+
+// ---------------------------------------------------------------------------
+// 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 WithHtmlForTemplate = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '4px', maxWidth: '360px' }}>
+    <Label htmlFor="pupil-name">Pupil full name</Label>
+    <TextInput id="pupil-name" placeholder="e.g. Amelia Pemberton" />
+  </div>
+);
+
+const WithDescriptionTemplate = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', maxWidth: '360px' }}>
+    <Label htmlFor="preferred-name">Preferred name</Label>
+    <div className="ds-form-field__description" style={{ marginBottom: '4px' }}>
+      This is the name the pupil prefers to be called — it may differ from their legal name.
+    </div>
+    <TextInput id="preferred-name" placeholder="e.g. Millie" />
+  </div>
+);
+
+const LongTextTemplate = () => (
+  <div style={{ maxWidth: '360px' }}>
+    <Label htmlFor="send-status">
+      Special educational needs and disabilities (SEND) status and current support requirements
+    </Label>
+    <TextInput id="send-status" placeholder="e.g. EHC plan in place" />
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      children: 'Pupil full name',
+      htmlFor: 'pupil-name',
+    },
+    render: args => <Label {...args} />,
+  },
+  'The interactive canvas — every prop is wired to the Controls panel below. Edit `children` to change the label text and `htmlFor` to set the associated input id.',
+);
+
+export const WithHtmlFor: Story = withDescription(
+  {
+    render: WithHtmlForTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Label, TextInput } from '@arbor-education/design-system.components';
+
+function PupilNameField() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
+      <Label htmlFor="pupil-name">Pupil full name</Label>
+      <TextInput id="pupil-name" placeholder="e.g. Amelia Pemberton" />
+    </div>
+  );
+}
+export default PupilNameField;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '**The most important pattern.** Pass `htmlFor` matching the input\'s `id` to create an accessible',
+    'label-input association. Clicking the label focuses the input — this enlarges the effective tap',
+    'target on touch devices. Screen readers announce the label text when the input receives focus.',
+  ].join(' '),
+);
+
+export const WithDescription: Story = withDescription(
+  {
+    render: WithDescriptionTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Label, TextInput } from '@arbor-education/design-system.components';
+
+function PreferredNameField() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column' }}>
+      <Label htmlFor="preferred-name">Preferred name</Label>
+      {/* .ds-form-field__description triggers :has() CSS — label margin-bottom reduces automatically */}
+      <div className="ds-form-field__description" style={{ marginBottom: '4px' }}>
+        This is the name the pupil prefers to be called — it may differ from their legal name.
+      </div>
+      <TextInput id="preferred-name" placeholder="e.g. Millie" />
+    </div>
+  );
+}
+export default PreferredNameField;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'When a `.ds-form-field__description` element immediately follows the label in the DOM,',
+    'the label\'s `margin-bottom` automatically reduces via `:has(+ .ds-form-field__description)` CSS.',
+    '`FormField` handles this for you — only relevant when composing a custom layout.',
+  ].join(' '),
+);
+
+export const LongText: Story = withDescription(
+  {
+    render: LongTextTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Label, TextInput } from '@arbor-education/design-system.components';
+
+function SendField() {
+  return (
+    <div style={{ maxWidth: '360px' }}>
+      <Label htmlFor="send-status">
+        Special educational needs and disabilities (SEND) status and current support requirements
+      </Label>
+      <TextInput id="send-status" placeholder="e.g. EHC plan in place" />
+    </div>
+  );
+}
+export default SendField;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Long label text wraps naturally — Label is `display: block` and fills the full width of its',
+    'container with no truncation. If your label is very long, consider shortening it or using a',
+    'description element for supplementary detail.',
+  ].join(' '),
+);