@f-ewald/components 1.33.1 → 1.34.0
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/custom-elements.json +53 -23
- package/dist/app-shell.d.ts +47 -29
- package/dist/app-shell.d.ts.map +1 -1
- package/dist/app-shell.js +154 -102
- package/dist/app-shell.js.map +1 -1
- package/dist/app-sidebar.d.ts +4 -3
- package/dist/app-sidebar.d.ts.map +1 -1
- package/dist/app-sidebar.js +4 -3
- package/dist/app-sidebar.js.map +1 -1
- package/docs/app-shell.md +37 -14
- package/docs/app-sidebar.md +4 -3
- package/docs/design-language.md +68 -23
- package/docs/layouts/list-only.md +35 -3
- package/llms.txt +39 -17
- package/package.json +1 -1
package/custom-elements.json
CHANGED
|
@@ -993,7 +993,7 @@
|
|
|
993
993
|
"declarations": [
|
|
994
994
|
{
|
|
995
995
|
"kind": "class",
|
|
996
|
-
"description": "The dashboard page shell: a slot-based CSS-grid backbone that arranges a\
|
|
996
|
+
"description": "The dashboard page shell: a slot-based CSS-grid backbone that arranges a\ntop bar, the main content, an optional right-hand detail column, an\noptional footer, and a sidebar. The top bar always spans the shell's full\nwidth, in every sidebar state.\n\nThe sidebar's visibility, width, and layout mode are three independent\nproperties:\n- `sidebar-open` (default closed) — whether it's shown at all.\n- `sidebar-width`: `\"full\"` (16rem, icons + labels, the default) or\n `\"icon\"` (3.5rem rail, icons only — drives the slotted `app-sidebar`'s\n own `collapsed` attribute).\n- `sidebar-mode`: `\"overlay\"` (the default) floats the sidebar above the\n shell's own content with a higher z-index, covering part of the top\n bar's corner and whatever content sits beneath it, without ever\n resizing or reflowing `main`/`footer`. `\"push\"` instead reserves a real\n grid column beside `main`/`footer` (which resize to make room) — the\n top bar still spans full width above it either way.\n\nBelow the shared 48rem breakpoint the sidebar always behaves as a\nfull-width, modal, scrim/Escape-dismissible drawer regardless of\n`sidebar-mode`/`sidebar-width` — those two properties only affect the\ndesktop presentation. Above 48rem, an `overlay`-mode sidebar is a\nnon-modal panel (no dimming scrim, no Escape-dismiss, since it reads as\nan ordinary always-interactive panel rather than a blocking dialog); a\n`push`-mode sidebar is even more clearly non-modal, since it never\ncovers anything.\n\nThe right-hand detail column is unaffected by any of the above: it still\nreserves an inline grid column on desktop and becomes a dismissible\noverlay (scrim/Escape) on mobile.\n\nWidths are tunable per instance via `--component-sidebar-width` (16rem),\n`--component-sidebar-rail-width` (3.5rem), and `--component-topbar-height`\n(3rem); the detail column reuses the 20rem/25rem panel widths. The main\ncontent area is white by default — override it with\n`--component-main-background`. Give the shell a height (e.g. `height:\n100vh`) so the sidebar and main can size and scroll.\n\nHovering or keyboard-focusing the toggle reveals a tooltip naming the\naction and its `[` shortcut — the shortcut is not shown as permanent\nchrome.",
|
|
997
997
|
"name": "AppShell",
|
|
998
998
|
"slots": [
|
|
999
999
|
{
|
|
@@ -1001,7 +1001,7 @@
|
|
|
1001
1001
|
"name": ""
|
|
1002
1002
|
},
|
|
1003
1003
|
{
|
|
1004
|
-
"description": "
|
|
1004
|
+
"description": "Sidebar navigation (typically `app-sidebar`).",
|
|
1005
1005
|
"name": "sidebar"
|
|
1006
1006
|
},
|
|
1007
1007
|
{
|
|
@@ -1020,13 +1020,35 @@
|
|
|
1020
1020
|
"members": [
|
|
1021
1021
|
{
|
|
1022
1022
|
"kind": "field",
|
|
1023
|
-
"name": "
|
|
1023
|
+
"name": "sidebarOpen",
|
|
1024
1024
|
"type": {
|
|
1025
1025
|
"text": "boolean"
|
|
1026
1026
|
},
|
|
1027
1027
|
"default": "false",
|
|
1028
|
-
"description": "
|
|
1029
|
-
"attribute": "sidebar-
|
|
1028
|
+
"description": "Whether the sidebar is open. Closed by default at every breakpoint.",
|
|
1029
|
+
"attribute": "sidebar-open",
|
|
1030
|
+
"reflects": true
|
|
1031
|
+
},
|
|
1032
|
+
{
|
|
1033
|
+
"kind": "field",
|
|
1034
|
+
"name": "sidebarMode",
|
|
1035
|
+
"type": {
|
|
1036
|
+
"text": "\"overlay\" | \"push\""
|
|
1037
|
+
},
|
|
1038
|
+
"default": "\"overlay\"",
|
|
1039
|
+
"description": "`\"overlay\"` (default) floats the sidebar above content; `\"push\"` reserves a grid column instead.",
|
|
1040
|
+
"attribute": "sidebar-mode",
|
|
1041
|
+
"reflects": true
|
|
1042
|
+
},
|
|
1043
|
+
{
|
|
1044
|
+
"kind": "field",
|
|
1045
|
+
"name": "sidebarWidth",
|
|
1046
|
+
"type": {
|
|
1047
|
+
"text": "\"full\" | \"icon\""
|
|
1048
|
+
},
|
|
1049
|
+
"default": "\"full\"",
|
|
1050
|
+
"description": "Sidebar width when open: `\"full\"` (16rem, icons + labels) or `\"icon\"` (3.5rem rail, icons only).",
|
|
1051
|
+
"attribute": "sidebar-width",
|
|
1030
1052
|
"reflects": true
|
|
1031
1053
|
},
|
|
1032
1054
|
{
|
|
@@ -1060,16 +1082,6 @@
|
|
|
1060
1082
|
"default": "false",
|
|
1061
1083
|
"description": "Whether the viewport is at/below the 48rem breakpoint."
|
|
1062
1084
|
},
|
|
1063
|
-
{
|
|
1064
|
-
"kind": "field",
|
|
1065
|
-
"name": "_mobileNavOpen",
|
|
1066
|
-
"type": {
|
|
1067
|
-
"text": "boolean"
|
|
1068
|
-
},
|
|
1069
|
-
"privacy": "private",
|
|
1070
|
-
"default": "false",
|
|
1071
|
-
"description": "Whether the mobile off-canvas nav drawer is open."
|
|
1072
|
-
},
|
|
1073
1085
|
{
|
|
1074
1086
|
"kind": "field",
|
|
1075
1087
|
"name": "_hasFooter",
|
|
@@ -1102,7 +1114,7 @@
|
|
|
1102
1114
|
"kind": "field",
|
|
1103
1115
|
"name": "_onMediaChange",
|
|
1104
1116
|
"privacy": "private",
|
|
1105
|
-
"description": "Tracks the breakpoint
|
|
1117
|
+
"description": "Tracks the breakpoint the sidebar's width and modality depend on."
|
|
1106
1118
|
},
|
|
1107
1119
|
{
|
|
1108
1120
|
"kind": "field",
|
|
@@ -1138,7 +1150,7 @@
|
|
|
1138
1150
|
"text": "void"
|
|
1139
1151
|
}
|
|
1140
1152
|
},
|
|
1141
|
-
"description": "Toggles the
|
|
1153
|
+
"description": "Toggles the sidebar and announces it."
|
|
1142
1154
|
},
|
|
1143
1155
|
{
|
|
1144
1156
|
"kind": "method",
|
|
@@ -1164,14 +1176,14 @@
|
|
|
1164
1176
|
},
|
|
1165
1177
|
{
|
|
1166
1178
|
"kind": "method",
|
|
1167
|
-
"name": "
|
|
1179
|
+
"name": "_syncSidebarWidth",
|
|
1168
1180
|
"privacy": "private",
|
|
1169
1181
|
"return": {
|
|
1170
1182
|
"type": {
|
|
1171
1183
|
"text": "void"
|
|
1172
1184
|
}
|
|
1173
1185
|
},
|
|
1174
|
-
"description": "Mirrors
|
|
1186
|
+
"description": "Mirrors `sidebar-width` onto the slotted sidebar's `collapsed` (icon rail) attribute."
|
|
1175
1187
|
},
|
|
1176
1188
|
{
|
|
1177
1189
|
"kind": "method",
|
|
@@ -1211,13 +1223,31 @@
|
|
|
1211
1223
|
],
|
|
1212
1224
|
"attributes": [
|
|
1213
1225
|
{
|
|
1214
|
-
"name": "sidebar-
|
|
1226
|
+
"name": "sidebar-open",
|
|
1215
1227
|
"type": {
|
|
1216
1228
|
"text": "boolean"
|
|
1217
1229
|
},
|
|
1218
1230
|
"default": "false",
|
|
1219
|
-
"description": "
|
|
1220
|
-
"fieldName": "
|
|
1231
|
+
"description": "Whether the sidebar is open. Closed by default at every breakpoint.",
|
|
1232
|
+
"fieldName": "sidebarOpen"
|
|
1233
|
+
},
|
|
1234
|
+
{
|
|
1235
|
+
"name": "sidebar-mode",
|
|
1236
|
+
"type": {
|
|
1237
|
+
"text": "\"overlay\" | \"push\""
|
|
1238
|
+
},
|
|
1239
|
+
"default": "\"overlay\"",
|
|
1240
|
+
"description": "`\"overlay\"` (default) floats the sidebar above content; `\"push\"` reserves a grid column instead.",
|
|
1241
|
+
"fieldName": "sidebarMode"
|
|
1242
|
+
},
|
|
1243
|
+
{
|
|
1244
|
+
"name": "sidebar-width",
|
|
1245
|
+
"type": {
|
|
1246
|
+
"text": "\"full\" | \"icon\""
|
|
1247
|
+
},
|
|
1248
|
+
"default": "\"full\"",
|
|
1249
|
+
"description": "Sidebar width when open: `\"full\"` (16rem, icons + labels) or `\"icon\"` (3.5rem rail, icons only).",
|
|
1250
|
+
"fieldName": "sidebarWidth"
|
|
1221
1251
|
},
|
|
1222
1252
|
{
|
|
1223
1253
|
"name": "detail-open",
|
|
@@ -1271,7 +1301,7 @@
|
|
|
1271
1301
|
"declarations": [
|
|
1272
1302
|
{
|
|
1273
1303
|
"kind": "class",
|
|
1274
|
-
"description": "Collapsible navigation sidebar for the `app-shell` sidebar slot. It is\ndeliberately presentational and router-agnostic: the consumer supplies the\nnav items as plain `<a>`/`<button>` elements (each an icon followed by a\nlabel), optional `<p>` group headings, and marks the active item with\n`aria-current=\"page\"`. The sidebar styles them, tracks hover/active/focus,\nand — in collapsed \"rail\" mode — centers the icons and hides the labels.\n\nRail mode is driven by the `collapsed` attribute
|
|
1304
|
+
"description": "Collapsible navigation sidebar for the `app-shell` sidebar slot. It is\ndeliberately presentational and router-agnostic: the consumer supplies the\nnav items as plain `<a>`/`<button>` elements (each an icon followed by a\nlabel), optional `<p>` group headings, and marks the active item with\n`aria-current=\"page\"`. The sidebar styles them, tracks hover/active/focus,\nand — in collapsed \"rail\" mode — centers the icons and hides the labels.\n\nRail mode is driven by the `collapsed` attribute, which callers set\ndirectly — `app-shell` no longer auto-manages it (its own sidebar is a\npure overlay, not a rail). Labels are hidden by the inherited\n`--app-sidebar-label` custom property, so each label element should read it, e.g.\n`<span style=\"display: var(--app-sidebar-label, inline)\">Reports</span>`;\nkeep an `aria-label` on the item so its accessible name survives collapse.\nThe sidebar fills the width and height of its container — `app-shell` owns\nthe actual rail/expanded width.",
|
|
1275
1305
|
"name": "AppSidebar",
|
|
1276
1306
|
"slots": [
|
|
1277
1307
|
{
|
package/dist/app-shell.d.ts
CHANGED
|
@@ -2,36 +2,55 @@ import { LitElement, type PropertyValues } from "lit";
|
|
|
2
2
|
import "./kbd-hint.js";
|
|
3
3
|
/** Fired when the built-in toggle changes the sidebar state. */
|
|
4
4
|
export interface SidebarToggleDetail {
|
|
5
|
-
/**
|
|
6
|
-
|
|
7
|
-
/** Mobile drawer open state. */
|
|
8
|
-
mobileOpen: boolean;
|
|
5
|
+
/** Whether the sidebar is now open. */
|
|
6
|
+
open: boolean;
|
|
9
7
|
}
|
|
10
8
|
/**
|
|
11
9
|
* The dashboard page shell: a slot-based CSS-grid backbone that arranges a
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
10
|
+
* top bar, the main content, an optional right-hand detail column, an
|
|
11
|
+
* optional footer, and a sidebar. The top bar always spans the shell's full
|
|
12
|
+
* width, in every sidebar state.
|
|
13
|
+
*
|
|
14
|
+
* The sidebar's visibility, width, and layout mode are three independent
|
|
15
|
+
* properties:
|
|
16
|
+
* - `sidebar-open` (default closed) — whether it's shown at all.
|
|
17
|
+
* - `sidebar-width`: `"full"` (16rem, icons + labels, the default) or
|
|
18
|
+
* `"icon"` (3.5rem rail, icons only — drives the slotted `app-sidebar`'s
|
|
19
|
+
* own `collapsed` attribute).
|
|
20
|
+
* - `sidebar-mode`: `"overlay"` (the default) floats the sidebar above the
|
|
21
|
+
* shell's own content with a higher z-index, covering part of the top
|
|
22
|
+
* bar's corner and whatever content sits beneath it, without ever
|
|
23
|
+
* resizing or reflowing `main`/`footer`. `"push"` instead reserves a real
|
|
24
|
+
* grid column beside `main`/`footer` (which resize to make room) — the
|
|
25
|
+
* top bar still spans full width above it either way.
|
|
26
|
+
*
|
|
27
|
+
* Below the shared 48rem breakpoint the sidebar always behaves as a
|
|
28
|
+
* full-width, modal, scrim/Escape-dismissible drawer regardless of
|
|
29
|
+
* `sidebar-mode`/`sidebar-width` — those two properties only affect the
|
|
30
|
+
* desktop presentation. Above 48rem, an `overlay`-mode sidebar is a
|
|
31
|
+
* non-modal panel (no dimming scrim, no Escape-dismiss, since it reads as
|
|
32
|
+
* an ordinary always-interactive panel rather than a blocking dialog); a
|
|
33
|
+
* `push`-mode sidebar is even more clearly non-modal, since it never
|
|
34
|
+
* covers anything.
|
|
35
|
+
*
|
|
36
|
+
* The right-hand detail column is unaffected by any of the above: it still
|
|
37
|
+
* reserves an inline grid column on desktop and becomes a dismissible
|
|
38
|
+
* overlay (scrim/Escape) on mobile.
|
|
18
39
|
*
|
|
19
40
|
* Widths are tunable per instance via `--component-sidebar-width` (16rem),
|
|
20
41
|
* `--component-sidebar-rail-width` (3.5rem), and `--component-topbar-height`
|
|
21
42
|
* (3rem); the detail column reuses the 20rem/25rem panel widths. The main
|
|
22
43
|
* content area is white by default — override it with
|
|
23
|
-
* `--component-main-background`. Give the shell a height (e.g. `height:
|
|
24
|
-
* so the sidebar and main can size and scroll.
|
|
44
|
+
* `--component-main-background`. Give the shell a height (e.g. `height:
|
|
45
|
+
* 100vh`) so the sidebar and main can size and scroll.
|
|
25
46
|
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
* naming the action and its `[` shortcut — the shortcut is not shown as
|
|
30
|
-
* permanent chrome.
|
|
47
|
+
* Hovering or keyboard-focusing the toggle reveals a tooltip naming the
|
|
48
|
+
* action and its `[` shortcut — the shortcut is not shown as permanent
|
|
49
|
+
* chrome.
|
|
31
50
|
*
|
|
32
51
|
* @element app-shell
|
|
33
52
|
* @slot - Main content area.
|
|
34
|
-
* @slot sidebar -
|
|
53
|
+
* @slot sidebar - Sidebar navigation (typically `app-sidebar`).
|
|
35
54
|
* @slot topbar - Top bar content, right of the built-in toggle.
|
|
36
55
|
* @slot detail - Optional right-hand detail; shown when `detail-open` is set.
|
|
37
56
|
* @slot footer - Optional footer beneath the main content.
|
|
@@ -39,16 +58,18 @@ export interface SidebarToggleDetail {
|
|
|
39
58
|
* @fires detail-close - The scrim or Escape dismissed the mobile detail overlay.
|
|
40
59
|
*/
|
|
41
60
|
export declare class AppShell extends LitElement {
|
|
42
|
-
/**
|
|
43
|
-
|
|
61
|
+
/** Whether the sidebar is open. Closed by default at every breakpoint. */
|
|
62
|
+
sidebarOpen: boolean;
|
|
63
|
+
/** `"overlay"` (default) floats the sidebar above content; `"push"` reserves a grid column instead. */
|
|
64
|
+
sidebarMode: "overlay" | "push";
|
|
65
|
+
/** Sidebar width when open: `"full"` (16rem, icons + labels) or `"icon"` (3.5rem rail, icons only). */
|
|
66
|
+
sidebarWidth: "full" | "icon";
|
|
44
67
|
/** Shows the right-hand detail region (inline column, or overlay on mobile). */
|
|
45
68
|
detailOpen: boolean;
|
|
46
69
|
/** Detail width: `compact` (20rem) or `comfortable` (25rem). */
|
|
47
70
|
detailWidth: "compact" | "comfortable";
|
|
48
71
|
/** Whether the viewport is at/below the 48rem breakpoint. */
|
|
49
72
|
private _mobile;
|
|
50
|
-
/** Whether the mobile off-canvas nav drawer is open. */
|
|
51
|
-
private _mobileNavOpen;
|
|
52
73
|
/** Whether the footer slot has assigned content. */
|
|
53
74
|
private _hasFooter;
|
|
54
75
|
static styles: import("lit").CSSResult[];
|
|
@@ -56,24 +77,21 @@ export declare class AppShell extends LitElement {
|
|
|
56
77
|
private _previousFocus;
|
|
57
78
|
connectedCallback(): void;
|
|
58
79
|
disconnectedCallback(): void;
|
|
59
|
-
/** Tracks the breakpoint
|
|
80
|
+
/** Tracks the breakpoint the sidebar's width and modality depend on. */
|
|
60
81
|
private _onMediaChange;
|
|
61
82
|
/** Handles the `[` sidebar shortcut and Escape dismissal of mobile overlays. */
|
|
62
83
|
private _onKeydown;
|
|
63
84
|
/** Whether the keydown originated in a text field, so the shortcut defers to typing. */
|
|
64
85
|
private _isEditableTarget;
|
|
65
|
-
/** Toggles the
|
|
86
|
+
/** Toggles the sidebar and announces it. */
|
|
66
87
|
private _toggleSidebar;
|
|
67
88
|
/** Closes the detail overlay and notifies the consumer that owns `detail-open`. */
|
|
68
89
|
private _closeDetail;
|
|
69
90
|
/** Scrim click dismisses whichever overlay is open. */
|
|
70
91
|
private _onScrim;
|
|
92
|
+
/** Mirrors `sidebar-width` onto the slotted sidebar's `collapsed` (icon rail) attribute. */
|
|
93
|
+
private _syncSidebarWidth;
|
|
71
94
|
protected updated(changed: PropertyValues): void;
|
|
72
|
-
/**
|
|
73
|
-
* Mirrors the shell's rail state onto the slotted sidebar so it hides labels
|
|
74
|
-
* when collapsed on desktop, and always shows them in the mobile drawer.
|
|
75
|
-
*/
|
|
76
|
-
private _syncSidebar;
|
|
77
95
|
render(): import("lit-html").TemplateResult<1>;
|
|
78
96
|
/** Collapses the footer row when nothing is slotted into it. */
|
|
79
97
|
private _onFooterSlotChange;
|
package/dist/app-shell.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"app-shell.d.ts","sourceRoot":"","sources":["../src/app-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,
|
|
1
|
+
{"version":3,"file":"app-shell.d.ts","sourceRoot":"","sources":["../src/app-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAGjE,OAAO,eAAe,CAAC;AAGvB,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBACa,QAAS,SAAQ,UAAU;IACtC,0EAA0E;IACH,WAAW,UAAS;IAC3F,uGAAuG;IAC/C,WAAW,EAAE,SAAS,GAAG,MAAM,CAAa;IACpG,uGAAuG;IAC9C,YAAY,EAAE,MAAM,GAAG,MAAM,CAAU;IAChG,gFAAgF;IACV,UAAU,UAAS;IACzF,gEAAgE;IACvB,WAAW,EAAE,SAAS,GAAG,aAAa,CAAa;IAE5F,6DAA6D;IACpD,OAAO,CAAC,OAAO,CAAS;IACjC,oDAAoD;IAC3C,OAAO,CAAC,UAAU,CAAS;IAEpC,OAAgB,MAAM,4BAqPpB;IAEF,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,cAAc,CAA4B;IAEzC,iBAAiB,IAAI,IAAI,CAMjC;IAEQ,oBAAoB,IAAI,IAAI,CAKpC;IAED,wEAAwE;IACxE,OAAO,CAAC,cAAc,CAEpB;IAEF,gFAAgF;IAChF,OAAO,CAAC,UAAU,CAsBhB;IAEF,wFAAwF;IACxF,OAAO,CAAC,iBAAiB;IAQzB,4CAA4C;IAC5C,OAAO,CAAC,cAAc;IActB,mFAAmF;IACnF,OAAO,CAAC,YAAY;IAKpB,uDAAuD;IACvD,OAAO,CAAC,QAAQ;IAKhB,4FAA4F;IAC5F,OAAO,CAAC,iBAAiB;IAQzB,UAAmB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CASxD;IAEQ,MAAM,yCAuDd;IAED,gEAAgE;IAChE,OAAO,CAAC,mBAAmB;CAG5B;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,QAAQ,CAAC;KACvB;CACF"}
|