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

package/src/components/dateTimePicker/DateTimePicker.stories.tsx

@@ -1,202 +1,980 @@
+import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { formatNativeDateTimeInputValue } from 'Components/datePicker/dateInputUtils';
-import { useEffect, useState } from 'react';
-import { fn } from 'storybook/test';
-import { DateTimePicker, type DateTimePickerProps } from './DateTimePicker';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { FormField } from 'Components/formField/FormField';
+import type { TimeValue } from 'Components/formField/inputs/time/TimeInput';
+import { DateTimePicker } from './DateTimePicker';
 
-const timeOptions = ['09:00', '09:30', '10:00', '10:30', '11:00'] as const;
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'DateTimePicker combines a date input with an embedded time input, keeping a single unified `Date`',
+  'value. Built on [Radix UI Popover](https://www.radix-ui.com/primitives/docs/components/popover)',
+  'and [react-day-picker](https://daypicker.dev/).',
+  '',
+  'The calendar popup contains both the date picker and the time input, keeping date and time',
+  'selection in a single interaction flow. When a date is picked from the calendar, the existing',
+  'time is preserved. When a time is changed, the existing date is preserved.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Event scheduling** — lesson start times, parent evening appointments, report deadlines',
+  '- **Booking flows** — any scenario where both a date AND a specific time are required',
+  '- **Audit timestamps** — log entries, registration opens/closes with precise time',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Date only (no time needed) | `DatePicker` |',
+  '| Time only (no date needed) | `TimeInput` |',
+  '| Date range selection | Two `DatePicker` fields |',
+  '| Fixed time slots from a list | `DateTimePicker` with `timeOptions` |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '> **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.',
+  '',
+  '**`onChange` receives a `Date` object — never a string.** Format for display with',
+  '`date?.toLocaleDateString(\'en-GB\')` + time as needed. Do not assume ISO string format.',
+  '',
+  '**`value` and `defaultValue` are `Date` objects — not strings.** Month is zero-indexed:',
+  '`new Date(2026, 3, 14, 9, 0)` = 14 April 2026, 09:00. Passing a string is a type error.',
+  '',
+  '```tsx',
+  '// ✅ Correct',
+  'value={new Date(2026, 3, 14, 9, 0)}',
+  '',
+  '// ❌ Wrong — type error',
+  'value="2026-04-14T09:00"',
+  '```',
+  '',
+  '**Three display formats — choose based on your context:**',
+  '',
+  '| `displayFormat` | Input type | Placeholder hint | Example value |',
+  '|---|---|---|---|',
+  '| `"native"` (default) | `datetime-local` | `YYYY-MM-DDTHH:mm` | `2026-04-14T14:27` |',
+  '| `"default"` | `text` | `DD/MM/YYYY HH:mm` | `14/04/2026 14:27` |',
+  '| `"friendly"` | `text` | `Pick a date, HH:mm` | `April 14th, 2026 14:27` |',
+  '',
+  '**`timeOptions` switches the embedded time input to combobox mode.** Instead of a free-form',
+  'time input, the user picks from a predefined list. Use for fixed appointment slots.',
+  '',
+  '**`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',
+  '<DateTimePicker hasError aria-invalid={true} aria-describedby="error-id" />',
+  '```',
+  '',
+  '**`granularity="second"` enables seconds** in both the `datetime-local` step attribute',
+  '(native mode) and the embedded time input.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Always label via `<FormField>` or `aria-label` / `aria-labelledby`',
+  '- Pair `hasError` with `aria-invalid={true}` when used standalone — `<FormField>` handles both',
+  '- The calendar icon button has built-in screen reader text ("Open date and time picker")',
+  '- The embedded time input has `aria-label="Select time"`',
+  '- The calendar closes and returns focus to the date input on date selection or Escape',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { DateTimePicker } from '@arbor-education/design-system.components';",
+  '',
+  '// Access via namespace:',
+  'function MyField(props: DateTimePicker.Props) { ... }',
+  '',
+  '// Display format type:',
+  'const format: DateTimePicker.DisplayFormat = "native"; // "native" | "default" | "friendly"',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `DateTimePicker.Props` | Full props interface |',
+  '| `DateTimePicker.DisplayFormat` | `"native" \\| "default" \\| "friendly"` |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[DatePicker](?path=/docs/components-datepicker--docs) · [TimeInput](?path=/docs/components-formfield-inputs-timeinput--docs) · [FormField](?path=/docs/components-formfield--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 DateTimePickerDocsPage() {
+  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/DateTimePicker',
   component: DateTimePicker,
