@cube-dev/ui-kit 0.166.0 → 0.168.0

package/docs/components/fields/ListBox.md

@@ -64,6 +64,7 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root wrapper element of the component.
 
 **Sub-elements:**
+
 - `ValidationState` - Container for validation and loading indicators
 
 #### listStyles
@@ -75,6 +76,7 @@ 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
@@ -126,42 +128,51 @@ 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
@@ -172,39 +183,47 @@ 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
@@ -235,16 +254,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 />}
@@ -291,14 +310,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
@@ -671,6 +690,7 @@ 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
@@ -678,6 +698,7 @@ 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">
@@ -686,6 +707,7 @@ 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>
@@ -693,6 +715,7 @@ 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 */}
@@ -700,6 +723,7 @@ 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 */}
@@ -707,6 +731,7 @@ 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">
@@ -717,6 +742,7 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 7. **Do**: Leverage Item features for rich content
+
    ```jsx
    <ListBox.Item
      key="admin"
@@ -786,4 +812,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,6 +53,7 @@ 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
@@ -157,11 +158,13 @@ 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,6 +47,7 @@ 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
@@ -186,6 +187,7 @@ 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"
@@ -196,6 +198,7 @@ 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,24 +1,17 @@
 # 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
 
@@ -47,8 +40,7 @@ paging through the arrows.
 - **`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
 
@@ -88,8 +80,7 @@ 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
 
@@ -105,8 +96,7 @@ navigation arrows stop at the edge of the range.
 ### 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,6 +80,7 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root wrapper element and the trigger button of the Picker component.
 
 **Sub-elements:**
+
 - None
 
 #### triggerStyles
@@ -87,6 +88,7 @@ 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
@@ -94,8 +96,9 @@ 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
@@ -105,6 +108,7 @@ 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
@@ -175,17 +179,18 @@ 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"
   >
@@ -195,16 +200,17 @@ 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"
@@ -274,12 +280,14 @@ 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
@@ -320,8 +328,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"
 >
@@ -460,7 +468,7 @@ const categories = [
 Picker supports three sizes: small, medium (default), and large.
 
 ```jsx
-<Picker 
+<Picker
   size="small"
   label="Small Picker"
   placeholder="Select a fruit"
@@ -469,7 +477,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"
@@ -478,7 +486,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"
@@ -552,6 +560,7 @@ 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
@@ -581,26 +590,30 @@ 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>
@@ -616,9 +629,10 @@ 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"
    >
@@ -628,12 +642,13 @@ 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
@@ -641,6 +656,7 @@ 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">
@@ -653,6 +669,7 @@ 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>}
@@ -660,10 +677,11 @@ 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..."
    >
@@ -672,11 +690,12 @@ 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
    >
@@ -686,10 +705,11 @@ 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>
@@ -781,7 +801,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];
@@ -789,7 +809,7 @@ const renderSummary = ({ selectedLabels, selectedKeys, selectionMode }) => {
   return `${selectedKeys.length} items selected`;
 };
 
-<Picker 
+<Picker
   label="Custom Summary"
   selectionMode="multiple"
   renderSummary={renderSummary}
@@ -822,6 +842,7 @@ 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);
 
@@ -837,6 +858,7 @@ const [selectedKey, setSelectedKey] = useState(null);
 ```
 
 **Multiple Selection:**
+
 ```jsx
 const [selectedKeys, setSelectedKeys] = useState([]);
 
@@ -888,15 +910,18 @@ 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
 
@@ -910,7 +935,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"
 >
@@ -934,8 +959,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} />