@cube-dev/ui-kit 0.0.0-canary-b67433b → 0.0.0-canary-41b773a

package/docs/components/fields/FilterListBox.md

@@ -230,6 +230,31 @@ Groups related items together with an optional heading.
 </FilterListBox>
 ```
 
+### With Sections (Dynamic)
+
+Sections and items can be defined dynamically using the `items` prop with a render function. Pass hierarchical data where each section contains a `children` array.
+
+```jsx
+const categories = [
+  { name: 'Fruits', children: [
+    { key: 'apple', label: 'Apple' },
+    { key: 'banana', label: 'Banana' },
+  ]},
+  { name: 'Vegetables', children: [
+    { key: 'carrot', label: 'Carrot' },
+    { key: 'broccoli', label: 'Broccoli' },
+  ]},
+];
+
+<FilterListBox label="Choose an ingredient" searchPlaceholder="Search ingredients..." items={categories}>
+  {(category) => (
+    <FilterListBox.Section key={category.name} title={category.name} items={category.children}>
+      {(item) => <FilterListBox.Item key={item.key}>{item.label}</FilterListBox.Item>}
+    </FilterListBox.Section>
+  )}
+</FilterListBox>
+```
+
 ### With Descriptions
 
 ```jsx

package/docs/components/fields/FilterPicker.md

@@ -234,6 +234,40 @@ For large datasets or dynamic content, use the `items` prop with a render functi
 </FilterPicker>
 ```
 
+### Dynamic Sections Pattern
+
+For hierarchical data with sections, use the `items` prop with nested render functions. Each section contains a `children` array of items.
+
+```jsx
+const categories = [
+  { name: 'Fruits', children: [
+    { key: 'apple', label: 'Apple' },
+    { key: 'banana', label: 'Banana' },
+  ]},
+  { name: 'Vegetables', children: [
+    { key: 'carrot', label: 'Carrot' },
+    { key: 'broccoli', label: 'Broccoli' },
+  ]},
+];
+
+<FilterPicker
+  label="Choose items"
+  placeholder="Choose items..."
+  searchPlaceholder="Search..."
+  items={categories}
+>
+  {(category) => (
+    <FilterPicker.Section key={category.name} title={category.name} items={category.children}>
+      {(item) => (
+        <FilterPicker.Item key={item.key} textValue={item.label}>
+          {item.label}
+        </FilterPicker.Item>
+      )}
+    </FilterPicker.Section>
+  )}
+</FilterPicker>
+```
+
 **Key Benefits:**
 - **Virtualization**: Automatically enabled for large lists without sections
 - **Performance**: Only renders visible items in the DOM

package/docs/components/fields/ListBox.md

@@ -313,6 +313,31 @@ Groups related items together with an optional heading.
 </ListBox>
 ```
 
+### With Sections (Dynamic)
+
+Sections and items can be defined dynamically using the `items` prop with a render function. Pass hierarchical data where each section contains a `children` array.
+
+```jsx
+const categories = [
+  { name: 'Fruits', children: [
+    { key: 'apple', label: 'Apple' },
+    { key: 'banana', label: 'Banana' },
+  ]},
+  { name: 'Vegetables', children: [
+    { key: 'carrot', label: 'Carrot' },
+    { key: 'broccoli', label: 'Broccoli' },
+  ]},
+];
+
+<ListBox label="Select food items" selectionMode="single" items={categories}>
+  {(category) => (
+    <ListBox.Section key={category.name} title={category.name} items={category.children}>
+      {(item) => <ListBox.Item key={item.key}>{item.label}</ListBox.Item>}
+    </ListBox.Section>
+  )}
+</ListBox>
+```
+
 ### Multiple Selection
 
 ```jsx
@@ -694,15 +719,20 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 
 ### Virtualization
 
-ListBox automatically enables virtualization when:
-- No sections are present (sections disable virtualization)
-- Provides smooth scrolling even with large datasets
-- Only visible items are rendered in the DOM
-- Uses `@tanstack/react-virtual` for efficient rendering
-- Automatically measures item heights for consistent scrolling
-- Supports items with varying heights (descriptions, complex content)
+For large datasets, use the `items` prop with a render function. This enables automatic virtualization — only visible items are rendered in the DOM, providing smooth scrolling even with thousands of items.
+
+```jsx
+const items = Array.from({ length: 1000 }, (_, i) => ({
+  key: `item-${i}`,
+  label: `Item ${i + 1}`,
+}));
+
+<ListBox label="Large Dataset" selectionMode="single" items={items}>
+  {(item) => <ListBox.Item key={item.key}>{item.label}</ListBox.Item>}
+</ListBox>
+```
 
-**Note**: Virtualization is transparent to the user - no configuration needed. It works automatically when you have a flat list without sections.
+**Note**: Virtualization is disabled when sections are present. For very large datasets, prefer a flat list structure.
 
 ### Optimization Tips
 

package/docs/components/fields/Picker.md

@@ -425,6 +425,31 @@ Organize items into logical groups with section headers.
 </Picker>
 ```
 
+### With Sections (Dynamic)
+
+Sections and items can be defined dynamically using the `items` prop with a render function. Pass hierarchical data where each section contains a `children` array.
+
+```jsx
+const categories = [
+  { name: 'Fruits', children: [
+    { key: 'apple', label: 'Apple' },
+    { key: 'banana', label: 'Banana' },
+  ]},
+  { name: 'Vegetables', children: [
+    { key: 'carrot', label: 'Carrot' },
+    { key: 'broccoli', label: 'Broccoli' },
+  ]},
+];
+
+<Picker label="Favorite Food" placeholder="Select a food" items={categories}>
+  {(category) => (
+    <Picker.Section key={category.name} title={category.name} items={category.children}>
+      {(item) => <Picker.Item key={item.key}>{item.label}</Picker.Item>}
+    </Picker.Section>
+  )}
+</Picker>
+```
+
 ### Different Sizes
 
 Picker supports three sizes: small, medium (default), and large.

package/docs/components/fields/Select.md

@@ -386,6 +386,8 @@ Groups related options together with an optional heading.
 
 ### With Sections (Dynamic)
 
+Sections and items can be defined dynamically using the `items` prop with a render function.
+
 ```jsx
 const groups = [
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.0.0-canary-b67433b",
+  "version": "0.0.0-canary-41b773a",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {