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

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

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

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

@@ -0,0 +1,293 @@
+# Drawer
+
+## Usage Guidelines
+
+### Overview
+
+#### When to Use
+
+- Use Drawer for focused tasks that need more space than a Popover, such as forms, settings, or detail views.
+- Use Drawer when the task should temporarily block interaction with the rest of the page.
+- Use with DialogTrigger for uncontrolled usage, or pair `open`/`onOpenChange` with your own state for controlled usage.
+
+#### When Not to Use
+
+- Do not use Drawer for brief explanatory content or a small set of actions. Use Popover instead.
+- Do not use Drawer for page-level navigation. Use SideNav instead.
+- Do not use Drawer when the task is the primary reason the user is on the page. Use a dedicated page instead.
+
+### Behavior
+
+- **Mouse and touch**: clicking the backdrop or the close button dismisses the drawer when `backdrop` allows it.
+- **Keyboard**: Escape dismisses the drawer. Tab and Shift+Tab cycle focus within the drawer while it is open.
+- **Focus management**: focus moves into the drawer on open and returns to the trigger on close, handled by the underlying React Aria `Modal`/`Dialog`.
+- **Placement**: use `placement` to slide the drawer in from the `left`, `right`, `top`, or `bottom` edge of the viewport.
+- **Sizing**: use `size` to control the drawer's width (left/right) or height (top/bottom); `full` spans the entire viewport dimension.
+- **Backdrop**: use `backdrop="dim"` for a scrim behind the drawer, or `backdrop="none"` when the surrounding context should remain fully visible.
+
+### Accessibility
+
+- The drawer renders with `role="dialog"` and is labeled by `title` automatically via `aria-labelledby`.
+- Always provide a `title`; it is the drawer's accessible name and its visible heading.
+- Use `description` for supporting context below the title rather than cramming it into `title`.
+- The close button has a built-in "Close" accessible name; do not remove it as the only dismissal path when `backdrop="none"`.
+- Keep focus indicators visible on interactive elements inside the drawer.
+
+### Content
+
+- Keep `title` short and specific to the task, such as "Configure Custom Pricing" rather than "Settings".
+- Use `description` for a single line of secondary context, such as a category or breadcrumb-style label.
+- Put primary and secondary actions in `footer` rather than at the end of the scrollable body.
+- Keep body content scannable; long-form content should still fit the drawer's fixed width or height.
+
+### Related
+
+- **[Popover](components-popover.md)**: use for lighter-weight, anchored content that doesn't need to block the page.
+- **[Button](components-buttons-button.md)**: use for the trigger that opens the drawer and for footer actions.
+
+## React
+
+```tsx
+import { Drawer, DialogTrigger } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Body, Button, DialogTrigger, Drawer } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Drawer
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `backdrop` | `"none" \| "dim"` | no | `dim` | - | DrawerProps |
+| `className` | `string` | no | - | - | DrawerProps |
+| `description` | `string` | no | - | - | DrawerProps |
+| `footer` | `ReactNode` | no | - | - | DrawerProps |
+| `onOpenChange` | `((open: boolean) => void)` | no | - | - | DrawerProps |
+| `open` | `boolean` | no | - | - | DrawerProps |
+| `placement` | `"left" \| "right" \| "top" \| "bottom"` | no | `right` | - | DrawerProps |
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | no | `md` | - | DrawerProps |
+| `title` | `string` | yes | - | - | DrawerProps |
+
+## Stories
+
+### Default
+
+```tsx
+const Default = () => <DialogTrigger>
+    <Button variant="secondary" size="md">Open Drawer
+              </Button>
+    <Drawer placement="right" size="md" backdrop="dim" title="Drawer title">
+        <Body size="sm">{LOREM}</Body>
+    </Drawer>
+</DialogTrigger>;
+```
+
+### Controlled (external state)
+
+```tsx
+const Controlled = () => {
+    const [open, setOpen] = React.useState(false);
+
+    return (
+        <>
+            <Button variant="secondary" size="md" onClick={() => setOpen(true)}>Open Drawer
+                        </Button>
+            <Drawer
+                placement="right"
+                size="md"
+                backdrop="dim"
+                title="Drawer title"
+                open={open}
+                onOpenChange={setOpen}>
+                <Body size="sm">{LOREM}</Body>
+            </Drawer>
+        </>
+    );
+};
+```
+
+### With footer
+
+```tsx
+const WithFooter = () => {
+    const [open, setOpen] = React.useState(false);
+
+    return (
+        <>
+            <Button variant="secondary" size="md" onClick={() => setOpen(true)}>Open Drawer
+                        </Button>
+            <Drawer
+                placement="right"
+                size="md"
+                backdrop="dim"
+                open={open}
+                onOpenChange={setOpen}
+                title="Settings"
+                footer={
+                  <>
+                    <Button
+                      variant="primary"
+                      size="md"
+                      onClick={() => setOpen(false)}
+                    >
+                      Save
+                    </Button>
+                    <Button
+                      variant="secondary"
+                      size="md"
+                      onClick={() => setOpen(false)}
+                    >
+                      Cancel
+                    </Button>
+                  </>
+                }>
+                <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+                    {PARAGRAPHS.map((p, i) => (
+                      <Body key={i} size="sm">
+                        {p}
+                      </Body>
+                    ))}
+                </div>
+            </Drawer>
+        </>
+    );
+};
+```
+
+### All sides
+
+```tsx
+const Sides = () => {
+  const placements: DrawerPlacement[] = ['right', 'left', 'top', 'bottom'];
+  const [openPlacement, setOpenPlacement] =
+    React.useState<DrawerPlacement | null>(null);
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>
+      {placements.map((placement) => (
+        <Button
+          key={placement}
+          variant="secondary"
+          size="md"
+          onClick={() => setOpenPlacement(placement)}
+        >
+          {placement}
+        </Button>
+      ))}
+      {placements.map((placement) => (
+        <Drawer
+          key={placement}
+          open={openPlacement === placement}
+          onOpenChange={(o) => !o && setOpenPlacement(null)}
+          placement={placement}
+          size="md"
+          title={`${placement} drawer`}
+        >
+          <Body size="sm">Slides in from the {placement}.</Body>
+        </Drawer>
+      ))}
+    </div>
+  );
+};
+```
+
+### Backdrop variants
+
+```tsx
+const BackdropVariants = () => {
+  const backdrops: DrawerBackdrop[] = ['dim', 'none'];
+  const [openBackdrop, setOpenBackdrop] =
+    React.useState<DrawerBackdrop | null>(null);
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>
+      {backdrops.map((b) => (
+        <Button
+          key={b}
+          variant="secondary"
+          size="md"
+          onClick={() => setOpenBackdrop(b)}
+        >
+          {b}
+        </Button>
+      ))}
+      {backdrops.map((b) => (
+        <Drawer
+          key={b}
+          open={openBackdrop === b}
+          onOpenChange={(o) => !o && setOpenBackdrop(null)}
+          backdrop={b}
+          title={`backdrop="${b}"`}
+        >
+          <Body size="sm">Backdrop style: {b}</Body>
+        </Drawer>
+      ))}
+    </div>
+  );
+};
+```
+
+### Sizes
+
+```tsx
+const Sizes = () => {
+  const sizes: DrawerSize[] = ['sm', 'md', 'lg', 'xl', 'full'];
+  const [openSize, setOpenSize] = React.useState<DrawerSize | null>(null);
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>
+      {sizes.map((s) => (
+        <Button
+          key={s}
+          variant="secondary"
+          size="md"
+          onClick={() => setOpenSize(s)}
+        >
+          {s}
+        </Button>
+      ))}
+      {sizes.map((s) => (
+        <Drawer
+          key={s}
+          open={openSize === s}
+          onOpenChange={(o) => !o && setOpenSize(null)}
+          size={s}
+          title={`size="${s}"`}
+        >
+          <Body size="sm">Width: {s}</Body>
+        </Drawer>
+      ))}
+    </div>
+  );
+};
+```
+
+### With description
+
+```tsx
+const WithDescription = () => {
+    const [open, setOpen] = React.useState(false);
+
+    return (
+        <>
+            <Button variant="secondary" size="md" onClick={() => setOpen(true)}>Open Drawer
+                        </Button>
+            <Drawer
+                placement="right"
+                size="md"
+                backdrop="dim"
+                open={open}
+                onOpenChange={setOpen}
+                title="Configure Custom Pricing"
+                description="API Credits · Product">
+                <Body size="sm">{LOREM}</Body>
+            </Drawer>
+        </>
+    );
+};
+```