@cube-dev/ui-kit 0.0.0-canary-d688797 → 0.0.0-canary-bdfccbd

package/docs/components/form/FormInstance.md

@@ -227,60 +227,48 @@ const [form] = Form.useForm(undefined, undefined, {
 
 ### Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `isSubmitting` | `boolean` | Whether the form is currently being submitted |
-| `submitError` | `unknown` | Error from the last submission attempt |
-| `isTouched` | `boolean` | Whether any field has been interacted with |
-| `isDirty` | `boolean` | Whether any field value differs from initial values |
-| `isValid` | `boolean` | Whether all fields are validated and valid |
-| `isInvalid` | `boolean` | Whether any field is validated and invalid |
+- **`isSubmitting`** `boolean` — Whether the form is currently being submitted
+- **`submitError`** `unknown` — Error from the last submission attempt
+- **`isTouched`** `boolean` — Whether any field has been interacted with
+- **`isDirty`** `boolean` — Whether any field value differs from initial values
+- **`isValid`** `boolean` — Whether all fields are validated and valid
+- **`isInvalid`** `boolean` — Whether any field is validated and invalid
 
 ### Methods
 
 #### Field Value Management
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getFieldValue` | `<Name>(name: Name) => T[Name]` | Get the value of a specific field |
-| `setFieldValue` | `<Name>(name: Name, value: T[Name], isTouched?, skipRender?) => void` | Set the value of a specific field |
-| `getFieldsValue` | `() => PartialString<T>` | Get all field values as a flat object |
-| `setFieldsValue` | `(newData: PartialString<T>, touched?, skipRender?) => void` | Set multiple field values |
-| `getFormData` | `() => T` | Get form data with dot notation converted to nested objects |
+- **`getFieldValue`** `<Name>(name: Name) => T[Name]` — Get the value of a specific field
+- **`setFieldValue`** `<Name>(name: Name, value: T[Name], isTouched?, skipRender?) => void` — Set the value of a specific field
+- **`getFieldsValue`** `() => PartialString<T>` — Get all field values as a flat object
+- **`setFieldsValue`** `(newData: PartialString<T>, touched?, skipRender?) => void` — Set multiple field values
+- **`getFormData`** `() => T` — Get form data with dot notation converted to nested objects
 
 #### Initial Values
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `setInitialFieldsValue` | `(values: PartialString<T>) => void` | Set initial values for fields |
-| `updateInitialFieldsValue` | `(values: FieldTypes) => void` | Update initial values (merge with existing) |
-| `resetFields` | `(names?: string[], skipRender?) => void` | Reset fields to initial values |
+- **`setInitialFieldsValue`** `(values: PartialString<T>) => void` — Set initial values for fields
+- **`updateInitialFieldsValue`** `(values: FieldTypes) => void` — Update initial values (merge with existing)
+- **`resetFields`** `(names?: string[], skipRender?) => void` — Reset fields to initial values
 
 #### Validation
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `validateField` | `<Name>(name: Name) => Promise<any>` | Validate a single field |
-| `validateFields` | `<Names>(names?: Names) => Promise<any>` | Validate multiple or all fields |
-| `isFieldValid` | `<Name>(name: Name) => boolean` | Check if a field is valid |
-| `isFieldInvalid` | `<Name>(name: Name) => boolean` | Check if a field is invalid |
-| `getFieldError` | `<Name>(name: Name) => ReactNode[]` | Get validation errors for a field |
-| `setFieldError` | `(name: string, error: ReactNode, skipRender?) => void` | Set a custom error for a field |
-| `resetFieldsValidation` | `(names?: string[], skipRender?) => void` | Clear validation errors |
+- **`validateField`** `<Name>(name: Name) => Promise<any>` — Validate a single field
+- **`validateFields`** `<Names>(names?: Names) => Promise<any>` — Validate multiple or all fields
+- **`isFieldValid`** `<Name>(name: Name) => boolean` — Check if a field is valid
+- **`isFieldInvalid`** `<Name>(name: Name) => boolean` — Check if a field is invalid
+- **`getFieldError`** `<Name>(name: Name) => ReactNode[]` — Get validation errors for a field
+- **`setFieldError`** `(name: string, error: ReactNode, skipRender?) => void` — Set a custom error for a field
+- **`resetFieldsValidation`** `(names?: string[], skipRender?) => void` — Clear validation errors
 
 #### State Checking
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `isFieldTouched` | `<Name>(name: Name) => boolean` | Check if a field has been interacted with |
-| `getFieldInstance` | `<Name>(name: Name) => TFormData[Name]` | Get the internal field instance |
+- **`isFieldTouched`** `<Name>(name: Name) => boolean` — Check if a field has been interacted with
+- **`getFieldInstance`** `<Name>(name: Name) => TFormData[Name]` — Get the internal field instance
 
 #### Submission
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `submit` | `() => Promise<void>` | Submit the form |
-| `setSubmitting` | `(isSubmitting: boolean) => void` | Set the submission state |
+- **`submit`** `() => Promise<void>` — Submit the form
+- **`setSubmitting`** `(isSubmitting: boolean) => void` — Set the submission state
 
 ## Type Definitions
 

package/docs/components/helpers/DisplayTransition.md

@@ -15,6 +15,17 @@ A headless helper component that manages enter and exit animation states for sho
 
 ### Properties
 
+- **`isShown`** `boolean` — Desired visibility state (driver for the transition)
+- **`duration`** `number` — Transition duration in milliseconds. If `0`, transitions are instant. If `undefined`, uses native CSS transition events for timing.
+- **`animateOnMount`** `boolean` (default: `true`) — Whether to animate on first mount. Set to `false` to skip the initial enter animation
+- **`respectReducedMotion`** `boolean` (default: `true`) — Respect the user's `prefers-reduced-motion` setting by collapsing duration to 0
+- **`preserveContent`** `boolean` (default: `true`) — Preserve children content during exit transition. When true, uses stored children from when content was visible
+- **`exposeUnmounted`** `boolean` (default: `false`) — Keep calling children during the `unmounted` phase instead of returning `null`
+- **`onRest`** `(transition: 'enter' | 'exit') => void` — Fires after enter settles or after exit completes (unmount)
+- **`onPhaseChange`** `(phase: ReportedPhase) => void` — Fires when the transition phase changes
+- **`onToggle`** `(isShown: boolean) => void` — Fires when the derived `isShown` value changes
+- **`children`** `(props: { phase, isShown, ref }) => ReactNode` — Render prop receiving the current phase, visibility state, and a ref callback to bind to the transitioned element
+
 ### Base Properties
 
 This is a headless component and does not support base properties.
@@ -23,12 +34,10 @@ This is a headless component and does not support base properties.
 
 The component manages four distinct phases:
 
-| Phase | Description | isShown value |
-|-------|-------------|---------------|
-| `unmounted` | Content is not mounted | `false` |
-| `enter` | Content is mounting, enter animation should start | `false` |
-| `entered` | Enter animation complete, content is visible | `true` |
-| `exit` | Content is exiting, exit animation should start | `false` |
+- **`unmounted`** — Content is not mounted (isShown: `false`)
+- **`enter`** — Content is mounting, enter animation should start (isShown: `false`)
+- **`entered`** — Enter animation complete, content is visible (isShown: `true`)
+- **`exit`** — Content is exiting, exit animation should start (isShown: `false`)
 
 The render prop receives an object `{ phase, isShown }` where `isShown` is only `true` during the `entered` phase.
 

package/docs/components/helpers/IconSwitch.md

@@ -15,9 +15,13 @@ A helper component that cross-fades between icons when children change. It provi
 
 ### 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)
+Supports [Base properties](../../BaseProperties.md)
 
 ## Examples
 

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>
+```