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

package/docs/components/content/Tag.md

@@ -0,0 +1,156 @@
+# Tag
+
+Tags are compact, inline elements used to label, categorize, or organize items. They provide visual metadata and can optionally be dismissed by users.
+
+## When to Use
+
+- **Categorization**: Label items with topics, categories, or types
+- **Filtering**: Display active filters or search criteria
+- **Status**: Show status indicators or states
+- **User Input**: Display selected items in multi-select scenarios
+- **Metadata**: Show additional information about content
+
+## When Not to Use
+
+- **Navigation**: Use `Button` or `Link` for navigation actions
+- **Actions**: Use `Button` for primary or secondary actions
+- **Long text**: Tags should contain short, scannable text
+- **Complex content**: For multi-line or detailed content, use `Badge` or `Card`
+
+## Component
+
+---
+
+### Properties
+
+### Base Properties
+
+Tag extends from `Item` component and supports all base design system properties including:
+- Layout props: `width`, `height`, `margin`, `padding`
+- Color props: `fill`, `color`, `border`
+- Typography props: `preset`, `fontSize`, `fontWeight`
+- Other Item props: `tooltip`, `isDisabled`, `qa`
+
+## Examples
+
+### Themes
+
+Tags support multiple themes for different semantic meanings:
+
+Available themes:
+- **Default**: Neutral, for general categorization
+- **Warning**: Yellow/amber, caution or attention needed
+- **Note**: Violet, informational content
+- **Success**: Green, positive states or completed actions
+- **Danger**: Red, errors or destructive actions
+- **Special**: Purple, highlighted or premium features
+- **Disabled**: Gray, inactive or unavailable items
+
+### With Icons
+
+Icons can be added to provide additional visual context:
+
+```jsx
+import { IconCoin } from '@tabler/icons-react';
+
+<Tag icon={<IconCoin />}>With Icon</Tag>
+```
+
+### Closable Tags
+
+Tags can be made dismissible with the `isClosable` prop:
+
+All themes support the closable variant:
+
+```jsx
+<Tag isClosable onClose={() => console.log('Tag closed')}>
+  Closable Tag
+</Tag>
+```
+
+### Closable with Icons
+
+Combine icons with closable functionality:
+
+### Sizes
+
+Tags support multiple sizes inherited from the Item component:
+
+- **inline** (default): Compact size that fits inline with text
+- **xsmall**: Extra small button-like size
+- **small**: Small button-like size
+- **medium**: Medium button-like size
+- **large**: Large button-like size
+
+### Custom Styles
+
+Apply custom styling using the `styles` prop:
+
+```jsx
+<Tag
+  styles={{
+    fill: '#purple.10',
+    color: '#purple',
+    border: '#purple.30',
+  }}
+>
+  Custom Tag
+</Tag>
+```
+
+## Best Practices
+
+### Content
+
+- Keep tag text short and scannable (1-3 words ideal)
+- Use sentence case for tag labels
+- Use consistent terminology across similar tags
+- Avoid punctuation unless necessary
+
+### Interaction
+
+- Only make tags closable when users can dismiss them
+- Provide feedback when a tag is closed (e.g., update list)
+- Consider confirmation for destructive closures
+- Ensure close buttons are accessible via keyboard
+
+### Visual Design
+
+- Use theme consistently for semantic meaning
+- Don't mix too many themes in the same group
+- Maintain adequate spacing between tags
+- Consider wrapping behavior for multiple tags
+
+### Accessibility
+
+- Tags have `role="status"` for screen readers
+- Close buttons include `aria-label="Close"`
+- All themes maintain sufficient color contrast
+- Keyboard navigation is fully supported via Item
+
+## Related Components
+
+- **Badge**: For numerical indicators or counts
+- **Chip**: For interactive selection chips
+- **Button**: For actions and navigation
+- **Item**: Base component that Tag extends from
+
+## Migration from Legacy Tag
+
+The Tag component now extends from `Item`, providing enhanced functionality:
+
+```jsx
+// Old API still works
+<Tag type="success">Legacy</Tag>
+
+// New API (preferred)
+<Tag theme="success">Modern</Tag>
+
+// New features from Item
+<Tag tooltip="Additional info" isDisabled>
+  With Tooltip
+</Tag>
+```
+
+The `type` prop is deprecated in favor of `theme` for consistency with other components.
+

package/docs/components/content/TextItem.md

