@cube-dev/ui-kit 0.0.0-canary-1f0dd2c → 0.0.0-canary-1d27aa0

package/docs/components/fields/ListBox.md

@@ -64,7 +64,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root wrapper element of the component.
 
 **Sub-elements:**
-
 - `ValidationState` - Container for validation and loading indicators
 
 #### listStyles
@@ -76,7 +75,6 @@ Customizes the list container element.
 Customizes individual option elements.
 
 **Sub-elements:**
-
 - `Label` - The main text of each option
 - `Description` - Secondary descriptive text for options
 - `Content` - Container for label and description
@@ -128,51 +126,42 @@ The `mods` property accepts the following modifiers you can override:
 ### Selection Behavior
 
 **isCheckable** (`boolean`, default: `false`)
-
 - When `true` in multiple selection mode, displays checkboxes on the left of each option
 - Checkboxes are visible when the item is hovered, focused, or selected
 - Improves clarity of multiple selection interactions
 
 **showSelectAll** (`boolean`, default: `false`)
-
 - When `true` in multiple selection mode, displays a "Select All" option in the header
 - The checkbox shows three states: unchecked (none selected), indeterminate (some selected), checked (all selected)
 - Only works with `selectionMode="multiple"`
 
 **selectAllLabel** (`ReactNode`, default: `'Select All'`)
-
 - Custom label for the "Select All" option
 - Only used when `showSelectAll={true}`
 
 **allValueProps** (`Partial<CubeItemProps>`)
-
 - Props to customize the styling and behavior of the "Select All" option
 - Accepts any Item props like `styles`, `icon`, etc.
 
 **disallowEmptySelection** (`boolean`, default: `false`)
-
 - When `true`, prevents the user from deselecting the last selected item
 - Ensures at least one item is always selected in single selection mode
 
 **allowDuplicateSelectionEvents** (`boolean`, default: `false`)
-
 - When `true`, `onSelectionChange` fires even when the new selection equals the current one (React Stately suppresses such duplicate events by default)
 - Used by popover-based wrappers (Picker, FilterPicker) together with `disallowEmptySelection` to close the popover when the user re-selects the current item
 
 **disableSelectionToggle** (`boolean`, default: `false`)
-
 - When `true`, clicking an already-selected item keeps it selected instead of toggling it off
 - Useful when embedding ListBox inside components like ComboBox
 
 **disabledKeys** (`Key[]`)
-
 - Array of keys for items that should be disabled
 - Disabled items cannot be selected and are visually distinguished
 
 ### Visual Styling
 
 **shape** (`'card' | 'plain' | 'popover'`, default: `'card'`)
-
 - Controls the visual styling of the ListBox container
 - `card`: Standard card styling with border and margin (default)
 - `plain`: No border, no margin, no radius - suitable for embedded use
@@ -183,47 +172,39 @@ The `mods` property accepts the following modifiers you can override:
 ### Focus and Interaction
 
 **focusOnHover** (`boolean`, default: `true`)
-
 - When `true`, moving the pointer over an option will move DOM focus to that option
 - Set to `false` for components that keep DOM focus outside (e.g., searchable FilterListBox)
 
 **shouldUseVirtualFocus** (`boolean`, default: `false`)
-
 - When `true`, uses virtual focus for keyboard navigation
 - DOM focus stays outside individual option elements (useful for searchable lists)
 
 **shouldFocusWrap** (`boolean`, default: `false`)
-
 - When `true`, keyboard navigation wraps around when reaching the end of the list
 
 ### Event Handlers
 
 **onSelectionChange** (`(key: Key | null | 'all' | Key[]) => void`)
-
 - Callback fired when selection changes
 - In single mode: receives a single key or `null`
 - In multiple mode: receives an array of keys or `'all'` for select all
 
 **onEscape** (`() => void`)
-
 - Callback fired when the user presses Escape key
 - When provided, prevents React Aria's default Escape behavior (selection reset)
 - Useful for closing parent overlays
 
 **onOptionClick** (`(key: Key) => void`)
-
 - Callback fired when an option is clicked (not on the checkbox area in checkable mode)
 - Used by FilterPicker to close the popover on non-checkbox clicks
 
 ### Advanced
 
 **stateRef** (`RefObject<any>`)
-
 - Ref to access the internal ListState instance
 - Allows parent components to access selection state and other list functionality
 
 **listRef** (`RefObject<HTMLUListElement>`)
-
 - Ref for accessing the list DOM element
 
 ## Sub-components
