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/patterns-auth-layout.md ADDED Viewed

@@ -0,0 +1,318 @@
+# Authentication Layout
+Provides screen layout for user authentication flow.
+```jsx
+import { AuthLayout } from '@maxio-com/react-ui-components';
+```
+## Playground
+## Alert
+Use an alert to show authentication errors, status updates, or other contextual information above the main content card.
+## Leading Element
+Use a leading element for back actions, status icons, or other compact header affordances.
+## Imports
+```tsx
+import { AuthLayout, Body, Button, Flex, Icon, IconButton, Link, Select, TextField } from "@maxio-com/react-ui-components";
+```
+## Prop Types
+### AuthLayout
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `alert` | `AlertProps` | no | - | - | TypeLiteral |
+| `description` | `ReactNode` | no | - | - | TypeLiteral |
+| `footer` | `ReactNode` | no | - | - | TypeLiteral |
+| `heading` | `string` | yes | - | - | TypeLiteral |
+| `leadingElement` | `ReactNode` | no | `null` | - | TypeLiteral |
+| `sentiment` | `"danger" \| "success"` | no | `success` | - | TypeLiteral |
+| `topAddon` | `ReactNode` | no | `null` | - | TypeLiteral |
+## Stories
+### With Form
+```tsx
+const WithForm = () => <AuthLayout
+    heading="Log In"
+    footer={(<>
+      <Flex
+        gap={2}
+        grow
+        style={{ color: 'var(--maxio-color-text-tertiary)' }}
+      >
+        <Body size="xs">&copy; Maxio, LLC.</Body>
+        <Link
+          href="https://www.maxio.com/privacy-policy"
+          size="xs"
+          underline
+          variant="tertiary"
+        >
+          Privacy
+        </Link>
+      </Flex>
+      <div>
+        <Select
+          label="Hosting Region"
+          options={[
+            { label: 'US', value: 'https://example.com' },
+            { label: 'EU', value: 'https://example.com' },
+          ]}
+          inline
+          onChange={() => {}}
+        ></Select>
+      </div>
+    </>)}
+    description={null}
+    children={
+      <Flex flexDirection="col" gap={4}>
+        <TextField size="lg" label="Email" onChange={() => {}} />
+        <Button
+          size="lg"
+          icon={<Icon variant="arrow-right-long" />}
+          fullWidth
+        >
+          Continue
+        </Button>
+      </Flex>
+    } />;
+```
+### With Alert
+```tsx
+const WithAlert = () => <AuthLayout
+    heading="Log In"
+    description="Description goes here. It can be a short text to guide the user."
+    footer={(<>
+      <Flex
+        gap={2}
+        grow
+        style={{ color: 'var(--maxio-color-text-tertiary)' }}
+      >
+        <Body size="xs">&copy; Maxio, LLC.</Body>
+        <Link
+          href="https://www.maxio.com/privacy-policy"
+          size="xs"
+          underline
+          variant="tertiary"
+        >
+          Privacy
+        </Link>
+      </Flex>
+      <div>
+        <Select
+          label="Hosting Region"
+          options={[
+            { label: 'US', value: 'https://example.com' },
+            { label: 'EU', value: 'https://example.com' },
+          ]}
+          inline
+          onChange={() => {}}
+        ></Select>
+      </div>
+    </>)}
+    alert={{
+      title: args.alert?.title || 'Alert Title',
+      children: args.alert?.children || 'This is an alert message.',
+      sentiment: args.alert?.sentiment || 'info',
+    }} />;
+```
+### With Buttons
+```tsx
+const WithButtons = () => <AuthLayout
+    heading="Log In"
+    description="Description goes here. It can be a short text to guide the user."
+    footer={(<>
+      <Flex
+        gap={2}
+        grow
+        style={{ color: 'var(--maxio-color-text-tertiary)' }}
+      >
+        <Body size="xs">&copy; Maxio, LLC.</Body>
+        <Link
+          href="https://www.maxio.com/privacy-policy"
+          size="xs"
+          underline
+          variant="tertiary"
+        >
+          Privacy
+        </Link>
+      </Flex>
+      <div>
+        <Select
+          label="Hosting Region"
+          options={[
+            { label: 'US', value: 'https://example.com' },
+            { label: 'EU', value: 'https://example.com' },
+          ]}
+          inline
+          onChange={() => {}}
+        ></Select>
+      </div>
+    </>)}
+    children={
+      <Flex flexDirection="col" gap={2}>
+        <Button
+          size="lg"
+          icon={<Icon variant="arrow-right-long" />}
+          fullWidth
+          variant="tertiary"
+        >
+          Button
+        </Button>
+        <Button
+          size="lg"
+          icon={<Icon variant="arrow-right-long" />}
+          fullWidth
+          variant="tertiary"
+        >
+          Button
+        </Button>
+        <Button
+          size="lg"
+          icon={<Icon variant="arrow-right-long" />}
+          fullWidth
+          variant="tertiary"
+        >
+          Button
+        </Button>
+      </Flex>
+    } />;
+```
+### With Clickable Leading Element
+```tsx
+const WithClickableLeadingElement = () => <AuthLayout
+    heading="Log In"
+    description="Description goes here. It can be a short text to guide the user."
+    footer={(<>
+      <Flex
+        gap={2}
+        grow
+        style={{ color: 'var(--maxio-color-text-tertiary)' }}
+      >
+        <Body size="xs">&copy; Maxio, LLC.</Body>
+        <Link
+          href="https://www.maxio.com/privacy-policy"
+          size="xs"
+          underline
+          variant="tertiary"
+        >
+          Privacy
+        </Link>
+      </Flex>
+      <div>
+        <Select
+          label="Hosting Region"
+          options={[
+            { label: 'US', value: 'https://example.com' },
+            { label: 'EU', value: 'https://example.com' },
+          ]}
+          inline
+          onChange={() => {}}
+        ></Select>
+      </div>
+    </>)}
+    leadingElement={
+      <IconButton
+        variant="tertiary"
+        size="sm"
+        aria-label="Go back"
+        icon={<Icon variant="arrow-left" />}
+        onClick={() => console.log('clicked')}
+      />
+    } />;
+```
+### With Leading Element
+```tsx
+const WithLeadingElement = () => <AuthLayout
+    heading="Log In"
+    description="Description goes here. It can be a short text to guide the user."
+    footer={(<>
+      <Flex
+        gap={2}
+        grow
+        style={{ color: 'var(--maxio-color-text-tertiary)' }}
+      >
+        <Body size="xs">&copy; Maxio, LLC.</Body>
+        <Link
+          href="https://www.maxio.com/privacy-policy"
+          size="xs"
+          underline
+          variant="tertiary"
+        >
+          Privacy
+        </Link>
+      </Flex>
+      <div>
+        <Select
+          label="Hosting Region"
+          options={[
+            { label: 'US', value: 'https://example.com' },
+            { label: 'EU', value: 'https://example.com' },
+          ]}
+          inline
+          onChange={() => {}}
+        ></Select>
+      </div>
+    </>)}
+    sentiment="danger"
+    leadingElement={
+      <Icon size="md" variant="check-circle maxio-icon--danger" />
+    } />;
+```
+### With Top Addon
+```tsx
+const WithTopAddon = () => <AuthLayout
+    heading="Log In"
+    description="Description goes here. It can be a short text to guide the user."
+    footer={(<>
+      <Flex
+        gap={2}
+        grow
+        style={{ color: 'var(--maxio-color-text-tertiary)' }}
+      >
+        <Body size="xs">&copy; Maxio, LLC.</Body>
+        <Link
+          href="https://www.maxio.com/privacy-policy"
+          size="xs"
+          underline
+          variant="tertiary"
+        >
+          Privacy
+        </Link>
+      </Flex>
+      <div>
+        <Select
+          label="Hosting Region"
+          options={[
+            { label: 'US', value: 'https://example.com' },
+            { label: 'EU', value: 'https://example.com' },
+          ]}
+          inline
+          onChange={() => {}}
+        ></Select>
+      </div>
+    </>)}
+    topAddon={<Link href="#">Log Out</Link>}
+    sentiment="danger"
+    leadingElement={
+      <Icon size="md" variant="check-circle maxio-icon--danger" />
+    } />;
+```

