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

package/docs/components/fields/NumberInput.md

@@ -0,0 +1,184 @@
+# NumberInput
+
+A number input component that allows users to enter numeric values and increment or decrement them using stepper buttons. Built with React Aria's `useNumberField` for accessibility and the Cube `tasty` style system for theming.
+
+## When to Use
+
+- Collect numeric input (quantities, prices, ages, etc.)
+- Allow users to increment/decrement values with stepper controls
+- Enforce min/max/step constraints on numbers
+- Build forms with validation and field decoration
+- Support both controlled and uncontrolled usage
+
+## Component
+
+---
+
+### Properties
+
+- **`value`** `number` — The numeric value in controlled mode
+- **`defaultValue`** `number` — The default numeric value in uncontrolled mode
+- **`placeholder`** `string` — Placeholder text when input is empty
+- **`prefix`** — Input decoration before the main input
+- **`suffix`** — Input decoration after the main input
+- **`hideStepper`** `boolean` (default: `false`) — Whether to hide the stepper buttons
+- **`minValue`** `number` — Minimum allowed value
+- **`maxValue`** `number` — Maximum allowed value
+- **`step`** `number` — Amount to increment or decrement the value
+- **`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 NumberInput 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
+
+- `number` – Standard number input (default)
+
+### Sizes
+
+- `small` – Compact height for dense interfaces
+- `medium` – Standard height for most use cases
+- `large` – Emphasized height for important inputs
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<NumberInput label="Quantity" placeholder="Enter a number" />
+```
+
+### With Stepper Hidden
+
+```jsx
+<NumberInput label="Amount" hideStepper />
+```
+
+### With Min/Max/Step
+
+```jsx
+<NumberInput label="Age" minValue={0} maxValue={120} step={1} />
+```
+
+### With Validation
+
+```jsx
+<NumberInput
+  label="Price"
+  validationState="invalid"
+  errorMessage="Price must be positive"
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` – Moves focus to the input field
+- `Shift + Tab` – Moves focus away from the input
+- Arrow keys – Increment/decrement value
+- `Home`/`End` – Set to min/max value
+- Standard text editing shortcuts
+
+### Screen Reader Support
+
+- Announces role "spinbutton"
+- Announces label, description, and validation messages
+- Announces min/max/step constraints
+- 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 `useNumberField`
+
+## Best Practices
+
+1. **Do**: Provide clear labels and helpful placeholder text
+   ```jsx
+   <NumberInput label="Quantity" placeholder="0" />
+   ```
+
+2. **Don't**: Use placeholder text as the only label
+   ```jsx
+   {/* Avoid this */}
+   <NumberInput placeholder="Enter a number" />
+   ```
+
+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 `maxValue`/`minValue` indicator with value range
+- Support for input masks and formatting
+- Built-in debouncing for onChange events
+
+## Related Components
+
+- [TextInput](./TextInput.md) – Single-line or multiline text input
+- [Slider](./Slider.md) – For selecting a value from a range

package/docs/components/fields/PasswordInput.md

