@cube-dev/ui-kit 0.0.0-canary-c210a8c → 0.0.0-canary-60981ef

package/docs/components/fields/Switch.md

@@ -0,0 +1,174 @@
+# Switch
+
+A switch allows users to toggle between two states: on and off. It provides immediate feedback and is commonly used for enabling/disabling features, settings, or binary choices.
+
+## When to Use
+
+- Enable or disable features, settings, or options
+- Toggle between two mutually exclusive states
+- Control real-time changes that take effect immediately
+- Provide on/off controls in forms and preference panels
+- Create compact binary controls where space is limited
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** `string` — The content to display as the switch label
+- **`label`** `string` — External label for the switch
+- **`isSelected`** `boolean` (default: `false`) — Whether the switch is selected (controlled)
+- **`defaultSelected`** `boolean` (default: `false`) — Whether the switch is selected by default (uncontrolled)
+- **`isDisabled`** `boolean` (default: `false`) — Whether the switch is disabled
+- **`isReadOnly`** `boolean` (default: `false`) — Whether the switch can be focused but not changed
+- **`isRequired`** `boolean` (default: `false`) — Whether the switch must be toggled before form submission
+- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions
+- **`validationState`** `undefined | 'valid' | 'invalid'` — Whether the switch should display valid or invalid visual styling
+- **`autoFocus`** `boolean` (default: `false`) — Whether the element should receive focus on render
+- **`size`** `'small' | 'medium' | 'large'` (default: `large`) — Switch size
+- **`onChange`** — Callback fired when the switch value changes
+- **`onFocus`** — Callback fired when the switch receives focus
+- **`onBlur`** — Callback fired when the switch loses focus
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root wrapper element of the component.
+
+#### inputStyles
+
+Customizes the switch toggle element specifically.
+
+**Sub-elements:**
+- `Thumb` - The movable indicator inside the switch
+
+#### fieldStyles
+
+Customizes the field wrapper element when the switch is used with labels or validation.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+`margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| checked | `boolean` | Whether the switch is in the "on" state |
+| disabled | `boolean` | Whether the switch is disabled |
+| invalid | `boolean` | Whether the switch has validation errors |
+| valid | `boolean` | Whether the switch is valid |
+| focused | `boolean` | Whether the switch has focus |
+| hovered | `boolean` | Whether the switch is being hovered |
+| side-label | `boolean` | Whether the label is positioned to the side |
+| inside-form | `boolean` | Whether the switch is inside a form field |
+
+## Variants
+
+### Sizes
+
+- `small` - Compact size for dense interfaces
+- `medium` - Standard size (default)
+- `large` - Larger size for emphasis
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<Switch>Enable notifications</Switch>
+```
+
+### With Default State
+
+### Controlled State
+
+```jsx
+const [isEnabled, setIsEnabled] = useState(false);
+
+<Switch
+  isSelected={isEnabled}
+  onChange={setIsEnabled}
+>
+  Feature enabled: {isEnabled ? 'On' : 'Off'}
+</Switch>
+```
+
+### All Sizes
+
+### With Validation
+
+### Disabled State
+
+### Loading State
+
+### All States Overview
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the switch
+- `Space` - Toggles the switch state
+- `Enter` - Toggles the switch state
+
+### Screen Reader Support
+
+- Component announces as "switch" to screen readers
+- Current state is announced (e.g., "on", "off")
+- State changes are immediately announced
+- Loading state is communicated when present
+
+### ARIA Properties
+
+- `aria-label` - Provides accessible label when no visible label exists
+- `aria-labelledby` - References external label elements
+- `aria-describedby` - References additional descriptive text
+- `aria-checked` - Indicates switch state (true/false)
+- `aria-required` - Indicates if toggling is required
+- `aria-invalid` - Indicates validation state
+
+## Best Practices
+
+1. **Do**: Use clear, descriptive labels that indicate what the switch controls
+   ```jsx
+   <Switch>Enable email notifications</Switch>
+   ```
+
+2. **Don't**: Use switches for actions that require additional steps
+   ```jsx
+   <Switch>Delete account</Switch> {/* Use Button instead */}
+   ```
+
+3. **Immediate Effect**: Use switches for settings that take effect immediately
+4. **State Clarity**: Make it clear what "on" and "off" states mean
+5. **Grouping**: Group related switches together in settings panels
+6. **Labels**: Always provide meaningful labels for screen readers
+
+## Integration with Forms
+
+This component supports all [Field properties](../form/Field.md) when used within a Form.
+
+## Suggested Improvements
+
+- Add support for custom thumb icons or content
+- Implement animation customization options
+- Add support for intermediate/indeterminate states
+- Consider adding color customization for different switch types
+- Implement grouped switch controls for related settings
+
+## Related Components
+
+- [Checkbox](./Checkbox.md) - For selection that doesn't take immediate effect
+- [RadioGroup](./RadioGroup.md) - For selecting one option from multiple choices
+- [Button](../actions/Button.md) - For actions that require confirmation

