@gjsify/adwaita-web 0.64.2-next.252 → 0.64.2-next.255

package/src/test.browser.mts

@@ -28,6 +28,7 @@ import { AdwMultiLayoutViewTest } from './adw-multi-layout-view.spec.js';
 import { AdwDataGridTest } from './adw-data-grid.spec.js';
 import { GtkSourceViewTest } from './gtksource/gtk-source-view.spec.js';
 import { AdwDialogTest } from './adw-dialog.spec.js';
+import { WidgetMapTest } from './widget-map.spec.js';
 import { AdwWindowTest } from './adw-window.spec.js';
 import { AdwShortcutsTest } from './adw-shortcuts.spec.js';
 import { AdwApplicationWindowTest } from './adw-application-window.spec.js';
@@ -65,7 +66,7 @@ import { PangoMarkupTest } from './pango-markup.spec.js';
 import { CopyGlyphTest } from './source-view/copy-glyph.spec.js';
 import { AdwButtonContentTest } from './adw-button-content.spec.js';
 import { GtkImageTest } from './gtk-image.spec.js';
-import { AdwIconRegistryTest } from './icon-registry.spec.js';
+import { AdwIconMasksTest } from './icon-masks.spec.js';
 import { AdwIconThemeTest } from './icon-theme.spec.js';
 import { GioResourceTest } from './gio-resource.spec.js';
 import { GtkSwitchTest } from './gtk-switch.spec.js';
@@ -95,6 +96,7 @@ import { GtkToggleButtonTest } from './gtk-toggle-button.spec.js';
 import { GtkExpanderTest } from './gtk-expander.spec.js';
 import { GtkOverlayTest } from './gtk-overlay.spec.js';
 import { ContainerFillTest } from './container-fill.spec.js';
+import { ComputeExpandTest } from './compute-expand.spec.js';
 import { GtkPanedTest } from './gtk-paned.spec.js';
 import { GtkRevealerTest } from './gtk-revealer.spec.js';
 import { GtkScaleTest } from './gtk-scale.spec.js';