@@ -254,16 +235,16 @@ ListBox.Item is built using [Item](../content/Item.md), which provides rich layo
 
 ```jsx
 <ListBox label="Team Members" selectionMode="multiple">
-  <ListBox.Item
-    key="user1"
+  <ListBox.Item 
+    key="user1" 
     icon={<IconUser />}
     description="Product Manager"
     suffix="Online"
   >
     Alice Johnson
   </ListBox.Item>
-  <ListBox.Item
-    key="user2"
+  <ListBox.Item 
+    key="user2" 
     icon={<IconUser />}
     description="Senior Developer"
     rightIcon={<IconBadge />}
@@ -310,14 +291,14 @@ Groups related items together with an optional heading.
 
 ```jsx
 <ListBox label="Choose a framework" selectionMode="single">
-  <ListBox.Item
-    key="react"
+  <ListBox.Item 
+    key="react" 
     description="A JavaScript library for building user interfaces"
   >
     React
   </ListBox.Item>
-  <ListBox.Item
-    key="vue"
+  <ListBox.Item 
+    key="vue" 
     description="The Progressive JavaScript Framework"
   >
     Vue.js
@@ -690,7 +671,6 @@ const [keyOrder, setKeyOrder] = useState([
 ## Best Practices
 
 1. **Do**: Provide clear, descriptive labels for options
-
    ```jsx
    <ListBox.Item key="react" description="JavaScript library for UIs">
      React
@@ -698,7 +678,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 2. **Don't**: Use ListBox for very large datasets without considering virtualization
-
    ```jsx
    // ✅ Virtualization is automatic for lists without sections
    <ListBox height="300px">
@@ -707,7 +686,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 3. **Do**: Use sections to organize related options
-
    ```jsx
    <ListBox.Section title="Frontend Frameworks">
      <ListBox.Item key="react">React</ListBox.Item>
@@ -715,7 +693,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 4. **Do**: Use `isCheckable` for clearer multiple selection UI
-
    ```jsx
    <ListBox selectionMode="multiple" isCheckable={true}>
      {/* Checkboxes make the selection state obvious */}
@@ -723,7 +700,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 5. **Do**: Use `showSelectAll` for efficient multiple selection from lists
-
    ```jsx
    <ListBox selectionMode="multiple" isCheckable={true} showSelectAll selectAllLabel="Select All">
      {/* Easy bulk selection with visual feedback */}
@@ -731,7 +707,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 6. **Do**: Use `textValue` for complex option content
-
    ```jsx
    <ListBox.Item key="item" textValue="Basic Plan - Free">
      <Space gap="1x" flow="column">
@@ -742,7 +717,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 7. **Do**: Leverage Item features for rich content
-
    ```jsx
    <ListBox.Item
      key="admin"
@@ -812,4 +786,4 @@ const items = Array.from({ length: 1000 }, (_, i) => ({
 - [Select](./Select.md) - Dropdown selection without persistent visibility
 - [ComboBox](./ComboBox.md) - Dropdown with text input and search
 - [RadioGroup](./RadioGroup.md) - Single selection with radio buttons
-- [CheckboxGroup](./Checkbox.md) - Multiple selection with checkboxes
+- [CheckboxGroup](./Checkbox.md) - Multiple selection with checkboxes 

package/docs/components/fields/NumberInput.md

@@ -53,7 +53,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root element of the component.
 
 **Sub-elements:**
-
 - `InputWrapper` – container around the input field
 - `Prefix` – wrapper around prefix content
 - `Suffix` – wrapper around suffix content
@@ -158,13 +157,11 @@ The `mods` prop accepts the following modifiers you can override:
 ## Best Practices
 
 1. **Do**: Provide clear labels and helpful placeholder text
-
    ```jsx
    <NumberInput label="Quantity" placeholder="0" />
    ```
 
 2. **Don't**: Use placeholder text as the only label
-
    ```jsx
    {/* Avoid this */}
    <NumberInput placeholder="Enter a number" />

package/docs/components/fields/PasswordInput.md

@@ -47,7 +47,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root wrapper element of the component.
 
 **Sub-elements:**
-
 - `Prefix` - Element displayed before the input
 - `Suffix` - Element displayed after the input (contains toggle button)
 - `State` - Container for validation state indicators
@@ -187,7 +186,6 @@ The `mods` property accepts the following modifiers you can override:
 ## Best Practices
 
 1. **Do**: Provide clear password requirements and feedback
-
    ```jsx
    <PasswordInput
      label="New Password"
@@ -198,7 +196,6 @@ The `mods` property accepts the following modifiers you can override:
    ```
 
 2. **Don't**: Use password input for non-sensitive data
-
    ```jsx
    <PasswordInput label="Username" /> {/* Use TextInput instead */}
    ```

package/docs/components/fields/PeriodPicker.md

@@ -1,17 +1,24 @@
 # Period Pickers
 
-`WeekPicker`, `MonthPicker`, `QuarterPicker`, and `YearPicker` let users select a whole calendar period instead of a specific day. They mirror Ant Design's `DatePicker picker="week|month|quarter|year"` feature, but are exposed as four dedicated components that share a single implementation.
+`WeekPicker`, `MonthPicker`, `QuarterPicker`, and `YearPicker` let users select a
+whole calendar period instead of a specific day. They mirror Ant Design's
+`DatePicker picker="week|month|quarter|year"` feature, but are exposed as four
+dedicated components that share a single implementation.
 
-The value is always a single `CalendarDate` (from `@internationalized/date`) **snapped to the start of the chosen period**:
+The value is always a single `CalendarDate` (from `@internationalized/date`)
+**snapped to the start of the chosen period**:
 
 - **Week** → the first day of the week (locale-aware)
 - **Month** → the 1st of the month
 - **Quarter** → the 1st of the first month of the quarter
 - **Year** → January 1st
 
-The field renders a compact label for the selected period (`2026-W33`, `2026-08`, `2026-Q3`, `2026`). Use `formatValue` to override it.
+The field renders a compact label for the selected period (`2026-W33`, `2026-08`,
+`2026-Q3`, `2026`). Use `formatValue` to override it.
 
-In the month and quarter panels the year in the header is a button that opens a year list, so picking a period several years away takes two clicks instead of paging through the arrows.
+In the month and quarter panels the year in the header is a button that opens a
+year list, so picking a period several years away takes two clicks instead of
+paging through the arrows.
 
 ## When to Use
 
@@ -40,7 +47,8 @@ In the month and quarter panels the year in the header is a button that opens a
 - **`onChange`** `(value: DateValue | null) => void` — Fired when the selected period changes
 - **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
 
-`WeekPicker`, `MonthPicker`, `QuarterPicker` and `YearPicker` are thin wrappers that pin `picker`; everything else is identical.
+`WeekPicker`, `MonthPicker`, `QuarterPicker` and `YearPicker` are thin wrappers
+that pin `picker`; everything else is identical.
 
 ### Base Properties
 
@@ -80,7 +88,8 @@ These properties allow direct style application without using the `styles` prop:
 
 ### Limited range
 
-Periods that fall entirely outside `minValue` / `maxValue` are disabled, and the navigation arrows stop at the edge of the range.
+Periods that fall entirely outside `minValue` / `maxValue` are disabled, and the
+navigation arrows stop at the edge of the range.
 
 ## Accessibility
 
@@ -96,7 +105,8 @@ Periods that fall entirely outside `minValue` / `maxValue` are disabled, and the
 ### Screen Reader Support
 
 - The panel is a `grid` labelled `Months`, `Quarters` or `Years`
-- The trigger is described by the field's current value, so the selection is announced along with the button
+- The trigger is described by the field's current value, so the selection is
+  announced along with the button
 
 ## Related Components
 

package/docs/components/fields/Picker.md

@@ -80,7 +80,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root wrapper element and the trigger button of the Picker component.
 
 **Sub-elements:**
-
 - None
 
 #### triggerStyles
@@ -88,7 +87,6 @@ Customizes the root wrapper element and the trigger button of the Picker compone
 Customizes the DialogTrigger wrapper that contains the trigger button and manages the popover.
 
 **Sub-elements:**
-
 - None
 
 #### listBoxStyles
@@ -96,9 +94,8 @@ Customizes the DialogTrigger wrapper that contains the trigger button and manage
 Customizes the ListBox component styles within the popover. See [ListBox documentation](./ListBox.md) for available sub-elements.
 
 **Sub-elements:**
-
 - `Label` - Item label text
-- `Description` - Item description text
+- `Description` - Item description text  
 - `Content` - Item content wrapper
 - `Checkbox` - Checkbox element in multiple selection mode
 - `CheckboxWrapper` - Wrapper around checkbox
@@ -108,7 +105,6 @@ Customizes the ListBox component styles within the popover. See [ListBox documen
 Customizes the popover Dialog that contains the ListBox. See [Dialog documentation](../overlays/Dialog.md) for available sub-elements.
 
 **Sub-elements:**
-
 - None for Dialog in popover mode
 
 #### listStyles
@@ -179,18 +175,17 @@ See [Item documentation](../content/Item.md) for the complete API. Common proper
 #### Examples with Rich Items
 
 **With Icons and Descriptions:**
-
 ```jsx
 <Picker label="Team Selection" selectionMode="single">
-  <Picker.Item
-    key="active"
+  <Picker.Item 
+    key="active" 
     icon={<IconUsers />}
     description="All active team members"
   >
     Active Users
   </Picker.Item>
-  <Picker.Item
-    key="admins"
+  <Picker.Item 
+    key="admins" 
     icon={<IconShield />}
     description="Admin users only"
   >
@@ -200,17 +195,16 @@ See [Item documentation](../content/Item.md) for the complete API. Common proper
 ```
 
 **With Prefix and Suffix:**
-
 ```jsx
 <Picker label="Select Plan" selectionMode="single">
-  <Picker.Item
+  <Picker.Item 
     key="free"
     prefix={<Badge>Free</Badge>}
     suffix="$0/mo"
   >
     Basic Plan
   </Picker.Item>
-  <Picker.Item
+  <Picker.Item 
     key="pro"
     prefix={<Badge type="primary">Pro</Badge>}
     suffix="$29/mo"
@@ -280,14 +274,12 @@ For large datasets or dynamic content, use the `items` prop with a render functi
 ```
 
 **Key Benefits:**
-
 - **Virtualization**: Automatically enabled for large lists without sections
 - **Performance**: Only renders visible items in the DOM
 - **Dynamic Content**: Perfect for data fetched from APIs or changing datasets
 - **Memory Efficient**: Handles thousands of items smoothly
 
 **When to Use:**
-
 - Lists with 50+ items
 - Dynamic data from APIs
 - Content that changes frequently
@@ -328,8 +320,8 @@ Control the color scheme with the `theme` prop:
 Standard single-selection picker with a placeholder and label.
 
 ```jsx
-<Picker
-  label="Favorite Fruit"
+<Picker 
+  label="Favorite Fruit" 
   placeholder="Select a fruit"
   selectionMode="single"
 >
@@ -468,7 +460,7 @@ const categories = [
 Picker supports three sizes: small, medium (default), and large.
 
 ```jsx
-<Picker
+<Picker 
   size="small"
   label="Small Picker"
   placeholder="Select a fruit"
@@ -477,7 +469,7 @@ Picker supports three sizes: small, medium (default), and large.
   <Picker.Item key="banana">Banana</Picker.Item>
 </Picker>
 
-<Picker
+<Picker 
   size="medium"
   label="Medium Picker"
   placeholder="Select a fruit"
@@ -486,7 +478,7 @@ Picker supports three sizes: small, medium (default), and large.
   <Picker.Item key="banana">Banana</Picker.Item>
 </Picker>
 
-<Picker
+<Picker 
   size="large"
   label="Large Picker"
   placeholder="Select a fruit"
@@ -560,7 +552,6 @@ The Picker component is built with React Aria hooks and provides comprehensive a
 - **`Space`** or **`Enter`** — Selects the focused item (single mode closes popover automatically)
 
 **In the popover:**
-
 - Arrow keys navigate through items
 - Home/End keys jump to first/last item
 - Type-ahead: typing characters focuses matching items
@@ -590,30 +581,26 @@ The following ARIA attributes are automatically managed by React Aria and do not
 ### Best Practices for Accessibility
 
 1. **Always provide a label**: Use the `label` prop or `aria-label` for screen reader users
-
    ```jsx
    <Picker label="Select Category">...</Picker>
    ```
 
 2. **Use meaningful placeholders**: Placeholders should describe the expected selection
-
    ```jsx
    <Picker placeholder="Choose a category" label="Category">...</Picker>
    ```
 
 3. **Provide help text**: Use `description` for additional context
-
    ```jsx
-   <Picker
+   <Picker 
      label="Priority"
      description="Select the task priority level"
    >...</Picker>
    ```
 
 4. **Handle validation properly**: Use the `isInvalid` / `isValid` and `errorMessage` props
-
    ```jsx
-   <Picker
+   <Picker 
      isInvalid
      message="Please select an option"
    >...</Picker>
@@ -629,10 +616,9 @@ The following ARIA attributes are automatically managed by React Aria and do not
 ## Best Practices
 
 1. **Do**: Provide clear, descriptive labels and placeholders
-
    ```jsx
-   <Picker
-     label="Product Category"
+   <Picker 
+     label="Product Category" 
      placeholder="Choose a category..."
      selectionMode="single"
    >
@@ -642,13 +628,12 @@ The following ARIA attributes are automatically managed by React Aria and do not
    ```
 
 2. **Don't**: Use overly long option texts that will be truncated
-
    ```jsx
    // Avoid
    <Picker.Item key="long">
      This is an extremely long option text that will be truncated and hard to read
    </Picker.Item>
-
+   
    // Instead, use description
    <Picker.Item key="short" description="Additional details here">
      Short Label
@@ -656,7 +641,6 @@ The following ARIA attributes are automatically managed by React Aria and do not
    ```
 
 3. **Do**: Use sections for logical grouping
-
    ```jsx
    <Picker label="Select Food" selectionMode="single">
      <Picker.Section title="Fruits">
@@ -669,7 +653,6 @@ The following ARIA attributes are automatically managed by React Aria and do not
    ```
 
 4. **Do**: Use the `items` prop for large datasets to enable virtualization
-
    ```jsx
    <Picker items={largeDataset} label="Select Item">
      {(item) => <Picker.Item key={item.id}>{item.name}</Picker.Item>}
@@ -677,11 +660,10 @@ The following ARIA attributes are automatically managed by React Aria and do not
    ```
 
 5. **Do**: Use `isClearable` for optional single selections
-
    ```jsx
-   <Picker
+   <Picker 
      label="Optional Filter"
-     selectionMode="single"
+     selectionMode="single" 
      isClearable
      placeholder="Choose an option..."
    >
@@ -690,12 +672,11 @@ The following ARIA attributes are automatically managed by React Aria and do not
    ```
 
 6. **Do**: Use `showSelectAll` for efficient multiple selection
-
    ```jsx
-   <Picker
+   <Picker 
      label="Permissions"
-     selectionMode="multiple"
-     showSelectAll
+     selectionMode="multiple" 
+     showSelectAll 
      selectAllLabel="All Permissions"
      isCheckable
    >
@@ -705,11 +686,10 @@ The following ARIA attributes are automatically managed by React Aria and do not
    ```
 
 7. **Do**: Use `isCheckable` in multiple selection mode for clarity
-
    ```jsx
-   <Picker
+   <Picker 
      label="Select Options"
-     selectionMode="multiple"
+     selectionMode="multiple" 
      isCheckable
    >
      <Picker.Item key="option1">Option 1</Picker.Item>
@@ -801,7 +781,7 @@ const renderSummary = ({ selectedLabels, selectedKeys, selectionMode }) => {
   if (selectionMode === 'single') {
     return selectedLabels?.[0] ? `Selected: ${selectedLabels[0]}` : null;
   }
-
+  
   if (!selectedKeys || selectedKeys.length === 0) return null;
   if (selectedKeys === 'all') return 'All items selected';
   if (selectedKeys.length === 1) return selectedLabels[0];
@@ -809,7 +789,7 @@ const renderSummary = ({ selectedLabels, selectedKeys, selectionMode }) => {
   return `${selectedKeys.length} items selected`;
 };
 
-<Picker
+<Picker 
   label="Custom Summary"
   selectionMode="multiple"
   renderSummary={renderSummary}
@@ -842,7 +822,6 @@ For space-constrained interfaces, hide the summary text and show only an icon:
 Full control over selection state for integration with external state management:
 
 **Single Selection:**
-
 ```jsx
 const [selectedKey, setSelectedKey] = useState(null);
 
@@ -858,7 +837,6 @@ const [selectedKey, setSelectedKey] = useState(null);
 ```
 
 **Multiple Selection:**
-
 ```jsx
 const [selectedKeys, setSelectedKeys] = useState([]);
 
@@ -910,18 +888,15 @@ const fruits = [
 ### Optimization Tips
 
 1. **Use Dynamic Content Pattern for Large Lists**
-
    - For lists with 50+ items, use the `items` prop with a render function
    - This enables automatic virtualization for better performance
    - Only visible items are rendered in the DOM
 
 2. **Avoid Sections with Large Datasets**
-
    - Virtualization is disabled when sections are present
    - For large lists, prefer flat structure or use filtering instead
 
 3. **Provide `textValue` for Complex Content**
-
    - When items contain complex JSX, provide a `textValue` prop
    - This helps with accessibility and potential search functionality
 
@@ -935,7 +910,7 @@ Virtualization is automatically enabled when using the `items` prop without sect
 
 ```jsx
 // ✅ Virtualized - excellent performance with thousands of items
-<Picker
+<Picker 
   items={thousandsOfItems}
   label="Large Dataset"
 >
@@ -959,8 +934,8 @@ Optimize complex item content with the `textValue` prop for better accessibility
 ```jsx
 <Picker label="Select User" items={users}>
   {(user) => (
-    <Picker.Item
-      key={user.id}
+    <Picker.Item 
+      key={user.id} 
       textValue={`${user.name} - ${user.role}`}
     >
       <UserCard user={user} />