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

package/dist/components/dateTimePicker/DateTimePicker.stories.js

@@ -1,163 +1,734 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { formatNativeDateTimeInputValue } from '../datePicker/dateInputUtils';
-import { useEffect, useState } from 'react';
-import { fn } from 'storybook/test';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { FormField } from '../formField/FormField';
 import { DateTimePicker } from './DateTimePicker';
-const timeOptions = ['09:00', '09:30', '10:00', '10:30', '11:00'];
+// ---------------------------------------------------------------------------
+// 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 (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
     title: 'Components/DateTimePicker',
     component: DateTimePicker,
-    decorators: [
-        Story => (_jsx("div", { style: { maxWidth: '280px', width: '100%' }, children: _jsx(Story, {}) })),
-    ],
+    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"' },
+            },
         },
-        timeOptions: {
-            control: 'object',
-            description: 'When provided, the embedded time input switches to list-backed time selection.',
+        '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' },
+            },
         },
-        value: {
+        'onChange': {
             control: false,
-            description: 'Controlled combined datetime value for app-level state.',
+            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' },
+            },
         },
-        defaultValue: {
+        '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' },
+            },
+        },
+        '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' },
+            },
+        },
+        'defaultValue': {
             control: false,
-            description: 'Uncontrolled initial combined datetime value.',
+            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' },
+            },
         },
-        onChange: {
-            action: 'changed',
-            description: 'Called with the next combined `Date` value, or `undefined` when the date becomes invalid/cleared.',
+        'timeOptions': {
+            control: false,
+            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"' },
+            },
         },
-        placeholder: {
+        'highlightStringMatches': {
+            control: 'boolean',
+            description: '**Only used when `timeOptions` is provided.** Bolds matched characters in the time dropdown.',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'id': {
+            control: 'text',
+            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: 'Optional override for the field placeholder (defaults from `displayFormat` and `granularity`).',
+            description: 'ID of the element describing the field (e.g. an error message).',
+            table: {
+                type: { summary: 'string' },
+            },
         },
     },
 };
 export default meta;
-const ControlledDateTimePicker = ({ showCurrentValue = false, ...args }) => {
-    const [value, setValue] = useState(args.value);
-    useEffect(() => {
-        setValue(args.value);
-    }, [args.value]);
-    return (_jsxs("div", { style: { display: 'grid', gap: 12, width: '100%', maxWidth: 320 }, children: [_jsx(DateTimePicker, { ...args, value: value, onChange: (nextValue) => {
-                    setValue(nextValue);
-                    args.onChange?.(nextValue);
-                } }), showCurrentValue && (_jsxs("span", { children: ["Current value:", ' ', value ? formatNativeDateTimeInputValue(value, args.granularity) : 'None'] }))] }));
-};
-export const NativeTime = {
-    args: {
-        value: new Date(2026, 3, 14, 14, 27),
-        granularity: 'minute',
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: {
+            ...story.parameters?.docs,
+            description: {
+                story: description,
+            },
+        },
     },
-    render: args => _jsx(ControlledDateTimePicker, { ...args }),
+});
+// ---------------------------------------------------------------------------
+// Named template components for stateful stories
+// ---------------------------------------------------------------------------
+const APPOINTMENT_SLOTS = [
+    '09:00',
+    '09:30',
+    '10:00',
+    '10:30',
+    '11:00',
+    '11:30',
+    '14:00',
+    '14:30',
+    '15:00',
+    '15:30',
+];
+const DisplayFormatDefaultTemplate = () => {
+    const [value, setValue] = useState(new Date(2026, 3, 14, 14, 27));
+    return (_jsxs("div", { style: { maxWidth: '320px' }, children: [_jsx(DateTimePicker, { displayFormat: "default", value: value, onChange: setValue, id: "format-default" }), _jsxs("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }, children: ["Value:", ' ', _jsx("code", { children: value
+                            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+                            : '(none)' })] })] }));
 };
-export const TimeList = {
-    args: {
-        value: new Date(2026, 3, 14, 10, 0),
-        timeOptions: [...timeOptions],
-    },
-    render: args => _jsx(ControlledDateTimePicker, { ...args }),
+const DisplayFormatFriendlyTemplate = () => {
+    const [value, setValue] = useState(new Date(2026, 3, 14, 14, 27));
+    return (_jsxs("div", { style: { maxWidth: '320px' }, children: [_jsx(DateTimePicker, { displayFormat: "friendly", value: value, onChange: setValue, id: "format-friendly" }), _jsxs("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }, children: ["Value:", ' ', _jsx("code", { children: value
+                            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+                            : '(none)' })] })] }));
 };
-export const ControlledValuePreview = {
-    args: {
-        value: new Date(2026, 3, 14, 14, 27),
-        granularity: 'minute',
-    },
-    render: args => _jsx(ControlledDateTimePicker, { ...args, showCurrentValue: true }),
+const WithTimeOptionsTemplate = () => {
+    const [value, setValue] = useState(new Date(2026, 3, 14, 9, 0));
+    return (_jsxs("div", { style: { maxWidth: '280px' }, children: [_jsx(DateTimePicker, { timeOptions: APPOINTMENT_SLOTS, value: value, onChange: setValue, id: "time-options" }), _jsxs("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }, children: ["Appointment:", ' ', _jsx("code", { children: value
+                            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+                            : '(none)' })] })] }));
+};
+const GranularitySecondTemplate = () => {
+    const [value, setValue] = useState(undefined);
+    return (_jsxs("div", { style: { maxWidth: '280px' }, children: [_jsx(DateTimePicker, { granularity: "second", value: value, onChange: setValue, id: "granularity-second" }), _jsxs("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }, children: ["Value (with seconds):", ' ', _jsx("code", { children: value
+                            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB')}`
+                            : '(none)' })] })] }));
 };
