@cube-dev/ui-kit 0.121.0 → 0.121.2

package/docs/components/content/Paragraph.md

@@ -0,0 +1,32 @@
+# Paragraph
+
+A block-level text component for body content. Renders as `<p>` and extends `Text` with paragraph-specific defaults.
+
+## When to Use
+
+- Body text and descriptions
+- Multi-line content that should flow as paragraphs
+
+## Properties
+
+Extends Text properties including `preset`, `color`, `weight`, `transform`, `ellipsis`, `nowrap`.
+
+### Style Defaults
+
+- `display` — `block`
+- `preset` — `p3`
+- `color` — `#dark-02`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Paragraph>This is a paragraph of body text.</Paragraph>
+
+<Paragraph preset="p2" color="#minor">
+  Secondary paragraph with custom styling.
+</Paragraph>
+```

package/docs/components/content/Placeholder.md

@@ -0,0 +1,37 @@
+# Placeholder
+
+A loading placeholder with optional shimmer animation. Used for skeleton-style loading states.
+
+## When to Use
+
+- Content loading states
+- Skeleton screens
+- Placeholder for images or text while loading
+
+## Properties
+
+- **`size`** `string` (default: `'2x'`) — Placeholder height
+- **`circle`** `boolean` — Circular shape with `aspect-ratio: 1/1` (e.g. for avatars)
+- **`isStatic`** `boolean` — Disable shimmer animation
+
+### Style Defaults
+
+- `display` — `block`
+- `fill` — `#dark.10`
+- `height` — `2x`
+- `radius` — `1r` (switches to `round` when `circle`)
+- `opacity` — `.35`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Placeholder width="200px" height="24px" />
+
+<Placeholder circle size="4x" />
+
+<Placeholder isStatic width="100%" />
+```

package/docs/components/content/PrismCode.md

@@ -0,0 +1,36 @@
+# PrismCode
+
+Syntax-highlighted code block using Prism. Supports multiple languages.
+
+## When to Use
+
+- Documentation code examples
+- Displaying code in UI
+- Technical content with syntax highlighting
+
+## Properties
+
+- **`code`** `string` (default: `''`) — The code snippet to highlight
+- **`language`** `string` (default: `'javascript'`) — Language for syntax highlighting (`javascript`, `typescript`, `json`, `yaml`, `bash`, `sql`, `css`, `html`, etc.)
+
+### Style Defaults
+
+- `margin` — `0`
+- `padding` — `0`
+- `overflow` — `auto`
+- `scrollbar` — `styled`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<PrismCode code="const x = 1;" language="javascript" />
+
+<PrismCode
+  code={'function hello() {\n  return "world";\n}'}
+  language="typescript"
+/>
+```

package/docs/components/content/PrismDiffCode.md

@@ -0,0 +1,29 @@
+# PrismDiffCode
+
+Displays a diff view of two code snippets with syntax highlighting. Highlights added and removed lines.
+
+## When to Use
+
+- Showing code changes
+- Before/after comparisons
+- Code review displays
+
+## Properties
+
+- **`original`** `string` (required) — Original code
+- **`modified`** `string` (required) — Modified code
+- **`language`** `string` — Syntax highlighting language
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<PrismDiffCode
+  original="const x = 1;"
+  modified="const x = 2;"
+  language="javascript"
+/>
+```

package/docs/components/content/Result.md

@@ -0,0 +1,46 @@
+# Result
+
+An empty state or result display with icon, title, and optional content. Supports status presets with built-in icons.
+
+## When to Use
+
+- Empty states (no data, no results)
+- Success/error feedback after actions
+- 404, 403, 500 error pages
+- Informational messages
+
+## Properties
+
+- **`status`** `'success' | 'error' | 'info' | 'warning' | 404 | 403 | 500` (default: `'info'`) — Predefined status with corresponding icon
+- **`title`** `ReactNode` — Main title text
+- **`subtitle`** `ReactNode` — Secondary text below title
+- **`icon`** `ReactNode` — Custom icon (overrides status icon)
+- **`isCompact`** `boolean` — Compact horizontal layout
+
+### Style Defaults
+
+- `display` — `flex` (switches to `grid` when `isCompact`)
+- `flow` — `column`
+- `placeContent` — `center` (switches to `start` when `isCompact`)
+- `placeItems` — `center` (switches to `start` when `isCompact`)
+- `gap` — `3x` (switches to `2x 1x` when `isCompact`)
+- `padding` — `6x 4x` (switches to `0` when `isCompact`)
+- `textAlign` — `center` (switches to `left` when `isCompact`)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Result status="success" title="Saved" subtitle="Your changes have been saved." />
+
+<Result status="error" title="Something went wrong" subtitle="Please try again." />
+
+<Result status={404} title="Page not found" />
+
+<Result status="info" title="No items" subtitle="Add your first item to get started.">
+  <Button>Add Item</Button>
+</Result>
+```

