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

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

@@ -0,0 +1,202 @@
+# RadioGroup
+
+## Usage Guidelines
+
+### Overview
+
+RadioGroup presents a related set of mutually exclusive choices. Use Radio only as a child of RadioGroup so selection state, names, labels, helper text, and validation are announced consistently.
+
+#### When to Use
+
+- Use when users must choose exactly one option from a small, visible set.
+- Use when comparing all choices before selecting is important to the task.
+- Use when the selected value should submit with a native form through a shared `name`.
+- Use helper text when the choice affects billing, access, or other downstream behavior.
+
+#### When Not to Use
+
+- Do not use when users can choose more than one option. Use CheckboxGroup instead.
+- Do not use for long, dynamic, or searchable lists. Use Select for compact closed lists or ComboBox when filtering helps.
+- Do not use for a single on/off setting. Use Toggle or Checkbox depending on the surrounding form pattern.
+- Do not render a Radio outside RadioGroup. RadioGroup coordinates the selection state, accessible group name, and form behavior.
+
+### Behavior
+
+- **Mouse and touch**: Selecting one radio clears the previously selected option in the same group.
+- **Keyboard**: Users tab to the group, move between options with arrow keys, and select an option with Space.
+- **Focus management**: Focus stays on the active radio option and follows native radio group behavior from React Aria.
+- **Controlled state**: Use `value` and `onChange` when product logic owns the selection. Use `defaultValue` when the form can own the initial selection.
+- **Validation**: Show `errorMessage` with `invalid` after submit, blur, or another clear validation moment. Helper text is hidden while the error is visible.
+
+### Accessibility
+
+- Provide a visible group `label` whenever possible. Use `aria-label` or `aria-labelledby` only when a visible label is not available.
+- Give every Radio a concise visible `label` that describes the option value.
+- Keep helper text and error text associated with the RadioGroup, not repeated on each option.
+- Keep the native radio inputs in the DOM so screen readers, keyboard users, and form submission receive the correct behavior.
+- Do not rely on color alone to communicate selected, disabled, or invalid state.
+
+### Content
+
+- Write option labels as short, parallel nouns or noun phrases, such as "Monthly", "Quarterly", and "Annual".
+- Order options by user expectation, frequency, or business priority. Avoid alphabetical order when it makes comparison harder.
+- Use helper text for consequences or constraints that apply to the whole group.
+- Write error messages that name the missing or invalid choice and how to recover, such as "Choose a collection method."
+
+### Related
+
+- **CheckboxGroup**: use when users may select multiple options from a visible set.
+- **[Select](components-forms-select.md)**: use when only one option can be selected but the list should stay compact.
+- **[ComboBox](components-forms-combobox.md)**: use when only one option can be selected and typing should filter a longer list.
+
+## React
+
+```tsx
+import { RadioGroup, Radio } from '@maxio-com/react-ui-components';
+```
+
+## Composition
+
+Render each Radio as a direct child of RadioGroup. RadioGroup owns the accessible group label, shared native `name`, selected value, helper text, error text, and disabled or invalid group state.
+
+```tsx
+<RadioGroup name="billing-cycle" label="Billing cycle" defaultValue="monthly">
+  <Radio value="monthly" label="Monthly" />
+  <Radio value="quarterly" label="Quarterly" />
+  <Radio value="annual" label="Annual" />
+</RadioGroup>
+```
+
+## State Management
+
+Use controlled state when product logic needs to save, validate, transform, or share the selected value as soon as it changes.
+
+### Controlled
+
+```tsx
+const [value, setValue] = React.useState('email');
+
+<RadioGroup
+  name="invoice-delivery"
+  label="Invoice delivery"
+  value={value}
+  onChange={setValue}
+>
+  <Radio value="email" label="Email invoice" />
+  <Radio value="mail" label="Mail invoice" />
+  <Radio value="portal" label="Customer portal only" />
+</RadioGroup>;
+```
+
+### Uncontrolled
+
+```tsx
+<RadioGroup name="billing-cycle" label="Billing cycle" defaultValue="monthly">
+  <Radio value="monthly" label="Monthly" />
+  <Radio value="quarterly" label="Quarterly" />
+  <Radio value="annual" label="Annual" />
+</RadioGroup>
+```
+
+## Imports
+
+```tsx
+import { Radio, RadioGroup } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### RadioGroup
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `children` | `ReactNode` | yes | - | Children of the radio group | TypeLiteral |
+| `disabled` | `boolean` | no | `false` | Disable the radio group | TypeLiteral |
+| `errorMessage` | `string` | no | - | Error message for the radio group | TypeLiteral |
+| `helperText` | `string` | no | - | Helper text for the radio group | TypeLiteral |
+| `invalid` | `boolean` | no | `false` | Invalid state of the radio group | TypeLiteral |
+| `label` | `string` | no | - | Label for the radio group | TypeLiteral |
+| `name` | `string` | yes | - | Name for the radio group | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use radio groups when all choices should stay visible and users can select exactly one value. Provide a group label and stable option values for form submission.
+
+```tsx
+const Default = () => {
+    return (
+        <RadioGroup
+            name="billing-cycle"
+            label="Billing cycle"
+            defaultValue="monthly"
+            onChange={action('onChange')}>
+            <Radio value="monthly" label="Monthly" />
+            <Radio value="quarterly" label="Quarterly" />
+            <Radio value="annual" label="Annual" />
+        </RadioGroup>
+    );
+};
+```
+
+### With Helper Text
+
+Use helper text when users need context before choosing, such as how the selected value affects billing, access, or downstream settings.
+
+```tsx
+const WithHelperText = () => <RadioGroup
+    name="payment-timing"
+    label="Payment timing"
+    helperText="Changes apply to invoices created after today."
+    defaultValue="next-invoice">
+    <Radio value="next-invoice" label="Next invoice only" />
+    <Radio value="future-invoices" label="All future invoices" />
+</RadioGroup>;
+```
+
+### Validation
+
+Use validation when a required choice is missing or the selected option is no longer available. Helper text is hidden while the error message is visible.
+
+```tsx
+const Validation = () => <RadioGroup
+    name="collection-method"
+    label="Collection method"
+    invalid
+    errorMessage="Choose a collection method.">
+    <Radio value="auto" label="Automatic payment" />
+    <Radio value="manual" label="Manual invoice" />
+</RadioGroup>;
+```
+
+### Disabled
+
+Use disabled groups when the choice is unavailable in the current context. Avoid disabling choices that users may need to review or copy.
+
+```tsx
+const Disabled = () => <RadioGroup name="contract-term" label="Contract term" defaultValue="annual" disabled>
+    <Radio value="monthly" label="Monthly" />
+    <Radio value="annual" label="Annual" />
+</RadioGroup>;
+```
+
+### Indented Option
+
+Use indent to visually nest a radio under related content while keeping it in the same RadioGroup. Do not use indentation to create a separate group.
+
+```tsx
+const IndentedOption = () => <RadioGroup name="tax-handling" label="Tax handling" defaultValue="standard">
+    <Radio value="standard" label="Use account defaults" />
+    <Radio value="override" label="Override account defaults" />
+    <Radio indent value="manual-review" label="Send to manual review" />
+</RadioGroup>;
+```
+
+### Controlled
+
+Use controlled state when product logic needs to save, validate, transform, or share the selected value as soon as it changes.
+
+```tsx
+const Controlled = () => <ControlledRadioGroupExample name="invoice-delivery" label="Invoice delivery" />;
+```

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

@@ -0,0 +1,295 @@
+# Select
+
+## Usage Guidelines
+
+### Overview
+
+Select lets users choose one value from a short, known list of options. Use it for native single-selection form fields where filtering or custom option content is not needed.
+
+#### When to Use
+
+- Use when users need to choose one value from a short, known list.
+- Use when native browser select behavior is enough and the option labels are simple text.
+- Use in forms, filters, and table controls where preserving standard keyboard and mobile picker behavior matters.
+- Use disabled options when a few choices are temporarily unavailable but the field should remain usable.
+
+#### When Not to Use
+
+- Do not use when users need to search or filter a long list. Use ComboBox instead.
+- Do not use when users can choose multiple values. Use CheckboxGroup or a multi-select pattern instead.
+- Do not use when options need rich content, icons, descriptions, or grouped actions.
+- Do not use placeholder text or the first option as the only label. Provide a visible `label` whenever possible.
+
+### Variants
+
+| Variants    | Purpose                             | Usage notes                                                  |
+| :---------- | :---------------------------------- | :----------------------------------------------------------- |
+| `sm`        | Compact field for dense interfaces. | Use in tables, filters, or compact toolbars.                 |
+| `md`        | Default select size.                | Use for most forms.                                          |
+| `lg`        | Larger field for prominent rows.    | Use sparingly when the field needs more visual emphasis.     |
+| `xl`        | Contained field treatment.          | Use when label and helper or error text should feel grouped. |
+| `inline`    | Horizontal label and select layout. | Use in compact controls where the row relationship is clear. |
+| `fullWidth` | Fills the available parent width.   | Use in stacked forms and responsive layouts.                 |
+| `disabled`  | Unavailable select field.           | Use only when users cannot change the value in this context. |
+
+### Behavior
+
+- **Mouse and touch**: Users open the native select picker and choose one option. Disabled options remain visible but cannot be selected.
+- **Keyboard**: Users tab to the select, open it with native browser shortcuts, move through options with arrow keys, and select using standard platform behavior.
+- **Focus management**: Focus stays on the native `<select>` element.
+- **Controlled state**: Use `value` and `onChange` when product state owns the selected value. Use `defaultValue` when the form can read the value on submit.
+- **Validation**: Show validation after users submit, blur the field, or otherwise finish interacting. Avoid showing errors before users have a chance to choose.
+
+### Accessibility
+
+- Provide a visible `label` whenever possible. Use `aria-label` or `aria-labelledby` only when a visible label is not available.
+- Keep labels associated with the native select through `htmlFor` and `id`.
+- Use `helperText` for guidance that helps users choose before they interact.
+- Use `errorMessage` for concise validation feedback, and pass native ARIA attributes when product validation requires announced invalid state.
+- Use native `disabled` on the select or individual options instead of visual-only disabled styling.
+- Do not rely on color alone to communicate disabled, unavailable, or error state.
+
+### Content
+
+- Write labels as short nouns, such as "Plan", "Billing cadence", or "Payment terms".
+- Keep option labels concise and mutually exclusive.
+- Put the most common or safest option first when there is a meaningful default.
+- Avoid using a blank first option unless users must make an explicit choice.
+- Write helper text that explains impact or constraints, not instructions to click the field.
+- Write error messages that name the recovery step, such as "Choose payment terms before saving."
+
+### Related
+
+- **[TextField](components-forms-textfield.md)**: use when users need to enter a free-form value.
+- **[ComboBox](components-forms-combobox.md)**: use when users choose from a list and typing should filter options.
+- **[Checkbox](components-forms-checkbox.md)**: use when users can choose multiple values from a list.
+
+## React
+
+```tsx
+import { Select } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+Select accepts native `<select>` props, including `name`, `value`, `defaultValue`, `onChange`, `disabled`, and ARIA attributes.
+
+#### Controlled
+
+Use controlled state when product logic needs the selected value immediately, such as updating a summary, enabling an action, or saving through client state.
+
+```tsx
+const [plan, setPlan] = React.useState('growth');
+
+<Select
+  label="Plan"
+  value={plan}
+  onChange={(event) => setPlan(event.currentTarget.value)}
+  options={[
+    { value: 'starter', label: 'Starter' },
+    { value: 'growth', label: 'Growth' },
+    { value: 'enterprise', label: 'Enterprise' },
+  ]}
+/>;
+```
+
+#### Uncontrolled
+
+Use uncontrolled state when the value can be read from a native form submit or ref.
+
+```tsx
+<Select
+  label="Plan"
+  name="plan"
+  defaultValue="growth"
+  options={[
+    { value: 'starter', label: 'Starter' },
+    { value: 'growth', label: 'Growth' },
+    { value: 'enterprise', label: 'Enterprise' },
+  ]}
+/>
+```
+
+## Imports
+
+```tsx
+import { Select } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Select
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | no | `false` | If `true`, the select will be disabled | SelectProps |
+| `errorMessage` | `string` | no | - | The error message of the select | SelectProps |
+| `fullWidth` | `boolean` | no | `false` | If `true`, the select will be full width | SelectProps |
+| `helperText` | `string` | no | - | The helper text of the select | SelectProps |
+| `inline` | `boolean` | no | `false` | If `true`, the select will be inline | SelectProps |
+| `label` | `string` | no | - | The label of the select | SelectProps |
+| `options` | `Option[]` | yes | - | The options of the select | SelectProps |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | no | `md` | The size of the select | SelectProps |
+
+## Stories
+
+### Default
+
+Use Select when users choose one value from a short, known list. Provide a visible label and use controlled state when product logic needs the selected value immediately.
+
+```tsx
+const Default = () => <Select label="Plan" options={planOptions} onChange={action('onChange')} />;
+```
+
+### With Helper Text
+
+Use helper text when users need context before choosing, such as how the selection affects billing, reporting, or another workflow.
+
+```tsx
+const WithHelperText = () => <Select
+    label="Billing cadence"
+    helperText="Changing cadence affects future invoices only."
+    options={[
+      {
+        value: 'monthly',
+        label: 'Monthly',
+      },
+      {
+        value: 'annual',
+        label: 'Annual',
+      },
+    ]}
+    onChange={action('onChange')} />;
+```
+
+### Validation
+
+Use errorMessage after validation when a required selection is missing or the chosen value is no longer available.
+
+```tsx
+const Validation = () => <Select
+    label="Payment terms"
+    errorMessage="Choose payment terms before saving."
+    options={[
+      {
+        value: '',
+        label: 'Select payment terms',
+      },
+      {
+        value: 'net-15',
+        label: 'Net 15',
+      },
+      {
+        value: 'net-30',
+        label: 'Net 30',
+      },
+    ]}
+    onChange={action('onChange')} />;
+```
+
+### Disabled
+
+Use disabled Selects when the value is unavailable and users cannot change it in the current context.
+
+```tsx
+const Disabled = () => <Select
+    label="Billing contact"
+    disabled
+    options={[
+      {
+        value: '',
+        label: 'Select an account first',
+      },
+    ]} />;
+```
+
+### With Disabled Options
+
+Use disabled options when only specific choices are unavailable. Keep the select itself enabled when users can still choose another option.
+
+```tsx
+const WithDisabledOptions = () => <Select
+    label="Billing region"
+    options={[
+      {
+        value: 'us',
+        label: 'United States',
+      },
+      {
+        value: 'ca',
+        label: 'Canada (coming soon)',
+        disabled: true,
+      },
+      {
+        value: 'gb',
+        label: 'United Kingdom',
+      },
+    ]}
+    onChange={action('onChange')} />;
+```
+
+### Sizes
+
+Use size to match the surrounding form density. Use md for most forms, sm in compact filters, lg for prominent rows, and xl when label and helper or error text should feel integrated with the field.
+
+```tsx
+const Sizes = (args) => (
+  <div style={{ display: 'grid', gap: '0.75rem', maxWidth: '18rem' }}>
+    {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+      <Select key={size} {...args} size={size} />
+    ))}
+  </div>
+);
+```
+
+### Inline
+
+Use inline Selects in compact toolbar or table controls where the label and field need to stay on one row.
+
+```tsx
+const Inline = () => <Select
+    label="Rows"
+    inline
+    options={[
+      {
+        value: '10',
+        label: '10',
+      },
+      {
+        value: '25',
+        label: '25',
+      },
+      {
+        value: '50',
+        label: '50',
+      },
+    ]}
+    onChange={action('onChange')} />;
+```
+
+### Full Width
+
+Use fullWidth in stacked forms and responsive layouts where the field should align to the available parent width.
+
+```tsx
+const FullWidth = () => <div style={{ maxWidth: '24rem' }}>
+    <Select
+        label="Default product"
+        fullWidth
+        options={[
+          {
+            value: 'subscriptions',
+            label: 'Subscriptions',
+          },
+          {
+            value: 'usage',
+            label: 'Usage',
+          },
+          {
+            value: 'invoices',
+            label: 'Invoices',
+          },
+        ]}
+        onChange={action('onChange')} />
+</div>;
+```