-  decorators: [
-    Story => (
-      <div style={{ maxWidth: '280px', width: '100%' }}>
-        <Story />
-      </div>
-    ),
-  ],
+  tags: ['autodocs'],
   parameters: {
-    layout: 'centered',
+    layout: 'padded',
     docs: {
-      description: {
-        component:
-          '`DateTimePicker` combines a date field with the existing `TimeInput`, keeping a single combined `Date` value. `displayFormat="native"` (default) uses a `datetime-local` input with a decorative empty-state hint span (browsers do not reliably show placeholders on native date/time fields). `"default"` and `"friendly"` use a plain text input with locale-style formatting and a real HTML placeholder.',
-      },
+      page: DateTimePickerDocsPage,
     },
   },
-  tags: ['autodocs'],
-  args: {
-    onChange: fn(),
-  },
   argTypes: {
-    displayFormat: {
-      control: 'inline-radio',
+    'displayFormat': {
+      control: { type: 'inline-radio' },
       options: ['native', 'default', 'friendly'],
-      description:
-        '`native`: ISO `datetime-local` (default). `default` / `friendly`: plain text field using the same date patterns as `DatePicker` plus time.',
+      description: [
+        'Controls input type and value format.',
+        '`"native"` (default): `datetime-local` input with `YYYY-MM-DDTHH:mm` hint.',
+        '`"default"`: text input with `DD/MM/YYYY HH:mm` format.',
+        '`"friendly"`: text input with `April 14th, 2026 14:27` format.',
+      ].join(' '),
+      table: {
+        type: { summary: '"native" | "default" | "friendly"' },
+        defaultValue: { summary: '"native"' },
+      },
     },
-    granularity: {
-      control: 'inline-radio',
+    'granularity': {
+      control: { type: 'inline-radio' },
       options: ['minute', 'second'],
-      description: 'Controls whether the native `datetime-local` input and embedded time input use minute or second precision.',
+      description: [
+        'Controls time precision.',
+        '`"minute"` (default): HH:mm.',
+        '`"second"`: HH:mm:ss — sets `step={1}` on the datetime-local input and shows seconds in the embedded time input.',
+      ].join(' '),
+      table: {
+        type: { summary: '"minute" | "second"' },
+        defaultValue: { summary: '"minute"' },
+      },
+    },
+    'placeholder': {
+      control: 'text',
+      description: [
+        'Custom text for the empty-state hint overlay (native mode only).',
+        '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 combined date+time changes.',
+        'Receives a `Date` object, or `undefined` when cleared.',
+        'Never receives a string.',
+      ].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}`. `<FormField>` handles both automatically.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
     },
-    timeOptions: {
-      control: 'object',
-      description: 'When provided, the embedded time input switches to list-backed time selection.',
+    'value': {
+      control: false,
+      description: [
+        'Controlled combined date+time value.',
+        'Must be a `Date` object — not a string.',
+        'Pair with `onChange` to keep state in sync.',
+      ].join(' '),
+      table: {
+        type: { summary: 'Date' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
-    value: {
+    'defaultValue': {
       control: false,
-      description: 'Controlled combined datetime value for app-level state.',
+      description: [
+        'Uncontrolled initial date+time.',
+        'Must be a `Date` object (month is zero-indexed: `new Date(2026, 3, 14, 9, 0)` = 14 Apr 2026 09:00).',
+        'Use when you only need the value on form submit.',
+      ].join(' '),
+      table: {
+        type: { summary: 'Date' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
-    defaultValue: {
+    'timeOptions': {
       control: false,
-      description: 'Uncontrolled initial combined datetime value.',
+      description: [
+        'Array of `TimeValue` strings to use as preset time slots.',
+        'When provided, the embedded time input switches to **combobox mode** — the user picks from the list instead of typing freely.',
+        'Ideal for fixed appointment slots like "09:00", "09:30", "10:00".',
+      ].join(' '),
+      table: {
+        type: { summary: 'TimeValue[]' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'searchType': {
+      control: { type: 'select' },
+      options: ['prefix', 'substring'],
+      description: [
+        '**Only used when `timeOptions` is provided.**',
+        'Controls how the time combobox filters options as the user types.',
+        '`"prefix"` (default) matches from the start; `"substring"` matches anywhere.',
+      ].join(' '),
+      table: {
+        type: { summary: '"prefix" | "substring"' },
+        defaultValue: { summary: '"prefix"' },
+      },
     },
-    onChange: {
-      action: 'changed',
-      description: 'Called with the next combined `Date` value, or `undefined` when the date becomes invalid/cleared.',
+    'highlightStringMatches': {
+      control: 'boolean',
+      description: '**Only used when `timeOptions` is provided.** Bolds matched characters in the time dropdown.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
     },
-    placeholder: {
+    'id': {
       control: 'text',
-      description: 'Optional override for the field placeholder (defaults from `displayFormat` and `granularity`).',
+      description: 'HTML `id` for the date input element. Required when inside `<FormField>` so the label `htmlFor` can be linked.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'className': {
+      control: 'text',
+      description: 'Additional CSS class names on the root wrapper element.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'aria-invalid': {
+      control: 'boolean',
+      description: [
+        'Marks the date 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"' },
+      },
+    },
+    'aria-describedby': {
+      control: 'text',
+      description: 'ID of the element describing the field (e.g. an error message).',
+      table: {
+        type: { summary: 'string' },
+      },
     },
   },
 } satisfies Meta<typeof DateTimePicker>;
 
 export default meta;
+type Story = StoryObj<typeof DateTimePicker>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
 
-type Story = StoryObj<typeof meta>;
+// ---------------------------------------------------------------------------
+// Named template components for stateful stories
+// ---------------------------------------------------------------------------
 
-const ControlledDateTimePicker = ({
-  showCurrentValue = false,
-  ...args
-}: DateTimePickerProps & { showCurrentValue?: boolean }) => {
-  const [value, setValue] = useState<Date | undefined>(args.value);
+const APPOINTMENT_SLOTS: TimeValue[] = [
+  '09:00',
+  '09:30',
+  '10:00',
+  '10:30',
+  '11:00',
+  '11:30',
+  '14:00',
+  '14:30',
+  '15:00',
+  '15:30',
+];
 
-  useEffect(() => {
-    setValue(args.value);
-  }, [args.value]);
+const DisplayFormatDefaultTemplate = () => {
+  const [value, setValue] = useState<Date | undefined>(new Date(2026, 3, 14, 14, 27));
+  return (
+    <div style={{ maxWidth: '320px' }}>
+      <DateTimePicker
+        displayFormat="default"
+        value={value}
+        onChange={setValue}
+        id="format-default"
+      />
+      <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }}>
+        Value:
+        {' '}
+        <code>
+          {value
+            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+            : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
+};
+
+const DisplayFormatFriendlyTemplate = () => {
+  const [value, setValue] = useState<Date | undefined>(new Date(2026, 3, 14, 14, 27));
+  return (
+    <div style={{ maxWidth: '320px' }}>
+      <DateTimePicker
+        displayFormat="friendly"
+        value={value}
+        onChange={setValue}
+        id="format-friendly"
+      />
+      <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }}>
+        Value:
+        {' '}
+        <code>
+          {value
+            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+            : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
+};
+
+const WithTimeOptionsTemplate = () => {
+  const [value, setValue] = useState<Date | undefined>(new Date(2026, 3, 14, 9, 0));
+  return (
+    <div style={{ maxWidth: '280px' }}>
+      <DateTimePicker
+        timeOptions={APPOINTMENT_SLOTS}
+        value={value}
+        onChange={setValue}
+        id="time-options"
+      />
+      <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }}>
+        Appointment:
+        {' '}
+        <code>
+          {value
+            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+            : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
+};
 
+const GranularitySecondTemplate = () => {
+  const [value, setValue] = useState<Date | undefined>(undefined);
   return (
-    <div style={{ display: 'grid', gap: 12, width: '100%', maxWidth: 320 }}>
+    <div style={{ maxWidth: '280px' }}>
       <DateTimePicker
-        {...args}
+        granularity="second"
         value={value}
-        onChange={(nextValue) => {
-          setValue(nextValue);
-          args.onChange?.(nextValue);
+        onChange={setValue}
+        id="granularity-second"
+      />
+      <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }}>
+        Value (with seconds):
+        {' '}
+        <code>
+          {value
+            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB')}`
+            : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
+};
+
+const ControlledWithDisplayTemplate = () => {
+  const [value, setValue] = useState<Date | undefined>(undefined);
+  return (
+    <div style={{ maxWidth: '280px' }}>
+      <DateTimePicker
+        id="controlled-display"
+        onChange={setValue}
+      />
+      <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }}>
+        Selected:
+        {' '}
+        <code>
+          {value
+            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+            : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
+};
+
+const WithFormFieldTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <FormField
+      label="Event start date and time"
+      id="ff-event-start"
+      inputType="dateTimePicker"
+      fieldDescription="Select the date and time the event will begin."
+      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="Lesson start date and time"
+        id="ff-lesson-start"
+        inputType="dateTimePicker"
+        errorText={hasError ? 'Please select a date and time for the lesson.' : undefined}
+        inputProps={{
+          'onChange': setSelectedDate,
+          hasError,
+          'aria-invalid': hasError ? true : undefined,
         }}
       />
-      {showCurrentValue && (
-        <span>
-          Current value:
+      <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' }}>
+          Lesson scheduled for
           {' '}
-          {value ? formatNativeDateTimeInputValue(value, args.granularity) : 'None'}
-        </span>
+          {selectedDate.toLocaleDateString('en-GB')}
+          {' at '}
+          {selectedDate.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}
+          .
+        </p>
       )}
     </div>
   );
 };
 
