@bitbaum/geo-kit 0.1.1 → 0.2.0

package/README.md

@@ -1,21 +1,19 @@
 # `@bitbaum/geo-kit`
 
 Country-neutral contracts for sharing versioned geography data across
-applications. The package owns no country packs, political claims, source
-choices, personal data, HTTP server, or rendering framework.
+applications, and one renderer for it (`@bitbaum/geo-kit/map`). The package
+owns no country packs, political claims, source choices, personal data, HTTP
+server, or UI framework.
 
 ## Install
 
-The Git repository is the install source until npm publishing is bootstrapped.
-Pin the reviewed v0.1.1 source commit for a reproducible install:
-
 ```sh
-pnpm add github:bitbaum/geo-kit#a337aec928cf7804fecf459c308d366b90f4b2fa
+pnpm add @bitbaum/geo-kit
 ```
 
-The npm workflow uses npm Trusted Publishing and provenance. The first npm
-publish and publisher trust setup require a maintainer-held passkey; publishing
-stays disabled until that is complete.
+Install releases from npm, not a commit: a semver range is what lets a fix
+reach every product. `@bitbaum/geo-kit@0.1.1` is on npm; later releases are
+published by this repository's `publish.yml`.
 
 ## Ownership
 
@@ -86,6 +84,56 @@ The library never reads the system clock. Pass the date displayed by the app to
 support historical maps deterministically. An explicit viewpoint is opt-in;
 the library does not treat any boundary representation as the default truth.
 
+## Drawing it: `@bitbaum/geo-kit/map`
+
+One map for every product: an orthographic globe on Canvas 2D (`d3-geo`).
+Zoomed far in, the globe is a flat map of the place in front of the reader, so
+the world, a country and a commune are one projection and one renderer.
+Canvas 2D rather than WebGL: a few thousand path segments a frame fit a
+phone's frame budget, and it runs wherever the page runs.
+
+```sh
+pnpm add @bitbaum/geo-kit d3-geo topojson-client
+```
+
+`d3-geo` (and `topojson-client`, for TopoJSON) are optional peer
+dependencies: a product that only loads data does not install them.
+
+```ts
+import { cameraForBounds, createMap, shapesFromTopology } from "@bitbaum/geo-kit/map";
+
+const shapes = shapesFromTopology(topology, { object: "communes", idOf: (f) => String(f.id) });
+const limits = { minZoom: 1, maxZoom: 2000, maxTilt: 80 };
+const map = createMap(canvas, {
+  shapes,
+  palette: { sphere: "#fff", land: "#eee", border: "#999", hover: "#555", selected: "#000" },
+  fills: new Map([["261", "#08519c"]]),
+  limits,
+  onSelect: (id) => console.log(id),
+});
+map.resize(390, 600);
+map.flyTo(cameraForBounds([5.96, 45.82, 10.49, 47.81], limits));
+```
+
+- **Framework-free.** `createMap` takes a `<canvas>` and returns methods
+  (`resize`, `setFills`, `setSelected`, `flyTo`, `zoomBy`, `destroy`, …); a
+  React or other page wraps it in a few lines and keeps no map state of its own.
+- **Input.** One finger or the mouse turns it, two pinch, the wheel zooms, a
+  tap selects, a flick coasts. The keyboard treats the canvas as one control:
+  arrows turn, + and − zoom, Home resets, Enter selects what faces the reader.
+- **Cost.** It draws only when something changes; in motion it paints the
+  coarse shapes (every third vertex of each shared arc, so neighbours still
+  meet), and full detail the frame after. Features on the far side, or off the
+  canvas when zoomed, are not drawn.
+- **Reduced motion.** Under `prefers-reduced-motion` a flight is a cut, a flick
+  does not coast and the idle turn never starts.
+- **Layers.** The palette's sphere, graticule, glow and limb shade are each
+  optional, so a lit globe of the world and a plain map where the data is the
+  picture are the same painter. `over` draws the caller's own layer (sites,
+  routes, figures) on top each frame, with the frame's projection.
+- **Pure parts.** The camera, motion, culling, picking and the fast
+  projection are exported and tested without a browser.
+
 ## Assertions and proposed boundaries
 
 `AreaAssertion` follows Solon's sourced `claims`, `administers`, and `proposes`

