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

package/dist/skills/maxio-react/references/components-notifications-alert.md

@@ -0,0 +1,103 @@
+# Alert
+
+## Usage Guidelines
+
+### Overview
+
+Alert presents contextual status feedback near the content or workflow it supports. Use it for concise messages that may include a follow-up link or a dismiss action.
+
+#### When to Use
+
+- Use Alert for contextual feedback tied to a specific page section, form, or workflow.
+- Use Alert when the message benefits from a visible sentiment icon, short title, optional supporting copy, or follow-up link.
+- Use Alert for status updates that can sit near the content they affect, such as pending verification, saved settings, warnings, or recoverable errors.
+
+#### When Not to Use
+
+- Do not use Alert for account-wide or system-wide announcements. Use Banner instead.
+- Do not use Alert for inline field validation. Use the form field error state and error message instead.
+- Do not use Alert for brief confirmation messages that should disappear automatically. Use a toast or notification pattern when available.
+
+### Variants
+
+Choose the sentiment that matches the message tone and user urgency. The default `info` sentiment uses the base `.maxio-alert` styling without an additional modifier class.
+
+| Variants  | Purpose                                | Usage notes                                                            |
+| :-------- | :------------------------------------- | :--------------------------------------------------------------------- |
+| `info`    | Neutral status or contextual guidance. | Use for non-blocking information, pending work, or helpful next steps. |
+| `success` | Positive completion feedback.          | Use when an action completed successfully and users may continue.      |
+| `warning` | Attention-needed status.               | Use when users should review something before continuing.              |
+| `danger`  | Error or high-risk status.             | Use when a problem prevents progress or requires corrective action.    |
+
+### Behavior
+
+- **Mouse and touch**: link activation follows normal Link behavior. The dismiss button calls `onDismiss` when provided.
+- **Keyboard**: links and dismiss buttons are included in the Tab order and activate with native keyboard behavior.
+- **Focus management**: when dismissing an alert, move focus to a sensible nearby control if removing the alert would otherwise leave focus in an unstable place.
+- **Dismissal or persistence**: include dismissal only for messages the user can safely hide. Keep required, blocking, or unresolved messages visible until the condition changes.
+- **Layout**: use `display="inline"` for compact messages and `display="block"` when the title, message, and link need stacked spacing.
+
+### Accessibility
+
+- Treat the alert as visible status content near the affected UI. Add a live region outside the component only when the message appears dynamically and must be announced.
+- Keep the sentiment icon decorative with `aria-hidden="true"` so the title and message carry the accessible meaning.
+- Provide a clear accessible name for the dismiss button. The React component uses `aria-label="Dismiss Notification"`.
+- Do not rely on color or icon shape alone to communicate severity. Use the title and message to state the condition.
+- Use a descriptive link label that explains the destination or next step.
+
+### Content
+
+- Lead with the status or condition: "ACH verification is pending", "Payment method updated", "Invoice could not be sent".
+- Keep the message to one short sentence when possible.
+- Use link text for a concrete next step, such as "View verification status" or "Update payment method".
+- Avoid repeating the sentiment in copy when the title can describe the outcome directly.
+
+### Related
+
+- **[Banner](components-notifications-banner.md)**: use for page-level, account-level, or system-wide announcements.
+- **[TextField](components-forms-textfield.md)**: use field-level error messaging for validation tied to one input.
+
+## React
+
+```tsx
+import { Alert } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Alert } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Alert
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `children` | `string` | no | - | Displays alert message | TypeLiteral |
+| `className` | `string` | no | - | Additional CSS class name to be applied to the alert | TypeLiteral |
+| `display` | `"inline" \| "block"` | no | `inline` | Changes the display of the alert. Defaults to `inline` | TypeLiteral |
+| `href` | `string` | no | - | Sets the link target - `href` must be present to include a link | TypeLiteral |
+| `linkExternal` | `boolean` | no | - | Sets the link target to '_blank' | TypeLiteral |
+| `linkText` | `string` | no | - | Sets the link text - `linkText` must be present to include a link | TypeLiteral |
+| `onDismiss` | `(() => void)` | no | - | A callback function to dismiss the alert | TypeLiteral |
+| `sentiment` | `"danger" \| "info" \| "success" \| "warning"` | no | `info` | Changes the color and icon of the alert. Component sentiment defaults to `info` | TypeLiteral |
+| `title` | `string` | no | - | Displays alert title | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use Alert for contextual feedback inside a page section or workflow. Choose the sentiment that matches the message, keep the copy short, and include a dismiss action only when the alert is not required for the user to continue.
+
+```tsx
+const Default = () => <Alert
+    title="ACH verification is pending"
+    onDismiss={action('Alert dismissed')}
+    linkText="View verification status"
+    linkExternal={false}
+    href="/settings/billing"
+    sentiment="info"
+    display="inline">We will notify you when micro-deposits are ready to confirm.</Alert>;
+```

package/dist/skills/maxio-react/references/components-notifications-banner.md

@@ -0,0 +1,173 @@
+# Banner
+
+## Usage Guidelines
+
+### Overview
+
+Banner communicates important page-level status, account, or product messages that should be noticed before the user continues their workflow.
+
+#### When to Use
+
+- Use Banner for important page-level notices that affect an account, product area, or workflow.
+- Use Banner when the message should stay visible until the condition changes or the user dismisses a temporary notice.
+- Use Banner when a message needs a sentiment icon, short title, message, and optional next-step link.
+
+#### When Not to Use
+
+- Do not use Banner for lightweight confirmations that can disappear automatically. Use Toast instead.
+- Do not use Banner for field-level validation or inline form guidance. Use the relevant form component helper or error state instead.
+- Do not use Banner as a persistent navigation or marketing surface.
+
+### Variants
+
+Choose the sentiment that matches the urgency and consequence of the message.
+
+| Sentiment | Purpose                          | Usage notes                                                                 |
+| :-------- | :------------------------------- | :-------------------------------------------------------------------------- |
+| `info`    | Neutral account or product note. | Use for reminders, setup prompts, and informational status.                 |
+| `success` | Completed positive state.        | Use when confirmation must stay visible beyond a transient toast.           |
+| `warning` | Attention needed soon.           | Use for recoverable issues, missing setup, or risk that does not block use. |
+| `danger`  | Immediate critical attention.    | Use for broken connections, failed required setup, or high-impact errors.   |
+
+### Behavior
+
+- **Mouse and touch**: links navigate to the provided destination; the dismiss button runs `onDismiss` when present.
+- **Keyboard**: links and dismiss buttons follow native keyboard behavior through the underlying Link and IconButton components.
+- **Focus management**: when a banner is dismissed, move focus only if removing the banner would otherwise strand keyboard focus.
+- **Dismissal or persistence**: keep required status, error, and compliance messages persistent. Add dismissal only for temporary guidance.
+
+### Accessibility
+
+- Use the banner for important page-level status updates and keep the message concise enough to be announced clearly.
+- Keep the visible title and message meaningful without relying on the sentiment icon or color alone.
+- Use a specific accessible name for dismiss controls when building equivalent HTML.
+- Keep links descriptive so the destination or next step is clear out of context.
+- Avoid stacking multiple assertive live-region banners unless each message truly needs immediate announcement.
+
+### Content
+
+- Lead with the condition or outcome: "Billing reminder", "Domain verification needed", "Collections interrupted".
+- Keep messages direct and actionable. Include a link only when there is a clear next step.
+- Avoid vague titles such as "Notice" or "Update".
+- Use dismissible banners for guidance users can safely hide, not for required account or error states.
+
+### Related
+
+- **[Toast](components-notifications-toast.md)**: use for transient success, warning, or error feedback that can disappear automatically.
+- **[Alert](components-notifications-alert.md)**: use for contextual notices inside a smaller surface when a full-width banner is too prominent.
+- **[Link](components-link.md)**: use for inline navigation outside the banner pattern.
+
+## React
+
+```tsx
+import { Banner } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Banner } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Banner
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `children` | `string` | yes | - | Displays banner message | TypeLiteral |
+| `className` | `string` | no | - | Additional CSS class name to be applied to the banner | TypeLiteral |
+| `display` | `"inline" \| "block"` | no | `inline` | Changes the display of the banner. Defaults to `inline` | TypeLiteral |
+| `href` | `string` | no | - | Sets the link target - `href` must be present to include a link | TypeLiteral |
+| `linkExternal` | `boolean` | no | - | Sets the link target to '_blank' | TypeLiteral |
+| `linkText` | `string` | no | - | Sets the link text - `linkText` must be present to include a link | TypeLiteral |
+| `onDismiss` | `(() => void)` | no | - | A callback function to dismiss the banner | TypeLiteral |
+| `sentiment` | `"danger" \| "info" \| "success" \| "warning"` | no | `info` | Changes the color and icon of the banner. Component sentiment defaults to `info` | TypeLiteral |
+| `title` | `string` | no | - | Displays banner title | TypeLiteral |
+
+## Stories
+
+### Default
+
+Use an info banner for neutral page-level notices that should be visible before the user continues.
+
+```tsx
+const Default = (args) => {
+  const bannerProps = {
+    ...args,
+    onDismiss: args.onDismiss,
+  };
+
+  return <Banner {...bannerProps}></Banner>;
+};
+```
+
+### Success
+
+Use success when a completed account or workflow state still needs visible confirmation outside a toast.
+
+```tsx
+const Success = () => <Banner
+    title="Payment method verified"
+    onDismiss={undefined}
+    linkText={undefined}
+    linkExternal={false}
+    href={undefined}
+    sentiment="success">Your payment method was verified and future invoices are ready.</Banner>;
+```
+
+### Warning
+
+Use warning for messages that need attention soon but do not block the current page.
+
+```tsx
+const Warning = () => <Banner
+    title="Domain verification needed"
+    onDismiss={undefined}
+    linkText="Verify domain"
+    linkExternal={false}
+    href="/settings/email-domain"
+    sentiment="warning">Some invoice emails are paused until your sending domain is verified.</Banner>;
+```
+
+### Danger
+
+Use danger for critical account or product states that need immediate attention before work can continue confidently.
+
+```tsx
+const Danger = () => <Banner
+    title="Collections interrupted"
+    onDismiss={undefined}
+    linkText="Reconnect gateway"
+    linkExternal={false}
+    href="/settings/payment-gateways"
+    sentiment="danger">Automatic collections are disabled because your payment gateway is disconnected.</Banner>;
+```
+
+### Dismissible
+
+Use a dismissible banner only for temporary messages the user can safely hide without losing required status or error context.
+
+```tsx
+const Dismissible = () => <Banner
+    title="New metrics available"
+    onDismiss={action('Banner dismissed')}
+    linkText="Review dashboard"
+    linkExternal={false}
+    href="/analytics">The dashboard has been updated with new subscription metrics.</Banner>;
+```
+
+### Block Layout
+
+Use block display when title, message, and link text need more room to wrap clearly in narrow or content-heavy layouts.
+
+```tsx
+const BlockLayout = () => <Banner
+    title="Manual review recommended"
+    onDismiss={undefined}
+    linkText="Open failed invoices"
+    linkExternal={false}
+    href="/invoices/failed"
+    display="block"
+    sentiment="warning">Review each failed invoice before retrying collection so customers do not receive duplicate notices.</Banner>;
+```

