@utilitywarehouse/hearth-react 0.30.2 → 0.31.0

package/public/llms/components/menu.md

@@ -1,6 +1,18 @@
 # Menu
 
-Use the `Menu` component to present a short list of actions or options in response to a user’s interaction. Menus are ideal for actions like sorting, filtering, or providing additional options without navigating away from the current screen.
+Use the `Menu` component to present a short list of actions or options in
+response to a user’s interaction. Menus are ideal for actions like sorting,
+filtering, or providing additional options without navigating away from the
+current screen.
+
+- [Usage](#usage)
+- [MenuTrigger](#menutrigger)
+- [Placement](#placement)
+- [MenuItem](#menuitem)
+- [Accessibility](#accessibility)
+- [SEO](#seo)
+- [Migration](#migration)
+- [API](#api)
 
 ```tsx
 <Menu {...args}>
@@ -66,7 +78,7 @@ outside of the first `Menu` to close it.
 <Menu modal={false}>
 ```
 
-## Menu trigger
+## MenuTrigger
 
 You must render either a `Button` or `IconButton` component as a child of the `MenuTrigger`.
 
@@ -86,7 +98,57 @@ You must render either a `Button` or `IconButton` component as a child of the `M
 </Menu>
 ```
 
-## Menu content placement
+### Detached trigger
+
+By default the `MenuTrigger` lives inside `Menu`. When the trigger needs to exist in a
+different part of the component tree — for example in a toolbar while the menu state is
+managed elsewhere — use `Menu.createHandle()` to connect them.
+
+Create the handle once at module level (outside any component), then pass it to both
+`MenuTrigger` and `Menu` via the `handle` prop. `Menu` no longer needs a `MenuTrigger`
+child in this pattern.
+
+```tsx
+<Flex gap="300" alignItems="center">
+  {/* MenuTrigger lives outside Menu — connected via handle */}
+  <MenuTrigger handle={detachedHandle}>
+    <Button variant="outline" colorScheme="functional">
+      Open menu
+      <ExpandSmallIcon />
+    </Button>
+  </MenuTrigger>
+  {/* Menu has no MenuTrigger child — it opens via the handle above */}
+  <Menu handle={detachedHandle}>
+    <MenuContent>
+      <MenuItem>Item</MenuItem>
+      <MenuItem>Item</MenuItem>
+      <MenuItem>Item</MenuItem>
+    </MenuContent>
+  </Menu>
+</Flex>
+```
+
+```tsx
+const menuHandle = Menu.createHandle();
+
+// Somewhere in the tree:
+<MenuTrigger handle={menuHandle}>
+  <Button variant="outline" colorScheme="functional">
+    Open menu
+    <ExpandSmallIcon />
+  </Button>
+</MenuTrigger>
+
+// Elsewhere in the tree:
+<Menu handle={menuHandle}>
+  <MenuContent>
+    <MenuItem>Item</MenuItem>
+    <MenuItem>Item</MenuItem>
+  </MenuContent>
+</Menu>
+```
+
+## Placement
 
 You can adjust the vertical and horizontal placement of the `MenuContent`.
 
@@ -139,12 +201,12 @@ You can adjust the vertical and horizontal placement of the `MenuContent`.
 </Flex>
 ```
 
-## Menu item
+## MenuItem
 
 The `MenuItem` can be either `functional` or `destructive`, and can also contain icons.
 
-If a `MenuItem` is navigating to another page, you can use the `asChild` prop to
-render a semantic `<a>` element.
+If a `MenuItem` is navigating to another page, use the `asChild` prop to render a
+semantic `<a>` element — all accessible attributes are merged onto the child.
 
 ```tsx
 <MenuContent>
@@ -154,7 +216,6 @@ render a semantic `<a>` element.
     Destructive item
     <TrashSmallIcon />
   </MenuItem>
-  {/* render a link element if navigating to somewhere else */}
   <MenuItem asChild>
     <a href="/another-page">
       Navigation Item
@@ -227,44 +288,111 @@ to manage focus movement among menu items.
 
 By default, `MenuContent` is removed from the DOM when the menu is closed, which
 means search engines may not index its content. If the menu items are important
-for SEO — for example, primary navigation links — use the `forceMount` prop on
+for SEO — for example, primary navigation links — use the `keepMounted` prop on
 `MenuContent` to keep them in the DOM at all times.
 
-When `forceMount` is set, the closed menu is hidden from view and the
-accessibility tree using the `hidden` attribute, so it has no impact on the
-visual layout or screen reader experience.
-
 ```tsx
-<MenuContent forceMount>
+<MenuContent keepMounted>
   <MenuItem>Item</MenuItem>
 </MenuContent>
 ```
 
-## Menu API
+### Migrating from `v0.30.x`
+
+**`MenuItem` deprecations:**
+
+- `onSelect` is deprecated. Use `onClick` instead — it fires for both mouse and keyboard activation.
+- `textValue` is deprecated. Use `label` instead — it is used for accessibility and keyboard navigation.
+
+**`MenuContent` deprecation:**
+
+- `forceMount` is deprecated. Use `keepMounted` instead.
+
+```tsx
+{/* Before */}
+<MenuItem onSelect={handleSelect} textValue="label">Item</MenuItem>
+<MenuContent forceMount>...</MenuContent>
+
+{/* After */}
+<MenuItem onClick={handleSelect} label="label">Item</MenuItem>
+<MenuContent keepMounted>...</MenuContent>
+```
+
+### Consumer migration prompt
 
-| Prop           | Type                        | Default | Description |
-| -------------- | --------------------------- | ------- | ----------- |
-| `open`         | `boolean`                   | —       |             |
-| `defaultOpen`  | `boolean`                   | —       |             |
-| `onOpenChange` | `((open: boolean) => void)` | —       |             |
-| `modal`        | `boolean`                   | —       |             |
+Paste the following into an agent to update all Menu usages in your codebase:
 
-## MenuContent API
+```
+I'm upgrading @utilitywarehouse/hearth-react. The Menu component has migrated
+from Radix UI to Base UI internally. The following prop changes affect consumers:
+
+RENAMED (deprecated — old name still works but logs a dev-mode warning):
+  - `MenuItem: onSelect` → `onClick`: Base UI uses standard React onClick for
+    both mouse and keyboard activation.
+  - `MenuItem: textValue` → `label`: used for keyboard text navigation and
+    accessibility.
+  - `MenuContent: forceMount` → `keepMounted`: aligned with Base UI's API.
+
+Please search this codebase for all usages of MenuItem and MenuContent imported
+from '@utilitywarehouse/hearth-react' and apply the following changes:
+  - Replace every `onSelect=` on MenuItem with `onClick=`
+  - Replace every `textValue=` on MenuItem with `label=`
+  - Replace every `forceMount` on MenuContent with `keepMounted`
+
+Do not change any other logic, styling, or structure. After making changes,
+run TypeScript to confirm no type errors remain.
+```
 
-| Prop                     | Type                                                       | Default      | Description                                                                                                           |
-| ------------------------ | ---------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
-| `forceMount`             | `true`                                                     | —            | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. |
-| `updatePositionStrategy` | `"optimized" \| "always"`                                  | —            |                                                                                                                       |
-| `placement`              | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight"` | `bottomLeft` |                                                                                                                       |
+## API
+
+| Prop               | Type                                                                  | Default | Description                                                                                                                                                                                                                                                                                                               |
+| ------------------ | --------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`         | `ReactNode`                                                           | —       | The content of the Menu. Should contain `MenuTrigger` and `MenuContent`.                                                                                                                                                                                                                                                  |
+| `open`             | `boolean`                                                             | —       | Whether the menu is currently open.                                                                                                                                                                                                                                                                                       |
+| `disabled`         | `boolean`                                                             | `false` | Whether the component should ignore user interaction.                                                                                                                                                                                                                                                                     |
+| `modal`            | `boolean`                                                             | `true`  | Determines if the menu enters a modal state when open. - `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed.                                                 |
+| `defaultOpen`      | `boolean`                                                             | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.                                                                                                                                                                                                                             |
+| `onOpenChange`     | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | —       | Event handler called when the menu is opened or closed.                                                                                                                                                                                                                                                                   |
+| `actionsRef`       | `RefObject<MenuRootActions \| null>`                                  | —       | A ref to imperative actions. - `unmount`: When specified, the menu will not be unmounted when closed. Instead, the `unmount` function must be called to unmount the menu manually. Useful when the menu's animation is controlled by an external library. - `close`: When specified, the menu can be closed imperatively. |
+| `triggerId`        | `string \| null`                                                      | —       | ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).                                                               |
+| `defaultTriggerId` | `string \| null`                                                      | —       | ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.                                                                                                                                                                     |
+| `handle`           | `MenuHandle<unknown>`                                                 | —       | A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state.                                                                                                                                                                                                   |
+
+### MenuTrigger API
+
+| Prop          | Type                                                          | Default | Description                                                                                                                     |
+| ------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `style`       | `CSSProperties`                                               | —       |                                                                                                                                 |
+| `className`   | `string`                                                      | —       |                                                                                                                                 |
+| `disabled`    | `boolean`                                                     | `false` | Whether the component should ignore user interaction.                                                                           |
+| `children`    | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | —       | The content of the MenuTrigger. Should contain a single `Button` or `IconButton` that will be used as the trigger for the Menu. |
+| `closeDelay`  | `number`                                                      | `0`     | How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.  |
+| `handle`      | `MenuHandle<unknown>`                                         | —       | A handle to associate the trigger with a menu.                                                                                  |
+| `delay`       | `number`                                                      | `100`   | How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.            |
+| `openOnHover` | `boolean`                                                     | —       | Whether the menu should also open when the trigger is hovered.                                                                  |
+
+### MenuContent API
+
+| Prop          | Type                                                       | Default      | Description                                                                          |
+| ------------- | ---------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
+| `className`   | `string`                                                   | —            |                                                                                      |
+| `style`       | `CSSProperties`                                            | —            |                                                                                      |
+| `placement`   | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight"` | `bottomLeft` | The placement of the menu relative to the trigger element. Defaults to 'bottomLeft'. |
+| `keepMounted` | `boolean`                                                  | `false`      | Whether the menu should be kept mounted in the DOM when closed. Defaults to false.   |
+| `forceMount`  | `true`                                                     | —            | @deprecated Use `keepMounted` instead. Will be removed in next major.                |
 
 ### MenuItem API
 
 This component is based on the `div` element.
 
-| Prop          | Type                            | Default      | Description |
-| ------------- | ------------------------------- | ------------ | ----------- |
-| `onSelect`    | `((event: Event) => void)`      | —            |             |
-| `asChild`     | `boolean`                       | —            |             |
-| `disabled`    | `boolean`                       | —            |             |
-| `textValue`   | `string`                        | —            |             |
-| `colorScheme` | `"functional" \| "destructive"` | `functional` |             |
+| Prop           | Type                                                                     | Default      | Description                                                                                                                                    |
+| -------------- | ------------------------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`        | `string`                                                                 | —            | Overrides the text label to use when the item is matched during keyboard text navigation.                                                      |
+| `className`    | `string`                                                                 | —            |                                                                                                                                                |
+| `id`           | `string`                                                                 | —            | @ignore                                                                                                                                        |
+| `onClick`      | `((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` | —            | The click handler for the menu item.                                                                                                           |
+| `disabled`     | `boolean`                                                                | `false`      | Whether the component should ignore user interaction.                                                                                          |
+| `closeOnClick` | `boolean`                                                                | `true`       | Whether to close the menu when the item is clicked.                                                                                            |
+| `colorScheme`  | `"functional" \| "destructive"`                                          | `functional` |                                                                                                                                                |
+| `asChild`      | `boolean`                                                                | —            | Change the default rendered element for the one passed as a child, merging their props and behaviour. Useful for rendering MenuItem as a link. |
+| `textValue`    | `string`                                                                 | —            | Deprecated override of the text label to use when the item is matched during keyboard text navigation. @deprecated Use `label` instead.        |

package/public/llms/components/modal.md

@@ -104,6 +104,60 @@ on mobile, and ensure the content scrolls correctly.
         Further terms apply see our Residential Products and Services{' '}
         <InlineLink href="#">terms and conditions.</InlineLink>
       </BodyText>
+      <BodyText paragraphSpacing size="md">
+        <Strong>Cheapest variable energy:</Strong> when you take energy and two other eligible
+        bundle services vs standard variable tariffs offered by major suppliers (large and medium
+        suppliers as defined by Ofgem), for sale nationally, excl. existing customer tariffs. Based
+        on Ofgem&apos;s typical domestic usage. Payment by Direct Debit. Correct as of 13/10/2025.
+        Contact us to verify. <InlineLink href="#">See UW terms and conditions.</InlineLink>
+      </BodyText>
+      <BodyText paragraphSpacing size="md">
+        <Strong>UW Price Pledge:</Strong> Eligible new customers (from 22/04/24) who take 3 or more
+        qualifying services and regularly use their Cashback Card. If a customer doesn&apos;t save
+        with UW (incl. Cashback) in their first year vs their previous provider (or cheapest major
+        provider where applicable), they can apply to claim the UW Price Pledge between 12 - 15
+        months after their sign-up date; the pledge & no exit fees only applies to qualifying
+        services taken at sign-up. When you claim, we&apos;ll assume an average Cashback Card saving
+        of £160 a year (based on customer usage data from 03.04.23 to 31.03.24, for users who earned
+        Cashback at least at least once a week, excluding promotional activities) or your actual
+        Cashback saving if higher. Full details, eligibility and terms available{' '}
+        <InlineLink href="#">here.</InlineLink>
+      </BodyText>
+      <BodyText paragraphSpacing size="md">
+        <Strong>£400 to help you switch:</Strong> When you take a 3 or 4+ Service Bundle, we&apos;ll
+        give you credit up to £400 towards any termination fees (excluding Home Insurance) you have
+        to pay your current providers. You&apos;ll need to return any equipment and pay for services
+        you used before you cancel. Additional requirements apply to customers who are tenants.
+        Further terms apply see our Residential Products and Services{' '}
+        <InlineLink href="#">terms and conditions.</InlineLink>
+      </BodyText>
+      <BodyText paragraphSpacing size="md">
+        <Strong>Cheapest variable energy:</Strong> when you take energy and two other eligible
+        bundle services vs standard variable tariffs offered by major suppliers (large and medium
+        suppliers as defined by Ofgem), for sale nationally, excl. existing customer tariffs. Based
+        on Ofgem&apos;s typical domestic usage. Payment by Direct Debit. Correct as of 13/10/2025.
+        Contact us to verify. <InlineLink href="#">See UW terms and conditions.</InlineLink>
+      </BodyText>
+      <BodyText paragraphSpacing size="md">
+        <Strong>UW Price Pledge:</Strong> Eligible new customers (from 22/04/24) who take 3 or more
+        qualifying services and regularly use their Cashback Card. If a customer doesn&apos;t save
+        with UW (incl. Cashback) in their first year vs their previous provider (or cheapest major
+        provider where applicable), they can apply to claim the UW Price Pledge between 12 - 15
+        months after their sign-up date; the pledge & no exit fees only applies to qualifying
+        services taken at sign-up. When you claim, we&apos;ll assume an average Cashback Card saving
+        of £160 a year (based on customer usage data from 03.04.23 to 31.03.24, for users who earned
+        Cashback at least at least once a week, excluding promotional activities) or your actual
+        Cashback saving if higher. Full details, eligibility and terms available{' '}
+        <InlineLink href="#">here.</InlineLink>
+      </BodyText>
+      <BodyText paragraphSpacing size="md">
+        <Strong>£400 to help you switch:</Strong> When you take a 3 or 4+ Service Bundle, we&apos;ll
+        give you credit up to £400 towards any termination fees (excluding Home Insurance) you have
+        to pay your current providers. You&apos;ll need to return any equipment and pay for services
+        you used before you cancel. Additional requirements apply to customers who are tenants.
+        Further terms apply see our Residential Products and Services{' '}
+        <InlineLink href="#">terms and conditions.</InlineLink>
+      </BodyText>
     </ModalContent>
     <ModalFooter>
       <ModalClose>

package/public/llms/components/segmented-control.md

@@ -0,0 +1,295 @@
+# SegmentedControl
+
+Use a Segmented Control to switch between alternative views of closely related content.
+
+- [Usage](#usage)
+- [Sizes](#sizes)
+- [Icons](#icons)
+- [API](#api)
+
+```tsx
+<Flex direction="column" gap="400">
+  <BodyText as="p" size="md" weight="semibold">
+    SM — labels
+  </BodyText>
+  <SegmentedControl defaultValue={['option-1']} size="sm">
+    <SegmentedControlOption value="option-1" label="Label" />
+    <SegmentedControlOption value="option-2" label="Label" />
+    <SegmentedControlOption value="option-3" label="Label" />
+    <SegmentedControlOption value="option-4" label="Label" />
+  </SegmentedControl>
+
+  <BodyText as="p" size="md" weight="semibold">
+    MD — labels
+  </BodyText>
+  <SegmentedControl defaultValue={['option-1']} size="md">
+    <SegmentedControlOption value="option-1" label="Label" />
+    <SegmentedControlOption value="option-2" label="Label" />
+    <SegmentedControlOption value="option-3" label="Label" />
+    <SegmentedControlOption value="option-4" label="Label" />
+  </SegmentedControl>
+
+  <BodyText as="p" size="md" weight="semibold">
+    SM — icons + labels
+  </BodyText>
+  <SegmentedControl defaultValue={['gas']} size="sm">
+    <SegmentedControlOption value="gas" label="Gas" icon={<GasSmallIcon />} />
+    <SegmentedControlOption
+      value="electricity"
+      label="Electricity"
+      icon={<ElectricitySmallIcon />}
+    />
+    <SegmentedControlOption value="mobile" label="Mobile" icon={<MobileSmallIcon />} />
+    <SegmentedControlOption value="broadband" label="Broadband" icon={<BroadbandSmallIcon />} />
+    <SegmentedControlOption value="insurance" label="Insurance" icon={<InsuranceSmallIcon />} />
+    <SegmentedControlOption value="cashback" label="Cashback" icon={<CashbackCardSmallIcon />} />
+  </SegmentedControl>
+
+  <BodyText as="p" size="md" weight="semibold">
+    MD — icons + labels
+  </BodyText>
+  <SegmentedControl defaultValue={['gas']} size="md">
+    <SegmentedControlOption value="gas" label="Gas" icon={<GasMediumIcon />} />
+    <SegmentedControlOption
+      value="electricity"
+      label="Electricity"
+      icon={<ElectricityMediumIcon />}
+    />
+    <SegmentedControlOption value="mobile" label="Mobile" icon={<MobileMediumIcon />} />
+    <SegmentedControlOption value="broadband" label="Broadband" icon={<BroadbandMediumIcon />} />
+    <SegmentedControlOption value="insurance" label="Insurance" icon={<InsuranceMediumIcon />} />
+    <SegmentedControlOption value="cashback" label="Cashback" icon={<CashbackCardMediumIcon />} />
+  </SegmentedControl>
+
+  <BodyText as="p" size="md" weight="semibold">
+    Disabled
+  </BodyText>
+  <SegmentedControl defaultValue={['option-1']} size="sm" disabled>
+    <SegmentedControlOption value="option-1" label="Label" />
+    <SegmentedControlOption value="option-2" label="Label" />
+    <SegmentedControlOption value="option-3" label="Label" />
+  </SegmentedControl>
+
+  <BodyText as="p" size="md" weight="semibold">
+    Per-option disabled
+  </BodyText>
+  <SegmentedControl defaultValue={['option-1']} size="sm">
+    <SegmentedControlOption value="option-1" label="Label" />
+    <SegmentedControlOption value="option-2" label="Label" disabled />
+    <SegmentedControlOption value="option-3" label="Label" />
+  </SegmentedControl>
+</Flex>
+```
+
+## Usage
+
+Wrap `SegmentedControlOption` components in a `SegmentedControl`. Each option requires a unique `value`. Always provide a `defaultValue` — a Segmented Control cannot be used without a selected option.
+
+```tsx
+<SegmentedControl defaultValue={['gas']}>
+  <SegmentedControlOption value="gas" label="Gas" />
+  <SegmentedControlOption value="electricity" label="Electricity" />
+</SegmentedControl>
+```
+
+```tsx
+<SegmentedControl {...args}>
+  <SegmentedControlOption value="option-1" label="Option 1" />
+  <SegmentedControlOption value="option-2" label="Option 2" />
+  <SegmentedControlOption value="option-3" label="Option 3" />
+  <SegmentedControlOption value="option-4" label="Option 4" />
+</SegmentedControl>
+```
+
+## Sizes
+
+Two sizes are available: `sm` (32px, default) and `md` (48px). The `size` prop is responsive and can be used to display different sizes at different breakpoints.
+
+```tsx
+<SegmentedControl size={{ mobile: 'sm', desktop: 'md' }} defaultValue={['gas']}>
+  ...
+</SegmentedControl>
+```
+
+## Icons
+
+Use the `icon` prop to display an icon before the label. Use the Small icon variant with `size="sm"` and the Medium icon variant with `size="md"`. Either add icons to all options or none — do not mix.
+
+```tsx
+<SegmentedControl defaultValue={['gas']} size="sm">
+  <SegmentedControlOption value="gas" label="Gas" icon={<GasSmallIcon />} />
+  <SegmentedControlOption value="electricity" label="Electricity" icon={<ElectricitySmallIcon />} />
+</SegmentedControl>
+```
+
+```tsx
+<Flex direction="column" gap="300" alignItems="start">
+  <SegmentedControl defaultValue={['gas']} size="sm">
+    <SegmentedControlOption value="gas" label="Gas" icon={<GasSmallIcon />} />
+    <SegmentedControlOption
+      value="electricity"
+      label="Electricity"
+      icon={<ElectricitySmallIcon />}
+    />
+    <SegmentedControlOption value="mobile" label="Mobile" icon={<MobileSmallIcon />} />
+    <SegmentedControlOption value="broadband" label="Broadband" icon={<BroadbandSmallIcon />} />
+    <SegmentedControlOption value="insurance" label="Insurance" icon={<InsuranceSmallIcon />} />
+    <SegmentedControlOption value="cashback" label="Cashback" icon={<CashbackCardSmallIcon />} />
+  </SegmentedControl>
+  <SegmentedControl defaultValue={['gas']} size="md">
+    <SegmentedControlOption value="gas" label="Gas" icon={<GasMediumIcon />} />
+    <SegmentedControlOption
+      value="electricity"
+      label="Electricity"
+      icon={<ElectricityMediumIcon />}
+    />
+    <SegmentedControlOption value="mobile" label="Mobile" icon={<MobileMediumIcon />} />
+    <SegmentedControlOption value="broadband" label="Broadband" icon={<BroadbandMediumIcon />} />
+    <SegmentedControlOption value="insurance" label="Insurance" icon={<InsuranceMediumIcon />} />
+    <SegmentedControlOption value="cashback" label="Cashback" icon={<CashbackCardMediumIcon />} />
+  </SegmentedControl>
+</Flex>
+```
+
+### Responsive icon sizes
+
+If you need to render different sized icons in conjunction with the responsive `size` prop, use `Box` with display props to show the appropriate icon at each breakpoint.
+
+```tsx
+import { GasMediumIcon, GasSmallIcon } from '@utilitywarehouse/hearth-react-icons';
+import { Box, SegmentedControl, SegmentedControlOption } from '@utilitywarehouse/hearth-react';
+
+<SegmentedControl defaultValue={['gas']} size={{ mobile: 'sm', desktop: 'md' }}>
+  <SegmentedControlOption
+    value="gas"
+    label="Gas"
+    icon={
+      <>
+        <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+          <GasMediumIcon />
+        </Box>
+        <Box asChild display={{ desktop: 'none' }}>
+          <GasSmallIcon />
+        </Box>
+      </>
+    }
+  />
+</SegmentedControl>;
+```
+
+```tsx
+<SegmentedControl defaultValue={['gas']} size={{ mobile: 'sm', desktop: 'md' }}>
+  <SegmentedControlOption
+    value="gas"
+    label="Gas"
+    icon={
+      <>
+        <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+          <GasMediumIcon />
+        </Box>
+        <Box asChild display={{ desktop: 'none' }}>
+          <GasSmallIcon />
+        </Box>
+      </>
+    }
+  />
+  <SegmentedControlOption
+    value="electricity"
+    label="Electricity"
+    icon={
+      <>
+        <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+          <ElectricityMediumIcon />
+        </Box>
+        <Box asChild display={{ desktop: 'none' }}>
+          <ElectricitySmallIcon />
+        </Box>
+      </>
+    }
+  />
+  <SegmentedControlOption
+    value="mobile"
+    label="Mobile"
+    icon={
+      <>
+        <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+          <MobileMediumIcon />
+        </Box>
+        <Box asChild display={{ desktop: 'none' }}>
+          <MobileSmallIcon />
+        </Box>
+      </>
+    }
+  />
+  <SegmentedControlOption
+    value="broadband"
+    label="Broadband"
+    icon={
+      <>
+        <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+          <BroadbandMediumIcon />
+        </Box>
+        <Box asChild display={{ desktop: 'none' }}>
+          <BroadbandSmallIcon />
+        </Box>
+      </>
+    }
+  />
+  <SegmentedControlOption
+    value="insurance"
+    label="Insurance"
+    icon={
+      <>
+        <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+          <InsuranceMediumIcon />
+        </Box>
+        <Box asChild display={{ desktop: 'none' }}>
+          <InsuranceSmallIcon />
+        </Box>
+      </>
+    }
+  />
+  <SegmentedControlOption
+    value="cashback"
+    label="Cashback"
+    icon={
+      <>
+        <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+          <CashbackCardMediumIcon />
+        </Box>
+        <Box asChild display={{ desktop: 'none' }}>
+          <CashbackCardSmallIcon />
+        </Box>
+      </>
+    }
+  />
+</SegmentedControl>
+```
+
+## API
+
+This component is based on the [Base UI ToggleGroup primitive](https://base-ui.com/react/components/toggle-group)
+and supports the following common props:
+
+- Margin
+
+| Prop            | Type                                                                                                                                                                                                                     | Default | Description                                                                                                                                                      |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`         | `readonly string[]`                                                                                                                                                                                                      | —       | The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of `defaultValue`. |
+| `defaultValue`  | `(readonly string[] & (string \| number \| readonly string[]))`                                                                                                                                                          | —       | The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of `value`.      |
+| `onValueChange` | `((groupValue: string[], eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element \| undefined; }) => void)` | —       | Callback fired when the pressed states of the toggle group changes.                                                                                              |
+| `disabled`      | `boolean`                                                                                                                                                                                                                | `false` | Whether the toggle group should ignore user interaction.                                                                                                         |
+| `size`          | `Responsive<"sm" \| "md">`                                                                                                                                                                                               | `sm`    | Sets the height of the control. `sm` is 32px and `md` is 48px. Accepts a responsive value to display different sizes at different breakpoints.                   |
+
+### SegmentedControlOption API
+
+This component is based on the `button` element.
+
+| Prop              | Type                                                                                                                                                                                                                 | Default | Description                                                                                                                                                                                                                  |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`           | `string`                                                                                                                                                                                                             | —       | The text label displayed inside the option.                                                                                                                                                                                  |
+| `value`           | `string`                                                                                                                                                                                                             | —       | The value that identifies this option within the SegmentedControl.                                                                                                                                                           |
+| `pressed`         | `boolean`                                                                                                                                                                                                            | —       | Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`.                                                                                                                      |
+| `defaultPressed`  | `boolean`                                                                                                                                                                                                            | `false` | Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`.                                                                                                                           |
+| `onPressedChange` | `((pressed: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element \| undefined; }) => void)` | —       | Callback fired when the pressed state is changed.                                                                                                                                                                            |
+| `icon`            | `ReactNode`                                                                                                                                                                                                          | —       | An icon to display before the label. Use the Small icon variant for `size="sm"` and the Medium icon variant for `size="md"`. When using the responsive `size` prop, see the docs for guidance on rendering responsive icons. |

package/public/llms/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Hearth React
 
-Current version: v0.30.1
+Current version: v0.31.0
 
 - [Install Hearth](#install-hearth)
 - [Import CSS](#import-css)

package/public/llms.txt

@@ -72,7 +72,7 @@
 - [Label](llms/components/label.md): ```tsx
 - [Link](llms/components/link.md): Links are used to navigate a user to another page or website, another place on the same page, or to open a link in a new tab.
 - [List](llms/components/list.md): The `List` component is a flexible and customizable component for displaying a
-- [Menu](llms/components/menu.md): Use the `Menu` component to present a short list of actions or options in response to a user’s interaction. Menus are ideal for actions like sorting, filtering, or providing additional options without navigating away from the current screen.
+- [Menu](llms/components/menu.md): Use the `Menu` component to present a short list of actions or options in
 - [Modal](llms/components/modal.md): A `Modal` overlays content to request a decision or inform users of important information. When
 - [Pagination](llms/components/pagination.md): Use the `Pagination` component to help users navigate through multiple pages of content.
 - [PasswordInput](llms/components/password-input.md): `PasswordInput` is an interactive field that is used to securely collect users passwords.
@@ -81,6 +81,7 @@
 - [RadioGroup](llms/components/radio-group.md): `RadioGroup` provides an accessible way to group and control a set of `Radio`, `RadioTile` or `RadioCard` components, allowing the user to select one option from a set. The `RadioGroup` is responsible for handling the value, helper text, validation status and text, as well as determining the presentation and selection of the items in the list. Follows the [WAI-ARIA Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) for radio groups not contained in a toolbar.
 - [SearchInput](llms/components/search-input.md): `SearchInput` allows users to enter a specific keyword or phrase and obtain results related to the context in which it is placed.
 - [SectionHeader](llms/components/section-header.md): Use the `SectionHeader` component to help define and separate content within a
+- [SegmentedControl](llms/components/segmented-control.md): Use a Segmented Control to switch between alternative views of closely related content.
 - [Select](llms/components/select.md): `Select` enables users to select an option from a list of choices, and generally requires a final submit action to confirm the selection.
 - [Skeleton](llms/components/skeleton.md): `Skeleton` is a collection of components that provide visual placeholders while
 - [Spinner](llms/components/spinner.md): Using a Spinner is a common method for indicating that an asynchronous process is ongoing.