Skip to content

Commit 5949113

Browse files
rivka-ungarrivka-ungar
committed
docs: update Dropdown documentation and add new Basic Dropdown and Box Mode components
1 parent 5421c76 commit 5949113

File tree

5 files changed

+703
-226
lines changed

5 files changed

+703
-226
lines changed

‎packages/docs/src/pages/components/Dropdown/Dropdown.mdx‎

Lines changed: 24 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,164 +1,74 @@
1-
import { Meta } from "@storybook/blocks";
2-
import { Link, Tip } from "vibe-storybook-components";
3-
import { Dropdown } from "@vibe/core/next";
4-
import * as DropdownStories from "./Dropdown.stories";
1+
import { Canvas, Meta } from "@storybook/blocks";
2+
import { Link, Tip, StorybookLink } from "vibe-storybook-components";
3+
import { Overview as BasicDropdownPreview } from "./DropdownBasicDropdown.stories";
4+
import { Overview as BoxModePreview } from "./DropdownBoxMode.stories";
55
import do1 from "./assets/do1.png";
66
import dont1 from "./assets/dont1.png";
77

8-
<Meta of={DropdownStories} />
8+
<Meta title="Components/Dropdown [New]" />
99

1010
# Dropdown
1111

12-
Dropdown present a list of options from which a user can select one or several.
13-
14-
<br />
12+
Select component present a list of options from which a user can select one or several.
1513

1614
<Tip title="Migration Guide Available" emoji="🚀">
1715
Migrating from the old Dropdown? Check out our comprehensive{" "}
1816
<Link href="/?path=/docs/components-dropdown-new-migration-guide--docs">Dropdown Migration Guide</Link> for
1917
step-by-step instructions, breaking changes, and new features.
2018
</Tip>
2119

22-
<Canvas of={DropdownStories.Overview} />
23-
2420
### Import
2521

22+
All the Dropdown-related components can be imported from `@vibe/core/next`.
23+
2624
```js
2725
import { Dropdown } from "@vibe/core/next";
2826
```
2927

30-
## Props
28+
### Basic dropdown
3129

32-
<PropsTable />
30+
The <StorybookLink page="Components/Dropdown [New]/Basic dropdown">Basic dropdown</StorybookLink> present a popup list of options from which a user can select one or several.
3331

34-
## Usage
32+
<Canvas of={BasicDropdownPreview} sourceState="none" />
3533

36-
<UsageGuidelines
37-
guidelines={[
38-
"Dropdown menus are typically used when you have 5-8 items to choose from. They're used for navigation or command menus, where an action is initiated based on the selection.",
39-
"Use a consistent size of form components on the same page. For example, if you are using a medium size dropdown also use the same size text inputs, buttons, and so on.",
40-
"Avoid having multiple lines of text in a dropdown. If the text is too long for one line, add an ellipsis (…).",
41-
"When the menu is open, each option in the menu should be the same height as the field.",
42-
"When organizing dropdown menu items, sort the list in a logical order by putting the most selected option at the top."
43-
]}
44-
/>
34+
### Dropdown box mode
35+
36+
The <StorybookLink page="Components/Dropdown [New]/Dropdown box mode">Dropdown box mode</StorybookLink> is an always open Dropdown, with the same properties as the basic Dropdown.
37+
38+
<Canvas of={BoxModePreview} sourceState="none" />
4539

46-
## Accessibility
40+
## Usage
4741

4842
<UsageGuidelines
4943
guidelines={[
50-
<>
51-
Using an <code>id</code> is highly recommended for all instances to ensure proper label association.
52-
</>,
53-
<>
54-
Always provide a <code>label</code> prop to ensure the dropdown's purpose is clear to all users.
55-
</>,
56-
<>
57-
Use <code>ariaLabel</code> prop when you need to provide a custom accessible name for the dropdown.
58-
</>,
59-
<>
60-
Use <code>clearAriaLabel</code> prop when dropdown is clearable.
61-
</>,
62-
<>
63-
Use <code>inputAriaLabel</code> prop when you need to provide a specific accessible name for the input field in
64-
searchable dropdowns.
65-
</>,
66-
<>
67-
Use <code>menuAriaLabel</code> prop when you need to provide a custom accessible name for the dropdown menu.
68-
</>,
69-
<>
70-
Use <code>autoFocus</code> prop when the dropdown should receive initial focus for keyboard navigation.
71-
</>
44+
"When the user needs to choose one or multiple values from a fixed set of options.",
45+
"When the selected value needs to be visible after selection.",
46+
"When the selection is part of a form, filter, or preference setting."
7247
]}
7348
/>
7449

