@cube-dev/ui-kit 0.0.0-canary-d688797 → 0.0.0-canary-bdfccbd

package/docs/components/Root.md

@@ -0,0 +1,50 @@
+# Root
+
+The root application wrapper. Provides theme context, global styles, portal container, modal/toast providers, and navigation. Wrap your app with `Root` at the top level.
+
+## When to Use
+
+- Top-level app component (required)
+- Provides context for modals, toasts, tooltips, and overlays
+- Theme and design token configuration
+
+## Properties
+
+- **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
+- **`tracking`** `TrackingProps` — Analytics/tracking event configuration
+- **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
+- **`fonts`** `boolean` — Whether to load default fonts
+- **`font`** `string` — Custom font family name
+- **`monospaceFont`** `string` — Custom monospace font family name
+- **`fontDisplay`** `'auto' | 'block' | 'swap' | 'fallback' | 'optional'` (default: `'swap'`) — Font display strategy
+- **`bodyStyles`** `Record<string, string>` — Raw CSS styles applied to the `<body>`
+- **`publicUrl`** `string` — Public URL for font loading
+- **`cursorStrategy`** `'web' | 'native'` (default: `'web'`) — Cursor style for interactive elements (`web` uses pointer, `native` uses default)
+
+### Style Defaults
+
+- `display` — `contents`
+- `color` — `#dark-02`
+- `preset` — `t3`
+
+### Base Properties
+
+Supports [Base properties](../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Root>
+  <App />
+</Root>
+```
+
+```jsx
+<Root
+  font="Inter"
+  navigation={routerAdapter}
+  tokens={{ '--gap': '8px', '--radius': '4px' }}
+>
+  <App />
+</Root>
+```

package/docs/components/actions/Action.md

@@ -0,0 +1,47 @@
+# Action
+
+A low-level action element that can render as `<button>`, `<a>`, or `<span>`. When `to` is provided, it renders as a link. Used as a base for `Button` and `Link`.
+
+## When to Use
+
+- Building custom interactive elements
+- Actions that may navigate or submit
+- When you need a button that can become a link via the `to` prop
+
+## Properties
+
+- **`to`** `NavigateArg` — Navigation target (renders as `<a>` when provided)
+- **`label`** `string` — Accessible label for screen readers
+- **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type
+- **`download`** `string` — Download attribute for link mode
+- **`onPress`** `() => void` — Press event handler (React Aria)
+
+### Style Defaults
+
+- `position` — `relative`
+- `preset` — `inherit`
+- `transition` — `theme`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md). Extends React Aria `AriaButtonProps`.
+
+## Examples
+
+### Button action
+
+```jsx
+<Action onPress={() => doSomething()}>Click me</Action>
+```
+
+### Navigation action
+
+```jsx
+<Action to="/dashboard">Go to Dashboard</Action>
+```
+
+### Form submit
+
+```jsx
+<Action htmlType="submit">Submit</Action>
+```

package/docs/components/actions/Banner.md

@@ -15,9 +15,17 @@ Banner displays prominent messages and notifications to users. It supports diffe
 
 ### Properties
 
+- **`theme`** `'danger' | 'warning' | 'note' | 'success'` (default: `'note'`) — Visual theme of the banner with corresponding icon and colors
+- **`isDismissable`** `boolean` (default: `false`) — Whether the banner shows a dismiss button
+- **`onDismiss`** `() => void` — Callback fired when the dismiss button is clicked
+- **`icon`** `ReactNode` — Custom icon to display; defaults to a theme-appropriate icon
+- **`actions`** `ReactNode` — Action buttons displayed on the right side of the banner. Use `Banner.Action` for consistent styling
+- **`description`** `string` — Secondary text shown below the main content, truncated with ellipsis after two lines
+- **`shape`** `'sharp'` — Use `'sharp'` to remove rounded corners when stacking multiple banners
+
 ### Base Properties
 
-Supports [Base properties](../../tasty/tasty.md)
+Supports [Base properties](../../BaseProperties.md)
 
 ### Styling Properties
 
@@ -33,9 +41,7 @@ Customizes the root element of the component.
 
 The `mods` property accepts the following modifiers you can override:
 
-| Modifier | Type | Description |
-|----------|------|-------------|
-| theme | `'danger' \| 'warning' \| 'note' \| 'success'` | Visual theme of the banner |
+- **`theme`** `'danger' \| 'warning' \| 'note' \| 'success'` — Visual theme of the banner
 
 ## Variants
 
@@ -186,4 +192,4 @@ import { IconBell } from '@tabler/icons-react';
 ## Related Components
 
 - [Item](../content/Item.md) - Base component that Banner extends
-- ItemAction - Action button component used by Banner.Action
+- [ItemAction](./ItemAction.md) - Action button component used by Banner.Action

package/docs/components/actions/Button.md

@@ -17,18 +17,21 @@ A versatile action component that triggers commands and navigates users.
 
 - **`type`** `'primary' | 'secondary' | 'outline' | 'neutral' | 'clear' | 'link'` (default: `outline`) — Visual style variant of the button
 - **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
-- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `medium`) — Button size
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Button size. Use `'inline'` for link-type buttons or a number/string for custom sizes (e.g. `64` or `'8x'`)
 - **`icon`** — Icon rendered before the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
 - **`rightIcon`** — Icon rendered after the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
-- **`children`** `string` — Button label or custom content
-- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions (default: false)
-- **`isSelected`** `boolean` (default: `false`) — Marks the button as pressed / selected (toggle) (default: false)
+- **`children`** `ReactNode` — Button label or custom content
+- **`label`** `string` — Accessible label for the button (used as `aria-label`)
+- **`tooltip`** `string | boolean | object` — Tooltip content. Use a string for simple text, `true` for auto tooltip on overflow, or an object with `{ title, auto, placement, ...tooltipProps }`
+- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions
+- **`isSelected`** `boolean` (default: `false`) — Marks the button as pressed / selected (toggle)
 - **`to`** `string` — Destination URL or route; prefix with `!` to open in new tab, `@` to bypass router
+- **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type attribute
 - **`onPress`** `function` — Callback fired when the button is activated by mouse, touch, or keyboard
 
 ### Base Properties
 
-Supports [Base properties](../../tasty/tasty.md)
+Supports [Base properties](../../BaseProperties.md)
 
 ### Styling Properties
 
@@ -36,8 +39,10 @@ Supports [Base properties](../../tasty/tasty.md)
 
 Customises the root element of the component.
 
-Sub-elements:
-- `ButtonIcon` – wrapper around `icon` and `rightIcon`.
+**Sub-elements:**
+- `Icon` – wrapper around the leading icon
+- `RightIcon` – wrapper around the trailing icon
+- `Label` – the button text content
 
 ### Style Properties
 
@@ -47,16 +52,17 @@ These properties allow direct styling without using the `styles` prop: `width`,
 
 The `mods` prop accepts the following modifiers you can override:
 
-| Modifier | Type | Description |
-|----------|------|-------------|
-| hovered | `boolean` | Forces hover state. |
-| pressed | `boolean` | Forces pressed state. |
-| focused | `boolean` | Forces focus ring. |
-| disabled | `boolean` | Forces disabled appearance. |
-| loading | `boolean` | Displays loading spinner. |
-| selected | `boolean` | Displays selected state. |
-| has-icons | `boolean` | Indicates that the button contains at least one icon. |
-| single-icon | `boolean` | Icon-only button without text. |
+- **`hovered`** `boolean` — Forces hover state
+- **`pressed`** `boolean` — Forces pressed state
+- **`focused`** `boolean` — Forces focus ring
+- **`disabled`** `boolean` — Forces disabled appearance
+- **`loading`** `boolean` — Displays loading spinner
+- **`selected`** `boolean` — Displays selected state
+- **`has-icons`** `boolean` — Indicates that the button contains at least one icon
+- **`has-icon`** `boolean` — Indicates that the button has a leading icon
+- **`has-right-icon`** `boolean` — Indicates that the button has a trailing icon
+- **`single-icon`** `boolean` — Icon-only button without text
+- **`text-only`** `boolean` — Button has only text content, no icons
 
 ## Variants
 
@@ -85,6 +91,8 @@ The `mods` prop accepts the following modifiers you can override:
 - `medium` – Default height (32px).
 - `large` – Spacious height (40px).
 - `xlarge` – Extra spacious height (48px).
+- `inline` – Inline size for link-type buttons (no fixed height).
+- Custom values – Pass a number (pixels) or a string (e.g. `'8x'`) for custom sizing.
 
 ## Examples
 
@@ -141,6 +149,26 @@ import { IconPlus } from '@tabler/icons-react';
 <Button isLoading>Processing…</Button>
 ```
 
+### With Tooltip
+
+```jsx
+{/* Simple tooltip text */}
+<Button icon={<IconPlus />} tooltip="Add new item" aria-label="Add" />
+
+{/* Auto tooltip on overflow */}
+<Button tooltip={true} width="100px">This text will be truncated</Button>
+```
+
+### Custom Size
+
+```jsx
+{/* Using a number (pixels) */}
+<Button size={64}>Large Custom</Button>
+
+{/* Using a string multiplier */}
+<Button size="8x">8x Size</Button>
+```
+
 ## Accessibility
 
 ### Keyboard Navigation
@@ -173,9 +201,7 @@ import { IconPlus } from '@tabler/icons-react';
 
 ## Suggested Improvements
 
-- Add `autoFocus` support.
 - Provide `block` modifier to stretch the button 100% width.
-- Expose a `tooltip` helper for icon-only buttons.
 
 ## Related Components
 

package/docs/components/actions/ButtonGroup.md

@@ -0,0 +1,46 @@
+# ButtonGroup
+
+A container for grouping buttons with consistent spacing. Extends `Space` and inherits all its defaults.
+
+## When to Use
+
+- Grouping related actions (Save/Cancel)
+- Button bars and toolbars
+
+## Properties
+
+Inherits all Space properties.
+
+### Style Defaults
+
+Inherits Space defaults:
+
+- `display` — `flex`
+- `gap` — `1x`
+- `flow` — `row`
+- `placeItems` — `center stretch`
+- `gridArea` — `buttonGroup`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Horizontal group
+
+```jsx
+<Button.Group>
+  <Button>Save</Button>
+  <Button type="secondary">Cancel</Button>
+</Button.Group>
+```
+
+### Vertical group
+
+```jsx
+<Button.Group direction="vertical">
+  <Button>Option 1</Button>
+  <Button>Option 2</Button>
+</Button.Group>
+```

package/docs/components/actions/ButtonSplit.md

@@ -14,9 +14,19 @@ A split button that groups a primary action with a dropdown trigger for secondar
 
 ## Properties
 
+- **`actions`** `ButtonSplitAction[]` — Array of actions for strict mode. Each action requires `key` and `label`
+- **`actionKey`** `string` — Currently selected action key (controlled)
+- **`defaultActionKey`** `string` — Initially selected action key (uncontrolled)
+- **`onAction`** `(key: string) => void` — Called when the action button is pressed
+- **`onActionChange`** `(key: string) => void` — Called when the selected action changes via the menu
+- **`type`** `'primary' | 'secondary' | 'outline' | 'neutral' | 'clear'` (default: `'outline'`) — Button type (inherited by children via context)
+- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `'default'`) — Button theme (inherited by children via context)
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `'medium'`) — Button size (inherited by children via context)
+- **`isDisabled`** `boolean` (default: `false`) — Disables all buttons (inherited via context)
+
 ### Base Properties
 
