@johnmorrisdotca/uchusen-rockets 0.2.2 → 0.4.0

package/dist/fit.d.ts

@@ -1,6 +1,17 @@
 import { type CreditId, type ModelCredit } from "./data/credits.ts";
 import type { Variant } from "./data/types.ts";
 import type { PartRecord } from "./parts.ts";
+/**
+ * A rocket to check or build: its id, its variant (left out: the rocket's default) and any other part in a slot, by part id.
+ *
+ * @example
+ * ```ts
+ * import { check, type Description } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const description: Description = { rocket: "starship", variant: "v3", parts: { ship: "starship-v2-ship" } };
+ * console.log(check(description).label);
+ * ```
+ */
 export interface Description {
     rocket: string;
     /** Left out: the rocket's default variant. */
@@ -8,17 +19,61 @@ export interface Description {
     /** Another part in a slot, by its id. */
     parts?: Readonly<Record<string, string>>;
 }
+/**
+ * Why a check said what it said: an unknown rocket, variant, slot or part, a part of the wrong kind, a joint that is missing, of another kind or of another width, or a custom build.
+ *
+ * @example
+ * ```ts
+ * import { check, type FitCode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const codes: FitCode[] = check({ rocket: "nowhere" }).issues.map((issue) => issue.code);
+ * console.log(codes);
+ * ```
+ */
 export type FitCode = "unknown-rocket" | "unknown-variant" | "unknown-slot" | "unknown-part" | "wrong-kind" | "no-joint" | "joint-kind" | "joint-diameter" | "custom";
+/**
+ * One thing a check found: its code, its level (`error` stops a build, `note` says what was decided) and a sentence saying it.
+ *
+ * @example
+ * ```ts
+ * import { check, type FitIssue } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const issue: FitIssue | undefined = check({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } }).issues[0];
+ * console.log(issue?.level, issue?.message);
+ * ```
+ */
 export interface FitIssue {
     code: FitCode;
     /** "error" stops the build. "note" says what the check decided. */
     level: "error" | "note";
     message: string;
 }
+/**
+ * A part standing in a slot of a checked rocket.
+ *
+ * @example
+ * ```ts
+ * import { check, type SlotPart } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const bottom: SlotPart | undefined = check({ rocket: "starship", variant: "v3" }).parts[0];
+ * console.log(bottom?.slot, bottom?.part.name);
+ * ```
+ */
 export interface SlotPart {
     slot: string;
     part: PartRecord;
 }
+/**
+ * The answer of `check`: whether the parts go together, the issues, the label to call the rocket, whether it is a custom build, the variant, the parts, the size and the credits of every licensed model.
+ *
+ * @example
+ * ```ts
+ * import { check, type FitReport } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const report: FitReport = check({ rocket: "falcon-9", variant: "block-5" });
+ * console.log(report.ok, report.size);
+ * ```
+ */
 export interface FitReport {
     ok: boolean;
     issues: readonly FitIssue[];
@@ -40,4 +95,19 @@ export interface FitReport {
         usedFor: readonly string[];
     })[];
 }
+/** How far apart two joints may be in metres and still meet. */
+export declare const JOINT_TOLERANCE = 0.1;
+/**
+ * Asks whether a rocket goes together, from the parts' records alone, with no three.js and no DOM. A rocket labelled as a real version uses only parts true for it; any mix is a custom build and says so.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns A report that says whether it fits and why, with the size and the credits.
+ * @example
+ * ```ts
+ * import { check } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const report = check({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * console.log(report.ok, report.issues[0]?.message);
+ * ```
+ */
 export declare function check(description: Description): FitReport;

package/dist/fit.js

@@ -3,14 +3,15 @@
 import { MODEL_CREDITS } from "./data/credits.js";
 import { partEntry } from "./model/registry.js";
 import { partIdOf, ROCKETS, variantOf } from "./rockets.js";