-export const NativeTime: Story = {
-  args: {
-    value: new Date(2026, 3, 14, 14, 27),
-    granularity: 'minute',
-  },
-  render: args => <ControlledDateTimePicker {...args} />,
-};
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 
-export const TimeList: Story = {
-  args: {
-    value: new Date(2026, 3, 14, 10, 0),
-    timeOptions: [...timeOptions],
+export const Default: Story = withDescription(
+  {
+    args: {
+      id: 'default-datetime',
+    },
+    render: args => (
+      <div style={{ maxWidth: '280px' }}>
+        <DateTimePicker {...args} />
+      </div>
+    ),
   },
-  render: args => <ControlledDateTimePicker {...args} />,
-};
+  [
+    'The interactive canvas — every prop is wired to the Controls panel.',
+    'Default `displayFormat="native"` shows the `YYYY-MM-DDTHH:mm` hint overlay (a decorative span,',
+    'because browsers do not reliably show `placeholder` on `datetime-local` inputs).',
+    'Click the calendar icon to open the combined date+time picker.',
+  ].join(' '),
+);
 
-export const ControlledValuePreview: Story = {
-  args: {
-    value: new Date(2026, 3, 14, 14, 27),
-    granularity: 'minute',
-  },
-  render: args => <ControlledDateTimePicker {...args} showCurrentValue />,
-};
+export const WithDefaultValue: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '280px' }}>
+        {/* 14 April 2026, 14:27 — month is zero-indexed (Apr = 3) */}
+        <DateTimePicker
+          id="default-value-datetime"
+          defaultValue={new Date(2026, 3, 14, 14, 27)}
+        />
+      </div>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DateTimePicker } from '@arbor-education/design-system.components';
+
+function EditEventStart() {
+  // 14 April 2026, 14:27 — month is zero-indexed (Apr = 3)
+  const eventStart = new Date(2026, 3, 14, 14, 27);
 
-export const PlaceholderNativeMinuteHint: Story = {
-  name: 'Placeholder · native minute hint',
-  args: {
-    granularity: 'minute',
+  return (
+    <DateTimePicker
+      id="event-start"
+      defaultValue={eventStart}
+      onChange={(date) => {
+        // date is Date | undefined — not a string
+        console.log('Updated to:', date?.toLocaleString('en-GB'));
+      }}
+    />
+  );
+}
+export default EditEventStart;
+`.trim(),
+        },
+      },
+    },
   },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Uncontrolled, no initial value — empty-state hint shows `YYYY-MM-DDTHH:mm` (decorative span for native mode).',
+  [
+    'Use `defaultValue` to pre-populate an uncontrolled DateTimePicker — for example when editing',
+    'an existing event. The prop must be a `Date` object (month is zero-indexed: April = 3).',
+  ].join(' '),
+);
+
+export const GranularitySecond: Story = withDescription(
+  {
+    render: () => <GranularitySecondTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { DateTimePicker } from '@arbor-education/design-system.components';
+
+function PreciseDateTimePickerExample() {
+  const [value, setValue] = useState<Date | undefined>(undefined);
+
+  return (
+    <DateTimePicker
+      granularity="second"
+      value={value}
+      onChange={setValue}
+      id="precise-datetime"
+    />
+  );
+}
+export default PreciseDateTimePickerExample;
+`.trim(),
+        },
       },
     },
   },
