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

package/docs/components/fields/CommandTextArea.md

@@ -1,6 +1,9 @@
 # CommandTextArea
 
-A multiline free-form field with inline token autocomplete. Typing a configured trigger such as `/` or `@` opens suggestions at the caret; choosing one inserts its literal value into the text and fires `onCommand`. The field value remains the complete textarea string rather than a selected option key.
+A multiline free-form field with inline token autocomplete. Typing a configured
+trigger such as `/` or `@` opens suggestions at the caret; choosing one inserts
+its literal value into the text and fires `onCommand`. The field value remains
+the complete textarea string rather than a selected option key.
 
 ## When to Use
 
@@ -36,13 +39,34 @@ Choose a different component when the interaction has another outcome:
 - **`rows`** `number` (default: `3`) — Visible rows.
 - **`maxRows`** `number` (default: `10`) — Max visible rows when `autoSize` is true.
 
-Each option's value is the **literal string to insert**. For commands, set the item's `textValue` (and `key`) to the full `/clear` — the slash is part of both the active token and the inserted value, so `/cle` becomes `/clear ` with no duplication. This decouples insertion from the trigger, so non-command autocomplete (e.g. a `@mention` resolving to `@john`) works the same way.
-
-> **What the filter matches.** The trigger char is stripped from the active token before matching (so `/co` searches for `co`), and the query is matched against each option's `textValue`, its plain-text `children`, and its plain-text `description`. This means an option can match by its description even though the description doesn't contain the trigger char (e.g. typing `/co` keeps `/clear` because its description "Clear conversation" contains "co"). A recommended layout is to put the command in `children` (e.g. `/clear`) and the human-readable text in the `description` prop (e.g. `Clear conversation`), keeping `textValue` equal to the command so it inserts correctly.
-
-The matched substring (the query with the trigger char stripped) is highlighted within each option's plain-text `children` **and** `description`, so wherever the query matched is visible.
-
-> **Popover anchors to the caret.** The autocomplete popover tracks the text caret on both axes — it opens at the caret's horizontal position and on the caret's current line (not pinned to the textarea's top/bottom edge). This matters for multiline inputs, where the caret can be on any line. The popover is clamped to the viewport, so it flips or shifts when the caret is near an edge. `direction` still controls whether it prefers to open above (`top`) or below (`bottom`) the caret.
+Each option's value is the **literal string to insert**. For commands, set the
+item's `textValue` (and `key`) to the full `/clear` — the slash is part of both
+the active token and the inserted value, so `/cle` becomes `/clear ` with no
+duplication. This decouples insertion from the trigger, so non-command
+autocomplete (e.g. a `@mention` resolving to `@john`) works the same way.
+
+> **What the filter matches.** The trigger char is stripped from the active
+> token before matching (so `/co` searches for `co`), and the query is matched
+> against each option's `textValue`, its plain-text `children`, and its
+> plain-text `description`. This means an option can match by its description
+> even though the description doesn't contain the trigger char (e.g. typing
+> `/co` keeps `/clear` because its description "Clear conversation" contains
+> "co"). A recommended layout is to put the command in `children` (e.g.
+> `/clear`) and the human-readable text in the `description` prop (e.g.
+> `Clear conversation`), keeping `textValue` equal to the command so it inserts
+> correctly.
+
+The matched substring (the query with the trigger char stripped) is highlighted
+within each option's plain-text `children` **and** `description`, so wherever the
+query matched is visible.
+
+> **Popover anchors to the caret.** The autocomplete popover tracks the text
+> caret on both axes — it opens at the caret's horizontal position and on the
+> caret's current line (not pinned to the textarea's top/bottom edge). This
+> matters for multiline inputs, where the caret can be on any line. The popover
+> is clamped to the viewport, so it flips or shifts when the caret is near an
+> edge. `direction` still controls whether it prefers to open above (`top`) or
+> below (`bottom`) the caret.
 
 ### Base Properties
 
@@ -50,7 +74,9 @@ Supports [Base properties](../../BaseProperties.md).
 
 ### Field Properties
 
