@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-inputs-calendar.json

@@ -0,0 +1,611 @@
+{
+  "meta": {
+    "id": "Components-Calendar",
+    "title": "Calendar",
+    "exportName": "Calendar",
+    "description": "Calendars display a grid of days in one or more months and allow users to select a single date.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/calendar/calendar.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Calendar"
+    ],
+    "route": "components/inputs/calendar",
+    "tags": [
+      "component",
+      "calendar",
+      "date",
+      "picker",
+      "month"
+    ],
+    "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 calendar component is most often used within the popover component when a\nuser interacts with a date input. Easily toggle between month, year, and single\nday selection.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=5818-15651)\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-date-calendar--docs)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n**Single date select**\n\nAllow users to see the current date, and select a single date.\n\n```jsx live\nconst App = () => <Calendar aria-label=\"Enter a date\" />\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe calendar component is most often used within the popover component when a\nuser interacts with a date input. Easily toggle between month, year, and single\nday selection.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=5818-15651)\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-date-calendar--docs)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n**Single date select**\n\nAllow users to see the current date, and select a single date.\n\n```jsx live\nconst App = () => <Calendar 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 = () => <Calendar aria-label=\"Enter a date\" />\n```\n\n### Accessibility standards\n\n- Ensure the calendar is navigable using a keyboard.\n- Use Tab to move focus to and from the calendar component.\n- Use Enter or Space to activate controls (e.g., to open/close the calendar,\n  select a date, or navigate months/years).\n- Use arrow keys to navigate between days within the calendar grid.\n- Ensure focus is clearly visible on the currently selected day or navigated\n  day.\n- Clearly indicate the current month and year.\n- Provide accessible controls for navigating to previous and next months/years.\n  These controls should have clear aria-label attributes if they are icon-only.\n- Ensure selected dates are clearly distinguished visually and announced by\n  screen readers.\n- Communicate invalid or unavailable dates (e.g., past dates, blackout dates) to\n  screen readers.\n- Provide a mechanism for users to select a specific date (e.g., clicking a day,\n  or typing a date into an associated input field).\n- Announce changes in month or year to screen readers.\n- Ensure sufficient color contrast for all calendar elements (text, borders,\n  icons, selected states, hover states).\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 { Calendar, type CalendarProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation displays a calendar with no pre-selected date:\n\n```jsx live-dev\nconst App = () => (\n  <Calendar />\n)\n```\n\n## Working with date values\n\nThe Calendar relies on `@internationalized/date`'s library for type-safe date handling. This library provides calendar system support, time zone handling, and locale-aware date formatting.\n\n### Date value types\n\nThree primary date types are available depending on your needs:\n\n```tsx\nimport { CalendarDate, CalendarDateTime, ZonedDateTime } from '@internationalized/date';\n\n// Date only (no time)\nconst dateOnly = new CalendarDate(2024, 1, 15);\n\n// Date with time (no timezone)\nconst dateTime = new CalendarDateTime(2024, 1, 15, 14, 30);\n\n// Date with time and timezone\nconst zonedDate = new ZonedDateTime(2024, 1, 15, 14, 30, 'America/New_York');\n```\n\n### Creating date values\n\nUse helper functions to parse ISO strings or create dates programmatically:\n\n```tsx\nimport { parseDate, parseDateTime, parseZonedDateTime } from '@internationalized/date';\n\n// Parse ISO date strings\nconst date = parseDate('2024-01-15');\nconst dateTime = parseDateTime('2024-01-15T14:30');\nconst zonedDate = parseZonedDateTime('2024-01-15T14:30[America/New_York]');\n```\n\n### Converting to ISO strings\n\nUse `.toString()` to convert date objects for API/backend consumption:\n\n```tsx\nconst date = new CalendarDate(2024, 1, 15);\ndate.toString(); // \"2024-01-15\"\n\nconst dateTime = new CalendarDateTime(2024, 1, 15, 14, 30);\ndateTime.toString(); // \"2024-01-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### Uncontrolled mode\n\nFor simpler use cases, use uncontrolled mode with `defaultValue` and `onChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedDate, setSelectedDate] = useState<string>('No selection');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Calendar\n        defaultValue={new CalendarDate(2025, 1, 15)}\n        onChange={(date) => {\n          setSelectedDate(date ? date.toString() : 'No selection');\n        }}\n      />\n      <Text fontSize=\"sm\">Selected: {selectedDate}</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<CalendarProps<DateValue>[\"value\"]>(null);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Calendar\n        value={value}\n        onChange={setValue}\n      />\n      <Text fontSize=\"sm\">\n        {value ? `Selected: ${value.toString()}` : 'No selection'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\nUse controlled mode when you need to:\n- Synchronize the date with external state\n- Validate or transform date selections\n- Clear or programmatically set the date\n\n### Multi-month display\n\nDisplay multiple months simultaneously using the `visibleDuration` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Calendar\n    defaultValue={new CalendarDate(2025, 1, 15)}\n    visibleDuration={{ months: 2 }}\n    width=\"680px\"\n  />\n)\n```\n\nSet an appropriate width to accommodate multiple months (approximately 340px per month).\n\n### Navigation behavior\n\nThe `pageBehavior` prop controls how the calendar navigates when using prev/next buttons:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Single month navigation</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Navigates by one month at a time</Text>\n      <Calendar\n        defaultValue={new CalendarDate(2025, 1, 15)}\n        visibleDuration={{ months: 2 }}\n        pageBehavior=\"single\"\n        width=\"680px\"\n      />\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Visible duration navigation</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Navigates by the number of visible months</Text>\n      <Calendar\n        defaultValue={new CalendarDate(2025, 1, 15)}\n        visibleDuration={{ months: 2 }}\n        pageBehavior=\"visible\"\n        width=\"680px\"\n      />\n    </Stack>\n  </Stack>\n)\n```\n\n**Behavioral differences:**\n- `pageBehavior=\"single\"`: Advances one month at a time, regardless of how many months are visible\n- `pageBehavior=\"visible\"`: Advances by the full visible duration (e.g., if showing 3 months, advances 3 months)\n\n### Date constraints\n\n#### Minimum and maximum values\n\nRestrict selectable dates using `minValue` and `maxValue`:\n\n```jsx live-dev\nconst App = () => {\n  const today = new CalendarDate(2025, 1, 15);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">Minimum date (today onwards)</Text>\n        <Calendar\n          minValue={today}\n          defaultValue={today}\n        />\n      </Stack>\n\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">Maximum date (up to 7 days from today)</Text>\n        <Calendar\n          maxValue={today.add({ days: 7 })}\n          defaultValue={today}\n        />\n      </Stack>\n\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">Date range (next 7 days only)</Text>\n        <Calendar\n          minValue={today.add({ days: 1 })}\n          maxValue={today.add({ days: 7 })}\n          defaultValue={today.add({ days: 1 })}\n        />\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n#### Unavailable dates\n\nMark specific dates as unavailable using the `isDateUnavailable` callback:\n\n```jsx live-dev\nconst App = () => {\n  const today = new CalendarDate(2025, 1, 15);\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"sm\" color=\"neutral.11\">\n        Only weekdays are selectable (weekends are disabled)\n      </Text>\n      <Calendar\n        defaultValue={today}\n        isDateUnavailable={(date) => {\n          const dayOfWeek = date.toDate(getLocalTimeZone()).getDay();\n          return dayOfWeek === 0 || dayOfWeek === 6; // Sunday or Saturday\n        }}\n      />\n    </Stack>\n  );\n}\n```\n\n### Custom week start day\n\nSpecify which day starts the week using `firstDayOfWeek`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Week starts on Sunday (default)</Text>\n      <Calendar />\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Week starts on Monday</Text>\n      <Calendar firstDayOfWeek=\"mon\" />\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Week starts on Saturday</Text>\n      <Calendar firstDayOfWeek=\"sat\" />\n    </Stack>\n  </Stack>\n)\n```\n\n### Internationalization\n\nThe Calendar automatically adapts to different locales when wrapped with `NimbusI18nProvider`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">English (US)</Text>\n      <NimbusI18nProvider locale=\"en-US\">\n        <Calendar defaultValue={new CalendarDate(2025, 1, 15)} />\n      </NimbusI18nProvider>\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">German</Text>\n      <NimbusI18nProvider locale=\"de-DE\">\n        <Calendar defaultValue={new CalendarDate(2025, 1, 15)} />\n      </NimbusI18nProvider>\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">French</Text>\n      <NimbusI18nProvider locale=\"fr-FR\">\n        <Calendar defaultValue={new CalendarDate(2025, 1, 15)} />\n      </NimbusI18nProvider>\n    </Stack>\n  </Stack>\n)\n```\n\n### State props\n\nControl the calendar's interactive state using `isDisabled`, `isReadOnly`, and `isInvalid`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Disabled</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">User cannot interact with the calendar</Text>\n      <Calendar isDisabled defaultValue={new CalendarDate(2025, 1, 15)} />\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Read-only</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Calendar is visible but selection is prevented</Text>\n      <Calendar isReadOnly defaultValue={new CalendarDate(2025, 1, 15)} />\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"600\">Invalid</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Indicates validation error state</Text>\n      <Calendar isInvalid defaultValue={new CalendarDate(2025, 1, 15)} />\n    </Stack>\n  </Stack>\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 values (recommended for most use cases)\n- `CalendarDateTime` for date with time\n- `ZonedDateTime` for date with time and timezone\n\n## Accessibility\n\nThe Calendar 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- Associating a `<label>` element with the Calendar using `aria-labelledby`:\n\n```tsx\n<label id=\"calendar-label\">\n  {msg.format(\"selectDate\")}\n</label>\n<Calendar aria-labelledby=\"calendar-label\" />\n```\n\n- Associating a `<label>` element with the Calendar using `htmlFor`:\n\n```tsx\n<label htmlFor=\"calendar-id\">\n  {msg.format(\"selectDate\")}\n</label>\n<Calendar id=\"calendar-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<Calendar aria-label={msg.format(\"selectDate\")} />\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 = \"booking-calendar\";\n\nexport const BookingForm = () => (\n  <Calendar id={PERSISTENT_ID} />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus into and out of the calendar\n- `Arrow keys`: Navigate between dates within the grid\n- `Page Up` / `Page Down`: Navigate to the previous/next month\n- `Shift + Page Up` / `Shift + Page Down`: Navigate to the previous/next year\n- `Home` / `End`: Navigate to the start/end of the current week\n- `Enter` / `Space`: Select the focused date\n\n## API reference\n\n<PropsTable id=\"Calendar\" />\n\n## Common patterns\n\n### Booking system with constraints\n\nA typical booking system that prevents past dates and weekends:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<CalendarProps<DateValue>[\"value\"]>(null);\n  const today = new CalendarDate(2025, 1, 15);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontWeight=\"600\">Select your booking date</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">\n        Available dates: Weekdays only, starting tomorrow\n      </Text>\n      <Calendar\n        value={value}\n        onChange={setValue}\n        minValue={today.add({ days: 1 })}\n        isDateUnavailable={(date) => {\n          const dayOfWeek = date.toDate(getLocalTimeZone()).getDay();\n          return dayOfWeek === 0 || dayOfWeek === 6;\n        }}\n      />\n      {value && (\n        <Text fontSize=\"sm\">\n          Selected booking date: {value.toString()}\n        </Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n### Working days selection\n\nCalendar configured for business day selection with current month focus:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<CalendarProps<DateValue>[\"value\"]>(\n    new CalendarDate(2025, 1, 15)\n  );\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontWeight=\"600\">Select working day</Text>\n      <Calendar\n        value={value}\n        onChange={setValue}\n        isDateUnavailable={(date) => {\n          const dayOfWeek = date.toDate(getLocalTimeZone()).getDay();\n          return dayOfWeek === 0 || dayOfWeek === 6;\n        }}\n      />\n      {value && (\n        <Stack direction=\"column\" gap=\"100\">\n          <Text fontSize=\"sm\">Selected: {value.toString()}</Text>\n          <Text fontSize=\"sm\" color=\"neutral.11\">\n            {value.toDate(getLocalTimeZone()).toLocaleDateString('en-US', {\n              weekday: 'long',\n              year: 'numeric',\n              month: 'long',\n              day: 'numeric'\n            })}\n          </Text>\n        </Stack>\n      )}\n    </Stack>\n  );\n}\n```\n\n### Multi-month date selection\n\nDisplay multiple months for easier range visualization:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<CalendarProps<DateValue>[\"value\"]>(null);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontWeight=\"600\">Select a date across multiple months</Text>\n      <Calendar\n        value={value}\n        onChange={setValue}\n        visibleDuration={{ months: 3 }}\n        pageBehavior=\"visible\"\n        width=\"1000px\"\n      />\n      {value && (\n        <Text fontSize=\"sm\">Selected: {value.toString()}</Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Calendar 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 Calendar component renders with expected grid structure\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within, act } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Calendar, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, getLocalTimeZone } from \"@internationalized/date\";\n\ndescribe(\"Calendar - Basic rendering\", () => {\n  it(\"renders calendar grid\", () => {\n    render(\n      <NimbusProvider>\n        <Calendar aria-label=\"Select date\" />\n      </NimbusProvider>\n    );\n\n    // Calendar uses grid role for accessibility\n    expect(screen.getByRole(\"grid\")).toBeInTheDocument();\n  });\n\n  it(\"renders with default value\", () => {\n    const defaultDate = new CalendarDate(2025, 1, 15);\n\n    render(\n      <NimbusProvider>\n        <Calendar aria-label=\"Select date\" defaultValue={defaultDate} />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    expect(grid).toBeInTheDocument();\n\n    // Verify selected date is marked with data-selected attribute\n    const dateCells = within(grid).getAllByRole(\"button\");\n    const selectedCell = dateCells.find(\n      (cell) => cell.getAttribute(\"data-selected\") === \"true\"\n    );\n    // Calendar renders with a selected date\n    expect(selectedCell).toBeTruthy();\n    if (selectedCell) {\n      expect(selectedCell).toHaveTextContent(\"15\");\n    }\n  });\n\n  it(\"renders navigation buttons\", () => {\n    render(\n      <NimbusProvider>\n        <Calendar aria-label=\"Select date\" />\n      </NimbusProvider>\n    );\n\n    // Calendar header contains previous/next month and year navigation\n    const previousButtons = screen.getAllByRole(\"button\", {\n      name: /previous/i,\n    });\n    const nextButtons = screen.getAllByRole(\"button\", { name: /next/i });\n\n    expect(previousButtons.length).toBeGreaterThan(0);\n    expect(nextButtons.length).toBeGreaterThan(0);\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled Calendar with value and onChange props\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within, act } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Calendar, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, getLocalTimeZone } from \"@internationalized/date\";\n\ndescribe(\"Calendar - Controlled mode\", () => {\n  it(\"displays controlled value\", () => {\n    const controlledDate = new CalendarDate(2025, 1, 15);\n\n    render(\n      <NimbusProvider>\n        <Calendar aria-label=\"Select date\" value={controlledDate} />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n    const selectedCell = dateCells.find(\n      (cell) => cell.getAttribute(\"data-selected\") === \"true\"\n    );\n\n    expect(selectedCell).toBeTruthy();\n    if (selectedCell) {\n      expect(selectedCell).toHaveTextContent(\"15\");\n    }\n  });\n\n  it(\"calls onChange when date is selected\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          value={null}\n          onChange={handleChange}\n          defaultFocusedValue={new CalendarDate(2025, 1, 15)}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    // Find an enabled date cell from current month\n    const dateCells = within(grid).getAllByRole(\"button\");\n    const availableCell = dateCells.find(\n      (cell) =>\n        cell.getAttribute(\"aria-disabled\") !== \"true\" &&\n        cell.textContent &&\n        parseInt(cell.textContent) > 0 &&\n        parseInt(cell.textContent) <= 31\n    );\n\n    if (availableCell) {\n      await user.click(availableCell);\n      expect(handleChange).toHaveBeenCalled();\n      // Verify the handler was called with a DateValue\n      const callArg = handleChange.mock.calls[0]?.[0];\n      expect(callArg).toBeTruthy();\n    }\n  });\n\n  it(\"allows programmatic value updates\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          value={new CalendarDate(2025, 1, 15)}\n        />\n      </NimbusProvider>\n    );\n\n    let grid = screen.getByRole(\"grid\");\n    let dateCells = within(grid).getAllByRole(\"button\");\n    let selectedCell = dateCells.find(\n      (cell) => cell.getAttribute(\"data-selected\") === \"true\"\n    );\n    expect(selectedCell).toBeTruthy();\n    if (selectedCell) {\n      expect(selectedCell).toHaveTextContent(\"15\");\n    }\n\n    // Update to a new date\n    rerender(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          value={new CalendarDate(2025, 1, 20)}\n        />\n      </NimbusProvider>\n    );\n\n    grid = screen.getByRole(\"grid\");\n    dateCells = within(grid).getAllByRole(\"button\");\n    selectedCell = dateCells.find(\n      (cell) => cell.getAttribute(\"data-selected\") === \"true\"\n    );\n    expect(selectedCell).toBeTruthy();\n    if (selectedCell) {\n      expect(selectedCell).toHaveTextContent(\"20\");\n    }\n  });\n});\n```\n\n### Date Constraints Tests\n\nTest minValue, maxValue, and isDateUnavailable constraints\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within, act } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Calendar, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, getLocalTimeZone } from \"@internationalized/date\";\n\ndescribe(\"Calendar - Date constraints\", () => {\n  it(\"disables dates before minValue\", () => {\n    const minDate = new CalendarDate(2025, 1, 15);\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          minValue={minDate}\n          defaultValue={minDate}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n\n    // Find cells before minValue (they should be disabled)\n    const disabledCells = dateCells.filter(\n      (cell) => cell.getAttribute(\"aria-disabled\") === \"true\"\n    );\n\n    expect(disabledCells.length).toBeGreaterThan(0);\n  });\n\n  it(\"disables dates after maxValue\", () => {\n    const maxDate = new CalendarDate(2025, 1, 15);\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          maxValue={maxDate}\n          defaultValue={maxDate}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n\n    // Find cells after maxValue (they should be disabled)\n    const disabledCells = dateCells.filter(\n      (cell) => cell.getAttribute(\"aria-disabled\") === \"true\"\n    );\n\n    expect(disabledCells.length).toBeGreaterThan(0);\n  });\n\n  it(\"marks unavailable dates as disabled\", () => {\n    const today = new CalendarDate(2025, 1, 15); // Wednesday\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          defaultValue={today}\n          isDateUnavailable={(date) => {\n            const dayOfWeek = date.toDate(getLocalTimeZone()).getDay();\n            return dayOfWeek === 0 || dayOfWeek === 6; // Weekends\n          }}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n\n    // Filter cells that are disabled due to isDateUnavailable\n    const disabledCells = dateCells.filter(\n      (cell) => cell.getAttribute(\"aria-disabled\") === \"true\"\n    );\n\n    // Should have weekend dates disabled\n    expect(disabledCells.length).toBeGreaterThan(0);\n  });\n});\n```\n\n### Multi-Month Display Tests\n\nTest calendar with multiple visible months\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within, act } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Calendar, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, getLocalTimeZone } from \"@internationalized/date\";\n\ndescribe(\"Calendar - Multi-month display\", () => {\n  it(\"renders multiple months when visibleDuration is set\", () => {\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          defaultValue={new CalendarDate(2025, 1, 15)}\n          visibleDuration={{ months: 2 }}\n        />\n      </NimbusProvider>\n    );\n\n    // Should render multiple grid elements (one per month)\n    const grids = screen.getAllByRole(\"grid\");\n    expect(grids.length).toBe(2);\n  });\n\n  it('navigates by visible duration when pageBehavior is \"visible\"', async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          defaultValue={new CalendarDate(2025, 1, 15)}\n          visibleDuration={{ months: 2 }}\n          pageBehavior=\"visible\"\n        />\n      </NimbusProvider>\n    );\n\n    const nextButtons = screen.getAllByRole(\"button\", { name: /next/i });\n    expect(nextButtons.length).toBeGreaterThan(0);\n\n    await user.click(nextButtons[0]);\n\n    // Calendar should advance by 2 months (the visible duration)\n    // Verify that calendar still renders two grids after navigation\n    const grids = screen.getAllByRole(\"grid\");\n    expect(grids.length).toBe(2);\n  });\n});\n```\n\n### State Props Tests\n\nTest isDisabled, isReadOnly, and isInvalid state props\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within, act } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Calendar, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, getLocalTimeZone } from \"@internationalized/date\";\n\ndescribe(\"Calendar - State props\", () => {\n  it(\"disables all interactions when isDisabled is true\", () => {\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          isDisabled\n          defaultValue={new CalendarDate(2025, 1, 15)}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n\n    // All date cells should be disabled\n    dateCells.forEach((cell) => {\n      expect(cell).toHaveAttribute(\"aria-disabled\", \"true\");\n    });\n  });\n\n  it(\"prevents selection when isReadOnly is true\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          isReadOnly\n          value={new CalendarDate(2025, 1, 15)}\n          onChange={handleChange}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n    const unselectedCell = dateCells.find(\n      (cell) => !cell.getAttribute(\"aria-pressed\")\n    );\n\n    if (unselectedCell) {\n      await user.click(unselectedCell);\n      // onChange should not be called in read-only mode\n      expect(handleChange).not.toHaveBeenCalled();\n    }\n  });\n\n  it(\"applies invalid styling when isInvalid is true\", () => {\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          isInvalid\n          defaultValue={new CalendarDate(2025, 1, 15)}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    expect(grid).toBeInTheDocument();\n    // Component should still render and be functional\n    // Visual invalid state is applied via CSS\n  });\n});\n```\n\n### Keyboard Navigation Tests\n\nTest keyboard interactions for date selection\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within, act } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Calendar, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, getLocalTimeZone } from \"@internationalized/date\";\n\ndescribe(\"Calendar - Keyboard navigation\", () => {\n  it(\"supports arrow key navigation\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          defaultValue={new CalendarDate(2025, 1, 15)}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n    const selectedCell = dateCells.find(\n      (cell) => cell.getAttribute(\"data-selected\") === \"true\"\n    );\n\n    // Focus the selected cell if it exists\n    if (selectedCell) {\n      // Wrap focus in act() to handle React state updates (React 19 requires async act)\n      await act(async () => {\n        selectedCell.focus();\n      });\n      expect(selectedCell).toHaveFocus();\n\n      // Arrow keys should navigate to adjacent dates\n      await user.keyboard(\"{ArrowRight}\");\n      // Focus should move to the next date\n      const focusedElement = document.activeElement;\n      expect(focusedElement).not.toBe(selectedCell);\n      expect(focusedElement?.getAttribute(\"role\")).toBe(\"button\");\n    } else {\n      // If no selected cell, just verify calendar has navigable buttons\n      expect(dateCells.length).toBeGreaterThan(0);\n    }\n  });\n\n  it(\"selects date with Enter key\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Calendar\n          aria-label=\"Select date\"\n          value={null}\n          onChange={handleChange}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    const dateCells = within(grid).getAllByRole(\"button\");\n    const firstAvailableCell = dateCells.find(\n      (cell) => cell.getAttribute(\"aria-disabled\") !== \"true\"\n    );\n\n    if (firstAvailableCell) {\n      // Wrap focus in act() to handle React state updates (React 19 requires async act)\n      await act(async () => {\n        firstAvailableCell.focus();\n      });\n      await user.keyboard(\"{Enter}\");\n\n      expect(handleChange).toHaveBeenCalledTimes(1);\n    }\n  });\n});\n```\n\n### Internationalization Tests\n\nTest calendar with different locales\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within, act } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Calendar, NimbusProvider } from \"@commercetools/nimbus\";\nimport { CalendarDate, getLocalTimeZone } from \"@internationalized/date\";\n\ndescribe(\"Calendar - Internationalization\", () => {\n  it(\"renders with German locale\", () => {\n    render(\n      <NimbusProvider locale=\"de-DE\">\n        <Calendar\n          aria-label=\"Datum wählen\"\n          defaultValue={new CalendarDate(2025, 1, 15)}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    expect(grid).toBeInTheDocument();\n\n    // German calendar should render with localized content\n    // Specific weekday names would be in German\n  });\n\n  it(\"renders with French locale\", () => {\n    render(\n      <NimbusProvider locale=\"fr-FR\">\n        <Calendar\n          aria-label=\"Select date\"\n          defaultValue={new CalendarDate(2025, 1, 15)}\n        />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\");\n    expect(grid).toBeInTheDocument();\n\n    // French calendar should render with localized content\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-date-calendar--docs)\n- [React Aria Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html)\n- [ARIA Grid Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/)\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 value types",
+          "href": "#date-value-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 ISO strings",
+          "href": "#converting-to-iso-strings",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-month display",
+          "href": "#multi-month-display",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Navigation behavior",
+          "href": "#navigation-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Date constraints",
+          "href": "#date-constraints",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Minimum and maximum values",
+          "href": "#minimum-and-maximum-values",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Unavailable dates",
+          "href": "#unavailable-dates",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom week start day",
+          "href": "#custom-week-start-day",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Internationalization",
+          "href": "#internationalization",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State props",
+          "href": "#state-props",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            8
+          ],
+          "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": "Booking system with constraints",
+          "href": "#booking-system-with-constraints",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Working days selection",
+          "href": "#working-days-selection",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-month date selection",
+          "href": "#multi-month-date-selection",
+          "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": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Date Constraints Tests",
+          "href": "#date-constraints-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-Month Display Tests",
+          "href": "#multi-month-display-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State Props Tests",
+          "href": "#state-props-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard Navigation Tests",
+          "href": "#keyboard-navigation-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Internationalization Tests",
+          "href": "#internationalization-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nCalendar guidelines focus on creating intuitive and accessible interfaces for\nviewing, navigating, and interacting with dates and events.\n\n### Best practices\n\n- **Clear visual hierarchy:** Distinguished between days, weeks, months, and\n  years. Highlight the current date and any selected dates.\n- **Intuitive navigation:** Clear controls to move between different time\n  periods (days, weeks, months, years).\n- **Clear labels and instructions:** Clear labels for navigation controls and\n  any interactive elements within the calendar.\n\n### Usage\n\nA calendar is used to visually display and manage time-based information,\nallowing users to view, schedule, and interact with dates. A common way this\ncomponent is used is within the popover, and paired with the date input.\n\n> [!TIP]\\\n> When to use\n\n- **Scheduling:** When users need to select specific dates and times.\n- **Visualizing time-based data:** To display data or to filter data in a\n  corresponding visual.\n- **Browsing dates:** When users need to navigate through different days, weeks,\n  or months to find a specific date or time.\n- **Contextual awareness of dates:** When the day of the week or the\n  relationship between dates is important for decision-making.\n- **Recurring events:** To allow users to set up and manage events that repeat\n  on a regular basis.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Simple date input:** If users already know the specific date (e.g., date of\n  birth) and typing it in a formatted field is quicker and easier.\n- **Selecting a single \"today\" or \"now\":** For actions that inherently refer to\n  the current date and time, a button or automatic function is more efficient.\n- **Limited screen space:** On very small interfaces, a compact date input or a\n  simplified selection method might be necessary.\n- **Linear processes:** For step-by-step workflows where date selection is just\n  one field, a calendar might be an unnecessary interruption.\n- **Non-time-related data:** For displaying or managing information that isn't\n  tied to specific dates or times.\n\n#### Keeping interactions simple\n\nSimple calendar interactions are vital because they minimize user effort and\ncognitive load, allowing for quick and efficient time management, the calendar's\nprimary function.\n\n> [!TIP]\\\n> **Do**\n>\n> - Provide clear navigation. Make it easy to move between days, weeks, months,\n>   and years using intuitive controls (arrows, drop downs).\n> - Ensure navigation controls are clearly labeled and their function is\n>   obvious.\n\n```jsx live\nconst App = () => <Calendar defaultValue={new CalendarDate(2025, 1, 15)} />;\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't over clutter. Avoid displaying too much information on the calendar\n>   grid at once, which can make it overwhelming.\n> - Don't make navigation confusing. Ensure navigation controls are clearly\n>   labeled and their function is obvious.\n> - Don't use it for simple date input. If users know the exact date, a direct\n>   date input field might be more efficient.\n> - Don't auto-submit on date selection. Avoid automatically submitting forms or\n>   triggering actions immediately after a date is selected.\n\n![interaction - dont's](/images/calendar/calendar-interactions-dont.png)\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": "Keeping interactions simple",
+          "href": "#keeping-interactions-simple",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}