@utilitywarehouse/hearth-react 0.31.9 → 0.32.1

package/public/llms/components/checkbox-group.md

@@ -1,6 +1,10 @@
 # CheckboxGroup
 
-`CheckboxGroup` provides a set of interactive buttons where multiple options can be selected at a time. The `CheckboxGroup` uses a fieldset to group related `Checkbox` controls. The `CheckboxGroup` is responsible for handling the value, label, helper text, validation, and disabled state, as well as determining the presentation and selection of the items in the list.
+Use CheckboxGroup to present a set of `Checkbox` controls where multiple
+options can be selected at once. It groups related checkboxes in a
+`fieldset` and handles their shared label, helper text, validation, and
+disabled state, as well as their layout. For single-select options, use
+RadioGroup instead.
 
 ```tsx
 <Flex asChild>
@@ -171,16 +175,16 @@ This component is based on the `fieldset` element and supports the following com
 | Prop                  | Type                          | Default | Description                                                                                                                                                                                                                                                           |
 | --------------------- | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `label`               | `ReactNode`                   | —       | The label for the formfield group. This should contain the question being answered by the formfield group. If you don't include a label you need to ensure you use the `aria-label` or `aria-labelledby` prop to properly associate a label with the formfield group. |
-| `name`                | `string`                      | —       |                                                                                                                                                                                                                                                                       |
-| `required`            | `boolean`                     | —       |                                                                                                                                                                                                                                                                       |
-| `disabled`            | `boolean`                     | —       |                                                                                                                                                                                                                                                                       |
-| `defaultValue`        | `string[]`                    | —       |                                                                                                                                                                                                                                                                       |
-| `value`               | `string[]`                    | —       |                                                                                                                                                                                                                                                                       |
-| `onValueChange`       | `((value: string[]) => void)` | —       |                                                                                                                                                                                                                                                                       |
+| `name`                | `string`                      | —       | The name given as data when submitted as part of a form, shared by all child `Checkbox` components.                                                                                                                                                                   |
+| `required`            | `boolean`                     | —       | Marks the checkbox group as requiring at least one selection.                                                                                                                                                                                                         |
+| `disabled`            | `boolean`                     | —       | Disables all `Checkbox` components within the group.                                                                                                                                                                                                                  |
+| `defaultValue`        | `string[]`                    | —       | The checked values when the group is initially rendered uncontrolled.                                                                                                                                                                                                 |
+| `value`               | `string[]`                    | —       | The controlled checked values of the group. Must be used in conjunction with `onValueChange`.                                                                                                                                                                         |
+| `onValueChange`       | `((value: string[]) => void)` | —       | Event handler called when the checked values of the group change.                                                                                                                                                                                                     |
 | `direction`           | `"column" \| "row"`           | —       | The direction of the checkboxes, will also set the aria-orientation value.                                                                                                                                                                                            |
 | `contentWidth`        | `Responsive<string>`          | —       | Set the container width of the CheckboxGroup children, independent to the width of the parent CheckboxGroup.                                                                                                                                                          |
 | `labelVariant`        | `"body" \| "heading"`         | —       | Set the label variant                                                                                                                                                                                                                                                 |
 | `helperText`          | `ReactNode`                   | —       | Helper text for the formfield group. Provides a hint such as specific requirements for what to choose. When displayed, child components should not display their own `helperText`.                                                                                    |
-| `validationText`      | `ReactNode`                   | —       |                                                                                                                                                                                                                                                                       |
-| `validationStatus`    | `"valid" \| "invalid"`        | —       |                                                                                                                                                                                                                                                                       |
-| `validationPlacement` | `"top" \| "bottom"`           | —       |                                                                                                                                                                                                                                                                       |
+| `validationText`      | `ReactNode`                   | —       | Text to display when the `validationStatus` is set.                                                                                                                                                                                                                   |
+| `validationStatus`    | `"valid" \| "invalid"`        | —       | Indicates the validation status of the formfield group.                                                                                                                                                                                                               |
+| `validationPlacement` | `"top" \| "bottom"`           | —       | Sets where the validation text is displayed relative to the group's children.                                                                                                                                                                                         |

package/public/llms/components/checkbox-tile.md

@@ -1,6 +1,11 @@
 # CheckboxTile
 
-The `CheckboxTile` component is a dual-state checkbox allowing users to toggle between checked and not checked. `CheckboxTile` can be used independently, however multiple checkboxes should be used within a `CheckboxGroup` to handle the state control and layout.
+Use CheckboxTile to let a user toggle a dual-state option between checked
+and not checked, presented as a larger, tile-style control rather than a
+standard checkbox. It can be used independently, but when presenting
+multiple options together use `CheckboxGroup` instead, which handles their
+state and layout. If not using the `label` prop, provide an `aria-label` or
+`aria-labelledby` so the tile has an accessible name.
 
 ```tsx
 <CheckboxTile {...args} />
