@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.5.0

package/dist/rockets.js

@@ -21,6 +21,16 @@ import { ISS_VARIANTS } from "./data/iss.js";
 import { HUBBLE_VARIANTS } from "./data/hubble.js";
 import { STARSHIP_VARIANTS } from "./data/starship.js";
 import { MADE_BY } from "./data/makers.js";
+/**
+ * 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 const ROCKETS = {
     starship: { id: "starship", name: "Starship", status: "built", ...MADE_BY["starship"], variants: STARSHIP_VARIANTS, defaultVariant: "v3" },
     "falcon-9": { id: "falcon-9", name: "Falcon 9", status: "built", ...MADE_BY["falcon-9"], variants: FALCON_9_VARIANTS, defaultVariant: "block-5" },
@@ -47,17 +57,63 @@ export const ROCKETS = {
     starbase: { id: "starbase", name: "Starbase", status: "built", ...MADE_BY["starbase"], variants: STARBASE_VARIANTS, defaultVariant: "launch-site" },
 };
 const fig = (value, source) => ({ value, source });
+/**
+ * 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 const PLANNED_ROCKETS = [
     { id: "vulcan-centaur", name: "Vulcan Centaur", status: "planned", height: fig(61.6, "wikipedia-vulcan"), diameter: fig(5.4, "wikipedia-vulcan"), firstFlight: { value: "2024-01-08", source: "wikipedia-vulcan" }, source: "wikipedia-vulcan" },
     { id: "ariane-6", name: "Ariane 6", status: "planned", height: fig(63, "wikipedia-ariane-6"), diameter: fig(5.4, "wikipedia-ariane-6"), firstFlight: { value: "2024-07-09", source: "wikipedia-ariane-6" }, source: "wikipedia-ariane-6" },
 ];
+/**
+ * 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 function variantOf(rocket, id) {
     const entry = Object.hasOwn(ROCKETS, rocket) ? ROCKETS[rocket] : undefined;
     return entry?.variants.find((variant) => variant.id === (id ?? entry.defaultVariant));
 }
-/** 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 const partIdOf = (rocket, variant, slot) => variantOf(rocket, variant)?.partIds?.[slot] ?? `${rocket}-${variant}-${slot}`;
-/** 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 const SLOT_NAMES = {
     booster: "Super Heavy",
     ship: "Ship",

package/dist/spin.d.ts

@@ -1,11 +1,66 @@
+/**
+ * Which way a rocket turns: `cw` (clockwise) or `ccw` (counter-clockwise).
+ *
+ * @example
+ * ```ts
+ * import type { Way } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const way: Way = "ccw";
+ * console.log(way);
+ * ```
+ */
 export type Way = "cw" | "ccw";
+/**
+ * The slow turn of a rocket: the seconds a full turn takes (0 is none) and which way.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SPIN, type Spin } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const spin: Spin = DEFAULT_SPIN;
+ * console.log(spin.seconds, spin.way);
+ * ```
+ */
 export interface Spin {
     /** Seconds a turn, 0 for not at all. */
     seconds: number;
     way: Way;
 }
+/**
+ * The spin used when none is asked for: 180 seconds a turn, clockwise.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SPIN } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(DEFAULT_SPIN);
+ * ```
+ */
 export declare const DEFAULT_SPIN: Spin;
-/** Anything but `ccw` is the default way. */
+/**
+ * Anything but `ccw` is the default way.
+ *
+ * @param value Anything.
+ * @returns `ccw` for `ccw`, and `cw` for anything else.
+ * @example
+ * ```ts
+ * import { cleanWay } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(cleanWay("ccw"), cleanWay("left"));
+ * ```
+ */
 export declare const cleanWay: (value: unknown) => Way;
-/** A spin from the `spin` and `way` attributes: a name, or seconds a turn. A nonsense value is the default, and a negative one is none. */
+/**
+ * A spin from the `spin` and `way` attributes: a name, or seconds a turn. A nonsense value is the default, and a negative one is none.
+ *
+ * @param spin The `spin` attribute: `off`, `slow`, `medium`, `fast`, or seconds a turn. Null when missing.
+ * @param way The `way` attribute. Null when missing.
+ * @returns The spin to use.
+ * @example
+ * ```ts
+ * import { spinOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(spinOf("fast", null), spinOf("30", "ccw"), spinOf("nonsense", null));
+ * ```
+ */
 export declare function spinOf(spin: string | null, way: string | null): Spin;

package/dist/spin.js

@@ -1,9 +1,42 @@
 // How a view turns by itself. `way` is which way round: `cw`, clockwise seen from above, takes the near side to the viewer's left, and `ccw` to the right. Pure.
 const NAMED = { off: 0, slow: 180, medium: 67, fast: 20 };
+/**
+ * The spin used when none is asked for: 180 seconds a turn, clockwise.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SPIN } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(DEFAULT_SPIN);
+ * ```
+ */
 export const DEFAULT_SPIN = { seconds: 180, way: "cw" };
