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

package/src/components/formField/inputs/time/TimeInput.stories.tsx

@@ -1,55 +1,341 @@
+import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Button } from 'Components/button/Button';
-import { useEffect, useState } from 'react';
-import { fn } from 'storybook/test';
-import { TimeInput, type TimeInputProps, type TimeValue } from './TimeInput';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { FormField } from 'Components/formField/FormField';
+import { TimeInput, type TimeValue } from './TimeInput';
 
-const timeOptions = ['09:00', '09:30', '10:00', '10:30', '11:00'] as const;
+// ---------------------------------------------------------------------------
+// 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 (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 
 const meta = {
   title: 'Components/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' },
+      },
+    },
+    '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' },
+      },
     },
-    value: {
+    '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' },
+      },
     },
   },
 } satisfies Meta<typeof TimeInput>;
 
 export default meta;
+type Story = StoryObj<typeof TimeInput>;
 
-type Story = StoryObj<typeof meta>;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description
+// ---------------------------------------------------------------------------
 
 const withDescription = (story: Story, description: string): Story => ({
   ...story,
@@ -64,107 +350,857 @@ const withDescription = (story: Story, description: string): Story => ({
   },
 });
 
-const ControlledTimeInput = (args: TimeInputProps) => {
-  const [value, setValue] = useState<TimeValue | ''>(args.value ?? args.defaultValue ?? '');
+// ---------------------------------------------------------------------------
+// Lesson period options (shared across combobox stories)
+// ---------------------------------------------------------------------------
+
+const LESSON_PERIOD_OPTIONS: TimeValue[] = [
+  '09:00',
+  '09:45',
+  '10:30',
+  '11:15',
+  '13:00',
+  '13:45',
+  '14:30',
+  '15:15',
+  '16:00',
+];
 
-  useEffect(() => {
-    setValue(args.value ?? args.defaultValue ?? '');
-  }, [args.defaultValue, args.value]);
+// ---------------------------------------------------------------------------
+// Named template components for stateful stories
+// ---------------------------------------------------------------------------
 
+const ControlledTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('09:30');
   return (
-    <TimeInput
-      {...args}
-      value={value}
-      onValueChange={(nextValue) => {
-        setValue(nextValue as TimeValue | '');
-        args.onValueChange?.(nextValue);
-      }}
-    />
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
+      <TimeInput
+        value={value}
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="controlled-time"
+        name="start-time"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Selected:
+        {' '}
+        <code>{value || '(none)'}</code>
+      </p>
+    </div>
   );
 };
 
-const NativeValidationDemo = (args: TimeInputProps) => {
-  const [value, setValue] = useState<TimeValue | ''>(args.value ?? '');
+const GranularitySecondTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
+      <TimeInput
+        granularity="second"
+        value={value}
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="second-granularity"
+        name="precise-time"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Selected:
+        {' '}
+        <code>{value || '(none)'}</code>
+      </p>
+    </div>
+  );
+};
 
-  useEffect(() => {
-    setValue(args.value ?? '');
-  }, [args.value]);
+const WithMinMaxBoundsTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
+      <TimeInput
+        min="08:00"
+        max="17:00"
+        value={value}
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="bounded-time"
+        name="school-time"
+        aria-label="School hours time"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Restricted to school hours: 08:00 – 17:00
+      </p>
+    </div>
+  );
+};
 
+const WithOptionsTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('');
   return (
-    <form
-      style={{ display: 'grid', gap: 12, width: 280 }}
-      onSubmit={(event) => {
-        event.preventDefault();
-        const form = event.currentTarget;
-        if (!form.reportValidity()) {
-          return;
-        }
-      }}
-    >
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
       <TimeInput
-        {...args}
+        options={LESSON_PERIOD_OPTIONS}
         value={value}
-        onValueChange={(nextValue) => {
-          setValue(nextValue as TimeValue | '');
-          args.onValueChange?.(nextValue);
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="lesson-period"
+        name="lesson-start"
+        placeholder="Select lesson period..."
+        aria-label="Lesson period"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Selected:
+        {' '}
+        <code>{value || '(none)'}</code>
+      </p>
+    </div>
+  );
+};
+
+const SubstringSearchTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
+      <TimeInput
+        options={LESSON_PERIOD_OPTIONS}
+        searchType="substring"
+        value={value}
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="substring-time"
+        name="lesson-substring"
+        placeholder="Type to search..."
+        aria-label="Lesson period"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Try typing
+        {' '}
+        <code>45</code>
+        {' '}
+        — matches any period containing "45".
+      </p>
+    </div>
+  );
+};
+
+const HighlightedMatchesTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
+      <TimeInput
+        options={LESSON_PERIOD_OPTIONS}
+        searchType="substring"
+        highlightStringMatches
+        value={value}
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="highlighted-time"
+        name="lesson-highlighted"
+        placeholder="Type to filter..."
+        aria-label="Lesson period"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Matched characters are bolded in the dropdown list.
+      </p>
+    </div>
+  );
+};
+
+const ControlledComboboxTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('13:00');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
+      <TimeInput
+        options={LESSON_PERIOD_OPTIONS}
+        value={value}
+        onValueChange={v => setValue(v as TimeValue | '')}
+        id="controlled-combobox"
+        name="lesson-controlled"
+        placeholder="Select lesson period..."
+        aria-label="Lesson period"
+      />
+      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Selected:
+        {' '}
+        <code>{value || '(none)'}</code>
+      </p>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// FormField template components
+// ---------------------------------------------------------------------------
+
+const InFormFieldTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <FormField
+      label="Lesson start time"
+      id="ff-start-time"
+      inputType="time"
+      inputProps={{ name: 'lesson-start', defaultValue: '09:00' }}
+    />
+  </div>
+);
+
+const InFormFieldWithErrorTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <FormField
+      label="Registration start time"
+      id="ff-error-time"
+      inputType="time"
+      errorText="Please enter a valid registration time."
+      inputProps={{ name: 'registration-time' }}
+    />
+  </div>
+);
+
+const InFormFieldComboboxTemplate = () => {
+  const [value, setValue] = useState<TimeValue | ''>('');
+  return (
+    <div style={{ maxWidth: '320px' }}>
+      <FormField
+        label="Lesson period"
+        id="ff-lesson-period"
+        inputType="time"
+        inputProps={{
+          name: 'lesson-period',
+          options: LESSON_PERIOD_OPTIONS,
+          value,
+          onValueChange: v => setValue(v as TimeValue | ''),
+          placeholder: 'Select a lesson period...',
         }}
       />
-      <Button variant="primary" size="M" type="submit">
-        Submit
-      </Button>
-    </form>
+    </div>
   );
 };
 
