Timeline marks carry labels; a tap by a tick goes to its mark

A layer's world clock coverage may now give each mark as an object,
{ time, label?, id?, kind? }, as well as a bare epoch ms number, and the
two may be mixed. worldClock.coverage() keeps marks as the sorted list of
distinct times, so existing readers are unchanged, and adds markDetails:
the merged marks in time order (then kind, label and id), each frozen and
holding only the fields given. Marks given alike by several sources appear
once, a bare time is dropped where a labelled mark shares it, and a mark
with no finite time is ignored. The contract is documented in the
worldClock JSDoc and docs/APPLICATION.md.

Launches label their marks with the mission's name (the launch's where it
has none), cut to 27 characters in capitals as the mission index shows
names. Earthquakes of magnitude 6 and up label theirs with the magnitude
as the map shows it and the feed's place cut to 40 characters, such as
"M6.4 · 113 km SSE of Lata, Solomon Islands"; the layer now tells the clock
when the labels change as well as the times.

On the timeline, a pointer within 6 px of a tick shows its label over the
track (nothing for an unlabelled mark), and a tap there goes exactly to
the mark's time instead of the point tapped. A tap elsewhere and a drag
work as before, and ticks stay ticks. The arrow keys still step from mark
to mark; with the handle on a mark, its labels follow the time in the
handle's aria-valuetext, and show over the track while it has focus.
This commit is contained in:
Sameh Khamis committed 2026-11-14 20:30:01 -08:00
1 parent 7cb854c923
commit 558e4a919a
17 files changed
+490 -50

No files matched your search

