@utilitywarehouse/hearth-react 0.28.6 → 0.29.0

package/public/llms/components/alert.md

@@ -0,0 +1,217 @@
+# Alert
+
+The `Alert` component displays a short, important message in a way that
+attracts the user's attention without interrupting the user's task. This
+component should be used to flag information of high importance, whether it be
+an error, warning, success or information.
+
+```tsx
+<Alert
+  colorScheme="info"
+  title="Alert Title"
+  text="This is an example of alert text which can wrap"
+/>
+```
+
+## Color schemes
+
+The `colorScheme` prop controls the visual appearance and semantic meaning of the Alert.
+
+```tsx
+<Flex direction="column" gap="400">
+  <Alert colorScheme="info" title="Information" text="Learn more about our rates." />
+  <Alert colorScheme="positive" title="Success" text="Mobile number updated." />
+  <Alert colorScheme="danger" title="Error" text="Email address already exists." />
+  <Alert colorScheme="warning" title="Warning" text="Payment details needed." />
+</Flex>
+```
+
+## With `AlertIconButton`
+
+Alerts can be made interactive by using the `AlertIconButton` component. This adds a clickable button to the alert with appropriate keyboard navigation.
+
+```tsx
+<Alert colorScheme="blue" title="Clickable Alert" text="This alert has an interactive button.">
+  <AlertIconButton label="Click me" onClick={() => alert('Alert button clicked!')} />
+</Alert>
+```
+
+```tsx
+<Flex direction="column" gap="400" alignItems="start">
+  <Alert
+    colorScheme="info"
+    title="Clickable Alert"
+    text="This entire alert is clickable because it contains an AlertButton."
+  >
+    <AlertIconButton label="Click me" onClick={() => alert('Alert button clicked!')} />
+  </Alert>
+  <Alert
+    colorScheme="positive"
+    title="Custom Button Text"
+    text="This alert has a button and a close button."
+    onClose={() => alert('Closed')}
+  >
+    <AlertIconButton label="Click me" onClick={() => alert('Alert button clicked!')} />
+  </Alert>
+</Flex>
+```
+
+## With `AlertLink`
+
+You can add a link to your alert using the `AlertLink` component. This is useful for directing users to relevant pages or actions.
+
+```tsx
+<Alert
+  colorScheme="info"
+  title="Information"
+  text="This alert contains additional information that might be helpful."
+>
+  <AlertLink href="#example">Learn more</AlertLink>
+</Alert>
+```
+
+If you need to you can also render the `AlertLink` as a `button` element using the `asChild` pattern:
+
+```tsx
+<AlertLink asChild>
+  <button onClick={() => alert('Custom action')}>Custom action as button</button>
+</AlertLink>
+```
+
+```tsx
+<Flex direction="column" gap="400" alignItems="start">
+  <Alert
+    colorScheme="info"
+    title="Information"
+    text="This alert contains additional information that might be helpful."
+  >
+    <AlertLink href="#example">Learn more</AlertLink>
+  </Alert>
+  <Alert
+    colorScheme="warning"
+    title="Warning"
+    text="This is a warning message with just an icon link."
+  >
+    <AlertLink href="#action" />
+  </Alert>
+  <Alert
+    colorScheme="danger"
+    title="Sorry, something went wrong"
+    text={
+      <>
+        If the problem persists, please contact Partner Support on{' '}
+        <InlineLink href="tel:+443337778777" style={{ color: 'inherit' }}>
+          <Strong>0333&nbsp;7778777</Strong>
+        </InlineLink>{' '}
+        (Monday to Friday 09:00-17:30, Saturdays 10:00-13:00).
+      </>
+    }
+  >
+    <AlertLink asChild>
+      <button onClick={() => alert('Custom action')}>Custom action as button</button>
+    </AlertLink>
+  </Alert>
+</Flex>
+```
+
+## Title and Text
+
+`Alert` supports a `title` and `text` prop to provide a clear and concise
+message to users. The `title` is typically used for a brief headline, while the
+`text` provides additional details.
+
+These props are optional as they can be used together or separately, depending
+on the context of the alert. While it is technically possible to provide a
+custom title via the `children` prop, it is generally not recommended as it may
+lead to a broken UI and a poor user experience.
+
+## Dismissable
+
+Alerts can be made dismissable by providing an `onClose` handler. This adds a
+close button that users can click to dismiss the alert.
+The `onClose` handler will be called when the alert is dismissed, allowing you
+to perform any necessary cleanup or state updates. It will not handle the
+actual hiding of the alert, so you will need to manage the visibility state of
+the alert in your component.
+
+```tsx
+<Alert
+  colorScheme="positive"
+  title="Success"
+  text="Your action was completed successfully."
+  onClose={() => console.log('Alert dismissed')}
+/>
+```
+
+```tsx
+<Alert
+  colorScheme="positive"
+  title="Success"
+  text="Your email address has been verified successfully."
+  onClose={() => {}}
+/>
+```
+
+## Accessibility
+
+- Alerts use the `alert` role by default for screen readers
+- `AlertIconButton` components support keyboard navigation
+- Icons are marked as `aria-hidden="true"` to avoid redundant announcements
+- Proper ARIA attributes are applied for live regions
+
+### AlertLink
+
+Use `AlertLink` to add navigational links within alerts.
+
+```tsx
+<Alert title="Information">
+  <BodyText>This alert provides important information.</BodyText>
+  <BodyText>The guide is helpful, you can read it below.</BodyText>
+  <AlertLink href="/guide">Read Guide</AlertLink>
+</Alert>
+```
+
+### AlertIconButton
+
+Use `AlertIconButton` to add interactive buttons to alerts.
+
+```tsx
+<Alert title="Action Required" text="Click the button to continue.">
+  <AlertIconButton label="Continue" onClick={() => handleAction()} />
+</Alert>
+```
+
+## API
+
+This component supports the following common props:
+
+- AlignSelf
+- Margin
+- Flex item
+- Grid item
+
+| Prop              | Type                                                                                                                                                                                                       | Default | Description                            |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------- |
+| `title`           | `string`                                                                                                                                                                                                   | —       | Sets the title of the alert.           |
+| `text`            | `ReactNode`                                                                                                                                                                                                | —       | Sets the text of the alert.            |
+| `colorScheme`     | `"info" \| "positive" \| "danger" \| "warning"`                                                                                                                                                            | `info`  | Sets the colour scheme.                |
+| `onClose`         | `(() => void)`                                                                                                                                                                                             | —       | Sets the onClose handler of the alert. |
+| `margin`          | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                        |
+| `marginTop`       | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                        |
+| `marginRight`     | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                        |
+| `marginBottom`    | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                        |
+| `marginLeft`      | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                        |
+| `marginX`         | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                        |
+| `marginY`         | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                        |
+| `flex`            | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `flexBasis`       | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `flexShrink`      | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `flexGrow`        | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `gridColumnSpan`  | `Responsive<Union<string, "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9" \| "10" \| "11" \| "12">>`                                                                                           | —       |                                        |
+| `gridArea`        | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `gridColumn`      | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `gridColumnStart` | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `gridColumnEnd`   | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `gridRow`         | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `gridRowStart`    | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |
+| `gridRowEnd`      | `Responsive<string>`                                                                                                                                                                                       | —       |                                        |

