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

package/src/learn6502-window.spec.ts

@@ -0,0 +1,113 @@
+// Learn6502's `main.window.blp`, reduced to the shapes that rendered short through
+// `buildWithSiblings`: header-bar buttons after a single `[start]` (GtkBuilder packs an untyped
+// child at start too), and `Overlay { child: Adw.ToastOverlay { Stack } }`. Every
+// widget the file authors has to be in the document once the built window is attached — the
+// failure was widgets that were built and then silently dropped on the way.
+import { describe, expect, it } from '@gjsify/unit';
+import { parseBlueprint, projectToSharedNode } from '@gjsify/blueprint';
+
+import { buildWithSiblings } from './shared-tree-builder.js';
+
+const BLUEPRINT = `using Gtk 4.0;
+using Adw 1;
+
+Adw.ApplicationWindow mainWindow {
+  content: Adw.ToolbarView toolbarView {
+    [top]
+    Adw.HeaderBar headerBar {
+      title-widget: Label titleLabel {
+        label: "Learn 6502";
+      };
+
+      [start]
+      ToggleButton sidebarToggleButton {
+        icon-name: "sidebar-show-symbolic";
+      }
+
+      Button learnBackButton {
+        icon-name: "go-previous-symbolic";
+      }
+
+      Button unsavedChangesIndicator {
+        icon-name: "dot-symbolic";
+      }
+
+      [end]
+      MenuButton menuButton {
+        icon-name: "open-menu-symbolic";
+      }
+    }
+
+    content: Overlay mainOverlay {
+      child: Adw.ToastOverlay toastOverlay {
+        Stack layoutHost {
+          StackPage singlePage {
+            name: "single";
+            child: Adw.Bin singleContainer {
+              child: Label singleLabel {
+                label: "single";
+              };
+            };
+          }
+
+          StackPage threePage {
+            name: "three";
+            child: Adw.Bin threeColumnContainer {
+              child: Box threeColumns {
+                Label threeLabel {
+                  label: "three";
+                }
+              };
+            };
+          }
+        }
+      };
+    };
+  };
+}
+`;
+
+const AUTHORED = [
+    'toolbarView',
+    'headerBar',
+    'titleLabel',
+    'sidebarToggleButton',
+    'learnBackButton',
+    'unsavedChangesIndicator',
+    'menuButton',
+    'mainOverlay',
+    'toastOverlay',
+    'layoutHost',
+    'singleContainer',
+    'singleLabel',
+    'threeColumnContainer',
+    'threeColumns',
+    'threeLabel',
+];
+
+export const AdwLearn6502WindowTest = async () => {
+    await describe("Learn6502's main window through buildWithSiblings", async () => {
+        const { node, lost } = projectToSharedNode(parseBlueprint(BLUEPRINT, 'main.window.blp'));
+
+        await it('projects without losing anything', () => {
+            expect(lost.map((loss) => `${loss.kind}@${loss.line}`).join()).toBe('');
+        });
+
+        await it('puts every authored widget in the document, the start buttons at start', () => {
+            const { root } = buildWithSiblings(node);
+            document.body.append(root);
+            const missing = AUTHORED.filter((id) => !root.querySelector(`#${id}`)?.isConnected);
+            const start = ['sidebarToggleButton', 'learnBackButton', 'unsavedChangesIndicator'].filter(
+                (id) => root.querySelector(`#${id}`)?.parentElement?.className !== 'adw-header-bar-start',
+            );
+            const toast = root.querySelector('#toastOverlay');
+            const overlaid =
+                toast?.closest('.adw-overlay-child') === root.querySelector('#mainOverlay > .adw-overlay-child');
+            root.remove();
+
+            expect(missing.join()).toBe('');
+            expect(start.join()).toBe('');
+            expect(overlaid).toBe(true);
+        });
+    });
+};

package/src/namespace/adw.ts