@@ -101,7 +106,7 @@ This component is based on the `button` element and supports the following commo
 | `value`            | `string`                       | —       | The value given as data when submitted with a `name`.                                                                                           |
 | `onCheckedChange`  | `((checked: boolean) => void)` | —       | Event handler called when the checked state of the checkbox changes.                                                                            |
 | `defaultChecked`   | `boolean`                      | —       | The checked state of the checkbox when it is initially rendered. Use when you do not need to control its checked state.                         |
-| `defaultValue`     | `string`                       | —       |                                                                                                                                                 |
+| `defaultValue`     | `string`                       | —       | The value given as data when submitted with a `name`, when the checkbox is initially rendered uncontrolled.                                     |
 | `checked`          | `boolean`                      | —       | The controlled checked state of the checkbox. Must be used in conjunction with onCheckedChange.                                                 |
 | `required`         | `boolean`                      | —       |                                                                                                                                                 |
 | `helperText`       | `ReactNode`                    | —       | Helper text for the Checkbox. Will not display if the checkbox group has `helperText` set.                                                      |

package/public/llms/components/checkbox.md

@@ -1,9 +1,10 @@
 # Checkbox
 
-The `Checkbox` component is a dual-state checkbox allowing users to toggle
-between checked and not checked. `Checkbox` can be used independently, however
-multiple checkboxes should be used within a `CheckboxGroup` to handle the state
-control and layout.
+Use Checkbox to let a user toggle a dual-state option between checked and
+not checked. It can be used independently, but when presenting multiple
+checkboxes together use `CheckboxGroup` instead, which handles their state
+and layout. If not using the `label` prop, provide an `aria-label` or
+`aria-labelledby` so the checkbox has an accessible name.
 
 ```tsx
 <Checkbox {...args} />
@@ -93,7 +94,7 @@ This component is based on the `button` element and supports the following commo
 | `value`            | `string`                       | —       | The value given as data when submitted with a `name`.                                                                                           |
 | `onCheckedChange`  | `((checked: boolean) => void)` | —       | Event handler called when the checked state of the checkbox changes.                                                                            |
 | `defaultChecked`   | `boolean`                      | —       | The checked state of the checkbox when it is initially rendered. Use when you do not need to control its checked state.                         |
-| `defaultValue`     | `string`                       | —       |                                                                                                                                                 |
+| `defaultValue`     | `string`                       | —       | The value given as data when submitted with a `name`, when the checkbox is initially rendered uncontrolled.                                     |
 | `checked`          | `boolean`                      | —       | The controlled checked state of the checkbox. Must be used in conjunction with onCheckedChange.                                                 |
 | `required`         | `boolean`                      | —       |                                                                                                                                                 |
 | `helperText`       | `ReactNode`                    | —       | Helper text for the Checkbox. Will not display if the checkbox group has `helperText` set.                                                      |

package/public/llms/components/chip.md

@@ -1,8 +1,8 @@
 # Chip
 
-Chip is a compact, interactive element that represents an input, attribute, or
-filter. It lets users see active selections at a glance and remove them with
-a single click.
+Use Chip to represent an input, attribute, or filter that a user can remove
+with a single click. Commonly used to show active filters applied to a list
+of results.
 
 - [Usage](#usage)
 - [Removable](#removable)

package/public/llms/components/combobox.md

@@ -1,6 +1,11 @@
 # Combobox
 
-`Combobox` allows users to both type to filter results and select from a predefined list.
+Use Combobox to let users type to filter results and select from a
+predefined list of options. Pass options via the `items` prop to have them
+rendered automatically, or render `ComboboxItem` children yourself for more
+control. Set `triggerOnlyOnType` when the user must type before options are
+surfaced (e.g. a postcode or address lookup); leave it unset when there is a
+predefined list to choose from by clicking.
 
 - [Usage](#usage)
 - [Trigger only on type](#trigger-only-on-type)
@@ -65,7 +70,7 @@ asynchronously loaded list.
 ## useComboboxFilter
 
 The `useComboboxFilter` hook provides robust string matching using `Intl.Collator`.
-It returns three filter functions — `contains`, `startsWith`, and `endsWith` —
+It returns three filter functions (`contains`, `startsWith`, and `endsWith`)
 that can be passed to the `filter` prop on `Combobox`.
 
 When using `useComboboxFilter`, pass the `items` prop to provide the full list
@@ -306,8 +311,8 @@ This component is based on the [Base UI Combobox](https://base-ui.com/react/comp
 
 | Prop                   | Type                                                                                                                                | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `triggerOnlyOnType`    | `boolean`                                                                                                                           | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `noOptionsFoundText`   | `string`                                                                                                                            | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `triggerOnlyOnType`    | `boolean`                                                                                                                           | —       | When `true`, the dropdown only opens once the user starts typing, and the trigger icon button is removed. When `false`, it also opens on click of the input — use this when there is a predefined list of options to choose from.                                                                                                                                                                                                                                                                                                                                                                         |
+| `noOptionsFoundText`   | `string`                                                                                                                            | —       | Text shown as a disabled option when a search returns no matches. Only applies when options are passed via the `items` prop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `statusText`           | `string`                                                                                                                            | —       | Displays a status message whose content changes are announced politely to screen readers. Useful for conveying the status of an asynchronously loaded list.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `loading`              | `boolean`                                                                                                                           | —       | Displays a loading indicator in the input field to show that options are being fetched or updated asynchronously.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `autoComplete`         | `string`                                                                                                                            | —       | Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -344,9 +349,9 @@ This component is based on the [Base UI Combobox](https://base-ui.com/react/comp
 | `defaultValue`         | `ComboboxValueType<Value, Multiple> \| null`                                                                                        | —       | The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the `value` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `value`                | `ComboboxValueType<Value, Multiple> \| null`                                                                                        | —       | The selected value of the combobox. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `onValueChange`        | `((value: ComboboxValueType<Value, Multiple> \| (Multiple extends true ? never : null), eventDetails: ChangeEventDetails) => void)` | —       | Event handler called when the selected value of the combobox changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `labelId`              | `string`                                                                                                                            | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `helperTextId`         | `string`                                                                                                                            | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `validationTextId`     | `string`                                                                                                                            | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `labelId`              | `string`                                                                                                                            | —       | The `id` of the element rendering the field's label, for `aria-labelledby` association.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `helperTextId`         | `string`                                                                                                                            | —       | The `id` of the element rendering the field's helper text, for `aria-describedby` association.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `validationTextId`     | `string`                                                                                                                            | —       | The `id` of the element rendering the field's validation text, for `aria-describedby` association.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `label`                | `string`                                                                                                                            | —       | The label for the form field, describing its purpose.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `hideLabel`            | `boolean`                                                                                                                           | —       | Visually hide the label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `labelVariant`         | `"body" \| "heading"`                                                                                                               | —       | Change the label variant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

package/public/llms/components/container.md

@@ -1,5 +1,13 @@
 # Container
 
+Use Container to constrain and center page content, with a max-width that
+follows the container width design token above the desktop breakpoint and
+spans 100% below it, plus optional responsive padding and gutters via the
+`spacing` prop.
+For primitive styling with no built-in max-width or spacing, use Box instead.
+For grid layouts, use Grid instead. For general flexbox-based layouts without
+the max-width/centering behaviour, use Flex instead.
+
 ```tsx
 <Container {...args}>
   <Placeholder

