@johnmorrisdotca/kazoku-ui 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-11-03
+
+One "Put it in your page" panel for every package of the family.
+
+- **`<kazoku-embed-panel>`** (KAZOKU-UI-40 and KAZOKU-UI-30; John, 2026-11-03: "does every package that has embedded have all these options?", "if we do it better elsewhere then we should also use that as a template"). A package fills it with its own choices and its own code; the panel is the same everywhere: a **compact picker** for the thing being embedded (chips by group, a search box from twelve things up, buttons that scroll in their own box; or the package's own in the `picker` slot), a **size** (160, 240, 320, 480 by default), **a tab for each way a page is made** (HTML, ES module, React, Vue, Angular, Svelte, iframe, and any a package adds, such as an image address), **the picture the code makes**, built from the same choices and scaled to fit its box at every size on every screen (wakusei-planets' Venus was cut off on the right), **Copy** with its name on it and a polite "Copied", **Open the embed page**, **Read the docs** and **the credit line**. Slots keep what a package had: `options` (its own choices, between the size and the tabs), `actions` (Save SVG, Download), `picker` and `lede`; `note` and `credits` are a text or a function of the choices. `address` keeps the tab and the size in the link (`?embed=react&size=240`). `lang` (English and Japanese), `theme`, light and dark, 48 px targets, arrow keys, Home and End on the tabs. A package that draws nothing says `no-preview no-size` and still has the tabs, Copy, the docs link and the credit. New part: `@johnmorrisdotca/kazoku-ui/embed-panel`, `/element` and `/define`; the event is `kazoku-embedchange` with `{ kind, size, value, code, reason }`, and `kazoku-embedcopy` follows Copy.
+- **`embedSnippet(kind, spec)`** writes the seven ways from one description of the element (`SnippetSpec`: package, CDN address, tag, entry points, attributes, a name, the iframe), taken from wakusei-planets' generators, byte for byte; with `EMBED_KINDS`, `attrText`, `parseKinds`, `parseSizes`, `nearestSize`, `filterItems`, `groupsOf`, `kindLabel`, the labels in both languages and the defaults. The module imports on a server.
+- **The must-have list has a new item, `embed-panel`**: the demo's "Put it in your page" is kazoku-ui's panel (`templates/check-standard.mjs`, `STANDARD_VERSION` 2026-11-03; `docs/package-standard.md`). A package that cannot say why in `family.notApplicable`. A repo takes the new check when it is next touched; its rollout is a ticket on the modules board.
+- New demo pages `embed-panel.html` (a made-up badge with every part, then a package that draws nothing) and `embed.html` (the badge's embed page), `e2e/embed-panel.demo.mjs` (Chromium and WebKit, desk and phone, light and dark), `test/embed-panel.test.ts`.
+- Fixed: the demo server (`scripts/dev.mjs`) crashed on a file that does not exist after answering 200; it reads first.
+
+### Documentation
+
+- A guide, `embed-panel.md`, with its Japanese page and a picture; [the survey](docs/embed-panel-survey.md) of every package's panel and which does each part best; the README, getting started, architecture, labels and upgrading pages; the API reference lists the new part.
+
 ## [0.14.0] - 2026-11-03
 
 One speed control for the whole family: the Auto-turn speeds are 0.5×, 1× and 2×, and the same buttons serve a solar system's days a second and a replay bar.

package/README.md

@@ -11,7 +11,7 @@ The family's shared interface parts, as their own versioned package: one part pe
 The first part is the **view controls** for any 3D or zoomable view. They never draw the scene: they tell your page what the reader chose, and your canvas, WebGL,
 SVG or CSS 3D applies it.
 
-[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Layouts demo](https://johnmorrisdotca.github.io/kazoku-ui/layouts.html) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Speed buttons](docs/guides/speed-buttons.md) · [Shared 3D renderer](docs/renderer.md) · [The drag rule](docs/drag-rule.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md) · [Builder](https://johnmorrisdotca.github.io/kazoku-ui/builder.html) · [API reference](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/API.md) · [Guides](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides)
+[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Layouts demo](https://johnmorrisdotca.github.io/kazoku-ui/layouts.html) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Speed buttons](docs/guides/speed-buttons.md) · [Embed panel](docs/guides/embed-panel.md) · [Shared 3D renderer](docs/renderer.md) · [The drag rule](docs/drag-rule.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md) · [Builder](https://johnmorrisdotca.github.io/kazoku-ui/builder.html) · [API reference](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/API.md) · [Guides](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides)
 
 ## In 30 seconds
 
@@ -58,6 +58,7 @@ console.log(zoomText(2.44)); // 2.4×
 - **Theme switch** (Light, Dark, Auto) and **language picker** (each language in its own name) that write `data-theme` and `lang` and tell the page.
 - **Save image** for a canvas, an SVG or any element, as PNG or SVG.
 - **Speed buttons**: one row of 0.5×, 1×, 2× (or the steps you name: a solar system's days a second, a replay's speeds) for the whole family, kept in an attribute and the address.
+- **Embed panel**: the family's one "Put it in your page" panel: a compact picker, a size, a tab for HTML, ES module, React, Vue, Angular, Svelte and iframe (and your own, such as an image), a live picture that always fits its box, Copy, the embed page, the docs and the credit line.
 - **Address state**, with no element: choices kept in the link with `replaceState`.
 - **A shared 3D renderer** and its **freeze checks**: one WebGL context, shared assets, stills, a pixel budget.
 - **Labels in English and Japanese**, light and dark, 48 px touch targets, reduced motion respected.
@@ -160,6 +161,9 @@ Each its own subpath; later ones: picture-tile pickers, Help, GitHub and npm pil
 | `@johnmorrisdotca/kazoku-ui/speed-buttons` | The steps, how a speed reads, the nearest step and the address key of the speed buttons. Imports on a server. |
 | `@johnmorrisdotca/kazoku-ui/speed-buttons/element` | The `SpeedButtonsElement` class (needs a browser). |
 | `@johnmorrisdotca/kazoku-ui/speed-buttons/define` | Registers `<kazoku-speed-buttons>` (once, and only if the tag is free). |
+| `@johnmorrisdotca/kazoku-ui/embed-panel` | The seven ways a page is made and their text (`embedSnippet`), the sizes, the picker's search and the labels of the embed panel. Imports on a server. |
+| `@johnmorrisdotca/kazoku-ui/embed-panel/element` | The `EmbedPanelElement` class (needs a browser). |
+| `@johnmorrisdotca/kazoku-ui/embed-panel/define` | Registers `<kazoku-embed-panel>` (once, and only if the tag is free). |
 | `@johnmorrisdotca/kazoku-ui/renderer` | The shared 3D renderer: one WebGL context for the focused view, shared assets, stills, drawing on demand, a pixel budget. three.js is an optional peer, loaded by your `import("three")`. Imports on a server. |
 | `@johnmorrisdotca/kazoku-ui/testing` | The freeze checks for a 3D package's e2e: count contexts, GPU objects, draws and frames; the canvas size against the budget. No test framework named. |
 | `@johnmorrisdotca/kazoku-ui/address-state` | Choices kept in the address: read, write and subscribe to URL parameters with `replaceState`. No element; imports on a server. |
@@ -441,6 +445,22 @@ What a picture of an element cannot carry (web fonts, `::before`, cross-origin i
 
 See [the guide](docs/guides/speed-buttons.md) for the attributes, the event and the functions without the element.
 
+## Embed panel
+
+`<kazoku-embed-panel>` is the "Put it in your page" panel every package of the family shares: a compact picker for the thing being embedded, a size, a tab for each way a page is made, the picture the code makes (scaled to fit its box), Copy with its name on it, Open the embed page, Read the docs and the credit line. The package gives it `generate` (the code of a tab) and `preview` (the picture); `embedSnippet` writes all seven tabs from one description of the element.
+
+```html
+<kazoku-embed-panel id="panel" kinds="html module react vue angular svelte iframe" docs-href="docs/"></kazoku-embed-panel>
+<script type="module">
+  import "@johnmorrisdotca/kazoku-ui/embed-panel/define";
+  import { embedSnippet } from "@johnmorrisdotca/kazoku-ui/embed-panel";
+  document.getElementById("panel").generate = ({ kind, size }) =>
+    embedSnippet(kind, { package: "@scope/dial", cdn: "https://cdn.jsdelivr.net/npm/@scope/dial@1.0.0", tag: "scope-dial", element: "element", entries: [], attrs: [["size", String(size)]], name: "dial", iframe: { src: "https://example.com/embed.html", title: "Dial", width: size, height: size } });
+</script>
+```
+
+See [the guide](docs/guides/embed-panel.md) for the slots (a package's own choices and buttons), the picker, the events and a package that draws nothing, and [the survey](docs/embed-panel-survey.md) for which package's panel does each part best.
+
 ## Shared 3D renderer
 
 A page with many 3D views gets one WebGL context, handed to the focused view; the others are stills made once from the same renderer, kept in a budgeted list. Shared geometries,

package/dist/embed-panel/choices.d.ts

@@ -0,0 +1,42 @@
+/** The sizes (pixels across) the size buttons offer by default. */
+export declare const DEFAULT_SIZES: readonly number[];
+/** The size the panel starts on when the page names none and it is one of the sizes. */
+export declare const DEFAULT_SIZE = 320;
+/** The tabs the panel shows when the page names none: the seven ways a page is made. */
+export declare const DEFAULT_KINDS: readonly string[];
+/** The address parameters the panel keeps its two choices in. */
+export declare const KIND_ADDRESS_KEY = "embed";
+export declare const SIZE_ADDRESS_KEY = "size";
+/** More than this many things to pick from and the picker shows a search box. */
+export declare const SEARCH_FROM = 12;
+/**
+ * One thing the compact picker offers: a planet, a jersey, a stadium.
+ *
+ * @example
+ * ```ts
+ * import { type PickItem } from "@johnmorrisdotca/kazoku-ui/embed-panel";
+ *
+ * const mars: PickItem = { id: "mars", label: "Mars", group: "Planets" };
+ * console.log(mars.label);
+ * ```
+ */
+export interface PickItem {
+    /** What the page reads back from `value`. */
+    id: string;
+    /** What the button says. */
+    label: string;
+    /** The row of choices it is under (chips above the list); items with no group are only under All. */
+    group?: string;
+    /** More words the search matches (another name, a country). */
+    words?: string;
+}
+/** The tab ids from a text such as `html module react`: lower case, once each, in order; no usable id is the default list. */
+export declare function parseKinds(text: string | null | undefined, fallback?: readonly string[]): string[];
+/** The sizes from a text such as `160 240 320`: whole numbers from 16 up to 4096, once each, smallest first; no usable number is the default sizes. */
+export declare function parseSizes(text: string | null | undefined, fallback?: readonly number[]): number[];
+/** The size to use for a wish: the wish if it is one of the sizes, else the sizes' nearest to it, else the one nearest `DEFAULT_SIZE`. */
+export declare function nearestSize(wish: number | string | null | undefined, sizes: readonly number[]): number;
+/** The groups of a list, once each, in the order they first appear. */
+export declare function groupsOf(items: readonly PickItem[]): string[];
+/** The items that are in `group` (all of them when it is empty) and have every word of `query` in their label, id, group or words, ignoring case and accents. */
+export declare function filterItems(items: readonly PickItem[], query?: string, group?: string): PickItem[];

package/dist/embed-panel/choices.js

@@ -0,0 +1,48 @@
+// What the panel's choices are, without the element: the tabs, the sizes and the compact picker's list. Nothing here touches the DOM, so it imports on a server.
+import { EMBED_KINDS } from "./snippets.js";
+/** The sizes (pixels across) the size buttons offer by default. */
+export const DEFAULT_SIZES = [160, 240, 320, 480];
+/** The size the panel starts on when the page names none and it is one of the sizes. */
+export const DEFAULT_SIZE = 320;
+/** The tabs the panel shows when the page names none: the seven ways a page is made. */
+export const DEFAULT_KINDS = EMBED_KINDS;
+/** The address parameters the panel keeps its two choices in. */
+export const KIND_ADDRESS_KEY = "embed";
+export const SIZE_ADDRESS_KEY = "size";
+/** More than this many things to pick from and the picker shows a search box. */
+export const SEARCH_FROM = 12;
+/** The tab ids from a text such as `html module react`: lower case, once each, in order; no usable id is the default list. */
+export function parseKinds(text, fallback = DEFAULT_KINDS) {
+    const found = [...new Set((text ?? "").toLowerCase().split(/[\s,]+/).filter((id) => /^[a-z][a-z0-9-]*$/.test(id)))];
+    return found.length > 0 ? found : [...fallback];
+}
+/** The sizes from a text such as `160 240 320`: whole numbers from 16 up to 4096, once each, smallest first; no usable number is the default sizes. */
+export function parseSizes(text, fallback = DEFAULT_SIZES) {
+    const found = [...new Set((text ?? "").split(/[\s,]+/).map(Number).filter((n) => Number.isInteger(n) && n >= 16 && n <= 4096))].sort((a, b) => a - b);
+    return found.length > 0 ? found : [...fallback];
+}
+/** The size to use for a wish: the wish if it is one of the sizes, else the sizes' nearest to it, else the one nearest `DEFAULT_SIZE`. */
+export function nearestSize(wish, sizes) {
+    const want = Number(wish);
+    const aim = Number.isFinite(want) && wish !== null && wish !== undefined && String(wish).trim() !== "" ? want : DEFAULT_SIZE;
+    let best = sizes[0] ?? DEFAULT_SIZE;
+    for (const size of sizes)
+        if (Math.abs(size - aim) < Math.abs(best - aim))
+            best = size;
+    return best;
+}
+/** The groups of a list, once each, in the order they first appear. */
+export function groupsOf(items) {
+    return [...new Set(items.flatMap((item) => (item.group !== undefined && item.group !== "" ? [item.group] : [])))];
+}
+/** The items that are in `group` (all of them when it is empty) and have every word of `query` in their label, id, group or words, ignoring case and accents. */
+export function filterItems(items, query = "", group = "") {
+    const fold = (text) => text.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase();
+    const needles = fold(query).split(/\s+/).filter((word) => word !== "");
+    return items.filter((item) => {
+        if (group !== "" && item.group !== group)
+            return false;
+        const hay = fold(`${item.label} ${item.id} ${item.group ?? ""} ${item.words ?? ""}`);
+        return needles.every((word) => hay.includes(word));
+    });
+}

package/dist/embed-panel/define.d.ts

@@ -0,0 +1 @@
+export declare function defineEmbedPanel(registry?: CustomElementRegistry): boolean;

package/dist/embed-panel/define.js

@@ -0,0 +1,9 @@
+// Importing this registers <kazoku-embed-panel>, unless the tag is already taken (the first definition wins; see view-controls/define.ts for why a taken tag is left alone).
+import { EmbedPanelElement, TAG } from "./element.js";
+export function defineEmbedPanel(registry = customElements) {
+    if (registry.get(TAG) !== undefined)
+        return false;
+    registry.define(TAG, EmbedPanelElement);
+    return true;
+}
+defineEmbedPanel();

package/dist/embed-panel/element.d.ts

@@ -0,0 +1,84 @@
+import { type PickItem } from "./choices.ts";
+import { EVENT, TAG } from "./index.ts";
+import { type PanelWords } from "./words.ts";
+export { EVENT, TAG };
+/** What the page's `generate`, `preview`, `credits` and `note` functions are told. */
+export interface EmbedContext {
+    /** The tab: `html`, `module`, `react`, `vue`, `angular`, `svelte`, `iframe`, or one the page added. */
+    kind: string;
+    /** The size chosen, in pixels across. */
+    size: number;
+    /** True when the text is for the picture beside the code, not for the reader to copy: a page may use a relative address there so the picture works from where the page is. */
+    preview: boolean;
+}
+/** What the `kazoku-embedchange` event carries in `detail`. */
+export interface EmbedChangeDetail {
+    kind: string;
+    size: number;
+    /** The picker's choice (an item's `id`), or an empty text where there is no built-in picker. */
+    value: string;
+    /** The text to copy now. */
+    code: string;
+    /** `init` (once, when it comes up), `kind` (a tab), `size` (a size button), `pick` (the picker) or `set` (a property or attribute). */
+    reason: "init" | "kind" | "size" | "pick" | "set";
+}
+type Text = string | ((context: EmbedContext) => string);
+/**
+ * Attributes: `kinds` (the tabs, `html module react vue angular svelte iframe` by default; add your own such as `image`), `kind` (the tab to start on), `sizes` (`160 240 320 480`) and
+ * `size` (the start, 320), `no-size` (no size choice), `value` (the picker's choice), `open-href` (the embed page), `docs-href` (the docs), `aspect` (the picture's height over its width, 1),
+ * `no-preview` (no picture), `heading` (show the shared heading), `search` / `no-search` (force the picker's search box on or off), `pick-label` (the picker's name), `address` (keep the tab and
+ * the size in the address under `kind-key`, `embed`, and `size-key`, `size`; the starts are left off it), `lang` (`en` or `ja`), `theme` (`light` or `dark`).
+ * Slots: `lede` (a line under the heading), `picker` (your own picker in place of the built-in one), `options` (your own choices between the size and the tabs), `actions` (more buttons
+ * beside Copy: Save SVG, Download). Parts: `panel`, `title`, `picker`, `size`, `tabs`, `tab`, `preview`, `note`, `code`, `copy`, `open`, `docs`, `credits`.
+ * Custom properties: `--kazoku-preview-bg` (behind the picture, the page's surface by default), `--kazoku-preview-width` (the picture's column, 260px).
+ */
+export declare class EmbedPanelElement extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    /** The tab now: one of `kinds`. Setting one that is not there is ignored. */
+    get kind(): string;
+    set kind(kind: string);
+    /** The size now, in pixels across: one of `sizes`. Setting a number that is not one takes the nearest. */
+    get size(): number;
+    set size(size: number | string);
+    /** The tabs, in order. Setting a list (or a text such as `html react iframe`) draws them again. */
+    get kinds(): readonly string[];
+    set kinds(list: readonly string[] | string);
+    /** The sizes the buttons offer, smallest first. */
+    get sizes(): readonly number[];
+    set sizes(list: readonly number[] | string);
+    /** The picker's choice: an item's `id`. Setting one that is not in `items` is ignored. */
+    get value(): string;
+    set value(id: string);
+    /** The things the built-in picker offers. Leave it empty and give the `picker` slot for a picker of your own. */
+    get items(): readonly PickItem[];
+    set items(items: readonly PickItem[]);
+    /** How a picker button looks inside: a node (a small picture) or a text. The label by default. */
+    set renderItem(render: ((item: PickItem) => Node | string) | undefined);
+    /** The text of a tab for the choices as they are. Required: without it the code box is empty. Call `update()` after the page's own choices change. */
+    set generate(generate: ((context: EmbedContext) => string) | undefined);
+    /** The picture the code makes, as a node (or nothing). It is called when the picture's choices change; the iframe tab draws the iframe itself when this returns nothing for it. */
+    set preview(preview: ((context: EmbedContext) => Node | undefined) | undefined);
+    /** The credit line shown under the code (and read by a screen reader): a text, or a function of the choices. */
+    set credits(credits: Text);
+    /** A line above the code for the tab shown ("The embed page is for a site that cannot run script."): a text, or a function of the choices. */
+    set note(note: Text);
+    /** The names of the tabs the family has no word for: `{ image: "Image address" }`. */
+    set labels(labels: Record<string, string>);
+    /** Your own words over the language's. */
+    set words(words: Partial<PanelWords>);
+    /** Where "Open the embed page" goes. Set it again when the choices change the address. */
+    get openHref(): string;
+    set openHref(href: string);
+    /** Where "Read the docs" goes. */
+    get docsHref(): string;
+    set docsHref(href: string);
+    /** The text of the tab shown: what Copy copies. */
+    get code(): string;
+    /** Reads the page's choices again: the code, the credit, the note, the links, and the picture if its choices changed. Call it whenever the page's own choices change. It tells no one. */
+    update(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+}