@@ -0,0 +1,218 @@
+# PasswordInput
+
+A password input is a specialized text field that masks user input to protect sensitive information like passwords, PINs, or security codes. It includes a toggle button to reveal or hide the password text for user convenience.
+
+## When to Use
+
+- Collect passwords, PINs, or other sensitive text data
+- Provide secure input fields in login and registration forms
+- Enable password creation with visibility toggle for verification
+- Collect security codes or tokens that should be masked by default
+- Offer accessible password entry with reveal functionality
+
+## Component
+
+---
+
+### Properties
+
+- **`value`** `string` — The password value in controlled mode
+- **`defaultValue`** `string` — The default password 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 (before toggle button)
+- **`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 wrapper element of the component.
+
+**Sub-elements:**
+- `Prefix` - Element displayed before the input
+- `Suffix` - Element displayed after the input (contains toggle button)
+- `State` - Container for validation state indicators
+- `InputIcon` - Icon displayed within the input area
+- `ValidationIcon` - Icon displayed for validation state
+
+#### inputStyles
+
+Customizes the password input field specifically.
+
+### Style Properties
+
+The PasswordInput 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` property accepts the following modifiers you can override:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| focused | `boolean` | Whether the input has focus |
+| disabled | `boolean` | Whether the password input is disabled |
+| invalid | `boolean` | Whether the password input has validation errors |
+| valid | `boolean` | Whether the password input is valid |
+| hovered | `boolean` | Whether the password input is being hovered |
+| inside-form | `boolean` | Whether the password input is inside a form field |
+
+## Variants
+
+### Sizes
+
+- `small` - Compact size for dense interfaces
+- `medium` - Standard size
+- `large` - Emphasized size for important password fields
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<PasswordInput
+  label="Password"
+  placeholder="Enter your password"
+/>
+```
+
+### With Icon
+
+```jsx
+<PasswordInput
+  label="Security Key"
+  icon={<IconKey />}
+  placeholder="Enter security key"
+/>
+```
+
+### With Validation
+
+```jsx
+<PasswordInput
+  label="New Password"
+  isRequired
+  validationState="invalid"
+  errorMessage="Password must be at least 8 characters"
+/>
+```
+
+### With Description
+
+```jsx
+<PasswordInput
+  label="Password"
+  description="Must be at least 8 characters with numbers and symbols"
+  placeholder="Create a strong password"
+/>
+```
+
+### Small Size
+
+```jsx
+<PasswordInput
+  label="PIN"
+  size="small"
+  placeholder="Enter 4-digit PIN"
+/>
+```
+
+### Disabled State
+
+```jsx
+<PasswordInput
+  label="Disabled password"
+  isDisabled
+  value="hidden-password"
+/>
+```
+
+### With Default Value
+
+```jsx
+<PasswordInput
+  label="Current Password"
+  defaultValue="existing-password"
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the password input
+- `Shift + Tab` - Moves focus to the toggle button
+- `Enter` - Toggles password visibility when toggle button is focused
+- `Space` - Toggles password visibility when toggle button is focused
+- All standard text input keyboard shortcuts work for text entry
+
+### Screen Reader Support
+
+- Component announces as "password" input type to screen readers
+- Toggle button announces its purpose ("Toggle masking", "Show password", "Hide password")
+- Current visibility state is communicated when changed
+- Validation errors and requirements are announced
+
+### 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-invalid` - Indicates validation state
+- `aria-required` - Indicates if password entry is required
+- Toggle button includes appropriate `aria-label` for its function
+
+## Best Practices
+
+1. **Do**: Provide clear password requirements and feedback
+   ```jsx
+   <PasswordInput
+     label="New Password"
+     description="8+ characters, including numbers and symbols"
+     validationState={isValid ? "valid" : "invalid"}
+   />
+   ```
+
+2. **Don't**: Use password input for non-sensitive data
+   ```jsx
+   <PasswordInput label="Username" /> {/* Use TextInput instead */}
+   ```
+
+3. **Security**: Always use HTTPS when handling password inputs
+4. **Validation**: Provide real-time validation feedback for password creation
+5. **Accessibility**: Ensure toggle button is easily accessible via keyboard
+6. **UX**: Include the visibility toggle for better user experience
+
+## Integration with Forms
+
+This component supports all [Field properties](../form/Field.md) when used within a Form.
+
+## Suggested Improvements
+
+- Add password strength indicator with visual feedback
+- Implement configurable password requirements validation
+- Add support for custom toggle button icons or text
+- Consider adding copy-to-clipboard functionality for generated passwords
+- Implement password suggestion/generation features
+
+## Related Components
+
+- [TextInput](./TextInput.md) - For non-sensitive text input
+- [NumberInput](./NumberInput.md) - For numeric PIN entries
+- [SearchInput](./SearchInput.md) - For search functionality