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

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

@@ -0,0 +1,178 @@
+# TooltipTrigger
+
+## Usage Guidelines
+
+### Overview
+
+TooltipTrigger displays brief contextual help next to a trigger while preserving overlay positioning, keyboard, and dismissal behavior.
+
+#### When to Use
+
+- Use TooltipTrigger for short, supplemental context that helps explain a nearby term, icon, value, or control.
+- Use TooltipTrigger when the information should appear on hover, focus, or click without changing page layout.
+- Use TooltipTrigger when the tooltip content is helpful but the trigger remains understandable without it.
+
+#### When Not to Use
+
+- Do not use TooltipTrigger for required instructions, errors, or warnings. Put essential content directly in the interface.
+- Do not use TooltipTrigger for rich interactive content, forms, or multi-step help. Use Popover instead.
+- Do not use TooltipTrigger as the only label for an icon-only action. Give the trigger its own accessible name.
+
+### Behavior
+
+- **Mouse and touch**: hover shows the tooltip when `hover` is included. Click shows it when `click` is included.
+- **Keyboard**: focus shows the tooltip when `focus` is included. Add `dismiss` when Escape or focus loss should close a persistent tooltip.
+- **Focus management**: keep the trigger reachable and keep the tooltip noninteractive so focus can remain on the trigger.
+- **Controlled state**: use `isVisible` with `onVisibilityUpdate` when application state needs to open, close, or synchronize tooltip visibility.
+- **Dismissal or persistence**: use `autoHideMs` for short-lived click-triggered confirmations, and avoid persistent tooltips for content users must act on.
+
+### Accessibility
+
+- Keep tooltip content brief and descriptive. Tooltips should supplement the trigger, not replace visible labels or instructions.
+- Ensure the trigger has an accessible name through visible text, `aria-label`, or `aria-labelledby`.
+- Connect hand-authored tooltip markup to its trigger with `aria-describedby` and expose the floating element with `role="tooltip"`.
+- Include focus support whenever hover reveals information that keyboard users also need.
+- Do not place buttons, links, fields, or other interactive content inside a tooltip.
+
+### Content
+
+- Write tooltip copy as a short phrase or sentence that explains the trigger in context.
+- Avoid repeating the trigger label unless the repetition clarifies a term or status.
+- Prefer concrete product language, such as "Invoices renew monthly", over generic help text.
+- Move long guidance, error recovery, or policy details into persistent page content.
+
+### Related
+
+- **[IconButton](components-buttons-iconbutton.md)**: use for icon-only actions that need their own accessible name.
+- **[ActionMenu](components-action-menu.md)**: use when a trigger opens a list of actions rather than explanatory text.
+- **[Popover](components-popover.md)**: use when the overlay needs richer content or interactive controls.
+
+## React
+
+```tsx
+import { TooltipTrigger } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { TooltipTrigger } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### TooltipTrigger
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `autoHideMs` | `number` | no | - | Milliseconds after the overlay is automatically deactivated | TypeLiteral |
+| `children` | `ReactNode` | yes | - | React children nodes | TypeLiteral |
+| `className` | `string` | no | - | Class name for the main container | TypeLiteral |
+| `floatingElementOffset` | `number` | no | `5` | Floating element offset | TypeLiteral |
+| `interactions` | `Interactions[]` | no | `['hover']` | Definition of interactions that manages displaying of overlay element | TypeLiteral |
+| `isVisible` | `boolean` | no | - | Tooltip visibility state - use with useExternalState property | TypeLiteral |
+| `maxWidth` | `number \| "none"` | no | `160` | Maximum tooltip container width in pixels | TypeLiteral |
+| `onVisibilityUpdate` | `((isVisible: boolean) => void)` | no | - | Tooltip visibility state | TypeLiteral |
+| `placement` | `"left" \| "right" \| "top" \| "bottom" \| "left-start" \| "left-end" \| "right-start" \| "right-end" \| "top-start" \| "top-end" \| "bottom-start" \| "bottom-end"` | no | `right` | Overlay element placement | TypeLiteral |
+| `renderContent` | `() => ReactNode` | yes | - | Tooltip content renderer | TypeLiteral |
+| `size` | `"small" \| "regular"` | no | `regular` | Tooltip component size variant | TypeLiteral |
+| `usePortal` | `boolean` | no | - | Render floating element in portal container | TypeLiteral |
+
+## Stories
+
+### Default
+
+Snippet unavailable: SyntaxError: Expected render to be an arrow function or function expression
+
+### Click Interaction
+
+Use click interaction when the trigger is already an explicit control and the tooltip should stay available after pointer movement.
+
+```tsx
+const ClickInteraction = () => (
+  <TooltipTrigger
+    interactions={['click']}
+    renderContent={() => 'This report includes all active subscriptions.'}
+  >
+    <ListItem label="Show report hint" />
+  </TooltipTrigger>
+);
+```
+
+### Dismiss Interaction
+
+Add dismiss when users need an explicit way to close a tooltip after click, focus, or another persistent interaction opens it.
+
+```tsx
+const DismissInteraction = () => (
+  <TooltipTrigger
+    interactions={['click', 'dismiss']}
+    renderContent={() =>
+      'Press Escape or move focus away to close this hint.'
+    }
+  >
+    <ListItem label="Show dismissible hint" />
+  </TooltipTrigger>
+);
+```
+
+### Hover Interaction
+
+Use hover interaction for pointer-only supporting information. Pair it with focus in product experiences when the same tooltip should be keyboard accessible.
+
+```tsx
+const HoverInteraction = () => (
+  <TooltipTrigger
+    interactions={['hover']}
+    renderContent={() => 'Revenue is shown before refunds and discounts.'}
+  >
+    <ListItem label="Hover for revenue hint" />
+  </TooltipTrigger>
+);
+```
+
+### Focus Interaction
+
+Use focus interaction when the tooltip explains something keyboard users can tab to. Keep the tooltip nonessential so the trigger remains understandable without it.
+
+```tsx
+const FocusInteraction = () => (
+  <TooltipTrigger
+    interactions={['focus']}
+    renderContent={() => 'This value is calculated from posted invoices.'}
+  >
+    <ListItem label="Focus for invoice hint" />
+  </TooltipTrigger>
+);
+```
+
+### Auto Hide
+
+Use autoHideMs when a click-triggered tooltip should clear itself after a short, predictable amount of time.
+
+```tsx
+const AutoHide = () => (
+  <TooltipTrigger
+    interactions={['click']}
+    autoHideMs={2000}
+    renderContent={() => 'Copied invoice link to clipboard.'}
+  >
+    <ListItem label="Copy invoice link" />
+  </TooltipTrigger>
+);
+```
+
+### Max Width
+
+Use maxWidth to keep longer tooltip copy readable. Prefer editing tooltip copy down before increasing the width.
+
+```tsx
+const MaxWidth = () => (
+  <TooltipTrigger
+    interactions={['hover']}
+    renderContent={() => longTooltipContent}
+  >
+    <ListItem label="Hover for plan-name hint" />
+  </TooltipTrigger>
+);
+```

package/dist/skills/maxio-react/references/components-typography-body.md

@@ -0,0 +1,101 @@
+# Body
+
+## Usage Guidelines
+
+### Overview
+
+Body renders paragraph-level and supporting text with Maxio typography classes. Choose the semantic element that matches the content, then use `size` and `compact` for visual rhythm.
+
+#### When to Use
+
+- Use Body for readable paragraph copy, descriptions, helper text, and supporting content.
+- Use Body when text should follow Maxio body typography without adding heading, label, link, or code semantics.
+- Use compact Body for dense supporting copy where tighter line height improves scannability.
+
+#### When Not to Use
+
+- Do not use Body for page or section titles. Use Heading or Display instead.
+- Do not use Body for form labels, captions, or compact metadata that should have label styling. Use Label instead.
+- Do not use Body to style inline links. Use Link so the text has link semantics and states.
+
+### Sizes
+
+Choose the size that matches the content hierarchy and available space.
+
+| Size | Purpose                        | Usage notes                                                      |
+| :--- | :----------------------------- | :--------------------------------------------------------------- |
+| `xs` | Small supporting text.         | Use for compact details, descriptions, or secondary metadata.    |
+| `sm` | Standard supporting text.      | Use for helper copy, table details, and dense interface content. |
+| `md` | Default body copy.             | Use for readable paragraphs and general page content.            |
+| `lg` | Emphasized readable body copy. | Use sparingly when body copy needs more presence than `md`.      |
+
+### Line Height
+
+- Use the default line height for most body copy and any paragraph that wraps across multiple lines.
+- Use `compact` for dense supporting text, table-adjacent details, and short descriptions inside constrained layouts.
+- Avoid compact line height for long-form reading or content that needs generous scanning space.
+
+### Accessibility
+
+- Choose the semantic element for the content first, then apply Body typography.
+- Use `p` for standalone paragraphs, `span` for inline text, and structural elements such as `li`, `td`, or `figcaption` when those semantics fit.
+- Preserve the document reading order and do not use body text as a replacement for headings, labels, or links.
+- Do not rely on size alone to communicate requiredness, hierarchy, or state.
+- Keep text readable at the selected size, especially for customer-generated content and localized strings.
+
+### Content
+
+- Keep body copy direct and useful; lead with the information the user needs to act.
+- Break long copy into short paragraphs or lists instead of forcing one dense block.
+- Use compact body text for supporting context, not for primary instructions or warnings.
+- Avoid all-caps body copy and decorative punctuation that makes content harder to scan.
+
+### Related
+
+- **[Display](components-typography-display.md)**: use for the largest marketing or page-level title treatments.
+- **[Heading](components-typography-heading.md)**: use for semantic section headings and page structure.
+- **[Label](components-typography-label.md)**: use for form labels, compact captions, and metadata styling.
+- **[Link](components-link.md)**: use for inline or standalone navigation text.
+
+## React
+
+```tsx
+import { Body } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Body } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Body
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `as` | `ElementType` | no | `div` | The component to render as (e.g. `span or div`) | TypeLiteral |
+| `children` | `ReactNode` | yes | - | The content of the label | TypeLiteral |
+| `className` | `string` | no | - | React className prop passed to the component | TypeLiteral |
+| `compact` | `boolean` | no | `false` | Set the body to compact mode - lower line height | TypeLiteral |
+| `id` | `string` | no | - | - | TypeLiteral |
+| `size` | `"sm" \| "md" \| "lg" \| "xs"` | no | `md` | Defines the size of the body text. | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Body for readable page copy, descriptions, helper text, and other paragraph-level content. Prefer semantic elements such as `p` for standalone paragraphs and `span` for inline text.
+
+```tsx
+const Default = () => <Body as="p">{SLOGAN}</Body>;
+```
+
+### Compact
+
+Use compact Body when dense layouts need a tighter line height, such as helper copy, table details, or supporting text inside compact UI surfaces.
+
+```tsx
+const Compact = () => <Body as="p" compact size="sm">Invoice details are synchronized nightly and may take a few minutes to appear in reports.</Body>;
+```

