@johnmorrisdotca/chikyu-earth 0.5.0 → 0.8.0

package/dist/styles.d.ts

@@ -1,3 +1,14 @@
+/**
+ * The lines and fills of one look: colours and widths only, never the geometry.
+ *
+ * @example
+ * ```ts
+ * import { STYLES, type Style } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const thick: Style = STYLES.thick;
+ * console.log(thick.outline, thick.line);
+ * ```
+ */
 export interface Style {
     /** The colour of the outlines and the rim. */
     line: string;
@@ -12,6 +23,16 @@ export interface Style {
     /** Graticule width, in SVG units. */
     graticule: number;
 }
+/**
+ * The looks the globe is drawn in, by name: `line` (thin outlines) and `thick`.
+ *
+ * @example
+ * ```ts
+ * import { STYLES } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(Object.keys(STYLES), STYLES.line.ocean);
+ * ```
+ */
 export declare const STYLES: {
     readonly line: {
         readonly line: "#8fa1b8";
@@ -30,9 +51,51 @@ export declare const STYLES: {
         readonly graticule: 0.5;
     };
 };
+/**
+ * The name of a look: `"line"` or `"thick"`.
+ *
+ * @example
+ * ```ts
+ * import { globe, type StyleName } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const look: StyleName = "thick";
+ * console.log(globe({ style: look, size: 100 }).includes("stroke-width"));
+ * ```
+ */
 export type StyleName = keyof typeof STYLES;
-/** The style a drawing is in when none is named. */
+/**
+ * The style a drawing is in when none is named.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_STYLE } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(DEFAULT_STYLE);
+ * ```
+ */
 export declare const DEFAULT_STYLE: StyleName;
+/**
+ * Every style's name, in the order they are listed.
+ *
+ * @example
+ * ```ts
+ * import { STYLE_NAMES } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(STYLE_NAMES.join(", "));
+ * ```
+ */
 export declare const STYLE_NAMES: StyleName[];
-/** A value from outside as a style's name: the default for anything else. */
+/**
+ * A value from outside (an attribute, a query parameter) as a style's name: the default for anything else.
+ *
+ * @param value - Anything.
+ * @returns A valid style name; {@link DEFAULT_STYLE} when `value` names none.
+ *
+ * @example
+ * ```ts
+ * import { cleanStyle } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(cleanStyle("thick"), cleanStyle("neon"), cleanStyle(null));
+ * ```
+ */
 export declare const cleanStyle: (value: unknown) => StyleName;

package/dist/styles.js

@@ -1,11 +1,52 @@
 // The two looks the globe is drawn in, the same line colours as hako-devices and uchusen-rockets: one table entry each,
 // a look changes lines and fills, never the geometry. Pure.
+/**
+ * The looks the globe is drawn in, by name: `line` (thin outlines) and `thick`.
+ *
+ * @example
+ * ```ts
+ * import { STYLES } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(Object.keys(STYLES), STYLES.line.ocean);
+ * ```
+ */
 export const STYLES = {
     line: { line: "#8fa1b8", ocean: "#0b1424", land: "#13203a", outline: 0.5, horizon: 1, graticule: 0.3 },
     thick: { line: "#b4c2d4", ocean: "#0b1424", land: "#1a2b47", outline: 1.2, horizon: 2, graticule: 0.5 },
 };
-/** The style a drawing is in when none is named. */
+/**
+ * The style a drawing is in when none is named.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_STYLE } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(DEFAULT_STYLE);
+ * ```
+ */
 export const DEFAULT_STYLE = "line";
+/**
+ * Every style's name, in the order they are listed.
+ *
+ * @example
+ * ```ts
+ * import { STYLE_NAMES } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(STYLE_NAMES.join(", "));
+ * ```
+ */
 export const STYLE_NAMES = Object.keys(STYLES);
-/** A value from outside as a style's name: the default for anything else. */
+/**
+ * A value from outside (an attribute, a query parameter) as a style's name: the default for anything else.
+ *
+ * @param value - Anything.
+ * @returns A valid style name; {@link DEFAULT_STYLE} when `value` names none.
+ *
+ * @example
+ * ```ts
+ * import { cleanStyle } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(cleanStyle("thick"), cleanStyle("neon"), cleanStyle(null));
+ * ```
+ */
 export const cleanStyle = (value) => typeof value === "string" && Object.hasOwn(STYLES, value) ? value : DEFAULT_STYLE;

package/dist/types.d.ts

@@ -1,5 +1,15 @@
 import type { StyleName } from "./styles.ts";
-/** What one country's outline carries: its English and Japanese name and its ISO alpha-2 code, all from kuni. */
+/**
+ * What one country's outline carries: its English and Japanese name and its ISO alpha-2 code, all from kuni.
+ *
+ * @example
+ * ```ts
+ * import { countryList, type CountryProps } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const first: CountryProps | undefined = countryList()[0];
+ * console.log(first?.name, first?.alpha2);
+ * ```
+ */
 export interface CountryProps {
     /** English name, from kuni (Natural Earth's own name where kuni has no entry). */
     name: string;
@@ -8,7 +18,17 @@ export interface CountryProps {
     /** ISO 3166-1 alpha-2 code, from kuni, or null where there is no code. */
     alpha2: string | null;
 }
-/** What a shared view controller tells the globe: its turn, tip, zoom and pan. */
+/**
+ * What a shared view controller tells the globe: its turn (`yaw`, degrees), tip (`tilt`, degrees), zoom (1 is Fit) and pan (`panX` and `panY`, CSS pixels).
+ *
+ * @example
+ * ```ts
+ * import { HOME_VIEW, type GlobeView } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const turned: GlobeView = { ...HOME_VIEW, yaw: 30 };
+ * console.log(turned);
+ * ```
+ */
 export interface GlobeView {
     yaw: number;
     tilt: number;
@@ -16,14 +36,44 @@ export interface GlobeView {
     panX: number;
     panY: number;
 }
-/** A point on the globe, in degrees. */
+/**
+ * A point on the globe, in degrees: `lon` from -180 to 180 (east is positive), `lat` from -90 to 90 (north is positive).
+ *
+ * @example
+ * ```ts
+ * import type { GeoPoint } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const tokyo: GeoPoint = { lon: 139.7, lat: 35.7 };
+ * console.log(tokyo);
+ * ```
+ */
 export interface GeoPoint {
     lon: number;
     lat: number;
 }
-/** How the globe is turned: [lambda, phi] in degrees, the pair d3-geo's `rotate` takes. */
+/**
+ * How the globe is turned: [lambda, phi] in degrees, the pair d3-geo's `rotate` takes.
+ *
+ * @example
+ * ```ts
+ * import { globe, type Rotation } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const rotation: Rotation = [-10, -30];
+ * console.log(globe({ rotation, size: 100 }).length > 1000);
+ * ```
+ */
 export type Rotation = [lambda: number, phi: number];
-/** What `globe()` may be asked. */
+/**
+ * What `globe()` may be asked.
+ *
+ * @example
+ * ```ts
+ * import { globe, type GlobeOptions } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const options: GlobeOptions = { size: 200, style: "thick", graticule: true, centre: { lon: 10, lat: 30 } };
+ * console.log(globe(options).startsWith("<svg"));
+ * ```
+ */
 export interface GlobeOptions {
     /** Width and height of the square SVG, in pixels. Default 320. */
     size?: number;

package/dist/view.d.ts

@@ -1,14 +1,73 @@
 import type { GeoPoint, GlobeView, Rotation } from "./types.ts";
-/** The view when it opens: the home centre, upright, at 1x with no pan. */
+/**
+ * The view when it opens: the home centre, upright, at 1x with no pan.
+ *
+ * @example
+ * ```ts
+ * import { HOME_VIEW } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(HOME_VIEW);
+ * ```
+ */
 export declare const HOME_VIEW: GlobeView;
+/**
+ * What d3-geo's orthographic projection is given for a view: its rotation, scale and translation.
+ *
+ * @example
+ * ```ts
+ * import { projectionView, type ProjectionView } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const view: ProjectionView = projectionView({ lon: 0, lat: 0 }, 400);
+ * console.log(view.scale, view.translate);
+ * ```
+ */
 export interface ProjectionView {
     rotation: Rotation;
     scale: number;
     translate: [number, number];
 }
-/** The radius of an unzoomed globe in a square of `size` pixels. */
+/**
+ * The radius of an unzoomed globe in a square of `size` pixels.
+ *
+ * @param size - The width and height of the square, in pixels.
+ * @returns The radius in pixels, one less than half the size so the rim is not cut off.
+ *
+ * @example
+ * ```ts
+ * import { globeBaseScale } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(globeBaseScale(420));
+ * ```
+ */
 export declare const globeBaseScale: (size: number) => number;
-/** Where the view is centred on the globe: the home centre, turned by yaw (west) and tipped by tilt (north), held to the poles. */
+/**
+ * Where the view is centred on the globe: the home centre, turned by yaw (west) and tipped by tilt (north), held to the poles.
+ *
+ * @param centre - The home centre.
+ * @param view - The turn, tip, zoom and pan from the view controls.
+ * @returns The place now in the middle of the disc.
+ *
+ * @example
+ * ```ts
+ * import { lookAt } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(lookAt({ lon: 10, lat: 80 }, { yaw: 25, tilt: 30, zoom: 1, panX: 0, panY: 0 }));
+ * ```
+ */
 export declare const lookAt: (centre: GeoPoint, view: GlobeView) => GeoPoint;
-/** yaw turns longitude, tilt tips latitude, zoom scales and pan moves the disc in CSS pixels. */
+/**
+ * What the projection is given for a view: yaw turns longitude, tilt tips latitude, zoom scales and pan moves the disc in CSS pixels.
+ *
+ * @param centre - The home centre.
+ * @param size - The width and height of the square the globe is drawn in, in pixels.
+ * @param view - The turn, tip, zoom and pan; the home view when left out.
+ * @returns The rotation, scale and translation for d3-geo's orthographic projection.
+ *
+ * @example
+ * ```ts
+ * import { projectionView } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(projectionView({ lon: 139.7, lat: 35.7 }, 420, { yaw: 10, tilt: 5, zoom: 2, panX: 0, panY: 0 }));
+ * ```
+ */
 export declare function projectionView(centre: GeoPoint, size: number, view?: GlobeView): ProjectionView;

package/dist/view.js

@@ -1,13 +1,61 @@
-/** The view when it opens: the home centre, upright, at 1x with no pan. */
+/**
+ * The view when it opens: the home centre, upright, at 1x with no pan.
+ *
+ * @example
+ * ```ts
+ * import { HOME_VIEW } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(HOME_VIEW);
+ * ```
+ */
 export const HOME_VIEW = Object.freeze({ yaw: 0, tilt: 0, zoom: 1, panX: 0, panY: 0 });
-/** The radius of an unzoomed globe in a square of `size` pixels. */
+/**
+ * The radius of an unzoomed globe in a square of `size` pixels.
+ *
+ * @param size - The width and height of the square, in pixels.
+ * @returns The radius in pixels, one less than half the size so the rim is not cut off.
+ *
+ * @example
+ * ```ts
+ * import { globeBaseScale } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(globeBaseScale(420));
+ * ```
+ */
 export const globeBaseScale = (size) => size / 2 - 1;
-/** Where the view is centred on the globe: the home centre, turned by yaw (west) and tipped by tilt (north), held to the poles. */
+/**
+ * Where the view is centred on the globe: the home centre, turned by yaw (west) and tipped by tilt (north), held to the poles.
+ *
+ * @param centre - The home centre.
+ * @param view - The turn, tip, zoom and pan from the view controls.
+ * @returns The place now in the middle of the disc.
+ *
+ * @example
+ * ```ts
+ * import { lookAt } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(lookAt({ lon: 10, lat: 80 }, { yaw: 25, tilt: 30, zoom: 1, panX: 0, panY: 0 }));
+ * ```
+ */
 export const lookAt = (centre, view) => ({
     lon: centre.lon - view.yaw,
     lat: Math.max(-90, Math.min(90, centre.lat + view.tilt)),
 });
-/** yaw turns longitude, tilt tips latitude, zoom scales and pan moves the disc in CSS pixels. */
+/**
+ * What the projection is given for a view: yaw turns longitude, tilt tips latitude, zoom scales and pan moves the disc in CSS pixels.
+ *
+ * @param centre - The home centre.
+ * @param size - The width and height of the square the globe is drawn in, in pixels.
+ * @param view - The turn, tip, zoom and pan; the home view when left out.
+ * @returns The rotation, scale and translation for d3-geo's orthographic projection.
+ *
+ * @example
+ * ```ts
+ * import { projectionView } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(projectionView({ lon: 139.7, lat: 35.7 }, 420, { yaw: 10, tilt: 5, zoom: 2, panX: 0, panY: 0 }));
+ * ```
+ */
 export function projectionView(centre, size, view = HOME_VIEW) {
     return {
         rotation: [-centre.lon + view.yaw, -centre.lat - view.tilt],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@johnmorrisdotca/chikyu-earth",
-  "version": "0.5.0",
-  "description": "Chikyu Earth 地球: a line-drawn globe with country outlines that turns at the Earth's own rate and opens centred on where you are. The outlines, names and codes come from chizu's world-geo (Natural Earth), drawn with d3-geo. SVG, with an optional realistic Earth from space (three.js) and markers.",
+  "version": "0.8.0",
+  "description": "Chikyu Earth 地球 — A line-drawn globe for the web: country outlines that turn at the Earth's own rate, centred on where you are, with an optional realistic Earth from space (three.js), the Sun, Moon and planets, satellites on their orbits, and markers for any place. A web component and an SVG string.",
   "keywords": [
     "earth",
     "globe",
@@ -26,7 +26,18 @@
     "markers",
     "satellite-imagery",
     "webgl",
-    "three"
+    "three",
+    "astronomy",
+    "solar-system",
+    "moon",
+    "planets",
+    "ephemeris",
+    "satellites",
+    "sgp4",
+    "orbits",
+    "iss",
+    "starlink",
+    "celestrak"
   ],
   "homepage": "https://johnmorrisdotca.github.io/chikyu-earth/",
   "repository": {
@@ -43,7 +54,9 @@
     "./dist/element.js",
     "./src/element.ts",
     "./dist/realistic/element.js",
-    "./src/realistic/element.ts"
+    "./src/realistic/element.ts",
+    "./dist/space/element.js",
+    "./src/space/element.ts"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -74,6 +87,21 @@
       "import": "./dist/markers/index.js",
       "default": "./dist/markers/index.js"
     },
+    "./space": {
+      "types": "./dist/space/index.d.ts",
+      "import": "./dist/space/index.js",
+      "default": "./dist/space/index.js"
+    },
+    "./space/element": {
+      "types": "./dist/space/element.d.ts",
+      "import": "./dist/space/element.js",
+      "default": "./dist/space/element.js"
+    },
+    "./satellites": {
+      "types": "./dist/satellites/index.d.ts",
+      "import": "./dist/satellites/index.js",
+      "default": "./dist/satellites/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -95,12 +123,20 @@
     "test:package": "pnpm build && node scripts/check-package.ts",
     "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && node scripts/check-package.ts",
     "prepublishOnly": "pnpm check",
+    "family:readme": "node scripts/family-readme.mjs",
     "site": "pnpm build && node scripts/site.ts",
     "dev": "pnpm site && node scripts/dev.ts",
-    "test:demo": "pnpm site && playwright test --project=chromium-desk --project=chromium-phone --project=webkit-desk --project=webkit-phone --project=chromium-gl",
+    "test:demo": "pnpm site && node scripts/docs-site.mjs build && playwright test --project=chromium-desk --project=chromium-phone --project=webkit-desk --project=webkit-phone --project=chromium-gl",
     "screenshots": "pnpm site && node scripts/screenshots.ts",
     "textures": "python3 scripts/make-textures.py",
-    "test:soak": "pnpm site && playwright test --project=soak"
+    "test:soak": "pnpm site && playwright test --project=soak",
+    "docs:site": "pnpm build && node scripts/docs-site.mjs build",
+    "docs:check": "pnpm build && node scripts/docs-site.mjs check",
+    "size": "node scripts/docs-site.mjs size",
+    "test:usage": "pnpm site && node scripts/check-usage.ts",
+    "test:readme": "pnpm build && node scripts/check-usage.ts readme",
+    "check:standard": "node scripts/check-standard.mjs",
+    "test:freeze": "pnpm site && playwright test e2e/freeze.demo.ts --project=chromium-desk"
   },
   "dependencies": {
     "@johnmorrisdotca/chizu": "^1.6.0",
@@ -108,7 +144,9 @@
   },
   "peerDependencies": {
     "@johnmorrisdotca/kazoku-ui": ">=0.9.0",
-    "three": ">=0.160.0"
+    "three": ">=0.160.0",
+    "astronomy-engine": ">=2.1.0",
+    "satellite.js": ">=6.0.0"
   },
   "peerDependenciesMeta": {
     "@johnmorrisdotca/kazoku-ui": {
@@ -116,22 +154,47 @@
     },
     "three": {
       "optional": true
+    },
+    "astronomy-engine": {
+      "optional": true
+    },
+    "satellite.js": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@angular/common": "^22.2.4",
+    "@angular/compiler": "^22.2.4",
+    "@angular/core": "^22.2.4",
+    "@angular/platform-browser": "^22.2.4",
     "@eslint/js": "^9.0.0",
     "@johnmorrisdotca/kazoku-ui": "^0.9.0",
     "@playwright/test": "1.64.0",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
     "@types/d3-geo": "^3.1.0",
     "@types/geojson": "^7946.0.14",
     "@types/node": "^24.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@types/three": "^0.187.0",
+    "@vitejs/plugin-vue": "^6.0.10",
     "astronomy-engine": "2.1.19",
     "esbuild": "^0.25.0",
     "eslint": "^9.0.0",
+    "marked": "^18.1.2",
+    "pagefind": "^1.6.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "rxjs": "^7.8.2",
+    "satellite.js": "6.0.2",
+    "svelte": "^5.57.3",
     "three": "0.186.1",
     "typescript": "^5.9.0",
-    "typescript-eslint": "^8.0.0"
+    "typescript-eslint": "^8.0.0",
+    "vite": "^8.3.5",
+    "vue": "^3.5.44",
+    "webpack": "^5.112.2",
+    "webpack-cli": "^7.3.1"
   },
   "publishConfig": {
     "access": "public"