diff --git a/docs/VUE-MIGRATION.md b/docs/VUE-MIGRATION.md index 8e1c34d046..aa2909df10 100644 --- a/docs/VUE-MIGRATION.md +++ b/docs/VUE-MIGRATION.md @@ -89,10 +89,16 @@ 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. +outside the kit, and no SFC's script, builds a button, select, field or +Material glyph in script or writes one as markup in a string, apart from +the globe panel's standalone page (`src/tools/globePanel.js`), plain HTML +a host serves with no Vue or kit, whose Expand and Open buttons are +written as markup (`src/ui/kit/viewControls.test.mjs` pins all of it). +The native fields left are the text, number, password and file inputs +and the two text areas (the chat's message box and the scene dialog's +multiline field) the kit has no control for, and the search fields whose +surfaces this document names. The scene dialog's single-line field takes +its type from its caller, which passes text-like types only. `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 0ab62e717f..7ef7d42ba2 100644 --- a/src/ui/kit/viewControls.test.mjs +++ b/src/ui/kit/viewControls.test.mjs @@ -5,8 +5,10 @@ // 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. +// clear button a UiCloseButton. Outside the kit, no module (nor an SFC's +// script) builds a button, select, field or Material glyph in script, or +// writes one as markup in a string, apart from the globe panel's standalone +// page named below. import { test } from 'node:test'; import assert from 'node:assert/strict'; import { readFileSync, readdirSync } from 'node:fs'; @@ -77,15 +79,31 @@ const NATIVE_RANGES = { '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; +// An attribute and its value, read from the tag rather than other values. +const ATTRIBUTE = /([^\s=/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'/>]+)))?/g; +/** + * A tag's `type`: written, bound to a quoted literal (`:type="'checkbox'"`), + * or named in a `v-bind` object; null when it is bound to anything else. + */ function inputType(attrs) { - for (const m of attrs.matchAll(ATTRIBUTE)) - if (m[1] === 'type') return m[2] ?? m[3] ?? m[4] ?? ''; + for (const m of attrs.matchAll(ATTRIBUTE)) { + const name = m[1].toLowerCase(); + const value = m[2] ?? m[3] ?? m[4] ?? ''; + if (name === 'type') return value.toLowerCase(); + if (name === ':type' || name === 'v-bind:type') { + const literal = /^\s*(['`])([^'`]*)\1\s*$/.exec(value); + if (literal) return literal[2].toLowerCase(); + } + if (name === 'v-bind' || name === ':') { + const named = /\btype\s*:\s*(['`])([^'`]*)\1/.exec(value); + if (named) return named[2].toLowerCase(); + } + } return null; } @@ -228,6 +246,25 @@ test('the scans find each hand-written button, glyph, checkbox and range', () => ).length, 0, ); + for (const markup of [ + ``, + ``, + ``, + '', + '', + ]) + assert.equal(nativeInputs(markup, 'checkbox').length, 1, markup); + assert.equal( + nativeInputs('', 'checkbox') + .length, + 0, + ); + assert.equal( + materialGlyphs( + ``, + ).length, + 1, + ); }); test('the views are read: the scan reaches the views and skips the kit', () => { @@ -298,46 +335,105 @@ test('every range in the views is a UiSlider apart from the two named', () => { assert.deepEqual(counts, NATIVE_RANGES); }); -/** Every module under src outside the kit, tests and test support. */ -function scriptFiles(directory = SRC_ROOT) { - const files = []; +// The globe panel's standalone page: plain HTML a host serves, with no Vue +// and no kit, so its two buttons are written as markup. +const STRING_MARKUP_PAGES = new Set(['src/tools/globePanel.js']); + +/** + * Every module under src outside the kit, tests and test support, and every + * SFC's script blocks, as `{ file, source }`. + */ +function scriptSources(directory = SRC_ROOT) { + const found = []; for (const entry of readdirSync(directory, { withFileTypes: true })) { const absolute = path.join(directory, entry.name); + const file = path.relative(REPO_ROOT, absolute).split(path.sep).join('/'); if (entry.isDirectory()) { if ( path.relative(KIT_ROOT, absolute) !== '' && entry.name !== 'testSupport' ) - files.push(...scriptFiles(absolute)); + found.push(...scriptSources(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); + !entry.isFile() || + /\.test\.(?:js|mjs|ts)$|Fixture\.mjs$/.test(entry.name) + ) { + continue; + } else if (/\.(?:js|mjs|ts)$/.test(entry.name)) { + found.push({ file, source: readFileSync(absolute, 'utf8') }); + } else if (entry.name.endsWith('.vue')) { + const blocks = [ + ...readFileSync(absolute, 'utf8').matchAll( + /]*>([\s\S]*?)<\/script\s*>/g, + ), + ]; + found.push({ file, source: blocks.map((m) => m[1]).join('\n') }); + } } - return files.sort(); + return found; } const SCRIPT_CONTROL = - /\bcreateElement(?:NS)?\(\s*(?:[^,)]*,\s*)?['"`](?:button|select|input|textarea)['"`]/; + /\bcreateElement(?:NS)?\(\s*(?:[^,)]*,\s*)?['"`](?:button|select|input|textarea)['"`]/gi; const SCRIPT_GLYPH = - /['"`][^'"`]*\bmaterial-symbols-(?:outlined|rounded|sharp)\b/; + /['"`][^'"`]*\bmaterial-symbols-(?:outlined|rounded|sharp|\$\{)/g; +const STRING_MARKUP = /<(?:button|select|input|textarea)\b/gi; + +/** A source with its comments blanked, line numbers kept. */ +const uncommented = (source) => + source + .replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ' ')) + .replace(/(^|[^:'"`\\])\/\/[^\n]*/g, '$1'); + +/** Each match in a source, as `file:line: text`. */ +function hits(file, source, pattern) { + return [...source.matchAll(pattern)].map((m) => { + const line = source.slice(0, m.index).split('\n').length; + return `${file}:${line}: ${source.split('\n')[line - 1].trim()}`; + }); +} 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 sees = (pattern, text) => [...text.matchAll(pattern)].length > 0; + assert.ok( + sees(SCRIPT_CONTROL, "const b = document.createElement('button');"), + ); + assert.ok(sees(SCRIPT_CONTROL, 'doc.createElement("INPUT")')); + assert.ok( + sees(SCRIPT_CONTROL, "someDocument.createElement(\n 'button',\n);"), + ); + assert.ok(!sees(SCRIPT_CONTROL, "document.createElement('div')")); + assert.ok( + sees(SCRIPT_GLYPH, "span.className = 'material-symbols-outlined';"), + ); + assert.ok(sees(SCRIPT_GLYPH, 'el.className = `material-symbols-${style}`;')); + assert.ok( + !sees(SCRIPT_GLYPH, 'ctx.font = \'24px "Material Symbols Outlined"\';'), + ); + assert.ok(sees(STRING_MARKUP, "host.innerHTML = '';")); + assert.ok( + !sees(STRING_MARKUP, "''".replace('', '')), + ); + + const sources = scriptSources(); + assert.ok( + sources.some(({ file }) => file === 'src/ui/views/panels/ChatPanel.vue'), + ); 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()}`); - }); + for (const { file, source } of sources) { + found.push( + ...hits(file, source, SCRIPT_CONTROL), + ...hits(file, source, SCRIPT_GLYPH), + ); + if (!STRING_MARKUP_PAGES.has(file)) + found.push(...hits(file, uncommented(source), STRING_MARKUP)); } assert.deepEqual(found, []); + for (const file of STRING_MARKUP_PAGES) { + const page = sources.find((s) => s.file === file); + assert.ok( + page && hits(file, page.source, STRING_MARKUP).length, + `${file} no longer writes markup`, + ); + } });