@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.4.0

package/dist/data/flight-log.js

@@ -1,3 +1,13 @@
+/**
+ * The flights this package keeps a record of, each from a named source. Use `flightLogOf` for one rocket.
+ *
+ * @example
+ * ```ts
+ * import { FLIGHT_LOG } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(FLIGHT_LOG.length > 0);
+ * ```
+ */
 export const FLIGHT_LOG = [
     { id: "falcon-1-flight-1", name: "Falcon 1, flight 1", rocket: "falcon-1", variant: "falcon-1", date: "2006-03-24", launch: "Failure", outcome: "Engine failure at T+33 seconds, and the vehicle was lost.", source: "wikipedia-falcon-1" },
     { id: "falcon-1-flight-2", name: "Falcon 1, flight 2", rocket: "falcon-1", variant: "falcon-1", date: "2007-03-21", launch: "Failure", outcome: "Reached 289 km and did not reach orbit: an oscillation of the second stage, and an early engine shutdown.", source: "wikipedia-falcon-1" },
@@ -19,5 +29,16 @@ export const FLIGHT_LOG = [
     { id: "starship-flight-13", name: "Starship flight 13", rocket: "starship", variant: "v3", date: "2026-07-24", launch: "Success", vehicles: "Booster B20, Ship S40", outcome: "Booster: Failure (gulf). Ship: Controlled (ocean).", source: "wikipedia-launches" },
     { id: "starship-flight-14", name: "Starship flight 14", rocket: "starship", variant: "v3", date: "2026-09-28", launch: "Success", vehicles: "Booster B21, Ship S41", outcome: "Booster: Controlled (gulf). Ship: Controlled (ocean).", source: "wikipedia-launches" },
 ];
-/** A rocket's flights, in order. */
+/**
+ * A rocket's flights, in order.
+ *
+ * @param rocket A rocket's id, such as `falcon-1`.
+ * @returns That rocket's logged flights, in order. It is empty for a rocket with none.
+ * @example
+ * ```ts
+ * import { flightLogOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(flightLogOf("falcon-1").map((flight) => flight.name));
+ * ```
+ */
 export const flightLogOf = (rocket) => FLIGHT_LOG.filter((flight) => flight.rocket === rocket);

package/dist/data/flights.d.ts

@@ -1,6 +1,16 @@
 import { type Figure } from "./types.ts";
 import type { SourceId } from "./sources.ts";
-/** How a part stands in the picture at a phase. A picture, not a measurement: `dx` and `dy` are in heights of the whole vehicle. */
+/**
+ * How a part stands in the picture at a phase. A picture, not a measurement: `dx` and `dy` are in heights of the whole vehicle.
+ *
+ * @example
+ * ```ts
+ * import type { PartPose } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const pose: PartPose = { dx: 0.2, dy: -0.1, pitch: 12 };
+ * console.log(pose);
+ * ```
+ */
 export interface PartPose {
     dx?: number;
     dy?: number;
@@ -11,11 +21,32 @@ export interface PartPose {
     /** It has left the picture. */
     gone?: boolean;
 }
-/** How many engines of a part burn. `drawn` says how many flames to draw where no page says how many burned. */
+/**
+ * How many engines of a part burn. `drawn` says how many flames to draw where no page says how many burned.
+ *
+ * @example
+ * ```ts
+ * import type { FlightBurn } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const burn: FlightBurn = { engines: { value: null, source: null, brief: "not given" }, drawn: 9 };
+ * console.log(burn);
+ * ```
+ */
 export interface FlightBurn {
     engines: Figure;
     drawn?: number;
 }
+/**
+ * One phase of a flight: its id and name, what happens, when (a figure with its source), how many engines burn, how each part stands, and how far the ground has fallen away. The poses and the smoke are a picture, not a measurement.
+ *
+ * @example
+ * ```ts
+ * import { FLIGHTS, type FlightPhase } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const phase: FlightPhase | undefined = FLIGHTS[0]?.phases[0];
+ * console.log(phase?.name, phase?.what);
+ * ```
+ */
 export interface FlightPhase {
     id: string;
     name: string;
@@ -34,6 +65,17 @@ export interface FlightPhase {
     altitude?: Figure<string>;
     speed?: Figure<string>;
 }
+/**
+ * A flight, from a published timeline: its rocket and variant, whose timing it is, its source and its phases in order.
+ *
+ * @example
+ * ```ts
+ * import { FLIGHTS, type Flight } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight: Flight | undefined = FLIGHTS[0];
+ * console.log(flight?.name, flight?.phases.length);
+ * ```
+ */
 export interface Flight {
     id: string;
     rocket: string;
@@ -46,4 +88,14 @@ export interface Flight {
     note?: string;
     phases: readonly FlightPhase[];
 }
+/**
+ * Every flight the package can play, one for each variant that has a timeline. Use `flightOf` to find one.
+ *
+ * @example
+ * ```ts
+ * import { FLIGHTS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(FLIGHTS.map((flight) => `${flight.rocket}:${flight.variant}`));
+ * ```
+ */
 export declare const FLIGHTS: readonly Flight[];

package/dist/data/flights.js

@@ -65,6 +65,16 @@ const FH = "wikipedia-fh-test-flight";
 const STARLINK = "sfn-starlink-2019";
 const CRS16 = "sfn-crs-16";
 const lower = (dy, extra = {}) => ({ dx: -0.26, dy, ...extra });
+/**
+ * Every flight the package can play, one for each variant that has a timeline. Use `flightOf` to find one.
+ *
+ * @example
+ * ```ts
+ * import { FLIGHTS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(FLIGHTS.map((flight) => `${flight.rocket}:${flight.variant}`));
+ * ```
+ */
 export const FLIGHTS = [
     starshipFlight({
         id: "starship-flight-5",

package/dist/data/makers.d.ts

@@ -1,4 +1,14 @@
 import { type Figure } from "./types.ts";
+/**
+ * The groups the demo lists rockets under, by id, with the name shown for each.
+ *
+ * @example
+ * ```ts
+ * import { MAKERS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAKERS.spacex, Object.keys(MAKERS).length);
+ * ```
+ */
 export declare const MAKERS: {
     readonly spacex: "SpaceX";
     readonly nasa: "NASA and partners";
@@ -8,6 +18,17 @@ export declare const MAKERS: {
     readonly "us-army": "US Army";
     readonly sites: "Sites";
 };
+/**
+ * The id of a group in `MAKERS`.
+ *
+ * @example
+ * ```ts
+ * import type { MakerId } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const maker: MakerId = "nasa";
+ * console.log(maker);
+ * ```
+ */
 export type MakerId = keyof typeof MAKERS;
 export interface MadeBy {
     maker: MakerId;

package/dist/data/makers.js

@@ -1,5 +1,15 @@
 // Whose each rocket is, as its own article's infobox and first lines say, read 2026-11-02. `maker` is how the demo groups them; `by` says what the source says, with the companies that built it where it names them. The sites have no maker here: a blank, not a guess.
 import { blank } from "./types.js";
+/**
+ * The groups the demo lists rockets under, by id, with the name shown for each.
+ *
+ * @example
+ * ```ts
+ * import { MAKERS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAKERS.spacex, Object.keys(MAKERS).length);
+ * ```
+ */
 export const MAKERS = { spacex: "SpaceX", nasa: "NASA and partners", "blue-origin": "Blue Origin", "rocket-lab": "Rocket Lab", russia: "Russia", "us-army": "US Army", sites: "Sites" };
 const SITE = { maker: "sites", madeBy: blank("A place or a ship, not a vehicle: its maker is not read here.") };
 export const MADE_BY = {

package/dist/data/sources.d.ts

@@ -1,3 +1,14 @@
+/**
+ * A source of a figure: its title, publisher and address, the date on it where it has one, how it was read (directly, by search or cited) and its licence.
+ *
+ * @example
+ * ```ts
+ * import { SOURCES, type Source } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const source: Source = SOURCES["wikipedia-starship"];
+ * console.log(source.publisher, source.read);
+ * ```
+ */
 export interface Source {
     title: string;
     publisher: string;
@@ -7,6 +18,16 @@ export interface Source {
     read: "direct" | "search" | "cited";
     licence?: string;
 }
+/**
+ * Every source a figure can name, by id. A figure carries only an id; look the id up here for the page it came from.
+ *
+ * @example
+ * ```ts
+ * import { SOURCES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(Object.keys(SOURCES).length > 20, SOURCES["wikipedia-starship"].url);
+ * ```
+ */
 export declare const SOURCES: {
     readonly "wikipedia-starship": {
         readonly title: "SpaceX Starship (the block table and infobox, read as raw wikitext)";
@@ -524,4 +545,15 @@ export declare const SOURCES: {
         readonly read: "direct";
     };
 };
+/**
+ * The id of a source in `SOURCES`.
+ *
+ * @example
+ * ```ts
+ * import type { SourceId } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const id: SourceId = "wikipedia-starship";
+ * console.log(id);
+ * ```
+ */
 export type SourceId = keyof typeof SOURCES;

package/dist/data/sources.js

@@ -1,5 +1,15 @@
 // Every source a figure may name. Plain facts are taken from these, and each figure says which one it came from. `read` is how this project read it: "direct" means the page itself, "search" that only
 // a search engine's quote of it could be read, and "cited" that it is known through another source's citation.
+/**
+ * Every source a figure can name, by id. A figure carries only an id; look the id up here for the page it came from.
+ *
+ * @example
+ * ```ts
+ * import { SOURCES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(Object.keys(SOURCES).length > 20, SOURCES["wikipedia-starship"].url);
+ * ```
+ */
 export const SOURCES = {
     "wikipedia-starship": { title: "SpaceX Starship (the block table and infobox, read as raw wikitext)", publisher: "Wikipedia", url: "https://en.wikipedia.org/wiki/SpaceX_Starship", date: "2026-10-31", read: "direct", licence: "CC BY-SA 4.0" },
     "wikipedia-super-heavy": { title: "SpaceX Super Heavy", publisher: "Wikipedia", url: "https://en.wikipedia.org/wiki/SpaceX_Super_Heavy", date: "2026-10-31", read: "direct", licence: "CC BY-SA 4.0" },

package/dist/data/types.d.ts

@@ -1,9 +1,31 @@
 import type { SourceId } from "./sources.ts";
+/**
+ * Another value a source gave for a figure, with the source and the reason it was not the one chosen.
+ *
+ * @example
+ * ```ts
+ * import { variantOf, type Disagreement } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const others: readonly Disagreement<number>[] = variantOf("starship", "v3")?.facts.parts.booster?.others ?? [];
+ * console.log(others.map((other) => other.value));
+ * ```
+ */
 export interface Disagreement<T> {
     value: T;
     source: SourceId;
     note: string;
 }
+/**
+ * A number or a text with where it came from. A figure with no source is blank (`value` is null) and is never estimated. Where sources disagree, the figure keeps the one chosen and `others` holds the rest.
+ *
+ * @example
+ * ```ts
+ * import { variantOf, type Figure } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const height: Figure | undefined = variantOf("starship", "v3")?.facts.height;
+ * console.log(height?.value, height?.source);
+ * ```
+ */
 export interface Figure<T = number> {
     value: T | null;
     source: SourceId | null;
@@ -14,10 +36,57 @@ export interface Figure<T = number> {
     brief?: string;
     others?: readonly Disagreement<T>[];
 }
+/**
+ * A figure with no value: the shape of "no source gives this".
+ *
+ * @param note Why there is no value. Optional.
+ * @param brief What to say in place of a value wherever it is shown. Optional.
+ * @returns A figure whose value and source are null.
+ * @example
+ * ```ts
+ * import { blank } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(blank("No source read gives it.", "not given"));
+ * ```
+ */
 export declare const blank: <T = number>(note?: string, brief?: string) => Figure<T>;
-/** A figure as words for a table: its value and whatever must stay beside it; a blank says why, or that no source gives it. */
+/**
+ * A figure as words for a table: its value and whatever must stay beside it; a blank says why, or that no source gives it.
+ *
+ * @param figure A figure, or undefined.
+ * @param unit Text to put after a number, such as " m". Optional.
+ * @returns The figure as words for a table. A blank gives its `brief`, or "No source" when it has none.
+ * @example
+ * ```ts
+ * import { figureWords, variantOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(figureWords(variantOf("starship", "v3")?.facts.height, " m"));
+ * ```
+ */
 export declare function figureWords(figure: Figure<number | string> | undefined, unit?: string): string;
+/**
+ * What kind of thing a variant is: flown, announced (not built), an artist's model, a test vehicle or a support item.
+ *
+ * @example
+ * ```ts
+ * import { variantOf, type VariantStatus } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const status: VariantStatus | undefined = variantOf("starship", "v4")?.status;
+ * console.log(status);
+ * ```
+ */
 export type VariantStatus = "flown" | "announced" | "artist-model" | "test-vehicle" | "support";
+/**
+ * The sourced numbers of a variant: its height and diameter, each part's height by slot, its engines, other facts and any sizes that are not a height or a width.
+ *
+ * @example
+ * ```ts
+ * import { variantOf, type VariantFacts } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const facts: VariantFacts | undefined = variantOf("falcon-9", "block-5")?.facts;
+ * console.log(facts?.height.value, Object.keys(facts?.parts ?? {}));
+ * ```
+ */
 export interface VariantFacts {
     /** Overall height with every part in place, metres. */
     height: Figure;
@@ -31,6 +100,17 @@ export interface VariantFacts {
     /** Sizes that are not a height or a width, shown as they are named here: "Deck length". */
     sizes?: Readonly<Record<string, Figure>>;
 }
+/**
+ * One version of a rocket as data: its id, name, status, first flight, its parts from the bottom up, and the sourced facts about it.
+ *
+ * @example
+ * ```ts
+ * import { variantOf, type Variant } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const variant: Variant | undefined = variantOf("starship", "v3");
+ * console.log(variant?.name, variant?.slots);
+ * ```
+ */
 export interface Variant {
     /** "v1", "v2" and so on; a label for what is not a numbered version. */
     id: string;

package/dist/data/types.js

@@ -1,5 +1,30 @@
+/**
+ * A figure with no value: the shape of "no source gives this".
+ *
+ * @param note Why there is no value. Optional.
+ * @param brief What to say in place of a value wherever it is shown. Optional.
+ * @returns A figure whose value and source are null.
+ * @example
+ * ```ts
+ * import { blank } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(blank("No source read gives it.", "not given"));
+ * ```
+ */
 export const blank = (note, brief) => ({ value: null, source: null, ...(note ? { note } : {}), ...(brief ? { brief } : {}) });
-/** A figure as words for a table: its value and whatever must stay beside it; a blank says why, or that no source gives it. */
+/**
+ * A figure as words for a table: its value and whatever must stay beside it; a blank says why, or that no source gives it.
+ *
+ * @param figure A figure, or undefined.
+ * @param unit Text to put after a number, such as " m". Optional.
+ * @returns The figure as words for a table. A blank gives its `brief`, or "No source" when it has none.
+ * @example
+ * ```ts
+ * import { figureWords, variantOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(figureWords(variantOf("starship", "v3")?.facts.height, " m"));
+ * ```
+ */
 export function figureWords(figure, unit = "") {
     if (!figure || figure.value === null)
         return figure?.brief ?? "No source";

package/dist/element.d.ts

@@ -3,10 +3,45 @@ import { UchusenFlight } from "./flightbar.ts";
 import type { Description, FitReport } from "./fit.ts";
 import { type Angle, type ViewChoice } from "./framing.ts";
 import { ROCKETS } from "./rockets.ts";
+/**
+ * What a `<uchusen-rocket>` is doing, as its `data-state` attribute says: `picture` (the drawing), `loading` (the 3D view is on its way), `3d`, `fallback` (no WebGL, so the drawing stays) or `error`.
+ *
+ * @example
+ * ```ts
+ * import type { RocketState } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * const states: RocketState[] = ["picture", "loading", "3d", "fallback", "error"];
+ * console.log(states.length);
+ * ```
+ */
 export type RocketState = "picture" | "loading" | "3d" | "fallback" | "error";
 declare const HTMLBase: typeof HTMLElement;
-/** Where the licensed models are, for every element with no `assets` attribute of its own. Left unset: beside this module, in ./assets/. */
+/**
+ * Where the licensed models are, for every element with no `assets` attribute of its own. Left unset: beside this module, in ./assets/.
+ *
+ * @param url The folder the licensed models are in. A trailing slash is added if it has none.
+ * @example
+ * ```ts no-run
+ * import { setAssetBase } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * setAssetBase("/static/uchusen-assets/");
+ * ```
+ */
 export declare function setAssetBase(url: string): void;
+/**
+ * The `<uchusen-rocket>` element: a rocket as a drawing that a 3D view takes over from when the browser can draw WebGL. Its attributes are the words of `RocketOptions`. It exposes its state as `data-state` and loads three.js only for a 3D view.
+ *
+ * @example
+ * ```ts no-run
+ * import { UchusenRocket } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * const rocket: UchusenRocket = document.createElement("uchusen-rocket") as UchusenRocket;
+ * rocket.setAttribute("rocket", "starship");
+ * rocket.setAttribute("variant", "v3");
+ * rocket.setAttribute("look", "painted");
+ * document.body.append(rocket);
+ * ```
+ */
 export declare class UchusenRocket extends HTMLBase {
     static readonly observedAttributes: string[];
     private descriptionValue;
@@ -117,14 +152,37 @@ export declare class UchusenRocket extends HTMLBase {
     private start;
     private startTilt;
 }
-/** Rockets side by side on one baseline at one scale: `<uchusen-lineup items="starship:v1,starship:v3,person,building" unit="4" ruler labels>`. */
+/**
+ * Rockets side by side on one baseline at one scale: `<uchusen-lineup items="starship:v1,starship:v3,person,building" unit="4" ruler labels>`.
+ *
+ * @example
+ * ```ts no-run
+ * import { UchusenLineup } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * const lineup: UchusenLineup = document.createElement("uchusen-lineup") as UchusenLineup;
+ * lineup.setAttribute("items", "starship:v2,starship:v3,person");
+ * lineup.setAttribute("unit", "3");
+ * lineup.toggleAttribute("ruler", true);
+ * document.body.append(lineup);
+ * ```
+ */
 export declare class UchusenLineup extends HTMLBase {
     static readonly observedAttributes: string[];
     connectedCallback(): void;
     attributeChangedCallback(name: string, before: string | null, after: string | null): void;
     private render;
 }
-/** Defines both elements, once. Importing this module does it. */
+/**
+ * Defines both elements, once. Importing this module does it.
+ *
+ * @example
+ * ```ts no-run
+ * import { defineUchusenRocket } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * defineUchusenRocket();
+ * console.log(customElements.get("uchusen-rocket") !== undefined);
+ * ```
+ */
 export declare function defineUchusenRocket(): void;
 export { ROCKETS, UchusenFlight };
 declare global {

package/dist/element.js

@@ -21,7 +21,17 @@ const RELEASE_MS = 30_000;
 /** The drawing, followed along a turn, is made again at most this often. */
 const PLACE_MS = 50;
 let assetBase = null;
-/** Where the licensed models are, for every element with no `assets` attribute of its own. Left unset: beside this module, in ./assets/. */
+/**
+ * Where the licensed models are, for every element with no `assets` attribute of its own. Left unset: beside this module, in ./assets/.
+ *
+ * @param url The folder the licensed models are in. A trailing slash is added if it has none.
+ * @example
+ * ```ts no-run
+ * import { setAssetBase } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * setAssetBase("/static/uchusen-assets/");
+ * ```
+ */
 export function setAssetBase(url) {
     assetBase = url.endsWith("/") ? url : `${url}/`;
 }
@@ -86,6 +96,20 @@ function whyNot(mode) {
         return "no-webgl";
     return "";
 }
+/**
+ * The `<uchusen-rocket>` element: a rocket as a drawing that a 3D view takes over from when the browser can draw WebGL. Its attributes are the words of `RocketOptions`. It exposes its state as `data-state` and loads three.js only for a 3D view.
+ *
+ * @example
+ * ```ts no-run
+ * import { UchusenRocket } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * const rocket: UchusenRocket = document.createElement("uchusen-rocket") as UchusenRocket;
+ * rocket.setAttribute("rocket", "starship");
+ * rocket.setAttribute("variant", "v3");
+ * rocket.setAttribute("look", "painted");
+ * document.body.append(rocket);
+ * ```
+ */
 export class UchusenRocket extends HTMLBase {
     static observedAttributes = ["rocket", "variant", "show", "look", "view", "build", "mode", "assets", "spin", "way", "label", "engines", "phase"];
     descriptionValue = null;
@@ -715,7 +739,20 @@ const LINEUP_CSS = `
 :host { display: block; overflow-x: auto; color: inherit; }
 svg { display: block; }
 `;
-/** Rockets side by side on one baseline at one scale: `<uchusen-lineup items="starship:v1,starship:v3,person,building" unit="4" ruler labels>`. */
+/**
+ * Rockets side by side on one baseline at one scale: `<uchusen-lineup items="starship:v1,starship:v3,person,building" unit="4" ruler labels>`.
+ *
+ * @example
+ * ```ts no-run
+ * import { UchusenLineup } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * const lineup: UchusenLineup = document.createElement("uchusen-lineup") as UchusenLineup;
+ * lineup.setAttribute("items", "starship:v2,starship:v3,person");
+ * lineup.setAttribute("unit", "3");
+ * lineup.toggleAttribute("ruler", true);
+ * document.body.append(lineup);
+ * ```
+ */
 export class UchusenLineup extends HTMLBase {
     static observedAttributes = ["items", "unit", "look", "view", "show", "ruler", "labels"];
     connectedCallback() {
@@ -754,7 +791,17 @@ export class UchusenLineup extends HTMLBase {
         this.dataset.count = String(shown.length);
     }
 }
-/** Defines both elements, once. Importing this module does it. */
+/**
+ * Defines both elements, once. Importing this module does it.
+ *
+ * @example
+ * ```ts no-run
+ * import { defineUchusenRocket } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * defineUchusenRocket();
+ * console.log(customElements.get("uchusen-rocket") !== undefined);
+ * ```
+ */
 export function defineUchusenRocket() {
     if (typeof customElements === "undefined")
         return;