@cube-dev/ui-kit 0.120.1 → 0.121.1

package/docs/RenderCache.md

@@ -0,0 +1,177 @@
+# RenderCache
+
+RenderCache is a performance optimization component that caches rendered React elements and only re-renders specific items when needed. It's useful for lists where most items remain unchanged but you need fine-grained control over which items to re-render.
+
+## When to Use
+
+- When rendering lists where only specific items need to re-render based on state changes
+- When child components are expensive to render and don't need to update on every parent re-render
+- When you want more control than React.memo provides, with explicit per-item cache invalidation
+- When building complex UI where selective re-rendering improves performance significantly
+
+## Component
+
+---
+
+### Properties
+
+- **`items`** `T[]` — Array of items to render
+- **`renderKeys`** `Array<string | number>` — Array of keys that should trigger re-render. Only items with keys in this array will be re-rendered
+- **`getKey`** `(item: T) => string | number` — Function that extracts a unique key from each item
+- **`children`** `(item: T) => ReactElement` — Render function that takes an item and returns a React element
+
+### Property Details
+
+- **items**: Array of items to render
+- **renderKeys**: Array of keys that should trigger re-render. Only items with keys in this array will be re-rendered
+- **getKey**: Function that extracts a unique key from each item
+- **children**: Render function that takes an item and returns a React element
+
+### Base Properties
+
+This is a headless component and does not support base properties.
+
+## How It Works
+
+The component maintains an internal cache of rendered elements. When rendering:
+
+1. For each item, it checks if the item's key is in renderKeys
+2. If the key is in renderKeys or the item hasn't been rendered before, it calls the children function to render/re-render
+3. Otherwise, it returns the cached element from the previous render
+4. It automatically cleans up cache entries for items that are no longer in the list
+
+## Examples
+
+### Basic Usage
+
+```jsx
+import { RenderCache } from '@cube-dev/ui-kit';
+
+const items = [
+  { id: 1, name: 'Item 1' },
+  { id: 2, name: 'Item 2' },
+  { id: 3, name: 'Item 3' },
+];
+
+const [selectedId, setSelectedId] = useState(1);
+
+<RenderCache
+  items={items}
+  renderKeys={[selectedId]}
+  getKey={(item) => item.id}
+>
+  {(item) => <ExpensiveItem item={item} isSelected={item.id === selectedId} />}
+</RenderCache>
+```
+
+### With List of Expensive Components
+
+```jsx
+import { RenderCache } from '@cube-dev/ui-kit';
+
+function ExpensiveListItem({ item, isActive }) {
+  // Complex rendering logic
+  return <div className={isActive ? 'active' : ''}>{item.name}</div>;
+}
+
+const [activeId, setActiveId] = useState(1);
+
+<RenderCache
+  items={data}
+  renderKeys={[activeId]}
+  getKey={(item) => item.id}
+>
+  {(item) => (
+    <ExpensiveListItem 
+      item={item} 
+      isActive={item.id === activeId}
+    />
+  )}
+</RenderCache>
+```
+
+## Performance Considerations
+
+- **Cache management**: The component uses useRef to maintain the cache across renders, avoiding unnecessary re-allocations
+- **Automatic cleanup**: Removes cached entries for items no longer in the list to prevent memory leaks
+- **Selective invalidation**: Only items with keys in renderKeys are re-rendered, others use cached elements
+- **Best for expensive renders**: Most effective when child components have significant render cost
+
+## Best Practices
+
+1. **Use stable keys**: Ensure getKey returns consistent keys for the same items across renders
+   ```jsx
+   // Good: Using stable IDs
+   <RenderCache
+     items={items}
+     getKey={(item) => item.id}
+     renderKeys={[selectedId]}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   
+   // Bad: Using indices (unstable when list changes)
+   <RenderCache
+     items={items}
+     getKey={(item, index) => index}
+     renderKeys={[selectedIndex]}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   ```
+
+2. **Minimize renderKeys**: Only include keys that truly need re-rendering to maximize cache benefits
+   ```jsx
+   // Good: Only re-render the active item
+   <RenderCache
+     items={items}
+     renderKeys={[activeItemId]}
+     getKey={(item) => item.id}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   
+   // Bad: Re-rendering all items defeats the purpose
+   <RenderCache
+     items={items}
+     renderKeys={items.map(item => item.id)}
+     getKey={(item) => item.id}
+   >
+     {(item) => <Item {...item} />}
+   </RenderCache>
+   ```
+
+3. **Consider alternatives**: For simple cases, React.memo might be sufficient and simpler
+
+4. **Profile first**: Use React DevTools Profiler to confirm you have a performance issue before adding this optimization
+
+5. **Avoid inline functions**: Use stable render functions to prevent unnecessary cache invalidation
+   ```jsx
+   // Good: Stable render function
+   const renderItem = useCallback((item) => (
+     <ExpensiveItem item={item} />
+   ), []);
+   
+   <RenderCache
+     items={items}
+     renderKeys={[selectedId]}
+     getKey={(item) => item.id}
+   >
+     {renderItem}
+   </RenderCache>
+   ```
+
+## When NOT to Use
+
+- **Simple lists**: For simple lists without performance issues, regular rendering is simpler
+- **All items update frequently**: If all items need to re-render on every change, the cache overhead isn't worth it
+- **Small lists**: Lists with < 10 items typically don't benefit from caching
+- **Simple components**: If child components render quickly, the optimization overhead may outweigh benefits
+
+## Related Components
+
+- **React.memo** - For simple component memoization
+- **useMemo** - For memoizing computed values
+- **useCallback** - For memoizing callback functions
+- **DisplayTransition** - For animating component mount/unmount
+