@@ -0,0 +1,211 @@
+# TextItem
+
+A text component with built-in overflow handling and auto-tooltips. When text is truncated, a tooltip automatically appears on hover showing the full content. Also supports text highlighting for search results.
+
+## When to Use
+
+- Display text that may overflow its container with automatic tooltip fallback
+- Show search results with highlighted matching terms
+- Labels or descriptions in constrained layouts (sidebars, tables, lists)
+- Any text that needs ellipsis truncation with accessible full-text disclosure
+
+## Component
+
+---
+
+### Properties
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md) and all Text properties including `preset`, `color`, `weight`, `transform`, `ellipsis`, `nowrap`.
+
+### Styling Properties
+
+#### styles
+
+Customizes the root text element. Inherits all styling capabilities from the Text component.
+
+#### highlightStyles
+
+Customizes the appearance of highlighted text portions.
+
+### Style Properties
+
+These properties allow direct style application: `preset`, `color`, `weight`, `transform`, and all standard text/color style props.
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<TextItem>Simple text content</TextItem>
+```
+
+### Overflow with Auto-Tooltip
+
+When text overflows its container, hovering reveals a tooltip with the full content:
+
+```jsx
+<Block width="200px">
+  <TextItem>
+    This is a very long text that will be truncated with ellipsis
+    and show a tooltip on hover
+  </TextItem>
+</Block>
+```
+
+### Text Highlighting
+
+Highlight matching text within the content - useful for search results:
+
+```jsx
+<TextItem highlight="search">
+  Search results with highlighted text matching your query
+</TextItem>
+```
+
+### Custom Highlight Styles
+
+Customize the appearance of highlighted text with `highlightStyles`:
+
+```jsx
+<TextItem 
+  highlight="important" 
+  highlightStyles={{ fill: '#purple.20', color: '#purple' }}
+>
+  This important text has custom highlight styling
+</TextItem>
+```
+
+### Case-Sensitive Highlighting
+
+By default, highlighting is case-insensitive. Enable case-sensitive matching with `highlightCaseSensitive`:
+
+```jsx
+{/* Case-insensitive (default) - matches TEXT, text, Text */}
+<TextItem highlight="text">
+  TEXT and text and Text are all highlighted
+</TextItem>
+
+{/* Case-sensitive - only matches exact case */}
+<TextItem highlight="text" highlightCaseSensitive>
+  TEXT and text and Text - only lowercase is highlighted
+</TextItem>
+```
+
+### Multiple Highlights
+
+All occurrences of the highlight string are highlighted:
+
+```jsx
+<TextItem highlight="fox">
+  The quick brown fox jumps over the lazy fox
+</TextItem>
+```
+
+### Custom Tooltip
+
+Override the auto-tooltip with custom content:
+
+```jsx
+<TextItem tooltip="Custom tooltip text that differs from the content">
+  Short text
+</TextItem>
+```
+
+### Disabled Tooltip
+
+Disable the tooltip entirely:
+
+```jsx
+<TextItem tooltip={false}>
+  This text will truncate but won't show a tooltip
+</TextItem>
+```
+
+### Tooltip Placement
+
+Control where the tooltip appears:
+
+```jsx
+<TextItem tooltipPlacement="bottom">
+  Tooltip appears below on hover
+</TextItem>
+```
+
+### With Text Styles
+
+Apply typography and color styles:
+
+```jsx
+<TextItem preset="h3">Heading style</TextItem>
+<TextItem preset="t2" color="#purple">Colored text</TextItem>
+<TextItem weight="bold">Bold text</TextItem>
+```
+
+### Search Results List
+
+Common pattern for filterable lists with highlighted search terms:
+
+```jsx
+const items = ['Apple', 'Application', 'Banana', 'Apply', 'Grape'];
+const searchTerm = 'app';
+
+<Space flow="column" gap="0.5x">
+  {items.map((item) => (
+    <TextItem key={item} highlight={searchTerm}>
+      {item}
+    </TextItem>
+  ))}
+</Space>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the component (when tooltip is enabled)
+- Tooltip content is accessible via focus, not just hover
+
+### Screen Reader Support
+
+- Truncated text is fully accessible via tooltip
+- Highlighted text uses semantic `<mark>` element for screen reader announcement
+- Tooltip content is announced when triggered
+
+### ARIA Properties
+
+- Tooltip trigger automatically manages `aria-describedby` for tooltip association
+
+## Best Practices
+
+1. **Do**: Use for text that may exceed container width
+   ```jsx
+   <Block width="200px">
+     <TextItem>Long filename-that-might-overflow.tsx</TextItem>
+   </Block>
+   ```
+
+2. **Do**: Provide meaningful highlight terms for search
+   ```jsx
+   <TextItem highlight={userSearchQuery}>{result.title}</TextItem>
+   ```
+
+3. **Don't**: Use for multi-line text (this component enforces single-line with ellipsis)
+   ```jsx
+   {/* Use Text component instead for multi-line content */}
+   <Text>Multi-line paragraph content...</Text>
+   ```
+
+4. **Don't**: Disable tooltips for important truncated content
+   ```jsx
+   {/* Users won't be able to see the full text */}
+   <TextItem tooltip={false}>Important information that gets cut off...</TextItem>
+   ```
+
+## Related Components
+
+- Text - Base text component without overflow handling
+- [Item](./Item.md) - Interactive list item with similar overflow behavior
+- [TooltipProvider](../overlays/Tooltip.md) - Standalone tooltip wrapper
+

package/docs/components/fields/Checkbox.md

