@gjsify/adwaita-web 0.64.1-next.240 → 0.64.1-next.243

package/src/icon-registry.ts

@@ -31,6 +31,7 @@ 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';
@@ -130,13 +131,20 @@ export function registerIcon(name: string, svg: string): void {
     // 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)) return;
-    insertMaskRule(sheet, resolved);
-    ruled.add(resolved);
+    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` has a glyph — compiled into the stylesheet, or registered at runtime.
+ * 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
@@ -151,7 +159,5 @@ export function registerIcon(name: string, svg: string): void {
  * {@link registerIcon} are the two things that create the pair, and both create both.
  */
 export function isIconAvailable(name: string): boolean {
-    const resolved = normalizeIconName(name);
-    if (resolved === '') return false;
-    return getComputedStyle(document.documentElement).getPropertyValue(`--icon-${resolved}`).trim() !== '';
+    return iconResolves(name);
 }

package/src/icon-theme.spec.ts

@@ -0,0 +1,182 @@
+// The colour half of the icon theme, measured through `getComputedStyle` like
+// `icon-registry.spec.ts` measures the symbolic half: a class on the node proves nothing
+// about what it paints.
+//
+// The order under test is GLib's (`g_themed_icon_update_names`, which `GtkImage`'s lookup
+// goes through): `X` tries [X, X-symbolic], `X-symbolic` tries [X-symbolic, X], and a name
+// neither answers draws `image-missing`. The registry is module-level and outlives a test,
+// so every case registers names of its own.
+import { describe, expect, it } from '@gjsify/unit';
+
+import { COLOR_ICON_CLASS, type GtkImage } from './elements/gtk-image.js';
+import { fallbackMask, maskOf } from './icon-registry.spec.js';
+import { isIconAvailable, registerIcon } from './icon-registry.js';
+import { registerColorIcon } from './icon-theme.js';
+
+/** A full-colour app icon: a red square on a blue disc, nothing `currentColor` about it. */
+const COLOR_SVG = `<svg height="128" viewBox="0 0 128 128" width="128" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="64" cy="64" r="60" fill="#3584e4"/>
+    <rect x="40" y="40" width="48" height="48" fill="#e01b24"/>
+</svg>`;
+
+/** A symbolic glyph, distinct from the colour one by its path data. */
+const SYMBOLIC_SVG = `<svg height="16px" viewBox="0 0 16 16" width="16px" xmlns="http://www.w3.org/2000/svg">
+    <path d="m 3 3 h 10 v 10 h -10 z m 0 0" fill="currentColor"/>
+</svg>`;
+
+function mount(iconName: string): { el: GtkImage; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('gtk-image') as GtkImage;
+    el.iconName = iconName;
+    host.appendChild(el);
+    return { el, host };
+}
+
+/** Every `.adw-icon--…` mask class on the node. */
+function maskClasses(el: HTMLElement): string[] {
+    return [...el.classList].filter((c) => c.startsWith('adw-icon--'));
+}
+
+/** True when `el` paints the registered colour image and nothing masked. */
+function drawsInColor(el: HTMLElement): boolean {
+    const style = getComputedStyle(el);
+    return (
+        el.classList.contains(COLOR_ICON_CLASS) &&
+        maskClasses(el).length === 0 &&
+        style.maskImage === 'none' &&
+        style.backgroundColor === 'rgba(0, 0, 0, 0)' &&
+        // `#e01b24` survives `toDataUri` as `%23e01b24`.
+        style.backgroundImage.includes('%23e01b24')
+    );
+}
+
+export const AdwIconThemeTest = async () => {
+    await describe('registerColorIcon — a full-colour icon draws as-is', async () => {
+        await it('a reverse-DNS application id draws its image, unmasked and unfilled', () => {
+            const APP_ID = 'org.gjsify.ColorProbe';
+            registerColorIcon(APP_ID, COLOR_SVG);
+
+            const { el, host } = mount(APP_ID);
+            expect(drawsInColor(el)).toBe(true);
+            expect(isIconAvailable(APP_ID)).toBe(true);
+            host.remove();
+        });
+
+        await it('an already-mounted element redraws when the registration lands', () => {
+            const APP_ID = 'org.gjsify.LateColorProbe';
+            const { el, host } = mount(APP_ID);
+            // Before: what GTK draws for a name its theme does not have.
+            expect(maskOf(el)).toBe(fallbackMask());
+
+            registerColorIcon(APP_ID, COLOR_SVG);
+            expect(drawsInColor(el)).toBe(true);
+            host.remove();
+        });
+
+        await it("AdwAboutDialog's application-icon draws in colour", () => {
+            const APP_ID = 'org.gjsify.AboutColorProbe';
+            registerColorIcon(APP_ID, COLOR_SVG);
+
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const dialog = document.createElement('adw-about-dialog');
+            dialog.setAttribute('application-icon', APP_ID);
+            host.appendChild(dialog);
+
+            const icon = dialog.querySelector('.adw-about-dialog-icon') as HTMLElement;
+            expect(drawsInColor(icon)).toBe(true);
+            // The 96px box, and NOT a solid square under the image: the about dialog used to
+            // force `background-color: currentColor` on it.
+            expect(getComputedStyle(icon).width).toBe('96px');
+            host.remove();
+        });
+
+        await it('a URL source resolves against the document', () => {
+            const APP_ID = 'org.gjsify.UrlColorProbe';
+            registerColorIcon(APP_ID, 'icons/org.gjsify.UrlColorProbe.svg');
+
+            const { el, host } = mount(APP_ID);
+            const expected = new URL('icons/org.gjsify.UrlColorProbe.svg', document.baseURI).href;
+            expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(true);
+            expect(getComputedStyle(el).backgroundImage).toBe(`url("${expected}")`);
+            host.remove();
+        });
+    });
+
+    await describe('the lookup order is GThemedIcon’s', async () => {
+        await it('a symbolic icon still masks — a compiled one with no colour entry', () => {
+            const { el, host } = mount('go-next-symbolic');
+            expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskClasses(el)).toStrictEqual(['adw-icon--go-next']);
+            expect(maskOf(el)).not.toBe(fallbackMask());
+            expect(getComputedStyle(el).backgroundImage).toBe('none');
+            host.remove();
+        });
+
+        await it('X prefers the colour icon, X-symbolic prefers the symbolic one', () => {
+            const NAME = 'gjsify-theme-both-probe';
+            registerColorIcon(NAME, COLOR_SVG);
+            registerIcon(`${NAME}-symbolic`, SYMBOLIC_SVG);
+
+            const plain = mount(NAME);
+            expect(drawsInColor(plain.el)).toBe(true);
+            plain.host.remove();
+
+            const symbolic = mount(`${NAME}-symbolic`);
+            expect(symbolic.el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskOf(symbolic.el).includes('m%203%203')).toBe(true);
+            expect(getComputedStyle(symbolic.el).backgroundImage).toBe('none');
+            symbolic.host.remove();
+        });
+
+        await it('X-symbolic falls back to the colour X, and back again once X-symbolic lands', () => {
+            const NAME = 'gjsify-theme-fallback-probe';
+            registerColorIcon(NAME, COLOR_SVG);
+
+            const { el, host } = mount(`${NAME}-symbolic`);
+            expect(drawsInColor(el)).toBe(true);
+            expect(isIconAvailable(`${NAME}-symbolic`)).toBe(true);
+
+            registerIcon(NAME, SYMBOLIC_SVG);
+            expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskOf(el).includes('m%203%203')).toBe(true);
+            host.remove();
+        });
+
+        await it('an unknown name draws image-missing', () => {
+            for (const unknown of ['org.gjsify.NeverRegistered', 'gjsify-theme-never-registered']) {
+                const { el, host } = mount(unknown);
+                expect(el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+                expect(maskOf(el)).toBe(fallbackMask());
+                expect(isIconAvailable(unknown)).toBe(false);
+                host.remove();
+            }
+        });
+    });
+
+    await describe('registerColorIcon rejects what it cannot draw faithfully', async () => {
+        await it('throws on a name that is empty, spaced, or symbolic', () => {
+            expect(() => registerColorIcon('', COLOR_SVG)).toThrow();
+            expect(() => registerColorIcon('a b', COLOR_SVG)).toThrow();
+            // The symbolic half has its own door; GTK's theme treats all three suffixes as
+            // symbolic files.
+            expect(() => registerColorIcon('gjsify-probe-symbolic', COLOR_SVG)).toThrow();
+            expect(() => registerColorIcon('gjsify-probe-symbolic-ltr', COLOR_SVG)).toThrow();
+            expect(() => registerColorIcon('gjsify-probe-symbolic-rtl', COLOR_SVG)).toThrow();
+        });
+
+        await it('throws on a source that is not SVG or an image URL, and registers nothing', () => {
+            const REJECTED = 'org.gjsify.RejectedColorProbe';
+            expect(() => registerColorIcon(REJECTED, '')).toThrow();
+            expect(() => registerColorIcon(REJECTED, '<p>not svg</p>')).toThrow();
+            expect(() => registerColorIcon(REJECTED, 'javascript:alert(1)')).toThrow();
+            expect(() => registerColorIcon(REJECTED, 'data:text/html,<svg></svg>')).toThrow();
+            expect(isIconAvailable(REJECTED)).toBe(false);
+
+            const { el, host } = mount(REJECTED);
+            expect(maskOf(el)).toBe(fallbackMask());
+            host.remove();
+        });
+    });
+};