package/dist/map/camera.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Where the map looks, kept pure so it can be tested without a browser: where
+ * the disc sits in the visible part of the canvas, the projection for a view,
+ * and where to look to face a feature and how close.
+ *
+ * Angles are degrees. A view is the point of the Earth facing the reader
+ * (`center`, [lon, lat]) and a zoom factor `k` on top of the resting radius,
+ * so a sheet rising or a panel opening only moves and resizes the disc; it
+ * never changes what the reader is looking at. Zoomed far in, the
+ * orthographic globe is a flat map of the place in front of the reader, so
+ * one projection serves the world and a commune.
+ */
+import { type GeoProjection } from "d3-geo";
+import type { Geometry, Position } from "geojson";
+/** The part of the canvas nothing floats over, in CSS pixels. */
+export interface View {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+export interface Camera {
+    /** The point of the Earth at the centre of the disc, [lon, lat]. */
+    center: [number, number];
+    /** Zoom on top of the resting radius; 1 is the whole globe in view. */
+    k: number;
+}
+/** How far the reader may zoom and tilt. */
+export interface Limits {
+    minZoom: number;
+    maxZoom: number;
+    /** How far north or south the reader can tilt: past this the poles spin. */
+    maxTilt: number;
+}
+/** A world: the whole globe at rest, a country at most. */
+export declare const WORLD_LIMITS: Limits;
+/** Centre and resting radius of the globe in the visible part of the canvas. */
+export declare function disc(view: View): {
+    cx: number;
+    cy: number;
+    radius: number;
+    short: number;
+};
+export declare const clampZoom: (k: number, limits?: Limits) => number;
+export declare const clampTilt: (lat: number, limits?: Limits) => number;
+/** Longitude folded into (-180, 180]. */
+export declare function wrapLon(lon: number): number;
+/** The d3 rotation that turns `center` to face the reader. */
+export declare function rotationOf(center: [number, number]): [number, number, number];
+export declare function projectionFor(view: View, camera: Camera): GeoProjection;
+/**
+ * The part of a feature to frame: its largest pieces, up to three quarters of
+ * its area. The whole outline is wrong for the features that matter most: the
+ * United States would be framed with Alaska and Hawaii (a view of the Pacific),
+ * France with Guiana, Norway with Svalbard.
+ */
+export declare function mainland(geometry: Geometry): Position[][][];
+export interface Focus {
+    /** [lon, lat] to turn to the reader. */
+    center: [number, number];
+    /** Degrees from the centre to the farthest point of the part framed. */
+    reach: number;
+}
+/**
+ * Where to look to face a feature, and how much of the sphere it spans.
+ * Spherical throughout (geoCentroid, geoDistance), so Russia, Fiji and the
+ * United States, which cross the antimeridian, need no special case.
+ */
+export declare function focusOf(geometry: Geometry): Focus | null;
+/**
+ * The zoom that fits a feature of angular `reach` in the disc. A point `r°`
+ * from the centre of an orthographic view lies `R·sin r` from its middle, so
+ * the feature fills `sin(reach)` of the radius at k = 1. Small features stop
+ * at `most` rather than filling the screen with one island.
+ */
+export declare function zoomFor(reach: number, { fill, most }?: {
+    fill?: number | undefined;
+    most?: number | undefined;
+}): number;
+/** The camera that faces a feature, or null when it has no area. */
+export declare function cameraFor(geometry: Geometry, limits?: Limits, zoom?: {
+    fill?: number;
+    most?: number;
+}): Camera | null;
+/** The camera that faces a lon/lat box [west, south, east, north]. */
+export declare function cameraForBounds([w, s, e, n]: [number, number, number, number], limits?: Limits, fill?: number): Camera;

package/dist/map/camera.js

@@ -0,0 +1,118 @@
+/**
+ * Where the map looks, kept pure so it can be tested without a browser: where
+ * the disc sits in the visible part of the canvas, the projection for a view,
+ * and where to look to face a feature and how close.
+ *
+ * Angles are degrees. A view is the point of the Earth facing the reader
+ * (`center`, [lon, lat]) and a zoom factor `k` on top of the resting radius,
+ * so a sheet rising or a panel opening only moves and resizes the disc; it
+ * never changes what the reader is looking at. Zoomed far in, the
+ * orthographic globe is a flat map of the place in front of the reader, so
+ * one projection serves the world and a commune.
+ */
+import { geoArea, geoCentroid, geoDistance, geoOrthographic } from "d3-geo";
+import { polygonsOf } from "./shapes.js";
+/** A world: the whole globe at rest, a country at most. */
+export const WORLD_LIMITS = { minZoom: 0.7, maxZoom: 14, maxTilt: 75 };
+/** Centre and resting radius of the globe in the visible part of the canvas. */
+export function disc(view) {
+    const w = Math.max(view.x1 - view.x0, 1);
+    const h = Math.max(view.y1 - view.y0, 1);
+    // Room around the limb for the atmosphere; a phone's strip above a sheet is
+    // short and wide, so the height decides there.
+    const radius = Math.max(Math.min(w, h) / 2 - Math.min(28, Math.min(w, h) * 0.08), 8);
+    return { cx: view.x0 + w / 2, cy: view.y0 + h / 2, radius, short: Math.min(w, h) };
+}
+export const clampZoom = (k, limits = WORLD_LIMITS) => Math.min(limits.maxZoom, Math.max(limits.minZoom, k));
+export const clampTilt = (lat, limits = WORLD_LIMITS) => Math.min(limits.maxTilt, Math.max(-limits.maxTilt, lat));
+/** Longitude folded into (-180, 180]. */
+export function wrapLon(lon) {
+    const x = (((lon + 180) % 360) + 360) % 360;
+    return x === 0 ? 180 : x - 180;
+}
+/** The d3 rotation that turns `center` to face the reader. */
+export function rotationOf(center) {
+    return [-center[0], -center[1], 0];
+}
+export function projectionFor(view, camera) {
+    const d = disc(view);
+    return (geoOrthographic()
+        .clipAngle(90)
+        // No adaptive resampling: boundary vertices are already closer than it would add.
+        .precision(0)
+        .translate([d.cx, d.cy])
+        .scale(d.radius * camera.k)
+        .rotate(rotationOf(camera.center)));
+}
+/**
+ * The part of a feature to frame: its largest pieces, up to three quarters of
+ * its area. The whole outline is wrong for the features that matter most: the
+ * United States would be framed with Alaska and Hawaii (a view of the Pacific),
+ * France with Guiana, Norway with Svalbard.
+ */
+export function mainland(geometry) {
+    const parts = polygonsOf(geometry)
+        .map((coordinates) => ({ coordinates, area: geoArea({ type: "Polygon", coordinates }) }))
+        .sort((a, b) => b.area - a.area);
+    const total = parts.reduce((s, p) => s + p.area, 0);
+    const kept = [];
+    let sum = 0;
+    for (const p of parts) {
+        kept.push(p.coordinates);
+        sum += p.area;
+        if (sum >= total * 0.75)
+            break;
+    }
+    return kept;
+}
+/**
+ * Where to look to face a feature, and how much of the sphere it spans.
+ * Spherical throughout (geoCentroid, geoDistance), so Russia, Fiji and the
+ * United States, which cross the antimeridian, need no special case.
+ */
+export function focusOf(geometry) {
+    const parts = mainland(geometry);
+    if (parts.length === 0)
+        return null;
+    const [lon, lat] = geoCentroid({ type: "MultiPolygon", coordinates: parts });
+    const center = [lon, lat];
+    let reach = 0;
+    for (const polygon of parts)
+        for (const point of polygon[0] ?? [])
+            reach = Math.max(reach, geoDistance(center, [point[0] ?? 0, point[1] ?? 0]));
+    return { center, reach: (reach * 180) / Math.PI };
+}
+/**
+ * The zoom that fits a feature of angular `reach` in the disc. A point `r°`
+ * from the centre of an orthographic view lies `R·sin r` from its middle, so
+ * the feature fills `sin(reach)` of the radius at k = 1. Small features stop
+ * at `most` rather than filling the screen with one island.
+ */
+export function zoomFor(reach, { fill = 0.6, most = 7 } = {}) {
+    const r = Math.min(Math.max(reach, 0.0001), 90);
+    const k = fill / Math.sin((r * Math.PI) / 180);
+    return Math.min(Math.max(k, 1), most);
+}
+/** The camera that faces a feature, or null when it has no area. */
+export function cameraFor(geometry, limits = WORLD_LIMITS, zoom = {}) {
+    const focus = focusOf(geometry);
+    if (!focus)
+        return null;
+    const k = zoomFor(focus.reach, { most: Math.min(7, limits.maxZoom), ...zoom });
+    return { center: [focus.center[0], clampTilt(focus.center[1], limits)], k: clampZoom(k, limits) };
+}
+/** The camera that faces a lon/lat box [west, south, east, north]. */
+export function cameraForBounds([w, s, e, n], limits = WORLD_LIMITS, fill = 0.8) {
+    const east = e < w ? e + 360 : e;
+    const center = [wrapLon((w + east) / 2), (s + n) / 2];
+    const reach = Math.max(...[
+        [w, s],
+        [w, n],
+        [east, s],
+        [east, n],
+    ].map((p) => (geoDistance(center, [p[0] ?? 0, p[1] ?? 0]) * 180) / Math.PI));
+    return {
+        center: [center[0], clampTilt(center[1], limits)],
+        k: clampZoom(zoomFor(reach, { fill, most: limits.maxZoom }), limits),
+    };
+}

package/dist/map/controller.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A map on one <canvas>, without a framework: hand it the canvas, the shapes
+ * and a palette, and it draws, turns, zooms and picks. One finger (or the
+ * mouse) turns it, two pinch, the wheel zooms, a tap selects the feature under
+ * it, a flick keeps it turning. The keyboard treats the canvas as one control:
+ * arrows turn it (Shift for larger steps), + and − zoom, Home resets, Enter
+ * selects the feature facing the reader.
+ *
+ * It draws only when something changes, so idle it costs nothing; while it
+ * moves it paints the coarse shapes, and full detail the frame after. Under
+ * prefers-reduced-motion a flight is a cut, a flick does not coast and the
+ * idle turn never starts. A page wraps it in whatever its framework is: it
+ * keeps no framework state of its own.
+ */
+import type { GeoProjection } from "d3-geo";
+import { type Camera, type Limits, type View } from "./camera.ts";
+import { type Fill, type Palette } from "./paint.ts";
+import type { MapShapes } from "./shapes.ts";
+import type { Basis } from "./trace.ts";
+/** What a frame tells the caller's overlay. */
+export interface FrameInfo {
+    now: number;
+    /** How far the current flight has come (0–1), or null when none. */
+    flight: number | null;
+    /** True while the map moves and paints its coarse shapes. */
+    moving: boolean;
+}
+export interface MapOptions<P = Record<string, unknown>> {
+    shapes: MapShapes<P>;
+    palette: Palette;
+    /** A colour per feature id; a feature without one is painted as land. */
+    fills?: ReadonlyMap<string, Fill>;
+    limits?: Limits;
+    /** Where the map rests and where Home returns to. */
+    home?: Camera;
+    /** How close a selected feature is framed: the share of the disc it fills, and the closest zoom (default 7). */
+    focusZoom?: {
+        fill?: number;
+        most?: number;
+    };
+    /** Turn slowly after a few seconds of rest, with nothing selected and zoomed out. */
+    idleTurn?: boolean;
+    /** A feature was tapped or chosen by keyboard; null for the sea. */
+    onSelect?: (id: string | null) => void;
+    /** The mouse is over a feature (null when over none), at a canvas point. */
+    onHover?: (id: string | null, x: number, y: number) => void;
+    /** Draw on top of the map each frame. */
+    over?: (ctx: CanvasRenderingContext2D, basis: Basis, projection: GeoProjection, frame: FrameInfo) => void;
+    /** True while the overlay animates and needs another frame. */
+    animating?: (now: number) => boolean;
+    /** True while the overlay wants the map held still (no idle turn). */
+    holdStill?: () => boolean;
+}
+export interface MapController {
+    /** Size the canvas, in CSS pixels, and the part of it nothing floats over. */
+    resize(width: number, height: number, view?: View): void;
+    setShapes<P>(shapes: MapShapes<P>): void;
+    setFills(fills: ReadonlyMap<string, Fill>): void;
+    setPalette(palette: Palette): void;
+    /** Mark a feature selected; `fly` turns the map to face it. */
+    setSelected(id: string | null, options?: {
+        fly?: boolean;
+    }): void;
+    flyTo(camera: Camera, duration?: number): void;
+    zoomBy(factor: number | "home"): void;
+    camera(): Camera;
+    projection(): GeoProjection | null;
+    /** Ask for a frame (the caller's overlay changed). */
+    invalidate(): void;
+    destroy(): void;
+}
+export declare function createMap<P>(canvas: HTMLCanvasElement, options: MapOptions<P>): MapController;