From ec4a5b6afe67b546022f851cc211a7395b9517a9 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Thu, 19 Nov 2026 01:16:46 -0800 Subject: [PATCH] Vue kit: UiDialog for the Data Library and scene sharing dialogs UiDialog is a native its owner opens and closes with open: true opens it with showModal() (on mount, for one mounted open), false closes it, and unmounting closes it. Each change is applied once the content has rendered and then emitted as opened or closed, so the Data Library still focuses its search field on open and returns focus to Browse on close. Escape's cancel is prevented and emitted as dismiss; backdropDismiss makes a click on the dialog itself a dismiss too, as the Data Library's was. When the browser closes the dialog on its own while open is still true, browserClose tells the owner, as the Data Library's close listener did; closing on unmount reports nothing. A DOM without showModal() leaves it closed. Attributes, classes, styles and listeners go to the dialog, and element is exposed. The two dialogs share no declarations, so there are no kit rules. dialogs.test.mjs fails if a view writes a by hand; the panels drawn as role="dialog" are other controls. Co-authored-by: Manjunath Paparaju --- docs/VUE-MIGRATION.md | 21 ++- scripts/format-scope.json | 3 + scripts/package-boundaries.json | 1 + src/ui/kit/UiDialog.test.mjs | 172 ++++++++++++++++++ src/ui/kit/UiDialog.vue | 72 ++++++++ src/ui/kit/dialogs.test.mjs | 66 +++++++ src/ui/sceneSharingView.test.mjs | 3 + .../views/panels/DataLibraryDialog.test.mjs | 24 +++ src/ui/views/panels/DataLibraryDialog.vue | 52 +++--- src/ui/views/panels/SceneDialog.vue | 16 +- 10 files changed, 388 insertions(+), 42 deletions(-) create mode 100644 src/ui/kit/UiDialog.test.mjs create mode 100644 src/ui/kit/UiDialog.vue create mode 100644 src/ui/kit/dialogs.test.mjs diff --git a/docs/VUE-MIGRATION.md b/docs/VUE-MIGRATION.md index 16e659f84a..5d5f0c0b63 100644 --- a/docs/VUE-MIGRATION.md +++ b/docs/VUE-MIGRATION.md @@ -38,7 +38,7 @@ one-panel rule too. Share links continue to record which panels are open. `src/ui/kit/` holds the generic components: `UiRail`, `UiTooltip`, `UiIcon`, `UiButton`, `UiCloseButton`, `UiPanel`, `UiSegmented`, `UiSlider`, `UiChip`, -`UiSelect`, `UiSearchField`, `UiCheckbox`, `UiBadge` and `UiEmpty` so far, with more +`UiSelect`, `UiSearchField`, `UiCheckbox`, `UiDialog`, `UiBadge` and `UiEmpty` so far, with more joining as the controls they serve are converted. One component serves every use of a control, with props for the differences (`UiPanel`'s `sideways`, `glow`, `scroll`), rather than a copy per panel. The components @@ -56,6 +56,7 @@ never copied: | `UiCloseButton` | a close, dismiss or clear button: a bare glyph (× with `glyph="times"`, the Material `close` symbol with `glyph="icon"`) with no padding, border or background of its own and a pointer; the site's feature class sets size, colour, hover and any surface, and `bare` leaves the look off for a skin that keeps the browser's padding | `src/ui/styles/close-button.css` | | `UiSearchField` | a search field: the Material `search` glyph and a search input in a flex row, the input bare (no border or background, free to shrink); the site's feature classes set the frame's size, surface and focus ring and the input's type and outline, and the browser's own cancel button is left to each skin | `src/ui/styles/search-field.css` | | `UiCheckbox` | a checkbox: a label wrapping a native box and its words in a centred flex row; the box keeps each site's size, margin and accent colour, and the site's feature class sets the row's gap, direction and colour | `src/ui/styles/checkbox.css` | +| `UiDialog` | none: a native modal ``; the site's feature class or inline style draws it | — | | `UiChip` | the read-only chip (a pill of uppercase mono text); `selected` takes the accent | `src/ui/styles/chip.css` | | `UiEmpty` | the one-line empty state (dim mono text), its hint on a line below | `src/ui/styles/empty-state.css` | | `UiBadge` | the read-only badge (`gev-status-badge`) | `src/ui/styles/status-badge.css` | @@ -136,6 +137,24 @@ preferences, the Data Library's filter and the welcome card's box are `UiCheckbox`es (`src/ui/kit/checkboxes.test.mjs` pins it); Story Explore's filters are not converted yet. Its kit rule holds the centred row the checkbox-only labels drew, moved rather than copied. +`UiDialog` is a native `` its owner opens and closes with `open`: +true opens it with `showModal()` (on mount, for one mounted open), false +closes it, and unmounting closes it. Each change is applied once the content +has rendered and then emitted as `opened` or `closed`, so the Data Library +focuses its search field on open and returns focus to Browse on close. +Escape's `cancel` is prevented and emitted as `dismiss`, so the owner +decides; `backdropDismiss` makes a click on the dialog itself, outside its +content, a `dismiss` too. When the browser closes the dialog on its own +while `open` is still true (an Escape the page may not cancel), +`browserClose` tells the owner; closing on unmount reports nothing. A DOM +without `showModal()` leaves it closed rather than failing. Attributes, +classes, styles and listeners go to the dialog, and `element` is exposed. +The Data Library and the scene sharing dialogs are `UiDialog`s +(`src/ui/kit/dialogs.test.mjs` pins it); the panels drawn as +`role="dialog"` (key setup, the welcome launcher, the CCTV popup, Story +Explore's filter, the credits) and the render failure's `alertdialog` are +other controls. The two dialogs share no declarations, so it has no kit +rules. `UiSlider` keeps the native range input rather than drawing a `role="slider"` track, so Core's keyboard, form behaviour and styling stay; it takes `v-model`, `min`, `max`, `step` and `disabled`, emits a diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 84f260d81c..76004da995 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1340,6 +1340,9 @@ "src/ui/kit/UiCheckbox.test.mjs", "src/ui/kit/checkboxes.test.mjs", "src/ui/styles/checkbox.css", + "src/ui/kit/UiDialog.vue", + "src/ui/kit/UiDialog.test.mjs", + "src/ui/kit/dialogs.test.mjs", "src/ui/styles/chip.css", "src/ui/styles/empty-state.css", "src/ui/rail/RailChips.vue", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 81c7ada1d4..caf06537ef 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -244,6 +244,7 @@ "src/ui/kit/UiCloseButton.vue", "src/ui/kit/UiSearchField.vue", "src/ui/kit/UiCheckbox.vue", + "src/ui/kit/UiDialog.vue", "src/ui/stores/globeActions.js", "src/ui/views/panels/GlobeActions.vue", "src/ui/views/panels/RenderFailure.vue", diff --git a/src/ui/kit/UiDialog.test.mjs b/src/ui/kit/UiDialog.test.mjs new file mode 100644 index 0000000000..9514706c8a --- /dev/null +++ b/src/ui/kit/UiDialog.test.mjs @@ -0,0 +1,172 @@ +import { after, before, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { installVueDom } from '../../testSupport/vueDom.mjs'; + +let mount; +let nextTick; +let UiDialog; +let uninstall; +before(async () => { + uninstall = installVueDom(); + ({ mount } = await import('@vue/test-utils')); + ({ nextTick } = await import('vue')); + UiDialog = (await import('./UiDialog.vue')).default; +}); +after(() => uninstall()); + +/** + * A dialog that records what it emits, each with whether the dialog was open + * then; its content is a paragraph. One is mounted at a time. + */ +function dialog(props = {}, attrs = {}) { + const events = []; + const record = (name) => () => + events.push( + name, + document.querySelector('dialog').open ? 'shown' : 'hidden', + ); + const wrapper = mount(UiDialog, { + attachTo: document.body, + props: { + ...props, + onDismiss: record('dismiss'), + onBrowserClose: record('browserClose'), + onOpened: record('opened'), + onClosed: record('closed'), + }, + attrs, + slots: { default: '

Words

' }, + }); + return { wrapper, events }; +} + +test('a dialog mounted closed stays closed until open', async () => { + const { wrapper, events } = dialog(); + const element = wrapper.element; + assert.equal(element.tagName, 'DIALOG'); + assert.equal(element.open, false); + assert.equal(wrapper.vm.element, element, 'element is exposed'); + await wrapper.setProps({ open: true }); + assert.equal(element.open, true); + assert.deepEqual(events, ['opened', 'shown']); + await wrapper.setProps({ open: false }); + assert.equal(element.open, false); + assert.deepEqual(events, ['opened', 'shown', 'closed', 'hidden']); + wrapper.unmount(); +}); + +test('a dialog mounted open opens modal on mount; unmounting closes it', async () => { + const modal = []; + const showModal = HTMLDialogElement.prototype.showModal; + HTMLDialogElement.prototype.showModal = function () { + modal.push(this); + return showModal.call(this); + }; + try { + const { wrapper, events } = dialog({ open: true }); + const element = wrapper.element; + assert.deepEqual(modal, [element]); + assert.equal(element.open, true); + assert.deepEqual(events, ['opened', 'shown']); + wrapper.unmount(); + assert.equal(element.open, false); + assert.deepEqual(events, ['opened', 'shown'], 'no dismiss on unmount'); + } finally { + HTMLDialogElement.prototype.showModal = showModal; + } +}); + +test('the open state follows the content: opened comes after it renders', async () => { + const { wrapper } = dialog(); + let seen; + await wrapper.setProps({ + open: true, + onOpened: () => { + seen = wrapper.element.querySelector('.content')?.textContent; + }, + }); + assert.equal(seen, 'Words'); + wrapper.unmount(); +}); + +test('Escape is prevented and emitted as dismiss; the owner decides', async () => { + const { wrapper, events } = dialog({ open: true }); + events.length = 0; + const cancel = new Event('cancel', { cancelable: true }); + wrapper.element.dispatchEvent(cancel); + assert.equal(cancel.defaultPrevented, true); + assert.equal(wrapper.element.open, true); + assert.deepEqual(events, ['dismiss', 'shown']); + wrapper.unmount(); +}); + +test('a close the browser made while open is reported once; the owner’s is not', async () => { + const { wrapper, events } = dialog({ open: true }); + events.length = 0; + wrapper.element.close(); + assert.deepEqual(events, ['browserClose', 'hidden']); + events.length = 0; + // The owner then closes it too: nothing to close, closed is still emitted. + await wrapper.setProps({ open: false }); + assert.deepEqual(events, ['closed', 'hidden']); + await wrapper.setProps({ open: true }); + events.length = 0; + await wrapper.setProps({ open: false }); + assert.deepEqual(events, ['closed', 'hidden'], 'no browserClose'); + wrapper.unmount(); +}); + +test('a backdrop click dismisses only when asked, and only on the dialog', async () => { + const plain = dialog({ open: true }); + plain.events.length = 0; + plain.wrapper.element.click(); + assert.deepEqual(plain.events, []); + plain.wrapper.unmount(); + + const backdrop = dialog({ open: true, backdropDismiss: true }); + backdrop.events.length = 0; + backdrop.wrapper.get('.content').element.click(); + assert.deepEqual(backdrop.events, [], 'a click inside is content'); + backdrop.wrapper.element.click(); + assert.deepEqual(backdrop.events, ['dismiss', 'shown']); + backdrop.wrapper.unmount(); +}); + +test('attributes, classes, styles and listeners pass through to the dialog', async () => { + const clicks = []; + const { wrapper } = dialog( + {}, + { + id: 'library', + class: 'library-dialog', + style: { width: '40px' }, + 'aria-label': 'Library', + 'data-panel-surface': '', + onClick: () => clicks.push('click'), + }, + ); + const element = wrapper.element; + assert.equal(element.id, 'library'); + assert.ok(element.classList.contains('library-dialog')); + assert.equal(element.style.width, '40px'); + assert.equal(element.getAttribute('aria-label'), 'Library'); + assert.equal(element.getAttribute('data-panel-surface'), ''); + element.click(); + assert.deepEqual(clicks, ['click']); + wrapper.unmount(); +}); + +test('a DOM without showModal leaves the dialog closed rather than failing', async () => { + const showModal = HTMLDialogElement.prototype.showModal; + HTMLDialogElement.prototype.showModal = undefined; + try { + const { wrapper, events } = dialog({ open: true }); + assert.equal(wrapper.element.open, false); + assert.deepEqual(events, ['opened', 'hidden']); + await wrapper.setProps({ open: false }); + await nextTick(); + wrapper.unmount(); + } finally { + HTMLDialogElement.prototype.showModal = showModal; + } +}); diff --git a/src/ui/kit/UiDialog.vue b/src/ui/kit/UiDialog.vue new file mode 100644 index 0000000000..986a74bc3e --- /dev/null +++ b/src/ui/kit/UiDialog.vue @@ -0,0 +1,72 @@ + + + diff --git a/src/ui/kit/dialogs.test.mjs b/src/ui/kit/dialogs.test.mjs new file mode 100644 index 0000000000..80a6244947 --- /dev/null +++ b/src/ui/kit/dialogs.test.mjs @@ -0,0 +1,66 @@ +// Every modal dialog in a Vue view is a UiDialog: no SFC template hand-writes +// ``. Panels drawn as `role="dialog"` (key setup, the welcome +// launcher, the CCTV popup, Story Explore's filter) and the render failure's +// `alertdialog` are other controls. +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync, readdirSync } from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const SRC_ROOT = fileURLToPath(new URL('../../', import.meta.url)); +const REPO_ROOT = path.resolve(SRC_ROOT, '..'); +const KIT = 'src/ui/kit/UiDialog.vue'; + +/** Every SFC under src. */ +function sfcFiles(directory = SRC_ROOT) { + const files = []; + for (const entry of readdirSync(directory, { withFileTypes: true })) { + const absolute = path.join(directory, entry.name); + if (entry.isDirectory()) files.push(...sfcFiles(absolute)); + else if (entry.isFile() && entry.name.endsWith('.vue')) + files.push(absolute); + } + return files.sort(); +} + +/** The template block: everything outside script and style. */ +function template(source) { + return source.replace(/<(script|style)\b[\s\S]*?<\/\1\s*>/g, ''); +} + +// An opening tag's attributes, quoted values may hold `>` (`() => x`). +const ATTRS = String.raw`(?:[^>"']|"[^"]*"|'[^']*')*`; +const HAND_WRITTEN_DIALOG = new RegExp(String.raw``, 'gi'); + +/** Hand-written dialogs in an SFC's template. */ +function handWrittenDialogs(source) { + return [...template(source).matchAll(HAND_WRITTEN_DIALOG)].map((m) => + m[0].replace(/\s+/g, ' '), + ); +} + +test('the scan finds each hand-written dialog', () => { + for (const markup of [ + '', + '', + ]) + assert.equal(handWrittenDialogs(markup).length, 1, markup); + for (const markup of [ + '', + '', + "", + ]) + assert.equal(handWrittenDialogs(markup).length, 0, markup); +}); + +test('no SFC hand-writes a dialog; each is a UiDialog', () => { + const found = []; + for (const file of sfcFiles()) { + const relative = path.relative(REPO_ROOT, file).split(path.sep).join('/'); + if (relative === KIT) continue; + for (const markup of handWrittenDialogs(readFileSync(file, 'utf8'))) + found.push(`${relative}: ${markup}`); + } + assert.deepEqual(found, []); +}); diff --git a/src/ui/sceneSharingView.test.mjs b/src/ui/sceneSharingView.test.mjs index 2166f07d9f..c9fd8e646a 100644 --- a/src/ui/sceneSharingView.test.mjs +++ b/src/ui/sceneSharingView.test.mjs @@ -178,9 +178,12 @@ test('Cancel and Escape close through the owner; dispose removes the dialog', as $('dialog').dispatchEvent(cancel); assert.equal(cancel.defaultPrevented, true); assert.equal(closes, 2); + const root = $('dialog'); + assert.equal(root.open, true, 'Escape leaves closing to the owner'); dialog.dispose(); await nextTick(); assert.equal($('dialog'), null); + assert.equal(root.open, false, 'the removed dialog is closed'); assert.equal(store.controls, null); }); diff --git a/src/ui/views/panels/DataLibraryDialog.test.mjs b/src/ui/views/panels/DataLibraryDialog.test.mjs index 1ec3ce9c3b..904bfd23df 100644 --- a/src/ui/views/panels/DataLibraryDialog.test.mjs +++ b/src/ui/views/panels/DataLibraryDialog.test.mjs @@ -139,6 +139,30 @@ test('Browse opens a modal on the search field, packs last; Escape returns to Br assert.equal(document.activeElement, $('#data-library-browse')); }); +test('a backdrop click and a close the browser made itself return to Browse', async (t_) => { + const { owner } = mount(t_); + owner.open(); + await settle(); + $('#data-library .data-library-intro').click(); + await settle(); + assert.equal($('#data-library').open, true, 'a click inside keeps it open'); + $('#data-library').click(); + await settle(); + assert.equal($('#data-library').open, false); + assert.equal(document.activeElement, $('#data-library-browse')); + owner.open(); + await settle(); + assert.equal(document.activeElement, $('#data-library input[type="search"]')); + // An Escape the page may not cancel: the browser closes it first. + $('#data-library').close(); + await settle(); + assert.equal($('#data-library').open, false); + assert.equal(document.activeElement, $('#data-library-browse')); + owner.open(); + await settle(); + assert.equal($('#data-library').open, true, 'the owner closed it too'); +}); + test('filters narrow the list as the viewer types and picks', async (t_) => { const { owner } = mount(t_); owner.open(); diff --git a/src/ui/views/panels/DataLibraryDialog.vue b/src/ui/views/panels/DataLibraryDialog.vue index 4d58ab834d..48701719b3 100644 --- a/src/ui/views/panels/DataLibraryDialog.vue +++ b/src/ui/views/panels/DataLibraryDialog.vue @@ -5,6 +5,7 @@ import { formatNumber, t, tn } from '../../../i18n/index.js'; import UiButton from '../../kit/UiButton.vue'; import UiCheckbox from '../../kit/UiCheckbox.vue'; import UiCloseButton from '../../kit/UiCloseButton.vue'; +import UiDialog from '../../kit/UiDialog.vue'; import UiSelect from '../../kit/UiSelect.js'; import { libraryStatTiles, @@ -24,27 +25,18 @@ const { controls } = storeToRefs(useDataLibraryStore()); const root = useTemplateRef('root'); const search = useTemplateRef('search'); -watch( - () => props.view.open, - async (open, wasOpen) => { - await nextTick(); - const dialog = root.value; - if (!dialog) return; - if (open) { - if (!dialog.open) dialog.showModal?.(); - search.value?.focus(); - return; - } - if (dialog.open) dialog.close(); - // The browser may already have closed it (Escape is not always - // cancelable); either way focus returns to Browse, unless the viewer - // has moved it somewhere else meanwhile. - const active = document.activeElement; - if (wasOpen && (!active || active === document.body || dialog.contains(active))) - document.getElementById('data-library-browse')?.focus(); - }, - { immediate: true }, -); +// UiDialog opens and closes the dialog as `view.open` says, once the content +// has rendered; Escape and a click on the backdrop dismiss. +const onOpened = () => search.value?.focus(); +// The browser may already have closed it (Escape is not always cancelable); +// either way focus returns to Browse, unless the viewer has moved it +// somewhere else meanwhile. +const onClosed = () => { + const dialog = root.value?.element; + const active = document.activeElement; + if (!active || active === document.body || dialog?.contains(active)) + document.getElementById('data-library-browse')?.focus(); +}; watch( () => props.view.focusSearch, async () => { @@ -81,24 +73,22 @@ const resetLabel = computed(() => ? t('Confirm: remove every added entry from Data Layers') : t('Remove every added entry from Data Layers'), ); -// A click on the backdrop (the dialog box itself, outside its content) -// dismisses, like Escape. -const onDialogClick = (event) => { - if (event.target === event.currentTarget) controls.value?.close(); -}; diff --git a/src/ui/views/panels/SceneDialog.vue b/src/ui/views/panels/SceneDialog.vue index 82932a729f..57ed00f70b 100644 --- a/src/ui/views/panels/SceneDialog.vue +++ b/src/ui/views/panels/SceneDialog.vue @@ -1,21 +1,17 @@