-/** Anything but `ccw` is the default way. */
+/**
+ * Anything but `ccw` is the default way.
+ *
+ * @param value Anything.
+ * @returns `ccw` for `ccw`, and `cw` for anything else.
+ * @example
+ * ```ts
+ * import { cleanWay } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(cleanWay("ccw"), cleanWay("left"));
+ * ```
+ */
 export const cleanWay = (value) => (value === "ccw" ? "ccw" : "cw");
-/** A spin from the `spin` and `way` attributes: a name, or seconds a turn. A nonsense value is the default, and a negative one is none. */
+/**
+ * A spin from the `spin` and `way` attributes: a name, or seconds a turn. A nonsense value is the default, and a negative one is none.
+ *
+ * @param spin The `spin` attribute: `off`, `slow`, `medium`, `fast`, or seconds a turn. Null when missing.
+ * @param way The `way` attribute. Null when missing.
+ * @returns The spin to use.
+ * @example
+ * ```ts
+ * import { spinOf } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(spinOf("fast", null), spinOf("30", "ccw"), spinOf("nonsense", null));
+ * ```
+ */
 export function spinOf(spin, way) {
     const raw = spin === null ? NaN : Object.hasOwn(NAMED, spin) ? NAMED[spin] : Number(spin);
     const seconds = spin === null || spin.trim() === "" || !Number.isFinite(raw) ? DEFAULT_SPIN.seconds : Math.max(0, raw);

package/dist/tilt.d.ts

@@ -1,20 +1,64 @@
+/**
+ * Whether tilting a device turns the view: `off`, `ask` (the browser must ask first, as on iOS) or `on`.
+ *
+ * @example
+ * ```ts
+ * import type { TiltMode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const mode: TiltMode = "ask";
+ * console.log(mode);
+ * ```
+ */
 export type TiltMode = "off" | "ask" | "on";
-/** Off under reduced motion, on a computer with a mouse, or where the browser has no orientation events; "ask" where it must ask first (iOS: a tap
- * on "Tilt to turn" asks, never the page by itself); else on. */
+/**
+ * Off under reduced motion, on a computer with a mouse, or where the browser has no orientation events; "ask" where it must ask first (iOS: a tap on "Tilt to turn" asks, never the page by itself); else on.
+ *
+ * @param env What the page knows: reduced motion, a coarse pointer (touch), whether the browser has orientation events, and whether it must ask permission first.
+ * @returns `off`, `ask` or `on`.
+ * @example
+ * ```ts
+ * import { tiltMode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(tiltMode({ reducedMotion: false, coarsePointer: true, hasOrientation: true, needsPermission: true }));
+ * ```
+ */
 export declare function tiltMode(env: {
     reducedMotion: boolean;
     coarsePointer: boolean;
     hasOrientation: boolean;
     needsPermission: boolean;
 }): TiltMode;
+/**
+ * One reading of a device's orientation: front to back (`beta`, -180 to 180 degrees) and left to right (`gamma`, -90 to 90 degrees). Either is null when the device gives none.
+ *
+ * @example
+ * ```ts
+ * import type { Reading } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const reading: Reading = { beta: 20, gamma: -5 };
+ * console.log(reading);
+ * ```
+ */
 export interface Reading {
     /** Front to back, -180 to 180 degrees. */
     beta: number | null;
     /** Left to right, -90 to 90 degrees. */
     gamma: number | null;
 }
-/** The turn (degrees round, degrees up or down) for a reading, measured from `rest` (how the device was held when tilting began). `angle` is the
- * screen's orientation (0, 90, 180 or 270), so leaning a phone held sideways still turns the view the way it looks. Null for an empty reading. */
+/**
+ * The turn (degrees round, degrees up or down) for a reading, measured from `rest` (how the device was held when tilting began). `angle` is the screen's orientation (0, 90, 180 or 270), so leaning a phone held sideways still turns the view the way it looks. Null for an empty reading.
+ *
+ * @param reading The current reading.
+ * @param rest The reading when tilting began.
+ * @param angle The screen's orientation: 0, 90, 180 or 270. Defaults to 0.
+ * @returns The turn in degrees round (`azimuth`) and up or down (`polar`), or null for an empty reading.
+ * @example
+ * ```ts
+ * import { tiltTurn } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(tiltTurn({ beta: 30, gamma: 10 }, { beta: 20, gamma: 0 }), tiltTurn({ beta: null, gamma: null }, { beta: 0, gamma: 0 }));
+ * ```
+ */
 export declare function tiltTurn(reading: Reading, rest: Reading, angle?: number): {
     azimuth: number;
     polar: number;

package/dist/tilt.js

@@ -1,6 +1,16 @@
 // Tilt to turn: on a phone or tablet, leaning the device turns a 3D view a little. Pure: when it is offered, and how a reading becomes a turn of the view.
-/** Off under reduced motion, on a computer with a mouse, or where the browser has no orientation events; "ask" where it must ask first (iOS: a tap
- * on "Tilt to turn" asks, never the page by itself); else on. */
+/**
+ * Off under reduced motion, on a computer with a mouse, or where the browser has no orientation events; "ask" where it must ask first (iOS: a tap on "Tilt to turn" asks, never the page by itself); else on.
+ *
+ * @param env What the page knows: reduced motion, a coarse pointer (touch), whether the browser has orientation events, and whether it must ask permission first.
+ * @returns `off`, `ask` or `on`.
+ * @example
+ * ```ts
+ * import { tiltMode } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(tiltMode({ reducedMotion: false, coarsePointer: true, hasOrientation: true, needsPermission: true }));
+ * ```
+ */
 export function tiltMode(env) {
     if (env.reducedMotion || !env.coarsePointer || !env.hasOrientation)
         return "off";
@@ -10,8 +20,20 @@ const GAIN = 0.6;
 const MAX_TURN = 25;
 const MAX_LEAN = 12;
 const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
-/** The turn (degrees round, degrees up or down) for a reading, measured from `rest` (how the device was held when tilting began). `angle` is the
- * screen's orientation (0, 90, 180 or 270), so leaning a phone held sideways still turns the view the way it looks. Null for an empty reading. */
+/**
+ * The turn (degrees round, degrees up or down) for a reading, measured from `rest` (how the device was held when tilting began). `angle` is the screen's orientation (0, 90, 180 or 270), so leaning a phone held sideways still turns the view the way it looks. Null for an empty reading.
+ *
+ * @param reading The current reading.
+ * @param rest The reading when tilting began.
+ * @param angle The screen's orientation: 0, 90, 180 or 270. Defaults to 0.
+ * @returns The turn in degrees round (`azimuth`) and up or down (`polar`), or null for an empty reading.
+ * @example
+ * ```ts
+ * import { tiltTurn } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(tiltTurn({ beta: 30, gamma: 10 }, { beta: 20, gamma: 0 }), tiltTurn({ beta: null, gamma: null }, { beta: 0, gamma: 0 }));
+ * ```
+ */
 export function tiltTurn(reading, rest, angle = 0) {
     if (reading.beta === null || reading.gamma === null || rest.beta === null || rest.gamma === null)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/uchusen-rockets",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Uchusen Rockets 宇宙船: line drawings and 3D views of rockets, as a web component. Every variant with its own sourced sizes, a typed way to assemble a rocket from parts, stack and separate. No logos. three.js is a peer dependency.",
   "keywords": [
     "rocket",
@@ -91,11 +91,17 @@
     "prepublishOnly": "pnpm check",
     "site": "pnpm build && node scripts/site.ts",
     "dev": "pnpm site && node scripts/dev.ts",
-    "test:demo": "pnpm site && playwright test",
+    "test:demo": "pnpm site && node scripts/docs-site.mjs build && playwright test",
     "test:freeze": "pnpm site && playwright test e2e/freeze.demo.ts --project=chromium-desk",
-    "screenshots": "pnpm site && node scripts/screenshots.ts",
+    "test:usage": "pnpm site && node scripts/check-usage.ts",
+    "family:readme": "node scripts/family-readme.mjs",
+    "check:standard": "node scripts/check-standard.mjs",
+    "screenshots": "pnpm site && node scripts/docs-site.mjs build && node scripts/screenshots.ts",
     "models": "node scripts/reduce-models.ts",
-    "models:nasa": "node scripts/reduce-nasa.ts"
+    "models:nasa": "node scripts/reduce-nasa.ts",
+    "docs:site": "pnpm build && node scripts/docs-site.mjs build",
+    "docs:check": "pnpm build && node scripts/docs-site.mjs check",
+    "size": "node scripts/docs-site.mjs size"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -110,26 +116,40 @@
     }
   },
   "devDependencies": {
+    "@angular/common": "^22.2.4",
+    "@angular/compiler": "^22.2.4",
+    "@angular/core": "^22.2.4",
+    "@angular/platform-browser": "^22.2.4",
     "@eslint/js": "9.39.5",
     "@gltf-transform/core": "4.5.1",
     "@gltf-transform/extensions": "4.5.1",
     "@gltf-transform/functions": "4.5.1",
-    "@johnmorrisdotca/chikyu-earth": "0.5.0",
-    "@johnmorrisdotca/kazoku-ui": "^0.10.0",
+    "@johnmorrisdotca/chikyu-earth": "0.10.0",
+    "@johnmorrisdotca/kazoku-ui": "^0.12.0",
     "@playwright/test": "1.64.0",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
     "@types/node": "24.10.1",
     "@types/react": "19.2.7",
     "@types/react-dom": "19.2.3",
     "@types/three": "0.186.0",
+    "@vitejs/plugin-vue": "^6.0.10",
     "draco3dgltf": "1.5.7",
     "esbuild": "0.25.12",
     "eslint": "9.39.5",
+    "marked": "^18.1.3",
     "meshoptimizer": "1.3.0",
+    "pagefind": "^1.6.0",
     "react": "19.3.1",
     "react-dom": "19.3.1",
+    "rxjs": "^7.8.2",
+    "svelte": "^5.57.3",
     "three": "0.186.1",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.72.1"
+    "typescript-eslint": "8.72.1",
+    "vite": "^8.3.5",
+    "vue": "^3.5.44",
+    "webpack": "^5.112.2",
+    "webpack-cli": "^7.3.1"
   },
   "publishConfig": {
     "access": "public"