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

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

@@ -0,0 +1,180 @@
+# Link
+
+## Usage Guidelines
+
+### Overview
+
+Link navigates users to another page, route, document, or external resource.
+
+#### When to Use
+
+- Use Link for navigation to another page, route, section, document, or external resource.
+- Use Link inside body copy, tables, lists, and other text-heavy surfaces where the destination is part of the content.
+- Use Link around a text component when the whole text element should navigate.
+- Use an icon on a standalone link when it helps clarify destination behavior, such as an external link.
+
+#### When Not to Use
+
+- Do not use Link for actions that change data, open UI, submit a form, or run client-side behavior. Use Button instead.
+- Do not use icon links inline with a sentence. Keep inline links text-only and underlined.
+- Do not wrap multiple controls or large regions in a Link. Put the link on the specific text or destination label.
+- Do not use vague link text such as "click here", "learn more", or a bare URL unless surrounding context supplies the accessible name.
+
+### Variants
+
+Choose the lowest emphasis that still makes the destination easy to find.
+
+| Variants        | Purpose                                    | Usage notes                                                                  |
+| :-------------- | :----------------------------------------- | :--------------------------------------------------------------------------- |
+| `primary`       | Standard navigational emphasis.            | Use for most standalone links and important destinations.                    |
+| `secondary`     | Reduced emphasis.                          | Use in dense interfaces, repeated rows, or when another action is primary.   |
+| `tertiary`      | Lowest emphasis.                           | Use for supporting destinations that should remain visually quiet.           |
+| `high-contrast` | Stronger contrast on light neutral areas.  | Use when the surrounding surface needs a more prominent text link.           |
+| `inverse`       | Link styling for dark or branded surfaces. | Use only where inverse text is required for contrast against the background. |
+
+### Behavior
+
+- **Mouse and touch**: clicking or tapping follows the anchor `href`.
+- **Keyboard**: native links with `href` receive focus in tab order and activate with Enter.
+- **Focus management**: keep the visible focus ring intact and avoid moving focus before navigation starts.
+- **External links**: use `external` for destinations that should open in a new tab, and make the destination clear from visible text.
+- **Disabled styling**: disabled links are visually unavailable and have pointer events removed. Use this sparingly; if a destination is unavailable, consider hiding the link or explaining the requirement nearby.
+
+### Accessibility
+
+- Use native `a href` semantics for navigation so browser link behavior, context menus, and keyboard support are preserved.
+- Give every link a clear accessible name that identifies the destination.
+- Underline inline links so they are not communicated by color alone.
+- Keep icons decorative unless they add meaning that is not already present in the visible text.
+- Do not nest buttons, form controls, or other interactive elements inside a link.
+- When composing disabled link states in HTML, pair visual styling with `aria-disabled="true"` and prevent activation in application logic.
+
+### Content
+
+- Write link text as a destination: "Customer profile", "Invoice settings", or "View revenue report".
+- Keep link text concise while preserving enough context for screen reader link lists.
+- Avoid repeating identical text for different destinations in the same view.
+- For external links, include destination context in the label or adjacent copy.
+
+### Related
+
+- **[Button](components-buttons-button.md)**: use for actions that happen on the current page.
+- **[IconButton](components-buttons-iconbutton.md)**: use for icon-only actions.
+- **[Breadcrumbs](components-breadcrumbs.md)**: use for hierarchical page navigation.
+
+## React
+
+```tsx
+import { Link } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Body, Heading, Link } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Link
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `children` | `ReactNode` | yes | - | The content of the link. | LinkProps |
+| `className` | `string` | no | - | Additional CSS class names to apply | LinkProps |
+| `disabled` | `boolean` | no | - | Defines whether the link is disabled. | LinkProps |
+| `external` | `boolean` | no | - | Defines if the link is external. External links are opened in a new tab. | LinkProps |
+| `icon` | `string` | no | - | Defines the icon variant. | LinkProps |
+| `size` | `"sm" \| "md" \| "lg" \| "xs"` | no | `sm` | Defines the size of the link text. | LinkProps |
+| `underline` | `boolean` | no | - | Applies underline style to the link | LinkProps |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "high-contrast" \| "inverse"` | no | - | Sets the link variant | LinkProps |
+
+## Stories
+
+### Default
+
+Use the default Link for standalone navigation to another page, route, or resource. The visible text should name the destination instead of describing the gesture.
+
+```tsx
+const Default = () => <Link underline={false} disabled={false} external={false} href="/customers">Customer profile</Link>;
+```
+
+### Component
+
+Use Link around heading or text components when the whole text element is the navigation target. Avoid wrapping large interactive regions or nesting interactive controls inside the anchor.
+
+```tsx
+const Component = () => <Link underline={false} disabled={false} external={false} href="#">
+    <Heading size="lg">Large heading</Heading>
+</Link>;
+```
+
+### Icon
+
+Use an icon only for standalone links where the icon reinforces destination behavior, such as opening an external resource. Do not use icon links inside sentences.
+
+```tsx
+const Icon = () => <Link
+    underline
+    disabled={false}
+    external
+    href="https://www.maxio.com"
+    icon="arrow-up-right">Maxio</Link>;
+```
+
+### Inline
+
+Use inline links inside body copy when the surrounding sentence supplies context. Underline inline links so they remain recognizable without relying on color alone.
+
+```tsx
+const Inline = () => <Body size="md">Use an{' '}
+    <Link disabled={false} external={false} href="#" underline>underlined link
+              </Link>{' '}in sentences
+        </Body>;
+```
+
+### Variants
+
+Use variants to tune link emphasis for the surrounding surface. Keep the meaning of the link in the label and choose the lowest emphasis that remains easy to find.
+
+```tsx
+const Variants = () => <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
+    <Link
+        underline={false}
+        disabled={false}
+        external={false}
+        href="/reports/revenue"
+        variant="primary">Primary report link
+              </Link>
+    <Link
+        underline={false}
+        disabled={false}
+        external={false}
+        href="/reports/revenue"
+        variant="secondary">Secondary report link
+              </Link>
+    <Link
+        underline={false}
+        disabled={false}
+        external={false}
+        href="/reports/revenue"
+        variant="tertiary">Tertiary report link
+              </Link>
+    <Link
+        underline={false}
+        disabled={false}
+        external={false}
+        href="/reports/revenue"
+        variant="high-contrast">High-contrast report link
+              </Link>
+    <div style={{ background: '#111827', padding: '0.75rem' }}>
+        <Link
+            underline={false}
+            disabled={false}
+            external={false}
+            href="/reports/revenue"
+            variant="inverse">Inverse report link
+                    </Link>
+    </div>
+</div>;
+```

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

