@cube-dev/ui-kit 0.121.0 → 0.121.2

package/docs/components/helpers/IconSwitch.md

@@ -0,0 +1,160 @@
+# IconSwitch
+
+A helper component that cross-fades between icons when children change. It provides smooth animated transitions between different icon states, making UI interactions feel more polished.
+
+## When to Use
+
+- When you need animated transitions between different icons based on state
+- For toggle buttons that switch between two icons (e.g., play/pause, expand/collapse)
+- When building interactive UI elements where icon changes should be visually smooth
+- In components like `Item` or `ItemButton` where icons change based on modifiers
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** `ReactNode` — The icon to display
+- **`contentKey`** `string | number` — Override key for detecting icon changes. When this value changes, a cross-fade transition is triggered
+- **`noWrapper`** `boolean` — When true, renders without wrapper element, expecting parent to provide grid context
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+## Examples
+
+### Nullish transitions (show / hide)
+
+`IconSwitch` preserves the last visible icon during the fade-out when switching to `null`/`undefined`/`false`, so you get a smooth “icon → empty” transition.
+
+### Basic Toggle
+
+Use `contentKey` to explicitly identify when the icon should transition:
+
+```jsx
+import { IconSwitch } from '@cube-dev/ui-kit';
+import { DownIcon, UpIcon } from '@cube-dev/ui-kit/icons';
+
+function ExpandToggle({ isExpanded }) {
+  return (
+    <IconSwitch contentKey={isExpanded ? 'up' : 'down'}>
+      {isExpanded ? <UpIcon /> : <DownIcon />}
+    </IconSwitch>
+  );
+}
+```
+
+### Play/Pause Button
+
+```jsx
+import { IconSwitch } from '@cube-dev/ui-kit';
+import { PlayIcon, PauseIcon } from '@cube-dev/ui-kit/icons';
+
+function MediaControl({ isPlaying }) {
+  return (
+    <IconSwitch contentKey={isPlaying ? 'pause' : 'play'}>
+      {isPlaying ? <PauseIcon /> : <PlayIcon />}
+    </IconSwitch>
+  );
+}
+```
+
+### Multiple States
+
+The component handles multiple state transitions seamlessly:
+
+```jsx
+import { IconSwitch } from '@cube-dev/ui-kit';
+import { DownIcon, CheckIcon, CloseIcon } from '@cube-dev/ui-kit/icons';
+
+function StatusIcon({ status }) {
+  const icons = {
+    idle: <DownIcon />,
+    success: <CheckIcon />,
+    error: <CloseIcon />,
+  };
+
+  return (
+    <IconSwitch contentKey={status}>
+      {icons[status]}
+    </IconSwitch>
+  );
+}
+```
+
+### Rapid Toggling
+
+The component handles rapid state changes gracefully, properly managing overlapping transitions.
+
+### With Dynamic Icons in Item Component
+
+```jsx
+import { Item, IconSwitch } from '@cube-dev/ui-kit';
+import { DownIcon, UpIcon } from '@cube-dev/ui-kit/icons';
+
+function ExpandableItem({ isExpanded, onToggle }) {
+  return (
+    <Item
+      icon={
+        <IconSwitch contentKey={isExpanded ? 'up' : 'down'}>
+          {isExpanded ? <UpIcon /> : <DownIcon />}
+        </IconSwitch>
+      }
+      onPress={onToggle}
+    >
+      {isExpanded ? 'Collapse' : 'Expand'}
+    </Item>
+  );
+}
+```
+
+## How It Works
+
+1. **Change Detection**: The component tracks icon changes using `contentKey` (if provided) or a best-effort derived key from the child element type (so prop-only updates don’t trigger transitions)
+2. **Stack Management**: When content changes, both old and new icons are rendered simultaneously
+3. **Cross-fade Animation**: The old icon fades out while the new icon fades in using CSS opacity transitions
+4. **Cleanup**: After the exit transition completes, the old icon is removed from the DOM
+
+## Best Practices
+
+1. **Prefer `contentKey`**: The component can derive a key from the child element type, but explicit keys are more reliable (especially for custom “same type, different meaning” icons):
+   ```jsx
+   // Good - explicit key
+   <IconSwitch contentKey={isOpen ? 'open' : 'closed'}>
+     {isOpen ? <OpenIcon /> : <CloseIcon />}
+   </IconSwitch>
+
+   // Avoid - relies on implicit key derivation
+   <IconSwitch>
+     {isOpen ? <OpenIcon /> : <CloseIcon />}
+   </IconSwitch>
+   ```
+
+2. **Use consistent icon sizes**: Ensure all icons within the same IconSwitch have the same dimensions for smooth transitions
+
+3. **Keep transitions subtle**: The default `transition: 'theme'` timing is designed to be quick and non-distracting
+
+## Accessibility
+
+### Screen Reader Support
+
+- Icon transitions are purely visual and don't affect screen reader announcements
+- Ensure the parent component provides appropriate `aria-label` or text content to convey state changes
+
+### Reduced Motion
+
+The component respects the user's `prefers-reduced-motion` preference through the underlying `DisplayTransition` component.
+
+## Suggested Improvements
+
+- Add `duration` prop to customize transition timing
+- Support custom transition styles beyond opacity
+- Add `onTransitionStart` and `onTransitionEnd` callbacks
+
+## Related Components
+
+- [DisplayTransition](/helpers/DisplayTransition) - Lower-level transition management
+- [Item](/content/Item) - Uses dynamic icons that could benefit from IconSwitch
+- [ItemButton](/actions/ItemButton) - Button variant with icon switching capability

