@fluentui-react-native/menu 0.16.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.json +76 -1
  2. package/CHANGELOG.md +31 -2
  3. package/MIGRATION.md +323 -0
  4. package/SPEC.md +405 -0
  5. package/assets/Menu.png +0 -0
  6. package/assets/Submenu.png +0 -0
  7. package/assets/checkbox.png +0 -0
  8. package/package.json +8 -8
package/CHANGELOG.json CHANGED
@@ -2,7 +2,82 @@
2
2
  "name": "@fluentui-react-native/menu",
3
3
  "entries": [
4
4
  {
5
- "date": "Tue, 28 Jun 2022 18:03:46 GMT",
5
+ "date": "Thu, 07 Jul 2022 21:22:09 GMT",
6
+ "tag": "@fluentui-react-native/menu_v1.0.3",
7
+ "version": "1.0.3",
8
+ "comments": {
9
+ "patch": [
10
+ {
11
+ "author": "beachball",
12
+ "package": "@fluentui-react-native/menu",
13
+ "comment": "Bump @fluentui-react-native/callout to v0.20.9",
14
+ "commit": "f10be0c3afa914ad42fcb639dc4d0a65a87c6425"
15
+ },
16
+ {
17
+ "author": "beachball",
18
+ "package": "@fluentui-react-native/menu",
19
+ "comment": "Bump @fluentui-react-native/experimental-text to v0.9.1",
20
+ "commit": "f10be0c3afa914ad42fcb639dc4d0a65a87c6425"
21
+ },
22
+ {
23
+ "author": "beachball",
24
+ "package": "@fluentui-react-native/menu",
25
+ "comment": "Bump @fluentui-react-native/framework to v0.7.31",
26
+ "commit": "f10be0c3afa914ad42fcb639dc4d0a65a87c6425"
27
+ },
28
+ {
29
+ "author": "beachball",
30
+ "package": "@fluentui-react-native/menu",
31
+ "comment": "Bump @fluentui-react-native/interactive-hooks to v0.16.4",
32
+ "commit": "f10be0c3afa914ad42fcb639dc4d0a65a87c6425"
33
+ },
34
+ {
35
+ "author": "beachball",
36
+ "package": "@fluentui-react-native/menu",
37
+ "comment": "Bump @fluentui-react-native/tokens to v0.15.0",
38
+ "commit": "f10be0c3afa914ad42fcb639dc4d0a65a87c6425"
39
+ },
40
+ {
41
+ "author": "beachball",
42
+ "package": "@fluentui-react-native/menu",
43
+ "comment": "Bump @fluentui-react-native/button to v0.22.30",
44
+ "commit": "f10be0c3afa914ad42fcb639dc4d0a65a87c6425"
45
+ }
46
+ ]
47
+ }
48
+ },
49
+ {
50
+ "date": "Wed, 29 Jun 2022 21:06:49 GMT",
51
+ "tag": "@fluentui-react-native/menu_v1.0.2",
52
+ "version": "1.0.2",
53
+ "comments": {
54
+ "patch": [
55
+ {
56
+ "author": "ruaraki@microsoft.com",
57
+ "package": "@fluentui-react-native/menu",
58
+ "commit": "c606f6deb5e1be500fc4183e6537dbf523c84194",
59
+ "comment": "Some refactoring"
60
+ }
61
+ ]
62
+ }
63
+ },
64
+ {
65
+ "date": "Tue, 28 Jun 2022 22:01:06 GMT",
66
+ "tag": "@fluentui-react-native/menu_v1.0.1",
67
+ "version": "1.0.1",
68
+ "comments": {
69
+ "patch": [
70
+ {
71
+ "author": "ruaraki@microsoft.com",
72
+ "package": "@fluentui-react-native/menu",
73
+ "commit": "46767277f2408687a94a808360affee37683673e",
74
+ "comment": "Update package.json version"
75
+ }
76
+ ]
77
+ }
78
+ },
79
+ {
80
+ "date": "Tue, 28 Jun 2022 18:04:00 GMT",
6
81
  "tag": "@fluentui-react-native/menu_v0.16.1",
7
82
  "version": "0.16.1",
8
83
  "comments": {
package/CHANGELOG.md CHANGED
@@ -1,12 +1,41 @@
1
1
  # Change Log - @fluentui-react-native/menu
2
2
 
3
- This log was last generated on Tue, 28 Jun 2022 18:03:46 GMT and should not be manually modified.
3
+ This log was last generated on Thu, 07 Jul 2022 21:22:09 GMT and should not be manually modified.
4
4
 
5
5
  <!-- Start content -->
6
6
 
7
+ ## 1.0.3
8
+
9
+ Thu, 07 Jul 2022 21:22:09 GMT
10
+
11
+ ### Patches
12
+
13
+ - Bump @fluentui-react-native/callout to v0.20.9
14
+ - Bump @fluentui-react-native/experimental-text to v0.9.1
15
+ - Bump @fluentui-react-native/framework to v0.7.31
16
+ - Bump @fluentui-react-native/interactive-hooks to v0.16.4
17
+ - Bump @fluentui-react-native/tokens to v0.15.0
18
+ - Bump @fluentui-react-native/button to v0.22.30
19
+
20
+ ## 1.0.2
21
+
22
+ Wed, 29 Jun 2022 21:06:49 GMT
23
+
24
+ ### Patches
25
+
26
+ - Some refactoring (ruaraki@microsoft.com)
27
+
28
+ ## 1.0.1
29
+
30
+ Tue, 28 Jun 2022 22:01:06 GMT
31
+
32
+ ### Patches
33
+
34
+ - Update package.json version (ruaraki@microsoft.com)
35
+
7
36
  ## 0.16.1
8
37
 
9
- Tue, 28 Jun 2022 18:03:46 GMT
38
+ Tue, 28 Jun 2022 18:04:00 GMT
10
39
 
11
40
  ### Patches
12
41
 
package/MIGRATION.md ADDED
@@ -0,0 +1,323 @@
1
+ # Menu Migration
2
+
3
+ ## Migration from ContextualMenu
4
+
5
+ ### Component rename
6
+
7
+ `ContextalMenu` and `Submenu` are now named `Menu`. `ContextualMenuItem` and `SubmenuItem` are now named `MenuItem`.
8
+
9
+ ### Structural difference
10
+
11
+ The v1 `Menu` differs from the v0 `ContextualMenu` by wrapping the anchor component. With this, the `Menu` component takes care of several aspects of managing the menu, including the ref of the target and anchoring the popover (or callout) to the correct component, and open and close behavior.
12
+
13
+ Additionally there is no difference between the root menu and submenus in terms of how they are written. Both controls use the same components with the V1 `Menu`.
14
+
15
+ In v0 a `ContextualMenu` looked like:
16
+
17
+ ```tsx
18
+ const stdBtnRef = React.useRef(null);
19
+ const [showContextualMenu, setShowContextualMenu] = React.useState(false);
20
+ const toggleShowContextualMenu = React.useCallback(() => {
21
+ setShowContextualMenu(!showContextualMenu);
22
+ }, [showContextualMenu, setShowContextualMenu]);
23
+ const onDismissContextualMenu = React.useCallback(() => {
24
+ setShowContextualMenu(false);
25
+ }, [setShowContextualMenu]);
26
+ const onItemClick = React.useCallback(
27
+ (key) => {
28
+ // Do something
29
+ },
30
+ [],
31
+ );
32
+
33
+ <>
34
+ <Button onClick={toggleShowContextualMenu} componentRef={stdBtnRef}>
35
+ Press for ContextualMenu
36
+ </Button>;
37
+ {
38
+ showContextualMenu && (
39
+ <ContextualMenu
40
+ target={stdBtnRef}
41
+ onDismiss={onDismissContextualMenu}
42
+ onItemClick={onItemClick}
43
+ setShowMenu={toggleShowContextualMenu}
44
+ >
45
+ <ContextualMenuItem text="MenuItem 1" itemKey="1" />
46
+ <ContextualMenuItem text="MenuItem 2" itemKey="2" />
47
+ <ContextualMenuItem text="Disabled Menu Item" itemKey="3" disabled />
48
+ <ContextualMenuItem text="MenuItem 4" itemKey="4" />
49
+ <ContextualMenuItem text="MenuItem 5" itemKey="5" />
50
+ </ContextualMenu>
51
+ );
52
+ }
53
+ </>
54
+ ```
55
+
56
+ While a similar setup with the V1 `Menu` looks like:
57
+
58
+ ```tsx
59
+ const onOption1Click = React.useCallback(
60
+ () => {
61
+ // Do something
62
+ },
63
+ [],
64
+ );
65
+
66
+ <Menu>
67
+ <MenuTrigger>
68
+ <Button>Press for Menu</Button>
69
+ </MenuTrigger>
70
+ <MenuPopover>
71
+ <MenuList>
72
+ <MenuItem onClick={onOption1Click}>Option 1</MenuItem>
73
+ <MenuItem>Option 2</MenuItem>
74
+ <MenuItem disabled>Disabled Menu Item</MenuItem>
75
+ <MenuItem>Option 4</MenuItem>
76
+ <MenuItem>Option 5</MenuItem>
77
+ </MenuList>
78
+ </MenuPopover>
79
+ <Menu>
80
+ ```
81
+
82
+ Mapping the `ContextualMenu` to the `Menu`:
83
+
84
+ 1. The `Menu` component wraps both the trigger or the anchor and the popover, while the `ContextualMenu` only represented the popover. This allows the `Menu` to share state between the anchor and the popover.
85
+ 2. The `MenuTrigger` component wraps the anchor. This allows for the anchor to be configured to open and close the popover and have the correct ref while providing flexibility for what the anchor component could be. There is no equivalent in the `ContextualMenu`.
86
+ 3. The `MenuPopover` wraps the popover or callout component which hosts the options of the menu. This can be thought of as equivalent to `ContextualMenu`.
87
+ 4. The `MenuList` wraps the menu options so that they can share state between each other and sets up the menu to be able to be a standalone component in the future. This can be thought of as handling some of the logic of the `ContextualMenu`.
88
+ 5. The `MenuItem`, `MenuItemCheckbox`, and `MenuItemRadio` represent options in a menu. These can be thought of as equivalent to `ContextualMenuItem`.
89
+
90
+ #### Submenu
91
+
92
+ In v0 a `ContextualMenu` with a `Submenu` looked like:
93
+
94
+ ```tsx
95
+ const stdBtnRef = React.useRef(null);
96
+ const [showContextualMenu, setShowContextualMenu] = React.useState(false);
97
+ const toggleShowContextualMenu = React.useCallback(() => {
98
+ setShowContextualMenu(!showContextualMenu);
99
+ }, [showContextualMenu, setShowContextualMenu]);
100
+ const onDismissContextualMenu = React.useCallback(() => {
101
+ setShowContextualMenu(false);
102
+ }, [setShowContextualMenu]);
103
+ const onItemClick = React.useCallback((key) => {
104
+ // Do something
105
+ }, []);
106
+
107
+ const stdMenuItemRef = React.useRef(null);
108
+
109
+ const [showSubmenu, setShowSubmenu] = React.useState(false);
110
+
111
+ const toggleShowSubmenu = React.useCallback(() => {
112
+ setShowSubmenu(!showSubmenu);
113
+ }, [showSubmenu, isSubmenuVisible, setShowSubmenu, setIsSubmenuVisible]);
114
+ const onDismissSubmenu = React.useCallback(() => {
115
+ setShowSubmenu(false);
116
+ }, [setShowSubmenu]);
117
+ const onClick = React.useCallback(() => {
118
+ console.log('submenu item clicked');
119
+ }, []);
120
+
121
+ <>
122
+ <Button onClick={toggleShowContextualMenu} componentRef={stdBtnRef}>
123
+ Press for ContextualMenu
124
+ </Button>
125
+ {showContextualMenu && (
126
+ <ContextualMenu target={stdBtnRef} onDismiss={onDismissContextualMenu} setShowMenu={toggleShowContextualMenu}>
127
+ <ContextualMenuItem text="Menu item 1" itemKey="1" />
128
+ <ContextualMenuItem text="Menu item 2" itemKey="2" />
129
+ <ContextualMenuItem text="Disabled Menu Item" itemKey="3" disabled />
130
+ <SubmenuItem text="Nested Menu" itemKey="4" onHoverIn={toggleShowSubmenu} componentRef={stdMenuItemRef} />
131
+ {showSubmenu && (
132
+ <Submenu target={stdMenuItemRef} onDismiss={onDismissSubmenu} setShowMenu={toggleShowSubmenu}>
133
+ <ContextualMenuItem text="SubmenuItem 1" itemKey="1" onClick={onClick} />
134
+ <ContextualMenuItem text="SubmenuItem 2" itemKey="2" />
135
+ <ContextualMenuItem text="Disabled Menu Item" itemKey="3" disabled />
136
+ </Submenu>
137
+ )}
138
+ <ContextualMenuItem text="Menuitem 5" itemKey="5" />
139
+ </ContextualMenu>
140
+ )}
141
+ </>;
142
+ ```
143
+
144
+ While a similar setup with the V1 `Menu` looks like:
145
+
146
+ ```tsx
147
+ const onSubmenuItemClick = React.useCallback(
148
+ () => {
149
+ // Do something
150
+ },
151
+ [],
152
+ );
153
+
154
+ <Menu>
155
+ <MenuTrigger>
156
+ <Button>Press for Menu</Button>
157
+ </MenuTrigger>
158
+ <MenuPopover>
159
+ <MenuList>
160
+ <MenuItem>Menu item 1</MenuItem>
161
+ <MenuItem>Menu item 2</MenuItem>
162
+ <MenuItem disabled>Disabled Menu Item</MenuItem>
163
+ <Menu>
164
+ <MenuTrigger>
165
+ <MenuItem>Nested Menu</MenuItem>
166
+ </MenuTrigger>
167
+ <MenuPopover>
168
+ <MenuList>
169
+ <MenuItem onClick={onSubmenuItemClick}>SubmenuItem 1</MenuItem>
170
+ <MenuItem >SubmenuItem 2</MenuItem>
171
+ <MenuItem disabled>Disabled Menu Item</MenuItem>
172
+ </MenuList>
173
+ </MenuPopover>
174
+ <MenuItem>Menu item 5</MenuItem>
175
+ </MenuList>
176
+ </MenuPopover>
177
+ <Menu>
178
+ ```
179
+
180
+ There is no separate `SubmenuItem` or `Submenu` component. You can wrap a `MenuItem` in a `Menu` component, and it will take care of showing an indicator for the submenu and opening the menu in a reasonable direction.
181
+
182
+ ### Prop and token mapping from ContextualMenu to Menu
183
+
184
+ #### Props no longer supported in ContextualMenu with an equivalent functionality in v1 Menu
185
+
186
+ - `shouldFocusOnMount` => Use `setInitialFocus` on `MenuPopover` instead. Defaults to `true`.
187
+ - `onItemClick` => Use `onClick` on the individual `MenuItem` instead.
188
+ - `setShowMenu` => Use `onOpenChange` on `Menu` instead. This is not required to toggle showing the `MenuPopover`, the `Menu` component will take care of it unless you want to control the component's `open` state.
189
+
190
+ #### Props no longer supported in ContextualMenu without an equivalent functionality in v1 Menu
191
+
192
+ - `shouldFocusOnContainer` - Default behavior is taken care of by `Menu`
193
+
194
+ #### Tokens with an equivalent functionality in v1 Menu
195
+
196
+ - `backgroundColor` => Use `backgroundColor` token on `MenuList`
197
+ - All other tokens can be passed as props to `MenuPopover`
198
+
199
+ ### Prop and token mapping from ContextualMenuItem to MenuItem
200
+
201
+ #### Props no longer supported in ContextualMenuItem with an equivalent functionality in v1 MenuItem
202
+
203
+ - `itemKey` => Use `name` instead.
204
+ - `text` => Pass text as child to component instead.
205
+
206
+ #### Props no longer supported in ContextualMenuItem without an equivalent functionality in v1 MenuItem
207
+
208
+ - `icon` - Not yet supported
209
+ - `title` - Not yet supported
210
+ - `dismissMenu`
211
+
212
+ #### Tokens with an equivalent functionality in v1 MenuItem
213
+
214
+ - `FontTokens`, `IColorTokens`, `IBorderTokens`
215
+
216
+ ### Updating ThemeProvider
217
+
218
+ If you are using the older theme provider `ThemeProvider` from `@uifabricshared/theming-react-native`, you will need to update the `ThemeProvider` to pull from `@fluentui-react-native/theme` to have the control work properly with themes. Please see [this page](../../../docs/pages/Guides/UpdateThemeProvider.md) for guidance.
219
+
220
+ ### Migrating customized ContextualMenus
221
+
222
+ Please see [this page](../../../docs/pages/Guides/UpdatingCustomize.md) for guidance on how to move from the old `customize` API to the new one.
223
+
224
+ ### Migrating composed ContextualMenus
225
+
226
+ Please see [this page](../../../docs/pages/Guides/UpdatingCustomize.md) for guidance on how to move from the old `customize` API to the new one.
227
+
228
+ ## Porting from FluentUI v9 Menu
229
+
230
+ The FURN menu cannot be used in place of a FluentUI menu - these componentss are intended to be used on their respective platforms. See [this porting guide](../../../docs/pages/Guides/PortingFromFluentUI.md) for general guidance on coming from FluentUI to FURN.
231
+
232
+ ### Not yet implemented
233
+
234
+ - Icons on MenuItems
235
+ - Secondary labels on MenuItems
236
+ - Split buttons for MenuItems
237
+ - MenuGroups (including headings)
238
+ - Scrollable menus
239
+ - Custom triggers for Menus (i.e. have a Menu trigger be a component that is not under MenuTrigger)
240
+ - Standalone MenuList
241
+
242
+ ### Menu
243
+
244
+ #### Menu Props that remain as is
245
+
246
+ - `children`
247
+ - `defaultOpen`
248
+ - `hoverDelay`
249
+ - `open`
250
+ - `openOnHover`
251
+
252
+ #### Menu Prop differences due to technical differences and limitations
253
+
254
+ - `onOpenChange` has a different event type and a bool for `isOpen` instead of `data` for its call signature.
255
+
256
+ #### Not implemented on Menu
257
+
258
+ - `inline`
259
+ - `openOnContext`
260
+ - `positioning` (`directionalHint` can be passed into `MenuPopover` instead)
261
+ - `closeOnScroll`
262
+
263
+ ### MenuTrigger
264
+
265
+ `MenuTrigger` should not need any changes.
266
+
267
+ ### MenuPopover
268
+
269
+ `MenuPopover` should not need any changes.
270
+
271
+ ### MenuList
272
+
273
+ #### MenuList Props that remain as is
274
+
275
+ - `hasCheckmarks`
276
+ - `children`
277
+
278
+ #### MenuList Prop differences due to technical differences and limitations
279
+
280
+ `MenuItem*` only uses `name` and not `value` since it is not based on an `input` HTML element. This changes the following props:
281
+
282
+ - `checkedValues` takes in `string[]` of names to be checked instead of `Record<string, string[]>`
283
+ - `defaultCheckedValues` takes in `string[]` of names to be checked instead of `Record<string, string[]>`
284
+ - `onCheckedValueChange` returns a `string[]` of names of items that are checked instead of `Record<string, string[]>`
285
+
286
+ #### Not implemented on MenuList
287
+
288
+ - `hasIcons`
289
+
290
+ ### MenuItem
291
+
292
+ #### MenuItem Props that remain as is
293
+
294
+ - `children`
295
+ - `disabled`
296
+
297
+ #### MenuItem Prop differences due to technical differences and limitations
298
+
299
+ - `componentRef` instead of `ref`
300
+
301
+ #### Not implemented on MenuItem
302
+
303
+ - `hasSubmenu` - currently automatically handled
304
+
305
+ ### MenuItemCheckbox and MenuItemRadio
306
+
307
+ #### MenuItemCheckbox Props that remain as is
308
+
309
+ - `children`
310
+ - `disabled`
311
+ - `name`
312
+
313
+ #### MenuItemCheckbox Prop differences due to technical differences and limitations
314
+
315
+ - `componentRef` instead of `ref`
316
+
317
+ #### Not implemented on MenuItemCheckbox
318
+
319
+ - `value`
320
+
321
+ ### MenuDivider
322
+
323
+ `MenuDivider` should not need any changes.
package/SPEC.md ADDED
@@ -0,0 +1,405 @@
1
+ # Menu
2
+
3
+ ## Background
4
+
5
+ A `Menu` is an component that displays a list of options on a temporary surface. They are invoked when users interact with a button, action, or other control.
6
+
7
+ ## Requirements
8
+
9
+ If using FURN's theming, the `Menu` and its sub-components require use of the `ThemeProvider` from `@fluentui-react-native/theme` to work properly with themes. Please see [this page](../../../docs/pages/Guides/UpdateThemeProvider.md) for information on updating your `ThemeProvider` if using the version from `@uifabricshared/theming-react-native`.
10
+
11
+ ## Sample code
12
+
13
+ The below samples do not represent the definitive props of the final implemented component, but represent the ideal final implementations. Can be subject to change during the implementation phase.
14
+
15
+ ### Basic Menu
16
+
17
+ ![Basic menu with three options](./assets/Menu.png)
18
+
19
+ ```tsx
20
+ const menu = (
21
+ <Menu>
22
+ <MenuTrigger>
23
+ <Button>Open menu</Button>
24
+ </MenuTrigger>
25
+ <MenuPopover>
26
+ <MenuList>
27
+ <MenuItem>Option 1</MenuItem>
28
+ <MenuItem>Option 2</MenuItem>
29
+ <MenuItem>Option 3</MenuItem>
30
+ </MenuList>
31
+ </MenuPopover>
32
+ </Menu>
33
+ );
34
+ ```
35
+
36
+ ### Submenus
37
+
38
+ ![A menu with a submenu with three options](./assets/Submenu.png)
39
+
40
+ ```tsx
41
+ const menu = (
42
+ <Menu>
43
+ <MenuTrigger>
44
+ <Button>Open menu</Button>
45
+ </MenuTrigger>
46
+ <MenuPopover>
47
+ <MenuList>
48
+ <MenuItem>Option 1</MenuItem>
49
+ <Menu>
50
+ <MenuTrigger>
51
+ <MenuItem>Open submenu</MenuItem>
52
+ </MenuTrigger>
53
+ <MenuPopover>
54
+ <MenuList>
55
+ <MenuItem>Option 1</MenuItem>
56
+ <MenuItem>Option 2</MenuItem>
57
+ <MenuItem>Option 3</MenuItem>
58
+ </MenuList>
59
+ </MenuPopover>
60
+ </Menu>
61
+ </MenuList>
62
+ </MenuPopover>
63
+ </Menu>
64
+ );
65
+ ```
66
+
67
+ ### Selection
68
+
69
+ ![A menu with three options that support selection](./assets/checkbox.png)
70
+
71
+ ```tsx
72
+ const [selectedItems, setSelectedItems] = React.useState([]);
73
+ const onCheckedChange = React.useCallback(
74
+ (e, checked) => {
75
+ setSelectedItems(checked);
76
+ },
77
+ [setSelectedItems],
78
+ );
79
+
80
+ const menuCheckbox = (
81
+ <Menu checked={selectedItems} onCheckedChange={onCheckedChange}>
82
+ <MenuTrigger>
83
+ <Button>Open menu</Button>
84
+ </MenuTrigger>
85
+ <MenuPopover>
86
+ <MenuList>
87
+ <MenuItemCheckbox name="checkbox1">Option 1</MenuItemCheckbox>
88
+ <MenuItemCheckbox name="checkbox2">Option 2</MenuItemCheckbox>
89
+ <MenuItemCheckbox name="checkbox3">Option 3</MenuItemCheckbox>
90
+ </MenuList>
91
+ </MenuPopover>
92
+ </Menu>
93
+ );
94
+ ```
95
+
96
+ ## Variants
97
+
98
+ ### Nested menus
99
+
100
+ A `Menu` should be able to trigger a submenu, or an additional instance of `Menu`, as a part of one or more of its options. The nested `Menu` component should have the same functional capabilities as the root `Menu` component, however it will have some default behavioral differences.
101
+
102
+ Nested menus are by default triggered by hovering over a trigger, but can also be opened by invoking the trigger component for the nested `Menu`.
103
+
104
+ ### Selection state
105
+
106
+ A `Menu` should be able to track and represent the selection, or checked, state of its options.
107
+
108
+ When an option has a configurable selection state, it does not dismiss the `Menu` when toggled, as opposed to other options which close the `Menu` on being invoked by default.
109
+
110
+ ### Sections
111
+
112
+ A `Menu` can be divided into sections using dividers. The `Menu` does not support `MenuGroups` yet, but can visually represent sections using `MenuDividers`.
113
+
114
+ ### Disabled option(s)
115
+
116
+ All options in a `Menu` component can be disabled and should provide a visible indication for this purpose. Although disabled actions cannot be invoked, they are keyboard focusable for the purposes of accessibility.
117
+
118
+ ## API
119
+
120
+ ### Menu
121
+
122
+ The root level component serves as a simplified interface for configuring the triggering of a Menu.
123
+
124
+ ```ts
125
+ export interface MenuProps extends MenuListProps {
126
+ /**
127
+ * Whether the popup is open on mount
128
+ */
129
+ defaultOpen?: boolean;
130
+
131
+ /**
132
+ * How much delay to have between hover in and showing the menu, in ms.
133
+ */
134
+ hoverDelay?: number;
135
+
136
+ /**
137
+ * Whether the popup is open
138
+ */
139
+ open?: boolean;
140
+
141
+ /**
142
+ * Call back when the component requests to change value
143
+ */
144
+ onOpenChange?: (e: InteractionEvent, isOpen: boolean) => void;
145
+
146
+ /*
147
+ * Opens the menu on hovering over the trigger
148
+ */
149
+ openOnHover?: boolean;
150
+
151
+ /**
152
+ * Do not dismiss the menu when a menu item is clicked
153
+ */
154
+ persistOnItemClick?: boolean;
155
+ }
156
+ ```
157
+
158
+ ### MenuTrigger
159
+
160
+ A non-visual component that wraps its child and configures them to be the trigger that will open a menu. This component should only accept one child. Accepts no other props.
161
+
162
+ ### MenuPopover
163
+
164
+ This component provides the temporary surface that will host the `Menu`'s options.
165
+
166
+ ```ts
167
+ export type MenuPopoverProps = ICalloutProps;
168
+ ```
169
+
170
+ ### MenuList
171
+
172
+ This component is used internally by `Menu` and manages the context and layout of its items.
173
+
174
+ #### MenuList Props
175
+
176
+ ```ts
177
+ export type MenuListProps = {
178
+ /**
179
+ * Array of all checked items
180
+ */
181
+ checked?: string[];
182
+
183
+ /**
184
+ * Default items to be checked on mount
185
+ */
186
+ defaultChecked?: string[];
187
+
188
+ /**
189
+ * States that menu items can contain selectable items and reserves space for item alignment
190
+ */
191
+ hasCheckmarks?: boolean;
192
+
193
+ /**
194
+ * Callback when checked items change
195
+ *
196
+ * @param checked Array of all currently checked values
197
+ */
198
+ onCheckedChange?: (e: InteractionEvent, checked[]) => void;
199
+
200
+ };
201
+ ```
202
+
203
+ #### MenuList Tokens
204
+
205
+ ```ts
206
+ export interface MenuListTokens extends LayoutTokens, IBackgroundColorTokens {
207
+ /**
208
+ * Space between items in pixels
209
+ */
210
+ gap?: number;
211
+ }
212
+ ```
213
+
214
+ #### MenuList Slots
215
+
216
+ - `root` - The container of the `Menu`'s options that wraps all `children`.
217
+
218
+ ### MenuDivider
219
+
220
+ Creates a divider element in the `MenuList`. This divider is purely visual and does not handle any grouping logic of the options in the `MenuList`.
221
+
222
+ ### MenuItem
223
+
224
+ #### MenuItem Props
225
+
226
+ ```ts
227
+ export interface MenuItemProps extends Omit<IWithPressableOptions<ViewProps>, 'onPress'> {
228
+ /**
229
+ * A RefObject to access the IButton interface. Use this to access the public methods and properties of the component.
230
+ */
231
+ componentRef?: React.RefObject<IFocusable>;
232
+
233
+ /**
234
+ * A callback to call on button click event
235
+ */
236
+ onClick?: (e: InteractionEvent) => void;
237
+
238
+ /**
239
+ * Do not dismiss the menu when a menu item is clicked
240
+ */
241
+ persistOnClick?: boolean;
242
+ }
243
+ ```
244
+
245
+ #### MenuItem Tokens
246
+
247
+ ```ts
248
+ export interface MenuItemTokens extends LayoutTokens, FontTokens, IBorderTokens, IColorTokens {
249
+ /**
250
+ * Height and width in pixels of the space that is reserved to align the item's text with other items which have checkmarks
251
+ */
252
+ checkmarkSize?: number;
253
+
254
+ /**
255
+ * Amount of space in pixels around the indicator that shows that an item has a submenu
256
+ */
257
+ submenuIndicatorPadding?: number;
258
+
259
+ /**
260
+ * Height and width in pixels of the indicator that shows that an item has a submenu
261
+ */
262
+ submenuIndicatorSize?: number;
263
+
264
+ /**
265
+ * Space between parts of the item control in pixels
266
+ */
267
+ gap?: number;
268
+
269
+ /**
270
+ * States of the item control
271
+ */
272
+ disabled?: MenuItemTokens;
273
+ focused?: MenuItemTokens;
274
+ hovered?: MenuItemTokens;
275
+ pressed?: MenuItemTokens;
276
+ }
277
+ ```
278
+
279
+ #### MenuItem Slots
280
+
281
+ - `root` - The outer container representing the `MenuItem` itself that wraps everything passed via the `children` prop.
282
+ - `content` - If specified, renders the `content` prop as text.
283
+ - `checkmark` - If specified, renders space such that the `content` aligns with other items which have checkmarks. Only used when the `Menu` has `hasCheckmarks`.
284
+ - `submenuIndicator` - If specified, renders an SVG which indicates that the `MenuItem` is a trigger for a nested `Menu`.
285
+
286
+ ### MenuItemCheckbox/Radio
287
+
288
+ Variants of `MenuItem` that allows a single or multiple selection state based on the value that it represents. These `MenuItems` do not support submenus. `MenuItemCheckbox` and `MenuItemRadio` share the same types for props, tokens, and slots.
289
+
290
+ #### MenuItemCheckbox/Radio Props
291
+
292
+ ```ts
293
+ export interface MenuItemCheckboxProps extends Omit<IWithPressableOptions<ViewProps>, 'onPress'> {
294
+ /**
295
+ * A RefObject to access the IButton interface. Use this to access the public methods and properties of the component.
296
+ */
297
+ componentRef?: React.RefObject<IFocusable>;
298
+
299
+ /**
300
+ * Identifier for the control
301
+ */
302
+ name: string;
303
+
304
+ /**
305
+ * Do not dismiss the menu when a menu item is clicked
306
+ */
307
+ persistOnClick?: boolean;
308
+ }
309
+ ```
310
+
311
+ #### MenuItemCheckbox/Radio Tokens
312
+
313
+ ```ts
314
+ export interface MenuItemCheckboxTokens extends LayoutTokens, FontTokens, IBorderTokens, IColorTokens {
315
+ /**
316
+ * Color of the checkmark icon
317
+ */
318
+ checkmarkColor?: ColorValue;
319
+
320
+ /**
321
+ * Amount of space in pixels around the checkmark icon
322
+ */
323
+ checkmarkPadding?: number;
324
+
325
+ /**
326
+ * Height and width in pixels of the checkmark icon
327
+ */
328
+ checkmarkSize?: number;
329
+
330
+ /**
331
+ * Opacity of the checkmark icon from 0 to 1
332
+ */
333
+ checkmarkVisibility?: number;
334
+
335
+ /**
336
+ * Space between parts of the item control in pixels
337
+ */
338
+ gap?: number;
339
+
340
+ /**
341
+ * States of the item control
342
+ */
343
+ checked?: MenuItemCheckboxTokens;
344
+ disabled?: MenuItemCheckboxTokens;
345
+ focused?: MenuItemCheckboxTokens;
346
+ hovered?: MenuItemCheckboxTokens;
347
+ pressed?: MenuItemCheckboxTokens;
348
+ }
349
+ ```
350
+
351
+ #### MenuItemCheckbox/Radio Slots
352
+
353
+ - `root` - The outer container representing the `MenuItem` itself that wraps everything passed via the `children` prop.
354
+ - `content` - If specified, renders the `content` prop as text.
355
+ - `checkmark` - If specified, renders an SVG which indicates that the `MenuItem` is selected.
356
+
357
+ ## Behaviors
358
+
359
+ ### Mouse interactions
360
+
361
+ - Clicking on a menu's trigger will open the menu
362
+ - Clicking outside of a menu's trigger and popover will light dismiss the menu
363
+ - Clicking on a `MenuItem` which is not configured to track selection will invoke the `MenuItem` and close the menu by default
364
+ - Clicking on a `MenuItem` variant which is configured to track selection will toggle its selection state in the configured way and not close the menu.
365
+ - If the menu is configured to open on hover, it will only close once the mouse leaves both the trigger and the popover. There is a delay for this behavior.
366
+ - Submenus are configured to open on hover by default. If the mouse stops hovering over the submenu, only the submenu will close.
367
+
368
+ ### Keyboard interactions
369
+
370
+ - When a menu is invoked via keyboard, open the menu and place focus on the first focusable element by default.
371
+ - Up and down inside of the menu that has focus should navigate vertically between keyboard focusable elements
372
+ - On win32, up and down should circularly navigate through a list of menu items. On MacOS, circular navigation does not occur.
373
+ - Right key on a menu item that has an available submenu or split button should invoke the submenu, and move focus into it onto the first focusable item (Left in RTL)
374
+ - Left key when in a submenu should close the submenu and place focus back on the parent menu's item that opened the submenu. (Right in RTL)
375
+ - ESC on a menu should close the currently focused menu. If focus is in a submenu and ESC is hit, it should only close the current submenu and return focus to the parent's element where focus was previously.
376
+ - Space and Enter key execute the action that is currently focused in the menu.
377
+
378
+ ### MenuItem selection
379
+
380
+ Below are the interactions that should be supported for all menu items that are required to handle a selection state.
381
+
382
+ In the event that the selection method is a radio, the previous selected item must be unselected.
383
+
384
+ | Type | Action | Result | Details |
385
+ | ------------- | ------ | ------ | -------------------------------------------- |
386
+ | Keyboard | Space | Toggle | Toggle the selection status of the menu item |
387
+ | Keyboard | Enter | Toggle | Toggle the selection status of the menu item |
388
+ | Mouse | Click | Toggle | Toggle the selection status of the menu item |
389
+ | Accessibility | Toggle | Toggle | Toggle the selection status of the menu item |
390
+
391
+ ### Positioning
392
+
393
+ #### Menu positioning
394
+
395
+ The default positioning for the root `Menu` is below the trigger and aligned with the left (or right in RTL) edge.
396
+
397
+ #### Submenu positioning
398
+
399
+ The default positioning for a submenu is to the right of the menu item trigger (or left in RTL) and aligned with the top edge.
400
+
401
+ ## Accessibility
402
+
403
+ The `MenuTrigger` will set `expand` or `collapsed` state and will respond to actions which explicitly tell it to expand or collapse (win32 only)
404
+ The `MenuPopover` has its role set to `menu`, and `MenuItmes` and variants have their role set to `menuitem`.
405
+ The `MenuItem` variants which track selection have the `Toggle` pattern available.
package/assets/Menu.png ADDED
Binary file
package/assets/Submenu.png ADDED
Binary file
package/assets/checkbox.png ADDED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fluentui-react-native/menu",
3
- "version": "0.16.1",
3
+ "version": "1.0.3",
4
4
  "description": "A cross-platform Menu component using the Fluent Design System",
5
5
  "main": "lib-commonjs/index.js",
6
6
  "module": "lib/index.js",
@@ -19,22 +19,22 @@
19
19
  "repository": {
20
20
  "type": "git",
21
21
  "url": "https://github.com/microsoft/fluentui-react-native.git",
22
- "directory": "packages/experimental/menu"
22
+ "directory": "packages/components/menu"
23
23
  },
24
24
  "dependencies": {
25
25
  "@fluentui-react-native/adapters": ">=0.8.5 <1.0.0",
26
- "@fluentui-react-native/callout": ">=0.20.8 <1.0.0",
27
- "@fluentui-react-native/experimental-text": ">=0.9.0 <1.0.0",
28
- "@fluentui-react-native/framework": "0.7.30",
29
- "@fluentui-react-native/interactive-hooks": ">=0.16.3 <1.0.0",
26
+ "@fluentui-react-native/callout": ">=0.20.9 <1.0.0",
27
+ "@fluentui-react-native/experimental-text": ">=0.9.1 <1.0.0",
28
+ "@fluentui-react-native/framework": "0.7.31",
29
+ "@fluentui-react-native/interactive-hooks": ">=0.16.4 <1.0.0",
30
30
  "@fluentui-react-native/theme-tokens": ">=0.18.0 <1.0.0",
31
- "@fluentui-react-native/tokens": ">=0.14.0 <1.0.0",
31
+ "@fluentui-react-native/tokens": ">=0.15.0 <1.0.0",
32
32
  "@fluentui-react-native/use-styling": ">=0.8.3 <1.0.0",
33
33
  "react-native-svg": "^12.3.0",
34
34
  "tslib": "^2.3.1"
35
35
  },
36
36
  "devDependencies": {
37
- "@fluentui-react-native/button": ">=0.22.29 <1.0.0",
37
+ "@fluentui-react-native/button": ">=0.22.30 <1.0.0",
38
38
  "@fluentui-react-native/eslint-config-rules": "^0.1.1",
39
39
  "@fluentui-react-native/scripts": "^0.1.1",
40
40
  "@fluentui-react-native/test-tools": ">=0.1.1 <1.0.0",