@cube-dev/ui-kit 0.120.1 → 0.121.1

package/docs/components/actions/ItemButton.md

@@ -0,0 +1,316 @@
+# ItemButton
+
+An interactive button component built on top of `Item` that provides all the layout and styling capabilities of Item with full button functionality. ItemButton supports actions, links, form submissions, and all the advanced features like hotkeys, tooltips, and selection states.
+
+## When to Use
+
+- For buttons that need structured content with icons, descriptions, or prefixes/suffixes
+- When you need button functionality with the flexible layout capabilities of Item
+- For interactive items in lists, menus, or toolbars that need consistent styling
+- When building buttons that support features like keyboard shortcuts or overflow tooltips
+- As an alternative to traditional buttons when you need more layout control
+
+## Component
+
+---
+
+### 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.md)
+
+### Item Properties
+
+ItemButton inherits all properties from [Item](../content/Item.md), including:
+- Layout properties: `icon`, `rightIcon`, `prefix`, `suffix`, `description`, `descriptionPlacement`
+- Interactive properties: `hotkeys`, `tooltip`, `isSelected`
+- Styling properties: `size`, `type`, `theme`, `styles`
+
+### Content Properties
+
+#### actions
+- **Type**: `ReactNode`
+- **Description**: Inline action buttons displayed on the right side of the button. Use `ItemButton.Action` for consistent styling. Actions automatically inherit the parent button's `type` prop and the component reserves space to prevent content overlap.
+
+### Action Properties
+
+#### onPress
+- **Type**: `(e: PressEvent) => void`
+- **Description**: Callback fired when the button is pressed via mouse, keyboard, or touch
+
+#### to
+- **Type**: `string`
+- **Description**: URL for link behavior - when provided, the button acts as a link
+
+#### htmlType
+- **Type**: `'button' | 'submit' | 'reset'`
+- **Description**: HTML button type attribute for form integration
+- **Default**: `'button'`
+
+#### isDisabled
+- **Type**: `boolean`
+- **Description**: Whether the button is disabled and non-interactive
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop: `width`, `height`, `padding`, `margin`, `color`, `fill`, `opacity`, `display`, `position`, `zIndex`, `gap`, `flow`, `placeItems`, `placeContent`, `alignItems`, `justifyContent`, `border`, `radius`, `shadow`, `overflow`.
+
+### Modifiers
+
+Inherits all modifiers from [Item](../content/Item.md) plus:
+
+- **`disabled`** `boolean` — Applied when the button is disabled
+- **`pressed`** `boolean` — Applied during button press interaction
+
+## Variants
+
+### Types
+
+- `primary` - Primary button with prominent styling for main actions
+- `secondary` - Secondary button with moderate emphasis
+- `outline` - Button with border outline and transparent background
+- `neutral` - Neutral styled button for subtle actions
+- `clear` - Transparent button with minimal visual weight
+- `link` - Link-styled button that looks like a text link
+
+### Themes
+
+- `default` - Standard appearance with default colors
+- `danger` - Red theme for destructive actions (delete, remove, etc.)
+- `success` - Green theme for positive actions (save, confirm, etc.)
+- `special` - Special theme with unique styling for standout actions
+
+### Sizes
+
+- `xsmall` - Extra small size for compact interfaces
+- `small` - Small size for dense layouts  
+- `medium` - Default size for most use cases
+- `large` - Large size for prominent actions
+- `xlarge` - Extra large size for hero actions
+
+## Examples
+
+### Basic Button
+
+```jsx
+<ItemButton onPress={() => console.log('Clicked')}>
+  Click me
+</ItemButton>
+```
+
+### Button with Icons
+
+```jsx
+<ItemButton 
+  icon={<IconFile />}
+  rightIcon={<IconExternalLink />}
+  onPress={handleOpen}
+>
+  Open File
+</ItemButton>
+```
+
+### Link Button
+
+```jsx
+<ItemButton to="/docs">
+  Go to Documentation
+</ItemButton>
+```
+
+### Button with Hotkey
+
+```jsx
+<ItemButton 
+  hotkeys="cmd+s"
+  onPress={handleSave}
+  type="primary"
+>
+  Save Document
+</ItemButton>
+```
+
+### Form Submit Button
+
+```jsx
+<ItemButton 
+  htmlType="submit"
+  type="primary"
+  icon={<IconCheck />}
+>
+  Submit Form
+</ItemButton>
+```
+
+### Button with Selection State
+
+```jsx
+<ItemButton 
+  isSelected={isSelected}
+  onPress={() => setIsSelected(!isSelected)}
+>
+  Toggle Selection
+</ItemButton>
+```
+
+### Button with Actions
+
+ItemButton supports inline actions that appear on the right side. Use the `ItemButton.Action` compound component for consistent styling:
+
+```jsx
+<ItemButton 
+  icon={<IconFile />}
+  actions={
+    <>
+      <ItemButton.Action icon={<IconEdit />} aria-label="Edit" onPress={handleEdit} />
+      <ItemButton.Action icon={<IconTrash />} aria-label="Delete" onPress={handleDelete} />
+    </>
+  }
+  onPress={handleOpen}
+>
+  Document with Actions
+</ItemButton>
+```
+
+Actions automatically inherit the parent button's `type` prop and adjust their styling accordingly. The component reserves space for actions to prevent content overlap.
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the button
+- `Space/Enter` - Activates the button
+- Custom hotkeys - Trigger button action when hotkeys are specified
+- `Escape` - Removes focus when pressed (standard browser behavior)
+
+### Screen Reader Support
+
+- Button announces as "button" to screen readers
+- Link buttons announce as "link" when `to` prop is provided
+- Button state is announced (pressed, disabled, selected)
+- Hotkey information is included in accessible description
+
+### ARIA Properties
+
+- `aria-label` - Provides accessible label when text content isn't descriptive enough
+- `aria-disabled` - Indicates disabled state
+- `aria-pressed` - Indicates toggle state for toggle buttons
+- `role` - Automatically set to "button" or "link" based on props
+
+## Best Practices
+
+1. **Do**: Use clear, action-oriented text
+   ```jsx
+   <ItemButton onPress={handleSave} type="primary">
+     Save Changes
+   </ItemButton>
+   ```
+
+2. **Do**: Add hotkeys for frequently used actions
+   ```jsx
+   <ItemButton hotkeys="cmd+s" onPress={handleSave}>
+     Save Document
+   </ItemButton>
+   ```
+
+3. **Do**: Use appropriate button types for forms
+   ```jsx
+   <ItemButton htmlType="submit" type="primary">
+     Submit Form
+   </ItemButton>
+   ```
+
+4. **Do**: Use `ItemButton.Action` for inline actions
+   ```jsx
+   <ItemButton 
+     icon={<IconFile />}
+     actions={
+       <>
+         <ItemButton.Action icon={<IconEdit />} aria-label="Edit" />
+         <ItemButton.Action icon={<IconTrash />} aria-label="Delete" />
+       </>
+     }
+     onPress={handleOpen}
+   >
+     Open Document
+   </ItemButton>
+   ```
+
+5. **Don't**: Use vague or unclear button text
+   ```jsx
+   {/* Avoid this - unclear what "OK" does */}
+   <ItemButton onPress={handleAction}>OK</ItemButton>
+   ```
+
+6. **Don't**: Add too many actions (limit to 2-3 for clarity)
+   ```jsx
+   {/* Avoid this - too many action buttons */}
+   <ItemButton 
+     actions={
+       <>
+         <ItemButton.Action icon={<IconEdit />} aria-label="Edit" />
+         <ItemButton.Action icon={<IconCopy />} aria-label="Copy" />
+         <ItemButton.Action icon={<IconShare />} aria-label="Share" />
+         <ItemButton.Action icon={<IconTrash />} aria-label="Delete" />
+       </>
+     }
+   >
+     Button with too many actions
+   </ItemButton>
+   ```
+
+7. **Don't**: Overcrowd buttons with too many visual elements
+   ```jsx
+   {/* Avoid this - too many competing elements */}
+   <ItemButton 
+     icon={<IconA />}
+     rightIcon={<IconB />}
+     prefix="Pre"
+     suffix="Suf"
+     description="Long description"
+   >
+     Overcrowded Button
+   </ItemButton>
+   ```
+
+8. **Accessibility**: Always ensure buttons have clear, descriptive labels, proper keyboard support, and provide `aria-label` for action buttons
+
+## Integration with Forms
+
+ItemButton integrates seamlessly with forms when using the `htmlType` prop:
+
+```jsx
+<form onSubmit={handleSubmit}>
+  <TextInput name="email" label="Email" />
+  <ItemButton htmlType="submit" type="primary">
+    Sign In
+  </ItemButton>
+  <ItemButton htmlType="reset" type="outline">
+    Clear Form
+  </ItemButton>
+</form>
+```
+
+## Related Components
+
+- [Item](../content/Item.md) - The foundational component that ItemButton extends
+- [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

@@ -0,0 +1,325 @@
+# Link
+
+Semantic navigation component styled as a textual link. It reuses `Button` under the hood with `type="link"`, but this page focuses on navigation via the `to` prop.
+
+## When to Use
+
+- Navigate inside your SPA using the configured router
+- Open destinations in a new tab
+- Jump to on‑page anchors via `#id`
+- Perform history navigation (back/forward/reload) using numbers
+- Bypass SPA routing and force a full page load
+
+## Component
+
+---
+
+## Properties
+
+- **`label`** (default: `Button`)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+Sub-elements:
+- `ButtonIcon` – wrapper around `icon` and `rightIcon` when used.
+
+### Style Properties
+
+These properties allow direct styling without using the `styles` prop: `width`, `height`.
+
+---
+
+## Link Syntax (`to` prop)
+
+`to` defines where and how navigation happens. It accepts a string, an object path, or a number for history navigation.
+
+### 1) String URL/Path (SPA push)
+
+```jsx
+// Navigate to internal route via the navigation adapter
+<Link to="/pricing">Pricing</Link>
+
+// External absolute URLs always use native navigation
+<Link to="https://cube.dev">Cube</Link>
+
+// Relative paths work properly with router context
+<Link to="../parent-page">Parent</Link>
+```
+
+### 2) Open in a new tab (`!` prefix)
+
+```jsx
+// Open internal route in a new tab
+<Link to="!/changelog">Changelog</Link>
+
+// Open external URL in a new tab
+<Link to="!https://cube.dev">Docs</Link>
+```
+
+Notes:
+- Adds `target="_blank"` and `rel="noopener noreferrer"` automatically.
+- Cmd/Ctrl/Shift + click also opens in a new tab, like a native link.
+
+### 3) Native navigation / full reload (`@` prefix)
+
+```jsx
+// Bypass SPA router and perform a full page load
+<Link to="@/signin">Sign in</Link>
+
+// External native navigation works as well
+<Link to="@https://cube.dev">Homepage</Link>
+```
+
+### 4) On‑page anchors (hash links)
+
+```jsx
+// Smoothly scrolls to the element with id="features"
+<Link to="#features">Jump to Features</Link>
+```
+
+### 5) Object path (modern routers)
+
+```jsx
+// Uses navigate(to) with object path support
+<Link
+  to={{ pathname: '/search', search: 'q=cube', hash: 'top' }}
+>
+  Advanced search
+</Link>
+```
+
+Accepted object shape:
+```ts
+{ pathname?: string; search?: string; hash?: string }
+```
+
+Notes:
+- `search` and `hash` are auto-prefixed with `?` and `#` if needed
+- `pathname` can be relative (e.g., `../parent`) or absolute (e.g., `/root`)
+- Works with `!` and `@` prefixes when passed as strings
+
+### 6) History navigation (numbers)
+
+```jsx
+// Go back one entry
+<Link to={-1}>Back</Link>
+
+// Go forward one entry
+<Link to={1}>Forward</Link>
+
+// Reload current entry (like location.reload but via history)
+<Link to={0}>Reload</Link>
+```
+
+Behavior:
+- Uses `navigate(delta)` from the navigation adapter with overload signature
+- The default adapter calls `window.history.go(delta)`
+
+---
+
+## Router Integration
+
+`Link` uses a hook-based navigation adapter that you provide via the `Root` component. The adapter enables proper relative path resolution for new-tab navigation and modern router integration.
+
+### Interface
+
+```ts
+type NavigateLike = {
+  (to: To, options?: NavigateOptions): void;
+  (delta: number): void;
+};
+
+interface NavigationAdapter {
+  useHref: (to: To, opts?: { relative?: 'route' | 'path' }) => string;
+  useNavigate: () => NavigateLike;
+}
+```
+
+### React Router v6+ (Recommended)
+
+React Router v6+ hooks are directly compatible with our `NavigationAdapter` interface:
+
+```jsx
+import { Root } from '@cube-dev/ui-kit';
+import { useHref, useNavigate } from 'react-router-dom';
+
+const navigation = { useHref, useNavigate };
+// React Router's useNavigate supports both overloads: navigate(to, options) and navigate(delta)
+
+export function App() {
+  return (
+    <Root navigation={navigation}>
+      {/* Your app content */}
+    </Root>
+  );
+}
+```
+
+### Custom adapter example
+
+For other routers, create a custom adapter:
+
+```jsx
+import { Root } from '@cube-dev/ui-kit';
+
+function MyRouterAdapter() {
+  return {
+    useHref: (to) => {
+      // Return resolved href for the given route
+      return typeof to === 'string' ? to : `${to.pathname || ''}${to.search || ''}${to.hash || ''}`;
+    },
+    useNavigate: () => {
+      // Return function with overload signatures
+      const navigate = (to, options) => {
+        if (typeof to === 'number') {
+          window.history.go(to);
+        } else {
+          myRouter.navigate(to, options);
+        }
+      };
+      return navigate;
+    },
+  };
+}
+
+export function App() {
+  const navigation = MyRouterAdapter();
+  return <Root navigation={navigation}>{/* Your app */}</Root>;
+}
+```
+
+### No router (default behavior)
+
+When no `navigation` prop is provided, `Link` falls back to native browser navigation:
+
+```jsx
+import { Root } from '@cube-dev/ui-kit';
+
+export function App() {
+  return (
+    <Root>
+      {/* Links will use window.location for navigation */}
+    </Root>
+  );
+}
+```
+
+Default adapter behavior:
+- String/object navigation uses `window.location.assign(href)`
+- History navigation uses `window.history.go(delta)`
+- `!` prefix opens resolved URLs in a new tab
+- `@` prefix forces native navigation to resolved URLs
+- Relative paths are resolved against the current page
+
+---
+
+## Navigation Options
+
+Control navigation behavior via the `navigationOptions` prop:
+
+```jsx
+<Link 
+  to="/search"
+  navigationOptions={{ 
+    replace: true, 
+    state: { from: 'homepage' },
+    relative: 'path',
+    preventScrollReset: true
+  }}
+>
+  Search (replace history)
+</Link>
+```
+
+### Available options
+
+- `replace`: Replace current history entry instead of pushing a new one
+- `state`: Navigation state data (router-specific)  
+- `relative`: How relative paths are resolved (`'route'` | `'path'`)
+- `preventScrollReset`: Prevent scroll reset on navigation
+
+These options are passed to the router's `navigate` function and have no effect on native navigation (`@` prefix, external URLs, or when no adapter is provided).
+
+---
+
+## Variants
+
+`Link` inherits `theme` and `size` from `Button`. The visual `type` is fixed to `link`.
+
+### Themes
+
+- `default`, `danger`, `success`, `special`
+
+### Sizes
+
+- `xsmall`, `small`, `medium`, `large`, `xlarge`
+
+---
+
+## Examples
+
+### Basic SPA push
+
+```jsx
+<Link to="/about">About</Link>
+```
+
+### Anchor and new tab
+
+```jsx
+<Link to="#faq">FAQ</Link>
+<Link to="!https://cube.dev">Open Docs in new tab</Link>
+```
+
+### Bypass SPA
+
+```jsx
+<Link to="@/logout">Log out</Link>
+```
+
+### History
+
+```jsx
+<Link to={-1}>Back</Link>
+<Link to={0}>Reload</Link>
+```
+
+---
+
+## Accessibility
+
+- Renders as an `<a>` element when `to` is a string/object; as a `<button>` when `to` is a number or omitted.
+- Keyboard interaction and focus management are handled by React Aria.
+- Provide `label`/`aria-label` when there is no visible text.
+
+### ARIA Properties
+
+- `aria-label`, `aria-labelledby` – Accessible name.
+- Additional ARIA attributes supported by React Aria's `useButton`.
+
+---
+
+## Best Practices
+
+1. Prefer SPA push (`to="/path"`) for in‑app navigation; use `@` only when a full reload is required.
+2. Use `!` for new tabs instead of adding `target` props yourself; security attributes are added automatically.
+3. Use object `to` when your router supports structured navigation.
+4. For back/forward actions in UI, use numeric `to` for predictable history behavior.
+
+## Suggested Improvements
+
+- Add a dedicated `href` prop alias for clarity in link‑only scenarios.
+- Expose a `replace` option for SPA navigation.
+
+## Related Components
+
+- [Button](./Button.md) – Action component with multiple visual styles, including `type="link"`.
+