-Supports [Base properties](../../tasty/tasty.md)
+Supports [Base properties](../../BaseProperties.md)
 
 ### Styling Properties
 

package/docs/components/actions/CommandMenu.md

@@ -64,9 +64,7 @@ Customizes the search input field specifically.
 
 The CommandMenu component supports the following modifiers:
 
-| Modifier | Type | Description |
-|----------|------|-------------|
-| loading | `boolean` | Whether the command palette is in loading state |
+- **`loading`** `boolean` — Whether the command palette is in loading state
 
 ## Sub-components
 
@@ -76,27 +74,23 @@ Individual menu items within the CommandMenu. Each item is rendered using [Item]
 
 For detailed information about all available item properties, see the [Menu.Item documentation](./Menu.md#sub-components) which provides the complete API reference. Key properties include:
 
-| Property | Type | Description |
-|----------|------|-------------|
-| key | `Key` | Unique identifier for the item (required) |
-| children | `ReactNode` | The main content/label for the menu item |
-| icon | `ReactNode` | Icon displayed before the content |
-| rightIcon | `ReactNode` | Icon displayed after the content |
-| description | `ReactNode` | Secondary text below the main content |
-| prefix | `ReactNode` | Content before the main text |
-| suffix | `ReactNode` | Content after the main text |
-| hotkeys | `string` | Keyboard shortcut that triggers this item |
-| tooltip | `string \| boolean \| object` | Tooltip configuration |
-| isDisabled | `boolean` | Whether the item is disabled |
-| onAction | `() => void` | Callback fired when item is activated |
+- **`key`** `Key` — Unique identifier for the item (required)
+- **`children`** `ReactNode` — The main content/label for the menu item
+- **`icon`** `ReactNode` — Icon displayed before the content
+- **`rightIcon`** `ReactNode` — Icon displayed after the content
+- **`description`** `ReactNode` — Secondary text below the main content
+- **`prefix`** `ReactNode` — Content before the main text
+- **`suffix`** `ReactNode` — Content after the main text
+- **`hotkeys`** `string` — Keyboard shortcut that triggers this item
+- **`tooltip`** `string | boolean | object` — Tooltip configuration
+- **`isDisabled`** `boolean` — Whether the item is disabled
+- **`onAction`** `() => void` — Callback fired when item is activated
 
 #### CommandMenu-specific Properties
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| keywords | `string[]` | - | Additional search terms for better discoverability |
-| forceMount | `boolean` | - | Whether to always show this item regardless of search filter |
-| textValue | `string` | - | Text value for search filtering (if different from children) |
+- **`keywords`** `string[]` — Additional search terms for better discoverability
+- **`forceMount`** `boolean` — Whether to always show this item regardless of search filter
+- **`textValue`** `string` — Text value for search filtering (if different from children)
 
 #### Example with Enhanced Search
 
@@ -126,10 +120,8 @@ For detailed information about all available item properties, see the [Menu.Item
 
 Groups related items together with an optional heading. Same as Menu.Section - see [Menu documentation](./Menu.md#sub-components) for full details.
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| title | `ReactNode` | - | Optional heading text for the section |
-| children | `CommandMenu.Item[]` | - | Collection of CommandMenu.Item components |
+- **`title`** `ReactNode` — Optional heading text for the section
+- **`children`** `CommandMenu.Item[]` — Collection of CommandMenu.Item components
 
 ### CommandMenu.Trigger
 

package/docs/components/actions/ItemAction.md

@@ -0,0 +1,60 @@
+# ItemAction
+
+A compact action button designed for use inside `Item`, `ItemButton`, and `ItemCard`. Automatically inherits `type` and `theme` from its parent context.
+
+## When to Use
+
+- Row actions in lists (edit, delete, etc.)
+- Card action buttons
+- Inline actions that inherit context from parent
+
+## Component
+
+---
+
+## Properties
+
+- **`icon`** `ReactNode | 'checkbox'` — Icon element or `'checkbox'` for a selection indicator
+- **`type`** `'primary' | 'secondary' | 'outline' | 'neutral' | 'clear'` (default: `'neutral'`) — Visual type. Inherits from parent context.
+- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `'default'`) — Color theme. Inherits from parent context.
+- **`isLoading`** `boolean` (default: `false`) — Shows loading spinner
+- **`isSelected`** `boolean` (default: `false`) — Selected state (works with `icon="checkbox"`)
+- **`isDisabled`** `boolean` (default: `false`) — Disables the action. Inherits from parent; use `isDisabled={false}` to override.
+- **`tooltip`** `string | object` — Tooltip content (shown for icon-only buttons)
+- **`onPress`** `() => void` — Press event handler
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Icon-only actions
+
+```jsx
+<ItemAction icon={<IconEdit />} tooltip="Edit" onPress={() => edit()} />
+<ItemAction icon={<IconTrash />} tooltip="Delete" theme="danger" />
+```
+
+### Checkbox action
+
+```jsx
+<ItemAction icon="checkbox" isSelected={isChecked} onPress={toggle} />
+```
+
+### Inside ItemButton
+
+```jsx
+<ItemButton
+  type="outline"
+  icon={<IconFile />}
+  actions={
+    <>
+      <ItemAction icon={<IconEdit />} tooltip="Edit" />
+      <ItemAction icon={<IconTrash />} tooltip="Delete" theme="danger" />
+    </>
+  }
+>
+  Document.pdf
+</ItemButton>
+```

package/docs/components/actions/ItemButton.md

@@ -16,9 +16,24 @@ An interactive button component built on top of `Item` that provides all the lay
 
 ### Properties
 
+- **`type`** `'primary' | 'secondary' | 'outline' | 'neutral' | 'clear'` — Visual type/variant of the button
+- **`theme`** `'default' | 'danger' | 'success' | 'special'` — Color theme of the button
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `medium`) — Size of the button (does not support `'inline'`)
+- **`hotkeys`** `string` — Keyboard shortcut that triggers the button (e.g., `"cmd+s"`, `"ctrl+alt+d"`)
+- **`tooltip`** `boolean | string | object` — Tooltip configuration: string for simple text, `true` for auto overflow tooltips, or object for advanced config with optional `auto` property
+- **`isDisabled`** `boolean` — Whether the button is disabled
+- **`isSelected`** `boolean` — Whether the button shows as selected with checkbox
+- **`to`** `string` — URL for link behavior (makes button act as link)
+- **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type attribute
+- **`description`** `string` — Secondary text shown below the main content
+- **`isLoading`** `boolean` — Whether the button shows loading state with disabled interaction
+- **`loadingSlot`** `'auto' | 'icon' | 'rightIcon' | 'prefix' | 'suffix'` — Which slot to replace with loading icon (`auto` intelligently selects)
+- **`autoHideActions`** `boolean` — When true, actions are hidden by default and fade in on hover
+- **`onPress`** `(e: PressEvent) => void` — Callback fired when button is pressed
+
 ### Base Properties
 
-Supports [Base properties](/BaseProperties)
+Supports [Base properties](../../BaseProperties.md)
 
 ### Item Properties
 
@@ -43,7 +58,7 @@ ItemButton inherits all properties from [Item](../content/Item.md), including:
 - **Type**: `string`
 - **Description**: URL for link behavior - when provided, the button acts as a link
 
-#### buttonType
+#### htmlType
 - **Type**: `'button' | 'submit' | 'reset'`
 - **Description**: HTML button type attribute for form integration
 - **Default**: `'button'`
@@ -60,10 +75,8 @@ These properties allow direct style application without using the `styles` prop:
 
 Inherits all modifiers from [Item](../content/Item.md) plus:
 
-| Modifier | Type | Description |
-|----------|------|-------------|
-| disabled | `boolean` | Applied when the button is disabled |
-| pressed | `boolean` | Applied during button press interaction |
+- **`disabled`** `boolean` — Applied when the button is disabled
+- **`pressed`** `boolean` — Applied during button press interaction
 
 ## Variants
 
@@ -90,7 +103,6 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 - `medium` - Default size for most use cases
 - `large` - Large size for prominent actions
 - `xlarge` - Extra large size for hero actions
-- `inline` - Inline size that adapts to content
 
 ## Examples
 
@@ -138,7 +150,7 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 
 ```jsx
 <ItemButton 
-  buttonType="submit"
+  htmlType="submit"
   type="primary"
   icon={<IconCheck />}
 >
@@ -219,7 +231,7 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
 
 3. **Do**: Use appropriate button types for forms
    ```jsx
-   <ItemButton buttonType="submit" type="primary">
+   <ItemButton htmlType="submit" type="primary">
      Submit Form
    </ItemButton>
    ```
@@ -281,15 +293,15 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
 
 ## Integration with Forms
 
-ItemButton integrates seamlessly with forms when using the `buttonType` prop:
+ItemButton integrates seamlessly with forms when using the `htmlType` prop:
 
 ```jsx
 <form onSubmit={handleSubmit}>
   <TextInput name="email" label="Email" />
-  <ItemButton buttonType="submit" type="primary">
+  <ItemButton htmlType="submit" type="primary">
     Sign In
   </ItemButton>
-  <ItemButton buttonType="reset" type="outline">
+  <ItemButton htmlType="reset" type="outline">
     Clear Form
   </ItemButton>
 </form>
@@ -298,7 +310,7 @@ ItemButton integrates seamlessly with forms when using the `buttonType` prop:
 ## Related Components
 
 - [Item](../content/Item.md) - The foundational component that ItemButton extends
-- ItemButton.Action - Action button component for inline actions (also available as `Item.Action`, `Menu.Item.Action`, etc.)
+- [ItemButton.Action](./ItemAction.md) - Action button component for inline actions (also available as `Item.Action`, `Menu.Item.Action`, etc.)
 - [Button](./Button.md) - Traditional button component for simpler use cases
 - [Link](./Link.md) - Text link component for navigation
 - [Menu.Item](./Menu.md) - Menu item component that also uses Item

package/docs/components/actions/Link.md

@@ -20,7 +20,7 @@ Semantic navigation component styled as a textual link. It reuses `Button` under
 
 ### Base Properties
 
-Supports [Base properties](../../tasty/tasty.md)
+Supports [Base properties](../../BaseProperties.md)
 
 ### Styling Properties