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

package/docs/components/actions/use-anchored-menu.md

@@ -0,0 +1,211 @@
+# `useAnchoredMenu` Hook
+
+## Purpose
+
+`useAnchoredMenu` is a React hook that enables components to display anchored menus (like `Menu` or `CommandMenu`) positioned relative to a specific anchor element. Unlike [`useContextMenu`](./use-context-menu.md) which positions at cursor coordinates, `useAnchoredMenu` anchors to an element, making it ideal for dropdown menus, popovers, or programmatically triggered menus attached to specific UI elements.
+
+The hook provides a clean API for programmatic menu opening and automatic integration with the global menu synchronization system.
+
+## Related Components
+
+- [`useContextMenu`](./use-context-menu.md) - For cursor-positioned context menus
+- [`MenuTrigger`](./MenuTrigger.md) - The underlying trigger component used for positioning
+- [`Menu`](./Menu.md) - The menu component typically used with this hook
+- [`CommandMenu`](./CommandMenu.md) - Command palette component that can be used with this hook
+
+## API
+
+```ts
+function useAnchoredMenu<P, T = ComponentProps<typeof MenuTrigger>>(
+  Component: ComponentType<P>,
+  defaultTriggerProps?: Omit<
+    ComponentProps<typeof MenuTrigger>,
+    'children' | 'isOpen' | 'onOpenChange' | 'targetRef'
+  >,
+  defaultMenuProps?: P,
+): {
+  /** Ref to attach to the anchor element for positioning the menu. */
+  anchorRef: RefObject<HTMLElement>;
+
+  /**
+   * Programmatically opens the menu with the provided props.
+   * Runtime props are merged with defaultMenuProps (runtime props take precedence).
+   * @param props - Props to pass to the menu component (merged with defaultMenuProps)
+   * @param triggerProps - Additional props for MenuTrigger (merged with defaultTriggerProps)
+   */
+  open(props: P, triggerProps?: T): void;
+
+  /**
+   * Updates the props of the currently open menu.
+   * Props are merged with defaultMenuProps.
+   */
+  update(props: P, triggerProps?: T): void;
+
+  /** Closes the menu programmatically. */
+  close(): void;
+
+  /** Current open/closed state of the menu. */
+  isOpen: boolean;
+
+  /**
+   * JSX element that must be rendered in your component tree.
+   * Contains the MenuTrigger and positioning logic.
+   */
+  get rendered(): ReactElement | null;
+};
+```
+
+### Parameters
+
+- **`Component`** - The menu component to render (`Menu`, `CommandMenu`, etc.)
+- **`defaultTriggerProps`** - Default props passed to `MenuTrigger` for positioning and behavior
+- **`defaultMenuProps`** - Default props passed to the menu component (merged with runtime props)
+
+## Key Features
+
+### Programmatic Control
+
+The hook provides full programmatic control over the menu:
+
+- **`open()`** opens the menu with provided props
+- **`update()`** updates menu props without closing/reopening
+- **`close()`** closes the menu
+- **No automatic triggering** - designed for manual control via events or state
+
+### Element-Based Positioning
+
+Positions menus relative to the anchor element:
+
+- Uses **`anchorRef`** for positioning context
+- Supports **collision detection** and automatic repositioning via MenuTrigger
+- **Default placement:** `"bottom start"`
+- Customizable via `defaultTriggerProps` or runtime `triggerProps`
+
+### Props Merging Strategy
+
+- **`defaultMenuProps`** - Used as base props for the menu component
+- **Runtime props** (via `open()`/`update()`) - Merged with defaults, taking precedence
+- **Trigger props** - Merged with `defaultTriggerProps` for positioning control
+
+### Menu Synchronization
+
+Integrates with the global menu synchronization system:
+
+- **Only one menu open** at a time across the entire application
+- **Automatic closing** when other menus open
+- **Works with** `MenuTrigger`, `useContextMenu`, `Select`, `ComboBox`, etc.
+
+## Usage
+
+```tsx
+import { useAnchoredMenu, Menu, Button, Flex } from '@cube-dev/ui-kit';
+import { IconDotsVertical } from '@tabler/icons-react';
+
+function TabWithMultipleTriggers() {
+  const menu = useAnchoredMenu(
+    Menu, 
+    {
+      placement: 'top end',
+    },
+    {
+      // Default menu props applied to all menu opens
+      onAction: (key) => {
+        console.log('Tab action:', key);
+      },
+      children: (
+        <>
+          <Menu.Item key="rename">Rename Tab</Menu.Item>
+          <Menu.Item key="duplicate">Duplicate Tab</Menu.Item>
+          <Menu.Item key="close">Close Tab</Menu.Item>
+          <Menu.Item key="close-others">Close Other Tabs</Menu.Item>
+        </>
+      ),
+    }
+  );
+
+  const openTab = () => {
+    console.log('Opening tab...');
+  };
+
+  const openActionsMenu = () => {
+    // Opens with default props - no need to pass them again
+    menu.open();
+  };
+
+  const handleRightClick = (event) => {
+    event.preventDefault();
+    openActionsMenu(event);
+  };
+
+  return (
+    <>
+      <Flex
+        ref={menu.anchorRef}
+        display="inline-flex"
+        onContextMenu={handleRightClick}
+      >
+        <Button size="small" radius="left" onPress={openTab}>
+          Open file
+        </Button>
+
+        <Button
+          size="small"
+          icon={<IconDotsVertical />}
+          aria-label="Tab actions"
+          padding="1x"
+          radius="right"
+          margin="-1bw left"
+          onPress={openActionsMenu}
+        />
+      </Flex>
+
+      {menu.rendered}
+    </>
+  );
+}
+```
+
+This example demonstrates how `defaultMenuProps` simplifies menu usage by defining common menu content once:
+
+1. **Click the dots button** to open the actions menu
+2. **Right-click anywhere on the tab** to also open the same actions menu
+
+The menu content and behavior are defined in `defaultMenuProps`, eliminating the need to pass the same props repeatedly. Both triggers share the same anchor point (`menu.anchorRef`) and use the predefined menu configuration, showcasing how `defaultMenuProps` reduces code duplication in complex UI interactions.
+
+> **Important:** The `{rendered}` element must be placed in the component tree such that the MenuTrigger can properly position relative to the anchorRef. Typically, place it adjacent to the anchor element.
+
+## Comparison with Related Hooks
+
+| Feature | `useAnchoredMenu` | `useContextMenu` |
+|---------|-------------------|------------------|
+| **Positioning** | Element-anchored | Cursor coordinates |
+| **Trigger** | Manual (programmatic) | Right-click (automatic) |
+| **Event Binding** | Manual event handling | Automatic `onContextMenu` |
+| **Use Cases** | Dropdown menus, action buttons | Context menus, right-click actions |
+| **Default Placement** | `"bottom start"` | `"bottom start"` |
+| **Setup Complexity** | Manual open calls | Minimal (auto-binding) |
+
+## Implementation Notes
+
+### Positioning
+
+The hook positions the menu by:
+
+1. Using the **`anchorRef`** as the positioning target
+2. Creating a visually hidden trigger for accessibility
+3. Delegating to **`MenuTrigger`** for collision detection and final positioning
+
+### Event Handling
+
+- **No automatic events** - consumer must call `open()` in response to events
+- **State management** handled internally with synchronization
+
+### Memory Management
+
+- **Event listeners** for global synchronization cleaned up automatically
+- **Menu content** only rendered when open
+- **No memory leaks** from uncleaned handlers
+
+---
+
+*Last updated: 2025-01-16* 