-};
+  [
+    '`granularity="second"` enables seconds in both the `datetime-local` native input (sets `step={1}`)',
+    'and the embedded time input inside the calendar popup.',
+    'Use for precise event logging, stopwatch-style entry, or when sub-minute accuracy matters.',
+  ].join(' '),
+);
+
+export const DisplayFormatDefault: Story = withDescription(
+  {
+    render: () => <DisplayFormatDefaultTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { DateTimePicker } from '@arbor-education/design-system.components';
 
-export const PlaceholderNativeSecondHint: Story = {
-  name: 'Placeholder · native second hint',
-  args: {
-    granularity: 'second',
+function FormattedDateTimePickerExample() {
+  const [value, setValue] = useState<Date | undefined>(new Date(2026, 3, 14, 14, 27));
+
+  return (
+    <DateTimePicker
+      displayFormat="default"
+      value={value}
+      onChange={setValue}
+      id="event-datetime"
+    />
+  );
+}
+export default FormattedDateTimePickerExample;
+`.trim(),
+        },
+      },
+    },
   },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Same as the minute story, but with `granularity="second"` so the hint includes seconds.',
+  [
+    '`displayFormat="default"` uses a plain text input showing the value as `DD/MM/YYYY HH:mm`',
+    '(e.g. `14/04/2026 14:27`). The appearance is consistent across all browsers — unlike `"native"`,',
+    'which uses the OS date/time widget and varies by platform.',
+  ].join(' '),
+);
+
+export const DisplayFormatFriendly: Story = withDescription(
+  {
+    render: () => <DisplayFormatFriendlyTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { DateTimePicker } from '@arbor-education/design-system.components';
+
+function FriendlyDateTimePickerExample() {
+  const [value, setValue] = useState<Date | undefined>(new Date(2026, 3, 14, 14, 27));
+
+  return (
+    <DateTimePicker
+      displayFormat="friendly"
+      value={value}
+      onChange={setValue}
+      id="event-datetime"
+    />
+  );
+}
+export default FriendlyDateTimePickerExample;
+`.trim(),
+        },
       },
     },
   },
