@commercetools/nimbus-mcp 0.1.0 → 2.11.0

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

@@ -0,0 +1,628 @@
+{
+  "meta": {
+    "id": "Components-DateInput",
+    "title": "Date input",
+    "exportName": "DateInput",
+    "description": "A date input component allows users to enter a specific date.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/date-input/date-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Date input"
+    ],
+    "route": "components/inputs/date-input",
+    "tags": [
+      "component",
+      "date",
+      "calendar"
+    ],
+    "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"
+      }
+    ],
+    "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\nThe date input field uses a conventional date format, such as mm/dd/yyyy, which\nis localized based on the user's region. Users can type a date directly into the\nfield. The component automatically formats the input as the user types.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma Link](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY?node-id=5818-15933#1436729216)\n[Storybook Link](https://nimbus-storybook.vercel.app/?path=/docs/components-date-dateinput--docs)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n**Medium**\n\n```jsx live\nconst App = () => <DateInput aria-label=\"Enter a date\"/>\n```\n\n**Small**\n\n```jsx live\nconst App = () => <DateInput size=\"sm\" aria-label=\"Enter a date\"/>\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe date input field uses a conventional date format, such as mm/dd/yyyy, which\nis localized based on the user's region. Users can type a date directly into the\nfield. The component automatically formats the input as the user types.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma Link](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY?node-id=5818-15933#1436729216)\n[Storybook Link](https://nimbus-storybook.vercel.app/?path=/docs/components-date-dateinput--docs)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n**Medium**\n\n```jsx live\nconst App = () => <DateInput aria-label=\"Enter a date\"/>\n```\n\n**Small**\n\n```jsx live\nconst App = () => <DateInput size=\"sm\" aria-label=\"Enter a date\"/>\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"
+        }
+      ]
+    },
+    "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  <DateInput aria-label=\"Enter a date\" />\n);\n```\n\n### Accessibility standards\n\n- Ensure the input field has a clear, descriptive label that is programmatically\n  associated with the input element.\n- The component should be fully operable using a keyboard.\n- The focus order must be logical and predictable.\n- The component should be compatible with screen readers, announcing its\n  purpose, state, and any validation errors.\n- Error messages should be clearly linked to the input field they refer to and\n  be announced by screen readers.\n- Maintain sufficient color contrast for text and other visual elements to\n  ensure readability.\n- The input field and any interactive elements should have large enough touch\n  targets for mobile users.\n- The date format should align with the user's regional settings and be easily\n  understandable.\n- Use appropriate autocomplete attributes, such as birthday, to assist users and\n  improve form-filling.\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 { DateInput, type DateInputProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode with an accessible label:\n\n```jsx live-dev\nconst App = () => (\n  <DateInput aria-label=\"Enter a date\" />\n)\n```\n\n## Working with date values\n\nThe DateInput component relies on `@internationalized/date`'s date types for type-safe date handling. This library provides calendar-system-aware date representations that work correctly across different locales and time zones.\n\n### Date types\n\nThe library provides several date types, each with different levels of precision:\n\n```tsx\nimport { CalendarDate, CalendarDateTime, ZonedDateTime } from '@internationalized/date';\n\n// Date only (no time component)\nconst date = new CalendarDate(2025, 6, 15);\n\n// Date and time (no timezone)\nconst dateTime = new CalendarDateTime(2025, 6, 15, 14, 30, 0);\n\n// Date, time, and timezone\nconst zonedDateTime = new ZonedDateTime(\n  2025,\n  6,\n  15,\n  'America/New_York',\n  -4 * 60 * 60 * 1000,\n  14,\n  30,\n  0\n);\n```\n\n### Creating date values\n\nUse the appropriate constructor based on the precision you need:\n\n```tsx\nimport { CalendarDate, CalendarDateTime } from '@internationalized/date';\n\n// For date-only inputs\nconst birthDate = new CalendarDate(1990, 5, 15);\n\n// For date and time inputs\nconst appointmentTime = new CalendarDateTime(2025, 12, 25, 10, 30, 0);\n```\n\n### Converting to strings\n\nUse the `toString()` method to convert date values to ISO 8601 format:\n\n```tsx\nconst date = new CalendarDate(2025, 6, 15);\ndate.toString(); // \"2025-06-15\"\n\nconst dateTime = new CalendarDateTime(2025, 6, 15, 14, 30, 0);\ndateTime.toString(); // \"2025-06-15T14:30:00\"\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    <DateInput size=\"sm\" aria-label=\"Small date input\" />\n    <DateInput size=\"md\" aria-label=\"Medium date input\" />\n  </Stack>\n)\n```\n\n### Visual variants\n\nChoose between `solid`, `ghost`, and `plain` variants to match your design context:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <DateInput variant=\"solid\" aria-label=\"Solid variant\" />\n    <DateInput variant=\"ghost\" aria-label=\"Ghost variant\" />\n    <DateInput variant=\"plain\" aria-label=\"Plain variant\" />\n  </Stack>\n)\n```\n\n**Behavioral differences:**\n- `variant=\"solid\"`: Outlined input with background, suitable for forms\n- `variant=\"ghost\"`: Subtle background on hover, suitable for inline editing\n- `variant=\"plain\"`: No background or border, suitable for minimal interfaces\n\n### Leading and trailing elements\n\nAdd icons or interactive elements to enhance the input:\n\n```jsx live-dev\nconst App = () => {\n  const [date, setDate] = useState(null);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DateInput\n        leadingElement={<Icons.CalendarMonth />}\n        aria-label=\"Date with calendar icon\"\n      />\n      <DateInput\n        trailingElement={\n          <IconButton\n            size=\"xs\"\n            variant=\"ghost\"\n            aria-label=\"Clear date\"\n            onPress={() => setDate(null)}\n          >\n            <Icons.Close />\n          </IconButton>\n        }\n        value={date}\n        onChange={setDate}\n        aria-label=\"Date with clear button\"\n      />\n      <DateInput\n        leadingElement={<Icons.Event />}\n        trailingElement={<Icons.ArrowDropDown />}\n        aria-label=\"Date with both icons\"\n      />\n    </Stack>\n  );\n}\n```\n\n### Granularity control\n\nThe `granularity` prop controls which date/time segments are displayed:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Day (date only)</Text>\n      <DateInput\n        granularity=\"day\"\n        defaultValue={new CalendarDate(2025, 6, 15)}\n        aria-label=\"Day granularity\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Hour (date + hour)</Text>\n      <DateInput\n        granularity=\"hour\"\n        defaultValue={new CalendarDateTime(2025, 6, 15, 14, 0, 0)}\n        aria-label=\"Hour granularity\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Minute (date + hour + minute)</Text>\n      <DateInput\n        granularity=\"minute\"\n        defaultValue={new CalendarDateTime(2025, 6, 15, 14, 30, 0)}\n        aria-label=\"Minute granularity\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Second (full precision)</Text>\n      <DateInput\n        granularity=\"second\"\n        defaultValue={new CalendarDateTime(2025, 6, 15, 14, 30, 45)}\n        aria-label=\"Second granularity\"\n      />\n    </Stack>\n  </Stack>\n)\n```\n\n### Hour cycle\n\nControl the time display format using the `hourCycle` prop when working with time values:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">12-hour format (2:30 PM)</Text>\n      <DateInput\n        defaultValue={new CalendarDateTime(2025, 6, 15, 14, 30, 0)}\n        hourCycle={12}\n        granularity=\"minute\"\n        aria-label=\"12-hour format\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">24-hour format (14:30)</Text>\n      <DateInput\n        defaultValue={new CalendarDateTime(2025, 6, 15, 14, 30, 0)}\n        hourCycle={24}\n        granularity=\"minute\"\n        aria-label=\"24-hour format\"\n      />\n    </Stack>\n  </Stack>\n)\n```\n\n### Leading zeros\n\nControl whether single-digit values display with leading zeros:\n\n```jsx live-dev\nconst App = () => {\n  const singleDigitDate = new CalendarDate(2025, 3, 5);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"100\">\n        <Text fontSize=\"sm\" fontWeight=\"600\">Default (locale-determined)</Text>\n        <DateInput\n          defaultValue={singleDigitDate}\n          aria-label=\"Default leading zeros\"\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"100\">\n        <Text fontSize=\"sm\" fontWeight=\"600\">Force leading zeros (05/03/2025)</Text>\n        <DateInput\n          defaultValue={singleDigitDate}\n          shouldForceLeadingZeros={true}\n          aria-label=\"With leading zeros\"\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"100\">\n        <Text fontSize=\"sm\" fontWeight=\"600\">No leading zeros (5/3/2025)</Text>\n        <DateInput\n          defaultValue={singleDigitDate}\n          shouldForceLeadingZeros={false}\n          aria-label=\"Without leading zeros\"\n        />\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Time zone handling\n\nWhen using `ZonedDateTime` values, control time zone display with the `hideTimeZone` prop:\n\n```jsx live-dev\nconst App = () => {\n  const zonedDateTime = new ZonedDateTime(\n    2025,\n    6,\n    15,\n    'America/New_York',\n    -4 * 60 * 60 * 1000,\n    14,\n    30,\n    0\n  );\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"100\">\n        <Text fontSize=\"sm\" fontWeight=\"600\">With time zone displayed</Text>\n        <DateInput\n          defaultValue={zonedDateTime}\n          hideTimeZone={false}\n          granularity=\"minute\"\n          aria-label=\"Date with timezone\"\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"100\">\n        <Text fontSize=\"sm\" fontWeight=\"600\">Time zone hidden</Text>\n        <DateInput\n          defaultValue={zonedDateTime}\n          hideTimeZone={true}\n          granularity=\"minute\"\n          aria-label=\"Date without timezone\"\n        />\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Placeholder values\n\nSet a starting point for keyboard input when the field is empty using `placeholderValue`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">With placeholder (starts at 2025-06-15)</Text>\n      <DateInput\n        placeholderValue={new CalendarDate(2025, 6, 15)}\n        aria-label=\"Date with placeholder\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Without placeholder (starts at today)</Text>\n      <DateInput aria-label=\"Date without placeholder\" />\n    </Stack>\n  </Stack>\n)\n```\n\n### Min/max validation\n\nRestrict date selection to a specific range using `minValue` and `maxValue`:\n\n```jsx live-dev\nconst App = () => {\n  const [date, setDate] = useState(null);\n  const minDate = new CalendarDate(2025, 6, 1);\n  const maxDate = new CalendarDate(2025, 6, 30);\n  \n  const isInvalid = date && (\n    date.compare(minDate) < 0 || \n    date.compare(maxDate) > 0\n  );\n\n  return (\n    <FormField.Root isInvalid={!!isInvalid}>\n      <FormField.Label>Select a date in June 2025</FormField.Label>\n      <FormField.Input>\n        <DateInput\n          value={date}\n          onChange={setDate}\n          minValue={minDate}\n          maxValue={maxDate}\n          aria-label=\"Date range validation\"\n        />\n      </FormField.Input>\n      <FormField.Description>\n        Valid range: June 1-30, 2025\n      </FormField.Description>\n      {isInvalid && (\n        <FormField.Error>\n          Date must be between {minDate.toString()} and {maxDate.toString()}\n        </FormField.Error>\n      )}\n    </FormField.Root>\n  );\n}\n```\n\n### Custom validation\n\nImplement custom validation logic beyond min/max constraints:\n\n```jsx live-dev\nconst App = () => {\n  const [date, setDate] = useState(null);\n\n  const isBusinessDay = (dateValue) => {\n    if (!dateValue) return true;\n    const dayOfWeek = dateValue.toDate('UTC').getDay();\n    return dayOfWeek >= 1 && dayOfWeek <= 5;\n  };\n\n  const isInvalid = date && !isBusinessDay(date);\n\n  return (\n    <FormField.Root isInvalid={!!isInvalid}>\n      <FormField.Label>Select a business day</FormField.Label>\n      <FormField.Input>\n        <DateInput\n          value={date}\n          onChange={setDate}\n          defaultValue={new CalendarDate(2025, 6, 17)}\n          aria-label=\"Business days only\"\n        />\n      </FormField.Input>\n      <FormField.Description>\n        Only Monday through Friday are allowed\n      </FormField.Description>\n      {isInvalid && (\n        <FormField.Error>\n          Please select a business day (Monday-Friday)\n        </FormField.Error>\n      )}\n      <Text fontSize=\"sm\" mt=\"200\">\n        Status: {date ? (isBusinessDay(date) ? '✅ Valid' : '❌ Invalid') : 'Not selected'}\n      </Text>\n    </FormField.Root>\n  );\n}\n```\n\n### State variations\n\nDateInput supports disabled, read-only, required, and invalid states:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Default</Text>\n      <DateInput\n        defaultValue={new CalendarDate(2025, 6, 15)}\n        aria-label=\"Default state\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Disabled</Text>\n      <DateInput\n        defaultValue={new CalendarDate(2025, 6, 15)}\n        isDisabled\n        aria-label=\"Disabled state\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Read-only</Text>\n      <DateInput\n        defaultValue={new CalendarDate(2025, 6, 15)}\n        isReadOnly\n        aria-label=\"Read-only state\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Required</Text>\n      <DateInput\n        isRequired\n        aria-label=\"Required state\"\n      />\n    </Stack>\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"sm\" fontWeight=\"600\">Invalid</Text>\n      <DateInput\n        defaultValue={new CalendarDate(2025, 6, 15)}\n        isInvalid\n        aria-label=\"Invalid state\"\n      />\n    </Stack>\n  </Stack>\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('No date selected');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DateInput\n        defaultValue={new CalendarDate(2025, 6, 15)}\n        onChange={(value) => {\n          setDisplayValue(value ? value.toString() : 'No date selected');\n        }}\n        aria-label=\"Uncontrolled date input\"\n      />\n      <Text fontSize=\"sm\">Selected: {displayValue}</Text>\n    </Stack>\n  );\n}\n```\n\nUse uncontrolled mode when you need to capture the selected date 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(new CalendarDate(2025, 6, 15));\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DateInput\n        value={value}\n        onChange={setValue}\n        aria-label=\"Controlled date input\"\n      />\n      <Text fontSize=\"sm\">\n        {value ? `Selected: ${value.toString()}` : 'No selection'}\n      </Text>\n      <Stack direction=\"row\" gap=\"200\">\n        <Button onPress={() => setValue(new CalendarDate(2025, 1, 1))}>\n          Set to Jan 1\n        </Button>\n        <Button onPress={() => setValue(new CalendarDate(2025, 12, 31))}>\n          Set to Dec 31\n        </Button>\n        <Button onPress={() => setValue(null)}>\n          Clear\n        </Button>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\nUse controlled mode when you need to:\n- Synchronize the value with external state\n- Validate or transform selections\n- Clear or programmatically set the value\n\n### Internationalization\n\nDateInput automatically adapts to different locales when wrapped with `NimbusI18nProvider`:\n\n```jsx live-dev\nconst App = () => {\n  const [locale, setLocale] = useState('en-US');\n  const dateValue = new CalendarDate(2025, 6, 15);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\">\n        <Button\n          variant={locale === 'en-US' ? 'solid' : 'outline'}\n          onPress={() => setLocale('en-US')}\n        >\n          English (US)\n        </Button>\n        <Button\n          variant={locale === 'de-DE' ? 'solid' : 'outline'}\n          onPress={() => setLocale('de-DE')}\n        >\n          German\n        </Button>\n        <Button\n          variant={locale === 'ja-JP' ? 'solid' : 'outline'}\n          onPress={() => setLocale('ja-JP')}\n        >\n          Japanese\n        </Button>\n      </Stack>\n      <NimbusI18nProvider locale={locale}>\n        <DateInput\n          defaultValue={dateValue}\n          aria-label=\"Localized date input\"\n        />\n      </NimbusI18nProvider>\n      <Text fontSize=\"sm\">Current locale: {locale}</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n### Date value requirements\n\nAll date values **must** use `@internationalized/date` types:\n- `CalendarDate` for date-only inputs (year, month, day)\n- `CalendarDateTime` for date and time without timezone\n- `ZonedDateTime` for date, time, and timezone information\n\n## Accessibility\n\nThe DateInput handles most accessibility requirements internally through React Aria's DateField. However, you must always associate an internationalized label with the component. Visual labels are preferable, and can be set by:\n\n- Wrapping the DateInput in a FormField (recommended for forms):\n\n```tsx\n<FormField.Root>\n  <FormField.Label>Birth Date</FormField.Label>\n  <FormField.Input>\n    <DateInput />\n  </FormField.Input>\n</FormField.Root>\n```\n\n- Associating a `<label>` element with the DateInput using `aria-labelledby`:\n\n```tsx\n<label id=\"label-id\">\n  {msg.format(labelMessage)}\n</label>\n<DateInput aria-labelledby=\"label-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<DateInput 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 = \"example-date-input\";\n\nexport const Example = () => (\n  <DateInput id={PERSISTENT_ID} aria-label=\"Enter date\" />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction for navigating and editing date segments:\n- `Tab` / `Shift+Tab`: Move between date segments (day, month, year, hour, etc.)\n- `Arrow Up` / `Arrow Down`: Increment or decrement the focused segment\n- `Page Up` / `Page Down`: Increment or decrement the focused segment by larger steps\n- `Home` / `End`: Set segment to minimum or maximum value\n- `0-9`: Type digits to set segment value\n- `Backspace`: Clear the focused segment\n\n## API reference\n\n<PropsTable id=\"DateInput\" />\n\n## Common patterns\n\n### Date of birth input\n\nA common pattern for capturing user birth dates with validation:\n\n```jsx live-dev\nconst App = () => {\n  const [birthDate, setBirthDate] = useState(null);\n  const today = new CalendarDate(2025, 12, 2);\n  const minDate = new CalendarDate(1900, 1, 1);\n  \n  const isInvalid = birthDate && (\n    birthDate.compare(minDate) < 0 || \n    birthDate.compare(today) > 0\n  );\n\n  return (\n    <FormField.Root isInvalid={!!isInvalid}>\n      <FormField.Label>Date of Birth</FormField.Label>\n      <FormField.Input>\n        <DateInput\n          value={birthDate}\n          onChange={setBirthDate}\n          minValue={minDate}\n          maxValue={today}\n          placeholderValue={new CalendarDate(1990, 1, 1)}\n          aria-label=\"Date of birth\"\n        />\n      </FormField.Input>\n      <FormField.Description>\n        Enter your birth date\n      </FormField.Description>\n      {isInvalid && (\n        <FormField.Error>\n          Please enter a valid birth date\n        </FormField.Error>\n      )}\n    </FormField.Root>\n  );\n}\n```\n\n### Appointment scheduler\n\nA pattern for scheduling appointments with time selection:\n\n```jsx live-dev\nconst App = () => {\n  const [appointmentTime, setAppointmentTime] = useState(\n    new CalendarDateTime(2025, 12, 15, 10, 0, 0)\n  );\n  \n  const businessHoursStart = 9;\n  const businessHoursEnd = 17;\n  \n  const isInvalidTime = appointmentTime && (\n    appointmentTime.hour < businessHoursStart || \n    appointmentTime.hour >= businessHoursEnd\n  );\n\n  return (\n    <FormField.Root isInvalid={isInvalidTime}>\n      <FormField.Label>Appointment Time</FormField.Label>\n      <FormField.Input>\n        <DateInput\n          value={appointmentTime}\n          onChange={setAppointmentTime}\n          granularity=\"minute\"\n          hourCycle={12}\n          leadingElement={<Icons.Schedule />}\n          aria-label=\"Appointment time\"\n        />\n      </FormField.Input>\n      <FormField.Description>\n        Select a time between 9:00 AM and 5:00 PM\n      </FormField.Description>\n      {isInvalidTime && (\n        <FormField.Error>\n          Please select a time during business hours (9 AM - 5 PM)\n        </FormField.Error>\n      )}\n      {appointmentTime && !isInvalidTime && (\n        <Text fontSize=\"sm\" mt=\"200\">\n          ✅ Appointment scheduled for {appointmentTime.toString()}\n        </Text>\n      )}\n    </FormField.Root>\n  );\n}\n```\n\n### Event date range start\n\nPattern for the start date of an event range (pairs with DateRangePicker):\n\n```jsx live-dev\nconst App = () => {\n  const [startDate, setStartDate] = useState(new CalendarDate(2025, 12, 10));\n  const [endDate, setEndDate] = useState(new CalendarDate(2025, 12, 15));\n  const today = new CalendarDate(2025, 12, 2);\n  \n  const isInvalid = startDate && endDate && startDate.compare(endDate) > 0;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <FormField.Root isInvalid={isInvalid}>\n        <FormField.Label>Event Start Date</FormField.Label>\n        <FormField.Input>\n          <DateInput\n            value={startDate}\n            onChange={setStartDate}\n            minValue={today}\n            maxValue={endDate}\n            leadingElement={<Icons.Event />}\n            aria-label=\"Event start date\"\n          />\n        </FormField.Input>\n        {isInvalid && (\n          <FormField.Error>\n            Start date must be before end date\n          </FormField.Error>\n        )}\n      </FormField.Root>\n      \n      <FormField.Root>\n        <FormField.Label>Event End Date</FormField.Label>\n        <FormField.Input>\n          <DateInput\n            value={endDate}\n            onChange={setEndDate}\n            minValue={startDate || today}\n            leadingElement={<Icons.Event />}\n            aria-label=\"Event end date\"\n          />\n        </FormField.Input>\n      </FormField.Root>\n      \n      <Text fontSize=\"sm\">\n        Event duration: {startDate && endDate ? \n          `${endDate.compare(startDate) + 1} day(s)` : \n          'Select dates'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using DateInput 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 DateInput renders with expected elements and date segments\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DateInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, CalendarDateTime } from \"@internationalized/date\";\n\ndescribe(\"DateInput - Basic rendering\", () => {\n  it(\"renders date input with segments\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput aria-label=\"Enter a date\" />\n      </NimbusProvider>\n    );\n\n    // DateInput uses role=\"group\" for the overall field\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n  });\n\n  it(\"renders with default value\", () => {\n    const defaultDate = new CalendarDate(2025, 6, 15);\n\n    render(\n      <NimbusProvider>\n        <DateInput\n          defaultValue={defaultDate}\n          aria-label=\"Date with default value\"\n        />\n      </NimbusProvider>\n    );\n\n    // Verify segments contain the default values\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n    // Find month value\n    expect(screen.getByText(\"6\")).toBeInTheDocument();\n  });\n\n  it(\"renders with leading element\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          leadingElement={<span data-testid=\"leading-icon\">📅</span>}\n          aria-label=\"Date with icon\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"leading-icon\")).toBeInTheDocument();\n  });\n\n  it(\"renders with trailing element\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          trailingElement={<span data-testid=\"trailing-icon\">✕</span>}\n          aria-label=\"Date with trailing icon\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"trailing-icon\")).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with date segments and keyboard navigation\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DateInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, CalendarDateTime } from \"@internationalized/date\";\n\ndescribe(\"DateInput - Interactions\", () => {\n  it(\"calls onChange when date value changes\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <DateInput\n          onChange={handleChange}\n          defaultValue={new CalendarDate(2025, 1, 15)}\n          aria-label=\"Interactive date input\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    const segments = group.querySelectorAll('[role=\"spinbutton\"]');\n\n    // Focus first segment (month) and use arrow up to increment\n    if (segments[0]) {\n      await user.click(segments[0]);\n      await user.keyboard(\"{ArrowUp}\");\n\n      // onChange should be called with a DateValue (month changed from 1 to 2)\n      await waitFor(() => {\n        expect(handleChange).toHaveBeenCalled();\n        const newValue = handleChange.mock.calls[0][0];\n        expect(newValue).toBeInstanceOf(CalendarDate);\n      });\n    }\n  });\n\n  it(\"allows keyboard navigation between segments\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <DateInput\n          defaultValue={new CalendarDate(2025, 6, 15)}\n          aria-label=\"Date for keyboard navigation\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    const segments = group.querySelectorAll('[role=\"spinbutton\"]');\n\n    // Focus first segment\n    if (segments[0]) {\n      await user.click(segments[0]);\n      expect(segments[0]).toHaveFocus();\n\n      // Tab to next segment\n      await user.keyboard(\"{Tab}\");\n      expect(segments[1]).toHaveFocus();\n    }\n  });\n\n  it(\"increments segment value with arrow up\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <DateInput\n          defaultValue={new CalendarDate(2025, 6, 15)}\n          onChange={handleChange}\n          aria-label=\"Date for arrow key test\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    const segments = group.querySelectorAll('[role=\"spinbutton\"]');\n\n    if (segments[0]) {\n      await user.click(segments[0]);\n      await user.keyboard(\"{ArrowUp}\");\n\n      await waitFor(() => {\n        expect(handleChange).toHaveBeenCalled();\n      });\n    }\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled component behavior with value and onChange\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DateInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, CalendarDateTime } from \"@internationalized/date\";\n\ndescribe(\"DateInput - Controlled mode\", () => {\n  it(\"accepts and displays controlled value\", () => {\n    const date = new CalendarDate(2025, 12, 25);\n\n    render(\n      <NimbusProvider>\n        <DateInput\n          value={date}\n          onChange={vi.fn()}\n          aria-label=\"Controlled date\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n  });\n\n  it(\"calls onChange with new value when changed\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    const initialDate = new CalendarDate(2025, 6, 15);\n\n    render(\n      <NimbusProvider>\n        <DateInput\n          value={initialDate}\n          onChange={handleChange}\n          aria-label=\"Controlled with onChange\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    const segments = group.querySelectorAll('[role=\"spinbutton\"]');\n\n    if (segments[0]) {\n      await user.click(segments[0]);\n      await user.keyboard(\"{ArrowUp}\");\n\n      await waitFor(() => {\n        expect(handleChange).toHaveBeenCalled();\n        const newValue = handleChange.mock.calls[0][0];\n        expect(newValue).toBeInstanceOf(CalendarDate);\n      });\n    }\n  });\n\n  it(\"updates when value prop changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <DateInput\n          value={new CalendarDate(2025, 1, 1)}\n          onChange={vi.fn()}\n          aria-label=\"Date that will change\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <DateInput\n          value={new CalendarDate(2025, 12, 31)}\n          onChange={vi.fn()}\n          aria-label=\"Date that will change\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"group\")).toBeInTheDocument();\n  });\n});\n```\n\n### State Tests\n\nTest various states: disabled, read-only, required, invalid\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DateInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, CalendarDateTime } from \"@internationalized/date\";\n\ndescribe(\"DateInput - States\", () => {\n  it(\"applies disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          isDisabled\n          defaultValue={new CalendarDate(2025, 6, 15)}\n          aria-label=\"Disabled date\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    expect(group).toHaveAttribute(\"data-disabled\", \"true\");\n  });\n\n  it(\"applies read-only state\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          isReadOnly\n          defaultValue={new CalendarDate(2025, 6, 15)}\n          aria-label=\"Read-only date\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    expect(group).toHaveAttribute(\"data-readonly\", \"true\");\n  });\n\n  it(\"applies required state\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput isRequired aria-label=\"Required date\" />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    // Verify component renders when required\n    expect(group).toBeInTheDocument();\n  });\n\n  it(\"applies invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          isInvalid\n          defaultValue={new CalendarDate(2025, 6, 15)}\n          aria-label=\"Invalid date\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    expect(group).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n});\n```\n\n### Granularity Tests\n\nTest different granularity levels (day, hour, minute, second)\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DateInput, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, CalendarDateTime } from \"@internationalized/date\";\n\ndescribe(\"DateInput - Granularity\", () => {\n  it(\"renders day granularity with date segments only\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          granularity=\"day\"\n          defaultValue={new CalendarDate(2025, 6, 15)}\n          aria-label=\"Day granularity\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    const segments = group.querySelectorAll('[role=\"spinbutton\"]');\n\n    // Should have segments for month, day, year (3 segments)\n    expect(segments.length).toBeGreaterThanOrEqual(3);\n  });\n\n  it(\"renders minute granularity with date and time segments\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          granularity=\"minute\"\n          defaultValue={new CalendarDateTime(2025, 6, 15, 14, 30, 0)}\n          aria-label=\"Minute granularity\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    const segments = group.querySelectorAll('[role=\"spinbutton\"]');\n\n    // Should have segments for month, day, year, hour, minute (5+ segments)\n    expect(segments.length).toBeGreaterThanOrEqual(5);\n  });\n\n  it(\"renders second granularity with full precision\", () => {\n    render(\n      <NimbusProvider>\n        <DateInput\n          granularity=\"second\"\n          defaultValue={new CalendarDateTime(2025, 6, 15, 14, 30, 45)}\n          aria-label=\"Second granularity\"\n        />\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"group\");\n    const segments = group.querySelectorAll('[role=\"spinbutton\"]');\n\n    // Should have segments for month, day, year, hour, minute, second (6+ segments)\n    expect(segments.length).toBeGreaterThanOrEqual(6);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-date-dateinput--docs)\n- [React Aria DateField](https://react-spectrum.adobe.com/react-aria/DateField.html)\n- [ARIA Date Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/)\n- [@internationalized/date](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 date values",
+          "href": "#working-with-date-values",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Date types",
+          "href": "#date-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Creating date values",
+          "href": "#creating-date-values",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Converting to strings",
+          "href": "#converting-to-strings",
+          "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": "Granularity control",
+          "href": "#granularity-control",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Hour cycle",
+          "href": "#hour-cycle",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Leading zeros",
+          "href": "#leading-zeros",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Time zone handling",
+          "href": "#time-zone-handling",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placeholder values",
+          "href": "#placeholder-values",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Min/max validation",
+          "href": "#minmax-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom validation",
+          "href": "#custom-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State variations",
+          "href": "#state-variations",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            11
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            12
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            13
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Internationalization",
+          "href": "#internationalization",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            14
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Date value requirements",
+          "href": "#date-value-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": "Date of birth input",
+          "href": "#date-of-birth-input",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Appointment scheduler",
+          "href": "#appointment-scheduler",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Event date range start",
+          "href": "#event-date-range-start",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "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": "State Tests",
+          "href": "#state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Granularity Tests",
+          "href": "#granularity-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nDate input guidelines establish a standardized approach for creating intuitive\nand accessible date input components, ensuring consistency in presentation and\ninteraction for selecting dates across all applications.\n\n### Best practices\n\n- **Use a clear placeholder.** Provide a placeholder in a conventional date\n  format to guide the user (e.g., mm/dd/yyyy).\n- **Provide clear validation.** Offer clear, concise error messages for\n  incorrect or invalid input.\n- **Format automatically.** Format the date as the user types to reduce errors\n  and improve usability.\n- **Use for specific dates.** Use this component when a user needs to enter a\n  known date. Avoid using it for date ranges or when a calendar view would be\n  more beneficial.\n- **Ensure accessibility.** The input field will have a clear accessible label\n  and be compatible with screen readers.\n\n### Usage\n\nA date input component allows users to enter a specific date. The component\nprovides a single input field for manual entry. Use this component when a\ncalendar selection is unnecessary or when a user is likely to know the specific\ndate they need to enter.\n\n> [!TIP]\\\n> When to use\n\n- **Entering a known date.** Use when the user knows the specific date, such as\n  a birth date, an expiration date, or a past event.\n- **A calendar is not necessary.** Use when a calendar popover would be an\n  unnecessary step for the user, simplifying the user experience.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Selecting a date range.** Do not use a single date input to select a start\n  and end date. Use a date range picker instead.\n- **Choosing an unknown date.** Avoid using this component when the user needs\n  to browse or select a date they don't already know, such as setting a date for\n  promotion or setting a range for expecting for a shipment. In these cases, a\n  calendar popover is more effective.\n\n### Basic interactions\n\nClear labels and concise messaging are crucial for a date input to ensure users\nunderstand what date information is required and how to provide it correctly.\n\n> [!TIP]\\\n> **Do**\n>\n> - Do provide a clear placeholder in a conventional date format.\n> - Do automatically format the date as the user types.\n> - Do provide validation and clear error messages.\n> - Do use this component when a user needs to enter a known, specific date.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Birth Date</FormField.Label>\n    <FormField.Input>\n      <DateInput aria-label=\"Birth date\" width=\"1/3\" />\n    </FormField.Input>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't use a generic placeholder like \"enter date.\"\n> - Don't require the user to manually enter separators like \"/\" or \"-\".\n> - Don't allow invalid dates to be submitted without feedback.\n> - Don't use this component when a calendar selection would be more helpful or\n>   when selecting a date range.\n\n```jsx live\nconst App = () => (\n  <FormField.Root isInvalid>\n    <FormField.Input>\n      <DateInput aria-label=\"Date\" width=\"1/3\" />\n    </FormField.Input>\n    <FormField.Error>Your date is not a valid input</FormField.Error>\n  </FormField.Root>\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": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic interactions",
+          "href": "#basic-interactions",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}