@johnmorrisdotca/kazoku-ui 0.13.1 → 0.15.0

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

@@ -0,0 +1,5 @@
+export { DEFAULT_KINDS, DEFAULT_SIZE, DEFAULT_SIZES, filterItems, groupsOf, KIND_ADDRESS_KEY, nearestSize, parseKinds, parseSizes, SEARCH_FROM, SIZE_ADDRESS_KEY, type PickItem } from "./choices.ts";
+export { attrText, EMBED_KINDS, embedSnippet, type EmbedKind, type SnippetSpec } from "./snippets.ts";
+export { kindLabel, languageOf, WORDS, wordsFor, type Language, type PanelWords } from "./words.ts";
+export declare const EVENT = "kazoku-embedchange";
+export declare const TAG = "kazoku-embed-panel";

package/dist/embed-panel/index.js

@@ -0,0 +1,6 @@
+// The embed panel without the element: the seven ways a page is made and their text, the sizes, the tab and picker choices, the words. Nothing here touches the DOM, so it imports on a server.
+export { DEFAULT_KINDS, DEFAULT_SIZE, DEFAULT_SIZES, filterItems, groupsOf, KIND_ADDRESS_KEY, nearestSize, parseKinds, parseSizes, SEARCH_FROM, SIZE_ADDRESS_KEY } from "./choices.js";
+export { attrText, EMBED_KINDS, embedSnippet } from "./snippets.js";
+export { kindLabel, languageOf, WORDS, wordsFor } from "./words.js";
+export const EVENT = "kazoku-embedchange";
+export const TAG = "kazoku-embed-panel";

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

@@ -0,0 +1,94 @@
+/**
+ * The ways `embedSnippet` writes an element into a page, in the order the panel's tabs show them.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/kazoku-ui/embed-panel";
+ *
+ * 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/kazoku-ui/embed-panel";
+ *
+ * const kind: EmbedKind = EMBED_KINDS[2];
+ * console.log(kind);
+ * ```
+ */
+export type EmbedKind = (typeof EMBED_KINDS)[number];
+/**
+ * What `embedSnippet` needs to know about an element: where it comes from, what it is called and what it is given.
+ *
+ * @example
+ * ```ts
+ * import { embedSnippet, type SnippetSpec } from "@johnmorrisdotca/kazoku-ui/embed-panel";
+ *
+ * const spec: SnippetSpec = {
+ *   package: "@scope/dial",
+ *   cdn: "https://cdn.jsdelivr.net/npm/@scope/dial@1.0.0",
+ *   tag: "scope-dial",
+ *   element: "element",
+ *   entries: [],
+ *   attrs: [["value", "7"]],
+ *   name: "dial",
+ *   iframe: { src: "https://example.com/embed.html?value=7", title: "Dial", width: 320, height: 320 },
+ * };
+ * console.log(embedSnippet("html", spec));
+ * ```
+ */
+export interface SnippetSpec {
+    /** The npm name, for the `import` lines: `@scope/name`. */
+    package: string;
+    /** The package on the CDN with its version: `https://cdn.jsdelivr.net/npm/@scope/name@1.2.3`. */
+    cdn: string;
+    /** The element's tag. */
+    tag: string;
+    /** The subpath (under the package name) that defines the tag; an empty text is the package's main entry. */
+    element: string;
+    /** More subpaths to load beside it (data, looks); none is fine. */
+    entries: readonly string[];
+    /** The attributes, in the order they are written. A value of `""` is written as a bare attribute. */
+    attrs: readonly (readonly [string, string])[];
+    /** The name the React, Angular and plain module examples use: `planet` gives `Planet`, `PlanetComponent`, `app-planet` and `#planet`. */
+    name: string;
+    /** The embed page as an iframe. */
+    iframe: {
+        src: string;
+        title: string;
+        width: number;
+        height: number;
+    };
+}
+/** The attributes as they are written in a tag: `body="mars" moons`. */
+export declare function attrText(attrs: SnippetSpec["attrs"]): string;
+/**
+ * The text that puts an element in a page, for one way of making the page: a script tag from the CDN, an ES module, a React component, a Vue single-file component, an Angular
+ * standalone component, a Svelte component, or an iframe.
+ *
+ * @param kind - The way the page is made.
+ * @param spec - The element and what it is given.
+ * @returns The text to paste into the page's source.
+ *
+ * @example
+ * ```ts
+ * import { embedSnippet } from "@johnmorrisdotca/kazoku-ui/embed-panel";
+ *
+ * const spec = {
+ *   package: "@scope/dial",
+ *   cdn: "https://cdn.jsdelivr.net/npm/@scope/dial@1.0.0",
+ *   tag: "scope-dial",
+ *   element: "element",
+ *   entries: [],
+ *   attrs: [["value", "7"]] as const,
+ *   name: "dial",
+ *   iframe: { src: "https://example.com/embed.html", title: "Dial", width: 320, height: 320 },
+ * };
+ * console.log(embedSnippet("react", spec));
+ * ```
+ */
+export declare function embedSnippet(kind: EmbedKind, spec: SnippetSpec): string;