@@ -209,7 +211,7 @@ run({
     CopyGlyphTest,
     AdwButtonContentTest,
     GtkImageTest,
-    AdwIconRegistryTest,
+    AdwIconMasksTest,
     AdwIconThemeTest,
     GioResourceTest,
     GtkSwitchTest,
@@ -244,6 +246,7 @@ run({
     GtkExpanderTest,
     GtkOverlayTest,
     ContainerFillTest,
+    ComputeExpandTest,
     GtkPanedTest,
     GtkRevealerTest,
     GtkScaleTest,
@@ -297,6 +300,7 @@ run({
     AdwDataGridTest,
     GtkSourceViewTest,
     AdwDialogTest,
+    WidgetMapTest,
     AdwWindowTest,
     AdwShortcutsTest,
     AdwApplicationWindowTest,

package/src/widget-element.ts

@@ -0,0 +1,75 @@
+// `Gtk.Widget`'s `visible` and `tooltip-text` on the element classes, once, so the types of every
+// widget carry them and so does a plain `document.createElement()`, not only a built tree.
+//
+// `WidgetElement` is `HTMLElement` plus `gtk_widget_get_visible` / `gtk_widget_set_visible` over
+// the DOM's `hidden` attribute, TRUE until hidden as GtkWidget's default is, and the `map` /
+// `unmap` signals with `gtk_widget_get_mapped` (`widget-mapping.ts`); `installVisible`
+// (`gobject-elements.ts`) gives the same to a class that does not extend it. It notifies only
+// where the element declares `notify::visible`. A subclass with its own `visible`
+// (`<gtk-stack-page>`, `<adw-sidebar>`) keeps its own.
+//
+// `TooltipElement` adds `Gtk.Widget:tooltip-text` for the elements that render the
+// `tooltip-text` attribute: a button, and the rows (`row-tooltip.ts`). It reflects that attribute
+// and the element's `attributeChangedCallback` draws it, so a widget that does not draw it does
+// not extend this class.
+//
+// Reference: GTK gtk/gtkwidget.c (gtk_widget_set_visible, gtk_widget_set_tooltip_text)
+// Copyright (c) GNOME contributors (GTK). LGPLv2.1+.
+
+import { WIDGET_VISIBLE_GETTERS, notifyElement } from './gobject-elements.js';
+import { dispatchedSignalsOf, type DispatchedSignals } from './signals.js';
+import { isMapped } from './widget-mapping.js';
+
+export class WidgetElement extends HTMLElement {
+    /** `Gtk.Widget::map` / `::unmap`, which every subclass inherits (`dispatchedSignalsOf`). */
+    static readonly signals: DispatchedSignals = { map: 'map', unmap: 'unmap' };
+
+    /** `Gtk.Widget:visible`. */
+    get visible(): boolean {
+        return !this.hidden;
+    }
+    set visible(value: boolean) {
+        const before = !this.hidden;
+        this.toggleAttribute('hidden', !value);
+        if (!this.hidden !== before && 'notify::visible' in dispatchedSignalsOf(this)) notifyElement(this, 'visible');
+    }
+    /** `gtk_widget_get_visible`. */
+    get_visible(): boolean {
+        return this.visible;
+    }
+    /** `gtk_widget_set_visible`. */
+    set_visible(visible: boolean): void {
+        this.visible = visible;
+    }
+    /** `gtk_widget_get_mapped`: on screen, which is in the document and rendered. */
+    get_mapped(): boolean {
+        return isMapped(this);
+    }
+}
+
+WIDGET_VISIBLE_GETTERS.add(Object.getOwnPropertyDescriptor(WidgetElement.prototype, 'visible')!.get!);
+
+export class TooltipElement extends WidgetElement {
+    /** `Gtk.Widget:tooltip-text`, the `tooltip-text` attribute; `null` while unset. */
+    get tooltip_text(): string | null {
+        return this.getAttribute('tooltip-text');
+    }
+    set tooltip_text(value: string | null) {
+        if (value === null || value === undefined) this.removeAttribute('tooltip-text');
+        else this.setAttribute('tooltip-text', value);
+    }
+    get tooltipText(): string | null {
+        return this.tooltip_text;
+    }
+    set tooltipText(value: string | null) {
+        this.tooltip_text = value;
+    }
+    /** `gtk_widget_get_tooltip_text`. */
+    get_tooltip_text(): string | null {
+        return this.tooltip_text;
+    }
+    /** `gtk_widget_set_tooltip_text`. */
+    set_tooltip_text(text: string | null): void {
+        this.tooltip_text = text;
+    }
+}

package/src/widget-map.spec.ts

@@ -0,0 +1,116 @@
+// `Gtk.Widget::map` / `::unmap` and `get_mapped()` on an element: WIDGET_MAP_VECTORS, plus the
+// program that found the gap — a registered `Adw.PreferencesDialog` subclass connecting `map` in
+// its constructor (Learn6502's preferences dialog), which threw "declares no signal 'map'".
+import { describe, expect, it } from '@gjsify/unit';
+import { driveWidgetMapVectors, WIDGET_MAP_VECTORS, type WidgetMapSubject } from '@gjsify/adwaita-core/conformance';
+
+import { Adw, GObject } from './index.js';
+import { installElementApi } from './gobject-elements.js';
+import type { WidgetElement } from './widget-element.js';
+
+type Connectable = HTMLElement & { connect(signal: string, handler: (...args: unknown[]) => unknown): number };
+
+function settle(): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve));
+}
+
+const hosts: HTMLElement[] = [];
+
+const subject: WidgetMapSubject = {
+    name: 'adwaita-web',
+    isOracle: false,
+    box() {
+        const el = document.createElement('gtk-box');
+        installElementApi(el);
+        return el;
+    },
+    append: (parent, child) => void (parent as HTMLElement).append(child as HTMLElement),
+    remove: (_parent, child) => void (child as HTMLElement).remove(),
+    present(widget) {
+        const host = document.createElement('div');
+        host.append(widget as HTMLElement);
+        document.body.append(host);
+        hosts.push(host);
+    },
+    setVisible: (widget, visible) => void ((widget as WidgetElement).visible = visible),
+    connect: (widget, signal, handler) => (widget as Connectable).connect(signal, handler),
+    isMapped: (widget) => (widget as WidgetElement).get_mapped(),
+    settle,
+    dispose() {
+        for (const host of hosts.splice(0)) host.remove();
+    },
+};
+
+class GoWebMapDialog extends Adw.PreferencesDialog {
+    log: string[] = [];
+    constructor(params?: Record<string, unknown>) {
+        // @ts-expect-error the element's own constructor takes none; the registered class's takes the params
+        super(params);
+        const self = this as unknown as Connectable & { get_mapped(): boolean };
+        self.connect('map', () => this.log.push(`map:${self.get_mapped()}`));
+        self.connect('unmap', () => this.log.push(`unmap:${self.get_mapped()}`));
+    }
+}
+GObject.registerClass({ GTypeName: 'GoWebMapDialog' }, GoWebMapDialog);
+
+export const WidgetMapTest = async () => {
+    await driveWidgetMapVectors(subject, { describe, it, expect }, WIDGET_MAP_VECTORS);
+
+    await describe('adwaita-web: map / unmap on an element', async () => {
+        await it('every widget declares both, a subclass with its own signals too', () => {
+            for (const tag of ['gtk-box', 'gtk-button', 'adw-preferences-dialog']) {
+                const el = document.createElement(tag);
+                installElementApi(el);
+                expect(() => (el as Connectable).connect('map', () => {})).not.toThrow();
+                expect(() => (el as Connectable).connect('unmap', () => {})).not.toThrow();
+            }
+            // `<gtk-button>` declares `clicked` itself and still has `map`.
+            const button = document.createElement('gtk-button');
+            installElementApi(button);
+            expect(() => (button as Connectable).connect('clicked', () => {})).not.toThrow();
+        });
+
+        await it('a registered dialog connecting `map` in its constructor maps on present() and unmaps on close()', async () => {
+            const dialog = new (GoWebMapDialog as unknown as new () => GoWebMapDialog)();
+            await settle();
+            expect(dialog.log).toStrictEqual([]);
+            (dialog as unknown as { present(): void }).present();
+            await settle();
+            expect(dialog.log).toStrictEqual(['map:true']);
+            (dialog as unknown as { close(): void }).close();
+            await settle();
+            expect(dialog.log).toStrictEqual(['map:true', 'unmap:false']);
+            dialog.remove();
+        });
+
+        await it('a disconnected handler stops the watch: no emission after it', async () => {
+            const box = subject.box() as Connectable & { disconnect(id: number): void };
+            let emitted = 0;
+            const id = box.connect('map', () => void emitted++);
+            box.disconnect(id);
+            subject.present(box);
+            await settle();
+            expect(emitted).toBe(0);
+            subject.dispose();
+        });
+
+        await it('a popover that opens maps, one that closes unmaps', async () => {
+            const host = document.createElement('div');
+            const popover = document.createElement('div');
+            popover.setAttribute('popover', '');
+            const inner = subject.box() as Connectable;
+            popover.append(inner);
+            host.append(popover);
+            document.body.append(host);
+            const log: string[] = [];
+            inner.connect('map', () => void log.push('map'));
+            inner.connect('unmap', () => void log.push('unmap'));
+            popover.showPopover();
+            await settle();
+            popover.hidePopover();
+            await settle();
+            host.remove();
+            expect(log).toStrictEqual(['map', 'unmap']);
+        });
+    });
+};

package/src/widget-mapping.ts

@@ -0,0 +1,100 @@
+// `Gtk.Widget`'s `map` / `unmap` signals and `gtk_widget_get_mapped` on an element.
+//
+// A widget is mapped while it is on screen: it is visible and so is every ancestor. Here that is
+// an element in the document that renders (`isConnected && checkVisibility()`), which covers a
+// `hidden` ancestor, a closed `<dialog>`, an inactive stack page and a popover that is not open.
+// `map` fires on the transition into that state and `unmap` on the way out, never on connect.
+//
+// The DOM has no event for either transition, so an element is only WATCHED while something
+// listens to one of the two: one `MutationObserver` on the document (children and attributes,
+// the whole subtree) and a capturing `toggle` listener (a popover opening changes no attribute)
+// re-check every watched element after each batch. A batch is delivered after the change, not
+// inside it as `gtk_widget_show` delivers it; a hide undone within the same turn emits nothing.
+//
+// Order is GTK's post-order (`map` and `unmap` are RUN_FIRST, and the class handler maps or
+// unmaps the children first): the deepest element of a batch emits first, unmaps before maps.
+//
+// Reference: GTK gtk/gtkwidget.c (gtk_widget_map, gtk_widget_unmap, gtk_widget_real_map,
+// gtk_widget_real_unmap, gtk_widget_get_mapped)
+// Copyright (c) GNOME contributors (GTK). LGPLv2.1+.
+
+/** Watched elements and the state each last emitted for. */
+const STATE = new WeakMap<HTMLElement, { mapped: boolean; listeners: number }>();
+const WATCHED = new Set<WeakRef<HTMLElement>>();
+const REFS = new WeakMap<HTMLElement, WeakRef<HTMLElement>>();
+let observer: MutationObserver | null = null;
+
+/** `gtk_widget_get_mapped`: in the document, and rendered. */
+export function isMapped(el: Element): boolean {
+    return el.isConnected && el.checkVisibility();
+}
+
+function depthOf(el: Element): number {
+    let depth = 0;
+    for (let at = el.parentElement; at !== null; at = at.parentElement) depth++;
+    return depth;
+}
+
+function recheck(): void {
+    const changed: HTMLElement[] = [];
+    for (const ref of WATCHED) {
+        const el = ref.deref();
+        if (el === undefined) {
+            WATCHED.delete(ref);
+            continue;
+        }
+        const state = STATE.get(el)!;
+        if (isMapped(el) !== state.mapped) changed.push(el);
+    }
+    if (changed.length === 0) return;
+    const deepestFirst = (list: HTMLElement[]) =>
+        list.map((el) => [el, depthOf(el)] as const).sort((a, b) => b[1] - a[1]);
+    const unmapped = deepestFirst(changed.filter((el) => STATE.get(el)!.mapped));
+    const mapped = deepestFirst(changed.filter((el) => !STATE.get(el)!.mapped));
+    for (const [el] of [...unmapped, ...mapped]) {
+        const state = STATE.get(el)!;
+        state.mapped = !state.mapped;
+        el.dispatchEvent(new CustomEvent(state.mapped ? 'map' : 'unmap'));
+    }
+}
+
+function observe(): void {
+    if (observer !== null) return;
+    observer = new MutationObserver(recheck);
+    observer.observe(document, { childList: true, subtree: true, attributes: true });
+    document.addEventListener('toggle', recheck, true);
+}
+
+function unobserve(): void {
+    if (observer === null || WATCHED.size > 0) return;
+    observer.disconnect();
+    observer = null;
+    document.removeEventListener('toggle', recheck, true);
+}
+
+/**
+ * Watches `el` for `map` / `unmap` while the returned function has not been called. Its present
+ * state is recorded and not emitted, as connecting a handler in GTK emits nothing.
+ */
+export function watchMapping(el: HTMLElement): () => void {
+    let state = STATE.get(el);
+    if (state === undefined || state.listeners === 0) {
+        state = { mapped: isMapped(el), listeners: 0 };
+        STATE.set(el, state);
+        const ref = new WeakRef(el);
+        REFS.set(el, ref);
+        WATCHED.add(ref);
+        observe();
+    }
+    state.listeners++;
+    let watching = true;
+    return () => {
+        if (!watching) return;
+        watching = false;
+        const current = STATE.get(el)!;
+        if (--current.listeners > 0) return;
+        WATCHED.delete(REFS.get(el)!);
+        REFS.delete(el);
+        unobserve();
+    };
+}

package/src/widget-visible.spec.ts

@@ -3,6 +3,8 @@
 import { describe, expect, it } from '@gjsify/unit';
 import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
 
+import { Adw, Gtk } from './index.js';
+
 import { mountSharedTree } from './shared-tree-builder.js';
 
 function settle(): Promise<void> {
@@ -101,4 +103,46 @@ export const AdwWidgetVisibleTest = async () => {
             expect(item.hasAttribute('hidden')).toBe(true);
         });
     });
+
+    await describe('adwaita-web: Gtk.Widget:visible and tooltip-text on the element class', async () => {
+        await it('a created button has visible, get_visible and set_visible, typed on the class', () => {
+            const button: Gtk.Button = new Gtk.Button();
+            expect(button.visible).toBe(true);
+            button.set_visible(false);
+            expect(button.hidden).toBe(true);
+            expect(button.get_visible()).toBe(false);
+            button.visible = true;
+            expect(button.hasAttribute('hidden')).toBe(false);
+        });
+
+        await it('a created widget that is not a button has them too', () => {
+            const box = new Gtk.Box();
+            box.visible = false;
+            expect(box.hidden).toBe(true);
+            expect(box.get_visible()).toBe(false);
+        });
+
+        await it('a button has tooltip_text, tooltipText and get/set_tooltip_text over one attribute', () => {
+            const button = new Gtk.Button();
+            document.body.append(button);
+            expect(button.get_tooltip_text()).toBe(null);
+            button.set_tooltip_text('Copy');
+            expect(button.tooltip_text).toBe('Copy');
+            expect(button.tooltipText).toBe('Copy');
+            expect(button.getAttribute('tooltip-text')).toBe('Copy');
+            expect(button.querySelector('button')?.title).toBe('Copy');
+            button.tooltip_text = null;
+            expect(button.hasAttribute('tooltip-text')).toBe(false);
+            button.remove();
+        });
+
+        await it('a row has them and draws the tooltip on its parts', () => {
+            const row: Adw.ActionRow = new Adw.ActionRow();
+            document.body.append(row);
+            row.set_tooltip_text('Hint');
+            expect(row.get_tooltip_text()).toBe('Hint');
+            expect(row.querySelector('[title="Hint"]') !== null).toBe(true);
+            row.remove();
+        });
+    });
 };