package/docs/components/fields/TextArea.md

@@ -0,0 +1,61 @@
+# TextArea
+
+<Badge variant="neutral">Form component</Badge>
+
+The TextArea component is a multi-line text input that allows users to enter and edit longer text content. It supports auto-sizing functionality and various text input features like validation and formatting.
+
+## Examples
+
+### With Default Value
+
+### With Icon
+
+### Auto Size
+
+### Auto Size with Max Rows
+
+## Variants
+
+### Sizes
+
+- `small` - Compact size for dense interfaces
+- `medium` - Standard size for most use cases
+- `large` - Emphasized size for important text areas
+
+## Properties
+
+## Sub-elements
+
+The TextArea component renders the following sub-elements that can be customized via the `styles` prop:
+
+- **Prefix**: Content displayed before the input area
+- **Suffix**: Content displayed after the input area
+- **State**: Container for validation and loading indicators
+- **InputIcon**: Icon displayed within the input
+
+## Style Properties
+
+The TextArea component supports all standard style properties:
+
+`display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`, `textAlign`, `color`, `fill`, `fade`, `textTransform`, `fontWeight`, `fontStyle`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
+## Accessibility
+
+The TextArea component follows WAI-ARIA guidelines:
+
+- Uses semantic `textarea` HTML element
+- Supports proper keyboard navigation and text selection
+- Associates labels with the input element using `aria-labelledby`
+- Provides clear focus indicators
+- Announces validation states and error messages to screen readers
+- Supports auto-completion and spell-checking
+
+## Best Practices
+
+- Use descriptive labels that clearly indicate the expected content
+- Provide placeholder text for additional context when appropriate
+- Set appropriate `rows` to indicate expected content length
+- Use `autoSize` for dynamic content that may vary in length
+- Consider `maxRows` to prevent excessive vertical growth
+- Provide clear validation messages when input is invalid
+- Use read-only state for displaying non-editable content

package/docs/components/fields/TextInput.md