-Supports all [Field properties](../../FieldProperties.md) (`label`, `name`, `isRequired`, `isDisabled`, `isReadOnly`, `isInvalid`, `description`, `rules`, etc.).
+Supports all [Field properties](../../FieldProperties.md)
+(`label`, `name`, `isRequired`, `isDisabled`, `isReadOnly`, `isInvalid`,
+`description`, `rules`, etc.).
 
 ### Styling Properties
 
@@ -118,7 +144,8 @@ These properties allow direct style application without using the `styles` prop:
 ### Screen Reader Support
 
 - The textarea is announced as a `combobox` with `aria-autocomplete="list"`.
-- `aria-expanded`, `aria-controls`, and `aria-activedescendant` track the popover and the highlighted option.
+- `aria-expanded`, `aria-controls`, and `aria-activedescendant` track the
+  popover and the highlighted option.
 
 ## Integration with Forms
 

package/docs/components/fields/DatePicker.md

@@ -54,7 +54,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root wrapper element of the component.
 
 **Sub-elements:**
-
 - `Prefix` - Element displayed before the input (icon area)
 - `Suffix` - Element displayed after the input (calendar button area)
 - `State` - Container for validation state indicators
@@ -194,7 +193,6 @@ The `mods` property accepts the following modifiers you can override:
 ## Best Practices
 
 1. **Do**: Provide clear labels and format hints
-
    ```jsx
    <DatePicker
      label="Event date"
@@ -203,7 +201,6 @@ The `mods` property accepts the following modifiers you can override:
    ```
 
 2. **Don't**: Use date picker for approximate dates
-
    ```jsx
    <DatePicker label="Approximately when?" /> {/* Use text input instead */}
    ```

package/docs/components/fields/FileInput.md

@@ -41,7 +41,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the root element of the component.
 
 **Sub-elements:**
-
 - `Button` - The clickable button element for file selection
 - `Placeholder` - Text shown when no file is selected
 - `Value` - Text showing the selected file name(s)
@@ -144,7 +143,6 @@ Pass `isValid` or `isInvalid` to tint the border and show the matching state ico
 ## Best Practices
 
 1. **Do**: Provide clear file type and size requirements
-
    ```jsx
    <FileInput
      label="Upload resume"
@@ -154,7 +152,6 @@ Pass `isValid` or `isInvalid` to tint the border and show the matching state ico
    ```
 
 2. **Don't**: Use unclear or missing labels
-
    ```jsx
    <FileInput /> {/* What should be uploaded? */}
    ```

package/docs/components/fields/FilterListBox.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
 
 #### searchInputStyles
@@ -72,7 +71,6 @@ Customizes the root wrapper element of the component.
 Customizes the search input field appearance.
 
 **Sub-elements:**
-
 - `Prefix` - Container for search icon
 - `InputIcon` - The search or loading icon
 
@@ -81,7 +79,6 @@ Customizes the search input field appearance.
 Customizes the list container element that holds the filtered options.
 
 **Sub-elements:**
-
 - Same as ListBox component sub-elements
 
 #### optionStyles
@@ -89,7 +86,6 @@ Customizes the list container element that holds the filtered options.
 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
@@ -101,7 +97,6 @@ Customizes individual option elements.
 Customizes section wrapper elements.
 
 **Sub-elements:**
-
 - Same as ListBox component sub-elements
 
 #### headingStyles
@@ -109,7 +104,6 @@ Customizes section wrapper elements.
 Customizes section heading elements.
 
 **Sub-elements:**
-
 - Same as ListBox component sub-elements
 
 #### listBoxStyles
@@ -121,7 +115,6 @@ Customizes the inner ListBox component.
 Customizes the header area when header prop is provided.
 
 **Sub-elements:**
-
 - None - styles apply directly to the header container
 
 #### footerStyles
@@ -129,7 +122,6 @@ Customizes the header area when header prop is provided.
 Customizes the footer area when footer prop is provided.
 
 **Sub-elements:**
-
 - None - styles apply directly to the footer container
 
 ### Style Properties