-const TOLERANCE = 0.1;
+/** How far apart two joints may be in metres and still meet. */
+export const JOINT_TOLERANCE = 0.1;
 /** The whole height, joint to joint up the stack, and the widest part. */
 function sizeOf(parts) {
     let y = 0;
     let top = 0;
     for (const { part } of parts) {
         if (part.strapOn) {
-            top = Math.max(top, part.height);
+            top = Math.max(top, (part.strapOn.y ?? 0) + part.height);
             continue;
         }
         const base = y - (part.joints.bottom?.y ?? 0);
@@ -19,6 +20,19 @@ function sizeOf(parts) {
     }
     return { height: Math.round(top * 1000) / 1000, diameter: Math.max(...parts.map(({ part }) => part.diameter)) };
 }
+/**
+ * Asks whether a rocket goes together, from the parts' records alone, with no three.js and no DOM. A rocket labelled as a real version uses only parts true for it; any mix is a custom build and says so.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns A report that says whether it fits and why, with the size and the credits.
+ * @example
+ * ```ts
+ * import { check } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const report = check({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * console.log(report.ok, report.issues[0]?.message);
+ * ```
+ */
 export function check(description) {
     const issues = [];
     const fail = (code, message) => issues.push({ code, level: "error", message });
@@ -84,7 +98,7 @@ export function check(description) {
         }
         if (top.kind !== bottom.kind)
             fail("joint-kind", `${below.name} ends in a ${top.kind} joint and ${above.name} starts with a ${bottom.kind} joint.`);
-        if (Math.abs(top.diameter - bottom.diameter) > TOLERANCE)
+        if (Math.abs(top.diameter - bottom.diameter) > JOINT_TOLERANCE)
             fail("joint-diameter", `${below.name} is ${top.diameter} m across at the joint and ${above.name} is ${bottom.diameter} m.`);
     }
     if (custom)

package/dist/flight.d.ts

@@ -0,0 +1,192 @@
+import { type Flight, type FlightPhase } from "./data/flights.ts";
+import type { Figure } from "./data/types.ts";
+export type { Flight, FlightBurn, FlightPhase, PartPose } from "./data/flights.ts";
+/**
+ * Seconds a phase takes on the screen when the timeline plays: one flight in under a minute, whatever its real length.
+ *
+ * @example
+ * ```ts
+ * import { SECONDS_PER_PHASE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SECONDS_PER_PHASE);
+ * ```
+ */
+export declare const SECONDS_PER_PHASE = 2.4;
+/**
+ * The flight for a rocket's variant, when a page gives one.
+ *
+ * @param rocket A rocket's id.
+ * @param variant A variant's id, or undefined.
+ * @returns The flight for that variant, or null when it has none.
+ * @example
+ * ```ts
+ * import { flightOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(flightOf("starship", "v3")?.name, flightOf("starship", "v4"));
+ * ```
+ */
+export declare const flightOf: (rocket: string, variant: string | undefined) => Flight | null;
+/**
+ * The last place on the timeline: the last phase.
+ *
+ * @param flight A flight.
+ * @returns The index of its last phase.
+ * @example
+ * ```ts
+ * import { flightOf, lastPosition } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * console.log(flight ? lastPosition(flight) : null);
+ * ```
+ */
+export declare const lastPosition: (flight: Flight) => number;
+/**
+ * Which phase a place on the timeline is in, and how far along to the next. A value that is not a number is the start.
+ *
+ * @param flight A flight.
+ * @param position A place on the timeline: 0 is the first phase, 1 the second, 1.5 halfway to the third.
+ * @returns The phase index, how far along to the next (0 to 1) and the phase.
+ * @example
+ * ```ts
+ * import { flightOf, phaseAt } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) console.log(phaseAt(flight, 1.5).phase.name);
+ * ```
+ */
+export declare function phaseAt(flight: Flight, position: number): {
+    index: number;
+    along: number;
+    phase: FlightPhase;
+};
+/**
+ * The place on the timeline of a phase by its id, or null for one the flight does not have.
+ *
+ * @param flight A flight.
+ * @param id A phase's id, or null or undefined.
+ * @returns The place of that phase on the timeline, or null for an id the flight does not have.
+ * @example
+ * ```ts
+ * import { flightOf, phasePosition } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) console.log(phasePosition(flight, "nonsense"));
+ * ```
+ */
+export declare function phasePosition(flight: Flight, id: string | null | undefined): number | null;
+/**
+ * How many engines of each part burn in a phase, as drawn: a blank figure draws its `drawn`.
+ *
+ * @param phase A phase of a flight.
+ * @returns The number of engines burning for each part, by slot.
+ * @example
+ * ```ts
+ * import { burnsOf, flightOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const phase = flightOf("falcon-9", "block-5")?.phases[0];
+ * console.log(phase ? burnsOf(phase) : {});
+ * ```
+ */
+export declare function burnsOf(phase: FlightPhase): Record<string, number>;
+export interface PoseNow {
+    dx: number;
+    dy: number;
+    pitch: number;
+    gone: boolean;
+}
+/**
+ * Everything the picture needs at one place on the timeline: the phase, how each part stands, which engines burn, how far the ground has fallen, and how much smoke stands on the pad.
+ *
+ * @example
+ * ```ts
+ * import { flightOf, frameAt, type FlightFrame } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * const frame: FlightFrame | undefined = flight ? frameAt(flight, 0, [{ slot: "first-stage", baseY: 0 }], 70) : undefined;
+ * console.log(frame?.phase.name, frame?.separated);
+ * ```
+ */
+export interface FlightFrame {
+    index: number;
+    phase: FlightPhase;
+    poses: Readonly<Record<string, PoseNow>>;
+    burns: Readonly<Record<string, number>>;
+    /** Metres. */
+    groundY: number;
+    smoke: number;
+    air: number;
+    /** A part stands away from the stack. */
+    separated: boolean;
+}
+export interface FlightPart {
+    slot: string;
+    /** Where it stands in the stack: the base's height, metres. */
+    baseY: number;
+}
+/**
+ * Everything the picture needs at a place on the timeline, for a vehicle `height` metres tall.
+ *
+ * @param flight A flight.
+ * @param position A place on the timeline.
+ * @param parts Each part's slot and the height of its base in the stack, in metres.
+ * @param height The vehicle's height in metres.
+ * @returns The frame to draw.
+ * @example
+ * ```ts
+ * import { flightOf, frameAt } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) console.log(frameAt(flight, 1, [{ slot: "first-stage", baseY: 0 }, { slot: "second-stage", baseY: 41 }], 70).burns);
+ * ```
+ */
+export declare function frameAt(flight: Flight, position: number, parts: readonly FlightPart[], height: number): FlightFrame;
+/** How far a flight's picture reaches, so the camera can hold all of it: the widest and highest every part stands, from the stack's own bounds. */
+export declare function flightBounds(flight: Flight, parts: readonly (FlightPart & {
+    height: number;
+    radius: number;
+})[], height: number): {
+    min: [number, number, number];
+    max: [number, number, number];
+};
+/**
+ * The clock of one timeline: where it is and whether it runs. It only moves when told to, once a frame by whoever draws, so a timeline out of sight stands still.
+ *
+ * @param flight The flight whose clock this is.
+ * @example
+ * ```ts
+ * import { FlightClock, flightOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) {
+ *   const clock = new FlightClock(flight);
+ *   clock.play();
+ *   clock.advance(2.4);
+ *   console.log(clock.position, clock.ended);
+ * }
+ * ```
+ */
+export declare class FlightClock {
+    readonly flight: Flight;
+    position: number;
+    playing: boolean;
+    constructor(flight: Flight);
+    get ended(): boolean;
+    play(): void;
+    pause(): void;
+    seek(position: number): void;
+    /** Moves on by `seconds` of the screen's time, and stops at the end. */
+    advance(seconds: number): void;
+}
+/**
+ * A time as words: `T+2:35`, `T-0:03`, `T+1:05:20`. A blank says so.
+ *
+ * @param at A figure holding seconds from the flight's zero.
+ * @returns The time as text, such as `T+2:35`. A blank figure gives "Time: no source".
+ * @example
+ * ```ts
+ * import { clockWords } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(clockWords({ value: 155, source: "wikipedia-starship" }), clockWords({ value: -3, source: null }));
+ * ```
+ */
+export declare function clockWords(at: Figure): string;

package/dist/flight.js

@@ -0,0 +1,237 @@
+// A flight as a timeline: where the reader is along it, which engines burn there and how each part stands. The times and the counts are `src/data/flights.ts`, each with its page. Moving between the phases is a picture. Pure: no three.js and no DOM.
+import { FLIGHTS } from "./data/flights.js";
+/**
+ * Seconds a phase takes on the screen when the timeline plays: one flight in under a minute, whatever its real length.
+ *
+ * @example
+ * ```ts
+ * import { SECONDS_PER_PHASE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SECONDS_PER_PHASE);
+ * ```
+ */
+export const SECONDS_PER_PHASE = 2.4;
+/**
+ * The flight for a rocket's variant, when a page gives one.
+ *
+ * @param rocket A rocket's id.
+ * @param variant A variant's id, or undefined.
+ * @returns The flight for that variant, or null when it has none.
+ * @example
+ * ```ts
+ * import { flightOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(flightOf("starship", "v3")?.name, flightOf("starship", "v4"));
+ * ```
+ */
+export const flightOf = (rocket, variant) => FLIGHTS.find((flight) => flight.rocket === rocket && flight.variant === variant) ?? null;
+/**
+ * The last place on the timeline: the last phase.
+ *
+ * @param flight A flight.
+ * @returns The index of its last phase.
+ * @example
+ * ```ts
+ * import { flightOf, lastPosition } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * console.log(flight ? lastPosition(flight) : null);
+ * ```
+ */
+export const lastPosition = (flight) => flight.phases.length - 1;
+/**
+ * Which phase a place on the timeline is in, and how far along to the next. A value that is not a number is the start.
+ *
+ * @param flight A flight.
+ * @param position A place on the timeline: 0 is the first phase, 1 the second, 1.5 halfway to the third.
+ * @returns The phase index, how far along to the next (0 to 1) and the phase.
+ * @example
+ * ```ts
+ * import { flightOf, phaseAt } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) console.log(phaseAt(flight, 1.5).phase.name);
+ * ```
+ */
+export function phaseAt(flight, position) {
+    const last = lastPosition(flight);
+    const place = Number.isFinite(position) ? Math.min(last, Math.max(0, position)) : 0;
+    const index = Math.floor(place);
+    return { index, along: place - index, phase: flight.phases[index] };
+}
+/**
+ * The place on the timeline of a phase by its id, or null for one the flight does not have.
+ *
+ * @param flight A flight.
+ * @param id A phase's id, or null or undefined.
+ * @returns The place of that phase on the timeline, or null for an id the flight does not have.
+ * @example
+ * ```ts
+ * import { flightOf, phasePosition } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) console.log(phasePosition(flight, "nonsense"));
+ * ```
+ */
+export function phasePosition(flight, id) {
+    const index = flight.phases.findIndex((phase) => phase.id === id);
+    return index < 0 ? null : index;
+}
+/**
+ * How many engines of each part burn in a phase, as drawn: a blank figure draws its `drawn`.
+ *
+ * @param phase A phase of a flight.
+ * @returns The number of engines burning for each part, by slot.
+ * @example
+ * ```ts
+ * import { burnsOf, flightOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const phase = flightOf("falcon-9", "block-5")?.phases[0];
+ * console.log(phase ? burnsOf(phase) : {});
+ * ```
+ */
+export function burnsOf(phase) {
+    const out = {};
+    for (const [slot, burn] of Object.entries(phase.burns))
+        out[slot] = burn.engines.value ?? burn.drawn ?? 0;
+    return out;
+}
+const smooth = (t) => t * t * (3 - 2 * t);
+const mix = (a, b, t) => a + (b - a) * t;
+const poseIn = (pose, part, height) => ({
+    dx: (pose?.dx ?? 0) * height,
+    dy: pose?.rest ? -part.baseY : (pose?.dy ?? 0) * height,
+    pitch: pose?.pitch ?? 0,
+    gone: pose?.gone ?? false,
+});
+/**
+ * Everything the picture needs at a place on the timeline, for a vehicle `height` metres tall.
+ *
+ * @param flight A flight.
+ * @param position A place on the timeline.
+ * @param parts Each part's slot and the height of its base in the stack, in metres.
+ * @param height The vehicle's height in metres.
+ * @returns The frame to draw.
+ * @example
+ * ```ts
+ * import { flightOf, frameAt } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) console.log(frameAt(flight, 1, [{ slot: "first-stage", baseY: 0 }, { slot: "second-stage", baseY: 41 }], 70).burns);
+ * ```
+ */
+export function frameAt(flight, position, parts, height) {
+    const { index, along, phase } = phaseAt(flight, position);
+    const next = flight.phases[Math.min(index + 1, lastPosition(flight))];
+    const t = smooth(along);
+    const poses = {};
+    let separated = false;
+    for (const part of parts) {
+        const from = poseIn(phase.pose[part.slot], part, height);
+        const to = poseIn(next.pose[part.slot], part, height);
+        const now = { dx: mix(from.dx, to.dx, t), dy: mix(from.dy, to.dy, t), pitch: mix(from.pitch, to.pitch, t), gone: from.gone };
+        poses[part.slot] = now;
+        if (now.dx !== 0 || now.dy !== 0)
+            separated = true;
+    }
+    return {
+        index,
+        phase,
+        poses,
+        burns: burnsOf(phase),
+        groundY: -mix(phase.ground, next.ground, t) * height,
+        smoke: mix(phase.smoke ?? 0, next.smoke ?? 0, t),
+        air: mix(phase.air ?? 0, next.air ?? 0, t),
+        separated,
+    };
+}
+/** How far a flight's picture reaches, so the camera can hold all of it: the widest and highest every part stands, from the stack's own bounds. */
+export function flightBounds(flight, parts, height) {
+    const min = [Infinity, 0, Infinity];
+    const max = [-Infinity, height, -Infinity];
+    for (const part of parts)
+        for (const phase of flight.phases) {
+            const pose = poseIn(phase.pose[part.slot], part, height);
+            if (pose.gone)
+                continue;
+            const reach = Math.max(part.radius, (Math.abs(Math.sin((pose.pitch * Math.PI) / 180)) * part.height) / 2);
+            min[0] = Math.min(min[0], pose.dx - reach);
+            max[0] = Math.max(max[0], pose.dx + reach);
+            min[1] = Math.min(min[1], part.baseY + pose.dy);
+            max[1] = Math.max(max[1], part.baseY + pose.dy + part.height);
+            min[2] = Math.min(min[2], -part.radius);
+            max[2] = Math.max(max[2], part.radius);
+        }
+    return { min, max };
+}
+/**
+ * The clock of one timeline: where it is and whether it runs. It only moves when told to, once a frame by whoever draws, so a timeline out of sight stands still.
+ *
+ * @param flight The flight whose clock this is.
+ * @example
+ * ```ts
+ * import { FlightClock, flightOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const flight = flightOf("falcon-9", "block-5");
+ * if (flight) {
+ *   const clock = new FlightClock(flight);
+ *   clock.play();
+ *   clock.advance(2.4);
+ *   console.log(clock.position, clock.ended);
+ * }
+ * ```
+ */
+export class FlightClock {
+    flight;
+    position = 0;
+    playing = false;
+    constructor(flight) {
+        this.flight = flight;
+    }
+    get ended() {
+        return this.position >= lastPosition(this.flight);
+    }
+    play() {
+        if (this.ended)
+            this.position = 0;
+        this.playing = true;
+    }
+    pause() {
+        this.playing = false;
+    }
+    seek(position) {
+        const { index, along } = phaseAt(this.flight, position);
+        this.position = index + along;
+        this.playing = false;
+    }
+    /** Moves on by `seconds` of the screen's time, and stops at the end. */
+    advance(seconds) {
+        if (!this.playing)
+            return;
+        this.position = Math.min(lastPosition(this.flight), this.position + seconds / SECONDS_PER_PHASE);
+        if (this.ended)
+            this.playing = false;
+    }
+}
+/**
+ * A time as words: `T+2:35`, `T-0:03`, `T+1:05:20`. A blank says so.
+ *
+ * @param at A figure holding seconds from the flight's zero.
+ * @returns The time as text, such as `T+2:35`. A blank figure gives "Time: no source".
+ * @example
+ * ```ts
+ * import { clockWords } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(clockWords({ value: 155, source: "wikipedia-starship" }), clockWords({ value: -3, source: null }));
+ * ```
+ */
+export function clockWords(at) {
+    if (at.value === null)
+        return "Time: no source";
+    const sign = at.value < 0 ? "-" : "+";
+    const total = Math.abs(at.value);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = String(total % 60).padStart(2, "0");
+    return h > 0 ? `T${sign}${h}:${String(m).padStart(2, "0")}:${s}` : `T${sign}${m}:${s}`;
+}

package/dist/flightbar.d.ts

@@ -0,0 +1,34 @@
+declare const HTMLBase: typeof HTMLElement;
+/**
+ * The `<uchusen-flight>` element: a play button, a slider and the phase's name for a rocket's flight. Its `for` attribute is the id of the `<uchusen-rocket>` it drives. A variant with no flight says so.
+ *
+ * @example
+ * ```ts no-run
+ * import { UchusenFlight } from "@johnmorrisdotca/uchusen-rockets/element";
+ *
+ * const flight: UchusenFlight = document.createElement("uchusen-flight") as UchusenFlight;
+ * flight.setAttribute("for", "rocket");
+ * document.body.append(flight);
+ * ```
+ */
+export declare class UchusenFlight extends HTMLBase {
+    static readonly observedAttributes: string[];
+    private rocket;
+    private drawnFor;
+    private chartKey;
+    private parts;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private bind;
+    private build;
+    private drawAbout;
+    private update;
+}
+export declare function defineUchusenFlight(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        "uchusen-flight": UchusenFlight;
+    }
+}
+export {};