@m3e/nav-menu 1.0.0-rc.3 โ 1.0.0-rc.4
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.
- package/README.md +57 -5
- package/dist/css-custom-data.json +10 -0
- package/dist/custom-elements.json +132 -12
- package/dist/html-custom-data.json +8 -2
- package/dist/index.js +846 -662
- package/dist/index.js.map +1 -1
- package/dist/index.min.js +81 -64
- package/dist/index.min.js.map +1 -1
- package/dist/src/NavMenuElement.d.ts +29 -2
- package/dist/src/NavMenuElement.d.ts.map +1 -1
- package/dist/src/NavMenuItemElement.d.ts +32 -3
- package/dist/src/NavMenuItemElement.d.ts.map +1 -1
- package/dist/src/NavMenuItemGroupElement.d.ts +63 -0
- package/dist/src/NavMenuItemGroupElement.d.ts.map +1 -0
- package/dist/src/index.d.ts +1 -0
- package/dist/src/index.d.ts.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @m3e/nav-menu
|
|
2
2
|
|
|
3
|
-
The `m3e-nav-menu`
|
|
3
|
+
The `m3e-nav-menu` component provides a hierarchical, accessible navigation menu. Designed for sidebars, navigation drawers, and complex menu structures, it supports nested expandable items, keyboard navigation, selection, and extensive theming via CSS custom properties.
|
|
4
4
|
|
|
5
5
|
> **This package is part of [M3E](https://github.com/matraic/m3e) monorepo**, a unified suite of Material 3 web components. [Explore the docs](https://matraic.github.io/m3e) to see them in action.
|
|
6
6
|
|
|
@@ -27,7 +27,7 @@ Alternately, you can explicitly reference the `html-custom-data.json` and `css-c
|
|
|
27
27
|
}
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
## ๐
|
|
30
|
+
## ๐ Native Module Support
|
|
31
31
|
|
|
32
32
|
This package uses [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#module_specifiers). To use it directly in a browser without a bundler, use a module script similar to the following.
|
|
33
33
|
|
|
@@ -53,10 +53,44 @@ In addition, you must use an [import map](https://developer.mozilla.org/en-US/do
|
|
|
53
53
|
|
|
54
54
|
## ๐๏ธ Elements
|
|
55
55
|
|
|
56
|
-
- `m3e-nav-menu` โ
|
|
57
|
-
- `m3e-nav-menu-item` โ An expandable item
|
|
56
|
+
- `m3e-nav-menu` โ A hierarchical menu, typically used on larger devices, that allows a user to switch between views.
|
|
57
|
+
- `m3e-nav-menu-item` โ An expandable item, selectable item within a navigation menu.
|
|
58
|
+
- `m3e-nav-menu-item-group` โ A top-level semantic grouping of items in a navigation menu.
|
|
58
59
|
|
|
59
|
-
## ๐งช
|
|
60
|
+
## ๐งช Examples
|
|
61
|
+
|
|
62
|
+
The following example illustrates a navigation menu with a top-level group of menu items.
|
|
63
|
+
|
|
64
|
+
```html
|
|
65
|
+
<m3e-nav-menu>
|
|
66
|
+
<m3e-nav-menu-item-group>
|
|
67
|
+
<m3e-heading slot="label" variant="label" size="large">Mail</m3e-heading>
|
|
68
|
+
|
|
69
|
+
<m3e-nav-menu-item>
|
|
70
|
+
<m3e-icon slot="icon" name="mail"></m3e-icon>
|
|
71
|
+
<span slot="label">Inbox</span>
|
|
72
|
+
<span slot="badge">24</span>
|
|
73
|
+
</m3e-nav-menu-item>
|
|
74
|
+
|
|
75
|
+
<m3e-nav-menu-item>
|
|
76
|
+
<m3e-icon slot="icon" name="send"></m3e-icon>
|
|
77
|
+
<span slot="label">Outbox</span>
|
|
78
|
+
</m3e-nav-menu-item>
|
|
79
|
+
|
|
80
|
+
<m3e-nav-menu-item>
|
|
81
|
+
<m3e-icon slot="icon" name="favorite"></m3e-icon>
|
|
82
|
+
<span slot="label">Favorites</span>
|
|
83
|
+
</m3e-nav-menu-item>
|
|
84
|
+
|
|
85
|
+
<m3e-nav-menu-item>
|
|
86
|
+
<m3e-icon slot="icon" name="delete"></m3e-icon>
|
|
87
|
+
<span slot="label">Trash</span>
|
|
88
|
+
</m3e-nav-menu-item>
|
|
89
|
+
</m3e-nav-menu-item-group>
|
|
90
|
+
</m3e-nav-menu>
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The next example illustrates a multilevel navigation menu.
|
|
60
94
|
|
|
61
95
|
```html
|
|
62
96
|
<m3e-nav-menu>
|
|
@@ -174,6 +208,24 @@ This section details the attributes, slots, events, and CSS custom properties av
|
|
|
174
208
|
| `--m3e-nav-menu-divider-margin` | Margin for divider elements. |
|
|
175
209
|
| `--m3e-nav-menu-item-vertical-inset` | Vertical margin for first/last child items. |
|
|
176
210
|
|
|
211
|
+
### ๐๏ธ m3e-nav-menu-item-group
|
|
212
|
+
|
|
213
|
+
This section details the slots and CSS custom properties available for the `m3e-nav-menu-item-group` component.
|
|
214
|
+
|
|
215
|
+
#### ๐งฉ Slots
|
|
216
|
+
|
|
217
|
+
| Slot | Description |
|
|
218
|
+
| ----------- | ------------------------------- |
|
|
219
|
+
| _(default)_ | Renders the items of the group. |
|
|
220
|
+
| `label` | Renders the label of the group. |
|
|
221
|
+
|
|
222
|
+
#### ๐๏ธ CSS Custom Properties
|
|
223
|
+
|
|
224
|
+
| Property | Description |
|
|
225
|
+
| --------------------------------------- | -------------------------------------------------- |
|
|
226
|
+
| `--m3e-nav-menu-item-group-label-inset` | Insets the label from the start edge of the group. |
|
|
227
|
+
| `--m3e-nav-menu-item-group-label-space` | Vertical spacing around the group's label. |
|
|
228
|
+
|
|
177
229
|
## ๐ค Contributing
|
|
178
230
|
|
|
179
231
|
See the root monorepo `CONTRIBUTING.md` for guidelines on contributing to this package.
|
|
@@ -191,6 +191,16 @@
|
|
|
191
191
|
"name": "--m3e-nav-menu-item-vertical-inset",
|
|
192
192
|
"description": "Vertical margin for first/last child items.",
|
|
193
193
|
"values": []
|
|
194
|
+
},
|
|
195
|
+
{
|
|
196
|
+
"name": "--m3e-nav-menu-item-group-label-inset",
|
|
197
|
+
"description": "Insets the label from the start edge of the group.",
|
|
198
|
+
"values": []
|
|
199
|
+
},
|
|
200
|
+
{
|
|
201
|
+
"name": "--m3e-nav-menu-item-group-label-space",
|
|
202
|
+
"description": "Vertical spacing around the group's label.",
|
|
203
|
+
"values": []
|
|
194
204
|
}
|
|
195
205
|
],
|
|
196
206
|
"pseudoElements": []
|
|
@@ -22,6 +22,14 @@
|
|
|
22
22
|
"name": "*",
|
|
23
23
|
"package": "\"./NavMenuItemElement\""
|
|
24
24
|
}
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"kind": "js",
|
|
28
|
+
"name": "*",
|
|
29
|
+
"declaration": {
|
|
30
|
+
"name": "*",
|
|
31
|
+
"package": "\"./NavMenuItemGroupElement\""
|
|
32
|
+
}
|
|
25
33
|
}
|
|
26
34
|
]
|
|
27
35
|
},
|
|
@@ -31,7 +39,7 @@
|
|
|
31
39
|
"declarations": [
|
|
32
40
|
{
|
|
33
41
|
"kind": "class",
|
|
34
|
-
"description": "
|
|
42
|
+
"description": "A hierarchical menu, typically used on larger devices, that allows a user to switch between views.",
|
|
35
43
|
"name": "M3eNavMenuElement",
|
|
36
44
|
"cssProperties": [
|
|
37
45
|
{
|
|
@@ -342,7 +350,7 @@
|
|
|
342
350
|
"declarations": [
|
|
343
351
|
{
|
|
344
352
|
"kind": "class",
|
|
345
|
-
"description": "An expandable item
|
|
353
|
+
"description": "An expandable item, selectable item within a navigation menu.",
|
|
346
354
|
"name": "M3eNavMenuItemElement",
|
|
347
355
|
"cssProperties": [
|
|
348
356
|
{
|
|
@@ -483,6 +491,10 @@
|
|
|
483
491
|
"description": "Renders the icon of the item.",
|
|
484
492
|
"name": "icon"
|
|
485
493
|
},
|
|
494
|
+
{
|
|
495
|
+
"description": "Renders the badge of the item.",
|
|
496
|
+
"name": "badge"
|
|
497
|
+
},
|
|
486
498
|
{
|
|
487
499
|
"description": "Renders the icon of the item when selected.",
|
|
488
500
|
"name": "selected-icon"
|
|
@@ -937,6 +949,111 @@
|
|
|
937
949
|
}
|
|
938
950
|
]
|
|
939
951
|
},
|
|
952
|
+
{
|
|
953
|
+
"kind": "javascript-module",
|
|
954
|
+
"path": "src/NavMenuItemGroupElement.ts",
|
|
955
|
+
"declarations": [
|
|
956
|
+
{
|
|
957
|
+
"kind": "class",
|
|
958
|
+
"description": "A top-level semantic grouping of items in a navigation menu.",
|
|
959
|
+
"name": "M3eNavMenuItemGroupElement",
|
|
960
|
+
"cssProperties": [
|
|
961
|
+
{
|
|
962
|
+
"description": "Insets the label from the start edge of the group.",
|
|
963
|
+
"name": "--m3e-nav-menu-item-group-label-inset"
|
|
964
|
+
},
|
|
965
|
+
{
|
|
966
|
+
"description": "Vertical spacing around the group's label.",
|
|
967
|
+
"name": "--m3e-nav-menu-item-group-label-space"
|
|
968
|
+
}
|
|
969
|
+
],
|
|
970
|
+
"slots": [
|
|
971
|
+
{
|
|
972
|
+
"description": "Renders the items of the group.",
|
|
973
|
+
"name": ""
|
|
974
|
+
},
|
|
975
|
+
{
|
|
976
|
+
"description": "Renders the label of the group.",
|
|
977
|
+
"name": "label"
|
|
978
|
+
}
|
|
979
|
+
],
|
|
980
|
+
"members": [
|
|
981
|
+
{
|
|
982
|
+
"kind": "field",
|
|
983
|
+
"name": "__nextId",
|
|
984
|
+
"type": {
|
|
985
|
+
"text": "number"
|
|
986
|
+
},
|
|
987
|
+
"privacy": "private",
|
|
988
|
+
"static": true,
|
|
989
|
+
"default": "0"
|
|
990
|
+
},
|
|
991
|
+
{
|
|
992
|
+
"kind": "field",
|
|
993
|
+
"name": "#labelId",
|
|
994
|
+
"privacy": "private",
|
|
995
|
+
"default": "`m3e-nav-menu-item-group-label-${M3eNavMenuItemGroupElement.__nextId++}`"
|
|
996
|
+
},
|
|
997
|
+
{
|
|
998
|
+
"kind": "field",
|
|
999
|
+
"name": "#label",
|
|
1000
|
+
"privacy": "private",
|
|
1001
|
+
"type": {
|
|
1002
|
+
"text": "Element | undefined"
|
|
1003
|
+
}
|
|
1004
|
+
},
|
|
1005
|
+
{
|
|
1006
|
+
"kind": "method",
|
|
1007
|
+
"name": "#handleLabelSlotChange",
|
|
1008
|
+
"privacy": "private",
|
|
1009
|
+
"return": {
|
|
1010
|
+
"type": {
|
|
1011
|
+
"text": "void"
|
|
1012
|
+
}
|
|
1013
|
+
},
|
|
1014
|
+
"parameters": [
|
|
1015
|
+
{
|
|
1016
|
+
"name": "e",
|
|
1017
|
+
"type": {
|
|
1018
|
+
"text": "Event"
|
|
1019
|
+
}
|
|
1020
|
+
}
|
|
1021
|
+
]
|
|
1022
|
+
}
|
|
1023
|
+
],
|
|
1024
|
+
"mixins": [
|
|
1025
|
+
{
|
|
1026
|
+
"name": "Role",
|
|
1027
|
+
"package": "@m3e/core"
|
|
1028
|
+
}
|
|
1029
|
+
],
|
|
1030
|
+
"superclass": {
|
|
1031
|
+
"name": "LitElement",
|
|
1032
|
+
"package": "lit"
|
|
1033
|
+
},
|
|
1034
|
+
"tagName": "m3e-nav-menu-item-group",
|
|
1035
|
+
"customElement": true
|
|
1036
|
+
}
|
|
1037
|
+
],
|
|
1038
|
+
"exports": [
|
|
1039
|
+
{
|
|
1040
|
+
"kind": "js",
|
|
1041
|
+
"name": "M3eNavMenuItemGroupElement",
|
|
1042
|
+
"declaration": {
|
|
1043
|
+
"name": "M3eNavMenuItemGroupElement",
|
|
1044
|
+
"module": "src/NavMenuItemGroupElement.ts"
|
|
1045
|
+
}
|
|
1046
|
+
},
|
|
1047
|
+
{
|
|
1048
|
+
"kind": "custom-element-definition",
|
|
1049
|
+
"name": "m3e-nav-menu-item-group",
|
|
1050
|
+
"declaration": {
|
|
1051
|
+
"name": "M3eNavMenuItemGroupElement",
|
|
1052
|
+
"module": "src/NavMenuItemGroupElement.ts"
|
|
1053
|
+
}
|
|
1054
|
+
}
|
|
1055
|
+
]
|
|
1056
|
+
},
|
|
940
1057
|
{
|
|
941
1058
|
"kind": "javascript-module",
|
|
942
1059
|
"path": "../core/src/shared/mixins/AttachInternals.ts",
|
|
@@ -2635,6 +2752,11 @@
|
|
|
2635
2752
|
"kind": "javascript-module",
|
|
2636
2753
|
"path": "../core/src/shared/mixins/Labelled.ts",
|
|
2637
2754
|
"declarations": [
|
|
2755
|
+
{
|
|
2756
|
+
"kind": "variable",
|
|
2757
|
+
"name": "updateLabels",
|
|
2758
|
+
"description": "A symbol through which to update labels to reflect a control's current state."
|
|
2759
|
+
},
|
|
2638
2760
|
{
|
|
2639
2761
|
"kind": "function",
|
|
2640
2762
|
"name": "isLabelledMixin",
|
|
@@ -2684,16 +2806,6 @@
|
|
|
2684
2806
|
},
|
|
2685
2807
|
"description": "The label elements that the element is associated with.",
|
|
2686
2808
|
"readonly": true
|
|
2687
|
-
},
|
|
2688
|
-
{
|
|
2689
|
-
"kind": "method",
|
|
2690
|
-
"name": "[_updateLabels]",
|
|
2691
|
-
"privacy": "private",
|
|
2692
|
-
"return": {
|
|
2693
|
-
"type": {
|
|
2694
|
-
"text": "void"
|
|
2695
|
-
}
|
|
2696
|
-
}
|
|
2697
2809
|
}
|
|
2698
2810
|
],
|
|
2699
2811
|
"parameters": [
|
|
@@ -2708,6 +2820,14 @@
|
|
|
2708
2820
|
}
|
|
2709
2821
|
],
|
|
2710
2822
|
"exports": [
|
|
2823
|
+
{
|
|
2824
|
+
"kind": "js",
|
|
2825
|
+
"name": "updateLabels",
|
|
2826
|
+
"declaration": {
|
|
2827
|
+
"name": "updateLabels",
|
|
2828
|
+
"module": "../core/src/shared/mixins/Labelled.ts"
|
|
2829
|
+
}
|
|
2830
|
+
},
|
|
2711
2831
|
{
|
|
2712
2832
|
"kind": "js",
|
|
2713
2833
|
"name": "isLabelledMixin",
|
|
@@ -4,13 +4,13 @@
|
|
|
4
4
|
"tags": [
|
|
5
5
|
{
|
|
6
6
|
"name": "m3e-nav-menu",
|
|
7
|
-
"description": "
|
|
7
|
+
"description": "A hierarchical menu, typically used on larger devices, that allows a user to switch between views.\n---\n\n\n### **Methods:**\n - **expand(items: _M3eNavMenuItemElement | undefined_): _void_** - Expands the specified items, or all items if no items are provided.\n- **collapse(items: _M3eNavMenuItemElement | undefined_): _void_** - Collapses the specified items, or all items if no items are provided.\n\n### **Slots:**\n - _default_ - Renders the items of the menu.\n\n### **CSS Properties:**\n - **--m3e-nav-menu-padding-top** - Top padding for the menu. _(default: undefined)_\n- **--m3e-nav-menu-padding-bottom** - Bottom padding for the menu. _(default: undefined)_\n- **--m3e-nav-menu-padding-left** - Left padding for the menu. _(default: undefined)_\n- **--m3e-nav-menu-padding-right** - Right padding for the menu. _(default: undefined)_\n- **--m3e-nav-menu-divider-margin** - Margin for divider elements in the menu. _(default: undefined)_\n- **--m3e-nav-menu-scrollbar-width** - Width of the menu scrollbar. _(default: undefined)_\n- **--m3e-nav-menu-scrollbar-color** - Color of the menu scrollbar. _(default: undefined)_",
|
|
8
8
|
"attributes": [],
|
|
9
9
|
"references": []
|
|
10
10
|
},
|
|
11
11
|
{
|
|
12
12
|
"name": "m3e-nav-menu-item",
|
|
13
|
-
"description": "An expandable item
|
|
13
|
+
"description": "An expandable item, selectable item within a navigation menu.\n---\n\n\n### **Events:**\n - **opening** - Emitted when the item begins to open.\n- **opened** - Emitted when the item has opened.\n- **closing** - Emitted when the item begins to close.\n- **closed** - Emitted when the item has closed.\n- **click** - Emitted when the element is clicked.\n\n### **Methods:**\n - **expand(descendants: _boolean_): _void_** - Expands this item, and optionally, all descendants.\n- **collapse(descendants: _boolean_): _void_** - Collapses this item, and optionally, all descendants.\n- **toggle(): _void_** - Toggles the expanded state of the item.\n\n### **Slots:**\n - _default_ - Renders the nested child items.\n- **label** - Renders the label of the item.\n- **icon** - Renders the icon of the item.\n- **badge** - Renders the badge of the item.\n- **selected-icon** - Renders the icon of the item when selected.\n- **toggle-icon** - Renders the toggle icon.\n\n### **CSS Properties:**\n - **--m3e-nav-menu-item-font-size** - Font size for the item label. _(default: undefined)_\n- **--m3e-nav-menu-item-font-weight** - Font weight for the item label. _(default: undefined)_\n- **--m3e-nav-menu-item-line-height** - Line height for the item label. _(default: undefined)_\n- **--m3e-nav-menu-item-tracking** - Letter spacing for the item label. _(default: undefined)_\n- **--m3e-nav-menu-item-padding** - Inline padding for the item. _(default: undefined)_\n- **--m3e-nav-menu-item-height** - Height of the item. _(default: undefined)_\n- **--m3e-nav-menu-item-spacing** - Spacing between icon and label. _(default: undefined)_\n- **--m3e-nav-menu-item-shape** - Border radius of the item and focus ring. _(default: undefined)_\n- **--m3e-nav-menu-item-icon-size** - Size of the icon. _(default: undefined)_\n- **--m3e-nav-menu-item-inset** - Indentation for nested items. _(default: undefined)_\n- **--m3e-nav-menu-item-label-color** - Text color for the item label. _(default: undefined)_\n- **--m3e-nav-menu-item-selected-label-color** - Text color for selected item label. _(default: undefined)_\n- **--m3e-nav-menu-item-selected-container-color** - Background color for selected item. _(default: undefined)_\n- **--m3e-nav-menu-item-selected-container-focus-color** - Focus color for selected item container. _(default: undefined)_\n- **--m3e-nav-menu-item-selected-container-hover-color** - Hover color for selected item container. _(default: undefined)_\n- **--m3e-nav-menu-item-selected-ripple-color** - Ripple color for selected item. _(default: undefined)_\n- **--m3e-nav-menu-item-unselected-container-focus-color** - Focus color for unselected item container. _(default: undefined)_\n- **--m3e-nav-menu-item-unselected-container-hover-color** - Hover color for unselected item container. _(default: undefined)_\n- **--m3e-nav-menu-item-unselected-ripple-color** - Ripple color for unselected item. _(default: undefined)_\n- **--m3e-nav-menu-item-open-container-color** - Background color for open item with children. _(default: undefined)_\n- **--m3e-nav-menu-item-open-container-focus-color** - Focus color for open item container. _(default: undefined)_\n- **--m3e-nav-menu-item-open-container-hover-color** - Hover color for open item container. _(default: undefined)_\n- **--m3e-nav-menu-item-open-ripple-color** - Ripple color for open item. _(default: undefined)_\n- **--m3e-nav-menu-item-disabled-color** - Text color for disabled item. _(default: undefined)_\n- **--m3e-nav-menu-item-disabled-color-opacity** - Opacity for disabled item text color. _(default: undefined)_\n- **--m3e-nav-menu-item-badge-font-size** - Font size for badge slot. _(default: undefined)_\n- **--m3e-nav-menu-item-badge-font-weight** - Font weight for badge slot. _(default: undefined)_\n- **--m3e-nav-menu-item-badge-line-height** - Line height for badge slot. _(default: undefined)_\n- **--m3e-nav-menu-badge-item-tracking** - Letter spacing for badge slot. _(default: undefined)_\n- **--m3e-nav-menu-divider-margin** - Margin for divider elements. _(default: undefined)_\n- **--m3e-nav-menu-item-vertical-inset** - Vertical margin for first/last child items. _(default: undefined)_",
|
|
14
14
|
"attributes": [
|
|
15
15
|
{
|
|
16
16
|
"name": "disabled",
|
|
@@ -34,6 +34,12 @@
|
|
|
34
34
|
}
|
|
35
35
|
],
|
|
36
36
|
"references": []
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
"name": "m3e-nav-menu-item-group",
|
|
40
|
+
"description": "A top-level semantic grouping of items in a navigation menu.\n---\n\n\n### **Slots:**\n - _default_ - Renders the items of the group.\n- **label** - Renders the label of the group.\n\n### **CSS Properties:**\n - **--m3e-nav-menu-item-group-label-inset** - Insets the label from the start edge of the group. _(default: undefined)_\n- **--m3e-nav-menu-item-group-label-space** - Vertical spacing around the group's label. _(default: undefined)_",
|
|
41
|
+
"attributes": [],
|
|
42
|
+
"references": []
|
|
37
43
|
}
|
|
38
44
|
]
|
|
39
45
|
}
|