@@ -269,14 +261,14 @@ const categories = [
 
 ```jsx
 <FilterListBox label="Choose a fruit" searchPlaceholder="Search fruits...">
-  <FilterListBox.Item
-    key="apple"
+  <FilterListBox.Item 
+    key="apple" 
     description="Crisp and sweet red fruit"
   >
     Apple
   </FilterListBox.Item>
-  <FilterListBox.Item
-    key="banana"
+  <FilterListBox.Item 
+    key="banana" 
     description="Yellow tropical fruit rich in potassium"
   >
     Banana
@@ -349,7 +341,7 @@ const categories = [
 <FilterListBox
   label="Programming Language"
   searchPlaceholder="Type first letters..."
-  filter={(text, search) =>
+  filter={(text, search) => 
     text.toLowerCase().startsWith(search.toLowerCase())
   }
 >
@@ -470,7 +462,6 @@ const categories = [
 ## Best Practices
 
 1. **Do**: Use for lists with more than 10-15 options
-
    ```jsx
    <FilterListBox label="Choose Country" searchPlaceholder="Search countries...">
      {countries.map(country => (
@@ -480,7 +471,6 @@ const categories = [
    ```
 
 2. **Don't**: Use for very small lists (under 5-7 options)
-
    ```jsx
    // ❌ Avoid for small lists - use ListBox instead
    <FilterListBox>
@@ -490,7 +480,6 @@ const categories = [
    ```
 
 3. **Do**: Provide `textValue` for complex option content
-
    ```jsx
    <FilterListBox.Item key="user1" textValue="John Doe john.doe@company.com">
      <Avatar src="/john.jpg" />
@@ -502,11 +491,10 @@ const categories = [
    ```
 
 4. **Do**: Use `showSelectAll` for efficient multiple selection from filtered lists
-
    ```jsx
-   <FilterListBox
-     selectionMode="multiple"
-     showSelectAll
+   <FilterListBox 
+     selectionMode="multiple" 
+     showSelectAll 
      selectAllLabel="Select All Visible"
      searchPlaceholder="Filter items..."
    >
@@ -515,10 +503,9 @@ const categories = [
    ```
 
 5. **Do**: Use `isCheckable` for visual clarity in multiple selection mode
-
    ```jsx
-   <FilterListBox
-     selectionMode="multiple"
+   <FilterListBox 
+     selectionMode="multiple" 
      isCheckable={true}
      searchPlaceholder="Search options..."
    >
@@ -564,7 +551,7 @@ FilterListBox supports custom filter functions for specialized search behavior:
 
 ```jsx
 // Starts-with filter
-const startsWithFilter = (text, search) =>
+const startsWithFilter = (text, search) => 
   text.toLowerCase().startsWith(search.toLowerCase());
 
 // Fuzzy search filter
@@ -572,7 +559,7 @@ const fuzzyFilter = (text, search) => {
   const searchChars = search.toLowerCase().split('');
   const textLower = text.toLowerCase();
   let searchIndex = 0;
-
+  
   for (const char of textLower) {
     if (char === searchChars[searchIndex]) {
       searchIndex++;
@@ -602,7 +589,6 @@ When `allowsCustomValue={true}`, users can add new options by typing:
 ```
 
 Custom values:
-
 - Are automatically added when selected
 - Persist across searches
 - Appear in the list with selected items
@@ -635,7 +621,6 @@ Use `customValueProps` to style existing custom values and `newCustomValueProps`
 ```
 
 **Key differences:**
-
 - `customValueProps` - Applied to custom values that are already selected
 - `newCustomValueProps` - Applied to new custom values appearing when typing in search (merged with `customValueProps`)
 
@@ -670,7 +655,6 @@ const handleSearchChange = useCallback((value) => {
 ```
 
 **How it works:**
-
 - **`filter={false}`** disables client-side filtering so items appear exactly as the server returns them
 - **`searchValue` + `onSearchChange`** give you control over the search input; debounce and fetch on your side
 - **`items`** is reactive — replace it with server results and the list updates automatically
@@ -698,7 +682,6 @@ Use the `onEscape` prop to handle custom behavior when Escape is pressed with em
 ```
 
 **Key behaviors:**
-
 - If search has text: Escape clears the search
 - If search is empty: Escape calls `onEscape` callback
 - Useful for closing parent modals or dialogs
@@ -728,7 +711,6 @@ useEffect(() => {
 ```
 
 **Use cases:**
-
 - Debouncing search input
 - Synchronizing with external UI
 - Tracking search analytics
@@ -756,14 +738,12 @@ const items = Array.from({ length: 1000 }, (_, i) => ({
 ```
 
 **Key features:**
-
 - Automatically enabled for large lists without sections
 - Handles items with varying heights
 - Works seamlessly with filtering
 - Maintains performance with thousands of items
 
 **Limitations:**
-
 - Virtualization is disabled when sections are present
 - For sectioned large lists, consider flattening or alternative approaches
 
@@ -779,8 +759,8 @@ const items = Array.from({ length: 1000 }, (_, i) => ({
 
 ```jsx
 // Optimized for performance
-<FilterListBox.Item
-  key="complex"
+<FilterListBox.Item 
+  key="complex" 
   textValue="John Doe - Senior Developer - Engineering Team"
 >
   <ComplexUserCard user={user} />

package/docs/components/fields/FilterPicker.md

@@ -91,7 +91,6 @@ Supports all [Field properties](../../FieldProperties.md)
 Customizes the main wrapper element of the FilterPicker component.
 
 **Sub-elements:**
-
 - None - styles apply directly to the wrapper
 
 #### triggerStyles
@@ -99,7 +98,6 @@ Customizes the main wrapper element of the FilterPicker component.
 Customizes the trigger button element.
 
 **Sub-elements:**
-
 - None - styles apply directly to the trigger button
 
 #### listBoxStyles
@@ -107,7 +105,6 @@ Customizes the trigger button element.
 Customizes the dropdown list container within the popover.
 
 **Sub-elements:**
-
 - Same as FilterListBox: `Label`, `Description`, `Content`, `Checkbox`, `CheckboxWrapper`
 
 #### popoverStyles
@@ -115,7 +112,6 @@ Customizes the dropdown list container within the popover.
 Customizes the popover dialog that contains the FilterListBox.
 
 **Sub-elements:**
-
 - Same as Dialog component sub-elements
 
 #### searchInputStyles
@@ -189,16 +185,16 @@ For detailed information about all available item properties, see [Item document
 
 ```jsx
 <FilterPicker label="Team Filters" selectionMode="multiple">
-  <FilterPicker.Item
-    key="active-users"
+  <FilterPicker.Item 
+    key="active-users" 
     icon={<IconUsers />}
     description="Filter by active users"
     suffix="12 users"
   >
     Active Users
   </FilterPicker.Item>
-  <FilterPicker.Item
-    key="recent-activity"
+  <FilterPicker.Item 
+    key="recent-activity" 
     icon={<IconClock />}
     description="Recent activity in the last week"
     rightIcon={<IconBadge />}
@@ -283,7 +279,6 @@ const categories = [
 ```
 
 **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
@@ -291,7 +286,6 @@ const categories = [
 - **Selected Items Sorting**: When using the `items` prop, selected items are automatically sorted to the top when the popover reopens (can be controlled with `sortSelectedToTop`)
 
 **When to Use:**
-
 - Lists with 50+ items
 - Dynamic data from APIs
 - Content that changes frequently
@@ -321,8 +315,8 @@ const categories = [
 ### Basic Usage
 
 ```jsx
-<FilterPicker
-  label="Select Options"
+<FilterPicker 
+  label="Select Options" 
   placeholder="Choose items..."
   searchPlaceholder="Search options..."
 >
@@ -494,7 +488,7 @@ Use `isLoadingItems` to indicate that items are currently being fetched. Unlike
   isCheckable={true}
   renderSummary={({ selectedKeys, selectedLabels }) => {
     if (selectedKeys.length === 0) return null;
-    if (selectedKeys.length <= 3)
+    if (selectedKeys.length <= 3) 
       return `${selectedKeys.length} filters: ${selectedLabels.join(', ')}`;
     return `${selectedKeys.length} filters applied`;
   }}
@@ -569,7 +563,6 @@ const [keyOrder, setKeyOrder] = useState([
 ## Best Practices
 
 1. **Do**: Provide clear, descriptive labels for the trigger
-
    ```jsx
    <FilterPicker label="Filter by Category" placeholder="Choose categories...">
      <FilterPicker.Item key="electronics">Electronics</FilterPicker.Item>
@@ -577,7 +570,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 2. **Don't**: Use overly long option texts that will be truncated
-
    ```jsx
    // ❌ Avoid very long option text
    <FilterPicker.Item key="long">
@@ -586,7 +578,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 3. **Do**: Use sections for logical grouping of small to medium lists
-
    ```jsx
    <FilterPicker.Section title="Categories">
      <FilterPicker.Item key="tech">Technology</FilterPicker.Item>
@@ -594,7 +585,6 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 4. **Do**: Use dynamic content pattern for large datasets
-
    ```jsx
    // ✅ For large lists (50+ items)
    <FilterPicker items={largeDataset}>
@@ -603,11 +593,10 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 5. **Do**: Use `showSelectAll` for efficient multiple selection in compact interfaces
-
    ```jsx
-   <FilterPicker
-     selectionMode="multiple"
-     showSelectAll
+   <FilterPicker 
+     selectionMode="multiple" 
+     showSelectAll 
      selectAllLabel="Select All Options"
      placeholder="Choose items..."
    >
@@ -616,10 +605,9 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 6. **Do**: Use `isClearable` when users need to quickly clear selections
-
    ```jsx
-   <FilterPicker
-     isClearable
+   <FilterPicker 
+     isClearable 
      selectionMode="single"
      label="Choose option"
    >
@@ -669,7 +657,7 @@ const renderSummary = ({ selectedLabels, selectedKeys, selectionMode }) => {
   if (selectionMode === 'single') {
     return selectedLabels[0] ? `Selected: ${selectedLabels[0]}` : null;
   }
-
+  
   if (selectedKeys.length === 0) return null;
   if (selectedKeys.length === 1) return selectedLabels[0];
   if (selectedKeys.length <= 3) return selectedLabels.join(', ');
@@ -696,9 +684,8 @@ When `allowsCustomValue={true}`, users can add new options:
 ```
 
 Custom values:
-
 - Are automatically added when typed and selected
-- Persist across popover sessions
+- Persist across popover sessions  
 - Appear in the selection summary
 - Can be removed like any other selection
 
@@ -732,7 +719,6 @@ When using the `items` prop, FilterPicker automatically sorts selected items to
 ```
 
 **Key behaviors:**
-
 - Sorting only works when using the `items` prop
 - Selected items move to the top when the popover reopens
 - Within sections, selected items sort to the top of their section
@@ -771,7 +757,6 @@ Add a clear button to quickly reset selection:
 ```
 
 The clear button:
-
 - Appears in the `rightIcon` slot when there's a selection
 - Only shows when `isClearable={true}` and a selection exists
 - Closes the popover when clicked
@@ -820,7 +805,6 @@ const handleSearchChange = useCallback((value) => {
 ```
 
 **How it works:**
-
 - **`filter={false}`** disables client-side filtering so items are shown exactly as the server returns them
 - **`searchValue` + `onSearchChange`** give you control over the search input; debounce and fetch on your side
 - **`items`** is a reactive prop — replace it with server results and the list updates automatically
@@ -831,7 +815,6 @@ const handleSearchChange = useCallback((value) => {
 - **Reset on close** — use `onOpenChange` to restore the initial item set and clear the search when the popover closes, ensuring the trigger label resolves correctly
 
 **Tips:**
-
 - Debouncing is the consumer's responsibility (300-500ms is typical)
 - During the debounce delay, old items remain visible — if you want instant client-side feedback while waiting, use a filter function instead of `false`
 
@@ -868,8 +851,8 @@ When using the dynamic content pattern (`items` prop) without sections, FilterPi
 
 ```jsx
 // Optimized for performance
-<FilterPicker.Item
-  key="complex"
+<FilterPicker.Item 
+  key="complex" 
   textValue="John Doe - Senior Developer"
 >
   <UserCard user={user} />

package/docs/components/fields/HueSlider.md

@@ -96,8 +96,8 @@ The `mods` property accepts the following modifiers you can override:
 ### Custom Value Formatting
 
 ```jsx
-<HueSlider
-  label="Hue"
+<HueSlider 
+  label="Hue" 
   defaultValue={180}
   getValueLabel={(val) => `${val}°`}
 />
@@ -129,9 +129,9 @@ function ColorPicker() {
 ### Vertical Orientation
 
 ```jsx
-<HueSlider
-  orientation="vertical"
-  fieldStyles={{ height: '200px' }}
+<HueSlider 
+  orientation="vertical" 
+  fieldStyles={{ height: '200px' }} 
 />
 ```