@@ -0,0 +1,205 @@
+# ListBox
+
+## Usage Guidelines
+
+### Overview
+
+#### When to Use
+
+- Use ListBox for a compact set of related options where users choose one or more values.
+- Use ListBox inside a Popover, Select-like picker, command surface, or custom filtering experience.
+- Use sections when options need short group labels that help users scan the set.
+
+#### When Not to Use
+
+- Do not use ListBox for plain navigation. Use ActionList, SideNav, Tabs, or Link depending on the context.
+- Do not use ListBox for native form dropdowns when a simple select is enough. Use Select instead.
+- Do not use ListBox for standalone checklists where every option needs persistent visible controls. Use Checkbox instead.
+
+### Behavior
+
+- **Mouse and touch**: clicking or tapping an option moves selection to that option. Multi-select listboxes can keep several options selected.
+- **Keyboard**: Tab moves focus into and out of the listbox. Arrow keys move between options, Enter or Space selects, Home and End move to the first or last option, and typeahead searches visible option text.
+- **Focus management**: the focused option receives the visible focus ring. When ListBox is inside a Popover, return focus to the trigger when the popover closes.
+- **Controlled state**: use `selectedKeys` and `onSelectionChange` when application state, form submission, or analytics need to know the current selection.
+- **Empty state**: use `renderEmptyState` when filtering or loading leaves no available options.
+
+### Accessibility
+
+- Provide an accessible name with a visible label, `aria-label`, or `aria-labelledby`.
+- Keep option labels concise and unique enough for typeahead and screen reader navigation.
+- Use `selectionMode="multiple"` only when more than one selected option is meaningful, and keep selected state visually and programmatically clear.
+- Do not rely on the checkmark alone to communicate selection; keep `aria-selected` synchronized through the React component.
+- Use sections only when their headers help users understand the option set.
+- Preserve the default keyboard navigation and focus indicators from React Aria.
+
+### Content
+
+- Use option labels that match the value users are choosing, such as plan names, statuses, or account types.
+- Keep section headers short nouns or noun phrases: "Popular", "Archived", "Payment methods".
+- Use empty-state copy that explains the current result, such as "No results found."
+- Avoid long instructional text inside options; put guidance in the field label, helper text, or surrounding UI.
+
+### Related
+
+- **[Select](components-forms-select.md)**: use for native dropdown form controls.
+- **[ActionList](components-action-list.md)**: use for compact action or destination lists.
+- **[Popover](components-popover.md)**: use when the listbox appears in an overlay triggered by another control.
+- **[Checkbox](components-forms-checkbox.md)**: use for visible standalone multi-selection.
+
+## React
+
+```tsx
+import { ListBox } from '@maxio-com/react-ui-components';
+```
+
+## State Management
+
+Use `defaultSelectedKeys` when the initial selection can be owned by the
+listbox. Use `selectedKeys` with `onSelectionChange` when product logic needs
+to validate, submit, persist, or share the selected option.
+
+### Controlled
+
+```tsx
+const [selectedKeys, setSelectedKeys] = React.useState(() => new Set(['cat']));
+
+<ListBox
+  aria-label="Favorite animal"
+  selectionMode="single"
+  selectedKeys={selectedKeys}
+  onSelectionChange={(keys) =>
+    setSelectedKeys(keys === 'all' ? new Set() : (keys as Set<string>))
+  }
+>
+  <ListBox.Item id="aardvark">Aardvark</ListBox.Item>
+  <ListBox.Item id="cat">Cat</ListBox.Item>
+  <ListBox.Item id="dog">Dog</ListBox.Item>
+</ListBox>;
+```
+
+### Uncontrolled
+
+```tsx
+<ListBox
+  aria-label="Favorite animal"
+  selectionMode="single"
+  defaultSelectedKeys={['cat']}
+>
+  <ListBox.Item id="aardvark">Aardvark</ListBox.Item>
+  <ListBox.Item id="cat">Cat</ListBox.Item>
+  <ListBox.Item id="dog">Dog</ListBox.Item>
+</ListBox>
+```
+
+## Imports
+
+```tsx
+import { Button, DialogTrigger, ListBox, Popover } from "@maxio-com/react-ui-components";
+```
+
+## Stories
+
+### Default
+
+Use ListBox when users need to choose one option from a compact set. Provide a visible label near the control or an `aria-label` when the label is supplied by surrounding UI.
+
+```tsx
+const Default = () => <ListBox
+    aria-label="Favorite animal"
+    selectionMode="single"
+    shouldFocusWrap={false}
+    disallowEmptySelection={false}>
+    <ListBox.Item id="aardvark">Aardvark</ListBox.Item>
+    <ListBox.Item id="cat">Cat</ListBox.Item>
+    <ListBox.Item id="dog">Dog</ListBox.Item>
+</ListBox>;
+```
+
+### Multi Select
+
+Use multiple selection when users can keep more than one option active at a time. Keep selected option state synchronized with `aria-selected`.
+
+```tsx
+const MultiSelect = () => (
+  <ListBox aria-label="Pick toppings" selectionMode="multiple">
+    <ListBox.Item id="lettuce">Lettuce</ListBox.Item>
+    <ListBox.Item id="tomato">Tomato</ListBox.Item>
+    <ListBox.Item id="onion">Onion</ListBox.Item>
+  </ListBox>
+);
+```
+
+### With Sections
+
+Use sections to group long option sets under short, scannable headers. Headers should describe the relationship between the options that follow.
+
+```tsx
+const WithSections = () => (
+  <ListBox aria-label="Grouped options" selectionMode="single">
+    <ListBox.Section>
+      <ListBox.Header>Popular</ListBox.Header>
+      <ListBox.Item id="one">First</ListBox.Item>
+      <ListBox.Item id="two">Second</ListBox.Item>
+    </ListBox.Section>
+    <ListBox.Section>
+      <ListBox.Header>More</ListBox.Header>
+      <ListBox.Item id="three">Third</ListBox.Item>
+    </ListBox.Section>
+  </ListBox>
+);
+```
+
+### In Popover
+
+Use ListBox inside Popover for picker or menu-like controls where the trigger opens a bounded option set. Return focus to the trigger when the popover closes.
+
+```tsx
+const InPopover = () => {
+  const [selected, setSelected] = useState(() => new Set<string>());
+
+  return (
+    <DialogTrigger>
+      <Button variant="secondary" size="md">
+        Choose an option
+      </Button>
+      <Popover placement="bottom start" hideArrow>
+        <ListBox
+          aria-label="Grouped options"
+          selectionMode="single"
+          selectedKeys={selected}
+          onSelectionChange={(keys) =>
+            setSelected(keys === 'all' ? new Set() : (keys as Set<string>))
+          }
+        >
+          <ListBox.Section>
+            <ListBox.Header>Popular</ListBox.Header>
+            <ListBox.Item id="one">First</ListBox.Item>
+            <ListBox.Item id="two">Second</ListBox.Item>
+          </ListBox.Section>
+          <ListBox.Section>
+            <ListBox.Header>More</ListBox.Header>
+            <ListBox.Item id="three">Third</ListBox.Item>
+          </ListBox.Section>
+        </ListBox>
+      </Popover>
+    </DialogTrigger>
+  );
+};
+```
+
+### Empty State
+
+Use an empty state when filtering or async loading leaves no options to select. Keep the message brief and avoid rendering disabled placeholder options.
+
+```tsx
+const EmptyState = () => (
+  <ListBox
+    aria-label="Grouped options"
+    selectionMode="single"
+    renderEmptyState={() => 'No results found.'}
+  >
+    {[]}
+  </ListBox>
+);
+```