package/dist/skills/maxio-react/references/components-typography-code.md

@@ -0,0 +1,72 @@
+# Code
+
+## Usage Guidelines
+
+### Overview
+
+Code renders short inline code, tokens, file names, identifiers, or values in the Maxio monospace typography style.
+
+#### When to Use
+
+- Use Code for short inline code, identifiers, API fields, file names,
+  environment variables, or values users may need to recognize or copy.
+- Use Code when monospace typography helps distinguish a machine-readable token
+  from surrounding prose.
+- Use semantic `code` markup when the content represents code or a literal value.
+
+#### When Not to Use
+
+- Do not use Code for regular body copy, labels, headings, or decorative
+  emphasis. Use the matching Typography component instead.
+- Do not use Code for long or multi-line examples. Use a dedicated code block
+  pattern that preserves formatting and supports scanning.
+- Do not use Code as the only way to communicate state, severity, or validation.
+
+### Accessibility
+
+- Prefer rendering Code as `code` when the snippet represents code, an
+  identifier, or a literal value.
+- Keep snippets short and readable in the surrounding sentence.
+- Provide enough surrounding text that users understand what the token means.
+- Do not rely on monospace styling alone to communicate meaning.
+
+### Content
+
+- Use exact values, field names, commands, or identifiers that match product and
+  developer-facing copy.
+- Avoid wrapping full sentences or marketing copy in Code.
+- Keep punctuation outside the coded value unless it is part of the value users
+  should read or copy.
+
+## React
+
+```tsx
+import { Code } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Code } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Code
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `as` | `ElementType` | no | `div` | The component to render as (e.g. `span or div`) | TypeLiteral |
+| `children` | `ReactNode` | yes | - | The content of the label | TypeLiteral |
+| `className` | `string` | no | - | React className prop passed to the component | TypeLiteral |
+| `id` | `string` | no | - | - | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Code for short inline snippets such as variable names, API fields, file names, keyboard-like values, or other machine-readable tokens. Render as semantic `code` when the content represents code or a value users may copy.
+
+```tsx
+const Default = () => <Code as="code">billing_cycle_anchor</Code>;
+```

package/dist/skills/maxio-react/references/components-typography-display.md

@@ -0,0 +1,91 @@
+# Display
+
+## Usage Guidelines
+
+### Overview
+
+Display renders prominent brand typography for page-level headlines, hero statements, and other high-emphasis moments.
+
+#### When to Use
+
+- Use Display for a page hero, marketing headline, or other short headline that
+  should carry the strongest visual emphasis.
+- Use Display when the text needs Maxio's display typography but the semantic
+  element should still come from the surrounding page structure.
+
+#### When Not to Use
+
+- Do not use Display for standard section headings. Use Heading instead.
+- Do not use Display for body copy, descriptions, labels, table content, or
+  compact UI text.
+- Do not use Display only to make arbitrary text larger when a semantic heading
+  size or layout change would be clearer.
+
+### Variants
+
+Choose the smallest size that still creates the intended hierarchy.
+
+| Size | Purpose                         | Usage notes                                                               |
+| :--- | :------------------------------ | :------------------------------------------------------------------------ |
+| `sm` | Compact display headline.       | Use when a high-emphasis headline appears in a constrained content area.  |
+| `md` | Standard display headline.      | Use for prominent page or section introductions.                          |
+| `lg` | Highest-emphasis hero headline. | Use sparingly for first-viewport page titles or major marketing messages. |
+
+### Accessibility
+
+- Choose `as` from the document outline, such as `h1` for the primary page title
+  or `h2` for a major section.
+- Do not skip heading levels to achieve a visual size. Use `size` for visual scale instead.
+- Keep Display text concise so it remains readable at large sizes and across
+  responsive layouts.
+- Preserve enough color contrast between display text and the surrounding background.
+
+### Content
+
+- Write short, specific headlines that communicate the page or section purpose.
+- Avoid long paragraphs, legal copy, or dense product details in Display.
+- Keep nearby supporting copy in Body or Heading typography so the visual
+  hierarchy stays clear.
+
+### Related
+
+- **[Heading](components-typography-heading.md)**: use for
+  standard page and section headings.
+- **[Body](components-typography-body.md)**: use for paragraphs
+  and supporting copy.
+- **[Label](components-typography-label.md)**: use for field
+  labels, captions, and compact metadata.
+
+## React
+
+```tsx
+import { Display } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Display } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Display
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `as` | `ElementType` | no | `div` | The component to render as (e.g. `span or div`) | TypeLiteral |
+| `children` | `ReactNode` | yes | - | The content of the label | TypeLiteral |
+| `className` | `string` | no | - | React className prop passed to the component | TypeLiteral |
+| `id` | `string` | no | - | - | TypeLiteral |
+| `size` | `"sm" \| "md" \| "lg"` | no | `md` | Defines the size of the display text | TypeLiteral |
+
+## Stories
+
+### Display
+
+Use Display for the most prominent headline in a page, hero, or marketing section. Keep the semantic element aligned with the document outline, and use the Display size only for visual scale.
+
+```tsx
+const Default = () => <Display as="h1" size="lg">{SLOGAN}</Display>;
+```