@@ -0,0 +1,180 @@
+# Checkbox
+
+Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected. They provide a clear visual indication of selection state and support indeterminate states for partially selected groups.
+
+## When to Use
+
+- Allow users to select multiple options from a list
+- Enable/disable features or settings in forms
+- Mark individual items as complete or selected
+- Show indeterminate state when some items in a group are selected
+- Create "Select All" functionality for data tables or lists
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** `string` — The content to display as the checkbox label
+- **`label`** `string` — External label for the checkbox
+- **`value`** `string` — Value for the checkbox when used in a group
+- **`isSelected`** `boolean` (default: `false`) — Whether the checkbox is selected (controlled)
+- **`defaultSelected`** `boolean` (default: `false`) — Whether the checkbox is selected by default (uncontrolled)
+- **`isIndeterminate`** `boolean` (default: `false`) — Whether the checkbox is in an indeterminate state
+- **`isDisabled`** `boolean` (default: `false`) — Whether the checkbox is disabled
+- **`isReadOnly`** `boolean` (default: `false`) — Whether the checkbox can be focused but not changed
+- **`isRequired`** `boolean` (default: `false`) — Whether the checkbox must be checked before form submission
+- **`validationState`** `undefined | 'valid' | 'invalid'` — Whether the checkbox 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 checkbox value changes
+- **`onFocus`** `function` — Callback fired when the checkbox receives focus
+- **`onBlur`** `function` — Callback fired when the checkbox loses focus
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root wrapper element of the component.
+
+#### inputStyles
+
+Customizes the checkbox input element specifically.
+
+### Style Properties
+
+The Checkbox 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 |
+|----------|------|-------------|
+| checked | `boolean` | Whether the checkbox is checked |
+| indeterminate | `boolean` | Whether the checkbox is in an indeterminate state |
+| invalid | `boolean` | Whether the checkbox has validation errors |
+| valid | `boolean` | Whether the checkbox is valid |
+| disabled | `boolean` | Whether the checkbox is disabled |
+| hovered | `boolean` | Whether the checkbox is being hovered |
+| focused | `boolean` | Whether the checkbox has focus |
+| side-label | `boolean` | Whether the label is positioned to the side |
+| inside-form | `boolean` | Whether the checkbox is inside a form field |
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<Checkbox>Accept terms and conditions</Checkbox>
+```
+
+### With Default Selection
+
+```jsx
+<Checkbox defaultSelected={true}>
+  Subscribe to newsletter
+</Checkbox>
+```
+
+### Indeterminate State
+
+```jsx
+<Checkbox isIndeterminate={true}>
+  Select All Items
+</Checkbox>
+```
+
+### Disabled State
+
+```jsx
+<Checkbox isDisabled={true}>
+  Cannot be changed
+</Checkbox>
+```
+
+### With Validation
+
+```jsx
+<Checkbox validationState="invalid" isRequired>
+  Must accept to continue
+</Checkbox>
+```
+
+### In a Group
+
+```jsx
+<Checkbox.Group
+  label="Select preferences"
+  value={['email', 'sms']}
+  onChange={setPreferences}
+>
+  <Checkbox value="email">Email notifications</Checkbox>
+  <Checkbox value="sms">SMS notifications</Checkbox>
+  <Checkbox value="push">Push notifications</Checkbox>
+</Checkbox.Group>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the checkbox
+- `Space` - Toggles the checkbox state
+- `Enter` - Activates the checkbox (when inside a form)
+
+### Screen Reader Support
+
+- Component announces as "checkbox" to screen readers
+- State changes are announced (e.g., "checked", "unchecked", "indeterminate")
+- Required state is communicated when `isRequired` is true
+- Validation errors are announced 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 checkbox state (true, false, or mixed for indeterminate)
+- `aria-required` - Indicates if selection is required
+- `aria-invalid` - Indicates validation state
+
+## Best Practices
+
+1. **Do**: Provide clear, descriptive labels
+   ```jsx
+   <Checkbox>Enable two-factor authentication</Checkbox>
+   ```
+
+2. **Don't**: Use unclear or ambiguous text
+   ```jsx
+   <Checkbox>Enable</Checkbox> {/* What gets enabled? */}
+   ```
+
+3. **Accessibility**: Always provide meaningful labels for screen readers
+4. **Groups**: Use CheckboxGroup for related options to improve organization
+5. **Validation**: Provide clear error messages when validation fails
+6. **Indeterminate**: Use sparingly, typically only for "Select All" scenarios
+
+## Integration with Forms
+
+This component supports all [Field properties](../form/Field.md) when used within a Form.
+
+## Suggested Improvements
+
+- Add support for custom icons for checked/unchecked states
+- Implement animation transitions for state changes
+- Add support for mixed checkbox groups with nested hierarchies
+- Consider adding size variants (small, medium, large)
+
+## Related Components
+
+- CheckboxGroup - For organizing multiple related checkboxes
+- [Switch](./Switch.md) - For binary on/off states
+- [RadioGroup](./RadioGroup.md) - For single selection from multiple options