package/public/llms/components/currency-input.md

@@ -1,6 +1,10 @@
 # CurrencyInput
 
-`CurrencyInput` is an interactive field that specifically used for entering monetary amounts. It’s commonly used across Cashback and payment areas.
+Use CurrencyInput for entering monetary amounts, such as in Cashback and
+payment areas. It displays values with comma-separated thousands by default
+and returns the underlying value without formatting via `onChange`.
+
+For general text entry, use TextInput instead.
 
 ```tsx
 <Flex direction="column" gap="400">
@@ -63,16 +67,16 @@ This component is based on the `TextInput` component and supports the following
 
 - Margin
 
-| Prop                     | Type                   | Default | Description                                                                 |
-| ------------------------ | ---------------------- | ------- | --------------------------------------------------------------------------- |
-| `label`                  | `string`               | —       | The label for the form field, describing its purpose.                       |
-| `defaultValue`           | `string \| number`     | —       | The initial value of the input when rendered.                               |
-| `value`                  | `string \| number`     | —       | The controlled value of the input. Must be used with an `onChange` handler. |
-| `labelId`                | `string`               | —       |                                                                             |
-| `helperTextId`           | `string`               | —       |                                                                             |
-| `validationTextId`       | `string`               | —       |                                                                             |
-| `labelVariant`           | `"body" \| "heading"`  | —       | Change the label variant                                                    |
-| `helperText`             | `string`               | —       | Optional helper text to provide additional context or instructions.         |
-| `validationText`         | `string`               | —       | Text to display when the `validationStatus` is set.                         |
-| `validationStatus`       | `"valid" \| "invalid"` | —       | Indicates the validation status.                                            |
-| `disableGroupSeparators` | `boolean`              | —       |                                                                             |
+| Prop                     | Type                   | Default | Description                                                                                        |
+| ------------------------ | ---------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `label`                  | `string`               | —       | The label for the form field, describing its purpose.                                              |
+| `defaultValue`           | `string \| number`     | —       | The initial value of the input when rendered.                                                      |
+| `value`                  | `string \| number`     | —       | The controlled value of the input. Must be used with an `onChange` handler.                        |
+| `labelId`                | `string`               | —       | The `id` of the element rendering the field's label, for `aria-labelledby` association.            |
+| `helperTextId`           | `string`               | —       | The `id` of the element rendering the field's helper text, for `aria-describedby` association.     |
+| `validationTextId`       | `string`               | —       | The `id` of the element rendering the field's validation text, for `aria-describedby` association. |
+| `labelVariant`           | `"body" \| "heading"`  | —       | Change the label variant                                                                           |
+| `helperText`             | `string`               | —       | Optional helper text to provide additional context or instructions.                                |
+| `validationText`         | `string`               | —       | Text to display when the `validationStatus` is set.                                                |
+| `validationStatus`       | `"valid" \| "invalid"` | —       | Indicates the validation status.                                                                   |
+| `disableGroupSeparators` | `boolean`              | `false` | Disables comma-separated thousands grouping in the displayed value.                                |

package/public/llms/components/date-input.md

@@ -1,6 +1,12 @@
 # DateInput
 
-`DateInput` allows users to enter a date manually using separate input fields for day, month, and year. It provides flexibility to show only the date segments you need. Use `DateInput` when you need users to enter dates manually.
+Use DateInput when users need to enter a date manually, using separate
+fields for day, month, and year. Use the `hideDay`, `hideMonth`, and
+`hideYear` props to show only the segments you need.
+
+For a date picker with a visual calendar, use DatePicker instead.
+DateInput renders the visual `valid`/`invalid` states but does not perform
+validation internally — validation logic must be supplied by the consumer.
 
 ```tsx
 <DateInput label="Date" helperText="Helper text" dayValue="15" monthValue="06" yearValue="1990" />
