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

package/src/components/datePicker/DatePicker.stories.tsx

@@ -1,105 +1,822 @@
+import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { fn } from 'storybook/test';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { FormField } from 'Components/formField/FormField';
 import { DatePicker } from './DatePicker';
 
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'DatePicker combines a native `<input type="date">` with a calendar popover for date selection.',
+  'Built on [Radix UI Popover](https://www.radix-ui.com/primitives/docs/components/popover) and',
+  '[react-day-picker](https://daypicker.dev/).',
+  '',
+  '> **Portal rendering.** The calendar panel renders via a Radix portal — do **not** place inside',
+  '> a container with `overflow: hidden` or the calendar will be clipped.',
+  '',
+  'When empty, a decorative span overlays the hint text (`DD/MM/YYYY` or `Pick a date`) because',
+  'browsers do not reliably show `placeholder` on native date inputs. When a custom `placeholder` is',
+  'provided and the field is empty, the input becomes read-only and the calendar opens on click only',
+  '— Tab focus does not trigger it.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Single date selection** — enrollment dates, event dates, term start/end dates',
+  '- **Date of birth entry** — with a clear format hint so users know the expected format',
+  '- **Booking and scheduling** — parent evenings, appointment slots, report deadlines',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Date ranges (from/to) | Two separate `DatePicker` fields |',
+  '| Date + time combined | `DatePicker` paired with `TimeInput` |',
+  '| Year-only or month-only selection | `SelectDropdown` with year/month options |',
+  '| Relative dates ("next week", "in 30 days") | `SelectDropdown` with relative option labels |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`onChange` receives a `Date` object — never a string.** Format for display with',
+  '`date?.toLocaleDateString(\'en-GB\')`. Do not call `date.toString()` or assume ISO format.',
+  '',
+  '**`value` and `defaultValue` are `Date` objects — not strings.** Month is zero-indexed:',
+  '`new Date(2024, 8, 1)` = 1 September 2024. Passing a string is a type error.',
+  '',
+  '```tsx',
+  '// ✅ Correct',
+  'defaultValue={new Date(2024, 8, 1)}',
+  '',
+  '// ❌ Wrong — type error',
+  'defaultValue="2024-09-01"',
+  '```',
+  '',
+  '**`hasError` is visual-only when used standalone.** It applies the red border but does NOT',
+  'set `aria-invalid`. Always pair both when outside `<FormField>`:',
+  '',
+  '```tsx',
+  '<DatePicker hasError aria-invalid={true} aria-describedby="error-id" />',
+  '```',
+  '',
+  '**Controlled vs uncontrolled.** Pass `value` + `onChange` for controlled mode.',
+  'Pass only `defaultValue` for uncontrolled. Do not pass both `value` and `defaultValue`.',
+  '',
+  '**Time preservation.** DatePicker preserves any time component from the previous value when the',
+  'date changes — this enables clean DateTimePicker composition.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Always label via `<FormField>` or `aria-label` / `aria-labelledby`',
+  '- Pair `hasError` with `aria-invalid={true}` when used standalone — `<FormField>` handles both',
+  '- `aria-describedby` should point to the error element ID for screen-reader coverage',
+  '- The calendar icon button has built-in screen reader text ("Open date picker")',
+  '- The calendar closes and returns focus to the input on date selection or Escape',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { DatePicker } from '@arbor-education/design-system.components';",
+  '',
+  'function MyDateField(props: DatePicker.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `DatePicker.Props` | Full props interface |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[FormField](?path=/docs/components-formfield--docs) · [TimeInput](?path=/docs/components-formfield-inputs-timeinput--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.';
+
+// ---------------------------------------------------------------------------
+// Docs page component
+// ---------------------------------------------------------------------------
+
+function DatePickerDocsPage() {
+  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/DatePicker',
   component: DatePicker,
-  decorators: [
-    Story => (
-      <div style={{ maxWidth: '220px', width: '100%' }}>
-        <Story />
-      </div>
-    ),
-  ],
+  tags: ['autodocs'],
   parameters: {
-    layout: 'centered',
+    layout: 'padded',
     docs: {
-      description: {
-        component:
-          '`DatePicker` uses a native `type="date"` input (`yyyy-MM-dd`) with a synced calendar popover. When empty, hint copy uses a decorative span (browsers do not reliably show `placeholder` on native date fields). `displayFormat` controls that hint (`DD/MM/YYYY` vs `Pick a date`). The custom month/year header uses the design-system select control.',
-      },
+      page: DatePickerDocsPage,
     },
   },
-  tags: ['autodocs'],
-  args: {
-    onChange: fn(),
-  },
   argTypes: {
-    displayFormat: {
-      control: 'inline-radio',
+    'displayFormat': {
+      control: { type: 'inline-radio' },
       options: ['default', 'friendly'],
-      description: 'Controls the empty-state hint text (`DD/MM/YYYY` vs `Pick a date`). The field value is always native ISO `yyyy-MM-dd`.',
+      description: [
+        'Controls the empty-state hint overlay.',
+        '`"default"` shows `DD/MM/YYYY`; `"friendly"` shows `Pick a date`.',
+        'Overridden by `placeholder` when that prop is provided.',
+      ].join(' '),
+      table: {
+        type: { summary: "'default' | 'friendly'" },
+        defaultValue: { summary: "'default'" },
+      },
+    },
+    'placeholder': {
+      control: 'text',
+      description: [
+        'Custom text for the empty-state overlay.',
+        'Overrides the `displayFormat` hint.',
+        'When set and the field is empty, the input becomes read-only — the calendar opens on click only, not Tab focus.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'onChange': {
+      control: false,
+      action: 'onChange',
+      description: [
+        'Callback fired when the selected date changes.',
+        'Receives a `Date` object, or `undefined` when the field is cleared.',
+        'Never receives a string — format with `date?.toLocaleDateString(\'en-GB\')`.',
+      ].join(' '),
+      table: {
+        type: { summary: '(newDate?: Date) => void' },
+      },
+    },
+    'hasError': {
+      control: 'boolean',
+      description: [
+        'Applies error-state visual styling (red border).',
+        'Does **not** set `aria-invalid` automatically when used standalone.',
+        'Always pair with `aria-invalid={true}` for screen-reader coverage.',
+        '`<FormField>` handles both automatically when `errorText` is set.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'value': {
+      control: false,
+      description: [
+        'Controlled selected date.',
+        'Must be a `Date` object — not a string.',
+        'Pair with `onChange` to keep state in sync.',
+      ].join(' '),
+      table: {
+        type: { summary: 'Date' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'defaultValue': {
+      control: false,
+      description: [
+        'Uncontrolled initial date.',
+        'Must be a `Date` object (month is zero-indexed: `new Date(2024, 8, 1)` = 1 Sep 2024).',
+        'Use when you only need the value on form submit.',
+      ].join(' '),
+      table: {
+        type: { summary: 'Date' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
-    placeholder: {
+    'id': {
       control: 'text',
-      description: 'Optional override for the empty-state hint (defaults from `displayFormat`).',
+      description: 'HTML `id` for the input element. Required when inside `<FormField>` so the label `htmlFor` can be linked.',
+      table: {
+        type: { summary: 'string' },
+      },
     },
-    className: {
+    'className': {
       control: 'text',
-      description: 'Additional CSS class names',
+      description: 'Additional CSS class names on the root wrapper element.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'autoFocus': {
+      control: 'boolean',
+      description: 'Autofocuses the date input on mount. Use sparingly — unexpected focus shifts can disorient screen-reader users.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'aria-invalid': {
+      control: 'boolean',
+      description: [
+        'Marks the input as invalid for screen readers.',
+        'Must be set manually when used standalone — `<FormField>` sets this automatically when `errorText` is provided.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean | "true" | "false"' },
+      },
     },
-    onChange: {
-      description: 'Callback fired when the selected date changes. Receives the selected Date, or undefined when cleared.',
+    'aria-describedby': {
+      control: 'text',
+      description: 'ID of the element describing the field (e.g. an error message). Links the input to the error for screen readers.',
+      table: {
+        type: { summary: 'string' },
+      },
     },
   },
 } satisfies Meta<typeof DatePicker>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof DatePicker>;
 
-export const Default: Story = {
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
   parameters: {
+    ...story.parameters,
     docs: {
+      ...story.parameters?.docs,
       description: {
-        story: 'Empty field shows hint **DD/MM/YYYY** (`displayFormat="default"`).',
+        story: description,
       },
     },
   },
+});
+
+// ---------------------------------------------------------------------------
+// Named template components for stateful stories
+// ---------------------------------------------------------------------------
+
+const ControlledWithDisplayTemplate = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+  return (
+    <div style={{ maxWidth: '280px' }}>
+      <DatePicker
+        id="controlled-display"
+        onChange={setSelectedDate}
+      />
+      <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }}>
+        Selected:
+        {' '}
+        <code>
+          {selectedDate ? selectedDate.toLocaleDateString('en-GB') : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
 };
 
-export const FriendlyFormat: Story = {
-  name: 'Friendly Format',
-  args: {
-    displayFormat: 'friendly',
+const ControlledWithValidationTemplate = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+  const [error, setError] = useState<string | undefined>(undefined);
+
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+
+  const handleChange = (date: Date | undefined) => {
+    setSelectedDate(date);
+    if (!date) {
+      setError(undefined);
+      return;
+    }
+    const picked = new Date(date);
+    picked.setHours(0, 0, 0, 0);
+    if (picked <= today) {
+      setError('The event date must be in the future. Please pick a later date.');
+    }
+    else {
+      setError(undefined);
+    }
+  };
+
+  return (
+    <div style={{ maxWidth: '280px' }}>
+      <DatePicker
+        id="validated-date"
+        onChange={handleChange}
+        hasError={!!error}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={error ? 'validated-date-error' : undefined}
+      />
+      {error && (
+        <p
+          id="validated-date-error"
+          role="alert"
+          style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-semantic-destructive-600)', fontSize: '0.875rem' }}
+        >
+          {error}
+        </p>
+      )}
+      {!error && selectedDate && (
+        <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-semantic-success-600)', fontSize: '0.875rem' }}>
+          Event date set:
+          {' '}
+          {selectedDate.toLocaleDateString('en-GB')}
+        </p>
+      )}
+    </div>
+  );
+};
+
+const WithFormFieldTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <FormField
+      label="Pupil enrollment date"
+      id="ff-enrollment-date"
+      inputType="datePicker"
+      fieldDescription="Select the date the pupil will join the school."
+      inputProps={{}}
+    />
+  </div>
+);
+
+const WithFormFieldAndErrorTemplate = () => {
+  const [submitted, setSubmitted] = useState(false);
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+  const hasError = submitted && !selectedDate;
+
+  return (
+    <div style={{ maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        label="Parent evening appointment"
+        id="ff-parent-evening"
+        inputType="datePicker"
+        errorText={hasError ? 'Please select an appointment date before submitting.' : undefined}
+        inputProps={{
+          'onChange': setSelectedDate,
+          hasError,
+          'aria-invalid': hasError ? true : undefined,
+        }}
+      />
+      <div>
+        <button
+          type="button"
+          onClick={() => setSubmitted(true)}
+          style={{ padding: 'var(--spacing-small) var(--spacing-medium)' }}
+        >
+          Submit
+        </button>
+      </div>
+      {submitted && selectedDate && (
+        <p style={{ margin: 0, color: 'var(--color-semantic-success-600)', fontSize: '0.875rem' }}>
+          Appointment booked for
+          {' '}
+          {selectedDate.toLocaleDateString('en-GB')}
+          .
+        </p>
+      )}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      id: 'default-date',
+    },
+    render: args => (
+      <div style={{ maxWidth: '280px' }}>
+        <DatePicker {...args} />
+      </div>
+    ),
   },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Empty field shows hint **Pick a date**.',
+  [
+    'The interactive canvas — every prop is wired to the Controls panel.',
+    'Empty field shows the **DD/MM/YYYY** hint overlay (`displayFormat="default"`).',
+    'Click the calendar icon or type directly into the field to select a date.',
+  ].join(' '),
+);
+
+export const FriendlyFormat: Story = withDescription(
+  {
+    args: {
+      displayFormat: 'friendly',
+      id: 'friendly-date',
+    },
+    render: args => (
+      <div style={{ maxWidth: '280px' }}>
+        <DatePicker {...args} />
+      </div>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DatePicker } from '@arbor-education/design-system.components';
+
+function FriendlyFormatExample() {
+  return (
+    <DatePicker
+      id="event-date"
+      displayFormat="friendly"
+      onChange={(date) => {
+        // date is Date | undefined — not a string
+        console.log('Event date:', date?.toLocaleDateString('en-GB'));
+      }}
+    />
+  );
+}
+export default FriendlyFormatExample;
+`.trim(),
+        },
       },
     },
   },
-};
+  '`displayFormat="friendly"` shows **Pick a date** instead of the `DD/MM/YYYY` format hint. Use for contexts where a conversational label reads better than a technical format string.',
+);
+
+export const WithDefaultValue: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '280px' }}>
+        {/* September 1 2024 — month is zero-indexed (Jan = 0, Sep = 8) */}
+        <DatePicker
+          id="default-value-date"
+          defaultValue={new Date(2024, 8, 1)}
+        />
+      </div>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DatePicker } from '@arbor-education/design-system.components';
 
-/** `placeholder` overrides the default empty-state hint. */
-export const PlaceholderCustomOverride: Story = {
-  name: 'Placeholder · custom copy',
-  args: {
-    displayFormat: 'default',
-    placeholder: 'e.g. 25/12/2024',
+function EditEnrollmentDate() {
+  // Month is zero-indexed: 8 = September
+  const currentEnrollmentDate = new Date(2024, 8, 1);
+
+  return (
+    <DatePicker
+      id="enrollment-date"
+      defaultValue={currentEnrollmentDate}
+      onChange={(date) => {
+        // date is Date | undefined — not a string
+        console.log('Updated to:', date?.toLocaleDateString('en-GB'));
+      }}
+    />
+  );
+}
+export default EditEnrollmentDate;
+`.trim(),
+        },
+      },
+    },
   },
-  parameters: {
-    docs: {
-      description: {
-        story: 'The optional `placeholder` prop replaces the default hint.',
+  [
+    'Use `defaultValue` to pre-populate an uncontrolled DatePicker — for example when an admin opens a',
+    'pupil\'s enrollment record to edit it. The prop must be a `Date` object (month is zero-indexed:',
+    '`new Date(2024, 8, 1)` = 1 September 2024). Passing a string is a type error.',
+  ].join(' '),
+);
+
+export const WithPlaceholder: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <DatePicker
+          id="placeholder-date"
+          placeholder="Choose term start date"
+        />
+      </div>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DatePicker } from '@arbor-education/design-system.components';
+
+function TermStartDatePicker() {
+  return (
+    <DatePicker
+      id="term-start-date"
+      placeholder="Choose term start date"
+      onChange={(date) => {
+        console.log('Term start:', date?.toLocaleDateString('en-GB'));
+      }}
+    />
+  );
+}
+export default TermStartDatePicker;
+`.trim(),
+        },
       },
     },
   },
-};
+  [
+    'When `placeholder` is set and the field is empty, the input becomes **read-only** and the',
+    'calendar opens on **click only** — Tab focus does not trigger it. This prevents the popup',
+    'from unexpectedly opening as keyboard users navigate through a form.',
+  ].join(' '),
+);
+
+export const ErrorState: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <DatePicker
+          id="error-state-date"
+          hasError
+          aria-invalid={true}
+          aria-describedby="error-state-msg"
+        />
+        <p
+          id="error-state-msg"
+          role="alert"
+          style={{ margin: 'var(--spacing-xsmall) 0 0', color: 'var(--color-semantic-destructive-600)', fontSize: '0.875rem' }}
+        >
+          Please select a valid enrollment date.
+        </p>
+      </div>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DatePicker } from '@arbor-education/design-system.components';
 
-/** Friendly format with custom hint copy. */
-export const PlaceholderFriendlyWithCustomCopy: Story = {
-  name: 'Placeholder · friendly format, custom hint',
-  args: {
-    displayFormat: 'friendly',
-    placeholder: 'Choose a date…',
+// Standalone — set both hasError (visual) and aria-invalid (screen reader) yourself.
+// Inside <FormField> both are handled automatically when errorText is set.
+function EnrollmentDateWithError() {
+  return (
+    <>
+      <DatePicker
+        id="enrollment-date"
+        hasError
+        aria-invalid={true}
+        aria-describedby="enrollment-date-error"
+      />
+      <p id="enrollment-date-error" role="alert">
+        Please select a valid enrollment date.
+      </p>
+    </>
+  );
+}
+export default EnrollmentDateWithError;
+`.trim(),
+        },
+      },
+    },
   },
-  parameters: {
-    docs: {
-      description: {
-        story: '`displayFormat="friendly"` with a custom hint instead of **Pick a date**.',
+  [
+    'The error state requires **both** `hasError` (visual red border) and `aria-invalid={true}`',
+    '(screen-reader signal). Use `aria-describedby` to link the input to the error message element.',
+    'When using `<FormField>`, set `errorText` and the component handles all three automatically.',
+  ].join(' '),
+);
+
+export const ControlledWithDisplay: Story = withDescription(
+  {
+    render: () => <ControlledWithDisplayTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { DatePicker } from '@arbor-education/design-system.components';
+
+function ControlledDatePickerExample() {
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+
+  return (
+    <div>
+      <DatePicker
+        id="event-date"
+        onChange={setSelectedDate}
+      />
+      <p>
+        Selected:{' '}
+        <code>
+          {selectedDate
+            ? selectedDate.toLocaleDateString('en-GB')
+            : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
+}
+export default ControlledDatePickerExample;
+`.trim(),
+        },
       },
     },
   },
-};
+  [
+    '`onChange` receives a `Date` object (or `undefined`) — never a string. Use',
+    '`date.toLocaleDateString(\'en-GB\')` for human-readable display.',
+    'This controlled example stores the value in state and renders it below the field.',
+  ].join(' '),
+);
+
+export const ControlledWithValidation: Story = withDescription(
+  {
+    render: () => <ControlledWithValidationTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { DatePicker } from '@arbor-education/design-system.components';
+
+function FutureDatePicker() {
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+  const [error, setError] = useState<string | undefined>(undefined);
+
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+
+  function handleChange(date: Date | undefined) {
+    setSelectedDate(date);
+    if (!date) { setError(undefined); return; }
+    const picked = new Date(date);
+    picked.setHours(0, 0, 0, 0);
+    if (picked <= today) {
+      setError('The event date must be in the future. Please pick a later date.');
+    } else {
+      setError(undefined);
+    }
+  }
+
+  return (
+    <div>
+      <DatePicker
+        id="event-date"
+        onChange={handleChange}
+        hasError={!!error}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={error ? 'event-date-error' : undefined}
+      />
+      {error && (
+        <p id="event-date-error" role="alert">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+export default FutureDatePicker;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Real-time validation: only future dates are accepted. Selecting today or a past date triggers',
+    'error styling (`hasError` + `aria-invalid` + `aria-describedby`). Clearing the date removes the error.',
+    'The accessible `role="alert"` paragraph announces the error to screen readers immediately.',
+  ].join(' '),
+);
+
+export const WithFormField: Story = withDescription(
+  {
+    render: () => <WithFormFieldTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function EnrollmentDateField() {
+  return (
+    <FormField
+      label="Pupil enrollment date"
+      id="enrollment-date"
+      inputType="datePicker"
+      fieldDescription="Select the date the pupil will join the school."
+      inputProps={{
+        onChange: (date) => {
+          // date is Date | undefined
+          console.log('Enrollment date:', date?.toLocaleDateString('en-GB'));
+        },
+      }}
+    />
+  );
+}
+export default EnrollmentDateField;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The recommended form usage: `<FormField inputType="datePicker">` provides the accessible',
+    'label, description, and error layout. Pass DatePicker-specific props through `inputProps`.',
+    'The `label`, `fieldDescription`, and `errorText` props belong on `<FormField>` itself.',
+  ].join(' '),
+);
+
+export const WithFormFieldAndError: Story = withDescription(
+  {
+    render: () => <WithFormFieldAndErrorTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { FormField } from '@arbor-education/design-system.components';
+
+function ParentEveningForm() {
+  const [submitted, setSubmitted] = useState(false);
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+  const hasError = submitted && !selectedDate;
+
+  return (
+    <div>
+      <FormField
+        label="Parent evening appointment"
+        id="parent-evening-date"
+        inputType="datePicker"
+        errorText={
+          hasError
+            ? 'Please select an appointment date before submitting.'
+            : undefined
+        }
+        inputProps={{
+          onChange: setSelectedDate,
+          hasError,
+          'aria-invalid': hasError ? true : undefined,
+        }}
+      />
+      <button type="button" onClick={() => setSubmitted(true)}>
+        Submit
+      </button>
+    </div>
+  );
+}
+export default ParentEveningForm;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A submit-gated form: clicking Submit without a date triggers the full error pattern.',
+    '`errorText` on `<FormField>` renders the message in the correct accessible layout below the input,',
+    'linked via `aria-describedby` automatically. Once a date is chosen, the error clears.',
+  ].join(' '),
+);