-};
+  [
+    '`displayFormat="friendly"` shows the value as `April 14th, 2026 14:27` — human-readable and',
+    'locale-style. Best for consumer-facing or less technical contexts where ISO-adjacent formats feel unfriendly.',
+  ].join(' '),
+);
+
+export const WithTimeOptions: Story = withDescription(
+  {
+    render: () => <WithTimeOptionsTemplate />,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { DateTimePicker, type TimeValue } from '@arbor-education/design-system.components';
 
-export const DisplayFormatDefault: Story = {
-  name: 'Display format · default (text)',
-  args: {
-    displayFormat: 'default',
-    value: new Date(2026, 3, 14, 14, 27),
-    granularity: 'minute',
+const APPOINTMENT_SLOTS: TimeValue[] = [
+  '09:00', '09:30', '10:00', '10:30', '11:00', '11:30',
+  '14:00', '14:30', '15:00', '15:30',
+];
+
+function AppointmentBookingExample() {
+  const [value, setValue] = useState<Date | undefined>(new Date(2026, 3, 14, 9, 0));
+
+  return (
+    <DateTimePicker
+      timeOptions={APPOINTMENT_SLOTS}
+      value={value}
+      onChange={setValue}
+      id="appointment-datetime"
+    />
+  );
+}
+export default AppointmentBookingExample;
+`.trim(),
+        },
+      },
+    },
   },
-  render: args => <ControlledDateTimePicker {...args} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Combined value is shown and edited as **15/04/2026 14:27** instead of the native ISO string.',
+  [
+    '`timeOptions` switches the embedded time input from free-form entry to a combobox list.',
+    'Ideal for appointment booking where only specific slots are valid — the user picks a date',
+    'from the calendar, then picks a slot from the dropdown. Both stay in a single `Date` value.',
+  ].join(' '),
+);
+
+export const WithPlaceholder: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <DateTimePicker
+          id="placeholder-datetime"
+          placeholder="Choose event start"
+        />
+      </div>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DateTimePicker } from '@arbor-education/design-system.components';
+
+function GuidedDateTimePickerExample() {
+  return (
+    <DateTimePicker
+      id="event-start"
+      placeholder="Choose event start"
+      onChange={(date) => {
+        console.log('Event start:', date?.toLocaleString('en-GB'));
+      }}
+    />
+  );
+}
+export default GuidedDateTimePickerExample;
+`.trim(),
+        },
       },
     },
   },