package/lib/types/icon-registry.d.ts

@@ -1,37 +0,0 @@
-/**
- * Make `name` drawable by every `.adw-icon` in the document, from an Adwaita symbolic SVG
- * source string (what `@gjsify/adwaita-icons` exports).
- *
- * BOTH arguments are checked and a wrong one THROWS rather than registering nothing: unlike
- * a render, this is an explicit call with a wrong argument, and silently doing nothing is
- * the failure mode this whole area exists to end. The name is normalized exactly as
- * `<gtk-image icon-name>` normalizes it — a single `-symbolic` suffix comes off, and the rest
- * must be one CSS token; the SVG has to parse to an `<svg>` root. `<gtk-image>` draws
- * `image-missing` for the same unusable name instead — there it came from markup, and
- * taking the page down over a typo is not proportionate.
- *
- * Registering a name the stylesheet already compiles is allowed and REPLACES the glyph:
- * the property is set on the document element, so it wins over the `:root` rule.
- *
- * CLIENT-SIDE ONLY: this touches `document.documentElement` and `document.head`, so at
- * module top level in an SSR/SSG build it throws before a page is rendered.
- */
-export declare function registerIcon(name: string, svg: string): void;
-/**
- * Whether `name` draws something other than `image-missing` — a symbolic glyph compiled into
- * the stylesheet or registered at runtime, or a colour icon from `registerColorIcon`. The
- * name is looked up exactly as `<gtk-image icon-name>` looks it up (`icon-theme.ts`).
- *
- * Reads the live cascade rather than a generated list, so it answers for a glyph that
- * arrived by any route, including a consumer's own `--icon-<name>` declaration. It is
- * deliberately the CUSTOM PROPERTY that is read and not the rendered `mask-image` of a
- * probe element: since `_icon.scss` gives every icon box the `image-missing` fallback,
- * a rendered mask is never `none`, and comparing against the fallback would answer
- * `false` for `image-missing` itself — the one name where being drawn and having fallen
- * back look identical.
- *
- * Narrowing worth knowing: a consumer who writes `.adw-icon--x { mask-image: url(…) }`
- * with no matching `--icon-x` gets `false` here and a drawn icon anyway. The generator and
- * {@link registerIcon} are the two things that create the pair, and both create both.
- */
-export declare function isIconAvailable(name: string): boolean;