package/src/icon-theme.ts

@@ -0,0 +1,178 @@
+// The one name → glyph lookup every icon in this package goes through, symbolic AND colour.
+//
+// GTK draws two kinds of icon from the same `icon-name`: a symbolic one, recoloured with the
+// foreground colour, and a full-colour one (an application icon, a document thumbnail) that
+// is drawn as it is. Which one a name reaches is not the widget's choice. `GtkImage` builds a
+// `GThemedIcon` for the name (gtkimage.c → `gtk_icon_theme_lookup_by_gicon`) without
+// `use-default-fallbacks`, and `g_themed_icon_update_names` (GLib gio/gthemedicon.c, not in refs/)
+// turns it into an ordered candidate list:
+//
+//   `X`           → [X, X-symbolic]
+//   `X-symbolic`  → [X-symbolic, X]
+//
+// and `gtk_icon_theme_lookup_icon` returns the first candidate the theme has, else
+// `image-missing` — it never returns NULL (refs/gtk/gtk/gtkicontheme.c, `choose_icon`).
+//
+// This package compiles and registers symbolic glyphs only (`icon-registry.ts`, the
+// stylesheet's `.adw-icon--<name>` masks). The colour half lives here: a map from an EXACT
+// name to an image URL, filled by {@link registerColorIcon}. With the map empty every lookup
+// ends where it ended before this module existed, so nothing that only uses symbolic icons
+// changes.
+//
+// The colour map is keyed by the raw name, not by `normalizeIconName`: an application icon
+// is named after its application ID (`org.gnome.Builder`, adw-about-dialog.c:1215), which is
+// not a CSS token and never could be a mask class, but is a perfectly good Map key.
+//
+// Original implementation.
+
+import { normalizeIconName } from '@gjsify/adwaita-core';
+import { toDataUri } from '@gjsify/adwaita-icons/utils';
+
+/** What one icon name resolves to, in the order GTK's theme would try it. */
+export type IconLookup =
+    /** A registered full-colour image, drawn as-is. `url` is ready for `url("…")`. */
+    | { kind: 'color'; name: string; url: string }
+    /** A symbolic glyph, drawn through the `.adw-icon--<name>` mask. `name` is normalized. */
+    | { kind: 'symbolic'; name: string }
+    /** Nothing in the theme answers this name — draw `image-missing`. */
+    | { kind: 'missing' };
+
+/** The suffix `g_themed_icon_update_names` swaps to build the other variant. */
+const SYMBOLIC_SUFFIX = /-symbolic$/;
+
+/**
+ * Every name GTK's theme treats as a symbolic FILE (gtkicontheme.c `icon_name_is_symbolic`):
+ * the directional variants are symbolic too, so none of them is a colour icon.
+ */
+const SYMBOLIC_FILE_NAME = /-symbolic(?:-ltr|-rtl)?$/;
+
+/** Schemes a colour icon may be fetched from. Anything else can run script or is unknown. */
+const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'blob:', 'file:']);
+
+const colorIcons = new Map<string, string>();
+
+/**
+ * Elements that drew a lookup result and have to redraw when the theme changes. A symbolic
+ * registration is live through CSS and needs no redraw, but a colour one is an inline
+ * `background-image`, and GTK's own images re-run their lookup on the theme's `changed`
+ * signal for the same reason.
+ */
+const listeners = new Set<() => void>();
+
+/** Subscribe to theme changes. Returns the unsubscribe function. */
+export function onIconThemeChanged(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+
+/** Run every subscriber — after any registration that can change a lookup's answer. */
+export function notifyIconThemeChanged(): void {
+    for (const listener of listeners) listener();
+}
+
+/** Whether a symbolic glyph for an already-normalized name is in the cascade. */
+function hasSymbolic(normalized: string): boolean {
+    if (normalized === '') return false;
+    return getComputedStyle(document.documentElement).getPropertyValue(`--icon-${normalized}`).trim() !== '';
+}
+
+/**
+ * Resolve `iconName` as `gtk_icon_theme_lookup_by_gicon` would for a `GtkImage`. `null` when
+ * no name was given — the state where GTK draws nothing, not `image-missing`.
+ *
+ * When no colour icon is registered for the name, a symbolic request is returned WITHOUT
+ * checking the cascade: the mask class falls back to `image-missing` through CSS by itself
+ * and corrects itself when a later `registerIcon` lands, which is how `<gtk-image>` behaved
+ * before this module. The cascade is read only to choose between a colour entry and a
+ * symbolic glyph.
+ */
+export function lookupIcon(iconName: string | null | undefined): IconLookup | null {
+    if (iconName === null || iconName === undefined || iconName === '') return null;
+    const symbolicRequest = SYMBOLIC_SUFFIX.test(iconName);
+    const colorName = symbolicRequest ? iconName.replace(SYMBOLIC_SUFFIX, '') : iconName;
+    const color = colorIcons.get(colorName);
+    const symbolic = normalizeIconName(iconName);
+
+    if (color === undefined) {
+        return symbolic === '' ? { kind: 'missing' } : { kind: 'symbolic', name: symbolic };
+    }
+    if (symbolicRequest && hasSymbolic(symbolic)) return { kind: 'symbolic', name: symbolic };
+    return { kind: 'color', name: colorName, url: color };
+}
+
+/**
+ * Whether `iconName` resolves to something other than `image-missing` — a registered colour
+ * icon, or a symbolic glyph compiled into the stylesheet or registered at runtime.
+ */
+export function iconResolves(iconName: string): boolean {
+    const found = lookupIcon(iconName);
+    if (found === null || found.kind === 'missing') return false;
+    return found.kind === 'color' || hasSymbolic(found.name);
+}
+
+/** `source` as a URL `background-image` can load, or a thrown reason why not. */
+function colorIconUrl(name: string, source: string): string {
+    if (source.trimStart().startsWith('<')) {
+        const root = new DOMParser().parseFromString(source, 'image/svg+xml').documentElement;
+        if (root.tagName !== 'svg') {
+            throw new TypeError(
+                `registerColorIcon(${JSON.stringify(name)}): the source starts with '<' but parsed ` +
+                    `to <${root.tagName}>, not an <svg> root.`,
+            );
+        }
+        return toDataUri(source);
+    }
+
+    let url: URL;
+    try {
+        url = new URL(source, document.baseURI);
+    } catch {
+        throw new TypeError(`registerColorIcon(${JSON.stringify(name)}): the source is neither SVG source nor a URL.`);
+    }
+    const isImageData = url.protocol === 'data:' && /^data:image\//i.test(url.href);
+    if (!isImageData && !ALLOWED_PROTOCOLS.has(url.protocol)) {
+        throw new TypeError(
+            `registerColorIcon(${JSON.stringify(name)}): ${JSON.stringify(url.protocol)} URLs are not ` +
+                'accepted — use http(s):, blob:, file: or a data:image/ URI.',
+        );
+    }
+    return url.href;
+}
+
+/**
+ * Register a FULL-COLOUR icon under `name` — what an application ships in
+ * `hicolor/scalable/apps/<app-id>.svg` and GTK finds through its icon theme. Every
+ * `<gtk-image>` asking for the name draws the image unrecoloured, the way `AdwAboutDialog`'s
+ * `application-icon` does on GNOME.
+ *
+ * `name` is the EXACT icon name, reverse-DNS application IDs included. A name with a
+ * `-symbolic` suffix THROWS: that is the other half of the theme, and {@link registerIcon}
+ * is its door. `source` is SVG source, or a URL (resolved against the document) to any
+ * image the browser can draw.
+ *
+ * Re-registering a name replaces the image, and every mounted `<gtk-image>` redraws.
+ *
+ * CLIENT-SIDE ONLY, like `registerIcon`: it reads `document`.
+ */
+export function registerColorIcon(name: string, source: string): void {
+    if (typeof name !== 'string' || name === '' || /\s/.test(name)) {
+        throw new TypeError(
+            `registerColorIcon: ${JSON.stringify(name)} is not an icon name — it must be non-empty ` +
+                'and contain no whitespace.',
+        );
+    }
+    if (SYMBOLIC_FILE_NAME.test(name)) {
+        throw new TypeError(
+            `registerColorIcon: ${JSON.stringify(name)} names a SYMBOLIC icon, which is recoloured ` +
+                'rather than drawn as-is — register it with registerIcon() instead.',
+        );
+    }
+    if (typeof source !== 'string' || source.trim() === '') {
+        throw new TypeError(`registerColorIcon(${JSON.stringify(name)}): the source is empty.`);
+    }
+
+    colorIcons.set(name, colorIconUrl(name, source));
+    notifyIconThemeChanged();
+}

package/src/index.ts

@@ -89,6 +89,9 @@ export { registerTemplateClass } from './template-classes.js';
 // the way in for an app that needs a glyph this package does not ship — see
 // `icon-registry.ts` for the full recipe.
 export { isIconAvailable, registerIcon } from './icon-registry.js';
+// The full-colour half of the icon theme — an application icon drawn as-is, the web stand-in
+// for an app's `hicolor/…/apps/<app-id>.svg`. See `icon-theme.ts` for the lookup order.
+export { registerColorIcon } from './icon-theme.js';
 
 // THE WIDGET CLASSES ARE REACHABLE ONLY AS `Adw.<Name>` / `Gtk.<Name>` (ADR 0034
 // clause 2 + § Amendment 6). The namespace used to be the LAST line in the file, under a

package/src/navigation-view.spec.ts

@@ -429,4 +429,30 @@ export const AdwNavigationViewTest = async () => {
             host.remove();
         });
     });