-};
+  [
+    '`placeholder` (native mode only) replaces the `YYYY-MM-DDTHH:mm` hint with custom copy.',
+    'When set and the field is empty, the input becomes **read-only** and the calendar opens on',
+    '**click only** — Tab focus does not trigger it. Prevents accidental popup during keyboard navigation.',
+  ].join(' '),
+);
+
+export const ErrorState: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <DateTimePicker
+          id="error-state-datetime"
+          hasError
+          aria-invalid={true}
+          aria-describedby="error-state-datetime-msg"
+        />
+        <p
+          id="error-state-datetime-msg"
+          role="alert"
+          style={{ margin: 'var(--spacing-xsmall) 0 0', color: 'var(--color-semantic-destructive-600)', fontSize: '0.875rem' }}
+        >
+          Please select a valid date and time.
+        </p>
+      </div>
+    ),
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DateTimePicker } from '@arbor-education/design-system.components';
 
-export const DisplayFormatFriendly: Story = {
-  name: 'Display format · friendly (text)',
-  args: {
-    displayFormat: 'friendly',
-    value: new Date(2026, 3, 14, 14, 27),
-    granularity: 'minute',
+// Standalone — set both hasError (visual) and aria-invalid (screen reader) yourself.
+// Inside <FormField> both are handled automatically when errorText is set.
+function DateTimePickerWithError() {
+  return (
+    <>
+      <DateTimePicker
+        id="event-start"
+        hasError
+        aria-invalid={true}
+        aria-describedby="event-start-error"
+      />
+      <p id="event-start-error" role="alert">
+        Please select a valid date and time.
+      </p>
+    </>
+  );
+}
+export default DateTimePickerWithError;
+`.trim(),
+        },
+      },
+    },
   },
-  render: args => <ControlledDateTimePicker {...args} />,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Combined value uses friendly wording, e.g. **April 14th, 2026 14:27**.',
+  [
+    '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.',
+    '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 { DateTimePicker } from '@arbor-education/design-system.components';
+
+function ControlledDateTimePickerExample() {
+  const [value, setValue] = useState<Date | undefined>(undefined);
+
+  return (
+    <div>
+      <DateTimePicker
+        id="event-datetime"
+        onChange={setValue}
+      />
+      <p>
+        Selected:{' '}
+        <code>
+          {value
+            ? \`\${value.toLocaleDateString('en-GB')} \${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}\`
+            : '(none)'}
+        </code>
+      </p>
+    </div>
+  );
+}
+export default ControlledDateTimePickerExample;
+`.trim(),
+        },
       },
     },
   },
