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

package/dist/components/datePicker/DatePicker.stories.js

@@ -1,94 +1,622 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-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 { 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 (_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/DatePicker',
     component: DatePicker,
-    decorators: [
-        Story => (_jsx("div", { style: { maxWidth: '220px', width: '100%' }, children: _jsx(Story, {}) })),
-    ],
+    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' },
+            },
         },
-        placeholder: {
+        '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' },
+            },
+        },
+        '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' },
+            },
         },
     },
 };
 export default meta;
-export const Default = {
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...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(undefined);
+    return (_jsxs("div", { style: { maxWidth: '280px' }, children: [_jsx(DatePicker, { id: "controlled-display", onChange: setSelectedDate }), _jsxs("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)' }, children: ["Selected:", ' ', _jsx("code", { children: selectedDate ? selectedDate.toLocaleDateString('en-GB') : '(none)' })] })] }));
+};
+const ControlledWithValidationTemplate = () => {
+    const [selectedDate, setSelectedDate] = useState(undefined);
+    const [error, setError] = useState(undefined);
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    const handleChange = (date) => {
+        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 (_jsxs("div", { style: { maxWidth: '280px' }, children: [_jsx(DatePicker, { id: "validated-date", onChange: handleChange, hasError: !!error, "aria-invalid": error ? true : undefined, "aria-describedby": error ? 'validated-date-error' : undefined }), error && (_jsx("p", { id: "validated-date-error", role: "alert", style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-semantic-destructive-600)', fontSize: '0.875rem' }, children: error })), !error && selectedDate && (_jsxs("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-semantic-success-600)', fontSize: '0.875rem' }, children: ["Event date set:", ' ', selectedDate.toLocaleDateString('en-GB')] }))] }));
+};
+const WithFormFieldTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(FormField, { label: "Pupil enrollment date", id: "ff-enrollment-date", inputType: "datePicker", fieldDescription: "Select the date the pupil will join the school.", 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: "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,
+                } }), _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: ["Appointment booked for", ' ', selectedDate.toLocaleDateString('en-GB'), "."] }))] }));
 };
-export const FriendlyFormat = {
-    name: 'Friendly Format',
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    args: {
+        id: 'default-date',
+    },
+    render: args => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(DatePicker, { ...args }) })),
+}, [
+    '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 = withDescription({
     args: {
         displayFormat: 'friendly',
+        id: 'friendly-date',
     },
+    render: args => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(DatePicker, { ...args }) })),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'Empty field shows hint **Pick a date**.',
+            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(),
             },
         },
     },
-};
-/** `placeholder` overrides the default empty-state hint. */
-export const PlaceholderCustomOverride = {
-    name: 'Placeholder · custom copy',
-    args: {
-        displayFormat: 'default',
-        placeholder: 'e.g. 25/12/2024',
+}, '`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 = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(DatePicker, { id: "default-value-date", defaultValue: new Date(2024, 8, 1) }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { DatePicker } from '@arbor-education/design-system.components';
+
+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(),
+            },
+        },
     },
+}, [
+    '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 = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(DatePicker, { id: "placeholder-date", placeholder: "Choose term start date" }) })),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: 'The optional `placeholder` prop replaces the default hint.',
+            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(),
             },
         },
     },
-};
-/** Friendly format with custom hint copy. */
-export const PlaceholderFriendlyWithCustomCopy = {
-    name: 'Placeholder · friendly format, custom hint',
-    args: {
-        displayFormat: 'friendly',
-        placeholder: 'Choose a date…',
+}, [
+    '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 = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '280px' }, children: [_jsx(DatePicker, { id: "error-state-date", hasError: true, "aria-invalid": true, "aria-describedby": "error-state-msg" }), _jsx("p", { id: "error-state-msg", role: "alert", style: { margin: 'var(--spacing-xsmall) 0 0', color: 'var(--color-semantic-destructive-600)', fontSize: '0.875rem' }, children: "Please select a valid enrollment date." })] })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { DatePicker } 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 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(),
+            },
+        },
     },
+}, [
+    '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 = withDescription({
+    render: () => _jsx(ControlledWithDisplayTemplate, {}),
     parameters: {
+        controls: { disable: true },
         docs: {
-            description: {
-                story: '`displayFormat="friendly"` with a custom hint instead of **Pick a date**.',
+            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 = withDescription({
+    render: () => _jsx(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 = withDescription({
+    render: () => _jsx(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 = 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 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(' '));
 //# sourceMappingURL=DatePicker.stories.js.map