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

package/docs/components/actions/Button.md

@@ -0,0 +1,183 @@
+# 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'` (default: `medium`) — Button size
+- **`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)
+- **`to`** `string` — Destination URL or route; prefix with `!` to open in new tab, `@` to bypass router
+- **`onPress`** `function` — Callback fired when the button is activated by mouse, touch, or keyboard
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+### Styling Properties
+
+#### styles
+
+Customises the root element of the component.
+
+Sub-elements:
+- `ButtonIcon` – wrapper around `icon` and `rightIcon`.
+
+### 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:
+
+| 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. |
+
+## 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).
+
+## 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>
+```
+
+## 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
+
+- Add `autoFocus` support.
+- Provide `block` modifier to stretch the button 100% width.
+- Expose a `tooltip` helper for icon-only buttons.
+
+## 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/ButtonSplit.md

@@ -0,0 +1,189 @@
+# 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
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.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.