package/dist/embed-panel/snippets.js

@@ -0,0 +1,73 @@
+// The text that puts an element 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 the embed page.
+// Pure: no DOM. A package gives the tag, the entry points and the attributes of its element once and gets all seven; the panel shows them as the reader changes a choice.
+/**
+ * The ways `embedSnippet` writes an element into a page, in the order the panel's tabs show them.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/kazoku-ui/embed-panel";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
+export const EMBED_KINDS = ["html", "module", "react", "vue", "angular", "svelte", "iframe"];
+const quote = (value) => `"${value.replace(/&/g, "&").replace(/"/g, """)}"`;
+const joinPath = (...parts) => parts.filter((part) => part !== "").join("/");
+/** The attributes as they are written in a tag: `body="mars" moons`. */
+export function attrText(attrs) {
+    return attrs.map(([key, value]) => (value === "" ? key : `${key}=${quote(value)}`)).join(" ");
+}
+/**
+ * The text that puts an element in a page, for one way of making the page: a script tag from the CDN, an ES module, a React component, a Vue single-file component, an Angular
+ * standalone component, a Svelte component, or an iframe.
+ *
+ * @param kind - The way the page is made.
+ * @param spec - The element and what it is given.
+ * @returns The text to paste into the page's source.
+ *
+ * @example
+ * ```ts
+ * import { embedSnippet } from "@johnmorrisdotca/kazoku-ui/embed-panel";
+ *
+ * const spec = {
+ *   package: "@scope/dial",
+ *   cdn: "https://cdn.jsdelivr.net/npm/@scope/dial@1.0.0",
+ *   tag: "scope-dial",
+ *   element: "element",
+ *   entries: [],
+ *   attrs: [["value", "7"]] as const,
+ *   name: "dial",
+ *   iframe: { src: "https://example.com/embed.html", title: "Dial", width: 320, height: 320 },
+ * };
+ * console.log(embedSnippet("react", spec));
+ * ```
+ */
+export function embedSnippet(kind, spec) {
+    const Name = spec.name.charAt(0).toUpperCase() + spec.name.slice(1);
+    const attrs = attrText(spec.attrs);
+    const subpaths = [spec.element, ...spec.entries];
+    if (kind === "iframe") {
+        const f = spec.iframe;
+        return `<iframe\n  src=${quote(f.src)}\n  title=${quote(f.title)}\n  width="${f.width}"\n  height="${f.height}"\n  loading="lazy"\n  style="border: 0"\n></iframe>`;
+    }
+    if (kind === "html") {
+        const scripts = subpaths.map((path) => `<script type="module" src="${joinPath(spec.cdn, path)}/+esm"></script>`);
+        return `${scripts.join("\n")}\n\n<${spec.tag} ${attrs}></${spec.tag}>`;
+    }
+    const imports = subpaths.map((path) => `import "${joinPath(spec.package, path)}";`);
+    if (kind === "module") {
+        const sets = spec.attrs.map(([key, value]) => `${spec.name}.setAttribute(${JSON.stringify(key)}, ${JSON.stringify(value)});`);
+        return `${imports.join("\n")}\n\nconst ${spec.name} = document.createElement("${spec.tag}");\n${sets.join("\n")}\ndocument.querySelector("#${spec.name}").append(${spec.name});`;
+    }
+    const dynamic = subpaths.map((path) => `void import("${joinPath(spec.package, path)}");`);
+    if (kind === "react") {
+        return `import { useEffect } from "react";\n\nexport function ${Name}() {\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 <${spec.tag} ${attrs} />;\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  <${spec.tag} ${attrs}></${spec.tag}>\n</template>`;
+    }
+    if (kind === "angular") {
+        return `import { Component, CUSTOM_ELEMENTS_SCHEMA, OnInit } from "@angular/core";\n\n@Component({\n  selector: "app-${spec.name}",\n  standalone: true,\n  schemas: [CUSTOM_ELEMENTS_SCHEMA],\n  template: \`<${spec.tag} ${attrs}></${spec.tag}>\`,\n})\nexport class ${Name}Component 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<${spec.tag} ${attrs}></${spec.tag}>`;
+}

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

@@ -0,0 +1 @@
+export declare const STYLES = "\n:host {\n  --_ink: var(--kazoku-ink, #1b1b1f);\n  --_surface: var(--kazoku-surface, #ffffff);\n  --_line: var(--kazoku-line, #c9ccd3);\n  --_accent: var(--kazoku-accent, #2457d6);\n  display: inline-block;\n  box-sizing: border-box;\n  color: var(--_ink);\n  font: 600 0.9rem/1.2 system-ui, -apple-system, \"Hiragino Sans\", \"Noto Sans JP\", \"Segoe UI\", sans-serif;\n  color-scheme: light dark;\n}\n@media (prefers-color-scheme: dark) {\n  :host(:not([theme=\"light\"]):not([data-scheme=\"light\"])) {\n    --_ink: var(--kazoku-ink, #f1f2f6);\n    --_surface: var(--kazoku-surface, #1c1d22);\n    --_line: var(--kazoku-line, #4a4d58);\n    --_accent: var(--kazoku-accent, #8fb0ff);\n  }\n}\n:host([theme=\"dark\"]), :host([data-scheme=\"dark\"]:not([theme=\"light\"])) {\n  --_ink: var(--kazoku-ink, #f1f2f6);\n  --_surface: var(--kazoku-surface, #1c1d22);\n  --_line: var(--kazoku-line, #4a4d58);\n  --_accent: var(--kazoku-accent, #8fb0ff);\n  color-scheme: dark;\n}\n:host([theme=\"light\"]) { color-scheme: light; }\n[hidden] { display: none !important; }\n.vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\n.group { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 4px; }\nbutton { -webkit-appearance: none; appearance: none; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-width: 48px; min-height: 48px; margin: 0; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; cursor: pointer; white-space: nowrap; }\nbutton:hover:not(:disabled) { border-color: var(--_ink); }\nbutton:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\nbutton[aria-pressed=\"true\"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }\nbutton:disabled { opacity: 0.4; cursor: default; }\nsvg { width: 18px; height: 18px; fill: currentColor; flex: none; }\n\n:host { display: block; box-sizing: border-box; width: 100%; justify-self: stretch; container-type: inline-size; --_preview-bg: var(--kazoku-preview-bg, var(--_surface)); --_preview-w: var(--kazoku-preview-width, 260px); }\n:host([hidden]) { display: none; }\n.panel { display: grid; gap: 12px; min-width: 0; }\n.title { margin: 0; font-size: 1.25rem; font-weight: 700; line-height: 1.25; }\n.row { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 12px; }\n.lbl { font-weight: 600; }\n.pick { display: grid; gap: 8px; min-width: 0; }\n.builtin { display: grid; gap: 8px; min-width: 0; }\n.chips { display: flex; flex-wrap: wrap; gap: 4px; }\n.search { -webkit-appearance: none; appearance: none; box-sizing: border-box; width: 100%; max-width: 320px; min-height: 48px; margin: 0; padding: 0 16px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; }\n.search:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\n.search::placeholder { color: var(--_ink); opacity: 0.6; }\n.items { display: flex; flex-wrap: wrap; gap: 4px; max-height: 164px; overflow: auto; padding: 2px; }\n.items button { white-space: normal; text-align: center; }\n.none { margin: 0; font-weight: 400; opacity: 0.75; }\n.tabs { display: flex; gap: 4px; overflow-x: auto; padding: 2px; margin: -2px; }\n.tabs button { flex: 0 0 auto; }\n.tabs button[aria-selected=\"true\"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }\n.grid { display: grid; grid-template-columns: minmax(0, var(--_preview-w)) minmax(0, 1fr); gap: 16px; align-items: start; min-width: 0; }\n:host([no-preview]) .grid { grid-template-columns: minmax(0, 1fr); }\n@container (max-width: 640px) { .grid { grid-template-columns: minmax(0, 1fr); } }\n.preview { box-sizing: border-box; display: grid; place-items: center; min-width: 0; min-height: 160px; padding: 8px; overflow: hidden; border: 1px solid var(--_line); border-radius: 12px; background: var(--_preview-bg); }\n.frame { position: relative; overflow: hidden; max-width: 100%; }\n.fit { display: grid; place-items: center; transform-origin: 0 0; }\n.fit > * { max-width: none; }\n.fit iframe { border: 0; display: block; }\n.codecol { display: grid; gap: 10px; min-width: 0; }\n.note { margin: 0; font-weight: 400; font-size: 0.85rem; }\n.codebox { box-sizing: border-box; margin: 0; padding: 12px; overflow: auto; max-height: 340px; border: 1px solid var(--_line); border-radius: 12px; background: var(--_surface); color: var(--_ink); font: 400 0.8rem/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; tab-size: 2; white-space: pre; }\n.codebox:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\n.actions { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }\na.btn { box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-height: 48px; min-width: 48px; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; text-decoration: none; white-space: nowrap; }\na.btn:hover { border-color: var(--_ink); }\na.btn:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\nbutton.primary { background: var(--_accent); border-color: var(--_accent); color: var(--_surface); }\nbutton.primary:hover:not(:disabled) { border-color: var(--_ink); }\n.status { font-weight: 400; font-size: 0.85rem; min-height: 1.2em; }\n.credits { margin: 0; font-weight: 400; font-size: 0.85rem; opacity: 0.85; }\n";

package/dist/embed-panel/styles.js

@@ -0,0 +1,43 @@
+import { BASE_STYLES } from "../shared/base.js";
+// The panel: a picker, the size buttons, the tabs, then the picture beside the code. It stacks when its own box is narrow (a container query on the host, so it
+// follows the box it sits in, not the window). The picture sits in a box it always fits: the element inside is scaled down to the box, never cut off.
+export const STYLES = `${BASE_STYLES}
+:host { display: block; box-sizing: border-box; width: 100%; justify-self: stretch; container-type: inline-size; --_preview-bg: var(--kazoku-preview-bg, var(--_surface)); --_preview-w: var(--kazoku-preview-width, 260px); }
+:host([hidden]) { display: none; }
+.panel { display: grid; gap: 12px; min-width: 0; }
+.title { margin: 0; font-size: 1.25rem; font-weight: 700; line-height: 1.25; }
+.row { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 12px; }
+.lbl { font-weight: 600; }
+.pick { display: grid; gap: 8px; min-width: 0; }
+.builtin { display: grid; gap: 8px; min-width: 0; }
+.chips { display: flex; flex-wrap: wrap; gap: 4px; }
+.search { -webkit-appearance: none; appearance: none; box-sizing: border-box; width: 100%; max-width: 320px; min-height: 48px; margin: 0; padding: 0 16px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; }
+.search:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }
+.search::placeholder { color: var(--_ink); opacity: 0.6; }
+.items { display: flex; flex-wrap: wrap; gap: 4px; max-height: 164px; overflow: auto; padding: 2px; }
+.items button { white-space: normal; text-align: center; }
+.none { margin: 0; font-weight: 400; opacity: 0.75; }
+.tabs { display: flex; gap: 4px; overflow-x: auto; padding: 2px; margin: -2px; }
+.tabs button { flex: 0 0 auto; }
+.tabs button[aria-selected="true"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }
+.grid { display: grid; grid-template-columns: minmax(0, var(--_preview-w)) minmax(0, 1fr); gap: 16px; align-items: start; min-width: 0; }
+:host([no-preview]) .grid { grid-template-columns: minmax(0, 1fr); }
+@container (max-width: 640px) { .grid { grid-template-columns: minmax(0, 1fr); } }
+.preview { box-sizing: border-box; display: grid; place-items: center; min-width: 0; min-height: 160px; padding: 8px; overflow: hidden; border: 1px solid var(--_line); border-radius: 12px; background: var(--_preview-bg); }
+.frame { position: relative; overflow: hidden; max-width: 100%; }
+.fit { display: grid; place-items: center; transform-origin: 0 0; }
+.fit > * { max-width: none; }
+.fit iframe { border: 0; display: block; }
+.codecol { display: grid; gap: 10px; min-width: 0; }
+.note { margin: 0; font-weight: 400; font-size: 0.85rem; }
+.codebox { box-sizing: border-box; margin: 0; padding: 12px; overflow: auto; max-height: 340px; border: 1px solid var(--_line); border-radius: 12px; background: var(--_surface); color: var(--_ink); font: 400 0.8rem/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; tab-size: 2; white-space: pre; }
+.codebox:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }
+.actions { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
+a.btn { box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-height: 48px; min-width: 48px; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; text-decoration: none; white-space: nowrap; }
+a.btn:hover { border-color: var(--_ink); }
+a.btn:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }
+button.primary { background: var(--_accent); border-color: var(--_accent); color: var(--_surface); }
+button.primary:hover:not(:disabled) { border-color: var(--_ink); }
+.status { font-weight: 400; font-size: 0.85rem; min-height: 1.2em; }
+.credits { margin: 0; font-weight: 400; font-size: 0.85rem; opacity: 0.85; }
+`;

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

@@ -0,0 +1,43 @@
+export interface PanelWords {
+    /** The panel's heading, when it shows one (`heading` attribute). */
+    title: string;
+    /** The name of the group of size buttons. */
+    size: string;
+    /** The name of the row of tabs. */
+    kinds: string;
+    /** The name of the picker. */
+    pick: string;
+    search: string;
+    all: string;
+    /** Said under the picker when the search finds nothing. */
+    none: string;
+    /** The name of the picture beside the code. */
+    preview: string;
+    /** The name of the code box. */
+    code: string;
+    copy: string;
+    copied: string;
+    copyFail: string;
+    open: string;
+    docs: string;
+    credits: string;
+    /** Tab names (`kind_<id>`). */
+    kind_html: string;
+    kind_module: string;
+    kind_react: string;
+    kind_vue: string;
+    kind_angular: string;
+    kind_svelte: string;
+    kind_iframe: string;
+    kind_image: string;
+    kind_element: string;
+    kind_url: string;
+    kind_svg: string;
+}
+export type Language = "en" | "ja";
+export declare const WORDS: Record<Language, PanelWords>;
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export declare const languageOf: (lang: string | null | undefined) => Language;
+export declare const wordsFor: (language: Language, overrides?: Partial<PanelWords>) => PanelWords;
+/** What a tab says: the family's word for the id, else the page's own `labels`, else the id itself. */
+export declare function kindLabel(id: string, language: Language, labels?: Readonly<Record<string, string>>, overrides?: Partial<PanelWords>): string;

package/dist/embed-panel/words.js

@@ -0,0 +1,69 @@
+export const WORDS = {
+    en: {
+        title: "Put it in your page",
+        size: "Size",
+        kinds: "How your page is made",
+        pick: "What to put in",
+        search: "Search",
+        all: "All",
+        none: "Nothing matches",
+        preview: "Preview",
+        code: "Code",
+        copy: "Copy code",
+        copied: "Copied",
+        copyFail: "Select the code and copy it by hand.",
+        open: "Open the embed page",
+        docs: "Read the docs",
+        credits: "Credit",
+        kind_html: "HTML",
+        kind_module: "ES module",
+        kind_react: "React",
+        kind_vue: "Vue",
+        kind_angular: "Angular",
+        kind_svelte: "Svelte",
+        kind_iframe: "iframe",
+        kind_image: "Image",
+        kind_element: "Custom element",
+        kind_url: "iframe URL",
+        kind_svg: "SVG",
+    },
+    ja: {
+        title: "自分のページに入れる",
+        size: "大きさ",
+        kinds: "ページの作り方",
+        pick: "入れるもの",
+        search: "さがす",
+        all: "すべて",
+        none: "見つかりません",
+        preview: "プレビュー",
+        code: "コード",
+        copy: "コードをコピー",
+        copied: "コピーしました",
+        copyFail: "コードを選んで、手でコピーしてください。",
+        open: "埋め込みページを開く",
+        docs: "ドキュメントを読む",
+        credits: "クレジット",
+        kind_html: "HTML",
+        kind_module: "ESモジュール",
+        kind_react: "React",
+        kind_vue: "Vue",
+        kind_angular: "Angular",
+        kind_svelte: "Svelte",
+        kind_iframe: "iframe",
+        kind_image: "画像",
+        kind_element: "カスタム要素",
+        kind_url: "iframe URL",
+        kind_svg: "SVG",
+    },
+};
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export const languageOf = (lang) => (/^ja\b/i.test(lang ?? "") ? "ja" : "en");
+export const wordsFor = (language, overrides = {}) => ({ ...WORDS[language], ...overrides });
+/** What a tab says: the family's word for the id, else the page's own `labels`, else the id itself. */
+export function kindLabel(id, language, labels = {}, overrides = {}) {
+    const mine = labels[id];
+    if (mine !== undefined && mine !== "")
+        return mine;
+    const words = wordsFor(language, overrides);
+    return words[`kind_${id}`] ?? id;
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 /** The subpaths of the parts, in the order they were added. */
-export declare const PARTS: readonly ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "renderer", "testing"];
+export declare const PARTS: readonly ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "speed-buttons", "embed-panel", "renderer", "testing"];
 export type Part = (typeof PARTS)[number];

