geotimelapse 0.1.0

package/src/types.ts

@@ -0,0 +1,66 @@
+import type { GlowTuning } from './glow-layer.js';
+
+/** Visible map area in degrees, WGS84. */
+export interface MapBounds {
+  west: number;
+  south: number;
+  east: number;
+  north: number;
+}
+
+/** Events of one frame window, aggregated by location. */
+export interface FramePoints {
+  /** Interleaved [lon, lat] pairs, one per distinct location. */
+  positions: Float32Array;
+  /** Events at each location; the rendered point AREA is linear in it. */
+  weights: Float32Array;
+  /** Number of locations (positions holds 2x this many floats). */
+  count: number;
+}
+
+/** Cumulative totals since the start of the day. */
+export interface Totals {
+  count: number;
+  value: number;
+}
+
+/**
+ * A day of geolocated events, queryable by the component. Times are seconds
+ * since the day's midnight, in [0, 86400). Every read reflects the scope set
+ * by the latest setScope() call (null scope = everything).
+ */
+export interface GeoTimelapseSource {
+  /** Prepares the day (downloads, tables...). Called once on mount. */
+  load(onProgress?: (loadedBytes: number, totalBytes: number) => void): Promise<void>;
+  /** Events won during [fromSecond, toSecond), aggregated by location. */
+  frame(fromSecond: number, toSecond: number): Promise<FramePoints>;
+  /** Cumulative totals from midnight up to (excluding) `second`. */
+  totals(second: number): Promise<Totals>;
+  /** Event count for each of the day's 1440 minutes. */
+  activity(): Promise<Float32Array>;
+  /** Scopes subsequent totals() and activity() reads to the given viewport. */
+  setScope(bounds: MapBounds | null): Promise<void>;
+  /**
+   * Releases everything the source holds (workers, in-memory tables...). The
+   * source is unusable afterwards. The component never calls it: the owner
+   * who created the source disposes it when done.
+   */
+  dispose(): Promise<void>;
+}
+
+export interface GeoTimelapseProps {
+  source: GeoTimelapseSource;
+  mapboxAccessToken: string;
+  /** Area the map initially fits; defaults to the continental US. */
+  initialBounds?: MapBounds;
+  /** Overrides on the glow rendering knobs (see GlowTuning). Calibrate
+   *  pointAlpha to the day's density: the playback trail stacks 12 additive
+   *  frames, so dense datasets need it well below the bench value. */
+  tuning?: Partial<GlowTuning>;
+  /** Shown before the clock time, e.g. "Sat, Sep 5, 2026". */
+  dateLabel?: string;
+  /** Shown after the clock time, e.g. "EDT". */
+  timeZoneLabel?: string;
+  formatValue?: (value: number) => string;
+  formatCount?: (count: number) => string;
+}

package/src/utils.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { formatDayTime, formatDayTime12, formatDayTime24, formatHourLabel } from './utils.js';
+
+describe('formatDayTime', () => {
+  it('formats midnight', () => {
+    assert.equal(formatDayTime(0), '00:00:00');
+  });
+
+  it('truncates fractional seconds', () => {
+    assert.equal(formatDayTime(59.9), '00:00:59');
+    assert.equal(formatDayTime(3661), '01:01:01');
+  });
+
+  it('pads every unit', () => {
+    assert.equal(formatDayTime(7 * 3600 + 5 * 60 + 3), '07:05:03');
+  });
+
+  it('formats the last second and the end of day', () => {
+    assert.equal(formatDayTime(86399), '23:59:59');
+    assert.equal(formatDayTime(86400), '24:00:00');
+  });
+
+  it('clamps negative values', () => {
+    assert.equal(formatDayTime(-10), '00:00:00');
+  });
+});
+
+describe('formatDayTime12', () => {
+  it('formats midnight and noon on the 12-hour clock', () => {
+    assert.equal(formatDayTime12(0), '12:00 AM');
+    assert.equal(formatDayTime12(12 * 3600), '12:00 PM');
+  });
+
+  it('formats morning and afternoon times', () => {
+    assert.equal(formatDayTime12(2 * 3600 + 30 * 60), '2:30 AM');
+    assert.equal(formatDayTime12(13 * 3600 + 5 * 60), '1:05 PM');
+  });
+
+  it('wraps the end of day back to midnight', () => {
+    assert.equal(formatDayTime12(86400), '12:00 AM');
+  });
+});
+
+describe('formatDayTime24', () => {
+  it('formats without a leading zero on the hour', () => {
+    assert.equal(formatDayTime24(2 * 3600 + 30 * 60), '2:30');
+    assert.equal(formatDayTime24(13 * 3600 + 5 * 60), '13:05');
+  });
+});
+
+describe('formatHourLabel', () => {
+  it('labels the day boundaries and afternoon hours', () => {
+    assert.equal(formatHourLabel(0), '0:00');
+    assert.equal(formatHourLabel(2), '2:00');
+    assert.equal(formatHourLabel(13), '13:00');
+    assert.equal(formatHourLabel(24), '24:00');
+  });
+});

package/src/utils.ts

@@ -0,0 +1,32 @@
+import { format } from 'date-fns';
+
+/** Manual on purpose: the end-of-day marker 24:00:00 has no date-fns spelling. */
+export function formatDayTime(daySeconds: number): string {
+  const total = Math.max(Math.floor(daySeconds), 0);
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = total % 60;
+  const pad = (value: number) => String(value).padStart(2, '0');
+  return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
+}
+
+// An arbitrary DST-free local date carrying a time of day for date-fns.
+function dayTimeAsDate(daySeconds: number): Date {
+  const total = Math.max(Math.floor(daySeconds), 0);
+  return new Date(2000, 0, 1, Math.floor(total / 3600) % 24, Math.floor((total % 3600) / 60), total % 60);
+}
+
+/** US-style clock time, e.g. "2:30 AM"; the end of day wraps to "12:00 AM". */
+export function formatDayTime12(daySeconds: number): string {
+  return format(dayTimeAsDate(daySeconds), 'h:mm a');
+}
+
+/** Compact 24-hour time, e.g. "2:30" or "13:05". */
+export function formatDayTime24(daySeconds: number): string {
+  return format(dayTimeAsDate(daySeconds), 'H:mm');
+}
+
+/** Compact 24-hour label for a full hour, e.g. 2 → "2:00"; 24 marks the end of day. */
+export function formatHourLabel(hour: number): string {
+  return hour === 24 ? '24:00' : formatDayTime24(hour * 3600);
+}