package/dist/skills/maxio-react/references/components-notifications-toast.md

@@ -0,0 +1,155 @@
+# Toast
+
+## Usage Guidelines
+
+### Overview
+
+Toast displays short-lived feedback about a background or just-completed action.
+
+#### When to Use
+
+- Use Toast to confirm that a user action completed successfully without interrupting the workflow.
+- Use Toast for short, time-sensitive updates that are useful immediately but do not need to remain on the page.
+- Use Toast for background process feedback when the user can continue working.
+
+#### When Not to Use
+
+- Do not use Toast for information the user must review before continuing. Use Alert or Banner instead.
+- Do not use Toast for validation errors tied to a form field. Place the error with the field.
+- Do not use Toast for persistent system status, onboarding instructions, or long-form content.
+
+### Sentiments
+
+Use sentiment to match the tone of the message. The sentiment changes the icon color and icon choice.
+
+| Sentiment | Purpose                           | Usage notes                                                                 |
+| :-------- | :-------------------------------- | :-------------------------------------------------------------------------- |
+| `info`    | Neutral update or default notice. | Use for general status changes or background updates.                       |
+| `success` | Completed or successful outcome.  | Use after saving, creating, importing, or completing a requested action.    |
+| `warning` | Recoverable issue or caution.     | Use when the user may need to check something but can keep working.         |
+| `danger`  | Failed action or important error. | Use for failures that do not block the entire page or require a modal flow. |
+
+### Behavior
+
+- **Mouse and touch**: users can dismiss closable toasts with the dismiss button.
+- **Keyboard**: the dismiss button follows native button keyboard behavior with Tab, Enter, and Space.
+- **Focus management**: do not move focus into a toast automatically. Keep focus in the user’s current workflow.
+- **Queueing**: use `ToastQueue` to limit visible toasts and preserve ordering.
+- **Dismissal or persistence**: keep toasts closable by default. Use timeouts only when the message can safely disappear.
+
+### Accessibility
+
+- Use the React toast providers so React Aria can create the toast region and announcement semantics.
+- Keep toast copy short enough to be announced clearly.
+- Provide a visible title, a message, or both. Do not rely on the sentiment icon alone to communicate the outcome.
+- Give the dismiss control an accessible name.
+- Do not move keyboard focus to transient feedback unless the toast contains a critical recovery action.
+
+### Content
+
+- Lead with the outcome: "Invoice created", "Payment failed", or "Customer imported".
+- Keep the message to one concise sentence when possible.
+- Use links only for a direct follow-up action, such as viewing the created object.
+- Avoid stacking multiple toasts for the same event. Update the existing flow or use page-level feedback instead.
+
+### Related
+
+- **[Alert](components-notifications-alert.md)**: use for contextual page feedback that should stay near related content.
+- **[Banner](components-notifications-banner.md)**: use for important page-level or system-level messages.
+
+## React
+
+```tsx
+import {
+  GlobalToastProvider,
+  ToastQueue,
+  useToast,
+} from '@maxio-com/react-ui-components';
+```
+
+### Provider Setup
+
+Create a `ToastQueue` and place `GlobalToastProvider` once near the application root.
+
+```tsx
+const toastQueue = new ToastQueue({ maxVisibleToasts: 5 });
+
+<GlobalToastProvider toastQueue={toastQueue}>
+  <App />
+</GlobalToastProvider>;
+```
+
+### Triggering Toasts
+
+Use `useToast` inside the provider tree. Keep the toast content short and reserve links for direct follow-up actions.
+
+```tsx
+const { addToast, removeAllToasts } = useToast();
+
+addToast({
+  title: 'Invoice created',
+  message: 'The invoice is ready to review and send.',
+  link: {
+    text: 'View invoice',
+    href: '/invoices/123',
+  },
+  sentiment: 'success',
+});
+```
+
+### Legacy Provider
+
+`ToastProvider` is still available for existing implementations, but new work should use `GlobalToastProvider`, `ToastQueue`, and `useToast`.
+
+## Imports
+
+```tsx
+import { Button, GlobalToastProvider, Toast, ToastProvider } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Toast
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `className` | `string` | no | - | Additional classes to apply to the ToastRegion | ToastRegionProps |
+| `state` | `ToastState<ToastContent>` | yes | - | The state for the toast provider | ToastRegionProps |
+| `toast` | `QueuedToast<ToastContent>` | yes | - | To add content to a toast | ToastProps |
+
+## Stories
+
+### Default
+
+Use the global toast API for new work. Place `GlobalToastProvider` once near the application root, then call `useToast().addToast(...)` from flows that need transient feedback.
+
+```tsx
+const Default = () => {
+  const toastQueue = new ToastQueue({ maxVisibleToasts: 5 });
+  return (
+    <GlobalToastProvider toastQueue={toastQueue}>
+      <GlobalToastTrigger />
+    </GlobalToastProvider>
+  );
+};
+```
+
+### Visible Toast
+
+Use this story to inspect the toast anatomy. Product code should create this state by adding content to a `ToastQueue`, not by rendering `Toast` directly.
+
+```tsx
+const VisibleToast = () => <VisibleToastExample />;
+```
+
+### Legacy Toast Provider
+
+Legacy `ToastProvider` remains available for existing implementations. Use `GlobalToastProvider` and `useToast` for new screens.
+
+```tsx
+const LegacyToastProvider = () => {
+  return (
+    <ToastProvider>{(state) => <ToastTrigger state={state} />}</ToastProvider>
+  );
+};
+```

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

@@ -0,0 +1,115 @@
+# Pagination
+
+## Usage Guidelines
+
+### Overview
+
+Use Pagination to help users move through a paged dataset and adjust how many rows or records are shown at once.
+
+#### When to Use
+
+- Use Pagination when a table, activity feed, or search result list is split across pages.
+- Use Pagination when users need to change the number of records shown per page.
+- Use manual page input for very large result sets where a page select would create too many options.
+
+#### When Not to Use
+
+- Do not use Pagination for short lists where all results can be scanned comfortably on one page.
+- Do not use Pagination for progressive loading or continuous feeds. Use a loading pattern that matches that experience instead.
+- Do not use Pagination without updating the connected dataset when page or page size changes.
+
+### Behavior
+
+- **Mouse and touch**: users can choose an items-per-page value, choose or type a page number, and move one page at a time with previous and next buttons.
+- **Keyboard**: the selects, manual page input, and navigation buttons are reachable in tab order. Native selects, inputs, and buttons keep their browser keyboard behavior.
+- **Focus management**: focus stays on the control the user activated while the paged content updates.
+- **State changes**: changing items per page resets the current page to `1`; changing page reports the selected page and current page size through `onChange`.
+- **Manual input**: typed values are validated on blur or Enter and clamped to the available page range.
+
+### Accessibility
+
+- Use semantic form controls for the items-per-page selector and page selector or page input.
+- Keep visible labels for items per page and descriptive accessible names for page selection, previous, and next controls.
+- Disable previous and next controls when users are already on the first or last page.
+- Keep the displayed item range, total item count, and total page count accurate after every dataset update.
+- Do not rely on the chevron icons alone; preserve accessible button names for previous and next navigation.
+
+### Related
+
+- **[DataTable](components-data-table.md)**: use with Pagination when tabular data needs paging, sorting, or selection.
+- **[Select](components-forms-select.md)**: use for standalone option selection outside of a paging control.
+- **[TextInput](deprecated-textinput.md)**: use for standalone typed values outside of a paging control.
+
+## React
+
+```tsx
+import { Pagination } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+Pagination manages its selected page and page size internally, then reports changes through `onChange`.
+Use `onChange` to request or filter the dataset that appears next to the component.
+
+```tsx
+const [pageInfo, setPageInfo] = React.useState({
+  currentPage: 1,
+  itemsPerPage: 10,
+});
+
+<Pagination
+  totalItems={125}
+  pageSizeOptions={[10, 25, 50, 100]}
+  currentPage={pageInfo.currentPage}
+  itemsPerPage={pageInfo.itemsPerPage}
+  onChange={setPageInfo}
+/>;
+```
+
+## Imports
+
+```tsx
+import { Pagination } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Pagination
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `currentPage` | `number` | no | `1` | Current page index | TypeLiteral |
+| `itemsPerPage` | `number` | no | `30` | Number of items shown per page | TypeLiteral |
+| `manualPageInput` | `boolean` | no | `false` | Use manual page input instead of dropdown for extremely large datasets | TypeLiteral |
+| `onChange` | `((pageInfo: PageInfo) => void)` | no | - | Export of currentPage and itemsPerPage data as an object | TypeLiteral |
+| `pageSizeOptions` | `number[]` | yes | - | Options for how many items are shown per page | TypeLiteral |
+| `size` | `"sm" \| "md" \| "lg"` | no | `md` | Modifier for the size of Pagination component | TypeLiteral |
+| `totalItems` | `number` | no | `0` | Total items returned from the API | TypeLiteral |
+
+## Stories
+
+### Pagination
+
+Use Pagination when a table or list has more results than should appear on one screen. Keep the page size choices short and update the adjacent dataset when `onChange` reports a new page or item count.
+
+```tsx
+const Default = () => <Pagination
+    totalItems={125}
+    pageSizeOptions={[10, 25, 50, 100]}
+    itemsPerPage={10}
+    currentPage={1} />;
+```
+
+### Pagination with manual page input
+
+Use manual page input when the number of pages is large enough that rendering every page as a select option would hurt browser performance. Validate typed values and clamp them to the available page range.
+
+```tsx
+const WithManualPageInput = () => <Pagination
+    totalItems={150}
+    pageSizeOptions={[10, 25, 50, 100]}
+    itemsPerPage={10}
+    currentPage={5}
+    size="lg"
+    manualPageInput />;
+```