@utilitywarehouse/hearth-react 0.28.6 → 0.29.0

package/public/llms/components/spinner.md

@@ -0,0 +1,59 @@
+# Spinner
+
+Using a Spinner is a common method for indicating that an asynchronous process is ongoing.
+
+```tsx
+<Flex gap="600">
+  {sizes.map(size => (
+    <Spinner key={size} size={size} />
+  ))}
+</Flex>
+```
+
+```tsx
+<Spinner size="md" />
+```
+
+## Size
+
+The size prop is responsive, so you can render different sizes at different breakpoints.
+
+```tsx
+<Spinner size={{ mobile: 'sm', tablet: 'md', desktop: 'lg' }} />
+```
+
+## Color
+
+The color prop allows you to set the strok width colour to any of the colour token values.
+
+```tsx
+<Spinner color="uwPurple" />
+```
+
+If you are using the `Spinner` as an element within a parent component, and
+need it to inherit the parent's colour scheme, you can set the `currentColor`
+prop.
+
+```tsx
+<Spinner currentColor />
+```
+
+## API
+
+This component is based on the `div` element and supports the following common props:
+
+- Color
+- Margin
+
+| Prop           | Type                                                                                                                                                                                                       | Default | Description                                                                                                                     |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `size`         | `Responsive<"xs" \| "sm" \| "md" \| "lg">`                                                                                                                                                                 | `md`    | Sets the button height.                                                                                                         |
+| `color`        | `"primary" \| "secondary" \| "brand" \| "inverted"`                                                                                                                                                        | —       | Sets the fill color.                                                                                                            |
+| `currentColor` | `boolean`                                                                                                                                                                                                  | —       | Sets the Spinner stroke colour to `currentColor`. For use when the Spinner needs to inherit a parent component's colour scheme. |
+| `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})`>` | —       |                                                                                                                                 |

package/public/llms/components/strong.md

@@ -0,0 +1,49 @@
+# Strong
+
+The `Strong` component is based on the HTML `strong` element and is used to indicate text that is of
+strong importance, seriousness, or urgency. `Strong` should be wrapped in a `BodyText` component,
+and will inherit its styles from its parent. You can also use this component within the `Heading`
+component, however as `Heading` has only one font-weight there will be no visual distinction, and
+so this is discouraged.
+
+```tsx
+<Flex direction="column" gap="100">
+  {sizes.map(size => (
+    <BodyText key={size} size={size}>
+      The most important thing to remember is, <Strong>stay positive</Strong>.
+    </BodyText>
+  ))}
+</Flex>
+```
+
+## Alternatives
+
+- BodyText - For body text
+- DetailText - For detail text
+- Heading - For heading-level text
+- Em - For emphasis
+
+## API
+
+This component is based on the `strong` element and supports the following common props:
+
+- Margin
+- Text transform
+- Text align
+- Text wrap
+
+| Prop            | Type                                                                                                                                                                                                       | Default | Description                                                                                                                                                                                                                           |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asChild`       | `boolean`                                                                                                                                                                                                  | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.                                                                                                                                  |
+| `truncate`      | `boolean`                                                                                                                                                                                                  | —       | If true, the text will not wrap, but instead will truncate with a text overflow ellipsis. Note that text overflow can only happen with block or inline-block level elements (the element needs to have a width in order to overflow). |
+| `textAlign`     | `Responsive<"center" \| "left" \| "right">`                                                                                                                                                                | —       |                                                                                                                                                                                                                                       |
+| `textTransform` | `"none" \| "uppercase" \| "lowercase" \| "capitalize"`                                                                                                                                                     | —       | Set the text-transform on the component.                                                                                                                                                                                              |
+| `wrap`          | `Responsive<"wrap" \| "nowrap" \| "balance" \| "pretty">`                                                                                                                                                  | —       | DEPRECATED: use `textWrap` instead of `wrap` @deprecated Use `textWrap` instead of `wrap`                                                                                                                                             |
+| `textWrap`      | `Responsive<"wrap" \| "nowrap" \| "balance" \| "pretty">`                                                                                                                                                  | —       |                                                                                                                                                                                                                                       |
+| `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})`>` | —       |                                                                                                                                                                                                                                       |

package/public/llms/components/switch.md

@@ -0,0 +1,106 @@
+# Switch
+
+`Switch` is used to indicate switching between two opposing options. Switches
+allow users to turn an individual option on or off. They are usually used to
+activate or deactivate a specific setting.
+
+```tsx
+<Switch size="sm" label="Switch label" />
+```
+
+## Sizes
+
+The `Switch` component supports two sizes: `sm` (small) and `md` (medium). You
+can control the size using the `size` prop.
+
+```tsx
+<Switch size="sm" />
+<Switch size="md" />
+```
+
+```tsx
+<Flex direction="row" gap="200">
+  {sizes.map(size => (
+    <Switch key={size} {...args} size={size} />
+  ))}
+</Flex>
+```
+
+## Disabled State
+
+The `Switch` can be disabled using the `disabled` prop. When disabled, the
+`Switch` is non-interactive and visually indicates its disabled state.
+
+```tsx
+<Switch disabled />
+<Switch disabled checked />
+```
+
+```tsx
+<Flex direction="row" gap="200">
+  <Switch {...args} />
+  <Switch {...args} checked />
+</Flex>
+```
+
+The disabled `Switch` uses `aria-disabled`, rather than the `disabled`
+attribute, so that they are still focusable when using the keyboard. This means
+that screen readers are still able to find the button, with the insight that it
+is disabled and that there is perhaps an action which needs to be taken, rather
+than not knowing there is a button there at all. The `onClick` handler will be
+disabled, however you will need to make sure you disable any other expected
+actions.
+
+## Responsive Sizes
+
+The `Switch` component supports responsive sizes. You can specify different
+sizes for different breakpoints using a responsive object.
+
+```tsx
+<Switch size={{ mobile: 'sm', desktop: 'md' }} />
+```
+
+### Keyboard Interactions
+
+- **Space**: Toggles the state of the `Switch`.
+- **Tab**: Moves focus to the `Switch`.
+
+### Label
+
+Do not use `Switch` without a label. If you do not use the `label` prop, then
+please make sure you properly label the component for screen reader users.
+
+```tsx
+<Flex direction="column" gap="600">
+  <Flex direction="row" gap="200" alignItems="center">
+    <BodyText as="label" htmlFor="airplane-mode">
+      Airplane mode
+    </BodyText>
+    <Switch id="airplane-mode" {...args} />
+  </Flex>
+  <Switch aria-label="airplane-mode" {...args} />
+</Flex>
+```
+
+## API
+
+This component is based on the `button` element, and supports the following common props:
+
+- Margin
+
+| Prop              | Type                                                                                                                                                                                                       | Default | Description                                       |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- |
+| `label`           | `string`                                                                                                                                                                                                   | —       | The label for the Switch, describing its purpose. |
+| `defaultChecked`  | `boolean`                                                                                                                                                                                                  | —       |                                                   |
+| `asChild`         | `boolean`                                                                                                                                                                                                  | —       |                                                   |
+| `size`            | `Responsive<"sm" \| "md">`                                                                                                                                                                                 | —       |                                                   |
+| `checked`         | `boolean`                                                                                                                                                                                                  | —       |                                                   |
+| `required`        | `boolean`                                                                                                                                                                                                  | —       |                                                   |
+| `onCheckedChange` | `((checked: boolean) => void)`                                                                                                                                                                             | —       |                                                   |
+| `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/table.md

