@gjsify/adwaita-web 0.55.0 → 0.56.0

package/src/shared-tree-builder.ts

@@ -36,13 +36,21 @@
 
 import { createBreakpointDriver, parseBreakpointCondition, type BreakpointSize } from '@gjsify/adwaita-core';
 import { assertTreeConstructs, type SharedTreeNode } from '@gjsify/adwaita-core/conformance';
-import { GTK_WIDGET_MARGIN_CSS, attributeOf, hostTagOf, propertyOf } from '@gjsify/adwaita-core/tags';
+import {
+    GTK_WIDGET_EXPAND,
+    attributeOf,
+    hostTagOf,
+    isValueBasedBooleanAttr,
+    propertyOf,
+    widgetLengthStyle,
+} from '@gjsify/adwaita-core/tags';
 
 import { observeAdaptiveSize } from './breakpoints.js';
 import { capabilities } from './capabilities.mjs';
 import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
 import { templateTagFor } from './template-classes.js';
+import { writeBooleanAttribute } from './attributes.js';
 
 /** One authored placement, kept so {@link mountSharedTree} can hold the renderer to it. */
 interface PlacedChild {
@@ -104,21 +112,22 @@ function isWritable(el: object, member: string): boolean {
  * A `SharedTreeNode`, realised as a DETACHED element tree: a tag, its authored properties as
  * attributes, its style classes as classes, its extensions (ADR 0072) as the markup the element
  * reads, its placement as `slot=`, its children, in that order — recursive and total,
- * no tag list, no per-block case. A boolean authored property is the ATTRIBUTE'S PRESENCE
- * (`toggleAttribute`), which is what every element in the corpus reads
- * (`hasAttribute('revealed')`, `hasAttribute('expanded')`); spelling `"true"` would set a
- * present attribute for `false` as well.
+ * no tag list, no per-block case.
  *
- * EXCEPT AN AUTHORED `false` ON A PROPERTY THE ELEMENT DECLARES. Absence cannot say `false`
- * where the GTK default is TRUE — `AdwNavigationPage:can-pop`, `GtkActionBar:revealed` —
- * because those elements read an absent attribute as that default, so `can-pop: false`
- * reached the page as `can-pop` unset and the page stayed poppable. The element's own
- * property setter knows its attribute convention, so an authored `false` is written
- * through it when the element (already upgraded: `createElement` of a defined tag
- * constructs it) declares one; everything else keeps the presence rule. "Declares" means a
- * member it can WRITE ({@link isWritable}): a getter-only accessor of the same name — the
- * split button's and the menu button's read-only `active` — would throw a bare `TypeError`
- * out of the assignment, so such a property falls back to the presence rule too.
+ * BOOLEAN ATTRIBUTES are written per (widget, property), not per attribute name. The same
+ * attribute name (e.g. `revealed`) can be VALUE-BASED for one widget (`gtk-action-bar`,
+ * default TRUE) and PRESENCE-BASED for another (`adw-banner`, default FALSE). The
+ * per-widget map in `@gjsify/adwaita-core/tags` ({@link isValueBasedBooleanAttr}) records this.
+ *
+ * - VALUE-BASED: `attr="false"` means false, absent means true (the GTK default).
+ *   The builder writes `attr="true"|"false"` directly via {@link writeBooleanAttribute}.
+ * - PRESENCE-BASED (style classes like `flat`, `round`, `compact`): `toggleAttribute`
+ *   writes the bare attribute for `true`, removes it for `false`.
+ *
+ * EXCEPT an authored `false` on a NON-value-based, WRITABLE property: the property is set
+ * directly (bypassing the attribute) because the element's setter will reflect it correctly.
+ * A getter-only property of the same name (e.g. `AdwSplitButton.active`) falls back to the
+ * presence rule since assignment would throw.
  *
  * THE SLOT IS WRITTEN AS THE ATTRIBUTE THIS RENDERER ALREADY ROUTES ON, not translated:
  * `src/slotted-children.ts` reads `slot=` off every light-DOM child and keeps the routing
@@ -258,16 +267,47 @@ function bindProperty(bind: PendingBind, record: BuildRecord): void {
     from.addEventListener(event, follow);
 }
 
-/** One authored property, written as the element reads it; a breakpoint setter takes the same door. */
-function writeProp(el: HTMLElement, prop: string, value: string | number | boolean): void {
+/**
+ * One authored property, written as the element reads it; a breakpoint setter takes the same door.
+ *
+ * BOOLEAN ATTRIBUTES are written per (widget, property), not per attribute name. The same
+ * attribute name (e.g. `revealed`) can be VALUE-BASED for one widget (`gtk-action-bar`,
+ * default TRUE) and PRESENCE-BASED for another (`adw-banner`, default FALSE). The
+ * per-widget map in `@gjsify/adwaita-core/tags` ({@link isValueBasedBooleanAttr}) records this.
+ *
+ * - VALUE-BASED: `attr="false"` means false, absent means true (the GTK default).
+ *   The builder writes `attr="true"|"false"` directly via {@link writeBooleanAttribute}.
+ * - PRESENCE-BASED (style classes like `flat`, `round`, `compact`): `toggleAttribute`
+ *   writes the bare attribute for `true`, removes it for `false`.
+ *
+ * EXCEPT an authored `false` on a NON-value-based, WRITABLE property: the property is set
+ * directly (bypassing the attribute) because the element's setter will reflect it correctly.
+ * A getter-only property of the same name (e.g. `AdwSplitButton.active`) falls back to the
+ * presence rule since assignment would throw. `hexpand` / `vexpand` keep an authored `false`
+ * as the attribute `"false"` and a later `true` rewrites it — `GTK_WIDGET_EXPAND` says why.
+ */
+export function writeProp(el: HTMLElement, prop: string, value: string | number | boolean): void {
+    const attr = attributeOf(prop);
     const member = propertyOf(prop);
-    if (value === false && isWritable(el, member)) (el as unknown as Record<string, unknown>)[member] = false;
-    else if (typeof value === 'boolean') el.toggleAttribute(attributeOf(prop), value);
-    else el.setAttribute(attributeOf(prop), String(value));
-    // A margin is also inline style (`GTK_WIDGET_MARGIN_CSS` says why); the attribute
-    // stays, since it is what the tree authored and what a reader of the DOM looks for.
-    const margin = GTK_WIDGET_MARGIN_CSS[attributeOf(prop)];
-    if (margin !== undefined) el.style.setProperty(margin, `${Number(value)}px`);
+    const expand = GTK_WIDGET_EXPAND.find((name) => name === attr);
+    if (expand !== undefined && typeof value === 'boolean') el.setAttribute(expand, value ? '' : 'false');
+    else if (typeof value === 'boolean' && isValueBasedBooleanAttr(el.localName, attr)) {
+        writeBooleanAttribute(el, attr, value);
+    } else if (value === false && isWritable(el, member)) {
+        // Non-value-based, writable property: set the property directly (bypasses attribute).
+        (el as unknown as Record<string, unknown>)[member] = false;
+    } else if (typeof value === 'boolean') {
+        // Presence-based (style classes) or true for non-value-based: use toggleAttribute.
+        el.toggleAttribute(attr, value);
+    } else {
+        el.setAttribute(attr, String(value));
+    }
+    // A margin or a size request is also inline style (`GTK_WIDGET_MARGIN_CSS` says why); the
+    // attribute stays, since it is what the tree authored and what a reader of the DOM looks for.
+    const length = widgetLengthStyle(attr, value);
+    if (length === undefined) return;
+    if (length[1] === null) el.style.removeProperty(length[0]);
+    else el.style.setProperty(length[0], length[1]);
 }
 
 function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
@@ -452,24 +492,37 @@ function refuseUnknownSlots(placed: readonly PlacedChild[]): void {
 export interface MountedSharedTree {
     /** The authored root — connected, so every custom element under it has upgraded and run. */
     root: HTMLElement;
-    /** Disconnects and discards the mount point. */
+    /** Disconnects the tree, and discards the mount point when this call made one. */
     unmount: () => void;
 }
 
+/** What {@link mountSharedTree} takes beside the tree. */
+export interface MountOptions {
+    /** 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;
+    /**
+     * Where the root is appended — a showcase's own container, which then lays the window out.
+     * Without it the tree gets a fresh host `<div>` in `document.body`, discarded on `unmount`.
+     */
+    into?: HTMLElement;
+}
+
 /**
  * {@link buildSharedTree}, attached under a fresh host `<div>` in `document.body` so the tree
  * — and every custom element in it — is REAL rather than merely constructed. This is the
  * instantiation half a caller reading the corpus's elements normally wants; a bare
  * `buildSharedTree` is for a caller that already has somewhere of its own to attach it.
  */
-export function mountSharedTree(
-    node: SharedTreeNode,
-    options: { scope?: Readonly<Record<string, unknown>>; observeSize?: SizeSource } = {},
-): MountedSharedTree {
-    const host = document.createElement('div');
+export function mountSharedTree(node: SharedTreeNode, options: MountOptions = {}): MountedSharedTree {
+    const { into } = options;
+    const host = into ?? document.createElement('div');
     const record = newRecord(options.scope, options.observeSize);
-    host.append(buildSharedTree(node, record));
-    document.body.append(host);
+    const root = buildSharedTree(node, record);
+    host.append(root);
+    if (into === undefined) document.body.append(host);
+    const discard = () => (into === undefined ? host : root).remove();
     // After the append, because that is what upgrades the elements and runs the binds the
     // refusal reads; before the return, because a caller handed a tree back has no way left
     // to tell a placement that was honoured from one that was dropped.
@@ -478,14 +531,14 @@ export function mountSharedTree(
         refuseUnheldExtensions(record.extended);
     } catch (error) {
         for (const dispose of record.disposers) dispose();
-        host.remove();
+        discard();
         throw error;
     }
     return {
-        root: host.firstElementChild as HTMLElement,
+        root,
         unmount: () => {
             for (const dispose of record.disposers) dispose();
-            host.remove();
+            discard();
         },
     };
 }

package/src/shared-tree-mount.spec.ts

@@ -0,0 +1,130 @@
+// A showcase window mounted from its tree (ADR 0093): the shape every showcase `.blp` writes — a
+// toggle button and a split view that bind to each other, two breakpoints that collapse the split
+// view, and a window sized by `default-width`. What is held here is the exact cycle the showcases
+// rely on, and `into`, the container a showcase mounts its window in.
+import { describe, expect, it } from '@gjsify/unit';
+import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+
+import { mountSharedTree } from './shared-tree-builder.js';
+
+/** Wait for a ResizeObserver delivery (it runs after layout, before paint). */
+function settle(): Promise<void> {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+/** The showcase window, sized by `default-width` and adapting at 800sp. */
+const tree = (width: number): SharedTreeNode => ({
+    tag: 'AdwApplicationWindow',
+    props: { 'default-width': width, 'default-height': 400 },
+    breakpoints: [
+        {
+            condition: 'max-width: 799sp',
+            setters: [
+                { object: 'splitView', property: 'collapsed', value: true },
+                { object: 'splitView', property: 'show-sidebar', value: false },
+            ],
+        },
+        {
+            condition: 'min-width: 800sp',
+            setters: [
+                { object: 'splitView', property: 'collapsed', value: false },
+                { object: 'splitView', property: 'show-sidebar', value: true },
+            ],
+        },
+    ],
+    children: [
+        {
+            tag: 'GtkBox',
+            slot: 'content',
+            children: [
+                {
+                    tag: 'GtkToggleButton',
+                    id: 'sidebarToggleButton',
+                    bindings: { active: { source: 'splitView', property: 'show-sidebar' } },
+                },
+                {
+                    tag: 'AdwOverlaySplitView',
+                    id: 'splitView',
+                    bindings: { 'show-sidebar': { source: 'sidebarToggleButton', property: 'active' } },
+                    children: [
+                        { tag: 'GtkBox', slot: 'sidebar' },
+                        { tag: 'GtkBox', slot: 'content' },
+                    ],
+                },
+            ],
+        },
+    ],
+});
+
+type SplitView = HTMLElement & { showSidebar: boolean; collapsed: boolean };
+type Toggle = HTMLElement & { active: boolean };
+
+export const AdwSharedTreeMountTest = async () => {
+    await describe('adwaita-web: a showcase window mounted from its tree', async () => {
+        await it('<adw-overlay-split-view> raises notify::show-sidebar once per real change', () => {
+            const view = document.createElement('adw-overlay-split-view') as SplitView;
+            document.body.append(view);
+            const seen: boolean[] = [];
+            view.addEventListener('notify::show-sidebar', (event) => {
+                seen.push((event as CustomEvent<{ showSidebar: boolean }>).detail.showSidebar);
+            });
+            view.showSidebar = true;
+            view.showSidebar = false;
+            view.showSidebar = false;
+            view.showSidebar = true;
+            view.remove();
+            expect(seen).toStrictEqual([false, true]);
+        });
+
+        await it('a wide window keeps the sidebar and the toggle follows the split view', async () => {
+            const { root, unmount } = mountSharedTree(tree(1100));
+            await settle();
+            const split = root.querySelector('#splitView') as SplitView;
+            expect(root.getBoundingClientRect().width).toBe(1100);
+            expect(split.collapsed).toBe(false);
+            expect(split.showSidebar).toBe(true);
+            expect((root.querySelector('#sidebarToggleButton') as Toggle).active).toBe(true);
+            unmount();
+        });
+
+        await it('a narrow window collapses the split view and the toggle follows it', async () => {
+            const { root, unmount } = mountSharedTree(tree(500));
+            await settle();
+            const split = root.querySelector('#splitView') as SplitView;
+            expect(split.collapsed).toBe(true);
+            expect(split.showSidebar).toBe(false);
+            expect((root.querySelector('#sidebarToggleButton') as Toggle).active).toBe(false);
+            unmount();
+        });
+
+        await it('the toggle drives the split view back, and the cycle settles', async () => {
+            const { root, unmount } = mountSharedTree(tree(1100));
+            await settle();
+            const toggle = root.querySelector('#sidebarToggleButton') as Toggle;
+            const split = root.querySelector('#splitView') as SplitView;
+            toggle.active = false;
+            expect(split.showSidebar).toBe(false);
+            split.showSidebar = true;
+            expect(toggle.active).toBe(true);
+            toggle.active = false;
+            toggle.active = true;
+            expect(split.showSidebar).toBe(true);
+            expect(split.getAttribute('show-sidebar')).toBe('');
+            unmount();
+        });
+
+        await it('a tree mounted into a container lives in it, and unmount takes only the tree', () => {
+            const container = document.createElement('div');
+            document.body.append(container);
+            const { root, unmount } = mountSharedTree(tree(1100), { into: container });
+            expect(root.parentElement).toBe(container);
+            expect(container.querySelector('adw-application-window')).toBe(root);
+            unmount();
+            expect(container.childElementCount).toBe(0);
+            expect(container.isConnected).toBe(true);
+            container.remove();
+        });
+    });
+};

package/src/shared-trees.spec.ts

@@ -295,6 +295,21 @@ export const AdwSharedTreesTest = async () => {
             });
         });
 
+        await it('Adw.Banner with revealed: false stays closed — attribute must be absent, not "false"', () => {
+            const tree = blueprintTree(`Adw.Banner {
+                title: "Test";
+                revealed: false;
+            }`);
+            mounted(tree, (root) => {
+                const banner = root as HTMLElement;
+                // The banner reads 'revealed' by PRESENCE (hasAttribute), so the attribute must be absent.
+                // Currently the builder writes revealed="false", which makes hasAttribute return true.
+                expect(banner.hasAttribute('revealed')).toBe(false);
+                expect(banner.classList.contains('revealed')).toBe(false);
+                expect(getComputedStyle(banner).display).toBe('none');
+            });
+        });
+
         await it('an authored false on a getter-only property keeps the presence rule instead of throwing', () => {
             // `<adw-split-button>` exposes `active` as a read-only getter; assigning through it
             // threw a bare TypeError out of the builder before the writability check.