@johnmorrisdotca/wakusei-planets 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0
+
+"Put it in your page" is a configurator.
+
+- **Set up a body, copy the code.** The demo's last section follows what is set up above it (body, look, sky and date, moons, turning) and a size (160, 240, 320 or 480), and writes working code for plain HTML from jsDelivr, an ES module, React, Vue, Angular, Svelte and an iframe of the embed page, on tabs that answer the arrow keys, beside a picture made from the same choices, with a Copy button and the credits that go with the picture. The choices are kept in the address (`?embed=react&size=240`).
+- **`embedCode(options, kind, settings)` and `embedCredit(options)`** make the same text for a page of your own (`EMBED_KINDS`: `html`, `module`, `react`, `vue`, `angular`, `svelte`, `iframe`). Pattern: senshu-jerseys' `embedCode` and its tabbed "Put it in your page". Every snippet is tested (`test/embed.test.ts`): the React component is built and rendered, the Vue and Svelte components compiled, the Angular template parsed, the module checked as TypeScript, the iframe's address read the way the embed page reads it, and every body's entry point exists in the package.
+- A guide, "Put it in your page", in English and Japanese.
+- **kazoku-ui 0.11.0**: the view controls' Centre button (it appears once the body is dragged away), a pan that keeps a quarter of the body in sight (told the body's size with `object-size`), and a drag that keeps the touched point under the pointer (`grab-radius`). The 0.3.1 stopgap that made Fit re-centre is gone.
+
 ## 0.3.1
 
 The Earth is a body like the others, and "To scale" is a comparison.

package/README.md

@@ -11,9 +11,9 @@ A clean line drawing, a shaded realistic drawing, or a painted surface map, with
 
 <p align="center"><a href="https://johnmorrisdotca.github.io/wakusei-planets/"><strong>Open the demo →</strong></a> · <a href="https://johnmorrisdotca.github.io/wakusei-planets/embed.html">Embed page</a> · <a href="https://johnmorrisdotca.github.io/wakusei-planets/docs/">Docs</a></p>
 
-<p align="center"><img alt="Jupiter and Saturn drawn in the realistic look, and Saturn as a line drawing" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.3.1/docs/images/hero-desk.png" width="640"></p>
+<p align="center"><img alt="Jupiter and Saturn drawn in the realistic look, and Saturn as a line drawing" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.4.0/docs/images/hero-desk.png" width="640"></p>
 
-<p align="center"><img alt="Every body at one scale, the Earth among them: each small body has a magnified picture joined by a line, and the Sun shows only its edge" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.3.1/docs/images/lineup-desk.png" width="640"></p>
+<p align="center"><img alt="Every body at one scale, the Earth among them: each small body has a magnified picture joined by a line, and the Sun shows only its edge" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.4.0/docs/images/lineup-desk.png" width="640"></p>
 
 ## One minute
 
@@ -94,6 +94,7 @@ Give a body a `time` and it is drawn as the sky shows it then: its pole and rota
 | An ES module in Vite or webpack, only the bodies you need | [bundlers guide](docs/guides/bundlers.md) |
 | React, Vue, Svelte, Angular; Next.js, Nuxt, SvelteKit | [frameworks guide](docs/guides/frameworks.md) |
 | An `<iframe>` of the embed page, no script of your own | [iframe guide](docs/guides/embed-in-an-iframe.md) |
+| Set up a body in the demo and copy the code for HTML, React, Vue, Angular, Svelte or an iframe | [Put it in your page](docs/guides/put-it-in-your-page.md), or `embedCode()` |
 | TypeScript types, an SVG string on a server, Node | [TypeScript and Node guide](docs/guides/typescript-and-node.md) |
 | The looks, the entry points, one WebGL context | [looks and bodies](docs/guides/looks-and-bodies.md) |
 | Moons where they are on a date, time that runs fast | [moons and time](docs/guides/moons-and-time.md) |

package/dist/element.d.ts

@@ -25,7 +25,7 @@ export type WakuseiState = "line" | "loading" | "still" | "live" | "lost" | "una
  * console.log(TEXTURE_BASE);
  * ```
  */
-export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@0.3.1/dist/textures/";
+export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@0.4.0/dist/textures/";
 /**
  * Where the sharpest surface pictures are: the files of this exact version in the repository, on jsDelivr's GitHub address. The npm package holds only the two smaller widths, so a page that
  * never zooms in never fetches them. Set `texture-far-base` on an element to serve them yourself.
@@ -37,7 +37,7 @@ export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdot
  * console.log(TEXTURE_FAR_BASE);
  * ```
  */
