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

package/dist/skills/maxio-react/references/components-action-menu.md

@@ -0,0 +1,162 @@
+# Menu
+
+## Usage Guidelines
+
+### Overview
+
+ActionMenu groups related contextual actions behind a trigger. Use it for secondary row, toolbar, or page actions that should stay available without occupying persistent space.
+
+#### When to Use
+
+- Use ActionMenu when several related actions belong to the same object, row, toolbar, or page area.
+- Use ActionMenu when secondary actions should stay available without taking persistent space.
+- Use ActionMenu when the actions can be described by a single trigger label, such as "Create" or "More actions".
+
+#### When Not to Use
+
+- Do not use ActionMenu for one high-priority action. Use Button or IconButton instead.
+- Do not use ActionMenu for primary navigation. Use SideNav, Tabs, or Link depending on the pattern.
+- Do not use ActionMenu for selectable form values. Use Select or ComboBox instead.
+
+### Behavior
+
+- **Mouse and touch**: activating the trigger opens or closes the menu. Activating a menu item follows that item's link target.
+- **Keyboard**: the trigger uses native `summary` behavior. Menu items support Arrow Up, Arrow Down, Enter, and Space through ActionList.
+- **Focus management**: the first action is focusable by default. Arrow keys move focus between actions and skip dividers.
+- **Internal state**: use the `Menu` render prop when trigger text or adjacent content needs to respond to `isOpen`.
+- **Alignment**: use end alignment when the trigger sits near a right edge or inside a table row action area.
+
+### Accessibility
+
+- Use `Menu` to wrap exactly one `MenuButton` and one `MenuList` so ids, open state, and ARIA relationships stay synchronized.
+- Give every `MenuButton` an accessible name. Icon-only triggers must use `aria-label`.
+- Keep `MenuButton` text concise and connected to the actions in the menu.
+- Use menu items for actions or related links only; each item should have a clear label.
+- Keep focus indicators visible and do not remove ActionList keyboard behavior.
+- Do not rely on the chevron or icon alone to communicate the trigger purpose.
+
+### Content
+
+- Label text triggers with the action family: "Create", "Export", "More actions", or "Subscription actions".
+- Avoid vague labels like "Menu" unless surrounding context supplies the object and action set.
+- Keep item labels action-oriented and specific, such as "Edit invoice" or "Cancel subscription".
+- Use icon-only triggers only where repeated layout context makes the menu purpose obvious.
+
+### Related
+
+- **[ActionList](components-action-list.md)**: use for the menu item list inside ActionMenu or for standalone action lists.
+- **[Button](components-buttons-button.md)**: use for a single visible action.
+- **[IconButton](components-buttons-iconbutton.md)**: use for a single icon-only action.
+- **[Select](components-forms-select.md)**: use for choosing a form value from a list.
+
+## React
+
+```tsx
+import { Menu, MenuButton, MenuList } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+`Menu` owns the open state for the underlying `details` element. Use the render-prop form when content needs to react to that state.
+
+```tsx
+<Menu>
+  {({ isOpen }) => (
+    <>
+      <MenuButton aria-label={isOpen ? 'Close actions' : 'Open actions'}>
+        {isOpen ? 'Close actions' : 'Open actions'}
+      </MenuButton>
+      <MenuList items={items} />
+    </>
+  )}
+</Menu>
+```
+
+Call `onClose` from custom menu content when an action should dismiss the menu before navigation or follow-up UI appears.
+
+## Imports
+
+```tsx
+import { Menu, MenuButton, MenuList } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Menu
+
+No props were emitted by reactDocgenTypescript for this component.
+
+## Stories
+
+### Default
+
+Use the default action menu for a small set of related actions behind a visible text trigger. The trigger needs an accessible name and controls the menu list through generated `aria-controls` and `aria-labelledby` values.
+
+```tsx
+const Default = () => (
+  <Menu>
+    <MenuButton aria-label="Create">Create</MenuButton>
+    <MenuList items={ITEMS} />
+  </Menu>
+);
+```
+
+### Button Classes
+
+Use MenuButton size and variant props when the trigger needs to match nearby button hierarchy. Keep the menu behavior the same; only the trigger styling changes.
+
+```tsx
+const ButtonClasses = () => (
+  <Menu>
+    <MenuButton aria-label="Create" size="lg" variant="ghost">
+      Create
+    </MenuButton>
+    <MenuList items={ITEMS} />
+  </Menu>
+);
+```
+
+### Internal State
+
+Use the render-prop state when the trigger label, adjacent controls, or custom content must react to the open state. Call `onClose` when custom content dismisses the menu.
+
+```tsx
+const InternalState = () => (
+  <Menu>
+    {({ isOpen }) => (
+      <>
+        <MenuButton aria-label={!isOpen ? 'Open' : 'Close'}>
+          {!isOpen ? 'Open' : 'Close'}
+        </MenuButton>
+        <MenuList items={ITEMS} />
+      </>
+    )}
+  </Menu>
+);
+```
+
+### Content Align End
+
+Use end alignment when the trigger sits near the right edge of a container or in a table row action area, so the menu stays visually connected to the trigger without overflowing nearby content.
+
+```tsx
+const ContentAlignEnd = () => (
+  <Menu>
+    <MenuButton aria-label="Create">Create</MenuButton>
+    <MenuList alignItemsEnd items={ITEMS} />
+  </Menu>
+);
+```
+
+### Icon Menu
+
+Use an icon-only action menu in dense toolbars or repeated rows. Always provide an `aria-label` that describes the actions available in the menu.
+
+```tsx
+const IconMenu = () => (
+  <Menu>
+    <MenuButton aria-label="Address" iconName="address-card" />
+    <MenuList items={ITEMS} />
+  </Menu>
+);
+```

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