package/docs/components/actions/use-context-menu.md

@@ -0,0 +1,220 @@
+# `useContextMenu` Hook
+
+## Purpose
+
+`useContextMenu` is a React hook that enables components to display context menus (like `Menu` or `CommandMenu`) at the exact cursor position where the user right-clicked or triggered a context action. Unlike [`useAnchoredMenu`](./use-anchored-menu.md) which anchors menus to specific elements, `useContextMenu` positions menus at cursor coordinates or centers them on the target element, making it perfect for traditional right-click context menus and programmatic menu opening.
+
+The hook automatically handles `onContextMenu` event binding and provides a clean API for both automatic (right-click) and programmatic menu opening.
+
+## Related Components
+
+- [`useAnchoredMenu`](./use-anchored-menu.md) - For menus anchored to specific elements
+- [`MenuTrigger`](./MenuTrigger.md) - The underlying trigger component used for positioning
+- [`Menu`](./Menu.md) - The menu component typically used with this hook
+- [`CommandMenu`](./CommandMenu.md) - Command palette component that can be used with this hook
+
+## API
+
+```ts
+function useContextMenu<P, T = ComponentProps<typeof MenuTrigger>>(
+  Component: ComponentType<P>,
+  defaultTriggerProps?: Omit<
+    ComponentProps<typeof MenuTrigger>,
+    'children' | 'isOpen' | 'onOpenChange' | 'targetRef'
+  >,
+  defaultMenuProps?: P,
+): {
+  /** Container element that receives context menu events. Attach this ref to your target element. */
+  targetRef: RefObject<HTMLElement>;
+
+  /**
+   * Programmatically opens the menu at the specified coordinates or element center.
+   * Runtime props are merged with defaultMenuProps (runtime props take precedence).
+   *
+   * @param props - Props to pass to the menu component (optional, defaults to defaultMenuProps)
+   * @param triggerProps - Additional props for MenuTrigger (merged with defaultTriggerProps)
+   * @param event - The pointer/mouse event containing coordinates for positioning (optional, centers on element if not provided)
+   */
+  open(
+    props?: P,
+    triggerProps?: T,
+    event?: MouseEvent | PointerEvent,
+  ): void;
+
+  /**
+   * Updates the props of the currently open menu without repositioning.
+   * Props are merged with defaultMenuProps.
+   */
+  update(props: P, triggerProps?: T): void;
+
+  /** Closes the menu programmatically. */
+  close(): void;
+
+  /** Current open/closed state of the menu. */
+  isOpen: boolean;
+
+  /**
+   * JSX element that must be rendered in your component tree.
+   * Contains the MenuTrigger and positioning logic.
+   * IMPORTANT: Must be placed directly inside the target container (the element with targetRef).
+   */
+  get rendered(): ReactElement | null;
+};
+```
+
+### Parameters
+
+- **`Component`** - The menu component to render (`Menu`, `CommandMenu`, etc.)
+- **`defaultTriggerProps`** - Default props passed to `MenuTrigger` for positioning and behavior
+- **`defaultMenuProps`** - Default props passed to the menu component (used for automatic right-click opening)
+
+## Key Features
+
+### Automatic Context Menu Binding
+
+The hook automatically binds `onContextMenu` events to the `targetRef` element:
+
+- **Right-click** automatically opens the menu using `defaultMenuProps`
+- **`event.preventDefault()`** is called automatically to suppress the browser's native context menu
+- **No manual event binding required** in most cases
+
+### Flexible Positioning
+
+`useContextMenu` supports two positioning modes:
+
+1. **Coordinate-Based Positioning** (when event is provided):
+   - Creates an **invisible anchor element** at click coordinates
+   - Supports **collision detection** and automatic repositioning
+   - **Clamps coordinates** to stay within the container bounds
+   - Works with **scrollable containers** by accounting for scroll offset
+
+2. **Center Positioning** (when no event is provided):
+   - Positions the menu at the **center of the target element**
+   - Useful for **programmatic menu opening** from buttons or keyboard shortcuts
+   - Respects **element padding and borders** for accurate centering
+
+### Props Merging Strategy
+
+The hook provides flexible prop management:
+
+- **`defaultMenuProps`** - Used for automatic right-click opening
+- **Runtime props** (via `open()`) - Merged with defaults, taking precedence
+- **Trigger props** - Merged with `defaultTriggerProps` for positioning control
+
+### Menu Synchronization
+
+Integrates with the global menu synchronization system:
+
+- **Only one menu open** at a time across the entire application
+- **Automatic closing** when other menus open
+- **Works with** `MenuTrigger`, `useAnchoredMenu`, `Select`, `ComboBox`, etc.
+
+## Basic Usage
+
+```tsx
+import { useContextMenu, Menu } from '@cube-dev/ui-kit';
+
+function FileItem({ file }) {
+  const handleAction = (key) => {
+    console.log(`Action ${key} on ${file.name}`);
+  };
+
+  const { targetRef, rendered } = useContextMenu(
+    Menu,
+    { placement: 'bottom start' },     // trigger props
+    { 
+      onAction: handleAction,
+      children: (
+        <>
+          <Menu.Item key="open">Open</Menu.Item>
+          <Menu.Item key="rename">Rename</Menu.Item>
+          <Menu.Item key="delete">Delete</Menu.Item>
+        </>
+      )
+    }
+  );
+
+  return (
+    <div ref={targetRef} className="file-item">
+      {/* IMPORTANT: rendered must be placed directly inside the target container */}
+      {rendered}
+      <span>{file.name}</span>
+    </div>
+  );
+}
+```
+
+> **Important:** The `{rendered}` element must be placed **directly inside** the element that has the `targetRef` attached. This ensures proper coordinate calculation and positioning for the context menu.
+
+## Comparison with Related Hooks
+
+| Feature | `useContextMenu` | `useAnchoredMenu` |
+|---------|------------------|-------------------|
+| **Positioning** | Cursor coordinates or element center | Element-anchored |
+| **Trigger** | Right-click (automatic) + programmatic | Manual (button click) |
+| **Event Binding** | Automatic `onContextMenu` | Manual event handling |
+| **Use Cases** | Context menus, right-click actions, toolbar dropdowns | Dropdown menus, action buttons |
+| **Default Placement** | `"bottom start"` | `"bottom start"` |
+| **Setup Complexity** | Minimal (auto-binding) | Manual event handling |
+
+## Implementation Notes
+
+### Coordinate Calculation
+
+The hook calculates menu position differently based on whether an event is provided:
+
+**With Event (Coordinate-Based):**
+1. **Getting viewport coordinates** from the pointer event
+2. **Converting to container-relative coordinates** accounting for borders and scroll
+3. **Clamping to container bounds** to ensure the menu stays visible
+4. **Creating an invisible anchor** at the calculated position
+5. **Delegating to MenuTrigger** for collision detection and final positioning
+
+**Without Event (Center-Based):**
+1. **Calculating element center** using `clientWidth/2` and `clientHeight/2`
+2. **Accounting for scroll offset** to position relative to content area
+3. **Clamping to container bounds** to ensure proper positioning
+4. **Creating an invisible anchor** at the center position
+
+### Event Handling
+
+- **Automatic binding** occurs via `useEffect` on the `targetRef`
+- **Event listeners** are properly cleaned up on unmount
+- **`preventDefault()`** is called automatically for context menu events
+- **Manual `open()` calls** can still prevent default if an event is provided
+
+### Memory Management
+
+- **Event listeners** are bound/unbound automatically
+- **Menu content** is only rendered when needed
+- **Position calculations** are performed only when opening
+- **No memory leaks** from uncleaned event handlers
+
+### Rendered Element Placement
+
+The `{rendered}` element contains the invisible anchor and MenuTrigger components needed for positioning. It **must** be placed directly inside the element with `targetRef` because:
+
+- **Coordinate calculations** are relative to the target container
+- **Scroll offset handling** requires the rendered element to be within the scrollable area
+- **CSS positioning context** needs to be established correctly
+- **Event coordinate mapping** depends on the proper parent-child relationship
+
+```tsx
+// ✅ Correct placement
+<div ref={targetRef}>
+  {rendered}
+  <content />
+</div>
+
+// ❌ Incorrect placement
+<div>
+  <div ref={targetRef}>
+    <content />
+  </div>
+  {rendered}
+</div>
+```
+
+---
+
+*Last updated: 2025-01-16* 