package/dist/skills/maxio-react/references/components-typography-heading.md

@@ -0,0 +1,88 @@
+# Heading
+
+## Usage Guidelines
+
+### Overview
+
+Heading is used for page and section titles.
+
+#### When to Use
+
+- Use Heading for page, section, and panel titles that should participate in the document outline.
+- Use Heading when content needs Maxio heading typography and semantic heading markup.
+
+#### When Not to Use
+
+- Do not use Heading for body copy, captions, or helper text. Use Body instead.
+- Do not use Heading for form labels or compact metadata. Use Label instead.
+- Do not use Heading only to make decorative text large. Use Display for non-structural display text.
+
+### Sizes
+
+Heading size sets both the visual style and the rendered heading element.
+
+| Size | Rendered element | Usage notes                            |
+| :--- | :--------------- | :------------------------------------- |
+| `lg` | `h1`             | Page or view title.                    |
+| `md` | `h2`             | Major section title beneath a page.    |
+| `sm` | `h3`             | Subsection, panel, or grouped content. |
+
+### Accessibility
+
+- Keep heading levels in order so the page outline is predictable.
+- Use one `h1` for the primary page or view title when possible.
+- Do not skip heading levels only to change visual size.
+- Keep heading text visible, concise, and specific to the content that follows.
+
+### Content
+
+- Use headings to name the section, not to describe instructions in sentence form.
+- Keep heading copy short enough to scan in dense application layouts.
+- Avoid punctuation unless the heading is a question or includes a proper noun that requires it.
+
+## React
+
+```tsx
+import { Heading } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Heading } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Heading
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `children` | `ReactNode` | yes | - | The content of the label | TypeLiteral |
+| `className` | `string` | no | - | React className prop passed to the component | TypeLiteral |
+| `id` | `string` | no | - | - | TypeLiteral |
+| `size` | `"sm" \| "md" \| "lg"` | no | `sm` | Defines the size of the heading text | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Heading for page, section, and panel titles that should participate in the document outline. Choose the size that matches the heading level: `lg` renders `h1`, `md` renders `h2`, and `sm` renders `h3`.
+
+```tsx
+const Default = () => <Heading>{SECTION_HEADING}</Heading>;
+```
+
+### Heading hierarchy
+
+Use a heading hierarchy to keep page titles, major sections, and subsections easy to scan. Keep heading levels in order so assistive technology users can navigate the page structure predictably.
+
+```tsx
+const HeadingHierarchy = () => (
+  <>
+    <Heading size="lg">Revenue dashboard</Heading>
+    <Heading size="md">Recurring revenue</Heading>
+    <Heading size="sm">Expansion trends</Heading>
+  </>
+);
+```

package/dist/skills/maxio-react/references/components-typography-label.md

@@ -0,0 +1,82 @@
+# Label
+
+## Usage Guidelines
+
+### Overview
+
+Label renders compact Maxio label typography for field labels, captions, table labels, and metadata names.
+
+#### When to Use
+
+- Use Label for compact text that names a nearby value, control, table column, or metadata field.
+- Use Label when the text needs more emphasis than body copy but less hierarchy than Heading.
+- Use Label for repeated UI labels where consistent size and weight help scanning.
+
+#### When Not to Use
+
+- Do not use Label for paragraphs or explanatory copy. Use Body instead.
+- Do not use Label for page, section, or card titles. Use Heading instead.
+- Do not use Label alone to create a complete form field in React. Use form components such as TextField when you need the label, control, helper text, and error state wired together.
+
+### Variants
+
+Choose the smallest size that stays readable in the surrounding layout.
+
+| Variants | Purpose                      | Usage notes                                             |
+| :------- | :--------------------------- | :------------------------------------------------------ |
+| `sm`     | Standard compact label text. | Use for most field labels, captions, and metadata keys. |
+| `xs`     | Dense supporting label text. | Use in tables, chips, tags, and other compact surfaces. |
+
+### Accessibility
+
+- Choose the rendered element for the content's purpose, not only for styling.
+- Use a native `label` element with a `for` and `id` relationship when static HTML labels a form control.
+- In React, prefer complete form components when you need accessible label, helper text, validation, and input associations.
+- Keep label text visible, concise, and specific so it can serve as the accessible name when it labels a control.
+- Do not rely on typography weight or color alone to communicate requiredness, error state, or selection.
+
+### Content
+
+- Use short nouns or noun phrases such as "Customer", "Status", or "Billing contact".
+- Match the label to the value or control it identifies.
+- Avoid sentence-length copy; use Body for descriptions, helper text, and instructions.
+
+### Related
+
+- **[Body](components-typography-body.md)**: use for paragraphs, descriptions, helper text, and longer supporting copy.
+- **[Heading](components-typography-heading.md)**: use for page, section, card, and grouped content titles.
+- **[TextField](components-forms-textfield.md)**: use for React form fields with labels, helper text, and validation behavior.
+
+## React
+
+```tsx
+import { Label } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Label } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Label
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `as` | `ElementType` | no | `div` | The component to render as (e.g. `span or div`) | TypeLiteral |
+| `children` | `ReactNode` | yes | - | The content of the label | TypeLiteral |
+| `className` | `string` | no | - | React className prop passed to the component | TypeLiteral |
+| `id` | `string` | no | - | - | TypeLiteral |
+| `size` | `"sm" \| "xs"` | no | `sm` | Defines the size of the label text | TypeLiteral |
+
+## Stories
+
+### Label
+
+Use Label for compact, medium-weight text that names a nearby value, field, table column, or supporting UI detail. Keep the semantic element aligned with the surrounding content; use form components for fully associated form labels.
+
+```tsx
+const Default = () => <Label as="span" size="sm">{LABEL_TEXT}</Label>;
+```