diff --git a/docs/VUE-MIGRATION.md b/docs/VUE-MIGRATION.md index bbe5450990..8e1c34d046 100644 --- a/docs/VUE-MIGRATION.md +++ b/docs/VUE-MIGRATION.md @@ -84,6 +84,15 @@ Home and End), since each of Core's groups keeps its own keyboard policy, and once and asks for a change only when it lands on another option. Every segmented group in Core is a `UiSegmented`; the old `segmentedControl.js` adapter is gone. +No view hand-writes a control the kit has: every button in an SFC outside +the kit is a `UiButton`, `UiCloseButton` or another kit control, every +Material Symbols glyph a `UiIcon`, every checkbox a `UiCheckbox`, every +select a `UiSelect`, and every range a `UiSlider` except the radio +tuner's and the world timeline's, for the reasons given below. No module +outside the kit builds a button, select, field or Material glyph in script +(`src/ui/kit/viewControls.test.mjs` pins all of it). The native fields +left are the text, number, password and file inputs the kit has no +control for, and the search fields whose surfaces this document names. `UiButton` adds `pressedClass`, Core's class on a pressed toggle (most use `active`); its pressed classes toggle through `classList`, so a class other code adds (a voice highlight) survives a press. Every pressed toggle (a diff --git a/src/ui/kit/viewControls.test.mjs b/src/ui/kit/viewControls.test.mjs index 81ff7a7ca4..0ab62e717f 100644 --- a/src/ui/kit/viewControls.test.mjs +++ b/src/ui/kit/viewControls.test.mjs @@ -1,10 +1,12 @@ // The kit's every-control claims in docs/VUE-MIGRATION.md, read from every -// SFC outside the kit: every select is a UiSelect, every pressed toggle a -// UiButton with `pressed` (no template hand-writes `aria-pressed` on any -// element, as an attribute or inside a `v-bind` object, apart from the -// exceptions below), and every close, dismiss and clear button a -// UiCloseButton. -// Controls built in script are not read here. +// SFC outside the kit: every button is a kit button, every select a +// UiSelect, every checkbox a UiCheckbox, every range a UiSlider apart from +// the two named below, and every Material Symbols glyph a UiIcon; every +// pressed toggle is a UiButton with `pressed` (no template hand-writes +// `aria-pressed` on any element, as an attribute or inside a `v-bind` +// object, apart from the exceptions below), and every close, dismiss and +// clear button a UiCloseButton. Outside the kit, no module builds a button, +// select, field or Material glyph in script. import { test } from 'node:test'; import assert from 'node:assert/strict'; import { readFileSync, readdirSync } from 'node:fs'; @@ -69,6 +71,43 @@ const HAND_WRITTEN_CLOSE = new RegExp( const tidy = (markup) => markup.replace(/\s+/g, ' '); +// The two ranges that stay native, by file (docs/VUE-MIGRATION.md says why). +const NATIVE_RANGES = { + 'src/ui/views/panels/RadioTuner.vue': 1, + 'src/ui/views/panels/WorldTimeline.vue': 1, +}; +const RAW_BUTTON = /`, 'gi'); +// A tag's static `type`, read from its attributes rather than their values. +const ATTRIBUTE = /([^\s=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+)))?/g; +function inputType(attrs) { + for (const m of attrs.matchAll(ATTRIBUTE)) + if (m[1] === 'type') return m[2] ?? m[3] ?? m[4] ?? ''; + return null; +} + +/** Hand-written buttons in an SFC's template. */ +const rawButtons = (source) => + [...template(source).matchAll(RAW_BUTTON)].map((m) => m[0]); + +/** Tags in an SFC's template that draw a Material glyph by hand. */ +function materialGlyphs(source) { + const found = []; + for (const m of template(source).matchAll(ANY_TAG)) + if (!/^ + [...template(source).matchAll(INPUT_TAG)] + .filter((m) => inputType(m[1]) === type) + .map((m) => tidy(m[0])); + /** Raw selects in an SFC's template. */ const rawSelects = (source) => [...template(source).matchAll(RAW_SELECT)].map((m) => m[0]); @@ -134,6 +173,63 @@ test('the scans find each hand-written control', () => { assert.equal(handWrittenCloses(markup).length, 0, markup); }); +test('the scans find each hand-written button, glyph, checkbox and range', () => { + for (const markup of [ + '', + '', + ]) + assert.equal(rawButtons(markup).length, 1, markup); + for (const markup of [ + '', + '', + '', + ]) + assert.equal(rawButtons(markup).length, 0, markup); + + for (const markup of [ + '', + '', + '', + '', + ]) + assert.equal(materialGlyphs(markup).length, 1, markup); + for (const markup of [ + '', + '', + '', + ]) + assert.equal(materialGlyphs(markup).length, 0, markup); + + assert.equal( + nativeInputs( + '', + 'checkbox', + ).length, + 1, + ); + assert.equal( + nativeInputs( + '', + 'range', + ).length, + 1, + ); + assert.equal( + nativeInputs( + '', + 'checkbox', + ).length, + 0, + ); + assert.equal( + nativeInputs( + '', + 'checkbox', + ).length, + 0, + ); +}); + test('the views are read: the scan reaches the views and skips the kit', () => { const files = views.map((view) => view.file); assert.ok(files.includes('src/ui/views/panels/ChatPanel.vue')); @@ -169,3 +265,79 @@ test('no view hand-writes a close button; each is a UiCloseButton', () => { found.push(`${file}: ${markup}`); assert.deepEqual(found, []); }); + +test('every button in the views is a kit button', () => { + const found = []; + for (const { file, source } of views) + for (const markup of rawButtons(source)) found.push(`${file}: ${markup}`); + assert.deepEqual(found, []); +}); + +test('every Material Symbols glyph in the views is a UiIcon', () => { + const found = []; + for (const { file, source } of views) + for (const markup of materialGlyphs(source)) + found.push(`${file}: ${markup}`); + assert.deepEqual(found, []); +}); + +test('every checkbox in the views is a UiCheckbox', () => { + const found = []; + for (const { file, source } of views) + for (const markup of nativeInputs(source, 'checkbox')) + found.push(`${file}: ${markup}`); + assert.deepEqual(found, []); +}); + +test('every range in the views is a UiSlider apart from the two named', () => { + const counts = {}; + for (const { file, source } of views) { + const n = nativeInputs(source, 'range').length; + if (n) counts[file] = n; + } + assert.deepEqual(counts, NATIVE_RANGES); +}); + +/** Every module under src outside the kit, tests and test support. */ +function scriptFiles(directory = SRC_ROOT) { + const files = []; + for (const entry of readdirSync(directory, { withFileTypes: true })) { + const absolute = path.join(directory, entry.name); + if (entry.isDirectory()) { + if ( + path.relative(KIT_ROOT, absolute) !== '' && + entry.name !== 'testSupport' + ) + files.push(...scriptFiles(absolute)); + } else if ( + entry.isFile() && + /\.(?:js|mjs|ts)$/.test(entry.name) && + !/\.test\.(?:js|mjs|ts)$/.test(entry.name) && + !/Fixture\.mjs$/.test(entry.name) + ) + files.push(absolute); + } + return files.sort(); +} + +const SCRIPT_CONTROL = + /\bcreateElement(?:NS)?\(\s*(?:[^,)]*,\s*)?['"`](?:button|select|input|textarea)['"`]/; +const SCRIPT_GLYPH = + /['"`][^'"`]*\bmaterial-symbols-(?:outlined|rounded|sharp)\b/; + +test('no module outside the kit builds a control or Material glyph in script', () => { + assert.ok(SCRIPT_CONTROL.test("const b = document.createElement('button');")); + assert.ok(SCRIPT_CONTROL.test('doc.createElement("input")')); + assert.ok(SCRIPT_GLYPH.test("span.className = 'material-symbols-outlined';")); + assert.ok(!SCRIPT_CONTROL.test("document.createElement('div')")); + const found = []; + for (const file of scriptFiles()) { + const relative = path.relative(REPO_ROOT, file).split(path.sep).join('/'); + const source = readFileSync(file, 'utf8'); + source.split('\n').forEach((line, index) => { + if (SCRIPT_CONTROL.test(line) || SCRIPT_GLYPH.test(line)) + found.push(`${relative}:${index + 1}: ${line.trim()}`); + }); + } + assert.deepEqual(found, []); +});