@johnmorrisdotca/chikyu-earth 0.5.0 → 0.8.0

package/dist/space/element.d.ts

@@ -0,0 +1,179 @@
+import type { GeoPoint } from "../types.ts";
+import { setThreeLoader } from "../realistic/shared.ts";
+import type { SatelliteInfo, SatelliteRef, Satellites } from "../satellites/types.ts";
+import { type SatelliteStyle } from "./satellite-layer.ts";
+import { type ScaleMode } from "./scale.ts";
+import { BODY_NAMES, type BodyName, type BodyPainter } from "./scene.ts";
+export { BODY_NAMES, type BodyName };
+/**
+ * Change how the Sun and the planets are drawn (before the first element connects): the space view keeps their places, sizes, light, names and orbits and asks
+ * the painter only for what to draw at each place (see `BodyPainter`). Left alone, they are plain spheres in the right colours.
+ *
+ * @param next - The painter to use, or `undefined` for the plain one.
+ *
+ * @example
+ * ```ts no-run
+ * import { plainPainter } from "@johnmorrisdotca/chikyu-earth/space";
+ * import { setBodyPainter } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * setBodyPainter({ make: (three, name) => plainPainter.make(three, name) });
+ * ```
+ */
+export declare function setBodyPainter(next: BodyPainter | undefined): void;
+/**
+ * What a page can tell a reader about a body now.
+ *
+ * @example
+ * ```ts no-run
+ * import type { BodyInfo } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const info: BodyInfo = { name: "Mars", radiusKm: 3389.5, distanceKm: 225_000_000 };
+ * console.log(`${info.name}: ${info.radiusKm} km`);
+ * ```
+ */
+export interface BodyInfo {
+    name: BodyName;
+    /** Mean radius, kilometres. */
+    radiusKm: number;
+    /** Distance from the Earth's centre now, kilometres (0 for the Earth). */
+    distanceKm: number;
+}
+export { setThreeLoader };
+/**
+ * What the space view is doing: `loading`, `live`, `unavailable` (no WebGL), `lost` (the GPU took the context; it comes back by itself) or `idle` (another view has the page's one context).
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuSpace, SpaceState } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const stateOf = (space: ChikyuSpace): SpaceState => space.stats.state;
+ * console.log(typeof stateOf);
+ * ```
+ */
+export type SpaceState = "loading" | "live" | "unavailable" | "lost" | "idle";
+/**
+ * A named distance for `zoomFor`: the Earth, the Moon, the Sun, the inner planets or the whole solar system.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuSpace, SpacePreset } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const zoomTo = (space: ChikyuSpace, preset: SpacePreset): number => space.zoomFor(preset);
+ * console.log(typeof zoomTo);
+ * ```
+ */
+export type SpacePreset = "earth" | "moon" | "sun" | "inner" | "solar-system";
+type SatelliteStats = {
+    groups: number;
+    placed: number;
+    tooFast: boolean;
+    propagations: number;
+    lastBatchMs: number;
+    maxBatchMs: number;
+    updateMs: number;
+    maxUpdateMs: number;
+    averageUpdateMs: number;
+    updates: number;
+};
+/**
+ * The `<chikyu-space>` custom element: the Earth, the Moon, the Sun and the planets where they are at a date and time, drawn with three.js through the shared renderer. It takes `center`, `time` (`now` or an ISO date), `speed` (1 is real time, 0 holds, 86400 is a day a second, negative runs backwards), `scale` (`compressed` or `true`), `labels` and `orbits` (`off` hides them); positions are computed in the browser by astronomy-engine, an optional peer dependency. It draws only when something changes, and nothing while it is out of sight.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuSpace } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const space = document.createElement("chikyu-space") as ChikyuSpace;
+ * space.setAttribute("time", "2026-11-02T12:00Z");
+ * space.setAttribute("speed", "0");
+ * document.body.append(space);
+ * ```
+ */
+export declare class ChikyuSpace extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    get centre(): GeoPoint;
+    set centre(value: GeoPoint);
+    /** The moment shown: milliseconds since the epoch, or "now" to follow the clock. Setting it points the camera at the same place on the ground again. */
+    get time(): number;
+    set time(value: number | Date | "now");
+    /** Seconds of game time per second: 1 is real time, 0 holds still, negative runs backwards. */
+    get speed(): number;
+    set speed(value: number);
+    get scale(): ScaleMode;
+    set scale(value: ScaleMode);
+    get labels(): boolean;
+    set labels(value: boolean);
+    get orbits(): boolean;
+    set orbits(value: boolean);
+    /** The shared controls' camera: yaw and tilt turn the view, zoom brings the camera in (1 shows the Earth, less shows the sky round it). Pan is not used. */
+    setView(view: {
+        yaw: number;
+        tilt: number;
+        zoom: number;
+    }): void;
+    /** The body the camera looks at: at zoom 1 it fills the view; the yaw and tilt turn the camera round it. */
+    get body(): BodyName;
+    set body(name: BodyName);
+    /**
+     * Show a group of satellites (made by `createSatellites`) under a name, or take the group away with `null`. A group is one draw call however many satellites it holds. Giving the name of a group
+     * that is already shown replaces it. `style`: `color` and `size` (CSS pixels) of the dots, and `orbits` to draw every orbit (only for a group of 40 or fewer, such as the stations).
+     * The groups are placed by SGP4 about once a second and interpolated between, and are hidden while the clock runs faster than `MAX_SATELLITE_SPEED`.
+     *
+     * @param group - The group's name, for `showSatellites`, `selectSatellite` and the events.
+     * @param satellites - The group, or `null` to remove it.
+     * @param style - How to draw it.
+     */
+    setSatellites(group: string, satellites: Satellites | null, style?: Partial<SatelliteStyle>): void;
+    /** Show or hide a group without losing it. */
+    showSatellites(group: string, on: boolean): void;
+    /** The groups now set, with how many satellites each holds and whether it is shown. */
+    get satelliteGroups(): {
+        name: string;
+        count: number;
+        visible: boolean;
+    }[];
+    /** Mark one satellite: a larger ring round it, its orbit drawn, and its name beside it. `null` lets it go. */
+    selectSatellite(ref: SatelliteRef | null): void;
+    /** The satellite marked by `selectSatellite` or by a press on it, if any. */
+    get selectedSatellite(): SatelliteRef | null;
+    /** Facts about one satellite at the moment shown (name, number, element age, height, speed, period); undefined if it cannot be placed then. */
+    satelliteInfo(ref: SatelliteRef): SatelliteInfo | undefined;
+    /** The words shown beside each body, for a page in another language (`{ Mars: "火星" }`). A body left out keeps its English name. */
+    get bodyNames(): Partial<Record<BodyName, string>>;
+    set bodyNames(value: Partial<Record<BodyName, string>>);
+    /** What a screen reader hears after a body's name: "choose to look at it" by default, or the page's own words. */
+    get bodyHint(): string;
+    set bodyHint(value: string);
+    /** The radius and the distance from the Earth of a body now, for a page's own caption. */
+    bodyInfo(name: BodyName): BodyInfo;
+    /** The zoom that shows a part of the sky: the Earth alone, the Moon's orbit, the Sun, the planets out to Mars, or all of them, at this scale and moment. */
+    zoomFor(preset: SpacePreset): number;
+    /** What the element is doing, for a page or a test. */
+    get stats(): {
+        state: SpaceState;
+        draws: number;
+        contexts: number;
+        canvas: {
+            width: number;
+            height: number;
+            pixels: number;
+        };
+        tiers: Record<string, number>;
+        distance: number;
+        assets: {
+            entries: number;
+            refs: number;
+        };
+        time: number;
+        lookups: number;
+        satellites: SatelliteStats;
+    };
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "chikyu-space": ChikyuSpace;
+    }
+}