@johnmorrisdotca/kazoku-ui 0.3.0 → 0.7.3

package/dist/language-picker/element.js

@@ -0,0 +1,194 @@
+// <kazoku-language-picker>: a button for each language the page gives, each in its own name. It writes the choice as `lang` on a target (the page's <html> by default),
+// keeps it in the address and, if asked, in localStorage, and tells the page with a `kazoku-languagechange` event. It translates nothing: the page reads the event and says its words.
+import { createAddressState } from "../address-state/address.js";
+import { adoptStyles } from "../shared/adopt.js";
+import { watchScheme } from "../shared/scheme.js";
+import { localStore, remember } from "../shared/store.js";
+import { resolveTarget } from "../shared/target.js";
+import { EVENT, TAG } from "./index.js";
+import { applyLanguage, LANGUAGE_ADDRESS_KEY, LANGUAGE_STORAGE_KEY, languageName, matchLanguage, parseLanguages, startingLanguage } from "./languages.js";
+import { STYLES } from "./styles.js";
+import { languageOf, wordsFor } from "./words.js";
+export { EVENT, TAG };
+/**
+ * Attributes: `languages` (the codes, `en ja` by default), `value` (the language to start in), `target` (a CSS selector for the element that gets `lang`; the page's <html>
+ * by default), `address` (keep the choice in `?lang=`, or the key `address-key` names), `storage` (also remember it in localStorage under that key; a bare `storage` uses
+ * `kazoku-lang`), `theme` (`light` or `dark`: its own look). The start is read, in this order, from the address, the store, `value`, the reader's languages
+ * (`navigator.languages`), the target's own `lang`, then the first code.
+ */
+export class LanguagePickerElement extends HTMLElement {
+    static observedAttributes = ["languages", "value", "target"];
+    #root;
+    #list = [];
+    #lang = "";
+    #target;
+    #names = {};
+    #words = {};
+    #ready = false;
+    #styled = false;
+    #address = createAddressState({ delay: 0 });
+    #stop = [];
+    #watching;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: "open" });
+    }
+    /** The language now chosen. Setting it applies it (event reason `set`); a code that is not in `languages` is ignored. */
+    get value() {
+        return this.#lang;
+    }
+    set value(code) {
+        const match = matchLanguage(code, this.#list);
+        if (match !== undefined)
+            this.#choose(match, "set");
+    }
+    /** The codes the picker offers. */
+    get languages() {
+        return this.#list;
+    }
+    get target() {
+        return this.#target;
+    }
+    set target(element) {
+        this.#aim(element);
+    }
+    /** Your own names over the family's, for example `{ fr: "Français (Canada)" }`. */
+    set names(names) {
+        this.#names = names;
+        this.#render();
+    }
+    /** Your own words over the language's, for example `{ group: "Choose a language" }`. */
+    set words(words) {
+        this.#words = words;
+        this.#render();
+    }
+    connectedCallback() {
+        if (!this.#styled) {
+            adoptStyles(this.#root, STYLES, this.nonce);
+            this.#styled = true;
+        }
+        this.#stop.push(watchScheme(this));
+        this.#list = parseLanguages(this.getAttribute("languages"));
+        this.#aim(resolveTarget(this, this.getAttribute("target")));
+        this.#lang = startingLanguage({
+            list: this.#list,
+            ...(this.hasAttribute("address") ? { search: globalThis.location?.search ?? "", addressKey: this.#addressKey() } : {}),
+            ...(this.hasAttribute("storage") ? { storage: localStore(), storageKey: this.#storageKey() } : {}),
+            value: this.getAttribute("value"),
+            preferred: globalThis.navigator?.languages ?? [],
+            current: this.#target?.getAttribute("lang") ?? null,
+        });
+        if (this.#target !== undefined)
+            applyLanguage(this.#target, this.#lang);
+        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(undefined, "init");
+        });
+    }
+    disconnectedCallback() {
+        for (const stop of this.#stop.splice(0))
+            stop();
+        this.#watching?.disconnect();
+        this.#watching = undefined;
+        this.#ready = false;
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (!this.#ready)
+            return;
+        if (name === "languages") {
+            this.#list = parseLanguages(value);
+            const kept = matchLanguage(this.#lang, this.#list);
+            if (kept === undefined)
+                this.#choose(this.#list[0], "set");
+            else
+                this.#render();
+        }
+        else if (name === "value") {
+            const match = matchLanguage(value, this.#list);
+            if (match !== undefined)
+                this.#choose(match, "set");
+        }
+        else if (name === "target") {
+            this.#aim(resolveTarget(this, value));
+            if (this.#target !== undefined)
+                applyLanguage(this.#target, this.#lang);
+        }
+    }
+    #addressKey() {
+        return this.getAttribute("address-key") || LANGUAGE_ADDRESS_KEY;
+    }
+    #storageKey() {
+        return this.getAttribute("storage") || LANGUAGE_STORAGE_KEY;
+    }
+    #aim(element) {
+        if (element === this.#target)
+            return;
+        this.#watching?.disconnect();
+        this.#target = element;
+        if (element === undefined)
+            return;
+        // Something else writing the target's lang (a page's own script, another picker) moves this one with it, when it is one of ours.
+        this.#watching = new MutationObserver(() => {
+            const held = matchLanguage(element.getAttribute("lang"), this.#list);
+            if (held !== undefined && held !== this.#lang) {
+                const previous = this.#lang;
+                this.#lang = held;
+                this.#render();
+                this.#dispatch(previous, "external");
+            }
+        });
+        this.#watching.observe(element, { attributes: true, attributeFilter: ["lang"] });
+    }
+    #choose(code, reason) {
+        const previous = this.#lang;
+        if (this.#target !== undefined)
+            applyLanguage(this.#target, code);
+        this.#lang = code;
+        this.#render();
+        if (this.hasAttribute("address"))
+            this.#address.set(this.#addressKey(), code);
+        if (this.hasAttribute("storage"))
+            remember(this.#storageKey(), code);
+        if (code !== previous || reason === "user")
+            this.#dispatch(previous, reason);
+    }
+    #render() {
+        const words = wordsFor(languageOf(this.#lang), this.#words);
+        let group = this.#root.querySelector(".group");
+        if (group === null) {
+            group = this.ownerDocument.createElement("div");
+            group.className = "group";
+            group.setAttribute("part", "group");
+            group.setAttribute("role", "group");
+            this.#root.append(group);
+        }
+        group.setAttribute("aria-label", words.group);
+        group.setAttribute("lang", languageOf(this.#lang));
+        const have = [...group.querySelectorAll("button")];
+        if (have.length !== this.#list.length || have.some((button, index) => button.dataset.v !== this.#list[index])) {
+            group.replaceChildren(...this.#list.map((code) => {
+                const button = this.ownerDocument.createElement("button");
+                button.type = "button";
+                button.dataset.v = code;
+                button.lang = code;
+                button.setAttribute("part", "button");
+                button.addEventListener("click", () => this.#choose(code, "user"));
+                return button;
+            }));
+        }
+        for (const button of group.querySelectorAll("button")) {
+            const code = button.dataset.v;
+            button.textContent = languageName(code, this.#names);
+            button.setAttribute("aria-pressed", String(code === this.#lang));
+        }
+    }
+    #dispatch(previous, reason) {
+        if (this.#target === undefined)
+            return;
+        const detail = { lang: this.#lang, previous, reason, target: this.#target };
+        this.dispatchEvent(new CustomEvent(EVENT, { detail, bubbles: true, composed: true }));
+    }
+}

package/dist/language-picker/index.d.ts

@@ -0,0 +1,4 @@
+export { applyLanguage, DEFAULT_LANGUAGES, LANGUAGE_ADDRESS_KEY, LANGUAGE_ATTRIBUTE, LANGUAGE_STORAGE_KEY, languageName, matchLanguage, normaliseCode, OWN_NAMES, parseLanguages, startingLanguage, type StartingLanguage } from "./languages.ts";
+export { languageOf, WORDS, wordsFor, type Language, type PickerWords } from "./words.ts";
+export declare const EVENT = "kazoku-languagechange";
+export declare const TAG = "kazoku-language-picker";

package/dist/language-picker/index.js

@@ -0,0 +1,5 @@
+// The language picker without the element: the codes, each language's own name, which one to start in and how one is applied. Nothing here touches the DOM until `applyLanguage` is called with an element.
+export { applyLanguage, DEFAULT_LANGUAGES, LANGUAGE_ADDRESS_KEY, LANGUAGE_ATTRIBUTE, LANGUAGE_STORAGE_KEY, languageName, matchLanguage, normaliseCode, OWN_NAMES, parseLanguages, startingLanguage } from "./languages.js";
+export { languageOf, WORDS, wordsFor } from "./words.js";
+export const EVENT = "kazoku-languagechange";
+export const TAG = "kazoku-language-picker";

package/dist/language-picker/languages.d.ts

@@ -0,0 +1,38 @@
+/** The codes when a page gives none. */
+export declare const DEFAULT_LANGUAGES: readonly string[];
+/** The attribute the choice is written to on the target. */
+export declare const LANGUAGE_ATTRIBUTE = "lang";
+/** The address parameter, with `address`. */
+export declare const LANGUAGE_ADDRESS_KEY = "lang";
+/** The localStorage key, with a bare `storage`. */
+export declare const LANGUAGE_STORAGE_KEY = "kazoku-lang";
+/** Each language's own name, for the codes the family uses. Any other code gets its name from `Intl.DisplayNames`, else the code itself. */
+export declare const OWN_NAMES: Readonly<Record<string, string>>;
+/** A code as the page may write it ("EN", "ja_JP", " fr ") in the form this part compares: lower case, dashes. `undefined` if it is not a language code. */
+export declare function normaliseCode(value: string | null | undefined): string | undefined;
+/** The codes of `languages="en ja fr"`: valid ones, once each, in the order given. Nothing usable gives `en` and `ja`. */
+export declare function parseLanguages(value: string | null | undefined): string[];
+/** The entry of `list` that a language tag means: the tag itself, else its main language ("ja-JP" is "ja"). `undefined` if the list has neither. */
+export declare function matchLanguage(tag: string | null | undefined, list: readonly string[]): string | undefined;
+/** A language's own name: yours (`names`), the family's table, `Intl.DisplayNames` in that language, else the code. */
+export declare function languageName(code: string, names?: Readonly<Record<string, string>>): string;
+/** What may say which language to start in, strongest first. Each is a language tag or `undefined`. */
+export interface StartingLanguage {
+    list: readonly string[];
+    /** The address' search string such as `?lang=ja`, read with `addressKey`. */
+    search?: string;
+    addressKey?: string;
+    /** A localStorage-like object and the key in it. A store that throws is the same as an empty one. */
+    storage?: Pick<Storage, "getItem">;
+    storageKey?: string;
+    /** The page's own start (the `value` attribute). */
+    value?: string | null;
+    /** The reader's languages, most wanted first (`navigator.languages`). */
+    preferred?: readonly string[];
+    /** What the target holds now. */
+    current?: string | null;
+}
+/** The language to start in: the address, the store, `value`, the reader's languages, what the page holds now, then the first of the list. */
+export declare function startingLanguage(from: StartingLanguage): string;
+/** Writes the choice as `lang` on the target. */
+export declare function applyLanguage(target: Element, code: string): void;

package/dist/language-picker/languages.js

@@ -0,0 +1,100 @@
+// The language choice without the element: the list of codes a page gives, each language's own name, which one to start in, and how one is applied.
+/** The codes when a page gives none. */
+export const DEFAULT_LANGUAGES = ["en", "ja"];
+/** The attribute the choice is written to on the target. */
+export const LANGUAGE_ATTRIBUTE = "lang";
+/** The address parameter, with `address`. */
+export const LANGUAGE_ADDRESS_KEY = "lang";
+/** The localStorage key, with a bare `storage`. */
+export const LANGUAGE_STORAGE_KEY = "kazoku-lang";
+/** Each language's own name, for the codes the family uses. Any other code gets its name from `Intl.DisplayNames`, else the code itself. */
+export const OWN_NAMES = {
+    en: "English",
+    ja: "日本語",
+    fr: "Français",
+    de: "Deutsch",
+    es: "Español",
+    pt: "Português",
+    it: "Italiano",
+    nl: "Nederlands",
+    sv: "Svenska",
+    pl: "Polski",
+    ru: "Русский",
+    ko: "한국어",
+    zh: "中文",
+    "zh-hans": "简体中文",
+    "zh-hant": "繁體中文",
+};
+const CODE = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/;
+/** A code as the page may write it ("EN", "ja_JP", " fr ") in the form this part compares: lower case, dashes. `undefined` if it is not a language code. */
+export function normaliseCode(value) {
+    const code = (value ?? "").trim().toLowerCase().replace(/_/g, "-");
+    return CODE.test(code) ? code : undefined;
+}
+/** The codes of `languages="en ja fr"`: valid ones, once each, in the order given. Nothing usable gives `en` and `ja`. */
+export function parseLanguages(value) {
+    const codes = [];
+    for (const word of (value ?? "").split(/[\s,]+/)) {
+        const code = normaliseCode(word);
+        if (code !== undefined && !codes.includes(code))
+            codes.push(code);
+    }
+    return codes.length > 0 ? codes : [...DEFAULT_LANGUAGES];
+}
+/** The entry of `list` that a language tag means: the tag itself, else its main language ("ja-JP" is "ja"). `undefined` if the list has neither. */
+export function matchLanguage(tag, list) {
+    const code = normaliseCode(tag);
+    if (code === undefined)
+        return undefined;
+    if (list.includes(code))
+        return code;
+    const main = code.split("-")[0];
+    return list.find((entry) => entry === main) ?? list.find((entry) => entry.split("-")[0] === main);
+}
+/** A language's own name: yours (`names`), the family's table, `Intl.DisplayNames` in that language, else the code. */
+export function languageName(code, names = {}) {
+    const own = names[code] ?? OWN_NAMES[code];
+    if (own !== undefined)
+        return own;
+    try {
+        const name = new Intl.DisplayNames([code], { type: "language" }).of(code);
+        if (name !== undefined && name !== code)
+            return name.charAt(0).toLocaleUpperCase(code) + name.slice(1);
+    }
+    catch {
+        /* a browser that does not know the code */
+    }
+    return code;
+}
+/** The language to start in: the address, the store, `value`, the reader's languages, what the page holds now, then the first of the list. */
+export function startingLanguage(from) {
+    const { list } = from;
+    if (from.search !== undefined) {
+        const asked = matchLanguage(new URLSearchParams(from.search).get(from.addressKey ?? LANGUAGE_ADDRESS_KEY), list);
+        if (asked !== undefined)
+            return asked;
+    }
+    if (from.storage !== undefined) {
+        try {
+            const kept = matchLanguage(from.storage.getItem(from.storageKey ?? LANGUAGE_STORAGE_KEY), list);
+            if (kept !== undefined)
+                return kept;
+        }
+        catch {
+            /* a browser that keeps nothing */
+        }
+    }
+    const own = matchLanguage(from.value, list);
+    if (own !== undefined)
+        return own;
+    for (const tag of from.preferred ?? []) {
+        const wanted = matchLanguage(tag, list);
+        if (wanted !== undefined)
+            return wanted;
+    }
+    return matchLanguage(from.current, list) ?? list[0];
+}
+/** Writes the choice as `lang` on the target. */
+export function applyLanguage(target, code) {
+    target.setAttribute(LANGUAGE_ATTRIBUTE, code);
+}

package/dist/language-picker/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";

package/dist/language-picker/styles.js

@@ -0,0 +1,3 @@
+import { BASE_STYLES } from "../shared/base.js";
+// A button for each language, in that language's own name.
+export const STYLES = BASE_STYLES;

package/dist/language-picker/words.d.ts

@@ -0,0 +1,8 @@
+export interface PickerWords {
+    group: string;
+}
+export type Language = "en" | "ja";
+export declare const WORDS: Record<Language, PickerWords>;
+/** 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<PickerWords>) => PickerWords;

package/dist/language-picker/words.js

@@ -0,0 +1,7 @@
+export const WORDS = {
+    en: { group: "Language" },
+    ja: { group: "言語" },
+};
+/** 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 });

package/dist/save-image/define.d.ts

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

package/dist/save-image/define.js

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

package/dist/save-image/element.d.ts

@@ -0,0 +1,39 @@
+import { EVENT, ERROR_EVENT, TAG } from "./index.ts";
+import { type Format } from "./format.ts";
+import { type Picture } from "./render.ts";
+import { type SaveWords } from "./words.ts";
+export { EVENT, ERROR_EVENT, TAG };
+/** What the `kazoku-save` event carries in `detail`. */
+export interface SaveDetail extends Picture {
+    /** The file name offered to the browser, with the extension. */
+    filename: string;
+    /** `user` (a button) or `api` (`save()` called by the page). */
+    reason: "user" | "api";
+}
+/** What the `kazoku-saveerror` event carries in `detail`. */
+export interface SaveErrorDetail {
+    format: Format;
+    error: Error;
+    reason: "user" | "api";
+}
+/**
+ * Attributes: `for` (the id of the canvas, SVG or element to save; or set `element.target`), `formats` (`png svg`, the buttons, in order; one the target cannot give is left out),
+ * `name` (the file name without its extension; `image` by default), `scale` (PNG pixels for each CSS pixel of an SVG or element; 2 by default; a canvas is saved at its own size),
+ * `background` (a CSS colour behind a PNG; transparent without it), `manual` (make the picture and send the event, but do not download), `no-inline-styles` (leave the computed styles out of what is saved),
+ * `lang` (`en` or `ja`), `theme` (`light` or `dark`: its own look, otherwise the page's).
+ */
+export declare class SaveImageElement extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    /** The element that is saved: the one `for` names, or the one you set. */
+    get target(): Element | undefined;
+    set target(element: Element | undefined);
+    /** Your own labels over the language's, for example `{ png: "Download PNG" }`. */
+    set words(words: Partial<SaveWords>);
+    /** Saves the target in a format (the first button's by default) and resolves with the picture; rejects with the error the event reports. */
+    save(format?: Format): Promise<SaveDetail>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+}

package/dist/save-image/element.js

@@ -0,0 +1,186 @@
+// <kazoku-save-image>: Save PNG and Save SVG buttons for a canvas, an SVG or an element on the page. It never draws the scene: it saves what the target shows, hands the picture to the
+// browser as a download, and tells the page with a `kazoku-save` event (or `kazoku-saveerror`).
+import { adoptStyles } from "../shared/adopt.js";
+import { watchScheme } from "../shared/scheme.js";
+import { EVENT, ERROR_EVENT, TAG } from "./index.js";
+import { filenameFor, formatsFor, parseFormats } from "./format.js";
+import { downloadBlob, kindOf, renderImage } from "./render.js";
+import { STYLES } from "./styles.js";
+import { languageOf, wordsFor } from "./words.js";
+export { EVENT, ERROR_EVENT, TAG };
+const icon = `<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M11 3h2v9.2l3.3-3.3 1.4 1.4L12 16.1l-5.7-5.8 1.4-1.4 3.3 3.3zM5 18h14v2H5z"/></svg>`;
+/**
+ * Attributes: `for` (the id of the canvas, SVG or element to save; or set `element.target`), `formats` (`png svg`, the buttons, in order; one the target cannot give is left out),
+ * `name` (the file name without its extension; `image` by default), `scale` (PNG pixels for each CSS pixel of an SVG or element; 2 by default; a canvas is saved at its own size),
+ * `background` (a CSS colour behind a PNG; transparent without it), `manual` (make the picture and send the event, but do not download), `no-inline-styles` (leave the computed styles out of what is saved),
+ * `lang` (`en` or `ja`), `theme` (`light` or `dark`: its own look, otherwise the page's).
+ */
+export class SaveImageElement extends HTMLElement {
+    static observedAttributes = ["for", "formats", "lang"];
+    #root;
+    #target;
+    #words = {};
+    #ready = false;
+    #styled = false;
+    #busy = false;
+    #stop = [];
+    #clear;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: "open" });
+    }
+    /** The element that is saved: the one `for` names, or the one you set. */
+    get target() {
+        return this.#target;
+    }
+    set target(element) {
+        this.#target = element;
+        this.#render();
+    }
+    /** Your own labels over the language's, for example `{ png: "Download PNG" }`. */
+    set words(words) {
+        this.#words = words;
+        this.#render();
+    }
+    /** Saves the target in a format (the first button's by default) and resolves with the picture; rejects with the error the event reports. */
+    async save(format = this.#formats()[0] ?? "png") {
+        return this.#save(format, "api");
+    }
+    connectedCallback() {
+        if (!this.#styled) {
+            adoptStyles(this.#root, STYLES, this.nonce);
+            this.#styled = true;
+        }
+        this.#stop.push(watchScheme(this));
+        this.#resolveTarget();
+        if (this.#target === undefined && this.ownerDocument.readyState === "loading")
+            this.ownerDocument.addEventListener("DOMContentLoaded", () => this.#resolveTarget(), { once: true });
+        this.#ready = true;
+        this.#render();
+    }
+    disconnectedCallback() {
+        for (const stop of this.#stop.splice(0))
+            stop();
+        globalThis.clearTimeout(this.#clear);
+        this.#ready = false;
+    }
+    attributeChangedCallback(name) {
+        if (!this.#ready)
+            return;
+        if (name === "for")
+            this.#resolveTarget();
+        else
+            this.#render();
+    }
+    #resolveTarget() {
+        const id = this.getAttribute("for");
+        if (id === null)
+            return;
+        const root = this.getRootNode();
+        const found = root.getElementById?.(id) ?? this.ownerDocument.getElementById(id);
+        if (found !== null && found !== undefined) {
+            this.#target = found;
+            this.#render();
+        }
+    }
+    /** The formats the buttons offer: those asked for that the target can give (all of them while there is no target yet). */
+    #formats() {
+        const asked = parseFormats(this.getAttribute("formats"));
+        if (this.#target === undefined)
+            return asked;
+        const can = formatsFor(kindOf(this.#target));
+        return asked.filter((format) => can.includes(format));
+    }
+    #render() {
+        if (!this.#ready)
+            return;
+        const language = languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
+        const words = wordsFor(language, this.#words);
+        const formats = this.#formats();
+        let group = this.#root.querySelector(".group");
+        if (group === null) {
+            group = this.ownerDocument.createElement("div");
+            group.className = "group";
+            group.setAttribute("part", "group");
+            group.setAttribute("role", "group");
+            const status = this.ownerDocument.createElement("span");
+            status.className = "vh";
+            status.setAttribute("role", "status");
+            this.#root.append(group, status);
+        }
+        group.setAttribute("aria-label", words.group);
+        group.setAttribute("lang", language);
+        const have = [...group.querySelectorAll("button")];
+        if (have.length !== formats.length || have.some((button, index) => button.dataset.v !== formats[index])) {
+            group.replaceChildren(...formats.map((format) => {
+                const button = this.ownerDocument.createElement("button");
+                button.type = "button";
+                button.dataset.v = format;
+                button.setAttribute("part", "button");
+                button.innerHTML = `${icon}<span class="t"></span>`;
+                button.addEventListener("click", () => {
+                    if (!this.#busy)
+                        void this.#save(format, "user").catch(() => undefined);
+                });
+                return button;
+            }));
+        }
+        for (const button of group.querySelectorAll("button"))
+            button.querySelector(".t").textContent = words[button.dataset.v];
+    }
+    async #save(format, reason) {
+        const words = wordsFor(languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang), this.#words);
+        const say = (text) => {
+            const status = this.#root.querySelector(".vh");
+            if (status !== null)
+                status.textContent = text;
+            globalThis.clearTimeout(this.#clear);
+            this.#clear = globalThis.setTimeout(() => status !== null && (status.textContent = ""), 3000);
+        };
+        try {
+            if (this.#target === undefined)
+                this.#resolveTarget();
+            if (this.#target === undefined)
+                throw new Error("there is nothing to save: `for` names no element");
+            if (this.#busy)
+                throw new Error("a picture is already being made");
+            this.#busy = true;
+            this.#busyButtons(true);
+            const scale = Number(this.getAttribute("scale"));
+            const background = this.getAttribute("background") ?? undefined;
+            const picture = await renderImage(this.#target, {
+                format,
+                scale: Number.isFinite(scale) && scale > 0 ? scale : 2,
+                ...(background !== undefined ? { background } : {}),
+                inlineStyles: !this.hasAttribute("no-inline-styles"),
+            });
+            const filename = filenameFor(this.getAttribute("name"), format);
+            if (!this.hasAttribute("manual"))
+                downloadBlob(picture.blob, filename);
+            const detail = { ...picture, filename, reason };
+            say(words.saved);
+            this.dispatchEvent(new CustomEvent(EVENT, { detail, bubbles: true, composed: true }));
+            return detail;
+        }
+        catch (caught) {
+            const error = caught instanceof Error ? caught : new Error(String(caught));
+            say(words.failed);
+            this.dispatchEvent(new CustomEvent(ERROR_EVENT, { detail: { format, error, reason }, bubbles: true, composed: true }));
+            throw error;
+        }
+        finally {
+            if (this.#busy) {
+                this.#busy = false;
+                this.#busyButtons(false);
+            }
+        }
+    }
+    #busyButtons(busy) {
+        for (const button of this.#root.querySelectorAll("button")) {
+            if (busy)
+                button.setAttribute("aria-busy", "true");
+            else
+                button.removeAttribute("aria-busy");
+        }
+    }
+}

package/dist/save-image/format.d.ts

@@ -0,0 +1,20 @@
+export declare const FORMATS: readonly ["png", "svg"];
+export type Format = (typeof FORMATS)[number];
+/** What a target is: a canvas, an SVG, or any other element (drawn through an SVG `foreignObject`). */
+export type TargetKind = "canvas" | "svg" | "element";
+export declare const MIME: Record<Format, string>;
+/** The most a picture may be on one side, and in all: past these a canvas fails in some browsers, so the scale is lowered instead. */
+export declare const MAX_SIDE = 8192;
+export declare const MAX_PIXELS = 36000000;
+/** The formats of `formats="png svg"`: the known ones, once each, in the order given. Nothing usable gives `png` and `svg`. */
+export declare function parseFormats(value: string | null | undefined): Format[];
+/** Which formats a kind of target can give: an SVG both, a canvas and any other element a PNG. */
+export declare const formatsFor: (kind: TargetKind) => readonly Format[];
+/** A file name that is safe on any system, with the format's extension: no path, no control or reserved characters, at most 80 characters of name. */
+export declare function filenameFor(name: string | null | undefined, format: Format): string;
+/** The pixels of a PNG of a target `width` by `height` CSS pixels at `scale`: whole pixels, and the scale lowered so that no side passes MAX_SIDE and the whole stays within MAX_PIXELS. */
+export declare function pixelSize(width: number, height: number, scale: number): {
+    width: number;
+    height: number;
+    scale: number;
+};