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 <[email protected]>
This commit is contained in:
Sameh KhamisandManjunath Paparaju committed 2026-11-19 02:10:49 -08:00
1 parent 7c858d96ee
commit 10a26e15ce
7 files changed
+293 -80

No files matched your search

+8 -3
View File
@@ -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
+1
View File
@@ -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",
+1
View File
@@ -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",
+78 -73
View File
@@ -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 =
'<div class="gev-guide-ring"><i></i></div>' +
'<div class="gev-guide-callout" role="dialog" aria-modal="false" tabindex="-1" aria-labelledby="gev-guide-title" aria-describedby="gev-guide-text">' +
'<div class="gev-guide-head"><p id="gev-guide-title" class="gev-guide-title"></p>' +
'<p class="gev-guide-count"></p>' +
'<button type="button" class="gev-guide-close"><span aria-hidden="true">×</span></button></div>' +
'<ol class="gev-guide-progress" aria-hidden="true"></ol>' +
'<div class="gev-guide-body"><p id="gev-guide-text" class="gev-guide-text"></p>' +
'<p class="gev-guide-hint"><span class="gev-guide-hint-dot"></span><span></span></p></div>' +
'<div class="gev-guide-actions"><p class="gev-guide-keys"><kbd></kbd><span></span></p>' +
'<span><button type="button" class="gev-guide-skip" hidden></button>' +
'<button type="button" class="gev-guide-offer" hidden></button>' +
'<button type="button" class="gev-guide-next"></button></span></div>' +
// 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.
'<p class="gev-guide-status" role="status" aria-live="polite"></p></div>';
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);
+111
View File
@@ -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');
});
+5 -4
View File
@@ -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;
+89
View File
@@ -0,0 +1,89 @@
<script setup>
import { ref } from 'vue';
import UiButton from '../../kit/UiButton.vue';
import UiCloseButton from '../../kit/UiCloseButton.vue';
// The Omnibar's guided walk: the spotlight ring and the callout beside it,
// teleported to the end of `to` (the page's body). `startGuide()` in
// src/ui/omnibarGuide.js owns every decision and every word: it renders this
// with the `view` it computes for each step and keeps the parts the template
// never binds: the guide's `visible` class, the callout's entrance replay
// (its `swap` class), place and side, the ring's and the extra rings' boxes,
// and focus. The elements those parts need are exposed.
defineProps({
to: { type: Object, required: true },
view: { type: Object, required: true },
onClose: { type: Function, required: true },
onSkip: { type: Function, required: true },
onOffer: { type: Function, required: true },
onNext: { type: Function, required: true },
});
const root = ref(null);
const ring = ref(null);
const callout = ref(null);
defineExpose({ root, ring, callout });
/** A progress segment's attributes: no class at all for one still to come. */
const dot = (name) => (name ? { class: name } : {});
</script>
<!-- Only line breaks inside tags: the markup has no whitespace between elements. -->
<template><Teleport :to="to"
><div ref="root" class="gev-guide"
><div ref="ring" class="gev-guide-ring"><i></i></div
><div
ref="callout"
class="gev-guide-callout"
role="dialog"
aria-modal="false"
tabindex="-1"
aria-labelledby="gev-guide-title"
aria-describedby="gev-guide-text"
><div class="gev-guide-head"
><p id="gev-guide-title" class="gev-guide-title">{{ view.title }}</p
><p class="gev-guide-count">{{ view.count }}</p
><UiCloseButton
class="gev-guide-close"
:label="view.endLabel"
:title="view.endLabel"
@click="onClose()" /></div
><ol class="gev-guide-progress" aria-hidden="true"
><li
v-for="(name, i) in view.progress"
:key="`${view.step}-${i}`"
v-bind="dot(name)"></li></ol
><div class="gev-guide-body"
><p id="gev-guide-text" class="gev-guide-text">{{ view.text }}</p
><p class="gev-guide-hint" :hidden="view.hintHidden"
><span class="gev-guide-hint-dot"></span
><span>{{ view.hint }}</span></p
></div
><div class="gev-guide-actions"
><p class="gev-guide-keys" :hidden="view.keysHidden"
><kbd>{{ view.keyCap }}</kbd><span>{{ view.keyText }}</span></p
><span
><UiButton
class="gev-guide-skip"
:hidden="view.skipHidden"
@click="onSkip()"
>{{ view.skipLabel }}</UiButton
><UiButton
class="gev-guide-offer"
:hidden="view.offerHidden"
@click="onOffer()"
>{{ view.offerLabel }}</UiButton
><UiButton
class="gev-guide-next"
:class="{ quiet: view.nextQuiet }"
:hidden="view.nextHidden"
@click="onNext()"
>{{ view.nextLabel }}</UiButton
></span
></div
><p class="gev-guide-status" role="status" aria-live="polite">{{
view.status
}}</p></div
></div
></Teleport
></template>