@monster-orange/den-ui 0.6.6 → 0.7.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/README.md CHANGED
@@ -168,7 +168,8 @@ repository root, one row per component, with a reason:
168
168
  | report | our reports go to a ticket desk, not an issue tracker |
169
169
 
170
170
  (or a list: `- report: our reports go to …`). The components are `shell`,
171
- `version`, `whatsnew`, `update`, `report` and `working`. A row without a
171
+ `version`, `whatsnew`, `update`, `report` and `working`, and since 0.7.0
172
+ `scope`, `search`, `bell`, `appearance` and `account`. A row without a
172
173
  reason does not count. With no DIVERGE.md, every copy fails.
173
174
 
174
175
  ### Nav inventory
@@ -255,6 +256,20 @@ env, elements, tokens }`. `env`: `userAgent`, `faces` (the
255
256
  either side. A host slot wider or narrower than the reference (or on
256
257
  one side only) may move or stretch its neighbours sideways by exactly
257
258
  that much, never by anything else.
259
+ - Host content: the kit stamps `data-nav-role` on what each host fills
260
+ with its own words: each scope crumb (`crumb`) and the separator after
261
+ it (`crumb-sep`), the brand's title (`brand-title`), the search's
262
+ placeholder (`search-ph`), each rail group (`rail-group`), its heading
263
+ (`group`) and its pages (`page`), and the account entry's words
264
+ (`account-name`). The search's name is the host's too
265
+ (`data-nav-name="host"`: its name is not compared). Their count, keys, ids, text and
266
+ width are never compared, on either side. The first of each role is
267
+ compared with the other side's first, and what it holds by key, on
268
+ every computed style and on height. Their size may move what follows by
269
+ exactly its change: sideways in the bar (their contents' width, not a
270
+ filled box's), down in the rail (heights; the rail's spacer shrinks by
271
+ as much). The mark, the search field's box and all other chrome stay
272
+ strict. The references hold each element's `host`.
258
273
  - `themeTokens`: empty by default, and never set on a parity run: both
259
274
  products run in `NAV_THEME`, so any colour or font that differs is a
260
275
  real gap. It is only for a run that switches themes on purpose. What a
@@ -270,9 +285,25 @@ env, elements, tokens }`. `env`: `userAgent`, `faces` (the
270
285
  list on its `font-family`, and read back, so it is in the form computed
271
286
  values take. `snapshot.tokens` maps each colour and family seen to the
272
287
  tokens that compute to it.
273
- - Fonts in Den's test: the system faces are pinned to the kit's own
274
- Rubik and Space Mono, so text lays out alike from run to run. A host
275
- pins them the same way (see `tests/unit/den-ui/nav-inventory-helpers.ts`).
288
+ - Fonts: `await pinNavFonts(context)` (from `./inventory`) pins the
289
+ system faces a nav names to the kit's own Rubik and Space Mono, so text
290
+ lays out alike from run to run, as when the reference was taken. Call it
291
+ on the Playwright `BrowserContext` before opening the page. It puts the
292
+ pin stylesheet first on every page and serves `/__pin-fonts/*` from the
293
+ package's `src/fonts` (or `{ fontsDir }`). It finds them from its own
294
+ files, never from the working folder: the package's `imports` entry
295
+ `#den-ui-fonts-dir` is `inventory/fonts-dir.mjs` for an ES module
296
+ (`import.meta.url`) and `inventory/fonts-dir.cjs` for CommonJS
297
+ (`__dirname`). Both ship in `inventory/`; a host serves neither.
298
+ - Font families in the fingerprint are one line each (`navFamily`: every
299
+ run of whitespace one space, trimmed), so a token written over several
300
+ lines names the same face as one written on one.
301
+ - The user agent: under `@playwright/test`, the config's device
302
+ `userAgent` leaks into the contexts of a browser you connect to, and the
303
+ environment check then sees another user agent than the reference's.
304
+ Set `test.use({ userAgent: "" })`, or create the context with no
305
+ `userAgent`. `NAV_BROWSER_IMAGE` and
306
+ `NAV_THEME` are exported beside it.
276
307
 
277
308
  Den runs it in `tests/unit/den-ui/nav-inventory.browser.test.ts` (CI's
278
309
  `den-ui-nav` job starts the image) with red cases that must fail: the
@@ -314,6 +345,156 @@ browser test, on the image (Den's real server on the demo distribution,
314
345
  is `src/kit.d.ts`. A test compiles a consumer against them with
315
346
  `--strict`.
316
347
 
348
+ ## 0.7.0
349
+
350
+ No new file. One import changes, for hosts that serve a fixed list of kit files:
351
+
352
+ `shell-client.js` now imports `dialog.js` (and `shell-html.js`): serve `dialog.js` wherever `shell-client.js` is served.
353
+
354
+ Default tokens are Den's theme. `tokens.css`'s defaults are now the values
355
+ of Den's own theme (`themes/den/den-theme.json`): its type stacks (sans,
356
+ mono, display, ja), its shape (radius 8px, radius-button 6px) and both
357
+ modes' colours, shadow and bar. A host on the kit's defaults looks like
358
+ Den. Light and dark switch as before. Themes are still token sets the host
359
+ lists in `appearanceMenuHtml({ themes })`; the kit ships no theme files.
360
+ Tokens the theme has no value for keep the kit's own: `--info`,
361
+ `--violet`, `--upd-shadow`, `--density` and the rest.
362
+
363
+ `tokens.css` owns `--den-pop-shadow`, the shadow of a pop-up or a picker
364
+ dialog: `0 16px 40px rgb(0 0 0 / 0.25)` in light, `/ 0.6` in dark. A host
365
+ that kept its own copy of that token can delete it.
366
+
367
+ The whole global nav is the kit's. Pieces of the top bar and the rail
368
+ that a host drew itself move into the kit, so every host draws them the
369
+ same way, with the same CSS values. In order: ☰ · brand · scope crumbs ·
370
+ search with ⌘K · the host's `end` slot (status chips) · Report · bell ·
371
+ version chip with its pip and the update-waiting pill · ◐ ▾. The rail's
372
+ foot: the host's entries · Settings · account · Collapse. The host gives words,
373
+ values and callbacks. The kit draws the markup and owns focus and keys.
374
+ Each piece is optional: one left out draws nothing.
375
+
376
+ - **Scope crumbs**: `scopeHtml({ crumbs, label?, after? })`, for the
377
+ `start` slot. Each crumb is `{ key, label, value, menu?, id?, title?,
378
+ hidden?, optional? }`. `label` is the small-caps word (COMPANY,
379
+ PROJECT, ENV). With a `menu`, the crumb is a ▾ button. Without one, it is
380
+ a plain label. `menu` is a list of links `[{ label, href, current? }]`
381
+ or HTML, and the kit draws and opens it below the ▾. Enter, Space, ↓ and
382
+ ↑ open it, and ↑ ↓ Home End move in it. Esc closes it and goes back to
383
+ the ▾. `menu: true` means the host opens its own menu: `onOpen(key,
384
+ button)`. A crumb left out of the list draws nothing, and no separator
385
+ either (a host with no ENV, say). `scopeCrumbHtml(crumb)` draws one crumb.
386
+ A kit-drawn list of more than 6 links gets a filter field at its top
387
+ (`filter`: a number sets that threshold, `false` turns it off). The menu
388
+ opens on the field. Typing hides the links that don't hold the text, and
389
+ "No match" shows when none do. ↓ goes to the links, Enter takes the first
390
+ one shown, and Esc clears the text, then closes the menu.
391
+ - **Search field**: `searchHtml({ placeholder, label?, id?, shortcut? })`,
392
+ for the `start` slot. It is the placeholder with ⌘K inside the field. A
393
+ click, Enter, ⌘K or Ctrl-K calls `onActivate(via)` (`"click"` or
394
+ `"key"`) and fires `den-ui:search` on the field. The kit owns no
395
+ palette.
396
+ - **Bell**: `bellButtonHtml({ count, label? })`, for the `bell` slot. It is
397
+ a button with a count badge (99+ past 99, none at 0) and
398
+ `aria-haspopup="dialog"`. Its name says the count. The panel is a dialog
399
+ on `<body>`: a heading, then the host's `items` as rows (`{ text, href?,
400
+ time?, read? }`) or the empty state. `bellPanelHtml(...)` takes `actions`
401
+ (buttons beside the heading), `lead`, `body` (the host's own rows),
402
+ `empty`, `after` and `foot`. A click on the bell toggles the panel.
403
+ Opening it focuses its first link or button. Esc closes it and focus goes
404
+ back to the bell, in Safari too (`focusBack` from `dialog.js`). A click
405
+ outside closes it. `onEscape(e)` returning true keeps it open (the
406
+ host's own question inside it, say). `shell.bell.setCount(n)` updates the
407
+ badge.
408
+ - **Account entry**: `account: { label, detail?, href? | menu? | action? }`
409
+ on `shellHtml` or `railHtml` puts it last in the rail's foot, before the
410
+ collapse toggle. It reads "label · detail". It is a link, or with
411
+ `action: true` a button that calls `onAction`. `accountHtml(...)` draws
412
+ it alone.
413
+ - **Account menu**: with `menu: true`, the entry is a button (id
414
+ `den-account`) that opens a menu: who is signed in, where, a rule, then
415
+ the entries. Wire it with `hydrate`'s `account: { menu, onPick?,
416
+ onSubmit? }`. `menu()` gives `{ name, detail?, items }`. An item is a link
417
+ `{ label, href }`, a button `{ label, id }` (`onPick("item", id)`), or a
418
+ form post `{ label, action: { method?, url, csrf?, field? } }`. A form
419
+ post needs no script: Sign out posts to `url`, with `csrf` in a hidden
420
+ field (named `field`, `csrf` by default). `onSubmit(event, form)` runs
421
+ first, and `preventDefault` there stops the post. The kit owns open,
422
+ close, the keys, Esc and focus going back to the entry.
423
+ `accountMenuHtml(...)` draws the content alone.
424
+ - **Appearance menu**: `appearanceButtonHtml({ label?, title? })`, for the
425
+ `account` slot (last in the bar): ◐ ▾ with `aria-haspopup="menu"`. Wire
426
+ it with `hydrate`'s `appearance: { menu, onPick }`. `menu()` gives, each
427
+ time it opens, `{ mode, modes?, themes, notice?, languages, items }`:
428
+ the mode (System, Dark, Light by default), the themes `{ value, label,
429
+ selected }`, a line under them, the languages `{ id, name, current }`,
430
+ each named in itself, and entries after a rule (`{ label, href? | id }`).
431
+ A pick calls `onPick(kind, value)` with `"mode"`, `"theme"`,
432
+ `"language"` or `"item"`, and closes the menu. Click, Enter, Space, ↓ or
433
+ ↑ open it on the checked entry. ↑ ↓ Home End move. Esc or Tab closes it
434
+ and focus goes back to ◐ ▾, in Safari too. A press outside closes it.
435
+ The host saves and applies the pick. The kit owns no settings.
436
+ - **Version pip and update-waiting pill**: the chip's pip (`#v-pip`) shows
437
+ unread notes (`DenUI.version.unread(on)`, as before).
438
+ `DenUI.version.waiting({ label, action, title?, name?, onClick })` shows
439
+ the update-waiting pill right after the chip ("⚠ label · action", a
440
+ pulsing warn pill; only ⚠ below 720px). `waiting(null)` hides it.
441
+ `waitingHtml(...)` draws it.
442
+ - **Settings**: `settings: { href, label?, current? }` on `shellHtml` or
443
+ `railHtml` puts Settings in the rail's foot after the host's entries and
444
+ before the account entry. `settingsHtml(...)` draws it alone.
445
+ - **Brand mark**: `product.mark: { src, label }` draws an image file the
446
+ way Den draws its theme's mark: `span.den-mark.den-mark-svg#den-mark`
447
+ titled `label`, holding `<img src alt="" width="18" height="18">`. The
448
+ kit ships the default theme's mark as `src/marks/den.svg`, beside
449
+ `src/fonts/`; a host serves it with the kit's other files and passes
450
+ `mark: { src: "<served path>/marks/den.svg", label }` (Den serves it at
451
+ `/kit/marks/den.svg`). An image runs no script. `markHtml(mark)` draws
452
+ it alone; Den's own theme mark is drawn by it. `{ text }` and `{ svg }`
453
+ work as before.
454
+ - **Mark layout**: `.den-mark` (a centred flex box, its image a block)
455
+ and the text and raster forms are in `shell.css`. A host deletes its
456
+ own copy.
457
+ - **A phone's tap targets**: below 480px every top-bar button is at least
458
+ 32px each way (`shell.css`).
459
+ - **The brand on a phone**: below 480px the brand (its mark alone) never
460
+ shrinks; the host's chips give way.
461
+ - **Search name**: `searchHtml({ label })` names the field; by default
462
+ the kit's "Search" (en, es, ja), not the placeholder.
463
+ - **Filtered menus**: a menu with the filter field is a pop-up holding the
464
+ field, then the `role="menu"` list (`.den-mlist`, id `<menu>-list`),
465
+ then "No match": a menu owns only its items. The field has
466
+ `aria-controls` on the list and its `aria-label` ("Filter <label>").
467
+ `attachMenuFilter(menu)` moves a host menu's rows, role and name into
468
+ that list; `menu` keeps its id and stays the pop-up. The keys and the
469
+ look are as before.
470
+ - **Key caps**: `.den-kbd` is the one key-cap rule: the search's ⌘K,
471
+ Report's ⌘⇧F and any `<kbd class="den-kbd">` a host draws (its palette's
472
+ hints, say). A 1px border with a 2px bottom, 4px corners, `--surface`
473
+ behind, 5px each side. A host deletes its own copy.
474
+ - **Group headings**: a heading with its "from" tag is as tall as one
475
+ without (32px in Den's fonts): the tag sits on a 12px line, centred.
476
+ - The kit's menus (◐ ▾, a crumb's own menu) wear `.den-pop`, `.den-mi`,
477
+ `.den-ml`, `.den-hr` and `.den-mnote`, styled in `shell.css`.
478
+ - Wiring: `DenUI.hydrate(root, { scope, search, bell, account, appearance })` (or
479
+ `mount`'s `model.hydrate`) wires each piece it finds. The shell it
480
+ returns has `.scope`, `.search`, `.bell` and `.appearance`. For a host's own wiring,
481
+ use `hydrateScope`, `hydrateSearch`, `hydrateBell`, `hydrateAccount`,
482
+ `hydrateAppearance` and `setWaiting` in `shell-client.js`.
483
+ - The words: `kit.scope`, `kit.search.ph`, `kit.bell`, `kit.bell.n`,
484
+ `kit.bell.empty`, `kit.settings`, `kit.appearance`,
485
+ `kit.appearance.title`, `kit.mode.system`, `kit.mode.dark`,
486
+ `kit.mode.light`, `kit.theme` and `kit.language`, in en, es and ja. The look is in `shell.css`. At 860px
487
+ the crumbs' keys and any `optional` crumb give way. At 720px the crumbs
488
+ hide and the search is only its icon.
489
+ - `den-ui-parity` knows them as components `scope`, `search`, `bell`,
490
+ `appearance` and `account`, and the update-waiting pill as part of
491
+ `version`. A product's own copy of one fails the gate. A product's
492
+ own rows inside the bell, or its own menu inside a crumb, are not copies.
493
+ - Report's screenshot shows what the person sees (issue 295): the
494
+ window's scroll and every scrolled pane's, with sticky and fixed parts
495
+ where they are on screen. The image is still the window's size, so
496
+ masks line up as before.
497
+
317
498
  ## 0.6.6
318
499
 
319
500
  - A time drawn by `upgradeTimes` reads in the language of the part of
@@ -100,9 +100,23 @@ export const COMPONENTS = {
100
100
  },
101
101
  version: {
102
102
  label: "version chip",
103
- markup: [id("version-pill"), cls("v-pill"), cls("v-pip")],
104
- css: ["v-pill", "v-pip", "v-txt", "version-pill"],
105
- code: ["versionChipHtml"],
103
+ // 0.7.0: and the update-waiting pill beside it.
104
+ markup: [
105
+ id("version-pill"),
106
+ cls("v-pill"),
107
+ cls("v-pip"),
108
+ cls("stale-pill"),
109
+ id("stale-pill"),
110
+ ],
111
+ css: [
112
+ "v-pill",
113
+ "v-pip",
114
+ "v-txt",
115
+ "version-pill",
116
+ "stale-pill",
117
+ "stale-lbl",
118
+ ],
119
+ code: ["versionChipHtml", "waitingHtml", "setWaiting"],
106
120
  files: ["version.js", "version-label.js"],
107
121
  },
108
122
  whatsnew: {
@@ -142,6 +156,67 @@ export const COMPONENTS = {
142
156
  code: ["configureBusy", "registerActions"],
143
157
  files: ["busy.js", "busy-words.js", "busy.css"],
144
158
  },
159
+ // 0.7.0: pieces of the top bar and rail a product drew itself before.
160
+ // Its words and values go in the kit's options; its own HTML in a crumb's
161
+ // menu or the bell's rows (classes of its own) is not a copy.
162
+ scope: {
163
+ label: "scope crumbs (COMPANY / PROJECT / ENV, each with its ▾)",
164
+ markup: [
165
+ cls("den-scope"),
166
+ cls("den-scope-btn"),
167
+ cls("den-scope-menu"),
168
+ cls("den-mfilter"),
169
+ cls("den-mnone"),
170
+ ],
171
+ css: ["den-scope", "den-scope-btn", "den-scope-menu", "den-mfilter"],
172
+ code: ["scopeHtml", "scopeCrumbHtml", "scopeButton", "hydrateScope"],
173
+ files: [],
174
+ },
175
+ search: {
176
+ label: "search field with ⌘K inside",
177
+ markup: [cls("den-search"), cls("den-search-ph"), cls("den-search-ic")],
178
+ css: ["den-search", "den-search-ph", "den-search-ic", "den-kbd"],
179
+ code: ["searchHtml", "hydrateSearch"],
180
+ files: [],
181
+ },
182
+ bell: {
183
+ label: "bell (its button, count and panel)",
184
+ markup: [
185
+ cls("den-bell"),
186
+ cls("den-bell-n"),
187
+ cls("den-bell-pop"),
188
+ cls("den-bell-hd"),
189
+ cls("den-bell-empty"),
190
+ ],
191
+ css: [
192
+ "den-bell",
193
+ "den-bell-n",
194
+ "den-bell-pop",
195
+ "den-bell-hd",
196
+ "den-bell-empty",
197
+ ],
198
+ code: ["bellButtonHtml", "bellPanelHtml", "hydrateBell"],
199
+ files: [],
200
+ },
201
+ appearance: {
202
+ label: "appearance menu (◐ ▾: mode, theme, language)",
203
+ markup: [cls("appearance-btn"), id("appearance-btn")],
204
+ css: ["appearance-btn"],
205
+ code: [
206
+ "appearanceButtonHtml",
207
+ "appearanceMenuHtml",
208
+ "hydrateAppearance",
209
+ "userMenu",
210
+ ],
211
+ files: [],
212
+ },
213
+ account: {
214
+ label: "account entry in the rail's foot",
215
+ markup: [/\bdata-den-account\b/, cls("den-acct-d"), cls("den-mform")],
216
+ css: ["den-acct-d", "den-mform"],
217
+ code: ["accountHtml", "accountMenuHtml", "hydrateAccount", "identityEntry"],
218
+ files: [],
219
+ },
145
220
  };
146
221
 
147
222
  const SCAN_EXT = /\.(m?[jt]sx?|css|html?)$/;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Where the kit's font files are (src/fonts), found from this file itself:
3
+ * the CommonJS side of the "#den-ui-fonts-dir" import (package.json
4
+ * "imports"), as a test runner that compiles to CommonJS loads it.
5
+ */
6
+ const path = require("node:path");
7
+
8
+ exports.FONTS_DIR = path.join(__dirname, "..", "src", "fonts");
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Where the kit's font files are (src/fonts), found from this file itself:
3
+ * the ES module side of the "#den-ui-fonts-dir" import (package.json
4
+ * "imports"). fonts-dir.cjs is the CommonJS side.
5
+ */
6
+ import { fileURLToPath } from "node:url";
7
+
8
+ export const FONTS_DIR = fileURLToPath(
9
+ new URL("../src/fonts/", import.meta.url),
10
+ );
@@ -23,6 +23,18 @@ export interface NavElement {
23
23
  box: NavBox;
24
24
  /** Computed styles, by property name (STYLE_PROPS). */
25
25
  style: Record<string, string>;
26
+ /**
27
+ * Host content: the nearest element (this one or an ancestor) with a
28
+ * data-nav-role, by role and key. Absent on the kit's own chrome.
29
+ */
30
+ host?: {
31
+ role: string;
32
+ key: string;
33
+ /** On the role's own element: its contents' width with padding and border. */
34
+ fit?: number;
35
+ };
36
+ /** Its accessible name is the host's words (data-nav-name="host"). */
37
+ hostName?: boolean;
26
38
  }
27
39
  export interface NavTheme {
28
40
  id: string;
@@ -81,9 +93,41 @@ export declare function collectNav(
81
93
  ): Promise<NavSnapshot>;
82
94
  /** The browser build's fingerprint: user agent and the faces' widths. */
83
95
  export declare function fingerprint(snap: NavSnapshot): string;
96
+ /** A font family or face key as one line: whitespace runs one space, trimmed. */
97
+ export declare function navFamily(s: string): string;
84
98
  export declare function compareNav(
85
99
  actual: NavSnapshot,
86
100
  reference: NavSnapshot,
87
101
  opts?: NavCompareOptions,
88
102
  ): NavDiff[];
89
103
  export declare function formatNavDiffs(diffs: NavDiff[]): string;
104
+ /** The pin stylesheet: the system faces a nav names, as the kit's own files. */
105
+ export declare const PIN_FONTS_CSS: string;
106
+ /**
107
+ * What pinNavFonts needs of a Playwright BrowserContext. Its results are
108
+ * not used: Playwright's resolve to a Disposable (1.61), others to nothing.
109
+ */
110
+ export interface NavFontContext {
111
+ route(
112
+ url: string,
113
+ handler: (route: {
114
+ request(): { url(): string };
115
+ fulfill(o: {
116
+ status?: number;
117
+ contentType?: string;
118
+ body?: string | Buffer;
119
+ }): Promise<unknown>;
120
+ }) => unknown,
121
+ ): Promise<unknown>;
122
+ addInitScript(script: () => void): Promise<unknown>;
123
+ }
124
+ /**
125
+ * Pins a context's fonts the way the reference was taken: the pin
126
+ * stylesheet first on every page, /__pin-fonts/* served from the kit's
127
+ * own font files (src/fonts, or opts.fontsDir). Call it before opening a
128
+ * page.
129
+ */
130
+ export declare function pinNavFonts(
131
+ context: NavFontContext,
132
+ opts?: { fontsDir?: string },
133
+ ): Promise<void>;