package/dist/skills/maxio-react/references/components-loading-spinner.md

@@ -0,0 +1,123 @@
+# LoadingSpinner
+
+## Usage Guidelines
+
+### Overview
+
+LoadingSpinner communicates indeterminate progress for short waits where the exact completion percentage is unknown.
+
+#### When to Use
+
+- Use LoadingSpinner for indeterminate work where the system is waiting but cannot report a percentage.
+- Use LoadingSpinner near the content, control, or region that is temporarily unavailable.
+- Use the white spinner when the indicator sits on a dark or brand-filled surface.
+
+#### When Not to Use
+
+- Do not use LoadingSpinner for known progress values. Use ProgressBar instead.
+- Do not use a standalone spinner for a button action that is already represented by a loading Button.
+- Do not use LoadingSpinner as a long-term empty state. Pair longer waits with visible status text or a more descriptive loading pattern.
+
+### Variants
+
+| Variant | Purpose              | Usage notes                                                             |
+| :------ | :------------------- | :---------------------------------------------------------------------- |
+| `size`  | Sets visual scale.   | Use `sm` or `md` in compact UI, and `lg` or `xl` for larger containers. |
+| `white` | Inverts the artwork. | Use only on dark or brand-filled backgrounds.                           |
+
+### Behavior
+
+- **Mouse and touch**: LoadingSpinner is not interactive and should not receive pointer handlers.
+- **Keyboard**: LoadingSpinner is not focusable. Keep focus on the control or region that started the work.
+- **Persistence**: show the spinner only while the related work is actively pending, then replace it with the loaded content or next state.
+
+### Accessibility
+
+- Keep `role="status"` and an accessible label when the spinner communicates loading state on its own.
+- Add nearby visible status text when the wait is long, page-wide, or affects a large region.
+- Do not rely on animation alone to explain what is happening.
+- Use `aria-hidden="true"` only when another nearby status label or control already communicates the loading state.
+
+### Content
+
+- Keep loading labels short and specific, such as "Loading invoices" or "Saving changes".
+- Match the status text to the thing that is pending.
+- Avoid vague copy like "Please wait" when the product can say what is loading.
+
+### Related
+
+- **[ProgressBar](components-progressbar.md)**: use for determinate progress with a known value.
+- **[Button](components-buttons-button.md)**: use the loading button state when progress is tied to a button action.
+
+## React
+
+```tsx
+import { LoadingSpinner } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { LoadingSpinner } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### LoadingSpinner
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `className` | `string` | no | - | Class name for the main container | TypeLiteral |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | no | `md` | The size of the loading spinner | TypeLiteral |
+| `white` | `boolean` | no | `false` | Changes color of the spinner to white for use on dark backgrounds. | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use LoadingSpinner when a local region or control is waiting on background work and the completion percentage is unknown.
+
+```tsx
+const Default = ({ white, ...props }) => (
+  <div
+    style={{
+      backgroundColor: white ? '#777' : 'white',
+      padding: '1rem',
+    }}
+  >
+    <LoadingSpinner {...props} white={white} />
+  </div>
+);
+```
+
+### On Dark Background
+
+Use the white spinner on dark or brand-filled surfaces so the indicator keeps enough contrast with its container.
+
+```tsx
+const OnDarkBackground = () => <div
+    style={{
+      backgroundColor: '#1f2937',
+      padding: '1rem',
+    }}>
+    <LoadingSpinner size="md" white />
+</div>;
+```
+
+### Sizes
+
+Choose the smallest spinner that remains visible in context. Use larger sizes for page or panel loading states, and smaller sizes inside compact controls.
+
+```tsx
+const Sizes = () => <div
+    style={{
+      alignItems: 'center',
+      display: 'flex',
+      gap: '1rem',
+    }}>
+    <LoadingSpinner size="sm" white={white} />
+    <LoadingSpinner size="md" white={white} />
+    <LoadingSpinner size="lg" white={white} />
+    <LoadingSpinner size="xl" white={white} />
+</div>;
+```

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

@@ -0,0 +1,91 @@
+# LogoComponent
+
+## Usage Guidelines
+
+### Overview
+
+Logo renders the Maxio brand lockup or mark.
+
+#### When to Use
+
+- Use Logo in persistent brand areas such as top bars, side navigation, and authentication layouts.
+- Use Logo when the interface needs to identify the current product or confirm that the user is in a Maxio-owned experience.
+- Use the mark when horizontal space is constrained or a full lockup is already visible nearby.
+
+#### When Not to Use
+
+- Do not use Logo as a decorative illustration or repeated background element.
+- Do not use the mark when users need the full brand name and there is enough room for the lockup.
+- Do not make the SVG itself interactive. Wrap it in a semantic link or button when it needs to navigate or trigger behavior.
+
+### Variants
+
+| Variant  | Purpose                  | Usage notes                                                                                 |
+| :------- | :----------------------- | :------------------------------------------------------------------------------------------ |
+| `lockup` | Full Maxio brand lockup. | Use by default when there is enough horizontal space and the brand name should be readable. |
+| `mark`   | Square Maxio brand mark. | Use in compact navigation, favicons, avatars, or places where the lockup appears nearby.    |
+
+### Accessibility
+
+- Logo renders as an inline SVG with `role="img"` and `aria-label`.
+- Keep the `alt` value short and contextual. Use "Maxio" when the logo identifies the brand.
+- When the logo links to home, wrap it in an `<a href="...">` and give the link an accessible name such as "Maxio home".
+- Do not rely on the logo color alone to communicate state or status.
+- Keep the logo visible against the selected theme background and preserve the dark mode theme attribute on the surrounding container.
+
+## React
+
+```tsx
+import { Logo } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { LogoComponent } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Logo
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `alt` | `string` | no | - | The alt text of the logo | TypeLiteral |
+| `className` | `string` | no | - | Class name for the svg element of the logo | TypeLiteral |
+| `size` | `number \| "sm" \| "md" \| "lg"` | no | - | Size of the logo, by default uses 'sm'. Pass a number for a custom pixel height (e.g. 20 → '20px'). | TypeLiteral |
+| `variant` | `"mark" \| "lockup"` | no | - | Variant of the logo, by default uses 'lockup' | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use the default lockup when there is enough horizontal space for the full Maxio identity, such as app headers, login screens, or branded empty states.
+
+```tsx
+const Default = () => <LogoComponent alt="Maxio" />;
+```
+
+### Default (Dark)
+
+Use the default lockup in dark mode without changing props. The logo fill is handled by the surrounding `data-maxio-mode="dark"` theme context.
+
+```tsx
+const DefaultDark = () => <LogoComponent alt="Maxio" />;
+```
+
+### Logo as Mark
+
+Use the mark where horizontal space is constrained or the brand lockup is already present nearby. Pair it with accessible text when it acts as a home link.
+
+```tsx
+const LogoAsMark = () => <LogoComponent variant="mark" alt="Maxio" />;
+```
+
+### Custom Size
+
+Use a custom numeric size only when a standard token size cannot align with the surrounding layout. Prefer `sm`, `md`, or `lg` for most product surfaces.
+
+```tsx
+const CustomSize = () => <LogoComponent alt="Maxio" size={100} />;
+```