npm - @maxio-com/react-ui-components - Versions diffs - 9.16.0 → 9.17.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (56) hide show

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

@@ -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 ADDED Viewed

@@ -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>;
+};
+```

package/dist/skills/maxio-react/references/components-data-table.md ADDED Viewed

@@ -0,0 +1,344 @@
+# DataTable
+## Usage Guidelines
+### Overview
+Displays TanStack Table data with Maxio table semantics, styling, and common interactions such as sorting, row selection, expansion, row actions, and pinned columns.
+DataTable uses TanStack Table for column, row, sorting, selection, expansion,
+and pinning state while rendering Maxio table markup and classes.
+#### When to Use
+- Use DataTable for tabular customer, invoice, subscription, or finance data.
+- Use DataTable when rows need sorting, selection, expansion, row actions, or pinned columns.
+- Use DataTable when a table needs consistent Maxio styling and accessible table semantics.
+- Use DataTable when the product surface already defines data and columns with TanStack Table.
+#### When Not to Use
+- Do not use DataTable for simple key-value summaries or static comparison tables. Use primitive table components or layout primitives instead.
+- Do not use DataTable for non-tabular card, list, or navigation layouts.
+- Do not hand-code sorting, selection, expansion, or pinning behavior outside TanStack Table.
+### Configuration
+DataTable renders the Maxio table shell around TanStack data and column
+definitions. Configure cell content, alignment, widths, grouped headers,
+sorting behavior, and pinned columns through TanStack column definitions and
+table state.
+| Option                | Purpose                                                  | Usage notes                                                                     |
+| :-------------------- | :------------------------------------------------------- | :------------------------------------------------------------------------------ |
+| `enableSorting`       | Allows sortable columns to cycle sort state.             | Configure per-column sorting behavior in the TanStack column definition.        |
+| `enableRowSelection`  | Adds checkbox controls for selecting rows.               | Use controlled row selection state when selections drive actions outside table. |
+| `enableExpanding`     | Adds row expansion controls.                             | Use `rowsOnly` when the table should not show an expand-all header control.     |
+| `actions`             | Adds a pinned row actions cell.                          | Use `IconButton` size `sm` for icon-only row actions.                           |
+| `onRowAction`         | Makes each parent row activate a primary row action.     | Keep nested controls interactive without triggering the row action.             |
+| `SubRowComponent`     | Renders custom expanded content connected to parent row. | Keep expanded content concise and related to the row.                           |
+| `state.columnPinning` | Pins important columns to the left or right.             | Set numeric column `size` values when multiple columns are pinned on one side.  |
+### Behavior
+- **Mouse and touch**: header controls sort columns, row checkboxes select rows, expand controls show nested or custom row content, and row action controls activate row-specific commands.
+- **Keyboard**: interactive controls are reachable with Tab. Buttons and checkboxes keep their native keyboard behavior. Actionable rows receive keyboard focus.
+- **Focus management**: keep focus indicators visible on row controls, sortable headers, action buttons, links, and actionable rows.
+- **Controlled state**: use TanStack Table state props when sorting, selection, expansion, or column pinning must be controlled by the product surface.
+- **Column pinning**: set numeric `size` values for multiple pinned columns on the same side so TanStack can calculate sticky offsets correctly.
+### Accessibility
+- Use semantic `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>` markup.
+- Keep sortable header state synchronized with `aria-sort`.
+- Give selection, expansion, and row action controls clear accessible names.
+- Label actionable rows from visible row content with `aria-labelledby`.
+- Preserve table semantics when rendering links, tags, buttons, or custom content inside cells.
+- Do not rely on color alone to communicate sorted, selected, expanded, or actionable state.
+### Content
+- Use concise column headers that match the data users need to compare.
+- Put units in headers when they apply to the whole column, such as "Home Revenue (USD)".
+- Keep row action labels specific to the command or provide a descriptive `aria-label` for icon-only actions.
+- Prefer scannable cell values over long prose. Use expandable custom rows for secondary detail.
+### Related
+- **[Link](components-link.md)**: use for plain text navigation inside table cells.
+- **[IconButton](components-buttons-iconbutton.md)**: use for icon-only row actions.
+- **[Checkbox](components-forms-checkbox.md)**: use for custom selection controls outside DataTable.
+## React
+```tsx
+import { DataTable } from '@maxio-com/react-ui-components';
+import { createColumnHelper } from '@tanstack/react-table';
+```
+### Column Configuration
+Define table data and columns with TanStack Table, then pass those columns and
+rows to DataTable.
+```tsx
+type Customer = {
+  name: string;
+  accountNumber: string;
+  homeRevenue: number;
+};
+const columnHelper = createColumnHelper<Customer>();
+const columns = [
+  columnHelper.accessor('name', {
+    header: 'Name',
+    cell: (info) => info.getValue(),
+  }),
+  columnHelper.accessor('accountNumber', {
+    header: 'Account #',
+    cell: (info) => info.getValue(),
+  }),
+  columnHelper.accessor('homeRevenue', {
+    header: 'Home Revenue (USD)',
+    cell: (info) => info.getValue(),
+  }),
+];
+<DataTable columns={columns} data={customers} />;
+```
+Use the column `meta` field for Maxio-specific presentation details.
+```tsx
+columnHelper.accessor('homeRevenue', {
+  header: 'Home Revenue (USD)',
+  cell: (info) => info.getValue(),
+  meta: {
+    align: 'right',
+    width: '12rem',
+  },
+});
+```
+### State Management
+DataTable can let TanStack Table manage interaction state internally. Control
+state when sorting, selection, expansion, or pinned columns need to drive
+application behavior outside the table.
+```tsx
+<DataTable
+  columns={columns}
+  data={customers}
+  enableSorting
+  enableRowSelection
+  state={{
+    columnPinning: {
+      left: ['name', 'accountNumber'],
+      right: ['homeRevenue'],
+    },
+  }}
+  onSort={setSorting}
+  onSelect={setRowSelection}
+  onExpand={setExpanded}
+/>
+```
+### Expansion
+Use nested `subRows` data for child records with the same shape as their parent
+row. Use `SubRowComponent` when expanded content needs a custom layout that is
+still attached to the row.
+```tsx
+<DataTable
+  columns={columns}
+  data={customers}
+  enableExpanding="rowsOnly"
+  SubRowComponent={({ original }) => <CustomerDetails customer={original} />}
+/>
+```
+## Imports
+```tsx
+import {
+    DataTable,
+    HeaderCell,
+    Icon,
+    IconButton,
+    Link,
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableRow,
+} from "@maxio-com/react-ui-components";
+```
+## Prop Types
+### DataTable
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `actions` | `((row: Row<TData>, table: Table<TData>) => ReactNode)` | no | - | render custom actions cell content | TypeLiteral |
+| `actionsColumnSize` | `number` | no | - | width (in px) of the actions column; defaults to 40 | TypeLiteral |
+| `aggregationFns` | `Record<string, AggregationFn<any>>` | no | - | - | TypeLiteral |
+| `align` | `"left" \| "right"` | no | - | - | TypeLiteral |
+| `enableExpanding` | `boolean \| "rowsOnly"` | no | - | Enable nested row expansion. Include `'rowsOnly'` for row-level toggles without group expand/collapse header control. | TypeLiteral |
+| `filterFns` | `Record<string, FilterFn<any>>` | no | - | - | TypeLiteral |
+| `isLoading` | `boolean` | no | - | - | TypeLiteral |
+| `onExpand` | `((expanded: ExpandedState) => void)` | no | - | function to peek into expanding state changes | TypeLiteral |
+| `onRowAction` | `((row: Row<TData>) => void)` | no | - | function called with the pressed row | TypeLiteral |
+| `onSelect` | `((selected: RowSelectionState) => void)` | no | - | function to peek into selection state changes | TypeLiteral |
+| `onSort` | `((selected: SortingState) => void)` | no | - | function to peek into sorting state changes | TypeLiteral |
+| `pattern` | `boolean` | no | - | - | TypeLiteral |
+| `size` | `"sm" \| "md" \| "lg"` | no | `md` | - | TypeLiteral |
+| `sortingFns` | `Record<string, SortingFn<any>>` | no | - | - | TypeLiteral |
+| `SubRowComponent` | `((row: Row<TData>) => ReactNode)` | no | - | - | TypeLiteral |
+## Stories
+### Default
+Use DataTable when a data set needs table semantics plus common interactions such as sorting, row selection, nested expansion, custom row actions, and pinned action or control columns.
+```tsx
+const Default = () => <DataTable
+    enableSorting
+    enableRowSelection
+    enableExpanding
+    data={customRowsData}
+    columns={customRowsColumns}
+    onRowAction={logRowAction}
+    actions={rowActions('ellipsis')} />;
+```
+### Sorting
+Use sorting when users need to compare rows by one or more column values. Sortable headers cycle through ascending, descending, and unsorted states.
+```tsx
+const Sorting = () => <DataTable enableSorting />;
+```
+### Selecting
+Use row selection when users need to choose individual rows or select all rows in the current table state for a follow-up action.
+```tsx
+const Selecting = () => <DataTable enableRowSelection />;
+```
+### Nested Rows
+Use nested rows when child records share the same shape as their parent row. Include `subRows` on the data and enable expansion controls.
+```tsx
+const NestedRows = () => <DataTable enableExpanding />;
+```
+### Custom Rows
+Use custom rows when an expanded row needs richer content than the standard column layout while remaining connected to the parent row.
+```tsx
+const CustomRows = () => <DataTable
+    data={customRowsData}
+    columns={customRowsColumns}
+    actions={rowActions()}
+    SubRowComponent={ExpandedBio}
+    enableExpanding />;
+```
+### Actions
+Use row actions for controls scoped to a single row. The actions cell is pinned to the right so those controls remain available while scrolling.
+```tsx
+const Actions = () => <DataTable data={customerData} columns={customerColumns} actions={rowActions()} />;
+```
+### Row Action
+Use row action behavior when the whole row should activate a primary row destination or action while preserving keyboard access.
+```tsx
+const RowAction = () => <DataTable data={customerData} columns={customerColumns} onRowAction={logRowAction} />;
+```
+### Components
+Use component cells when mapped values need Maxio components such as links, tags, or other inline display elements.
+```tsx
+const Components = () => <DataTable pattern size="lg" />;
+```
+### Header Groups
+Use header groups when related columns need a shared parent heading above their individual column headers.
+```tsx
+const HeaderGroups = () => <DataTable />;
+```
+### Column Pinning
+Use column pinning when important identifying columns or action columns must stay visible while the table scrolls horizontally.
+```tsx
+const ColumnPinning = () => <div style={{ overflowX: 'auto' }}>
+    <DataTable
+        enableRowSelection
+        data={customerData}
+        columns={pinningDemoColumns}
+        actions={rowActions()}
+        state={{
+          columnPinning: {
+            left: ['Name', 'Number'],
+            right: ['Home Revenue Total (USD)'],
+          },
+        }} />
+</div>;
+```
+### Custom
+Use the primitive table components only for simple static tables that do not need sorting, selection, expansion, pinning, or TanStack Table state.
+```tsx
+const Custom = () => (
+  <Table>
+    <TableHead>
+      <TableRow isHeader>
+        <HeaderCell colSpan={2}>Financial Summary</HeaderCell>
+      </TableRow>
+      <TableRow isHeader>
+        <HeaderCell></HeaderCell>
+        <HeaderCell>USD</HeaderCell>
+      </TableRow>
+    </TableHead>
+    <TableBody>
+      <TableRow>
+        <TableCell>Total Transactions:</TableCell>
+        <TableCell>28,000.00</TableCell>
+      </TableRow>
+      <TableRow>
+        <TableCell>Total Revenue Scheduled:</TableCell>
+        <TableCell>28,000.00</TableCell>
+      </TableRow>
+      <TableRow>
+        <TableCell>Total Invoice Line Items Scheduled:</TableCell>
+        <TableCell>28,000.00</TableCell>
+      </TableRow>
+      <TableRow>
+        <TableCell>Total Open Balance:</TableCell>
+        <TableCell>7,437.00</TableCell>
+      </TableRow>
+    </TableBody>
+  </Table>
+);
+```