-export const NativeMinute: Story = withDescription({
+// ---------------------------------------------------------------------------
+// Stories — Native mode
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {
   args: {
-    value: '14:30',
-    granularity: 'minute',
+    'id': 'default-time',
+    'name': 'default-time',
+    'aria-label': 'Start time',
   },
-  render: args => <ControlledTimeInput {...args} />,
-}, 'Controlled native time input in minute mode. This story keeps local state on purpose to demonstrate the correct `value` + `onValueChange` integration pattern.');
+  render: args => (
+    <div style={{ maxWidth: '280px' }}>
+      <TimeInput {...args} />
+    </div>
+  ),
+};
 
-export const NativeSecond: Story = withDescription({
-  args: {
-    value: '14:30:15',
-    granularity: 'second',
+export const Controlled: Story = 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: () => <ControlledTemplate />,
   },
-  render: args => <ControlledTimeInput {...args} />,
-}, 'Controlled native time input in second mode, showing the same parent-managed state pattern with `HH:MM:SS` values.');
+  '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 NativeWithBounds: Story = withDescription({
-  args: {
-    value: '08:30',
-    granularity: 'minute',
-    min: '09:00',
-    max: '17:30',
+export const Uncontrolled: Story = 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: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <TimeInput
+          defaultValue="08:45"
+          id="uncontrolled-time"
+          name="registration-time"
+          aria-label="Registration time"
+        />
+      </div>
+    ),
   },
-  render: args => <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.');
+  '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 TimeList: Story = withDescription({
-  args: {
-    options: [...timeOptions],
-    value: '10:00',
-    placeholder: 'Select time',
+export const GranularitySecond: Story = 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: () => <GranularitySecondTemplate />,
   },
-  render: args => <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.');
+  '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 TimeListHighlightedMatches: Story = withDescription({
-  args: {
-    options: [...timeOptions],
-    value: '',
-    placeholder: 'Search times',
-    searchType: 'substring',
-    highlightStringMatches: true,
+export const WithMinMaxBounds: Story = 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: () => <WithMinMaxBoundsTemplate />,
   },
-  render: args => <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`.');
+  '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 UncontrolledNative: Story = withDescription({
-  args: {
-    defaultValue: '09:30',
-    granularity: 'minute',
+export const WithError: Story = 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: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <TimeInput
+          hasError
+          aria-invalid={true}
+          aria-label="End time"
+          id="end-time-error-story"
+          name="end-time"
+        />
+      </div>
+    ),
+  },
+  '`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: Story = 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: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <TimeInput
+          disabled
+          value="09:00"
+          aria-label="Lesson start time"
+          id="disabled-time-story"
+          name="disabled-time"
+        />
+      </div>
+    ),
+  },
+  '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: Story = 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: () => <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: Story = 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: () => <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: Story = 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: () => <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: Story = 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: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <TimeInput
+          options={LESSON_PERIOD_OPTIONS}
+          hasError
+          aria-invalid={true}
+          aria-label="Lesson period"
+          id="combobox-error-story"
+          name="lesson-error"
+          placeholder="Select a lesson period..."
+        />
+      </div>
+    ),
+  },
+  '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: Story = 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: () => (
+      <div style={{ maxWidth: '280px' }}>
+        <TimeInput
+          options={LESSON_PERIOD_OPTIONS}
+          disabled
+          value="09:00"
+          aria-label="Lesson period"
+          id="combobox-disabled-story"
+          name="lesson-disabled"
+        />
+      </div>
+    ),
+  },
+  'Combobox mode respects the `disabled` prop. The trigger button is non-interactive and visually muted, but the selected value remains readable.',
+);
+
+export const ControlledCombobox: Story = 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: () => <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: Story = 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: () => <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: Story = 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: () => <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: Story = 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(),
+        },
+      },
+    },
+    render: () => <InFormFieldComboboxTemplate />,
   },
-}, 'Uncontrolled native usage using `defaultValue`. This is useful when the parent does not need to drive the current value after initial render.');
+  '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.',
+);