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

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

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 (51) hide show

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

@@ -0,0 +1,176 @@
+# Popover
+## Usage Guidelines
+### Overview
+Popover positions dismissible overlay content next to a trigger.
+#### When to Use
+- Use Popover for dismissible rich content that is anchored to a trigger.
+- Use when the content needs more structure than a Tooltip, such as text with actions, short forms, or contextual details.
+- Use with DialogTrigger when the trigger opens a generic dialog-like overlay.
+- Use as the shared overlay shell for components that already manage listbox, menu, or combobox behavior.
+#### When Not to Use
+- Do not use for brief explanatory text. Use Tooltip instead.
+- Do not use for a simple list of contextual actions. Use ActionMenu instead.
+- Do not use for page-level or blocking decisions. Use a modal dialog pattern instead.
+- Do not use Popover by itself when you need trigger state, focus return, or dismissal behavior. Pair it with a React Aria trigger.
+### Behavior
+- **Mouse and touch**: activating the trigger opens the popover. Pressing outside the popover or selecting a closing action should dismiss it.
+- **Keyboard**: Tab moves through focusable content in the trigger and popover. Escape dismisses the popover.
+- **Focus management**: focus remains predictable through React Aria trigger components and returns to the trigger after dismissal.
+- **Placement**: use `placement`, `offset`, and `shouldFlip` to keep the popover connected to the trigger without clipping the viewport.
+- **Arrow**: keep the arrow for most standalone popovers. Hide it when the popover is visually anchored by another component, such as an input or menu surface.
+### Accessibility
+- Pair Popover with DialogTrigger or another React Aria trigger so `aria-expanded`, `aria-controls`, dismissal, and focus return stay synchronized.
+- Give the trigger an accessible name that describes what opens, such as "Show billing details" or "Edit filters".
+- Keep popover content concise and focused on the trigger context.
+- Include a clear dismiss path when the content contains interactive controls or can stay open while users review information.
+- Keep focus indicators visible inside the popover and preserve Escape dismissal.
+- Do not rely on placement or arrow direction alone to communicate meaning.
+### Content
+- Use short, specific copy that extends the trigger context.
+- Start action labels with verbs when the popover includes buttons or links.
+- Avoid placing long workflows, dense tables, or unrelated navigation inside a popover.
+### Related
+- **[Tooltip](components-tooltip.md)**: use for short, noninteractive explanatory text.
+- **[ActionMenu](components-action-menu.md)**: use for a menu of related actions behind a trigger.
+- **[Button](components-buttons-button.md)**: use as the typical trigger for standalone popovers.
+## React
+```tsx
+import {
+  Body,
+  Button,
+  Popover,
+  DialogTrigger,
+} from '@maxio-com/react-ui-components';
+```
+### State Management
+Use uncontrolled state for ordinary trigger-and-popover interactions. Use controlled state when product logic needs to open or close the popover from another control, route change, or validation result.
+#### Controlled
+```tsx
+const [isOpen, setOpen] = React.useState(false);
+<DialogTrigger isOpen={isOpen} onOpenChange={setOpen}>
+  <Button variant="secondary" size="md">
+    Open popover
+  </Button>
+  <Popover placement="bottom start">
+    <Body size="sm">Review customer billing details.</Body>
+  </Popover>
+</DialogTrigger>;
+```
+#### Uncontrolled
+```tsx
+<DialogTrigger>
+  <Button variant="secondary" size="md">
+    Open popover
+  </Button>
+  <Popover placement="bottom start">
+    <Body size="sm">Review customer billing details.</Body>
+  </Popover>
+</DialogTrigger>
+```
+### Related Exports
+`DialogTrigger` and `Pressable` are re-exported from
+`react-aria-components` for convenience.
+## Imports
+```tsx
+import { Body, Button, DialogTrigger, Popover } from "@maxio-com/react-ui-components";
+```
+## Prop Types
+### Popover
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `hideArrow` | `boolean` | no | `false` | When true, hides the arrow aligned to the trigger. | PopoverProps |
+## Stories
+### Default
+Use Popover for dismissible rich content that is tied to a trigger, such as compact details, contextual controls, or selection surfaces. Pair it with DialogTrigger so trigger state, focus return, and Escape dismissal are wired by React Aria.
+```tsx
+const Default = () => <DialogTrigger>
+    <Button variant="secondary" size="md">Open popover
+              </Button>
+    <Popover hideArrow={false} placement="bottom start" shouldFlip>
+        <Body size="sm">Review customer billing details.</Body>
+    </Popover>
+</DialogTrigger>;
+```
+### Without arrow
+Hide the arrow when the popover is visually anchored by another shape, such as an input, menu, or flush container. Keep the trigger relationship and dismissal behavior the same.
+```tsx
+const WithoutArrow = () => (
+  <DialogTrigger>
+    <Button variant="secondary" size="md">
+      Open popover
+    </Button>
+    <Popover hideArrow={true} placement="bottom start">
+      <Body size="sm">Review customer billing details.</Body>
+    </Popover>
+  </DialogTrigger>
+);
+```
+### All placements
+Use placement options to keep the popover visually connected to its trigger. Leave `shouldFlip` enabled in product code unless a fixed placement is required for visual QA or documentation.
+```tsx
+const AllPlacements = ({ ...args }) => (
+  <div
+    style={{
+      display: 'grid',
+      gridTemplateColumns: 'repeat(3, 1fr)',
+      gap: '1rem',
+      justifyItems: 'center',
+      maxWidth: '32rem',
+    }}
+  >
+    {ALL_PLACEMENTS.map((placement) => (
+      <div key={placement}>
+        <DialogTrigger>
+          <Button variant="secondary" size="sm">
+            {placement}
+          </Button>
+          <Popover placement={placement} shouldFlip={false} {...args}>
+            <Body size="sm">Popover placement preview.</Body>
+          </Popover>
+        </DialogTrigger>
+      </div>
+    ))}
+  </div>
+);
+```

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

