@maxio-com/react-ui-components 9.15.0 → 9.16.1

package/dist/skills/maxio-react/references/components-forms-checkbox.md

@@ -0,0 +1,257 @@
+# Checkbox
+
+## Usage Guidelines
+
+### Overview
+
+Checkbox is a form control for single and multiple selections.
+
+#### When to Use
+
+- Use Checkbox for independent yes/no choices or optional form settings.
+- Use CheckboxGroup when users can choose any number of related options from a set.
+- Use an indeterminate checkbox for a parent option that summarizes a partially selected child list.
+- Use helper text when the consequences of selecting options are not obvious from the labels alone.
+
+#### When Not to Use
+
+- Do not use Checkbox when users must choose exactly one option. Use RadioGroup instead.
+- Do not use Checkbox as an immediate action trigger. Use Button, IconButton, or ActionMenu instead.
+- Do not use Checkbox for on/off settings that apply immediately without form submission. Use Toggle instead.
+- Do not use placeholder or helper text as the accessible label. Provide a visible label or another accessible name.
+
+### Variants
+
+| Variants        | Purpose                                    | Usage notes                                                                 |
+| :-------------- | :----------------------------------------- | :-------------------------------------------------------------------------- |
+| `default`       | Unselected option.                         | Use for available options that are not currently selected.                  |
+| `checked`       | Selected option.                           | Use `checked` for controlled state or `defaultChecked` for uncontrolled UI. |
+| `indeterminate` | Mixed parent state.                        | Use only when the checkbox summarizes a partially selected collection.      |
+| `error`         | Invalid option or invalid selection group. | Pair with visible validation text and `aria-invalid`.                       |
+| `disabled`      | Option or group cannot be changed.         | Use when users cannot act on the option in the current context.             |
+| `skeleton`      | Placeholder while checkbox content loads.  | Use only as a noninteractive loading placeholder.                           |
+
+### Behavior
+
+- **Mouse and touch**: clicking or tapping the label or control toggles the selected state unless disabled.
+- **Keyboard**: native checkboxes receive focus with Tab and toggle with Space.
+- **Focus management**: focus lands on the native checkbox input. Keep the visible Maxio focus treatment intact.
+- **Controlled state**: use `checked` and `onChange` for a single controlled checkbox. Use `value` and `onChange` on CheckboxGroup when product state owns the selected value array.
+- **Validation**: show validation after users submit, blur the group, or otherwise finish interacting. Use group-level validation when the requirement applies to the collection.
+
+### Accessibility
+
+- Use a native `input type="checkbox"` for each option.
+- Give every checkbox an accessible name with visible `label`, `aria-label`, or `aria-labelledby`.
+- Wrap related checkboxes in CheckboxGroup with a group label when they are part of one question.
+- Associate helper text and error text with the group or input through `aria-describedby`.
+- Use `aria-invalid="true"` for invalid checkboxes or invalid group options.
+- Use `aria-checked="mixed"` for indeterminate checkboxes when composing static HTML.
+- Do not rely on color alone to communicate selected, mixed, disabled, or invalid state.
+
+### Content
+
+- Write checkbox labels as specific options, such as "Send invoice receipt" or "Customer portal".
+- Keep group labels short and question-like enough to frame the option set.
+- Use helper text to explain consequences, limits, or selection requirements before validation fails.
+- Write error messages that name the recovery step, such as "Select at least one delivery method."
+- Avoid labels that describe the control gesture, such as "Check this box".
+
+### Related
+
+- **[Radio](components-forms-radio-group.md)**: use when users must choose exactly one option from a set.
+- **[Toggle](components-toggle.md)**: use for immediate on/off settings.
+- **[TextField](components-forms-textfield.md)**: use when users need to enter a custom value.
+
+## React
+
+```tsx
+import { Checkbox, CheckboxGroup } from '@maxio-com/react-ui-components';
+```
+
+## State Management
+
+Use controlled state when product logic needs to validate, save, or share the current selection. Use uncontrolled state when the selected value can be read from a form submit or ref.
+
+### Controlled Checkbox
+
+```tsx
+const [selected, setSelected] = React.useState(false);
+
+<Checkbox
+  label="Send invoice receipt"
+  value="receipt"
+  checked={selected}
+  onChange={setSelected}
+/>;
+```
+
+### Uncontrolled Checkbox
+
+```tsx
+<Checkbox label="Auto-collect payments" value="auto-collect" defaultChecked />
+```
+
+### Controlled Group
+
+```tsx
+const [deliveryMethods, setDeliveryMethods] = React.useState(['email']);
+
+<CheckboxGroup
+  name="invoice-delivery-methods"
+  label="Invoice delivery methods"
+  value={deliveryMethods}
+  onChange={setDeliveryMethods}
+>
+  <Checkbox value="email" label="Email" />
+  <Checkbox value="postal-mail" label="Postal mail" />
+  <Checkbox value="customer-portal" label="Customer portal" />
+</CheckboxGroup>;
+```
+
+## Imports
+
+```tsx
+import { Checkbox, CheckboxGroup } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Checkbox
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | no | - | - | CheckboxProps |
+| `error` | `boolean` | no | `false` | - | CheckboxProps |
+| `indeterminate` | `boolean` | no | - | - | CheckboxProps |
+| `label` | `string` | no | - | - | CheckboxProps |
+| `onChange` | `((selected: boolean) => void)` | no | - | - | CheckboxProps |
+| `value` | `string` | no | - | - | CheckboxProps |
+
+## Stories
+
+### Default
+
+Use Checkbox for an independent yes/no choice. Provide a visible label that describes the option being selected, and use value when the checkbox belongs to a submitted form or group.
+
+```tsx
+const Default = () => <Checkbox
+    label="Send invoice receipt"
+    onChange={action('onChange')}
+    value="receipt" />;
+```
+
+### Checked
+
+Use a checked checkbox when the option is already selected. Use defaultChecked for uncontrolled forms, or checked with onChange when product state owns the selected value.
+
+```tsx
+const Checked = () => <Checkbox
+    defaultChecked
+    label="Auto-collect payments"
+    onChange={() => {}}
+    value="auto-collect" />;
+```
+
+### Error
+
+Use error state when a required acknowledgement or group selection fails validation. Pair the invalid control with visible error text in the surrounding form.
+
+```tsx
+const Error = () => <Checkbox
+    label="I confirm these billing changes are approved"
+    error
+    value="approval-confirmed" />;
+```
+
+### Indeterminate
+
+Use indeterminate for parent options that summarize a partially selected child list, such as selecting all visible subscriptions.
+
+```tsx
+const Indeterminate = () => <Checkbox indeterminate label="Select all subscriptions" value="all-subscriptions" />;
+```
+
+### Disabled
+
+Use disabled state for options that cannot be changed in the current context. Keep the label visible so users can understand what is unavailable.
+
+```tsx
+const Disabled = () => <Checkbox label="Apply expired coupon" disabled value="expired-coupon" />;
+```
+
+### Default Group
+
+Use CheckboxGroup when multiple related options share one group label, helper text, validation message, and selected value array.
+
+```tsx
+const DefaultGroup = (
+  args // eslint-disable-line @typescript-eslint/no-unused-vars
+) => (
+  <CheckboxGroup name="invoice-notifications" label="Invoice notifications">
+    <Checkbox value="customer" label="Customer receipt" />
+    <Checkbox value="accounting" label="Accounting copy" />
+    <Checkbox value="collections" label="Collections alert" />
+  </CheckboxGroup>
+);
+```
+
+### Disabled Group
+
+Use a disabled group when the whole set of related choices is unavailable. The disabled state should apply consistently to every option in the group.
+
+```tsx
+const DisabledGroup = (
+  args // eslint-disable-line @typescript-eslint/no-unused-vars
+) => (
+  <CheckboxGroup
+    name="disabled-checkbox-group"
+    label="Legacy notification settings"
+    disabled
+  >
+    <Checkbox value="email" label="Email" />
+    <Checkbox value="sms" label="SMS" />
+    <Checkbox value="webhook" label="Webhook" />
+  </CheckboxGroup>
+);
+```
+
+### Helper Text Group
+
+Use helper text to explain how the selected options affect a workflow before users make a choice.
+
+```tsx
+const HelperTextGroup = (
+  args // eslint-disable-line @typescript-eslint/no-unused-vars
+) => (
+  <CheckboxGroup
+    name="helper-checkbox-group"
+    label="Renewal reminders"
+    helperText="Choose every reminder channel your team wants to receive."
+  >
+    <Checkbox value="30-days" label="30 days before renewal" />
+    <Checkbox value="7-days" label="7 days before renewal" />
+    <Checkbox value="day-of" label="On the renewal date" />
+  </CheckboxGroup>
+);
+```
+
+### Error Group
+
+Use group-level error messaging when validation depends on the set of selected options. Reference the error from the group so assistive technology announces the problem once for the collection.
+
+```tsx
+const ErrorGroup = (
+  args // eslint-disable-line @typescript-eslint/no-unused-vars
+) => (
+  <CheckboxGroup
+    name="error-checkbox-group"
+    label="Invoice delivery methods"
+    errorMessage="Select at least one delivery method."
+  >
+    <Checkbox value="email" label="Email" />
+    <Checkbox value="postal-mail" label="Postal mail" />
+    <Checkbox value="customer-portal" label="Customer portal" />
+  </CheckboxGroup>
+);
+```

package/dist/skills/maxio-react/references/components-forms-combobox.md

@@ -0,0 +1,250 @@
+# ComboBox
+
+## Usage Guidelines
+
+### Overview
+
+#### When to Use
+
+- Use when users choose from a known set of values and typing helps them find the right option.
+- Use when the option list is long, customer-generated, or easier to search than scan.
+- Use when options can be grouped into sections or rendered from dynamic product data.
+- Use with `allowsCustomValue` only when values outside the provided options are valid.
+
+#### When Not to Use
+
+- Do not use for short, predictable lists. Use Select or RadioGroup instead.
+- Do not use for command menus or action lists. Use ActionMenu or ActionList instead.
+- Do not use when users need to browse a static list without text filtering. Use ListBox instead.
+- Do not rely on placeholder text as the only label.
+
+### Variants
+
+| Variants            | Purpose                                       | Usage notes                                                                     |
+| :------------------ | :-------------------------------------------- | :------------------------------------------------------------------------------ |
+| `sm`                | Compact field for dense interfaces.           | Use where form density is high and labels remain readable.                      |
+| `md`                | Default field size.                           | Use for most forms.                                                             |
+| `lg`                | Larger field for prominent form rows.         | Use sparingly when the field needs more visual emphasis.                        |
+| `xl`                | Field with integrated label and helper/error. | Use when the field needs a stronger contained treatment.                        |
+| `selectionMode`     | Single or multiple value selection.           | Use multiple selection only when users can choose several values for one field. |
+| `allowsCustomValue` | Free-form text entry.                         | Use only when typed values outside the list can be saved.                       |
+
+### Behavior
+
+- **Mouse and touch**: Users type in the input, open the listbox with the trigger, and select an option from the popup.
+- **Keyboard**: Users tab to the input, type to filter, use arrow keys to move through options, press `Enter` to select, and press `Escape` to close the listbox.
+- **Focus management**: Focus remains on the input while users filter and move through the listbox.
+- **Controlled state**: Use `value` and `onChange` when product state owns the selected value. Use `defaultValue` for uncontrolled form fields.
+- **Filtering**: Keep visible options aligned with the current query. Use dynamic item rendering when options come from product data.
+
+### Accessibility
+
+- Provide a visible `label` whenever possible. Use `aria-label` or `aria-labelledby` only when a visible label is not available.
+- Use `description` for helper text and `errorMessage` for validation feedback.
+- Pair invalid values with `isInvalid` and an actionable `errorMessage`.
+- Keep focus indicators visible on the input and options.
+- Keep disabled options in the list only when seeing the unavailable value helps users understand the choice set.
+- Do not rely on color alone to communicate validation, disabled, read-only, or selected state.
+
+### Content
+
+- Write labels as short nouns, such as "Account", "Customer", or "Plan".
+- Use placeholder text for examples, not instructions that replace the label.
+- Keep option names concise and unique enough to scan after filtering.
+- Group options with clear section headers when the list mixes statuses or categories.
+- Write error messages that name the problem and recovery step, such as "Account is required."
+
+### Related
+
+- **[Select](components-forms-select.md)**: use when users choose from a shorter closed list.
+- **[ListBox](components-listbox.md)**: use when the option list should remain visible on the page.
+- **[RadioGroup](components-forms-radio-group.md)**: use when all choices should be visible and only one option can be selected.
+- **[ActionMenu](components-action-menu.md)**: use when the choices are actions instead of form values.
+
+## React
+
+```tsx
+import { ComboBox } from '@maxio-com/react-ui-components';
+```
+
+## State Management
+
+Use controlled state when product logic needs to validate, transform, save, or share the selected value. Use `onInputChange` when product logic also needs the typed query.
+
+### Controlled
+
+```tsx
+const [account, setAccount] = React.useState('acme');
+
+<ComboBox label="Account" value={account} onChange={setAccount}>
+  <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+  <ComboBox.Item id="globex">Globex</ComboBox.Item>
+</ComboBox>;
+```
+
+### Uncontrolled
+
+```tsx
+<ComboBox label="Account" defaultValue="acme">
+  <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+  <ComboBox.Item id="globex">Globex</ComboBox.Item>
+</ComboBox>
+```
+
+## Imports
+
+```tsx
+import { ComboBox, Grid, Icon } from "@maxio-com/react-ui-components";
+```
+
+## Stories
+
+### Default
+
+Use ComboBox when users choose from a known set of values and typing helps them find the right option. Provide a visible label and use placeholder text only as an example of the expected value.
+
+```tsx
+const Default = () => <ComboBox
+    label="Account"
+    placeholder="Select account"
+    onChange={action('onChange')}
+    menuTrigger="focus">
+    <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+    <ComboBox.Item id="globex">Globex</ComboBox.Item>
+    <ComboBox.Item id="initech">Initech</ComboBox.Item>
+</ComboBox>;
+```
+
+### Dynamic Items
+
+Use dynamic items when options are loaded from typed product data. Keep each item id stable so selection state remains consistent after filtering or data refreshes.
+
+```tsx
+const DynamicItems = (args) => (
+  <ComboBox<Account> {...(args as ComboBoxProps<Account>)}>
+    {(item) => <ComboBox.Item id={item.id}>{item.name}</ComboBox.Item>}
+  </ComboBox>
+);
+```
+
+### With Sections
+
+Use sections when the option set mixes statuses, categories, or other groups that help users scan the list after filtering.
+
+```tsx
+const WithSections = () => <ComboBox label="Account" placeholder="Select account">
+    <ComboBox.Section>
+        <ComboBox.Header>Active</ComboBox.Header>
+        <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+        <ComboBox.Item id="globex">Globex</ComboBox.Item>
+    </ComboBox.Section>
+    <ComboBox.Section>
+        <ComboBox.Header>Archived</ComboBox.Header>
+        <ComboBox.Item id="initech">Initech</ComboBox.Item>
+    </ComboBox.Section>
+</ComboBox>;
+```
+
+### With Disabled Option
+
+Use disabled options when seeing an unavailable value helps users understand the full choice set. Omit unavailable options when they add noise.
+
+```tsx
+const WithDisabledOption = () => <ComboBox label="Account" placeholder="Select account">
+    <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+    <ComboBox.Item id="globex" isDisabled>Globex
+              </ComboBox.Item>
+    <ComboBox.Item id="initech">Initech</ComboBox.Item>
+</ComboBox>;
+```
+
+### Custom Value
+
+Use custom values only when typed values outside the provided options are accepted by the product flow. Validate custom text before saving it.
+
+```tsx
+const CustomValue = () => <ComboBox
+    label="Account"
+    placeholder="Type an account"
+    allowsCustomValue
+    onInputChange={action('onInputChange')}>
+    <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+    <ComboBox.Item id="globex">Globex</ComboBox.Item>
+    <ComboBox.Item id="initech">Initech</ComboBox.Item>
+</ComboBox>;
+```
+
+### Multiple Selection
+
+Use multiple selection when users can assign more than one value to the same field. Provide surrounding UI that makes selected values easy to review.
+
+```tsx
+const MultipleSelection = () => <ComboBox
+    label="Accounts"
+    placeholder="Add accounts"
+    selectionMode="multiple"
+    defaultValue={['acme']}>
+    <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+    <ComboBox.Item id="globex">Globex</ComboBox.Item>
+    <ComboBox.Item id="initech">Initech</ComboBox.Item>
+</ComboBox>;
+```
+
+### With Icon
+
+Use a leading icon when the field benefits from compact visual context, such as search. Keep decorative icons hidden from the accessible name.
+
+```tsx
+const WithIcon = () => <ComboBox
+    label="Account"
+    placeholder="Search accounts"
+    leadingElement={<Icon variant="search" />}>
+    <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+    <ComboBox.Item id="globex">Globex</ComboBox.Item>
+    <ComboBox.Item id="initech">Initech</ComboBox.Item>
+</ComboBox>;
+```
+
+### Validation
+
+Use errorMessage with isInvalid so assistive technology receives invalid state and users get actionable validation feedback.
+
+```tsx
+const Validation = () => <ComboBox
+    label="Account"
+    placeholder="Select account"
+    isInvalid
+    errorMessage="Account is required.">
+    <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+    <ComboBox.Item id="globex">Globex</ComboBox.Item>
+    <ComboBox.Item id="initech">Initech</ComboBox.Item>
+</ComboBox>;
+```
+
+### Sizes
+
+Use size to match the density and prominence of the surrounding form. Use md for most forms, sm in dense interfaces, and lg or xl only when the form row needs more emphasis.
+
+```tsx
+const Sizes = (args) => (
+  <Grid gap={4}>
+    {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+      <ComboBox key={size} size={size} {...args}>
+        <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+        <ComboBox.Item id="globex">Globex</ComboBox.Item>
+      </ComboBox>
+    ))}
+  </Grid>
+);
+```
+
+### Disabled
+
+Use disabled ComboBoxes when the value is unavailable and users cannot act on it in the current context.
+
+```tsx
+const Disabled = () => <ComboBox label="Account" placeholder="Select account" isDisabled>
+    <ComboBox.Item id="acme">Acme Co.</ComboBox.Item>
+    <ComboBox.Item id="globex">Globex</ComboBox.Item>
+</ComboBox>;
+```