@gjsify/adwaita-web 0.31.0 → 0.32.0

package/src/elements/adw-toggle-group.ts

@@ -21,10 +21,13 @@
 // Reference: refs/adwaita-web/adwaita-web/scss/_toggle_group.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
-// selection state machine composed from @gjsify/adwaita-core.
+// selection state machine composed from @gjsify/adwaita-core, the icon node
+// from <adw-icon>.
 
 import { ToggleGroupState } from '@gjsify/adwaita-core';
 
+import { createAdwIcon } from './adw-icon.js';
+
 /** A single toggle. Children of <adw-toggle-group>; consumed at connect time. */
 export class AdwToggle extends HTMLElement {
     static get observedAttributes() {
@@ -70,12 +73,7 @@ export class AdwToggleGroup extends HTMLElement {
 
             const label = toggle.getAttribute('label') ?? '';
             const icon = toggle.getAttribute('icon-name') ?? '';
-            if (icon) {
-                const span = document.createElement('span');
-                span.className = `adw-icon adw-icon--${icon}`;
-                span.setAttribute('aria-hidden', 'true'); // decorative (mask-image only)
-                btn.appendChild(span);
-            }
+            if (icon) btn.appendChild(createAdwIcon(icon));
             if (label) btn.appendChild(document.createTextNode(label));
 
             // An icon-only toggle has no text — give it an accessible name.

package/src/elements/adw-toolbar-view.ts

@@ -1,17 +1,46 @@
-// <adw-toolbar-view> — A content area framed by flat top and/or bottom bars
+// <adw-toolbar-view> — A content area framed by top and/or bottom bars
 // (typically header bars). Mirrors Adw.ToolbarView.
 // Slots: slot="top" (top bars, stacked), slot="bottom" (bottom bars), and any
 //   remaining children become the scrollable content.
-// Reference: refs/adwaita-web/adwaita-web/docs/widgets/toolbarview.md
+// Attributes: top-bar-style / bottom-bar-style (flat | raised | raised-border),
+//   extend-content-to-top-edge, extend-content-to-bottom-edge (boolean).
+//
+// The four style classes libadwaita derives — `raised` and `border` on a bar box,
+// `undershoot-top` / `undershoot-bottom` on the view — come from
+// `@gjsify/adwaita-core`'s `toolbarViewClasses`. Neither renderer had any of them,
+// so a toolbar view looked identical in all three styles and the scroll fade under
+// a flat bar was missing entirely.
+//
+// The undershoot decision reads the ALLOCATED bar heights, exactly as
+// `update_undershoots` reads `gtk_widget_get_height (self->top_bar)` — so the
+// classes are recomputed whenever a bar box resizes, not once at connect time.
+// The allocation itself stays with the browser: flexbox is the layout manager
+// here, and `toolbarViewAllocate` is the specification it is measured against
+// (see `@gjsify/adwaita-core/conformance`), not a second layout pass fighting it.
+//
+// Reference: refs/libadwaita/src/adw-toolbar-view.c (update_undershoots, style setters)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_toolbars.scss
+// Reference: refs/adwaita-web/adwaita-web/docs/widgets/toolbarview.md
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import {
+    ADW_TOOLBAR_BAR_CLASSES,
+    ADW_TOOLBAR_VIEW_CLASSES,
+    parseToolbarStyle,
+    toolbarViewClasses,
+} from '@gjsify/adwaita-core';
+
 export class AdwToolbarView extends HTMLElement {
     private _topEl!: HTMLDivElement;
     private _contentEl!: HTMLDivElement;
     private _bottomEl!: HTMLDivElement;
     private _initialized = false;
+    private _resize: ResizeObserver | null = null;
+
+    static get observedAttributes() {
+        return ['top-bar-style', 'bottom-bar-style', 'extend-content-to-top-edge', 'extend-content-to-bottom-edge'];
+    }
 
     /** The top-bar container — append header bars here imperatively. */
     get topBar(): HTMLDivElement {
@@ -29,31 +58,65 @@ export class AdwToolbarView extends HTMLElement {
     }
 
     connectedCallback() {
-        if (this._initialized) return;
-        this._initialized = true;
+        if (!this._initialized) {
+            this._initialized = true;
+
+            const topChildren = Array.from(this.querySelectorAll(':scope > [slot="top"]'));
+            const bottomChildren = Array.from(this.querySelectorAll(':scope > [slot="bottom"]'));
+            const contentChildren = Array.from(this.childNodes).filter(
+                (n) => !topChildren.includes(n as Element) && !bottomChildren.includes(n as Element),
+            );
+
+            this._topEl = document.createElement('div');
+            this._topEl.className = 'adw-toolbar-view-top';
+            for (const child of topChildren) this._topEl.appendChild(child);
 
-        const topChildren = Array.from(this.querySelectorAll(':scope > [slot="top"]'));
-        const bottomChildren = Array.from(this.querySelectorAll(':scope > [slot="bottom"]'));
-        const contentChildren = Array.from(this.childNodes).filter(
-            (n) => !topChildren.includes(n as Element) && !bottomChildren.includes(n as Element),
-        );
+            this._contentEl = document.createElement('div');
+            this._contentEl.className = 'adw-toolbar-view-content';
+            for (const child of contentChildren) this._contentEl.appendChild(child);
 
-        this._topEl = document.createElement('div');
-        this._topEl.className = 'adw-toolbar-view-top';
-        for (const child of topChildren) this._topEl.appendChild(child);
+            this._bottomEl = document.createElement('div');
+            this._bottomEl.className = 'adw-toolbar-view-bottom';
+            for (const child of bottomChildren) this._bottomEl.appendChild(child);
 
-        this._contentEl = document.createElement('div');
-        this._contentEl.className = 'adw-toolbar-view-content';
-        for (const child of contentChildren) this._contentEl.appendChild(child);
+            this._topEl.hidden = this._topEl.childElementCount === 0;
+            this._bottomEl.hidden = this._bottomEl.childElementCount === 0;
 
-        this._bottomEl = document.createElement('div');
-        this._bottomEl.className = 'adw-toolbar-view-bottom';
-        for (const child of bottomChildren) this._bottomEl.appendChild(child);
+            this.replaceChildren(this._topEl, this._contentEl, this._bottomEl);
+        }
+
+        // `update_undershoots` runs from size_allocate, so the classes have to
+        // follow the bars' real heights rather than a one-shot read.
+        this._resize = new ResizeObserver(() => this._syncClasses());
+        this._resize.observe(this._topEl);
+        this._resize.observe(this._bottomEl);
+        this._syncClasses();
+    }
+
+    disconnectedCallback() {
+        this._resize?.disconnect();
+        this._resize = null;
+    }
+
+    attributeChangedCallback() {
+        if (this._initialized) this._syncClasses();
+    }
 
-        this._topEl.hidden = this._topEl.childElementCount === 0;
-        this._bottomEl.hidden = this._bottomEl.childElementCount === 0;
+    private _syncClasses(): void {
+        const { view, topBar, bottomBar } = toolbarViewClasses({
+            topBarStyle: parseToolbarStyle(this.getAttribute('top-bar-style')),
+            bottomBarStyle: parseToolbarStyle(this.getAttribute('bottom-bar-style')),
+            extendContentToTopEdge: this.hasAttribute('extend-content-to-top-edge'),
+            extendContentToBottomEdge: this.hasAttribute('extend-content-to-bottom-edge'),
+            topBarHeight: this._topEl.offsetHeight,
+            bottomBarHeight: this._bottomEl.offsetHeight,
+        });
 
-        this.replaceChildren(this._topEl, this._contentEl, this._bottomEl);
+        for (const cls of ADW_TOOLBAR_VIEW_CLASSES) this.classList.toggle(cls, view.includes(cls));
+        for (const cls of ADW_TOOLBAR_BAR_CLASSES) {
+            this._topEl.classList.toggle(cls, topBar.includes(cls));
+            this._bottomEl.classList.toggle(cls, bottomBar.includes(cls));
+        }
     }
 }
 

package/src/elements/adw-view-stack.ts

@@ -6,139 +6,168 @@
 // their own pages (<adw-view-switcher>, <adw-inline-view-switcher>) but no
 // standalone stack a separate switcher can drive.
 //
-// Pages are declared as <adw-view-stack-page> children with `name`, `title` and
-// `icon-name` attributes (their own children become the page body), OR added
-// imperatively with `add(content, name, title?, icon?)`. The first page added
-// is shown automatically.
+// The SELECTION itself — the name lookup, the guards on an index change, the
+// first-visible-page auto-pick and which paths notify — is HEADLESS and lives in
+// `@gjsify/adwaita-core` (ADR 0004) as {@link ViewStackState}, shared with the
+// NativeScript twin and specced by the conformance vectors in
+// `@gjsify/adwaita-core/conformance`. This element is the DOM half only: it
+// turns declared markup into pages, toggles their visibility, reflects the
+// selection to an attribute, and re-emits the change as a DOM event.
+//
+// Pages are declared as <adw-view-stack-page> children with `name`, `title`,
+// `icon-name` and `hidden` attributes (their own children become the page body),
+// OR added imperatively with `add(content, name, title?, icon?)`. The first
+// VISIBLE page is shown automatically.
 //
 // Attributes:
 //   visible-child-name — the name of the page to show. Reading/writing it stays
 //     in sync with the `visibleChildName` property so an adaptive layout can
 //     drive the stack declaratively (mirrors the Adw.ViewStack GObject prop).
+//     An EMPTY value is a legal name lookup, not "no name".
 // Properties (mirroring Adw.ViewStack):
-//   pages               — readonly page descriptors ({ name, title, icon, element }).
-//   visibleChildName    — name of the visible page ('' when empty).
-//   visibleChildIndex   — zero-based index of the visible page (bounds-guarded).
+//   pages               — readonly page descriptors ({ name, title, icon, content, visible }).
+//   visibleChildName    — name of the visible page ('' when nothing is selected).
+//   visibleChildIndex   — zero-based index of the visible page, -1 for none (guarded).
 //   visibleChild        — the visible page's content element (or null).
 // Methods:
 //   add(content, name, title?, icon?) — append a page; returns its descriptor.
 //   addTitled(content, name, title)   — Adw.ViewStack.add_titled convenience.
+//   removePage(name)                  — Adw.ViewStack.remove; clears the selection
+//                                       when the removed page was the visible one.
+//   setPageVisible(name, visible)     — AdwViewStackPage:visible; hiding the visible
+//                                       page falls back to the next visible one.
 // Events:
-//   `notify::visible-child` (CustomEvent, bubbles, detail = { index, name, title })
-//     when the visible page CHANGES — mirrors Adw.ViewStack's visible-child
-//     notify. It does NOT fire for the initial/auto-shown page or on add().
+//   `notify::visible-child` (CustomEvent, bubbles,
+//     detail = { index, name, title, interactive }) whenever the visible page
+//     changes — including the auto-shown first page, exactly as
+//     `set_visible_child` notifies there (adw-view-stack.c:1038-1039). It used to
+//     stay silent on that path, which is why a bound switcher needed a manual
+//     `refresh()`. `interactive` is false for an auto-pick.
 // Reference: refs/libadwaita/src/adw-view-stack.c (AdwViewStack behaviour)
 // Reference: packages/nativescript-bridge/adwaita/src/widgets/adw-view-stack.ts (NS twin)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { ViewStackState } from '@gjsify/adwaita-core';
+import type { AdwViewStackPageInfo as CorePageInfo, ViewStackStateChange } from '@gjsify/adwaita-core';
+
 /** A page descriptor exposed via `pages` (consumed by a bound switcher bar). */
-export interface AdwViewStackPageInfo {
-    /** Stable id used by visibleChildName + switcher binding. */
-    name: string;
-    /** Human-facing title shown by a bound switcher. */
-    title: string;
-    /** Symbolic icon name (no `-symbolic` suffix), or '' for none. */
-    icon: string;
-    /** The page's content container (the visibility-toggled node). */
-    element: HTMLElement;
-}
+export type AdwViewStackPageInfo = CorePageInfo<HTMLElement>;
 
 export class AdwViewStack extends HTMLElement {
-    private _pages: AdwViewStackPageInfo[] = [];
-    private _visibleIndex = 0;
+    private readonly _state = new ViewStackState<HTMLElement>();
     private _initialized = false;
 
     static get observedAttributes() {
         return ['visible-child-name'];
     }
 
+    constructor() {
+        super();
+        // Subscribing touches no attributes and no children, so it is legal in a
+        // custom element constructor — unlike anything DOM-shaped.
+        this._state.subscribe((change) => this._onStateChange(change));
+    }
+
     /** All pages in declaration/add order. A bound switcher reads this. */
     get pages(): readonly AdwViewStackPageInfo[] {
-        return this._pages;
+        return this._state.pages;
     }
 
-    /** Zero-based index of the visible page. Out-of-range/same values no-op. */
+    /** Zero-based index of the visible page, `-1` when nothing is selected. */
     get visibleChildIndex(): number {
-        return this._visibleIndex;
+        return this._state.visibleIndex;
     }
 
     set visibleChildIndex(value: number) {
-        if (!Number.isFinite(value) || value < 0 || value >= this._pages.length) return;
-        if (value === this._visibleIndex) return;
-        this._visibleIndex = value;
-        this._apply(true);
+        this._state.setVisibleIndex(value);
     }
 
-    /** Name of the visible page, or '' when the stack is empty. */
+    /** Name of the visible page, or '' when nothing is selected. */
     get visibleChildName(): string {
-        return this._pages[this._visibleIndex]?.name ?? '';
+        return this._state.visibleName;
     }
 
-    set visibleChildName(name: string) {
-        const index = this._pages.findIndex((p) => p.name === name);
-        if (index >= 0) this.visibleChildIndex = index;
+    set visibleChildName(name: string | null | undefined) {
+        this._state.setVisibleName(name);
     }
 
-    /** The visible page's content element, or null when empty. */
+    /** The visible page's content element, or null when nothing is selected. */
     get visibleChild(): HTMLElement | null {
-        return this._pages[this._visibleIndex]?.element ?? null;
+        return this._state.visiblePage?.content ?? null;
     }
 
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Snapshot the declared <adw-view-stack-page> children before we take
-        // over the subtree — their name / title / icon-name + child nodes become
-        // the pages. Wrapping each page's content lets us toggle exactly one.
-        const declared = Array.from(this.querySelectorAll(':scope > adw-view-stack-page')) as HTMLElement[];
-        const wrappers = declared.map((pageEl, index) => {
-            const name = pageEl.getAttribute('name') ?? `page-${index}`;
-            const title = pageEl.getAttribute('title') ?? name;
-            const icon = (pageEl.getAttribute('icon-name') ?? '').replace(/-symbolic$/, '');
+        // Read the declared selection BEFORE adopting any page: the auto-pick
+        // reflects its own name back into this very attribute, which would
+        // otherwise overwrite the author's value with page 0's name.
+        const initialName = this.getAttribute('visible-child-name');
+
+        // Adopt the declared <adw-view-stack-page> children by APPENDING them —
+        // never by replacing the page list. The old code assigned the parsed
+        // wrappers wholesale and then `replaceChildren()`d the subtree away, so a
+        // stack built imperatively before it entered the document
+        // (`createElement` → `add()` → `body.append()`) lost every page it had
+        // been given. libadwaita has no parse-once phase that can discard
+        // children: the buildable adds them one at a time
+        // (adw_view_stack_buildable_add_child, adw-view-stack.c:1666-1680) and
+        // `adw_view_stack_add` works at any point in the widget's life.
+        for (const pageEl of Array.from(this.querySelectorAll(':scope > adw-view-stack-page')) as HTMLElement[]) {
+            // A declared page with no `name` is the page named '' — C stores the
+            // name verbatim (adw-view-stack.c:1170), and an invented `page-<index>`
+            // is addressable by a name the author never wrote.
+            const name = pageEl.getAttribute('name') ?? '';
+            // Wrapping each page's content lets us toggle exactly one.
             const element = document.createElement('div');
             element.className = 'adw-view-stack-child';
             element.dataset.name = name;
             for (const child of Array.from(pageEl.childNodes)) element.appendChild(child);
-            return { name, title, icon, element };
-        });
 
-        this._pages = wrappers;
-        this.replaceChildren(...wrappers.map((p) => p.element));
+            this._state.addPage({
+                name,
+                title: pageEl.getAttribute('title'),
+                icon: pageEl.getAttribute('icon-name'),
+                content: element,
+                // `hidden` is the DOM spelling of AdwViewStackPage:visible, which
+                // gates the auto-pick and refuses selection (adw-view-stack.c:1149-1151, :2415).
+                visible: !pageEl.hasAttribute('hidden'),
+            });
+            this.replaceChild(element, pageEl);
+        }
 
-        // A declared `visible-child-name` selects the initial page; otherwise the
-        // first page is auto-visible (matching Adw.ViewStack + the NS twin).
-        const initialName = this.getAttribute('visible-child-name');
-        const initialIndex = initialName ? this._pages.findIndex((p) => p.name === initialName) : -1;
-        this._visibleIndex = initialIndex >= 0 ? initialIndex : 0;
-        this._apply(false);
+        // An explicit `visible-child-name` selects the initial page. Only a
+        // MISSING attribute falls through to the auto-pick — an empty value is a
+        // legal lookup for a page named '' (g_strcmp0, adw-view-stack.c:901),
+        // which the old `initialName ? … : -1` falsy check silently dropped.
+        if (initialName !== null) this._state.setVisibleName(initialName, false);
+        this._applyVisibility();
+        this._reflectName();
     }
 
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
         if (!this._initialized) return;
-        if (name === 'visible-child-name' && value !== null && value !== this.visibleChildName) {
-            this.visibleChildName = value;
+        // Only a REMOVAL is ignored (there is no name to select). An empty value
+        // goes through the same lookup as the property setter — the declarative
+        // and imperative paths must not disagree on the same input.
+        if (name === 'visible-child-name' && value !== null && value !== this._state.visibleName) {
+            this._state.setVisibleName(value);
         }
     }
 
     /**
-     * Append a page. The FIRST page added becomes visible automatically; later
-     * pages are added hidden. Mirrors Adw.ViewStack.add()/the NS twin's add().
+     * Append a page. It becomes visible when nothing is selected yet, matching
+     * `Adw.ViewStack.add()` — and, unlike before, that auto-pick NOTIFIES.
      */
     add(content: HTMLElement, name: string, title?: string, icon?: string): AdwViewStackPageInfo {
         content.classList.add('adw-view-stack-child');
         content.dataset.name = name;
-        const page: AdwViewStackPageInfo = {
-            name,
-            title: title ?? name,
-            icon: (icon ?? '').replace(/-symbolic$/, ''),
-            element: content,
-        };
-        this._pages.push(page);
+        const page = this._state.addPage({ name, title, icon, content });
         this.appendChild(content);
-        // Keep exactly one page shown without emitting (add is not a user change).
-        this._apply(false);
+        this._applyVisibility();
+        this._reflectName();
         return page;
     }
 
@@ -147,26 +176,74 @@ export class AdwViewStack extends HTMLElement {
         return this.add(content, name, title);
     }
 
-    private _apply(emit: boolean): void {
-        this._pages.forEach((page, index) => {
-            const isVisible = index === this._visibleIndex;
-            page.element.classList.toggle('active-view', isVisible);
-            page.element.hidden = !isVisible;
+    /**
+     * Remove the first page named `name` and detach its content. Returns whether
+     * anything was removed. When the removed page was the visible one the stack
+     * ends up showing NOTHING and emits no event — `stack_remove` clears
+     * `visible_child` without re-picking (adw-view-stack.c:1202-1203).
+     */
+    removePage(name: string): boolean {
+        const content = this._state.pages[this._state.indexOfName(name)]?.content;
+        if (!this._state.removePage(name)) return false;
+        content?.remove();
+        this._applyVisibility();
+        this._reflectName();
+        return true;
+    }
+
+    /**
+     * Show or hide a page (`AdwViewStackPage:visible`). Returns whether the
+     * SELECTION moved: hiding the visible page falls back to the next visible
+     * one, and making a page visible while nothing is selected selects it
+     * (`update_child_visible`, adw-view-stack.c:1061-1082).
+     */
+    setPageVisible(name: string, visible: boolean): boolean {
+        const moved = this._state.setPageVisible(name, visible);
+        this._applyVisibility();
+        return moved;
+    }
+
+    private _onStateChange(change: ViewStackStateChange<HTMLElement>): void {
+        this._applyVisibility();
+        this._reflectName();
+        this.dispatchEvent(
+            new CustomEvent('notify::visible-child', {
+                bubbles: true,
+                detail: {
+                    index: change.index,
+                    name: change.name,
+                    title: change.title,
+                    interactive: change.interactive,
+                },
+            }),
+        );
+    }
+
+    private _applyVisibility(): void {
+        const selected = this._state.visibleIndex;
+        this._state.pages.forEach((page, index) => {
+            const element = page.content;
+            if (!element) return;
+            const isVisible = index === selected;
+            element.classList.toggle('active-view', isVisible);
+            element.hidden = !isVisible;
         });
-        // Reflect the current selection to the attribute (without re-entering the
-        // guarded callback — the value already matches, so it no-ops).
-        const current = this.visibleChildName;
-        if (current && this.getAttribute('visible-child-name') !== current) {
-            this.setAttribute('visible-child-name', current);
+    }
+
+    private _reflectName(): void {
+        // With nothing selected there is no name to mirror — C's
+        // `adw_view_stack_get_visible_child_name` returns NULL there
+        // (adw-view-stack.c:2384), and a missing attribute is the DOM spelling of
+        // that. An EMPTY name is still a name and IS reflected: the old
+        // `if (current && …)` guard meant a stack of nameless pages never
+        // reflected its selection at all.
+        if (this._state.visibleIndex < 0) {
+            this.removeAttribute('visible-child-name');
+            return;
         }
-        if (emit) {
-            const page = this._pages[this._visibleIndex];
-            this.dispatchEvent(
-                new CustomEvent('notify::visible-child', {
-                    bubbles: true,
-                    detail: { index: this._visibleIndex, name: page?.name ?? '', title: page?.title ?? '' },
-                }),
-            );
+        const current = this._state.visibleName;
+        if (this.getAttribute('visible-child-name') !== current) {
+            this.setAttribute('visible-child-name', current);
         }
     }
 }