@johnmorrisdotca/chikyu-earth 0.4.0 → 0.7.0

package/dist/globe.js

@@ -5,7 +5,21 @@ import { COUNTRIES } from "./countries.js";
 import { cleanStyle, STYLES } from "./styles.js";
 import { projectionView } from "./view.js";
 const SPHERE = { type: "Sphere" };
-/** The globe as an SVG string, turned to `rotation` and drawn in `style`, `size` pixels square. */
+/**
+ * The globe as an SVG string, turned to `rotation` and drawn in `style`, `size` pixels square. It is pure: the same options always give the same markup, so it runs on a server, in a test or in a build step with no DOM.
+ *
+ * @param options - Size, turn, look and graticule; every one has a default, so `globe()` draws a 320-pixel globe facing the Greenwich meridian.
+ * @returns One `<svg>` element as text, with the country outlines as paths.
+ *
+ * @example
+ * ```ts
+ * import { globe } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const svg = globe({ size: 240, rotation: [-139.7, -35.7], style: "line" });
+ * console.log(svg.slice(0, 60));
+ * console.log(svg.length > 10_000);
+ * ```
+ */
 export function globe(options = {}) {
     const size = options.size ?? 320;
     const style = STYLES[cleanStyle(options.style)];

package/dist/index.d.ts

@@ -5,5 +5,16 @@ export { centreRotation, DEGREES_PER_MS, rotationAt, SIDEREAL_DAY_MS, spinAt } f
 export { globeBaseScale, HOME_VIEW, projectionView, type ProjectionView } from "./view.ts";
 export type { CountryProps, GeoPoint, GlobeOptions, GlobeView, Rotation } from "./types.ts";
 import type { CountryProps } from "./types.ts";
-/** Every country the globe draws, with its kuni name and code. */
+/**
+ * Every country the globe draws, with its kuni name and code.
+ *
+ * @returns A list of English name, Japanese name (or `null`) and two-letter code (or `null` where a place has none).
+ *
+ * @example
+ * ```ts
+ * import { countryList } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(countryList().find((country) => country.alpha2 === "JP"));
+ * ```
+ */
 export declare const countryList: () => CountryProps[];

package/dist/index.js

@@ -4,5 +4,16 @@ export { cleanStyle, DEFAULT_STYLE, STYLE_NAMES, STYLES } from "./styles.js";
 export { centreRotation, DEGREES_PER_MS, rotationAt, SIDEREAL_DAY_MS, spinAt } from "./rotate.js";
 export { globeBaseScale, HOME_VIEW, projectionView } from "./view.js";
 import { COUNTRIES } from "./countries.js";
-/** Every country the globe draws, with its kuni name and code. */
+/**
+ * Every country the globe draws, with its kuni name and code.
+ *
+ * @returns A list of English name, Japanese name (or `null`) and two-letter code (or `null` where a place has none).
+ *
+ * @example
+ * ```ts
+ * import { countryList } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(countryList().find((country) => country.alpha2 === "JP"));
+ * ```
+ */
 export const countryList = () => COUNTRIES.features.map((f) => f.properties);

package/dist/markers/cluster.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Several points gathered into one on the screen: where it is drawn and which points are in it.
+ *
+ * @example
+ * ```ts
+ * import { clusterPoints, type Cluster } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const clusters: Cluster[] = clusterPoints([0, 1], 2, [10, 12], [10, 11], 28);
+ * console.log(clusters[0]?.members);
+ * ```
+ */
+export interface Cluster {
+    x: number;
+    y: number;
+    /** Indices of the points in it. */
+    members: number[];
+}
+/**
+ * Group the points `indices` (into `xs` and `ys`) by the grid cell they fall in. A cell with one point is that point alone; with more it is one cluster at their
+ * average. Order is stable: clusters come in the order their first member was seen.
+ *
+ * @param indices - Which points to group: indices into `xs` and `ys`.
+ * @param count - How many of `indices` to read.
+ * @param xs - Every point's x on the screen, in pixels.
+ * @param ys - Every point's y on the screen, in pixels.
+ * @param cell - The side of a grid cell in pixels; points in one cell join.
+ * @returns The clusters, each with the indices of its members; a lone point is a cluster of one.
+ *
+ * @example
+ * ```ts
+ * import { clusterPoints } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = [10, 14, 200];
+ * const ys = [10, 12, 200];
+ * console.log(clusterPoints([0, 1, 2], 3, xs, ys, 28).map((cluster) => cluster.members));
+ * ```
+ */
+export declare function clusterPoints(indices: ArrayLike<number>, count: number, xs: ArrayLike<number>, ys: ArrayLike<number>, cell: number): Cluster[];

package/dist/markers/cluster.js

@@ -0,0 +1,42 @@
+// Crowded markers become one: points closer than a cell on the screen share a cluster. A grid, so thousands of points cost one pass. Pure.
+/**
+ * Group the points `indices` (into `xs` and `ys`) by the grid cell they fall in. A cell with one point is that point alone; with more it is one cluster at their
+ * average. Order is stable: clusters come in the order their first member was seen.
+ *
+ * @param indices - Which points to group: indices into `xs` and `ys`.
+ * @param count - How many of `indices` to read.
+ * @param xs - Every point's x on the screen, in pixels.
+ * @param ys - Every point's y on the screen, in pixels.
+ * @param cell - The side of a grid cell in pixels; points in one cell join.
+ * @returns The clusters, each with the indices of its members; a lone point is a cluster of one.
+ *
+ * @example
+ * ```ts
+ * import { clusterPoints } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = [10, 14, 200];
+ * const ys = [10, 12, 200];
+ * console.log(clusterPoints([0, 1, 2], 3, xs, ys, 28).map((cluster) => cluster.members));
+ * ```
+ */
+export function clusterPoints(indices, count, xs, ys, cell) {
+    const cells = new Map();
+    const out = [];
+    for (let k = 0; k < count; k += 1) {
+        const i = indices[k];
+        const key = Math.floor(xs[i] / cell) * 100_003 + Math.floor(ys[i] / cell);
+        const found = cells.get(key);
+        if (found) {
+            const n = found.members.length;
+            found.x = (found.x * n + xs[i]) / (n + 1);
+            found.y = (found.y * n + ys[i]) / (n + 1);
+            found.members.push(i);
+        }
+        else {
+            const made = { x: xs[i], y: ys[i], members: [i] };
+            cells.set(key, made);
+            out.push(made);
+        }
+    }
+    return out;
+}

package/dist/markers/index.d.ts

@@ -0,0 +1,5 @@
+export { attachMarkers, type Markers, type MarkerOptions, type OverlayElement, type OverlayHost, type OverlayPose } from "./layer.ts";
+export { project, projectAll, canvasRatio, type Pose } from "./project.ts";
+export { clusterPoints, type Cluster } from "./cluster.ts";
+export { placeLabels, type LabelItem, type Placement } from "./labels.ts";
+export type { GroupInfo, MarkerEventDetail, MarkerIcon, MarkerInput } from "./types.ts";

package/dist/markers/index.js

@@ -0,0 +1,6 @@
+// Markers on the globe: `attachMarkers(element)` for `<chikyu-earth>` or `<chikyu-earth-realistic>`. The pure parts (projection, clusters, label placement)
+// import on a server.
+export { attachMarkers } from "./layer.js";
+export { project, projectAll, canvasRatio } from "./project.js";
+export { clusterPoints } from "./cluster.js";
+export { placeLabels } from "./labels.js";

package/dist/markers/labels.d.ts

@@ -0,0 +1,64 @@
+/**
+ * One label to place: its dot's centre and radius, its box's size and its priority.
+ *
+ * @example
+ * ```ts
+ * import type { LabelItem } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const label: LabelItem = { x: 100, y: 100, r: 4, w: 60, h: 20, priority: 1 };
+ * console.log(label.w);
+ * ```
+ */
+export interface LabelItem {
+    /** The dot's centre and radius. */
+    x: number;
+    y: number;
+    r: number;
+    /** The label's box size. */
+    w: number;
+    h: number;
+    /** Higher is placed first. */
+    priority: number;
+}
+/**
+ * Where one label goes: which item it is and its box's top-left corner.
+ *
+ * @example
+ * ```ts
+ * import { placeLabels, type Placement } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const placed: Placement[] = placeLabels([{ x: 100, y: 100, r: 4, w: 60, h: 20, priority: 1 }], 300, 300, 10);
+ * console.log(placed[0]);
+ * ```
+ */
+export interface Placement {
+    /** Index into the items given. */
+    item: number;
+    /** The label box's top-left corner. */
+    left: number;
+    top: number;
+}
+/**
+ * Place up to `max` labels inside `width` x `height`. Each label is tried to the right of its dot, then to the left, above and below; the first spot that is inside
+ * and free of the labels already placed wins. Items are taken highest priority first (a tie keeps the order given). The cost is the number of items times at most
+ * four tries against a grid of what is placed.
+ *
+ * @param items - The dots and the size of each one's label.
+ * @param width - The width of the area the labels must stay inside, in pixels.
+ * @param height - The height of that area, in pixels.
+ * @param max - The most labels to place.
+ * @param cell - The side of the grid cell used to find overlaps, in pixels.
+ * @returns A placement for each label that fits; the others are left out.
+ *
+ * @example
+ * ```ts
+ * import { placeLabels } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const items = [
+ *   { x: 100, y: 100, r: 4, w: 60, h: 20, priority: 1 },
+ *   { x: 110, y: 104, r: 4, w: 60, h: 20, priority: 9 },
+ * ];
+ * console.log(placeLabels(items, 300, 300, 10).map((place) => place.item));
+ * ```
+ */
+export declare function placeLabels(items: readonly LabelItem[], width: number, height: number, max: number, cell?: number): Placement[];

package/dist/markers/labels.js

@@ -0,0 +1,70 @@
+// Which labels to show: the most important first, each beside its dot, none over another label or a dot's label slot already taken. Pure.
+const GAP = 3;
+/**
+ * Place up to `max` labels inside `width` x `height`. Each label is tried to the right of its dot, then to the left, above and below; the first spot that is inside
+ * and free of the labels already placed wins. Items are taken highest priority first (a tie keeps the order given). The cost is the number of items times at most
+ * four tries against a grid of what is placed.
+ *
+ * @param items - The dots and the size of each one's label.
+ * @param width - The width of the area the labels must stay inside, in pixels.
+ * @param height - The height of that area, in pixels.
+ * @param max - The most labels to place.
+ * @param cell - The side of the grid cell used to find overlaps, in pixels.
+ * @returns A placement for each label that fits; the others are left out.
+ *
+ * @example
+ * ```ts
+ * import { placeLabels } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const items = [
+ *   { x: 100, y: 100, r: 4, w: 60, h: 20, priority: 1 },
+ *   { x: 110, y: 104, r: 4, w: 60, h: 20, priority: 9 },
+ * ];
+ * console.log(placeLabels(items, 300, 300, 10).map((place) => place.item));
+ * ```
+ */
+export function placeLabels(items, width, height, max, cell = 64) {
+    const order = items.map((_, i) => i).sort((a, b) => items[b].priority - items[a].priority || a - b);
+    const grid = new Map();
+    const placed = [];
+    const keys = (box) => {
+        const out = [];
+        for (let gx = Math.floor(box.l / cell); gx <= Math.floor(box.r / cell); gx += 1)
+            for (let gy = Math.floor(box.t / cell); gy <= Math.floor(box.b / cell); gy += 1)
+                out.push(gx * 100_003 + gy);
+        return out;
+    };
+    const free = (box) => {
+        for (const key of keys(box))
+            for (const other of grid.get(key) ?? [])
+                if (box.l < other.r && box.r > other.l && box.t < other.b && box.b > other.t)
+                    return false;
+        return true;
+    };
+    for (const index of order) {
+        if (placed.length >= max)
+            break;
+        const it = items[index];
+        const tries = [
+            [it.x + it.r + GAP, it.y - it.h / 2],
+            [it.x - it.r - GAP - it.w, it.y - it.h / 2],
+            [it.x - it.w / 2, it.y - it.r - GAP - it.h],
+            [it.x - it.w / 2, it.y + it.r + GAP],
+        ];
+        for (const [left, top] of tries) {
+            const box = { l: left, t: top, r: left + it.w, b: top + it.h };
+            if (box.l < 0 || box.t < 0 || box.r > width || box.b > height || !free(box))
+                continue;
+            for (const key of keys(box)) {
+                const list = grid.get(key);
+                if (list)
+                    list.push(box);
+                else
+                    grid.set(key, [box]);
+            }
+            placed.push({ item: index, left, top });
+            break;
+        }
+    }
+    return placed;
+}

package/dist/markers/layer.d.ts

@@ -0,0 +1,129 @@
+import { type Pose } from "./project.ts";
+import type { GroupInfo, MarkerInput } from "./types.ts";
+/** The view as an element tells it: the Pose, the size of the box it is drawn in, and the CSS transform its picture carries between redraws. */
+/**
+ * The pose of an element's last drawing, with the size of its box and the CSS transform its picture carries between redraws.
+ *
+ * @example
+ * ```ts
+ * import type { OverlayPose } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const where = (pose: OverlayPose): string => `${pose.lon}, ${pose.lat} at ${pose.width} x ${pose.height}`;
+ * console.log(typeof where);
+ * ```
+ */
+export interface OverlayPose extends Pose {
+    width: number;
+    height: number;
+    transform: string;
+}
+/** What an element gives the markers: a box laid over its view, the pose of its last draw, and a way to hear the next ones. */
+/**
+ * What an element gives the markers (`element.overlay`): a box laid over its view, the pose of its last draw, and a way to hear the next ones.
+ *
+ * @example
+ * ```ts
+ * import type { OverlayHost } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const follow = (host: OverlayHost): (() => void) => host.subscribe((pose) => console.log(pose.radius));
+ * console.log(typeof follow);
+ * ```
+ */
+export interface OverlayHost {
+    readonly overlayRoot: HTMLElement;
+    readonly pose: OverlayPose | null;
+    subscribe(listener: (pose: OverlayPose) => void): () => void;
+}
+/**
+ * What {@link attachMarkers} may be asked: the most labels, how close markers gather, and the default colour.
+ *
+ * @example
+ * ```ts
+ * import { attachMarkers, type MarkerOptions, type OverlayElement } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const options: MarkerOptions = { maxLabels: 12, clusterRadius: 20, color: "#ffcc00" };
+ * const mark = (element: OverlayElement) => attachMarkers(element, options);
+ * console.log(typeof mark);
+ * ```
+ */
+export interface MarkerOptions {
+    /** Most labels shown at once (24). */
+    maxLabels?: number;
+    /** Gather markers closer than this many pixels into a cluster (28); 0 turns clustering off. */
+    clusterRadius?: number;
+    /** The colour of a marker with none of its own. */
+    color?: string;
+}
+/**
+ * The markers on one globe: add, update, remove and find them, show or hide groups, and detach.
+ *
+ * @example
+ * ```ts no-run
+ * import { attachMarkers, type Markers, type OverlayElement } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * declare const earth: OverlayElement;
+ * const markers: Markers = attachMarkers(earth);
+ * markers.add({ id: "tokyo", lon: 139.69, lat: 35.69, label: "Tokyo", group: "Cities" });
+ * markers.toggleGroup("Cities");
+ * console.log(markers.size, markers.groups());
+ * ```
+ */
+export interface Markers {
+    add(marker: MarkerInput): void;
+    addAll(markers: readonly MarkerInput[]): void;
+    update(id: string, patch: Partial<Omit<MarkerInput, "id">>): void;
+    remove(id: string): void;
+    clear(): void;
+    get(id: string): MarkerInput | undefined;
+    list(): MarkerInput[];
+    readonly size: number;
+    groups(): GroupInfo[];
+    showGroup(name: string): void;
+    hideGroup(name: string): void;
+    /** Show it if hidden and hide it if shown (or set it with `force`). Returns whether it is shown. */
+    toggleGroup(name: string, force?: boolean): boolean;
+    /** Markers and clusters drawn at the last render (for a page or a test). */
+    readonly stats: {
+        markers: number;
+        clusters: number;
+        labels: number;
+        renders: number;
+    };
+    detach(): void;
+}
+/**
+ * An element markers can be put on: any HTML element with an `overlay` (both `<chikyu-earth>` and `<chikyu-earth-realistic>` have one).
+ *
+ * @example
+ * ```ts
+ * import { attachMarkers, type OverlayElement } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const mark = (element: OverlayElement) => attachMarkers(element);
+ * console.log(typeof mark);
+ * ```
+ */
+export type OverlayElement = HTMLElement & {
+    overlay: OverlayHost;
+};
+/**
+ * Put markers on a globe, for either look: dots drawn in one pass on a canvas, a few labels as real buttons, crowded places gathered into clusters. It draws only when the view or the markers change, reads no layout to place a label, and shows no more labels than `maxLabels`. Hovering, clicking or focusing a marker fires `chikyu-marker-hover`, `chikyu-marker-click` and `chikyu-marker-focus` on the element, with your own `data` in the detail.
+ *
+ * @param element - `<chikyu-earth>` or `<chikyu-earth-realistic>`.
+ * @param options - The most labels, the cluster radius and the default colour; each has a default.
+ * @returns The markers: `add`, `addAll`, `update`, `remove`, `clear`, `groups`, `toggleGroup`, `stats` and `detach`.
+ *
+ * @example
+ * ```ts no-run
+ * import "@johnmorrisdotca/chikyu-earth/element";
+ * import { attachMarkers, type MarkerEventDetail } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const earth = document.querySelector("chikyu-earth")!;
+ * const markers = attachMarkers(earth);
+ * markers.add({ id: "tokyo", lon: 139.69, lat: 35.69, label: "Tokyo", group: "Cities" });
+ * earth.addEventListener("chikyu-marker-click", (event) => {
+ *   const { marker } = (event as CustomEvent<MarkerEventDetail>).detail;
+ *   console.log("chose", marker?.label);
+ * });
+ * ```
+ */
+export declare function attachMarkers(element: OverlayElement, options?: MarkerOptions): Markers;