+1
View File
@@ -119,6 +119,7 @@ test('at the live edge a layer with a timeline only follows and registers', asyn
start: WALL - 3_600_000,
end: WALL,
marks: [],
markDetails: [],
});
assert.equal(h.follower.active(), false);
assert.deepEqual(h.calls, []);
+81 -5
View File
@@ -20,6 +20,49 @@
* (weather) do not drive it: they gate continuous play at their next frame.
*/
/**
* A timeline mark as a layer gives it: its time in epoch ms, and optionally
* a short label to show for it, the layer's own id for it and its kind.
* @typedef {{time: number, label?: string, id?: string, kind?: string}} WorldClockMarkInput
*/
/**
* A timeline mark as `coverage().markDetails` returns it: a finite time, and
* only those of `label`, `id` and `kind` that are non-empty strings.
* @typedef {Readonly<{time: number, label?: string, id?: string, kind?: string}>} WorldClockMark
*/
const MARK_TEXT = ['label', 'id', 'kind'];
/**
* A mark (a number, or `{time, label?, id?, kind?}`) in its one shape, or
* null for one with no finite time.
* @param {unknown} input
* @returns {WorldClockMark | null}
*/
function readMark(input) {
if (typeof input === 'number')
return Number.isFinite(input) ? Object.freeze({ time: input }) : null;
if (!input || typeof input !== 'object') return null;
const { time } = input;
if (typeof time !== 'number' || !Number.isFinite(time)) return null;
const mark = { time };
for (const key of MARK_TEXT) {
const value = input[key];
if (typeof value === 'string' && value.trim()) mark[key] = value.trim();
}
return Object.freeze(mark);
}
// Marks in time order; at one time, by kind, label and id, so the order
// never depends on which source registered first.
const byText = (a = '', b = '') => (a < b ? -1 : a > b ? 1 : 0);
const byMark = (a, b) =>
a.time - b.time ||
byText(a.kind, b.kind) ||
byText(a.label, b.label) ||
byText(a.id, b.id);
/** The span a JS Date can hold, either side of 1970. */
const MAX_DATE_MS = 8.64e15;
@@ -372,7 +415,15 @@ export function createWorldClock({
/**
* A layer's span of time it can show, for a host's timeline; null while
* it has none (off, or nothing loaded). Returns the unregister.
* @param {{id: string, coverage: () => ({start: number, end: number, marks?: number[]} | null)}} source
*
* `marks` are the moments in that span worth going to (a launch, a strong
* earthquake), drawn as ticks the timeline's arrow keys step to. Each is
* an epoch ms number, or `{time, label?, id?, kind?}`: `label` is short
* text the timeline shows for it (a name, `M6.4 · a place`), `id` the
* layer's own key for the event and `kind` what sort of event it is.
* Numbers and objects may be mixed; a mark with no finite time is
* ignored, as are a label, id or kind that is not a non-empty string.
* @param {{id: string, coverage: () => ({start: number, end: number, marks?: Array<number | WorldClockMarkInput>} | null)}} source
*/
register(source) {
// Each registration is its own, even under a shared id.
@@ -387,20 +438,45 @@ export function createWorldClock({
coverageChanged: () => changed(),
/** Whether a followed layer has time to show; see getState().supported. */
isSupported,
/** The union of the registered sources' coverage, or null with none. */
/**
* The union of the registered sources' coverage, or null with none:
* `{start, end, marks, markDetails}`. `marks` is every mark's time, once
* each, in order, as numbers. `markDetails` is the marks themselves, in
* time order, each `{time, label?, id?, kind?}` (frozen): a mark several
* sources give alike is there once, and a bare time is dropped where a
* mark with more to say shares it.
* @returns {{start: number, end: number, marks: number[], markDetails: WorldClockMark[]} | null}
*/
coverage() {
let start = Infinity;
let end = -Infinity;
const marks = new Set();
const details = new Map();
for (const { source } of sources) {
const span = spanOf(source);
if (!span) continue;
start = Math.min(start, span.start);
end = Math.max(end, span.end);
for (const mark of span.marks ?? []) marks.add(mark);
for (const input of span.marks ?? []) {
const mark = readMark(input);
if (!mark) continue;
const key = JSON.stringify([
mark.time,
mark.label,
mark.id,
mark.kind,
]);
if (!details.has(key)) details.set(key, mark);
}
}
if (start > end) return null;
return { start, end, marks: [...marks].sort((a, b) => a - b) };
const told = new Set();
for (const mark of details.values())
if (Object.keys(mark).length > 1) told.add(mark.time);
const markDetails = [...details.values()]
.filter((mark) => Object.keys(mark).length > 1 || !told.has(mark.time))
.sort(byMark);
const marks = [...new Set(markDetails.map((mark) => mark.time))];
return { start, end, marks, markDetails };
},
getState,
+52 -1
View File
@@ -253,9 +253,60 @@ test('coverage is the union of the registered sources', () => {
start: 50,
end: 200,
marks: [100, 150, 200],
markDetails: [{ time: 100 }, { time: 150 }, { time: 200 }],
});
off();
assert.deepEqual(clock.coverage(), { start: 50, end: 180, marks: [] });
assert.deepEqual(clock.coverage(), {
start: 50,
end: 180,
marks: [],
markDetails: [],
});
});
test('marks may carry a label, an id and a kind, and merge in one order', () => {
const clock = createWorldClock(fakeTime().options);
clock.register({
id: 'launches',
coverage: () => ({
start: 100,
end: 300,
marks: [
{ time: 300, label: ' ARTEMIS II ', id: 'a2', kind: 'launch' },
100,
{ time: 200, label: 'M6.4 · Fiji', kind: 'earthquake', extra: 1 },
],
}),
});
clock.register({
id: 'others',
coverage: () => ({
start: 100,
end: 300,
marks: [
200,
{ time: 200, label: 'M6.4 · Fiji', kind: 'earthquake' },
{ time: 200, label: 'ALPHA', kind: 'launch' },
{ time: 250, label: '', id: 7, kind: null },
{ time: Number.NaN, label: 'never' },
Number.POSITIVE_INFINITY,
null,
'soon',
],
}),
});
const covered = clock.coverage();
assert.deepEqual(covered.marks, [100, 200, 250, 300], 'the times, once each');
assert.deepEqual(covered.markDetails, [
{ time: 100 },
// A bare 200 says nothing a labelled mark there does not; alike marks
// from two sources are one.
{ time: 200, label: 'M6.4 · Fiji', kind: 'earthquake' },
{ time: 200, label: 'ALPHA', kind: 'launch' },
{ time: 250 },
{ time: 300, label: 'ARTEMIS II', id: 'a2', kind: 'launch' },
]);
assert.ok(covered.markDetails.every(Object.isFrozen));
});
test('seek refuses anything but epoch ms and rate must be positive', () => {