package/docs/Result.md

@@ -0,0 +1,42 @@
+# Result
+
+Used to feed back the results of a series of operational tasks.
+
+## When To Use
+
+Use when important operations need to inform the user to process the results and the feedback is more complicated.
+
+## Examples
+
+### Success
+
+### Info
+
+### Warning
+
+### Error
+
+### Custom Icon
+
+### Custom Title
+
+### Compact
+
+## Properties
+
+- **`status`** `'success' | 'error' | 'info' | 'warning' | 404 | 403 | 500` (default: `'info'`) — Result status, determines the icon and color from ready-made templates
+- **`title`** `ReactNode` — The title of the result
+- **`subtitle`** `ReactNode` — Subtitle of the result component
+- **`icon`** `ReactNode` — Custom icon element. Don't use together with `status`
+- **`isCompact`** `boolean` — Whether the result component has a compact presentation
+- **`children`** `ReactNode` — Additional block content, e.g. a set of action buttons
+
+## Differences from Ant Design
+
+| There are differences | Ant Design property | Cube UIKit property |
+| :-------------------: | :-----------------: | :-----------------: |
+|          No           |      `status`       |      `status`       |
+|          No           |       `title`       |       `title`       |
+|          Yes          |     `subTitle`      |     `subtitle`      |
+|          No           |       `icon`        |       `icon`        |
+|          Yes          |       `extra`       |     `children`      |

package/docs/SimpleLayout.md

@@ -0,0 +1,26 @@
+# Layout examples
+
+## Flow layout
+
+Flow Component is used to create gaps between blocks inside block layout.
+
+## Flex layout
+
+Use Space Component to create a row or a column of elements.
+
+Use Flex Component for more flexible layouts.
+
+## Grid layout
+
+Use Grid Component for grid layouts.
+
+### Simple layout with side bar.
+
+```jsx
+<Grid gridColumns="200px 1fr" gridRows="60px 1fr" height="500px">
+  <Card gridColumn="1 / -1">Header</Card>
+  <Card>Sidebar</Card>
+  <Card>Content</Card>
+</Grid>
+```
+

package/docs/Typography.md

