@monster-orange/den-ui 0.0.0-stage → 0.6.6

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 (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +408 -2
  3. package/bin/den-ui-parity.mjs +365 -0
  4. package/inventory/nav-inventory.d.ts +89 -0
  5. package/inventory/nav-inventory.js +590 -0
  6. package/inventory/reference/den-chromium-1280.json +5137 -0
  7. package/inventory/reference/den-chromium-390.json +3653 -0
  8. package/inventory/reference/den-webkit-1280.json +5137 -0
  9. package/inventory/reference/den-webkit-390.json +3653 -0
  10. package/package.json +51 -4
  11. package/src/base.css +80 -0
  12. package/src/busy-words.d.ts +2 -0
  13. package/src/busy-words.js +71 -0
  14. package/src/busy.css +155 -0
  15. package/src/busy.d.ts +80 -0
  16. package/src/busy.js +662 -0
  17. package/src/dialog.css +103 -0
  18. package/src/dialog.d.ts +44 -0
  19. package/src/dialog.js +282 -0
  20. package/src/fonts/OFL.txt +97 -0
  21. package/src/fonts/rubik-latin-400-normal.woff2 +0 -0
  22. package/src/fonts/rubik-latin-500-normal.woff2 +0 -0
  23. package/src/fonts/rubik-latin-ext-400-normal.woff2 +0 -0
  24. package/src/fonts/rubik-latin-ext-500-normal.woff2 +0 -0
  25. package/src/fonts/space-mono-latin-400-normal.woff2 +0 -0
  26. package/src/fonts/space-mono-latin-ext-400-normal.woff2 +0 -0
  27. package/src/fonts.css +71 -0
  28. package/src/icons.d.ts +4 -0
  29. package/src/icons.js +43 -0
  30. package/src/kit.d.ts +146 -0
  31. package/src/kit.js +224 -0
  32. package/src/report-shot.d.ts +47 -0
  33. package/src/report-shot.js +255 -0
  34. package/src/report.css +387 -0
  35. package/src/report.d.ts +61 -0
  36. package/src/report.js +909 -0
  37. package/src/shell-client.d.ts +31 -0
  38. package/src/shell-client.js +240 -0
  39. package/src/shell-html.d.ts +91 -0
  40. package/src/shell-html.js +289 -0
  41. package/src/shell.css +558 -0
  42. package/src/strings.d.ts +18 -0
  43. package/src/strings.js +514 -0
  44. package/src/time.d.ts +18 -0
  45. package/src/time.js +254 -0
  46. package/src/tokens.css +158 -0
  47. package/src/update-pill.css +32 -0
  48. package/src/update-pill.d.ts +17 -0
  49. package/src/update-pill.js +95 -0
  50. package/src/version.d.ts +7 -0
  51. package/src/version.js +31 -0
  52. package/src/whatsnew.css +235 -0
  53. package/src/whatsnew.d.ts +36 -0
  54. package/src/whatsnew.js +411 -0
@@ -0,0 +1,365 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * den-ui-parity: fails when a product keeps its own copy of a kit
4
+ * component, instead of the kit's.
5
+ *
6
+ * den-ui-parity [--root <dir>] [--src <dir>]... [--json]
7
+ *
8
+ * --root the product's repository (default: the working directory); its
9
+ * DIVERGE.md is read from there.
10
+ * --src a folder of UI source to scan, relative to --root (repeatable;
11
+ * default: src). node_modules, dist, build, .git and the kit's
12
+ * own package (packages/den-ui) are never scanned.
13
+ *
14
+ * What counts as a copy (per component, see COMPONENTS below):
15
+ * - markup: a string that draws the kit's element (class="den-top", …);
16
+ * - CSS: a rule whose selector starts with the kit's class or id;
17
+ * - code: a function with the name of the kit's own builder;
18
+ * - files: a file named as a kit file, or with the same bytes as one.
19
+ * Reading the kit's elements (querySelector(".den-rail"), say) is not a
20
+ * copy: only drawing or styling them is.
21
+ *
22
+ * DIVERGE.md at the root lets a product keep a copy on purpose: a
23
+ * markdown table or list naming the component and a reason,
24
+ *
25
+ * | component | reason |
26
+ * |---|---|
27
+ * | report | our reports go to a ticket desk, not an issue tracker |
28
+ *
29
+ * - report: our reports go to a ticket desk, not an issue tracker
30
+ *
31
+ * A row with an empty reason does not count. Exit 0: no copies (or each
32
+ * one diverges by name); 1: copies found; 2: bad arguments.
33
+ */
34
+ import { createHash } from "node:crypto";
35
+ import * as fs from "node:fs";
36
+ import * as path from "node:path";
37
+ import { fileURLToPath } from "node:url";
38
+
39
+ const KIT_SRC = path.join(
40
+ path.dirname(fileURLToPath(import.meta.url)),
41
+ "..",
42
+ "src",
43
+ );
44
+
45
+ /** Markup that draws an element with this class (an attribute or className). */
46
+ const cls = (name) =>
47
+ new RegExp(
48
+ `(class(Name)?\\s*[=:]\\s*\\\\?["'\`]|classList\\.add\\(\\s*["'])[^"'\`]*\\b${name}(?![\\w-])`,
49
+ );
50
+ /** Markup that draws an element with this id. */
51
+ const id = (name) =>
52
+ new RegExp(`\\bid\\s*[=:]\\s*\\\\?["'\`]${name}(?![\\w-])`);
53
+
54
+ /** Each component: what drawing, styling or building it looks like. */
55
+ export const COMPONENTS = {
56
+ shell: {
57
+ label: "global shell (top bar, left rail, pins, collapse, ☰ drawer)",
58
+ markup: [
59
+ cls("den-top"),
60
+ cls("den-rail"),
61
+ cls("den-rail-box"),
62
+ cls("den-rail-group"),
63
+ cls("den-ni"),
64
+ cls("den-gh"),
65
+ cls("den-skip"),
66
+ cls("den-brand"),
67
+ cls("den-menu-btn"),
68
+ cls("den-collapse-btn"),
69
+ cls("den-pin-row"),
70
+ id("den-rail"),
71
+ ],
72
+ css: [
73
+ "den-top",
74
+ "den-rail",
75
+ "den-rail-box",
76
+ "den-rail-group",
77
+ "den-ni",
78
+ "den-gh",
79
+ "den-skip",
80
+ "den-brand",
81
+ "den-menu-btn",
82
+ "den-collapse-btn",
83
+ "den-pin-row",
84
+ "den-scrim",
85
+ // Not here: den-has-shell, den-rail-collapsed and den-rail-open are
86
+ // the body's state classes, for a page to lay its own content out by.
87
+ ],
88
+ code: [
89
+ "shellHtml",
90
+ "topBarHtml",
91
+ "railHtml",
92
+ "railGroupHtml",
93
+ "navItemHtml",
94
+ "hydrateShell",
95
+ "applyCollapsed",
96
+ "unpinFromRail",
97
+ "syncPinToggles",
98
+ ],
99
+ files: ["shell-html.js", "shell-client.js", "shell.css", "icons.js"],
100
+ },
101
+ version: {
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"],
106
+ files: ["version.js", "version-label.js"],
107
+ },
108
+ whatsnew: {
109
+ label: "What's new (release notes pop-up)",
110
+ markup: [id("cl-overlay"), cls("cl-overlay"), cls("cl-box")],
111
+ css: [
112
+ "cl-overlay",
113
+ "cl-box",
114
+ "cl-hdr",
115
+ "cl-body",
116
+ "cl-footer",
117
+ "cl-got-it",
118
+ ],
119
+ code: ["changelogView", "whatsNewHtml"],
120
+ files: ["whatsnew.js", "whatsnew.css", "changelog-view.js"],
121
+ },
122
+ update: {
123
+ label: "update pill",
124
+ markup: [cls("den-upd"), cls("upd-pill")],
125
+ css: ["den-upd", "upd-pill"],
126
+ code: ["showUpdate"],
127
+ files: ["update-pill.js", "update-pill.css"],
128
+ },
129
+ report: {
130
+ label: "Report button and form",
131
+ // The form's own dialog (class exactly "fb-dlg"); a product's other
132
+ // dialog may wear the class for its look ("fb-dlg fb-my").
133
+ markup: [cls("den-rb"), /class(Name)?\s*[=:]\s*\\?["'`]fb-dlg["'`\\]/],
134
+ css: ["den-rb", "den-rb-top", "fb-dlg", "fb-b", "fb-btns"],
135
+ code: ["reportButtonHtml", "openReportForm", "clientSections"],
136
+ files: ["report.js", "report.css", "report-shot.js", "report-dialog.js"],
137
+ },
138
+ working: {
139
+ label: "working pop-up",
140
+ markup: [cls("bz-dlg")],
141
+ css: ["bz-dlg"],
142
+ code: ["configureBusy", "registerActions"],
143
+ files: ["busy.js", "busy-words.js", "busy.css"],
144
+ },
145
+ };
146
+
147
+ const SCAN_EXT = /\.(m?[jt]sx?|css|html?)$/;
148
+ const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
149
+
150
+ function args(argv) {
151
+ const o = { root: process.cwd(), src: [], json: false };
152
+ for (let i = 0; i < argv.length; i++) {
153
+ const a = argv[i];
154
+ if (a === "--root") o.root = argv[++i];
155
+ else if (a === "--src") o.src.push(argv[++i]);
156
+ else if (a === "--json") o.json = true;
157
+ else if (a === "--help" || a === "-h") o.help = true;
158
+ else throw new Error(`unknown argument: ${a}`);
159
+ if (o.root === undefined || o.src.includes(undefined))
160
+ throw new Error(`${a} needs a value`);
161
+ }
162
+ if (!o.src.length) o.src = ["src"];
163
+ return o;
164
+ }
165
+
166
+ function* walk(dir, kitDir) {
167
+ let ents = [];
168
+ try {
169
+ ents = fs.readdirSync(dir, { withFileTypes: true });
170
+ } catch {
171
+ return;
172
+ }
173
+ for (const e of ents) {
174
+ const p = path.join(dir, e.name);
175
+ if (e.isDirectory()) {
176
+ if (SKIP_DIRS.has(e.name)) continue;
177
+ if (path.resolve(p) === kitDir) continue;
178
+ yield* walk(p, kitDir);
179
+ } else if (e.isFile()) yield p;
180
+ }
181
+ }
182
+
183
+ const sha = (buf) => createHash("sha256").update(buf).digest("hex");
184
+ const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
185
+
186
+ /**
187
+ * A CSS rule for the kit's element itself: the class (or id) is the
188
+ * selector's subject, alone or with a state (.den-ni:hover,
189
+ * .den-ni[aria-current], body.den-has-shell). A product styling what it
190
+ * puts inside the kit's element (.den-top kbd) or its own element that
191
+ * carries a kit class beside its own (.den-scrim.den-svp-scrim) is not a
192
+ * copy.
193
+ */
194
+ function cssRule(name) {
195
+ return new RegExp(
196
+ `(^|[}\\s"'\`,;>+~])([a-z]+)?[.#]${reEsc(name)}((:{1,2}[\\w-]+(\\([^)]*\\))?)|\\[[^\\]]*\\])*\\s*[,{]`,
197
+ "m",
198
+ );
199
+ }
200
+ function codeDef(name) {
201
+ return new RegExp(
202
+ `(function\\s+${name}\\s*\\(|(const|let|var)\\s+${name}\\s*=\\s*(async\\s*)?(function|\\())`,
203
+ );
204
+ }
205
+
206
+ /** DIVERGE.md: component → reason (rows with a reason only). */
207
+ export function readDiverge(root) {
208
+ const file = path.join(root, "DIVERGE.md");
209
+ const out = {};
210
+ if (!fs.existsSync(file)) return out;
211
+ for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
212
+ let m = /^\s*\|\s*([\w-]+)\s*\|\s*(.*?)\s*\|\s*$/.exec(line);
213
+ if (!m) m = /^\s*[-*]\s*`?([\w-]+)`?\s*[:|]\s*(.+?)\s*$/.exec(line);
214
+ if (!m) continue;
215
+ const [, comp, reason] = m;
216
+ if (!COMPONENTS[comp]) continue;
217
+ if (!reason || /^-+$/.test(reason) || /^reason$/i.test(reason)) continue;
218
+ out[comp] = reason;
219
+ }
220
+ return out;
221
+ }
222
+
223
+ /** Every copy in the product's source: [{ component, file, line, what }]. */
224
+ export function scan(root, srcDirs) {
225
+ const kitDir = path.resolve(KIT_SRC, "..");
226
+ const kitFiles = new Map();
227
+ for (const f of walk(KIT_SRC, null)) {
228
+ const rel = path.relative(KIT_SRC, f);
229
+ if (!SCAN_EXT.test(f)) continue;
230
+ kitFiles.set(sha(fs.readFileSync(f)), rel);
231
+ }
232
+ const found = [];
233
+ for (const src of srcDirs) {
234
+ const dir = path.resolve(root, src);
235
+ for (const file of walk(dir, kitDir)) {
236
+ if (!SCAN_EXT.test(file)) continue;
237
+ const rel = path.relative(root, file);
238
+ const buf = fs.readFileSync(file);
239
+ const text = buf.toString("utf-8");
240
+ const base = path.basename(file);
241
+ const copyOf = kitFiles.get(sha(buf));
242
+ for (const [comp, c] of Object.entries(COMPONENTS)) {
243
+ if (
244
+ c.files.includes(base) ||
245
+ (copyOf && c.files.includes(path.basename(copyOf)))
246
+ )
247
+ found.push({
248
+ component: comp,
249
+ file: rel,
250
+ line: 1,
251
+ what: copyOf
252
+ ? `a copy of the kit's ${copyOf}`
253
+ : `a file named as the kit's ${base}`,
254
+ });
255
+ const lines = text.split("\n");
256
+ const at = (re) => {
257
+ for (let i = 0; i < lines.length; i++)
258
+ if (re.test(lines[i])) return i + 1;
259
+ return 0;
260
+ };
261
+ for (const re of c.markup) {
262
+ const n = at(re);
263
+ if (n)
264
+ found.push({
265
+ component: comp,
266
+ file: rel,
267
+ line: n,
268
+ what: `draws the kit's markup (${(lines[n - 1] || "").trim().slice(0, 70)})`,
269
+ });
270
+ }
271
+ for (const name of c.css) {
272
+ const re = cssRule(name);
273
+ const n = at(re);
274
+ if (n)
275
+ found.push({
276
+ component: comp,
277
+ file: rel,
278
+ line: n,
279
+ what: `styles .${name}`,
280
+ });
281
+ }
282
+ for (const name of c.code) {
283
+ const n = at(codeDef(name));
284
+ if (n)
285
+ found.push({
286
+ component: comp,
287
+ file: rel,
288
+ line: n,
289
+ what: `defines ${name}()`,
290
+ });
291
+ }
292
+ }
293
+ }
294
+ }
295
+ return found;
296
+ }
297
+
298
+ function main() {
299
+ let o;
300
+ try {
301
+ o = args(process.argv.slice(2));
302
+ } catch (e) {
303
+ console.error(`den-ui-parity: ${e.message}`);
304
+ return 2;
305
+ }
306
+ if (o.help) {
307
+ console.log("den-ui-parity [--root <dir>] [--src <dir>]... [--json]");
308
+ return 0;
309
+ }
310
+ const diverge = readDiverge(o.root);
311
+ const found = scan(o.root, o.src);
312
+ const bad = found.filter((f) => !diverge[f.component]);
313
+ if (o.json) {
314
+ console.log(
315
+ JSON.stringify(
316
+ {
317
+ copies: bad,
318
+ diverged: found.filter((f) => diverge[f.component]),
319
+ diverge,
320
+ },
321
+ null,
322
+ 2,
323
+ ),
324
+ );
325
+ return bad.length ? 1 : 0;
326
+ }
327
+ for (const [comp, why] of Object.entries(diverge))
328
+ console.log(`den-ui-parity: ${comp} diverges (DIVERGE.md): ${why}`);
329
+ if (!bad.length) {
330
+ console.log(
331
+ `den-ui-parity: ok, no copies of the kit's ${Object.keys(COMPONENTS).length} components in ${o.src.join(", ")}`,
332
+ );
333
+ return 0;
334
+ }
335
+ const by = {};
336
+ for (const f of bad) (by[f.component] ??= []).push(f);
337
+ for (const [comp, list] of Object.entries(by)) {
338
+ console.log(
339
+ `\n✗ ${comp}: ${COMPONENTS[comp].label}: ${list.length} cop${list.length === 1 ? "y" : "ies"}`,
340
+ );
341
+ for (const f of list) console.log(` ${f.file}:${f.line} ${f.what}`);
342
+ }
343
+ console.log(
344
+ `\nden-ui-parity: ${bad.length} cop${bad.length === 1 ? "y" : "ies"} of kit components. Use the kit's, or name the component and a reason in DIVERGE.md (| component | reason |).`,
345
+ );
346
+ return 1;
347
+ }
348
+
349
+ /**
350
+ * Run as a command: through npx or node_modules/.bin, argv[1] is a
351
+ * symlink to this file, so both sides are compared as real paths.
352
+ */
353
+ function isMain() {
354
+ if (!process.argv[1]) return false;
355
+ try {
356
+ return (
357
+ fs.realpathSync(path.resolve(process.argv[1])) ===
358
+ fs.realpathSync(fileURLToPath(import.meta.url))
359
+ );
360
+ } catch {
361
+ return false;
362
+ }
363
+ }
364
+
365
+ if (isMain()) process.exitCode = main();
@@ -0,0 +1,89 @@
1
+ /** A Playwright Page, or anything that evaluates a function in a page. */
2
+ export interface NavPage {
3
+ evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg: A): Promise<R>;
4
+ }
5
+ /** Where an element sits: the top bar, the rail, or the rail's foot. */
6
+ export type NavSlot = "top" | "rail" | "foot";
7
+ export interface NavBox {
8
+ x: number;
9
+ y: number;
10
+ w: number;
11
+ h: number;
12
+ }
13
+ export interface NavElement {
14
+ /** "#id", '[data-nav="x"]', or the parent's key " > " tag.class[n]. */
15
+ key: string;
16
+ parent: string | null;
17
+ slot: NavSlot;
18
+ role: string;
19
+ tag: string;
20
+ /** aria-label, else aria-labelledby, else alt, else its text, else title. */
21
+ name: string;
22
+ classes: string[];
23
+ box: NavBox;
24
+ /** Computed styles, by property name (STYLE_PROPS). */
25
+ style: Record<string, string>;
26
+ }
27
+ export interface NavTheme {
28
+ id: string;
29
+ version: string;
30
+ }
31
+ export interface NavEnv {
32
+ userAgent: string;
33
+ /** Each face ("<weight> <size> <family>") → its fixed line's width, px. */
34
+ faces: Record<string, number>;
35
+ /** Where the browser ran (collectNav's `image`), if given. */
36
+ image?: string;
37
+ /** The theme the page drew in (collectNav's `theme`), if given. */
38
+ theme?: NavTheme;
39
+ }
40
+ export interface NavSnapshot {
41
+ version: number;
42
+ viewport: { w: number; h: number };
43
+ /** The browser build: boxes compare only between equal fingerprints. */
44
+ env: NavEnv;
45
+ elements: NavElement[];
46
+ /** Each colour and font-family seen → the :root --tokens that compute to it. */
47
+ tokens: Record<string, string[]>;
48
+ }
49
+ export interface NavCompareOptions {
50
+ /** Keys ("#den-status") or one class (".den-scope"): left out, with all under them. */
51
+ hostSlots?: string[];
52
+ /**
53
+ * Tokens ("--accent", "--sans") whose colour or font-family may differ.
54
+ * Default empty; never for a parity run (both products run in NAV_THEME).
55
+ */
56
+ themeTokens?: string[];
57
+ /** How far a box edge may move, in px (default 2). */
58
+ tolerance?: number;
59
+ }
60
+ export interface NavDiff {
61
+ key: string;
62
+ slot: NavSlot | "";
63
+ /** "env" (another browser build), "theme" (another theme), "element", "order", "slot", "role", "tag", "name", "classes", "box.<edge>", "style.<prop>", "version". */
64
+ property: string;
65
+ reference: string | number;
66
+ actual: string | number;
67
+ }
68
+ export declare const STYLE_PROPS: string[];
69
+ export declare const COLOR_PROPS: string[];
70
+ /** Colours and font-family: what a theme token may stand for. */
71
+ export declare const TOKEN_PROPS: string[];
72
+ export declare const NAV_INVENTORY_VERSION: number;
73
+ /** The pinned Playwright image (version and digest) the nav is measured in. */
74
+ export declare const NAV_BROWSER_IMAGE: string;
75
+ export declare const FINGERPRINT_TEXT: string;
76
+ /** The theme the reference was taken in ("den" 2.0.1): every parity run uses it. */
77
+ export declare const NAV_THEME: NavTheme;
78
+ export declare function collectNav(
79
+ page: NavPage,
80
+ opts?: { image?: string; theme?: NavTheme },
81
+ ): Promise<NavSnapshot>;
82
+ /** The browser build's fingerprint: user agent and the faces' widths. */
83
+ export declare function fingerprint(snap: NavSnapshot): string;
84
+ export declare function compareNav(
85
+ actual: NavSnapshot,
86
+ reference: NavSnapshot,
87
+ opts?: NavCompareOptions,
88
+ ): NavDiff[];
89
+ export declare function formatNavDiffs(diffs: NavDiff[]): string;