@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.5.0

package/dist/builder.d.ts

@@ -1,10 +1,32 @@
 import { type Description, type FitReport } from "./fit.ts";
+/**
+ * One part a row of the builder offers: its id, its name and the rocket it comes from.
+ *
+ * @example
+ * ```ts
+ * import { builderState, type BuilderOption } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const first: BuilderOption | undefined = builderState().rows[0]?.options[0];
+ * console.log(first);
+ * ```
+ */
 export interface BuilderOption {
     id: string;
     name: string;
     /** Which rocket it comes from, to group a long list. */
     rocket: string;
 }
+/**
+ * One row of the builder, from the bottom: what it chooses, the parts it offers, the one chosen, and whether the builder made the choice because only one part fits.
+ *
+ * @example
+ * ```ts
+ * import { builderState, type BuilderRow } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const row: BuilderRow | undefined = builderState().rows[0];
+ * console.log(row?.label, row?.chosen, row?.auto);
+ * ```
+ */
 export interface BuilderRow {
     /** What this row chooses. */
     label: string;
@@ -13,10 +35,34 @@ export interface BuilderRow {
     /** One answer only: the builder made the choice. */
     auto: boolean;
 }
+/**
+ * What the builder shows for a set of picks: its rows, the description they make and the fit report for it.
+ *
+ * @example
+ * ```ts
+ * import { builderState, type BuilderState } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const state: BuilderState = builderState();
+ * console.log(state.rows.length, state.report.ok);
+ * ```
+ */
 export interface BuilderState {
     rows: readonly BuilderRow[];
     description: Description;
     report: FitReport;
 }
-/** The rows for these picks, from the bottom. A pick that is not offered, for a change lower down or a hostile value, gives way to the part that belongs with what is below, or else the first that fits. */
+/**
+ * The rows for these picks, from the bottom. A pick that is not offered, for a change lower down or a hostile value, gives way to the part that belongs with what is below, or else the first that fits.
+ *
+ * @param picks The part ids chosen so far, row by row from the bottom. Leave it out to start.
+ * @returns The rows to show, the description they make and its fit report.
+ * @example
+ * ```ts
+ * import { builderState } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const start = builderState();
+ * const next = builderState([start.rows[0]?.chosen ?? ""]);
+ * console.log(next.description, next.report.label);
+ * ```
+ */
 export declare function builderState(picks?: readonly string[]): BuilderState;

package/dist/builder.js

@@ -24,7 +24,20 @@ const fitsOn = (part, below) => {
 };
 const REAL_PARTS = () => PART_ENTRIES.map(({ record }) => record).filter((record) => record.trueTo.length > 0);
 const optionOf = (part) => ({ id: part.id, name: part.name, rocket: ROCKETS[part.rocket]?.name ?? part.rocket });
-/** The rows for these picks, from the bottom. A pick that is not offered, for a change lower down or a hostile value, gives way to the part that belongs with what is below, or else the first that fits. */
+/**
+ * The rows for these picks, from the bottom. A pick that is not offered, for a change lower down or a hostile value, gives way to the part that belongs with what is below, or else the first that fits.
+ *
+ * @param picks The part ids chosen so far, row by row from the bottom. Leave it out to start.
+ * @returns The rows to show, the description they make and its fit report.
+ * @example
+ * ```ts
+ * import { builderState } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const start = builderState();
+ * const next = builderState([start.rows[0]?.chosen ?? ""]);
+ * console.log(next.description, next.report.label);
+ * ```
+ */
 export function builderState(picks = []) {
     const every = framesOf();
     const parts = REAL_PARTS();

package/dist/crossfade.d.ts

@@ -1,6 +1,48 @@
-/** The drawing stays at least this long after it first comes on screen. */
+/**
+ * The drawing stays at least this long after it first comes on screen.
+ *
+ * @example
+ * ```ts
+ * import { DRAWING_HOLD_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(DRAWING_HOLD_MS);
+ * ```
+ */
 export declare const DRAWING_HOLD_MS = 1200;
+/**
+ * How long the drawing and the 3D view cross-fade, in milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { CROSSFADE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(CROSSFADE_MS);
+ * ```
+ */
 export declare const CROSSFADE_MS = 1500;
+/**
+ * How long the cross-fade lasts for a reader who asked for reduced motion, in milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { REDUCED_FADE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(REDUCED_FADE_MS);
+ * ```
+ */
 export declare const REDUCED_FADE_MS = 400;
-/** How long to wait, once the 3D view is ready at `readyAt`, before it takes over from a drawing first seen at `shownAt` (0 under reduced motion). */
+/**
+ * How long to wait, once the 3D view is ready at `readyAt`, before it takes over from a drawing first seen at `shownAt` (0 under reduced motion).
+ *
+ * @param shownAt When the drawing first came on screen, in milliseconds.
+ * @param readyAt When the 3D view became ready, on the same clock.
+ * @param reducedMotion True when the reader asked for reduced motion.
+ * @returns The milliseconds to wait before the 3D view takes over.
+ * @example
+ * ```ts
+ * import { revealDelay } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(revealDelay(0, 300, false), revealDelay(0, 300, true));
+ * ```
+ */
 export declare function revealDelay(shownAt: number, readyAt: number, reducedMotion: boolean): number;

package/dist/crossfade.js

@@ -1,9 +1,51 @@
 // The change from a rocket's drawing to its 3D view: the drawing stays a moment even when the 3D view is ready sooner, then a slow crossfade; under reduced motion, a plain short fade. Pure.
-/** The drawing stays at least this long after it first comes on screen. */
+/**
+ * The drawing stays at least this long after it first comes on screen.
+ *
+ * @example
+ * ```ts
+ * import { DRAWING_HOLD_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(DRAWING_HOLD_MS);
+ * ```
+ */
 export const DRAWING_HOLD_MS = 1200;
+/**
+ * How long the drawing and the 3D view cross-fade, in milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { CROSSFADE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(CROSSFADE_MS);
+ * ```
+ */
 export const CROSSFADE_MS = 1500;
+/**
+ * How long the cross-fade lasts for a reader who asked for reduced motion, in milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { REDUCED_FADE_MS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(REDUCED_FADE_MS);
+ * ```
+ */
 export const REDUCED_FADE_MS = 400;
-/** How long to wait, once the 3D view is ready at `readyAt`, before it takes over from a drawing first seen at `shownAt` (0 under reduced motion). */
+/**
+ * How long to wait, once the 3D view is ready at `readyAt`, before it takes over from a drawing first seen at `shownAt` (0 under reduced motion).
+ *
+ * @param shownAt When the drawing first came on screen, in milliseconds.
+ * @param readyAt When the 3D view became ready, on the same clock.
+ * @param reducedMotion True when the reader asked for reduced motion.
+ * @returns The milliseconds to wait before the 3D view takes over.
+ * @example
+ * ```ts
+ * import { revealDelay } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(revealDelay(0, 300, false), revealDelay(0, 300, true));
+ * ```
+ */
 export function revealDelay(shownAt, readyAt, reducedMotion) {
     if (reducedMotion)
         return 0;

package/dist/data/credits.d.ts

@@ -1,3 +1,14 @@
+/**
+ * The credit for one licensed model: its title, its creator and their page, where it came from, its licence and what this package changed.
+ *
+ * @example
+ * ```ts
+ * import { MODEL_CREDITS, type ModelCredit } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const credit: ModelCredit = MODEL_CREDITS["clarence365-block3"];
+ * console.log(credit.creator, credit.licence);
+ * ```
+ */
 export interface ModelCredit {
     title: string;
     creator: string;
@@ -8,6 +19,16 @@ export interface ModelCredit {
     /** What this package changed. */
     changes: string;
 }
+/**
+ * Every licensed model this package paints with, by credit id. A painted rocket must carry the credit of the parts that are showing; `embedCode` writes it for you.
+ *
+ * @example
+ * ```ts
+ * import { MODEL_CREDITS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(Object.keys(MODEL_CREDITS).length > 10);
+ * ```
+ */
 export declare const MODEL_CREDITS: {
     readonly "clarence365-block3": {
         readonly title: "SpaceX Starship Block 3";
@@ -100,6 +121,28 @@ export declare const MODEL_CREDITS: {
     readonly "nasa-iss": ModelCredit;
     readonly "nasa-hubble": ModelCredit;
 };
+/**
+ * The id of one model's credit in `MODEL_CREDITS`.
+ *
+ * @example
+ * ```ts
+ * import type { CreditId } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const id: CreditId = "clarence365-block3";
+ * console.log(id);
+ * ```
+ */
 export type CreditId = keyof typeof MODEL_CREDITS;
-/** One credit as a line of text. */
+/**
+ * One credit as a line of text.
+ *
+ * @param id The id of a credit in `MODEL_CREDITS`.
+ * @returns The credit as one line of text.
+ * @example
+ * ```ts
+ * import { creditLine } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(creditLine("clarence365-block3"));
+ * ```
+ */
 export declare function creditLine(id: CreditId): string;

package/dist/data/credits.js

@@ -11,6 +11,16 @@ const nasa = (title, slug, changes) => ({
     licenceUrl: "https://www.nasa.gov/nasa-brand-center/images-and-media/",
     changes,
 });
+/**
+ * Every licensed model this package paints with, by credit id. A painted rocket must carry the credit of the parts that are showing; `embedCode` writes it for you.
+ *
+ * @example
+ * ```ts
+ * import { MODEL_CREDITS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(Object.keys(MODEL_CREDITS).length > 10);
+ * ```
+ */
 export const MODEL_CREDITS = {
     "clarence365-block3": {
         title: "SpaceX Starship Block 3",
@@ -104,7 +114,18 @@ export const MODEL_CREDITS = {
     "nasa-hubble": nasa("Hubble Space Telescope", "nasa-3d-models-hubble-space-telescope", "A lettered plate painted out of its picture; rescaled to the sourced length; its materials made into one picture."),
     // new rows go here
 };
-/** One credit as a line of text. */
+/**
+ * One credit as a line of text.
+ *
+ * @param id The id of a credit in `MODEL_CREDITS`.
+ * @returns The credit as one line of text.
+ * @example
+ * ```ts
+ * import { creditLine } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(creditLine("clarence365-block3"));
+ * ```
+ */
 export function creditLine(id) {
     const c = MODEL_CREDITS[id];
     return `"${c.title}" by ${c.creator} (${c.sourceUrl}), ${c.licence} (${c.licenceUrl}). ${c.changes}`;

package/dist/data/flight-log.d.ts

@@ -1,4 +1,15 @@
 import type { SourceId } from "./sources.ts";
+/**
+ * One flight from the flight log: its name, the rocket and variant that show it, the date, whether the launch succeeded, the source's own words on the outcome, and the source.
+ *
+ * @example
+ * ```ts
+ * import { FLIGHT_LOG, type LoggedFlight } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight: LoggedFlight | undefined = FLIGHT_LOG[0];
+ * console.log(flight?.name, flight?.launch);
+ * ```
+ */
 export interface LoggedFlight {
     id: string;
     name: string;
@@ -13,6 +24,27 @@ export interface LoggedFlight {
     outcome: string;
     source: SourceId;
 }
+/**
+ * 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 declare const FLIGHT_LOG: readonly LoggedFlight[];
-/** 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 declare const flightLogOf: (rocket: string) => readonly LoggedFlight[];

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;
@@ -10,12 +20,35 @@ export interface PartPose {
     rest?: boolean;
     /** It has left the picture. */
     gone?: boolean;
+    /** Degrees each moving group of the part (`grid-fins`, `legs`, `forward-flaps`, `aft-flaps`) is turned from where it is drawn at rest. A picture, not a measurement. */
+    moves?: Readonly<Record<string, number>>;
 }
-/** 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 +67,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;
@@ -44,6 +88,21 @@ export interface Flight {
     source: SourceId;
     /** What the picture leaves out. */
     note?: string;
+    /** What turns in it (grid fins, legs, flaps), and the page that says so. How far each turns is a picture. */
+    moves?: readonly {
+        source: SourceId;
+        says: 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[];