@@ -0,0 +1,98 @@
+# ProgressBar
+## Usage Guidelines
+### Overview
+ProgressBar communicates the completion state of a known or ongoing process.
+#### When to Use
+- Use ProgressBar for determinate work with a known value, such as imports, exports, file uploads, batch jobs, or onboarding progress.
+- Use ProgressBar for indeterminate work when progress is active but the current value is unknown.
+- Use helper text to clarify the current milestone, percentage, or completion result.
+#### When Not to Use
+- Do not use ProgressBar for short blocking page loads with no meaningful task context. Use LoadingSpinner instead.
+- Do not use ProgressBar for success, error, or warning messages by themselves. Pair status with helper text or use Alert/Banner for standalone messages.
+- Do not use ProgressBar as a step navigation control.
+### Variants
+Choose the variant based on how much surrounding context the progress message
+needs.
+| Variant   | Purpose                                 | Usage notes                                                        |
+| :-------- | :-------------------------------------- | :----------------------------------------------------------------- |
+| `default` | Stacks label, track, and helper text.   | Use for most progress states and when helper text carries detail.  |
+| `inline`  | Places label, track, and helper inline. | Use in dense layouts where the label and value are short.          |
+| `indent`  | Indents label and helper text.          | Use when the bar belongs to nested content or a grouped task list. |
+### States
+| State           | Purpose                        | Usage notes                                                                 |
+| :-------------- | :----------------------------- | :-------------------------------------------------------------------------- |
+| `value` set     | Shows determinate progress.    | Keep `value` within `0` and `maxValue` and update helper text as needed.    |
+| `value` omitted | Shows indeterminate progress.  | Use when work is active but the percentage or completion value is unknown.  |
+| `success`       | Reinforces completed progress. | Use with completion copy such as "Import complete".                         |
+| `error`         | Reinforces failed progress.    | Use with actionable helper text that explains what failed or what to retry. |
+### Accessibility
+- Provide a concise visible label that names the task being tracked.
+- Use determinate values when progress is measurable; omit `value` only when the amount completed is unknown.
+- Keep helper text synchronized with the visual state when progress succeeds, fails, or reaches a meaningful milestone.
+- Do not rely on the progress color alone to communicate success or error status.
+- Avoid rapidly changing helper text in a way that would create noisy announcements.
+### Content
+- Name the task, such as "Importing customers" or "Uploading contract".
+- Use helper text for user-relevant progress, such as "50% complete" or "Retry failed records".
+- Keep status copy short and update it when the process completes or fails.
+### Related
+- **[LoadingSpinner](components-loading-spinner.md)**: Use for indeterminate loading with no useful percentage or milestone.
+- **[Alert](components-notifications-alert.md)**: Use for standalone success, warning, or error feedback.
+## React
+```tsx
+import { ProgressBar } from '@maxio-com/react-ui-components';
+```
+## Imports
+```tsx
+import { ProgressBar } from "@maxio-com/react-ui-components";
+```
+## Prop Types
+### ProgressBar
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `helperText` | `string` | no | - | Helper text for the progress bar | ProgressBarProps |
+| `label` | `string` | yes | - | Label for the progress bar | ProgressBarProps |
+| `maxValue` | `number` | no | `100` | Defines the maximum value of the progress bar | ProgressBarProps |
+| `size` | `"md" \| "lg"` | no | `md` | Defines the size of the progress bar | ProgressBarProps |
+| `status` | `"error" \| "success"` | no | - | Defines the status of the progress bar | ProgressBarProps |
+| `value` | `number` | no | - | Defines the current value of the progress bar. If `undefined` the progress bar will be indeterminate. | ProgressBarProps |
+| `variant` | `"inline" \| "indent" \| "default"` | no | `default` | Defines the position applied to the label and helper text | ProgressBarProps |
+## Stories
+### Default
+Use ProgressBar when a user needs to understand how much of a process has completed. Keep the label specific to the task and use helper text for the current milestone, percentage, or outcome.
+```tsx
+const Default = () => <ProgressBar
+    helperText="50% complete"
+    label="Importing customers"
+    maxValue={100}
+    value={50} />;
+```

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