package/dist/index.js

@@ -1,3 +1,3 @@
 // Kazoku UI 家族: the family's shared interface parts, each its own subpath so a page loads only what it uses.
 /** The subpaths of the parts, in the order they were added. */
-export const PARTS = ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "renderer", "testing"];
+export const PARTS = ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "speed-buttons", "embed-panel", "renderer", "testing"];

package/dist/speed-buttons/define.d.ts

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

package/dist/speed-buttons/define.js

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

package/dist/speed-buttons/element.d.ts

@@ -0,0 +1,34 @@
+import { EVENT, TAG } from "./index.ts";
+import { type SpeedWords } from "./words.ts";
+export { EVENT, TAG };
+/** What the `kazoku-speedchange` event carries in `detail`. */
+export interface SpeedChangeDetail {
+    /** The speed now: one of `steps`. */
+    value: number;
+    steps: readonly number[];
+    /** `init` (once, when it comes up), `user` (a button or `step()`) or `set` (the `value` property or attribute). */
+    reason: "init" | "user" | "set";
+}
+/**
+ * Attributes: `steps` (the speeds, `0.5 1 2` by default; any numbers, `1 10 100`, `0 1 3600 86400 -3600`), `value` (the one that is on; the start, and it follows the reader's choice),
+ * `unit` (the word after each number, `×` by default), `label` (the group's name, shown before the buttons and read by a screen reader; "Speed" or 速さ by default), `no-label`
+ * (hide the name from the eye), `address` (keep the choice in the address under `address-key`, `speed` by default; the start is left off it), `lang` (`en` or `ja`), `theme` (`light` or `dark`).
+ */
+export declare class SpeedButtonsElement extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    /** The speed now. Setting it to a speed that is not a step takes the nearest step. */
+    get value(): number;
+    set value(next: number | string);
+    /** The speeds the buttons stand for. Setting a list (or a text such as `1 10 100`) draws them again, keeping the nearest to the speed now. */
+    get steps(): readonly number[];
+    set steps(list: readonly number[] | string);
+    /** Your own label over the language's, for example `{ group: "Time" }`. */
+    set words(words: Partial<SpeedWords>);
+    /** One press of a single button that cycles: the next speed (`direction` 1) or the one before (-1), going round at the ends. */
+    step(direction?: 1 | -1): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+}

