@monster-orange/den-ui 0.5.1 → 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.
Files changed (45) hide show
  1. package/README.md +515 -1
  2. package/bin/den-ui-parity.mjs +440 -0
  3. package/inventory/fonts-dir.cjs +8 -0
  4. package/inventory/fonts-dir.mjs +10 -0
  5. package/inventory/nav-inventory.d.ts +133 -0
  6. package/inventory/nav-inventory.js +839 -0
  7. package/inventory/reference/den-chromium-1280.json +5388 -0
  8. package/inventory/reference/den-chromium-390.json +3834 -0
  9. package/inventory/reference/den-webkit-1280.json +5388 -0
  10. package/inventory/reference/den-webkit-390.json +3834 -0
  11. package/package.json +40 -3
  12. package/src/busy-words.d.ts +2 -0
  13. package/src/busy-words.js +6 -0
  14. package/src/busy.css +155 -0
  15. package/src/busy.d.ts +80 -0
  16. package/src/busy.js +105 -35
  17. package/src/dialog.css +103 -0
  18. package/src/dialog.d.ts +44 -0
  19. package/src/dialog.js +95 -30
  20. package/src/icons.d.ts +4 -0
  21. package/src/icons.js +43 -0
  22. package/src/kit.d.ts +217 -0
  23. package/src/kit.js +299 -0
  24. package/src/marks/den.svg +6 -0
  25. package/src/report-shot.d.ts +47 -0
  26. package/src/report-shot.js +437 -0
  27. package/src/report.css +387 -0
  28. package/src/report.d.ts +61 -0
  29. package/src/report.js +909 -0
  30. package/src/shell-client.d.ts +149 -0
  31. package/src/shell-client.js +820 -0
  32. package/src/shell-html.d.ts +305 -0
  33. package/src/shell-html.js +903 -0
  34. package/src/shell.css +1010 -0
  35. package/src/strings.d.ts +18 -0
  36. package/src/strings.js +565 -0
  37. package/src/time.d.ts +18 -0
  38. package/src/time.js +14 -2
  39. package/src/tokens.css +81 -67
  40. package/src/update-pill.d.ts +17 -0
  41. package/src/version.d.ts +7 -0
  42. package/src/version.js +31 -0
  43. package/src/whatsnew.css +235 -0
  44. package/src/whatsnew.d.ts +36 -0
  45. package/src/whatsnew.js +411 -0
package/README.md CHANGED
@@ -56,6 +56,519 @@ own copy, so a page never mixes two versions.
56
56
  `--text`, `--muted`, `--border-strong`, `--accent`, `--accent-text` and
57
57
  `--upd-shadow`.
58
58
 