@@ -0,0 +1,66 @@
+# AvatarComponent
+
+## Usage Guidelines
+
+### Overview
+
+Avatar is an image that represents a user or organization.
+
+#### When to Use
+
+- Use Avatar to represent a known person, account, or user profile.
+- Use Avatar when a compact visual identity cue helps people scan ownership, authorship, or account context.
+
+#### When Not to Use
+
+- Do not use Avatar for decorative brand, product, or status imagery. Use the more specific component or image treatment for that content.
+- Do not use Avatar when the image is the only way to distinguish a user and no accessible text alternative is available.
+
+### Behavior
+
+- Avatar is static image content and does not add interaction by itself.
+- Pair Avatar with a Button, IconButton, or Link only when the surrounding pattern is interactive.
+
+### Accessibility
+
+- Provide `alt` text that identifies the person when the avatar image conveys identity.
+- Use empty `alt=""` when adjacent visible text already identifies the same person and the image would be repetitive.
+- Do not rely on the profile image alone to communicate status, role, or account state.
+- Keep the image source stable enough that a missing avatar does not remove required identity text from the interface.
+
+### Content
+
+- Use a human-readable name in `alt` text, such as "Profile photo for Alex Morgan".
+- Avoid generic alternatives such as "avatar" or "user image" when the image identifies a specific person.
+
+## React
+
+```tsx
+import { Avatar } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { AvatarComponent } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Avatar
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `alt` | `string` | no | `avatar` | The alt text of the avatar | TypeLiteral |
+| `className` | `string` | no | - | Class name for the main container | TypeLiteral |
+| `src` | `string` | yes | - | The image source of the avatar | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Avatar to show a known user's profile image in account menus, headers, activity rows, or other identity-focused UI. Provide alt text that names the person when the image identifies them.
+
+```tsx
+const Default = () => <AvatarComponent src={avatarSrc} alt="Profile photo for Alex Morgan" />;
+```

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

@@ -0,0 +1,86 @@
+# Breadcrumbs
+
+## Usage Guidelines
+
+### Overview
+
+Breadcrumbs show the current page location in a hierarchy and provide links back to parent pages.
+
+#### When to Use
+
+- Use Breadcrumbs when users are on a page that belongs to a clear hierarchy.
+- Use Breadcrumbs to help users move back to parent pages without relying on browser history.
+- Use Breadcrumbs in products with deep navigation, nested resources, or detail pages reached from several parent sections.
+
+#### When Not to Use
+
+- Do not use Breadcrumbs for single-level pages or short flows with no parent hierarchy.
+- Do not use Breadcrumbs as the primary navigation for major product sections. Use SideNav or TopBar navigation instead.
+- Do not use Breadcrumbs to show step progress. Use a stepper or progress pattern instead.
+
+### Behavior
+
+- **Mouse and touch**: users can activate linked parent items. The current page item is not interactive.
+- **Keyboard**: linked parent items receive focus in document order and activate as normal links.
+- **Focus management**: focus stays on the activated link until navigation occurs. Do not move focus to the current page item.
+- **Current page**: the final item is always the current page and must not include `href`.
+
+### Accessibility
+
+- Use a named navigation landmark so assistive technology can identify the breadcrumb trail.
+- Use an ordered list so the hierarchy and item order are preserved.
+- Mark the current page item with `aria-current="page"`.
+- Keep the current page item as text instead of a self-link.
+- Keep link text specific enough that each destination is understandable out of context.
+
+### Content
+
+- Use page or resource names, not instructions such as "Back" or "Previous".
+- Keep labels short and recognizable. Truncate long names only when the full value is available nearby or on the destination page.
+- Start with the broadest useful parent and end with the current page.
+- Avoid including every possible ancestor when the trail becomes too long to scan.
+
+### Related
+
+- **[Link](components-link.md)**: use for inline navigation outside a breadcrumb trail.
+- **[SideNav](patterns-side-nav.md)**: use for persistent navigation across major product areas.
+- **[TopBar](patterns-top-bar.md)**: use for global navigation, account controls, and product-level actions.
+
+## React
+
+```tsx
+import { Breadcrumbs, BreadcrumbsItem } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Breadcrumbs, BreadcrumbsItem } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Breadcrumbs
+
+No props were emitted by reactDocgenTypescript for this component.
+
+## Stories
+
+### Default
+
+Use Breadcrumbs when the current page sits inside a clear hierarchy. Link parent pages and keep the final item as plain text for the current page.
+
+```tsx
+const Default = () => <Breadcrumbs>{[
+      <BreadcrumbsItem href={'/'} key="link">
+        WAI-ARIA Authoring Practices Guide (APG)
+      </BreadcrumbsItem>,
+      <BreadcrumbsItem href={'/section/'} key="linkb">
+        Patterns
+      </BreadcrumbsItem>,
+      <BreadcrumbsItem href={'/section/subsection'} key="linkc">
+        Breadcrumb Pattern
+      </BreadcrumbsItem>,
+      <BreadcrumbsItem key="linkd">Breadcrumb Example</BreadcrumbsItem>,
+    ]}</Breadcrumbs>;
+```

