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 =
- '
' +
- '' +
- '
' +
- '
' +
- '
' +
- '
' +
+ // What the view renders: the owner writes it for each step, then paints.
+ // The view never binds what is set on the elements: the guide's `visible`
+ // class, the callout's entrance replay, place and side, and the rings'
+ // boxes, set per frame.
+ const endLabel = t('End guide');
+ const view = {
+ title: title ? t('Guide · {topic}', { topic: title }) : t('Guide'),
+ endLabel,
+ count: '',
+ step: 0,
+ progress: [],
+ text: '',
+ hint: t('Press the highlighted control'),
+ hintHidden: false,
+ // i18n-ignore: the Escape keycap, matching the keyboard shortcut.
+ keyCap: 'Esc',
+ keyText: t('to end'),
+ keysHidden: false,
+ skipLabel: '',
+ skipHidden: true,
+ offerLabel: '',
+ offerHidden: true,
+ nextLabel: t('Next'),
+ nextHidden: false,
+ nextQuiet: false,
// Announces each step once; the dialog itself is not a live region, so
// its buttons and progress are not read out on every change.
- '
';
+ 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 @@
+
+
+
+
{{ view.title }}
{{ view.count }}
{{ view.text }}
{{ view.hint }}
{{ view.keyCap }}{{ view.keyText }}
{{ view.skipLabel }}{{ view.offerLabel }}{{ view.nextLabel }}{{
+ view.status
+ }}