Files
gods-eye-view/src/ui/omnibarGuide.js
T
Sameh KhamisandManjunath Paparaju 40cbe52782 Vue kit: the small surfaces' buttons and glyphs are kit controls
Every hand-written <button> in the locale picker, phone tab bar, globe
actions (Clear, Share, Reset) and compass, imagery divider handle, scene
sharing dialog, layer group index, title logo, Exit clean view, the HUD's
cockpit entry, News card face, rail card header, layer row toggle, credits
line's Data attribution and the camera calibration chips is a ghost
UiButton keeping its id, classes, data-*, aria-* and listeners. Their
Material Symbols spans (tab icons, globe actions, compass needle, cockpit
entry, celestial ring sun and moon) are UiIcons with :size="null".

The Omnibar guide's extra rings, one per further target of a step, are now
drawn by OmnibarGuide.vue from view.subRings instead of being built in
script; startGuide() still reads them from the rendered tree and sets
their boxes each frame.

A UiButton's slot renders inside the button, so under an owner that
patches synchronously (News cards, rail cards, the credits line, the
Omnibar guide's Skip, Offer and Next) a change the button's attributes do
not carry would land a tick late. Those slots are given under a named
condition that is always true (v-if="redrawWithView"), which Vue redraws
with the view.

src/ui/kit/smallSurfacesControls.test.mjs pins it; docs/VUE-MIGRATION.md
describes the surface and the conditional slot.

Co-authored-by: Manjunath Paparaju <[email protected]>
2026-11-19 10:44:16 -08:00

723 lines
24 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// "Show me how": a short guided walk through the real controls. Each step
// spotlights the control to press, explains it in one line, and waits until
// the visitor presses it (or the step is already done), then moves on. It
// does not press the controls the walk is about. A layer walk clears
// layer-list filter chips only when they would hide the row it is about;
// steps scroll their target into view.
//
// The callout is a non-modal dialog: focus moves to it when a walk starts,
// the rest of the page stays usable (the walk is about pressing it), Escape
// ends the walk and no other key is taken.
//
// Recipes are data: any data layer gets one from its id, and the main
// 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';
const MOBILE_PANELS = {
'data-panel': 'layers',
'pp-toggles': 'more',
'global-context-panel': 'context',
};
const SEARCH_BUTTON = '#layer-finder-search-btn';
const SEARCH_INPUT = '#layer-finder-input';
const FILTER_BUTTON = '#data-panel .layer-finder__filter button';
const AIRCRAFT_LAYERS = new Set(['flights', 'military', 'local-adsb']);
/** Above this altitude (metres) the camera already shows the globe. */
const GLOBE_ALTITUDE = 2_500_000;
/**
* Layers spread wider than a street-level view, and the camera altitude
* (metres) from which enough of them are in frame. Traffic layers spread over
* a region: aircraft cruise kilometres up across hundreds of kilometres, so
* from a low, tilted camera almost none are in view. Global layers read best
* from the globe view.
*/
const VIEW_ALTITUDE = Object.freeze({
flights: 150_000,
military: 400_000,
'local-adsb': 60_000,
'ais-live-vessels': 120_000,
satellites: GLOBE_ALTITUDE,
'rocket-launches': GLOBE_ALTITUDE,
'weather-cyclones': GLOBE_ALTITUDE,
'telegeography-submarine-cables': GLOBE_ALTITUDE,
earthquakes: GLOBE_ALTITUDE,
'local-firms': GLOBE_ALTITUDE,
'weather-satellite': GLOBE_ALTITUDE,
});
const $ = (selector, doc = globalThis.document) => doc?.querySelector(selector);
/** The camera altitude from the share hash, the app's own record of it. */
function cameraAltitude() {
const alt = Number(
new URLSearchParams(globalThis.location?.hash.slice(1) || '').get('alt'),
);
return Number.isFinite(alt) ? alt : 0;
}
const pressed = (selector) =>
$(selector)?.getAttribute('aria-pressed') === 'true';
const screenIsOwned = (doc) =>
EXCLUSIVE_SURFACE_CLASSES.some((name) => doc.body.classList.contains(name));
/** Steps that open a side panel from its rail, unless it is already open. */
function openPanelSteps(rail, item, label) {
const button = () =>
MOBILE_PANELS[item] &&
globalThis.document?.body.classList.contains('mobile-shell')
? $(`#mobile-tab-bar [data-mobile-sheet="${MOBILE_PANELS[item]}"]`)
: $(`${rail}[data-rail-item="${item}"]`);
return [
{
targets: () => [button()],
text: () => t('Open {panel}', { panel: label }),
done: () =>
button()?.getAttribute('aria-pressed') === 'true' ||
button()?.getAttribute('aria-expanded') === 'true',
},
];
}
/** Steps that open the Visual panel from the left rail. */
function openVisualSteps() {
return openPanelSteps(LEFT_RAIL, 'pp-toggles', t('Visual'));
}
/** Steps that bring up a section of Context's Properties tab. */
function propertiesSteps(section, text) {
const pane = `#context-tab-${section}`;
const tab = () => $('#context-tab-btn-props');
return [
...openPanelSteps(RIGHT_RAIL, 'global-context-panel', t('Context')),
{
targets: () => [tab()],
text: () => t('Open Properties: settings for the layers that are on'),
skip: () => !tab(),
done: () => tab()?.getAttribute('aria-selected') === 'true',
},
{
prepare: () => $(pane)?.scrollIntoView?.({ block: 'center' }),
targets: () => [$(pane)?.closest('.context-props__section') || $(pane)],
text,
skip: () => !$(pane)?.offsetParent,
},
];
}
const rowHidden = (selector) =>
Boolean($(selector)?.classList.contains('is-filtered'));
const hasSearchQuery = () => Boolean($(SEARCH_INPUT)?.value.trim());
/**
* The settings that change what a layer shows: its own option chips in the
* Data layers row, then, where they apply, the Display panel's detection
* labels and how dense they are.
* @param {{id: string, shown: string}} layer
*/
export function layerSettingsGuide(layer) {
const rowSelector = `[data-layer-id="${layer.id}"]`;
const controls = `${rowSelector} .data-toggle-controls`;
const chipNames = () =>
[...(globalThis.document?.querySelectorAll(`${controls} button`) || [])]
.map((chip) => {
const name = chip.textContent.trim();
const what = chip.getAttribute('title');
// The title as translated: lowering its first letter is wrong in
// German and other languages.
return what ? `${name}: ${what}` : name;
})
.filter(Boolean)
.join(' · ');
return [
...openPanelSteps(LEFT_RAIL, 'data-panel', t('Data layers')),
{
prepare: () => $(rowSelector)?.scrollIntoView?.({ block: 'center' }),
targets: () => [$(controls)],
text: () =>
chipNames()
? t('{layer} options. {options}', {
layer: layer.shown,
options: chipNames(),
})
: t('{layer} options appear here once it has loaded.', {
layer: layer.shown,
}),
skip: () => !$(controls),
},
// Labels and 3D models now sit in Context's Properties while their
// layers are on.
...(LABEL_LAYERS.has(layer.id)
? propertiesSteps('labels', () =>
t(
'Labels tag {layer} on the map. Density sets how many are labelled; Fade and Outside set how they thin out beyond the scope.',
{
layer: layer.shown,
},
),
)
: []),
...(AIRCRAFT_LAYERS.has(layer.id)
? propertiesSteps('aircraft', () =>
t(
'3D models: Proximity shows them up close only, All shows every aircraft as a model.',
),
)
: []),
];
}
/**
* The walk for one data layer.
* @param {{id: string, shown: string}} layer
* @param {(id: string) => boolean} isEnabled
* @param {{readAltitude?: () => number}} [options] Current camera altitude in metres.
*/
export function layerGuide(
layer,
isEnabled,
{ readAltitude = cameraAltitude } = {},
) {
const rowSelector = `[data-layer-id="${layer.id}"]`;
return [
// The walk asks for Data layers to be opened (or skips that when it is
// open); it closes no panel the visitor has open.
...openPanelSteps(LEFT_RAIL, 'data-panel', t('Data layers')),
{
// A filter left on from before could hide the row; start from the full list.
prepare: () => {
if (rowHidden(rowSelector) && !hasSearchQuery()) {
for (const chip of globalThis.document.querySelectorAll(
'#data-panel .layer-finder__chip',
))
chip.click();
}
},
targets: () => [$(SEARCH_BUTTON)],
text: () =>
t('Press search to find {layer} in the list', { layer: layer.shown }),
skip: () => isEnabled(layer.id) || !$(SEARCH_BUTTON),
done: () => pressed(SEARCH_BUTTON),
},
{
targets: () => [$(SEARCH_INPUT)],
text: () => t('Type {layer}', { layer: layer.shown }),
skip: () => isEnabled(layer.id) || !$(SEARCH_INPUT),
done: () => hasSearchQuery() && !rowHidden(rowSelector),
},
{
prepare: () => $(rowSelector)?.scrollIntoView?.({ block: 'center' }),
targets: () => [$(rowSelector), $(`${rowSelector} .data-toggle-btn`)],
text: () => t('Turn on {layer} with its switch', { layer: layer.shown }),
skip: () => isEnabled(layer.id),
done: () => isEnabled(layer.id),
},
{
// Too close to see them: zoom out (any way) or press the globe view.
targets: () => [$('#reset-globe-view')],
text: () =>
VIEW_ALTITUDE[layer.id] >= GLOBE_ALTITUDE
? t('{layer} are easiest to see from the globe view', {
layer: layer.shown,
})
: t(
'{layer} spread over a wide area, so few are in view this close. Zoom out, or press the globe view.',
{
layer: layer.shown,
},
),
skip: () =>
!VIEW_ALTITUDE[layer.id] || readAltitude() >= VIEW_ALTITUDE[layer.id],
done: () => readAltitude() >= VIEW_ALTITUDE[layer.id],
},
{
// The end: offer the settings that shape this layer.
text: () =>
t('{layer} is on. Want to fine-tune what it shows?', {
layer: layer.shown,
}),
offer: {
label: () => t('Show settings'),
steps: () => layerSettingsGuide(layer),
},
},
];
}
/** Walks for features, keyed like the omnibar's commands. */
export const FEATURE_GUIDES = Object.freeze({
styles: () => [
...openVisualSteps(),
{
prepare: () =>
$('.visual-presets__grid')?.scrollIntoView?.({ block: 'center' }),
targets: () => [$('.visual-presets__grid')],
text: () =>
t('Pick a look: Normal, CRT, NVG, FLIR, Anime or Noir (keys 1–6)'),
},
],
'map-source': () => [
...openVisualSteps(),
{
prepare: () =>
$('#pp-toggles .visual-presets')?.scrollIntoView?.({ block: 'start' }),
targets: () => [$('#pp-toggles .visual-presets')],
text: () =>
t(
'Under Map source, pick the map underneath: Google 3D, Bing, Esri or OpenStreetMap',
),
},
],
hud: () => [
...openVisualSteps(),
{
prepare: () => $('#hud-toggle')?.scrollIntoView?.({ block: 'center' }),
targets: () => [$('#hud-toggle')],
text: () =>
t('Switch the HUD on or off here; Layout picks Tactical or Minimal'),
},
],
scope: () => [
...openVisualSteps(),
{
prepare: () => $('#scope-toggle')?.scrollIntoView?.({ block: 'center' }),
targets: () => [$('#scope-toggle')?.closest('.pp-toggle-group')],
text: () =>
t(
'Scope frames the view in a circle. Feather softens its edge, Opacity sets how dark it shades outside.',
),
},
],
clean: () => [
...openVisualSteps(),
{
prepare: () =>
$('#clean-view-toggle')?.scrollIntoView?.({ block: 'center' }),
targets: () => [$('#clean-view-toggle')],
text: () => t('Clean UI hides the panels and readouts for a clear view'),
},
],
'find-layer': () => [
...openPanelSteps(LEFT_RAIL, 'data-panel', t('Data layers')),
{
targets: () => [$(SEARCH_BUTTON)],
text: () => t('Press search, then type part of a layer name or source'),
done: () => pressed(SEARCH_BUTTON),
},
{
targets: () => [$(SEARCH_INPUT)],
text: () => t('Type to narrow the list; Esc clears it'),
done: hasSearchQuery,
},
{
targets: () => [$(FILTER_BUTTON)],
text: () =>
t('Filter shows only layers that are on or off, or one category'),
},
],
'filter-layers': () => [
...openPanelSteps(LEFT_RAIL, 'data-panel', t('Data layers')),
{
targets: () => [$(FILTER_BUTTON)],
text: () => t('Open the filter'),
done: () => $(FILTER_BUTTON)?.getAttribute('aria-expanded') === 'true',
},
{
targets: () => [$('.layer-finder__menu')],
text: () =>
t(
'Pick a status (On, Off) and a category; each shows as a chip you can clear',
),
},
],
'section-index': () => [
...openPanelSteps(LEFT_RAIL, 'data-panel', t('Data layers')),
{
targets: () => [$('.layer-section-index')],
text: () => t('Hover a tick to see its group; click to jump there'),
},
],
preferences: () => [
{
targets: () => [$('#corner-actions')],
text: () => t('Add provider keys with Power Up, or change the language'),
},
],
edge: () => [
...openPanelSteps(LEFT_RAIL, 'data-panel', t('Data layers')),
{
targets: () => [$('#data-panel .ui-panel-edge')],
text: () =>
t(
'Press this to slide panels over the rail to the screen edge; press again to bring them back',
),
},
],
context: () => [
...openPanelSteps(RIGHT_RAIL, 'global-context-panel', t('Context')),
{
targets: () => [$('#global-context-panel .cyber-panel-body')],
text: () =>
t(
'Context describes the view: weather, hazards, what your layers have nearby, and whatever you pick on the map',
),
},
],
properties: () =>
propertiesSteps('labels', () =>
t(
'Properties holds the settings for the layers that are on, each layer marked by a coloured dot',
),
),
north: () => [
{
targets: () => [$('#north-up-view')],
text: () => t('Press the compass to face north'),
},
],
tilt: () => [
{
targets: () => [$('#tilt-map-view')],
text: () => t('Tilt the camera for a 3D view'),
},
],
globe: () => [
{
targets: () => [$('#reset-globe-view')],
text: () => t('Zoom out to the whole globe'),
},
],
share: () => [
{
targets: () => [$('#share-btn')],
text: () => t('Copy a link to exactly this view'),
},
],
clear: () => [
{
targets: () => [$('#clear-selected-layers')],
text: () => t('Turn off every layer at once'),
},
],
// Drawing, and measuring with it: a line shows its length and an area its
// size while it is drawn (src/annotations/drawMode.js).
draw: () => [
...openPanelSteps(LEFT_RAIL, 'utilities-panel', t('Utilities')),
{
prepare: () => $('#draw-group')?.scrollIntoView?.({ block: 'center' }),
targets: () => [$('#draw-toggle')],
text: () => t('Press Draw to start drawing on the map'),
skip: () => pressed('#draw-toggle'),
done: () => pressed('#draw-toggle'),
},
{
targets: () => [$('#draw-mode-row')],
text: () =>
t(
'Pick Line to measure a distance or Area for its size, then click points on the map; double-click or Enter finishes',
),
},
],
});
/** The omnibar command ids that have a feature walk. */
export function featureGuideFor(commandId) {
if (commandId.startsWith('style-')) return 'styles';
if (commandId.startsWith('map-')) return 'map-source';
if (commandId.startsWith('hud-')) return 'hud';
if (commandId === 'reset') return 'globe';
return FEATURE_GUIDES[commandId] ? commandId : null;
}
let active = null;
/**
* Run a walk. Starting another ends the one in progress.
* @param {Array<object>} steps
* @param {{title?: string}} [options]
*/
export function startGuide(steps, { title = '' } = {}) {
active?.stop();
const doc = globalThis.document;
if (!doc?.body || screenIsOwned(doc) || !steps?.length) return;
// 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,
// The extra rings for a step's further targets, after the callout; the
// count only grows, and rings a step does not use are faded out.
subRings: 0,
// 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;
}
// Focus returns where it was when the walk ends, if that is still there.
const returnFocus = doc.activeElement;
// 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');
// The extra rings, read again from the rendered tree whenever more are
// drawn.
let subRings = [];
const live = steps.filter(Boolean);
let index = -1;
let frame = 0;
let advanceTimer = 0;
let stopped = false;
let current = null;
let shown = 0;
const stop = () => {
if (stopped) return;
stopped = true;
cancelAnimationFrame(frame);
clearInterval(poll);
clearTimeout(advanceTimer);
resizeObserver?.disconnect();
globalThis.removeEventListener?.('resize', schedule);
doc.removeEventListener('scroll', schedule, true);
doc.removeEventListener('click', onClick, true);
doc.removeEventListener('keydown', onKey, true);
const hadFocus = root.contains(doc.activeElement);
mounted = false;
renderVue(null, host);
if (hadFocus && returnFocus?.isConnected) returnFocus.focus?.();
if (active?.stop === stop) active = null;
};
const next = () => {
clearTimeout(advanceTimer);
advanceTimer = 0;
void run(index + 1);
};
const advance = () => {
if (advanceTimer) return;
advanceTimer = setTimeout(next, 350);
};
async function run(at) {
if (stopped) return;
if (screenIsOwned(doc)) return stop();
current = null;
index = at;
const step = live[index];
if (!step) return stop();
await step.prepare?.();
if (stopped || at !== index) return;
if (step.skip?.() || step.done?.()) return run(index + 1);
current = step;
shown += 1;
// The total is what is shown so far plus the steps still to come that
// would not be skipped as things stand.
const total =
shown + live.slice(index + 1).filter((later) => !later.skip?.()).length;
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();
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;
view.hintHidden = !waits;
view.offerHidden = !step.offer;
view.skipHidden = !step.offer;
view.keysHidden = Boolean(step.offer);
if (step.offer) {
view.offerLabel = step.offer.label();
view.skipLabel = t('Not now');
}
const last = index === live.length - 1;
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;
callout.classList.add('swap');
root.classList.add('visible');
schedule();
}
// The visitor pressed the spotlit control: give the app a moment to react,
// then move on (or let `done` decide, for steps that wait on a state).
function onClick(event) {
if (!current || callout.contains(event.target)) return;
const [target] = current.targets?.() || [];
if (target?.contains(event.target) && !current.done) advance();
}
// Only Escape is the walk's: it ends the walk and nothing else (the
// Omnibar or a panel behind it stays as it is). Every other key goes on to
// the page untouched.
function onKey(event) {
if (screenIsOwned(doc)) {
stop();
return;
}
if (event.key !== 'Escape' || event.isComposing) return;
event.preventDefault();
event.stopPropagation();
stop();
}
doc.addEventListener('click', onClick, true);
doc.addEventListener('keydown', onKey, true);
// Follow the targets as panels open and scroll, and notice when a step's
// goal is reached however it happened: on resize and scroll, when the page
// changes size, and otherwise four times a second (panels slide open
// without an event to follow). Each is at most one frame's work.
let poll = 0;
let resizeObserver = null;
function schedule() {
if (stopped || frame) return;
frame = requestAnimationFrame(() => {
frame = 0;
place();
});
}
const place = () => {
if (screenIsOwned(doc)) return stop();
if (!current) return;
if (current.done?.()) advance();
const targets = (current.targets?.() || []).filter(Boolean);
const [main, ...rest] = targets.map((element) =>
element.getBoundingClientRect(),
);
if (!main || !main.width) {
// Nothing to point at (the closing offer): centre the callout.
ring.style.opacity = '0';
subRings.forEach((sub) => (sub.style.opacity = '0'));
callout.dataset.side = 'none';
callout.style.left = `${(innerWidth - (callout.offsetWidth || 280)) / 2}px`;
callout.style.top = `${innerHeight * 0.32}px`;
return;
}
const pad = 6;
Object.assign(ring.style, {
opacity: '1',
left: `${main.left - pad}px`,
top: `${main.top - pad}px`,
width: `${main.width + pad * 2}px`,
height: `${main.height + pad * 2}px`,
});
if (subRings.length < rest.length) {
view.subRings = rest.length;
paint();
subRings = [...root.querySelectorAll(':scope > .gev-guide-ring--sub')];
}
subRings.forEach((sub, i) => {
const box = rest[i];
Object.assign(
sub.style,
box?.width
? {
opacity: '1',
left: `${box.left - 4}px`,
top: `${box.top - 4}px`,
width: `${box.width + 8}px`,
height: `${box.height + 8}px`,
}
: { opacity: '0' },
);
});
// The callout sits beside the target, on whichever side has room.
const width = callout.offsetWidth || 280;
const height = callout.offsetHeight || 120;
const gap = 18;
const right = main.right + pad + gap;
const onRight = right + width < innerWidth - 12;
const left = onRight ? right : Math.max(12, main.left - pad - gap - width);
const centre = main.top + main.height / 2;
const top = Math.max(
12,
Math.min(innerHeight - height - 12, centre - height / 2),
);
// The arrow points at the target's middle, kept inside the callout.
callout.dataset.side = onRight ? 'right' : 'left';
callout.style.setProperty(
'--gev-guide-arrow-y',
`${Math.min(height - 18, Math.max(18, centre - top))}px`,
);
callout.style.left = `${left}px`;
callout.style.top = `${top}px`;
};
globalThis.addEventListener?.('resize', schedule);
doc.addEventListener('scroll', schedule, true);
if (typeof ResizeObserver === 'function') {
resizeObserver = new ResizeObserver(schedule);
resizeObserver.observe(doc.body);
}
// A hidden tab has nothing to follow: the poll rests until it is shown.
poll = setInterval(() => {
if (!doc.hidden) schedule();
}, 250);
schedule();
callout.focus({ preventScroll: true });
active = { stop };
void run(0);
return stop;
}