-export declare const TEXTURE_FAR_BASE = "https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v0.3.1/textures/";
+export declare const TEXTURE_FAR_BASE = "https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v0.4.0/textures/";
 /**
  * The `<wakusei-body>` custom element: a body of the solar system, drawn in a look.
  *

package/dist/embed.d.ts

@@ -0,0 +1,96 @@
+import { type BodyId, type Look } from "./facts.ts";
+/**
+ * The ways `embedCode` writes a body into a page.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
+export declare const EMBED_KINDS: readonly ["html", "module", "react", "vue", "angular", "svelte", "iframe"];
+/**
+ * One of the ways in `EMBED_KINDS`.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS, type EmbedKind } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const kind: EmbedKind = EMBED_KINDS[2];
+ * console.log(kind);
+ * ```
+ */
+export type EmbedKind = (typeof EMBED_KINDS)[number];
+/**
+ * What the reader chose: the body, how it is drawn, and whether it is a portrait or the sky at a date.
+ *
+ * @example
+ * ```ts
+ * import { embedCode, type EmbedOptions } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const options: EmbedOptions = { body: "saturn", look: "painted", size: 320, turn: 12 };
+ * console.log(embedCode(options, "html"));
+ * ```
+ */
+export interface EmbedOptions {
+    body: BodyId;
+    look?: Look;
+    /** The date and time as an ISO string, or `now`: the body as the Earth sees it then. Left out, a portrait. */
+    time?: string;
+    /** A planet with its moons on their orbits (needs `time`). */
+    moons?: boolean;
+    /** Degrees a second it turns by itself; left out or 0, it is still. */
+    turn?: number;
+    /** Pixels across. */
+    size?: number;
+}
+/**
+ * Where the embed code points: the package's version on jsDelivr, and the published demo, where `embed.html` is.
+ *
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCode({ body: "mars", look: "line" }, "iframe", { site: "https://example.com/wakusei/" }));
+ * ```
+ */
+export interface EmbedSettings {
+    /** The published demo's address, ending in a slash. */
+    site?: string;
+    /** The package's address on the CDN, with its version. */
+    cdn?: string;
+}
+/** The entry point that holds a body's shaded and painted look. */
+export declare function entryOf(id: BodyId): string;
+/**
+ * The text that puts a body in a page, for one way of making the page. Each way is built, parsed or run by the package's tests: the plain HTML one with a script tag from jsDelivr, an ES module, a React component,
+ * a Vue single-file component, an Angular standalone component, a Svelte component, and an iframe of the demo's `embed.html`.
+ *
+ * @param options - The body, its look, the date, the moons, the turn and the size.
+ * @param kind - The way the page is made; `html` by default.
+ * @param settings - The CDN and the demo's address, when they are not the package's own.
+ * @returns The text to paste into the page's source.
+ *
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCode({ body: "jupiter", look: "realistic", time: "now", moons: true }, "react"));
+ * ```
+ */
+export declare function embedCode(options: EmbedOptions, kind?: EmbedKind, settings?: EmbedSettings): string;
+/**
+ * The credits that travel with a picture of a body: the line and shaded looks are drawn from numbers, the painted look uses public-domain pictures.
+ *
+ * @param options - The choices, so only what is used is named.
+ * @returns A short line of credit to put near the picture.
+ *
+ * @example
+ * ```ts
+ * import { embedCredit } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCredit({ body: "mars", look: "painted" }));
+ * ```
+ */
+export declare function embedCredit(options: EmbedOptions): string;

package/dist/embed.js