@@ -111,4 +111,4 @@ export { AdwWindowTitle as WindowTitle } from '../elements/adw-window-title.js';
 export { AdwWrapBox as WrapBox } from '../elements/adw-wrap-box.js';
 export { AdwApplication as Application } from '../application.js';
 export { AdwStyleManager as StyleManager } from '../style-manager.js';
-export { ColorScheme } from '@gjsify/adwaita-core';
+export { ColorScheme, Toast, ToastPriority } from '@gjsify/adwaita-core';

package/src/namespace/gtk.ts

@@ -86,6 +86,7 @@ export { GtkSeparator as Separator } from '../elements/gtk-separator.js';
 export { GtkSpinButton as SpinButton } from '../elements/gtk-spin-button.js';
 export { GtkSpinner as Spinner } from '../elements/gtk-spinner.js';
 export { GtkStack as Stack } from '../elements/gtk-stack.js';
+export { GtkStackPage as StackPage } from '../elements/gtk-stack-page.js';
 export { GtkStackSidebar as StackSidebar } from '../elements/gtk-stack-sidebar.js';
 export { GtkStackSwitcher as StackSwitcher } from '../elements/gtk-stack-switcher.js';
 export { GtkStringList as StringList } from '@gjsify/adwaita-core';
@@ -101,6 +102,7 @@ export type { WindowCommon } from '@gjsify/adwaita-core';
 export { GtkWindowControls as WindowControls } from '../elements/gtk-window-controls.js';
 export { GtkViewport as Viewport } from '../elements/gtk-viewport.js';
 export { GtkWindowHandle as WindowHandle } from '../elements/gtk-window-handle.js';
