Skip to content

Commit 5fc8121

Browse files
tenphitenphi
committed
chore: update docs
1 parent 2114fc6 commit 5fc8121

File tree

6 files changed

+311
-12
lines changed

6 files changed

+311
-12
lines changed

‎src/components/actions/Button/Button.stories.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export default {
2929
},
3030
},
3131
size: {
32-
options: ['small', 'medium', 'large'],
32+
options: ['tiny', 'small', 'medium', 'large'],
3333
control: { type: 'radio' },
3434
description: 'Button size',
3535
table: {

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -241,7 +241,8 @@ const memoizedFilter = useCallback((text, search) => {
241241

242242
## Related Components
243243

244-
- **[ListBox](/docs/forms-listbox--docs)** - Simple list selection without search
245-
- **[ComboBox](/docs/forms-combobox--docs)** - Dropdown with search and text input
246-
- **[Select](/docs/forms-select--docs)** - Dropdown selection without search
247-
- **[SearchInput](/docs/forms-searchinput--docs)** - Standalone search input component
244+
- [ListBox](/docs/forms-listbox--docs) - Simple list selection without search
245+
- [FilterPicker](/docs/forms-filterpicker--docs) - Simple list selection without search
246+
- [ComboBox](/docs/forms-combobox--docs) - Dropdown with search and text input
247+
- [Select](/docs/forms-select--docs) - Dropdown selection without search
248+
- [SearchInput](/docs/forms-searchinput--docs) - Standalone search input component

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

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
import { Meta, Canvas, Story, Controls } from '@storybook/blocks';
2+
import { FilterPicker } from './FilterPicker';
3+
import * as FilterPickerStories from './FilterPicker.stories';
4+
5+
<Meta of={FilterPickerStories} />
6+
7+
# FilterPicker
8+
9+
FilterPicker is a versatile selection component that combines a trigger button with a filterable dropdown. It provides a searchable interface for selecting one or multiple items from a list, with support for sections, custom summaries, and various UI states.
10+
11+
## When to Use
12+
13+
- Creating filter interfaces where users need to select from predefined options
14+
- Building advanced search and filtering systems with multiple criteria
15+
- Implementing tag-based selection systems where users can choose multiple categories
16+
- Designing compact selection interfaces where space is limited and search functionality is important
17+
- Building user preference panels where options need to be organized into logical groups
18+
19+
## Component
20+
21+
<Story of={FilterPickerStories.Default} />
22+
23+
---
24+
25+
### Properties
26+
27+
<Controls of={FilterPickerStories.Default} />
28+
29+
### Base Properties
30+
31+
Supports [Base properties](/BaseProperties)
32+
33+
### Styling Properties
34+
35+
#### styles
36+
37+
Customizes the root element of the component.
38+
39+
**Sub-elements:**
40+
- None - styles apply directly to the trigger button wrapper
41+
42+
#### listBoxStyles
43+
44+
Customizes the dropdown list container within the popover.
45+
46+
#### popoverStyles
47+
48+
Customizes the popover dialog that contains the list.
49+
50+
#### headerStyles
51+
52+
Customizes the header area when header prop is provided.
53+
54+
#### footerStyles
55+
56+
Customizes the footer area when footer prop is provided.
57+
58+
### Style Properties
59+
60+
These properties allow direct style application without using the `styles` prop: `width`, `height`, `margin`, `padding`, `position`, `inset`, `zIndex`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `opacity`, `color`, `fill`, `fade`.
61+
62+
### Modifiers
63+
64+
The `mods` property accepts the following modifiers you can override:
65+
66+
| Modifier | Type | Description |
67+
|----------|------|-------------|
68+
| placeholder | `boolean` | Applied when no selection is made |
69+
| selected | `boolean` | Applied when items are selected |
70+
| disabled | `boolean` | Applied when the component is disabled |
71+
| loading | `boolean` | Applied when the component is in loading state |
72+
| invalid | `boolean` | Applied when validation state is invalid |
73+
| valid | `boolean` | Applied when validation state is valid |
74+
| focused | `boolean` | Applied when the component has focus |
75+
76+
## Variants
77+
78+
### Types
79+
80+
- `outline` - Default outlined button appearance
81+
- `clear` - Transparent background with minimal styling
82+
- `primary` - Primary brand color styling
83+
- `secondary` - Secondary color styling
84+
- `neutral` - Neutral gray styling
85+
86+
### Themes
87+
88+
- `default` - Standard appearance
89+
- `danger` - Used when validationState is invalid
90+
91+
### Sizes
92+
93+
- `small` - Compact size for dense interfaces
94+
- `medium` - Default size
95+
- `large` - Emphasized size for prominent selections
96+
97+
## Examples
98+
99+
### Basic Usage
100+
101+
```jsx
102+
<FilterPicker label="Select Fruits" placeholder="Choose fruits...">
103+
<FilterPicker.Item key="apple">Apple</FilterPicker.Item>
104+
<FilterPicker.Item key="banana">Banana</FilterPicker.Item>
105+
<FilterPicker.Item key="cherry">Cherry</FilterPicker.Item>
106+
</FilterPicker>
107+
```
108+
109+
### Multiple Selection
110+
111+
```jsx
112+
<FilterPicker
113+
label="Select Multiple Options"
114+
selectionMode="multiple"
115+
placeholder="Choose items..."
116+
>
117+
<FilterPicker.Item key="option1">Option 1</FilterPicker.Item>
118+
<FilterPicker.Item key="option2">Option 2</FilterPicker.Item>
119+
<FilterPicker.Item key="option3">Option 3</FilterPicker.Item>
120+
</FilterPicker>
121+
```
122+
123+
### With Sections
124+
125+
```jsx
126+
<FilterPicker
127+
label="Categorized Options"
128+
selectionMode="multiple"
129+
placeholder="Select from categories..."
130+
>
131+
<FilterPicker.Section title="Fruits">
132+
<FilterPicker.Item key="apple">Apple</FilterPicker.Item>
133+
<FilterPicker.Item key="banana">Banana</FilterPicker.Item>
134+
</FilterPicker.Section>
135+
<FilterPicker.Section title="Vegetables">
136+
<FilterPicker.Item key="carrot">Carrot</FilterPicker.Item>
137+
<FilterPicker.Item key="broccoli">Broccoli</FilterPicker.Item>
138+
</FilterPicker.Section>
139+
</FilterPicker>
140+
```
141+
142+
### With Checkboxes
143+
144+
```jsx
145+
<FilterPicker
146+
label="Multi-select with Checkboxes"
147+
selectionMode="multiple"
148+
isCheckable={true}
149+
placeholder="Select options..."
150+
>
151+
<FilterPicker.Item key="option1">Option 1</FilterPicker.Item>
152+
<FilterPicker.Item key="option2">Option 2</FilterPicker.Item>
153+
<FilterPicker.Item key="option3">Option 3</FilterPicker.Item>
154+
</FilterPicker>
155+
```
156+
157+
### Custom Summary Display
158+
159+
```jsx
160+
<FilterPicker
161+
label="Custom Summary"
162+
selectionMode="multiple"
163+
placeholder="Choose items..."
164+
renderSummary={({ selectedKeys, selectedLabels }) => {
165+
if (selectedKeys.length === 0) return null;
166+
if (selectedKeys.length === 1) return selectedLabels[0];
167+
return `${selectedKeys.length} items selected`;
168+
}}
169+
>
170+
<FilterPicker.Item key="item1">Item 1</FilterPicker.Item>
171+
<FilterPicker.Item key="item2">Item 2</FilterPicker.Item>
172+
<FilterPicker.Item key="item3">Item 3</FilterPicker.Item>
173+
</FilterPicker>
174+
```
175+
176+
### With Header and Footer
177+
178+
```jsx
179+
<FilterPicker
180+
label="Advanced Options"
181+
placeholder="Filter options..."
182+
header={
183+
<div>
184+
<h4>Filter Options</h4>
185+
<Badge>12 available</Badge>
186+
</div>
187+
}
188+
footer={
189+
<div>
190+
<Text>Select multiple to combine filters</Text>
191+
<Button type="link" size="small">Reset all</Button>
192+
</div>
193+
}
194+
>
195+
<FilterPicker.Item key="filter1">Active Items</FilterPicker.Item>
196+
<FilterPicker.Item key="filter2">Recent Items</FilterPicker.Item>
197+
<FilterPicker.Item key="filter3">Archived Items</FilterPicker.Item>
198+
</FilterPicker>
199+
```
200+
201+
### Icon-Only Filter Button
202+
203+
```jsx
204+
<FilterPicker
205+
selectionMode="multiple"
206+
renderSummary={false}
207+
icon={<FilterIcon />}
208+
aria-label="Apply filters"
209+
>
210+
<FilterPicker.Item key="filter1">Recent</FilterPicker.Item>
211+
<FilterPicker.Item key="filter2">Popular</FilterPicker.Item>
212+
<FilterPicker.Item key="filter3">Favorites</FilterPicker.Item>
213+
</FilterPicker>
214+
```
215+
216+
### Controlled Component
217+
218+
```jsx
219+
function ControlledFilterPicker() {
220+
const [selectedKeys, setSelectedKeys] = useState(['apple', 'banana']);
221+
222+
return (
223+
<FilterPicker
224+
label="Controlled Selection"
225+
selectionMode="multiple"
226+
selectedKeys={selectedKeys}
227+
onSelectionChange={setSelectedKeys}
228+
>
229+
<FilterPicker.Item key="apple">Apple</FilterPicker.Item>
230+
<FilterPicker.Item key="banana">Banana</FilterPicker.Item>
231+
<FilterPicker.Item key="cherry">Cherry</FilterPicker.Item>
232+
</FilterPicker>
233+
);
234+
}
235+
```
236+
237+
## Accessibility
238+
239+
### Keyboard Navigation
240+
241+
- `Tab` - Moves focus to the FilterPicker trigger
242+
- `Space/Enter` - Opens the dropdown when trigger is focused
243+
- `Arrow Up/Down` - Navigates between options in the search input
244+
- `Enter` - Selects the focused option
245+
- `Space` - Toggles selection (when search input is empty)
246+
- `Escape` - Closes the dropdown or clears search text
247+
248+
### Screen Reader Support
249+
250+
- Component announces as "button" with appropriate expanded state
251+
- Search input is properly labeled as "combobox" with aria-activedescendant
252+
- Selection changes are announced with current selection count
253+
- Options announce their selected state and text content
254+
- Sections are properly grouped and announced
255+
256+
### ARIA Properties
257+
258+
- `aria-label` - Provides accessible label for the trigger button when no visible label exists
259+
- `aria-expanded` - Indicates whether the dropdown is open
260+
- `aria-haspopup` - Indicates the trigger opens a listbox
261+
- `aria-activedescendant` - Points to the currently focused option in search mode
262+
263+
## Best Practices
264+
265+
1. **Do**: Provide clear, descriptive labels for options
266+
```jsx
267+
<FilterPicker label="Filter by Category">
268+
<FilterPicker.Item key="electronics">Electronics & Gadgets</FilterPicker.Item>
269+
<FilterPicker.Item key="clothing">Clothing & Accessories</FilterPicker.Item>
270+
</FilterPicker>
271+
```
272+
273+
2. **Don't**: Use overly long option texts that will be truncated
274+
```jsx
275+
// Avoid this
276+
<FilterPicker.Item key="long">
277+
This is an extremely long option text that will be truncated and hard to read
278+
</FilterPicker.Item>
279+
```
280+
281+
3. **Accessibility**: Always provide meaningful labels and use sections for logical grouping
282+
4. **Performance**: Use `textValue` prop for options with complex content to ensure proper searching
283+
5. **UX**: Consider using `isCheckable` for multiple selection to make selection state more obvious
284+
285+
## Integration with Forms
286+
287+
This component supports all [Field properties](/field-properties.md) when used within a Form. The component automatically handles form validation, field states, and integrates with form submission.
288+
289+
## Suggested Improvements
290+
291+
- Enhanced keyboard shortcuts: Add support for typing to jump to options
292+
- Async data loading: Built-in support for loading options dynamically
293+
- Virtualization: Support for rendering large lists efficiently
294+
- Custom filter functions: More sophisticated filtering options beyond text matching
295+
- Batch operations: Support for "select all" and "clear all" actions in multiple selection mode
296+
297+
## Related Components
298+
299+
- [FilterListBox](/docs/forms-filterlistbox--docs) - The underlying searchable list component
300+
- [Select](/docs/forms-select--docs) - Use for simple selection without search functionality
301+
- [ComboBox](/docs/forms-combobox--docs) - Use when users need to enter custom values
302+
- [ListBox](/docs/forms-listbox--docs) - Use for basic list selection without search
303+
- [Button](/docs/actions-button--docs) - The underlying trigger component

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

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,6 @@ const meta: Meta<typeof FilterPicker> = {
9696
defaultValue: { summary: 'medium' },
9797
},
9898
},
99-
maxTags: {
100-
control: 'number',
101-
description:
102-
'Maximum number of tags to show before showing count (multiple mode only)',
103-
},
10499
},
105100
};
106101

‎src/components/fields/FilterPicker/FilterPicker.tsx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,6 @@ export interface CubeFilterPickerProps<T>
5959
size?: 'small' | 'medium' | 'large';
6060
/** Children (FilterListBox.Item and FilterListBox.Section elements) */
6161
children?: ReactNode;
62-
/** Maximum number of tags to show before showing count */
63-
maxTags?: number;
6462
/** Custom styles for the list box */
6563
listBoxStyles?: Styles;
6664
/** Custom styles for the popover */

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -402,6 +402,8 @@ const [selectedKey, setSelectedKey] = useState(null);
402402

403403
## Related Components
404404

405+
- [FilterPicker](/docs/forms-filterpicker--docs) - Simple list selection without search
406+
- [FilterListBox](/docs/forms-filterlistbox--docs) - Simple list selection without search
405407
- [Select](/docs/forms-select--docs) - For dropdown selection that saves space
406408
- [ComboBox](/docs/forms-combobox--docs) - For searchable selection with text input
407409
- [RadioGroup](/docs/forms-radiogroup--docs) - For single selection with radio buttons

0 commit comments

Comments
 (0)