@@ -68,16 +74,16 @@ This component is based on the `fieldset` element and supports the following com
 | `onDayChange`       | `ChangeEventHandler<HTMLInputElement, HTMLInputElement>`                    | —       | Callback fired when the day value changes.                                                                                                                                                                                                                            |
 | `onMonthChange`     | `ChangeEventHandler<HTMLInputElement, HTMLInputElement>`                    | —       | Callback fired when the month value changes.                                                                                                                                                                                                                          |
 | `onYearChange`      | `ChangeEventHandler<HTMLInputElement, HTMLInputElement>`                    | —       | Callback fired when the year value changes.                                                                                                                                                                                                                           |
-| `onDayFocus`        | `FocusEventHandler<HTMLInputElement>`                                       | —       |                                                                                                                                                                                                                                                                       |
-| `onMonthFocus`      | `FocusEventHandler<HTMLInputElement>`                                       | —       |                                                                                                                                                                                                                                                                       |
-| `onYearFocus`       | `FocusEventHandler<HTMLInputElement>`                                       | —       |                                                                                                                                                                                                                                                                       |
-| `onDayBlur`         | `FocusEventHandler<HTMLInputElement>`                                       | —       |                                                                                                                                                                                                                                                                       |
-| `onMonthBlur`       | `FocusEventHandler<HTMLInputElement>`                                       | —       |                                                                                                                                                                                                                                                                       |
-| `onYearBlur`        | `FocusEventHandler<HTMLInputElement>`                                       | —       |                                                                                                                                                                                                                                                                       |
+| `onDayFocus`        | `FocusEventHandler<HTMLInputElement>`                                       | —       | Callback fired when the day segment receives focus.                                                                                                                                                                                                                   |
+| `onMonthFocus`      | `FocusEventHandler<HTMLInputElement>`                                       | —       | Callback fired when the month segment receives focus.                                                                                                                                                                                                                 |
+| `onYearFocus`       | `FocusEventHandler<HTMLInputElement>`                                       | —       | Callback fired when the year segment receives focus.                                                                                                                                                                                                                  |
+| `onDayBlur`         | `FocusEventHandler<HTMLInputElement>`                                       | —       | Callback fired when the day segment loses focus.                                                                                                                                                                                                                      |
+| `onMonthBlur`       | `FocusEventHandler<HTMLInputElement>`                                       | —       | Callback fired when the month segment loses focus.                                                                                                                                                                                                                    |
+| `onYearBlur`        | `FocusEventHandler<HTMLInputElement>`                                       | —       | Callback fired when the year segment loses focus.                                                                                                                                                                                                                     |
 | `label`             | `ReactNode`                                                                 | —       | The label for the formfield group. This should contain the question being answered by the formfield group. If you don't include a label you need to ensure you use the `aria-label` or `aria-labelledby` prop to properly associate a label with the formfield group. |
 | `labelVariant`      | `"body" \| "heading"`                                                       | —       | Set the label variant                                                                                                                                                                                                                                                 |
 | `helperText`        | `ReactNode`                                                                 | —       | Helper text for the formfield group. Provides a hint such as specific requirements for what to choose. When displayed, child components should not display their own `helperText`.                                                                                    |
