@johnmorrisdotca/chikyu-earth 0.5.0 → 0.7.0

package/dist/markers/labels.js

@@ -4,6 +4,24 @@ 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);

package/dist/markers/layer.d.ts

@@ -1,17 +1,51 @@
 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;
@@ -20,6 +54,20 @@ export interface MarkerOptions {
     /** 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;
@@ -43,7 +91,39 @@ export interface Markers {
     };
     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;

package/dist/markers/layer.js

@@ -14,6 +14,27 @@ const CSS = `
 const EDGE = 16;
 const LABEL_FONT = "12px system-ui, -apple-system, sans-serif";
 const TEXT_LIST_MAX = 200;
+/**
+ * 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 function attachMarkers(element, options = {}) {
     const host = element.overlay;
     const root = host.overlayRoot;

package/dist/markers/project.d.ts

@@ -1,4 +1,15 @@
 /** The view: the point of the Earth at the middle of the disc, the disc's radius and its centre, in CSS pixels. */
+/**
+ * The view: the point of the Earth at the middle of the disc, the disc's radius and its centre, in CSS pixels.
+ *
+ * @example
+ * ```ts
+ * import { project, type Pose } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const pose: Pose = { lon: 10, lat: 20, radius: 100, cx: 150, cy: 150 };
+ * console.log(project(10, 20, pose));
+ * ```
+ */
 export interface Pose {
     lon: number;
     lat: number;
@@ -9,13 +20,63 @@ export interface Pose {
 /**
  * Project a longitude and latitude (degrees) to the screen. `z` is the cosine of the angle from the middle of the disc: above 0 the point faces
  * the viewer, below it is on the far side. North is up.
+ *
+ * @param lon - Longitude in degrees east.
+ * @param lat - Latitude in degrees north.
+ * @param pose - The view.
+ * @returns The point's x and y in pixels and `z`, the cosine of its angle from the middle of the disc.
+ *
+ * @example
+ * ```ts
+ * import { project } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const where = project(139.69, 35.69, { lon: 139.69, lat: 35.69, radius: 200, cx: 210, cy: 210 });
+ * console.log(where.x, where.y, where.z);
+ * ```
  */
 export declare function project(lon: number, lat: number, pose: Pose): {
     x: number;
     y: number;
     z: number;
 };
-/** Project many points into flat arrays (reused between calls); `z` is left as it is for a point's facing test. */
+/**
+ * Project many points into flat arrays (reused between calls); `z` is the cosine used for a point's facing test.
+ *
+ * @param lons - Longitudes in degrees.
+ * @param lats - Latitudes in degrees.
+ * @param count - How many points to project.
+ * @param pose - The view.
+ * @param xs - Filled with each point's x in pixels.
+ * @param ys - Filled with each point's y in pixels.
+ * @param zs - Filled with each point's `z`: above 0 it faces the viewer.
+ *
+ * @example
+ * ```ts
+ * import { projectAll } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = new Float32Array(2);
+ * const ys = new Float32Array(2);
+ * const zs = new Float32Array(2);
+ * projectAll([0, 180], [0, 0], 2, { lon: 0, lat: 0, radius: 100, cx: 100, cy: 100 }, xs, ys, zs);
+ * console.log(zs[0], zs[1]);
+ * ```
+ */
 export declare function projectAll(lons: ArrayLike<number>, lats: ArrayLike<number>, count: number, pose: Pose, xs: Float32Array, ys: Float32Array, zs: Float32Array): void;
-/** The pixel ratio for an overlay canvas: the device's, to 2, held to 4096 a side and 6 million pixels (the same budget as the 3D canvas). */
+/**
+ * The pixel ratio for an overlay canvas: the device's, to 2, held to 4096 a side and 6 million pixels (the same budget as the 3D canvas).
+ *
+ * @param width - The canvas's width in CSS pixels.
+ * @param height - The canvas's height in CSS pixels.
+ * @param deviceRatio - The device's pixel ratio.
+ * @param maxSide - The most pixels on a side.
+ * @param maxPixels - The most pixels in all.
+ * @returns The ratio to draw at, between 0.1 and 2.
+ *
+ * @example
+ * ```ts
+ * import { canvasRatio } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * console.log(canvasRatio(420, 420, 3), canvasRatio(5000, 3000, 2));
+ * ```
+ */
 export declare function canvasRatio(width: number, height: number, deviceRatio: number, maxSide?: number, maxPixels?: number): number;

package/dist/markers/project.js

@@ -3,6 +3,19 @@ const RAD = Math.PI / 180;
 /**
  * Project a longitude and latitude (degrees) to the screen. `z` is the cosine of the angle from the middle of the disc: above 0 the point faces
  * the viewer, below it is on the far side. North is up.
+ *
+ * @param lon - Longitude in degrees east.
+ * @param lat - Latitude in degrees north.
+ * @param pose - The view.
+ * @returns The point's x and y in pixels and `z`, the cosine of its angle from the middle of the disc.
+ *
+ * @example
+ * ```ts
+ * import { project } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const where = project(139.69, 35.69, { lon: 139.69, lat: 35.69, radius: 200, cx: 210, cy: 210 });
+ * console.log(where.x, where.y, where.z);
+ * ```
  */
 export function project(lon, lat, pose) {
     const phi = lat * RAD;
@@ -16,7 +29,28 @@ export function project(lon, lat, pose) {
         z,
     };
 }
-/** Project many points into flat arrays (reused between calls); `z` is left as it is for a point's facing test. */
+/**
+ * Project many points into flat arrays (reused between calls); `z` is the cosine used for a point's facing test.
+ *
+ * @param lons - Longitudes in degrees.
+ * @param lats - Latitudes in degrees.
+ * @param count - How many points to project.
+ * @param pose - The view.
+ * @param xs - Filled with each point's x in pixels.
+ * @param ys - Filled with each point's y in pixels.
+ * @param zs - Filled with each point's `z`: above 0 it faces the viewer.
+ *
+ * @example
+ * ```ts
+ * import { projectAll } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = new Float32Array(2);
+ * const ys = new Float32Array(2);
+ * const zs = new Float32Array(2);
+ * projectAll([0, 180], [0, 0], 2, { lon: 0, lat: 0, radius: 100, cx: 100, cy: 100 }, xs, ys, zs);
+ * console.log(zs[0], zs[1]);
+ * ```
+ */
 export function projectAll(lons, lats, count, pose, xs, ys, zs) {
     const phi0 = pose.lat * RAD;
     const sin0 = Math.sin(phi0);
@@ -32,7 +66,23 @@ export function projectAll(lons, lats, count, pose, xs, ys, zs) {
         ys[i] = pose.cy - pose.radius * (cos0 * sinPhi - sin0 * cosPhi * cosDelta);
     }
 }
-/** The pixel ratio for an overlay canvas: the device's, to 2, held to 4096 a side and 6 million pixels (the same budget as the 3D canvas). */
+/**
+ * The pixel ratio for an overlay canvas: the device's, to 2, held to 4096 a side and 6 million pixels (the same budget as the 3D canvas).
+ *
+ * @param width - The canvas's width in CSS pixels.
+ * @param height - The canvas's height in CSS pixels.
+ * @param deviceRatio - The device's pixel ratio.
+ * @param maxSide - The most pixels on a side.
+ * @param maxPixels - The most pixels in all.
+ * @returns The ratio to draw at, between 0.1 and 2.
+ *
+ * @example
+ * ```ts
+ * import { canvasRatio } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * console.log(canvasRatio(420, 420, 3), canvasRatio(5000, 3000, 2));
+ * ```
+ */
 export function canvasRatio(width, height, deviceRatio, maxSide = 4096, maxPixels = 6_000_000) {
     let ratio = Math.min(Math.max(deviceRatio, 1), 2);
     ratio = Math.min(ratio, maxSide / Math.max(width, 1), maxSide / Math.max(height, 1));

package/dist/markers/types.d.ts

@@ -1,6 +1,27 @@
-/** The shapes a marker can be drawn as. */
+/**
+ * The shapes a marker can be drawn as: `dot`, `ring`, `square` or `diamond`.
+ *
+ * @example
+ * ```ts
+ * import type { MarkerIcon, MarkerInput } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const icon: MarkerIcon = "diamond";
+ * const stadium: MarkerInput = { id: "camp-nou", lon: 2.12, lat: 41.38, icon, group: "Stadiums" };
+ * console.log(stadium.icon);
+ * ```
+ */
 export type MarkerIcon = "dot" | "ring" | "square" | "diamond";
-/** A place on the Earth. Chikyu ships none: the page brings its own. */
+/**
+ * A place on the Earth. Chikyu ships none: the page brings its own.
+ *
+ * @example
+ * ```ts
+ * import type { MarkerInput } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const tokyo: MarkerInput = { id: "tokyo", lon: 139.69, lat: 35.69, label: "Tokyo", group: "Cities", priority: 5, data: { population: 14_000_000 } };
+ * console.log(tokyo.label);
+ * ```
+ */
 export interface MarkerInput {
     /** Your own unique name for it. */
     id: string;
@@ -23,7 +44,20 @@ export interface MarkerInput {
     /** Yours: given back in every event. */
     data?: unknown;
 }
-/** What `chikyu-marker-*` events carry. A cluster click has `marker: null` and `cluster` listing the ids in it. */
+/**
+ * What the `chikyu-marker-hover`, `chikyu-marker-click` and `chikyu-marker-focus` events carry in `event.detail`. A cluster click has `marker: null` and `cluster` listing the ids in it.
+ *
+ * @example
+ * ```ts
+ * import type { MarkerEventDetail } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const on = (event: Event): void => {
+ *   const detail = (event as CustomEvent<MarkerEventDetail>).detail;
+ *   console.log(detail.marker?.label ?? `${detail.cluster?.length} places`, detail.x, detail.y);
+ * };
+ * console.log(typeof on);
+ * ```
+ */
 export interface MarkerEventDetail {
     marker: MarkerInput | null;
     cluster?: string[];
@@ -31,6 +65,17 @@ export interface MarkerEventDetail {
     x: number;
     y: number;
 }
+/**
+ * One group of markers: its name, how many it holds and whether it is shown.
+ *
+ * @example
+ * ```ts
+ * import type { GroupInfo } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const show = (groups: GroupInfo[]): string => groups.map((group) => `${group.name}: ${group.count}${group.visible ? "" : " (hidden)"}`).join(", ");
+ * console.log(show([{ name: "Cities", count: 3, visible: true }]));
+ * ```
+ */
 export interface GroupInfo {
     name: string;
     count: number;

package/dist/realistic/earth.d.ts

@@ -2,11 +2,20 @@ import type * as THREE from "three";
 import type { AssetCache, Item3D } from "@johnmorrisdotca/kazoku-ui/renderer";
 import type { GeoPoint, GlobeView } from "../types.ts";
 import { lookAt } from "../view.ts";
-import { type Layer } from "./tiers.ts";
-/** The parts of three.js the Earth uses. A page can hand over a module that re-exports just these (see `setThreeLoader`) instead of all of three. */
-export type ThreeParts = Pick<typeof THREE, "Texture" | "BufferGeometry" | "BufferAttribute" | "ShaderMaterial" | "Group" | "Mesh" | "Scene" | "OrthographicCamera" | "Vector3" | "WebGLRenderer" | "RepeatWrapping" | "ClampToEdgeWrapping" | "LinearMipmapLinearFilter" | "LinearFilter" | "BackSide">;
+import type { Layer } from "./tiers.ts";
+import { type ThreeParts } from "./textures.ts";
+export type { ThreeParts };
 type Three = ThreeParts;
-/** The glow reaches this many radii from the centre; the globe at 1x is drawn to fit inside it. */
+/**
+ * The glow reaches this many radii from the centre; the globe at 1x is drawn to fit inside it.
+ *
+ * @example
+ * ```ts
+ * import { ATMOSPHERE_OUTER } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(ATMOSPHERE_OUTER);
+ * ```
+ */
 export declare const ATMOSPHERE_OUTER = 1.08;
 /** What the scene reads at each draw; the element changes it and asks for a draw. */
 export interface EarthModel {
@@ -50,7 +59,23 @@ export interface EarthDeps {
     }) => void;
 }
 export declare const newModel: () => EarthModel;
-/** The disc's radius in CSS pixels in a box of `width` x `height` at `zoom`: it fits the glow in the box at 1x. */
+/**
+ * The disc's radius in CSS pixels in a box of `width` x `height` at `zoom`: it fits the glow in the box at 1x.
+ *
+ * @param width - The box's width in CSS pixels.
+ * @param height - The box's height in CSS pixels.
+ * @param zoom - The view's zoom, 1 at Fit.
+ * @returns The radius in CSS pixels, at least 1.
+ *
+ * @example
+ * ```ts
+ * import { discRadius } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(discRadius(400, 400, 1).toFixed(1));
+ * ```
+ */
 export declare const discRadius: (width: number, height: number, zoom: number) => number;
 export { lookAt };
+/** An equirectangular sphere: +z is longitude 0 on the equator, +x east, +y north; v is 0 at the north pole (the top row of the picture). */
+export declare function sphere(three: Three, columns: number, rows: number): THREE.BufferGeometry;
 export declare function createEarthItem(model: EarthModel, deps: EarthDeps): Item3D<Three>;