@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.5.0

package/dist/model/pieces.d.ts

@@ -7,6 +7,15 @@ export interface Frame {
     v: Vec3;
     w: Vec3;
 }
+/**
+ * A piece that a flight can turn: the name of the group it belongs to (every piece with the same name and pivot turns together), the point it turns about and the axis it turns round, in the part's own metres.
+ * A positive angle turns it right-handed about the axis. The piece is drawn where its group is at rest, which is the angle 0.
+ */
+export interface Move {
+    name: string;
+    pivot: Vec3;
+    axis: Vec3;
+}
 /** A body of revolution: `profile` is [radius, y] points going up the outside (going the other way faces inward). */
 export interface Lathe {
     kind: "lathe";
@@ -32,6 +41,7 @@ export interface Lathe {
     body?: boolean;
     /** Its outline is drawn in a drawing. */
     outline?: boolean;
+    move?: Move;
 }
 /** A flat outline with a thickness, in a frame: `outline` is [u, v] points, going round; it stands from -thickness/2 to +thickness/2 along w. Convex, or it is drawn as its hull. */
 export interface Plate {
@@ -47,6 +57,7 @@ export interface Plate {
     only?: "mesh" | "drawing";
     /** No feature lines of its own. */
     plain?: boolean;
+    move?: Move;
 }
 /** Lines only, in the part's own space. */
 export interface Lines {
@@ -54,6 +65,7 @@ export interface Lines {
     weight: "feature" | "weld";
     paths: readonly (readonly Vec3[])[];
     only?: "mesh" | "drawing";
+    move?: Move;
 }
 export type Piece = Lathe | Plate | Lines;
 /** A frame standing on the axis: u points outwards at `az` radians, v is up, w is along the circle. */
@@ -76,15 +88,34 @@ export interface LineBuffers {
     positions: number[];
     indices: number[];
 }
+/** The mesh of one moving group, its points relative to its pivot, so the group turns about its own origin. */
+export interface MoveMesh {
+    /** The group's name, and a node name of its own: `grid-fins~0`, `grid-fins~1`. */
+    name: string;
+    id: string;
+    pivot: Vec3;
+    axis: Vec3;
+    mesh: PartMesh;
+}
 export interface PartMesh {
     faces: Map<MaterialName, Buffers>;
     feature: LineBuffers;
     weld: LineBuffers;
+    /** What a flight can turn, apart from the rest. Empty for a part with no moving group. */
+    moves: MoveMesh[];
 }
 /** A ring just proud of the surface at a height, so it is not lost in it. */
 export declare function ringPath(piece: Lathe, y: number, lift?: number): Vec3[];
 /** The triangles and lines of a part. */
 export declare function meshOf(pieces: readonly Piece[]): PartMesh;
+/** The groups a flight can turn: the pieces with a `move`, by name and pivot, in the order they come, each with a node name of its own. */
+export declare function moveGroups(pieces: readonly Piece[]): {
+    name: string;
+    id: string;
+    pivot: Vec3;
+    axis: Vec3;
+    pieces: Piece[];
+}[];
 export interface Bounds {
     min: Vec3;
     max: Vec3;

package/dist/model/pieces.js

@@ -178,7 +178,43 @@ function plateFaces(mesh, piece) {
 }
 /** The triangles and lines of a part. */
 export function meshOf(pieces) {
-    const mesh = { faces: new Map(), feature: { positions: [], indices: [] }, weld: { positions: [], indices: [] } };
+    const mesh = meshOfFixed(pieces.filter((piece) => !piece.move));
+    for (const group of moveGroups(pieces)) {
+        const part = meshOfFixed(group.pieces);
+        const shift = (positions) => {
+            for (let i = 0; i < positions.length; i += 3)
+                for (let c = 0; c < 3; c++)
+                    positions[i + c] -= group.pivot[c];
+        };
+        for (const buffers of part.faces.values())
+            shift(buffers.positions);
+        shift(part.feature.positions);
+        shift(part.weld.positions);
+        mesh.moves.push({ name: group.name, id: group.id, pivot: group.pivot, axis: group.axis, mesh: part });
+    }
+    return mesh;
+}
+/** The groups a flight can turn: the pieces with a `move`, by name and pivot, in the order they come, each with a node name of its own. */
+export function moveGroups(pieces) {
+    const groups = [];
+    const counts = new Map();
+    for (const piece of pieces) {
+        if (!piece.move)
+            continue;
+        const key = `${piece.move.name}@${piece.move.pivot.join(",")}`;
+        let group = groups.find((one) => one.key === key);
+        if (!group) {
+            const n = counts.get(piece.move.name) ?? 0;
+            counts.set(piece.move.name, n + 1);
+            group = { name: piece.move.name, id: `${piece.move.name}~${n}`, pivot: piece.move.pivot, axis: piece.move.axis, pieces: [], key };
+            groups.push(group);
+        }
+        group.pieces.push(piece);
+    }
+    return groups.map((group) => ({ name: group.name, id: group.id, pivot: group.pivot, axis: group.axis, pieces: group.pieces }));
+}
+function meshOfFixed(pieces) {
+    const mesh = { faces: new Map(), feature: { positions: [], indices: [] }, weld: { positions: [], indices: [] }, moves: [] };
     for (const piece of pieces) {
         if (piece.only === "drawing")
             continue;
@@ -211,13 +247,19 @@ export function meshOf(pieces) {
 export function boundsOf(mesh) {
     const min = [Infinity, Infinity, Infinity];
     const max = [-Infinity, -Infinity, -Infinity];
-    for (const b of mesh.faces.values())
-        for (let i = 0; i < b.positions.length; i += 3)
-            for (let c = 0; c < 3; c++) {
-                if (b.positions[i + c] < min[c])
-                    min[c] = b.positions[i + c];
-                if (b.positions[i + c] > max[c])
-                    max[c] = b.positions[i + c];
-            }
+    const sweep = (from, offset) => {
+        for (const b of from.faces.values())
+            for (let i = 0; i < b.positions.length; i += 3)
+                for (let c = 0; c < 3; c++) {
+                    const value = b.positions[i + c] + offset[c];
+                    if (value < min[c])
+                        min[c] = value;
+                    if (value > max[c])
+                        max[c] = value;
+                }
+    };
+    sweep(mesh, [0, 0, 0]);
+    for (const group of mesh.moves)
+        sweep(group.mesh, group.pivot);
     return { min, max };
 }

package/dist/model/registry.d.ts

@@ -4,5 +4,27 @@ export interface PartEntry {
     record: PartRecord;
     pieces: () => Piece[];
 }
+/**
+ * Every part of every rocket, each with its record: its real size in metres, the joints it mates at, and where its shape came from.
+ *
+ * @example
+ * ```ts
+ * import { PART_ENTRIES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(PART_ENTRIES.length, PART_ENTRIES[0]?.record.name);
+ * ```
+ */
 export declare const PART_ENTRIES: readonly PartEntry[];
+/**
+ * Finds a part by its id.
+ *
+ * @param id A part's id.
+ * @returns The part's entry, or undefined for an id that is not a part.
+ * @example
+ * ```ts
+ * import { partEntry } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(partEntry("raptor-vacuum")?.record.height, partEntry("nonsense"));
+ * ```
+ */
 export declare const partEntry: (id: string) => PartEntry | undefined;

package/dist/model/registry.js

@@ -162,6 +162,28 @@ const RAPTOR_LENGTH = { value: 3.1, source: "wikipedia-raptor", note: "The famil
 const b3 = STARSHIP_DRAWS.v3;
 const b2 = STARSHIP_DRAWS.v2;
 entries.push(detail("raptor-sea-level", "engine", "Raptor, sea-level", 3.1, 1.24, { height: RAPTOR_LENGTH, diameter: RAPTOR_DIAMETER }, () => raptor([0, 0], 0, "sea")), detail("raptor-vacuum", "engine", "Raptor, vacuum", 4.4, 2.3, { height: blankFigure, diameter: blankFigure }, () => raptor([0, 0], 0, "vacuum")), detail("grid-fin-four", "fin", "Grid fin, Blocks 1 and 2", 0.9, 2.9, { height: blankFigure, diameter: blankFigure }, () => gridFin(90, 0, b2.radius, b2.fins.reach, b2.fins.width, b2.fins.thick, false)), detail("grid-fin-three", "fin", "Grid fin, Block 3", 0.9, 3.4, { height: blankFigure, diameter: blankFigure }, () => gridFin(90, 0, b3.radius, b3.fins.reach, b3.fins.width, b3.fins.thick, true)), detail("flap-aft", "flap", "Aft flap", 11.6, 3.8, { height: blankFigure, diameter: blankFigure }, () => [flap(b3.aft, 1)]), detail("flap-forward", "flap", "Forward flap, Blocks 2 and 3", 8.1, 4.7, { height: blankFigure, diameter: blankFigure }, () => [flap(b3.forward, 1)]), detail("merlin-sea-level", "engine", "Merlin, sea-level", 2, 0.92, { height: blankFigure, diameter: blankFigure }, () => merlin([0, 0], 0, 0.46, 2)));
+/**
+ * Every part of every rocket, each with its record: its real size in metres, the joints it mates at, and where its shape came from.
+ *
+ * @example
+ * ```ts
+ * import { PART_ENTRIES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(PART_ENTRIES.length, PART_ENTRIES[0]?.record.name);
+ * ```
+ */
 export const PART_ENTRIES = entries;
 const byId = new Map(entries.map((entry) => [entry.record.id, entry]));
+/**
+ * Finds a part by its id.
+ *
+ * @param id A part's id.
+ * @returns The part's entry, or undefined for an id that is not a part.
+ * @example
+ * ```ts
+ * import { partEntry } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(partEntry("raptor-vacuum")?.record.height, partEntry("nonsense"));
+ * ```
+ */
 export const partEntry = (id) => byId.get(id);

package/dist/model/starship.d.ts

@@ -57,10 +57,13 @@ export interface StarshipDraw {
 export declare const STARSHIP_DRAWS: Readonly<Record<string, StarshipDraw>>;
 /** One Raptor from its exit up: the bell, its dark inside and the machinery over it. Its origin is the middle of its exit. */
 export declare function raptor(at: readonly [number, number], y: number, type: "sea" | "vacuum"): Piece[];
-/** A grid fin held out flat: a frame and a lattice, u outwards and v along the circle. */
-export declare function gridFin(azDeg: number, y: number, rootRadius: number, reach: number, width: number, thick: number, octagon: boolean): Piece[];
+/** A grid fin held out flat: a frame and a lattice, u outwards and v along the circle. With `turn`, every piece of it is one moving group, hinged at its root: round the fin's own axis out from the hull (`radial`, how it steers) or across it (`tangent`, how it folds in). */
+export declare function gridFin(azDeg: number, y: number, rootRadius: number, reach: number, width: number, thick: number, octagon: boolean, turn?: {
+    name: string;
+    about: "radial" | "tangent";
+}): Piece[];
 /** A flap's plate, tiled on its windward face. `outline` is [radius, height]. */
-export declare function flap(draw: FlapDraw, side: 1 | -1): Plate;
+export declare function flap(draw: FlapDraw, side: 1 | -1, name?: string): Plate;
 /** Super Heavy: its base on the axis at the bells' exit. */
 export declare function boosterPieces(d: StarshipDraw): Piece[];
 /** The ship: its base on the axis at the bottom of its skirt. */

package/dist/model/starship.js

@@ -230,8 +230,8 @@ function clip(a, b, outline) {
         [a[0] + d[0] * t1, a[1] + d[1] * t1],
     ];
 }
-/** A grid fin held out flat: a frame and a lattice, u outwards and v along the circle. */
-export function gridFin(azDeg, y, rootRadius, reach, width, thick, octagon) {
+/** A grid fin held out flat: a frame and a lattice, u outwards and v along the circle. With `turn`, every piece of it is one moving group, hinged at its root: round the fin's own axis out from the hull (`radial`, how it steers) or across it (`tangent`, how it folds in). */
+export function gridFin(azDeg, y, rootRadius, reach, width, thick, octagon, turn) {
     const frame = flat(deg(azDeg), y);
     const r0 = rootRadius + 0.35;
     const hw = width / 2;
@@ -291,10 +291,14 @@ export function gridFin(azDeg, y, rootRadius, reach, width, thick, octagon) {
     });
     // where it meets the hull
     pieces.push(strut("fin", pointOf(frame, rootRadius - 0.1, 0, 0), pointOf(frame, r0 + 0.05, 0, 0), 1, 0.7, { only: "mesh" }));
+    if (turn) {
+        const move = { name: turn.name, pivot: pointOf(frame, r0, 0, 0), axis: turn.about === "radial" ? frame.u : frame.v };
+        return pieces.map((piece) => ({ ...piece, move }));
+    }
     return pieces;
 }
 /** A flap's plate, tiled on its windward face. `outline` is [radius, height]. */
-export function flap(draw, side) {
+export function flap(draw, side, name) {
     const az = deg(draw.az) * side;
     const frame = radial(az);
     // w must look windward, so the +w face takes the tiles
@@ -308,7 +312,8 @@ export function flap(draw, side) {
         if (seam)
             ribs.push(seam);
     }
-    return { kind: "plate", material: "steel", top: "tile-plain", frame: windward, outline: draw.outline, thickness: draw.thickness, ribs };
+    const hinge = name ? { name, pivot: pointOf(frame, Math.min(...reach), 0, 0), axis: [0, side, 0] } : undefined;
+    return { kind: "plate", material: "steel", top: "tile-plain", frame: windward, outline: draw.outline, thickness: draw.thickness, ribs, ...(hinge ? { move: hinge } : {}) };
 }
 /** A flap's root fairing above it. */
 function fairing(azDeg, y0, y1, surface, proud) {
@@ -448,7 +453,7 @@ export function boosterPieces(d) {
     // the band of vents round the common dome
     pieces.push({ kind: "lathe", material: "engine-pale", segs: 64, only: "mesh", profile: [[r + 0.015, topOfHull * 0.62 - 0.12], [r + 0.015, topOfHull * 0.62 + 0.12]] });
     for (const az of d.fins.az)
-        pieces.push(...gridFin(az, d.fins.y, r, d.fins.reach, d.fins.width, d.fins.thick, d.fins.octagon));
+        pieces.push(...gridFin(az, d.fins.y, r, d.fins.reach, d.fins.width, d.fins.thick, d.fins.octagon, { name: "grid-fins", about: "radial" }));
     if (d.ring.height > 0)
         pieces.push(...hotStage(d));
     else
@@ -475,8 +480,8 @@ export function shipPieces(d) {
     pieces.push(...engineRings(d.shipEngines, 0.2));
     const surface = (y) => radiusAt(profile, y);
     for (const side of [1, -1]) {
-        pieces.push(flap(d.aft, side));
-        pieces.push(flap(d.forward, side));
+        pieces.push(flap(d.aft, side, "aft-flaps"));
+        pieces.push(flap(d.forward, side, "forward-flaps"));
         const aftTop = Math.max(...d.aft.outline.map(([, y]) => y));
         pieces.push(fairing(d.aft.az * side, aftTop - 1, aftTop + 2.8, surface, 0.8));
         const fwdBottom = Math.min(...d.forward.outline.map(([, y]) => y));

package/dist/parts.d.ts

@@ -1,7 +1,28 @@
 import type { CreditId } from "./data/credits.ts";
 import type { Figure } from "./data/types.ts";
+/**
+ * What kind of part a record is: a booster, a ship, a stage, a fairing, a capsule, an engine, a fin and so on. A joint only mates a part of a kind that fits it.
+ *
+ * @example
+ * ```ts
+ * import { partEntry, type PartKind } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const kind: PartKind | undefined = partEntry("raptor-vacuum")?.record.kind;
+ * console.log(kind);
+ * ```
+ */
 export type PartKind = "booster" | "first-stage" | "ship" | "second-stage" | "fairing" | "capsule" | "trunk" | "engine" | "fin" | "flap" | "ring" | "test-vehicle" | "third-stage" | "adapter" | "service-module" | "tower" | "tank" | "solid-booster" | "liquid-booster" | "orbiter" | "deck" | "mount" | "arms" | "site" | "spacecraft";
-/** Where a part mates. Every part's origin is the middle of its base on its axis, at its lowest point; Y is up and the windward side faces +Z, in metres. */
+/**
+ * Where a part mates. Every part's origin is the middle of its base on its axis, at its lowest point; Y is up and the windward side faces +Z, in metres.
+ *
+ * @example
+ * ```ts
+ * import { partEntry, type Joint } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const top: Joint | undefined = partEntry("starship-v3-booster")?.record.joints.top;
+ * console.log(top);
+ * ```
+ */
 export interface Joint {
     /** What this joint is, so only like meets like: "stage". */
     kind: "stage";
@@ -10,6 +31,17 @@ export interface Joint {
     /** Metres across at the joint. */
     diameter: number;
 }
+/**
+ * The one record every part has: its id, kind and name, the rocket and variants it is true for, its height and diameter in metres, the sourced figures, its joints, any painted model, and where its shape came from.
+ *
+ * @example
+ * ```ts
+ * import { partEntry, type PartRecord } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const record: PartRecord | undefined = partEntry("starship-v3-ship")?.record;
+ * console.log(record?.name, record?.height, record?.trueTo);
+ * ```
+ */
 export interface PartRecord {
     id: string;
     kind: PartKind;

package/dist/pixels.d.ts

@@ -1,8 +1,48 @@
-/** The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million). */
+/**
+ * The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million).
+ *
+ * @example
+ * ```ts
+ * import { MAX_PIXELS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_PIXELS);
+ * ```
+ */
 export declare const MAX_PIXELS = 6000000;
-/** The longest side the backing store may have. */
+/**
+ * The longest side the backing store may have.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SIDE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_SIDE);
+ * ```
+ */
 export declare const MAX_SIDE = 4096;
-/** The sharpest ratio ever used, however dense the screen. */
+/**
+ * The sharpest ratio ever used, however dense the screen.
+ *
+ * @example
+ * ```ts
+ * import { MAX_RATIO } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_RATIO);
+ * ```
+ */
 export declare const MAX_RATIO = 2;
-/** The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value. */
+/**
+ * The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value.
+ *
+ * @param width The view's width in CSS pixels.
+ * @param height Its height in CSS pixels.
+ * @param deviceRatio The screen's own pixel ratio.
+ * @returns The ratio to draw at.
+ * @example
+ * ```ts
+ * import { pixelRatioFor } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(pixelRatioFor(620, 827, 3), pixelRatioFor(3000, 3000, 2));
+ * ```
+ */
 export declare function pixelRatioFor(width: number, height: number, deviceRatio: number): number;

package/dist/pixels.js

@@ -1,11 +1,51 @@
 // How sharp the 3D canvas may be. The backing store is width x height x ratio squared, and a view as big as a 5K screen at a ratio of 2 would ask the graphics card for 15 million pixels, every frame. Pure.
-/** The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million). */
+/**
+ * The most the backing store may hold, in pixels (a 620 x 827 view at a ratio of 2 is 2 million).
+ *
+ * @example
+ * ```ts
+ * import { MAX_PIXELS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_PIXELS);
+ * ```
+ */
 export const MAX_PIXELS = 6_000_000;
-/** The longest side the backing store may have. */
+/**
+ * The longest side the backing store may have.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SIDE } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_SIDE);
+ * ```
+ */
 export const MAX_SIDE = 4096;
-/** The sharpest ratio ever used, however dense the screen. */
+/**
+ * The sharpest ratio ever used, however dense the screen.
+ *
+ * @example
+ * ```ts
+ * import { MAX_RATIO } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(MAX_RATIO);
+ * ```
+ */
 export const MAX_RATIO = 2;
-/** The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value. */
+/**
+ * The device pixel ratio to draw a `width` x `height` view at: the screen's own, held to 2, to 4096 pixels a side and to 6 million in all. At least 0.25, and 1 for a nonsense value.
+ *
+ * @param width The view's width in CSS pixels.
+ * @param height Its height in CSS pixels.
+ * @param deviceRatio The screen's own pixel ratio.
+ * @returns The ratio to draw at.
+ * @example
+ * ```ts
+ * import { pixelRatioFor } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(pixelRatioFor(620, 827, 3), pixelRatioFor(3000, 3000, 2));
+ * ```
+ */
 export function pixelRatioFor(width, height, deviceRatio) {
     const w = Math.max(1, width);
     const h = Math.max(1, height);

package/dist/react.d.ts

@@ -2,6 +2,17 @@ import { type HTMLAttributes, type Ref } from "react";
 import type { Description } from "./fit.ts";
 import type { ViewName } from "./framing.ts";
 import type { LookName } from "./looks.ts";
+/**
+ * The props of the React wrapper: the element's attributes as props (`rocket`, `variant`, `show`, `look`, `view`, `mode`, `assets`, `spin`, `way`, `label`, `engines`, `phase`), `build` as an object, and any other HTML attribute.
+ *
+ * @example
+ * ```ts
+ * import type { UchusenRocketProps } from "@johnmorrisdotca/uchusen-rockets/react";
+ *
+ * const props: UchusenRocketProps = { rocket: "starship", variant: "v3", look: "thick" };
+ * console.log(props);
+ * ```
+ */
 export interface UchusenRocketProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
     rocket?: string;
     variant?: string;
@@ -22,6 +33,19 @@ export interface UchusenRocketProps extends Omit<HTMLAttributes<HTMLElement>, "s
     phase?: string;
     ref?: Ref<HTMLElement>;
 }
+/**
+ * A thin React wrapper round `<uchusen-rocket>`. It loads the element on first use, so server rendering draws only the tag.
+ *
+ * @param props The props. `build` is turned into the element's JSON attribute; the rest go through as they are.
+ * @returns The `<uchusen-rocket>` element. It is never null or undefined.
+ * @example
+ * ```tsx no-run
+ * import { UchusenRocket } from "@johnmorrisdotca/uchusen-rockets/react";
+ *
+ * export const Hero = () => <UchusenRocket rocket="falcon-9" variant="block-5" look="painted" />;
+ * console.log(typeof UchusenRocket);
+ * ```
+ */
 export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): import("react").DOMElement<{
     build: string | undefined;
     rocket?: string;
@@ -40,14 +64,14 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     /** A phase of the rocket's flight, by its id. */
     phase?: string;
     ref?: Ref<HTMLElement>;
-    part?: string | undefined | undefined;
     id?: string | undefined | undefined;
+    about?: string | undefined | undefined;
+    part?: string | undefined | undefined;
     slot?: string | undefined | undefined;
     children?: import("react").ReactNode;
     title?: string | undefined | undefined;
     "aria-label"?: string | undefined | undefined;
     "aria-live"?: "off" | "assertive" | "polite" | undefined | undefined;
-    about?: string | undefined | undefined;
     "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined | undefined;
     "aria-valuetext"?: string | undefined | undefined;
     color?: string | undefined | undefined;

package/dist/react.js

@@ -1,5 +1,18 @@
 // A thin React wrapper round `<uchusen-rocket>`.
 import { createElement, useEffect } from "react";
+/**
+ * A thin React wrapper round `<uchusen-rocket>`. It loads the element on first use, so server rendering draws only the tag.
+ *
+ * @param props The props. `build` is turned into the element's JSON attribute; the rest go through as they are.
+ * @returns The `<uchusen-rocket>` element. It is never null or undefined.
+ * @example
+ * ```tsx no-run
+ * import { UchusenRocket } from "@johnmorrisdotca/uchusen-rockets/react";
+ *
+ * export const Hero = () => <UchusenRocket rocket="falcon-9" variant="block-5" look="painted" />;
+ * console.log(typeof UchusenRocket);
+ * ```
+ */
 export function UchusenRocket({ build, ...rest }) {
     useEffect(() => {
         void import("./element.js");

package/dist/rockets.d.ts

@@ -1,7 +1,29 @@
 import { type MakerId } from "./data/makers.ts";
 import type { Figure, Variant } from "./data/types.ts";
 import type { SourceId } from "./data/sources.ts";
+/**
+ * Whether a rocket is `built` (it has a shape) or `planned` (it has facts and no shape yet).
+ *
+ * @example
+ * ```ts
+ * import { ROCKETS, type RocketStatus } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const status: RocketStatus | undefined = ROCKETS["starship"]?.status;
+ * console.log(status);
+ * ```
+ */
 export type RocketStatus = "built" | "planned";
+/**
+ * One rocket: its id and name, its variants, its default variant, the group it is listed under and who made it.
+ *
+ * @example
+ * ```ts
+ * import { ROCKETS, type RocketEntry } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const starship: RocketEntry | undefined = ROCKETS["starship"];
+ * console.log(starship?.name, starship?.variants.map((variant) => variant.id));
+ * ```
+ */
 export interface RocketEntry {
     id: string;
     name: string;
@@ -13,7 +35,17 @@ export interface RocketEntry {
     /** Whose it is and who built it, as its source says, or a blank. */
     madeBy: Figure<string>;
 }
-/** A rocket on the list with no mesh yet: its name and the sourced facts to build it from. */
+/**
+ * A rocket on the list with no mesh yet: its name and the sourced facts to build it from.
+ *
+ * @example
+ * ```ts
+ * import { PLANNED_ROCKETS, type PlannedRocket } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const planned: PlannedRocket | undefined = PLANNED_ROCKETS[0];
+ * console.log(planned?.name);
+ * ```
+ */
 export interface PlannedRocket {
     id: string;
     name: string;
@@ -23,10 +55,66 @@ export interface PlannedRocket {
     firstFlight: Figure<string>;
     source: SourceId;
 }
+/**
+ * Every rocket that has a shape, by id, each with its variants. Add a rocket here and the element, the drawing, the fit check and the demo all read it.
+ *
+ * @example
+ * ```ts
+ * import { ROCKETS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(Object.keys(ROCKETS).slice(0, 6));
+ * ```
+ */
 export declare const ROCKETS: Readonly<Record<string, RocketEntry>>;
+/**
+ * Rockets with sourced facts and no shape yet.
+ *
+ * @example
+ * ```ts
+ * import { PLANNED_ROCKETS } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(PLANNED_ROCKETS.map((rocket) => rocket.name));
+ * ```
+ */
 export declare const PLANNED_ROCKETS: readonly PlannedRocket[];
+/**
+ * Finds a rocket's variant, with its sourced sizes.
+ *
+ * @param rocket A rocket's id.
+ * @param id A variant's id. Left out, null or undefined: the rocket's default variant.
+ * @returns The variant, or undefined when the rocket or the variant is not known.
+ * @example
+ * ```ts
+ * import { variantOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const v3 = variantOf("starship", "v3");
+ * console.log(v3?.facts.height.value, variantOf("starship", "v99"));
+ * ```
+ */
 export declare function variantOf(rocket: string, id?: string | null): Variant | undefined;
-/** A part's name for a rocket's slot in a variant. */
+/**
+ * A part's name for a rocket's slot in a variant.
+ *
+ * @param rocket A rocket's id.
+ * @param variant A variant's id.
+ * @param slot A slot name.
+ * @returns The id of the part that stands in that slot.
+ * @example
+ * ```ts
+ * import { partIdOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(partIdOf("starship", "v3", "booster"));
+ * ```
+ */
 export declare const partIdOf: (rocket: string, variant: string, slot: string) => string;
-/** What to call a slot. */
+/**
+ * What to call a slot.
+ *
+ * @example
+ * ```ts
+ * import { SLOT_NAMES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(SLOT_NAMES["booster"]);
+ * ```
+ */
 export declare const SLOT_NAMES: Readonly<Record<string, string>>;