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

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" />;
+```

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

@@ -0,0 +1,175 @@
+# Card
+
+## Usage Guidelines
+
+### Overview
+
+#### When to Use
+
+- Use Card to group related content that should be scanned as one unit.
+- Use Card for page sections, settings panels, summaries, and content blocks with local actions.
+- Use Card.Header, Card.Body, and Card.Footer when a grouped section needs a title, content, and actions.
+
+#### When Not to Use
+
+- Do not use Card as a generic spacing wrapper when the content does not need a visible container.
+- Do not use Card for a whole page layout. Use layout primitives such as Flex or Grid instead.
+
+### Variants
+
+Choose the surface treatment that matches the card's hierarchy.
+
+| Variants    | Purpose                      | Usage notes                                                    |
+| :---------- | :--------------------------- | :------------------------------------------------------------- |
+| `primary`   | Standard grouped surface.    | Use for the main card or focused section within a page area.   |
+| `secondary` | Lower-emphasis grouped area. | Use when header and footer should sit behind the card surface. |
+
+### Behavior
+
+- **Mouse and touch**: Card has no built-in interaction. Interactive controls inside the card keep their own behavior.
+- **Keyboard**: Card does not enter the tab order unless you add focusable content inside it.
+- **Focus management**: do not move focus to the card container; move focus to meaningful headings or controls when needed.
+- **Composition**: keep Card.Header, Card.Body, and Card.Footer in visual reading order when using multiple sections.
+
+### Accessibility
+
+- Use Card as a visual grouping container, not as a landmark by default.
+- Include a visible heading in Card.Header when the grouped content needs a label.
+- Preserve semantic HTML for the content inside the card, such as headings, lists, tables, forms, links, and buttons.
+- Keep actions in Card.Footer related to the card content they affect.
+- Do not rely on the card surface color alone to communicate status, priority, or selection.
+
+### Content
+
+- Keep card headings short and specific to the grouped content.
+- Put primary details in Card.Body and supporting actions in Card.Footer.
+- Avoid mixing unrelated topics or actions in the same card.
+- Consider long customer-generated content and make sure it can wrap without hiding actions.
+
+### Related
+
+- **[Tile](components-tile.md)**: use when the entire surface is clickable or navigates.
+- **[Flex](components-flex.md)**: use for alignment and spacing without adding a bordered container.
+- **[Grid](components-grid.md)**: use for arranging multiple sections in responsive layouts.
+
+## React
+
+```tsx
+import { Card } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Body, Button, Card, Flex, Heading } from "@maxio-com/react-ui-components";
+```
+
+## Stories
+
+### Default
+
+Use Default for a simple static content group. Always wrap the main content in Card.Body so spacing remains consistent if header or footer sections are added later.
+
+```tsx
+const Default = () => <Card>
+    <Card.Body>
+        <Body size="sm">Subscription details and supporting context stay grouped in one
+                      surface.
+                    </Body>
+    </Card.Body>
+</Card>;
+```
+
+### With Header
+
+Use WithHeader when the card needs a visible title or section label. The heading level should fit the surrounding page hierarchy.
+
+```tsx
+const WithHeader = () => <Card>
+    <Card.Header>
+        <Heading size="sm">Billing summary</Heading>
+    </Card.Header>
+    <Card.Body>
+        <Body size="sm">Review the customer plan, renewal date, and current balance before
+                      making changes.
+                    </Body>
+    </Card.Body>
+</Card>;
+```
+
+### With Footer
+
+Use WithFooter when the card includes actions that apply to the grouped content. Keep footer actions specific to this card.
+
+```tsx
+const WithFooter = () => <Card>
+    <Card.Body>
+        <Body size="sm">Send the upcoming invoice reminder after confirming the billing
+                      contact.
+                    </Body>
+    </Card.Body>
+    <Card.Footer>
+        <Button variant="primary">Send reminder</Button>
+    </Card.Footer>
+</Card>;
+```
+
+### Secondary
+
+Use Secondary for supporting panels that should sit behind the primary card hierarchy while still grouping related content.
+
+```tsx
+const Secondary = () => <Card variant="secondary">
+    <Card.Body>
+        <Body size="sm">Use a quieter surface for supplemental account notes or background
+                      details.
+                    </Body>
+    </Card.Body>
+</Card>;
+```
+
+### Full
+
+Use Full when the card has a title, primary content, and local actions. Header, body, and footer sections should remain in that order.
+
+```tsx
+const Full = () => <Card>
+    <Card.Header>
+        <Heading size="sm">Payment method</Heading>
+    </Card.Header>
+    <Card.Body>
+        <Body size="sm">Visa ending in 4242 is used for subscription renewals and invoice
+                      retries.
+                    </Body>
+    </Card.Body>
+    <Card.Footer>
+        <Flex gap={2} justifyContent="end">
+            <Button variant="secondary">Cancel</Button>
+            <Button variant="primary">Update method</Button>
+        </Flex>
+    </Card.Footer>
+</Card>;
+```
+
+### Full Secondary
+
+Use FullSecondary for lower-emphasis sections that still need the complete header, body, and footer composition.
+
+```tsx
+const FullSecondary = () => <Card variant="secondary">
+    <Card.Header>
+        <Heading size="sm">Account notes</Heading>
+    </Card.Header>
+    <Card.Body>
+        <Body size="sm">Capture internal context that supports the customer record without
+                      competing with billing tasks.
+                    </Body>
+    </Card.Body>
+    <Card.Footer>
+        <Flex gap={2} justifyContent="end">
+            <Button variant="secondary">Cancel</Button>
+            <Button variant="primary">Save notes</Button>
+        </Flex>
+    </Card.Footer>
+</Card>;
+```

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

@@ -0,0 +1,151 @@
+# Chip
+
+## Usage Guidelines
+
+### Overview
+
+Chip is used for compact, interactive values such as applied filters that can be selected, toggled, or dismissed without leaving the current context.
+
+#### When to Use
+
+- Use Chip for compact interactive values, such as applied filters, selected criteria, or removable tokens.
+- Use Chip when the value can be toggled, selected, or dismissed in the current context.
+- Use Chip in toolbars, filter summaries, and dense workflows where a full button would add too much visual weight.
+
+#### When Not to Use
+
+- Do not use Chip for static labels or status metadata. Use Tag instead.
+- Do not use Chip for primary page actions. Use Button instead.
+- Do not use Chip for navigation to another page or resource. Use Link or Button rendered as a link when stronger emphasis is required.
+
+### Behavior
+
+- **Mouse and touch**: pressing the chip button toggles selection and calls `onPress`; pressing the dismiss button calls `onDismiss`.
+- **Keyboard**: the chip button and dismiss button are separate tab stops. Native button behavior supports Enter and Space activation.
+- **Focus management**: keep both focus indicators visible. After dismissing a chip, move focus to the next logical control in the owning workflow.
+- **Controlled state**: use `defaultSelected` for uncontrolled state, or pair `isSelected` with `onChange` when another component owns selection.
+- **Dismissal**: provide `dismissLabel` whenever the chip can be dismissed so the icon-only button has an accessible name.
+
+### Accessibility
+
+- Use native `button` semantics for both the chip control and dismiss control.
+- Provide a visible label that identifies the chip value.
+- Use `aria-pressed` to communicate selected state on the chip button.
+- Give the dismiss button a specific accessible name, such as "Remove Status: Active filter".
+- Do not rely on color alone to communicate selection; preserve the pressed state and visible focus treatment.
+
+### Content
+
+- Keep labels short and specific, especially when chips appear in groups.
+- Use the value the user selected, such as "Status: Active" or "Plan: Growth".
+- Avoid generic labels like "Filter" when several chips appear together.
+- Write dismiss labels that include the chip value when the visible label is not adjacent in the accessibility tree.
+
+### Related
+
+- **[Tag](components-tag.md)**: use for static labels, metadata, or statuses.
+- **[Button](components-buttons-button.md)**: use for standalone actions with stronger emphasis.
+- **[DataTable](components-data-table.md)**: chips are often used to summarize applied table filters.
+
+## React
+
+```jsx
+import { Chip } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+Chip can manage its own selected state with `defaultSelected`, or it can be controlled with `isSelected` and `onChange`.
+
+Use uncontrolled state for a chip that only needs to toggle itself. Use controlled state when selection is owned by another component, such as a filter menu, table toolbar, or saved view.
+
+## Imports
+
+```tsx
+import { Chip } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Chip
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `dismissLabel` | `string` | no | - | An aria-label for the dismiss button | TypeLiteral |
+| `label` | `string` | yes | - | Button's visible label | TypeLiteral |
+| `leadingIcon` | `string` | no | - | Adds a leading icon to the chip | TypeLiteral |
+| `onDismiss` | `(() => void)` | no | - | Callback function when the dismiss button is pressed | TypeLiteral |
+| `title` | `string` | no | - | Adds a title to the chip | TypeLiteral |
+| `trailingIcon` | `string` | no | - | Adds a trailing icon to the chip | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Chip for a selected, actionable value such as an applied filter. Include a dismiss button when users can remove that value from the current context.
+
+```tsx
+const Default = (args: any) => {
+  const chipProps = {
+    ...args,
+    onDismiss: args?.onDismiss && action('Chip dismissed'),
+  };
+
+  return <Chip {...chipProps}>{args.label}</Chip>;
+};
+```
+
+### Selected
+
+Use the selected state when the chip represents an active toggle, filter, or segmented choice. Keep `aria-pressed` synchronized with the visual selected state in static HTML.
+
+```tsx
+const Selected = (args: any) => {
+  const chipProps = {
+    ...args,
+    defaultSelected: true,
+    onDismiss: undefined,
+    trailingIcon: undefined,
+  };
+
+  return <Chip {...chipProps}>{args.label}</Chip>;
+};
+```
+
+### With Icons
+
+Use icons only when they help identify the chip value faster. Icons are supporting visuals; the visible label still provides the accessible name.
+
+```tsx
+const WithIcons = (args: any) => {
+  const chipProps = {
+    ...args,
+    onDismiss: undefined,
+    leadingIcon: 'dollar',
+    trailingIcon: 'arrow-right',
+  };
+
+  return <Chip {...chipProps}>{args.label}</Chip>;
+};
+```
+
+### Controlled
+
+Use controlled state when another component owns the selection, such as a filter menu, table toolbar, or saved view. Update `isSelected` from `onChange` so visual and announced state stay in sync.
+
+```tsx
+const Controlled = (args: any) => {
+  const [isSelected, setSelected] = useState(false);
+  const chipProps = {
+    ...args,
+    isSelected,
+    onDismiss: args?.onDismiss && action('Chip dismissed'),
+    onChange: (nextSelected: boolean) => {
+      setSelected(nextSelected);
+      action('Selected state')(String(nextSelected));
+    },
+  };
+
+  return <Chip {...chipProps}>{args.label}</Chip>;
+};
+```