@@ -0,0 +1,230 @@
+# Table
+
+Use a `Table` to arrange data in rows and columns. They are used to communicate relationships between content and to display references, comparisons, and choices.
+
+- [Usage](#usage)
+- [Variants](#variants)
+- [Pagination](#pagination)
+- [Header cells](#header-cells)
+- [API](#api)
+
+```tsx
+<Table {...args}>
+  <TableHeader>
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>Phone</TableHeaderCell>
+    <TableHeaderCell>City</TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    {personalDetails.slice(0, 3).map(person => (
+      <TableRow key={person.id}>
+        <TableCell>{person.name}</TableCell>
+        <TableCell>{person.email}</TableCell>
+        <TableCell>{person.phone}</TableCell>
+        <TableCell>{person.city}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+## Usage
+
+- `Table` groups the `TableHeader` and `TableBody` components, and provides UI variants.
+- `TableHeader` groups table column headers
+- `TableBody` provides the body of the table, grouping table rows.
+- `TableRow` wraps rows of data cells
+- `TableHeaderCell` provides the header cell, which can be used within both `TableHeader` and `TableRow` components.
+- `TableCell` for data cells within a `TableRow`.
+- `TablePagination` provides pagination controls for the table.
+
+## Variants
+
+`Table` supports the following variants, based on the `Card` component:
+
+- `undefined` - No `Card` container, minimal styling
+- `subtle` - Subtle `Card` container
+- `emphasis` - Emphasis `Card` container
+
+```tsx
+<Table variant="subtle">
+  <TableHeader>
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Occupation</TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableHeaderCell row>Toni Morrison</TableCell>
+      <TableCell>Writer</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+```tsx
+<Flex direction="column" gap="600">
+  {variants.map(variant => (
+    <Table key={variant} variant={variant}>
+      <TableHeader>
+        <TableHeaderCell>Name</TableHeaderCell>
+        <TableHeaderCell>Email</TableHeaderCell>
+        <TableHeaderCell>Phone</TableHeaderCell>
+        <TableHeaderCell>City</TableHeaderCell>
+      </TableHeader>
+      <TableBody>
+        {personalDetails.slice(0, 5).map(person => (
+          <TableRow key={person.id}>
+            <TableHeaderCell row>{person.name}</TableHeaderCell>
+            <TableCell>{person.email}</TableCell>
+            <TableCell>{person.phone}</TableCell>
+            <TableCell>{person.city}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  ))}
+</Flex>
+```
+
+## Pagination
+
+Use the `pagination` prop to include pagination.
+
+```tsx
+<Table
+  pagination={
+    <TablePagination
+      currentPage={currentPage}
+      totalPages={totalPages}
+      onPageChange={setCurrentPage}
+    />
+  }
+>
+  <TableHeader>{...}</TableHeader>
+  <TableBody>{...}</TableBody>
+</Table>
+```
+
+```tsx
+<Table
+  {...args}
+  pagination={
+    <TablePagination
+      currentPage={currentPage}
+      totalPages={totalPages}
+      onPageChange={setCurrentPage}
+    />
+  }
+>
+  <TableHeader>
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>Phone</TableHeaderCell>
+    <TableHeaderCell>City</TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    {pageData.map(person => (
+      <TableRow key={person.id}>
+        <TableHeaderCell row>{person.name}</TableHeaderCell>
+        <TableCell>{person.email}</TableCell>
+        <TableCell>{person.phone}</TableCell>
+        <TableCell>{person.city}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+## Header cells
+
+The `TableHeaderCell` component is used for column header cell within the `TableHeader` component.
+
+When the `row` prop is set it can also be used as the first cell in a `TableRow`.
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Occupation</TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableHeaderCell row>Toni Morrison</TableHeaderCell>
+      <TableCell>Writer</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Text Align
+
+You can align the text in both the `TableHeaderCell` and `TableCell` components using the `textAlign` prop.
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableHeaderCell textAlign="left">Name</TableHeaderCell>
+    <TableHeaderCell textAlign="center">Occupation</TableHeaderCell>
+    <TableHeaderCell textAlign="right">Location</TableHeaderCell>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell textAlign="left">Toni Morrison</TableCell>
+      <TableCell textAlign="center">Writer</TableCell>
+      <TableCell textAlign="right">United States</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## API
+
+This component is based on the `table` element and supports the following common props:
+
+- Margin
+
+| Prop           | Type                                                                                                                                                                                                       | Default | Description                                                                                         |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `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})`>` | —       |                                                                                                     |
+| `variant`      | `"emphasis" \| "subtle"`                                                                                                                                                                                   | —       | Sets the visual variant of the table. When undefined, the table is rendered without a Card wrapper. |
+| `pagination`   | `ReactElement<TablePaginationProps, string \| JSXElementConstructor<any>>`                                                                                                                                 | —       |                                                                                                     |
+
+### TableHeader API
+
+This component is based on the `thead` element.
+
+### TableHeaderCell API
+
+This component is based on the `th` element and supports the following common props:
+
+- Text Align
+
+| Prop        | Type                                        | Default | Description |
+| ----------- | ------------------------------------------- | ------- | ----------- |
+| `row`       | `boolean`                                   | —       |             |
+| `textAlign` | `Responsive<"center" \| "left" \| "right">` | —       |             |
+
+### TableBody API
+
+This component is based on the `tbody` element.
+
+### TableRow API
+
+This component is based on the `tr` element.
+
+### TableCell API
+
+This component is based on the `td` element and supports the following common props:
+
+- Text Align
+
+### TablePagination API
+
+This component is based on the `Pagination` component.