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

package/dist/skills/maxio-react/references/components-tabs.md

@@ -0,0 +1,193 @@
+# Tabs
+
+## Usage Guidelines
+
+### Overview
+
+Tabs organizes related content into one selected panel at a time.
+
+#### When to Use
+
+- Use Tabs to switch between closely related views in the same page or workflow.
+- Use Tabs when one section should be visible at a time and the tab labels make the available sections easy to scan.
+- Use Tabs to keep account, billing, settings, or report subsections grouped under one stable context.
+
+#### When Not to Use
+
+- Do not use Tabs for navigation between unrelated pages or major app areas. Use SideNav or page navigation instead.
+- Do not use Tabs when users need to compare multiple sections at the same time. Use visible sections, cards, or a table instead.
+- Do not use icon-only tabs unless every tab has an accessible name and the icons are highly recognizable.
+
+### Variants
+
+Choose the visual treatment that fits the surrounding surface.
+
+| Variants      | Purpose                       | Usage notes                                                                 |
+| :------------ | :---------------------------- | :-------------------------------------------------------------------------- |
+| `line`        | Default page-level tabs.      | Use for most horizontal tab groups on a plain page or inside a section.     |
+| `contained`   | Higher-contrast grouped tabs. | Use when tabs need a stronger container relationship or sit in dense areas. |
+| `withDivider` | Adds dividers between tabs.   | Use only when neighboring tabs need clearer separation.                     |
+
+### Behavior
+
+- **Mouse and touch**: selecting a tab updates the active tab and renders the matching panel.
+- **Keyboard**: Tab moves focus into the tab list. ArrowRight and ArrowLeft move selection across enabled tabs.
+- **Focus management**: the selected tab receives focus after keyboard selection.
+- **Controlled state**: use `index` with `onChange` when the active tab needs to be driven by route state, saved preferences, or another component.
+- **Uncontrolled state**: use `defaultIndex` when Tabs can manage its own selection after the initial render.
+
+### Accessibility
+
+- Provide `ariaLabel` on `TabList` so the tab group has an accessible name.
+- Keep `Tab` and `TabPanel` order aligned so each tab maps to the panel at the same index.
+- Give icon-only tabs an accessible name with `aria-label`.
+- Do not put disabled tabs in the selected state.
+- Keep focus indicators visible and preserve the built-in arrow-key behavior.
+
+### Content
+
+- Use short noun labels that describe the panel content, such as "Invoices", "Usage", or "Settings".
+- Keep labels parallel in structure and specific to the current context.
+- Avoid long tab labels that wrap or make the active section hard to scan.
+- Use icons as supporting context; do not rely on icons alone unless the meaning is unmistakable.
+
+### Related
+
+- **[SideNav](patterns-side-nav.md)**: use for primary navigation across app areas.
+- **[Breadcrumbs](components-breadcrumbs.md)**: use to show page location in a hierarchy.
+- **[ActionList](components-action-list.md)**: use for a vertical list of actions or choices rather than mutually exclusive content panels.
+
+## React
+
+```tsx
+import {
+  Tabs,
+  TabList,
+  Tab,
+  TabPanels,
+  TabPanel,
+} from '@maxio-com/react-ui-components';
+```
+
+### Composition
+
+- `Tabs` provides selection state to the tab list and panels.
+- `TabList` renders the horizontal `tablist` and accepts only `Tab` children.
+- `Tab` renders one selectable tab. Use `rightIcon` for a supporting icon or `type="icon"` with `icon` for icon-only tabs.
+- `TabPanels` renders the active panel and accepts only `TabPanel` children.
+- `TabPanel` contains the content for the tab at the same index.
+
+Keep the number and order of `Tab` and `TabPanel` children aligned.
+
+### State Management
+
+Use uncontrolled Tabs for local page state. Use controlled Tabs when selection is driven by routing, persisted preferences, or another component.
+
+#### Controlled
+
+```tsx
+const Example = () => {
+  const [index, setIndex] = React.useState(0);
+
+  return (
+    <Tabs index={index} onChange={(idx) => setIndex(idx)}>
+      <TabList ariaLabel="Customer account sections">
+        <Tab>Overview</Tab>
+        <Tab>Invoices</Tab>
+      </TabList>
+      <TabPanels>
+        <TabPanel>Overview content</TabPanel>
+        <TabPanel>Invoices content</TabPanel>
+      </TabPanels>
+    </Tabs>
+  );
+};
+```
+
+#### Uncontrolled
+
+```tsx
+<Tabs defaultIndex={1}>
+  <TabList ariaLabel="Customer account sections">
+    <Tab>Overview</Tab>
+    <Tab>Invoices</Tab>
+  </TabList>
+  <TabPanels>
+    <TabPanel>Overview content</TabPanel>
+    <TabPanel>Invoices content</TabPanel>
+  </TabPanels>
+</Tabs>
+```
+
+## Imports
+
+```tsx
+import { Body, Icon, Tab, TabList, TabPanel, TabPanels, Tabs } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Tabs
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `defaultIndex` | `number` | no | `0` | Indicates which tab should be active by default | TypeLiteral |
+| `index` | `number` | no | - | Indicates which tab should be active in controlled mode. | TypeLiteral |
+| `onChange` | `((idx: number \| ((prevIdx: number) => number)) => void)` | no | - | Callback function that is fired when the tab is changed | TabsContext |
+| `variant` | `"line" \| "contained"` | no | `line` | The variant of the tabs. | TabsContext |
+| `withDivider` | `boolean` | no | `false` | Add divider between tabs | TabsContext |
+
+## Stories
+
+### Default
+
+Snippet unavailable: SyntaxError: Expected render to be an arrow function or function expression
+
+### Contained
+
+Snippet unavailable: SyntaxError: Expected render to be an arrow function or function expression
+
+### With Icon
+
+Use supporting icons only when they reinforce the visible tab label. The text label remains the accessible name.
+
+```tsx
+const WithIcon = () => <Tabs>
+    <TabList ariaLabel="Billing setup sections">
+        <Tab rightIcon={<Icon variant="bank" />}>Payment methods</Tab>
+        <Tab rightIcon={<Icon variant="address-card" />}>Billing contacts</Tab>
+    </TabList>
+    <TabPanels>
+        <TabPanel>
+            <Body>Manage saved bank accounts and cards.</Body>
+        </TabPanel>
+        <TabPanel>
+            <Body>Manage billing contacts and invoice recipients.</Body>
+        </TabPanel>
+    </TabPanels>
+</Tabs>;
+```
+
+### Bare Icon
+
+Use icon-only tabs only in compact interfaces where every icon is recognizable. Provide an accessible name for each tab.
+
+```tsx
+const BareIcon = () => <Tabs>
+    <TabList ariaLabel="Contact method sections">
+        <Tab
+            type="icon"
+            icon={<Icon variant="address-card" />}
+            aria-label="Billing contact" />
+        <Tab type="icon" icon={<Icon variant="bank" />} aria-label="Bank account" />
+    </TabList>
+    <TabPanels>
+        <TabPanel>
+            <Body>Billing contact details.</Body>
+        </TabPanel>
+        <TabPanel>
+            <Body>Bank account details.</Body>
+        </TabPanel>
+    </TabPanels>
+</Tabs>;
+```

package/dist/skills/maxio-react/references/components-tag.md

@@ -0,0 +1,117 @@
+# Tag
+
+## Usage Guidelines
+
+### Overview
+
+Tags label non-interactive metadata, statuses, or categories.
+
+#### When to Use
+
+- Use Tag to label non-interactive metadata, categories, plans, or statuses.
+- Use Tag in dense layouts such as tables, cards, summaries, and detail headers where a compact label helps users scan.
+- Use sentiment when the label communicates a recognizable state such as success, warning, danger, information, or highlight.
+
+#### When Not to Use
+
+- Do not use Tag for selectable, dismissible, or clickable values. Use [Chip](components-chip.md) instead.
+- Do not use Tag for urgent page-level messages. Use [Alert](components-notifications-alert.md), [Banner](components-notifications-banner.md), or [Toast](components-notifications-toast.md) instead.
+- Do not use Tag as the only way to explain complex status details. Pair it with nearby text when users need next steps or consequences.
+
+### Variants
+
+Use kind for visual emphasis and sentiment for status meaning.
+
+| Variants    | Purpose                       | Usage notes                                                                 |
+| :---------- | :---------------------------- | :-------------------------------------------------------------------------- |
+| `primary`   | Highest-emphasis tag.         | Use sparingly for important statuses that should stand out in a focused UI. |
+| `secondary` | Standard metadata tag.        | Use for most statuses and categories in repeated layouts.                   |
+| `tertiary`  | Lowest-emphasis metadata tag. | Use when the tag should support nearby content without adding a fill.       |
+
+| Sentiment   | Purpose                     | Usage notes                                                            |
+| :---------- | :-------------------------- | :--------------------------------------------------------------------- |
+| `info`      | Neutral information.        | Use for informational states such as trial, draft, or pending review.  |
+| `success`   | Positive or complete state. | Use for active, paid, completed, approved, or healthy states.          |
+| `warning`   | Needs attention.            | Use when users should notice a state before it becomes blocking.       |
+| `danger`    | Error or high-risk state.   | Use for overdue, failed, inactive, blocked, or destructive states.     |
+| `highlight` | Special categorization.     | Use for featured, enterprise, promoted, or otherwise notable metadata. |
+
+### Accessibility
+
+- Use Tag for static text only. Do not attach click handlers or keyboard behavior to the tag container.
+- Make the visible label specific enough to communicate the status without relying on color.
+- Use icons as decorative or supporting visuals only; the label must still carry the meaning.
+- Keep labels short and avoid abbreviations that are not familiar to the audience.
+- Pair tags with nearby explanatory text when a status requires action.
+
+### Content
+
+- Use one to three words when possible: "Active", "Past due", "Enterprise".
+- Use nouns or short status phrases rather than action labels.
+- Prefer customer-facing language over internal state names.
+- Avoid stacking several tags when one clear status is enough.
+
+### Related
+
+- **[Chip](components-chip.md)**: use for selected, dismissible, or interactive values.
+- **[Alert](components-notifications-alert.md)**: use for contextual messages that need explanation or action.
+- **[Banner](components-notifications-banner.md)**: use for page-level or product-level announcements.
+
+## React
+
+```tsx
+import { Tag } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Tag } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Tag
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `children` | `ReactNode` | yes | - | React children nodes | TypeLiteral |
+| `kind` | `"primary" \| "secondary" \| "tertiary"` | no | `primary` | Modifier for the tag Kind | TypeLiteral |
+| `leadingIcon` | `string` | no | - | Element allowing leading icon selection | TypeLiteral |
+| `sentiment` | `"danger" \| "info" \| "success" \| "warning" \| "highlight"` | no | - | Modifier for the tag Sentiment | TypeLiteral |
+| `size` | `"sm"` | no | - | Modifier for the size of the tag. Default tag size is `md` | TypeLiteral |
+| `trailingIcon` | `string` | no | - | Element allowing trailing icon selection | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Tag for short, non-interactive metadata such as customer type, plan status, invoice state, or categorization. Use the visible label as the accessible name.
+
+```tsx
+const Default = () => <Tag kind="secondary" sentiment="success">Active</Tag>;
+```
+
+### Sentiment
+
+Use sentiment when the tag communicates a recognizable status. Do not rely on color alone; keep the label specific enough to carry the meaning.
+
+```tsx
+const Sentiment = () => <Tag kind="primary" sentiment="danger">Past due</Tag>;
+```
+
+### With Icon
+
+Use icons only when they help identify the tag faster. Icons are supporting visuals; the label still communicates the tag's meaning.
+
+```tsx
+const WithIcon = () => <Tag kind="tertiary" sentiment="highlight" leadingIcon="briefcase">Enterprise</Tag>;
+```
+
+### Small
+
+Use small tags in dense areas such as table cells, compact summaries, and metadata rows where the tag should not dominate surrounding content.
+
+```tsx
+const Small = () => <Tag kind="secondary" sentiment="info" size="sm">Trial</Tag>;
+```

