@monster-orange/den-ui 0.6.6 → 0.7.1

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
@@ -200,8 +201,8 @@ browsers to it through `DEN_PW_WS`:
200
201
  DEN_PW_WS=ws://localhost:3921/
201
202
 
202
203
  import { chromium } from "playwright"; // 1.61.1, as the image
203
- import { collectNav, compareNav, formatNavDiffs, NAV_BROWSER_IMAGE,
204
- NAV_THEME } from "@monster-orange/den-ui/inventory";
204
+ import { collectNav, compareNav, formatNavDiffs, navWarnings,
205
+ NAV_BROWSER_IMAGE, NAV_THEME } from "@monster-orange/den-ui/inventory";
205
206
  import { readFileSync } from "node:fs";
206
207
  import { createRequire } from "node:module";
207
208
 
@@ -215,12 +216,17 @@ browsers to it through `DEN_PW_WS`:
215
216
  const ref = JSON.parse(readFileSync(createRequire(import.meta.url)
216
217
  .resolve("@monster-orange/den-ui/inventory/reference/den-chromium-1280.json"),
217
218
  "utf-8"));
219
+ const snap = await collectNav(page, { image: NAV_BROWSER_IMAGE,
220
+ theme: NAV_THEME });
218
221
  const diffs = compareNav(
219
- await collectNav(page, { image: NAV_BROWSER_IMAGE, theme: NAV_THEME }),
222
+ snap,
220
223
  ref,
221
224
  { hostSlots: ["#my-status"] }, // what the host fills itself
222
225
  );
223
226
  expect(formatNavDiffs(diffs)).toBe(""); // one line per difference
227
+ // 0.7.1: host HTML where the kit's account or search should be.
228
+ // Listed, not failed, until 0.7.2 gives every slot a data path.
229
+ for (const w of navWarnings(snap)) console.warn(w);
224
230
 
