@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.5.0

package/dist/attrs.d.ts

@@ -1,4 +1,25 @@
+/**
+ * The attributes of `<uchusen-rocket>` that choose what is drawn, in the order the demo writes them. The `embed.html` query uses the same words.
+ *
+ * @example
+ * ```ts
+ * import { OPTION_ATTRIBUTES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(OPTION_ATTRIBUTES.join(", "));
+ * ```
+ */
 export declare const OPTION_ATTRIBUTES: readonly ["rocket", "variant", "show", "look", "view", "build", "mode", "spin", "way", "label", "assets", "engines", "phase"];
+/**
+ * Every choice that draws a rocket, as plain text: the same names and values as the element's attributes. Nothing here is trusted. A value outside its list falls back to a default when it is drawn.
+ *
+ * @example
+ * ```ts
+ * import type { RocketOptions } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const options: RocketOptions = { rocket: "falcon-9", variant: "block-5", look: "thick", view: "below" };
+ * console.log(options);
+ * ```
+ */
 export interface RocketOptions {
     rocket?: string;
     variant?: string;
@@ -17,11 +38,56 @@ export interface RocketOptions {
     /** A phase of the rocket's flight, by its id: the engines that burn there. */
     phase?: string;
 }
-/** The attributes that draw these options. Empty values are left out. */
+/**
+ * The attributes that draw these options. Empty values are left out.
+ *
+ * @param options The choices to turn into attributes.
+ * @returns The attributes by name, as text. A choice left out or empty has no entry.
+ * @example
+ * ```ts
+ * import { attributesFromOptions } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(attributesFromOptions({ rocket: "starship", variant: "v3", look: "painted", show: "" }));
+ * ```
+ */
 export declare function attributesFromOptions(options: RocketOptions): Record<string, string>;
-/** The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket. */
+/**
+ * The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket.
+ *
+ * @param read Reads one attribute by name and gives null when it is missing, as `element.getAttribute` does.
+ * @returns The choices found, as written. A missing attribute is left out of the result.
+ * @example
+ * ```ts
+ * import { optionsFromAttributes } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const attributes: Record<string, string> = { rocket: "starship", look: "thick" };
+ * console.log(optionsFromAttributes((name) => attributes[name] ?? null));
+ * ```
+ */
 export declare function optionsFromAttributes(read: (name: string) => string | null): RocketOptions;
-/** The options as a query for `embed.html`. */
+/**
+ * The options as a query for `embed.html`.
+ *
+ * @param options The choices to write.
+ * @returns A query for `embed.html`, with one entry for each choice made.
+ * @example
+ * ```ts
+ * import { rocketToParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketToParams({ rocket: "falcon-9", show: "apart" }).toString());
+ * ```
+ */
 export declare function rocketToParams(options: RocketOptions): URLSearchParams;
-/** The options a query names. */
+/**
+ * The options a query names.
+ *
+ * @param params The query of an `embed.html` address.
+ * @returns The choices the query names.
+ * @example
+ * ```ts
+ * import { rocketFromParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketFromParams(new URLSearchParams("rocket=falcon-9&look=thick")));
+ * ```
+ */
 export declare function rocketFromParams(params: URLSearchParams): RocketOptions;

package/dist/attrs.js

@@ -1,7 +1,28 @@
 // A rocket's options as text: the attributes of `<uchusen-rocket>` and the query of `embed.html` are the same words, read by one function and written by another.
+/**
+ * The attributes of `<uchusen-rocket>` that choose what is drawn, in the order the demo writes them. The `embed.html` query uses the same words.
+ *
+ * @example
+ * ```ts
+ * import { OPTION_ATTRIBUTES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(OPTION_ATTRIBUTES.join(", "));
+ * ```
+ */
 export const OPTION_ATTRIBUTES = ["rocket", "variant", "show", "look", "view", "build", "mode", "spin", "way", "label", "assets", "engines", "phase"];
 const text = (value) => (typeof value === "string" && value !== "" ? value : undefined);
-/** The attributes that draw these options. Empty values are left out. */
+/**
+ * The attributes that draw these options. Empty values are left out.
+ *
+ * @param options The choices to turn into attributes.
+ * @returns The attributes by name, as text. A choice left out or empty has no entry.
+ * @example
+ * ```ts
+ * import { attributesFromOptions } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(attributesFromOptions({ rocket: "starship", variant: "v3", look: "painted", show: "" }));
+ * ```
+ */
 export function attributesFromOptions(options) {
     const out = {};
     for (const name of OPTION_ATTRIBUTES) {
@@ -11,7 +32,19 @@ export function attributesFromOptions(options) {
     }
     return out;
 }
-/** The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket. */
+/**
+ * The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket.
+ *
+ * @param read Reads one attribute by name and gives null when it is missing, as `element.getAttribute` does.
+ * @returns The choices found, as written. A missing attribute is left out of the result.
+ * @example
+ * ```ts
+ * import { optionsFromAttributes } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const attributes: Record<string, string> = { rocket: "starship", look: "thick" };
+ * console.log(optionsFromAttributes((name) => attributes[name] ?? null));
+ * ```
+ */
 export function optionsFromAttributes(read) {
     const options = {};
     for (const name of OPTION_ATTRIBUTES) {
@@ -21,11 +54,33 @@ export function optionsFromAttributes(read) {
     }
     return options;
 }
-/** The options as a query for `embed.html`. */
+/**
+ * The options as a query for `embed.html`.
+ *
+ * @param options The choices to write.
+ * @returns A query for `embed.html`, with one entry for each choice made.
+ * @example
+ * ```ts
+ * import { rocketToParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketToParams({ rocket: "falcon-9", show: "apart" }).toString());
+ * ```
+ */
 export function rocketToParams(options) {
     return new URLSearchParams(attributesFromOptions(options));
 }
-/** The options a query names. */
+/**
+ * The options a query names.
+ *
+ * @param params The query of an `embed.html` address.
+ * @returns The choices the query names.
+ * @example
+ * ```ts
+ * import { rocketFromParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketFromParams(new URLSearchParams("rocket=falcon-9&look=thick")));
+ * ```
+ */
 export function rocketFromParams(params) {
     return optionsFromAttributes((name) => params.get(name));
 }

package/dist/build/glb.d.ts

@@ -5,8 +5,33 @@ export interface GlbPart {
     mesh: PartMesh;
     at: readonly [number, number, number];
 }
+/**
+ * A binary glTF file: its bytes and how many triangles it holds. Save the bytes as a `.glb` file or hand them to any glTF viewer.
+ *
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const glb = build({ rocket: "starship", variant: "v3" }).glb();
+ * console.log(glb.bytes.length > 1000, glb.triangles > 0);
+ * ```
+ */
 export interface Glb {
     bytes: Uint8Array;
     triangles: number;
 }
+/**
+ * Writes parts into one small binary glTF file, in Node or a browser, with no dependency: one node for each part and one primitive for each material. The same parts always give the same bytes.
+ *
+ * @param parts The parts to write: each has a node name, its mesh and where it stands in metres.
+ * @returns The file's bytes and its triangle count.
+ * @example
+ * ```ts
+ * import { build, toGlb } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-9", variant: "block-5" });
+ * const glb = toGlb(rocket.parts.map((part) => ({ name: part.slot, mesh: part.mesh, at: [0, 0, 0] as const })));
+ * console.log(glb.bytes.length > 1000, glb.triangles > 0);
+ * ```
+ */
 export declare function toGlb(parts: readonly GlbPart[]): Glb;

package/dist/build/glb.js

@@ -10,6 +10,20 @@ const LINES = 1;
 const round6 = (v) => Math.round(v * 1e6) / 1e6;
 const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
 const linearOf = (hex) => [1, 3, 5].map((i) => round6(toLinear(Number.parseInt(hex.slice(i, i + 2), 16) / 255)));
+/**
+ * Writes parts into one small binary glTF file, in Node or a browser, with no dependency: one node for each part and one primitive for each material. The same parts always give the same bytes.
+ *
+ * @param parts The parts to write: each has a node name, its mesh and where it stands in metres.
+ * @returns The file's bytes and its triangle count.
+ * @example
+ * ```ts
+ * import { build, toGlb } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-9", variant: "block-5" });
+ * const glb = toGlb(rocket.parts.map((part) => ({ name: part.slot, mesh: part.mesh, at: [0, 0, 0] as const })));
+ * console.log(glb.bytes.length > 1000, glb.triangles > 0);
+ * ```
+ */
 export function toGlb(parts) {
     const chunks = [];
     let offset = 0;
@@ -47,8 +61,8 @@ export function toGlb(parts) {
     const meshes = [];
     const nodes = [];
     const roots = [];
-    for (const part of parts) {
-        const { mesh } = part;
+    /** One mesh of a part or of one of its moving groups: its primitives and the packing's middle and half-size, returned as the nodes that hold it. */
+    const packMesh = (mesh, name) => {
         const faces = [...mesh.faces];
         // the packing's middle and half-size, over all of the part's points
         const lo = [Infinity, Infinity, Infinity];
@@ -112,11 +126,19 @@ export function toGlb(parts) {
                 continue;
             primitives.push({ attributes: { POSITION: packPositions(lines.positions) }, indices: indexAccessor(lines.indices, lines.positions.length / 3), material: useMaterial(name), mode: LINES });
         }
-        meshes.push({ name: part.name, primitives });
-        // a holder that the viewer moves, and the packed mesh under it
-        nodes.push({ name: `${part.name}-mesh`, mesh: meshes.length - 1, translation: q.map(round6), scale: [round6(half), round6(half), round6(half)] });
-        const child = nodes.length - 1;
-        nodes.push({ name: part.name, children: [child], translation: part.at.map(round6) });
+        meshes.push({ name, primitives });
+        nodes.push({ name: `${name}-mesh`, mesh: meshes.length - 1, translation: q.map(round6), scale: [round6(half), round6(half), round6(half)] });
+        return nodes.length - 1;
+    };
+    for (const part of parts) {
+        // a holder that the viewer moves, and the packed mesh under it; each moving group is a node of its own beside it, at its pivot, with the axis it turns about
+        const children = [packMesh(part.mesh, part.name)];
+        for (const group of part.mesh.moves) {
+            const inside = packMesh(group.mesh, `${part.name}~${group.id}`);
+            nodes.push({ name: `${part.name}~${group.id}`, children: [inside], translation: group.pivot.map(round6), extras: { axis: group.axis.map(round6), group: group.name } });
+            children.push(nodes.length - 1);
+        }
+        nodes.push({ name: part.name, children, translation: part.at.map(round6) });
         roots.push(nodes.length - 1);
     }
     const json = {

package/dist/build/index.d.ts

@@ -1,3 +1,4 @@
+import { type FlameKind } from "../data/propellants.ts";
 import { type Description, type FitReport } from "../fit.ts";
 import { type Angle, type Vec3, type ViewName } from "../framing.ts";
 import { type LookName } from "../looks.ts";
@@ -5,25 +6,77 @@ import { type PartMesh, type Bounds, type Piece } from "../model/pieces.ts";
 import type { PartRecord } from "../parts.ts";
 import { type LitBell } from "../engines.ts";
 import { type Glb, toGlb } from "./glb.ts";
-/** Raised when a description does not fit: its report says why. */
+/**
+ * Raised by `build` when a description does not fit. Its `report` says why, in the same words `check` gives.
+ *
+ * @param report The report of the fit check that failed.
+ * @example
+ * ```ts
+ * import { build, FitError } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * try {
+ *   build({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * } catch (error) {
+ *   if (error instanceof FitError) console.log(error.report.issues[0]?.message);
+ * }
+ * ```
+ */
 export declare class FitError extends Error {
     readonly report: FitReport;
     constructor(report: FitReport);
 }
+/**
+ * One part of a built rocket: its slot, its record, the pieces it is made of, its mesh and its bounds in metres.
+ *
+ * @example
+ * ```ts
+ * import { build, type BuiltPart } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const first: BuiltPart | undefined = build({ rocket: "falcon-9", variant: "block-5" }).parts[0];
+ * console.log(first?.slot, first?.record.name);
+ * ```
+ */
 export interface BuiltPart {
     slot: string;
     record: PartRecord;
     pieces: readonly Piece[];
     mesh: PartMesh;
     bounds: Bounds;
+    /** The colour of this part's flame, from what a page says its engine burns; `neutral` when none read here says. */
+    flame: FlameKind;
 }
+/**
+ * What a drawing is asked for: the look, the view, what to show and whether the engines are lit. Anything left out takes its default.
+ *
+ * @example
+ * ```ts
+ * import { build, type SvgOptions } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const options: SvgOptions = { look: "thick", view: "below", show: "booster" };
+ * console.log(build({ rocket: "starship", variant: "v3" }).svg(options).startsWith("<svg"));
+ * ```
+ */
 export interface SvgOptions {
     look?: LookName;
     view?: ViewName | Angle;
     show?: string;
     /** A flame at each engine that is showing, or as many as a count names for each part. The length is a picture, not a measured flame. Left out, the drawing is unchanged. */
     engines?: boolean | Readonly<Record<string, number>>;
+    /** Degrees each moving group of each part is turned from where it is drawn at rest, by slot and then by name: `{ booster: { "grid-fins": 12 } }`. A flight asks for them. */
+    moves?: Readonly<Record<string, Readonly<Record<string, number>>>>;
 }
+/**
+ * A rocket built from a description: the fit report, its parts, and the ways to ask for its size, where each part stands, its lit engines, a `.glb` file and a drawing.
+ *
+ * @example
+ * ```ts
+ * import { build, type Built } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket: Built = build({ rocket: "starship", variant: "v3" });
+ * console.log(rocket.shows.join(", "));
+ * console.log(rocket.boundsOf("together").max);
+ * ```
+ */
 export interface Built {
     report: FitReport;
     parts: readonly BuiltPart[];
@@ -44,14 +97,51 @@ export interface Built {
     /** The drawing, in a look, from an angle. */
     svg(options?: SvgOptions): string;
 }
-/** What a drawing draws of a part: in a stack, what nests inside the part below is out of sight. */
+/**
+ * What a drawing draws of a part: in a stack, what nests inside the part below is out of sight.
+ *
+ * @param part A built part: its record and its pieces.
+ * @param together True when the part stands in a stack, false when it is shown alone.
+ * @returns The pieces to draw. In a stack, what nests inside the part below is left out.
+ * @example
+ * ```ts
+ * import { build, drawnPieces } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const [first] = build({ rocket: "falcon-9", variant: "block-5" }).parts;
+ * if (first) console.log(drawnPieces(first, true).length, drawnPieces(first, false).length);
+ * ```
+ */
 export declare function drawnPieces(part: {
     record: PartRecord;
     pieces: readonly Piece[];
 }, together: boolean): readonly Piece[];
-/** A rocket from a description. Throws FitError when it does not go together. */
+/**
+ * A rocket from a description. Throws FitError when it does not go together.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns The built rocket. It throws a `FitError` when the description does not go together.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-heavy" });
+ * console.log(rocket.report.label, rocket.glb().bytes.length > 1000);
+ * ```
+ */
 export declare function build(description: Description): Built;
-/** One part on its own, by its id. */
+/**
+ * One part on its own, by its id.
+ *
+ * @param id A part's id, as `PART_ENTRIES` lists it.
+ * @returns The part's record and bounds, a function for its `.glb` and one for its drawing. It throws for an id that is not a part.
+ * @example
+ * ```ts
+ * import { buildPart } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const raptor = buildPart("raptor-vacuum");
+ * console.log(raptor.record.name, raptor.bounds.max);
+ * ```
+ */
 export declare function buildPart(id: string): {
     record: PartRecord;
     bounds: Bounds;

package/dist/build/index.js

@@ -1,15 +1,32 @@
 // The builder: one description into one mesh and one drawing. Works in Node and in a browser, with no dependency: the geometry here is this package's own.
+import { propellantOf } from "../data/propellants.js";
 import { check } from "../fit.js";
 import { cleanView, DEFAULT_VIEW, PICTURE_H, PICTURE_W, VIEWS } from "../framing.js";
 import { cleanShow, placesFor, showsOf } from "../layout.js";
 import { DEFAULT_LOOK } from "../looks.js";
 import { boundsOf, meshOf } from "../model/pieces.js";
+import { moved } from "../model/moves.js";
 import { partEntry } from "../model/registry.js";
+import { partIdOf, variantOf } from "../rockets.js";
 import { plumeMarkup } from "../draw/plume.js";
 import { defsOf, drawPart, perspective } from "../draw/svg.js";
 import { bellsOf, litBells, pickBells, plumeLength } from "../engines.js";
 import { toGlb } from "./glb.js";
-/** Raised when a description does not fit: its report says why. */
+/**
+ * Raised by `build` when a description does not fit. Its `report` says why, in the same words `check` gives.
+ *
+ * @param report The report of the fit check that failed.
+ * @example
+ * ```ts
+ * import { build, FitError } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * try {
+ *   build({ rocket: "starship", variant: "v3", parts: { booster: "starship-v3-ship" } });
+ * } catch (error) {
+ *   if (error instanceof FitError) console.log(error.report.issues[0]?.message);
+ * }
+ * ```
+ */
 export class FitError extends Error {
     report;
     constructor(report) {
@@ -42,10 +59,20 @@ const widthOf = (id) => {
     const { min, max } = made(id).bounds;
     return Math.max(Math.abs(min[0]), Math.abs(max[0]), Math.abs(min[2]), Math.abs(max[2]));
 };
+/** What colour a part's flame is: the kind its engine's page says it burns, found by the engine's name in the data of a variant the part is true for. */
+function flameKindOf(part) {
+    for (const variantId of part.trueTo) {
+        const variant = variantOf(part.rocket, variantId);
+        for (const [slot, engines] of Object.entries(variant?.facts.engines ?? {}))
+            if (partIdOf(part.rocket, variantId, slot) === part.id)
+                return propellantOf(part.rocket, engines.value)?.flame ?? "neutral";
+    }
+    return "neutral";
+}
 function assembled(report) {
     const parts = report.parts.map(({ slot, part }) => {
         const { pieces, mesh, bounds } = made(part.id);
-        return { slot, record: part, pieces, mesh, bounds };
+        return { slot, record: part, pieces, mesh, bounds, flame: flameKindOf(part) };
     });
     const slots = parts.map((part) => part.slot);
     const placesOf = (show) => placesFor(report.parts, cleanShow(show, slots), (part) => widthOf(part.id));
@@ -84,7 +111,7 @@ function assembled(report) {
         placesOf,
         flamesOf,
         glb: () => toGlb(parts.map((part) => ({ name: part.slot, mesh: part.mesh, at: placesOf("together").find((place) => place.slot === part.slot)?.at ?? [0, 0, 0] }))),
-        svg: ({ look = DEFAULT_LOOK, view = DEFAULT_VIEW, show, engines = false } = {}) => {
+        svg: ({ look = DEFAULT_LOOK, view = DEFAULT_VIEW, show, engines = false, moves } = {}) => {
             const angle = typeof view === "string" ? VIEWS[cleanView(view)] : view;
             const places = placesOf(show).filter((place) => place.shown);
             // a flame drawn at full thrust is held in the picture; a count of engines is the timeline's, which has its own room
@@ -103,26 +130,63 @@ function assembled(report) {
                     ? flamesOf(show).filter((bell) => places.some((place) => place.slot === bell.slot))
                     : [];
             return wrap(ordered
-                .map(({ place, part }) => drawPart(drawnPieces(part, together), place.at, cam, look) + plumeMarkup(flames.filter((bell) => bell.slot === place.slot), place.at, cam, look, part.slot))
+                .map(({ place, part }) => drawPart(moved(drawnPieces(part, together), moves?.[part.slot] ?? {}), place.at, cam, look) + plumeMarkup(flames.filter((bell) => bell.slot === place.slot), place.at, cam, look, part.slot, part.flame))
                 .join(""), look, PICTURE_W, PICTURE_H, report.label);
         },
     };
 }
-/** What a drawing draws of a part: in a stack, what nests inside the part below is out of sight. */
+/**
+ * What a drawing draws of a part: in a stack, what nests inside the part below is out of sight.
+ *
+ * @param part A built part: its record and its pieces.
+ * @param together True when the part stands in a stack, false when it is shown alone.
+ * @returns The pieces to draw. In a stack, what nests inside the part below is left out.
+ * @example
+ * ```ts
+ * import { build, drawnPieces } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const [first] = build({ rocket: "falcon-9", variant: "block-5" }).parts;
+ * if (first) console.log(drawnPieces(first, true).length, drawnPieces(first, false).length);
+ * ```
+ */
 export function drawnPieces(part, together) {
     const joint = part.record.joints.bottom?.y ?? 0;
     if (!together || joint <= 0)
         return part.pieces;
     return part.pieces.filter((piece) => !(piece.kind === "lathe" && piece.under && Math.max(...piece.profile.map(([, y]) => y)) <= joint + 0.01));
 }
-/** A rocket from a description. Throws FitError when it does not go together. */
+/**
+ * A rocket from a description. Throws FitError when it does not go together.
+ *
+ * @param description The rocket, its variant and any other part in a slot.
+ * @returns The built rocket. It throws a `FitError` when the description does not go together.
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-heavy" });
+ * console.log(rocket.report.label, rocket.glb().bytes.length > 1000);
+ * ```
+ */
 export function build(description) {
     const report = check(description);
     if (!report.ok)
         throw new FitError(report);
     return assembled(report);
 }
-/** One part on its own, by its id. */
+/**
+ * One part on its own, by its id.
+ *
+ * @param id A part's id, as `PART_ENTRIES` lists it.
+ * @returns The part's record and bounds, a function for its `.glb` and one for its drawing. It throws for an id that is not a part.
+ * @example
+ * ```ts
+ * import { buildPart } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const raptor = buildPart("raptor-vacuum");
+ * console.log(raptor.record.name, raptor.bounds.max);
+ * ```
+ */
 export function buildPart(id) {
     const entry = partEntry(id);
     if (!entry)

package/dist/build/lineup.d.ts

@@ -1,6 +1,15 @@
 import { type ViewName } from "../framing.ts";
 import { type LookName } from "../looks.ts";
-/** Comparison shapes: plain round sizes, for scale, not facts about anything. */
+/**
+ * Comparison shapes: plain round sizes, for scale, not facts about anything.
+ *
+ * @example
+ * ```ts
+ * import { COMPARES } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * console.log(COMPARES.person.height, COMPARES.building.height);
+ * ```
+ */
 export declare const COMPARES: {
     readonly person: {
         readonly name: "A person, 1.8 m";
@@ -13,13 +22,46 @@ export declare const COMPARES: {
         readonly width: 18;
     };
 };
+/**
+ * The name of a comparison shape that can stand in a lineup: `person` or `building`.
+ *
+ * @example
+ * ```ts
+ * import type { CompareId } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const id: CompareId = "person";
+ * console.log(id);
+ * ```
+ */
 export type CompareId = keyof typeof COMPARES;
+/**
+ * One thing standing in a lineup: its key (`starship:v3` or a comparison's name), its label and its height in metres.
+ *
+ * @example
+ * ```ts
+ * import { lineupSvg, type LineupItem } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const items: LineupItem[] = lineupSvg({ items: ["starship:v3", "person"], unit: 3 }).items;
+ * console.log(items.map((item) => item.label));
+ * ```
+ */
 export interface LineupItem {
     /** "starship:v3" or a comparison's name. */
     key: string;
     label: string;
     height: number;
 }
+/**
+ * What a lineup is asked for: the items by key, how many pixels make a metre, and optionally the look, the view, what to show, a ruler and labels.
+ *
+ * @example
+ * ```ts
+ * import { lineupSvg, type LineupOptions } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const options: LineupOptions = { items: ["starship:v2", "starship:v3", "building"], unit: 3, ruler: true, labels: true };
+ * console.log(lineupSvg(options).width);
+ * ```
+ */
 export interface LineupOptions {
     /** "starship:v1,starship:v3,person,building". */
     items: readonly string[];
@@ -31,7 +73,19 @@ export interface LineupOptions {
     ruler?: boolean;
     labels?: boolean;
 }
-/** The whole picture as SVG text. Unknown items are left out. */
+/**
+ * The whole picture as SVG text. Unknown items are left out.
+ *
+ * @param options The items and how they are drawn.
+ * @returns The picture as SVG text, the items it holds, and its width and height.
+ * @example
+ * ```ts
+ * import { lineupSvg } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const picture = lineupSvg({ items: ["falcon-9:block-5", "falcon-heavy:falcon-heavy", "person"], unit: 4, ruler: true });
+ * console.log(picture.items.length, picture.svg.startsWith("<svg"));
+ * ```
+ */
 export declare function lineupSvg(options: LineupOptions): {
     svg: string;
     items: LineupItem[];

package/dist/build/lineup.js

@@ -6,7 +6,16 @@ import { DEFAULT_LOOK, LOOKS } from "../looks.js";
 import { defsOf, drawPart, orthographic } from "../draw/svg.js";
 import { MATERIALS } from "../model/materials.js";
 import { variantOf } from "../rockets.js";
-/** Comparison shapes: plain round sizes, for scale, not facts about anything. */
+/**
+ * Comparison shapes: plain round sizes, for scale, not facts about anything.
+ *
+ * @example
+ * ```ts
+ * import { COMPARES } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * console.log(COMPARES.person.height, COMPARES.building.height);
+ * ```
+ */
 export const COMPARES = {
     person: { name: "A person, 1.8 m", height: 1.8, width: 0.5 },
     building: { name: "A ten-storey building, 30 m", height: 30, width: 18 },
@@ -33,7 +42,19 @@ function comparison(id, x, base, unit, line, fill) {
         floors += `M${n(x)} ${n(base - (h * i) / 10)}h${n(w)}`;
     return `<rect x="${n(x)}" y="${n(base - h)}" width="${n(w)}" height="${n(h)}" fill="${fill}" stroke="${line}" stroke-width=".9"/><path d="${floors}" stroke="${line}" stroke-width=".35" opacity=".6"/>`;
 }
-/** The whole picture as SVG text. Unknown items are left out. */
+/**
+ * The whole picture as SVG text. Unknown items are left out.
+ *
+ * @param options The items and how they are drawn.
+ * @returns The picture as SVG text, the items it holds, and its width and height.
+ * @example
+ * ```ts
+ * import { lineupSvg } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const picture = lineupSvg({ items: ["falcon-9:block-5", "falcon-heavy:falcon-heavy", "person"], unit: 4, ruler: true });
+ * console.log(picture.items.length, picture.svg.startsWith("<svg"));
+ * ```
+ */
 export function lineupSvg(options) {
     const { items, unit, look = DEFAULT_LOOK, view = "front", ruler = true, labels = true } = options;
     const angle = VIEWS[cleanView(view)];