package/dist/skills/maxio-react/references/patterns-side-nav.md ADDED Viewed

@@ -0,0 +1,182 @@
+# SideNav
+## Usage Guidelines
+### Overview
+SideNav provides persistent application navigation for Maxio products.
+#### When to Use
+- Use SideNav for persistent product navigation that should remain available across application pages.
+- Use SideNav when navigation needs grouped sections, expandable sub-navigation, and a current-page indicator.
+- Use SideNav when users need to switch between sites or reach site-level actions from the same navigation region.
+#### When Not to Use
+- Do not use SideNav for secondary page-level actions. Use TopBar, Tabs, ActionMenu, or Button patterns depending on the task.
+- Do not use SideNav for short in-page navigation or step-by-step flows.
+- Do not use SideNav when the page has only one or two destinations that are better represented as links in the main content.
+### Behavior
+- **Mouse and touch**: links navigate immediately. Parent menu buttons expand one section at a time and open the collapsed sidebar before showing sub-items.
+- **Keyboard**: the brand link, site switcher, toggle button, section buttons, and links are reachable through normal Tab order. Parent buttons toggle with Enter or Space.
+- **Focus management**: keep the Maxio focus ring visible. When the sidebar is collapsed, top-level items expose hover tooltips while focus and activation remain on the link or button.
+- **Controlled state**: pass `isOpen` and `onChange` when application layout owns the collapsed state. Omit `isOpen` for internal responsive state based on `collapseBreakpoint`.
+- **Persistence**: keep the active section marked through `isCurrent` so visual state and `aria-current="page"` stay aligned after route changes.
+### Accessibility
+- Use the rendered `<nav>` landmark for the primary application navigation. Add a descriptive `aria-label` in static HTML when the page includes multiple navigation landmarks.
+- Use real links with `href` for destinations and buttons for expandable section headers.
+- Mark the current destination with `aria-current="page"` through the section item's `isCurrent` value.
+- Keep `aria-expanded` synchronized on parent menu buttons that reveal nested lists.
+- Keep site switcher actions as keyboard-accessible links with descriptive labels.
+### Content
+- Keep top-level section names short and stable so collapsed tooltips and expanded labels match.
+- Group related destinations under clear headings such as "Integrations" only when the heading improves scanning.
+- Use one active item at a time. If a child route is current, keep its parent section expanded or visually associated with the active child.
+- Avoid using icons as the only way to identify a destination; labels should remain meaningful when icons are hidden.
+### Related
+- **[TopBar](patterns-top-bar.md)**: use for global utilities such as search, help, notifications, and profile actions.
+- **[ActionMenu](components-action-menu.md)**: use for compact groups of contextual actions.
+- **[Tabs](components-tabs.md)**: use for switching between related views inside one page or workflow.
+## React
+```tsx
+import { SideNav } from '@maxio-com/react-ui-components';
+```
+### State Management
+SideNav can manage its own collapsed state or receive it from the application shell.
+#### Controlled
+```tsx
+const [isOpen, setIsOpen] = React.useState(true);
+<SideNav
+  topDropdownItems={topDropdownItems}
+  sections={sections}
+  isOpen={isOpen}
+  onChange={setIsOpen}
+  shouldToggleSidebar
+/>;
+```
+#### Uncontrolled
+```tsx
+<SideNav
+  topDropdownItems={topDropdownItems}
+  sections={sections}
+  collapseBreakpoint={800}
+  shouldToggleSidebar
+/>
+```
+### Navigation Data
+Use `topDropdownItems` for the site switcher and `sections` for grouped navigation lists. Each item with `isCurrent: true` renders the active page state.
+### `topDropdownItems` typings:
+```ts
+topDropdownItems: {
+  mainItem: SideNavTopDropdownItem;
+  otherItems: SideNavTopDropdownItem[];
+  actions: SideNavTopDropdownItem[];
+}
+interface SideNavTopDropdownItem {
+  id: string;
+  title: string;
+  icon: IconVariant;
+  url: string;
+  iconClass?: string;
+  rel?: string;
+}
+```
+### `sections` typings:
+As of `Component` property, it is used to render custom component instead of default one.
+```ts
+sections: SectionGroup[];
+type SectionGroup = (Section | SectionHeading)[];
+interface SectionHeading {
+  title: string;
+  type?: 'heading';
+}
+interface Section extends SingleSectionWithItems {
+  Component?: SectionComponent;
+}
+type SectionComponent = React.FC<{ section: SingleSectionWithItems }>;
+interface SingleSectionWithItems extends SingleSection {
+  isOpen?: boolean;
+  items?: SingleSection[];
+}
+interface SingleSection {
+  href?: string;
+  icon: IconVariant | null;
+  name: string;
+  key: string;
+  isCurrent?: boolean;
+  type?: 'regular';
+}
+```
+## Imports
+```tsx
+import { SideNav } from "@maxio-com/react-ui-components";
+```
+## Prop Types
+### SideNav
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `collapseBreakpoint` | `number` | no | `800` | - | SideNavProviderProps |
+| `isOpen` | `boolean` | no | - | - | SideNavProviderProps |
+| `onChange` | `((isOpen: boolean) => void)` | no | - | - | SideNavProviderProps |
+| `sections` | `SectionGroup[]` | no | `[]` | - | SideNavProviderProps |
+| `shouldToggleSidebar` | `boolean` | no | `false` | - | SideNavProviderProps |
+| `topDropdownItems` | `SideNavTopDropdown` | yes | - | - | SideNavProviderProps |
+| `withIcons` | `boolean` | no | `true` | - | SideNavProviderProps |
+## Stories
+### Default
+Use SideNav for persistent application navigation with a site switcher, grouped product areas, and expandable sub-navigation. Mark the current page with `isCurrent` so the generated link receives `aria-current="page"`.
+```tsx
+const Default = () => <SideNav
+    topDropdownItems={TOP_DROPDOWN_ITEMS_MOCK}
+    sections={[
+      SIDE_NAV_ITEMS_MOCK,
+      SIDE_NAV_INTEGRATION_ITEMS_MOCK,
+      SIDE_NAV_BOTTOM_ITEMS_MOCK,
+    ]}
+    withIcons
+    shouldToggleSidebar
+    collapseBreakpoint={800}
+    isOpen={undefined}
+    onChange={() => {}} />;
+```

