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-drawer.md ADDED Viewed

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

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

@@ -0,0 +1,185 @@
+# Flex
+## Usage Guidelines
+### Overview
+Flex is a layout primitive for arranging child content along a single axis, with optional wrapping, spacing, alignment, and item sizing.
+#### When to Use
+- Use Flex for one-dimensional layout where children flow in a row or column.
+- Use Flex to apply consistent gaps, alignment, wrapping, and item sizing to a small group of related elements.
+- Use Flex when the layout should adapt to available space without introducing grid tracks.
+#### When Not to Use
+- Do not use Flex for two-dimensional layouts that need explicit rows and columns. Use Grid instead.
+- Do not use reverse directions to change meaningful reading order. Keep important content order correct in the DOM.
+- Do not use Flex as a spacing wrapper when semantic grouping, list markup, or a component-specific layout is more appropriate.
+### Layout Properties
+Choose the smallest set of flex utilities needed for the layout.
+| Property                          | Purpose                             | Usage notes                                                                    |
+| :-------------------------------- | :---------------------------------- | :----------------------------------------------------------------------------- |
+| `flexDirection`                   | Sets the main axis.                 | Use `row` for inline groups and `col` for stacked content.                     |
+| `wrap`                            | Allows items to continue on rows.   | Pair with predictable item widths or `basis` values.                           |
+| `gap`, `gapX`, `gapY`             | Sets spacing between items.         | Prefer gap utilities over item margins for consistent spacing.                 |
+| `alignItems`                      | Aligns items on the cross axis.     | Use `center` for mixed-size inline content and `stretch` for equal heights.    |
+| `justifyContent`                  | Distributes items on the main axis. | Use `between`, `around`, or `evenly` only when the empty space is intentional. |
+| `basis`, `flex`, `grow`, `shrink` | Controls item sizing.               | Apply item sizing to children, not the parent container.                       |
+### Accessibility
+- Flex uses a `div` by default and does not add interactive behavior or ARIA semantics.
+- Preserve meaningful DOM order, especially when using `row-reverse` or `col-reverse`.
+- Use semantic elements inside Flex when the content is a list, navigation, form group, toolbar, or status region.
+- Avoid using visual alignment alone to communicate relationships that need text, headings, labels, or programmatic structure.
+- Keep focus order logical when interactive children wrap or resize across breakpoints.
+### Related
+- **[Grid](components-grid.md)**: use for two-dimensional layouts with explicit rows, columns, or item placement.
+## React
+```tsx
+import { Flex } from '@maxio-com/react-ui-components';
+```
+## Imports
+```tsx
+import { Flex } from "@maxio-com/react-ui-components";
+```
+## Prop Types
+### Flex
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `alignItems` | `"center" \| "start" \| "end" \| "baseline" \| "stretch"` | no | - | Controls how flex items are positioned along the main axis (defined by `FlexDirection`). Items will stretch by default if no value is set. | TypeLiteral |
+| `basis` | `"auto" \| "1/2" \| "1/3" \| "2/3" \| "1/4" \| "2/4" \| "3/4" \| "1/5" \| "2/5" \| "3/5" \| "4/5" \| "1/6" \| "2/6" \| "3/6" \| "4/6" \| "5/6" \| "1/12" \| "2/12" \| "3/12" \| "4/12" \| "5/12" \| "6/12" \| "7/12" \| "8/12" \| "9/12" \| "10/12" \| "11/12" \| "full"` | no | - | Defines the initial size of flex items. | TypeLiteral |
+| `children` | `ReactNode` | no | - | The content of the flex container. Can be any valid `ReactNode`. | TypeLiteral, DOMAttributes |
+| `className` | `string` | no | - | Additional class names for custom styling. | TypeLiteral, HTMLAttributes |
+| `flex` | `"none" \| "auto" \| "initial" \| 1` | no | - | Controls how flex items both grow and shrink. | TypeLiteral |
+| `flexDirection` | `"row" \| "col" \| "row-reverse" \| "col-reverse"` | no | - | Defines the flex direction. Default orientation is `row`. | TypeLiteral |
+| `gap` | `0 \| 1 \| "px" \| 0.5 \| 1.5 \| 2 \| 2.5 \| 3 \| 3.5 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 14 \| 16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 52 \| 56 \| 60 \| 64 \| 72 \| 80 \| 96` | no | - | Controls the vertical and horizontal space between flex items. | TypeLiteral |
+| `gapX` | `0 \| 1 \| "px" \| 0.5 \| 1.5 \| 2 \| 2.5 \| 3 \| 3.5 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 14 \| 16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 52 \| 56 \| 60 \| 64 \| 72 \| 80 \| 96` | no | - | Controls the horizontal space between flex items. | TypeLiteral |
+| `gapY` | `0 \| 1 \| "px" \| 0.5 \| 1.5 \| 2 \| 2.5 \| 3 \| 3.5 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 14 \| 16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 52 \| 56 \| 60 \| 64 \| 72 \| 80 \| 96` | no | - | Controls the vertical space between flex items. | TypeLiteral |
+| `grow` | `boolean` | no | - | Allows or restricts growing. | TypeLiteral |
+| `justifyContent` | `"center" \| "start" \| "end" \| "stretch" \| "normal" \| "between" \| "around" \| "evenly"` | no | - | Controls how flex items are positioned along the main axis (defined by `FlexDirection`). | TypeLiteral |
+| `shrink` | `boolean` | no | - | Allows or restricts shrinking. | TypeLiteral |
+| `wrap` | `"wrap" \| "nowrap" \| "wrap-reverse"` | no | - | Controls whether the flex items are forced onto one line or can wrap onto multiple lines. | TypeLiteral |
+## Stories
+### Flex
+Use Flex for one-dimensional layout when child items need shared direction, spacing, alignment, wrapping, or proportional sizing.
+```tsx
+const Default = (props) => (
+  <Flex
+    flexDirection={props.flexDirection}
+    gap={props.gap}
+    alignItems={props.alignItems}
+    justifyContent={props.justifyContent}
+    wrap={props.wrap}
+    style={container}
+    gapX={props.gapX}
+    gapY={props.gapY}
+    className={'maxio-body-sm'}
+  >
+    <>
+      <Flex
+        key="1"
+        flex={props.flex}
+        basis={props.basis}
+        shrink={props.shrink}
+        grow={props.grow}
+        style={blueSquare}
+      >
+        01
+      </Flex>
+      <Flex
+        key="2"
+        flex={props.flex}
+        basis={props.basis}
+        shrink={props.shrink}
+        style={purpleSquare}
+      >
+        02
+      </Flex>
+      <Flex
+        key="3"
+        flex={props.flex}
+        basis={props.basis}
+        shrink={props.shrink}
+        style={pinkSquare}
+      >
+        03
+      </Flex>
+    </>
+  </Flex>
+);
+```
+### Basis
+Use basis values when sibling items need predictable initial widths before available space is distributed.
+```tsx
+const Basis = (props) => <Flex {...props}>{props.children}</Flex>;
+```
+### Row Reverse
+Use row-reverse only when the visual order should be reversed while the source order remains unchanged for reading and assistive technology.
+```tsx
+const RowReverse = (props) => <Flex {...props}>{props.children}</Flex>;
+```
+### Column Reverse
+Use column-reverse sparingly because it changes visual order without changing DOM order.
+```tsx
+const ColumnReverse = (props) => <Flex {...props}>{props.children}</Flex>;
+```
+### Wrap reverse
+Use wrap-reverse only when additional rows should stack in the opposite cross-axis direction.
+```tsx
+const WrapReverse = (props) => <Flex {...props}>{props.children}</Flex>;
+```
+### Wrap
+Use wrapping when items may exceed the available inline space and should continue on additional rows instead of overflowing.
+```tsx
+const Wrap = (props) => <Flex {...props}>{props.children}</Flex>;
+```
+### Grow
+Use grow when one or more items should absorb remaining space while fixed siblings keep their initial size.
+```tsx
+const Grow = (props) => <Flex {...props}>{props.children}</Flex>;
+```
+### Shrink
+Use shrink when an item may reduce in size to keep the row within its container.
+```tsx
+const Shrink = (props) => <Flex {...props}>{props.children}</Flex>;
+```