@@ -0,0 +1,204 @@
+# TextInput
+
+A text input component that allows users to input custom text entries with a keyboard. Built with React Aria's `useTextField` hook for full accessibility and the Cube `tasty` style system for theming.
+
+## When to Use
+
+- Collect single-line text input from users (names, emails, URLs)
+- Create multiline text areas for longer content
+- Build forms with validation and field decoration
+- Implement search inputs with icons and prefixes
+- Handle password inputs with proper masking
+
+## Component
+
+---
+
+### Properties
+
+- **`value`** `string` — The text value in controlled mode
+- **`defaultValue`** `string` — The default text value in uncontrolled mode
+- **`placeholder`** `string` — Placeholder text when input is empty
+- **`icon`** — Icon element rendered before the input
+- **`prefix`** — Input decoration before the main input
+- **`suffix`** — Input decoration after the main input
+- **`type`** `'text' | 'password' | 'email' | 'url' | 'tel' | 'search'` (default: `text`) — Input type
+- **`multiLine`** `boolean` (default: `false`) — Whether the input is multiline (textarea)
+- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
+- **`isDisabled`** `boolean` (default: `false`) — Whether the input is disabled
+- **`isReadOnly`** `boolean` (default: `false`) — Whether the input can be selected but not changed
+- **`isRequired`** `boolean` (default: `false`) — Whether user input is required before form submission
+- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions
+- **`validationState`** `undefined | 'valid' | 'invalid'` — Whether the input should display valid or invalid visual styling
+- **`autoFocus`** `boolean` (default: `false`) — Whether the element should receive focus on render
+- **`onChange`** `function` — Callback fired when the input value changes
+- **`onBlur`** `function` — Callback fired when the input loses focus
+- **`onFocus`** `function` — Callback fired when the input receives focus
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+**Sub-elements:**
+- `InputWrapper` – container around the input field
+- `Prefix` – wrapper around prefix content
+- `Suffix` – wrapper around suffix content
+- `State` – container for validation and loading icons
+- `InputIcon` – wrapper around the main icon
+- `ValidationIcon` – wrapper around validation state icons
+
+#### inputStyles
+
+Customizes the input element itself.
+
+#### wrapperStyles
+
+Customizes the input wrapper container.
+
+### Style Properties
+
+The TextInput component supports all standard style properties:
+
+`display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`, `textAlign`, `color`, `fill`, `fade`, `textTransform`, `fontWeight`, `fontStyle`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
+### Modifiers
+
+The `mods` prop accepts the following modifiers you can override:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| focused | `boolean` | Forces focus ring appearance. |
+| disabled | `boolean` | Forces disabled appearance. |
+| invalid | `boolean` | Forces invalid state styling. |
+| valid | `boolean` | Forces valid state styling. |
+| loading | `boolean` | Displays loading spinner. |
+| prefix | `boolean` | Indicates presence of prefix content. |
+| suffix | `boolean` | Indicates presence of suffix content. |
+
+## Variants
+
+### Types
+
+- `text` – Standard text input (default)
+- `password` – Masked password input
+- `email` – Email input with validation
+- `url` – URL input with validation
+- `tel` – Telephone number input
+- `search` – Search input styling
+
+### Sizes
+
+- `small` – Compact height for dense interfaces
+- `medium` – Standard height for most use cases
+- `large` – Emphasized height for important inputs
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<TextInput
+  label="Name"
+  placeholder="Enter your name"
+  onChange={(value) => console.log(value)}
+/>
+```
+
+### With Icon
+
+```jsx
+import { IconMail } from '@tabler/icons-react';
+
+<TextInput
+  label="Email"
+  type="email"
+  icon={<IconMail />}
+  placeholder="Enter your email"
+/>
+```
+
+### Multiline Text Area
+
+```jsx
+<TextInput
+  label="Description"
+  multiLine
+  rows={4}
+  placeholder="Enter description..."
+/>
+```
+
+### With Validation
+
+```jsx
+<TextInput
+  label="Username"
+  isRequired
+  validationState="invalid"
+  message="Username must be at least 3 characters"
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` – Moves focus to the input field
+- `Shift + Tab` – Moves focus away from the input
+- Standard text editing shortcuts (Ctrl+A, Ctrl+C, etc.)
+
+### Screen Reader Support
+
+- Announces role "textbox" or "searchbox" for search inputs
+- Announces label, description, and validation messages
+- State changes like "invalid" or "required" are announced
+- Loading state is announced to screen readers
+
+### ARIA Properties
+
+- `aria-label`, `aria-labelledby` – Accessible name for the input
+- `aria-describedby` – Links to description and error messages
+- `aria-invalid` – Managed automatically based on `validationState`
+- `aria-required` – Set when `isRequired` is true
+- Additional ARIA attributes supported by React Aria's `useTextField`
+
+## Best Practices
+
+1. **Do**: Provide clear labels and helpful placeholder text
+   ```jsx
+   <TextInput label="Email Address" placeholder="you@example.com" />
+   ```
+
+2. **Don't**: Use placeholder text as the only label
+   ```jsx
+   {/* Avoid this */}
+   <TextInput placeholder="Enter your email" />
+   ```
+
+3. **Accessibility**: Always provide proper labels for screen readers
+4. **Validation**: Use `validationState` and `message` for user feedback
+5. **Performance**: Use `defaultValue` for uncontrolled inputs when possible
+
+## Integration with Forms
+
+This component supports all [Field properties](../form/Field.md) when used within a Form.
+
+## Suggested Improvements
+
+- Add `autoComplete` prop mapping for better browser integration
+- Provide `maxLength` indicator with character count
+- Support for input masks and formatting
+- Built-in debouncing for onChange events
+
+## Related Components
+
+- [TextArea](./TextArea.md) – Dedicated multiline text input
+- [SearchInput](./SearchInput.md) – Specialized search input with clear button
+- [PasswordInput](./PasswordInput.md) – Enhanced password input with show/hide toggle
+- [NumberInput](./NumberInput.md) – Numeric input with increment/decrement controls

package/docs/components/fields/TextInputMapper.md

@@ -0,0 +1,34 @@
+# TextInputMapper
+
+The TextInputMapper component allows users to create and manage key-value pairs dynamically. It provides an interface for adding, editing, and removing mappings with customizable input components for both keys and values.
+
+## Properties
+
+## Sub-elements
+
+The TextInputMapper component is a complex compound component that doesn't expose styled sub-elements via the `styles` prop. Instead, it uses internal layout components and delegates styling to its key and value input components.
+
+## Style Properties
+
+The TextInputMapper component supports all standard style properties:
+
+`display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`, `textAlign`, `color`, `fill`, `fade`, `textTransform`, `fontWeight`, `fontStyle`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
+## Accessibility
+
+The TextInputMapper component follows WAI-ARIA guidelines:
+
+- Uses semantic form controls for key-value inputs
+- Provides clear labeling for all interactive elements
+- Supports keyboard navigation between fields and actions
+- Announces changes when mappings are added or removed
+- Associates labels with input elements using appropriate ARIA attributes
+
+## Best Practices
+
+- Use descriptive labels that clearly indicate the purpose of the key-value pairs
+- Provide appropriate `actionLabel` text for the add button
+- Consider using custom components for specialized input types
+- Set appropriate validation on both key and value inputs
+- Use `allowsCustomValue` when users need flexibility in value selection
+- Provide clear feedback when validation fails on individual pairs