-export const PlaceholderNativeMinuteHint = {
-    name: 'Placeholder · native minute hint',
+const ControlledWithDisplayTemplate = () => {
+    const [value, setValue] = useState(undefined);
+    return (_jsxs("div", { style: { maxWidth: '280px' }, children: [_jsx(DateTimePicker, { id: "controlled-display", onChange: setValue }), _jsxs("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }, children: ["Selected:", ' ', _jsx("code", { children: value
+                            ? `${value.toLocaleDateString('en-GB')} ${value.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}`
+                            : '(none)' })] })] }));
+};
+const WithFormFieldTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(FormField, { label: "Event start date and time", id: "ff-event-start", inputType: "dateTimePicker", fieldDescription: "Select the date and time the event will begin.", inputProps: {} }) }));
+const WithFormFieldAndErrorTemplate = () => {
+    const [submitted, setSubmitted] = useState(false);
+    const [selectedDate, setSelectedDate] = useState(undefined);
+    const hasError = submitted && !selectedDate;
+    return (_jsxs("div", { style: { maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(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,
+                } }), _jsx("div", { children: _jsx("button", { type: "button", onClick: () => setSubmitted(true), style: { padding: 'var(--spacing-small) var(--spacing-medium)' }, children: "Submit" }) }), submitted && selectedDate && (_jsxs("p", { style: { margin: 0, color: 'var(--color-semantic-success-600)', fontSize: '0.875rem' }, children: ["Lesson scheduled for", ' ', selectedDate.toLocaleDateString('en-GB'), ' at ', selectedDate.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }), "."] }))] }));
+};
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
     args: {
-        granularity: 'minute',
+        id: 'default-datetime',
     },
+    render: args => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(DateTimePicker, { ...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 WithDefaultValue = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(DateTimePicker, { id: "default-value-datetime", defaultValue: new Date(2026, 3, 14, 14, 27) }) })),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Uncontrolled, no initial value — empty-state hint shows `YYYY-MM-DDTHH:mm` (decorative span for native mode).',
+            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);
+
+  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(),
             },
         },
     },
-};
-export const PlaceholderNativeSecondHint = {
-    name: 'Placeholder · native second hint',
-    args: {
-        granularity: 'second',
+}, [
+    '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 = withDescription({
+    render: () => _jsx(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 = withDescription({
+    render: () => _jsx(DisplayFormatDefaultTemplate, {}),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Same as the minute story, but with `granularity="second"` so the hint includes seconds.',
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { DateTimePicker } from '@arbor-education/design-system.components';
+
+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(),
             },
         },
     },
-};
-export const DisplayFormatDefault = {
-    name: 'Display format · default (text)',
-    args: {
-        displayFormat: 'default',
-        value: new Date(2026, 3, 14, 14, 27),
-        granularity: 'minute',
+}, [
+    '`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 = withDescription({
+    render: () => _jsx(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(),
+            },
+        },
     },
-    render: args => _jsx(ControlledDateTimePicker, { ...args }),
+}, [
+    '`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 = withDescription({
+    render: () => _jsx(WithTimeOptionsTemplate, {}),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Combined value is shown and edited as **15/04/2026 14:27** instead of the native ISO string.',
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { DateTimePicker, type TimeValue } from '@arbor-education/design-system.components';
+
+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(),
             },
         },
     },
-};
-export const DisplayFormatFriendly = {
-    name: 'Display format · friendly (text)',
-    args: {
-        displayFormat: 'friendly',
-        value: new Date(2026, 3, 14, 14, 27),
-        granularity: 'minute',
+}, [
+    '`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 = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(DateTimePicker, { id: "placeholder-datetime", placeholder: "Choose event start" }) })),
+    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(),
+            },
+        },
     },
-    render: args => _jsx(ControlledDateTimePicker, { ...args }),
+}, [
+    '`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 = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '280px' }, children: [_jsx(DateTimePicker, { id: "error-state-datetime", hasError: true, "aria-invalid": true, "aria-describedby": "error-state-datetime-msg" }), _jsx("p", { id: "error-state-datetime-msg", role: "alert", style: { margin: 'var(--spacing-xsmall) 0 0', color: 'var(--color-semantic-destructive-600)', fontSize: '0.875rem' }, children: "Please select a valid date and time." })] })),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Combined value uses friendly wording, e.g. **April 14th, 2026 14:27**.',
+            source: {
+                language: 'tsx',
+                code: `
+import { DateTimePicker } from '@arbor-education/design-system.components';
+
+// 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(),
             },
         },
     },
-};
-export const PlaceholderCustomOverride = {
-    name: 'Placeholder · custom copy',
-    args: {
-        granularity: 'minute',
-        placeholder: 'Event start (local)',
+}, [
+    '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 = withDescription({
+    render: () => _jsx(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 WithFormField = withDescription({
+    render: () => _jsx(WithFormFieldTemplate, {}),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Pass `placeholder` to replace the default native empty-state hint.',
+            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(),
             },
         },
     },
-    render: args => _jsx(ControlledDateTimePicker, { ...args }),
-};
+}, [
+    '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 = withDescription({
+    render: () => _jsx(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(),
+            },
+        },
+    },
+}, [
+    '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(' '));
 //# sourceMappingURL=DateTimePicker.stories.js.map