-| `validationText`    | `ReactNode`                                                                 | —       |                                                                                                                                                                                                                                                                       |
-| `validationStatus`  | `"valid" \| "invalid"`                                                      | —       |                                                                                                                                                                                                                                                                       |
-| `type`              | `"number" \| "search" \| "text" \| "tel" \| "url" \| "email" \| "password"` | —       |                                                                                                                                                                                                                                                                       |
+| `validationText`    | `ReactNode`                                                                 | —       | Text to display when the `validationStatus` is set.                                                                                                                                                                                                                   |
+| `validationStatus`  | `"valid" \| "invalid"`                                                      | —       | Indicates the validation status of the formfield group.                                                                                                                                                                                                               |
+| `type`              | `"number" \| "search" \| "text" \| "tel" \| "url" \| "email" \| "password"` | `text`  | Sets the input's HTML `type` attribute, which determines the keyboard and validation behavior the browser applies to it.                                                                                                                                              |
 | `value`             | `string \| number`                                                          | —       | The controlled value of the input. Must be used with an `onChange` handler.                                                                                                                                                                                           |

package/public/llms/components/date-picker.md

@@ -1,6 +1,11 @@
 # DatePicker
 
-`DatePicker` allows a user to specify a date, month or date range through the use of an expandable calendar.
+Use DatePicker when a user needs to specify a single date via an
+expandable calendar. It is built on the React Datepicker library and only
+supports single-date selection — range and multi-date selection are not
+supported.
+
+For faster, manual date entry without a calendar, use DateInput instead.
 
 ```tsx
 <DatePicker
@@ -29,7 +34,7 @@ It supports the following common props:
 | `label`                         | `string`                                                                                                                                                                                                                                                                            | —       | The label for the form field, describing its purpose.                                                           |
 | `title`                         | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
 | `date`                          | `Date`                                                                                                                                                                                                                                                                              | —       |                                                                                                                 |
-| `onChange`                      | `((date: Date \| null, event?: MouseEvent<HTMLElement, MouseEvent> \| KeyboardEvent<HTMLElement> \| undefined) => void)`                                                                                                                                                            | —       |                                                                                                                 |
+| `onChange`                      | `((date: Date \| null, event?: MouseEvent<HTMLElement, MouseEvent> \| KeyboardEvent<HTMLElement> \| undefined) => void)`                                                                                                                                                            | —       | Callback fired when the selected date changes.                                                                  |
 | `minDate`                       | `Date`                                                                                                                                                                                                                                                                              | —       |                                                                                                                 |
 | `maxDate`                       | `Date`                                                                                                                                                                                                                                                                              | —       |                                                                                                                 |
 | `scrollableYearDropdown`        | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
@@ -44,9 +49,9 @@ It supports the following common props:
 | `excludeDates`                  | `{ date: Date; message?: string \| undefined; }[] \| Date[]`                                                                                                                                                                                                                        | —       |                                                                                                                 |
 | `includeDates`                  | `Date[]`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
 | `filterDate`                    | `((date: Date) => boolean)`                                                                                                                                                                                                                                                         | —       |                                                                                                                 |
-| `disabled`                      | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
+| `disabled`                      | `boolean`                                                                                                                                                                                                                                                                           | —       | Disables the DatePicker, preventing interaction.                                                                |
 | `disabledKeyboardNavigation`    | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
-| `selectsMultiple`               | `undefined`                                                                                                                                                                                                                                                                         | —       |                                                                                                                 |
+| `selectsMultiple`               | `undefined`                                                                                                                                                                                                                                                                         | —       | Not supported — DatePicker only supports selecting a single date.                                               |
 | `selectedDates`                 | `Date[]`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
 | `selected`                      | `Date \| null`                                                                                                                                                                                                                                                                      | —       |                                                                                                                 |
 | `inline`                        | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
@@ -54,7 +59,7 @@ It supports the following common props:
 | `renderYearContent`             | `((year: number) => ReactNode)`                                                                                                                                                                                                                                                     | —       |                                                                                                                 |
 | `selectsEnd`                    | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
 | `selectsStart`                  | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
-| `selectsRange`                  | `undefined`                                                                                                                                                                                                                                                                         | —       |                                                                                                                 |
+| `selectsRange`                  | `undefined`                                                                                                                                                                                                                                                                         | —       | Not supported — DatePicker only supports selecting a single date.                                               |
 | `startDate`                     | `Date \| null`                                                                                                                                                                                                                                                                      | —       |                                                                                                                 |
 | `endDate`                       | `Date \| null`                                                                                                                                                                                                                                                                      | —       |                                                                                                                 |
 | `yearItemNumber`                | `number`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
@@ -105,9 +110,9 @@ It supports the following common props:
 | `timeInputLabel`                | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
 | `customTimeInput`               | `ReactElement<{ date?: Date \| undefined; value: string; onChange: (time: string) => void; }, string \| JSXElementConstructor<any>>`                                                                                                                                                | —       |                                                                                                                 |
 | `className`                     | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
-| `onMonthChange`                 | `((date: Date) => void)`                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
-| `onYearChange`                  | `((date: Date) => void)`                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
-| `onMonthMouseLeave`             | `VoidFunction`                                                                                                                                                                                                                                                                      | —       |                                                                                                                 |
+| `onMonthChange`                 | `((date: Date) => void)`                                                                                                                                                                                                                                                            | —       | Callback fired when the displayed month changes.                                                                |
+| `onYearChange`                  | `((date: Date) => void)`                                                                                                                                                                                                                                                            | —       | Callback fired when the displayed year changes.                                                                 |
+| `onMonthMouseLeave`             | `VoidFunction`                                                                                                                                                                                                                                                                      | —       | Callback fired when the mouse leaves a month in the calendar.                                                   |
 | `onClickOutside`                | `ClickOutsideHandler`                                                                                                                                                                                                                                                               | —       |                                                                                                                 |
 | `icon`                          | `ReactNode`                                                                                                                                                                                                                                                                         | —       |                                                                                                                 |
 | `portalId`                      | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
@@ -135,18 +140,18 @@ It supports the following common props:
 | `autoFocus`                     | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
 | `placeholderText`               | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
 | `autoComplete`                  | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
-| `required`                      | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
+| `required`                      | `boolean`                                                                                                                                                                                                                                                                           | —       | Marks the field as required.                                                                                    |
 | `tabIndex`                      | `number`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
 | `aria-describedby`              | `string`                                                                                                                                                                                                                                                                            | —       | Identifies the element (or elements) that describes the object. @see aria-labelledby                            |
 | `aria-invalid`                  | `"false" \| "true" \| "grammar" \| "spelling"`                                                                                                                                                                                                                                      | —       | Indicates the entered value does not conform to the format expected by the application. @see aria-errormessage. |
 | `aria-labelledby`               | `string`                                                                                                                                                                                                                                                                            | —       | Identifies the element (or elements) that labels the current element. @see aria-describedby.                    |
 | `aria-required`                 | `"false" \| "true"`                                                                                                                                                                                                                                                                 | —       | Indicates that user input is required on the element before a form may be submitted.                            |
 | `onChangeRaw`                   | `((event?: MouseEvent<HTMLElement, MouseEvent> \| KeyboardEvent<HTMLElement> \| undefined, selectionMeta?: { date: Date; formattedDate: string; } \| undefined) => void)`                                                                                                           | —       |                                                                                                                 |
-| `labelId`                       | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
-| `helperTextId`                  | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
-| `validationTextId`              | `string`                                                                                                                                                                                                                                                                            | —       |                                                                                                                 |
+| `labelId`                       | `string`                                                                                                                                                                                                                                                                            | —       | The `id` of the element rendering the field's label, for `aria-labelledby` association.                         |
+| `helperTextId`                  | `string`                                                                                                                                                                                                                                                                            | —       | The `id` of the element rendering the field's helper text, for `aria-describedby` association.                  |
+| `validationTextId`              | `string`                                                                                                                                                                                                                                                                            | —       | The `id` of the element rendering the field's validation text, for `aria-describedby` association.              |
 | `labelVariant`                  | `"body" \| "heading"`                                                                                                                                                                                                                                                               | —       | Change the label variant                                                                                        |
 | `helperText`                    | `string`                                                                                                                                                                                                                                                                            | —       | Optional helper text to provide additional context or instructions.                                             |
 | `validationText`                | `string`                                                                                                                                                                                                                                                                            | —       | Text to display when the `validationStatus` is set.                                                             |
 | `validationStatus`              | `"valid" \| "invalid"`                                                                                                                                                                                                                                                              | —       | Indicates the validation status.                                                                                |
-| `disableTodayIndicator`         | `boolean`                                                                                                                                                                                                                                                                           | —       |                                                                                                                 |
+| `disableTodayIndicator`         | `boolean`                                                                                                                                                                                                                                                                           | `false` | Hides the indicator that highlights today's date in the calendar.                                               |

package/public/llms/components/description-list.md

@@ -1,6 +1,9 @@
 # DescriptionList
 
-Use the `DescriptionList` component when you need to present pairs of related information together.
+Use DescriptionList to present pairs of related information together, such
+as contact details or account information. Wrap any number of
+DescriptionListItem components, which render as `dt`/`dd` pairs inside a
+semantic `dl` element.
 
 ```tsx
 <Box width="550px">
