feat(earthquakes): select quakes by click and show their details

Clicking a quake's disc selects it and shows a card with its magnitude and
USGS class, a class meter with the depth band, place, UTC time and source.
With a USGS event id the card opens the event page. Clicking a magnitude
label, the part a far view can hit, also flies the camera to the quake. The
selection joins the shared context selection, so "what's selected" answers
with it.

The selected disc is painted with a gradient that fades to its outer circle,
and wavy contour lines run out from the marker for three cycles while it is
on screen, then rest as still contours, so a parked camera returns to idle.
A feed refresh updates the selection in place without restarting the lines
or taking back the shared selection.

The package takes input, picking, context, focus, the opener, the painter
and the translator by injection; without them it draws as before.
This commit is contained in:
manjunath22466 committed 2026-11-16 17:55:29 +05:30
1 parent da81cf743b
commit a8ac8eeb9b
25 files changed
+2292 -34

No files matched your search

+292
View File
@@ -123,6 +123,298 @@ export function createEarthquakeOverlayEntry({
};
}
/** Where USGS publishes one event's page, its event id appended. */
export const USGS_EVENT_PAGE_URL =
'https://earthquake.usgs.gov/earthquakes/eventpage/';
/**
* The USGS page for an event id, or null when there is no usable id (a
* fallback `event-N` id never names a USGS page, and is never sent).
* @param {unknown} usgsId
* @returns {string|null}
*/
export function earthquakeEventLink(usgsId) {
const id =
typeof usgsId === 'string' || typeof usgsId === 'number'
? String(usgsId).trim()
: '';
return /^[A-Za-z0-9_-]{1,64}$/.test(id)
? `${USGS_EVENT_PAGE_URL}${id}`
: null;
}
// The package carries no i18n: with no translator given, the card stays
// English, its `{name}` slots filled in.
const english = (text, values) =>
String(text).replace(/\{(\w+)\}/g, (all, key) =>
values && Object.hasOwn(values, key) ? String(values[key]) : all,
);
const utcMinute = (time) =>
`${new Date(time).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
const oneDecimal = (value) => String(Math.round(value * 10) / 10);
/**
* The detail card one clicked earthquake shows: its magnitude as the title,
* then where, when and how deep, and the source. With a USGS event id the
* card opens that event's page.
* @param {{mag: number, place?: string|null, time?: number|null,
* depthKm?: number|null, usgsId?: string|null}} event
* @param {object} [text] The application's formatters.
* @param {(text: string, values?: object) => string} [text.t] Translator.
* @param {(time: number) => string} [text.formatTime] An event time.
* @param {(value: number) => string} [text.formatDepth] A depth in km.
* @returns {{title: string, details: string[], link: string|null,
* accessibilityLabel: string}}
*/
export function describeEarthquake(
event,
{ t = english, formatTime = utcMinute, formatDepth = oneDecimal } = {},
) {
const details = [];
// Severity at a glance, right under the title: the class meter, then
// where in the crust it broke.
const glance = [earthquakeSeverityMeter(event?.mag)];
if (Number.isFinite(event?.depthKm)) {
glance.push(
`${earthquakeDepthBandName(event.depthKm, t)} · ${t('{km} km deep', {
km: formatDepth(event.depthKm),
})}`,
);
}
details.push(glance.join(' '));
const place =
typeof event?.place === 'string'
? event.place.replace(/\s+/g, ' ').trim()
: '';
if (place) details.push(place);
if (Number.isFinite(event?.time)) details.push(formatTime(event.time));
details.push(t('Source: {value}', { value: 'USGS' }));
const link = earthquakeEventLink(event?.usgsId);
if (link) details.push(t('Click the card to open the source ↗'));
const title = `${earthquakeMagnitudeTitle(event?.mag)} · ${earthquakeSeverityName(
event?.mag,
t,
)}`;
return {
title,
details,
link,
accessibilityLabel: t('Open the source for {title}', { title }),
};
}
/**
* USGS's magnitude classes, weakest first: minor (under 4; the feed starts
* at M2.5), light, moderate, strong, major, great (8 and up).
*/
export const EARTHQUAKE_SEVERITY_LEVELS = 6;
/**
* A magnitude's USGS class, 0 (minor) to 5 (great).
* @param {number} magnitude
* @returns {number}
*/
export function earthquakeSeverityLevel(magnitude) {
const mag = Number(magnitude);
if (!Number.isFinite(mag) || mag < 4) return 0;
return Math.min(EARTHQUAKE_SEVERITY_LEVELS - 1, Math.floor(mag) - 3);
}
/** A magnitude's class, as a word in the page's language. */
export function earthquakeSeverityName(magnitude, t = english) {
switch (earthquakeSeverityLevel(magnitude)) {
case 5:
return t('Great', { context: 'earthquake' });
case 4:
return t('Major', { context: 'earthquake' });
case 3:
return t('Strong', { context: 'earthquake' });
case 2:
return t('Moderate', { context: 'earthquake' });
case 1:
return t('Light', { context: 'earthquake' });
default:
return t('Minor', { context: 'earthquake' });
}
}
/**
* The class as a six-step meter, one filled block per class up to this one:
* `■■□□□□` for a light quake. Plain text, so the card shows it as it is.
* @param {number} magnitude
* @returns {string}
*/
export function earthquakeSeverityMeter(magnitude) {
const filled = earthquakeSeverityLevel(magnitude) + 1;
return '■'.repeat(filled) + '□'.repeat(EARTHQUAKE_SEVERITY_LEVELS - filled);
}
/**
* The depth band the disc's colour shows, as a word: shallow (under 70 km,
* red), intermediate (to 300 km, orange), deep (yellow).
*/
export function earthquakeDepthBandName(depthKm, t = english) {
const band = depthBand(depthKm);
if (band === SHALLOW) return t('Shallow', { context: 'earthquake' });
if (band === INTERMEDIATE)
return t('Intermediate', { context: 'earthquake' });
return t('Deep', { context: 'earthquake' });
}
/**
* A quake's disc radius on the ground, in metres: it doubles with each
* magnitude step (about 5.7 km at M2.5, 32 km at M5, 64 km at M6).
* @param {number} magnitude
* @returns {number}
*/
export const earthquakeDiscRadiusM = (magnitude) =>
Math.pow(2, magnitude) * 1000;
/** How many contour lines run out from a selected quake at once. */
export const EARTHQUAKE_RIPPLE_RINGS = 6;
/** How long one contour line takes from the marker to the disc's edge. */
export const EARTHQUAKE_RIPPLE_PERIOD_MS = 4800;
/** Every this many lines one is an index contour, drawn heavier. */
export const EARTHQUAKE_INDEX_CONTOUR_EVERY = 3;
/**
* How far a contour line dents in from the circle, as a share of its
* radius. Kept with the drift below so nested lines never cross: a line's
* radius grows with `fraction` faster than its dents move (see
* earthquakeContourScale).
*/
export const EARTHQUAKE_CONTOUR_WOBBLE = 0.24;
const CONTOUR_HARMONICS = Object.freeze([2, 3, 5]);
const CONTOUR_WEIGHTS = Object.freeze([1, 0.6, 0.3]);
const CONTOUR_MAX_DRIFT = 1.5;
/** A stable 32-bit hash of a string (FNV-1a). */
function hashString(text) {
let h = 0x811c9dc5;
for (const ch of String(text ?? '')) {
h ^= ch.codePointAt(0);
h = Math.imul(h, 0x01000193);
}
return h >>> 0;
}
/**
* One quake's contour shape: a few harmonics around the circle, each with
* its own phase and a drift that turns it as a line runs outward, seeded by
* the quake's id so the same quake always draws the same contours.
* @param {string} seed The quake's stable id.
* @returns {ReadonlyArray<{harmonic: number, weight: number, phase: number, drift: number}>}
*/
export function earthquakeContourShape(seed) {
let state = hashString(seed) || 1;
// xorshift32: a small, stable stream from the seed.
const next = () => {
state ^= state << 13;
state ^= state >>> 17;
state ^= state << 5;
return (state >>> 0) / 0x100000000;
};
return Object.freeze(
CONTOUR_HARMONICS.map((harmonic, i) =>
Object.freeze({
harmonic,
weight: CONTOUR_WEIGHTS[i],
phase: next() * 2 * Math.PI,
drift: (next() * 2 - 1) * CONTOUR_MAX_DRIFT,
}),
),
);
}
/**
* Where a contour line runs at `angle` (radians), as a share of a circle of
* the same `fraction`: between 1 - EARTHQUAKE_CONTOUR_WOBBLE and 1, so the
* outermost line never leaves the disc. The dents turn as `fraction` grows,
* and no faster than the line grows, so lines never cross: with wobble A
* and drift D, d(fraction · scale)/d(fraction) ≥ 1 - A - A·D/2 > 0.
* @param {ReturnType<typeof earthquakeContourShape>} shape
* @param {number} angle
* @param {number} fraction 0 at the marker, 1 at the disc's edge.
* @returns {number}
*/
export function earthquakeContourScale(shape, angle, fraction) {
let sum = 0;
let total = 0;
for (const { harmonic, weight, phase, drift } of shape) {
sum += weight * Math.sin(harmonic * angle + phase + drift * fraction);
total += weight;
}
const n = total > 0 ? sum / total : 0;
return 1 - (EARTHQUAKE_CONTOUR_WOBBLE * (1 - n)) / 2;
}
/**
* The selected quake's contour lines at a time: each runs from the marker
* (`fraction` 0) out to the disc's edge (1), evenly staggered, fading in
* just after it starts and out as it reaches the edge; every
* EARTHQUAKE_INDEX_CONTOUR_EVERY-th is an index contour. Pure: the painter
* gives the clock.
* @param {number} timeMs Any steady clock, in milliseconds.
* @param {{count?: number, periodMs?: number}} [options]
* @returns {Array<{fraction: number, alpha: number, index: boolean}>}
*/
export function earthquakeRippleRings(
timeMs,
{
count = EARTHQUAKE_RIPPLE_RINGS,
periodMs = EARTHQUAKE_RIPPLE_PERIOD_MS,
} = {},
) {
const phase = Number.isFinite(timeMs) && periodMs > 0 ? timeMs / periodMs : 0;
const rings = [];
for (let k = 0; k < count; k++) {
const fraction = (((phase + k / count) % 1) + 1) % 1;
rings.push({
fraction,
alpha: earthquakeRippleAlpha(fraction),
index: k % EARTHQUAKE_INDEX_CONTOUR_EVERY === 0,
});
}
return rings;
}
/**
* Still contour lines, for viewers who ask for reduced motion: the same
* lines as the animation, held evenly spaced out to the edge.
* @param {number} [count]
* @returns {Array<{fraction: number, alpha: number, index: boolean}>}
*/
export function earthquakeContourRings(count = EARTHQUAKE_RIPPLE_RINGS) {
const rings = [];
for (let k = 1; k <= count; k++)
rings.push({
fraction: k / count,
alpha: 0.7,
index: k % EARTHQUAKE_INDEX_CONTOUR_EVERY === 0,
});
return rings;
}
const RIPPLE_FADE_IN = 0.12;
/** A ring's opacity where it is: in from 0 near the marker, out to 0 at the edge. */
function earthquakeRippleAlpha(fraction) {
if (fraction <= 0 || fraction >= 1) return 0;
return fraction < RIPPLE_FADE_IN
? fraction / RIPPLE_FADE_IN
: (1 - fraction) / (1 - RIPPLE_FADE_IN);
}
/**
* What a magnitude label says to assistive technology: activating it zooms
* to the quake (`Zoom to M5.0 · 42 km SW of Anchorage, Alaska`).
* @param {{mag: number, place?: string|null}} event
* @param {{t?: (text: string, values?: object) => string}} [text]
* @returns {string}
*/
export function earthquakeZoomLabel(event, { t = english } = {}) {
return t('Zoom to {name}', { name: earthquakeMarkLabel(event) });
}
/** Keep the largest events, with stable identity as the tie-break. */
export function selectEarthquakeOverlayCohort(
entries,