spacemap 0.1.3 → 0.1.5

package/index.d.ts

@@ -289,6 +289,18 @@ export declare interface CoreMessages {
     cooperative_wheel: () => string;
     cooperative_wheel_mac: () => string;
     cooperative_touch: () => string;
+    planetary_system_primary: () => string;
+    planetary_system_retrograde: () => string;
+    planetary_system_axis_unit: () => string;
+    tab_rings: () => string;
+    system_map_solar_system: () => string;
+    system_map_moons: (inputs: {
+        count: number;
+    }) => string;
+    system_map_zone_inner: () => string;
+    system_map_zone_outer: () => string;
+    unit_symbol_astronomical_unit: () => string;
+    system_map_axis_au: () => string;
 }
 
 /**
@@ -340,6 +352,15 @@ export declare function createPanorama(options: PanoramaCreateOptions): Promise<
  *  the extent sampling. */
 export declare function createProjection(id: ProjectionId, options?: ProjectionOptions): Projection;
 
+/** Mount a system map and resolve once its first view is drawn. It is as wide
+ *  as its container and three times as wide as it is tall. A click reports
+ *  what was picked and goes nowhere: following it is {@link SystemMap.setView},
+ *  which the page calls or does not.
+ *
+ *  Rejects when the data does not load, or the opening view is a `system`
+ *  named for a body with no moons. */
+export declare function createSystemMap(options: SystemMapCreateOptions): Promise<SystemMap>;
+
 /** Convert a JS Date to Julian Date. */
 export declare function dateToJD(date: Date): number;
 