package/dist/skills/maxio-react/references/components-buttons-button.md

@@ -0,0 +1,170 @@
+# Button
+
+## Usage Guidelines
+
+### Overview
+
+Button helps users complete a task, move through a workflow, or make a clear choice. Use it for page actions by default, and provide `href` only when the button needs to navigate with button-level emphasis.
+
+#### When to Use
+
+- Use Button for actions that happen immediately or in response to user input.
+- Use Button for the primary action in a form, modal, toolbar, or page section.
+- Use Button for destructive actions when the action needs stronger visual warning.
+
+#### When Not to Use
+
+- Do not use Button for plain text navigation. Use Link instead.
+- Do not use Button for icon-only actions. Use IconButton so the accessible name requirement is clear.
+- Do not use multiple primary buttons in the same decision area unless the actions are truly equal choices.
+
+### Variants
+
+Choose the lowest emphasis that still makes the action easy to find.
+
+| Variants    | Purpose                               | Usage notes                                                                                                             |
+| :---------- | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
+| `primary`   | Highest-emphasis action.              | Use for the main action in a focused area, such as saving a form or continuing a setup flow.                            |
+| `secondary` | Standard supporting action.           | Use for actions that should be easy to find without competing with the primary action.                                  |
+| `tertiary`  | Low-emphasis action.                  | Use for supporting actions in dense interfaces or repeated rows.                                                        |
+| `ghost`     | Lowest-emphasis action.               | Use where the action should be available but visually quiet.                                                            |
+| `danger`    | Destructive or high-risk action.      | Use for delete, remove, cancel subscription, and similar actions. Add confirmation when the consequence is not obvious. |
+| `skeleton`  | Placeholder while content is loading. | Use only as a noninteractive loading placeholder.                                                                       |
+
+### Behavior
+
+- **Mouse and touch**: clicking or tapping activates the button once the pointer is released.
+- **Keyboard**: native buttons activate with Enter or Space. Anchor buttons activate with Enter.
+- **Focus management**: keep the visible focus ring intact and return focus to a sensible place after dialogs or menus close.
+- **Navigation**: use link rendering only when activation changes location or opens another resource.
+- **Loading**: keep the button visible while the action is pending so users can connect the progress state to the action they started.
+
+### Accessibility
+
+- Use native `button` semantics for actions and native `a href` semantics for navigation.
+- Give every button a clear accessible name through visible text. Use IconButton for icon-only controls.
+- Do not rely on color alone to communicate destructive, disabled, or loading state.
+- Keep focus indicators visible and avoid removing keyboard activation behavior.
+- Use `disabled` for unavailable native buttons. Use `aria-disabled` only when a non-native or anchor-style control must remain discoverable.
+- Communicate long-running progress near the button or through an appropriate status region when the action affects more than the button itself.
+
+### Content
+
+- Start labels with a specific verb: "Create invoice", "Save changes", "Delete customer".
+- Make the label describe the outcome, not the gesture. Avoid labels like "Click here" or "Go".
+- Keep labels short enough to scan, but not so short that the outcome is unclear.
+- Keep destructive labels explicit. "Delete invoice" is clearer than "Delete".
+- Avoid changing a label so dramatically in loading state that users cannot recognize which action is pending.
+
+### Related
+
+- **[IconButton](components-buttons-iconbutton.md)**: use for icon-only actions.
+- **[Link](components-link.md)**: use for plain text navigation in body copy, tables, or lists.
+- **[ActionMenu](components-action-menu.md)**: use when several related actions need to be grouped behind one trigger.
+- **[LoadingSpinner](components-loading-spinner.md)**: use for standalone progress that is not tied to a button action.
+
+## React
+
+```tsx
+import { Button } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Button, Icon } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Button
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | no | - | Determines if the button is disabled | InternalButtonProps |
+| `fullWidth` | `boolean` | no | `false` | Allows button to expand and fill the available horizontal space within its container | CommonButtonProps |
+| `href` | `string` | no | - | Disallows `href` on button element | InternalButtonProps, InternalLinkProps |
+| `icon` | `ReactNode` | no | - | Displays a trailing icon (depricated) | CommonButtonProps |
+| `leadingElement` | `ReactNode` | no | - | Displays a leading icon | CommonButtonProps |
+| `loading` | `boolean` | no | `false` | Indicates that the component is in a loading state, typically during asynchronous operations such as data fetching, form submissions, or any action that requires some time to complete | InternalButtonProps |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | no | - | Changes the size of the button | CommonButtonProps |
+| `trailingElement` | `ReactNode` | no | - | Displays a trailing icon | CommonButtonProps |
+| `value` | `string` | no | - | Button value - must be string for React Aria compatibility | InternalButtonProps |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "ghost" \| "danger" \| "skeleton"` | no | `primary` | Changes the button variant | CommonButtonProps |
+
+## Stories
+
+### Default
+
+Use Button for actions that happen on the current page. Prefer visible labels that describe the result of the action, and use native button behavior for actions.
+
+```tsx
+const Default = () => <Button onClick={action('Clicked')}>Create invoice</Button>;
+```
+
+### As Link
+
+Use Button as navigation only when the destination still needs button-level emphasis, such as a prominent next step in a workflow. Use Link for plain text navigation.
+
+```tsx
+const AsLink = () => <Button href="/customers/123" variant="secondary">View customer</Button>;
+```
+
+### Destructive
+
+Use danger variant for actions that remove data, cancel service, or are difficult to reverse. Pair destructive actions with confirmation or recovery guidance when the consequence is not obvious.
+
+```tsx
+const Destructive = () => <Button onClick={action('Deleted')} variant="danger">Delete invoice</Button>;
+```
+
+### Loading
+
+Use a loading button after the user starts an action and repeated activation should be prevented. Keep the label connected to the action that is running.
+
+```tsx
+const Loading = () => <Button loading onClick={action('Submitted')} type="submit">Saving changes</Button>;
+```
+
+### With Elements
+
+Use leading or trailing elements to reinforce a visible label.
+
+```tsx
+const WithElements = () => <Button
+    leadingElement={<Icon variant="plus" />}
+    trailingElement={<Icon variant="arrow-right" />}>Add subscription
+        </Button>;
+```
+
+### Full Width
+
+Use full-width buttons in constrained layouts where the action should align to the container width.
+
+```tsx
+const FullWidth = () => <div style={{ maxWidth: '20rem' }}>
+    <Button fullWidth>Continue
+              </Button>
+</div>;
+```
+
+### Variants
+
+Use variants to set visual emphasis and action tone. Choose the lowest emphasis that still makes the action easy to find.
+
+```tsx
+const Variants = () => <>
+    <Button variant="primary">Primary
+              </Button>
+    <Button variant="secondary">Secondary
+              </Button>
+    <Button variant="tertiary">Tertiary
+              </Button>
+    <Button variant="ghost">Ghost
+              </Button>
+    <Button variant="danger">Danger
+              </Button>
+    <Button variant="skeleton">Skeleton
+              </Button>
+</>;
+```