@@ -0,0 +1,112 @@
+// The text to put a body in a page, for each way a page is made: a script tag from a CDN, an ES module, React, Vue, Angular, Svelte, or an iframe of `embed.html`. The demo's "Put it in your page"
+// section shows these as the reader changes a choice, and the tests build or parse every one. Pure: no DOM.
+import { BODIES } from "./facts.js";
+import { VERSION } from "./version.js";
+/**
+ * The ways `embedCode` writes a body into a page.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
+export const EMBED_KINDS = ["html", "module", "react", "vue", "angular", "svelte", "iframe"];
+const SITE = "https://johnmorrisdotca.github.io/wakusei-planets/";
+const CDN = `https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@${VERSION}`;
+const PACKAGE = "@johnmorrisdotca/wakusei-planets";
+/** The entry point that holds a body's shaded and painted look. */
+export function entryOf(id) {
+    const parent = BODIES[id].parent;
+    return parent === undefined ? id : `moons-${parent}`;
+}
+/** The attributes of the element for these choices, in the order they are written. */
+function attributesOf(o) {
+    const out = [["body", o.body], ["look", o.look ?? "realistic"]];
+    if (o.size !== undefined && o.size !== 320)
+        out.push(["size", String(o.size)]);
+    if (o.time !== undefined)
+        out.push(["time", o.time]);
+    if (o.moons === true && o.time !== undefined)
+        out.push(["moons", ""]);
+    if (o.turn !== undefined && o.turn > 0)
+        out.push(["turn", String(o.turn)]);
+    return out;
+}
+const quote = (v) => `"${v.replace(/&/g, "&").replace(/"/g, """)}"`;
+const tagAttrs = (o) => attributesOf(o).map(([k, v]) => (v === "" ? k : `${k}=${quote(v)}`)).join(" ");
+const needsShading = (o) => (o.look ?? "realistic") !== "line";
+/**
+ * The text that puts a body in a page, for one way of making the page. Each way is built, parsed or run by the package's tests: the plain HTML one with a script tag from jsDelivr, an ES module, a React component,
+ * a Vue single-file component, an Angular standalone component, a Svelte component, and an iframe of the demo's `embed.html`.
+ *
+ * @param options - The body, its look, the date, the moons, the turn and the size.
+ * @param kind - The way the page is made; `html` by default.
+ * @param settings - The CDN and the demo's address, when they are not the package's own.
+ * @returns The text to paste into the page's source.
+ *
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCode({ body: "jupiter", look: "realistic", time: "now", moons: true }, "react"));
+ * ```
+ */
+export function embedCode(options, kind = "html", settings = {}) {
+    const cdn = settings.cdn ?? CDN;
+    const site = settings.site ?? SITE;
+    const shaded = needsShading(options);
+    const entry = entryOf(options.body);
+    const size = options.size ?? 320;
+    if (kind === "iframe") {
+        const query = new URLSearchParams({ body: options.body, look: options.look ?? "realistic" });
+        if (options.time !== undefined)
+            query.set("time", options.time);
+        if (options.moons === true && options.time !== undefined)
+            query.set("moons", "1");
+        if (options.turn !== undefined && options.turn > 0)
+            query.set("turn", String(options.turn));
+        return `<iframe\n  src=${quote(`${site}embed.html?${query.toString()}`)}\n  title=${quote(BODIES[options.body].name.en)}\n  width="${size}"\n  height="${size}"\n  loading="lazy"\n  style="border: 0"\n></iframe>`;
+    }
+    if (kind === "html") {
+        const scripts = [`<script type="module" src="${cdn}/element/+esm"></script>`, ...(shaded ? [`<script type="module" src="${cdn}/${entry}/+esm"></script>`] : [])];
+        return `${scripts.join("\n")}\n\n<wakusei-body ${tagAttrs(options)}></wakusei-body>`;
+    }
+    const imports = [`import "${PACKAGE}/element";`, ...(shaded ? [`import "${PACKAGE}/${entry}";`] : [])];
+    if (kind === "module") {
+        const sets = attributesOf(options).map(([k, v]) => `planet.setAttribute(${JSON.stringify(k)}, ${JSON.stringify(v)});`);
+        return `${imports.join("\n")}\n\nconst planet = document.createElement("wakusei-body");\n${sets.join("\n")}\ndocument.querySelector("#planet").append(planet);`;
+    }
+    const dynamic = [`void import("${PACKAGE}/element");`, ...(shaded ? [`void import("${PACKAGE}/${entry}");`] : [])];
+    if (kind === "react") {
+        const props = attributesOf(options).map(([k, v]) => (v === "" ? k : `${k}=${quote(v)}`)).join(" ");
+        return `import { useEffect } from "react";\n\nexport function Planet() {\n  useEffect(() => {\n    // The element needs a browser, so it is imported in an effect, never at the top of the file.\n${dynamic.map((l) => `    ${l}`).join("\n")}\n  }, []);\n  return <wakusei-body ${props} />;\n}`;
+    }
+    if (kind === "vue") {
+        return `<script setup lang="ts">\nimport { onMounted } from "vue";\n\nonMounted(() => {\n${dynamic.map((l) => `  ${l}`).join("\n")}\n});\n</script>\n\n<template>\n  <wakusei-body ${tagAttrs(options)}></wakusei-body>\n</template>`;
+    }
+    if (kind === "angular") {
+        return `import { Component, CUSTOM_ELEMENTS_SCHEMA, OnInit } from "@angular/core";\n\n@Component({\n  selector: "app-planet",\n  standalone: true,\n  schemas: [CUSTOM_ELEMENTS_SCHEMA],\n  template: \`<wakusei-body ${tagAttrs(options)}></wakusei-body>\`,\n})\nexport class PlanetComponent implements OnInit {\n  ngOnInit(): void {\n    // The element needs a browser: ngOnInit also runs when a server renders.\n    if (typeof window !== "undefined") {\n${dynamic.map((l) => `      ${l}`).join("\n")}\n    }\n  }\n}`;
+    }
+    return `<script lang="ts">\n  import { onMount } from "svelte";\n\n  onMount(() => {\n${dynamic.map((l) => `    ${l}`).join("\n")}\n  });\n</script>\n\n<wakusei-body ${tagAttrs(options)}></wakusei-body>`;
+}
+/**
+ * The credits that travel with a picture of a body: the line and shaded looks are drawn from numbers, the painted look uses public-domain pictures.
+ *
+ * @param options - The choices, so only what is used is named.
+ * @returns A short line of credit to put near the picture.
+ *
+ * @example
+ * ```ts
+ * import { embedCredit } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCredit({ body: "mars", look: "painted" }));
+ * ```
+ */
+export function embedCredit(options) {
+    const base = "Wakusei Planets by John Morris (MIT). Sizes, tilt and rotation: IAU and NASA fact sheets.";
+    const painted = (options.look ?? "realistic") === "painted" ? " Surface pictures: NASA, USGS and JPL imagery in the public domain (details in the package's NOTICE.md)." : "";
+    const earth = options.body === "earth" ? " Earth: NASA Earth Observatory, Blue Marble." : "";
+    return `${base}${painted}${earth}`;
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { apparent, moonGeocentric, heliocentric, orbitPath, system, type Apparen
 export { drawnTilt, portrait, type PortraitOptions } from "./pose.ts";
 export { lineSvg, mix, type LineOptions } from "./line.ts";
 export { ringStrip, type RingStrip } from "./scene/rings.ts";
+export { embedCode, embedCredit, EMBED_KINDS, type EmbedKind, type EmbedOptions, type EmbedSettings } from "./embed.ts";

package/dist/index.js

@@ -3,3 +3,4 @@ export { apparent, moonGeocentric, heliocentric, orbitPath, system } from "./eph
 export { drawnTilt, portrait } from "./pose.js";
 export { lineSvg, mix } from "./line.js";
 export { ringStrip } from "./scene/rings.js";
+export { embedCode, embedCredit, EMBED_KINDS } from "./embed.js";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.4.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.3.1";
+export const VERSION = "0.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/wakusei-planets",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Wakusei Planets 惑星 — The Sun, planets and moons for the web: each as a clean line drawing, a shaded realistic drawing or a painted surface map, with real sizes, axial tilt and rotation as data, and positions of the moons for any date and time. SVG for the lines, three.js (optional) for the rest.",
   "keywords": [
     "planets",
@@ -217,11 +217,11 @@
   },
   "packageManager": "pnpm@10.28.0",
   "dependencies": {
-    "@johnmorrisdotca/kazoku-ui": "^0.9.1"
+    "@johnmorrisdotca/kazoku-ui": "^0.11.0"
   },
   "peerDependencies": {
-    "three": ">=0.160.0",
-    "@johnmorrisdotca/chikyu-earth": ">=0.10.0"
+    "@johnmorrisdotca/chikyu-earth": ">=0.10.0",
+    "three": ">=0.160.0"
   },
   "peerDependenciesMeta": {
     "three": {