package/src/icon-registry.ts

@@ -1,163 +0,0 @@
-// The runtime half of icon resolution — how a name OUTSIDE the compiled set gets drawn.
-//
-// `scripts/build-scss.mjs` inlines a chosen subset of `@gjsify/adwaita-icons` into the
-// stylesheet as `--icon-<name>` custom properties plus matching `.adw-icon--<name>` mask
-// classes. The subset exists because the whole set does not fit — inlining every icon that
-// package exports costs a measured ~1.07 MB of data-URI, some five times the stylesheet it
-// would sit in — so a consumer whose app needs a glyph this package does not ship needs a
-// way in that is not "wait for a release".
-//
-// That is this module. `registerIcon` writes the SAME pair the generator writes — the
-// custom property on the document element, the mask class into a stylesheet this module
-// owns — so a registered icon is indistinguishable from a compiled one at every later
-// point: `<gtk-image icon-name="…">`, a hand-written `class="adw-icon adw-icon--…"`, a
-// widget attribute, `var(--icon-…)` in the consumer's own CSS.
-//
-//   import { registerIcon } from '@gjsify/adwaita-web';
-//   import { dialogErrorSymbolic } from '@gjsify/adwaita-icons/status';
-//
-//   registerIcon('dialog-error-symbolic', dialogErrorSymbolic);
-//   // …then anywhere: <gtk-image icon-name="dialog-error-symbolic"></gtk-image>
-//
-// Register BEFORE the icon is mounted where you can. A `<gtk-image>` already in the
-// document draws the `image-missing` fallback (see `_icon.scss`) until the registration
-// lands; the CSS is live, so it corrects itself on the next style recalculation with no
-// re-render, but there is a visible frame in between.
-//
-// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+ — the icon SVGs.
-// Original implementation.
-
-import { normalizeIconName } from '@gjsify/adwaita-core';
-import { toDataUri } from '@gjsify/adwaita-icons/utils';
-
-import { MASK_CLASS_PREFIX } from './elements/gtk-image.js';
-import { iconResolves, notifyIconThemeChanged } from './icon-theme.js';
-
-/** Marks the one `<style>` element this module owns, so a reload reuses it. */
-const REGISTRY_STYLE_ID = 'adwaita-web-icon-registry';
-
-/**
- * Names already given a mask rule. Re-registering a name has to update the GLYPH without
- * appending a second rule: the custom property carries the glyph and the rule only points
- * at it, so the property assignment is the whole update and a duplicate rule would be
- * dead weight that grows without bound under a live theme switcher.
- */
-const ruled = new Set<string>();
-
-/** The one rule a registration adds: the class, pointing at the custom property. */
-function insertMaskRule(sheet: CSSStyleSheet, name: string): void {
-    sheet.insertRule(
-        `.${MASK_CLASS_PREFIX}${name} { mask-image: var(--icon-${name}); ` +
-            `-webkit-mask-image: var(--icon-${name}); }`,
-        sheet.cssRules.length,
-    );
-}
-
-/** This module's stylesheet, created on first use and appended last so nothing hides it. */
-function registrySheet(): CSSStyleSheet {
-    const existing = document.getElementById(REGISTRY_STYLE_ID) as HTMLStyleElement | null;
-    if (existing?.sheet) return existing.sheet;
-
-    const style = document.createElement('style');
-    style.id = REGISTRY_STYLE_ID;
-    document.head.appendChild(style);
-    // `sheet` is non-null the moment a <style> is in a document — the property is only
-    // null while the element is disconnected, which the append above rules out.
-    const sheet = style.sheet as CSSStyleSheet;
-
-    // Reaching here a SECOND time means the previous element was taken away — an SPA head
-    // swap, an Astro view transition — and every rule it held went with it. The custom
-    // properties did NOT: they sit on the document element. So re-issue the rules, or every
-    // name registered before the swap keeps its glyph in a property nothing consumes and
-    // draws the fallback forever. Nothing observes the head, so the recovery happens on the
-    // next `registerIcon` call rather than at the moment of the swap.
-    for (const name of ruled) insertMaskRule(sheet, name);
-    return sheet;
-}
-
-/**
- * The second argument has to be SVG SOURCE, and nothing else can tell us so: `toDataUri`
- * percent-encodes whatever it is handed, so `registerIcon('x', 'not an svg')` produces a
- * perfectly well-formed `mask-image` that masks NOTHING — an icon strictly worse than an
- * unregistered one, because the registered class beats `:where(.adw-icon)` and switches the
- * `image-missing` fallback OFF, while `isIconAvailable` reports `true`. Measured in Firefox:
- * `url("data:image/svg+xml,not%20an%20svg")`, 0 % of the box painted, no throw, no warning.
- *
- * A real parser rather than a `^<svg` test: an icon read from a file carries an XML prolog
- * or a DOCTYPE before its root element, and both are legitimate here.
- */
-function svgRootOf(source: string): Element {
-    return new DOMParser().parseFromString(source, 'image/svg+xml').documentElement;
-}
-
-/**
- * Make `name` drawable by every `.adw-icon` in the document, from an Adwaita symbolic SVG
- * source string (what `@gjsify/adwaita-icons` exports).
- *
- * BOTH arguments are checked and a wrong one THROWS rather than registering nothing: unlike
- * a render, this is an explicit call with a wrong argument, and silently doing nothing is
- * the failure mode this whole area exists to end. The name is normalized exactly as
- * `<gtk-image icon-name>` normalizes it — a single `-symbolic` suffix comes off, and the rest
- * must be one CSS token; the SVG has to parse to an `<svg>` root. `<gtk-image>` draws
- * `image-missing` for the same unusable name instead — there it came from markup, and
- * taking the page down over a typo is not proportionate.
- *
- * Registering a name the stylesheet already compiles is allowed and REPLACES the glyph:
- * the property is set on the document element, so it wins over the `:root` rule.
- *
- * CLIENT-SIDE ONLY: this touches `document.documentElement` and `document.head`, so at
- * module top level in an SSR/SSG build it throws before a page is rendered.
- */
-export function registerIcon(name: string, svg: string): void {
-    const resolved = normalizeIconName(name);
-    if (resolved === '') {
-        throw new TypeError(
-            `registerIcon: ${JSON.stringify(name)} is not usable as an icon name — it has to be a single ` +
-                'CSS token ([A-Za-z0-9_-]+) once an optional `-symbolic` suffix is removed.',
-        );
-    }
-
-    const root = svgRootOf(svg);
-    if (root.tagName !== 'svg') {
-        throw new TypeError(
-            `registerIcon(${JSON.stringify(resolved)}): the second argument has to be SVG SOURCE — the ` +
-                'kind of string `@gjsify/adwaita-icons` exports, not a URL, a data-URI or a DOM node. ' +
-                `Parsing it produced <${root.tagName}>, so it would have masked nothing at all.`,
-        );
-    }
-
-    document.documentElement.style.setProperty(`--icon-${resolved}`, toDataUri(svg));
-
-    // BEFORE the `ruled` early return: taking the sheet is what detects a lost <style>,
-    // and a name already in `ruled` is exactly the one the early return would skip.
-    const sheet = registrySheet();
-    if (!ruled.has(resolved)) {
-        insertMaskRule(sheet, resolved);
-        ruled.add(resolved);
-    }
-    // The CSS above is live for every mask class, but a `name-symbolic` request that fell
-    // back to a registered COLOUR icon has no mask class to update — the symbolic glyph
-    // now wins that lookup, so the element has to run it again.
-    notifyIconThemeChanged();
-}
-
-/**
- * Whether `name` draws something other than `image-missing` — a symbolic glyph compiled into
- * the stylesheet or registered at runtime, or a colour icon from `registerColorIcon`. The
- * name is looked up exactly as `<gtk-image icon-name>` looks it up (`icon-theme.ts`).
- *
- * Reads the live cascade rather than a generated list, so it answers for a glyph that
- * arrived by any route, including a consumer's own `--icon-<name>` declaration. It is
- * deliberately the CUSTOM PROPERTY that is read and not the rendered `mask-image` of a
- * probe element: since `_icon.scss` gives every icon box the `image-missing` fallback,
- * a rendered mask is never `none`, and comparing against the fallback would answer
- * `false` for `image-missing` itself — the one name where being drawn and having fallen
- * back look identical.
- *
- * Narrowing worth knowing: a consumer who writes `.adw-icon--x { mask-image: url(…) }`
- * with no matching `--icon-x` gets `false` here and a drawn icon anyway. The generator and
- * {@link registerIcon} are the two things that create the pair, and both create both.
- */
-export function isIconAvailable(name: string): boolean {
-    return iconResolves(name);
-}