+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "Demonstrates the hotkeys functionality in ItemButton. When the `hotkeys` prop is provided, it automatically displays the keyboard shortcut in the suffix area (unless a custom suffix is provided) and registers a global keyboard listener. The hotkeys work from anywhere on the page and will trigger the button's onPress handler.",
+ },
+ },
+ },
+};
+
+export const WithCheckbox: Story = {
+ render: (args) => (
+
+
+ With checkbox (selected)
+
+
+ With checkbox (not selected)
+
+ }>
+ With regular icon
+
+
+
+
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'Demonstrates the checkbox functionality in ItemButton when `isSelected` prop is provided. When `isSelected` is `true`, the checkbox is visible (opacity 1, hover opacity 0.8). When `isSelected` is `false`, the checkbox is invisible (opacity 0, hover opacity 0.4). The checkbox replaces the `icon` prop when `isSelected` is provided, inherited from the ItemBase component.',
+ },
+ },
+ },
+};
+
+export const AutoTooltipOnOverflow: Story = {
+ render: (args) => (
+
+
+
Auto Tooltip with tooltip=true
+
+ }
+ style={{ width: '200px' }}
+ >
+ This text is long enough to overflow and trigger auto tooltip
+
+ }
+ style={{ width: '200px' }}
+ >
+ Short text
+
+
+
+
+
+
Auto Tooltip with Configuration Object
+
+ }
+ style={{ width: '180px' }}
+ >
+ Long text with custom placement that will show tooltip on top
+
+ }
+ style={{ width: '180px' }}
+ >
+ Text with custom delay and bottom placement
+
+
+
+
+
+
Auto vs Explicit Tooltip
+
+ }
+ style={{ width: '150px' }}
+ >
+ Explicit title takes priority over auto
+
+ }
+ style={{ width: '150px' }}
+ >
+ Auto tooltip shows this text when overflowed
+
+
+
+
+
+
No Tooltip When Not Overflowed
+
+ }
+ style={{ width: '300px' }}
+ >
+ Short text (no tooltip)
+
+ }
+ style={{ width: '400px' }}
+ >
+ Normal length text (no tooltip)
+
+
: null}
-
-
-
- {rendered}
-
- {description ? (
-
- {description}
-
- ) : null}
-
- {finalPostfix && getPostfix(finalPostfix)}
-
-
-
-
+ {rendered}
+
);
}
diff --git a/src/components/actions/Menu/MenuSection.tsx b/src/components/actions/Menu/MenuSection.tsx
index 9cceabc3c..b4dd3613c 100644
--- a/src/components/actions/Menu/MenuSection.tsx
+++ b/src/components/actions/Menu/MenuSection.tsx
@@ -25,7 +25,11 @@ export function MenuSection(props: CubeMenuSectionProps) {
<>
{heading && (
-
+
{heading}
)}
diff --git a/src/components/actions/Menu/MenuTrigger.tsx b/src/components/actions/Menu/MenuTrigger.tsx
index a521d7958..6846bea14 100644
--- a/src/components/actions/Menu/MenuTrigger.tsx
+++ b/src/components/actions/Menu/MenuTrigger.tsx
@@ -172,7 +172,7 @@ function MenuTrigger(props: CubeMenuTriggerProps, ref: DOMRef) {
style={positionProps.style}
placement={placement}
shouldCloseOnInteractOutside={(el) => {
- const menuTriggerEl = el.closest('[data-menu-trigger]');
+ const menuTriggerEl = el.closest('[data-popover-trigger]');
// If no menu trigger was clicked, allow closing
if (!menuTriggerEl) return true;
// For dummy triggers (like useAnchoredMenu), check if the clicked element
@@ -205,7 +205,7 @@ function MenuTrigger(props: CubeMenuTriggerProps, ref: DOMRef) {
{menuTrigger}
diff --git a/src/components/actions/Menu/styled.tsx b/src/components/actions/Menu/styled.tsx
index e90e522f2..aed2f8e26 100644
--- a/src/components/actions/Menu/styled.tsx
+++ b/src/components/actions/Menu/styled.tsx
@@ -1,6 +1,7 @@
-import { DEFAULT_BUTTON_STYLES, DEFAULT_NEUTRAL_STYLES } from '..';
+import { DEFAULT_NEUTRAL_STYLES } from '../../../data/item-themes';
import { tasty } from '../../../tasty';
import { Space } from '../../layout/Space';
+import { DEFAULT_BUTTON_STYLES } from '../Button/Button';
export const StyledMenuWrapper = tasty({
qa: 'Menu',
@@ -74,13 +75,21 @@ export const StyledHeader = tasty(Space, {
placeContent: 'space-between',
placeItems: 'center',
whiteSpace: 'nowrap',
- padding: '.5x 1.5x',
- height: {
- '': 'min $size-md',
- '[data-size="large"]': 'min $size-lg',
- },
+ padding: '.5x $inline-padding',
+ height: 'min $size',
boxSizing: 'border-box',
border: 'bottom',
+
+ $size: {
+ '': '$size-md',
+ '[data-size="small"]': '$size-sm',
+ '[data-size="medium"]': '$size-md',
+ '[data-size="large"]': '$size-lg',
+ },
+ '$inline-padding':
+ 'max($min-inline-padding, (($size - 1lh) / 2 + $inline-compensation))',
+ '$inline-compensation': '1x',
+ '$min-inline-padding': '1x',
},
});
@@ -201,9 +210,23 @@ export const StyledSectionHeading = tasty(Space, {
styles: {
color: '#dark-04',
preset: 'c2',
- padding: '.5x 1x',
height: '3x',
placeContent: 'center space-between',
align: 'start',
+ padding: {
+ '': '.5x $inline-padding',
+ prefix: '0 $inline-padding 0 .5x',
+ },
+
+ $size: {
+ '': '$size-md',
+ '[data-size="small"]': '$size-sm',
+ '[data-size="medium"]': '$size-md',
+ '[data-size="large"]': '$size-lg',
+ },
+ '$inline-padding':
+ 'max($min-inline-padding, (($size - 1lh) / 2 + $inline-compensation - 1bw))',
+ '$inline-compensation': '.5x',
+ '$min-inline-padding': '1x',
},
});
diff --git a/src/components/actions/index.ts b/src/components/actions/index.ts
index aacc40b3a..11cf6653c 100644
--- a/src/components/actions/index.ts
+++ b/src/components/actions/index.ts
@@ -10,6 +10,7 @@ const Button = Object.assign(
export * from './Button';
export * from './Action/Action';
+export * from './ItemButton';
export * from './Menu';
export * from './CommandMenu';
export * from './use-action';
diff --git a/src/components/actions/use-anchored-menu.docs.mdx b/src/components/actions/use-anchored-menu.docs.mdx
index abe07e35e..b484f39c5 100644
--- a/src/components/actions/use-anchored-menu.docs.mdx
+++ b/src/components/actions/use-anchored-menu.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/blocks';
+import { Meta } from '@storybook/addon-docs/blocks';
@@ -26,20 +26,22 @@ function useAnchoredMenu<P, T = ComponentProps<typeof MenuTrigger>>(
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.
- * @param props - Props to pass to the menu component
+ * 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 if defaults are provided.
+ * Props are merged with defaultMenuProps.
*/
update(props: P, triggerProps?: T): void;
@@ -61,6 +63,7 @@ function useAnchoredMenu<P, T = ComponentProps<typeof MenuTrigger>>(
- **`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
@@ -84,8 +87,9 @@ Positions menus relative to the anchor element:
### Props Merging Strategy
-- **Runtime props** (via `open()`/`update()`) for menu component
-- **Trigger props** merged with `defaultTriggerProps` for positioning control
+- **`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
@@ -102,16 +106,13 @@ 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',
- });
-
- const openTab = () => {
- console.log('Opening tab...');
- };
-
- const openActionsMenu = () => {
- menu.open({
+ const menu = useAnchoredMenu(
+ Menu,
+ {
+ placement: 'top end',
+ },
+ {
+ // Default menu props applied to all menu opens
onAction: (key) => {
console.log('Tab action:', key);
},
@@ -123,7 +124,16 @@ function TabWithMultipleTriggers() {
Close Other Tabs
),
- });
+ }
+ );
+
+ const openTab = () => {
+ console.log('Opening tab...');
+ };
+
+ const openActionsMenu = () => {
+ // Opens with default props - no need to pass them again
+ menu.open();
};
const handleRightClick = (event) => {
@@ -159,12 +169,12 @@ function TabWithMultipleTriggers() {
}
```
-This example demonstrates a more realistic use case where a single menu can be triggered in multiple ways:
+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
-Both triggers share the same anchor point (`menu.anchorRef`) and open the same menu with identical content, showcasing the flexibility of `useAnchoredMenu` for creating sophisticated UI interactions.
+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.
diff --git a/src/components/actions/use-anchored-menu.tsx b/src/components/actions/use-anchored-menu.tsx
index 2f9f6b38b..5a4d490cf 100644
--- a/src/components/actions/use-anchored-menu.tsx
+++ b/src/components/actions/use-anchored-menu.tsx
@@ -27,7 +27,7 @@ export interface UseAnchoredMenuReturn {
* @param props - Props to pass to the menu component
* @param triggerProps - Additional props for MenuTrigger (merged with defaultTriggerProps)
*/
- open(props: P, triggerProps?: T): void;
+ open(props?: P, triggerProps?: T): void;
/**
* Updates the props of the currently open menu.
@@ -53,6 +53,7 @@ export interface UseAnchoredMenuReturn {
*
* @param Component - A React component that represents the menu content (Menu or CommandMenu).
* @param defaultTriggerProps - Default props to pass to the MenuTrigger.
+ * @param defaultMenuProps - Default props to pass to the Menu component.
* @returns An object with `anchorRef` to position the menu, `open` function to open the menu with provided props, `close` function to close the menu, and `rendered` JSX element to include in your component tree.
*/
export function useAnchoredMenu>(
@@ -61,6 +62,7 @@ export function useAnchoredMenu>(
ComponentProps,
'children' | 'isOpen' | 'onOpenChange' | 'targetRef'
>,
+ defaultMenuProps?: P,
): UseAnchoredMenuReturn {
const [isOpen, setIsOpen] = useState(false);
const [componentProps, setComponentProps] = useState
(null);
@@ -112,10 +114,15 @@ export function useAnchoredMenu>(
}
// 'open' accepts props required by the Component and opens the menu
- const open = useEvent((props: P, triggerProps?: T) => {
+ const open = useEvent((props: P = {} as P, triggerProps?: T) => {
setupCheck();
- setComponentProps(props);
+ // Merge defaultMenuProps with provided props
+ const finalProps = defaultMenuProps
+ ? { ...defaultMenuProps, ...props }
+ : props;
+
+ setComponentProps(finalProps);
setTriggerProps(triggerProps ?? null);
setIsOpen(true);
});
@@ -123,7 +130,12 @@ export function useAnchoredMenu>(
const update = useEvent((props: P, triggerProps?: T) => {
setupCheck();
- setComponentProps(props);
+ // Merge defaultMenuProps with provided props
+ const finalProps = defaultMenuProps
+ ? { ...defaultMenuProps, ...props }
+ : props;
+
+ setComponentProps(finalProps);
setTriggerProps(triggerProps ?? null);
});
diff --git a/src/components/actions/use-context-menu.docs.mdx b/src/components/actions/use-context-menu.docs.mdx
index 9c19c4373..9a0dd0f48 100644
--- a/src/components/actions/use-context-menu.docs.mdx
+++ b/src/components/actions/use-context-menu.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/blocks';
+import { Meta } from '@storybook/addon-docs/blocks';
diff --git a/src/components/actions/use-context-menu.tsx b/src/components/actions/use-context-menu.tsx
index 49bbfaf17..b41d8bdb6 100644
--- a/src/components/actions/use-context-menu.tsx
+++ b/src/components/actions/use-context-menu.tsx
@@ -199,7 +199,7 @@ export function useContextMenu<
// 'open' accepts props, trigger props, and optional event for positioning, then opens the menu
const open = useEvent(
(
- props?: P,
+ props: P = {} as P,
triggerProps?: T,
event?: NativeMouseEvent | NativePointerEvent | MouseEvent | PointerEvent,
) => {
@@ -234,7 +234,7 @@ export function useContextMenu<
? { ...defaultMenuProps, ...props }
: props;
- setComponentProps(finalProps as P);
+ setComponentProps(finalProps);
setTriggerProps(triggerProps ?? null);
setIsOpen(true);
},
diff --git a/src/components/content/Alert/Alert.stories.tsx b/src/components/content/Alert/Alert.stories.tsx
index 6b658a37c..438642f18 100644
--- a/src/components/content/Alert/Alert.stories.tsx
+++ b/src/components/content/Alert/Alert.stories.tsx
@@ -1,4 +1,4 @@
-import { Meta, StoryFn } from '@storybook/react';
+import { Meta, StoryFn } from '@storybook/react-vite';
import { baseProps } from '../../../stories/lists/baseProps';
diff --git a/src/components/content/Avatar/Avatar.stories.tsx b/src/components/content/Avatar/Avatar.stories.tsx
index 460fcfc8c..e8183ed09 100644
--- a/src/components/content/Avatar/Avatar.stories.tsx
+++ b/src/components/content/Avatar/Avatar.stories.tsx
@@ -1,4 +1,4 @@
-import { StoryFn } from '@storybook/react';
+import { StoryFn } from '@storybook/react-vite';
import { IconCoin } from '@tabler/icons-react';
import { baseProps } from '../../../stories/lists/baseProps';
diff --git a/src/components/content/CopyPasteBlock/CopyPasteBlock.stories.tsx b/src/components/content/CopyPasteBlock/CopyPasteBlock.stories.tsx
index 60fd8e1d2..f0b936026 100644
--- a/src/components/content/CopyPasteBlock/CopyPasteBlock.stories.tsx
+++ b/src/components/content/CopyPasteBlock/CopyPasteBlock.stories.tsx
@@ -1,4 +1,4 @@
-import { Meta, StoryFn } from '@storybook/react';
+import { Meta, StoryFn } from '@storybook/react-vite';
import { useState } from 'react';
import { baseProps } from '../../../stories/lists/baseProps';
diff --git a/src/components/content/CopySnippet/CopySnippet.stories.tsx b/src/components/content/CopySnippet/CopySnippet.stories.tsx
index 8d521e2fe..f6ce49180 100644
--- a/src/components/content/CopySnippet/CopySnippet.stories.tsx
+++ b/src/components/content/CopySnippet/CopySnippet.stories.tsx
@@ -1,4 +1,4 @@
-import { Meta, StoryFn } from '@storybook/react';
+import { Meta, StoryFn } from '@storybook/react-vite';
import { IconSettings } from '@tabler/icons-react';
import { baseProps } from '../../../stories/lists/baseProps';
diff --git a/src/components/content/HotKeys/HotKeys.docs.mdx b/src/components/content/HotKeys/HotKeys.docs.mdx
index f5c575f51..5980f46b1 100644
--- a/src/components/content/HotKeys/HotKeys.docs.mdx
+++ b/src/components/content/HotKeys/HotKeys.docs.mdx
@@ -1,4 +1,4 @@
-import { Meta, Canvas, Story, Controls } from '@storybook/blocks';
+import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';
import { HotKeys } from './HotKeys';
import * as HotKeysStories from './HotKeys.stories';
diff --git a/src/components/content/HotKeys/HotKeys.stories.tsx b/src/components/content/HotKeys/HotKeys.stories.tsx
index 3e539d2d8..59cb23d13 100644
--- a/src/components/content/HotKeys/HotKeys.stories.tsx
+++ b/src/components/content/HotKeys/HotKeys.stories.tsx
@@ -1,4 +1,4 @@
-import { StoryFn } from '@storybook/react';
+import { StoryFn } from '@storybook/react-vite';
import { CubeHotKeysProps, HotKeys } from './HotKeys';
diff --git a/src/components/content/HotKeys/HotKeys.tsx b/src/components/content/HotKeys/HotKeys.tsx
index f96e7efe4..e315e6c8d 100644
--- a/src/components/content/HotKeys/HotKeys.tsx
+++ b/src/components/content/HotKeys/HotKeys.tsx
@@ -10,7 +10,6 @@ import {
} from '../../../tasty';
import { useKeySymbols } from '../../../utils/react/useKeySymbols';
import { Space } from '../../layout/Space';
-import { Tag } from '../Tag/Tag';
import { Text } from '../Text';
const StyledHotKeys = tasty(Space, {
@@ -21,6 +20,37 @@ const StyledHotKeys = tasty(Space, {
display: 'inline-flex',
flow: 'row',
gap: '1x',
+ placeSelf: 'center',
+ },
+});
+
+const KeyElement = tasty({
+ as: 'kbd',
+ role: 'text',
+ styles: {
+ display: 'inline-flex',
+ placeContent: 'center',
+ placeItems: 'center start',
+ radius: '1r',
+ preset: 'tag',
+ boxSizing: 'border-box',
+ width: '2.5x max-content max-content',
+ height: 'min-content',
+ textAlign: 'left',
+ whiteSpace: 'nowrap',
+ padding: '0 (.5x - 1bw)',
+ color: {
+ '': '#dark.65',
+ '[data-type="primary"]': '#white',
+ },
+ fill: {
+ '': '#dark.04',
+ '[data-type="primary"]': '#clear',
+ },
+ border: {
+ '': true,
+ '[data-type="primary"]': '#white',
+ },
},
});
@@ -28,10 +58,11 @@ export interface CubeHotKeysProps
extends BasePropsWithoutChildren,
ContainerStyleProps {
children: string;
+ type?: 'default' | 'primary';
}
function HotKeys(props: CubeHotKeysProps, ref) {
- const { children: keys, ...otherProps } = props;
+ const { children: keys, type, ...otherProps } = props;
const parsedKeys = useKeySymbols(keys);
const styles = extractStyles(otherProps, CONTAINER_STYLES);
@@ -56,14 +87,15 @@ function HotKeys(props: CubeHotKeysProps, ref) {
aria-label={`Key combination ${groupIndex + 1}`}
>
{keyGroup.map((key, keyIndex) => (
-
{key}
-
+
))}
diff --git a/src/components/content/ItemBase/ItemBase.docs.mdx b/src/components/content/ItemBase/ItemBase.docs.mdx
new file mode 100644
index 000000000..231d7ad82
--- /dev/null
+++ b/src/components/content/ItemBase/ItemBase.docs.mdx
@@ -0,0 +1,223 @@
+import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';
+import { ItemBase } from './ItemBase';
+import * as ItemBaseStories from './ItemBase.stories';
+
+
+
+# ItemBase
+
+A foundational component that provides a standardized layout and styling for item-like elements across the design system. ItemBase offers a flexible grid-based structure with support for icons, labels, descriptions, prefixes, suffixes, and interactive features like hotkeys and tooltips.
+
+## When to Use
+
+- As a building block for other components that need item-like styling (Select options, Menu items, List items, etc.)
+- When creating custom interactive elements that need consistent spacing and alignment
+- For buttons or clickable elements that need to display structured content with icons and descriptions
+- When building components that need to support features like selection states, hotkeys, or overflow tooltips
+
+## Component
+
+
+
+---
+
+### Properties
+
+
+
+### Base Properties
+
+Supports [Base properties](/BaseProperties)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+**Sub-elements:**
+- `Icon` - The main icon displayed before the content
+- `RightIcon` - The icon displayed after the content
+- `Label` - The main text content area
+- `Description` - The secondary text below or inline with the main content
+- `Prefix` - Additional content displayed before the main content
+- `Suffix` - Additional content displayed after the main content
+
+### 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
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| with-icon | `boolean` | Applied when an icon is present |
+| with-right-icon | `boolean` | Applied when a right icon is present |
+| with-prefix | `boolean` | Applied when a prefix is present |
+| with-suffix | `boolean` | Applied when a suffix is present |
+| with-description | `boolean` | Applied when a description is present |
+| with-description-block | `boolean` | Applied when description placement is "block" |
+| checkbox | `boolean` | Applied when using checkbox icon (icon="checkbox") |
+| selected | `boolean` | Applied when isSelected is true |
+
+## Variants
+
+### Types
+
+- `item` - Default item appearance (no specific styling)
+- `primary` - Primary styled item with prominent appearance
+- `secondary` - Secondary styled item with moderate emphasis
+- `outline` - Item with border outline styling
+- `neutral` - Neutral colored item styling
+- `clear` - Transparent item with minimal styling
+- `link` - Link-styled item appearance
+
+### Themes
+
+- `default` - Standard appearance with default colors
+- `danger` - Red theme for destructive or warning actions
+- `success` - Green theme for positive actions
+- `special` - Special theme with unique styling
+
+### 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 items
+- `xlarge` - Extra large size for emphasized items
+- `inline` - Inline size that adapts to content
+
+## Examples
+
+### Basic Usage
+
+```jsx
+Simple item content
+```
+
+### With Icons
+
+```jsx
+} rightIcon={}>
+ Item with icons
+
+```
+
+### With Description
+
+```jsx
+}
+ description="Secondary description text"
+ descriptionPlacement="inline"
+>
+ Main item content
+
+```
+
+### With Hotkeys
+
+```jsx
+ console.log('Save triggered')}
+>
+ Save Document
+
+```
+
+### With Selection State
+
+```jsx
+
+ Selected item with checkbox
+
+```
+
+### With Auto Tooltip
+
+```jsx
+
+ This is a very long text that will show a tooltip when overflowed
+
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the component when it's focusable
+- `Space/Enter` - Activates the component when used as a button
+- Custom hotkeys - Trigger component actions when hotkeys are specified
+
+### Screen Reader Support
+
+- Component announces its role based on the `as` prop (button, link, etc.)
+- Selection state is announced when `isSelected` is used
+- Disabled state is properly communicated
+- Tooltip content is accessible to screen readers
+
+### ARIA Properties
+
+- `aria-label` - Provides accessible label when no visible label exists
+- `aria-disabled` - Indicates disabled state
+- `aria-selected` - Indicates selection state when applicable
+- `tabIndex` - Controls focus behavior
+
+## Best Practices
+
+1. **Do**: Use clear, descriptive text for the main content
+ ```jsx
+ }>User Profile
+ ```
+
+2. **Do**: Provide tooltips for items that might overflow
+ ```jsx
+
+ Long item name that might be truncated
+
+ ```
+
+3. **Do**: Use hotkeys for frequently accessed actions
+ ```jsx
+
+ Save Document
+
+ ```
+
+4. **Don't**: Overcrowd the component with too many elements
+ ```jsx
+ {/* Avoid this - too many elements competing for attention */}
+ }
+ rightIcon={}
+ prefix="Pre"
+ suffix="Suf"
+ description="Very long description with lots of details"
+ >
+ Complex item with everything
+
+ ```
+
+5. **Accessibility**: Always ensure interactive items are focusable and have proper ARIA attributes
+
+## Related Components
+
+- [ItemButton](/docs/actions-itembutton--docs) - Interactive button built on ItemBase
+- [Select](/docs/fields-select--docs) - Dropdown selection component using ItemBase
+- [ComboBox](/docs/fields-combobox--docs) - Searchable dropdown component using ItemBase
+- [ListBox](/docs/fields-listbox--docs) - List selection component using ItemBase
+- [FilterListBox](/docs/fields-filterlistbox--docs) - Filterable list component using ItemBase
+- [FilterPicker](/docs/fields-filterpicker--docs) - Filter selection component using ItemBase
+- [Menu](/docs/actions-menu--docs) - Context menu component using ItemBase
+- [CommandMenu](/docs/actions-commandmenu--docs) - Command palette component using ItemBase
+- [Button](/docs/actions-button--docs) - Traditional button component
+- [Link](/docs/navigation-link--docs) - Text link component
+- [Text](/docs/generic-text--docs) - Typography component for simple text
diff --git a/src/components/content/ItemBase/ItemBase.stories.tsx b/src/components/content/ItemBase/ItemBase.stories.tsx
new file mode 100644
index 000000000..f59bfe8b1
--- /dev/null
+++ b/src/components/content/ItemBase/ItemBase.stories.tsx
@@ -0,0 +1,915 @@
+import { IconCoin, IconSettings, IconUser } from '@tabler/icons-react';
+
+import { DirectionIcon } from '../../../icons';
+import { baseProps } from '../../../stories/lists/baseProps';
+import { Space } from '../../layout/Space';
+import { Title } from '../Title';
+
+import { CubeItemBaseProps, ItemBase } from './ItemBase';
+
+// Using any type due to Storybook type compatibility issues
+type StoryFn = any;
+
+export default {
+ title: 'Content/ItemBase',
+ component: ItemBase,
+ parameters: {
+ controls: {
+ exclude: baseProps,
+ },
+ },
+ argTypes: {
+ /* Content */
+ children: {
+ control: { type: 'text' },
+ description: 'The content inside the ItemBase',
+ },
+ icon: {
+ control: { type: null },
+ description: 'Icon element rendered before the content',
+ },
+ rightIcon: {
+ control: { type: null },
+ description: 'Icon element rendered after the content',
+ },
+ prefix: {
+ control: { type: null },
+ description: 'Element rendered before the content (after icon)',
+ },
+ suffix: {
+ control: { type: null },
+ description: 'Element rendered after the content (before rightIcon)',
+ },
+ description: {
+ control: { type: 'text' },
+ description: 'Description text displayed with the item',
+ },
+ descriptionPlacement: {
+ options: ['inline', 'block', 'auto'],
+ control: { type: 'radio' },
+ description:
+ 'How the description is positioned relative to the main content',
+ table: {
+ defaultValue: { summary: 'inline' },
+ },
+ },
+
+ /* Presentation */
+ size: {
+ options: ['xsmall', 'small', 'medium', 'large', 'xlarge', 'inline'],
+ control: { type: 'radio' },
+ description: 'ItemBase size',
+ table: {
+ defaultValue: { summary: 'medium' },
+ },
+ },
+ },
+};
+
+const DEFAULT_STYLES = {
+ // border: true,
+ // radius: true,
+};
+
+const DefaultTemplate: StoryFn = (props) => (
+
+);
+
+const Template: StoryFn = (props) => (
+
+);
+
+export const Default = DefaultTemplate.bind({});
+Default.args = {
+ children: 'Default ItemBase',
+};
+
+export const WithIcon = Template.bind({});
+WithIcon.args = {
+ children: 'ItemBase with icon',
+ icon: ,
+};
+
+export const WithRightIcon = Template.bind({});
+WithRightIcon.args = {
+ children: 'ItemBase with right icon',
+ rightIcon: ,
+};
+
+export const WithBothIcons = Template.bind({});
+WithBothIcons.args = {
+ children: 'ItemBase with both icons',
+ icon: ,
+ rightIcon: ,
+};
+
+export const WithPrefix = Template.bind({});
+WithPrefix.args = {
+ children: 'ItemBase with prefix',
+ prefix: '$',
+};
+
+export const WithSuffix = Template.bind({});
+WithSuffix.args = {
+ children: 'ItemBase with suffix',
+ suffix: '.00',
+};
+
+export const FullConfiguration = Template.bind({});
+FullConfiguration.args = {
+ children: 'Complete ItemBase',
+ icon: ,
+ rightIcon: ,
+ prefix: '$',
+ suffix: '.00',
+};
+
+export const DifferentSizes: StoryFn = (args) => (
+
+ XSmall ItemBase
+
+ XSmall size
+
+
+ Small ItemBase
+
+ Small size
+
+
+ Medium ItemBase
+
+ Medium size
+
+
+ Large ItemBase
+
+ Large size
+
+
+ XLarge ItemBase
+
+ XLarge size
+
+
+ Inline ItemBase
+
+ Inline size
+
+
+);
+
+DifferentSizes.args = {
+ width: '300px',
+};
+
+DifferentSizes.parameters = {
+ docs: {
+ description: {
+ story:
+ 'ItemBase supports six sizes: `xsmall`, `small`, `medium` (default), `large`, `xlarge`, and `inline` to accommodate different interface requirements.',
+ },
+ },
+};
+
+export const SizesWithIcons: StoryFn = (args) => (
+
+ XSmall with Icons
+ }
+ rightIcon={}
+ >
+ XSmall with icons
+
+
+ Small with Icons
+ }
+ rightIcon={}
+ >
+ Small with icons
+
+
+ Medium with Icons
+ }
+ rightIcon={}
+ >
+ Medium with icons
+
+
+ Large with Icons
+ }
+ rightIcon={}
+ >
+ Large with icons
+
+
+ XLarge with Icons
+ }
+ rightIcon={}
+ >
+ XLarge with icons
+
+
+ Inline with Icons
+ }
+ rightIcon={}
+ >
+ Inline with icons
+
+
+);
+
+SizesWithIcons.args = {
+ width: '350px',
+};
+
+SizesWithIcons.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Comparison of all ItemBase sizes when used with icons to show how the component adapts to different content configurations.',
+ },
+ },
+};
+
+export const TextOverflow: StoryFn = (args) => (
+
+ Text Overflow with Limited Width
+ }
+ rightIcon={}
+ >
+ This is a very long text that should overflow and show ellipsis when the
+ container width is limited
+
+
+ Text Overflow with Prefix and Suffix
+ }
+ prefix="$"
+ suffix=".00"
+ >
+ Very long product name that exceeds container width
+
+
+ Different Sizes with Text Overflow
+
+ }
+ >
+ Long text in small size component
+
+ }
+ >
+ Long text in medium size component
+
+ }
+ >
+ Long text in large size component
+
+
+
+);
+
+TextOverflow.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Demonstrates how ItemBase handles text overflow with ellipsis when content exceeds the available width. The component uses `text-overflow: ellipsis` and `white-space: nowrap` to gracefully handle long content.',
+ },
+ },
+};
+
+export const ExtraWidth: StoryFn = (args) => (
+
+ Short Text with Extra Width
+ }
+ rightIcon={}
+ >
+ Short text
+
+
+ Medium Text with Extra Width
+ }
+ prefix="$"
+ suffix=".00"
+ >
+ Product name
+
+
+ Different Sizes with Extra Width
+
+ }
+ >
+ Small size
+
+ }
+ >
+ Medium size
+
+ }
+ >
+ Large size
+
+
+
+ Icon Only with Extra Width
+ }
+ rightIcon={}
+ >
+ Icon
+
+
+);
+
+ExtraWidth.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Shows how ItemBase behaves when given more width than needed for its content. The component maintains its grid layout with proper spacing, and content alignment is controlled by the `placeItems` property.',
+ },
+ },
+};
+
+export const WithCheckbox: StoryFn = (args) => (
+
+ Selected Items (Checkbox Visible)
+
+
+ Selected item with checkbox
+
+
+ Small selected item
+
+
+ Large selected item
+
+
+
+ Non-Selected Items (Checkbox Hidden)
+
+
+ Non-selected item with hidden checkbox
+
+
+ Small non-selected item
+
+
+ Large non-selected item
+
+
+
+ Mixed Selection States
+
+
+ Item 1
+
+
+ Item 2
+
+
+ Item 3
+
+
+
+ Comparison: Checkbox vs Regular Icon
+
+
+ With checkbox (selected)
+
+
+ With checkbox (not selected)
+
+ }>
+ With regular icon
+
+
+
+);
+
+WithCheckbox.args = {
+ width: '300px',
+};
+
+WithCheckbox.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Demonstrates the checkbox functionality when `isSelected` prop is provided. When `isSelected` is `true`, the checkbox is visible (opacity 1, hover opacity 0.8). When `isSelected` is `false`, the checkbox is invisible (opacity 0, hover opacity 0.4). The checkbox replaces the `icon` prop when `isSelected` is provided.',
+ },
+ },
+};
+
+export const WithHotkeys: StoryFn = (args) => (
+
+ ItemBase with Hotkeys
+
+ alert('Save action triggered!')}
+ >
+ Save Document
+
+ }
+ onClick={() => alert('New action triggered!')}
+ >
+ New Item
+
+ alert('Cancel action triggered!')}
+ >
+ Cancel
+
+
+
+ Different Sizes with Hotkeys
+
+ alert('Small button clicked!')}
+ >
+ Small with hotkey
+
+ alert('Large button clicked!')}
+ >
+ Large with hotkey
+
+
+
+ Disabled ItemBase with Hotkeys
+ alert('This should not trigger!')}
+ >
+ Disabled (hotkey won't work)
+
+
+);
+
+WithHotkeys.args = {
+ width: '300px',
+};
+
+WithHotkeys.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Demonstrates the hotkeys functionality when `hotkeys` prop is provided. The hotkey is displayed as a suffix with the HotKeys component, and pressing the specified key combination triggers the onClick handler. Hotkeys are automatically disabled when the component is disabled.',
+ },
+ },
+};
+
+export const WithTooltip: StoryFn = (args) => (
+
+ Simple String Tooltips
+
+ }
+ onClick={() => alert('Button clicked!')}
+ >
+ Hover for tooltip
+
+ alert('Primary button clicked!')}
+ >
+ Primary with tooltip
+
+
+
+ Advanced Tooltip Configuration
+
+ }
+ onClick={() => alert('Top tooltip clicked!')}
+ >
+ Top placement
+
+ alert('Right tooltip clicked!')}
+ >
+ Right placement
+
+
+
+ Tooltip with Hotkeys
+ }
+ onClick={() => alert('Save triggered!')}
+ >
+ Save Document
+
+
+ Different Sizes with Tooltips
+
+ alert('Small clicked!')}
+ >
+ Small
+
+ alert('Large clicked!')}
+ >
+ Large
+
+
+
+);
+
+WithTooltip.args = {
+ width: '250px',
+};
+
+WithTooltip.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Demonstrates the tooltip functionality when `tooltip` prop is provided. Supports both string tooltips and advanced configuration objects with custom placement. Note: `activeWrap: true` is required in the tooltip object to make the item interactive.',
+ },
+ },
+};
+
+export const CombinedFeatures: StoryFn = (args) => (
+
+ Hotkeys + Tooltip + Icons
+
+ }
+ onClick={() => alert('New document created!')}
+ >
+ New Document
+
+ }
+ rightIcon={}
+ onClick={() => alert('Open document!')}
+ >
+ Open Document
+
+
+
+ With Checkbox Selection
+
+ alert('Selection toggled!')}
+ >
+ Selected item
+
+ alert('Item selected!')}
+ >
+ Unselected item
+
+
+
+ Complete Configuration
+ }
+ rightIcon={}
+ prefix="$"
+ suffix=".doc"
+ description="Advanced save operation"
+ onClick={() => alert('Special save!')}
+ >
+ Save Special
+
+
+);
+
+CombinedFeatures.args = {
+ width: '350px',
+};
+
+CombinedFeatures.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Demonstrates the combination of hotkeys, tooltips, icons, checkboxes, and other ItemBase features working together. This shows the full potential of the enhanced ItemBase component.',
+ },
+ },
+};
+
+export const WithDescriptionBlock: StoryFn = (args) => (
+
+ Description Position Comparison
+
+ }
+ description="This description appears inside the content area"
+ descriptionPlacement="inline"
+ >
+ Item with description inline (default)
+
+ }
+ description="This description appears below the entire item"
+ descriptionPlacement="block"
+ >
+ Item with description block
+
+
+
+ Different Sizes with Description Block
+
+ }
+ description="Small size description block"
+ descriptionPlacement="block"
+ >
+ Small item
+
+ }
+ description="Medium size description block"
+ descriptionPlacement="block"
+ >
+ Medium item
+
+ }
+ description="Large size description block"
+ descriptionPlacement="block"
+ >
+ Large item
+
+
+
+ With Multiple Elements and Description Block
+
+ }
+ rightIcon={}
+ prefix="$"
+ suffix=".99"
+ description="Complete configuration with description positioned below the item"
+ descriptionPlacement="block"
+ >
+ Product Name
+
+ }
+ hotkeys="cmd+u"
+ description="User management with hotkey and description block"
+ descriptionPlacement="block"
+ as="button"
+ onClick={() => alert('User action triggered!')}
+ >
+ Manage Users
+
+
+
+ Long Description Block
+ }
+ description="This is a very long description that demonstrates how the description text flows when positioned below the item. It can contain multiple lines and will wrap naturally."
+ descriptionPlacement="block"
+ >
+ Item with long description
+
+
+);
+
+WithDescriptionBlock.args = {
+ width: '400px',
+};
+
+WithDescriptionBlock.parameters = {
+ docs: {
+ description: {
+ story:
+ 'Demonstrates the `descriptionPlacement="block"` functionality where descriptions are positioned below the entire ItemBase component instead of inside the content area. This is useful for longer descriptions or when you want to maintain a clean main content area.',
+ },
+ },
+};
diff --git a/src/components/content/ItemBase/ItemBase.tsx b/src/components/content/ItemBase/ItemBase.tsx
new file mode 100644
index 000000000..be26f1b68
--- /dev/null
+++ b/src/components/content/ItemBase/ItemBase.tsx
@@ -0,0 +1,578 @@
+import { FocusableRef } from '@react-types/shared';
+import {
+ ComponentProps,
+ ForwardedRef,
+ forwardRef,
+ ReactNode,
+ useMemo,
+ useState,
+} from 'react';
+import { FocusableOptions, OverlayProps, useFocusable } from 'react-aria';
+import { useHotkeys } from 'react-hotkeys-hook';
+
+import {
+ DANGER_CLEAR_STYLES,
+ DANGER_ITEM_STYLES,
+ DANGER_LINK_STYLES,
+ DANGER_NEUTRAL_STYLES,
+ DANGER_OUTLINE_STYLES,
+ DANGER_PRIMARY_STYLES,
+ DANGER_SECONDARY_STYLES,
+ DEFAULT_CLEAR_STYLES,
+ DEFAULT_ITEM_STYLES,
+ DEFAULT_LINK_STYLES,
+ DEFAULT_NEUTRAL_STYLES,
+ DEFAULT_OUTLINE_STYLES,
+ DEFAULT_PRIMARY_STYLES,
+ DEFAULT_SECONDARY_STYLES,
+ ItemVariant,
+ SPECIAL_CLEAR_STYLES,
+ SPECIAL_ITEM_STYLES,
+ SPECIAL_LINK_STYLES,
+ SPECIAL_NEUTRAL_STYLES,
+ SPECIAL_OUTLINE_STYLES,
+ SPECIAL_PRIMARY_STYLES,
+ SPECIAL_SECONDARY_STYLES,
+ SUCCESS_CLEAR_STYLES,
+ SUCCESS_ITEM_STYLES,
+ SUCCESS_LINK_STYLES,
+ SUCCESS_NEUTRAL_STYLES,
+ SUCCESS_OUTLINE_STYLES,
+ SUCCESS_PRIMARY_STYLES,
+ SUCCESS_SECONDARY_STYLES,
+} from '../../../data/item-themes';
+import { CheckIcon } from '../../../icons/CheckIcon';
+import {
+ BaseProps,
+ CONTAINER_STYLES,
+ ContainerStyleProps,
+ Props,
+ Styles,
+ tasty,
+} from '../../../tasty';
+import {
+ mergeProps,
+ useCombinedRefs,
+ useLayoutEffect,
+} from '../../../utils/react';
+import {
+ CubeTooltipProviderProps,
+ TooltipProvider,
+} from '../../overlays/Tooltip/TooltipProvider';
+import { HotKeys } from '../HotKeys';
+
+export interface CubeItemBaseProps extends BaseProps, ContainerStyleProps {
+ icon?: ReactNode | 'checkbox';
+ rightIcon?: ReactNode;
+ prefix?: ReactNode;
+ suffix?: ReactNode;
+ description?: ReactNode;
+ descriptionPlacement?: 'inline' | 'block' | 'auto';
+ isSelected?: boolean;
+ size?:
+ | 'xsmall'
+ | 'small'
+ | 'medium'
+ | 'large'
+ | 'xlarge'
+ | 'inline'
+ | (string & {});
+ type?:
+ | 'item'
+ | 'primary'
+ | 'secondary'
+ | 'outline'
+ | 'neutral'
+ | 'clear'
+ | 'link'
+ | (string & {});
+ theme?: 'default' | 'danger' | 'success' | 'special' | (string & {});
+ variant?: ItemVariant;
+ /** Keyboard shortcut that triggers the element when pressed */
+ hotkeys?: string;
+ /**
+ * Tooltip content and configuration:
+ * - string: simple tooltip text
+ * - true: auto tooltip on overflow (shows children as tooltip when truncated)
+ * - object: advanced configuration with optional auto property
+ */
+ tooltip?:
+ | string
+ | boolean
+ | (Omit & { auto?: boolean });
+ /**
+ * HTML button type to avoid implicit form submission when used as `as="button"`.
+ * Kept separate from visual `type` prop.
+ */
+ buttonType?: 'button' | 'submit' | 'reset';
+ labelProps?: Props;
+ descriptionProps?: Props;
+ keyboardShortcutProps?: Props;
+ /**
+ * @private
+ * Default tooltip placement for the item.
+ * @default "top"
+ */
+ defaultTooltipPlacement?: OverlayProps['placement'];
+}
+
+const DEFAULT_ICON_STYLES: Styles = {
+ display: 'grid',
+ placeItems: 'center',
+ placeContent: 'stretch',
+ aspectRatio: '1 / 1',
+ width: '($size - 2bw)',
+ opacity: {
+ '': 1,
+ 'checkbox & selected': 1,
+ 'checkbox & !selected': 0,
+ 'checkbox & !selected & hovered': 0.4,
+ },
+ gridRow: 'span 2',
+};
+
+const ADDITION_STYLES: Styles = {
+ display: 'grid',
+ flow: 'column',
+ placeItems: 'center',
+ placeContent: 'stretch',
+ gridRow: 'span 2',
+};
+
+const FocusableItemBase = forwardRef(function FocusableItembase(
+ props: ComponentProps & FocusableOptions,
+ ref: FocusableRef,
+) {
+ let { focusableProps } = useFocusable(props, ref as any);
+
+ return ;
+});
+
+const ItemBaseElement = tasty({
+ styles: {
+ display: 'inline-grid',
+ flow: 'column dense',
+ gap: 0,
+ placeItems: 'stretch',
+ placeContent: 'stretch',
+ gridColumns: {
+ '': '1sf max-content max-content',
+ 'with-icon ^ with-prefix': 'max-content 1sf max-content max-content',
+ 'with-icon & with-prefix':
+ 'max-content max-content 1sf max-content max-content',
+ },
+ gridRows: {
+ '': 'auto auto',
+ 'with-description-block': 'auto auto auto',
+ },
+ flexShrink: 0,
+ position: 'relative',
+ padding: 0,
+ margin: 0,
+ radius: true,
+ height: {
+ '': 'min $size',
+ '[data-size="inline"]': 'initial',
+ },
+ border: '#clear',
+ fill: {
+ '': '#dark.0',
+ 'hovered | focused': '#dark.03',
+ selected: '#dark.09',
+ 'selected & (hovered | focused)': '#dark.12',
+ pressed: '#dark.09',
+ '[disabled] | disabled': '#clear',
+ },
+ color: {
+ '': '#dark-02',
+ hovered: '#dark-02',
+ pressed: '#dark',
+ '[disabled] | disabled': '#dark-04',
+ },
+ preset: {
+ '': 't3m',
+ '[data-size="xsmall"]': 't4',
+ '[data-size="xlarge"]': 't2m',
+ },
+ boxSizing: 'border-box',
+ textDecoration: 'none',
+ transition: 'theme',
+ reset: 'button',
+ outlineOffset: 1,
+ cursor: {
+ '': 'default',
+ ':is(button) | :is(a)': 'pointer',
+ '[disabled] | disabled': 'not-allowed',
+ },
+
+ $size: {
+ '': '$size-md',
+ '[data-size="xsmall"]': '$size-xs',
+ '[data-size="small"]': '$size-sm',
+ '[data-size="medium"]': '$size-md',
+ '[data-size="large"]': '$size-lg',
+ '[data-size="xlarge"]': '$size-xl',
+ '[data-size="inline"]': '',
+ },
+ '$inline-padding': {
+ '': 'max($min-inline-padding, (($size - 1lh - 2bw) / 2 + $inline-compensation))',
+ '[data-size="inline"]': 0,
+ },
+ '$block-padding': {
+ '': '.5x',
+ '[data-size="xsmall"] | [data-size="small"]': '.25x',
+ '[data-size="inline"]': 0,
+ },
+ '$inline-compensation': '.5x',
+ '$min-inline-padding': '(1x - 1bw)',
+
+ Icon: DEFAULT_ICON_STYLES,
+
+ RightIcon: DEFAULT_ICON_STYLES,
+
+ Label: {
+ display: 'block',
+ placeSelf: 'center start',
+ boxSizing: 'border-box',
+ placeContent: 'stretch',
+ whiteSpace: 'nowrap',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ maxWidth: '100%',
+ padding: {
+ '': '$block-padding $inline-padding',
+ '(with-icon | with-prefix)':
+ '$block-padding $inline-padding $block-padding 0',
+ '(with-right-icon | with-suffix)':
+ '$block-padding 0 $block-padding $inline-padding',
+ '(with-icon | with-prefix) & (with-right-icon | with-suffix)':
+ '$block-padding 0',
+ 'with-description & !with-description-block':
+ '$block-padding $inline-padding 0 $inline-padding',
+ 'with-description & !with-description-block & (with-icon | with-prefix)':
+ '$block-padding $inline-padding 0 0',
+ 'with-description & !with-description-block & (with-right-icon | with-suffix)':
+ '$block-padding 0 0 $inline-padding',
+ 'with-description & !with-description-block & (with-icon | with-prefix) & (with-right-icon | with-suffix)':
+ '$block-padding 0 0 0',
+ },
+ gridRow: {
+ '': 'span 2',
+ 'with-description': 'span 1',
+ 'with-description-block': 'span 2',
+ },
+ },
+
+ Description: {
+ preset: 't4',
+ color: 'inherit',
+ opacity: 0.75,
+ overflow: 'hidden',
+ whiteSpace: 'nowrap',
+ textOverflow: 'ellipsis',
+ maxWidth: '100%',
+ textAlign: 'left',
+ gridRow: {
+ '': 'span 1',
+ 'with-description-block': '3 / span 1',
+ },
+ gridColumn: {
+ '': 'span 1',
+ 'with-description-block': '1 / -1',
+ },
+ padding: {
+ '': '0 $inline-padding $block-padding $inline-padding',
+ '(with-icon | with-prefix)': '0 $inline-padding $block-padding 0',
+ '(with-right-icon | with-suffix)': '0 0 $block-padding $inline-padding',
+ '(with-icon | with-prefix) & (with-right-icon | with-suffix)':
+ '0 0 $block-padding 0',
+ 'with-description-block':
+ '0 ($inline-padding - $inline-compensation + 1bw) $block-padding ($inline-padding - $inline-compensation + 1bw)',
+ 'with-description-block & !with-icon':
+ '0 ($inline-padding - $inline-compensation + 1bw) $block-padding $inline-padding',
+ 'with-description-block & !with-right-icon':
+ '0 $inline-padding $block-padding ($inline-padding - $inline-compensation + 1bw)',
+ 'with-description-block & !with-right-icon & !with-icon':
+ '0 $inline-padding $block-padding $inline-padding',
+ },
+ },
+
+ Prefix: {
+ ...ADDITION_STYLES,
+ padding: {
+ '': '$inline-padding left',
+ 'with-icon': 0,
+ },
+ },
+
+ Suffix: {
+ ...ADDITION_STYLES,
+ padding: {
+ '': '$inline-padding right',
+ 'with-right-icon': 0,
+ },
+ },
+ },
+ variants: {
+ // Default theme
+ 'default.primary': DEFAULT_PRIMARY_STYLES,
+ 'default.secondary': DEFAULT_SECONDARY_STYLES,
+ 'default.outline': DEFAULT_OUTLINE_STYLES,
+ 'default.neutral': DEFAULT_NEUTRAL_STYLES,
+ 'default.clear': DEFAULT_CLEAR_STYLES,
+ 'default.link': DEFAULT_LINK_STYLES,
+ 'default.item': DEFAULT_ITEM_STYLES,
+ // Danger theme
+ 'danger.primary': DANGER_PRIMARY_STYLES,
+ 'danger.secondary': DANGER_SECONDARY_STYLES,
+ 'danger.outline': DANGER_OUTLINE_STYLES,
+ 'danger.neutral': DANGER_NEUTRAL_STYLES,
+ 'danger.clear': DANGER_CLEAR_STYLES,
+ 'danger.link': DANGER_LINK_STYLES,
+ 'danger.item': DANGER_ITEM_STYLES,
+ // Success theme
+ 'success.primary': SUCCESS_PRIMARY_STYLES,
+ 'success.secondary': SUCCESS_SECONDARY_STYLES,
+ 'success.outline': SUCCESS_OUTLINE_STYLES,
+ 'success.neutral': SUCCESS_NEUTRAL_STYLES,
+ 'success.clear': SUCCESS_CLEAR_STYLES,
+ 'success.link': SUCCESS_LINK_STYLES,
+ 'success.item': SUCCESS_ITEM_STYLES,
+ // Special theme
+ 'special.primary': SPECIAL_PRIMARY_STYLES,
+ 'special.secondary': SPECIAL_SECONDARY_STYLES,
+ 'special.outline': SPECIAL_OUTLINE_STYLES,
+ 'special.neutral': SPECIAL_NEUTRAL_STYLES,
+ 'special.clear': SPECIAL_CLEAR_STYLES,
+ 'special.link': SPECIAL_LINK_STYLES,
+ 'special.item': SPECIAL_ITEM_STYLES,
+ },
+ styleProps: CONTAINER_STYLES,
+});
+
+const ItemBase = (
+ props: CubeItemBaseProps,
+ ref: ForwardedRef,
+) => {
+ let {
+ children,
+ size,
+ type = 'item',
+ theme = 'default',
+ mods,
+ icon,
+ rightIcon,
+ prefix,
+ suffix,
+ description,
+ descriptionPlacement = 'inline',
+ labelProps,
+ descriptionProps,
+ keyboardShortcutProps,
+ styles,
+ buttonType,
+ isSelected,
+ hotkeys,
+ tooltip,
+ isDisabled,
+ defaultTooltipPlacement = 'top',
+ ...rest
+ } = props;
+
+ // Determine if we should show checkbox instead of icon
+ const hasCheckbox = icon === 'checkbox';
+
+ // Build final suffix: custom suffix or HotKeys hint if provided and no explicit suffix
+ const finalSuffix =
+ suffix ??
+ (hotkeys ? (
+
+ {hotkeys}
+
+ ) : undefined);
+
+ // Register global hotkey if provided
+ useHotkeys(
+ typeof hotkeys === 'string' ? hotkeys.toLowerCase() : '',
+ () => {
+ if (!hotkeys) return;
+ if (isDisabled) return;
+ // Simulate a click on the element so all existing handlers run
+ if (ref && typeof ref === 'object' && ref.current) {
+ (ref.current as HTMLElement).click();
+ }
+ },
+ {
+ enableOnContentEditable: true,
+ enabled: !!hotkeys,
+ preventDefault: true,
+ enableOnFormTags: true,
+ },
+ [hotkeys, isDisabled],
+ );
+
+ mods = useMemo(() => {
+ return {
+ 'with-icon': !!icon,
+ 'with-right-icon': !!rightIcon,
+ 'with-prefix': !!prefix,
+ 'with-suffix': !!finalSuffix,
+ 'with-description': !!description,
+ 'with-description-block':
+ !!description && descriptionPlacement === 'block',
+ checkbox: hasCheckbox,
+ selected: isSelected === true,
+ ...mods,
+ };
+ }, [
+ icon,
+ rightIcon,
+ prefix,
+ finalSuffix,
+ description,
+ descriptionPlacement,
+ hasCheckbox,
+ isSelected,
+ mods,
+ ]);
+
+ // Determine if auto tooltip is enabled
+ const isAutoTooltipEnabled = useMemo(() => {
+ if (tooltip === true) return true;
+ if (typeof tooltip === 'object' && tooltip?.auto) return true;
+ return false;
+ }, [tooltip]);
+
+ // Track label overflow for auto tooltip (only when enabled)
+ const mergedLabelRef = useCombinedRefs((labelProps as any)?.ref);
+ const [isLabelOverflowed, setIsLabelOverflowed] = useState(false);
+
+ const checkLabelOverflow = () => {
+ const label = mergedLabelRef.current;
+ if (!label) {
+ setIsLabelOverflowed(false);
+ return;
+ }
+
+ const hasOverflow = label.scrollWidth > label.clientWidth;
+
+ setIsLabelOverflowed(hasOverflow);
+ };
+
+ useLayoutEffect(() => {
+ if (isAutoTooltipEnabled) {
+ checkLabelOverflow();
+ }
+ }, [children, isAutoTooltipEnabled]);
+
+ useLayoutEffect(() => {
+ if (!isAutoTooltipEnabled) return;
+
+ const label = mergedLabelRef.current;
+ if (!label) return;
+
+ // Initial check
+ checkLabelOverflow();
+
+ // const resizeObserver = new ResizeObserver(checkLabelOverflow);
+ // resizeObserver.observe(label);
+
+ // return () => resizeObserver.disconnect();
+ }, [mergedLabelRef.current, isAutoTooltipEnabled]);
+
+ const finalLabelProps = useMemo(() => {
+ return {
+ ...(labelProps || {}),
+ ref: mergedLabelRef,
+ } as Props & { ref?: any };
+ }, [labelProps, mergedLabelRef]);
+
+ const Component = tooltip || isDisabled ? FocusableItemBase : ItemBaseElement;
+
+ const itemElement = (
+
+ {icon && (
+