-};
+  [
+    '`onChange` receives a `Date` object (or `undefined`) — never a string.',
+    'This controlled example stores the combined date+time in state and renders it below the field.',
+    'Use `toLocaleDateString` + `toLocaleTimeString` (or `date-fns format`) for display.',
+  ].join(' '),
+);
 
-export const PlaceholderCustomOverride: Story = {
-  name: 'Placeholder · custom copy',
-  args: {
-    granularity: 'minute',
-    placeholder: 'Event start (local)',
+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 EventStartField() {
+  return (
+    <FormField
+      label="Event start date and time"
+      id="event-start"
+      inputType="dateTimePicker"
+      fieldDescription="Select the date and time the event will begin."
+      inputProps={{
+        onChange: (date) => {
+          // date is Date | undefined
+          console.log('Event start:', date?.toLocaleString('en-GB'));
+        },
+      }}
+    />
+  );
+}
+export default EventStartField;
+`.trim(),
+        },
+      },
+    },
   },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Pass `placeholder` to replace the default native empty-state hint.',
+  [
+    'The recommended form usage: `<FormField inputType="dateTimePicker">` provides the accessible',
+    'label, description, and error layout. DateTimePicker props go in `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 LessonSchedulerForm() {
+  const [submitted, setSubmitted] = useState(false);
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+  const hasError = submitted && !selectedDate;
+
+  return (
+    <div>
+      <FormField
+        label="Lesson start date and time"
+        id="lesson-start"
+        inputType="dateTimePicker"
+        errorText={
+          hasError
+            ? 'Please select a date and time for the lesson.'
+            : undefined
+        }
+        inputProps={{
+          onChange: setSelectedDate,
+          hasError,
+          'aria-invalid': hasError ? true : undefined,
+        }}
+      />
+      <button type="button" onClick={() => setSubmitted(true)}>
+        Submit
+      </button>
+    </div>
+  );
+}
+export default LessonSchedulerForm;
+`.trim(),
+        },
       },
     },
   },
-  render: args => <ControlledDateTimePicker {...args} />,
-};
+  [
+    'A submit-gated form: clicking Submit without a selection triggers the full error pattern.',
+    '`errorText` on `<FormField>` renders the message in the correct accessible layout,',
+    'linked via `aria-describedby` automatically. Once a date+time is chosen, the error clears.',
+  ].join(' '),
+);