fix(ItemBase): auto tooltip by default (#799)

Author: tenphi

.changeset/sharp-roses-judge.md

@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Fix tooltip implementation so it doesn't break item navigation.

.changeset/ten-llamas-do.md

@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Use auto tooltip in ItemBase component by default. See documentation to learn more.

.gitignore

@@ -16,4 +16,4 @@ yarn-error.log
 coverage
 size-limit-report/stats.json
 docs-static
-*.spec.md
+*.plan.md

DOCUMENTATION_GUIDELINES.md

@@ -22,7 +22,7 @@ Our component documentation serves multiple purposes:
 Every component documentation file should follow this structure:
 
 ```mdx
-import { Meta, Canvas, Story, Controls } from '@storybook/blocks';
+import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';
 import { ComponentName } from './ComponentName';
 import * as ComponentStories from './ComponentName.stories';
 

src/components/content/ItemBase/ItemBase.docs.mdx

@@ -21,17 +21,17 @@ A foundational component that provides a standardized layout and styling for ite
 
 ---
 
-### Properties
+## Properties
 
 <Controls of={ItemBaseStories.Default} />
 
 ### Base Properties
 
 Supports [Base properties](/BaseProperties)
 
-### Styling Properties
+## Styling
 
-#### styles
+### styles
 
 Customizes the root element of the component.
 
@@ -45,11 +45,11 @@ Customizes the root element of the component.
 
 ### 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`.
+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:
+The `mods` property accepts the following modifiers:
 
 | Modifier | Type | Description |
 |----------|------|-------------|
@@ -138,14 +138,49 @@ The `mods` property accepts the following modifiers you can override:
 </ItemBase>
 ```
 
-### With Auto Tooltip
+### With Tooltip
+
+By default, ItemBase shows an auto tooltip when content overflows.
+
+**Type:** `string | boolean | object`
+
+**Values:**
+- `true` (default) - Shows tooltip with item content when text overflows
+- `false` - Disables tooltip entirely
+- `string` - Shows tooltip with the specified text (always visible, not auto)
+- `object` - Advanced configuration:
+  - `title?: string` - Custom tooltip text (when provided, always shows tooltip unless `auto: true`)
+  - `auto?: boolean` - Enable/disable auto overflow behavior (defaults to `true` when no `title` is provided)
+  - `placement?: string` - Tooltip position (top, bottom, left, right, etc.)
+  - Plus other [TooltipProvider props](/docs/overlays-tooltip--docs)
 
 ```jsx
+{/* Auto tooltip on overflow (default) */}
+<ItemBase style={{ width: '200px' }}>
+  This is a very long text that will show a tooltip when overflowed
+</ItemBase>
+
+{/* Disable tooltip */}
+<ItemBase tooltip={false} style={{ width: '200px' }}>
+  This text will be truncated without a tooltip
+</ItemBase>
+
+{/* Always show custom tooltip */}
+<ItemBase tooltip={{ title: 'Custom tooltip text' }}>
+  Hover to see custom tooltip
+</ItemBase>
+
+{/* Auto tooltip with custom placement */}
+<ItemBase tooltip={{ placement: 'right' }} style={{ width: '200px' }}>
+  Long text with tooltip on the right when overflowed
+</ItemBase>
+
+{/* Custom tooltip only on overflow */}
 <ItemBase 
-  tooltip={true}
+  tooltip={{ title: 'Custom overflow tooltip', auto: true }}
   style={{ width: '200px' }}
 >
-  This is a very long text that will show a tooltip when overflowed
+  This shows custom tooltip only when text overflows
 </ItemBase>
 ```
 
@@ -178,10 +213,10 @@ The `mods` property accepts the following modifiers you can override:
    <ItemBase icon={<IconUser />}>User Profile</ItemBase>
    ```
 
-2. **Do**: Provide tooltips for items that might overflow
+2. **Do**: Use descriptions to provide additional context
    ```jsx
-   <ItemBase tooltip={true} style={{ width: '200px' }}>
-     Long item name that might be truncated
+   <ItemBase icon={<IconFile />} description="Last edited 2 hours ago">
+     Document.pdf
    </ItemBase>
    ```
 

src/components/content/ItemBase/ItemBase.stories.tsx

@@ -1,4 +1,5 @@
 import { IconCoin, IconSettings, IconUser } from '@tabler/icons-react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
 
 import { DirectionIcon } from '../../../icons';
 import { baseProps } from '../../../stories/lists/baseProps';
@@ -1067,3 +1068,40 @@ WithDescriptionBlock.parameters = {
     },
   },
 };
+
+const timeout = (ms: number) =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+export const WithAutoTooltip: StoryFn<CubeItemBaseProps> = () => (
+  <ItemBase
+    qa="auto-tooltip-item"
+    icon={<IconUser />}
+    style={{ width: '200px' }}
+    tooltip={{ delay: 0 }}
+  >
+    This is a very long label that will overflow and trigger the auto tooltip
+  </ItemBase>
+);
+
+WithAutoTooltip.play = async ({ canvasElement }) => {
+  const canvas = within(canvasElement);
+
+  await timeout(250);
+
+  const item = await canvas.findByTestId('auto-tooltip-item');
+  // this is a weird hack that makes tooltip working properly on page load
+  await userEvent.unhover(item);
+  await userEvent.hover(item);
+
+  // Wait for the tooltip to appear - getByRole will throw if not found
+  await waitFor(() => expect(canvas.getByRole('tooltip')).toBeVisible());
+};
+
+WithAutoTooltip.parameters = {
+  docs: {
+    description: {
+      story:
+        'Demonstrates the auto tooltip feature that automatically shows a tooltip when the label text overflows. The tooltip is triggered on hover and displays the full text content.',
+    },
+  },
+};