@@ -116,15 +119,15 @@ This component is based on the `dl` element and supports the following common pr
 - Margin
 - Size (width props only)
 
-| Prop               | Type                                    | Default | Description                                                                                       |
-| ------------------ | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
-| `heading`          | `string`                                | —       | Actual string to display as section header                                                        |
-| `headingElement`   | `"div" \| "h1" \| "h2" \| "h3" \| "h4"` | `h2`    |                                                                                                   |
-| `helperText`       | `string`                                | —       | Optional helper text to provide additional context or instructions.                               |
-| `trailingContent`  | `ReactNode`                             | —       | Optional trailing content element                                                                 |
-| `validationStatus` | `"invalid"`                             | —       | Indicates the validation state                                                                    |
-| `validationText`   | `string`                                | —       | Text to display when the `validationStatus` is set.                                               |
-| `direction`        | `Responsive<"row" \| "column">`         | —       | Responsive direction of the section header content. By default, the content is laid out in a row. |
+| Prop               | Type                                    | Default | Description                                                                                         |
+| ------------------ | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `heading`          | `string`                                | —       | Actual string to display as section header                                                          |
+| `headingElement`   | `"div" \| "h1" \| "h2" \| "h3" \| "h4"` | `h2`    | The element type to render the heading as.                                                          |
+| `helperText`       | `string`                                | —       | Optional helper text to provide additional context or instructions.                                 |
+| `trailingContent`  | `ReactNode`                             | —       | Optional trailing content element                                                                   |
+| `validationStatus` | `"invalid"`                             | —       | Indicates the validation state                                                                      |
+| `validationText`   | `string`                                | —       | Text to display when the `validationStatus` is set.                                                 |
+| `direction`        | `Responsive<"row" \| "column">`         | —       | The layout direction of the `DescriptionListItem` children. Responsive — can be set per breakpoint. |
 
 ## DescriptionListItem API
 

