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

package/dist/skills/maxio-react/references/deprecated-textinput.md

@@ -0,0 +1,250 @@
+> Deprecated: use this reference only when maintaining existing legacy UI or intentionally matching legacy behavior.
+
+# TextInput
+
+## Usage Guidelines
+
+### Overview
+
+TextInput lets users enter or edit a short, single-line text value in a form.
+
+#### When to Use
+
+- Use only when maintaining existing TextInput implementations that cannot be migrated immediately.
+- Use when users need to enter a short, single-line value in a legacy form.
+- Use helper text when users need a format hint, example, or constraint before they type.
+- Use leading or trailing content for simple visual context, units, prefixes, suffixes, or a small field-level action.
+
+#### When Not to Use
+
+- Do not use for new React implementation. Use [TextField](components-forms-textfield.md) instead.
+- Do not use for long-form or multi-line writing. Use a textarea pattern instead.
+- Do not use when users must choose from a known list. Use Select for short lists or ComboBox when filtering helps.
+- Do not use placeholder text as the only label. Provide a visible `label` whenever possible.
+- Do not use for actions or navigation. Use Button, IconButton, or Link instead.
+
+### Variants
+
+| Variants | Purpose                               | Usage notes                                                |
+| :------- | :------------------------------------ | :--------------------------------------------------------- |
+| `sm`     | Compact field for dense interfaces.   | Use where form density is high and labels remain readable. |
+| `md`     | Default field size.                   | Use for most legacy TextInput forms.                       |
+| `lg`     | Larger field for prominent form rows. | Use sparingly when the field needs more visual emphasis.   |
+| `xl`     | Field with contained label treatment. | Use when matching an existing legacy form layout.          |
+
+### Behavior
+
+- **Mouse and touch**: Users can place the cursor in the field, select text, and activate any nested trailing or leading action independently.
+- **Keyboard**: Users tab to the input, type or edit the value, and use native text editing shortcuts.
+- **Focus management**: Focus lands on the native input. Leading or trailing actions that are interactive should have their own accessible name and keyboard behavior.
+- **Controlled state**: Use `value` and `onChange` when product state owns the value. Use `defaultValue` for simple uncontrolled form fields.
+- **Validation**: Show validation after users submit, blur the field, or otherwise finish interacting. Avoid showing errors before users have a chance to enter a value.
+
+### Accessibility
+
+- Provide a visible `label` whenever possible. Use `aria-label` or `aria-labelledby` only when a visible label is not available.
+- Use `helperText` for guidance and `errorMessage` with `invalid` for validation feedback.
+- Pair invalid values with `invalid` and an actionable `errorMessage`.
+- Use native text-like `type` values so browsers can expose the right keyboard, autocomplete, and validation behavior.
+- Keep disabled fields out of the editing flow only when users cannot act on them. Use read-only fields when the value should remain focusable or copyable.
+- Do not rely on color alone to communicate validation, disabled, or read-only state.
+
+### Content
+
+- Write labels as short nouns, such as "Customer name", "Email address", or "Invoice prefix".
+- Use placeholder text for examples, not instructions that replace the label.
+- Use helper text for constraints that prevent errors, such as expected format, length, or source of the value.
+- Write error messages that name the problem and recovery step, such as "Enter a valid email address."
+- Mark optional fields only when the form otherwise implies fields are required.
+
+### Related
+
+- **[TextField](components-forms-textfield.md)**: preferred replacement for TextInput in new React usage.
+- **[Select](components-forms-select.md)**: use when users choose from a shorter closed list.
+- **[ComboBox](components-forms-combobox.md)**: use when users choose from a list and typing should filter options.
+- **[IconButton](components-buttons-iconbutton.md)**: use for compact actions inside trailing or leading content.
+
+## React
+
+TextInput is deprecated. Use TextField for new React usage.
+
+```tsx
+import { TextInput } from '@maxio-com/react-ui-components';
+```
+
+TextInput accepts text input props and renders a single native input. Use
+`leadingElement` or `trailingElement` for compact field-level context or
+actions, and give interactive elements their own accessible names.
+
+## State Management
+
+Use controlled state when product logic needs to validate, transform, save, or share the current value. TextInput's `onChange` callback receives the next string value.
+
+### Controlled
+
+```tsx
+const [value, setValue] = React.useState('');
+
+<TextInput label="Customer name" value={value} onChange={setValue} />;
+```
+
+### Uncontrolled
+
+```tsx
+<TextInput
+  label="Customer name"
+  defaultValue="Acme Co."
+  onChange={(value) => console.log(value)}
+/>
+```
+
+## Imports
+
+```tsx
+import { Body, Icon, IconButton, TextInput } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### TextInput
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | no | `false` | Disable the text input | TextInputProps |
+| `errorMessage` | `string` | no | - | Error message for the text input | TextInputProps |
+| `fullWidth` | `boolean` | no | - | Ensures the input spans the full width of its parent | TextInputProps |
+| `helperText` | `string` | no | - | Helper text for the text input. It will not be visible if there is an error message. | TextInputProps |
+| `invalid` | `boolean` | no | `false` | Invalid state of the text input | TextInputProps |
+| `label` | `string` | no | - | Label for the text input | TextInputProps |
+| `leadingElement` | `ReactNode` | no | `null` | Leading element for the text input | TextInputProps |
+| `onChange` | `(value: string) => void` | yes | - | Callback function for the text input change | TextInputProps |
+| `readOnly` | `boolean` | no | `false` | - | TextInputProps |
+| `showErrorMessage` | `boolean` | no | `true` | Show error message | TextInputProps |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | no | `md` | Size of the text input | TextInputProps |
+| `trailingElement` | `ReactNode` | no | `null` | Trailing element for the text input | TextInputProps |
+
+## Stories
+
+### Default
+
+TextInput is deprecated; use TextField for new React usage. Keep existing TextInput usage labeled, and use placeholder text only as an example of the expected value.
+
+```tsx
+const Default = () => <TextInput
+    label="Customer name"
+    placeholder="Acme Co."
+    onChange={action('onChange')} />;
+```
+
+### With Helper Text
+
+Use helper text for format hints, examples, or constraints that help users enter a valid value before validation runs.
+
+```tsx
+const WithHelperText = () => <TextInput
+    label="Invoice prefix"
+    placeholder="INV"
+    helperText="Use 2-5 letters that identify this invoice series."
+    onChange={action('onChange')} />;
+```
+
+### With Icon
+
+Use an icon when existing TextInput usage benefits from compact visual context. Keep the icon decorative unless it is exposed through an interactive element.
+
+```tsx
+const WithIcon = () => <TextInput
+    label="Signature"
+    placeholder="John Hancock"
+    onChange={action('onChange')}
+    leadingElement={<Icon variant="signature" />} />;
+```
+
+### With Text
+
+Use leading or trailing text for compact units, prefixes, suffixes, or other field-level context in existing TextInput forms.
+
+```tsx
+const WithText = () => <TextInput
+    label="Price"
+    placeholder="1.00"
+    onChange={action('onChange')}
+    leadingElement={<Body size="sm">€</Body>}
+    trailingElement={<Body size="sm">EUR</Body>} />;
+```
+
+### Validation
+
+Use invalid with errorMessage so assistive technology receives invalid state and users get actionable validation feedback.
+
+```tsx
+const Validation = () => <TextInput
+    label="Email address"
+    placeholder="billing@example.com"
+    type="email"
+    invalid
+    errorMessage="Enter a valid email address."
+    onChange={action('onChange')} />;
+```
+
+### Disabled
+
+Use disabled fields when the value is unavailable and users cannot act on it in the current context.
+
+```tsx
+const Disabled = () => <TextInput
+    label="Billing contact"
+    placeholder="Select an account first"
+    disabled
+    onChange={action('onChange')} />;
+```
+
+### Read Only
+
+Use read-only fields when the value should remain selectable and readable but cannot be edited.
+
+```tsx
+const ReadOnly = () => <TextInput
+    label="Account ID"
+    value="acct_12345"
+    readOnly
+    onChange={action('onChange')} />;
+```
+
+### With Leading Element
+
+Use an interactive leading element when legacy TextInput usage needs a compact action inside the input. Match the IconButton size to the input size.
+
+```tsx
+const WithLeadingElement = () => <TextInput
+    label="Date"
+    placeholder="mm/dd/yyyy"
+    onChange={action('onChange')}
+    leadingElement={
+      <IconButton
+        icon={<Icon variant="calendar" />}
+        variant="ghost"
+        size="sm"
+        aria-label="Select a date"
+      />
+    } />;
+```
+
+### With Trailing Element
+
+Use an interactive trailing element when the field needs a compact action inside the input. Give the action its own accessible name.
+
+```tsx
+const WithTrailingElement = () => <TextInput
+    label="Password"
+    type="password"
+    onChange={action('onChange')}
+    trailingElement={
+      <IconButton
+        icon={<Icon variant="eye" />}
+        variant="ghost"
+        size="sm"
+        aria-label="Password shown"
+      />
+    } />;
+```

package/dist/skills/maxio-react/references/foundations-dark-mode.md

@@ -0,0 +1,85 @@
+# Dark Mode
+
+The dark mode is a feature that allows you to switch between a light and dark theme in a per-component basis. The consistency of the dark mode is important for the user experience—that's why we rely on the semantic design tokens.
+
+To learn more about how the design tokens are implemented to achieve this, please refer to the [Design Tokens Repository](https://github.com/maxio-com/front-end-platform/blob/main/packages/design-tokens/README.md#dark-mode) documentation.
+
+## Usage
+
+To enable the dark mode, you need to add the `data-maxio-mode="dark"` attribute to the root element of your component.
+
+```html
+<div data-maxio-mode="dark">
+  <!-- Your component here -->
+</div>
+```
+
+OR
+
+```html
+<button class="maxio-button maxio-button--primary" data-maxio-mode="dark">
+  Click me
+</button>
+```
+
+To enforce light mode, you can use the `data-maxio-mode="light"` attribute.
+
+```html
+<button class="maxio-button maxio-button--primary" data-maxio-mode="light">
+  Click me
+</button>
+```
+
+## Dark Mode in Storybook
+
+You can control the mode in Storybook via theme addon on the top left corner of the preview window. Try it now.
+
+**Example:**
+
+## Nesting Components
+
+When you have a component that contains other components, you can nest the dark mode attribute to the root element of the child component.
+In regular conditions, all your child components will inherit the dark mode from the parent component. However, you can force a child component to use a different mode by adding the `data-maxio-mode` attribute to the root element of the child component.
+
+## Imports
+
+```tsx
+import { Button } from "@maxio-com/react-ui-components";
+```
+
+## Stories
+
+### Example
+
+```tsx
+const Example = () => <Button>Button</Button>;
+```
+
+### Nested Components
+
+```tsx
+const NestedComponents = () => (
+  <div className="maxio-flex maxio-flex-col maxio-gap-4 maxio-items-start">
+    <Button variant="primary">Default button</Button>
+    <div>
+      <p className="maxio-heading-md" style={{ marginBottom: '.25rem' }}>
+        Nested in a dark mode parent
+      </p>
+      <div
+        data-maxio-mode="dark"
+        className="maxio-flex maxio-flex-col maxio-gap-4"
+        style={{
+          backgroundColor: 'var(--maxio-color-bg-secondary)',
+          padding: '1rem',
+          borderRadius: '0.25rem',
+        }}
+      >
+        <Button variant="primary">Dark mode button</Button>
+        <Button variant="primary" data-maxio-mode="light">
+          Forced light mode
+        </Button>
+      </div>
+    </div>
+  </div>
+);
+```

package/dist/skills/maxio-react/references/foundations-design-tokens-about.md

@@ -0,0 +1,108 @@
+# Design Tokens
+
+Design tokens are a crucial aspect of design systems. They are atomic units of design that represent visual properties such as colors, typography, spacing, and more. These tokens serve as the foundation for maintaining consistency and scalability across various digital products and platforms.
+
+You can learn more about design tokens in our [Maxio Design System Hub](https://www.notion.so/maxioevolution/Design-tokens-7e2081d708d6485396e3237cbb8028c7).
+
+## Benefits of Design Tokens
+
+- **Consistency:** By using design tokens, designers and developers ensure that visual elements remain consistent across all products and platforms.
+- **Scalability:** Design tokens make it easier to scale design systems. As products evolve and grow, updating visual properties becomes more manageable through token adjustments.
+- **Flexibility:** Tokens allow for quick iterations and experimentation. Changing a token value can automatically update all instances throughout the system.
+
+## Types of Design Tokens
+
+1. **Color Tokens:** Representing a palette of colors used throughout the design system.
+2. **Typography Tokens:** Including font families, sizes, weights, and line heights.
+3. **Spacing Tokens:** Defining space between elements such as margins, padding, and grid gutters.
+4. **Border Tokens:** Specifying border widths, styles, and colors.
+5. **Shadow Tokens:** Describing shadow effects used in UI components.
+6. **Icon Tokens:** Identifying icon sizes and styles.
+
+## Light and Dark Mode Support
+
+Our design tokens accommodates both light and dark modes to ensure a seamless user experience across different environments. By defining design tokens for colors, typography, and other visual properties that adapt to light and dark themes, designers can ensure consistency and readability in various contexts.
+
+## Naming Conventions
+
+Our naming convention is ordered from the most generic categories to more specific. This is an intentional way of ordering each category to build upon one another, resulting in tokens that have natural, human-friendly names.
+
+```
+$namespace-category-element-status-emphasis-state
+```
+
+#### Example
+
+```
+--maxio-color-border-success-primary-hover
+```
+
+## How to Use the Design Tokens Package
+
+<br />
+
+### Install with CSS
+
+Replace `$VERSION` with the release version that you would like to use.
+
+```html
+<link rel="stylesheet" href="https://ui.maxio.com/$VERSION/variables.css" />
+```
+
+### Install with Your Favorite Package Manager
+
+Make sure you use compatible styles version (available in the [package readme](https://www.npmjs.com/package/@maxio-com/react-ui-components)).
+
+```
+pnpm install @maxio-com/design-tokens
+```
+
+```
+yarn add @maxio-com/design-tokens
+```
+
+```
+npm install @maxio-com/design-tokens
+```
+
+Then import it in your project:
+
+```js
+import { tailwindTheme } from '@maxio-com/design-tokens';
+```
+
+### Using Color Tokens in a Project
+
+In Maxio Theme (TailwindCSS), color tokens are applied with the following syntax:
+
+**Semantic tokens**
+
+```html
+<div class="bg-secondary border-info">...<//div>
+```
+
+**Primitive tokens**
+
+```html
+<div class="border-blue-80 bg-gray-05">...</div>
+```
+
+In any other situation:
+
+**Semantic tokens**
+
+```css
+.my-component {
+  background-color: var(--maxio-color-bg-secondary);
+  border-color: var(--maxio-color-border-info);
+}
+```
+
+**Primitive tokens**
+
+```css
+.my-component {
+  background-color: var(--maxio-color-gray-40);
+  border-color: var(--maxio-color-blue-100);
+}
+```

package/dist/skills/maxio-react/references/foundations-design-tokens-colors-primitive-colors.md

@@ -0,0 +1,33 @@
+# Primitive Colors
+
+These are the core colors used throughout the design system. They form the foundation for the full color palette, semantic tokens, and component styles.
+
+Whenever possible, **default to using [Semantic Colors](foundations-design-tokens-colors-semantic-colors.md).** Before reaching for a primitive color, check if a semantic token meets your needs.
+
+## Colors
+
+<br />
+
+<style>
+  {`
+  .wrapper .docblock-colorpalette > div > div {
+    flex-basis: 15%;
+  }
+
+  .wrapper .docblock-colorpalette span {
+    display: none;
+  }
+`}
+</style>
+
+<div className="wrapper">
+  <ColorPalette>
+    {Object.entries(tailwindTheme.colors).map(([name, colors]) => {
+      const sorted =
+        typeof colors === 'string'
+          ? { [name]: colors }
+          : returnOrderedColors(colors);
+      return <ColorItem key={name} title={name} colors={sorted} />;
+    })}
+  </ColorPalette>
+</div>

package/dist/skills/maxio-react/references/foundations-design-tokens-colors-semantic-colors.md

@@ -0,0 +1,11 @@
+# Semantic Colors
+
+Semantic colors help align Maxio's UI with user intent and accessibility needs. These tokens adapt automatically to light and dark modes, ensuring consistency across themes. **Use semantic color tokens whenever possible** to promote clarity, cohesion, and future flexibility.
+
+If a suitable semantic color isn't available, you may use [Primitive Colors](foundations-design-tokens-colors-primitive-colors.md) as a fallback.
+
+## Colors
+
+<br />
+
+<ColorsCollection />

package/dist/skills/maxio-react/references/foundations-start-here.md

@@ -0,0 +1,128 @@
+# Maxio Design System
+
+The goal of this project is to create a consistent user experience across all Maxio products. The current version of the library supports both **React** and plain **HTML/CSS**. It’s designed to improve developer experience and boost productivity by handling the foundational UI work, so you can focus on building great features instead of reinventing the basics.
+
+[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-yellow.svg)](https://github.com/prettier/prettier)
+[![tested with jest](https://img.shields.io/badge/tested_with-jest-99424f.svg)](https://facebook.github.io/jest/)
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+[![pnpm](https://img.shields.io/badge/maintained%20with-pnpm-cc00ff.svg)](https://pnpm.io/)
+
+<br />
+
+## Getting Started with HTML/CSS
+
+<br />
+
+### Install the Stylesheet
+
+Include the snippet with stylesheet CSS file on your page:
+
+You can also replace the version above with any specific release of the `@maxio-com/ui-components` package. All available versions are listed [here](https://github.com/maxio-com/front-end-platform/releases).
+
+### Install Fonts
+
+The [Inter](https://fonts.google.com/specimen/Inter) font is not a part of a Design System and will be not loaded automatically.
+We recommend using the Google Fonts service to load the font from a CDN.
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap"
+  rel="stylesheet"
+/>
+```
+
+### Install Font Awesome Icons
+
+We host our library of custom icons on Font Awesome. To use any of these icons, you must include the CSS for our kit in your project.
+
+```html
+<link
+  rel="stylesheet"
+  href="https://kit.fontawesome.com/6743334a5d.css"
+  crossorigin="anonymous"
+/>
+```
+
+### Example HTML/CSS Install
+
+The code snippet presented below shows an `HTML` page with the design system installed and an example of rendering a simple `icon` component.
+`$VERSION` should be replaced with the specific release version you'd like to use. (<code>{getLatestRelease()}</code> is the latest.)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="stylesheet" href="https://ui.maxio.com/$VERSION/styles.css" />
+  </head>
+  <body>
+    <i class="fa-kit fa-bank"></i>
+  </body>
+</html>
+```
+
+### Design Tokens
+
+If you're using the HTML/CSS version of the Maxio Design System, you'll also need to install the `@maxio-com/design-tokens` package. This includes the CSS variables for colors, fonts, spacing, and other foundational styles used across our components.
+
+For setup instructions, refer to our [Design Tokens documentation](foundations-design-tokens-about.md).
+
+<br />
+
+## Getting Started with React
+
+If your project uses React, install the Maxio component library using your preferred package manager:
+
+```
+npm install --save @maxio-com/react-ui-components
+```
+
+```
+yarn add @maxio-com/react-ui-components
+```
+
+```
+pnpm add @maxio-com/react-ui-components
+```
+
+Then, import components individually:
+
+```jsx
+import { Button } from '@maxio-com/react-ui-components';
+```
+
+You can find the correct import path for each component in its Storybook example.
+
+## How to Use Storybook
+
+This Storybook serves as the source of truth for the Maxio Design System. It includes all available components, along with usage guidelines, examples, and instructions for using them in your projects.
+
+We've provided tools to enable you to easily compose React components right in Storybook.
+
+Each component's main documentation includes a **Playground** section, which lists the customizable props associated with that component. Simply configure these props and click "Show Code" to view the JSX for your configured component, ready to copy and paste.
+
+You can also configure components from within each Story. Select the Story and open the **Controls** tab in the Addons panel to toggle props as needed.
+
+Note that most documented props are custom to our design system. Standard attributes (like `href` or `target` on a Link component) are not always listed, since they’re part of the underlying HTML element and not specific to our components.
+
+To learn more about how to properly use a component, visit its main documentation page.
+
+### Using HTML/CSS?
+
+If you're working with HTML/CSS, composing a component works much the same way.
+
+Select the Story, adjust the props in the **Controls** tab of the Addons panel, then open the **HTML** tab to view and copy the generated markup directly into your project.
+
+Note: When composing with HTML/CSS, it’s important to ensure your components meet ARIA accessibility requirements. While the React library includes these features by default, using the HTML/CSS library means you’ll need to add appropriate roles and attributes yourself, following Maxio’s accessibility guidelines. For help, refer to the [WAI-ARIA Authoring Best Practices Guide](https://www.w3.org/WAI/ARIA/apg).
+
+## More Resources
+
+Want to learn even more? Check out the [Maxio Design System Hub](https://www.notion.so/maxioevolution/1802f1e19a89453089a67c8aadcbd10a?v=b111ca816dc744ae8be3a982bdac33b2&source=copy_link) in Notion. This resource provides guidelines, principles, and patterns for designing and building UI at Maxio.
+
+## Questions and Feedback
+
+The Maxio Design System is a work in progress. Our team is working hard to continue expanding and improving what this library offers.
+
+If you have requests, feedback, or questions about the system, components, or how to use them, please reach out to us on our public Slack channel, **#maxio-design-system**.