package/docs/components/layout/Flex.md

@@ -0,0 +1,51 @@
+# Flex
+
+A flexbox layout container. Arranges children in a row by default with no predefined gap.
+
+## When to Use
+
+- One-dimensional layouts (row or column)
+- Aligning and distributing space between items
+- When you need more control than `Space` provides
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `flex`
+- `flow` — `row`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Row with gap
+
+```jsx
+<Flex gap="1x">
+  <Button>Action 1</Button>
+  <Button>Action 2</Button>
+</Flex>
+```
+
+### Column layout
+
+```jsx
+<Flex flow="column" gap="2x">
+  <Title level={3}>Section</Title>
+  <Paragraph>Content</Paragraph>
+</Flex>
+```
+
+### Space between
+
+```jsx
+<Flex placeContent="space-between">
+  <Text>Left</Text>
+  <Text>Right</Text>
+</Flex>
+```

package/docs/components/layout/Flow.md

@@ -0,0 +1,32 @@
+# Flow
+
+A block-level container with column flow. Children stack vertically by default.
+
+## When to Use
+
+- Vertical content stacking
+- Document-like layouts (top to bottom)
+- Simple column flow without flex complexity
+
+## Properties
+
+No component-specific props. Use style props directly.
+
+### Style Defaults
+
+- `display` — `block`
+- `flow` — `column`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Flow gap="1x">
+  <Title level={3}>Section</Title>
+  <Paragraph>First paragraph</Paragraph>
+  <Paragraph>Second paragraph</Paragraph>
+</Flow>
+```

package/docs/components/layout/Grid.md

@@ -0,0 +1,46 @@
+# Grid
+
+A CSS Grid layout container. Arranges children in a grid with configurable columns and rows.
+
+## When to Use
+
+- Two-dimensional layouts (rows and columns)
+- Complex layouts requiring precise placement
+- Responsive grids with different breakpoint configurations
+
+## Properties
+
+- **`template`** `string` — Shorthand for `gridTemplate`
+- **`columns`** `string` — Shorthand for `gridColumns` (e.g. `"1fr 1fr"`, `"auto 1fr"`)
+- **`rows`** `string` — Shorthand for `gridRows`
+- **`areas`** `string` — Shorthand for `gridAreas`
+
+### Style Defaults
+
+- `display` — `grid`
+- `flow` — `row`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Two columns
+
+```jsx
+<Grid columns="1fr 1fr" gap="1x">
+  <Block>Column 1</Block>
+  <Block>Column 2</Block>
+</Grid>
+```
+
+### Three-column layout
+
+```jsx
+<Grid columns="auto 1fr auto" gap="2x">
+  <Text>Label</Text>
+  <Text>Value</Text>
+  <Text>Unit</Text>
+</Grid>
+```

package/docs/components/layout/Panel.md

@@ -0,0 +1,65 @@
+# Panel
+
+> **Deprecated**: Use [Layout](../content/Layout.md) with `Layout.Panel` instead. Layout.Panel provides collapsible side panels with resizing, transitions, overlay modes, and automatic content adjustment — all features that Panel lacks.
+
+A section container with optional stretched, floating, or card styling. Renders as `<section>` with an absolute-positioned inner scrollable area.
+
+## When to Use
+
+- Sidebar or drawer content
+- Modal/dialog content areas
+- Card-styled panels with border and radius
+
+## Properties
+
+- **`isStretched`** `boolean` — Fill available space (absolute positioning, `inset: 0`)
+- **`isCard`** `boolean` — Card appearance with border (`1bw`) and radius (`1r`)
+- **`isFloating`** `boolean` — Floating overlay positioning (absolute)
+- **`isFlex`** `boolean` — Use flex layout instead of grid for the inner element
+- **`innerStyles`** `Styles` — Styles applied to the inner content area
+- **`extra`** `ReactNode` — Content rendered outside the inner scrollable area
+- **`placeContent`** `string` — Content placement for the inner area
+- **`placeItems`** `string` — Items placement for the inner area
+- **`gridColumns`** `string` — Grid columns for the inner area
+- **`gridRows`** `string` — Grid rows for the inner area
+- **`flow`** `string` — Flow direction for the inner area
+- **`gap`** `string` — Gap for the inner area
+
+### Style Defaults
+
+- `display` — `block`
+- `position` — `relative` (switches to `absolute` when `isStretched` or `isFloating`)
+- `flexGrow` — `1`
+- `radius` — `0` (switches to `1r` when `isCard`)
+- `border` — `0` (switches to `1bw` when `isCard`)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Basic panel
+
+```jsx
+<Panel>
+  <Title level={3}>Panel Content</Title>
+  <Paragraph>Content goes here</Paragraph>
+</Panel>
+```
+
+### Card-styled panel
+
+```jsx
+<Panel isCard padding="1x">
+  Card-styled panel with border
+</Panel>
+```
+
+### Stretched sidebar
+
+```jsx
+<Panel isStretched fill="#surface">
+  Fills its parent container
+</Panel>
+```

package/docs/components/layout/Prefix.md

@@ -0,0 +1,37 @@
+# Prefix
+
+An absolutely positioned prefix slot, typically used inside input-like components to show icons or labels on the left.
+
+## When to Use
+
+- Input prefixes (icons, labels)
+- Left-aligned decorations in form fields
+
+## Properties
+
+- **`onWidthChange`** `Function` — Callback when prefix width changes (used for input padding calculation)
+- **`outerGap`** `CSSProperties['gap']` (default: `'1bw'`) — Gap between prefix and the component edge
+
+### Style Defaults
+
+- `position` — `absolute`
+- `display` — `grid`
+- `flow` — `column`
+- `gap` — `0`
+- `placeItems` — `center`
+- `color` — `#dark-02`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Block position="relative">
+  <Prefix>
+    <Icon icon={IconSearch} />
+  </Prefix>
+  <TextInput placeholder="Search..." />
+</Block>
+```

package/docs/components/layout/ResizablePanel.md

@@ -0,0 +1,69 @@
+# ResizablePanel
+
+> **Deprecated**: Use [Layout](../content/Layout.md) with `Layout.Panel` (set `isResizable`) or `Layout.Pane` instead. Layout.Panel supports resizing, transitions, overlay modes, size persistence, and automatic content adjustment. Layout.Pane provides inline resizable sections within the normal flex/grid flow.
+
+A `Panel` with a draggable resize handle. Users can adjust the panel size by dragging the handle.
+
+## When to Use
+
+- Resizable sidebars or split views
+- Adjustable layout panels
+- User-customizable workspace layouts
+
+## Component
+
+---
+
+## Properties
+
+- **`direction`** `'top' | 'right' | 'bottom' | 'left'` (default: `'right'`) — Position of the resize handle
+- **`size`** `number` — Panel size in pixels. When provided, the component becomes controlled.
+- **`onSizeChange`** `(size: number) => void` — Callback when size changes via dragging
+- **`minSize`** `string | number` (default: `200`) — Minimum size constraint
+- **`maxSize`** `string | number` (default: `'min(50%, 400px)'` for uncontrolled) — Maximum size constraint
+- **`isDisabled`** `boolean` — Disable resizing
+- **`handlerStyles`** `Styles` — Custom styles for the resize handle
+
+### Base Properties
+
+Extends [Panel](#) and supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Resizable sidebar
+
+```jsx
+<Panel isFlex isStretched height="min 30x" fill="#white">
+  <ResizablePanel direction="right">
+    <Block padding="1x">Sidebar content</Block>
+  </ResizablePanel>
+  <Panel fill="#purple-04.10">Main content</Panel>
+</Panel>
+```
+
+### Controlled size
+
+```jsx
+function ControlledExample() {
+  const [size, setSize] = useState(200);
+
+  return (
+    <ResizablePanel
+      direction="right"
+      size={size}
+      onSizeChange={(s) => setSize(Math.min(500, Math.max(100, s)))}
+      fill="#light"
+    >
+      Sidebar
+    </ResizablePanel>
+  );
+}
+```
+
+### Disabled
+
+```jsx
+<ResizablePanel direction="right" isDisabled>
+  Non-resizable panel
+</ResizablePanel>
+```

package/docs/components/layout/Space.md

@@ -0,0 +1,44 @@
+# Space
+
+A flex container that adds consistent gap between children. Supports horizontal (default) and vertical directions.
+
+## When to Use
+
+- Spacing between buttons, icons, or inline elements
+- Vertical or horizontal stacks with consistent gaps
+- Replacing manual margin hacks with semantic spacing
+
+## Properties
+
+- **`direction`** `'vertical' | 'horizontal'` (default: `'horizontal'`) — Layout direction
+
+### Style Defaults
+
+- `display` — `flex`
+- `gap` — `1x`
+- `flow` — `row` (switches to `column` when `direction="vertical"`)
+- `placeItems` — `center stretch` (switches to `stretch` when vertical)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+### Horizontal (default)
+
+```jsx
+<Space>
+  <Button>Save</Button>
+  <Button>Cancel</Button>
+</Space>
+```
+
+### Vertical with custom gap
+
+```jsx
+<Space direction="vertical" gap="2x">
+  <Title level={3}>Title</Title>
+  <Paragraph>Description</Paragraph>
+</Space>
+```

package/docs/components/layout/Suffix.md

@@ -0,0 +1,39 @@
+# Suffix
+
+An absolutely positioned suffix slot, typically used inside input-like components to show icons or actions on the right.
+
+## When to Use
+
+- Input suffixes (clear button, unit labels)
+- Right-aligned decorations in form fields
+
+## Properties
+
+- **`onWidthChange`** `Function` — Callback when suffix width changes (used for input padding calculation)
+- **`outerGap`** `CSSProperties['gap']` (default: `'1bw'`) — Gap between suffix and the component edge
+
+### Style Defaults
+
+- `position` — `absolute`
+- `display` — `grid`
+- `flow` — `column`
+- `gap` — `0`
+- `placeItems` — `center`
+- `color` — `#dark-02`
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+## Examples
+
+```jsx
+<Block position="relative">
+  <TextInput placeholder="Search..." />
+  <Suffix>
+    <Button size="small" iconOnly>
+      <Icon icon={IconX} />
+    </Button>
+  </Suffix>
+</Block>
+```