package/public/llms/components/detail-text.md

@@ -1,5 +1,11 @@
 # DetailText
 
+Use DetailText for smaller, secondary text such as captions, metadata, or
+form field hints — it renders a `span` element by default, with responsive
+`size` and `color` props including built-in `valid`/`invalid` states.
+For the main body copy of a page, use BodyText instead.
+For heading-level text, use Heading instead.
+
 ```tsx
 <Flex direction="column" gap="100">
   <DetailText size="sm">Hamburgefons (sm)</DetailText>
@@ -87,4 +93,4 @@ This component is based on the `span` element and supports the following common
 | `size`     | `Responsive<"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl">` | `md`    | Set the text size styles.                                                                            |
 | `color`    | `(Responsive<"text" \| "valid" \| "invalid"> & string)`               | `text`  | Set the text color                                                                                   |
 | `inverted` | `boolean`                                                             | —       | Inverts the component colours, for use on darker surface colours.                                    |
-| `as`       | `"span" \| "div" \| "p"`                                              | —       |                                                                                                      |
+| `as`       | `"span" \| "div" \| "p"`                                              | —       | Renders a `span` element. This is the default. Renders a `div` element. Renders a `p` element.       |

package/public/llms/components/divider.md

@@ -1,8 +1,10 @@
 # Divider
 
-Used to provide a visual break and semantically divide content. Supports
-vertical and horizontal orientations. Vertical dividers will only be visible
-when contained inside an element with display set to `flex` or `grid`.
+Use Divider to provide a visual break and semantically divide content.
+It renders an `hr` with a `separator` role by default — use the
+`decorative` prop instead of CSS styling when you need a purely visual
+separation removed from the accessibility tree. A vertical orientation
+is only visible inside a flex or grid container.
 
 ```tsx
 <Flex direction="column" gap="400" width="100%" maxWidth="800px" padding="200">
@@ -77,5 +79,5 @@ This component is based on the `hr` element, and supports the following common p
 
 | Prop          | Type                         | Default      | Description                                                                                                                                                                          |
 | ------------- | ---------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `orientation` | `"horizontal" \| "vertical"` | `horizontal` |                                                                                                                                                                                      |
+| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | Sets whether the divider is drawn as a horizontal or vertical line.                                                                                                                  |
 | `decorative`  | `boolean`                    | —            | Whether or not the component is purely decorative. When true, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. |

package/public/llms/components/em.md

@@ -1,5 +1,10 @@
 # Em
 
+Use Em to mark up a run of text with stress emphasis within a larger body
+of text — it renders an `em` element by default.
+For strong importance rather than emphasis, use Strong instead.
+For standalone body or detail text, use BodyText or DetailText instead.
+
 ```tsx
 <Flex direction="column" gap="100">
   {sizes.map(size => (

package/public/llms/components/expandable-card.md

@@ -1,7 +1,11 @@
 # ExpandableCard
 
-Use `ExpandableCard` to show a summary header with an optional leading icon and helper text, which
-can be expanded to reveal additional content.
+Use ExpandableCard to show a summary header — with an optional leading
+icon, helper text, badge, and numeric value — that can be expanded to
+reveal additional content. Group multiple cards with ExpandableCardGroup.
+
+For multiple sections of content that need to expand and collapse
+independently as a related set, use Accordion instead.
 
 - [Leading icon](#leading-icon)
 - [Default open](#default-open)
@@ -73,7 +77,7 @@ icon in a coloured `IconContainer`.
 ## Default open
 
 Use `defaultOpen` to render the card in the open state on initial mount. This is an uncontrolled
-approach — the card manages its own open/closed state internally after mount.
+approach: the card manages its own open/closed state internally after mount.
 
 ```tsx
 <ExpandableCard heading="Heading" helperText="Helper text" defaultOpen>
@@ -191,17 +195,18 @@ This component is based on the `div` element and supports the following common p
 
 - Margin
 
-| Prop                              | Type                                                                                       | Default | Description |
-| --------------------------------- | ------------------------------------------------------------------------------------------ | ------- | ----------- |
-| `heading`                         | `string`                                                                                   | —       |             |
-| `helperText`                      | `string`                                                                                   | —       |             |
-| `leadingIcon`                     | `ReactNode`                                                                                | —       |             |
-| `leadingIconContainerColorScheme` | `"energy" \| "mobile" \| "broadband" \| "insurance" \| "cashback" \| "pig" \| "highlight"` | —       |             |
-| `badge`                           | `ReactNode`                                                                                | —       |             |
-| `numericValue`                    | `string`                                                                                   | —       |             |
-| `open`                            | `boolean`                                                                                  | —       |             |
-| `defaultOpen`                     | `boolean`                                                                                  | —       |             |
-| `onOpenChange`                    | `((open: boolean) => void)`                                                                | —       |             |
+| Prop                              | Type                                                                                       | Default | Description                                                                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `heading`                         | `string`                                                                                   | —       | The heading shown in the card's summary header, always visible regardless of expanded state.                                 |
+| `helperText`                      | `string`                                                                                   | —       | Additional helper text shown below the heading in the summary header.                                                        |
+| `leadingIcon`                     | `ReactNode`                                                                                | —       | An icon rendered to the left of the heading. Pass `aria-hidden` on the icon to ensure it is not announced to screen readers. |
+| `leadingIconContainerColorScheme` | `"energy" \| "mobile" \| "broadband" \| "insurance" \| "cashback" \| "pig" \| "highlight"` | —       | Wraps `leadingIcon` in a coloured `IconContainer` using the given colour scheme.                                             |
+| `badge`                           | `ReactNode`                                                                                | —       | An optional badge rendered below the heading and helper text in the summary header.                                          |
+| `numericValue`                    | `string`                                                                                   | —       | A numeric value rendered on the right side of the summary header.                                                            |
+| `children`                        | `ReactNode`                                                                                | —       | The content revealed when the card is expanded.                                                                              |
+| `open`                            | `boolean`                                                                                  | —       |                                                                                                                              |
+| `defaultOpen`                     | `boolean`                                                                                  | —       |                                                                                                                              |
+| `onOpenChange`                    | `((open: boolean) => void)`                                                                | —       |                                                                                                                              |
 
 ### ExpandableCardGroup API
 
@@ -214,4 +219,4 @@ This component is based on the `div` element and supports the following common p
 | `heading`         | `string`                       | —       | Actual string to display as section header                          |
 | `helperText`      | `string`                       | —       | Optional helper text to provide additional context or instructions. |
 | `trailingContent` | `ReactNode`                    | —       | Optional trailing content element                                   |
-| `headingElement`  | `"h1" \| "h2" \| "h3" \| "h4"` | —       |                                                                     |
+| `headingElement`  | `"h1" \| "h2" \| "h3" \| "h4"` | —       | Sets the heading element rendered for the group's `heading`.        |