@cube-dev/ui-kit 0.121.0 → 0.121.1

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

@@ -0,0 +1,209 @@
+# `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
+
+- **`Positioning`** — useAnchoredMenu: Element-anchored; useContextMenu: Cursor coordinates
+- **`Trigger`** — useAnchoredMenu: Manual (programmatic); useContextMenu: Right-click (automatic)
+- **`Event Binding`** — useAnchoredMenu: Manual event handling; useContextMenu: Automatic `onContextMenu`
+- **`Use Cases`** — useAnchoredMenu: Dropdown menus, action buttons; useContextMenu: Context menus, right-click actions
+- **`Default Placement`** — Both: `"bottom start"`
+- **`Setup Complexity`** — useAnchoredMenu: Manual open calls; useContextMenu: 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,218 @@
+# `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
+
+- **`Positioning`** — useContextMenu: Cursor coordinates or element center; useAnchoredMenu: Element-anchored
+- **`Trigger`** — useContextMenu: Right-click (automatic) + programmatic; useAnchoredMenu: Manual (button click)
+- **`Event Binding`** — useContextMenu: Automatic `onContextMenu`; useAnchoredMenu: Manual event handling
+- **`Use Cases`** — useContextMenu: Context menus, right-click actions, toolbar dropdowns; useAnchoredMenu: Dropdown menus, action buttons
+- **`Default Placement`** — Both: `"bottom start"`
+- **`Setup Complexity`** — useContextMenu: Minimal (auto-binding); useAnchoredMenu: 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/ActiveZone.md

@@ -0,0 +1,37 @@
+# ActiveZone
+
+A focusable, clickable zone with hover and focus states. Used for making non-button elements interactive.
+
+## When to Use
+
+- Clickable cards or list items
+- Custom interactive regions
+- Wrapping content that should respond to click/hover/focus
+
+## Properties
+
+- **`label`** `string` — Accessible label for screen readers
+- **`onClick`** `MouseEventHandler` — Click handler
+- **`isDisabled`** `boolean` — Disables interaction, reduces opacity
+
+### Style Defaults
+
+- `display` — `inline-grid`
+- `position` — `relative`
+- `opacity` — `1` (switches to `0.4` when disabled)
+- `transition` — `theme`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<ActiveZone label="Open details" onClick={() => openDetails()}>
+  <Card>
+    <Title level={4}>Clickable Card</Title>
+    <Paragraph>This whole card is clickable</Paragraph>
+  </Card>
+</ActiveZone>
+```

package/docs/components/content/Alert.md

@@ -0,0 +1,40 @@
+# Alert
+
+An alert message with theme variants. Used for announcements, warnings, and informational messages.
+
+## When to Use
+
+- Form validation messages
+- Success/error/warning notifications
+- Informational banners
+
+## Properties
+
+- **`theme`** `'note' | 'success' | 'danger' | 'warning' | 'disabled'` (default: `'note'`) — Visual theme
+- **`type`** — Deprecated, use `theme` instead
+- **`shape`** `'card' | 'sharp'` (default: `'card'`) — `card` shows border radius and border; `sharp` removes both
+
+### Style Defaults
+
+- `display` — `block`
+- `flow` — `column`
+- `padding` — `1.5x`
+- `preset` — `t3`
+- `radius` — `1cr` (switches to `0` when `shape="sharp"`)
+- `color` — `#dark-02`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Alert theme="note">Informational message</Alert>
+
+<Alert theme="success">Operation completed successfully</Alert>
+
+<Alert theme="danger">Something went wrong</Alert>
+
+<Alert theme="warning" shape="sharp">Warning with sharp corners</Alert>
+```

package/docs/components/content/Avatar.md

@@ -0,0 +1,37 @@
+# Avatar
+
+A circular avatar for user profiles. Displays initials, icons, or images.
+
+## When to Use
+
+- User profile pictures
+- User lists and comments
+- Account indicators
+
+## Properties
+
+- **`size`** `string` (default: `'4x'`) — Avatar size (width and height)
+- **`icon`** `ReactNode` — Icon to display
+
+### Style Defaults
+
+- `display` — `grid`
+- `fill` — `#primary`
+- `color` — `#white`
+- `radius` — `round`
+- `placeContent` — `center`
+- `fontWeight` — `500`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Avatar>JD</Avatar>
+
+<Avatar size="6x">AB</Avatar>
+
+<Avatar icon={<IconUser />} />
+```