@@ -0,0 +1,38 @@
+# Typography
+
+There are many ways to create typography elements like text labels and headings. You can use complete components, presets or low-level styles to get exact text label you want.
+
+## Typography Components
+
+### Headings
+
+### Paragraphs
+
+Paragraphs with gaps between them.
+
+### Text labels
+
+### Links
+
+Use `!` prefix to open link in new tab.
+
+```jsx
+(
+  <Link to="https://cube-uikit-storybook.netlify.app/">
+    Open Cube Cloud UI Kit
+  </Link>
+) |
+  (
+    <Link to="!https://cube-uikit-storybook.netlify.app/">
+      Open Cube Cloud UI Kit in new tab
+    </Link>
+  );
+```
+
+Use `@` prefix to navigate to the new page without using the Router.
+
+```jsx
+<Link to="@">Reload this page</Link> |
+<Link to="@/">Move to the Main Page</Link>;
+```
+

package/docs/components/Block.md

@@ -0,0 +1,33 @@
+# Block
+
+A simple block-level container. The most basic layout primitive.
+
+## When to Use
+
+- Wrapping content in a block display context
+- Base layout when you need `display: block` without extra semantics
+- Generic container for styling with style props
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `block`
+
+### Base Properties
+
+Supports [Base properties](../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Block>
+  <Text>Content in a block container</Text>
+</Block>
+
+<Block padding="1x" fill="#surface">
+  Styled block with padding and background
+</Block>
+```

package/docs/components/CollectionItem.md

@@ -0,0 +1,293 @@
+# CollectionItem
+
+`CollectionItem` is the building block for all collection-based components in the UI Kit, providing a consistent API for list items, menu options, and selectors.
+
+## Used By
+
+ListBox, FilterListBox, Select, ComboBox, FilterPicker, Picker, Menu, CommandMenu
+
+## Usage Patterns
+
+There are two ways to provide items to collection components:
+
+### Static JSX
+
+Define items directly. You **must** provide `key` props:
+
+```jsx live=false
+<ListBox>
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+```
+
+### Data-driven (Recommended)
+
+**🚨 IMPORTANT:** The `items` prop **must be an array of objects**, where each object contains at least an `id` or `key` property.
+
+```jsx live=false
+// ✅ Correct: Array of objects with id/key
+const items = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+];
+
+<ListBox items={items}>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+```jsx live=false
+// ❌ Wrong: Array of strings won't work
+const items = ['apple', 'banana']; // Don't do this!
+
+// ❌ Wrong: Array of primitives won't work
+const items = [1, 2, 3]; // Don't do this!
+```
+
+## Item Requirements
+
+- **`id` or `key`** `string | number` — Unique identifier - **critical for selection callbacks** (✅ Required)
+- **`textValue`** `string` — For filtering & accessibility (⚠️ Recommended)
+
+**Without `id`/`key`:** React Aria falls back to using order-based keys (e.g., `"0"`, `"1"`), which breaks selection functionality in select components as these values are meaningless for identifying specific items.
+
+**Without `textValue`:** Falls back to rendered content, then to key/id.
+
+### Rules
+
+```jsx live=false
+// ✅ Using 'id'
+const items = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+];
+
+// ✅ Using 'key'
+const items = [
+  { key: 'apple', name: 'Apple' },
+  { key: 'banana', name: 'Banana' },
+];
+
+// ✅ Consistent types
+const items = [
+  { id: '1', name: 'First' },
+  { id: '2', name: 'Second' },
+];
+
+// ✅ Explicit textValue for complex content
+const items = [{
+  id: 'user-1',
+  firstName: 'John',
+  lastName: 'Smith',
+  textValue: 'John Smith',
+}];
+```
+
+**Always provide explicit `textValue` for:**
+- Icons/images without text
+- Formatted/complex content
+- Non-readable keys (UUIDs)
+- Searchable components (ComboBox, FilterListBox, FilterPicker, CommandMenu)
+
+## Properties
+
+Extends all [Item component](./content/Item.md) props:
+
+- `children` - Item content
+- `icon` / `rightIcon` - Icons
+- `prefix` / `suffix` - Additional content
+- `description` - Secondary text
+- `textValue` - Text for filtering/accessibility
+- `onAction` - Action handler (Menu items)
+
+## Examples
+
+### Basic
+
+```jsx live=false
+const permissions = [
+  { id: 'read', name: 'Read' },
+  { id: 'write', name: 'Write' },
+];
+
+<ListBox items={permissions}>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+### With Icons
+
+```jsx live=false
+import { IconFile, IconFolder } from '@tabler/icons-react';
+
+const items = [
+  { id: 'file', name: 'File', icon: <IconFile /> },
+  { id: 'folder', name: 'Folder', icon: <IconFolder /> },
+];
+
+<Menu items={items}>
+  {(item) => <Menu.Item key={item.id} icon={item.icon}>{item.name}</Menu.Item>}
+</Menu>
+```
+
+### With Descriptions
+
+```jsx live=false
+const users = [
+  {
+    id: '1',
+    name: 'John Smith',
+    email: 'john@example.com',
+    textValue: 'John Smith john@example.com',
+  },
+];
+
+<ComboBox items={users}>
+  {(item) => (
+    <ComboBox.Item key={item.id} description={item.email}>
+      {item.name}
+    </ComboBox.Item>
+  )}
+</ComboBox>
+```
+
+### With Sections
+
+```jsx live=false
+<ListBox>
+  <ListBox.Section title="Fruits">
+    <ListBox.Item key="apple">Apple</ListBox.Item>
+    <ListBox.Item key="banana">Banana</ListBox.Item>
+  </ListBox.Section>
+  <ListBox.Section title="Vegetables">
+    <ListBox.Item key="carrot">Carrot</ListBox.Item>
+  </ListBox.Section>
+</ListBox>
+```
+
+### Disabled Items
+
+```jsx live=false
+const items = [
+  { id: 'read', name: 'Read' },
+  { id: 'write', name: 'Write' },
+  { id: 'delete', name: 'Delete', disabled: true },
+];
+
+<ListBox
+  items={items}
+  disabledKeys={items.filter(i => i.disabled).map(i => i.id)}
+>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+## Best Practices
+
+```jsx live=false
+// ✅ Items must be an array of objects
+const items = [{ id: 'user-1', name: 'John' }];
+
+// ✅ Always provide id/key in each object
+const items = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+];
+
+// ✅ Always pass key prop to Item
+<ListBox items={items}>
+  {(item) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+
+// ✅ Consistent types for id/key
+const items = [
+  { id: '1', name: 'First' },
+  { id: '2', name: 'Second' },
+];
+
+// ✅ Explicit textValue for complex content
+const items = [{
+  id: 'user-1',
+  name: 'John Smith',
+  textValue: 'John Smith',
+}];
+
+// ✅ Memoize large collections
+const items = useMemo(
+  () => data.map(d => ({ id: d.id, name: d.name })),
+  [data]
+);
+
+// ❌ Don't pass array of strings
+const items = ['apple', 'banana']; // Wrong!
+
+// ❌ Don't pass array of numbers
+const items = [1, 2, 3]; // Wrong!
+
+// ❌ Don't omit key prop
+<ListBox items={items}>
+  {(item) => <ListBox.Item>{item.name}</ListBox.Item>}
+</ListBox>
+
+// ❌ Don't omit id/key in objects
+const items = [
+  { name: 'First' }, // Missing id!
+  { name: 'Second' }, // Missing id!
+];
+
+// ❌ Don't mix types
+const items = [
+  { id: 1, name: 'First' },
+  { id: '2', name: 'Second' },
+];
+```
+
+## TypeScript
+
+```tsx live=false
+interface User {
+  id: string;          // Required!
+  name: string;
+  textValue?: string;
+}
+
+const items: User[] = [
+  { id: '1', name: 'John', textValue: 'John' },
+];
+
+<ListBox items={items}>
+  {(item: User) => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>}
+</ListBox>
+```
+
+## Quick Reference
+
+- **Static JSX** — Key Prop: ✅ Required; Source: Hardcoded value
+- **Data-driven (`items`)** — Key Prop: ✅ Required; Source: Pass `item.key` or `item.id`
+- **Using `.map()`** — Key Prop: ✅ Required; Source: Pass `item.key` or `item.id`
+
+- **ListBox** — Selection: Single/Multiple; Search: ❌
+- **FilterListBox** — Selection: Single/Multiple; Search: ✅
+- **Select** — Selection: Single; Search: ❌
+- **ComboBox** — Selection: Single; Search: ✅
+- **FilterPicker** — Selection: Single/Multiple; Search: ✅
+- **Picker** — Selection: Single/Multiple; Search: ❌
+- **Menu** — Selection: Single action; Search: ❌
+- **CommandMenu** — Selection: Single action; Search: ✅
+
+## Essential Rules
+
+1. **🚨 The `items` prop must be an array of objects** - Never pass arrays of strings, numbers, or other primitives. Each object must have an `id` or `key` property.
+2. **🚨 Always provide `id` or `key` in each object** - Required for selection callbacks to work properly. Without it, React Aria uses order-based keys which are useless in select components.
+3. **🚨 Always pass `key` prop to Item** - Must explicitly pass `key={item.id}` or `key={item.key}` in the render function
+4. **Provide explicit `textValue`** - For icons, complex content, or searchable components
+5. **Use consistent types** - All strings or all numbers, never mixed
+
+## Related Components
+
+- [Item](./content/Item.md) - Base item component
+- [ListBox](./fields/ListBox.md) - List with selection
+- [Select](./fields/Select.md) - Dropdown selector
+- [ComboBox](./fields/ComboBox.md) - Searchable input
+- [Menu](./actions/Menu.md) - Action menu