package/dist/skills/maxio-react/references/patterns-top-bar.md ADDED Viewed

@@ -0,0 +1,214 @@
+# TopBar
+## Usage Guidelines
+### Overview
+TopBar provides the persistent application header area for global actions, search, account controls, and the side navigation opener in responsive layouts.
+#### When to Use
+- Use TopBar for persistent application-level actions such as search, help, notifications, profile access, and account context.
+- Use TopBar with SideNav when responsive layouts need a header control to reopen collapsed navigation.
+- Use the center area for high-value global controls that should remain available across pages, such as search or environment menus.
+#### When Not to Use
+- Do not use TopBar as the primary page navigation. Use SideNav or page-level navigation for destination lists.
+- Do not place page-specific actions in TopBar when they only affect one table, card, or form section.
+- Do not overload TopBar with every global link. Group secondary choices in ActionMenu or move them to SideNav.
+### Behavior
+- **Mouse and touch**: icon buttons and menus activate according to their underlying Button, IconButton, Link, or ActionMenu behavior.
+- **Keyboard**: preserve native Tab order through the side navigation opener, center controls, and right-side actions.
+- **Focus management**: when the side navigation opener is shown, return focus to a sensible place after the side navigation opens or closes.
+- **Responsive state**: set `sideNavIsClosed` only when the side navigation is collapsed and the opener should be visible.
+- **Composition**: pass persistent right-side controls through `actions` and optional center content through `children`.
+### Accessibility
+- TopBar renders a `nav` landmark, so use it for navigation and application actions that deserve landmark navigation.
+- Keep every icon-only action accessible with a specific `aria-label`, such as "Open Search" or "Notifications".
+- Use buttons for in-page actions and anchors for navigation to another route or resource.
+- Keep search fields labelled and submit them with semantic form behavior when search can be submitted.
+- Do not rely on icon shape alone to communicate action purpose.
+### Content
+- Keep action labels short and outcome-oriented, even when they are only exposed to assistive technology.
+- Use profile avatar alt text that identifies the account or person when the image conveys identity.
+- Prefer visible labels for center menus so administrative or environment context can be scanned quickly.
+### Related
+- **[SideNav](patterns-side-nav.md)**: use for primary application navigation and collapsed navigation state.
+- **[IconButton](components-buttons-iconbutton.md)**: use for icon-only actions inside the top bar.
+- **[ActionMenu](components-action-menu.md)**: use to group multiple related top bar actions.
+## React
+```tsx
+import { TopBar } from '@maxio-com/react-ui-components';
+```
+## Imports
+```tsx
+import {
+    Avatar,
+    Flex,
+    Icon,
+    IconButton,
+    Menu,
+    MenuButton,
+    MenuList,
+    Select,
+    TextField,
+    TopBar,
+} from "@maxio-com/react-ui-components";
+```
+## Prop Types
+### TopBar
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `actions` | `ReactNode` | yes | - | Actions displayed on the right side of the top bar | TypeLiteral |
+| `children` | `ReactNode` | no | - | Additional actions displayed in the middle of the top bar | TypeLiteral |
+| `openSideNav` | `(() => void)` | no | - | Callback function to open the side navigation | TypeLiteral |
+| `sideNavIsClosed` | `boolean` | no | - | Show/hide side navigation button | TypeLiteral |
+## Stories
+### Default
+Use the default top bar for persistent global actions such as search, help, notifications, and profile access. Keep icon-only actions accessible with concise `aria-label` values.
+```tsx
+const Default = () => <TopBar actions={topBarActions} />;
+```
+### With Search Input
+Use a search field in the top bar when search is active and benefits from filters or visible input. Include the side navigation opener when responsive layout has collapsed the side navigation.
+```tsx
+const WithSearchInput = () => <TopBar
+    actions={topBarActions}
+    sideNavIsClosed
+    openSideNav={action('Open side navigation')}>(<>
+      <form>
+        <Flex gap={2}>
+          <Select
+            options={[
+              {
+                label: 'Customer Name / Number',
+                value: 'customer-name-number',
+              },
+              {
+                label: 'Option 2',
+                value: 'option-2',
+              },
+            ]}
+          />
+          <TextField
+            aria-label="Search"
+            leadingElement={<Icon variant="search" />}
+            trailingElement={
+              <IconButton
+                aria-label="Clear Search"
+                variant="ghost"
+                icon={<Icon variant="cross" />}
+                onClick={action('Search button clicked')}
+              />
+            }
+            onChange={() => {}}
+            placeholder="Search customers"
+            fullWidth
+          />
+        </Flex>
+      </form>
+    </>)</TopBar>;
+```
+### With Action Menus
+Use action menus in the center area when administrative context switching or environment controls need to remain available across pages. Keep menu labels visible so the options are scannable.
+```tsx
+const WithActionMenus = () => <TopBar
+    actions={topBarActions}
+    sideNavIsClosed
+    openSideNav={action('Open side navigation')}>(<>
+      <form>
+        <Flex>
+          <Menu>
+            <MenuButton variant="ghost" aria-label="Admin">
+              Admin
+            </MenuButton>
+            <MenuList
+              items={[
+                {
+                  id: 1,
+                  label: 'Item 1',
+                  link: {
+                    href: '#',
+                  },
+                },
+              ]}
+            />
+          </Menu>
+          <Menu>
+            <MenuButton variant="ghost" aria-label="Admin Reports">
+              Admin Reports
+            </MenuButton>
+            <MenuList
+              items={[
+                {
+                  id: 1,
+                  label: 'Item 1',
+                  link: {
+                    href: '#',
+                  },
+                },
+              ]}
+            />
+          </Menu>
+          <Menu>
+            <MenuButton variant="ghost" aria-label="Staging">
+              Staging
+            </MenuButton>
+            <MenuList
+              items={[
+                {
+                  id: 1,
+                  label: 'Item 1',
+                  link: {
+                    href: '#',
+                  },
+                },
+              ]}
+            />
+          </Menu>
+          <Menu>
+            <MenuButton variant="ghost" aria-label="Feature Flags">
+              Feature Flags
+            </MenuButton>
+            <MenuList
+              items={[
+                {
+                  id: 1,
+                  label: 'Item 1',
+                  link: {
+                    href: '#',
+                  },
+                },
+              ]}
+            />
+          </Menu>
+        </Flex>
+      </form>
+    </>)</TopBar>;
+```