225
231
  Pass `theme` as the theme the page really draws in (Den reads it from
226
232
  `/api/themes`). On another browser build (a different fingerprint: user
@@ -255,6 +261,20 @@ env, elements, tokens }`. `env`: `userAgent`, `faces` (the
255
261
  either side. A host slot wider or narrower than the reference (or on
256
262
  one side only) may move or stretch its neighbours sideways by exactly
257
263
  that much, never by anything else.
264
+ - Host content: the kit stamps `data-nav-role` on what each host fills
265
+ with its own words: each scope crumb (`crumb`) and the separator after
266
+ it (`crumb-sep`), the brand's title (`brand-title`), each rail group
267
+ (`rail-group`), its heading (`group`) and its pages (`page`), and the
268
+ account entry's words (`account-name`). An element with
269
+ `data-nav-name="host"` holds a name that is the host's (not compared).
270
+ The search's placeholder and name are the kit's, and compared. Their count, keys, ids, text and
271
+ width are never compared, on either side. The first of each role is
272
+ compared with the other side's first, and what it holds by key, on
273
+ every computed style and on height. Their size may move what follows by
274
+ exactly its change: sideways in the bar (their contents' width, not a
275
+ filled box's), down in the rail (heights; the rail's spacer shrinks by
276
+ as much). The mark, the search field's box and all other chrome stay
277
+ strict. The references hold each element's `host`.
258
278
  - `themeTokens`: empty by default, and never set on a parity run: both
259
279
  products run in `NAV_THEME`, so any colour or font that differs is a
260
280
  real gap. It is only for a run that switches themes on purpose. What a
@@ -270,9 +290,25 @@ env, elements, tokens }`. `env`: `userAgent`, `faces` (the
270
290
  list on its `font-family`, and read back, so it is in the form computed
271
291
  values take. `snapshot.tokens` maps each colour and family seen to the
272
292
  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`).
293
+ - Fonts: `await pinNavFonts(context)` (from `./inventory`) pins the
294
+ system faces a nav names to the kit's own Rubik and Space Mono, so text
295
+ lays out alike from run to run, as when the reference was taken. Call it
296
+ on the Playwright `BrowserContext` before opening the page. It puts the
297
+ pin stylesheet first on every page and serves `/__pin-fonts/*` from the
298
+ package's `src/fonts` (or `{ fontsDir }`). It finds them from its own
299
+ files, never from the working folder: the package's `imports` entry
300
+ `#den-ui-fonts-dir` is `inventory/fonts-dir.mjs` for an ES module
301
+ (`import.meta.url`) and `inventory/fonts-dir.cjs` for CommonJS
302
+ (`__dirname`). Both ship in `inventory/`; a host serves neither.
303
+ - Font families in the fingerprint are one line each (`navFamily`: every
304
+ run of whitespace one space, trimmed), so a token written over several
305
+ lines names the same face as one written on one.
306
+ - The user agent: under `@playwright/test`, the config's device
307
+ `userAgent` leaks into the contexts of a browser you connect to, and the
308
+ environment check then sees another user agent than the reference's.
309
+ Set `test.use({ userAgent: "" })`, or create the context with no
310
+ `userAgent`. `NAV_BROWSER_IMAGE` and
311
+ `NAV_THEME` are exported beside it.
276
312
 
277
313
  Den runs it in `tests/unit/den-ui/nav-inventory.browser.test.ts` (CI's
278
314
  `den-ui-nav` job starts the image) with red cases that must fail: the
@@ -314,6 +350,234 @@ browser test, on the image (Den's real server on the demo distribution,
314
350
  is `src/kit.d.ts`. A test compiles a consumer against them with
315
351
  `--strict`.
316
352
 
353
+ ## 0.7.1
354
+
355
+ The top bar's search sits in the same place in every product (issue 303).
356
+
357
+ - **The account is data.** `accountHtml` and `accountMenuHtml` take
358
+ `{ name?, login, role? }`. The rail's entry is the name over `@login`,
359
+ or `@login` alone when no name is known; never the role. The account
360
+ menu's header is the same, then the role on its own line. The kit adds the `@`. The old `{ label, detail }`
361
+ (and the menu's `{ name, detail }`) still work for this release, drawn
362
+ as given, and the nav inventory fails a host that uses them
363
+ (`legacy`). `accountWho(a)` gives the lines and the shape.
364
+ - **The search never moves.** Its x is a function of the viewport only:
365
+ `searchSlot(width)` gives `{ x, w }` (464 / 304 at 1280, 396 at 1100,
366
+ 256 at 960, 82 / 54 on a phone), the same in any host. The left part is
367
+ the smaller of `--den-top-left` (444px) and what the search and the
368
+ right group's reserve (`--den-top-right`, 380px) leave.
369
+ - **The right group is anchored from the right edge.** ◐ at the bar's
370
+ padding, then the version in a fixed slot (`--den-top-version` 96px;
371
+ `--den-top-version-md` 64px up to 1100px; its text ends in "…", the
372
+ whole version in its title), the bell and Report, 4px apart: the same
373
+ x in any host. Report, the bell and ◐ never shrink; the kit sets their
374
+ font and box. The host's chips (`div.den-end`, always drawn, empty
375
+ without chips) take the room left: a chip gives way down to its dot
376
+ and "…", and the kit puts its whole words in its title and name (a
377
+ name or title the host set itself is kept).
378
+ - **Crumbs.** A crumb's label gives way first, then its value ends in
379
+ "…"; before the last crumb a value keeps about 4ch and its ▾.
380
+ - **Checks.** `topSlotDiffs(snap)` checks the search's slot and the
381
+ right group's places at any width (no reference needed); `compareNav`
382
+ runs it too, and fails a crumb whose label shows while its value is
383
+ hidden.
384
+ - **Shape, not only style.** The inventory compares what a kit slot
385
+ draws: the account entry's shape is one of the kit's (`name,login` on
386
+ two lines, `login` or `local` on one: `ACCOUNT_SHAPES`), the old fields
387
+ fail (`legacy`), and the search's box is pinned. `navWarnings(snap)` lists host HTML where the kit's account
388
+ or search should be: a warning in 0.7.1, a failure in 0.7.2.
389
+
390
+ - **Three parts.** The bar is a grid: the left part (`div.den-left`: ☰,
391
+ the brand, and what `start` holds before the search, the crumbs), the
392
+ search, then the chips (the host's `end` in `div.den-end`, then Report,
393
+ the bell, the version and ◐ ▾, pinned to the right edge). The kit finds
394
+ its search in `start` and puts it in its slot; a host's markup is
395
+ unchanged.
396
+ - **Settings** (custom properties on `.den-top`, with their defaults):
397
+ `--den-top-left` (444px), `--den-top-search` (304px), and under 720px
398
+ `--den-top-left-md`
399
+ (200px) and, under 480px, `--den-top-left-sm` (62px: ☰ and the mark).
400
+ At 1280px the search is at x 464, 304 wide; on a phone at x 82.
401
+ - **Giving way.** Long words never move the search. The crumbs give way
402
+ first: each crumb gets an equal share until it is whole, so a short one
403
+ keeps its words and a long one ends in "…"; the last crumb is kept
404
+ whole. Then the install name ends in "…". Under about 1100px the
405
+ host's chips give way (their words end in "…"; the kit's buttons keep
406
+ their size). The chips' column is never narrower than the kit's own
407
+ buttons, so the chips never run under the search: when the bar is too
408
+ narrow for all three parts, the left part gives way and the search
409
+ moves left. A host chip is width 0 growing to its own width
410
+ (`max-width: max-content`): put its words in its last child, a span,
411
+ which ends in "…".
412
+ - **A gap after ⌕**: 8px between the search and the chips, and 8px more
413
+ before the first chip.
414
+ - **The search's words** are the kit's ("Search…", named "Search"; es,
415
+ ja): `searchHtml()` takes no placeholder or label.
416
+ - **Touch** (`pointer: coarse`): every control in the bar takes a 44×44px
417
+ tap (an `::after` hit area, centred; the look is the same), and the
418
+ key hints (⌘K, ⌘⇧F, any `.den-kbd`) hide.
419
+ - **`.den-hit`**: the same 44×44px tap for a host's own buttons and tabs.
420
+ On a touch screen it is `position: relative` plus a transparent,
421
+ centred `::after` at least 44×44px; without touch it does nothing. Its
422
+ look and layout never change. It sits beside `.den-kbd`, the one
423
+ key-cap rule, which hides on a touch screen wherever it is (a palette,
424
+ a button). `den-ui-parity` knows both: a host keeps no copy.
425
+ - **Nav inventory**: the search, Report, the bell, the version chip and ◐
426
+ ▾ (`PINNED_CLASSES`) are compared at the reference's x and width: no
427
+ host-content shift excuses moving them. Den's references, and the
428
+ parity fixture and PNGs, were re-taken for this layout.
429
+
430
+ ## 0.7.0
431
+
432
+ No new file. One import changes, for hosts that serve a fixed list of kit files:
433
+
434
+ `shell-client.js` now imports `dialog.js` (and `shell-html.js`): serve `dialog.js` wherever `shell-client.js` is served.
435
+
436
+ Default tokens are Den's theme. `tokens.css`'s defaults are now the values
437
+ of Den's own theme (`themes/den/den-theme.json`): its type stacks (sans,
438
+ mono, display, ja), its shape (radius 8px, radius-button 6px) and both
439
+ modes' colours, shadow and bar. A host on the kit's defaults looks like
440
+ Den. Light and dark switch as before. Themes are still token sets the host
441
+ lists in `appearanceMenuHtml({ themes })`; the kit ships no theme files.
442
+ Tokens the theme has no value for keep the kit's own: `--info`,
443
+ `--violet`, `--upd-shadow`, `--density` and the rest.
444
+
445
+ `tokens.css` owns `--den-pop-shadow`, the shadow of a pop-up or a picker
446
+ dialog: `0 16px 40px rgb(0 0 0 / 0.25)` in light, `/ 0.6` in dark. A host
447
+ that kept its own copy of that token can delete it.
448
+
449
+ The whole global nav is the kit's. Pieces of the top bar and the rail
450
+ that a host drew itself move into the kit, so every host draws them the
451
+ same way, with the same CSS values. In order: ☰ · brand · scope crumbs ·
452
+ search with ⌘K · the host's `end` slot (status chips) · Report · bell ·
453
+ version chip with its pip and the update-waiting pill · ◐ ▾. The rail's
454
+ foot: the host's entries · Settings · account · Collapse. The host gives words,
455
+ values and callbacks. The kit draws the markup and owns focus and keys.
456
+ Each piece is optional: one left out draws nothing.
457
+
458
+ - **Scope crumbs**: `scopeHtml({ crumbs, label?, after? })`, for the
459
+ `start` slot. Each crumb is `{ key, label, value, menu?, id?, title?,
460
+ hidden?, optional? }`. `label` is the small-caps word (COMPANY,
461
+ PROJECT, ENV). With a `menu`, the crumb is a ▾ button. Without one, it is
462
+ a plain label. `menu` is a list of links `[{ label, href, current? }]`
463
+ or HTML, and the kit draws and opens it below the ▾. Enter, Space, ↓ and
464
+ ↑ open it, and ↑ ↓ Home End move in it. Esc closes it and goes back to
465
+ the ▾. `menu: true` means the host opens its own menu: `onOpen(key,
466
+ button)`. A crumb left out of the list draws nothing, and no separator
467
+ either (a host with no ENV, say). `scopeCrumbHtml(crumb)` draws one crumb.
468
+ A kit-drawn list of more than 6 links gets a filter field at its top
469
+ (`filter`: a number sets that threshold, `false` turns it off). The menu
470
+ opens on the field. Typing hides the links that don't hold the text, and
471
+ "No match" shows when none do. ↓ goes to the links, Enter takes the first
472
+ one shown, and Esc clears the text, then closes the menu.
473
+ - **Search field**: `searchHtml({ id?, shortcut? })`, for the `start`
474
+ slot. It is the kit's placeholder ("Search…") with ⌘K inside the field. A
475
+ click, Enter, ⌘K or Ctrl-K calls `onActivate(via)` (`"click"` or
476
+ `"key"`) and fires `den-ui:search` on the field. The kit owns no
477
+ palette.
478
+ - **Bell**: `bellButtonHtml({ count, label? })`, for the `bell` slot. It is
479
+ a button with a count badge (99+ past 99, none at 0) and
480
+ `aria-haspopup="dialog"`. Its name says the count. The panel is a dialog
481
+ on `<body>`: a heading, then the host's `items` as rows (`{ text, href?,
482
+ time?, read? }`) or the empty state. `bellPanelHtml(...)` takes `actions`
483
+ (buttons beside the heading), `lead`, `body` (the host's own rows),
484
+ `empty`, `after` and `foot`. A click on the bell toggles the panel.
485
+ Opening it focuses its first link or button. Esc closes it and focus goes
486
+ back to the bell, in Safari too (`focusBack` from `dialog.js`). A click
487
+ outside closes it. `onEscape(e)` returning true keeps it open (the
488
+ host's own question inside it, say). `shell.bell.setCount(n)` updates the
489
+ badge.
490
+ - **Account entry**: `account: { label, detail?, href? | menu? | action? }`
491
+ on `shellHtml` or `railHtml` puts it last in the rail's foot, before the
492
+ collapse toggle. It reads "label · detail". It is a link, or with
493
+ `action: true` a button that calls `onAction`. `accountHtml(...)` draws
494
+ it alone.
495
+ - **Account menu**: with `menu: true`, the entry is a button (id
496
+ `den-account`) that opens a menu: who is signed in, where, a rule, then
497
+ the entries. Wire it with `hydrate`'s `account: { menu, onPick?,
498
+ onSubmit? }`. `menu()` gives `{ name, detail?, items }`. An item is a link
499
+ `{ label, href }`, a button `{ label, id }` (`onPick("item", id)`), or a
500
+ form post `{ label, action: { method?, url, csrf?, field? } }`. A form
501
+ post needs no script: Sign out posts to `url`, with `csrf` in a hidden
502
+ field (named `field`, `csrf` by default). `onSubmit(event, form)` runs
503
+ first, and `preventDefault` there stops the post. The kit owns open,
504
+ close, the keys, Esc and focus going back to the entry.
505
+ `accountMenuHtml(...)` draws the content alone.
506
+ - **Appearance menu**: `appearanceButtonHtml({ label?, title? })`, for the
507
+ `account` slot (last in the bar): ◐ ▾ with `aria-haspopup="menu"`. Wire
508
+ it with `hydrate`'s `appearance: { menu, onPick }`. `menu()` gives, each
509
+ time it opens, `{ mode, modes?, themes, notice?, languages, items }`:
510
+ the mode (System, Dark, Light by default), the themes `{ value, label,
511
+ selected }`, a line under them, the languages `{ id, name, current }`,
512
+ each named in itself, and entries after a rule (`{ label, href? | id }`).
513
+ A pick calls `onPick(kind, value)` with `"mode"`, `"theme"`,
514
+ `"language"` or `"item"`, and closes the menu. Click, Enter, Space, ↓ or
515
+ ↑ open it on the checked entry. ↑ ↓ Home End move. Esc or Tab closes it
516
+ and focus goes back to ◐ ▾, in Safari too. A press outside closes it.
517
+ The host saves and applies the pick. The kit owns no settings.
518
+ - **Version pip and update-waiting pill**: the chip's pip (`#v-pip`) shows
519
+ unread notes (`DenUI.version.unread(on)`, as before).
520
+ `DenUI.version.waiting({ label, action, title?, name?, onClick })` shows
521
+ the update-waiting pill right after the chip ("⚠ label · action", a
522
+ pulsing warn pill; only ⚠ below 720px). `waiting(null)` hides it.
523
+ `waitingHtml(...)` draws it.
524
+ - **Settings**: `settings: { href, label?, current? }` on `shellHtml` or
525
+ `railHtml` puts Settings in the rail's foot after the host's entries and
526
+ before the account entry. `settingsHtml(...)` draws it alone.
527
+ - **Brand mark**: `product.mark: { src, label }` draws an image file the
528
+ way Den draws its theme's mark: `span.den-mark.den-mark-svg#den-mark`
529
+ titled `label`, holding `<img src alt="" width="18" height="18">`. The
530
+ kit ships the default theme's mark as `src/marks/den.svg`, beside
531
+ `src/fonts/`; a host serves it with the kit's other files and passes
532
+ `mark: { src: "<served path>/marks/den.svg", label }` (Den serves it at
533
+ `/kit/marks/den.svg`). An image runs no script. `markHtml(mark)` draws
534
+ it alone; Den's own theme mark is drawn by it. `{ text }` and `{ svg }`
535
+ work as before.
536
+ - **Mark layout**: `.den-mark` (a centred flex box, its image a block)
537
+ and the text and raster forms are in `shell.css`. A host deletes its
538
+ own copy.
539
+ - **A phone's tap targets**: below 480px every top-bar button is at least
540
+ 32px each way (`shell.css`).
541
+ - **The brand on a phone**: below 480px the brand (its mark alone) never
542
+ shrinks; the host's chips give way.
543
+ - **Search words**: the placeholder ("Search…") and the field's name
544
+ ("Search") are the kit's, in en, es and ja. A host can't set them: one
545
+ search in every product.
546
+ - **Filtered menus**: a menu with the filter field is a pop-up holding the
547
+ field, then the `role="menu"` list (`.den-mlist`, id `<menu>-list`),
548
+ then "No match": a menu owns only its items. The field has
549
+ `aria-controls` on the list and its `aria-label` ("Filter <label>").
550
+ `attachMenuFilter(menu)` moves a host menu's rows, role and name into
551
+ that list; `menu` keeps its id and stays the pop-up. The keys and the
552
+ look are as before.
553
+ - **Key caps**: `.den-kbd` is the one key-cap rule: the search's ⌘K,
554
+ Report's ⌘⇧F and any `<kbd class="den-kbd">` a host draws (its palette's
555
+ hints, say). A 1px border with a 2px bottom, 4px corners, `--surface`
556
+ behind, 5px each side. A host deletes its own copy.
557
+ - **Group headings**: a heading with its "from" tag is as tall as one
558
+ without (32px in Den's fonts): the tag sits on a 12px line, centred.
559
+ - The kit's menus (◐ ▾, a crumb's own menu) wear `.den-pop`, `.den-mi`,
560
+ `.den-ml`, `.den-hr` and `.den-mnote`, styled in `shell.css`.
561
+ - Wiring: `DenUI.hydrate(root, { scope, search, bell, account, appearance })` (or
562
+ `mount`'s `model.hydrate`) wires each piece it finds. The shell it
563
+ returns has `.scope`, `.search`, `.bell` and `.appearance`. For a host's own wiring,
564
+ use `hydrateScope`, `hydrateSearch`, `hydrateBell`, `hydrateAccount`,
565
+ `hydrateAppearance` and `setWaiting` in `shell-client.js`.
566
+ - The words: `kit.scope`, `kit.search.ph`, `kit.bell`, `kit.bell.n`,
567
+ `kit.bell.empty`, `kit.settings`, `kit.appearance`,
568
+ `kit.appearance.title`, `kit.mode.system`, `kit.mode.dark`,
569
+ `kit.mode.light`, `kit.theme` and `kit.language`, in en, es and ja. The look is in `shell.css`. At 860px
570
+ the crumbs' keys and any `optional` crumb give way. At 720px the crumbs
571
+ hide and the search is only its icon.
572
+ - `den-ui-parity` knows them as components `scope`, `search`, `bell`,
573
+ `appearance` and `account`, and the update-waiting pill as part of
574
+ `version`. A product's own copy of one fails the gate. A product's
575
+ own rows inside the bell, or its own menu inside a crumb, are not copies.
576
+ - Report's screenshot shows what the person sees (issue 295): the
577
+ window's scroll and every scrolled pane's, with sticky and fixed parts
578
+ where they are on screen. The image is still the window's size, so
579
+ masks line up as before.
580
+
317
581
  ## 0.6.6
318
582
 
319
583
  - A time drawn by `upgradeTimes` reads in the language of the part of
@@ -82,6 +82,8 @@ export const COMPONENTS = {
82
82
  "den-collapse-btn",
83
83
  "den-pin-row",
84
84
  "den-scrim",
85
+ // 0.7.1: the 44px tap on touch, for any control.
86
+ "den-hit",
85
87
  // Not here: den-has-shell, den-rail-collapsed and den-rail-open are
86
88
  // the body's state classes, for a page to lay its own content out by.
87
89
  ],
@@ -100,9 +102,23 @@ export const COMPONENTS = {
100
102
  },
101
103
  version: {
102
104
  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"],
105
+ // 0.7.0: and the update-waiting pill beside it.
106
+ markup: [
107
+ id("version-pill"),
108
+ cls("v-pill"),
109
+ cls("v-pip"),
110
+ cls("stale-pill"),
111
+ id("stale-pill"),
112
+ ],
113
+ css: [
114
+ "v-pill",
115
+ "v-pip",
116
+ "v-txt",
117
+ "version-pill",
118
+ "stale-pill",
119
+ "stale-lbl",
120
+ ],
121
+ code: ["versionChipHtml", "waitingHtml", "setWaiting"],
106
122
  files: ["version.js", "version-label.js"],
107
123
  },
108
124
  whatsnew: {
@@ -142,6 +158,67 @@ export const COMPONENTS = {
142
158
  code: ["configureBusy", "registerActions"],
143
159
  files: ["busy.js", "busy-words.js", "busy.css"],
144
160
  },
161
+ // 0.7.0: pieces of the top bar and rail a product drew itself before.
162
+ // Its words and values go in the kit's options; its own HTML in a crumb's
163
+ // menu or the bell's rows (classes of its own) is not a copy.
164
+ scope: {
165
+ label: "scope crumbs (COMPANY / PROJECT / ENV, each with its ▾)",
166
+ markup: [
167
+ cls("den-scope"),
168
+ cls("den-scope-btn"),
169
+ cls("den-scope-menu"),
170
+ cls("den-mfilter"),
171
+ cls("den-mnone"),
172
+ ],
173
+ css: ["den-scope", "den-scope-btn", "den-scope-menu", "den-mfilter"],
174
+ code: ["scopeHtml", "scopeCrumbHtml", "scopeButton", "hydrateScope"],
175
+ files: [],
176
+ },
177
+ search: {
178
+ label: "search field with ⌘K inside",
179
+ markup: [cls("den-search"), cls("den-search-ph"), cls("den-search-ic")],
180
+ css: ["den-search", "den-search-ph", "den-search-ic", "den-kbd"],
181
+ code: ["searchHtml", "hydrateSearch"],
182
+ files: [],
183
+ },
184
+ bell: {
185
+ label: "bell (its button, count and panel)",
186
+ markup: [
187
+ cls("den-bell"),
188
+ cls("den-bell-n"),
189
+ cls("den-bell-pop"),
190
+ cls("den-bell-hd"),
191
+ cls("den-bell-empty"),
192
+ ],
193
+ css: [
194
+ "den-bell",
195
+ "den-bell-n",
196
+ "den-bell-pop",
197
+ "den-bell-hd",
198
+ "den-bell-empty",
199
+ ],
200
+ code: ["bellButtonHtml", "bellPanelHtml", "hydrateBell"],
201
+ files: [],
202
+ },
203
+ appearance: {
204
+ label: "appearance menu (◐ ▾: mode, theme, language)",
205
+ markup: [cls("appearance-btn"), id("appearance-btn")],
206
+ css: ["appearance-btn"],
207
+ code: [
208
+ "appearanceButtonHtml",
209
+ "appearanceMenuHtml",
210
+ "hydrateAppearance",
211
+ "userMenu",
212
+ ],
213
+ files: [],
214
+ },
215
+ account: {
216
+ label: "account entry in the rail's foot",
217
+ markup: [/\bdata-den-account\b/, cls("den-acct-d"), cls("den-mform")],
218
+ css: ["den-acct-d", "den-mform"],
219
+ code: ["accountHtml", "accountMenuHtml", "hydrateAccount", "identityEntry"],
220
+ files: [],
221
+ },
145
222
  };
146
223
 
147
224
  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,30 @@ 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;
38
+ /** 0.7.1: a kit-owned slot's content shape (data-nav-shape: its fields). */
39
+ shape?: string;
40
+ /** 0.7.1: drawn from the old free-text fields (data-nav-legacy). */
41
+ legacy?: boolean;
42
+ /** The rail's account entry (data-den-account). */
43
+ account?: boolean;
44
+ /** The account entry's drawn lines. */
45
+ lines?: number;
46
+ /** A crumb whose label shows while its value is hidden. */
47
+ labelOnly?: boolean;
48
+ /** The kit's stamp on what it draws (data-nav-kit). */
49
+ kit?: string;
26
50
  }
