@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-inputs-time-input.json

@@ -0,0 +1,775 @@
+{
+  "meta": {
+    "id": "Components-TimeInput",
+    "title": "Time input",
+    "exportName": "TimeInput",
+    "description": "A time input allows users to enter and select a specific time. It supports flexible input methods while ensuring accuracy and ease of use.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/time-input/time-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Time input"
+    ],
+    "route": "components/inputs/time-input",
+    "tags": [
+      "component",
+      "time",
+      "date"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visual options",
+        "href": "#visual-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Solid appearance",
+        "href": "#solid-appearance",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Ghost appearance",
+        "href": "#ghost-appearance",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nA time input enables users to enter and select a specific time. It offers\nflexible input methods while maintaining accuracy and usability.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React ARIA](https://react-spectrum.adobe.com/react-aria/TimeField.html)\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=3047-46447&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n#### Size\n\nMedium size is the default sizing used most commonly, with a small size for\ncompact use cases.\n\n```jsx live\nconst App = () => (\n  <Grid templateColumns=\"repeat(2, 1fr)\" gap=\"400\">\n    <TimeInput\n      size=\"md\"\n      hourCycle={24}\n      defaultValue={new Time(20, 0)}\n    />\n    <TimeInput\n      size=\"sm\"\n      hourCycle={12}\n      defaultValue={new Time(9, 30)}\n    />\n  </Grid>\n);\n```\n\n#### Solid appearance\n\nThis is the default styling, it provides a more prominent, filled style for\nstandard form usage where the input needs to stand out clearly.\n\n```jsx live\nconst App = () => (\n  <TimeInput\n    size=\"md\"\n    hourCycle={12}\n    defaultValue={new Time(15, 45)}\n    width=\"50%\"\n  />\n);\n```\n\n#### Ghost appearance\n\nOffers a minimalist style (e.g., no background fill, just a border) for\nintegration into uncluttered interfaces or specific contexts.\n\n```jsx live\nconst App = () => (\n  <TimeInput\n    size=\"md\"\n    variant=\"ghost\"\n    hourCycle={24}\n    defaultValue={new Time(7, 0)}\n    width=\"50%\"\n  />\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nA time input enables users to enter and select a specific time. It offers\nflexible input methods while maintaining accuracy and usability.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React ARIA](https://react-spectrum.adobe.com/react-aria/TimeField.html)\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=3047-46447&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n#### Size\n\nMedium size is the default sizing used most commonly, with a small size for\ncompact use cases.\n\n```jsx live\nconst App = () => (\n  <Grid templateColumns=\"repeat(2, 1fr)\" gap=\"400\">\n    <TimeInput\n      size=\"md\"\n      hourCycle={24}\n      defaultValue={new Time(20, 0)}\n    />\n    <TimeInput\n      size=\"sm\"\n      hourCycle={12}\n      defaultValue={new Time(9, 30)}\n    />\n  </Grid>\n);\n```\n\n#### Solid appearance\n\nThis is the default styling, it provides a more prominent, filled style for\nstandard form usage where the input needs to stand out clearly.\n\n```jsx live\nconst App = () => (\n  <TimeInput\n    size=\"md\"\n    hourCycle={12}\n    defaultValue={new Time(15, 45)}\n    width=\"50%\"\n  />\n);\n```\n\n#### Ghost appearance\n\nOffers a minimalist style (e.g., no background fill, just a border) for\nintegration into uncluttered interfaces or specific contexts.\n\n```jsx live\nconst App = () => (\n  <TimeInput\n    size=\"md\"\n    variant=\"ghost\"\n    hourCycle={24}\n    defaultValue={new Time(7, 0)}\n    width=\"50%\"\n  />\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual options",
+          "href": "#visual-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Solid appearance",
+          "href": "#solid-appearance",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ghost appearance",
+          "href": "#ghost-appearance",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <TimeInput\n    size=\"md\"\n    hourCycle={24}\n    defaultValue={new Time(10, 10)}\n    width=\"50%\"\n  />\n);\n```\n\n### Accessibility standards\n\n- **Provide clear labeling:** Use a `<label>` element that is programmatically\n  associated with the input field.\n- **Indicate required fields:** Visually mark required fields (e.g., with an\n  asterisk) and programmatically denote them using `aria-required=\"true\"`.\n- **Set an appropriate input type:** Use `type=\"time\"` for native browser\n  accessibility features and keyboard support.\n- **Include helpful instructions:** Offer clear instructions or formatting\n  guidance for the expected time format.\n- **Enable keyboard navigation:** Ensure users can tab through the input and\n  select times using only a keyboard.\n- **Support screen reader announcements:** Verify that screen readers announce\n  the input's purpose, current value, and any validation errors.\n- **Manage focus:** Maintain logical focus order when users interact with the\n  time input, especially with custom pickers.\n- **Provide accessible error messages:** Display validation errors clearly and\n  associate them with the input using `aria-describedby`.\n- **Use sufficient color contrast:** Ensure all text and interactive elements\n  have adequate color contrast against their background.\n- **Design for different input methods:** Consider touch targets for mobile\n  users and ensure compatibility with assistive technologies.\n- **Test with assistive technologies:** Validate accessibility with screen\n  readers and keyboard-only navigation.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { TimeInput, type TimeInputProps } from '@commercetools/nimbus';\nimport { Time, type TimeValue } from '@internationalized/date';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <TimeInput aria-label=\"Enter a time\" />\n)\n```\n\n## Working with @internationalized/date\n\nThe TimeInput component relies on `@internationalized/date`'s time value types for representing times. This library provides timezone-aware time handling and locale-specific formatting.\n\n### TimeValue types\n\nThe component accepts and returns `TimeValue` objects, which can be one of several types:\n\n```tsx\nimport { Time, ZonedDateTime } from '@internationalized/date';\n\n// A simple time without date or timezone\nconst simpleTime = new Time(14, 30); // 2:30 PM\n\n// A time with timezone from a full date-time\nconst zonedTime = parseZonedDateTime('2024-12-04T14:30[America/New_York]');\n```\n\n### Creating Time values\n\nUse the `Time` constructor to create time values:\n\n```tsx\nimport { Time } from '@internationalized/date';\n\n// Create a time: 9:30 AM\nconst morningTime = new Time(9, 30);\n\n// Create a time with seconds: 3:45:15 PM\nconst afternoonTime = new Time(15, 45, 15);\n```\n\n### Converting time values\n\nUse `toString()` to convert Time objects for display or storage:\n\n```tsx\nconst time = new Time(14, 30);\ntime.toString(); // \"14:30:00\"\n\n// Access individual components\ntime.hour;     // 14\ntime.minute;   // 30\ntime.second;   // 0\n```\n\n> [!TIP]\\\n> See [@internationalized/date documentation](https://react-spectrum.adobe.com/internationalized/date/) for complete API reference and advanced usage.\n\n## Usage examples\n\n### Size options\n\nThe `sm` and `md` size variants are available to match your interface density:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TimeInput size=\"sm\" aria-label=\"Small time input\" defaultValue={new Time(9, 30)} />\n    <TimeInput size=\"md\" aria-label=\"Medium time input\" defaultValue={new Time(15, 45)} />\n  </Stack>\n)\n```\n\n### Visual variants\n\nChoose between `solid` (default) and `ghost` variants to match your design context:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TimeInput variant=\"solid\" aria-label=\"Solid variant\" defaultValue={new Time(10, 0)} />\n    <TimeInput variant=\"ghost\" aria-label=\"Ghost variant\" defaultValue={new Time(14, 30)} />\n  </Stack>\n)\n```\n\n### Leading and trailing elements\n\nAdd icons or interactive elements before or after the time segments:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TimeInput\n      leadingElement={<Icon as={Icons.AccessTime} />}\n      aria-label=\"Time with leading icon\"\n      defaultValue={new Time(9, 0)}\n    />\n    <TimeInput\n      trailingElement={<Icon as={Icons.CalendarMonth} />}\n      aria-label=\"Time with trailing icon\"\n      defaultValue={new Time(17, 0)}\n    />\n    <TimeInput\n      leadingElement={<Icon as={Icons.AccessTime} />}\n      trailingElement={<Icon as={Icons.CalendarMonth} />}\n      aria-label=\"Time with both icons\"\n      defaultValue={new Time(12, 30)}\n    />\n  </Stack>\n)\n```\n\n### Hour cycle\n\nControl whether the time displays in 12-hour or 24-hour format using the `hourCycle` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">12-hour format</Text>\n      <TimeInput\n        hourCycle={12}\n        aria-label=\"12-hour format\"\n        defaultValue={new Time(14, 30)}\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">24-hour format</Text>\n      <TimeInput\n        hourCycle={24}\n        aria-label=\"24-hour format\"\n        defaultValue={new Time(14, 30)}\n      />\n    </Stack>\n  </Stack>\n)\n```\n\n**Behavioral differences:**\n- `hourCycle={12}`: Displays time with AM/PM indicator (e.g., 2:30 PM)\n- `hourCycle={24}`: Displays time in 24-hour format (e.g., 14:30)\n\n### Granularity\n\nThe `granularity` prop controls which time segments are displayed and editable:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">Hour only</Text>\n      <TimeInput\n        granularity=\"hour\"\n        aria-label=\"Hour granularity\"\n        defaultValue={new Time(14, 30, 45)}\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">Hour and minute (default)</Text>\n      <TimeInput\n        granularity=\"minute\"\n        aria-label=\"Minute granularity\"\n        defaultValue={new Time(14, 30, 45)}\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">Hour, minute, and second</Text>\n      <TimeInput\n        granularity=\"second\"\n        aria-label=\"Second granularity\"\n        defaultValue={new Time(14, 30, 45)}\n      />\n    </Stack>\n  </Stack>\n)\n```\n\n**Available granularities:**\n- `\"hour\"`: Only hour segment\n- `\"minute\"`: Hour and minute segments (default)\n- `\"second\"`: Hour, minute, and second segments\n\n### Hide timezone\n\nControl timezone visibility when using ZonedDateTime values:\n\n```jsx live-dev\nconst App = () => {\n  const zonedTime = parseZonedDateTime('2024-12-04T14:30[America/New_York]');\n  \n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontSize=\"sm\" fontWeight=\"semibold\">With timezone</Text>\n        <TimeInput\n          aria-label=\"With timezone\"\n          defaultValue={zonedTime}\n          hideTimeZone={false}\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontSize=\"sm\" fontWeight=\"semibold\">Without timezone</Text>\n        <TimeInput\n          aria-label=\"Without timezone\"\n          defaultValue={zonedTime}\n          hideTimeZone={true}\n        />\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Force leading zeros\n\nDisplay single-digit hours and minutes with leading zeros:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">Without leading zeros</Text>\n      <TimeInput\n        aria-label=\"Without leading zeros\"\n        defaultValue={new Time(9, 5)}\n        shouldForceLeadingZeros={false}\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">With leading zeros</Text>\n      <TimeInput\n        aria-label=\"With leading zeros\"\n        defaultValue={new Time(9, 5)}\n        shouldForceLeadingZeros={true}\n      />\n    </Stack>\n  </Stack>\n)\n```\n\n### Placeholder value\n\nThe `placeholderValue` sets the default values when a user first interacts with empty segments:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">With placeholder (starts at 9:00 AM)</Text>\n      <TimeInput\n        aria-label=\"With placeholder value\"\n        placeholderValue={new Time(9, 0)}\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" fontWeight=\"semibold\">Without placeholder (default behavior)</Text>\n      <TimeInput\n        aria-label=\"Without placeholder value\"\n      />\n    </Stack>\n  </Stack>\n)\n```\n\n### Min and max values\n\nRestrict selectable times using `minValue` and `maxValue`:\n\n```jsx live-dev\nconst App = () => {\n  const [time, setTime] = useState<TimeValue | null>(new Time(10, 0));\n  const minTime = new Time(9, 0);\n  const maxTime = new Time(17, 0);\n  \n  const isInvalid = time\n    ? (time.compare(minTime) < 0 || time.compare(maxTime) > 0)\n    : false;\n  \n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TimeInput\n        aria-label=\"Business hours only\"\n        value={time}\n        onChange={setTime}\n        minValue={minTime}\n        maxValue={maxTime}\n        isInvalid={isInvalid}\n      />\n      <Text fontSize=\"sm\" color={isInvalid ? \"critical.11\" : \"neutral.11\"}>\n        {isInvalid \n          ? \"Time must be between 9:00 AM and 5:00 PM\"\n          : \"Valid time range: 9:00 AM - 5:00 PM\"}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Disabled state\n\nPrevent user interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => (\n  <TimeInput\n    isDisabled\n    aria-label=\"Disabled time input\"\n    defaultValue={new Time(10, 30)}\n  />\n)\n```\n\n### Invalid state\n\nIndicate validation errors with the `isInvalid` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <TimeInput\n      isInvalid\n      aria-label=\"Invalid time\"\n      defaultValue={new Time(8, 0)}\n    />\n    <Text fontSize=\"sm\" color=\"critical.11\">\n      Selected time is outside business hours\n    </Text>\n  </Stack>\n)\n```\n\n### Read-only state\n\nDisplay time values without allowing edits:\n\n```jsx live-dev\nconst App = () => (\n  <TimeInput\n    isReadOnly\n    aria-label=\"Read-only time\"\n    defaultValue={new Time(14, 30)}\n  />\n)\n```\n\n### Required state\n\nMark the input as required for form validation:\n\n```jsx live-dev\nconst App = () => (\n  <TimeInput\n    isRequired\n    aria-label=\"Required time input\"\n  />\n)\n```\n\n### Uncontrolled mode\n\nFor simpler use cases, use uncontrolled mode with `defaultValue` and `onChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [displayValue, setDisplayValue] = useState<string>('No time selected');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TimeInput\n        defaultValue={new Time(9, 30)}\n        onChange={(value) => {\n          if (value) {\n            setDisplayValue(`Selected: ${value.toString()}`);\n          } else {\n            setDisplayValue('No time selected');\n          }\n        }}\n        aria-label=\"Uncontrolled time input\"\n      />\n      <Text fontSize=\"sm\">{displayValue}</Text>\n    </Stack>\n  );\n}\n```\n\nUse uncontrolled mode when you need to capture the selected time without managing state yourself.\n\n### Controlled mode\n\nFor scenarios requiring programmatic control or coordination with other components, use controlled mode:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<TimeInputProps[\"value\"]>(new Time(12, 0));\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TimeInput\n        value={value}\n        onChange={setValue}\n        aria-label=\"Controlled time input\"\n      />\n      <Stack direction=\"row\" gap=\"300\">\n        <Button onPress={() => setValue(new Time(9, 0))}>\n          Set to 9:00 AM\n        </Button>\n        <Button onPress={() => setValue(new Time(17, 0))}>\n          Set to 5:00 PM\n        </Button>\n        <Button variant=\"secondary\" onPress={() => setValue(null)}>\n          Clear\n        </Button>\n      </Stack>\n      <Text fontSize=\"sm\">\n        {value ? `Current time: ${value.toString()}` : 'No time selected'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\nUse controlled mode when you need to:\n- Synchronize the time with external state\n- Validate or transform time selections\n- Clear or programmatically set the time value\n\n### Different locales\n\nThe TimeInput automatically formats times according to the current locale:\n\n```jsx live-dev\nconst App = () => {\n  const sampleTime = new Time(14, 30);\n  \n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontSize=\"sm\" fontWeight=\"semibold\">US (en-US)</Text>\n        <NimbusI18nProvider locale=\"en-US\">\n          <TimeInput\n            aria-label=\"US locale\"\n            defaultValue={sampleTime}\n          />\n        </NimbusI18nProvider>\n      </Stack>\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontSize=\"sm\" fontWeight=\"semibold\">German (de-DE)</Text>\n        <NimbusI18nProvider locale=\"de-DE\">\n          <TimeInput\n            aria-label=\"German locale\"\n            defaultValue={sampleTime}\n          />\n        </NimbusI18nProvider>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Form integration\n\nIntegrate TimeInput with FormField for complete form layouts:\n\n```jsx live-dev\nconst App = () => {\n  const [time, setTime] = useState<TimeValue | null>(new Time(10, 30));\n  const minTime = new Time(9, 0);\n  const maxTime = new Time(17, 0);\n  \n  const isInvalid = time\n    ? (time.compare(minTime) < 0 || time.compare(maxTime) > 0)\n    : true;\n\n  return (\n    <FormField.Root isInvalid={isInvalid} isRequired>\n      <FormField.Label>Appointment Time</FormField.Label>\n      <FormField.Input>\n        <TimeInput\n          value={time}\n          onChange={setTime}\n          minValue={minTime}\n          maxValue={maxTime}\n          width=\"full\"\n        />\n      </FormField.Input>\n      <FormField.Description>\n        Select a time between 9:00 AM and 5:00 PM\n      </FormField.Description>\n      <FormField.Error>\n        The selected time must be between 9:00 AM and 5:00 PM\n      </FormField.Error>\n    </FormField.Root>\n  );\n}\n```\n\n## Component requirements\n\n### TimeValue requirements\n\nAll time values **must** use `@internationalized/date` types:\n- `Time` for simple time values without timezone\n- `ZonedDateTime` for times with timezone information\n- `TimeValue` as the union type for component props\n\n## Accessibility\n\nThe TimeInput handles most accessibility requirements internally. However, you must always associate an internationalized label with the component. Visual labels are preferable, and can be set by:\n\n- Using FormField with FormField.Label (recommended for forms)\n- Associating a `<label>` element with the TimeInput using `aria-labelledby`:\n\n```tsx\n<label id=\"time-label\">\n  {msg.format(labelMessage)}\n</label>\n<TimeInput aria-labelledby=\"time-label\" />\n```\n\n- Associating a `<label>` element with the TimeInput using `htmlFor`:\n\n```tsx\n<label htmlFor=\"time-input-id\">\n  {msg.format(labelMessage)}\n</label>\n<TimeInput id=\"time-input-id\" />\n```\n\nIf your design requires that the label should not be visible, the label should be set using the `aria-label` prop:\n\n```tsx\n<TimeInput aria-label={msg.format(labelMessage)} />\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"appointment-time-input\";\n\nexport const AppointmentForm = () => (\n  <TimeInput id={PERSISTENT_ID} aria-label=\"Appointment time\" />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus between segments and out of the component\n- `Arrow Up` / `Arrow Down`: Increment or decrement the focused segment\n- `Arrow Left` / `Arrow Right`: Move between time segments\n- `Number keys`: Directly type numeric values into segments\n- `A` / `P` (in 12-hour mode): Type \"A\" or \"P\" to set AM/PM\n\n## API reference\n\n<PropsTable id=\"TimeInput\" />\n\n## Common patterns\n\n### Business hours restriction\n\nLimit time selection to standard business hours:\n\n```jsx live-dev\nconst App = () => {\n  const [time, setTime] = useState<TimeValue | null>(new Time(9, 0));\n  const businessStart = new Time(9, 0);\n  const businessEnd = new Time(17, 0);\n  \n  const isOutsideBusinessHours = time\n    ? (time.compare(businessStart) < 0 || time.compare(businessEnd) > 0)\n    : false;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <TimeInput\n        value={time}\n        onChange={setTime}\n        minValue={businessStart}\n        maxValue={businessEnd}\n        isInvalid={isOutsideBusinessHours}\n        aria-label=\"Business hours\"\n      />\n      <Text fontSize=\"sm\" color=\"neutral.11\">\n        Business hours: 9:00 AM - 5:00 PM\n      </Text>\n      {isOutsideBusinessHours && (\n        <Text fontSize=\"sm\" color=\"critical.11\">\n          ⚠ Selected time is outside business hours\n        </Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n### Time range selector\n\nCreate start and end time inputs with validation:\n\n```jsx live-dev\nconst App = () => {\n  const [startTime, setStartTime] = useState<TimeValue | null>(new Time(9, 0));\n  const [endTime, setEndTime] = useState<TimeValue | null>(new Time(17, 0));\n  \n  const hasError = startTime && endTime && endTime.compare(startTime) <= 0;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"300\" alignItems=\"end\">\n        <Stack direction=\"column\" gap=\"200\" flex=\"1\">\n          <Text fontSize=\"sm\" fontWeight=\"semibold\">Start Time</Text>\n          <TimeInput\n            value={startTime}\n            onChange={setStartTime}\n            isInvalid={hasError}\n            aria-label=\"Start time\"\n          />\n        </Stack>\n        <Text fontSize=\"sm\" color=\"neutral.11\">to</Text>\n        <Stack direction=\"column\" gap=\"200\" flex=\"1\">\n          <Text fontSize=\"sm\" fontWeight=\"semibold\">End Time</Text>\n          <TimeInput\n            value={endTime}\n            onChange={setEndTime}\n            minValue={startTime ?? undefined}\n            isInvalid={hasError}\n            aria-label=\"End time\"\n          />\n        </Stack>\n      </Stack>\n      {hasError && (\n        <Text fontSize=\"sm\" color=\"critical.11\">\n          End time must be after start time\n        </Text>\n      )}\n      {!hasError && startTime && endTime && (\n        <Text fontSize=\"sm\" color=\"neutral.11\">\n          Duration: {endTime.hour - startTime.hour} hours\n        </Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using TimeInput within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the TimeInput component renders with expected elements and structure\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Basic rendering\", () => {\n  it(\"renders time input with accessible structure\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Enter a time\" />\n      </NimbusProvider>\n    );\n\n    const timeInput = screen.getByRole(\"group\", { name: /Enter a time/i });\n    expect(timeInput).toBeInTheDocument();\n  });\n\n  it(\"renders with default value\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" defaultValue={new Time(14, 30)} />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments.length).toBe(3);\n  });\n\n  it(\"renders with different sizes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Small time\" size=\"sm\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Medium time\" size=\"md\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n  });\n\n  it(\"renders with different variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Solid variant\" variant=\"solid\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Ghost variant\" variant=\"ghost\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with time segments using keyboard\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Interactions\", () => {\n  it(\"can focus and navigate between segments\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    const firstSegment = segments[0];\n\n    // Tab to focus first segment\n    await user.tab();\n    expect(firstSegment).toHaveFocus();\n\n    // Navigate to next segment\n    await user.keyboard(\"{ArrowRight}\");\n    expect(segments[1]).toHaveFocus();\n  });\n\n  it(\"increments and decrements segment values with arrow keys\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" defaultValue={new Time(10, 30)} />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    const hourSegment = segments[0];\n\n    await user.tab();\n    expect(hourSegment).toHaveFocus();\n\n    // Increment hour\n    await user.keyboard(\"{ArrowUp}\");\n    expect(hourSegment.textContent).toBe(\"11\");\n\n    // Decrement hour\n    await user.keyboard(\"{ArrowDown}\");\n    expect(hourSegment.textContent).toBe(\"10\");\n  });\n\n  it(\"calls onChange when time value changes\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Time input\"\n          defaultValue={new Time(10, 0)}\n          onChange={handleChange}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n\n    await user.tab();\n    expect(segments[0]).toHaveFocus();\n\n    await user.keyboard(\"{ArrowUp}\");\n\n    expect(handleChange).toHaveBeenCalled();\n    const newTime = handleChange.mock.calls[0][0];\n    expect(newTime).toHaveProperty(\"hour\");\n    expect(newTime).toHaveProperty(\"minute\");\n  });\n\n  it(\"allows direct numeric input\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    const hourSegment = segments[0];\n\n    await user.tab();\n    expect(hourSegment).toHaveFocus();\n\n    // Type a number\n    await user.keyboard(\"09\");\n    expect(hourSegment.textContent).toBe(\"9\");\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled component behavior with value prop\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Controlled mode\", () => {\n  it(\"respects controlled value prop\", () => {\n    const controlledTime = new Time(14, 30);\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Controlled time\"\n          value={controlledTime}\n          onChange={vi.fn()}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments[0].textContent).toBe(\"2\");\n    expect(segments[1].textContent).toBe(\"30\");\n  });\n\n  it(\"calls onChange with new Time value when user interacts\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    const controlledTime = new Time(10, 0);\n\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Controlled time\"\n          value={controlledTime}\n          onChange={handleChange}\n        />\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    await user.keyboard(\"{ArrowUp}\");\n\n    expect(handleChange).toHaveBeenCalled();\n    const newValue = handleChange.mock.calls[0][0] as Time;\n    expect(newValue.hour).toBe(11);\n  });\n\n  it(\"updates display when controlled value changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Controlled time\"\n          value={new Time(10, 0)}\n          onChange={vi.fn()}\n        />\n      </NimbusProvider>\n    );\n\n    let segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments[0].textContent).toBe(\"10\");\n\n    rerender(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Controlled time\"\n          value={new Time(15, 30)}\n          onChange={vi.fn()}\n        />\n      </NimbusProvider>\n    );\n\n    segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments[0].textContent).toBe(\"3\");\n    expect(segments[1].textContent).toBe(\"30\");\n  });\n});\n```\n\n### Uncontrolled Mode Tests\n\nTest uncontrolled component behavior with defaultValue prop\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Uncontrolled mode\", () => {\n  it(\"uses defaultValue for initial display\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Uncontrolled time\"\n          defaultValue={new Time(9, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments[0].textContent).toBe(\"9\");\n    expect(segments[1].textContent).toBe(\"30\");\n  });\n\n  it(\"manages internal state after user interaction\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Uncontrolled time\"\n          defaultValue={new Time(10, 0)}\n          onChange={handleChange}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n\n    await user.tab();\n    await user.keyboard(\"{ArrowUp}\");\n\n    expect(segments[0].textContent).toBe(\"11\");\n    expect(handleChange).toHaveBeenCalled();\n    const newTime = handleChange.mock.calls[0][0];\n    expect(newTime).toHaveProperty(\"hour\");\n    expect(newTime).toHaveProperty(\"minute\");\n  });\n});\n```\n\n### Hour Cycle Tests\n\nTest 12-hour and 24-hour format behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Hour cycle\", () => {\n  it(\"displays time in 12-hour format with AM/PM\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"12-hour format\"\n          hourCycle={12}\n          defaultValue={new Time(14, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments[0].textContent).toBe(\"2\"); // 2 PM\n\n    // Last segment should be AM/PM\n    const lastSegment = segments[segments.length - 1];\n    expect(lastSegment.textContent).toBe(\"PM\");\n  });\n\n  it(\"displays time in 24-hour format without AM/PM\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"24-hour format\"\n          hourCycle={24}\n          defaultValue={new Time(14, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments[0].textContent).toBe(\"14\");\n\n    // Should have hour and minute segments only (no AM/PM)\n    expect(segments.length).toBe(2);\n  });\n}); /**\n```\n\n### Granularity Tests\n\nTest different time granularity levels (hour, minute, second)\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Granularity\", () => {\n  it(\"shows only hour segment when granularity is hour\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Hour granularity\"\n          granularity=\"hour\"\n          defaultValue={new Time(14, 30, 45)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    // Should have hour and AM/PM segments only (in 12-hour format)\n    expect(segments.length).toBeLessThanOrEqual(2);\n  });\n\n  it(\"shows hour and minute segments when granularity is minute\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Minute granularity\"\n          granularity=\"minute\"\n          defaultValue={new Time(14, 30, 45)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments.length).toBeGreaterThanOrEqual(2);\n  });\n\n  it(\"shows hour, minute, and second segments when granularity is second\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Second granularity\"\n          granularity=\"second\"\n          defaultValue={new Time(14, 30, 45)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments.length).toBeGreaterThanOrEqual(3);\n  });\n});\n```\n\n### Validation Tests\n\nTest min/max value validation behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Validation\", () => {\n  it(\"accepts minValue prop\", () => {\n    const minTime = new Time(9, 0);\n\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Time with min\"\n          minValue={minTime}\n          defaultValue={new Time(10, 0)}\n        />\n      </NimbusProvider>\n    );\n\n    const timeInput = screen.getByRole(\"group\");\n    expect(timeInput).toBeInTheDocument();\n  });\n\n  it(\"accepts maxValue prop\", () => {\n    const maxTime = new Time(17, 0);\n\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Time with max\"\n          maxValue={maxTime}\n          defaultValue={new Time(16, 0)}\n        />\n      </NimbusProvider>\n    );\n\n    const timeInput = screen.getByRole(\"group\");\n    expect(timeInput).toBeInTheDocument();\n  });\n}); /**\n```\n\n### State Tests\n\nTest different component states (disabled, invalid, readonly, required)\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - States\", () => {\n  it(\"renders disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Disabled time\"\n          isDisabled\n          defaultValue={new Time(10, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const timeInput = screen.getByRole(\"group\");\n    expect(timeInput).toHaveAttribute(\"aria-disabled\", \"true\");\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    segments.forEach((segment) => {\n      expect(segment).toHaveAttribute(\"aria-disabled\", \"true\");\n    });\n  });\n\n  it(\"prevents interaction when disabled\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Disabled time\"\n          isDisabled\n          defaultValue={new Time(10, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    const hourSegment = segments[0];\n\n    await user.tab();\n\n    // Disabled segments should not receive focus\n    expect(hourSegment).not.toHaveFocus();\n  });\n\n  it(\"renders invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Invalid time\"\n          isInvalid\n          defaultValue={new Time(10, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const timeInput = screen.getByRole(\"group\");\n    expect(timeInput).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n\n  it(\"renders readonly state\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Readonly time\"\n          isReadOnly\n          defaultValue={new Time(10, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    segments.forEach((segment) => {\n      expect(segment).toHaveAttribute(\"aria-readonly\", \"true\");\n    });\n  });\n\n  it(\"prevents editing when readonly\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Readonly time\"\n          isReadOnly\n          defaultValue={new Time(10, 30)}\n        />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    const hourSegment = segments[0];\n    const initialValue = hourSegment.textContent;\n\n    await user.tab();\n    expect(hourSegment).toHaveFocus();\n\n    // Try to change value\n    await user.keyboard(\"{ArrowUp}\");\n\n    // Value should not change\n    expect(hourSegment.textContent).toBe(initialValue);\n  });\n\n  it(\"accepts isRequired prop\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Required time\" isRequired />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    segments.forEach((segment) => {\n      expect(segment).toHaveAttribute(\"aria-required\", \"true\");\n    });\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify ARIA attributes and keyboard navigation\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Accessibility\", () => {\n  it(\"has proper ARIA role\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" />\n      </NimbusProvider>\n    );\n\n    const timeInput = screen.getByRole(\"group\", { name: /Time input/i });\n    expect(timeInput).toBeInTheDocument();\n  });\n\n  it(\"supports aria-label\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Appointment time\" />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"group\", { name: /Appointment time/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"supports aria-labelledby\", () => {\n    render(\n      <NimbusProvider>\n        <div>\n          <span id=\"time-label\">Select time</span>\n          <TimeInput aria-labelledby=\"time-label\" />\n        </div>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"group\", { name: /Select time/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"time segments have spinbutton role\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" defaultValue={new Time(10, 30)} />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n    expect(segments.length).toBeGreaterThan(0);\n  });\n\n  it(\"supports keyboard navigation between segments\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" />\n      </NimbusProvider>\n    );\n\n    const segments = screen.getAllByRole(\"spinbutton\");\n\n    await user.tab();\n    expect(segments[0]).toHaveFocus();\n\n    await user.keyboard(\"{ArrowRight}\");\n    expect(segments[1]).toHaveFocus();\n\n    await user.keyboard(\"{ArrowLeft}\");\n    expect(segments[0]).toHaveFocus();\n  });\n});\n```\n\n### Form Integration Tests\n\nTest TimeInput integration with FormField component\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TimeInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Time } from \"@internationalized/date\";\n\ndescribe(\"TimeInput - Form integration\", () => {\n  it(\"integrates with FormField\", () => {\n    render(\n      <NimbusProvider>\n        <div>\n          <label htmlFor=\"time-field\">Meeting time</label>\n          <TimeInput\n            aria-label=\"Meeting time\"\n            id=\"time-field\"\n            defaultValue={new Time(10, 0)}\n          />\n        </div>\n      </NimbusProvider>\n    );\n\n    const label = screen.getByText(\"Meeting time\");\n    expect(label).toBeInTheDocument();\n\n    const timeInput = screen.getByRole(\"group\");\n    expect(timeInput).toBeInTheDocument();\n  });\n\n  it(\"displays validation errors in FormField context\", () => {\n    render(\n      <NimbusProvider>\n        <TimeInput\n          aria-label=\"Invalid time\"\n          isInvalid\n          defaultValue={new Time(10, 0)}\n        />\n      </NimbusProvider>\n    );\n\n    const timeInput = screen.getByRole(\"group\");\n    expect(timeInput).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n\n  it(\"calls onBlur when focus leaves the component\", async () => {\n    const user = userEvent.setup();\n    const handleBlur = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <TimeInput aria-label=\"Time input\" onBlur={handleBlur} />\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    await user.tab();\n    await user.tab();\n    await user.tab(); // Tab through all segments and out\n\n    expect(handleBlur).toHaveBeenCalled();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-timeinput--docs)\n- [React Aria TimeField](https://react-spectrum.adobe.com/react-aria/TimeField.html)\n- [@internationalized/date documentation](https://react-spectrum.adobe.com/internationalized/date/)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Working with @internationalized/date",
+          "href": "#working-with-internationalizeddate",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "TimeValue types",
+          "href": "#timevalue-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Creating Time values",
+          "href": "#creating-time-values",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Converting time values",
+          "href": "#converting-time-values",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Leading and trailing elements",
+          "href": "#leading-and-trailing-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Hour cycle",
+          "href": "#hour-cycle",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Granularity",
+          "href": "#granularity",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Hide timezone",
+          "href": "#hide-timezone",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Force leading zeros",
+          "href": "#force-leading-zeros",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placeholder value",
+          "href": "#placeholder-value",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Min and max values",
+          "href": "#min-and-max-values",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid state",
+          "href": "#invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            11
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            12
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Required state",
+          "href": "#required-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            13
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            14
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            15
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Different locales",
+          "href": "#different-locales",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            16
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form integration",
+          "href": "#form-integration",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            17
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "TimeValue requirements",
+          "href": "#timevalue-requirements",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            5,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Business hours restriction",
+          "href": "#business-hours-restriction",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Time range selector",
+          "href": "#time-range-selector",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled Mode Tests",
+          "href": "#uncontrolled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Hour Cycle Tests",
+          "href": "#hour-cycle-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Granularity Tests",
+          "href": "#granularity-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Validation Tests",
+          "href": "#validation-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State Tests",
+          "href": "#state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility Tests",
+          "href": "#accessibility-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form Integration Tests",
+          "href": "#form-integration-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nNumber input guidelines focus on clear labels, suitable ranges, easy interaction\nvia keyboard and buttons, and strong error handling, all while following WCAG\naccessibility rules.\n\n### Best practices\n\n- **Labels:** Always include a concise and clear label using sentence case.\n  Labels should not be hidden. In the rare case where context is sufficient and\n  label can be absent, review the design with an accessibility expert.\n- **Default values:** Provide a clear and logical default time when possible\n  (e.g., current time, a common start time like 9:00 AM). Avoid leaving the\n  input blank.\n- **Helper text:** Use helper text to indicate the expected time format (e.g.,\n  \"HH:MM AM/PM\", \"24-hour format\") or other constraints like valid time ranges.\n  It is optional and is replaced by error messages during validation.\n- **Validation:**\n  - Provide clear and concise error messages below the input field, replacing\n    any helper text.\n  - Highlight errors visually, for example, with a red border and an error icon.\n  - Validate the entered time against any defined constraints (e.g., valid time\n    format, time within allowed range).\n\n## Usage\n\nA time input enables users to enter or select a specific time, offering\nflexibility while maintaining precision.\n\n> [!TIP]\\\n> When to use\n\n- Inputting a specific time of day (e.g., appointment times, event schedules).\n- When time is a discrete data point rather than a duration.\n- When users need to select from a predefined set of time slots.\n\n> [!CAUTION]\\\n> When not to use\n\n- For durations (e.g., \"5 hours 30 minutes\"); use a separate duration input or a\n  set of number inputs.\n- When a broad range of continuous times is needed and exact entry is less\n  critical; a simple text input with a time format mask might suffice.\n- When users need to select a time zone along with the time; use a dedicated\n  time and time zone selector.\n\n## Keeping interactions simple\n\nTime inputs should be straightforward and require minimal effort from the user.\nThis includes clear labeling and error states, and aiding the user with\ndefaults.\n\n> [!TIP]\\\n> **Do**\n>\n> - Always include a label.\n> - Set a clear default time when relevant.\n> - Provide helper text for format or range constraints.\n> - Offer clear error messages and visual indicators.\n\n```jsx live\nconst App = () => (\n  <FormField.Root isInvalid>\n    <FormField.Label>Start time</FormField.Label>\n    <FormField.Input>\n      <TimeInput\n        size=\"md\"\n        hourCycle={24}\n        defaultValue={new Time(20, 15)}\n        width=\"50%\"\n      />\n    </FormField.Input>\n     <FormField.Error>\n      Start time can only be :30, :45, or :00.\n    </FormField.Error>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - You cannot use a time input for durations, instead use a date range input.\n> - Do not rely solely on color to indicate errors.\n> - Never hide labels.\n\n```jsx live\nconst App = () => (\n  <TimeInput\n    size=\"md\"\n    hourCycle={24}\n    defaultValue={new Time(20, 15)}\n    width=\"50%\"\n  />\n);\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keeping interactions simple",
+          "href": "#keeping-interactions-simple",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}