@@ -393,9 +414,9 @@ export declare interface FeatureTarget extends CameraTarget {
  *  joins the page's own load rather than starting a second one. */
 export declare function fetchPanoramaIndex(fetcher?: (url: string) => Promise<Response>): Promise<PanoramaBodySummary[]>;
 
-/** Every panorama taken on a body, mission by mission in time order. The view
- *  reads the same list when it opens; a page that decides which panorama to
- *  open reads it first. Empty when the body has none. */
+/** Every panorama taken on a body, mission by mission in time order: the list
+ *  the view reads when it opens, before it drops the stops it cannot show
+ *  ({@link isViewable}). Empty when the body has none. */
 export declare function fetchPanoramas(bodyId: string): Promise<PanoramaEntry[]>;
 
 export declare function findPanorama(entries: PanoramaEntry[], at: string | null): PanoramaEntry | null;
@@ -937,6 +958,10 @@ export declare type Interpolation =
 *  track means by a straight line. */
 | 'geodesic';
 
+/** Whether a stop has a sphere to open, as against a place on the traverse:
+ *  one exists, and this host's terms reach it. */
+export declare function isViewable(entry: PanoramaEntry): boolean;
+
 /** Convert a Julian Date to a JS Date. */
 export declare function jdToDate(jd: number): Date;
 
@@ -1562,6 +1587,9 @@ export declare interface PolylineOptions {
     widthPx?: number;
     /** 0 to 1. */
     opacity?: number;
+    /** A dash and a gap in screen pixels, written as the flat map takes them:
+     *  `"4 3"`. Solid when left out. */
+    dash?: string;
     /** Fade the line toward its last point, the way an orbit trail fades
      *  behind a body. */
     fade?: boolean;
@@ -1855,6 +1883,23 @@ export declare class SpaceMap {
     /** Ids of the objects orbiting `id` that this map has loaded. Loading is
      *  driven by focus and by the clock, so the list grows as the reader moves. */
     getChildren(id: string): string[];
+    /** The date the measures answer for: the one the bodies are placed at,
+     *  which the clock runs ahead of while no frame is drawn. */
+    private get placedJd();
+    /** Kilometres between two places, as the last frame drew them: a body's
+     *  centre, a point on its surface, anything an anchor names. Null while
+     *  either end is on a body this map has not loaded, or one that is nowhere
+     *  at that date. */
+    distanceKm(from: Anchor, to: Anchor): number | null;
+    /** The same measure with its direction kept: from one place to the other,
+     *  in kilometres on ecliptic J2000 axes. What a held camera's `up` is made
+     *  from, when up is a way along a body's surface. */
+    offsetKm(from: Anchor, to: Anchor): OffsetKm | null;
+    /** Where on `id` the Sun is overhead, as the last frame drew it: the middle
+     *  of the lit half, in the frame a surface anchor is placed in. Null for a
+     *  body not loaded, and until the map has read how it spins, which it does
+     *  once the camera is on the body or its system. */
+    getSubsolarPoint(id: string): LonLat | null;
     /* Excluded from this release type: load */
     /* Excluded from this release type: open */
     /* Excluded from this release type: applyInitialView */
@@ -1993,6 +2038,17 @@ export declare class SpaceMap {
      * is nothing to choose once a host has said what it looks like.
      */
     setBodyAppearance(id: string, appearance: BodyAppearance): this;
+    /**
+     * Keep these bodies in sight from however far: named, with their orbits,
+     * where the map would let a small or distant one drop out and would give
+     * its name up to a bigger neighbour's. A hidden layer does not take them
+     * either. An id the map has not loaded yet is pinned once it has. Each call
+     * replaces the last; an empty list gives the map its own judgement back.
+     *
+     * A moon is only drawn inside the system the camera is in, pinned or not:
+     * pin its planet to mark it from outside.
+     */
+    setPinnedBodies(ids: readonly string[]): this;
     /** A cap's radius as an angle, from whichever of the two ways the host gave
      *  it. A radius in kilometres needs the body's own radius, which an
      *  unloaded body has not published yet. */
@@ -2072,6 +2128,9 @@ export declare interface SurfacePolygonOptions extends SurfaceShapeOptions {
 export declare interface SurfacePolylineOptions extends SurfaceShapeOptions {
     /** Join the last place back to the first. */
     closed?: boolean;
+    /** A dash and a gap in screen pixels, written as the flat map takes them:
+     *  `"4 3"`. Solid when left out. */
+    dash?: string;
 }
 
 /** A shape on a body's surface, for as long as the host keeps it. */
@@ -2100,6 +2159,153 @@ export declare interface SurfaceShapeOptions extends ShapeStyle {
     altitudeKm?: number;
 }
 
+/** The diagram and what it shows. It follows no click: `select` says what was
+ *  picked and {@link SystemMap.setView} is the page's to call. */
+export declare class SystemMap {
+    private readonly chart;
+    private readonly listeners;
+    private view;
+    private bodies;
+    private readonly names;
+    private readonly grouping;
+    private readonly zones;
+    private readonly places;
+    private targets;
+    /** Bundles read for the bodies no map file places, by id; null where the
+     *  bundle has no orbit to place it by. */
+    private readonly extras;
+    /** Draws run one after another, so a later one neither lands under an
+     *  earlier nor takes it off the map by failing. */
+    private queue;
+    private disposed;
+    constructor(options?: SystemMapOptions);
+    /* Excluded from this release type: mount */
+    /** Take the map back out of its container. It is finished afterwards; open
+     *  another with {@link createSystemMap}. */
+    remove(): void;
+    /* Excluded from this release type: load */
+    /** Draw another view. Resolves once it is on screen; rejects, leaving the
+     *  map as it was, when the view cannot be loaded — a `system` named for a
+     *  body with no moons has no map. */
+    setView(view: SystemMapView): Promise<void>;
+    getView(): SystemMapView;
+    /** Change which bodies are worth drawing; null for all of them. The view
+     *  stays, redrawn: resolves once it is, and `error` says when it could not be. */
+    setBodies(ids: readonly string[] | null): Promise<void>;
+    /** Everything a click on the current view can pick. */
+    getTargets(): SystemMapTarget[];
+    /** Draw `view`, or the one on the map, in its turn. `bodies` is taken up
+     *  at that turn too, so it never changes under a draw that is under way. */
+    private draw;
+    private drawNow;
+    private build;
+    /** One body's own bundle, read once. A body that cannot be read is left
+     *  off the map and reported, rather than taking the view down with it. */
+    private extra;
+    /** The primary's and its notable moons' names as the export has them, in
+     *  the reading language where it has them in it. Empty when the bundle does not load: the map then
+     *  falls back to ids rather than failing over a label. */
+    private exportedNames;
+    /** Listen for `event`. The returned function stops listening, which is the
+     *  same thing {@link off} does. */
+    on<K extends keyof SystemMapEvents>(event: K, listener: SystemMapEvents[K]): () => void;
+    /** Listen for the next `event` only. */
+    once<K extends keyof SystemMapEvents>(event: K, listener: SystemMapEvents[K]): () => void;
+    off<K extends keyof SystemMapEvents>(event: K, listener: SystemMapEvents[K]): void;
+    private emit;
+}
+
+export declare interface SystemMapCreateOptions extends CommonOptions, SystemMapOptions {
+    /** Listeners attached before the first load, so a failed one is observable
+     *  while it runs. Later ones go through {@link SystemMap.on}. */
+    events?: {
+        [K in keyof SystemMapEvents]?: SystemMapEvents[K];
+    };
+}
+
+export declare interface SystemMapEvents {
+    /** Something was picked. The map does not follow it: {@link SystemMap.setView}
+     *  is the host's to call. */
+    select: (target: SystemMapTarget) => void;
+    viewchange: (view: SystemMapView) => void;
+    /** A view could not be loaded, or a body named in `bodies` could not be read. */
+    error: (error: Error) => void;
+}
+
+export declare interface SystemMapOptions {
+    /** What to draw first; the Solar System when omitted. */
+    view?: SystemMapView;
+    /** The ids worth drawing, for a map that offers part of the catalogue. A
+     *  primary outside them is still drawn while a moon of it is in, as the
+     *  thing the moon is found by. Everything the export lists when omitted. */
+    bodies?: readonly string[];
+    /** Names by id, over the export's own. */
+    names?: Record<string, string>;
+    /** Bodies neither map file places, described by the page so the map need
+     *  not read each one's bundle to draw it in its zone. */
+    places?: readonly SystemMapPlace[];
+    /** `systems` makes a primary and the moons stacked on it one target, a
+     *  `system`; `bodies` leaves the dot and the stack a target each. */
+    grouping?: 'bodies' | 'systems';
+    /** `inner-outer` turns the two belts into the doors of the two zones of
+     *  small bodies; `belts` leaves them the scenery they are. */
+    zones?: 'belts' | 'inner-outer';
+}
+
+/**
+ * A body the map files name no place for, as a page that already knows it
+ * describes it. The map otherwise reads the body's own bundle to place it,
+ * which is a few hundred kilobytes a body.
+ */
+export declare interface SystemMapPlace {
+    id: string;
+    /** The id when left out, unless `names` has one. */
+    name?: string;
+    /** A moon rides in the stack over `parent` rather than on the axis. */
+    moon?: boolean;
+    /** Semi-major axis about the Sun in AU, or the perihelion of an orbit that
+     *  has none. A moon needs none. */
+    aAu?: number;
+    /** Inclination to the ecliptic. */
+    tiltDeg?: number;
+    radiusKm?: number;
+    /** `#rrggbb`. */
+    color?: string;
+    /** What a moon orbits. */
+    parent?: string;
+}
+
+/** What a click picked. A `system` is a primary drawn with satellites, named
+ *  by the primary's id. */
+export declare type SystemMapTarget = {
+    kind: 'body';
+    id: string;
+    name: string;
+} | {
+    kind: 'system';
+    id: string;
+    name: string;
+} | {
+    kind: 'zone';
+    zone: SystemMapZone;
+    name: string;
+};
+
+export declare type SystemMapView = {
+    kind: 'solar-system';
+}
+/** One planetary system, named by its primary: `naif-699`, `naif-999`. */
+| {
+    kind: 'system';
+    id: string;
+} | {
+    kind: 'zone';
+    zone: SystemMapZone;
+};
+
+/** Small bodies inside Jupiter's orbit, or from it outward. */
+export declare type SystemMapZone = 'inner' | 'outer';
+
 /** Who may serve a surface map, widest first. A body whose map this embed may
  *  not draw renders in its fallback colour, as an untextured body does. */
 declare type TextureDistribution = 'open' | 'non-commercial' | 'site-only';