@tribepad/themis 1.0.0

package/src/elements/TimeField/TimeField.stories.tsx

@@ -0,0 +1,671 @@
+/**
+ * TimeField Component Stories
+ * Storybook stories for TimeField component demonstrating all variants, sizes, and states
+ *
+ * @see timefield-prd.md for full requirements
+ */
+
+import { useState, type FormEventHandler } from 'react';
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { TimeField, Time } from './index';
+
+const meta = {
+  title: 'Elements/TimeField',
+  component: TimeField,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Accessible time input component with keyboard-editable segments. Built with React Aria TimeField primitive for WCAG 2.2 AAA compliance (7:1 contrast ratio, 44x44px touch targets). Supports 12/24-hour formats, granularity control, and i18n.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg'],
+      description: 'TimeField size variant',
+      table: {
+        defaultValue: { summary: 'default' },
+      },
+    },
+    granularity: {
+      control: 'select',
+      options: ['hour', 'minute', 'second'],
+      description: 'Time granularity (which segments to display)',
+      table: {
+        defaultValue: { summary: 'minute' },
+      },
+    },
+    hourCycle: {
+      control: 'select',
+      options: [12, 24],
+      description: '12-hour (with AM/PM) or 24-hour format',
+    },
+    label: {
+      control: 'text',
+      description: 'Label text for the time field',
+    },
+    description: {
+      control: 'text',
+      description: 'Helper text displayed below the input',
+    },
+    errorMessage: {
+      control: 'text',
+      description: 'Error message displayed when isInvalid is true',
+    },
+    isRequired: {
+      control: 'boolean',
+      description: 'Shows required indicator and sets aria-required',
+    },
+    isReadOnly: {
+      control: 'boolean',
+      description: 'Makes input read-only',
+    },
+    isDisabled: {
+      control: 'boolean',
+      description: 'Disables the input',
+    },
+    isInvalid: {
+      control: 'boolean',
+      description: 'Shows error styling and displays error message',
+    },
+    hideTimeZone: {
+      control: 'boolean',
+      description: 'Hides timezone display when using ZonedDateTime',
+    },
+  },
+} satisfies Meta<typeof TimeField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// =============================================================================
+// Basic Stories
+// =============================================================================
+
+export const Default: Story = {
+  args: {
+    label: 'Meeting Time',
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: 'Event Time',
+    description: 'Enter the time the event starts',
+  },
+};
+
+export const WithDefaultValue: Story = {
+  args: {
+    label: 'Meeting Time',
+    defaultValue: new Time(14, 30),
+    description: 'Pre-filled with 2:30 PM',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    label: 'Appointment Time',
+    isInvalid: true,
+    errorMessage: 'Please select a valid time',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Error state with validation message. Uses destructive styling for border and text.',
+      },
+    },
+  },
+};
+
+export const Required: Story = {
+  args: {
+    label: 'Start Time',
+    isRequired: true,
+    description: 'This field is required',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: 'Meeting Time',
+    defaultValue: new Time(9, 30),
+    isDisabled: true,
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: 'Confirmed Time',
+    defaultValue: new Time(14, 0),
+    isReadOnly: true,
+    description: 'This time cannot be changed',
+  },
+};
+
+// =============================================================================
+// Granularity Stories
+// =============================================================================
+
+export const HourOnly: Story = {
+  args: {
+    label: 'Shift Start',
+    granularity: 'hour',
+    defaultValue: new Time(9),
+    description: 'Hour granularity for shift scheduling',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Hour-only granularity. Shows only hour segment (and AM/PM in 12-hour mode).',
+      },
+    },
+  },
+};
+
+export const HourAndMinute: Story = {
+  args: {
+    label: 'Meeting Time',
+    granularity: 'minute',
+    defaultValue: new Time(14, 30),
+    description: 'Default granularity for most use cases',
+  },
+};
+
+export const WithSeconds: Story = {
+  args: {
+    label: 'Race Start',
+    granularity: 'second',
+    defaultValue: new Time(12, 0, 0),
+    description: 'Second granularity for precise timing',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Full granularity with seconds. Use for precise timing scenarios.',
+      },
+    },
+  },
+};
+
+export const AllGranularities: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <TimeField label="Hour Only" granularity="hour" defaultValue={new Time(9)} />
+      <TimeField label="Hour + Minute" granularity="minute" defaultValue={new Time(14, 30)} />
+      <TimeField
+        label="Hour + Minute + Second"
+        granularity="second"
+        defaultValue={new Time(12, 0, 45)}
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Comparison of all granularity levels: hour, minute, and second.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Hour Cycle Stories
+// =============================================================================
+
+export const TwelveHourFormat: Story = {
+  args: {
+    label: 'Appointment',
+    hourCycle: 12,
+    defaultValue: new Time(14, 30),
+    description: 'Shows 2:30 PM with AM/PM selector',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: '12-hour format with AM/PM segment. Common in US and UK.',
+      },
+    },
+  },
+};
+
+export const TwentyFourHourFormat: Story = {
+  args: {
+    label: 'Appointment',
+    hourCycle: 24,
+    defaultValue: new Time(14, 30),
+    description: 'Shows 14:30 without AM/PM',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: '24-hour format without AM/PM. Common in Europe and military time.',
+      },
+    },
+  },
+};
+
+export const HourCycleComparison: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <TimeField
+        label="12-hour Format"
+        hourCycle={12}
+        defaultValue={new Time(14, 30)}
+        description="2:30 PM"
+      />
+      <TimeField
+        label="24-hour Format"
+        hourCycle={24}
+        defaultValue={new Time(14, 30)}
+        description="14:30"
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Side-by-side comparison of 12-hour and 24-hour formats with the same time value.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Size Variants Stories
+// =============================================================================
+
+export const Small: Story = {
+  args: {
+    label: 'Time',
+    size: 'sm',
+    description: 'Compact size (36px height)',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    label: 'Time',
+    size: 'lg',
+    description: 'Large size (56px height)',
+  },
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <TimeField label="Small" size="sm" defaultValue={new Time(9, 0)} />
+      <TimeField label="Default" size="default" defaultValue={new Time(12, 0)} />
+      <TimeField label="Large" size="lg" defaultValue={new Time(18, 0)} />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All 3 size variants: sm (36px), default (44px), lg (56px). Default and large meet WCAG 2.2 AAA touch targets.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Validation Stories
+// =============================================================================
+
+export const WithMinValue: Story = {
+  args: {
+    label: 'Appointment Time',
+    minValue: new Time(9, 0),
+    defaultValue: new Time(9, 0),
+    description: 'Available from 9:00 AM',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Minimum time constraint. Times before 9:00 AM will be marked invalid.',
+      },
+    },
+  },
+};
+
+export const WithMaxValue: Story = {
+  args: {
+    label: 'Appointment Time',
+    maxValue: new Time(17, 0),
+    defaultValue: new Time(17, 0),
+    description: 'Available until 5:00 PM',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Maximum time constraint. Times after 5:00 PM will be marked invalid.',
+      },
+    },
+  },
+};
+
+export const WithMinAndMaxValue: Story = {
+  args: {
+    label: 'Office Hours',
+    minValue: new Time(9, 0),
+    maxValue: new Time(17, 0),
+    defaultValue: new Time(12, 0),
+    hourCycle: 12,
+    description: 'Available 9 AM - 5 PM',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Combined min/max constraints for business hours selection.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Form Integration Stories
+// =============================================================================
+
+export const WithFormName: Story = {
+  args: {
+    label: 'Meeting Time',
+    name: 'meetingTime',
+    defaultValue: new Time(14, 30),
+    description: 'Creates a hidden input for form submission',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Form integration with name prop. Value is serialized as HH:MM:SS format.',
+      },
+    },
+  },
+};
+
+export const FormExample: Story = {
+  render: () => {
+    const handleSubmit: FormEventHandler = (e) => {
+      e.preventDefault();
+      const form = e.currentTarget;
+      const formData = new FormData(form as unknown as globalThis.HTMLFormElement);
+      alert(`Start: ${formData.get('startTime')}\nEnd: ${formData.get('endTime')}`);
+    };
+
+    return (
+      <form onSubmit={handleSubmit} className="flex flex-col gap-4 w-80">
+        <TimeField
+          label="Start Time"
+          name="startTime"
+          defaultValue={new Time(9, 0)}
+          isRequired
+        />
+        <TimeField
+          label="End Time"
+          name="endTime"
+          defaultValue={new Time(17, 0)}
+          isRequired
+        />
+        <button
+          type="submit"
+          className="mt-2 rounded-md bg-[var(--primary)] px-4 py-2 text-sm font-medium text-[var(--primary-foreground)]"
+        >
+          Submit
+        </button>
+      </form>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Complete form example with two TimeFields. Submit to see the serialized values.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Controlled Mode Stories
+// =============================================================================
+
+export const ControlledMode: Story = {
+  render: () => {
+    const [time, setTime] = useState<typeof Time.prototype | null>(new Time(10, 30));
+
+    return (
+      <div className="flex flex-col gap-4 w-80">
+        <TimeField
+          label="Meeting Time"
+          value={time}
+          onChange={setTime}
+          hourCycle={12}
+        />
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Selected: {time ? `${time.hour}:${String(time.minute).padStart(2, '0')}` : 'None'}
+        </p>
+        <button
+          type="button"
+          onClick={() => setTime(new Time(12, 0))}
+          className="rounded-md bg-[var(--secondary)] px-3 py-1 text-sm"
+        >
+          Set to Noon
+        </button>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Controlled mode with external state management. The time value can be read and modified programmatically.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// All States Stories
+// =============================================================================
+
+export const AllStates: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <TimeField label="Default" />
+      <TimeField label="With Value" defaultValue={new Time(14, 30)} />
+      <TimeField label="Required" isRequired description="This field is required" />
+      <TimeField label="Invalid" isInvalid errorMessage="Please enter a valid time" />
+      <TimeField label="Disabled" isDisabled defaultValue={new Time(9, 0)} />
+      <TimeField label="Read-only" isReadOnly defaultValue={new Time(17, 0)} />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All state variants: default, with value, required, invalid, disabled, and read-only.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Real-World Examples
+// =============================================================================
+
+export const MeetingScheduler: Story = {
+  render: () => {
+    const [startTime, setStartTime] = useState<typeof Time.prototype | null>(new Time(9, 0));
+    const [endTime, setEndTime] = useState<typeof Time.prototype | null>(new Time(10, 0));
+
+    return (
+      <div className="flex flex-col gap-4 w-80">
+        <h3 className="text-lg font-semibold">Schedule Meeting</h3>
+        <TimeField
+          label="Start Time"
+          value={startTime}
+          onChange={setStartTime}
+          minValue={new Time(8, 0)}
+          maxValue={new Time(18, 0)}
+          hourCycle={12}
+          isRequired
+        />
+        <TimeField
+          label="End Time"
+          value={endTime}
+          onChange={setEndTime}
+          minValue={startTime || new Time(8, 0)}
+          maxValue={new Time(18, 0)}
+          hourCycle={12}
+          isRequired
+        />
+        {startTime && endTime && (
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Duration: {endTime.hour - startTime.hour} hour(s)
+          </p>
+        )}
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Meeting scheduler with start/end time validation. End time minimum is dynamically set to start time.',
+      },
+    },
+  },
+};
+
+export const BusinessHoursConfig: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-96">
+      <h3 className="text-lg font-semibold">Business Hours</h3>
+      <div className="grid grid-cols-2 gap-4">
+        <TimeField
+          label="Monday Open"
+          name="monday_open"
+          defaultValue={new Time(9, 0)}
+          hourCycle={12}
+          size="sm"
+        />
+        <TimeField
+          label="Monday Close"
+          name="monday_close"
+          defaultValue={new Time(17, 0)}
+          hourCycle={12}
+          size="sm"
+        />
+        <TimeField
+          label="Tuesday Open"
+          name="tuesday_open"
+          defaultValue={new Time(9, 0)}
+          hourCycle={12}
+          size="sm"
+        />
+        <TimeField
+          label="Tuesday Close"
+          name="tuesday_close"
+          defaultValue={new Time(17, 0)}
+          hourCycle={12}
+          size="sm"
+        />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Business hours configuration form using compact (sm) TimeFields in a grid layout.',
+      },
+    },
+  },
+};
+
+export const AlarmClock: Story = {
+  render: () => {
+    const [alarmTime, setAlarmTime] = useState<typeof Time.prototype | null>(new Time(7, 0));
+
+    return (
+      <div className="flex flex-col gap-4 w-80 items-center">
+        <h3 className="text-lg font-semibold">Set Alarm</h3>
+        <TimeField
+          label="Alarm Time"
+          value={alarmTime}
+          onChange={setAlarmTime}
+          hourCycle={12}
+          size="lg"
+        />
+        {alarmTime && (
+          <p className="text-2xl font-mono">
+            {alarmTime.hour > 12 ? alarmTime.hour - 12 : alarmTime.hour || 12}:
+            {String(alarmTime.minute).padStart(2, '0')}
+            {alarmTime.hour >= 12 ? ' PM' : ' AM'}
+          </p>
+        )}
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Alarm clock interface with large TimeField and formatted display.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Accessibility Stories
+// =============================================================================
+
+export const FocusVisible: Story = {
+  args: {
+    label: 'Focus Me',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tab to focus individual segments. Each segment shows a visible focus ring meeting WCAG 2.2 AAA standards.',
+      },
+    },
+  },
+};
+
+export const KeyboardNavigation: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-80">
+      <TimeField label="First Time" />
+      <TimeField label="Second Time" />
+      <TimeField label="Disabled" isDisabled />
+      <TimeField label="Third Time" />
+      <p className="text-sm text-[var(--muted-foreground)]">
+        Use Tab to move between fields. Arrow keys increment/decrement within segments.
+        Disabled fields are skipped.
+      </p>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Navigate between fields with Tab. Arrow Up/Down changes values. Disabled fields are skipped.',
+      },
+    },
+  },
+};
+
+export const ScreenReaderSupport: Story = {
+  args: {
+    label: 'Appointment Time',
+    description: 'Select a time for your appointment',
+    isRequired: true,
+    hourCycle: 12,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'All elements are properly linked via ARIA. Segments announce as spinbuttons with min/max values. Description linked via aria-describedby.',
+      },
+    },
+  },
+};