package/docs/components/content/Skeleton.md

@@ -0,0 +1,35 @@
+# Skeleton
+
+A skeleton loading indicator with preset layouts. Composes `Placeholder` components to mimic content structure.
+
+## When to Use
+
+- Loading states for complex layouts
+- Progressive content loading
+- Replacing spinners with content-aware placeholders
+
+## Properties
+
+- **`layout`** `'page' | 'content' | 'topbar' | 'menu' | 'stats' | 'tabs' | 'table' | 'chart'` (default: `'page'`) — Preset layout pattern
+- **`lines`** `number` (default: `5`) — Number of placeholder lines (for page, content, menu, tabs layouts)
+- **`rows`** `number` (default: `5`) — Number of table rows (for table layout)
+- **`columns`** `number` (default: `5`) — Number of columns (for table and chart layouts)
+- **`tabs`** `number` (default: `3`) — Number of tabs (for tabs layout)
+- **`cards`** `number` (default: `3`) — Number of stat cards (for stats layout)
+- **`isStatic`** `boolean` (default: `false`) — Disable shimmer animation
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Skeleton layout="content" lines={5} />
+
+<Skeleton layout="page" />
+
+<Skeleton layout="table" rows={5} columns={4} />
+
+<Skeleton layout="chart" columns={8} />
+```

package/docs/components/content/Tag.md

@@ -0,0 +1,165 @@
+# Tag
+
+Tags are compact, inline elements used to label, categorize, or organize items. They provide visual metadata and can optionally be dismissed by users.
+
+## When to Use
+
+- **Categorization**: Label items with topics, categories, or types
+- **Filtering**: Display active filters or search criteria
+- **Status**: Show status indicators or states
+- **User Input**: Display selected items in multi-select scenarios
+- **Metadata**: Show additional information about content
+
+## When Not to Use
+
+- **Navigation**: Use `Button` or `Link` for navigation actions
+- **Actions**: Use `Button` for primary or secondary actions
+- **Long text**: Tags should contain short, scannable text
+- **Complex content**: For multi-line or detailed content, use `Badge` or `Card`
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** `ReactNode` — Tag content
+- **`icon`** `ReactNode` — Icon to display before the tag content
+- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special' | 'disabled'` (default: `default`) — Visual theme of the tag
+- **`type`** `string` — Deprecated: Use theme instead
+- **`size`** `string` (default: `inline`) — Size of the tag
+- **`isClosable`** `boolean` (default: `false`) — Whether the tag can be closed
+- **`onClose`** `() => void` — Handler called when close button is pressed
+- **`closeButtonStyles`** `Styles` — Custom styles for the close button
+
+### Base Properties
+
+Tag 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
+
+Tags support multiple themes for different semantic meanings:
+
+Available themes:
+- **Default**: Neutral, for general categorization
+- **Warning**: Yellow/amber, caution or attention needed
+- **Note**: Violet, informational content
+- **Success**: Green, positive states or completed actions
+- **Danger**: Red, errors or destructive actions
+- **Special**: Purple, highlighted or premium features
+- **Disabled**: Gray, inactive or unavailable items
+
+### With Icons
+
+Icons can be added to provide additional visual context:
+
+```jsx
+import { IconCoin } from '@tabler/icons-react';
+
+<Tag icon={<IconCoin />}>With Icon</Tag>
+```
+
+### Closable Tags
+
+Tags can be made dismissible with the `isClosable` prop:
+
+All themes support the closable variant:
+
+```jsx
+<Tag isClosable onClose={() => console.log('Tag closed')}>
+  Closable Tag
+</Tag>
+```
+
+### Closable with Icons
+
+Combine icons with closable functionality:
+
+### Sizes
+
+Tags support multiple sizes inherited from the Item component:
+
+- **inline** (default): Compact size that fits inline with text
+- **xsmall**: Extra small button-like size
+- **small**: Small button-like size
+- **medium**: Medium button-like size
+- **large**: Large button-like size
+
+### Custom Styles
+
+Apply custom styling using the `styles` prop:
+
+```jsx
+<Tag
+  styles={{
+    fill: '#purple.10',
+    color: '#purple',
+    border: '#purple.30',
+  }}
+>
+  Custom Tag
+</Tag>
+```
+
+## Best Practices
+
+### Content
+
+- Keep tag text short and scannable (1-3 words ideal)
+- Use sentence case for tag labels
+- Use consistent terminology across similar tags
+- Avoid punctuation unless necessary
+
+### Interaction
+
+- Only make tags closable when users can dismiss them
+- Provide feedback when a tag is closed (e.g., update list)
+- Consider confirmation for destructive closures
+- Ensure close buttons are accessible via keyboard
+
+### Visual Design
+
+- Use theme consistently for semantic meaning
+- Don't mix too many themes in the same group
+- Maintain adequate spacing between tags
+- Consider wrapping behavior for multiple tags
+
+### Accessibility
+
+- Tags have `role="status"` for screen readers
+- Close buttons include `aria-label="Close"`
+- All themes maintain sufficient color contrast
+- Keyboard navigation is fully supported via Item
+
+## Related Components
+
+- **Badge**: For numerical indicators or counts
+- **Chip**: For interactive selection chips
+- **Button**: For actions and navigation
+- **Item**: Base component that Tag extends from
+
+## Migration from Legacy Tag
+
+The Tag component now extends from `Item`, providing enhanced functionality:
+
+```jsx
+// Old API still works
+<Tag type="success">Legacy</Tag>
+
+// New API (preferred)
+<Tag theme="success">Modern</Tag>
+
+// New features from Item
+<Tag tooltip="Additional info" isDisabled>
+  With Tooltip
+</Tag>
+```
+
+The `type` prop is deprecated in favor of `theme` for consistency with other components.
+