+
+    await describe('<adw-navigation-view> GJS-spelled API and declared signals', async () => {
+        await it('push_by_tag and get_visible_page_tag follow the camelCase members', () => {
+            const { adapter, view, host, page } = mountView();
+            adapter.add(page('root'));
+            adapter.add(page('detail'));
+            expect(view.push_by_tag('detail')).toBe(true);
+            expect(view.get_visible_page_tag()).toBe('detail');
+            host.remove();
+        });
+
+        await it('connects `pushed` and `notify::visible-page`', () => {
+            const { adapter, view, host, page } = mountView();
+            adapter.add(page('root'));
+            adapter.add(page('detail'));
+            const api = view as unknown as { connect(s: string, h: () => void): number };
+            let pushed = 0;
+            let visible = 0;
+            api.connect('pushed', () => pushed++);
+            api.connect('notify::visible-page', () => visible++);
+            view.push_by_tag('detail');
+            expect(pushed).toBe(1);
+            expect(visible).toBeGreaterThan(0);
+            host.remove();
+        });
+    });
 };

package/src/shared-tree-builder.ts

@@ -55,7 +55,7 @@ import {
 
 import { observeAdaptiveSize } from './breakpoints.js';
 import { capabilities } from './capabilities.mjs';
-import { endpointOf, hasElementApi, installElementApi } from './gobject-elements.js';
+import { endpointOf, hasElementApi, installElementApi, installSensitive } from './gobject-elements.js';
 import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
 import { isTemplateTag, templateTagFor } from './template-classes.js';
@@ -389,6 +389,7 @@ function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
 /** What a node asks to be wired once every id exists: its binds and its breakpoints. */
 function collectNode(el: HTMLElement, node: SharedTreeNode, record: BuildRecord): void {
     for (const [property, binding] of Object.entries(node.bindings ?? {})) {
+        if (property === 'sensitive') installSensitive(el);
         record.binds.push({
             el,
             property,