+export { ApplicationInhibitFlags } from '@gjsify/adwaita-core';
 export { GtkApplication as Application } from '../application.js';
 export {
     STYLE_PROVIDER_PRIORITY_APPLICATION,

package/src/shared-tree-builder.ts

@@ -55,7 +55,14 @@ import {
 
 import { observeAdaptiveSize } from './breakpoints.js';
 import { capabilities } from './capabilities.mjs';
-import { endpointOf, hasElementApi, installElementApi, installSensitive } from './gobject-elements.js';
+import {
+    endpointOf,
+    hasElementApi,
+    hasInstalledVisible,
+    installElementApi,
+    installSensitive,
+    installVisible,
+} from './gobject-elements.js';
 import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
 import { isTemplateTag, templateTagFor } from './template-classes.js';
@@ -154,14 +161,93 @@ function isWritable(el: object, member: string): boolean {
  * upgraded has declared no slots yet, so the refusal below belongs to the mount.
  */
 export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = newRecord()): HTMLElement {
+    refuseSiblings(node, 'buildSharedTree');
+    return buildTree(node, record).root;
+}
+
+/** What {@link buildWithSiblings} hands back: the root element and the objects built beside it. */
+export interface BuiltTree {
+    /** The element the tree roots at, as {@link buildSharedTree} returns it. */
+    root: HTMLElement;
+    /**
+     * The sibling objects by id — `Adw.AlertDialog unsavedChangesDialog { }` or `$Learn learn { }`
+     * written after the template. A sibling is built in the root's id scope (a setter or a bind
+     * may name it) but is no child of the root: the code beside the file decides where, or
+     * whether, it is placed.
+     */
+    siblings: ReadonlyMap<string, HTMLElement>;
+    /** Every element the tree names by id, siblings included: what `GtkBuilder.get_object` answers for. */
+    objects: ReadonlyMap<string, HTMLElement>;
+}
+
+/** What {@link buildWithSiblings} takes beside the tree. */
+export interface BuildOptions {
+    /** The object a handler NAME is looked up on (ADR 0093 § 3). */
+    scope?: Readonly<Record<string, unknown>>;
+    /** The size source a `breakpoints` node is driven from. */
+    observeSize?: SizeSource;
+}
+
+/**
+ * A tree with sibling roots (ADR 0093): the root element, and each sibling by id, all DETACHED
+ * like {@link buildSharedTree}'s result.
+ *
+ * {@link buildSharedTree}, {@link mountSharedTree} and {@link buildTemplateTree} refuse such a
+ * tree by name, because they return one element and the siblings would be built and then thrown
+ * away. A sibling with no id is refused too: nothing could ever ask for it, which is how a
+ * dropped object looks finished.
+ */
+export function buildWithSiblings(node: SharedTreeNode, options: BuildOptions = {}): BuiltTree {
+    const record = newRecord(options.scope, options.observeSize);
+    const built = buildTree(node, record);
+    // An element declares its slots when it is connected, so a detached tree cannot be checked
+    // as it stands. It is connected for the length of the check and handed back detached, as
+    // documented: a placement the renderer could not honour is refused here, like
+    // `mountSharedTree` refuses it, instead of surfacing as a widget missing from the page.
+    const probe = document.createElement('div');
+    probe.hidden = true;
+    probe.append(built.root, ...built.siblings.values());
+    document.body.append(probe);
+    try {
+        refuseUnknownSlots(record.placed);
+        refuseUnheldExtensions(record.extended);
+    } catch (error) {
+        for (const dispose of record.disposers) dispose();
+        throw error;
+    } finally {
+        probe.remove();
+        for (const el of [built.root, ...built.siblings.values()]) el.remove();
+    }
+    return built;
+}
+
+function refuseSiblings(node: SharedTreeNode, door: string): void {
+    if ((node.siblings?.length ?? 0) === 0) return;
+    throw new Error(
+        `\`${node.tag}\` carries ${node.siblings!.length} sibling object(s), and \`${door}\` returns one object ` +
+            'so they would be built and lost. Use `buildWithSiblings`, which hands them back by id.',
+    );
+}
+
+/** Every node, its siblings in the same id scope, then the binds and breakpoints that name them. */
+function buildTree(node: SharedTreeNode, record: BuildRecord): BuiltTree {
     // ADR 0093 § 2: the whole tree is checked against the capability table before an element is
     // created. A refused `layout` is named with its node and the reason the table gives.
     assertTreeConstructs('adwaita-web', capabilities, node);
     if (node.menus !== undefined) record.menus = node.menus;
     const root = buildNode(node, record);
+    const siblings = new Map<string, HTMLElement>();
+    for (const sibling of node.siblings ?? []) {
+        if (sibling.id === undefined) {
+            throw new Error(
+                `the sibling \`${sibling.tag}\` has no id, so nothing could ever ask for it: give it one in the .blp.`,
+            );
+        }
+        siblings.set(sibling.id, buildNode(sibling, record));
+    }
     for (const bind of record.binds) bindProperty(bind, record);
     for (const host of record.breakpointHosts) bindBreakpoints(host.el, host.node, record);
-    return root;
+    return { root, siblings, objects: new Map(record.ids) };
 }
 
 /** A fresh record, with the scope when the caller has one. */
@@ -344,7 +430,9 @@ export function writeProp(el: HTMLElement, prop: string, value: string | number
     const member = propertyOf(prop);
     const expand = GTK_WIDGET_EXPAND.find((name) => name === attr);
     if (expand !== undefined && typeof value === 'boolean') el.setAttribute(expand, value ? '' : 'false');
-    else if (isTemplateTag(el.localName) && member in el) {
+    else if (attr === 'visible' && typeof value === 'boolean' && hasInstalledVisible(el)) {
+        (el as unknown as Record<string, unknown>)[member] = value;
+    } else if (isTemplateTag(el.localName) && member in el) {
         // An application class has no attributeChangedCallback: its properties are GObject properties,
         // set the way `Gtk.Builder` sets them, after the constructor.
         (el as unknown as Record<string, unknown>)[member] = value;
@@ -372,9 +460,14 @@ function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
     const el = document.createElement(node.extern === true ? templateTagFor(node.tag) : hostTagOf(node.tag));
     // A template's children talk GObject to the template: `connect`, `emit`, `notify` (ADR 0096).
     if (record.template !== undefined) installElementApi(el);
+    // `Gtk.Widget:visible`, which no element spells: a setter's target and an authored `false` need it.
+    installVisible(el);
     // The id is how the TypeScript beside a `.blp` reaches this element
     // (`root.querySelector('#…')`), the counterpart of `InternalChildren` on GTK.
     if (node.id !== undefined) {
+        if (record.ids.has(node.id)) {
+            throw new Error(`Two nodes of this tree carry the id '${node.id}'; GtkBuilder refuses a duplicate id.`);
+        }
         el.id = node.id;
         record.ids.set(node.id, el);
     }
@@ -492,6 +585,7 @@ export interface BuiltTemplateTree {
  * belong to the first `connectedCallback`.
  */
 export function buildTemplateTree(tree: SharedTreeNode, scope: TemplateScope, host: HTMLElement): BuiltTemplateTree {
+    refuseSiblings(tree, 'buildTemplateTree');
     assertTreeConstructs('adwaita-web', capabilities, tree);
     const record = newRecord(undefined, undefined, scope);
     record.menus = tree.menus;
@@ -591,9 +685,9 @@ function writeExtensions(el: HTMLElement, node: SharedTreeNode): void {
 
 /** The response API an element answers to — `<adw-alert-dialog>`'s, named after libadwaita's. */
 interface ResponseReader {
-    getResponseLabel(id: string): string | null;
-    getResponseAppearance(id: string): string | null;
-    getResponseEnabled(id: string): boolean;
+    get_response_label(id: string): string | null;
+    get_response_appearance(id: string): string | null;
+    get_response_enabled(id: string): boolean;
 }
 
 /**
@@ -617,10 +711,10 @@ function refuseUnheldExtensions(extended: readonly ExtendedNode[]): void {
         const reader = el as unknown as Partial<ResponseReader>;
         for (const response of node.extensions?.responses ?? []) {
             const held =
-                typeof reader.getResponseLabel === 'function' &&
-                reader.getResponseLabel(response.id) === response.label &&
-                reader.getResponseAppearance?.(response.id) === (response.appearance ?? 'default') &&
-                reader.getResponseEnabled?.(response.id) === (response.enabled ?? true);
+                typeof reader.get_response_label === 'function' &&
+                reader.get_response_label(response.id) === response.label &&
+                reader.get_response_appearance?.(response.id) === (response.appearance ?? 'default') &&
+                reader.get_response_enabled?.(response.id) === (response.enabled ?? true);
             if (!held) {
                 throw new Error(
                     `<${el.localName}> did not register the response "${response.id}" as authored, so the ` +
@@ -696,6 +790,7 @@ export interface MountOptions {
  * `buildSharedTree` is for a caller that already has somewhere of its own to attach it.
  */
 export function mountSharedTree(node: SharedTreeNode, options: MountOptions = {}): MountedSharedTree {
+    refuseSiblings(node, 'mountSharedTree');
     const { into } = options;
     const host = into ?? document.createElement('div');
     const record = newRecord(options.scope, options.observeSize);

package/src/shared-trees.spec.ts

@@ -54,7 +54,7 @@ import { ADWAITA_GALLERY_SHARED_TREES } from '../../../../scripts/adwaita-galler
 
 import '@gjsify/adwaita-web';
 
-import { mountSharedTree } from './shared-tree-builder.js';
+import { buildWithSiblings, mountSharedTree } from './shared-tree-builder.js';
 
 /**
  * Connect the authored root — these elements build on connect — run, and take it down again.
@@ -364,6 +364,20 @@ export const AdwSharedTreesTest = async () => {
             ).toThrow('has no slot "middle"');
         });
 
+        // The detached door refuses it too: a root built and handed back is mounted by the
+        // caller, after the builder could still say anything.
+        await it('`buildWithSiblings` refuses the same placement, and hands a good tree back detached', () => {
+            const bad = { tag: 'AdwToolbarView', children: [{ tag: 'AdwBanner', slot: 'middle' }] };
+            expect(() => buildWithSiblings(bad)).toThrow('has no slot "middle"');
+            const { root, siblings } = buildWithSiblings({
+                tag: 'AdwToolbarView',
+                children: [{ tag: 'AdwBanner', slot: 'top' }],
+                siblings: [{ tag: 'GtkLabel', id: 'beside' }],
+            });
+            expect(root.isConnected || siblings.get('beside')!.isConnected).toBe(false);
+            expect(root.querySelector('adw-banner') !== null).toBe(true);
+        });
+
         // ADR 0092's `layout { }`: a grid child's cell. GTK counts from 0, CSS Grid from 1.
         await it('`layout { }` places a grid child in its cell, spans defaulting to one', () => {
             mounted(

package/src/slotted-children.spec.ts

@@ -113,6 +113,30 @@ export const AdwSlottedChildrenTest = async () => {
             expect(report).toBe('[1]');
         });
 
+        // The DECLARED twin of the case above. `install()` replaces the host's children with
+        // its structure, and a child no slot took used to go with them — gone without a word.
+        await it('keeps a declared child no slot takes, and warns that it was not placed', () => {
+            const host = document.createElement('div');
+            const typo = probe('sied', 'a');
+            host.append(document.createTextNode('\n  '), typo);
+            mounted(host);
+            const side = document.createElement('div');
+            side.className = 'side';
+
+            const warned: string[] = [];
+            const warn = console.warn;
+            console.warn = (...args: unknown[]) => void warned.push(args.join(' '));
+            try {
+                bindSlottedChildren(host, [{ name: 'side', into: side }]).install(side);
+            } finally {
+                console.warn = warn;
+            }
+
+            const report = `${placement(host, typo)} | ${warned.join()}`;
+            host.remove();
+            expect(report).toBe("[1] | 'sied' is not a valid child type of 'div'");
+        });
+
         await it('re-adopts a child that was appended, removed and appended again', async () => {
             const host = mounted(document.createElement('div'));
             const side = document.createElement('div');

package/src/slotted-children.ts

@@ -113,6 +113,12 @@ export interface AdwSlottedChildren {
 /** Where a bound host's slots can be read back from — see {@link slottedChildrenOf}. */
 const BOUND = new WeakMap<Element, AdwSlottedChildren>();
 
+/** An element or a text node with something in it — markup's indentation and comments are not. */
+function isContent(node: Node): boolean {
+    if (node instanceof Element) return true;
+    return node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '';
+}
+
 /**
  * The slot binding `host` installed, if it has one.
  *
@@ -184,9 +190,19 @@ export function bindSlottedChildren(
         slots,
         slotFor,
         install(...nodes: readonly Node[]) {
-            for (const node of Array.from(host.childNodes)) route(node);
+            const unplaced: Node[] = [];
+            for (const node of Array.from(host.childNodes)) {
+                if (route(node) !== null || node.parentNode !== host || !isContent(node)) continue;
+                // `replaceChildren` below would delete it, and a child the author wrote that
+                // vanishes without a word is the silent drop this used to be. It stays beside
+                // the structure, as a late child with the same slot does, and says so the
+                // way GtkBuilder does (GTK_BUILDER_WARN_INVALID_CHILD_TYPE).
+                unplaced.push(node);
+                const type = node instanceof Element ? (node.getAttribute('slot') ?? '') : '';
+                console.warn(`'${type}' is not a valid child type of '${host.localName}'`);
+            }
             structure = new Set(nodes);
-            host.replaceChildren(...nodes);
+            host.replaceChildren(...nodes, ...unplaced);
             // Armed AFTER `replaceChildren`, so its own records are never delivered: an
             // observer armed first would see the whole of `structure` as added nodes and
             // spend a microtask rejecting them.