package/docs/components/content/Text.md

@@ -0,0 +1,54 @@
+# Text
+
+A flexible text component for inline or block text. Renders as `<span>` by default with support for typography presets, ellipsis, and semantic variants.
+
+## When to Use
+
+- Inline text within other components
+- Labels, captions, and short text content
+- Text that needs ellipsis truncation or custom typography
+
+## Properties
+
+- **`as`** `TagName` (default: `'span'`) — HTML element to render
+- **`monospace`** `boolean` — Use monospace font
+- **`ellipsis`** `boolean` — Truncate overflow with ellipsis (sets `display: block`, `nowrap`, `overflow: hidden`)
+- **`nowrap`** `boolean` — Prevent text wrapping
+- **`block`** `boolean` — Display as block element
+- **`italic`** `string` — Font style (maps to `fontStyle`)
+- **`weight`** `string | number` — Font weight (maps to `fontWeight`)
+- **`transform`** `string` — Text transform (maps to `textTransform`)
+
+### Style Defaults
+
+- `display` — `inline` (switches to `block` when `ellipsis` or `block`)
+- `margin` — `0`
+- `padding` — `0`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+### Variants
+
+- `Text.Minor` — Muted/secondary text color
+- `Text.Danger` — Error or destructive text
+- `Text.Success` — Success or positive text
+- `Text.Strong` — Bold emphasis
+- `Text.Emphasis` — Italic emphasis
+- `Text.Placeholder` — Placeholder-style text
+- `Text.Highlight` — Highlighted text (mark element)
+
+## Examples
+
+```jsx
+<Text>Inline text</Text>
+
+<Text ellipsis style={{ maxWidth: 200 }}>
+  Long text that will be truncated with ellipsis
+</Text>
+
+<Text.Minor>Secondary information</Text.Minor>
+
+<Text.Danger>Error message</Text.Danger>
+```