package/docs/components/GridProvider.md

@@ -0,0 +1,38 @@
+# GridProvider
+
+Provides CSS custom properties for responsive grid column calculations. Children can use `$column-width` for precise column sizing.
+
+## When to Use
+
+- Responsive grid layouts with consistent column sizing
+- Layouts that need to calculate column widths based on container size
+- Grid systems with configurable column counts
+
+## Properties
+
+- **`columns`** `number` (default: `2`) — Number of grid columns
+- **`gap`** `Styles['gap']` (default: `'0'`) — Gap between columns
+- **`width`** `Styles['width']` — Forced container width (bypasses auto-detection)
+- **`initialWidth`** `Styles['width']` — Initial width before resize observer kicks in
+
+### CSS Custom Properties Provided
+
+- `--grid-width` — Total grid width
+- `--columns-amount` — Number of columns
+- `--column-gap` — Gap between columns
+- `--column-width` — Calculated width per column
+
+### Style Defaults
+
+- `display` — `contents`
+
+## Examples
+
+```jsx
+<GridProvider columns={12} gap="1x">
+  <Grid columns="repeat(12, $column-width)">
+    <Block gridColumn="span 6">Half</Block>
+    <Block gridColumn="span 6">Half</Block>
+  </Grid>
+</GridProvider>
+```