@@ -0,0 +1,292 @@
+# SegmentedControl
+## Usage Guidelines
+### Overview
+#### When to Use
+- Use SegmentedControl when users choose one option from a small set of closely related views, modes, or filters.
+- Use SegmentedControl when the selection should take effect immediately and stay visible in a compact control.
+- Use SegmentedControl for chart type, billing period, report range, export format, or density settings that change the current view.
+#### When Not to Use
+- Do not use SegmentedControl for navigation between unrelated pages or major app areas. Use SideNav instead.
+- Do not use SegmentedControl when each option reveals a separate content panel with its own heading hierarchy. Use Tabs instead.
+- Do not use SegmentedControl for form submission with many options or helper text per choice. Use Radio or Select instead.
+- Do not use SegmentedControl when users can choose more than one option. Use CheckboxGroup instead.
+### Variants
+Choose the size and layout that fit the surrounding surface.
+| Variants    | Purpose                         | Usage notes                                                            |
+| :---------- | :------------------------------ | :--------------------------------------------------------------------- |
+| `sm`        | Compact inline selection.       | Use in dense toolbars, table filters, or chart controls.               |
+| `md`        | Default size for most surfaces. | Use for standard page-level mode switching.                            |
+| `lg`        | Larger touch and scan targets.  | Use when segments include supporting metrics or secondary content.     |
+| `fullWidth` | Equal-width segments.           | Use when the control spans a container and each option needs balance.  |
+| `vertical`  | Stacked segment layout.         | Use when horizontal space is limited or options read better as a list. |
+### Behavior
+- **Mouse and touch**: Selecting a segment updates the active choice and clears the previous selection.
+- **Keyboard**: Tab moves focus into the group. Arrow keys move selection across enabled segments in the current orientation.
+- **Focus management**: Focus stays on the selected segment after keyboard selection. Disabled segments are skipped.
+- **Controlled state**: Use `selectedKeys` with `onSelectionChange` when route state, saved preferences, or another component owns the selection.
+- **Uncontrolled state**: Use `defaultSelectedKeys` when the control can manage its own selection after the initial render.
+- **Disabled state**: Disable individual segments with `isDisabled` on `SegmentedControl.Item`, or disable the entire group with `isDisabled` on `SegmentedControl`.
+### Accessibility
+- Provide an accessible group name with `aria-label` or `aria-labelledby` on `SegmentedControl`.
+- Give each `SegmentedControl.Item` a concise visible label that describes the option.
+- Provide `aria-label` on icon-only segments because the icon does not name the option by itself.
+- Keep disabled segments out of keyboard selection and prevent activation.
+- Do not rely on color alone to communicate the selected segment; the selection indicator provides an additional cue.
+### Content
+- Use short, parallel labels that describe the view or mode, such as "Monthly", "Annual", or "Custom".
+- Keep labels specific to the current context instead of generic words such as "Option 1".
+- Use icons as supporting context next to text labels; avoid icon-only segments unless the meaning is unmistakable.
+- Consider truncation and localization when labels may grow in translated copy.
+### Related
+- **[Tabs](components-tabs.md)**: Use when each option reveals a separate panel with its own content area.
+- **[Radio Group](components-forms-radio-group.md)**: Use when the choice belongs to a form and needs a visible group label, helper text, or validation.
+- **[Select](components-forms-select.md)**: Use when only one option can be selected but the list should stay compact.
+## React
+```tsx
+import { SegmentedControl } from '@maxio-com/react-ui-components';
+```
+### Composition
+- `SegmentedControl` owns selection state and renders the toggle button group.
+- `SegmentedControl.Item` renders one selectable segment. Each item needs a stable `id` that matches the keys used in `defaultSelectedKeys` or `selectedKeys`.
+```tsx
+<SegmentedControl aria-label="Billing period" defaultSelectedKeys={['monthly']}>
+  <SegmentedControl.Item id="monthly">Monthly</SegmentedControl.Item>
+  <SegmentedControl.Item id="annual">Annual</SegmentedControl.Item>
+  <SegmentedControl.Item id="custom">Custom</SegmentedControl.Item>
+</SegmentedControl>
+```
+### State Management
+Use uncontrolled SegmentedControl for local view state. Use controlled SegmentedControl when selection is driven by routing, persisted preferences, or another component.
+#### Controlled
+```tsx
+const [selectedKeys, setSelectedKeys] = React.useState(new Set(['week']));
+<SegmentedControl
+  aria-label="Report range"
+  selectedKeys={selectedKeys}
+  onSelectionChange={setSelectedKeys}
+>
+  <SegmentedControl.Item id="day">Day</SegmentedControl.Item>
+  <SegmentedControl.Item id="week">Week</SegmentedControl.Item>
+  <SegmentedControl.Item id="month">Month</SegmentedControl.Item>
+</SegmentedControl>;
+```
+#### Uncontrolled
+```tsx
+<SegmentedControl aria-label="Billing period" defaultSelectedKeys={['monthly']}>
+  <SegmentedControl.Item id="monthly">Monthly</SegmentedControl.Item>
+  <SegmentedControl.Item id="annual">Annual</SegmentedControl.Item>
+  <SegmentedControl.Item id="custom">Custom</SegmentedControl.Item>
+</SegmentedControl>
+```
+## Imports
+```tsx
+import { Flex, Heading, Icon, Label, SegmentedControl } from "@maxio-com/react-ui-components";
+```
+## Stories
+### Default
+Use Default for switching between closely related views or modes with a compact control. Provide `aria-label` when no visible group label is present.
+```tsx
+const Default = () => <SegmentedControl aria-label="Billing period" defaultSelectedKeys={['monthly']}>
+    <SegmentedControl.Item id="monthly">Monthly</SegmentedControl.Item>
+    <SegmentedControl.Item id="annual">Annual</SegmentedControl.Item>
+    <SegmentedControl.Item id="custom">Custom</SegmentedControl.Item>
+</SegmentedControl>;
+```
+### Controlled
+Use Controlled when application state owns the selected segment.
+```tsx
+const Controlled = () => {
+  const [selectedKeys, setSelectedKeys] = React.useState<Set<Key>>(
+    () => new Set(['week'])
+  );
+  return (
+    <SegmentedControl
+      aria-label="Report range"
+      selectedKeys={selectedKeys}
+      onSelectionChange={setSelectedKeys}
+    >
+      <SegmentedControl.Item id="day">Day</SegmentedControl.Item>
+      <SegmentedControl.Item id="week">Week</SegmentedControl.Item>
+      <SegmentedControl.Item id="month">Month</SegmentedControl.Item>
+    </SegmentedControl>
+  );
+};
+```
+### Disabled
+Use Disabled when one or more segments are unavailable in the current context. Disable individual items before disabling the entire group.
+```tsx
+const Disabled = () => (
+  <Flex flexDirection="col" gap={4}>
+    <SegmentedControl
+      aria-label="Calendar view"
+      defaultSelectedKeys={['month']}
+    >
+      <SegmentedControl.Item id="week">Week</SegmentedControl.Item>
+      <SegmentedControl.Item id="month">Month</SegmentedControl.Item>
+      <SegmentedControl.Item id="quarter" isDisabled>
+        Quarter
+      </SegmentedControl.Item>
+    </SegmentedControl>
+    <SegmentedControl aria-label="Calendar view" isDisabled>
+      <SegmentedControl.Item id="week">Week</SegmentedControl.Item>
+      <SegmentedControl.Item id="month">Month</SegmentedControl.Item>
+      <SegmentedControl.Item id="quarter" isDisabled>
+        Quarter
+      </SegmentedControl.Item>
+    </SegmentedControl>
+  </Flex>
+);
+```
+### Full Width
+Use Full Width when segments should share the available width equally.
+```tsx
+const FullWidth = () => (
+  <SegmentedControl
+    aria-label="Revenue type"
+    defaultSelectedKeys={['gross']}
+    fullWidth
+  >
+    <SegmentedControl.Item id="gross">Gross revenue</SegmentedControl.Item>
+    <SegmentedControl.Item id="net">Net revenue</SegmentedControl.Item>
+    <SegmentedControl.Item id="mrr">MRR</SegmentedControl.Item>
+  </SegmentedControl>
+);
+```
+### Small
+Use Small in dense toolbars, table filters, or chart controls.
+```tsx
+const Small = () => (
+  <SegmentedControl
+    aria-label="Density"
+    defaultSelectedKeys={['compact']}
+    size="sm"
+  >
+    <SegmentedControl.Item id="compact">Compact</SegmentedControl.Item>
+    <SegmentedControl.Item id="comfortable">
+      Comfortable
+    </SegmentedControl.Item>
+  </SegmentedControl>
+);
+```
+### Vertical
+Use Vertical when horizontal space is limited or options read better as a stacked list.
+```tsx
+const Vertical = () => (
+  <SegmentedControl
+    aria-label="Export format"
+    defaultSelectedKeys={['csv']}
+    orientation="vertical"
+  >
+    <SegmentedControl.Item id="csv">CSV</SegmentedControl.Item>
+    <SegmentedControl.Item id="xlsx">XLSX</SegmentedControl.Item>
+    <SegmentedControl.Item id="pdf">PDF</SegmentedControl.Item>
+  </SegmentedControl>
+);
+```
+### With Icons
+Use icons as supporting context next to labels, or provide `aria-label` for icon-only segments.
+```tsx
+const WithIcons = () => (
+  <Flex flexDirection="col" gap={4}>
+    <SegmentedControl aria-label="Chart type" defaultSelectedKeys={['bar']}>
+      <SegmentedControl.Item id="bar">
+        <Icon variant="bar-chart" />
+        Bar
+      </SegmentedControl.Item>
+      <SegmentedControl.Item id="list">
+        <Icon variant="list" />
+        List
+      </SegmentedControl.Item>
+    </SegmentedControl>
+    <SegmentedControl aria-label="Chart type" defaultSelectedKeys={['bar']}>
+      <SegmentedControl.Item id="bar" aria-label="Bar chart">
+        <Icon variant="bar-chart" />
+      </SegmentedControl.Item>
+      <SegmentedControl.Item id="list" aria-label="List view">
+        <Icon variant="list" />
+      </SegmentedControl.Item>
+    </SegmentedControl>
+  </Flex>
+);
+```
+### Custom
+Use custom content sparingly when a segment needs supporting metrics or secondary text.
+```tsx
+const Custom = () => <SegmentedControl aria-label="Status" defaultSelectedKeys={['active']} size="lg">
+    <SegmentedControl.Item id="active">
+        <Flex flexDirection="col" alignItems="start">
+            <Label size="sm">Active</Label>
+            <Heading size="md">96</Heading>
+        </Flex>
+    </SegmentedControl.Item>
+    <SegmentedControl.Item id="inactive">
+        <Flex flexDirection="col" alignItems="start">
+            <Label size="sm">Inactive</Label>
+            <Heading size="md">12</Heading>
+        </Flex>
+    </SegmentedControl.Item>
+    <SegmentedControl.Item id="pending">
+        <Flex flexDirection="col" alignItems="start">
+            <Label size="sm">Pending</Label>
+            <Heading size="md">3</Heading>
+        </Flex>
+    </SegmentedControl.Item>
+</SegmentedControl>;
+```