@utilitywarehouse/hearth-react 0.28.6 → 0.29.0

package/public/llms/components/icon-container.md

@@ -0,0 +1,247 @@
+# IconContainer
+
+Use the `IconContainer` when using icons that sit within a coloured container.
+
+```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">
+          {otherColorSchemes.map(colorScheme => (
+            <IconContainer
+              key={`${size}${variant}${colorScheme}`}
+              variant={variant}
+              colorScheme={colorScheme}
+              size={size}
+            >
+              {size === 'sm' ? <PlaceholderSmallIcon /> : <PlaceholderMediumIcon />}
+            </IconContainer>
+          ))}
+          {variant === 'subtle'
+            ? subtleOnlyColorSchemes.map(colorScheme => (
+                <IconContainer
+                  key={`${size}${variant}${colorScheme}`}
+                  variant={variant}
+                  colorScheme={colorScheme}
+                  size={size}
+                >
+                  {size === 'sm' ? <PlaceholderSmallIcon /> : <PlaceholderMediumIcon />}
+                </IconContainer>
+              ))
+            : null}
+        </Flex>
+      ))}
+    </Flex>
+  ))}
+</Flex>
+```
+
+```tsx
+<IconContainer {...args}>
+  {args.size === 'sm' ? <PlaceholderSmallIcon /> : <PlaceholderMediumIcon />}
+</IconContainer>
+```
+
+- [Icons](#icons)
+- [Variants](#variants)
+- [Sizes](#sizes)
+- [Color schemes](#color-schemes)
+- [Dead prop combinations](#dead-prop-combinations)
+- [Radius none](#radius-none)
+- [Fill](#fill)
+- [API](#api)
+
+## Icons
+
+The `IconContainer` component is intended to be used with the `@utilitywarehouse/hearth-react-icons` package.
+
+## Variants
+
+The variant prop controls the visual appearance of the Icon container.
+
+```tsx
+<Flex gap="200">
+  {variants.map(variant => (
+    <IconContainer key={variant} variant={variant}>
+      <PlaceholderMediumIcon />
+    </IconContainer>
+  ))}
+</Flex>
+```
+
+## Sizes
+
+The size prop controls the size of the Icon container. This prop is responsive.
+
+```tsx
+<Flex gap="200">
+  {sizes.map(size => (
+    <IconContainer key={size} size={size}>
+      {size === 'sm' ? <PlaceholderSmallIcon /> : <PlaceholderMediumIcon />}
+    </IconContainer>
+  ))}
+</Flex>
+```
+
+If you need to render different sized icons in conjunction with the responsive
+size prop, there are a couple of ways you can do this.
+
+1. Using JS, with the `useMediaQuery` hook.
+
+```tsx
+import { AddMediumIcon, AddSmallIcon } from '@utilitywarehouse/hearth-react-icons';
+import { IconContainer, useMediaQuery, media } from '@utilitywarehouse/hearth-react';
+
+const MyComponent = () => {
+  const showSmallIcon = useMediaQuery(media.below('tablet'));
+
+  return (
+    <IconContainer size={{ mobile: 'sm', tablet: 'md', desktop: 'lg' }}>
+      {showSmallIcon ? <AddSmallIcon /> : <AddMediumIcon />}
+    </IconContainer>
+  );
+};
+```
+
+2. Using CSS, with `Box` and style props.
+
+```tsx
+import { AddMediumIcon, AddSmallIcon } from '@utilitywarehouse/hearth-react-icons';
+import { IconContainer, Box } from '@utilitywarehouse/hearth-react';
+
+const MyComponent = () => (
+  <IconContainer size={{ mobile: 'sm', desktop: 'md' }}>
+    <Box asChild display={{ mobile: 'none', desktop: 'block' }}>
+      <AddMediumIcon />
+    </Box>
+    <Box asChild display={{ desktop: 'none' }}>
+      <AddSmallIcon />
+    </Box>
+  </IconContainer>
+);
+```
+
+## Color schemes
+
+The `colorScheme` prop will change the Icon container colours.
+
+```tsx
+<Flex gap="200">
+  {colorSchemes.map(colorScheme => (
+    <IconContainer key={colorScheme} colorScheme={colorScheme}>
+      <PlaceholderMediumIcon />
+    </IconContainer>
+  ))}
+</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 an icon container with no colours at all. You will also see a TypeScript error.
+
+## Radius none
+
+Use the border radius common props to remove the default `border-radius`, for
+use when the icon container needs to sit flush against the edge of a card.
+
+```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">
+          {otherColorSchemes.map(colorScheme => (
+            <IconContainer
+              key={`${size}${variant}${colorScheme}`}
+              variant={variant}
+              colorScheme={colorScheme}
+              size={size}
+              borderRadius="none"
+            >
+              {size === 'sm' ? <PlaceholderSmallIcon /> : <PlaceholderMediumIcon />}
+            </IconContainer>
+          ))}
+          {variant === 'subtle'
+            ? subtleOnlyColorSchemes.map(colorScheme => (
+                <IconContainer
+                  key={`${size}${variant}${colorScheme}`}
+                  variant={variant}
+                  colorScheme={colorScheme}
+                  size={size}
+                  borderRadius="none"
+                >
+                  {size === 'sm' ? <PlaceholderSmallIcon /> : <PlaceholderMediumIcon />}
+                </IconContainer>
+              ))
+            : null}
+        </Flex>
+      ))}
+    </Flex>
+  ))}
+</Flex>
+```
+
+## Fill
+
+The `fill` prop will remove the `border-radius` and set the size to fill it's
+container. You can also use this in conjuntion with the Border Radius common
+props to inherit the container border-radius as needed.
+
+```tsx
+<Flex direction="row" gap="200">
+  <Card width="200px" height="200px" paddingNone>
+    <IconContainer fill="both" borderRadius="inherit">
+      <PlaceholderSmallIcon />
+    </IconContainer>
+  </Card>
+  <Card width="200px" height="200px" paddingNone>
+    <IconContainer
+      fill="height"
+      borderRadius="none"
+      borderTopLeftRadius="inherit"
+      borderBottomLeftRadius="inherit"
+    >
+      <PlaceholderSmallIcon />
+    </IconContainer>
+  </Card>
+  <Card width="200px" height="200px" paddingNone>
+    <IconContainer
+      fill="width"
+      borderRadius="none"
+      borderTopLeftRadius="inherit"
+      borderTopRightRadius="inherit"
+    >
+      <PlaceholderSmallIcon />
+    </IconContainer>
+  </Card>
+</Flex>
+```
+
+## API
+
+This component is based on the `span` element and supports the following common props:
+
+- Margin
+- Border Radius
+- Size
+
+| Prop                      | Type                                                                                                                                                                                                       | Default  | Description                                                                     |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------- |
+| `size`                    | `Responsive<"sm" \| "md" \| "lg">`                                                                                                                                                                         | `md`     | Sets the container size.                                                        |
+| `variant`                 | `"emphasis" \| "subtle"`                                                                                                                                                                                   | `subtle` | Sets the container's visual variant                                             |
+| `colorScheme`             | `"mobile" \| "energy" \| "broadband" \| "insurance" \| "cashback" \| "pig" \| "highlight"`                                                                                                                 | `pig`    | Sets the colour scheme.                                                         |
+| `fill`                    | `"height" \| "width" \| "both"`                                                                                                                                                                            | —        | Fill the container height, width or both, rather than having a constrained size |
+| `borderRadius`            | `Responsive<"none" \| "inherit">`                                                                                                                                                                          | —        |                                                                                 |
+| `borderTopLeftRadius`     | `Responsive<"none" \| "inherit">`                                                                                                                                                                          | —        |                                                                                 |
+| `borderTopRightRadius`    | `Responsive<"none" \| "inherit">`                                                                                                                                                                          | —        |                                                                                 |
+| `borderBottomRightRadius` | `Responsive<"none" \| "inherit">`                                                                                                                                                                          | —        |                                                                                 |
+| `borderBottomLeftRadius`  | `Responsive<"none" \| "inherit">`                                                                                                                                                                          | —        |                                                                                 |
+| `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/inline-link.md

@@ -0,0 +1,190 @@
+# InlineLink
+
+- [Alternatives](#alternatives)
+- [Semantic HTML](#semantic-html)
+- [Colour](#colour)
+- [Open in new tab](#open-in-new-tab)
+- [Usage with Next.js](#usage-with-next.js)
+- [API](#api)
+
+```tsx
+<Flex
+  direction="column"
+  gap="400"
+  width="500px"
+  padding="400"
+  backgroundColor="primary"
+  alignItems="center"
+  justifyContent="center"
+>
+  <BodyText>
+    <InlineLink {...args} />
+  </BodyText>
+  <BodyText>
+    Agnes Martin was an American <InlineLink>abstract painter</InlineLink> known for her{' '}
+    <InlineLink>minimalist</InlineLink> style. Martin&apos;s art was characterized by serene
+    compositions featuring <InlineLink>grids and lines</InlineLink>. Martin&apos;s minimalist
+    approach conveyed tranquility and <InlineLink>spirituality</InlineLink>, and her paintings often
+    carried positive names reflective of her <InlineLink>philosophy</InlineLink>.
+  </BodyText>
+</Flex>
+```
+
+## Alternatives
+
+- Link - For standalone links
+
+## Semantic HTML
+
+> If it goes somewhere it's a link, if it does something it's a button.
+
+A semantic HTML `a` is rendered by default.
+
+## Colour
+
+You can override the default link colours, setting `color` to `"inverted"` when
+used on brand backgrounds, or to `"inherit"` when the link colours need to
+match the parent text colour.
+
+```tsx
+<Flex
+  direction="column"
+  gap="600"
+  width="500px"
+  backgroundColor="primary"
+  alignItems="center"
+  justifyContent="center"
+>
+  <Flex direction="column" gap="400" backgroundColor="brand" padding="400">
+    <BodyText>
+      <InlineLink {...args} color="inverted">
+        Inverted color
+      </InlineLink>
+    </BodyText>
+    <BodyText color="inverted">
+      Agnes Martin was an American <InlineLink color="inverted">abstract painter</InlineLink> known
+      for her <InlineLink color="inverted">minimalist</InlineLink> style. Martin&apos;s art was
+      characterized by serene compositions featuring{' '}
+      <InlineLink color="inverted">grids and lines</InlineLink>. Martin&apos;s minimalist approach
+      conveyed tranquility and <InlineLink color="inverted">spirituality</InlineLink>, and her
+      paintings often carried positive names reflective of her{' '}
+      <InlineLink color="inverted">philosophy</InlineLink>.
+    </BodyText>
+  </Flex>
+  <Flex direction="column" gap="400" backgroundColor="secondary" padding="400">
+    <BodyText color="primary">
+      <InlineLink {...args} color="inherit">
+        Inherited color
+      </InlineLink>
+    </BodyText>
+    <BodyText color="brand">
+      Agnes Martin was an American <InlineLink color="inherit">abstract painter</InlineLink> known
+      for her <InlineLink color="inherit">minimalist</InlineLink> style. Martin&apos;s art was
+      characterized by serene compositions featuring{' '}
+      <InlineLink color="inherit">grids and lines</InlineLink>. Martin&apos;s minimalist approach
+      conveyed tranquility and <InlineLink color="inherit">spirituality</InlineLink>, and her
+      paintings often carried positive names reflective of her{' '}
+      <InlineLink color="inherit">philosophy</InlineLink>.
+    </BodyText>
+  </Flex>
+</Flex>
+```
+
+## Open in new tab
+
+Avoid using `target=_blank` ([When to use target="\_blank"](https://css-tricks.com/use-target_blank/)).
+
+If you do use it, be aware that [browsers now implicitly set rel=noopener for any "target=\_blank" link](https://mathiasbynens.github.io/rel-noopener/).
+
+An icon will also be added to indicate that the link opens in a new tab or
+window, improving accessibility. You can override this behaviour by setting the
+`hideOpenIcon` prop.
+
+```tsx
+<Flex gap="600">
+  <InlineLink {...args}>Visit help pages</InlineLink>
+  <InlineLink {...args} hideOpenIcon>
+    Go to help
+  </InlineLink>
+</Flex>
+```
+
+### Next.js v13
+
+The Next.js `Link` component behaviour has changed in v13, so that an `<a>` is
+no longer required as a child. You can render the Web UI `InlineLink` component as a
+Next.js `Link` component using `asChild`:
+
+```tsx
+import NextLink from 'next/link';
+import { InlineLink } from '@utilitywarehouse/hearth-react';
+
+[...]
+
+{/* // eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+<InlineLink asChild>
+  <NextLink href={href} onClick={onClick}>
+    {title}
+  </NextLink>
+</InlineLink>
+```
+
+You can also use the `legacyBehavior` prop directly on the Next.js Link component:
+
+```tsx
+import NextLink from 'next/link';
+import { InlineLink } from '@utilitywarehouse/hearth-react';
+
+[...]
+
+<NextLink href={href} passHref onClick={onClick} legacyBehavior>
+  {/* // eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+  <InlineLink>{title}</InlineLink>
+</NextLink>
+```
+
+And if you want to set this behavior globally you can use the following Next.js
+configuration:
+
+```
+{
+  experimental: {
+    newNextLinkBehavior: false
+  }
+}
+```
+
+### Next.js before v13
+
+```tsx
+import NextLink from 'next/link';
+import { InlineLink } from '@utilitywarehouse/hearth-react';
+
+[...]
+
+<NextLink href={href} passHref onClick={onClick}>
+  {/* // eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+  <TextLink>{title}</TextLink>
+</NextLink>
+```
+
+## API
+
+This component is based on the `a` element and supports the following common props:
+
+- Margin
+- Text transform
+
+| Prop            | Type                                                                                                                                                                                                       | Default | Description                                                                                                                                                                                                                                                                                                                     |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color`         | `"default" \| "inverted" \| "inherit"`                                                                                                                                                                     | —       | Sets the color scheme for the InlineLink. - 'default': Uses the standard link color. - 'inverted': Uses a color suitable for dark backgrounds. Use when placing the link on a dark or colored background for better contrast. - 'inherit': Inherits the color from its parent element. Use to match the surrounding text color. |
+| `asChild`       | `boolean`                                                                                                                                                                                                  | —       | Change the default rendered element for the one passed as a child, merging their props and behavior.                                                                                                                                                                                                                            |
+| `hideOpenIcon`  | `boolean`                                                                                                                                                                                                  | —       | Hides the "open in new tab" icon when `target="_blank"` is set.                                                                                                                                                                                                                                                                 |
+| `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.                                                                                                                                                                                                                                                                                        |

package/public/llms/components/label.md

@@ -0,0 +1,28 @@
+# Label
+
+```tsx
+<Label marginTop="300">Label</Label>
+```
+
+## API
+
+This component is based on the `label` element, and supports the following common props:
+
+- Margin
+- Text transform
+
+| Prop                | Type                                                                                                                                                                                                       | Default | Description                                                                                                                                    |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `as`                | `"label" \| "span"`                                                                                                                                                                                        | `label` | Shorthand for changing the default rendered element into a semantically appropriate alternative. Cannot be used in combination with `asChild`. |
+| `variant`           | `"body" \| "heading"`                                                                                                                                                                                      | —       |                                                                                                                                                |
+| `fontWeight`        | `"regular" \| "semibold"`                                                                                                                                                                                  | —       |                                                                                                                                                |
+| `disabled`          | `boolean`                                                                                                                                                                                                  | —       | Set the label appearance to disabled                                                                                                           |
+| `disableUserSelect` | `boolean`                                                                                                                                                                                                  | —       | Make the text unselectable, for use when associated with input elements.                                                                       |
+| `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.                                                                                                       |