diff --git a/changelog.d/1846-sfc-omnibar-guide.md b/changelog.d/1846-sfc-omnibar-guide.md new file mode 100644 index 0000000000..cdd91d63c1 --- /dev/null +++ b/changelog.d/1846-sfc-omnibar-guide.md @@ -0,0 +1,3 @@ +- The Omnibar's guided walk is now a single-file component with the kit's + close and buttons, and a walk started while the page is still drawing no + longer fails (manjunath22466, samehkhamis, #1846). diff --git a/docs/VUE-MIGRATION.md b/docs/VUE-MIGRATION.md index a64d55e0c9..7b20c82fe5 100644 --- a/docs/VUE-MIGRATION.md +++ b/docs/VUE-MIGRATION.md @@ -109,7 +109,8 @@ 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, and so does the credits list's. The -guide's close button, built in script, is not converted yet. +Quebec CCTV overlay's close is one too, and so is the Omnibar guide's, +which keeps its feature class and tip. `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 @@ -301,7 +302,11 @@ once passes the locale itself as a prop or key, as the credits line does. `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 7dc54bc407..336b0ad4b2 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1626,6 +1626,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 e8a87b2f34..ad73b786c3 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..0e1a668a80 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,71 @@ 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; + } // 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'); + // 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 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 +533,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 +565,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 +616,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..615f7d2f8f --- /dev/null +++ b/src/ui/omnibarGuide.test.mjs @@ -0,0 +1,136 @@ +// 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 { createApp, h, onMounted } from 'vue'; +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'); +}); + +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/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..71f1c95069 --- /dev/null +++ b/src/ui/views/panels/OmnibarGuide.vue @@ -0,0 +1,82 @@ + + + +