package/docs/components/Root.md

@@ -0,0 +1,50 @@
+# Root
+
+The root application wrapper. Provides theme context, global styles, portal container, modal/toast providers, and navigation. Wrap your app with `Root` at the top level.
+
+## When to Use
+
+- Top-level app component (required)
+- Provides context for modals, toasts, tooltips, and overlays
+- Theme and design token configuration
+
+## Properties
+
+- **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
+- **`tracking`** `TrackingProps` — Analytics/tracking event configuration
+- **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
+- **`fonts`** `boolean` — Whether to load default fonts
+- **`font`** `string` — Custom font family name
+- **`monospaceFont`** `string` — Custom monospace font family name
+- **`fontDisplay`** `'auto' | 'block' | 'swap' | 'fallback' | 'optional'` (default: `'swap'`) — Font display strategy
+- **`bodyStyles`** `Record<string, string>` — Raw CSS styles applied to the `<body>`
+- **`publicUrl`** `string` — Public URL for font loading
+- **`cursorStrategy`** `'web' | 'native'` (default: `'web'`) — Cursor style for interactive elements (`web` uses pointer, `native` uses default)
+
+### Style Defaults
+
+- `display` — `contents`
+- `color` — `#dark-02`
+- `preset` — `t3`
+
+### Base Properties
+
+Supports [Base properties](../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Root>
+  <App />
+</Root>
+```
+
+```jsx
+<Root
+  font="Inter"
+  navigation={routerAdapter}
+  tokens={{ '--gap': '8px', '--radius': '4px' }}
+>
+  <App />
+</Root>
+```