From 121d11d3ff92671a14844d4cbc302bbc2f688528 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Thu, 19 Nov 2026 01:43:57 -0800 Subject: [PATCH 1/8] Vue: the Quebec CCTV overlay is a single-file component MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit QuebecCctvOverlay renders the Québec 511 player window and its map preview, teleported to the end of the body as before, with the kit's UiCloseButton and UiButtons. createQuebecCctvOverlay() keeps its API and every decision: it renders the view synchronously from the state it computes on each change, and keeps the parts the template never binds (each video's source, playback and refresh timer, the window's drag, and the marker's per-frame visibility and place). The markup is unchanged apart from the kit's button classes. The overlay test renders in the registered document, which Vue binds when it loads, and adds Escape closing the window until the camera is picked again. Co-authored-by: Manjunath Paparaju --- docs/VUE-MIGRATION.md | 13 +- scripts/package-boundaries.json | 7 + src/ui/quebecCctvOverlay.js | 296 ++++++++++------------ src/ui/quebecCctvOverlay.test.mjs | 60 +++-- src/ui/views/panels/QuebecCctvOverlay.vue | 110 ++++++++ 5 files changed, 302 insertions(+), 184 deletions(-) create mode 100644 src/ui/views/panels/QuebecCctvOverlay.vue diff --git a/docs/VUE-MIGRATION.md b/docs/VUE-MIGRATION.md index 5d5f0c0b63..8cdeb68781 100644 --- a/docs/VUE-MIGRATION.md +++ b/docs/VUE-MIGRATION.md @@ -108,8 +108,8 @@ no tip unless the site passes a `title`; attributes and classes pass through, so each site keeps its id, feature class and look. Every close, dismiss and clear button in the views is one (`src/ui/kit/closeButtons.test.mjs` pins it); Street Level's and the space mission's keep `bare`, since their skins -keep the browser's padding. The close buttons built in script (credits, the -Quebec CCTV overlay, the guide) are not converted yet. +keep the browser's padding. The close buttons built in script (credits and +the guide) are not converted yet. `UiSearchField` takes `v-model`, a required `label` (the input's accessible name), `placeholder` and `tag` (`div`, given `role="search"` by the site, or `label`); attributes and classes go to the frame, and @@ -244,8 +244,13 @@ a feature supplying only its accent. the whole panel from the `gev-cctv` store, including the camera picker, the inline pose editor, the frame preview, source badge and typed summary; `CctvControls` keeps its listeners, the frame requests and the - live video surface), Layers (done: `LayerPanel` presents each row and - renders `LayerRows` synchronously; keyed chips and list items keep focus + live video surface; `QuebecCctvOverlay` teleports the Québec 511 player + and its map preview to the end of the body, rendered synchronously by + `createQuebecCctvOverlay()` from the view it computes, as the rail cards + are; the owner keeps every decision and the parts the template never + binds: each video's source, playback and refresh timer, the window's drag + and the marker's per-frame visibility and place), Layers (done: + `LayerPanel` presents each row and renders `LayerRows` synchronously; keyed chips and list items keep focus through the refresh their own click triggers, and clicks re-read the live descriptor before acting), Display (in progress: `DisplayPanel` renders the HUD, Sonar, Scope, Celestial, detection, bloom, sharpen and the diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index caf06537ef..2367606ddb 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1096,6 +1096,11 @@ "src/ui/cctvVideo.js", "src/ui/cctvPresentation.js", "src/ui/quebecCctvOverlay.js", + "src/ui/views/panels/QuebecCctvOverlay.vue", + "src/ui/kit/UiButton.vue", + "src/ui/kit/UiCloseButton.vue", + "src/ui/kit/UiIcon.vue", + "src/ui/rail/classToggle.js", "src/i18n/index.js", "src/i18n/locale.js", "src/i18n/locales/ar.json", @@ -1635,6 +1640,7 @@ "src/layers/wildlifeSightings/photoText.js", "src/data/iconOrientation.js", "src/ui/quebecCctvOverlay.js", + "src/ui/views/panels/QuebecCctvOverlay.vue", "src/time/worldClock.js", "src/cockpitSubjects.js", "src/cockpitRadar.js", @@ -5459,6 +5465,7 @@ "src/layers/wildlifeSightings/iconCollection.js", "src/layers/wildlifeSightings/view.js", "src/ui/quebecCctvOverlay.js", + "src/ui/views/panels/QuebecCctvOverlay.vue", "src/time/viewerClock.js", "src/time/worldClock.js", "src/cockpitSubjects.js", diff --git a/src/ui/quebecCctvOverlay.js b/src/ui/quebecCctvOverlay.js index 2416aca945..0cf3e0a61e 100644 --- a/src/ui/quebecCctvOverlay.js +++ b/src/ui/quebecCctvOverlay.js @@ -1,3 +1,4 @@ +import { h, render as renderVue } from 'vue'; import { fromDegrees } from '../geo/ellipsoid.js'; import { horizonFrom } from '../geo/horizon.js'; import { distance } from '../geo/vector.js'; @@ -8,6 +9,7 @@ import { findQuery, } from '../render/rendererOf.js'; import { t } from '../i18n/index.js'; +import QuebecCctvOverlay from './views/panels/QuebecCctvOverlay.vue'; function isQuebecCamera(camera) { return String(camera?.sourceKind || '').startsWith('quebec-'); @@ -77,72 +79,77 @@ function mediaRefreshUrl(value) { * Attach the active Québec source to a floating browser player and map * preview. The browser contacts Québec 511 only after the viewer presses Play * for that camera; selecting it (by click, auto-hop, a scene or voice) only - * shows its details and the play control. + * shows its details and the play control. The panel and marker are the + * `QuebecCctvOverlay` view, rendered synchronously on each change. */ export function createQuebecCctvOverlay(viewer) { if (!viewer || typeof document === 'undefined') return null; const controller = new AbortController(); const { signal } = controller; - const panel = document.createElement('section'); - panel.className = 'qci-panel'; - panel.hidden = true; - panel.setAttribute('role', 'region'); - panel.setAttribute('aria-label', t('CCTV camera')); - - const header = document.createElement('header'); - header.className = 'qci-header'; - const title = document.createElement('strong'); - const close = document.createElement('button'); - close.type = 'button'; - close.textContent = '×'; - close.setAttribute('aria-label', t('Close camera preview')); - header.append(title, close); - - const coordinates = document.createElement('p'); - coordinates.className = 'qci-coordinates'; - const credit = document.createElement('p'); - credit.className = 'qci-credit'; - const live = document.createElement('video'); - live.className = 'qci-live'; - live.controls = true; - live.muted = true; - live.autoplay = true; - live.loop = true; - live.playsInline = true; - live.setAttribute('aria-label', t('CCTV camera')); - - const actions = document.createElement('div'); - actions.className = 'qci-actions'; - const play = document.createElement('button'); - play.type = 'button'; - play.className = 'qci-play'; - play.textContent = t('Play'); - const refresh = document.createElement('button'); - refresh.type = 'button'; - refresh.textContent = t('Refresh map still'); - actions.append(play, refresh); - const note = document.createElement('p'); - note.className = 'qci-note'; - const sourceLink = document.createElement('a'); - sourceLink.target = '_blank'; - sourceLink.rel = 'noopener noreferrer'; - sourceLink.textContent = t("Open this image on the provider's site"); - panel.append(header, coordinates, credit, live, actions, note, sourceLink); - - const marker = document.createElement('div'); - marker.className = 'qci-marker'; - marker.hidden = true; - const still = document.createElement('video'); - still.className = 'qci-marker-still'; - still.muted = true; - still.playsInline = true; - still.preload = 'none'; - still.setAttribute('aria-hidden', 'true'); - const markerLabel = document.createElement('span'); - markerLabel.className = 'qci-marker-label'; - marker.append(still, markerLabel); - document.body.append(panel, marker); + // What the view renders. The owner writes it where it used to write the + // elements, then paints; the view never binds the media sources, the + // panel's dragged position or the marker's per-frame visibility and place. + const view = { + panelHidden: true, + title: '', + coordinates: '', + credit: '', + creditHidden: false, + liveHidden: false, + actionsHidden: false, + playHidden: false, + refreshHidden: false, + note: '', + noteHidden: false, + sourceHref: null, + sourceHidden: false, + markerLinkOnly: false, + stillHidden: false, + markerLabel: '', + }; + const host = document.createElement('div'); + let disposed = false; + const handlers = { + onClose: closeWindow, + onPlay: startPlayback, + onRefresh: refreshStill, + onKeydown(event) { + if (event.key === 'Escape') close.click(); + }, + onHeaderPointerdown: startDrag, + onLiveError: markLiveUnavailable, + onLiveLoadeddata() { + liveUnavailable = false; + view.note = t( + 'The map still uses a separate request and may show a different moment.', + ); + view.noteHidden = false; + paint(); + }, + onStillError: markStillUnavailable, + onStillLoadeddata() { + stillUnavailable = false; + if (selected) + view.markerLabel = markerLabelText(selected, Boolean(selectedMediaUrl)); + paint(); + still.pause(); + }, + }; + /** Render the view now: the panel and marker go to the end of the body. */ + function paint() { + if (disposed) return null; + const vnode = h(QuebecCctvOverlay, { view: { ...view }, ...handlers }); + renderVue(vnode, host); + return vnode.component.exposed; + } + const elements = paint(); + const panel = elements.panel.value; + const header = elements.header.value; + const close = elements.close.value.$el; + const live = elements.live.value; + const marker = elements.marker.value; + const still = elements.still.value; let selected = null; let selectedPosition = null; @@ -166,13 +173,15 @@ export function createQuebecCctvOverlay(viewer) { function markLiveUnavailable() { liveUnavailable = true; - note.textContent = t('Source unavailable'); - note.hidden = false; + view.note = t('Source unavailable'); + view.noteHidden = false; + paint(); } function markStillUnavailable() { stillUnavailable = true; - markerLabel.textContent = t('Source unavailable'); + view.markerLabel = t('Source unavailable'); + paint(); } function startRender() { @@ -218,16 +227,17 @@ export function createQuebecCctvOverlay(viewer) { playingCameraId = selected.id; liveUnavailable = false; stillUnavailable = false; - play.hidden = true; - refresh.hidden = false; - live.hidden = false; - still.hidden = false; - marker.classList.remove('qci-marker-link-only'); - note.textContent = t( + view.playHidden = true; + view.refreshHidden = false; + view.liveHidden = false; + view.stillHidden = false; + view.markerLinkOnly = false; + view.note = t( 'The map still uses a separate request and may show a different moment.', ); - note.hidden = false; - markerLabel.textContent = markerLabelText(selected, true); + view.noteHidden = false; + view.markerLabel = markerLabelText(selected, true); + paint(); setMedia(live, selectedMediaUrl); setMedia(still, selectedMediaUrl); void live.play().catch(onPlayFailure(markLiveUnavailable)); @@ -246,7 +256,8 @@ export function createQuebecCctvOverlay(viewer) { stillUnavailable = false; stopMediaRefresh(); stopRender(); - panel.hidden = true; + view.panelHidden = true; + paint(); marker.hidden = true; setMedia(live, ''); setMedia(still, ''); @@ -263,7 +274,8 @@ export function createQuebecCctvOverlay(viewer) { Number(camera.elevationM) || 10, ); if (closedWindowCameraId === camera.id && !reselected) { - panel.hidden = true; + view.panelHidden = true; + paint(); updateMarker(); return; } @@ -276,8 +288,8 @@ export function createQuebecCctvOverlay(viewer) { playingCameraId = null; } const playing = Boolean(mediaUrl) && playingCameraId === camera.id; - title.textContent = camera.name || t('CCTV camera'); - coordinates.textContent = [ + view.title = camera.name || t('CCTV camera'); + view.coordinates = [ `${Number(camera.lat).toFixed(5)}, ${Number(camera.lon).toFixed(5)}`, Number.isFinite(camera.accuracyM) && camera.accuracyM > 0 ? `±${Math.round(camera.accuracyM)} m` @@ -286,14 +298,13 @@ export function createQuebecCctvOverlay(viewer) { ] .filter(Boolean) .join(' · '); - credit.textContent = camera.credit || camera.provider || ''; - credit.hidden = !credit.textContent; - live.hidden = !playing; - play.hidden = !mediaUrl || playing; - refresh.hidden = !playing; - actions.hidden = !mediaUrl; - note.hidden = !mediaUrl; - note.textContent = mediaUrl + view.credit = camera.credit || camera.provider || ''; + view.creditHidden = !view.credit; + view.liveHidden = !playing; + view.playHidden = !mediaUrl || playing; + view.refreshHidden = !playing; + view.actionsHidden = !mediaUrl; + view.note = mediaUrl ? !playing ? t('Video plays from Québec 511, which sees your IP address.') : liveUnavailable @@ -304,15 +315,16 @@ export function createQuebecCctvOverlay(viewer) { : sourceUrl ? '' : t('Source unavailable'); - note.hidden = !note.textContent; - sourceLink.href = sourceUrl || '#'; - sourceLink.hidden = !sourceUrl; - markerLabel.textContent = stillUnavailable + view.noteHidden = !view.note; + view.sourceHref = sourceUrl || '#'; + view.sourceHidden = !sourceUrl; + view.markerLabel = stillUnavailable ? t('Source unavailable') : markerLabelText(camera, playing); - marker.classList.toggle('qci-marker-link-only', !playing); - still.hidden = !playing; - panel.hidden = false; + view.markerLinkOnly = !playing; + view.stillHidden = !playing; + view.panelHidden = false; + paint(); if (changed || mediaUrl !== selectedMediaUrl) { selectedMediaUrl = mediaUrl; @@ -366,34 +378,6 @@ export function createQuebecCctvOverlay(viewer) { ); } - still.addEventListener( - 'loadeddata', - () => { - stillUnavailable = false; - if (selected) - markerLabel.textContent = markerLabelText( - selected, - Boolean(selectedMediaUrl), - ); - still.pause(); - }, - { signal }, - ); - still.addEventListener('error', markStillUnavailable, { signal }); - live.addEventListener('error', markLiveUnavailable, { signal }); - live.addEventListener( - 'loadeddata', - () => { - liveUnavailable = false; - note.textContent = t( - 'The map still uses a separate request and may show a different moment.', - ); - note.hidden = false; - }, - { signal }, - ); - refresh.addEventListener('click', refreshStill, { signal }); - play.addEventListener('click', startPlayback, { signal }); const resetCanvasRect = () => { canvasRect = null; }; @@ -403,49 +387,35 @@ export function createQuebecCctvOverlay(viewer) { capture: true, passive: true, }); - panel.addEventListener( - 'keydown', - (event) => { - if (event.key === 'Escape') close.click(); - }, - { signal }, - ); - close.addEventListener( - 'click', - () => { - closedWindowCameraId = selected?.id || null; - panel.hidden = true; - live.pause(); - stopMediaRefresh(); - // The floating player closes independently; keep the paused map still. - updateMarker(); - }, - { signal }, - ); - header.addEventListener( - 'pointerdown', - (event) => { - if (event.target.closest('button')) return; - const rect = panel.getBoundingClientRect(); - const offsetX = event.clientX - rect.left; - const offsetY = event.clientY - rect.top; - header.setPointerCapture(event.pointerId); - const move = (moveEvent) => { - panel.style.left = `${Math.max(0, Math.min(window.innerWidth - panel.offsetWidth, moveEvent.clientX - offsetX))}px`; - panel.style.top = `${Math.max(0, Math.min(window.innerHeight - panel.offsetHeight, moveEvent.clientY - offsetY))}px`; - panel.style.right = 'auto'; - }; - const stop = () => { - header.removeEventListener('pointermove', move); - header.removeEventListener('pointerup', stop); - header.removeEventListener('pointercancel', stop); - }; - header.addEventListener('pointermove', move, { signal }); - header.addEventListener('pointerup', stop, { once: true, signal }); - header.addEventListener('pointercancel', stop, { once: true, signal }); - }, - { signal }, - ); + function closeWindow() { + closedWindowCameraId = selected?.id || null; + view.panelHidden = true; + paint(); + live.pause(); + stopMediaRefresh(); + // The floating player closes independently; keep the paused map still. + updateMarker(); + } + function startDrag(event) { + if (event.target.closest('button')) return; + const rect = panel.getBoundingClientRect(); + const offsetX = event.clientX - rect.left; + const offsetY = event.clientY - rect.top; + header.setPointerCapture(event.pointerId); + const move = (moveEvent) => { + panel.style.left = `${Math.max(0, Math.min(window.innerWidth - panel.offsetWidth, moveEvent.clientX - offsetX))}px`; + panel.style.top = `${Math.max(0, Math.min(window.innerHeight - panel.offsetHeight, moveEvent.clientY - offsetY))}px`; + panel.style.right = 'auto'; + }; + const stop = () => { + header.removeEventListener('pointermove', move); + header.removeEventListener('pointerup', stop); + header.removeEventListener('pointercancel', stop); + }; + header.addEventListener('pointermove', move, { signal }); + header.addEventListener('pointerup', stop, { once: true, signal }); + header.addEventListener('pointercancel', stop, { once: true, signal }); + } document.addEventListener( 'visibilitychange', () => { @@ -469,8 +439,8 @@ export function createQuebecCctvOverlay(viewer) { stopRender(); setMedia(live, ''); setMedia(still, ''); - panel.remove(); - marker.remove(); + disposed = true; + renderVue(null, host); selected = null; selectedPosition = null; }, diff --git a/src/ui/quebecCctvOverlay.test.mjs b/src/ui/quebecCctvOverlay.test.mjs index ca8a04934a..386dd7547a 100644 --- a/src/ui/quebecCctvOverlay.test.mjs +++ b/src/ui/quebecCctvOverlay.test.mjs @@ -1,6 +1,6 @@ +import '../testSupport/registerDom.mjs'; import { test } from 'node:test'; import assert from 'node:assert/strict'; -import { Window } from 'happy-dom'; import { fromDegrees } from '../geo/ellipsoid.js'; import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs'; import { fakeCameraPort } from '../testSupport/fakeCameraPort.mjs'; @@ -22,23 +22,36 @@ const CAMERA = Object.freeze({ }); /** - * Mount the overlay in a happy-dom window with recorded media loads, timers - * and postRender listeners. `play` decides what each play() returns. + * Mount the overlay in the registered happy-dom window (Vue binds the + * document it loads with) with recorded media loads, timers and postRender + * listeners. `play` decides what each play() returns. */ function mountOverlay(t, { play = () => Promise.resolve() } = {}) { - const window = new Window({ url: 'http://localhost:4173/' }); - const previousWindow = globalThis.window; - const previousDocument = globalThis.document; - globalThis.window = window; - globalThis.document = window.document; + const { window } = globalThis; + const media = window.HTMLMediaElement.prototype; + const previous = { + load: media.load, + play: media.play, + pause: media.pause, + setInterval: window.setInterval, + clearInterval: window.clearInterval, + }; + t.after(() => { + media.load = previous.load; + media.play = previous.play; + media.pause = previous.pause; + window.setInterval = previous.setInterval; + window.clearInterval = previous.clearInterval; + delete window.document.hidden; + }); const loads = []; - window.HTMLMediaElement.prototype.load = function () { + media.load = function () { if (this.getAttribute('src')) loads.push(this.getAttribute('src')); }; - window.HTMLMediaElement.prototype.play = function () { + media.play = function () { return play(this); }; - window.HTMLMediaElement.prototype.pause = function () {}; + media.pause = function () {}; const intervals = new Map(); let nextTimer = 1; window.setInterval = (fn) => { @@ -65,12 +78,7 @@ function mountOverlay(t, { play = () => Promise.resolve() } = {}) { }); t.after(unbind); const overlay = createQuebecCctvOverlay(viewer); - t.after(() => { - overlay?.dispose(); - globalThis.window = previousWindow; - globalThis.document = previousDocument; - window.close(); - }); + t.after(() => overlay?.dispose()); const [live, still] = window.document.querySelectorAll('video'); return { window, @@ -203,3 +211,21 @@ test('the refresh timer reloads with a cache-buster, skips hidden tabs, and stop assert.equal(ui.renderListeners.size, 0); assert.equal(ui.window.document.querySelector('.qci-panel') === null, true); }); + +test('Escape in the window closes it and stops the refresh until the camera is picked again', (t) => { + const ui = mountOverlay(t); + ui.overlay.setCamera(CAMERA); + ui.playButton().click(); + const panel = ui.window.document.querySelector('.qci-panel'); + panel.dispatchEvent( + new ui.window.KeyboardEvent('keydown', { key: 'Escape', bubbles: true }), + ); + assert.equal(panel.hidden, true); + assert.equal(ui.intervals.size, 0); + + ui.overlay.setCamera({ ...CAMERA }); + assert.equal(panel.hidden, true, 'a routine update keeps it closed'); + ui.overlay.setCamera({ ...CAMERA }, { reselected: true }); + assert.equal(panel.hidden, false, 'picking the camera again reopens it'); + assert.equal(ui.intervals.size, 1); +}); diff --git a/src/ui/views/panels/QuebecCctvOverlay.vue b/src/ui/views/panels/QuebecCctvOverlay.vue new file mode 100644 index 0000000000..e13a5e56fb --- /dev/null +++ b/src/ui/views/panels/QuebecCctvOverlay.vue @@ -0,0 +1,110 @@ + + + + From 10a26e15cede13f80bc2b658ab3c503f2c22aded Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Thu, 19 Nov 2026 02:10:49 -0800 Subject: [PATCH 2/8] Vue: the Omnibar's guided walk is a single-file component OmnibarGuide renders the walk's spotlight ring and callout, teleported to the end of the body as before, with the kit's UiCloseButton for its close and UiButtons for Not now, the offer and Next. startGuide() keeps its signature and every decision and word: it renders the view synchronously from what it computes for each step and keeps the parts the template never binds: the guide's visible class and the callout's entrance replay (in the same order, so the first step still fades in), the callout's place and side and the rings' boxes each frame, focus and its return, Escape and the checks for a screen another surface owns. The ids, roles, aria attributes, hidden attributes, tabindex, text and focus order are unchanged. The buttons gain the kit's classes, which carry no rules, so they look as before. The close drops the aria-hidden span around its glyph: its name is still its aria-label, "End guide", and its tip the same words. Progress segments are new elements each step, as before, so a segment's colour does not animate across steps, and the status line changes once per step. New tests: the walk is the last of the body, takes focus and gives it back, announces each step once and draws new progress each step, and a new walk ends the one in progress. Co-authored-by: Manjunath Paparaju --- docs/VUE-MIGRATION.md | 11 +- scripts/format-scope.json | 1 + scripts/package-boundaries.json | 1 + src/ui/omnibarGuide.js | 151 ++++++++++++++------------- src/ui/omnibarGuide.test.mjs | 111 ++++++++++++++++++++ src/ui/styles/close-button.css | 9 +- src/ui/views/panels/OmnibarGuide.vue | 89 ++++++++++++++++ 7 files changed, 293 insertions(+), 80 deletions(-) create mode 100644 src/ui/omnibarGuide.test.mjs create mode 100644 src/ui/views/panels/OmnibarGuide.vue diff --git a/docs/VUE-MIGRATION.md b/docs/VUE-MIGRATION.md index b7c030dc10..ebb3b1d4cc 100644 --- a/docs/VUE-MIGRATION.md +++ b/docs/VUE-MIGRATION.md @@ -108,8 +108,9 @@ no tip unless the site passes a `title`; attributes and classes pass through, so each site keeps its id, feature class and look. Every close, dismiss and clear button in the views is one (`src/ui/kit/closeButtons.test.mjs` pins it); Street Level's and the space mission's keep `bare`, since their skins -set their own padding and border. The close buttons built in script (credits, the -Quebec CCTV overlay, the guide) are not converted yet. +set their own padding and border. The Omnibar guide's close is one too, +keeping its feature class and tip. The close buttons built in script +(credits, the Quebec CCTV overlay) are not converted yet. `UiSearchField` takes `v-model`, a required `label` (the input's accessible name), `placeholder` and `tag` (`div`, given `role="search"` by the site, or `label`); attributes and classes go to the frame, and @@ -290,7 +291,11 @@ a feature supplying only its accent. `gev-location` store, and the search field keeps its listeners; beside the voice control, the dock teleports each voice pointer reticle to the body where its `PointerReticle` presents it in the `gev-pointer-reticle` - store), the phone shell (`PhoneTabBar` renders the tabs and open sheet the shell + store; `startGuide()` renders the Omnibar's guided walk, `OmnibarGuide`, + synchronously from the view it computes for each step, teleported to the + end of the body, and keeps every decision and word, focus and its return, + Escape, the entrance replay, and the callout's and spotlight rings' place + each frame), the phone shell (`PhoneTabBar` renders the tabs and open sheet the shell publishes to the `gev-display` store, teleporting the tab bar and sheet backdrop to the end of the page from the first publish until the shell is destroyed; the shell takes their clicks from the document), the diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 76004da995..a947ca4cde 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1624,6 +1624,7 @@ "src/tooling/wikidataPlaceTiles.test.mjs", "src/ui/omnibarIntent.test.mjs", "src/ui/omnibarRows.test.mjs", + "src/ui/omnibarGuide.test.mjs", "src/ui/styles/omnibar-dock.css", "src/ui/styles/guide.css", "src/ui/commandDock.test.mjs", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index caf06537ef..7da835f67b 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -300,6 +300,7 @@ "src/exclusiveSurfaces.js", "src/geoDistance.js", "src/ui/omnibarGuide.js", + "src/ui/views/panels/OmnibarGuide.vue", "src/cityPois.js", "src/search/photonSetting.js", "src/sources/requestDeadline.js", diff --git a/src/ui/omnibarGuide.js b/src/ui/omnibarGuide.js index bcfe8d5b50..6903357400 100644 --- a/src/ui/omnibarGuide.js +++ b/src/ui/omnibarGuide.js @@ -13,9 +13,11 @@ // features (styles, HUD, compass, tilt, globe view, share, clear) have their // own. The walk works the same for all of them. +import { h, render as renderVue } from 'vue'; import { t } from '../i18n/index.js'; import { EXCLUSIVE_SURFACE_CLASSES } from '../exclusiveSurfaces.js'; import { LABEL_LAYERS } from './contextLayerTabs.js'; +import OmnibarGuide from './views/panels/OmnibarGuide.vue'; const LEFT_RAIL = '.ui-rail--left .ui-rail__item'; const RIGHT_RAIL = '.ui-rail--right .ui-rail__item'; @@ -445,43 +447,69 @@ export function startGuide(steps, { title = '' } = {}) { active?.stop(); const doc = globalThis.document; if (!doc?.body || screenIsOwned(doc) || !steps?.length) return; - const root = doc.createElement('div'); - root.className = 'gev-guide'; - root.innerHTML = - '
' + - ''; + status: '', + }; + const host = doc.createElement('div'); + const handlers = { + onClose: () => stop(), + onSkip: () => stop(), + // Taking the offer carries the walk on with its steps. + onOffer() { + if (!current?.offer) return; + const extra = current.offer.steps() || []; + live.splice(index + 1, live.length, ...extra.filter(Boolean)); + next(); + }, + onNext() { + if (current) next(); + }, + }; + let mounted = true; + /** Render the view now: the guide goes to the end of the body. */ + function paint() { + if (!mounted) return null; + const vnode = h(OmnibarGuide, { + to: doc.body, + view: { ...view }, + ...handlers, + }); + renderVue(vnode, host); + return vnode.component.exposed; + } // Focus returns where it was when the walk ends, if that is still there. const returnFocus = doc.activeElement; - doc.body.append(root); - const ring = root.querySelector('.gev-guide-ring'); - const callout = root.querySelector('.gev-guide-callout'); + const elements = paint(); + const root = elements.root.value; + const ring = elements.ring.value; + const callout = elements.callout.value; const subRings = []; - const endLabel = t('End guide'); - root.querySelector('.gev-guide-close').setAttribute('aria-label', endLabel); - root.querySelector('.gev-guide-close').title = endLabel; - // i18n-ignore: the Escape keycap, matching the keyboard shortcut. - root.querySelector('.gev-guide-keys kbd').textContent = 'Esc'; - root.querySelector('.gev-guide-keys span').textContent = t('to end'); - root.querySelector('.gev-guide-title').textContent = title - ? t('Guide · {topic}', { topic: title }) - : t('Guide'); - root.querySelector('.gev-guide-next').textContent = t('Next'); - root.querySelector('.gev-guide-hint span:last-child').textContent = t( - 'Press the highlighted control', - ); const live = steps.filter(Boolean); let index = -1; @@ -503,7 +531,8 @@ export function startGuide(steps, { title = '' } = {}) { doc.removeEventListener('click', onClick, true); doc.removeEventListener('keydown', onKey, true); const hadFocus = root.contains(doc.activeElement); - root.remove(); + mounted = false; + renderVue(null, host); if (hadFocus && returnFocus?.isConnected) returnFocus.focus?.(); if (active?.stop === stop) active = null; }; @@ -534,41 +563,29 @@ export function startGuide(steps, { title = '' } = {}) { // would not be skipped as things stand. const total = shown + live.slice(index + 1).filter((later) => !later.skip?.()).length; - root.querySelector('.gev-guide-count').textContent = `${shown} / ${total}`; - const progress = root.querySelector('.gev-guide-progress'); - progress.replaceChildren( - ...Array.from({ length: total }, (_, i) => { - const dot = doc.createElement('li'); - if (i < shown - 1) dot.className = 'done'; - if (i === shown - 1) dot.className = 'current'; - return dot; - }), + view.count = `${shown} / ${total}`; + view.step = shown; + view.progress = Array.from({ length: total }, (_, i) => + i < shown - 1 ? 'done' : i === shown - 1 ? 'current' : null, ); const text = step.text(); - root.querySelector('.gev-guide-text').textContent = text; - root.querySelector('.gev-guide-status').textContent = - `${shown} / ${total}: ${text}`; + view.text = text; + view.status = `${shown} / ${total}: ${text}`; // Steps that point at a control wait for it to be pressed; say so. const waits = Boolean(step.targets) && !step.offer; - root.querySelector('.gev-guide-hint').hidden = !waits; - const offer = root.querySelector('.gev-guide-offer'); - const skip = root.querySelector('.gev-guide-skip'); - offer.hidden = !step.offer; - skip.hidden = !step.offer; - root.querySelector('.gev-guide-keys').hidden = Boolean(step.offer); + view.hintHidden = !waits; + view.offerHidden = !step.offer; + view.skipHidden = !step.offer; + view.keysHidden = Boolean(step.offer); if (step.offer) { - offer.textContent = step.offer.label(); - skip.textContent = t('Not now'); + view.offerLabel = step.offer.label(); + view.skipLabel = t('Not now'); } const last = index === live.length - 1; - const nextButton = root.querySelector('.gev-guide-next'); - nextButton.hidden = Boolean(step.offer); - nextButton.textContent = last - ? t('Finish') - : waits - ? t('Skip step') - : t('Next'); - nextButton.classList.toggle('quiet', waits && !last); + view.nextHidden = Boolean(step.offer); + view.nextLabel = last ? t('Finish') : waits ? t('Skip step') : t('Next'); + view.nextQuiet = waits && !last; + paint(); // Replay the entrance so each step reads as new. callout.classList.remove('swap'); void callout.offsetWidth; @@ -597,18 +614,6 @@ export function startGuide(steps, { title = '' } = {}) { event.stopPropagation(); stop(); } - root.querySelector('.gev-guide-skip').addEventListener('click', stop); - root.querySelector('.gev-guide-close').addEventListener('click', stop); - root.querySelector('.gev-guide-next').addEventListener('click', () => { - if (current) next(); - }); - // Taking the offer carries the walk on with its steps. - root.querySelector('.gev-guide-offer').addEventListener('click', () => { - if (!current?.offer) return; - const extra = current.offer.steps() || []; - live.splice(index + 1, live.length, ...extra.filter(Boolean)); - next(); - }); doc.addEventListener('click', onClick, true); doc.addEventListener('keydown', onKey, true); diff --git a/src/ui/omnibarGuide.test.mjs b/src/ui/omnibarGuide.test.mjs new file mode 100644 index 0000000000..b221f73a69 --- /dev/null +++ b/src/ui/omnibarGuide.test.mjs @@ -0,0 +1,111 @@ +// The guided walk's callout, rendered by startGuide() over happy-dom. +import '../testSupport/registerDom.mjs'; +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { startGuide } from './omnibarGuide.js'; + +const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); +const $ = (selector) => document.querySelector(selector); + +function fixture(t) { + document.body.replaceChildren(); + const target = document.body.appendChild(document.createElement('button')); + const field = document.body.appendChild(document.createElement('input')); + field.focus(); + t.after(() => $('.gev-guide-close')?.click()); + return { target, field }; +} + +test('the walk is the last of the body, takes focus and gives it back', async (t) => { + const { target, field } = fixture(t); + startGuide([{ targets: () => [target], text: () => 'Press it' }], { + title: 'Flights', + }); + await settle(); + const guide = $('.gev-guide'); + assert.equal(document.body.lastElementChild, guide); + assert.equal(guide.parentElement, document.body); + assert.ok(guide.classList.contains('visible')); + const callout = $('.gev-guide-callout'); + assert.equal(document.activeElement, callout); + assert.equal(callout.getAttribute('role'), 'dialog'); + assert.equal(callout.getAttribute('aria-modal'), 'false'); + assert.equal(callout.getAttribute('tabindex'), '-1'); + assert.equal($('.gev-guide-title').textContent, 'Guide · Flights'); + const close = $('.gev-guide-close'); + assert.equal(close.getAttribute('type'), 'button'); + assert.equal(close.getAttribute('aria-label'), 'End guide'); + assert.equal(close.getAttribute('title'), 'End guide'); + assert.ok(close.classList.contains('ui-close-button')); + close.focus(); + close.click(); + assert.equal($('.gev-guide'), null); + assert.equal(document.activeElement, field); +}); + +test('the status line says each step once, and each step draws new progress', async (t) => { + const { target } = fixture(t); + startGuide([ + { targets: () => [target], text: () => 'Press it' }, + { text: () => 'Then this' }, + { + text: () => 'More?', + offer: { label: () => 'Show more', steps: () => [] }, + }, + ]); + const status = $('.gev-guide-status'); + const said = []; + // One change per step: its text replaced once, never cleared first. + const observer = new MutationObserver(() => said.push(status.textContent)); + observer.observe(status, { + childList: true, + characterData: true, + subtree: true, + }); + t.after(() => observer.disconnect()); + await settle(); + const firstDots = [...document.querySelectorAll('.gev-guide-progress li')]; + assert.deepEqual( + firstDots.map((dot) => dot.getAttribute('class')), + ['current', null, null], + ); + const next = $('.gev-guide-next'); + assert.equal(next.textContent, 'Skip step'); + assert.ok(next.classList.contains('quiet')); + assert.equal($('.gev-guide-hint').hidden, false); + next.click(); + await settle(); + const secondDots = [...document.querySelectorAll('.gev-guide-progress li')]; + assert.deepEqual( + secondDots.map((dot) => dot.getAttribute('class')), + ['done', 'current', null], + ); + assert.ok(secondDots.every((dot) => !firstDots.includes(dot))); + assert.equal(next.textContent, 'Next'); + assert.equal(next.classList.contains('quiet'), false); + assert.equal($('.gev-guide-hint').hidden, true); + next.click(); + await settle(); + // The closing offer: its two buttons, no Esc hint and no Next. + assert.equal($('.gev-guide-keys').hidden, true); + assert.equal(next.hidden, true); + assert.equal($('.gev-guide-skip').hidden, false); + assert.equal($('.gev-guide-skip').textContent, 'Not now'); + assert.equal($('.gev-guide-offer').textContent, 'Show more'); + assert.deepEqual(said, [ + '1 / 3: Press it', + '2 / 3: Then this', + '3 / 3: More?', + ]); + $('.gev-guide-skip').click(); + assert.equal($('.gev-guide'), null); +}); + +test('starting another walk ends the one in progress', async (t) => { + fixture(t); + startGuide([{ text: () => 'First' }]); + startGuide([{ text: () => 'Second' }]); + await settle(); + assert.equal(document.querySelectorAll('.gev-guide').length, 1); + assert.equal($('.gev-guide-text').textContent, 'Second'); +}); diff --git a/src/ui/styles/close-button.css b/src/ui/styles/close-button.css index a17c605fd1..d8fddb540e 100644 --- a/src/ui/styles/close-button.css +++ b/src/ui/styles/close-button.css @@ -1,9 +1,10 @@ /* Core's close, dismiss and clear buttons draw a bare glyph: no padding, * border or background of their own, and a pointer. The kit's - * UiCloseButton wears it as .ui-close-button; the guide's close button, - * built in script, shares the rule. It selects one class and loads before - * the feature stylesheets, so each feature rule still sets its size, colour, - * hover and any surface (a border, a chip, a tinted square). */ + * UiCloseButton wears it as .ui-close-button, and the guide's close (a + * UiCloseButton too) shares the rule by its feature class. It selects one + * class and loads before the feature stylesheets, so each feature rule still + * sets its size, colour, hover and any surface (a border, a chip, a tinted + * square). */ .ui-close-button, .gev-guide-close { padding: 0; diff --git a/src/ui/views/panels/OmnibarGuide.vue b/src/ui/views/panels/OmnibarGuide.vue new file mode 100644 index 0000000000..3be5b9b852 --- /dev/null +++ b/src/ui/views/panels/OmnibarGuide.vue @@ -0,0 +1,89 @@ + + + + From 4a6f185d0785d93e53eb83e0b86dd9dbaf6c59fe Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Thu, 19 Nov 2026 02:16:38 -0800 Subject: [PATCH 3/8] The guided walk finds its elements in the rendered tree Template refs are filled after a render returns, and later still when the walk starts inside one of Vue's own post-render updates, where the walk would have failed with its listeners already in place. Co-authored-by: Manjunath Paparaju --- src/ui/omnibarGuide.js | 12 +++++++----- src/ui/omnibarGuide.test.mjs | 25 +++++++++++++++++++++++++ src/ui/views/panels/OmnibarGuide.vue | 13 +++---------- 3 files changed, 35 insertions(+), 15 deletions(-) diff --git a/src/ui/omnibarGuide.js b/src/ui/omnibarGuide.js index 6903357400..0e1a668a80 100644 --- a/src/ui/omnibarGuide.js +++ b/src/ui/omnibarGuide.js @@ -501,14 +501,16 @@ export function startGuide(steps, { title = '' } = {}) { ...handlers, }); renderVue(vnode, host); - return vnode.component.exposed; + return vnode; } // Focus returns where it was when the walk ends, if that is still there. const returnFocus = doc.activeElement; - const elements = paint(); - const root = elements.root.value; - const ring = elements.ring.value; - const callout = elements.callout.value; + // The elements come from the rendered tree, which is in place as soon as the + // render returns; template refs are filled after it, and later still when + // the walk starts inside one of Vue's own post-render updates. + const root = paint().component.subTree.children[0].el; + const ring = root.querySelector(':scope > .gev-guide-ring'); + const callout = root.querySelector(':scope > .gev-guide-callout'); const subRings = []; const live = steps.filter(Boolean); diff --git a/src/ui/omnibarGuide.test.mjs b/src/ui/omnibarGuide.test.mjs index b221f73a69..615f7d2f8f 100644 --- a/src/ui/omnibarGuide.test.mjs +++ b/src/ui/omnibarGuide.test.mjs @@ -2,6 +2,7 @@ import '../testSupport/registerDom.mjs'; import test from 'node:test'; import assert from 'node:assert/strict'; +import { createApp, h, onMounted } from 'vue'; import { startGuide } from './omnibarGuide.js'; const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); @@ -109,3 +110,27 @@ test('starting another walk ends the one in progress', async (t) => { assert.equal(document.querySelectorAll('.gev-guide').length, 1); assert.equal($('.gev-guide-text').textContent, 'Second'); }); + +test('a walk started while Vue mounts something else still starts and ends', async (t) => { + const { target, field } = fixture(t); + let stop = null; + const app = createApp({ + setup() { + onMounted(() => { + stop = startGuide([ + { targets: () => [target], text: () => 'Press it' }, + ]); + }); + return () => h('span'); + }, + }); + app.mount(document.body.appendChild(document.createElement('div'))); + t.after(() => app.unmount()); + await settle(); + assert.equal(typeof stop, 'function'); + assert.equal(document.activeElement, $('.gev-guide-callout')); + assert.ok($('.gev-guide').classList.contains('visible')); + stop(); + assert.equal($('.gev-guide'), null); + assert.equal(document.activeElement, field); +}); diff --git a/src/ui/views/panels/OmnibarGuide.vue b/src/ui/views/panels/OmnibarGuide.vue index 3be5b9b852..71f1c95069 100644 --- a/src/ui/views/panels/OmnibarGuide.vue +++ b/src/ui/views/panels/OmnibarGuide.vue @@ -1,5 +1,4 @@