package/dist/skills/maxio-react/references/components-tile.md

@@ -0,0 +1,114 @@
+# Tile
+
+## Usage Guidelines
+
+### Overview
+
+Tile groups concise content in a standalone surface.
+
+#### When to Use
+
+- Use Tile for compact, standalone content that should be scanned as one choice or summary.
+- Use Tile when the entire surface should navigate to one destination or perform one clear action.
+- Use Tile for dashboards, setup steps, feature shortcuts, or next-step prompts where the whole surface has the same outcome.
+
+#### When Not to Use
+
+- Do not use Tile for page sections with headings, body content, and local actions. Use Card instead.
+- Do not use Tile as a generic layout wrapper when the content does not need a visible surface.
+- Do not put multiple links, buttons, or form controls inside an interactive Tile. Use a noninteractive Tile or Card with separate controls instead.
+- Do not use Tile for inline text navigation. Use Link instead.
+
+### Behavior
+
+- **Mouse and touch**: static tiles do not respond to pointer input. Interactive tiles activate when the tile surface is clicked or tapped.
+- **Keyboard**: link tiles follow native anchor behavior and activate with Enter. Static tiles do not enter the tab order.
+- **Focus management**: keep the visible focus ring intact on interactive tiles and make the tile text describe the destination or action.
+- **Disabled state**: disabled interactive tiles receive disabled styling and suppress React click handling. For HTML usage, keep disabled styling and semantic state attributes synchronized.
+
+### Accessibility
+
+- Use static `div` markup only when the tile itself is not interactive.
+- Use native `a href` semantics when the tile navigates to another page or resource.
+- Use a native button pattern for hand-authored HTML action tiles so Enter and Space activation work by default.
+- Make the accessible name clear from visible tile content. The heading and summary should describe the destination or action.
+- Do not rely on color alone to communicate disabled or unavailable state. Provide nearby explanatory text when the reason is not obvious.
+- Avoid nesting interactive controls inside an interactive tile because nested click targets create confusing focus and activation behavior.
+
+### Content
+
+- Lead with a short, specific heading that names the destination, action, or summary.
+- Use supporting copy to explain what happens next or why the tile matters.
+- Keep tile content concise enough to scan in a grid or dashboard.
+- Use disabled copy to explain availability requirements when users can resolve the issue.
+
+### Related
+
+- **[Card](components-card.md)**: use for grouped page sections with header, body, footer, or local actions.
+- **[Link](components-link.md)**: use for inline or standalone text navigation.
+- **[Button](components-buttons-button.md)**: use for ordinary actions that do not need the whole-surface tile treatment.
+
+## React
+
+```tsx
+import { Tile } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Tile } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Tile
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | no | - | - | TypeLiteral |
+| `href` | `string` | no | - | - | TypeLiteral |
+| `onClick` | `((() => void) & MouseEventHandler<HTMLDivElement>)` | no | - | - | TypeLiteral, DOMAttributes |
+| `target` | `"string"` | no | - | - | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use a static Tile when the content is grouped for scanning but the whole surface does not navigate or trigger an action.
+
+```tsx
+const Default = () => <Tile onClick={undefined}><div className="maxio-heading-md">Text content</div></Tile>;
+```
+
+### Navigation
+
+Use a link Tile when clicking anywhere on the tile should take users to one destination. Keep the destination clear from the visible content.
+
+```tsx
+const ClickableHref = () => <Tile href="https://www.maxio.com"><div className="maxio-heading-md">Href</div></Tile>;
+```
+
+### Action
+
+Use an action Tile only when the whole surface performs one clear action. Do not place additional interactive elements inside an action Tile.
+
+```tsx
+const ClickableOnClick = () => <Tile><div className="maxio-heading-md">On click</div></Tile>;
+```
+
+### Disabled navigation
+
+Use disabled styling when a navigation Tile is temporarily unavailable. Prevent navigation in JavaScript and communicate the unavailable reason near the tile when the reason is not obvious.
+
+```tsx
+const ClickableHrefDisabled = () => <Tile disabled href="/revenue-recognition"><div className="maxio-heading-md">href disabled</div></Tile>;
+```
+
+### Disabled action
+
+Use disabled action Tiles only when the action cannot currently be performed. Avoid using disabled tiles for permissions or hidden features that need more explanatory copy.
+
+```tsx
+const ClickableOnClickDisabled = () => <Tile disabled onClick={action('Disabled tile action')}><div className="maxio-heading-md">onClick disabled</div></Tile>;
+```

package/dist/skills/maxio-react/references/components-toggle.md

@@ -0,0 +1,218 @@
+# ToggleComponent
+
+## Usage Guidelines
+
+### Overview
+
+Toggle lets users turn a setting on or off.
+
+#### When to Use
+
+- Use Toggle for a single setting that can be either on or off.
+- Use Toggle when changing the setting can take effect immediately.
+- Use Toggle for persistent preferences such as notifications, automation, or feature access.
+
+#### When Not to Use
+
+- Do not use Toggle for one-time actions such as saving, deleting, or submitting. Use Button instead.
+- Do not use Toggle when users must choose one option from a set. Use Radio or Select instead.
+- Do not use Toggle for multi-select lists. Use Checkbox instead.
+
+### Behavior
+
+- **Mouse and touch**: clicking or tapping the input changes the setting between off and on.
+- **Keyboard**: the native checkbox receives focus in tab order and changes state with Space. The React component also supports Enter.
+- **Focus management**: keep the Maxio focus ring visible on the switch track.
+- **Controlled state**: use `checked` with `onChange` when app state owns the setting. Use `defaultChecked` for simple uncontrolled form use.
+- **Disabled state**: disabled toggles remain visible but cannot be changed.
+
+### Accessibility
+
+- Keep the native checkbox input as the interactive control.
+- Provide a clear accessible name with visible `valueDescription` text or `aria-label`.
+- Connect visible `valueDescription` labels with `id` and `htmlFor`; the component generates an id when one is not provided.
+- Keep the checkbox state, visual track position, and any persisted setting value synchronized.
+- Do not rely on color alone to communicate on or off state; the track includes iconography as an additional cue.
+
+### Content
+
+- Label the setting, not the current state. Use "Email notifications" instead of only "On" or "Off".
+- Keep labels short and specific enough to scan in dense settings pages.
+- Place explanatory or eligibility copy near the toggle when a disabled state needs context.
+
+### Related
+
+- **[Checkbox](components-forms-checkbox.md)**: use for independent selections in a form or list.
+- **[Radio](components-forms-radio-group.md)**: use when users must choose one option from a related set.
+- **[Button](components-buttons-button.md)**: use for actions that run only after activation.
+
+## React
+
+```tsx
+import { Toggle } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+Use `checked` and `onChange` when application state owns the setting.
+
+```tsx
+const [checked, setChecked] = React.useState(false);
+
+<Toggle
+  checked={checked}
+  onChange={setChecked}
+  valueDescription="Email notifications"
+  valueDescriptionPosition="right"
+/>;
+```
+
+Use `defaultChecked` when the initial state is enough and the form can read the checkbox value later.
+
+```tsx
+<Toggle
+  defaultChecked
+  name="auto-renewal"
+  valueDescription="Auto-renewal"
+  valueDescriptionPosition="left"
+/>
+```
+
+## Imports
+
+```tsx
+import { ToggleComponent } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Toggle
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `aria-label` | `string` | no | - | Aria label for the toggle - should be provided if no valueDescription is provided | TypeLiteral |
+| `checked` | `boolean` | no | - | The state of the toggle | TypeLiteral |
+| `className` | `string` | no | - | Class name for the main container | TypeLiteral |
+| `defaultChecked` | `boolean` | no | - | The state for uncontrolled toggle. | TypeLiteral |
+| `disabled` | `boolean` | no | - | Is the toggle disabled | TypeLiteral |
+| `id` | `string` | no | - | Toggle id - if id not provided then it will be generated automatically | TypeLiteral |
+| `name` | `string` | no | - | Toggle name | TypeLiteral |
+| `onChange` | `((value: boolean, event?: KeyboardEvent<HTMLInputElement> \| ChangeEvent<HTMLInputElement>) => void)` | no | - | The onChange function | TypeLiteral |
+| `valueDescription` | `string` | no | - | Toggle label | TypeLiteral |
+| `valueDescriptionPosition` | `"left" \| "right"` | no | - | Toggle label position | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Default for a single setting that can be toggled on or off immediately. Prefer a visible label that names the setting instead of only describing the current state.
+
+```tsx
+const Default = ({
+  checked = false,
+  onChange,
+  ...props
+}: ToggleProps) => {
+  const [isChecked, setIsChecked] = React.useState(Boolean(checked));
+
+  return (
+    <ToggleComponent
+      {...props}
+      checked={isChecked}
+      onChange={(value, event) => {
+        setIsChecked(value);
+        onChange?.(value, event);
+      }}
+    />
+  );
+};
+```
+
+### Checked
+
+Use Checked when the setting is already enabled. Keep the input `checked` state aligned with the visual track position.
+
+```tsx
+const Checked = ({
+  checked = false,
+  onChange,
+  ...props
+}: ToggleProps) => {
+  const [isChecked, setIsChecked] = React.useState(Boolean(checked));
+
+  return (
+    <ToggleComponent
+      {...props}
+      checked={isChecked}
+      onChange={(value, event) => {
+        setIsChecked(value);
+        onChange?.(value, event);
+      }}
+    />
+  );
+};
+```
+
+### Label Left
+
+Place the label on the left when the surrounding form reads label first.
+
+```tsx
+const LabelLeft = ({
+  checked = false,
+  onChange,
+  ...props
+}: ToggleProps) => {
+  const [isChecked, setIsChecked] = React.useState(Boolean(checked));
+
+  return (
+    <ToggleComponent
+      {...props}
+      checked={isChecked}
+      onChange={(value, event) => {
+        setIsChecked(value);
+        onChange?.(value, event);
+      }}
+    />
+  );
+};
+```
+
+### Label Right
+
+Place the label on the right when the switch appears before its setting name.
+
+```tsx
+const LabelRight = ({
+  checked = false,
+  onChange,
+  ...props
+}: ToggleProps) => {
+  const [isChecked, setIsChecked] = React.useState(Boolean(checked));
+
+  return (
+    <ToggleComponent
+      {...props}
+      checked={isChecked}
+      onChange={(value, event) => {
+        setIsChecked(value);
+        onChange?.(value, event);
+      }}
+    />
+  );
+};
+```
+
+### Disabled
+
+Use Disabled when a setting is visible but cannot be changed in the current context. Include supporting copy nearby when users need to know why.
+
+```tsx
+const Disabled = () => <ToggleComponent
+    id="toggle-subscription-paused"
+    name="subscription-paused"
+    disabled
+    checked={false}
+    valueDescription="Subscription paused"
+    valueDescriptionPosition="right" />;
+```