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

package/dist/components/formField/inputs/time/TimeInput.stories.js

@@ -1,49 +1,303 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Button } from '../../../button/Button';
-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 { TimeInput } from './TimeInput';
-const timeOptions = ['09:00', '09:30', '10:00', '10:30', '11:00'];
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'TimeInput is a flexible time-entry field that operates in **two distinct modes** depending on',
+    'whether the `options` prop is supplied.',
+    '',
+    '**Native mode** (no `options`) renders a browser-native `<input type="time">` decorated with a',
+    'clock icon. The browser handles the picker UI, spin-button keyboard navigation, and locale-aware',
+    'display. This mode supports `min`, `max`, `granularity`, `className`, a forwarded `ref`, and the',
+    'native `onChange` event.',
+    '',
+    '**Combobox mode** (`options` provided) replaces the native input with a searchable Combobox.',
+    'The user can type to filter or click to select from a predefined list of time values. This mode',
+    'supports `searchType` and `highlightStringMatches`, but ignores `min`, `max`, `granularity`,',
+    '`className`, `ref`, and `onChange`.',
+    '',
+    'Both modes share: `value`, `defaultValue`, `onValueChange`, `hasError`, `disabled`, `id`, `name`,',
+    '`placeholder`, and ARIA attributes.',
+].join('\n');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- **Any valid time** — use native mode (the default). The browser enforces valid time entry and',
+    '  supports `min`/`max` bounds for school hours (e.g. `min="08:00" max="17:00"`).',
+    '- **Fixed set of allowed times** — use combobox mode with `options`. Ideal for lesson periods,',
+    '  appointment slots, or any scenario where only specific times are valid.',
+    '- **Inside a form** — always wrap in `<FormField inputType="time">` so label, error text, and',
+    '  ARIA attributes are wired up automatically.',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Situation | Use instead |',
+    '|---|---|',
+    '| Date + time combined | Separate `DateInput` and `TimeInput` fields |',
+    '| Free-form duration entry | `TextInput` with format hint |',
+    '| More than ~50 time options | Native mode with `min`/`max` bounds |',
+    '| Status or category selection | `SelectDropdown` with meaningful labels |',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical usage patterns',
+    '',
+    '**Prop availability varies by mode.** Props that are native-only are silently ignored in combobox',
+    'mode, and vice versa:',
+    '',
+    '| Prop | Native mode | Combobox mode |',
+    '|---|---|---|',
+    '| `granularity` | Sets `step={1}` for second-level precision | **Ignored** |',
+    '| `min` / `max` | Restricts picker range | **Ignored** — filter `options` array instead |',
+    '| `className` | Applied to the wrapper `<div>` | **Ignored** |',
+    '| `ref` (forwarded) | Attached to the `<input>` element | **Ignored** |',
+    '| `onChange` | Native `ChangeEvent<HTMLInputElement>` | **Ignored** — use `onValueChange` |',
+    '| `searchType` | **Ignored** | Controls `prefix`/`substring` matching |',
+    '| `highlightStringMatches` | **Ignored** | Bolds matched characters in dropdown |',
+    '| `onValueChange` | Fires with the string value | Fires with the string value |',
+    '',
+    '**`aria-invalid` is NOT automatic.** When using TimeInput standalone (outside FormField),',
+    '`hasError` only applies visual error styling. It does NOT set `aria-invalid`:',
+    '',
+    '```tsx',
+    '// Standalone — set aria-invalid yourself:',
+    '<TimeInput hasError aria-invalid={true} aria-label="Start time" />',
+    '',
+    '// Inside FormField — aria-invalid is set automatically when errorText is present:',
+    '<FormField label="Start time" id="start" inputType="time" errorText="Required." inputProps={{}} />',
+    '```',
+    '',
+    '**`onValueChange` is the preferred callback** — it works in both modes and receives the plain',
+    'string value (`HH:MM` or `HH:MM:SS`). The native `onChange` event is only available in native',
+    'mode and is not forwarded in combobox mode.',
+    '',
+    '**`TimeValue` is format-shaped, not strictly validated.** The TypeScript type',
+    '`` `${string}:${string}` `` accepts `"99:99"` without complaint. The browser rejects it at render',
+    'time for `<input type="time">`, but the component itself does no validation.',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- Always provide a visible label via `<FormField>` or `aria-label` / `aria-labelledby`.',
+    '- In native mode, the browser\'s built-in time picker is fully keyboard-navigable (arrow keys',
+    '  cycle through the hour/minute/second segments; AM/PM toggles with A/P).',
+    '- In combobox mode, the Combobox component implements the ARIA combobox pattern',
+    '  (`role="combobox"`, `aria-expanded`, `aria-activedescendant`).',
+    '- The clock icon is decorative and carries `aria-hidden="true"`.',
+    '- Pair `hasError` with `aria-invalid={true}` when used standalone — one is visual, the other',
+    '  is for screen readers. `<FormField>` handles this automatically when `errorText` is set.',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { TimeInput, type TimeValue, type TimeGranularity } from '@arbor-education/design-system.components';",
+    '',
+    '// TimeValue: HH:MM or HH:MM:SS (format-shaped, not strictly validated)',
+    'type TimeValue = `${string}:${string}` | `${string}:${string}:${string}`;',
+    "type TimeGranularity = 'minute' | 'second';",
+    '',
+    '// Access types via the namespace:',
+    'function MyField(props: TimeInput.Props) { ... }',
+    '```',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[FormField](?path=/docs/components-formfield--docs) · [DateInput](?path=/docs/components-formfield-inputs-dateinput--docs) · [Combobox](?path=/docs/components-combobox--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 TimeInputDocsPage() {
+    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/FormField/Inputs/TimeInput',
     component: TimeInput,
+    tags: ['autodocs'],
     parameters: {
-        layout: 'centered',
+        layout: 'padded',
         docs: {
-            description: {
-                component: '`TimeInput` supports both native time entry and a combobox-backed time list. When you pass `value`, treat it as a controlled component and update it in `onValueChange`; use `defaultValue` for uncontrolled usage.',
-            },
+            page: TimeInputDocsPage,
         },
     },
-    tags: ['autodocs'],
-    args: {
-        onValueChange: fn(),
-    },
     argTypes: {
-        granularity: {
-            control: 'inline-radio',
-            options: ['minute', 'second'],
-            description: 'Controls whether the native time input works in minute or second increments.',
+        'value': {
+            description: [
+                'Controlled value in `HH:MM` or `HH:MM:SS` format.',
+                'Pair with `onValueChange` to keep state in sync.',
+                'If `undefined`, the component manages its own state (uncontrolled).',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: "TimeValue | ''" },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        'defaultValue': {
+            description: [
+                'Uncontrolled initial value in `HH:MM` or `HH:MM:SS` format.',
+                'Use when you only need the value on form submit, not on every change.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: "TimeValue | ''" },
+                defaultValue: { summary: "''" },
+            },
         },
-        options: {
+        'onValueChange': {
+            description: [
+                'Callback fired with the plain string value on every change.',
+                'Works in **both** native and combobox modes.',
+                'Prefer this over the native `onChange` event for cross-mode compatibility.',
+            ].join(' '),
+            action: 'onValueChange',
+            control: false,
+            table: {
+                type: { summary: '(value: string) => void' },
+            },
+        },
+        'options': {
+            description: [
+                'Array of `TimeValue` strings to display as selectable options.',
+                'Providing this prop switches to **combobox mode** — the native `<input type="time">` is',
+                'replaced by a searchable Combobox. Omit to use the browser-native time picker.',
+            ].join(' '),
             control: 'object',
-            description: 'When provided, `TimeInput` switches from native `input[type="time"]` to the combobox-backed time list mode.',
+            table: {
+                type: { summary: 'TimeValue[]' },
+                defaultValue: { summary: 'undefined' },
+            },
         },
-        value: {
+        'granularity': {
+            description: [
+                '**Native mode only.** Controls the precision of the time input.',
+                '`"second"` sets `step={1}` so the seconds segment is visible.',
+                'Silently ignored when `options` is provided.',
+            ].join(' '),
+            control: { type: 'select' },
+            options: ['minute', 'second'],
+            table: {
+                type: { summary: "'minute' | 'second'" },
+                defaultValue: { summary: "'minute'" },
+            },
+        },
+        'searchType': {
+            description: [
+                '**Combobox mode only.** Controls how options are filtered as the user types.',
+                '`"prefix"` (default) matches from the start of the string;',
+                '`"substring"` matches anywhere in the string.',
+                'Silently ignored in native mode.',
+            ].join(' '),
+            control: { type: 'select' },
+            options: ['prefix', 'substring'],
+            table: {
+                type: { summary: "'prefix' | 'substring'" },
+                defaultValue: { summary: "'prefix'" },
+            },
+        },
+        'highlightStringMatches': {
+            description: [
+                '**Combobox mode only.** When `true`, matched characters in dropdown options are bolded.',
+                'Silently ignored in native mode.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'hasError': {
+            description: [
+                'Applies error-state visual styling (red border).',
+                'Does **not** set `aria-invalid` automatically when used standalone outside FormField.',
+                'Always pair with `aria-invalid={true}` for screen-reader coverage.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'disabled': {
+            description: 'Disables the input. The current value remains visible.',
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'id': {
+            description: [
+                'HTML `id` for the input element.',
+                'Required when inside FormField so the `<label>` `htmlFor` can be linked.',
+            ].join(' '),
             control: 'text',
-            description: 'Controlled value. If you provide this, update it from `onValueChange` in your app or story state.',
+            table: {
+                type: { summary: 'string' },
+            },
         },
-        defaultValue: {
+        'name': {
+            description: 'HTML `name` attribute for native form submission.',
             control: 'text',
-            description: 'Uncontrolled initial value. Use this when you want the component to manage its own state.',
+            table: {
+                type: { summary: 'string' },
+            },
         },
-        onValueChange: {
-            action: 'value changed',
-            description: 'Called with the next string value (`HH:MM` or `HH:MM:SS`).',
+        'placeholder': {
+            description: 'Placeholder text shown when no value is selected. Most useful in combobox mode.',
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        'aria-label': {
+            description: [
+                'Accessible label for the input.',
+                'Required when the component is used standalone without a visible `<label>`.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        'aria-invalid': {
+            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(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'aria-describedby': {
+            description: 'ID of the element that describes the field (e.g. an error or hint message).',
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+            },
         },
     },
 };
 export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description
+// ---------------------------------------------------------------------------
 const withDescription = (story, description) => ({
     ...story,
     parameters: {
@@ -56,77 +310,582 @@ const withDescription = (story, description) => ({
         },
     },
 });
-const ControlledTimeInput = (args) => {
-    const [value, setValue] = useState(args.value ?? args.defaultValue ?? '');
-    useEffect(() => {
-        setValue(args.value ?? args.defaultValue ?? '');
-    }, [args.defaultValue, args.value]);
-    return (_jsx(TimeInput, { ...args, value: value, onValueChange: (nextValue) => {
-            setValue(nextValue);
-            args.onValueChange?.(nextValue);
-        } }));
+// ---------------------------------------------------------------------------
+// Lesson period options (shared across combobox stories)
+// ---------------------------------------------------------------------------
+const LESSON_PERIOD_OPTIONS = [
+    '09:00',
+    '09:45',
+    '10:30',
+    '11:15',
+    '13:00',
+    '13:45',
+    '14:30',
+    '15:15',
+    '16:00',
+];
+// ---------------------------------------------------------------------------
+// Named template components for stateful stories
+// ---------------------------------------------------------------------------
+const ControlledTemplate = () => {
+    const [value, setValue] = useState('09:30');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }, children: [_jsx(TimeInput, { value: value, onValueChange: v => setValue(v), id: "controlled-time", name: "start-time" }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Selected:", ' ', _jsx("code", { children: value || '(none)' })] })] }));
+};
+const GranularitySecondTemplate = () => {
+    const [value, setValue] = useState('');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }, children: [_jsx(TimeInput, { granularity: "second", value: value, onValueChange: v => setValue(v), id: "second-granularity", name: "precise-time" }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Selected:", ' ', _jsx("code", { children: value || '(none)' })] })] }));
 };
-const NativeValidationDemo = (args) => {
-    const [value, setValue] = useState(args.value ?? '');
-    useEffect(() => {
-        setValue(args.value ?? '');
-    }, [args.value]);
-    return (_jsxs("form", { style: { display: 'grid', gap: 12, width: 280 }, onSubmit: (event) => {
-            event.preventDefault();
-            const form = event.currentTarget;
-            if (!form.reportValidity()) {
-                return;
-            }
-        }, children: [_jsx(TimeInput, { ...args, value: value, onValueChange: (nextValue) => {
-                    setValue(nextValue);
-                    args.onValueChange?.(nextValue);
-                } }), _jsx(Button, { variant: "primary", size: "M", type: "submit", children: "Submit" })] }));
+const WithMinMaxBoundsTemplate = () => {
+    const [value, setValue] = useState('');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }, children: [_jsx(TimeInput, { min: "08:00", max: "17:00", value: value, onValueChange: v => setValue(v), id: "bounded-time", name: "school-time", "aria-label": "School hours time" }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Restricted to school hours: 08:00 \u2013 17:00" })] }));
 };
-export const NativeMinute = withDescription({
+const WithOptionsTemplate = () => {
+    const [value, setValue] = useState('');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }, children: [_jsx(TimeInput, { options: LESSON_PERIOD_OPTIONS, value: value, onValueChange: v => setValue(v), id: "lesson-period", name: "lesson-start", placeholder: "Select lesson period...", "aria-label": "Lesson period" }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Selected:", ' ', _jsx("code", { children: value || '(none)' })] })] }));
+};
+const SubstringSearchTemplate = () => {
+    const [value, setValue] = useState('');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }, children: [_jsx(TimeInput, { options: LESSON_PERIOD_OPTIONS, searchType: "substring", value: value, onValueChange: v => setValue(v), id: "substring-time", name: "lesson-substring", placeholder: "Type to search...", "aria-label": "Lesson period" }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Try typing", ' ', _jsx("code", { children: "45" }), ' ', "\u2014 matches any period containing \"45\"."] })] }));
+};
+const HighlightedMatchesTemplate = () => {
+    const [value, setValue] = useState('');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }, children: [_jsx(TimeInput, { options: LESSON_PERIOD_OPTIONS, searchType: "substring", highlightStringMatches: true, value: value, onValueChange: v => setValue(v), id: "highlighted-time", name: "lesson-highlighted", placeholder: "Type to filter...", "aria-label": "Lesson period" }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Matched characters are bolded in the dropdown list." })] }));
+};
+const ControlledComboboxTemplate = () => {
+    const [value, setValue] = useState('13:00');
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }, children: [_jsx(TimeInput, { options: LESSON_PERIOD_OPTIONS, value: value, onValueChange: v => setValue(v), id: "controlled-combobox", name: "lesson-controlled", placeholder: "Select lesson period...", "aria-label": "Lesson period" }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Selected:", ' ', _jsx("code", { children: value || '(none)' })] })] }));
+};
+// ---------------------------------------------------------------------------
+// FormField template components
+// ---------------------------------------------------------------------------
+const InFormFieldTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(FormField, { label: "Lesson start time", id: "ff-start-time", inputType: "time", inputProps: { name: 'lesson-start', defaultValue: '09:00' } }) }));
+const InFormFieldWithErrorTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(FormField, { label: "Registration start time", id: "ff-error-time", inputType: "time", errorText: "Please enter a valid registration time.", inputProps: { name: 'registration-time' } }) }));
+const InFormFieldComboboxTemplate = () => {
+    const [value, setValue] = useState('');
+    return (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(FormField, { label: "Lesson period", id: "ff-lesson-period", inputType: "time", inputProps: {
+                name: 'lesson-period',
+                options: LESSON_PERIOD_OPTIONS,
+                value,
+                onValueChange: v => setValue(v),
+                placeholder: 'Select a lesson period...',
+            } }) }));
+};
+// ---------------------------------------------------------------------------
+// Stories — Native mode
+// ---------------------------------------------------------------------------
+export const Default = {
     args: {
-        value: '14:30',
-        granularity: 'minute',
+        'id': 'default-time',
+        'name': 'default-time',
+        'aria-label': 'Start time',
     },
-    render: args => _jsx(ControlledTimeInput, { ...args }),
-}, 'Controlled native time input in minute mode. This story keeps local state on purpose to demonstrate the correct `value` + `onValueChange` integration pattern.');
-export const NativeSecond = withDescription({
-    args: {
-        value: '14:30:15',
-        granularity: 'second',
+    render: args => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(TimeInput, { ...args }) })),
+};
+export const Controlled = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+function ControlledTimeInputExample() {
+  const [value, setValue] = useState<TimeValue | ''>('09:30');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
+      <TimeInput
+        value={value}
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="start-time"
+        name="start-time"
+        aria-label="Start time"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Selected: <code>{value || '(none)'}</code>
+      </p>
+    </div>
+  );
+}
+
+export default ControlledTimeInputExample;
+          `.trim(),
+            },
+        },
     },
-    render: args => _jsx(ControlledTimeInput, { ...args }),
-}, 'Controlled native time input in second mode, showing the same parent-managed state pattern with `HH:MM:SS` values.');
-export const NativeWithBounds = withDescription({
-    args: {
-        value: '08:30',
-        granularity: 'minute',
-        min: '09:00',
-        max: '17:30',
-    },
-    render: args => _jsx(NativeValidationDemo, { ...args }),
-}, 'Demonstrates the browser-native min/max validation flow. Enter a time outside the allowed range and submit the form to let the browser show its own native validation message.');
-export const TimeList = withDescription({
-    args: {
-        options: [...timeOptions],
-        value: '10:00',
-        placeholder: 'Select time',
+    render: () => _jsx(ControlledTemplate, {}),
+}, 'A controlled TimeInput keeps the value in React state via `onValueChange`. This is the recommended pattern for forms where you need to read, validate, or derive other values from the selected time.');
+export const Uncontrolled = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { TimeInput } from '@arbor-education/design-system.components';
+
+function UncontrolledTimeInputExample() {
+  return (
+    <TimeInput
+      defaultValue="08:45"
+      id="uncontrolled-time"
+      name="registration-time"
+      aria-label="Registration time"
+    />
+  );
+}
+
+export default UncontrolledTimeInputExample;
+          `.trim(),
+            },
+        },
     },
-    render: args => _jsx(ControlledTimeInput, { ...args }),
-}, 'Controlled time-list mode using the combobox-backed variant. Selecting a time updates the local story state the same way an app component would.');
-export const TimeListHighlightedMatches = withDescription({
-    args: {
-        options: [...timeOptions],
-        value: '',
-        placeholder: 'Search times',
-        searchType: 'substring',
-        highlightStringMatches: true,
-    },
-    render: args => _jsx(ControlledTimeInput, { ...args }),
-}, 'Combobox-backed time-list mode with substring matching and highlighted text so consumers can review how search behaves when users type partial time fragments such as `30`.');
-export const UncontrolledNative = withDescription({
-    args: {
-        defaultValue: '09:30',
-        granularity: 'minute',
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(TimeInput, { defaultValue: "08:45", id: "uncontrolled-time", name: "registration-time", "aria-label": "Registration time" }) })),
+}, 'An uncontrolled TimeInput uses `defaultValue` to set the initial time. React does not track subsequent changes — the current value is read via a form `FormData` or a forwarded `ref`. Suitable for simple forms where you only need the value on submit.');
+export const GranularitySecond = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+function PreciseTimeInputExample() {
+  const [value, setValue] = useState<TimeValue | ''>('');
+
+  return (
+    <TimeInput
+      granularity="second"
+      value={value}
+      onValueChange={v => setValue(v as TimeValue | '')}
+      id="precise-time"
+      name="precise-time"
+      aria-label="Precise time"
+    />
+  );
+}
+
+export default PreciseTimeInputExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(GranularitySecondTemplate, {}),
+}, 'Setting `granularity="second"` adds a seconds segment to the native time input (`step={1}`). Use this for stopwatch-style timing or precise event logging. **Native mode only** — silently ignored when `options` is provided.');
+export const WithMinMaxBounds = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+function BoundedTimeInputExample() {
+  return (
+    <TimeInput
+      min="08:00"
+      max="17:00"
+      id="school-time"
+      name="school-time"
+      aria-label="School hours time"
+    />
+  );
+}
+
+export default BoundedTimeInputExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(WithMinMaxBoundsTemplate, {}),
+}, 'The `min` and `max` props restrict the selectable range in the native browser picker to school hours. **Native mode only** — in combobox mode, restrict available times by filtering the `options` array instead.');
+export const WithError = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { TimeInput } from '@arbor-education/design-system.components';
+
+// Standalone usage — you MUST set aria-invalid yourself.
+// Inside <FormField> this is handled automatically when errorText is present.
+function ErrorTimeInputExample() {
+  return (
+    <TimeInput
+      hasError
+      aria-invalid={true}
+      aria-label="End time"
+      id="end-time"
+      name="end-time"
+    />
+  );
+}
+
+export default ErrorTimeInputExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(TimeInput, { hasError: true, "aria-invalid": true, "aria-label": "End time", id: "end-time-error-story", name: "end-time" }) })),
+}, '`hasError` applies error-state visual styling. **Important:** it does NOT automatically set `aria-invalid` when used standalone — add that attribute yourself for screen-reader coverage. Inside `<FormField>`, both are set automatically when `errorText` is provided.');
+export const Disabled = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { TimeInput } from '@arbor-education/design-system.components';
+
+function DisabledTimeInputExample() {
+  return (
+    <TimeInput
+      disabled
+      value="09:00"
+      aria-label="Lesson start time"
+      id="disabled-time"
+      name="disabled-time"
+    />
+  );
+}
+
+export default DisabledTimeInputExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(TimeInput, { disabled: true, value: "09:00", "aria-label": "Lesson start time", id: "disabled-time-story", name: "disabled-time" }) })),
+}, 'A disabled TimeInput prevents user interaction. The current value remains visible, so users can still read the scheduled time. Pass `disabled` via `inputProps` when using inside `<FormField>`.');
+// ---------------------------------------------------------------------------
+// Stories — Combobox mode
+// ---------------------------------------------------------------------------
+export const WithOptions = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+const LESSON_PERIODS: TimeValue[] = [
+  '09:00', '09:45', '10:30', '11:15',
+  '13:00', '13:45', '14:30', '15:15', '16:00',
+];
+
+function LessonPeriodPickerExample() {
+  const [value, setValue] = useState<TimeValue | ''>('');
+
+  return (
+    <TimeInput
+      options={LESSON_PERIODS}
+      value={value}
+      onValueChange={v => setValue(v as TimeValue | '')}
+      id="lesson-period"
+      name="lesson-start"
+      placeholder="Select lesson period..."
+      aria-label="Lesson period"
+    />
+  );
+}
+
+export default LessonPeriodPickerExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(WithOptionsTemplate, {}),
+}, 'Providing an `options` array switches the component to **combobox mode**. The user can type to filter or click to select from the predefined list. Ideal for scheduling interfaces where only specific time slots are valid.');
+export const SubstringSearch = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+const LESSON_PERIODS: TimeValue[] = [
+  '09:00', '09:45', '10:30', '11:15',
+  '13:00', '13:45', '14:30', '15:15', '16:00',
+];
+
+function SubstringSearchPickerExample() {
+  const [value, setValue] = useState<TimeValue | ''>('');
+
+  return (
+    <TimeInput
+      options={LESSON_PERIODS}
+      searchType="substring"
+      value={value}
+      onValueChange={v => setValue(v as TimeValue | '')}
+      id="lesson-substring"
+      name="lesson-substring"
+      placeholder="Type to search..."
+      aria-label="Lesson period"
+    />
+  );
+}
+
+export default SubstringSearchPickerExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(SubstringSearchTemplate, {}),
+}, '`searchType="substring"` matches anywhere in the option string, not just the start. Try typing `"45"` to match `09:45`, `13:45`, and `14:45`. **Combobox mode only** — silently ignored in native mode.');
+export const HighlightedMatches = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+const LESSON_PERIODS: TimeValue[] = [
+  '09:00', '09:45', '10:30', '11:15',
+  '13:00', '13:45', '14:30', '15:15', '16:00',
+];
+
+function HighlightedMatchesPickerExample() {
+  const [value, setValue] = useState<TimeValue | ''>('');
+
+  return (
+    <TimeInput
+      options={LESSON_PERIODS}
+      searchType="substring"
+      highlightStringMatches
+      value={value}
+      onValueChange={v => setValue(v as TimeValue | '')}
+      id="lesson-highlighted"
+      name="lesson-highlighted"
+      placeholder="Type to filter..."
+      aria-label="Lesson period"
+    />
+  );
+}
+
+export default HighlightedMatchesPickerExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(HighlightedMatchesTemplate, {}),
+}, '`highlightStringMatches` bolds the matched characters in each dropdown option. Combine with `searchType="substring"` for maximum clarity when filtering. **Combobox mode only.**');
+export const ComboboxWithError = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+const LESSON_PERIODS: TimeValue[] = ['09:00', '09:45', '10:30', '11:15'];
+
+function ErrorComboboxTimeInputExample() {
+  return (
+    <TimeInput
+      options={LESSON_PERIODS}
+      hasError
+      aria-invalid={true}
+      aria-label="Lesson period"
+      id="lesson-error"
+      name="lesson-error"
+      placeholder="Select a lesson period..."
+    />
+  );
+}
+
+export default ErrorComboboxTimeInputExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(TimeInput, { options: LESSON_PERIOD_OPTIONS, hasError: true, "aria-invalid": true, "aria-label": "Lesson period", id: "combobox-error-story", name: "lesson-error", placeholder: "Select a lesson period..." }) })),
+}, 'Combobox mode supports `hasError` for error-state styling. As with native mode, `aria-invalid` must be set manually when used outside `<FormField>`.');
+export const ComboboxDisabled = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+const LESSON_PERIODS: TimeValue[] = ['09:00', '09:45', '10:30', '11:15'];
+
+function DisabledComboboxTimeInputExample() {
+  return (
+    <TimeInput
+      options={LESSON_PERIODS}
+      disabled
+      value="09:00"
+      aria-label="Lesson period"
+      id="lesson-disabled"
+      name="lesson-disabled"
+    />
+  );
+}
+
+export default DisabledComboboxTimeInputExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '280px' }, children: _jsx(TimeInput, { options: LESSON_PERIOD_OPTIONS, disabled: true, value: "09:00", "aria-label": "Lesson period", id: "combobox-disabled-story", name: "lesson-disabled" }) })),
+}, 'Combobox mode respects the `disabled` prop. The trigger button is non-interactive and visually muted, but the selected value remains readable.');
+export const ControlledCombobox = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
+
+const LESSON_PERIODS: TimeValue[] = [
+  '09:00', '09:45', '10:30', '11:15',
+  '13:00', '13:45', '14:30', '15:15', '16:00',
+];
+
+function ControlledComboboxTimeInputExample() {
+  const [value, setValue] = useState<TimeValue | ''>('13:00');
+
+  return (
+    <TimeInput
+      options={LESSON_PERIODS}
+      value={value}
+      onValueChange={v => setValue(v as TimeValue | '')}
+      id="lesson-controlled"
+      name="lesson-controlled"
+      placeholder="Select lesson period..."
+      aria-label="Lesson period"
+    />
+  );
+}
+
+export default ControlledComboboxTimeInputExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(ControlledComboboxTemplate, {}),
+}, 'A controlled combobox TimeInput pre-selects the afternoon session ("13:00") via the `value` prop. `onValueChange` keeps React state in sync whenever the user picks a different period.');
+// ---------------------------------------------------------------------------
+// Stories — FormField integration
+// ---------------------------------------------------------------------------
+export const InFormField = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function InFormFieldExample() {
+  return (
+    <div style={{ maxWidth: '320px' }}>
+      <FormField
+        label="Lesson start time"
+        id="lesson-start"
+        inputType="time"
+        inputProps={{ name: 'lesson-start', defaultValue: '09:00' }}
+      />
+    </div>
+  );
+}
+
+export default InFormFieldExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(InFormFieldTemplate, {}),
+}, 'The recommended usage pattern — `<FormField inputType="time">` wires the accessible `<label>`, `aria-describedby`, `hasError`, and `aria-invalid` automatically. No manual prop threading required.');
+export const InFormFieldWithError = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function InFormFieldWithErrorExample() {
+  return (
+    <div style={{ maxWidth: '320px' }}>
+      <FormField
+        label="Registration start time"
+        id="registration-time"
+        inputType="time"
+        errorText="Please enter a valid registration time."
+        inputProps={{ name: 'registration-time' }}
+      />
+    </div>
+  );
+}
+
+export default InFormFieldWithErrorExample;
+          `.trim(),
+            },
+        },
+    },
+    render: () => _jsx(InFormFieldWithErrorTemplate, {}),
+}, 'Setting `errorText` on `<FormField>` automatically applies error styling to the input, renders the error message, sets `aria-invalid`, and links `aria-describedby` to the error element. No extra props needed on `TimeInput` itself.');
+export const InFormFieldCombobox = withDescription({
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { FormField, type TimeValue } from '@arbor-education/design-system.components';
+
+const LESSON_PERIODS: TimeValue[] = [
+  '09:00', '09:45', '10:30', '11:15',
+  '13:00', '13:45', '14:30', '15:15', '16:00',
+];
+
+function InFormFieldComboboxExample() {
+  const [value, setValue] = useState<TimeValue | ''>('');
+
+  return (
+    <div style={{ maxWidth: '320px' }}>
+      <FormField
+        label="Lesson period"
+        id="lesson-period"
+        inputType="time"
+        inputProps={{
+          name: 'lesson-period',
+          options: LESSON_PERIODS,
+          value,
+          onValueChange: v => setValue(v as TimeValue | ''),
+          placeholder: 'Select a lesson period...',
+        }}
+      />
+    </div>
+  );
+}
+
+export default InFormFieldComboboxExample;
+          `.trim(),
+            },
+        },
     },
-}, 'Uncontrolled native usage using `defaultValue`. This is useful when the parent does not need to drive the current value after initial render.');
+    render: () => _jsx(InFormFieldComboboxTemplate, {}),
+}, 'Combobox mode works seamlessly inside `<FormField>`. Pass `options` (and any combobox-mode props) via `inputProps`. The label, ARIA wiring, and error handling are all handled identically to native mode.');
 //# sourceMappingURL=TimeInput.stories.js.map