package/docs/components/content/TextItem.md

@@ -0,0 +1,217 @@
+# TextItem
+
+A text component with built-in overflow handling and auto-tooltips. When text is truncated, a tooltip automatically appears on hover showing the full content. Also supports text highlighting for search results.
+
+## When to Use
+
+- Display text that may overflow its container with automatic tooltip fallback
+- Show search results with highlighted matching terms
+- Labels or descriptions in constrained layouts (sidebars, tables, lists)
+- Any text that needs ellipsis truncation with accessible full-text disclosure
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** `ReactNode` — Text content
+- **`highlight`** `string` — String to highlight within children
+- **`highlightCaseSensitive`** `boolean` (default: `false`) — Whether highlight matching is case-sensitive
+- **`tooltip`** `string | boolean | TooltipProviderProps` (default: `true`) — Tooltip configuration. Use true for auto tooltip on overflow, string for custom tooltip text.
+- **`tooltipPlacement`** `Placement` (default: `top`) — Default tooltip placement
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md) and all Text properties including `preset`, `color`, `weight`, `transform`, `ellipsis`, `nowrap`.
+
+### Styling Properties
+
+#### styles
+
+Customizes the root text element. Inherits all styling capabilities from the Text component.
+
+#### highlightStyles
+
+Customizes the appearance of highlighted text portions.
+
+### Style Properties
+
+These properties allow direct style application: `preset`, `color`, `weight`, `transform`, and all standard text/color style props.
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<TextItem>Simple text content</TextItem>
+```
+
+### Overflow with Auto-Tooltip
+
+When text overflows its container, hovering reveals a tooltip with the full content:
+
+```jsx
+<Block width="200px">
+  <TextItem>
+    This is a very long text that will be truncated with ellipsis
+    and show a tooltip on hover
+  </TextItem>
+</Block>
+```
+
+### Text Highlighting
+
+Highlight matching text within the content - useful for search results:
+
+```jsx
+<TextItem highlight="search">
+  Search results with highlighted text matching your query
+</TextItem>
+```
+
+### Custom Highlight Styles
+
+Customize the appearance of highlighted text with `highlightStyles`:
+
+```jsx
+<TextItem 
+  highlight="important" 
+  highlightStyles={{ fill: '#purple.20', color: '#purple' }}
+>
+  This important text has custom highlight styling
+</TextItem>
+```
+
+### Case-Sensitive Highlighting
+
+By default, highlighting is case-insensitive. Enable case-sensitive matching with `highlightCaseSensitive`:
+
+```jsx
+{/* Case-insensitive (default) - matches TEXT, text, Text */}
+<TextItem highlight="text">
+  TEXT and text and Text are all highlighted
+</TextItem>
+
+{/* Case-sensitive - only matches exact case */}
+<TextItem highlight="text" highlightCaseSensitive>
+  TEXT and text and Text - only lowercase is highlighted
+</TextItem>
+```
+
+### Multiple Highlights
+
+All occurrences of the highlight string are highlighted:
+
+```jsx
+<TextItem highlight="fox">
+  The quick brown fox jumps over the lazy fox
+</TextItem>
+```
+
+### Custom Tooltip
+
+Override the auto-tooltip with custom content:
+
+```jsx
+<TextItem tooltip="Custom tooltip text that differs from the content">
+  Short text
+</TextItem>
+```
+
+### Disabled Tooltip
+
+Disable the tooltip entirely:
+
+```jsx
+<TextItem tooltip={false}>
+  This text will truncate but won't show a tooltip
+</TextItem>
+```
+
+### Tooltip Placement
+
+Control where the tooltip appears:
+
+```jsx
+<TextItem tooltipPlacement="bottom">
+  Tooltip appears below on hover
+</TextItem>
+```
+
+### With Text Styles
+
+Apply typography and color styles:
+
+```jsx
+<TextItem preset="h3">Heading style</TextItem>
+<TextItem preset="t2" color="#purple">Colored text</TextItem>
+<TextItem weight="bold">Bold text</TextItem>
+```
+
+### Search Results List
+
+Common pattern for filterable lists with highlighted search terms:
+
+```jsx
+const items = ['Apple', 'Application', 'Banana', 'Apply', 'Grape'];
+const searchTerm = 'app';
+
+<Space flow="column" gap="0.5x">
+  {items.map((item) => (
+    <TextItem key={item} highlight={searchTerm}>
+      {item}
+    </TextItem>
+  ))}
+</Space>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to the component (when tooltip is enabled)
+- Tooltip content is accessible via focus, not just hover
+
+### Screen Reader Support
+
+- Truncated text is fully accessible via tooltip
+- Highlighted text uses semantic `<mark>` element for screen reader announcement
+- Tooltip content is announced when triggered
+
+### ARIA Properties
+
+- Tooltip trigger automatically manages `aria-describedby` for tooltip association
+
+## Best Practices
+
+1. **Do**: Use for text that may exceed container width
+   ```jsx
+   <Block width="200px">
+     <TextItem>Long filename-that-might-overflow.tsx</TextItem>
+   </Block>
+   ```
+
+2. **Do**: Provide meaningful highlight terms for search
+   ```jsx
+   <TextItem highlight={userSearchQuery}>{result.title}</TextItem>
+   ```
+
+3. **Don't**: Use for multi-line text (this component enforces single-line with ellipsis)
+   ```jsx
+   {/* Use Text component instead for multi-line content */}
+   <Text>Multi-line paragraph content...</Text>
+   ```
+
+4. **Don't**: Disable tooltips for important truncated content
+   ```jsx
+   {/* Users won't be able to see the full text */}
+   <TextItem tooltip={false}>Important information that gets cut off...</TextItem>
+   ```
+
+## Related Components
+
+- Text - Base text component without overflow handling
+- [Item](./Item.md) - Interactive list item with similar overflow behavior
+- [TooltipProvider](../overlays/Tooltip.md) - Standalone tooltip wrapper
+

package/docs/components/content/Title.md

@@ -0,0 +1,45 @@
+# Title
+
+A heading component for section titles. Renders as `h1`–`h6` based on the `level` prop.
+
+## When to Use
+
+- Page and section headings
+- Hierarchical content structure
+- Accessible heading levels for document outline
+
+## Properties
+
+- **`level`** `1 | 2 | 3 | 4 | 5 | 6` (default: `1`) — Heading level (maps to `h1`–`h6` tag and corresponding preset `h1`–`h6`)
+- **`ellipsis`** `boolean` — Truncate overflow with ellipsis
+- **`nowrap`** `boolean` — Prevent text wrapping
+
+### Style Defaults
+
+- `display` — `block`
+- `color` — `#dark`
+- `margin` — `0`
+- `gridArea` — `title`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+### Variants
+
+- `Title.Danger` — Error or destructive heading
+- `Title.Success` — Success or positive heading
+
+## Examples
+
+```jsx
+<Title level={1}>Page Title</Title>
+
+<Title level={2}>Section Heading</Title>
+
+<Title level={3} ellipsis>
+  Long heading that truncates
+</Title>
+
+<Title.Danger level={4}>Error State</Title.Danger>
+```