fix(FilterListBox): support for items prop

Author: tenphi

src/components/actions/Button/Button.tsx

@@ -117,18 +117,16 @@ export const DEFAULT_BUTTON_STYLES = {
 
   ButtonIcon: {
     width: 'max-content',
-    margin: {
-      '': 0,
-      ':first-child': '-.5x left',
-      ':last-child': '-.5x right',
-      '(:first-child & :last-child) | [data-size="xsmall"]': 0,
-    },
-    placeSelf: {
-      '': 'center',
-      ':first-child': 'center start',
-      ':last-child': 'center end',
-      ':first-child & :last-child': 'center',
-    },
+  },
+
+  '& [data-element="ButtonIcon"]:first-child:not(:last-child)': {
+    marginLeft: '-.5x',
+    placeSelf: 'center start',
+  },
+
+  '& [data-element="ButtonIcon"]:last-child:not(:first-child)': {
+    marginRight: '-.5x',
+    placeSelf: 'center end',
   },
 } as const;
 

src/components/fields/FilterListBox/FilterListBox.docs.mdx

@@ -157,6 +157,24 @@ The `mods` property accepts the following modifiers you can override:
 </FilterListBox>
 ```
 
+### Multiple Selection with Select All
+
+<Story of={FilterListBoxStories.WithSelectAll} />
+
+```jsx
+<FilterListBox
+  label="Select permissions"
+  selectionMode="multiple"
+  showSelectAll={true}
+  selectAllLabel="All Permissions"
+  searchPlaceholder="Search permissions..."
+>
+  <FilterListBox.Item key="read">Read</FilterListBox.Item>
+  <FilterListBox.Item key="write">Write</FilterListBox.Item>
+  <FilterListBox.Item key="execute">Execute</FilterListBox.Item>
+</FilterListBox>
+```
+
 ### With Descriptions
 
 <Story of={FilterListBoxStories.WithDescriptions} />
@@ -322,9 +340,21 @@ The `mods` property accepts the following modifiers you can override:
    </FilterListBox.Item>
    ```
 
-4. **Performance**: Use custom filter functions for specialized search needs
-5. **UX**: Provide meaningful empty state messages
-6. **Accessibility**: Always provide clear search placeholders
+4. **Do**: Use `showSelectAll` for efficient multiple selection from filtered lists
+   ```jsx
+   <FilterListBox 
+     selectionMode="multiple" 
+     showSelectAll 
+     selectAllLabel="Select All Visible"
+     searchPlaceholder="Filter items..."
+   >
+     {/* many items */}
+   </FilterListBox>
+   ```
+
+5. **Performance**: Use custom filter functions for specialized search needs
+6. **UX**: Provide meaningful empty state messages
+7. **Accessibility**: Always provide clear search placeholders
 
 ## Integration with Forms
 

src/components/fields/FilterListBox/FilterListBox.stories.tsx