package/dist/speed-buttons/element.js

@@ -0,0 +1,178 @@
+// <kazoku-speed-buttons>: one button for each speed (0.5×, 1×, 2× by default), no menu. It is the one speed control of the family: the view controls use it for Auto-turn,
+// and a solar system, a replay bar or a race takes it with the steps it needs. The choice is the `value` (an attribute, a property and, if asked, the address) and the
+// page hears every change as a `kazoku-speedchange` event. It moves nothing itself: the page applies the number.
+import { applyParams, createAddressWriter, readParam } from "../address-state/address.js";
+import { adoptStyles } from "../shared/adopt.js";
+import { watchScheme } from "../shared/scheme.js";
+import { EVENT, TAG } from "./index.js";
+import { DEFAULT_STEPS, DEFAULT_UNIT, nearestStep, parseSpeed, parseSteps, SPEED_ADDRESS_KEY, speedText, startStep, stepFrom } from "./steps.js";
+import { STYLES } from "./styles.js";
+import { languageOf, wordsFor } from "./words.js";
+export { EVENT, TAG };
+/**
+ * Attributes: `steps` (the speeds, `0.5 1 2` by default; any numbers, `1 10 100`, `0 1 3600 86400 -3600`), `value` (the one that is on; the start, and it follows the reader's choice),
+ * `unit` (the word after each number, `×` by default), `label` (the group's name, shown before the buttons and read by a screen reader; "Speed" or 速さ by default), `no-label`
+ * (hide the name from the eye), `address` (keep the choice in the address under `address-key`, `speed` by default; the start is left off it), `lang` (`en` or `ja`), `theme` (`light` or `dark`).
+ */
+export class SpeedButtonsElement extends HTMLElement {
+    static observedAttributes = ["steps", "value", "unit", "label", "lang"];
+    #root;
+    #steps = [...DEFAULT_STEPS];
+    #value = 1;
+    #start = 1;
+    #ready = false;
+    #styled = false;
+    #words = {};
+    #writer = createAddressWriter({ delay: 0 });
+    #stop;
+    #reflecting = false;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: "open" });
+    }
+    /** The speed now. Setting it to a speed that is not a step takes the nearest step. */
+    get value() {
+        return this.#value;
+    }
+    set value(next) {
+        const value = typeof next === "number" ? next : Number(next);
+        if (Number.isFinite(value))
+            this.#choose(nearestStep(value, this.#steps) ?? this.#value, "set");
+    }
+    /** The speeds the buttons stand for. Setting a list (or a text such as `1 10 100`) draws them again, keeping the nearest to the speed now. */
+    get steps() {
+        return this.#steps;
+    }
+    set steps(list) {
+        this.#aim(typeof list === "string" ? parseSteps(list) : parseSteps(list.join(" ")));
+    }
+    /** Your own label over the language's, for example `{ group: "Time" }`. */
+    set words(words) {
+        this.#words = words;
+        this.#render();
+    }
+    /** One press of a single button that cycles: the next speed (`direction` 1) or the one before (-1), going round at the ends. */
+    step(direction = 1) {
+        this.#choose(stepFrom(this.#value, this.#steps, direction), "user");
+    }
+    connectedCallback() {
+        if (!this.#styled) {
+            // Inside another part's shadow root (the view controls) it carries no nonce of its own: the part it sits in has the page's.
+            const outer = this.getRootNode();
+            adoptStyles(this.#root, STYLES, this.nonce || (outer instanceof ShadowRoot ? outer.host.nonce : "") || "");
+            this.#styled = true;
+        }
+        this.#stop = watchScheme(this);
+        this.#steps = parseSteps(this.getAttribute("steps"));
+        this.#start = parseSpeed(this.getAttribute("value"), this.#steps) ?? startStep(this.#steps);
+        const kept = this.hasAttribute("address") ? parseSpeed(readParam(this.#key(), globalThis.location?.search ?? ""), this.#steps) : undefined;
+        this.#value = kept ?? this.#start;
+        this.#render();
+        this.#ready = true;
+        // Said once the page has had its turn to listen; `value` can be read at any time.
+        queueMicrotask(() => {
+            if (this.isConnected)
+                this.#dispatch("init");
+        });
+    }
+    disconnectedCallback() {
+        this.#stop?.();
+        this.#stop = undefined;
+        this.#writer.cancel();
+        this.#ready = false;
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (!this.#ready || this.#reflecting)
+            return;
+        if (name === "steps")
+            this.#aim(parseSteps(value));
+        else if (name === "value") {
+            const next = parseSpeed(value, this.#steps);
+            if (next !== undefined)
+                this.#choose(next, "set");
+        }
+        else
+            this.#render();
+    }
+    #key() {
+        return this.getAttribute("address-key") || SPEED_ADDRESS_KEY;
+    }
+    #aim(steps) {
+        this.#steps = steps;
+        this.#start = nearestStep(this.#start, steps) ?? startStep(steps);
+        const kept = nearestStep(this.#value, steps) ?? this.#start;
+        if (kept !== this.#value)
+            this.#value = kept;
+        this.#render();
+        if (kept !== this.#value)
+            this.#dispatch("set");
+    }
+    #choose(next, reason) {
+        if (next === this.#value)
+            return;
+        this.#value = next;
+        this.#render();
+        this.#reflect();
+        if (this.hasAttribute("address")) {
+            const key = this.#key();
+            this.#writer.write((search) => applyParams(search, { [key]: next }, { [key]: String(this.#start) }));
+        }
+        this.#dispatch(reason);
+    }
+    /** The `value` attribute follows the reader's choice, so the page and a framework that watches attributes see it. */
+    #reflect() {
+        if (this.getAttribute("value") === String(this.#value))
+            return;
+        this.#reflecting = true;
+        this.setAttribute("value", String(this.#value));
+        this.#reflecting = false;
+    }
+    #render() {
+        const language = languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
+        const group = this.getAttribute("label") || wordsFor(language, this.#words).group;
+        const unit = this.getAttribute("unit") ?? DEFAULT_UNIT;
+        const doc = this.ownerDocument;
+        let box = this.#root.querySelector(".group");
+        if (box === null) {
+            const label = doc.createElement("span");
+            label.className = "lbl";
+            label.setAttribute("part", "label");
+            label.setAttribute("aria-hidden", "true");
+            box = doc.createElement("div");
+            box.className = "group";
+            box.setAttribute("part", "group");
+            box.setAttribute("role", "group");
+            this.#root.append(label, box);
+            box.addEventListener("click", (event) => {
+                const button = event.target.closest("button[data-v]");
+                if (button !== null)
+                    this.#choose(Number(button.dataset["v"]), "user");
+            });
+        }
+        const label = this.#root.querySelector(".lbl");
+        if (label !== null && label.textContent !== group)
+            label.textContent = group;
+        box.setAttribute("aria-label", group);
+        const stale = [...box.querySelectorAll("button")];
+        const same = stale.length === this.#steps.length && stale.every((button, i) => button.dataset["v"] === String(this.#steps[i]));
+        if (!same) {
+            box.replaceChildren(...this.#steps.map((step) => {
+                const button = doc.createElement("button");
+                button.type = "button";
+                button.dataset["v"] = String(step);
+                button.setAttribute("part", "button");
+                return button;
+            }));
+        }
+        for (const button of box.querySelectorAll("button")) {
+            const step = Number(button.dataset["v"]);
+            const text = speedText(step, unit);
+            if (button.textContent !== text)
+                button.textContent = text;
+            button.setAttribute("aria-pressed", String(step === this.#value));
+        }
+    }
+    #dispatch(reason) {
+        this.dispatchEvent(new CustomEvent(EVENT, { detail: { value: this.#value, steps: this.#steps, reason }, bubbles: true, composed: true }));
+    }
+}

package/dist/speed-buttons/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_STEPS, DEFAULT_UNIT, nearestStep, parseSpeed, parseSteps, SPEED_ADDRESS_KEY, speedText, startStep, stepFrom } from "./steps.ts";
+export { languageOf, WORDS, wordsFor, type Language, type SpeedWords } from "./words.ts";
+export declare const EVENT = "kazoku-speedchange";
+export declare const TAG = "kazoku-speed-buttons";

package/dist/speed-buttons/index.js

@@ -0,0 +1,5 @@
+// The speed buttons without the element: the steps, how a speed reads and how one is chosen. Nothing here touches the DOM, so it imports on a server.
+export { DEFAULT_STEPS, DEFAULT_UNIT, nearestStep, parseSpeed, parseSteps, SPEED_ADDRESS_KEY, speedText, startStep, stepFrom } from "./steps.js";
+export { languageOf, WORDS, wordsFor } from "./words.js";
+export const EVENT = "kazoku-speedchange";
+export const TAG = "kazoku-speed-buttons";

package/dist/speed-buttons/steps.d.ts

@@ -0,0 +1,18 @@
+/** The steps when a page names none: half speed, normal and double. */
+export declare const DEFAULT_STEPS: readonly number[];
+/** The word on each step's button after its number, when the page names none. */
+export declare const DEFAULT_UNIT = "\u00D7";
+/** The address key the buttons keep their choice under, unless `address-key` names another. */
+export declare const SPEED_ADDRESS_KEY = "speed";
+/** The steps in a list such as `0.5 1 2` or `1, 10, 100`: finite numbers in the order given, each once. `fallback` when the list holds none. A step may be 0 (Paused) or negative (Back). */
+export declare function parseSteps(text: string | null | undefined, fallback?: readonly number[]): number[];
+/** The number as a button shows it: `0.5×`, `1×`, `100×`, `−1×` (a real minus sign). At most four significant figures, so 0.333333 reads `0.333×`. */
+export declare function speedText(value: number, unit?: string): string;
+/** The step nearest `value`: by ratio where both are above zero (so 2.5 is nearer 2 than 4), else by plain distance. `undefined` when there are no steps. */
+export declare function nearestStep(value: number, steps: readonly number[]): number | undefined;
+/** The step the buttons start on: 1 where the steps have it (normal speed), else the first. */
+export declare function startStep(steps: readonly number[]): number;
+/** The step after (`direction` 1) or before (-1) `value`, going round at the ends: one press of a single button that cycles through the speeds. */
+export declare function stepFrom(value: number, steps: readonly number[], direction?: 1 | -1): number;
+/** What an address or attribute says: a number that is (or is nearest to) one of the steps. `undefined` when it is not a number at all. The words `slow`, `medium` and `fast` of the first view controls mean 0.5, 1 and 2. */
+export declare function parseSpeed(text: string | null | undefined, steps: readonly number[]): number | undefined;