feat(Item): show actions on hover (#880)

Author: tenphi

.changeset/bright-rabbits-walk.md

@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Allow text wrapping in labels.

.changeset/filter-picker-render-summary-no-selection.md

@@ -0,0 +1,6 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Fix FilterPicker `renderSummary` to be evaluated regardless of selection state. The custom summary renderer and `renderSummary={false}` now work correctly even when no items are selected, providing consistent control over trigger content display.
+

.changeset/item-show-actions-on-hover.md

@@ -0,0 +1,6 @@
+---
+"@cube-dev/ui-kit": minor
+---
+
+Add `showActionsOnHover` prop to Item component. When enabled, actions are hidden by default and revealed smoothly on hover, focus, or focus-within states using opacity transitions. This provides a cleaner interface while keeping actions easily accessible without content shifting.
+

.changeset/text-placeholder-variant.md

@@ -0,0 +1,7 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Add `Text.Placeholder` variant with disabled opacity styling. This new text variant is useful for displaying placeholder content with reduced visual emphasis.
+
+

.cursor/rules/documentation.mdc

@@ -1,30 +1,18 @@
 ---
-description: When updating the component documentation file *.docs.mdx
+description: When creating or updating the component documentation file *.docs.mdx
 alwaysApply: false
 ---
 # Component Documentation Guidelines
 
-This guide outlines the standards and structure for documenting components in the Cube UI Kit. Following these guidelines ensures consistency, clarity, and comprehensive coverage of component features.
-
-## Overview
-
-Our component documentation serves multiple purposes:
-- Provides clear usage instructions for developers
-- Ensures accessibility best practices are communicated
-- Documents styling capabilities through the `tasty` style system
-- Maintains consistency across all component documentation
-
 ## Key Principles
 
-1. **Accessibility First**: Components use React Aria Hooks and documentation should emphasize accessibility features
-2. **Style System Integration**: Document `tasty` styling capabilities thoroughly
-3. **Practical Examples**: Include real-world usage examples, not just API references
-4. **Clear Structure**: Follow the prescribed documentation structure for consistency
+1. **Accessibility First**: Document React Aria features and keyboard/screen reader support
+2. **Style System**: Document `tasty` styling capabilities (sub-elements, modifiers, style props)
+3. **Code Examples Required**: **CRITICAL - Stories alone are NOT code examples. Always include actual JSX code snippets showing usage.**
+4. **Clear Structure**: Follow the prescribed structure below
 
 ## Documentation Structure
 
-Every component documentation file should follow this structure:
-
 ```mdx
 import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';
 import { ComponentName } from './ComponentName';
@@ -104,6 +92,8 @@ The `mods` property accepts the following modifiers you can override:
 
 ## Examples
 
+**IMPORTANT: Stories are for interactive demos. You MUST also provide JSX code snippets in this section.**
+
 ### Basic Usage
 
 ```jsx
@@ -112,6 +102,8 @@ The `mods` property accepts the following modifiers you can override:
 
 ### [Additional Examples as needed]
 
+**Each example must show actual code, not just reference a story.**
+
 ## Accessibility
 
 ### Keyboard Navigation
@@ -163,84 +155,55 @@ This component supports all [Field properties](/field-properties.md) when used w
 - [RelatedComponent2](/components/RelatedComponent2) - Complementary component
 ```
 
-## Specific Guidelines
-
-### 1. Component Description
+## Guidelines
 
-- Start with a clear, concise description of what the component is
-- Follow with scenarios where the component should be used
-- Avoid technical implementation details in the introduction
-
-### 2. Properties Documentation
-
-#### Base Properties
-- If the component uses `filterBaseProps`, don't list base properties individually
-- Instead, include the link: `Supports [Base properties](/base-properties.md)`
-- Exception: Always document the `qa` property if it has special behavior
-
-#### Styling Properties
-- Document each `styles` or `*Styles` property separately
-- For each styling property, list all available tasty sub-elements with descriptions. Count only those sub-elements that are mentioned in tasty styles in the root element inside component and can be overrided by passing an object with a specific key (sub-element name) to `styles` property
-- Format: `ElementName` - Description of what this element represents
-
-#### Style Properties
-- List all properties that can be used for direct styling (e.g., `width`, `height`, `padding`)
-- These are properties that map to `tasty` styles without using the `styles` prop
-- Use `src/tasty/styles/list.ts` file to understand how it works.
+### Properties
 
-#### React Aria Properties
-- Document all React Aria properties with clear descriptions
-- It's acceptable to rewrite React Aria descriptions for clarity
-- Focus on practical usage rather than technical implementation
+- **Props List**: Use `<Controls of={componentStories.Default} />` - DO NOT manually list props if Controls is used
+- **Base Properties**: Link to `/base-properties.md` instead of listing (unless `qa` has special behavior)
+- **Styling Properties**: Document `styles`/`*Styles` props. List sub-elements that can be overridden (check component's tasty styles)
+- **Style Properties**: List direct styling props (`width`, `height`, etc.) - see `src/tasty/styles/list.ts`
+- **React Aria Properties**: Only document if adding clarifications beyond what Controls shows
 
-### 3. Examples
+### Examples
 
-- Provide practical, real-world examples written in `jsx` code
-- Avoid styling examples unless it demonstrates essential capabilities
-- Each example should have a clear purpose and title
-- Do not use Storybook's Canvas and Story components for interactive examples
-- Each story should describe a usage case
-- The more sophisticated component, the more stories we need to cover all cases
+- **CRITICAL**: Must include JSX code snippets, not just story references
+- Provide real-world examples with clear purpose
+- Avoid pure styling examples unless demonstrating essential capabilities
+- More sophisticated components need more examples to cover all cases
 
-### 4. Modifiers
+### Modifiers
 
-- Document all available modifiers that can be passed via the `mods` property
-- Explain how each modifier affects the component's appearance or behavior
-- Include any modifier combinations that have special behavior
+- Document all `mods` property values
+- Explain effects on appearance/behavior
+- Note special modifier combinations
 
-### 5. Accessibility Section
+### Accessibility
 
-- Include keyboard navigation patterns
-- Document screen reader behavior
-- List relevant ARIA properties and their usage
-- Provide guidance on ensuring accessible implementations
+- Keyboard navigation patterns
+- Screen reader behavior
+- Relevant ARIA properties
+- Accessible implementation guidance
 
-### 6. Form Integration
+### Form Integration
 
-For input components (TextInput, Select, DatePicker, etc.):
-- Don't duplicate field property documentation
-- Include: "This component supports all [Field properties](/field-properties.md) when used within a Form."
+For input components: "This component supports all [Field properties](/field-properties.md) when used within a Form."
 
-### 7. File Naming and Location
+### File Naming
 
-- Documentation files use `.docs.mdx` extension
-- Place in the same directory as the component
-- Naming convention: `ComponentName.tsx` → `ComponentName.docs.mdx`
+`ComponentName.tsx` → `ComponentName.docs.mdx` in same directory
 
 ## Review Checklist
 
-Before submitting component documentation, ensure:
-
-- [ ] Follows the prescribed structure
-- [ ] Includes practical examples with Storybook Stories
-- [ ] Documents all styling properties and sub-elements
-- [ ] Lists all modifiers with descriptions
-- [ ] Includes accessibility information
-- [ ] Contains best practices section
-- [ ] Has "Suggested Improvements" section
-- [ ] Uses correct file naming and location
-- [ ] All links use provided placeholder format
-- [ ] Style properties are documented separately from styling properties
-- [ ] Form integration mentioned for input components
+- [ ] **JSX code snippets provided (not just stories)**
+- [ ] **No manual props list if using `<Controls />`**
+- [ ] Follows prescribed structure
+- [ ] Styling properties and sub-elements documented
+- [ ] Modifiers listed with descriptions
+- [ ] Accessibility section complete
+- [ ] Best practices included
+- [ ] Suggested improvements section
+- [ ] Style props vs styling props separated
+- [ ] Form integration noted (input components)
 - [ ] Base properties linked, not listed (except `qa`)
-- [ ] Tabler (`@tabler/icons-react`) or UI Kit icons are used in examples
+- [ ] Icons from `@tabler/icons-react` or `/src/icons`

.cursor/rules/storybook.mdc

@@ -1,13 +1,13 @@
 ---
-description: When updating storybook files and documentatino files *.stories.tsx, *.docs.mdx
+description: When creating or updating storybook files and documentatino files *.stories.tsx, *.docs.mdx
 alwaysApply: false
 ---
 ## Imports
 
 ### Stories Files (.stories.tsx)
 - Import types: `import type { Meta, StoryObj } from '@storybook/react-vite';`
 - Import `StoryFn` for custom template functions
-- For interactive tests: `import { userEvent, within } from 'storybook/test';` (NOT from `@testing-library/react`)
+- For interactive tests: `import { userEvent, within } from '@storybook/test';` (NOT from `@testing-library/react`)
 
 ### Documentation Files (.docs.mdx)
 - `import { Meta, Canvas, Story, Controls } from '@storybook/addon-docs/blocks';`
@@ -103,7 +103,7 @@ export const Interactive: StoryObj = {
 };
 ```
 
-**Important:** Always import `userEvent` and `within` from `'storybook/test'` in story files. This ensures they respect Storybook's configuration (e.g., `testIdAttribute: 'data-qa'` set in `.storybook/preview.jsx`). Do NOT use `@testing-library/react` imports in stories.
+**Important:** Always import `userEvent` and `within` from `'@storybook/test'` in story files. This ensures they respect Storybook's configuration (e.g., `testIdAttribute: 'data-qa'` set in `.storybook/preview.jsx`). Do NOT use `@testing-library/react` imports in stories.
 
 ## MDX Documentation Structure
 

.storybook/preview.jsx

@@ -1,6 +1,6 @@
+import { configure } from '@storybook/test';
 import isChromatic from 'chromatic/isChromatic';
 import { config } from 'react-transition-group';
-import { configure } from 'storybook/test';
 
 import { Root } from '../src';
 

package.json

@@ -75,6 +75,7 @@
     "@react-stately/utils": "^3.10.8",
     "@react-types/shared": "^3.31.0",
     "@sparticuz/chromium": "^137.0.1",
+    "@storybook/test": "^8.6.14",
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@trivago/prettier-plugin-sort-imports": "^5.2.2",