27
51
  export interface NavTheme {
28
52
  id: string;
@@ -75,15 +99,72 @@ export declare const NAV_BROWSER_IMAGE: string;
75
99
  export declare const FINGERPRINT_TEXT: string;
76
100
  /** The theme the reference was taken in ("den" 2.0.1): every parity run uses it. */
77
101
  export declare const NAV_THEME: NavTheme;
102
+ /**
103
+ * issue 303: classes of the top bar's pinned elements (the search, Report,
104
+ * the bell, the version chip, ◐ ▾): compared at the reference's x and
105
+ * width, with no host-content allowance.
106
+ */
107
+ export declare const PINNED_CLASSES: readonly string[];
108
+ /** The search's x and width for a viewport width, the same in any host. */
109
+ export declare function searchSlot(viewportW: number): { x: number; w: number };
110
+ export declare const TOP_RIGHT_MIN: number;
111
+ /** The search away from searchSlot (slot.x, slot.w), at any width. */
112
+ export declare function searchSlotDiffs(
113
+ snap: NavSnapshot,
114
+ tolerance?: number,
115
+ ): NavDiff[];
116
+ /** The account entry's shapes the kit draws → their line counts. */
117
+ export declare const ACCOUNT_SHAPES: Record<string, number>;
118
+ /** The version's fixed slot width for a viewport width (0 on a phone). */
119
+ export declare function versionSlotW(viewportW: number): number;
120
+ /** searchSlotDiffs plus Report, bell, version and ◐ anchored from the right. */
121
+ export declare function topSlotDiffs(
122
+ snap: NavSnapshot,
123
+ tolerance?: number,
124
+ ): NavDiff[];
125
+ /** 0.7.1: host HTML in the kit's account and search slots (warnings). */
126
+ export declare function navWarnings(snap: NavSnapshot): string[];
78
127
  export declare function collectNav(
79
128
  page: NavPage,
80
129
  opts?: { image?: string; theme?: NavTheme },
81
130
  ): Promise<NavSnapshot>;
82
131
  /** The browser build's fingerprint: user agent and the faces' widths. */
83
132
  export declare function fingerprint(snap: NavSnapshot): string;
133
+ /** A font family or face key as one line: whitespace runs one space, trimmed. */
134
+ export declare function navFamily(s: string): string;
84
135
  export declare function compareNav(
85
136
  actual: NavSnapshot,
86
137
  reference: NavSnapshot,
87
138
  opts?: NavCompareOptions,
88
139
  ): NavDiff[];
89
140
  export declare function formatNavDiffs(diffs: NavDiff[]): string;
141
+ /** The pin stylesheet: the system faces a nav names, as the kit's own files. */
142
+ export declare const PIN_FONTS_CSS: string;
143
+ /**
144
+ * What pinNavFonts needs of a Playwright BrowserContext. Its results are
145
+ * not used: Playwright's resolve to a Disposable (1.61), others to nothing.
146
+ */
147
+ export interface NavFontContext {
148
+ route(
149
+ url: string,
150
+ handler: (route: {
151
+ request(): { url(): string };
152
+ fulfill(o: {
153
+ status?: number;
154
+ contentType?: string;
155
+ body?: string | Buffer;
156
+ }): Promise<unknown>;
157
+ }) => unknown,
158
+ ): Promise<unknown>;
159
+ addInitScript(script: () => void): Promise<unknown>;
160
+ }
161
+ /**
162
+ * Pins a context's fonts the way the reference was taken: the pin
163
+ * stylesheet first on every page, /__pin-fonts/* served from the kit's
164
+ * own font files (src/fonts, or opts.fontsDir). Call it before opening a
165
+ * page.
166
+ */
167
+ export declare function pinNavFonts(
168
+ context: NavFontContext,
169
+ opts?: { fontsDir?: string },
170
+ ): Promise<void>;