75-
## Variants
76-
77-
### Sizes
78-
79-
There are three sizes available: Small, Medium, and Large
80-
81-
<Canvas of={DropdownStories.Sizes} />
82-
83-
### States
84-
85-
<Canvas of={DropdownStories.States} />
86-
87-
### Multi-select
88-
89-
The Dropdown component supports multi select option that display as chips. The selected items can be shown in either a single line (with additional option for hidden list), or multiple line. This mode also supports all standard dropdown states.
90-
91-
<Canvas of={DropdownStories.MultiSelect} />
92-
93-
### Dropdown with icon or avatar
94-
95-
<Canvas of={DropdownStories.DropdownWithIconOrAvatar} />
96-
97-
## Do’s and Don’ts
50+
## Do's and Don'ts
9851

9952
<ComponentRules
10053
rules={[
10154
{
10255
positive: {
10356
component: <img src={do1} alt="do1" style={{ width: "300px" }} />,
104-
description:
105-
"Use the dropdown as a closed component. Users should normally be allowed only to click on the items; search is not recommended, though possible."
57+
description: "Use the select when theres a need to choose one or multiple options from a predefined list."
10658
},
10759
negative: {
10860
component: <img src={dont1} alt="dont1" style={{ width: "200px" }} />,
10961
description: (
11062
<>
111-
Don't keep the dropdown component in open mode as permanent state. If this is a design requirement consider
112-
use <StorybookLink page="Components/Combobox">Combo box</StorybookLink> instead.
63+
Use select when the purpose of the list is to provide actions or navigation options. Use a{" "}
64+
<StorybookLink page="Components/Menu">menu</StorybookLink> instead.
11365
</>
11466
)
11567
}
11668
}
11769
]}
11870
/>
11971

120-
## Use cases and examples
121-
122-
### Searchable dropdown
123-
124-
The dropdown can also function as a search for a specific item within the list.
125-
126-
<Canvas of={DropdownStories.Searchable} />
127-
128-
### Dropdown with groups
129-
130-
Dropdown menu can be organized into groups, either with titled sections or dividers. Group titles can be configured to remain sticky or non-sticky.
131-
132-
<Canvas of={DropdownStories.DropdownWithGroups} />
133-
134-
### Dropdown item with elements
135-
136-
The dropdown item can contain start element or end element. This are the options:
137-
138-
<Canvas of={DropdownStories.DropdownItemWithElements} />
139-
140-
### Hide selected items
141-
142-
You can choose to hide selected items within the dropdown list, so users can see only the available options.
143-
144-
<Canvas of={DropdownStories.DropdownHideSelectedItems} />
145-
146-
### Dropdown with tooltips
147-
148-
<Canvas of={DropdownStories.DropdownWithTooltips} />
149-
150-
### Dropdown with virtualization
151-
152-
For performance optimization with large datasets, the Dropdown supports virtualization through the menuRenderer prop. You can integrate any virtualization library of your choice - this example demonstrates implementation using <a href="https://github.com/bvaughn/react-window" target="_blank">react-window</a>.
153-
154-
<Canvas of={DropdownStories.DropdownWithVirtualization} />
155-
156-
### Dropdown in box mode
157-
158-
The Dropdown component supports box mode, which displays the dropdown in a box-like container. This mode is useful when you want to display the dropdown in a fixed-width container, such as a modal or a card.
159-
160-
<Canvas of={DropdownStories.BoxMode} />
161-
16272
## Related components
16373

16474
<RelatedComponents componentsNames={["Combobox", "SplitButton", "Menu"]} />