package/docs/components/content/Badge.md

@@ -0,0 +1,187 @@
+# Badge
+
+Badges are small, circular indicators that display numerical counts or short status text. They are typically used to draw attention to new, updated, or important information.
+
+## When to Use
+
+- **Notification counts**: Show unread messages, notifications, or pending items
+- **Status indicators**: Display simple status like "NEW", "HOT", or error counts
+- **Numerical data**: Show counts, quantities, or metrics at a glance
+- **Activity indicators**: Highlight areas with recent activity or updates
+- **Completion tracking**: Display progress counts (e.g., "3/10")
+
+## When Not to Use
+
+- **Long text**: Use `Tag` for longer labels or categorization
+- **Interactive elements**: Use `Button` for clickable actions
+- **Detailed information**: Use `Tooltip` or expanded content for complex details
+- **Navigation**: Use `Button` or `Link` for navigation purposes
+
+## Component
+
+---
+
+### Properties
+
+### Base Properties
+
+Badge 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
+
+Badges support multiple themes for different semantic meanings:
+
+Available themes:
+- **Special** (default): Purple background, highlighted features
+- **Warning**: Yellow/amber background, caution or attention needed
+- **Note**: Violet background, informational content
+- **Success**: Green background, positive states
+- **Danger**: Red background, errors or urgent items
+- **Disabled**: Gray background, inactive items
+
+### Numbers
+
+Badges commonly display numerical counts:
+
+Best practices for numbers:
+- Use single digits for small counts (1-9)
+- Show exact numbers up to 99
+- Consider "99+" format for counts over 99
+- Keep numerical badges concise and scannable
+
+```jsx
+<Badge>5</Badge>
+<Badge>99</Badge>
+<Badge theme="danger">12</Badge>
+```
+
+### Text Content
+
+Short text labels work well in badges:
+
+Guidelines for text badges:
+- Keep text to 2-4 characters maximum
+- Use uppercase for better readability
+- Common patterns: "NEW", "HOT", "BETA", "PRO"
+
+```jsx
+<Badge>NEW</Badge>
+<Badge theme="success">OK</Badge>
+<Badge theme="danger">ERR</Badge>
+```
+
+### Sizes
+
+Badges support multiple sizes inherited from the Item component:
+
+- **inline** (default): Compact, inline badge optimized for text flow
+- **xsmall**: Extra small size
+- **small**: Small size
+- **medium**: Medium size
+- **large**: Large size
+- **xlarge**: Extra large size
+
+### With Icons
+
+Badges can include icons for additional visual context:
+
+Add an icon before the badge content using the `icon` prop:
+
+```jsx
+import { IconCoin } from '@tabler/icons-react';
+
+<Badge icon={<IconCoin />} theme="success">
+  12
+</Badge>
+```
+
+### With Right Icon
+
+Place icons after the content using the `rightIcon` prop:
+
+```jsx
+<Badge rightIcon={<IconCoin />} theme="danger">
+  ERR
+</Badge>
+```
+
+### With Both Icons
+
+Combine both `icon` and `rightIcon` for complex layouts:
+
+```jsx
+<Badge icon={<IconCoin />} rightIcon={<IconCoin />} theme="success">
+  NEW
+</Badge>
+```
+
+## Best Practices
+
+### Content
+
+- Keep badge content concise and scannable
+- Use numbers for counts ("3" not "three")
+- Use uppercase for text badges for better readability
+- Consider "99+" format for very large counts
+
+### Placement
+
+- Position badges near related content without obscuring it
+- Maintain consistent positioning across similar contexts
+
+### Visual Design
+
+- Use theme colors consistently for semantic meaning
+- Ensure adequate spacing from surrounding content
+
+### Accessibility
+
+- Provide context for counts via tooltips when needed
+- Don't rely solely on color to convey meaning
+- All themes maintain sufficient color contrast
+
+## Use Cases
+
+### Navigation Badges
+
+Display notification counts on menu items:
+
+```jsx
+<Item icon={<IconBell />}>
+  Notifications
+  <Badge theme="danger">5</Badge>
+</Item>
+```
+
+### Status Indicators
+
+Show item status or state:
+
+```jsx
+<Item>
+  Beta Feature <Badge theme="special">BETA</Badge>
+</Item>
+```
+
+### Inline Counts
+
+Display counts within text:
+
+```jsx
+<Text>
+  Unread Messages <Badge>12</Badge>
+</Text>
+```
+
+## Related Components
+
+- **Tag**: For longer labels, categorization, or closable elements
+- **Chip**: For interactive selection chips
+- **Item**: Base component that Badge extends from
+- **Text**: For displaying badge content inline with text