@utilitywarehouse/hearth-react 0.28.6 → 0.29.0

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

@@ -0,0 +1,228 @@
+# TextInput
+
+`TextInput` is an interactive field that allows users to enter text and data.
+
+```tsx
+<TextInput {...args} />
+```
+
+- [Alternatives](#alternatives)
+- [Label](#label)
+- [Required](#required)
+- [Disabled and Read-only](#disabled-and-read-only)
+- [Validation](#validation)
+- [Prefix and Suffix](#prefix-and-suffix)
+- [Grouping inputs](#grouping-inputs)
+- [API](#api)
+
+## Alternatives
+
+- PasswordInput - For entering
+  passwords
+- SearchInput - For search
+- CurrencyInput - For money
+- VerificationInput - For one-time
+  passwords
+- DateInput - For entering dates
+
+## Label
+
+A label is required, this should be clear and descriptive to guide the user.
+
+The `hideLabel` prop will visually hide the label but keep it available for screen readers.
+
+## Required
+
+In it's default state the `TextInput` is optional, and is indicated as such
+with the `(optional)` text following the label.
+
+When using online forms, most users assume all fields are required by default,
+so the `TextInput` draws attention to when it is optional. Please make sure
+that when the input field is required for successful completion of the form,
+that you apply the `required` prop and appropriate validation is included.
+
+You may also need to set the `novalidate` attribute to prevent the browser from
+displaying its own validation errors.
+
+## Disabled and Read-only
+
+Read-only inputs cannot be edited, but remain focusable, and should only be
+used when presenting already submitted information. They differ from
+disabled inputs, as there may be actions a user can take to activate a disabled
+input, but read-only fields should stay undeditable in the same view.
+
+```tsx
+<Flex direction="column" gap="400">
+  <TextInput {...args} label="Disabled" disabled helperText="Please do something before this" />
+  <TextInput
+    {...args}
+    label="Read only"
+    readOnly
+    value="Uneditable previously provided information"
+  />
+</Flex>
+```
+
+## Validation
+
+The input `validationStatus` can be set to either `"valid"` or `"invalid"` to
+indicate the status. This status must be accompanied by the `validationText` to
+explain the reason for the status.
+
+```tsx
+<Flex direction="column" gap="400">
+  <TextInput
+    {...args}
+    label="Email"
+    type="email"
+    defaultValue="rphoenix@uw.co.uk"
+    validationStatus="valid"
+    validationText="Valid email address"
+    required
+  />
+  <TextInput
+    {...args}
+    label="Email"
+    type="email"
+    defaultValue="rphoenix@geemail."
+    validationStatus="invalid"
+    validationText="Please enter a valid email address"
+    required
+  />
+</Flex>
+```
+
+You can set the `validationText` according to what the `validationStatus` is:
+
+```tsx
+const validationStatus = isValid ? "valid" : isInvalid ? "invalid" : undefined
+const validationText = isValid ? "Your input is valid" : isInvalid ? "Your input is invalid" : undefined
+
+[...]
+
+<TextInput
+  label="Name"
+  required
+  validationStatus={validationStatus}
+  validationText={validationText}
+/>
+```
+
+Be aware that you probably want to set `noValidate` on your form to prevent
+the browser from displaying its own validation messages.
+
+```tsx
+<form noValidate>
+  <TextInput
+    label="Name"
+    required
+    validationStatus="invalid"
+    validationText="Please enter your name"
+  />
+</form>
+```
+
+## Prefix and Suffix
+
+To include a prefix or suffix in the `TextInput` you need to wrap the content
+in the `InputSlot` component. You can then set the `placement` prop on the
+`InputSlot` component to display it as either a `prefix` or a `suffix`.
+
+```tsx
+<Flex direction="column" gap="400">
+  <TextInput {...args}>
+    <InputSlot placement="prefix">
+      <BodyText size="md" weight="semibold">
+        £
+      </BodyText>
+    </InputSlot>
+  </TextInput>
+  <TextInput {...args}>
+    <InputSlot placement="suffix">
+      <BodyText size="md" weight="semibold">
+        kWh
+      </BodyText>
+    </InputSlot>
+  </TextInput>
+</Flex>
+```
+
+You can do the same with icons.
+
+```tsx
+<TextInput {...args}>
+  <InputSlot placement="prefix">
+    <EmailMediumIcon />
+  </InputSlot>
+</TextInput>
+```
+
+## Grouping inputs
+
+When grouping inputs you should
+[use the `fieldset` and `legend` elements](https://accessibility.blog.gov.uk/2016/07/22/using-the-fieldset-and-legend-elements/).
+This will ensure the group title is properly associated with child input
+elements. Make sure you place the `legend` element as the first child of the
+`fieldset` otherwise the relationship is broken. If this is not possible, you
+can use `aria-label` or `aria-labelledby` to create the relationship.
+
+If you are also including supporting text, then this should be associated with
+each individual input, rather than with the grouping fieldset.
+
+Please take the time to test what you build with a screen reader.
+
+```tsx
+<Flex asChild direction="column">
+  <fieldset>
+    <legend>
+      <Heading as="h3" size="lg" marginBottom="200">
+        Grouping Inputs
+      </Heading>
+    </legend>
+    <BodyText size="md" marginBottom="250" id="supporting-info">
+      Supporting information
+    </BodyText>
+    <Card variant="subtle" direction="column" gap="250">
+      <TextInput label="First name" required aria-describedby="supporting-info" />
+      <TextInput label="Last name" required aria-describedby="supporting-info" />
+      <TextInput
+        label="Email"
+        helperText="this is the helper text"
+        aria-describedby="supporting-info"
+      >
+        <InputSlot placement="prefix">
+          <EmailMediumIcon />
+        </InputSlot>
+      </TextInput>
+    </Card>
+  </fieldset>
+</Flex>
+```
+
+## API
+
+This component is based on the `input` element and supports the following common props:
+
+- Margin
+
+| Prop               | Type                                                                                                                                                                                                       | Default | Description                                                                 |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------- |
+| `label`            | `string`                                                                                                                                                                                                   | —       | The label for the form field, describing its purpose.                       |
+| `defaultValue`     | `string \| number`                                                                                                                                                                                         | —       | The initial value of the input when rendered.                               |
+| `type`             | `"number" \| "search" \| "text" \| "email" \| "password" \| "tel" \| "url"`                                                                                                                                | —       |                                                                             |
+| `value`            | `string \| number`                                                                                                                                                                                         | —       | The controlled value of the input. Must be used with an `onChange` handler. |
+| `labelId`          | `string`                                                                                                                                                                                                   | —       |                                                                             |
+| `helperTextId`     | `string`                                                                                                                                                                                                   | —       |                                                                             |
+| `validationTextId` | `string`                                                                                                                                                                                                   | —       |                                                                             |
+| `hideLabel`        | `boolean`                                                                                                                                                                                                  | —       | Visually hide the label.                                                    |
+| `labelVariant`     | `"body" \| "heading"`                                                                                                                                                                                      | —       | Change the label variant                                                    |
+| `helperText`       | `string`                                                                                                                                                                                                   | —       | Optional helper text to provide additional context or instructions.         |
+| `validationText`   | `string`                                                                                                                                                                                                   | —       | Text to display when the `validationStatus` is set.                         |
+| `validationStatus` | `"valid" \| "invalid"`                                                                                                                                                                                     | —       | Indicates the validation status.                                            |
+| `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/toast.md

@@ -0,0 +1,323 @@
+# Toast
+
+A `Toast` is a brief, non-intrusive message that appears temporarily to provide feedback on an action or notify users of important information. Toasts automatically dismiss after a set duration or can be dismissed manually.
+
+- [Usage](#usage)
+- [Icon](#icon)
+- [Dismiss toast](#dismiss-toast)
+- [Actions](#actions)
+- [Custom duration](#custom-duration)
+- [Accessibility](#accessibility)
+  - [Sensitivity](#sensitivity)
+  - [Keyboard interactions](#keyboard-interactions)
+- [Duplicate toasts](#duplicate-toasts)
+- [API](#api)
+
+```tsx
+<div>
+  <Button
+    onClick={() => {
+      setOpen(false);
+      window.clearTimeout(timerRef.current);
+      timerRef.current = window.setTimeout(() => {
+        setOpen(true);
+      }, 100);
+    }}
+  >
+    Show Toast
+  </Button>
+  <Toast open={open} onOpenChange={setOpen} icon={<TickCircleMediumIcon />} {...args}>
+    <ToastActionLink href="#" altText="Visit #">
+      Link
+    </ToastActionLink>
+  </Toast>
+</div>
+```
+
+## Usage
+
+When using toasts you must first wrap your usage in a provider. It usually
+makes sense to do this at the root of the application.
+
+```tsx
+import { ToastProvider } from '@utilitywarehouse/hearth-react';
+
+[...]
+
+<ToastProvider>
+  {children}
+</ToastProvider>
+```
+
+You can then render your toast:
+
+```tsx
+<Toast description="Toast description" />
+```
+
+## Icon
+
+Include an icon using the `icon` prop:
+
+```tsx
+import { Toast } from '@utilitywarehouse/hearth-react';
+import { TickCircleMediumIcon } from '@utilitywarehouse/hearth-react-icons';
+
+[...]
+
+<Toast
+  description='With icon'
+  icon={<TickCircleMediumIcon />}
+/>
+```
+
+## Dismiss toast
+
+A dismiss button can be included.
+
+```tsx
+<Toast description="Show dismiss button" showDismissButton />
+```
+
+Users can also swipe down on any toast to dismiss it immediately.
+
+## Actions
+
+You can include an `action` using the `ToastActionLink` or `ToastActionButton`
+components as children. Only use one per toast.
+
+The action should be safe to ignore so that users are not expected to complete
+tasks with unexpected side effects as a result of a time limit. You can direct
+the user to a permanent place in your application where they can action it. Use
+foreground type to announce immediately and increase the duration to give the
+user ample time.
+
+When obtaining a user response is necessary, consider using an `Alert` instead.
+
+```tsx
+<Toast
+  type="foreground"
+  duration={10000}
+  description="You can change your details anytime"
+>
+  <ToastActionLink
+    href="/account-settings"
+    altText="Visit account settings to change your details"
+  >
+    Account settings
+  </ToastActionLink>
+</Toast>
+
+[...]
+
+<Toast
+  type="foreground"
+  duration={10000}
+  description="Settings updated"
+>
+  <ToastActionButton altText="Go to settings to undo">Undo</ToastActionButton>
+</Toast>
+```
+
+```tsx
+<div>
+  <Flex gap="400">
+    <Button
+      onClick={() => {
+        setOpenLinkActionToast(false);
+        window.clearTimeout(linkActionTimerRef.current);
+        linkActionTimerRef.current = window.setTimeout(() => {
+          setOpenLinkActionToast(true);
+        }, 100);
+      }}
+    >
+      Show Link Action Toast
+    </Button>
+    <Button
+      onClick={() => {
+        setOpenButtonActionToast(false);
+        window.clearTimeout(buttonActionTimerRef.current);
+        buttonActionTimerRef.current = window.setTimeout(() => {
+          setOpenButtonActionToast(true);
+        }, 100);
+      }}
+    >
+      Show Button Action Toast
+    </Button>
+  </Flex>
+  <Toast
+    type="foreground"
+    duration={10000}
+    description="You can change your details anytime"
+    open={openLinkActionToast}
+    onOpenChange={setOpenLinkActionToast}
+  >
+    <ToastActionLink
+      href="/account-settings"
+      altText="Visit account settings to change your details"
+    >
+      Account settings
+    </ToastActionLink>
+  </Toast>
+  <Toast
+    type="foreground"
+    duration={10000}
+    description="Settings updated"
+    open={openButtonActionToast}
+    onOpenChange={setOpenButtonActionToast}
+  >
+    <ToastActionButton altText="Go to settings to undo">Undo</ToastActionButton>
+  </Toast>
+</div>
+```
+
+## Custom duration
+
+The default duration of 5 seconds is set on the `ToastProvider`, you
+can override this on the provider, or setting this on the individual toast will
+override the global default.
+
+```tsx
+<Toast duration={10000} description="Custom toast duration of 10 seconds" />
+```
+
+## Accessibility
+
+Adheres to the [aria-live requirements](https://www.w3.org/TR/wai-aria/#aria-live)
+
+### Sensitivity
+
+You can control the sensitivity of the toast for screen readers, using the `type` prop.
+
+For toasts that are the result of a user action, choose `foreground`. Toasts
+generated from background tasks should use `background`. The default type is
+`foreground`.
+
+Foreground toasts are announced immediately. Assistive technologies may choose
+to clear previously queued messages when a foreground toast appears. Try to
+avoid stacking distinct foreground toasts at the same time.
+
+Background toasts are announced at the next graceful opportunity, for example,
+when the screen reader has finished reading its current sentence. They do not
+clear queued messages so overusing them can be perceived as a laggy user
+experience for screen reader users when used in response to a user interaction.
+
+### Keyboard interactions
+
+<Flex direction="column" gap="200" className="sb-unstyled">
+  <Flex>
+    <Box width="300px">
+      <BodyText as="span" weight="bold">
+        Key
+      </BodyText>
+    </Box>
+    <BodyText as="span" weight="bold">
+      Description
+    </BodyText>
+  </Flex>
+  <Divider />
+  {[
+    {
+      key: 'F8',
+      description: 'Focuses toasts viewport.',
+    },
+    {
+      key: 'Tab',
+      description: 'Moves focus to the next focusable element.',
+    },
+    {
+      key: 'Shift+Tab',
+      description: 'Moves focus to the previous focusable element.',
+    },
+    {
+      key: 'Space',
+      description:
+        'When focus is on a Toast action component or the Toast dismiss button, closes the toast.',
+    },
+    {
+      key: 'Enter',
+      description:
+        'When focus is on a Toast action component or the Toast dismiss button, closes the toast.',
+    },
+    {
+      key: 'Esc',
+      description: 'When focus is on a Toast, closes the toast.',
+    },
+  ].map((kbi, i) => (
+    <>
+      <Flex>
+        <Box width="300px">
+          <kbd>{kbi.key}</kbd>
+        </Box>
+        <BodyText as="span">{kbi.description}</BodyText>
+      </Flex>
+      {i < 5 ? <Divider /> : null}
+    </>
+  ))}
+</Flex>
+
+## Duplicate toasts
+
+When a toast must appear every time a user clicks a button, use state to render
+multiple instances of the same toast. Toasts will stack vertically with the
+newest appearing at the bottom.
+
+```tsx
+const [savedCount, setSavedCount] = React.useState(0);
+
+return (
+  <div>
+    <Button onClick={() => setSavedCount(count => count + 1)}>Save</Button>
+
+    {Array.from({ length: savedCount }).map((_, index) => (
+      <Toast key={index} description={`Saved! (${index})`} showDismissButton />
+    ))}
+  </div>
+);
+```
+
+### ToastProvider
+
+This component is based on [Radix UI's Toast primitive](https://www.radix-ui.com/primitives/docs/components/toast).
+
+| Prop             | Type       | Default | Description                                                                                                                                      |
+| ---------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `viewportLabel`  | `string`   | —       |                                                                                                                                                  |
+| `viewportHotkey` | `string[]` | —       |                                                                                                                                                  |
+| `label`          | `string`   | —       | An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast. @defaultValue 'Notification' |
+| `duration`       | `number`   | `5000`  | Time in milliseconds that each toast should remain visible for. @defaultValue 5000                                                               |
+
+### Toast
+
+This component is based on [Radix UI's Toast primitive](https://www.radix-ui.com/primitives/docs/components/toast).
+
+| Prop                | Type                               | Default | Description                                                                                          |
+| ------------------- | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `open`              | `boolean`                          | —       |                                                                                                      |
+| `onPause`           | `(() => void)`                     | —       |                                                                                                      |
+| `type`              | `"foreground" \| "background"`     | —       |                                                                                                      |
+| `duration`          | `number`                           | —       | Time in milliseconds that toast should remain visible for. Overrides value given to `ToastProvider`. |
+| `onEscapeKeyDown`   | `((event: KeyboardEvent) => void)` | —       |                                                                                                      |
+| `onResume`          | `(() => void)`                     | —       |                                                                                                      |
+| `onSwipeStart`      | `((event: SwipeEvent) => void)`    | —       |                                                                                                      |
+| `onSwipeMove`       | `((event: SwipeEvent) => void)`    | —       |                                                                                                      |
+| `onSwipeCancel`     | `((event: SwipeEvent) => void)`    | —       |                                                                                                      |
+| `onSwipeEnd`        | `((event: SwipeEvent) => void)`    | —       |                                                                                                      |
+| `defaultOpen`       | `boolean`                          | —       |                                                                                                      |
+| `onOpenChange`      | `((open: boolean) => void)`        | —       |                                                                                                      |
+| `description`       | `ReactNode`                        | —       |                                                                                                      |
+| `icon`              | `ReactNode`                        | —       |                                                                                                      |
+| `showDismissButton` | `boolean`                          | —       |                                                                                                      |
+
+### ToastActionLink
+
+This component is based on the `a` element and [Radix UI's Toast primitive](https://www.radix-ui.com/primitives/docs/components/toast).
+
+| Prop      | Type      | Default | Description                                                                                                                                                                                                                                                                                                     |
+| --------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asChild` | `boolean` | —       |                                                                                                                                                                                                                                                                                                                 |
+| `altText` | `string`  | —       | A short description for an alternate way to carry out the action. For screen reader users who will not be able to navigate to the button easily/quickly. @example <ToastAction altText="Goto account settings to upgrade">Upgrade</ToastAction> @example <ToastAction altText="Undo (Alt+U)">Undo</ToastAction> |
+
+### ToastActionButton
+
+This component is based on the `button` element and [Radix UI's Toast primitive](https://www.radix-ui.com/primitives/docs/components/toast).