@cube-dev/ui-kit 0.120.1 → 0.121.1

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

@@ -0,0 +1,195 @@
+# Banner
+
+Banner displays prominent messages and notifications to users. It supports different visual themes with appropriate icons and can include action buttons and inline links.
+
+## When to Use
+
+- Display system-wide notifications or alerts that require user attention
+- Show billing, subscription, or account status warnings
+- Communicate deployment errors or operational issues
+- Provide contextual information with optional calls-to-action
+
+## Component
+
+---
+
+### 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](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+**Sub-elements:**
+- `Label` - The main text content area
+- `Actions` - Container for action buttons
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+- **`theme`** `'danger' \| 'warning' \| 'note' \| 'success'` — Visual theme of the banner
+
+## Variants
+
+### Themes
+
+- `note` (default) - Informational messages, tips, or neutral notifications
+- `warning` - Alerts that require attention but are not critical
+- `danger` - Critical errors or issues that need immediate action
+- `success` - Confirmation of successful operations
+
+## Sub-components
+
+### Banner.Action
+
+Action button styled to match the banner's theme. Use for primary calls-to-action.
+
+```jsx
+<Banner theme="warning" actions={<Banner.Action to="/upgrade">Upgrade Plan</Banner.Action>}>
+  You are approaching your monthly API request limit.
+</Banner>
+```
+
+### Banner.Link
+
+Inline link styled with white color and underline. Use for links within the banner's text content.
+
+```jsx
+<Banner theme="danger">
+  <Banner.Link to="https://docs.example.com">Daily limit</Banner.Link> exceeded.
+  Please contact support.
+</Banner>
+```
+
+## Examples
+
+### Basic Banner
+
+```jsx
+<Banner theme="note">
+  Scheduled maintenance will occur on Sunday at 2:00 AM UTC.
+</Banner>
+```
+
+### Dismissible Banner
+
+```jsx
+<Banner theme="success" isDismissable onDismiss={() => console.log('Dismissed')}>
+  Your deployment has been successfully updated.
+</Banner>
+```
+
+### Banner with Actions
+
+```jsx
+<Banner
+  theme="danger"
+  actions={
+    <>
+      <Banner.Action to="/billing">Go to Billing</Banner.Action>
+      <Banner.Action onPress={() => openChat()}>Contact us</Banner.Action>
+    </>
+  }
+>
+  Your account has been suspended due to payment failure.
+</Banner>
+```
+
+### Banner with Inline Links
+
+```jsx
+<Banner theme="warning" actions={<Banner.Action>Upgrade tier</Banner.Action>}>
+  The selected time range exceeds{' '}
+  <Banner.Link to="https://docs.example.com/retention">
+    the retention period
+  </Banner.Link>
+  . To extend this period, please upgrade or contact us.
+</Banner>
+```
+
+### Stacked Banners
+
+Use `shape="sharp"` when stacking multiple banners to remove gaps between them.
+
+```jsx
+<Flex flow="column">
+  <Banner theme="danger" shape="sharp">Critical alert</Banner>
+  <Banner theme="warning" shape="sharp">Warning message</Banner>
+  <Banner theme="note" shape="sharp">Information</Banner>
+</Flex>
+```
+
+### Custom Icon
+
+```jsx
+import { IconBell } from '@tabler/icons-react';
+
+<Banner theme="note" icon={<IconBell />} isDismissable>
+  You have new notifications.
+</Banner>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to action buttons within the banner
+- `Space/Enter` - Activates focused action button or dismiss button
+
+### Screen Reader Support
+
+- Banner has `role="status"` to announce content changes
+- Dismiss button includes tooltip "Hide banner" for accessibility
+
+### ARIA Properties
+
+- `role="status"` - Announces the banner as a status message
+- Action buttons inherit proper focus management from Item.Action
+
+## Best Practices
+
+1. **Do**: Use appropriate theme for the message severity
+
+```jsx
+<Banner theme="danger">Critical error requiring immediate action</Banner>
+<Banner theme="warning">Warning that needs attention</Banner>
+<Banner theme="note">Informational message</Banner>
+<Banner theme="success">Success confirmation</Banner>
+```
+
+2. **Do**: Keep banner messages concise and actionable
+
+```jsx
+<Banner theme="warning" actions={<Banner.Action>Upgrade</Banner.Action>}>
+  API usage at 85% of monthly limit.
+</Banner>
+```
+
+3. **Don't**: Use banners for non-important information that doesn't need prominent display
+
+4. **Do**: Use Banner.Link for inline links within content, Banner.Action for buttons
+
+```jsx
+<Banner theme="danger" actions={<Banner.Action>Contact us</Banner.Action>}>
+  <Banner.Link to="/docs/limits">Daily limit</Banner.Link> exceeded.
+</Banner>
+```
+
+## Related Components
+
+- [Item](../content/Item.md) - Base component that Banner extends
+- [ItemAction](./ItemAction.md) - Action button component used by Banner.Action

package/docs/components/actions/Button.md

@@ -0,0 +1,209 @@
+# Button
+
+A versatile action component that triggers commands and navigates users.
+
+## When to Use
+
+- Trigger an immediate in-page action (e.g., open a dialog)
+- Navigate to another route or URL using the `to` prop while keeping button styling
+- Toggle a boolean state with `isSelected`
+- Display progress feedback with `isLoading`
+
+## Component
+
+---
+
+## Properties
+
+- **`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' | '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`** `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](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customises the root element of the component.
+
+**Sub-elements:**
+- `Icon` – wrapper around the leading icon
+- `RightIcon` – wrapper around the trailing icon
+- `Label` – the button text content
+
+### Style Properties
+
+These properties allow direct styling without using the `styles` prop: `width`, `height`.
+
+### Modifiers
+
+The `mods` prop accepts the following modifiers you can override:
+
+- **`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
+
+### Types. `type` prop
+
+- `primary` – Emphasised call-to-action.
+- `secondary` – Less emphasised, alternative action.
+- `outline` – Transparent background with border.
+- `neutral` – Minimal style that blends with surroundings.
+- `clear` – Text-only variant without background and border.
+- `link` – Styled as a textual link.
+
+### Themes. `theme` prop
+
+- `default` – Brand purple colours.
+- `danger` – Red palette for destructive actions.
+- `success` – Green palette for positive actions.
+- `warning` – Yellow/amber palette for caution or attention.
+- `note` – Violet palette for informational context.
+- `special` – White palette for dark backgrounds.
+
+### Sizes. `size` prop
+
+- `xsmall` – Extra compact height (24px).
+- `small` – Compact height (28px).
+- `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
+
+### Basic Usage
+
+```jsx
+<Button onPress={() => console.log('Pressed')}>Save</Button>
+```
+
+### Icon Button
+
+```jsx
+import { IconPlus } from '@tabler/icons-react';
+
+{/* Standard icon */}
+<Button icon={<IconPlus />} aria-label="Add item" />
+
+{/* Empty slot (reserves space but shows nothing) */}
+<Button icon={true} aria-label="Empty slot" />
+
+{/* Dynamic icon based on mods */}
+<Button 
+  icon={({ loading }) => loading ? <SpinnerIcon /> : <IconPlus />}
+  aria-label="Dynamic icon"
+>
+  Save
+</Button>
+
+{/* Return true from function for empty slot */}
+<Button 
+  icon={({ selected }) => selected ? <CheckIcon /> : true}
+  aria-label="Conditional icon"
+>
+  Option
+</Button>
+```
+
+### Link Button
+
+```jsx
+<!-- Navigate to a new page using the router -->
+<Button to="/pricing">Pricing</Button>
+<!-- Use `!` prefix to open in a new tab -->
+<Button to="!/pricing">Pricing</Button>
+<!-- Use `@` prefix to navigate to a new page without using the router -->
+<Button to="@/pricing">Pricing</Button>
+<!-- Use `@` to reload the page -->
+<Button to="@/pricing">Pricing</Button>
+```
+
+### Loading State
+
+```jsx
+<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
+
+- `Tab` – Moves focus to the button.
+- `Space` / `Enter` – Activates the button.
+
+### Screen Reader Support
+
+- Announces role "button".
+- Announces state changes such as "pressed", "disabled", or "selected".
+- Provide `label`/`aria-label` when the button has no visible text.
+
+### ARIA Properties
+
+- `aria-label`, `aria-labelledby` – Accessible name.
+- `aria-pressed` – Managed automatically when `isSelected` is used.
+- Additional ARIA attributes supported by React Aria's `useButton`.
+
+## Best Practices
+
+1. **Do**: Provide a label for icon-only buttons
+   ```jsx
+   <Button icon={<IconPlus />} aria-label="Add" />
+   ```
+2. **Don't**: Use the `link` type for destructive actions – prefer `danger.primary` instead.
+3. **Callbacks**: Always use `onPress` for actions that don't navigate. Use `onClick` only if you need to access the event object.
+4. **Accessibility**: Use `isLoading` rather than disabling a button without feedback.
+5. **Performance**: Reuse icon components to avoid unnecessary re-renders.
+
+## Suggested Improvements
+
+- Provide `block` modifier to stretch the button 100% width.
+
+## Related Components
+
+- [Link](./Link.md) – Semantic navigation styled like a button.
+- [ItemButton](./ItemButton.md) – Interactive button built on Item with icon support.

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

@@ -0,0 +1,199 @@
+# Button.Split
+
+A split button that groups a primary action with a dropdown trigger for secondary actions. Supports two modes: **custom** (arbitrary button children) and **strict** (declarative action list with built-in menu).
+
+## When to Use
+
+- Present a default action alongside alternative actions in a compact control
+- Allow users to switch between related operations (e.g., deploy targets, save modes)
+- Group two or more buttons visually as a single connected unit
+
+## Component
+
+---
+
+## 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](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customises the root wrapper element of the split button.
+
+### Style Properties
+
+These properties allow direct styling without using the `styles` prop: `width`, `height`.
+
+### Context Inheritance
+
+`type`, `theme`, `size`, and `isDisabled` set on `Button.Split` are inherited by all child `Button` components via context. Explicitly passed props on individual buttons always take precedence.
+
+## Modes
+
+### Strict Mode
+
+Pass an `actions` array to automatically render an action button and a trigger button with a dropdown menu. The trigger displays a `DirectionIcon` pointing down.
+
+Each action object requires `key` and `label`, and inherits all other props from `Menu.Item` (`icon`, `rightIcon`, `description`, `descriptionPlacement`, `prefix`, `suffix`, `hotkeys`, `textValue`, `isDisabled`, `qa`, `styles`, etc.).
+
+```jsx
+import { Button } from '@cube-dev/ui-kit';
+
+const actions = [
+  { key: 'deploy', label: 'Deploy', icon: <IconSend />, hotkeys: 'Mod+D' },
+  { key: 'deploy-staging', label: 'Deploy to Staging', icon: <IconSend />, description: 'Preview environment' },
+  { key: 'deploy-preview', label: 'Deploy Preview', icon: <IconPlayerPlay /> },
+];
+
+<Button.Split
+  actions={actions}
+  defaultActionKey="deploy"
+  type="primary"
+  onAction={(key) => console.log('Executed:', key)}
+  onActionChange={(key) => console.log('Switched to:', key)}
+/>
+```
+
+#### Controlled
+
+Use `actionKey` and `onActionChange` for controlled state.
+
+```jsx
+const [currentKey, setCurrentKey] = useState('deploy');
+
+<Button.Split
+  actions={actions}
+  actionKey={currentKey}
+  type="primary"
+  onAction={(key) => console.log('Executed:', key)}
+  onActionChange={setCurrentKey}
+/>
+```
+
+### Custom Mode
+
+Pass `children` to render arbitrary buttons with split-group styling (joined radius, collapsed borders). Set `type` and `theme` on the wrapper -- child buttons inherit them via context.
+
+```jsx
+import { Button, Menu } from '@cube-dev/ui-kit';
+import { DirectionIcon } from '@cube-dev/ui-kit';
+
+<Button.Split type="primary">
+  <Button onPress={() => console.log('Save')}>Save</Button>
+  <Menu.Trigger placement="bottom end">
+    <Button
+      aria-label="More save options"
+      icon={({ pressed }) => <DirectionIcon to={pressed ? 'up' : 'down'} />}
+    />
+    <Menu onAction={(key) => console.log(key)}>
+      <Menu.Item key="save-draft">Save as Draft</Menu.Item>
+      <Menu.Item key="save-publish">Save & Publish</Menu.Item>
+    </Menu>
+  </Menu.Trigger>
+</Button.Split>
+```
+
+### Multiple Buttons
+
+More than two buttons are supported. Middle buttons have no border radius.
+
+```jsx
+<Button.Split type="outline">
+  <Button icon={<IconPlus />}>Add</Button>
+  <Button icon={<IconCopy />}>Copy</Button>
+  <Button icon={<IconDownload />}>Export</Button>
+</Button.Split>
+```
+
+## Examples
+
+### Variants
+
+Different types and themes can be applied. All child buttons inherit the styling.
+
+```jsx
+<Button.Split actions={actions} defaultActionKey="copy" type="primary" />
+<Button.Split actions={actions} defaultActionKey="copy" type="secondary" />
+<Button.Split actions={actions} defaultActionKey="copy" type="outline" />
+<Button.Split actions={actions} defaultActionKey="copy" type="primary" theme="danger" />
+<Button.Split actions={actions} defaultActionKey="copy" type="primary" isDisabled />
+```
+
+### Customizing Sub-Components
+
+Use `actionProps`, `triggerProps`, and `menuProps` to customise individual parts in strict mode.
+
+```jsx
+<Button.Split
+  actions={actions}
+  defaultActionKey="deploy"
+  type="primary"
+  actionProps={{ size: 'large' }}
+  triggerProps={{ 'aria-label': 'Select deploy target' }}
+  menuProps={{ placement: 'bottom start' }}
+/>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` -- Moves focus between the action button and the trigger button.
+- `Space` / `Enter` -- Activates the focused button. On the trigger, opens the dropdown menu.
+- `Arrow Down` -- When the menu is open, navigates menu items.
+- `Escape` -- Closes the dropdown menu and returns focus to the trigger.
+
+### Screen Reader Support
+
+- The action button announces its label.
+- The trigger button has `aria-label="More options"` by default (override via `triggerProps`).
+- The dropdown menu announces selection changes.
+
+### ARIA Properties
+
+- `aria-label` -- Provide on the trigger for context (e.g., "Select deploy target").
+- Menu items support `aria-disabled` via the `isDisabled` property on actions.
+
+## Best Practices
+
+1. **Do**: Use strict mode for standard action+trigger patterns.
+   ```jsx
+   <Button.Split actions={actions} defaultActionKey="deploy" type="primary" />
+   ```
+
+2. **Do**: Set `type` and `theme` on the wrapper instead of repeating on each child.
+   ```jsx
+   <Button.Split type="primary">
+     <Button>Save</Button>
+     <Button icon={<DirectionIcon to="down" />} aria-label="Options" />
+   </Button.Split>
+   ```
+
+3. **Don't**: Mix `actions` prop with `children`. Use one mode or the other.
+
+4. **Accessibility**: Always provide `aria-label` on icon-only trigger buttons.
+
+## Suggested Improvements
+
+- Support `isLoading` on the action button in strict mode.
+- Add keyboard shortcut display in menu items via `hotkeys` prop.
+
+## Related Components
+
+- [Button](./Button.md) -- Standalone action button.
+- [Menu](./Menu.md) -- Dropdown menu for action lists.
+- Button.Group -- Layout wrapper for spacing multiple buttons.