@utilitywarehouse/hearth-react 0.28.6 → 0.29.0

package/public/llms/components/tabs.md

@@ -0,0 +1,320 @@
+# Tabs
+
+Use Tabs to organize and navigate between content sections within the same context without leaving the page.
+
+- [Usage](#usage)
+- [Examples](#examples)
+  - [Controlled](#controlled)
+  - [Overflow & Scrolling](#overflow--scrolling)
+  - [With icons](#with-icons)
+- [Size variants](#size-variants)
+- [Activation mode](#activation-mode)
+- [Accessibility](#accessibility)
+- [API](#api)
+
+```tsx
+<Tabs {...args}>
+  <TabsList>
+    <Tab value="account">Account</Tab>
+    <Tab value="security">Security</Tab>
+    <Tab value="billing">Billing</Tab>
+  </TabsList>
+  <TabContent value="account">
+    <BodyText>Manage your personal details and preferences.</BodyText>
+  </TabContent>
+  <TabContent value="security">
+    <BodyText>Update your password and security settings.</BodyText>
+  </TabContent>
+  <TabContent value="billing">
+    <BodyText>View invoices and update payment methods.</BodyText>
+  </TabContent>
+</Tabs>
+```
+
+## Usage
+
+Use Tabs to organize and navigate between content sections within the same page context.
+
+```tsx
+import { Tabs, TabsList, Tab, TabContent } from '@utilitywarehouse/hearth-react';
+
+<Tabs defaultValue="account">
+  <TabsList>
+    <Tab value="account">Account</Tab>
+    <Tab value="security">Security</Tab>
+    <Tab value="billing">Billing</Tab>
+  </TabsList>
+  <TabContent value="account">Account content</TabContent>
+  <TabContent value="security">Security content</TabContent>
+  <TabContent value="billing">Billing content</TabContent>
+</Tabs>;
+```
+
+### Spacing
+
+The `spacing` prop on the `Tabs` component controls the space between the `TabsList` and the `TabContent`.
+It is set to `"xl"` by default, and can be overridden as needed.
+
+```tsx
+<Tabs defaultValue="account" spacing="lg">
+  <TabsList>
+    <Tab value="account">Account</Tab>
+    <Tab value="security">Security</Tab>
+    <Tab value="billing">Billing</Tab>
+  </TabsList>
+  <TabContent value="account">Account content</TabContent>
+  <TabContent value="security">Security content</TabContent>
+  <TabContent value="billing">Billing content</TabContent>
+</Tabs>
+```
+
+## Controlled
+
+Tabs can be controlled by passing `value` and `onValueChange` to the `Tabs` root.
+
+```tsx
+const [tab, setTab] = useState('account');
+<Tabs value={tab} onValueChange={setTab}>
+  <TabsList>
+    <Tab value="account">Account</Tab>
+    <Tab value="billing">Billing</Tab>
+    <Tab value="usage">Usage</Tab>
+  </TabsList>
+  <TabContent value="account">Account content</TabContent>
+  <TabContent value="billing">Billing content</TabContent>
+  <TabContent value="usage">Usage metrics content</TabContent>
+</Tabs>;
+```
+
+```tsx
+<Flex direction="row" gap="400" alignItems="center">
+  <Tabs value={value} onValueChange={setValue}>
+    <TabsList>
+      <Tab value="account">Account</Tab>
+      <Tab value="billing">Billing</Tab>
+      <Tab value="usage">Usage</Tab>
+    </TabsList>
+    <TabContent value="account">
+      <BodyText>Account content</BodyText>
+    </TabContent>
+    <TabContent value="billing">
+      <BodyText>Billing content</BodyText>
+    </TabContent>
+    <TabContent value="usage">
+      <BodyText>Usage metrics content</BodyText>
+    </TabContent>
+  </Tabs>
+  <Button onClick={next}>Next Tab</Button>
+</Flex>
+```
+
+## Overflow & Scrolling
+
+When tab labels exceed the available width, the list becomes horizontally
+scrollable. Contextual scroll buttons appear only when further scrolling is
+possible.
+
+```tsx
+<Tabs defaultValue="one">
+  <TabsList>
+    <Tab value="one">One</Tab>
+    <Tab value="two">Two</Tab>
+    <Tab value="three">Three</Tab>
+    <Tab value="four">Four</Tab>
+    <Tab value="five">Five</Tab>
+    <Tab value="six">Six</Tab>
+    <Tab value="seven">Seven</Tab>
+    <Tab value="eight">Eight</Tab>
+    <Tab value="nine">Nine</Tab>
+    <Tab value="ten">Ten</Tab>
+    <Tab value="eleven">Eleven</Tab>
+    <Tab value="twelve">Twelve</Tab>
+    <Tab value="thirteen">Thirteen</Tab>
+    <Tab value="fourteen">Fourteen</Tab>
+    <Tab value="fifteen">Fifteen</Tab>
+    <Tab value="sixteen">Sixteen</Tab>
+    <Tab value="seventeen">Seventeen</Tab>
+    <Tab value="eighteen">Eighteen</Tab>
+    <Tab value="nineteen">Nineteen</Tab>
+    <Tab value="twenty">Twenty</Tab>
+  </TabsList>
+  <TabContent value="one">
+    <BodyText>One panel</BodyText>
+  </TabContent>
+  <TabContent value="two">
+    <BodyText>Two panel</BodyText>
+  </TabContent>
+  <TabContent value="three">
+    <BodyText>Three panel</BodyText>
+  </TabContent>
+  <TabContent value="four">
+    <BodyText>Four panel</BodyText>
+  </TabContent>
+  <TabContent value="five">
+    <BodyText>Five panel</BodyText>
+  </TabContent>
+  <TabContent value="six">
+    <BodyText>Six panel</BodyText>
+  </TabContent>
+  <TabContent value="seven">
+    <BodyText>Seven panel</BodyText>
+  </TabContent>
+  <TabContent value="eight">
+    <BodyText>Eight panel</BodyText>
+  </TabContent>
+  <TabContent value="nine">
+    <BodyText>Nine panel</BodyText>
+  </TabContent>
+  <TabContent value="ten">
+    <BodyText>Ten panel</BodyText>
+  </TabContent>
+  <TabContent value="eleven">
+    <BodyText>Eleven panel</BodyText>
+  </TabContent>
+  <TabContent value="twelve">
+    <BodyText>Twelve panel</BodyText>
+  </TabContent>
+  <TabContent value="thirteen">
+    <BodyText>Thirteen panel</BodyText>
+  </TabContent>
+  <TabContent value="fourteen">
+    <BodyText>Fourteen panel</BodyText>
+  </TabContent>
+  <TabContent value="fifteen">
+    <BodyText>Fifteen panel</BodyText>
+  </TabContent>
+  <TabContent value="sixteen">
+    <BodyText>Sixteen panel</BodyText>
+  </TabContent>
+  <TabContent value="seventeen">
+    <BodyText>Seventeen panel</BodyText>
+  </TabContent>
+  <TabContent value="eighteen">
+    <BodyText>Eighteen panel</BodyText>
+  </TabContent>
+  <TabContent value="nineteen">
+    <BodyText>Nineteen panel</BodyText>
+  </TabContent>
+  <TabContent value="twenty">
+    <BodyText>Twenty panel</BodyText>
+  </TabContent>
+</Tabs>
+```
+
+### With icons
+
+You can include icons directly as children inside a `Tab`.
+
+```tsx
+<Tabs defaultValue="one">
+  <TabsList>
+    <Tab value="one">
+      <ElectricityMediumIcon /> Energy
+    </Tab>
+    <Tab value="two">
+      <BroadbandMediumIcon /> Broadband
+    </Tab>
+    <Tab value="three">
+      <MobileMediumIcon /> Mobile
+    </Tab>
+    <Tab value="four">
+      <InsuranceMediumIcon /> Insurance
+    </Tab>
+  </TabsList>
+  <TabContent value="one">
+    <BodyText>One panel</BodyText>
+  </TabContent>
+  <TabContent value="two">
+    <BodyText>Two panel</BodyText>
+  </TabContent>
+  <TabContent value="three">
+    <BodyText>Three panel</BodyText>
+  </TabContent>
+  <TabContent value="four">
+    <BodyText>Four panel</BodyText>
+  </TabContent>
+</Tabs>
+```
+
+## Size variants
+
+```tsx
+<Flex direction="column" gap="400">
+  <Tabs size="md" defaultValue="a">
+    <TabsList>
+      <Tab value="a">Medium A</Tab>
+      <Tab value="b">Medium B</Tab>
+      <Tab value="c">Medium C</Tab>
+    </TabsList>
+    <TabContent value="a">
+      <BodyText>Medium A panel</BodyText>
+    </TabContent>
+    <TabContent value="b">
+      <BodyText>Medium B panel</BodyText>
+    </TabContent>
+    <TabContent value="c">
+      <BodyText>Medium C panel</BodyText>
+    </TabContent>
+  </Tabs>
+
+  <Tabs size="lg" defaultValue="a">
+    <TabsList>
+      <Tab value="a">Large A</Tab>
+      <Tab value="b">Large B</Tab>
+      <Tab value="c">Large C</Tab>
+    </TabsList>
+    <TabContent value="a">
+      <BodyText>Large A panel</BodyText>
+    </TabContent>
+    <TabContent value="b">
+      <BodyText>Large B panel</BodyText>
+    </TabContent>
+    <TabContent value="c">
+      <BodyText>Large C panel</BodyText>
+    </TabContent>
+  </Tabs>
+</Flex>
+```
+
+## Activation mode
+
+The `activationMode` prop controls how keyboard focus activates a tab:
+
+- `automatic` (default): arrow keys both move focus and select the focused tab.
+- `manual`: arrow keys move focus between tabs; selection changes when you press <kbd>Space</kbd> or <kbd>Enter</kbd>.
+
+```tsx
+<Tabs defaultValue="a" activationMode="manual">
+  ...
+</Tabs>
+```
+
+### Performance considerations
+
+The default `automatic` mode provides the best user experience for most cases.
+However, **use `manual` mode when tab panels contain heavily loaded content**
+that might cause lag during automatic activation. This prevents automatic panel
+switching as users navigate with arrow keys, avoiding performance issues.
+
+**Prefetching panel data is the preferred solution** over relying on manual
+activation mode. Consider preloading content for adjacent tabs to provide a
+smooth experience while maintaining the benefits of automatic activation.
+
+## Accessibility
+
+- The `Tabs` root provides the `tablist` role; each `Tab` is a `tab`; each `TabContent` is a `tabpanel`.
+- Selection is communicated via ARIA attributes and `data-state` provided by the underlying primitives.
+- The animated indicator respects the user's reduced motion preferences.
+- Overflow scroll buttons are hidden from assistive technologies and only render when scrolling is possible.
+- Provide concise, descriptive tab labels; avoid relying on icons alone.
+
+### Tabs
+
+| Prop             | Type                                                               | Default | Description                                                |
+| ---------------- | ------------------------------------------------------------------ | ------- | ---------------------------------------------------------- |
+| `defaultValue`   | `string`                                                           | —       | The value of the tab to select by default, if uncontrolled |
+| `value`          | `string`                                                           | —       | The value for the selected tab, if controlled              |
+| `onValueChange`  | `((value: string) => void)`                                        | —       | A function called when a new tab is selected               |
+| `activationMode` | `"manual" \| "automatic"`                                          | —       | Activation mode for tabs                                   |
+| `size`           | `Responsive<"md" \| "lg">`                                         | —       | Size variant                                               |
+| `spacing`        | `"none" \| "md" \| "lg" \| "2xs" \| "xs" \| "sm" \| "xl" \| "2xl"` | —       |                                                            |

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

@@ -0,0 +1,141 @@
+# TextArea
+
+`TextArea` is a multi-line text input field that allows users to enter longer text content.
+
+```tsx
+<TextArea {...args} />
+```
+
+- [Label](#label)
+- [Helper Text](#helper-text)
+- [Validation](#validation)
+- [Disabled and Read-only](#disabled-and-read-only)
+- [Custom Rows](#custom-rows)
+- [Height](#height)
+- [Controlled Usage](#controlled-usage)
+- [API](#api)
+
+## Label
+
+A label is required for the `TextArea` component. It should clearly describe
+the purpose of the field.
+
+## Helper Text
+
+You can provide additional context or instructions using the `helperText` prop.
+
+## Validation
+
+The `validationStatus` prop can be set to either `"valid"` or `"invalid"` to
+indicate the validation state. This must be accompanied by a `validationText`
+to explain the reason for the status.
+
+```tsx
+<Flex direction="column" gap="400">
+  <TextArea
+    {...args}
+    label="Valid TextArea"
+    validationStatus="valid"
+    validationText="Looks good!"
+    value="This is valid input."
+  />
+  <TextArea
+    {...args}
+    label="Invalid TextArea"
+    validationStatus="invalid"
+    validationText="Please correct the error."
+    value="This is invalid input."
+  />
+</Flex>
+```
+
+## Disabled and Read-only
+
+- **Disabled**: The `disabled` prop prevents user interaction with the `TextArea`.
+- **Read-only**: The `readOnly` prop allows the field to be focusable but not editable.
+
+```tsx
+<Flex direction="column" gap="400">
+  <TextArea {...args} label="Disabled" disabled helperText="This field is disabled." />
+  <TextArea
+    {...args}
+    label="Read-only"
+    readOnly
+    value="This is a read-only text area."
+    helperText="This field is read-only."
+  />
+</Flex>
+```
+
+## Custom Rows
+
+You can control the number of visible rows using the `rows` prop.
+
+```tsx
+<Flex direction="column" gap="400">
+  <TextArea {...args} label="3 Rows" rows={3} />
+  <TextArea {...args} label="5 Rows" rows={5} />
+  <TextArea {...args} label="10 Rows" rows={10} />
+</Flex>
+```
+
+## Height
+
+You can set a minimum and maximum height for the `TextArea` using the `minHeight` & `maxHeight` props.
+
+```tsx
+<TextArea {...args} />
+```
+
+## Controlled Usage
+
+The `TextArea` can be used as a controlled component by managing its `value` and `onChange` props.
+
+```tsx
+const [value, setValue] = React.useState<string>('Initial value');
+return (
+  <TextArea
+    {...args}
+    value={value}
+    onChange={(event: React.ChangeEvent<HTMLTextAreaElement>) => setValue(event.target.value)}
+    label="Controlled TextArea"
+  />
+);
+```
+
+```tsx
+<TextArea
+  {...args}
+  value={value}
+  onChange={(event: ChangeEvent<HTMLTextAreaElement>) => setValue(event.target.value)}
+  label="Controlled TextArea"
+/>
+```
+
+## API
+
+This component is based on the `textarea` element, and supports the following common props:
+
+- Margin
+
+| Prop               | Type                                                                                                                                                                                                       | Default  | Description                                                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
+| `label`            | `string`                                                                                                                                                                                                   | —        | The label for the form field, describing its purpose.                          |
+| `value`            | `string`                                                                                                                                                                                                   | —        | The controlled value of the TextArea. Must be used with an `onChange` handler. |
+| `labelId`          | `string`                                                                                                                                                                                                   | —        |                                                                                |
+| `helperTextId`     | `string`                                                                                                                                                                                                   | —        |                                                                                |
+| `validationTextId` | `string`                                                                                                                                                                                                   | —        |                                                                                |
+| `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.                                               |
+| `resize`           | `"none" \| "both" \| "horizontal" \| "vertical"`                                                                                                                                                           | `"both"` | Controls the resize behavior of the TextArea.                                  |
+| `minHeight`        | `Responsive<string>`                                                                                                                                                                                       | —        | Sets the minimum height of the TextArea.                                       |
+| `maxHeight`        | `Responsive<string>`                                                                                                                                                                                       | —        | Sets the maximum height of the TextArea.                                       |
+| `margin`           | `Responsive<"auto" \| `var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —        |                                                                                |
+| `marginTop`        | `Responsive<"auto" \| `var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —        |                                                                                |
+| `marginRight`      | `Responsive<"auto" \| `var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —        |                                                                                |
+| `marginBottom`     | `Responsive<"auto" \| `var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —        |                                                                                |
+| `marginLeft`       | `Responsive<"auto" \| `var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —        |                                                                                |
+| `marginX`          | `Responsive<"auto" \| `var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —        |                                                                                |
+| `marginY`          | `Responsive<"auto" \| `var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —        |                                                                                |