@@ -1220,13 +1220,14 @@ export const VirtualizedList: StoryFn<CubeFilterListBoxProps<any>> = (args) => {
         selectedKeys={selectedKeys}
         height="300px"
         overflow="auto"
+        items={items}
         onSelectionChange={(keys) => setSelectedKeys(keys as string[])}
       >
-        {items.map((item) => (
+        {(item) => (
           <FilterListBox.Item key={item.id} description={item.description}>
             {item.name}
           </FilterListBox.Item>
-        ))}
+        )}
       </FilterListBox>
 
       <Text>

src/components/fields/FilterListBox/FilterListBox.tsx

@@ -215,14 +215,48 @@ export const FilterListBox = forwardRef(function FilterListBox<
     headerStyles,
     footerStyles,
     listBoxStyles,
-    children,
+    items,
+    children: renderChildren,
     onEscape,
     isCheckable,
     onOptionClick,
     selectionMode = 'single',
     ...otherProps
   } = props;
 
+  // Preserve the original `children` (may be a render function) before we
+  // potentially overwrite it.
+  let children: ReactNode = renderChildren as ReactNode;
+
+  const renderFn = renderChildren as unknown;
+
+  if (items && typeof renderFn === 'function') {
+    try {
+      const itemsArray = Array.from(items as Iterable<any>);
+      // Execute the render function for each item to obtain <Item/> / <Section/> nodes.
+      children = itemsArray.map((item, idx) => {
+        const rendered = (renderFn as (it: any) => ReactNode)(item);
+        // Ensure every element has a stable key: rely on the user-provided key
+        // inside the render function, otherwise fall back to the item itself or
+        // the index. This mirrors React Aria examples where the render function
+        // is expected to set keys, but we add a fallback for robustness.
+        if (
+          React.isValidElement(rendered) &&
+          (rendered as ReactElement).key == null
+        ) {
+          return React.cloneElement(rendered as ReactElement, {
+            key: (rendered as any)?.key ?? item?.key ?? idx,
+          });
+        }
+
+        return rendered as ReactNode;
+      });
+    } catch {
+      // If conversion fails for some reason, we silently ignore and proceed
+      // with the original children value so we don't break runtime.
+    }
+  }
+
   // Collect original option keys to avoid duplicating them as custom values.
   const originalKeys = useMemo(() => {
     const keys = new Set<string>();
@@ -881,6 +915,7 @@ export const FilterListBox = forwardRef(function FilterListBox<
           mods={mods}
           size={size}
           isCheckable={isCheckable}
+          items={items as any}
           onSelectionChange={handleSelectionChange}
           onEscape={onEscape}
           onOptionClick={handleOptionClick}

src/components/fields/FilterPicker/FilterPicker.docs.mdx

@@ -165,6 +165,24 @@ The `mods` property accepts the following modifiers you can override:
 </FilterPicker>
 ```
 
+### Multiple Selection with Select All
+
+<Story of={FilterPickerStories.WithSelectAll} />
+
+```jsx
+<FilterPicker
+  label="Select permissions"
+  placeholder="Choose permissions"
+  selectionMode="multiple"
+  showSelectAll={true}
+  selectAllLabel="All Permissions"
+>
+  <FilterPicker.Item key="read">Read</FilterPicker.Item>
+  <FilterPicker.Item key="write">Write</FilterPicker.Item>
+  <FilterPicker.Item key="execute">Execute</FilterPicker.Item>
+</FilterPicker>
+```
+
 ### Custom Summary
 
 <Story of={FilterPickerStories.CustomSummary} />
@@ -365,9 +383,21 @@ The `mods` property accepts the following modifiers you can override:
    </FilterPicker.Section>
    ```
 
-4. **Accessibility**: Always provide meaningful labels and placeholders
-5. **Performance**: Use `textValue` prop for complex option content
-6. **UX**: Consider using `isCheckable` for multiple selection clarity
+4. **Do**: Use `showSelectAll` for efficient multiple selection in compact interfaces
+   ```jsx
+   <FilterPicker 
+     selectionMode="multiple" 
+     showSelectAll 
+     selectAllLabel="Select All Options"
+     placeholder="Choose items..."
+   >
+     {/* many items */}
+   </FilterPicker>
+   ```
+
+5. **Accessibility**: Always provide meaningful labels and placeholders
+6. **Performance**: Use `textValue` prop for complex option content
+7. **UX**: Consider using `isCheckable` for multiple selection clarity
 
 ## Integration with Forms
 

src/components/fields/FilterPicker/FilterPicker.stories.tsx

@@ -1518,17 +1518,18 @@ export const VirtualizedList: Story = {
         <FilterPicker
           {...args}
           selectedKeys={selectedKeys}
+          items={items}
           onSelectionChange={(keys) => setSelectedKeys(keys as string[])}
         >
-          {items.map((item) => (
+          {(item) => (
             <FilterPicker.Item
               key={item.id}
               textValue={item.name}
               description={item.description}
             >
               {item.name}
             </FilterPicker.Item>
-          ))}
+          )}
         </FilterPicker>
 
         <Text preset="t4" color="#dark.60">

src/components/fields/FilterPicker/FilterPicker.tsx

@@ -196,6 +196,7 @@ export const FilterPicker = forwardRef(function FilterPicker<T extends object>(
     focusOnHover,
     showSelectAll,
     selectAllLabel,
+    items,
     header,
     footer,
     headerStyles,
@@ -742,6 +743,7 @@ export const FilterPicker = forwardRef(function FilterPicker<T extends object>(
             <FocusScope restoreFocus>
               <FilterListBox
                 autoFocus
+                items={items}
                 // Pass an aria-label so the internal ListBox is properly labeled and React Aria doesn't warn.
                 aria-label={`${props['aria-label'] ?? props.label ?? ''} Picker`}
                 selectedKey={

src/components/fields/ListBox/ListBox.docs.mdx

@@ -168,6 +168,23 @@ The `mods` property accepts the following modifiers you can override:
 </ListBox>
 ```
 
+### Multiple Selection with Select All
+
+<Story of={ListBoxStories.WithSelectAll} />
+
+```jsx
+<ListBox
+  label="Select permissions"
+  selectionMode="multiple"
+  showSelectAll={true}
+  selectAllLabel="All Permissions"
+>
+  <ListBox.Item key="read">Read</ListBox.Item>
+  <ListBox.Item key="write">Write</ListBox.Item>
+  <ListBox.Item key="execute">Execute</ListBox.Item>
+</ListBox>
+```
+
 ### With Header and Footer
 
 <Story of={ListBoxStories.WithHeaderAndFooter} />
@@ -294,9 +311,16 @@ const [selectedKey, setSelectedKey] = useState('apple');
    </ListBox.Section>
    ```
 
-4. **Accessibility**: Always provide meaningful labels and descriptions
-5. **Performance**: Use virtualization for lists with 50+ items
-6. **UX**: Consider FilterListBox for searchable lists with many options
+4. **Do**: Use `showSelectAll` for efficient multiple selection from large lists
+   ```jsx
+   <ListBox selectionMode="multiple" showSelectAll selectAllLabel="Select All Items">
+     {/* many items */}
+   </ListBox>
+   ```
+
+5. **Accessibility**: Always provide meaningful labels and descriptions
+6. **Performance**: Use virtualization for lists with 50+ items
+7. **UX**: Consider FilterListBox for searchable lists with many options
 
 ## Integration with Forms