@m3e/app-bar 1.0.0-rc.2

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/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 matraic
4
+ Contact: matraic@yahoo.com
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,186 @@
1
+ # @m3e/app-bar
2
+
3
+ The `m3e-app-bar` component is a prominent user interface component that provides consistent access to key actions, navigation, and contextual information at the top of an application screen. Designed according to Material 3 principles, it organizes content with clear hierarchy, supports dynamic color, elevation, alignment, and adapts to scrolling behavior.
4
+
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
+
7
+ ## ๐Ÿ“ฆ Installation
8
+
9
+ ```bash
10
+ npm install @m3e/app-bar
11
+ ```
12
+
13
+ ## ๐Ÿ’ป Editor Integration
14
+
15
+ This package includes a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) to support enhanced editor tooling and developer experience.
16
+
17
+ ### Visual Studio Code
18
+
19
+ To enable autocomplete and hover documentation for `@m3e/app-bar`, install the [Custom Elements Manifest Language Server](https://marketplace.visualstudio.com/items?itemName=pwrs.cem-language-server-vscode) extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.
20
+
21
+ Alternately, you can explicitly reference the `html-custom-data.json` and `css-custom-data.json` in your workspace settings:
22
+
23
+ ```json
24
+ {
25
+ "html.customData": ["./node_modules/@m3e/app-bar/dist/html-custom-data.json"],
26
+ "css.customData": ["./node_modules/@m3e/app-bar/dist/css-custom-data.json"]
27
+ }
28
+ ```
29
+
30
+ ## ๐Ÿš€ Browser Usage
31
+
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
+
34
+ ```html
35
+ <script type="module" src="/node_modules/@m3e/app-bar/dist/index.js"></script>
36
+ ```
37
+
38
+ In addition, you must use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) to include dependencies.
39
+
40
+ ```html
41
+ <script type="importmap">
42
+ {
43
+ "imports": {
44
+ "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
45
+ "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
46
+ }
47
+ }
48
+ </script>
49
+ ```
50
+
51
+ > For production, use index.min.js for faster load times.
52
+
53
+ ## ๐Ÿ—‚๏ธ Elements
54
+
55
+ - `m3e-app-bar` โ€” A bar, placed a the top of a screen, used to help users navigate through an application.
56
+
57
+ ## ๐Ÿงช Examples
58
+
59
+ The following example illustrates a medium size `m3e-app-bar` consisting of a leading button, title, subtitle, and trailing button.
60
+
61
+ > This example uses the `@m3e/icon` package to present Material Design symbols, but any icon package can be substituted depending on your design system or preferences
62
+
63
+ ```html
64
+ <m3e-app-bar size="medium">
65
+ <m3e-icon-button slot="leading-icon" aria-label="Back">
66
+ <m3e-icon name="arrow_back"></m3e-icon>
67
+ </m3e-icon-button>
68
+ <span slot="title">Top 10 hiking trails</span>
69
+ <span slot="subtitle">Discover popular trails</span>
70
+ <m3e-icon-button slot="trailing-icon" aria-label="Bookmark" variant="tonal">
71
+ <m3e-icon name="bookmark" filled></m3e-icon>
72
+ </m3e-icon-button>
73
+ </m3e-app-bar>
74
+ ```
75
+
76
+ The next example illustrates how to attach an app bar to a parent scroll container to produce elevation on scroll. In this example, the `for` attribute is used to attach a sticky-positioned `m3e-app-bar` to a parenting container styled to overflow vertically. When scrolled, the app bar will automatically transition to an elevated state.
77
+
78
+ ```html
79
+ <div style="overflow-y: auto; height: 300px" id="scrollContainer">
80
+ <m3e-app-bar for="scrollContainer" style="position: sticky; top: 0">
81
+ <span slot="title">Title</span>
82
+ </m3e-app-bar>
83
+ <div style="height: 400px; display: flex; align-items: center; justify-content: center">I am scrolling content</div>
84
+ </div>
85
+ ```
86
+
87
+ ## ๐Ÿ“– API Reference
88
+
89
+ This section details the attributes, slots and CSS custom properties available for the `m3e-app-bar` component.
90
+
91
+ ### โš™๏ธ Attributes
92
+
93
+ | Attribute | Type | Default | Description |
94
+ | ---------- | -------------------------------- | --------- | ---------------------------------------------------------------------------- |
95
+ | `centered` | `boolean` | `false` | Whether the title and subtitle are centered. |
96
+ | `size` | `"small" \| "medium" \| "large"` | `"small"` | The size of the bar. |
97
+ | `for` | `string` | | The identifier of the interactive control to which this element is attached. |
98
+
99
+ ### ๐Ÿงฉ Slots
100
+
101
+ | Slot | Description |
102
+ | --------------- | ------------------------ |
103
+ | `leading-icon` | Renders a leading icon. |
104
+ | `title` | Renders the title. |
105
+ | `subtitle` | Renders the subtitle. |
106
+ | `trailing-icon` | Renders a trailing icon. |
107
+
108
+ ### ๐ŸŽ›๏ธ CSS Custom Properties
109
+
110
+ The `m3e-app-bar` component supports theming via scoped CSS custom properties for layout, color, elevation, and interaction states.
111
+
112
+ #### Container & Color Properties
113
+
114
+ | Property | Description |
115
+ | --------------------------------------------- | -------------------------------------------- |
116
+ | `--m3e-app-bar-container-color` | Background color of the app bar container. |
117
+ | `--m3e-app-bar-container-color-on-scroll` | Background color when scrolled. |
118
+ | `--m3e-app-bar-container-elevation` | Elevation (shadow) of the app bar container. |
119
+ | `--m3e-app-bar-container-elevation-on-scroll` | Elevation (shadow) when scrolled. |
120
+ | `--m3e-app-bar-title-text-color` | Color of the app bar title text. |
121
+ | `--m3e-app-bar-subtitle-text-color` | Color of the app bar subtitle text. |
122
+ | `--m3e-app-bar-padding-left` | Left padding for the app bar container. |
123
+ | `--m3e-app-bar-padding-right` | Right padding for the app bar container. |
124
+
125
+ #### Small Size Properties
126
+
127
+ | Property | Description |
128
+ | ----------------------------------------------- | ------------------------------------------------ |
129
+ | `--m3e-app-bar-small-container-height` | Height of the small app bar container. |
130
+ | `--m3e-app-bar-small-title-text-font-size` | Font size for the small app bar title text. |
131
+ | `--m3e-app-bar-small-title-text-font-weight` | Font weight for the small app bar title text. |
132
+ | `--m3e-app-bar-small-title-text-line-height` | Line height for the small app bar title text. |
133
+ | `--m3e-app-bar-small-subtitle-text-tracking` | Letter spacing for the small app bar title text. |
134
+ | `--m3e-app-bar-small-subtitle-text-font-size` | Font size for the small app bar subtitle text. |
135
+ | `--m3e-app-bar-small-subtitle-text-font-weight` | Font weight for the small app bar subtitle text. |
136
+ | `--m3e-app-bar-small-subtitle-text-line-height` | Line height for the small app bar subtitle text. |
137
+ | `--m3e-app-bar-small-heading-padding-left` | Left padding for the small app bar heading. |
138
+ | `--m3e-app-bar-small-heading-padding-right` | Right padding for the small app bar heading. |
139
+
140
+ #### Medium Size Properties
141
+
142
+ | Property | Description |
143
+ | ----------------------------------------------------- | ------------------------------------------------- |
144
+ | `--m3e-app-bar-medium-container-height` | Height of the medium app bar container. |
145
+ | `--m3e-app-bar-medium-container-height-with-subtitle` | Height of the medium app bar with subtitle. |
146
+ | `--m3e-app-bar-medium-title-text-font-size` | Font size for the medium app bar title text. |
147
+ | `--m3e-app-bar-medium-title-text-font-weight` | Font weight for the medium app bar title text. |
148
+ | `--m3e-app-bar-medium-title-text-line-height` | Line height for the medium app bar title text. |
149
+ | `--m3e-app-bar-medium-subtitle-text-tracking` | Letter spacing for the medium app bar title text. |
150
+ | `--m3e-app-bar-medium-subtitle-text-font-size` | Font size for the medium app bar subtitle text. |
151
+ | `--m3e-app-bar-medium-subtitle-text-font-weight` | Font weight for the medium app bar subtitle text. |
152
+ | `--m3e-app-bar-medium-subtitle-text-line-height` | Line height for the medium app bar subtitle text. |
153
+ | `--m3e-app-bar-medium-heading-padding-left` | Left padding for the medium app bar heading. |
154
+ | `--m3e-app-bar-medium-heading-padding-right` | Right padding for the medium app bar heading. |
155
+ | `--m3e-app-bar-medium-padding-top` | Top padding for the medium app bar. |
156
+ | `--m3e-app-bar-medium-padding-bottom` | Bottom padding for the medium app bar. |
157
+ | `--m3e-app-bar-medium-title-max-lines` | Max lines for the medium app bar title. |
158
+ | `--m3e-app-bar-medium-subtitle-max-lines` | Max lines for the medium app bar subtitle. |
159
+
160
+ #### Large Size Properties
161
+
162
+ | Property | Description |
163
+ | ---------------------------------------------------- | ------------------------------------------------ |
164
+ | `--m3e-app-bar-large-container-height` | Height of the large app bar container. |
165
+ | `--m3e-app-bar-large-container-height-with-subtitle` | Height of the large app bar with subtitle. |
166
+ | `--m3e-app-bar-large-title-text-font-size` | Font size for the large app bar title text. |
167
+ | `--m3e-app-bar-large-title-text-font-weight` | Font weight for the large app bar title text. |
168
+ | `--m3e-app-bar-large-title-text-line-height` | Line height for the large app bar title text. |
169
+ | `--m3e-app-bar-large-subtitle-text-tracking` | Letter spacing for the large app bar title text. |
170
+ | `--m3e-app-bar-large-subtitle-text-font-size` | Font size for the large app bar subtitle text. |
171
+ | `--m3e-app-bar-large-subtitle-text-font-weight` | Font weight for the large app bar subtitle text. |
172
+ | `--m3e-app-bar-large-subtitle-text-line-height` | Line height for the large app bar subtitle text. |
173
+ | `--m3e-app-bar-large-heading-padding-left` | Left padding for the large app bar heading. |
174
+ | `--m3e-app-bar-large-heading-padding-right` | Right padding for the large app bar heading. |
175
+ | `--m3e-app-bar-large-padding-top` | Top padding for the large app bar. |
176
+ | `--m3e-app-bar-large-padding-bottom` | Bottom padding for the large app bar. |
177
+ | `--m3e-app-bar-large-title-max-lines` | Max lines for the large app bar title. |
178
+ | `--m3e-app-bar-large-subtitle-max-lines` | Max lines for the large app bar subtitle. |
179
+
180
+ ## ๐Ÿค Contributing
181
+
182
+ See the root monorepo `CONTRIBUTING.md` for guidelines on contributing to this package.
183
+
184
+ ## ๐Ÿ“„ License
185
+
186
+ This package is licensed under the MIT License.
@@ -0,0 +1,262 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
3
+ "version": 1.1,
4
+ "properties": [
5
+ {
6
+ "name": "--m3e-app-bar-container-color",
7
+ "description": "Background color of the app bar container.",
8
+ "values": []
9
+ },
10
+ {
11
+ "name": "--m3e-app-bar-container-color-on-scroll",
12
+ "description": "Background color of the app bar container when scrolled.",
13
+ "values": []
14
+ },
15
+ {
16
+ "name": "--m3e-app-bar-container-elevation",
17
+ "description": "Elevation (shadow) of the app bar container.",
18
+ "values": []
19
+ },
20
+ {
21
+ "name": "--m3e-app-bar-container-elevation-on-scroll",
22
+ "description": "Elevation (shadow) of the app bar container when scrolled.",
23
+ "values": []
24
+ },
25
+ {
26
+ "name": "--m3e-app-bar-title-text-color",
27
+ "description": "Color of the app bar title text.",
28
+ "values": []
29
+ },
30
+ {
31
+ "name": "--m3e-app-bar-subtitle-text-color",
32
+ "description": "Color of the app bar subtitle text.",
33
+ "values": []
34
+ },
35
+ {
36
+ "name": "--m3e-app-bar-padding-left",
37
+ "description": "Left padding for the app bar container.",
38
+ "values": []
39
+ },
40
+ {
41
+ "name": "--m3e-app-bar-padding-right",
42
+ "description": "Right padding for the app bar container.",
43
+ "values": []
44
+ },
45
+ {
46
+ "name": "--m3e-app-bar-small-container-height",
47
+ "description": "Height of the small app bar container.",
48
+ "values": []
49
+ },
50
+ {
51
+ "name": "--m3e-app-bar-small-title-text-font-size",
52
+ "description": "Font size for the small app bar title text.",
53
+ "values": []
54
+ },
55
+ {
56
+ "name": "--m3e-app-bar-small-title-text-font-weight",
57
+ "description": "Font weight for the small app bar title text.",
58
+ "values": []
59
+ },
60
+ {
61
+ "name": "--m3e-app-bar-small-title-text-line-height",
62
+ "description": "Line height for the small app bar title text.",
63
+ "values": []
64
+ },
65
+ {
66
+ "name": "--m3e-app-bar-small-subtitle-text-tracking",
67
+ "description": "Letter spacing (tracking) for the small app bar title text.",
68
+ "values": []
69
+ },
70
+ {
71
+ "name": "--m3e-app-bar-small-subtitle-text-font-size",
72
+ "description": "Font size for the small app bar subtitle text.",
73
+ "values": []
74
+ },
75
+ {
76
+ "name": "--m3e-app-bar-small-subtitle-text-font-weight",
77
+ "description": "Font weight for the small app bar subtitle text.",
78
+ "values": []
79
+ },
80
+ {
81
+ "name": "--m3e-app-bar-small-subtitle-text-line-height",
82
+ "description": "Line height for the small app bar subtitle text.",
83
+ "values": []
84
+ },
85
+ {
86
+ "name": "--m3e-app-bar-small-subtitle-text-tracking",
87
+ "description": "Letter spacing (tracking) for the small app bar subtitle text.",
88
+ "values": []
89
+ },
90
+ {
91
+ "name": "--m3e-app-bar-small-heading-padding-left",
92
+ "description": "Left padding for the small app bar heading.",
93
+ "values": []
94
+ },
95
+ {
96
+ "name": "--m3e-app-bar-small-heading-padding-right",
97
+ "description": "Right padding for the small app bar heading.",
98
+ "values": []
99
+ },
100
+ {
101
+ "name": "--m3e-app-bar-medium-container-height",
102
+ "description": "Height of the medium app bar container.",
103
+ "values": []
104
+ },
105
+ {
106
+ "name": "--m3e-app-bar-medium-container-height-with-subtitle",
107
+ "description": "Height of the medium app bar container with subtitle.",
108
+ "values": []
109
+ },
110
+ {
111
+ "name": "--m3e-app-bar-medium-title-text-font-size",
112
+ "description": "Font size for the medium app bar title text.",
113
+ "values": []
114
+ },
115
+ {
116
+ "name": "--m3e-app-bar-medium-title-text-font-weight",
117
+ "description": "Font weight for the medium app bar title text.",
118
+ "values": []
119
+ },
120
+ {
121
+ "name": "--m3e-app-bar-medium-title-text-line-height",
122
+ "description": "Line height for the medium app bar title text.",
123
+ "values": []
124
+ },
125
+ {
126
+ "name": "--m3e-app-bar-medium-subtitle-text-tracking",
127
+ "description": "Letter spacing (tracking) for the medium app bar title text.",
128
+ "values": []
129
+ },
130
+ {
131
+ "name": "--m3e-app-bar-medium-subtitle-text-font-size",
132
+ "description": "Font size for the medium app bar subtitle text.",
133
+ "values": []
134
+ },
135
+ {
136
+ "name": "--m3e-app-bar-medium-subtitle-text-font-weight",
137
+ "description": "Font weight for the medium app bar subtitle text.",
138
+ "values": []
139
+ },
140
+ {
141
+ "name": "--m3e-app-bar-medium-subtitle-text-line-height",
142
+ "description": "Line height for the medium app bar subtitle text.",
143
+ "values": []
144
+ },
145
+ {
146
+ "name": "--m3e-app-bar-medium-subtitle-text-tracking",
147
+ "description": "Letter spacing (tracking) for the medium app bar subtitle text.",
148
+ "values": []
149
+ },
150
+ {
151
+ "name": "--m3e-app-bar-medium-heading-padding-left",
152
+ "description": "Left padding for the medium app bar heading.",
153
+ "values": []
154
+ },
155
+ {
156
+ "name": "--m3e-app-bar-medium-heading-padding-right",
157
+ "description": "Right padding for the medium app bar heading.",
158
+ "values": []
159
+ },
160
+ {
161
+ "name": "--m3e-app-bar-medium-padding-top",
162
+ "description": "Top padding for the medium app bar.",
163
+ "values": []
164
+ },
165
+ {
166
+ "name": "--m3e-app-bar-medium-padding-bottom",
167
+ "description": "Bottom padding for the medium app bar.",
168
+ "values": []
169
+ },
170
+ {
171
+ "name": "--m3e-app-bar-medium-title-max-lines",
172
+ "description": "Maximum number of lines for the medium app bar title.",
173
+ "values": []
174
+ },
175
+ {
176
+ "name": "--m3e-app-bar-medium-subtitle-max-lines",
177
+ "description": "Maximum number of lines for the medium app bar subtitle.",
178
+ "values": []
179
+ },
180
+ {
181
+ "name": "--m3e-app-bar-large-container-height",
182
+ "description": "Height of the large app bar container.",
183
+ "values": []
184
+ },
185
+ {
186
+ "name": "--m3e-app-bar-large-container-height-with-subtitle",
187
+ "description": "Height of the large app bar container with subtitle.",
188
+ "values": []
189
+ },
190
+ {
191
+ "name": "--m3e-app-bar-large-title-text-font-size",
192
+ "description": "Font size for the large app bar title text.",
193
+ "values": []
194
+ },
195
+ {
196
+ "name": "--m3e-app-bar-large-title-text-font-weight",
197
+ "description": "Font weight for the large app bar title text.",
198
+ "values": []
199
+ },
200
+ {
201
+ "name": "--m3e-app-bar-large-title-text-line-height",
202
+ "description": "Line height for the large app bar title text.",
203
+ "values": []
204
+ },
205
+ {
206
+ "name": "--m3e-app-bar-large-subtitle-text-tracking",
207
+ "description": "Letter spacing (tracking) for the large app bar title text.",
208
+ "values": []
209
+ },
210
+ {
211
+ "name": "--m3e-app-bar-large-subtitle-text-font-size",
212
+ "description": "Font size for the large app bar subtitle text.",
213
+ "values": []
214
+ },
215
+ {
216
+ "name": "--m3e-app-bar-large-subtitle-text-font-weight",
217
+ "description": "Font weight for the large app bar subtitle text.",
218
+ "values": []
219
+ },
220
+ {
221
+ "name": "--m3e-app-bar-large-subtitle-text-line-height",
222
+ "description": "Line height for the large app bar subtitle text.",
223
+ "values": []
224
+ },
225
+ {
226
+ "name": "--m3e-app-bar-large-subtitle-text-tracking",
227
+ "description": "Letter spacing (tracking) for the large app bar subtitle text.",
228
+ "values": []
229
+ },
230
+ {
231
+ "name": "--m3e-app-bar-large-heading-padding-left",
232
+ "description": "Left padding for the large app bar heading.",
233
+ "values": []
234
+ },
235
+ {
236
+ "name": "--m3e-app-bar-large-heading-padding-right",
237
+ "description": "Right padding for the large app bar heading.",
238
+ "values": []
239
+ },
240
+ {
241
+ "name": "--m3e-app-bar-large-padding-top",
242
+ "description": "Top padding for the large app bar.",
243
+ "values": []
244
+ },
245
+ {
246
+ "name": "--m3e-app-bar-large-padding-bottom",
247
+ "description": "Bottom padding for the large app bar.",
248
+ "values": []
249
+ },
250
+ {
251
+ "name": "--m3e-app-bar-large-title-max-lines",
252
+ "description": "Maximum number of lines for the large app bar title.",
253
+ "values": []
254
+ },
255
+ {
256
+ "name": "--m3e-app-bar-large-subtitle-max-lines",
257
+ "description": "Maximum number of lines for the large app bar subtitle.",
258
+ "values": []
259
+ }
260
+ ],
261
+ "pseudoElements": []
262
+ }