package/dist/skills/maxio-react/references/components-buttons-iconbutton.md

@@ -0,0 +1,102 @@
+# IconButton
+
+## Usage Guidelines
+
+### Overview
+
+IconButton is used for buttons that show an icon in place of a text label.
+
+#### When to Use
+
+- Use IconButton for compact actions in dense interfaces such as tables, toolbars, headers, and cards.
+- Use IconButton when the icon is a familiar control and the action can be named clearly with `aria-label`.
+- Use IconButton for icon-only navigation only when the destination still needs button-level emphasis.
+
+#### When Not to Use
+
+- Do not use IconButton when visible text is needed to make the action understandable. Use Button instead.
+- Do not use IconButton as a decorative icon. Use Icon when there is no action.
+- Do not rely on a tooltip as the only accessible name. Tooltips may not be available to every user.
+
+### Variants
+
+IconButton uses the same visual variants as Button. Choose the lowest emphasis that still makes the action easy to find.
+
+| Variants    | Purpose                          | Usage notes                                                                                                             |
+| :---------- | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
+| `primary`   | Highest-emphasis icon action.    | Use sparingly for the main compact action in a focused area.                                                            |
+| `secondary` | Standard supporting icon action. | Use for most standalone icon-only actions.                                                                              |
+| `tertiary`  | Low-emphasis icon action.        | Use for supporting actions in dense interfaces or repeated rows.                                                        |
+| `ghost`     | Lowest-emphasis icon action.     | Use when the action should be available but visually quiet.                                                             |
+| `danger`    | Destructive or high-risk action. | Use for delete, remove, cancel subscription, and similar actions. Add confirmation when the consequence is not obvious. |
+
+### Behavior
+
+- **Mouse and touch**: clicking or tapping activates the button once the pointer is released.
+- **Keyboard**: native icon buttons activate with Enter or Space. Anchor icon buttons activate with Enter.
+- **Focus management**: keep the visible focus ring intact and return focus to a sensible place after dialogs or menus close.
+- **Navigation**: use link rendering only when activation changes location or opens another resource.
+- **Loading**: keep the control visible while the action is pending, and provide nearby status text when the icon alone does not explain progress.
+
+### Accessibility
+
+- Use native `button` semantics for icon-only actions and native `a href` semantics for icon-only navigation.
+- Provide a required `aria-label` that describes the action outcome, such as "Search" or "Delete invoice".
+- Treat the visible icon as decorative unless it is also part of the accessible name.
+- Do not rely on color alone to communicate destructive, disabled, or loading state.
+- Keep focus indicators visible and avoid removing keyboard activation behavior.
+
+### Content
+
+- Make `aria-label` specific enough to stand alone when read by assistive technology.
+- Start action labels with a verb when possible: "Search", "Edit customer", "Delete invoice".
+- Include the object when repeated IconButtons appear in a list or table.
+- Keep tooltip copy aligned with the `aria-label` when a visible tooltip is provided.
+
+### Related
+
+- **[Button](components-buttons-button.md)**: use when the action should have a visible text label.
+- **[Icon](components-icon.md)**: use for decorative or noninteractive icons.
+- **[ActionMenu](components-action-menu.md)**: use when several related actions need to be grouped behind one trigger.
+
+## React
+
+```tsx
+import { IconButton } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Icon, IconButton } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### IconButton
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | no | - | Determines if the button is disabled | InternalButtonProps |
+| `href` | `string` | no | - | Disallows `href` on button element | InternalButtonProps, InternalLinkProps |
+| `icon` | `ReactNode` | no | - | Displays a trailing icon (depricated) | CommonButtonProps |
+| `leadingElement` | `ReactNode` | no | - | Displays a leading icon | CommonButtonProps |
+| `loading` | `boolean` | no | - | Indicates that the component is in a loading state, typically during asynchronous operations such as data fetching, form submissions, or any action that requires some time to complete | InternalButtonProps |
+| `size` | `"sm" \| "md" \| "lg"` | no | - | Changes the size of the button | CommonButtonProps, TypeLiteral |
+| `trailingElement` | `ReactNode` | no | - | Displays a trailing icon | CommonButtonProps |
+| `value` | `string` | no | - | Button value - must be string for React Aria compatibility | InternalButtonProps |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "ghost" \| "danger" \| "skeleton"` | no | - | Changes the button variant | CommonButtonProps |
+
+## Stories
+
+### Default
+
+Use IconButton for compact icon-only actions when surrounding context or an accessible name makes the action clear. Every IconButton must include an `aria-label` that describes the action outcome.
+
+```tsx
+const Default = () => <IconButton
+    aria-label="Search"
+    icon={<Icon variant="search" />}
+    onClick={action('Clicked')}
+    variant="secondary" />;
+```