‎packages/docs/src/pages/components/Dropdown/DropdownBasicDropdown.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
import { Meta } from "@storybook/blocks";
2+
import * as DropdownBasicDropdownStories from "./DropdownBasicDropdown.stories";
3+
4+
<Meta of={DropdownBasicDropdownStories} />
5+
6+
# Basic Dropdown
7+
8+
The basic dropdown is intended for quick value selection when space is limited and the list of options doesn't need to remain visible. It typically is used when you have 5-8 items to choose from where an action is initiated based on the selection.
9+
10+
<Canvas of={DropdownBasicDropdownStories.Overview} />
11+
12+
### Import
13+
14+
All the Dropdown components can be imported from `@vibe/core/next`.
15+
16+
Notice not to import components directly from the `@vibe/core` package, as they are deprecated.
17+
18+
```js
19+
import { Dropdown } from "@vibe/core/next";
20+
```
21+
22+
## Props
23+
24+
<PropsTable />
25+
26+
## Usage
27+
28+
<UsageGuidelines
29+
guidelines={[
30+
"Dropdown is typically used when you have 5-8 items to choose from. They are used for navigation or command menus, where an action is initiated based on the selection.",
31+
"Use a consistent size of form components on the same page. For example, if you are using a medium size dropdown also use the same size text inputs, buttons, and so on.",
32+
"Avoid having multiple lines of text in a dropdown. If the text is too long for one line, add an ellipsis (…).",
33+
"When the menu is open, each option in the menu should be the same height as the field.",
34+
"When organizing dropdown menu items, sort the list in a logical order by putting the most selected option at the top."
35+
]}
36+
/>
37+
38+
## Accessibility
39+
40+
<UsageGuidelines
41+
guidelines={[
42+
<>
43+
Using an <code>id</code> is highly recommended for all instances to ensure proper label association.
44+
</>,
45+
<>
46+
Always provide a <code>label</code> prop to ensure the dropdown's purpose is clear to all users.
47+
</>,
48+
<>
49+
Use <code>ariaLabel</code> prop when you need to provide a custom accessible name for the dropdown.
50+
</>,
51+
<>
52+
Use <code>clearAriaLabel</code> prop when dropdown is clearable.
53+
</>,
54+
<>
55+
Use <code>inputAriaLabel</code> prop when you need to provide a specific accessible name for the input field in
56+
searchable dropdowns.
57+
</>,
58+
<>
59+
Use <code>menuAriaLabel</code> prop when you need to provide a custom accessible name for the dropdown menu.
60+
</>,
61+
<>
62+
Use <code>autoFocus</code> prop when the dropdown should receive initial focus for keyboard navigation.
63+
</>
64+
]}
65+
/>
66+
67+
## Variants
68+
69+
### Sizes
70+
71+
There are three sizes available: Small, Medium, and Large
72+
73+
<Canvas of={DropdownBasicDropdownStories.Sizes} />
74+
75+
### States
76+
77+
<Canvas of={DropdownBasicDropdownStories.States} />
78+
79+
### Multi select
80+
81+
The Dropdown component supports multi select option that display as chips. The selected items can be shown in either a single line (with additional option for hidden list), or multiple line. This mode also supports all standard dropdown states.
82+
83+
<Canvas of={DropdownBasicDropdownStories.MultiSelect} />
84+
85+
### Dropdown with icon or avatar
86+
87+
<Canvas of={DropdownBasicDropdownStories.DropdownWithIconOrAvatar} />
88+
89+
## Use cases and examples
90+
91+
### Searchable dropdown
92+
93+
The dropdown can also function as a search for a specific item within the list.
94+
95+
<Canvas of={DropdownBasicDropdownStories.Searchable} />
96+
97+
### Dropdown with groups
98+
99+
Dropdown can be organized into groups, either with titled sections or dividers. Group titles can be configured to remain sticky or non-sticky.
100+
101+
<Canvas of={DropdownBasicDropdownStories.DropdownWithGroups} />
102+
103+
### Dropdown with elements
104+
105+
The dropdown item can contain start element or end element. This are the options:
106+
107+
<Canvas of={DropdownBasicDropdownStories.DropdownItemWithElements} />
108+
109+
### Hide selected items
110+
111+
You can choose to hide selected items within the dropdown list, so users can see only the available options.
112+
113+
<Canvas of={DropdownBasicDropdownStories.DropdownHideSelectedItems} />
114+
115+
### Dropdown with tooltips
116+
117+
<Canvas of={DropdownBasicDropdownStories.DropdownWithTooltips} />
118+
119+
### Dropdown with virtualization
120+
121+
For performance optimization with large datasets, the Dropdown supports virtualization through the menuRenderer prop. You can integrate any virtualization library of your choice - this example demonstrates implementation using <a href="https://github.com/bvaughn/react-window" target="_blank">react-window</a>.
122+
123+
<Canvas of={DropdownBasicDropdownStories.DropdownWithVirtualization} />
124+
125+
## Related components
126+
127+
<RelatedComponents componentsNames={["DropdownBoxMode", "Combobox", "Menu"]} />

0 commit comments

Comments
 (0)