59
+ ## The shell and its parts (0.6.0)
60
+
61
+ The global shell is the kit's: the top bar, the left rail with its pins,
62
+ collapse toggle and ☰ drawer, the version chip, What's new, the Report
63
+ button and form, and the update pill. A product gives its own parts as
64
+ data and HTML slots; it keeps no copy of the kit's markup, CSS or code.
65
+
66
+ - `src/shell-html.js` (export `./shell-html`): the markup, pure (no DOM),
67
+ so it runs in Node and in the page. A product renders its frame on the
68
+ server and in the browser with the same function.
69
+
70
+ import { shellHtml } from "@monster-orange/den-ui/shell-html";
71
+ const html = shellHtml({
72
+ product: { name: "Acme", version: "2.0.0" }, // title?, href?
73
+ nav: [{ id: "home", label: "Home", href: "/", group: "work",
74
+ icon: "home", current: true }], // badge, pin, lead, …
75
+ groups: [{ id: "work", label: "Work" }], // from? tags a group
76
+ foot: [], // under the spacer
77
+ lang: "en", // en, es or ja
78
+ slots: { start, end, bell, account }, // the product's HTML
79
+ collapsed: false,
80
+ report: true, // false: reports off
81
+ });
82
+
83
+ Also `topBarHtml`, `railHtml`, `navItemHtml`, `versionChipHtml`,
84
+ `reportButtonHtml`, `icon(name)` (`src/icons.js`) and `esc`.
85
+
86
+ - **Slots.** The top bar reads: ☰, the brand, `start` (a search, a scope
87
+ menu), then the right group: `end` (status chips), Report, `bell`, the
88
+ version chip, `account`. Report · bell · account keep their place
89
+ whatever a product puts in its slots.
90
+ - `src/shell-client.js` (export `./shell-client`): hydrates what
91
+ shell-html drew. `hydrateShell(root, { lang, onCollapse, onUnpin,
92
+ inert, menuOpen })` binds the rail's keys (↑ ↓ Home End, Delete unpins),
93
+ the collapse toggle and the ☰ drawer (a modal below 720px: the page
94
+ inert, Escape or the scrim closes it), and returns `{ rove, paint(html,
95
+ force), setCollapsed, unpin, openDrawer, closeDrawer, drawerOpen,
96
+ syncPinToggles }`.
97
+ - `src/shell.css`, `src/whatsnew.css`, `src/report.css`: the look. Link
98
+ them after `tokens.css`.
99
+ - `src/version.js` (the chip's label and its unread dot), `src/whatsnew.js`
100
+ (the release notes pop-up: newest first, earlier versions on request,
101
+ copy as Markdown or for chat), `src/report.js` and `src/report-shot.js`
102
+ (the Report form, its screenshot and masks).
103
+
104
+ ### The client entry: `src/kit.js` (`window.DenUI`)
105
+
106
+ import DenUI from "/kit/kit.js"; // also sets window.DenUI
107
+ DenUI.configure({ lang, product: { name }, adapter, report, whatsNew });
108
+ DenUI.mount(root, model) // shellHtml(model) into root, hydrated
109
+ DenUI.hydrate(root, opts) // a shell rendered on the server
110
+ DenUI.version.set("v2.0.0"); DenUI.version.unread(true);
111
+ DenUI.whatsNew.open(); // .close(), .load()
112
+ DenUI.update.set({ version }); // the update pill; .hide()
113
+ DenUI.report.open({ prefill }); // ⌘⇧F and any [data-den-report] too
114
+ DenUI.busy.run(action, run, opts) // the working pop-up (busy.js)
115
+
116
+ ### The adapter
117
+
118
+ The kit names no URL. Every call to the product goes through the adapter;
119
+ a missing call turns its feature off rather than failing.
120
+
121
+ | call | used by | returns |
122
+ | --------------------- | -------------------------------- | --------------------------------------------- |
123
+ | `changelog()` | What's new | `[{ version, date, sections }]`, newest first |
124
+ | `applyUpdate()` | the update pill's Reload | anything; the page reloads after |
125
+ | `fileReport(payload)` | Report | `{ number, url }` or `{ error }` |
126
+ | `request(id)` | the working pop-up's Check again | `{ state, result?, error? }` |
127
+
128
+ With `fileReport`, Report ends on "Filed as #N" and a link to it. With no
129
+ way to send, Report offers "Copy report" only: the report as text, to
130
+ paste where the team tracks issues. A product with more (a preview, a
131
+ sign-in flow, drafts) gives `info`, `diagnostics`, `preview`, `send`,
132
+ `githubSend`, `githubPoll` and `saveDraft`; see the top of `report.js`.
133
+
134
+ ### Strings
135
+
136
+ `src/strings.js` (export `./strings`) exports `en`, `es` and `ja`: every
137
+ word the kit shows, each key starting `kit.`, the same keys and
138
+ `{placeholders}` in all three (a test checks). `{product}` is the name
139
+ given to `configure`. A product adds its own words, or its own versions
140
+ of the kit's, with `DenUI.strings(lang, table)`; an unknown language falls
141
+ back to English.
142
+
143
+ ### Content Security Policy
144
+
145
+ The shell, the version chip, What's new, the update pill, Report, the
146
+ working pop-up and the dialogs work under `script-src 'self'; style-src 'self'`: no
147
+ inline `style` attributes, no inline scripts, handlers or `<style>`, no
148
+ `eval`. They set custom properties through the CSSOM
149
+ (`style.setProperty`), which the policy allows. A browser test loads a
150
+ kit page under that policy and fails on any violation. Since 0.6.2 the
151
+ ask-and-tell dialogs (dialog.js) work under it too, and the test covers
152
+ them.
153
+
154
+ ### The parity gate: `den-ui-parity`
155
+
156
+ npx den-ui-parity [--root .] [--src src]... [--json]
157
+
158
+ It scans a product's source for its own copy of a kit component (markup
159
+ that draws the kit's elements, CSS for them, a function with a kit
160
+ builder's name, a file named as or identical to a kit file) and exits 1
161
+ when it finds one. Den runs it in CI (`npm run gate:den-ui`).
162
+
163
+ A product that keeps a copy on purpose names it in `DIVERGE.md` at its
164
+ repository root, one row per component, with a reason:
165
+
166
+ | component | reason |
167
+ |---|---|
168
+ | report | our reports go to a ticket desk, not an issue tracker |
169
+
170
+ (or a list: `- report: our reports go to …`). The components are `shell`,
171
+ `version`, `whatsnew`, `update`, `report` and `working`, and since 0.7.0
172
+ `scope`, `search`, `bell`, `appearance` and `account`. A row without a
173
+ reason does not count. With no DIVERGE.md, every copy fails.
174
+
175
+ ### Nav inventory
176
+
177
+ `inventory/nav-inventory.js` (export `./inventory`, types beside it): one
178
+ spec every product runs, so two products' top bars and rails never
179
+ quietly differ. It lists the global nav element by element and compares
180
+ it with the kit's reference: Den's nav as signed off, in
181
+ `inventory/reference/den-<browser>-<width>.json` (export
182
+ `./inventory/reference/*`), for `chromium` and `webkit` at `1280` and
183
+ `390`.
184
+
185
+ One browser build and one theme. The references were taken on
186
+ Playwright's image `NAV_BROWSER_IMAGE`, its linux/amd64 build (the arm64
187
+ build ships another Chromium; on an arm64 machine add
188
+ `--platform linux/amd64`):
189
+
190
+ mcr.microsoft.com/playwright:v1.61.1-noble@sha256:cf0daee9b994042e011bc29f20cdff1a9f682a039b43fcd738f7d8a9d3bcd9d6
191
+
192
+ in the theme `NAV_THEME`, Den's default theme "den" 2.0.1 (the kit's
193
+ default tokens). A host must run the inventory on that image, in that
194
+ theme, with the shipped references, so both products are measured in one
195
+ browser build and one look. Start the image's run-server and connect both
196
+ browsers to it through `DEN_PW_WS`:
197
+
198
+ docker run -d --init --platform linux/amd64 -p 127.0.0.1:3921:3921 \
199
+ mcr.microsoft.com/playwright:v1.61.1-noble@sha256:cf0daee9b994042e011bc29f20cdff1a9f682a039b43fcd738f7d8a9d3bcd9d6 \
200
+ npx -y playwright@1.61.1 run-server --port 3921 --host 0.0.0.0
201
+ DEN_PW_WS=ws://localhost:3921/
202
+
203
+ import { chromium } from "playwright"; // 1.61.1, as the image
204
+ import { collectNav, compareNav, formatNavDiffs, NAV_BROWSER_IMAGE,
205
+ NAV_THEME } from "@monster-orange/den-ui/inventory";
206
+ import { readFileSync } from "node:fs";
207
+ import { createRequire } from "node:module";
208
+
209
+ // exposeNetwork: the browser in the container reaches the host's own
210
+ // server on this machine's loopback through the connection.
211
+ const browser = await chromium.connect(process.env.DEN_PW_WS,
212
+ { exposeNetwork: "<loopback>" });
213
+ const page = await browser.newPage({ viewport: { width: 1280, height: 900 },
214
+ colorScheme: "light" });
215
+ await page.goto("http://localhost:<port>/"); // the host's own page
216
+ const ref = JSON.parse(readFileSync(createRequire(import.meta.url)
217
+ .resolve("@monster-orange/den-ui/inventory/reference/den-chromium-1280.json"),
218
+ "utf-8"));
219
+ const diffs = compareNav(
220
+ await collectNav(page, { image: NAV_BROWSER_IMAGE, theme: NAV_THEME }),
221
+ ref,
222
+ { hostSlots: ["#my-status"] }, // what the host fills itself
223
+ );
224
+ expect(formatNavDiffs(diffs)).toBe(""); // one line per difference
225
+
226
+ Pass `theme` as the theme the page really draws in (Den reads it from
227
+ `/api/themes`). On another browser build (a different fingerprint: user
228
+ agent and the measured width of one fixed line in each face the nav
229
+ uses) the one difference is `env`, "reference taken on X, running on Y";
230
+ in another theme it is `theme`. Boxes that can't match are never
231
+ compared.
232
+
233
+ - `collectNav(page, { image, theme })` returns `{ version, viewport,
234
+ env, elements, tokens }`. `env`: `userAgent`, `faces` (the
235
+ fingerprint), `image`, `theme`. `elements`: `header.den-top`,
236
+ `nav.den-rail` and every element under them with a box, in DOM order
237
+ (hidden ones and an `<svg>`'s shapes left out). Each has `key`,
238
+ `parent`, `slot` (`top`, `rail`, or `foot`: after the rail's spacer),
239
+ `role`, `tag`, `name` (aria-label, aria-labelledby, alt, its text for a
240
+ control or a leaf, title), `classes`, `box` `{ x, y, w, h }` and
241
+ `style`: display, visibility, height, the four corner radii,
242
+ background-color, each side's border width, style and colour,
243
+ font-size, -weight, -family, -style, line-height, letter-spacing,
244
+ text-transform, padding, row-gap, column-gap, color, opacity,
245
+ box-shadow. A key is `#id`, `[data-nav="x"]`, or the parent's key `>`
246
+ tag.class (`[n]` among like siblings): `#den-search > kbd`.
247
+ - `compareNav(actual, reference, { hostSlots, themeTokens, tolerance })`
248
+ returns `[{ key, slot, property, reference, actual }]`, empty when the
249
+ navs match. It fails on an element missing, extra or out of order
250
+ (`property` `element`, `order`); a role, tag, name or class list that
251
+ differs; a box edge moved more than `tolerance` px (default 2:
252
+ `box.left`, …); any computed style that differs (`style.font-weight`),
253
+ colours and fonts included.
254
+ - `hostSlots`: keys (`#den-status`) or one class (`.den-scope`) whose
255
+ element and everything under it are the host's own: not compared, on
256
+ either side. A host slot wider or narrower than the reference (or on
257
+ one side only) may move or stretch its neighbours sideways by exactly
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`.
273
+ - `themeTokens`: empty by default, and never set on a parity run: both
274
+ products run in `NAV_THEME`, so any colour or font that differs is a
275
+ real gap. It is only for a run that switches themes on purpose. What a
276
+ theme may change, and so what the list may name: the colour tokens
277
+ (`--bg`, `--surface`, `--raised`, `--sunken`, `--text`, `--muted`,
278
+ `--faint`, `--border`, `--border-strong`, `--accent`, and the rest of
279
+ tokens.css's colours) and the font tokens (`--sans`, `--mono`,
280
+ `--display`). A colour or font-family listed may differ when, on both
281
+ sides, it comes from that token. How a value's token is found: every
282
+ custom property declared on `:root` or `html` (in any sheet the page
283
+ can read, inside `@media` and `@layer` too) is read from `<html>`'s
284
+ computed style; a colour is set on a probe element's `color`, a family
285
+ list on its `font-family`, and read back, so it is in the form computed
286
+ values take. `snapshot.tokens` maps each colour and family seen to the
287
+ tokens that compute to it.
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.
307
+
308
+ Den runs it in `tests/unit/den-ui/nav-inventory.browser.test.ts` (CI's
309
+ `den-ui-nav` job starts the image) with red cases that must fail: the
310
+ search field 3 px over, its corners, the bell gone, two elements
311
+ swapped, a font weight, the search's ⌘K and icon gone, a theme token's
312
+ colour, a font-family; a host slot's new contents must pass.
313
+ `nav-inventory.test.ts` checks the comparer with no browser. To take the
314
+ reference again, on purpose only: `DEN_UI_NAV_CAPTURE=1` with the
315
+ browser test, on the image (Den's real server on the demo distribution,
316
+ `/settings`).
317
+
318
+ ## The working pop-up and types (0.6.1)
319
+
320
+ - `src/busy.js`, `src/busy-words.js` and `src/busy.css` (exports `./busy`,
321
+ `./busy-words`, `./busy.css`): the working pop-up. Its look is
322
+ `busy.css`, linked, never injected. Link it in the page's `<head>`;
323
+ without that, busy.js links it from beside itself the first time it
324
+ opens.
325
+
326
+ busyAction("save", async (headers, progress) => {
327
+ progress("Copying files"); // a line under the title
328
+ const r = await fetch("/api/save", { method: "POST", headers });
329
+ if (!r.ok) throw { status: r.status };
330
+ return r.json();
331
+ }, {
332
+ // A failure trying again won't fix: its link in place of Try again.
333
+ next: (err) => (err.status === 403
334
+ ? { label: "Sign in", href: "/sign-in" } : null),
335
+ });
336
+
337
+ `next` is `{ label, href }` or a function of the failure that returns
338
+ one (or null for Try again). The pop-up then says that trying again
339
+ won't help, and the link is its primary button. `progress(text)` lines
340
+ show in order while it works. `quietFail`, `inlineError`, `skipDone`
341
+ and `extra` are as before, and a success still closes at once with a
342
+ toast.
343
+
344
+ - Types: every `src/*.js` has a `.d.ts` beside it; the package's `types`
345
+ is `src/kit.d.ts`. A test compiles a consumer against them with
346
+ `--strict`.
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
+
498
+ ## 0.6.6
499
+
500
+ - A time drawn by `upgradeTimes` reads in the language of the part of
501
+ the page it sits in: the nearest `[lang]` around the `<time>` first,
502
+ then `<html lang>`, then the browser's. Text and title both. A row
503
+ still in English on a translated page no longer reads "connected 今".
504
+ - No new files: hosts serving a fixed list change nothing.
505
+
506
+ ## 0.6.5
507
+
508
+ - Focus goes back to what opened a pop-up when it closes, in Safari too.
509
+ Safari doesn't focus a button on a click, so the browser's own dialog
510
+ restore went to the page's body. Report, `askConfirm`, `askText`,
511
+ `tell` and What's new now remember their opener and focus it again on
512
+ every way out (Esc, Discard, Cancel, Close, after a send), without
513
+ scrolling, when it is still on the page.
514
+ - The opener is `opts.opener` when given (`report.open({ opener })`,
515
+ `askConfirm({ opener })`), else the focused element, else the control
516
+ just pressed. A kit Report button is its own opener.
517
+ - The shared helper is in `dialog.js` (`openerOf`, `focusBack`), a file
518
+ hosts already serve: no new kit file. The working pop-up already
519
+ focuses its own `button` again; it is unchanged.
520
+
521
+ ## 0.6.4
522
+
523
+ - shell.css: the top bar is its own layer from the start
524
+ (`will-change: transform`). The update pill's glass (`blur(3px)
525
+ saturate(1.4)`, unchanged) made Chromium draw the page's text grayscale
526
+ while the pill showed, so the bar's mark and name changed pixels when
527
+ the pill appeared. Now the bar is the same with the pill shown or
528
+ hidden. Its text is drawn as on any layer of its own (grayscale), as a
529
+ sticky bar's always was.
530
+ - Inside the bar, a `position: fixed` element is placed against the bar,
531
+ not the window: put pop-ups, palettes and toasts on `<body>`. A slot's
532
+ `position: absolute` menu still drops below the bar (the bar never
533
+ clips).
534
+
535
+ ## 0.6.3
536
+
537
+ - Report: ⌘↵ (Ctrl+Enter) is the form's primary button on Write and on
538
+ Include, as in every pop-up: Write → Include → Review. Review still
539
+ sends nothing until the person clicks.
540
+ - shell.css: the page's main (`#den-content`) takes what is left of the
541
+ window under the top bar (`flex: 1 1 auto`), so a short page's last row
542
+ can reach the window's bottom at every width.
543
+ - shell.css: the top bar is pinned. It is `position: fixed` at the top,
544
+ as the rail under it is, and the body has `padding-top` of the bar's
545
+ height (and `box-sizing: border-box`, so its 100vh minimum still holds).
546
+ On a page whose body scrolls, or whose `html, body` are `height: 100%`,
547
+ the bar stays put and no gap opens above the rail.
548
+ - `reportButtonHtml({ label, prefill })` (and `DenUI.report.button`): a
549
+ row's own Report button. `label` replaces the word and names the button;
550
+ `prefill` (`{ kind?, title?, description? }`) is kept on it as JSON
551
+ (`data-den-report-prefill`), and the kit's click opens Report filled
552
+ from it. `reportPrefillOf(el)` reads it back. With neither, the button
553
+ is as before.
554
+
555
+ ## 0.6.2
556
+
557
+ - `src/dialog.css` (export `./dialog.css`): the ask-and-tell dialogs'
558
+ look, linked, never injected. Link it in the page's `<head>`. Without
559
+ that, dialog.js links it from `configureDialog({ css })`, else from
560
+ beside another kit stylesheet on the page.
561
+ - Report: `fileReport(payload)` gets `payload.shot`, the masked
562
+ screenshot as a PNG data URL, or `null` when "Don't include" is picked.
563
+ - `busyAction`'s `next` takes `{ label }` with no `href`: the failure
564
+ says those words in place of Try again, and Close is the primary.
565
+ - `shellHtml`'s `product.mark`: `{ text?, svg?, label }`, drawn in
566
+ `.den-mark`. `text` is escaped. `svg` is the product's own markup, with
567
+ the same trust as the icons. `label` names it (role="img"). With no
568
+ mark, the slot is empty as before.
569
+ - `den-ui-parity` works through npx and `node_modules/.bin`: it compares
570
+ real paths to know it was run as a command.
571
+
59
572
  ## Themes
60
573
 
61
574
  A theme may override every colour in both modes, the shadow, the bar,
@@ -67,7 +580,8 @@ spacing, motion or layers, so layouts stay the same.
67
580
  - Components use tokens only: a test fails on a raw colour outside
68
581
  `tokens.css`.
69
582
  - Every text and background pair passes WCAG AA in both modes (4.5:1 for
70
- text, 3:1 for marks); status pills are checked on their own tint.
583
+ text, 3:1 for marks); status pills are checked on their own tint, and
584
+ the remote colour on its 16% disc.
71
585
  - The fonts stay within 120 KB.
72
586
 
73
587
  ## Licence