package/public/llms/components/avatar.md

@@ -0,0 +1,112 @@
+# Avatar
+
+Use `Avatar` to help humanise the product experience by connecting users with the product and to each other.
+
+```tsx
+<Flex direction="row" gap="400">
+  <Flex direction="row" gap="200">
+    <Avatar size="md" />
+    <Avatar size="sm" />
+  </Flex>
+  <Flex direction="row" gap="200">
+    <Avatar size="md" name="Rob Phoenix" />
+    <Avatar size="sm" name="Rob Phoenix" />
+  </Flex>
+  <Flex direction="row" gap="200">
+    <Avatar
+      size="md"
+      src="https://ca.slack-edge.com/T0HR00WDA-UN6U78K0R-afda0a8a2fa7-512"
+      name="Rob Phoenix"
+    />
+    <Avatar
+      size="sm"
+      src="https://ca.slack-edge.com/T0HR00WDA-UN6U78K0R-afda0a8a2fa7-512"
+      name="Rob Phoenix"
+    />
+  </Flex>
+</Flex>
+```
+
+```tsx
+<Avatar />
+```
+
+## Usage
+
+By default `Avatar` will display an icon.
+
+```tsx
+<Avatar />
+```
+
+If a name is passed then `Avatar` will display initials.
+
+```tsx
+<Avatar name="Rob Phoenix" />
+```
+
+If a valid image is passed to the `src` prop, then this will be displayed. When
+doing this you also need to pass the name of the user in the image, to be used
+as an accessible description for the image.
+
+```tsx
+<Avatar src="https://ca.slack-edge.com/T0HR00WDA-UN6U78K0R-afda0a8a2fa7-512" name="Rob Phoenix" />
+```
+
+## Accessibility
+
+When passing a user image to the `src` prop, you must also pass their name to
+the `name` prop so it can be used as an accessible description for the image.
+
+## Image
+
+By default the image will only render when it has loaded. While the image is
+loading, or if there has been an error, the user's initials will be rendered.
+there was an error. If you notice a flash during loading, you can provide a
+`delayMs` prop to delay its rendering so it only renders for those with slower
+connections.
+
+## Name
+
+The `name` prop will be used to generate initials used in the `Avatar`, it will
+also be used for the `alt` text when an image is provided.
+
+## Sizes
+
+The size prop controls the size of the Avatar. This prop is responsive.
+
+```tsx
+<Avatar size={{ mobile: 'sm', desktop: 'md' }} />
+```
+
+```tsx
+<Flex direction="row" gap="200" alignItems="center">
+  <Avatar
+    size={{ mobile: 'sm', desktop: 'md' }}
+    src="https://ca.slack-edge.com/T0HR00WDA-UN6U78K0R-afda0a8a2fa7-512"
+    name="Rob Phoenix"
+  />
+  <Avatar size={{ mobile: 'sm', desktop: 'md' }} name="Rob Phoenix" />
+  <Avatar size={{ mobile: 'sm', desktop: 'md' }} />
+</Flex>
+```
+
+## API
+
+This component is based on the `img` & `span` elements and supports the following common props:
+
+- Margin
+
+| Prop                    | Type                                                                                                                                                                                                       | Default | Description                                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `onLoadingStatusChange` | `((status: ImageLoadingStatus) => void)`                                                                                                                                                                   | —       |                                                                                                     |
+| `delayMs`               | `number`                                                                                                                                                                                                   | —       |                                                                                                     |
+| `name`                  | `string`                                                                                                                                                                                                   | —       | Set the name associated with the avatar, used for creating initials, and an accessible description. |
+| `size`                  | `Responsive<"sm" \| "md">`                                                                                                                                                                                 | `md`    | Sets the avatar size.                                                                               |
+| `margin`                | `Responsive<"0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                                                                                     |
+| `marginTop`             | `Responsive<"0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                                                                                     |
+| `marginRight`           | `Responsive<"0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                                                                                     |
+| `marginBottom`          | `Responsive<"0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                                                                                     |
+| `marginLeft`            | `Responsive<"0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                                                                                     |
+| `marginX`               | `Responsive<"0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                                                                                     |
+| `marginY`               | `Responsive<"0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —       |                                                                                                     |

package/public/llms/components/badge.md

@@ -0,0 +1,158 @@
+# Badge
+
+A `Badge` is a visual label or indicator used to convey status or highlight content. Badges are read-only status indicators or labels and are not interactive.
+
+```tsx
+<Flex direction="column" gap="500">
+  {sizes.map(size => (
+    <Flex key={size} direction="column" gap="200" alignItems="start">
+      {variants.map(variant => (
+        <Flex key={variant} gap="200" justifyContent="center" direction="row">
+          {allVariantColorSchemes.map(colorScheme => (
+            <Badge
+              key={`${size}${variant}${colorScheme}`}
+              variant={variant}
+              colorScheme={colorScheme}
+              size={size}
+            >
+              Badge
+            </Badge>
+          ))}
+          {variant !== 'outline'
+            ? nonOutlineColorSchemes.map(colorScheme => (
+                <Badge
+                  key={`${size}${variant}${colorScheme}`}
+                  variant={variant}
+                  colorScheme={colorScheme}
+                  size={size}
+                >
+                  Badge
+                </Badge>
+              ))
+            : null}
+          {variant === 'subtle'
+            ? subtleOnlyColorSchemes.map(colorScheme => (
+                <Badge
+                  key={`${size}${variant}${colorScheme}`}
+                  variant={variant}
+                  colorScheme={colorScheme}
+                  size={size}
+                >
+                  Badge
+                </Badge>
+              ))
+            : null}
+        </Flex>
+      ))}
+    </Flex>
+  ))}
+</Flex>
+```
+
+```tsx
+<Badge variant="subtle" size="md" colorScheme="info">
+  Badge
+</Badge>
+```
+
+## Variants
+
+The variant prop controls the visual appearance of the Badge.
+
+```tsx
+<Flex gap="200">
+  <Badge variant="subtle">Subtle</Badge>
+  <Badge variant="emphasis">Emphasis</Badge>
+  <Badge variant="outline">Outline</Badge>
+</Flex>
+```
+
+## Sizes
+
+The size prop controls the size of the Badge. This prop is responsive.
+
+```tsx
+<Flex gap="200" alignItems="center">
+  <Badge size="sm">Small</Badge>
+  <Badge size="md">Medium</Badge>
+  <Badge size={{ mobile: 'sm', desktop: 'md' }}>Responsive</Badge>
+</Flex>
+```
+
+## Color schemes
+
+The `colorScheme` prop will change the Badge colours.
+
+```tsx
+<Flex gap="200" wrap="wrap">
+  <Badge colorScheme="info">Info</Badge>
+  <Badge colorScheme="positive">Positive</Badge>
+  <Badge colorScheme="danger">Danger</Badge>
+  <Badge colorScheme="warning">Warning</Badge>
+  <Badge colorScheme="functional">Functional</Badge>
+  <Badge colorScheme="energy">Energy</Badge>
+  <Badge colorScheme="mobile">Mobile</Badge>
+  <Badge colorScheme="broadband">Broadband</Badge>
+</Flex>
+```
+
+## Dead prop combinations
+
+Be aware there are some combinations of `colorScheme` & `variant` that do not work together (ie. `emphasis` &
+`highlight`), and if used will render a button with no colours at all. You will also see a TypeScript error.
+
+## Flat Base
+
+The `flatBase` will remove the `border-bottom-right-radius` and `border-bottom-left-radius`, for use when the badge is positioned on top of another element.
+
+```tsx
+<Box>
+  <Flex justifyContent="end" paddingRight="300" width="400px">
+    <Badge colorScheme="positive" variant="emphasis" size="sm" flatBase>
+      Multi SIM offer
+    </Badge>
+  </Flex>
+  <Card width="400px" height="200px" colorScheme="neutralSubtle" />
+</Box>
+```
+
+## Icons
+
+You can enhance the your badge's meaning by adding a small icon to the
+left. This icon is not an interactive icon button; its purpose is to reinforce
+the meaning of the text.
+
+```tsx
+<Flex gap="200">
+  <Badge colorScheme="positive">
+    <TickSmallIcon />
+    Success
+  </Badge>
+  <Badge colorScheme="danger">
+    <CloseSmallIcon />
+    Unsuccessful
+  </Badge>
+</Flex>
+```
+
+## API
+
+This component is based on the `span` element and supports the following common props:
+
+- Margin
+- Text transform
+
+| Prop            | Type                                                                                                                                                                                                       | Default  | Description                                                                         |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `variant`       | `"emphasis" \| "subtle" \| "outline"`                                                                                                                                                                      | `subtle` | Sets the badges's visual variant                                                    |
+| `size`          | `Responsive<"sm" \| "md">`                                                                                                                                                                                 | `md`     | Sets the badge size.                                                                |
+| `colorScheme`   | `"mobile" \| "info" \| "positive" \| "danger" \| "warning" \| "functional" \| "energy" \| "broadband" \| "insurance" \| "cashback" \| "pig" \| "highlight"`                                                | `info`   | Sets the colour scheme.                                                             |
+| `flatBase`      | `boolean`                                                                                                                                                                                                  | `false`  | Removes the bottom radius, set when the Badge sits directly above another container |
+| `margin`        | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —        |                                                                                     |
+| `marginTop`     | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —        |                                                                                     |
+| `marginRight`   | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —        |                                                                                     |
+| `marginBottom`  | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —        |                                                                                     |
+| `marginLeft`    | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —        |                                                                                     |
+| `marginX`       | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —        |                                                                                     |
+| `marginY`       | `Responsive<"auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000" \| `var(--h-${string})`>` | —        |                                                                                     |
+| `textTransform` | `"none" \| "uppercase" \| "lowercase" \| "capitalize"`                                                                                                                                                     | —        | Set the text-transform on the component.                                            |