@gjsify/adwaita-web 0.32.0 → 0.34.0

package/src/elements/adw-inline-view-switcher.ts

@@ -53,6 +53,7 @@ import {
     isInlineViewSwitcherDisplayMode,
     toggleIndexForPage,
 } from '@gjsify/adwaita-core';
+import type { ViewSwitcherScheduler } from '@gjsify/adwaita-core';
 import type {
     AdwInlineViewSwitcherDisplayMode,
     AdwViewSwitcherPage,
@@ -75,21 +76,43 @@ export class AdwViewStackPage extends HTMLElement {
 }
 
 export class AdwInlineViewSwitcher extends HTMLElement {
-    private readonly _state = new ViewSwitcherState({ scheduler: domViewSwitcherScheduler });
+    /**
+     * The dwell timer, injectable.
+     *
+     * It used to be `new ViewSwitcherState({ scheduler: domViewSwitcherScheduler })`
+     * inline, which left NOWHERE to hand a clock in — so
+     * `VIEW_SWITCHER_DRAG_VECTORS` was driven by the core suite alone, and the
+     * conformance header claimed all three suites drove it. `scheduler` is a
+     * property so a test can replace it before the element connects; the DOM one
+     * is the default, exactly as before.
+     */
+    scheduler: ViewSwitcherScheduler = domViewSwitcherScheduler;
+    private _stateInstance: ViewSwitcherState | null = null;
+
+    /** Built on first access, so a `scheduler` set before connect is the one used. */
+    private get _state(): ViewSwitcherState {
+        if (!this._stateInstance) {
+            this._stateInstance = new ViewSwitcherState({ scheduler: this.scheduler });
+            this._stateInstance.subscribe((change) => this._onStateChange(change));
+        }
+        return this._stateInstance;
+    }
     private _groupEl!: HTMLDivElement;
     private _pagesEl!: HTMLDivElement;
     private _panels: HTMLDivElement[] = [];
     private _toggles: HTMLButtonElement[] = [];
     private _displayMode: AdwInlineViewSwitcherDisplayMode = 'labels';
     private _initialized = false;
+    /** The page ELEMENTS, kept because this element detaches them from the tree. */
+    private _declared: HTMLElement[] = [];
+    private _pageObserver: MutationObserver | undefined;
 
     static get observedAttributes() {
-        return ['active', 'display-mode', 'flat', 'round'];
+        return ['active', 'display-mode', 'flat', 'round', 'osd'];
     }
 
     constructor() {
         super();
-        this._state.subscribe((change) => this._onStateChange(change));
     }
 
     /** Zero-based index of the visible PAGE, `-1` when nothing is selected. */
@@ -147,7 +170,13 @@ export class AdwInlineViewSwitcher extends HTMLElement {
     }
 
     connectedCallback() {
-        if (this._initialized) return;
+        if (this._initialized) {
+            // Re-entering a document — same reason as `adw-view-switcher.ts`:
+            // the page observer is dropped on disconnect, so it has to be
+            // rebuilt here or a moved switcher goes deaf permanently.
+            this._watchPages();
+            return;
+        }
 
         // `:scope >` rather than a subtree scan — `<adw-view-stack>` uses the
         // same tag for its pages, so an unscoped query adopted a nested stack's.
@@ -176,6 +205,8 @@ export class AdwInlineViewSwitcher extends HTMLElement {
         this._displayMode = this._readDisplayModeAttr();
         this._initialized = true;
 
+        this._declared = declared;
+        this._watchPages();
         this._state.setPages(declared.map((pageEl) => readSwitcherPage(pageEl)));
         if (declaredActive !== null) {
             const index = Number.parseInt(declaredActive, 10);
@@ -186,6 +217,37 @@ export class AdwInlineViewSwitcher extends HTMLElement {
 
     disconnectedCallback() {
         this._state.cancelDrag();
+        this._pageObserver?.disconnect();
+        this._pageObserver = undefined;
+    }
+
+    /**
+     * Re-read every declared page and push it into the state.
+     *
+     * Driven by {@link _watchPages}, which is what makes a runtime
+     * `badge-number` or `icon-name` change reach the toggle — C rebinds on every
+     * page `notify` (adw-view-switcher.c:184-193) and this element did not.
+     */
+    refreshPages(): void {
+        if (!this._initialized) return;
+        this._state.setPages(this._declared.map((pageEl) => readSwitcherPage(pageEl)));
+        this._rebuildToggles();
+    }
+
+    /**
+     * Watch the declared pages for attribute changes — the DOM's `notify::` on
+     * `AdwViewStackPage`, which C binds per page (adw-view-switcher.c:184-193).
+     *
+     * A `MutationObserver` rather than an `attributeChangedCallback`: this
+     * element consumes the page elements at connect and `replaceChildren`s them
+     * out of the tree, so a detached page cannot find its owner. It delivers on
+     * a MICROTASK where GTK's notify is synchronous — invisible to a user, and
+     * nothing here reads the toggle back inside the setter.
+     */
+    private _watchPages(): void {
+        this._pageObserver?.disconnect();
+        this._pageObserver = new MutationObserver(() => this.refreshPages());
+        for (const pageEl of this._declared) this._pageObserver.observe(pageEl, { attributes: true });
     }
 
     attributeChangedCallback(name: string) {
@@ -265,8 +327,21 @@ export class AdwInlineViewSwitcher extends HTMLElement {
             toggle.addEventListener('click', () => {
                 this._state.setSelected(model.pageIndex);
             });
-            toggle.addEventListener('dragenter', () => this._state.dragEnter(model.pageIndex));
-            toggle.addEventListener('dragleave', () => this._state.dragLeave(model.pageIndex));
+            // The `relatedTarget` test is load-bearing: a toggle holds an icon,
+            // a label and an indicator, and the DOM fires `dragleave` +
+            // `dragenter` when the pointer crosses BETWEEN them — which cleared
+            // the dwell timer and re-armed a fresh 500ms, so a drag that merely
+            // slid across the toggle never switched the page. C has one
+            // `GtkDropControllerMotion` per BUTTON widget
+            // (adw-view-switcher-button.c:79-96), which has no internal edges.
+            toggle.addEventListener('dragenter', (event) => {
+                if (toggle.contains((event as DragEvent).relatedTarget as Node | null)) return;
+                this._state.dragEnter(model.pageIndex);
+            });
+            toggle.addEventListener('dragleave', (event) => {
+                if (toggle.contains((event as DragEvent).relatedTarget as Node | null)) return;
+                this._state.dragLeave(model.pageIndex);
+            });
 
             this._groupEl.appendChild(toggle);
             return toggle;
@@ -314,8 +389,16 @@ export class AdwInlineViewSwitcher extends HTMLElement {
     }
 
     private _applyStyleClasses(): void {
-        this.classList.toggle('flat', this.hasAttribute('flat'));
-        this.classList.toggle('round', this.hasAttribute('round'));
+        // `css_classes_changed_cb` (adw-inline-view-switcher.c:528-545) forwards
+        // THREE classes onto the toggle group, not two: `flat`, `round` and
+        // `osd`. This element carried the first two and only onto the host, so an
+        // `osd` inline switcher — the one in a floating overlay, where the class
+        // exists to make it legible — styled nothing at all.
+        for (const name of ['flat', 'round', 'osd'] as const) {
+            const present = this.hasAttribute(name);
+            this.classList.toggle(name, present);
+            this._groupEl?.classList.toggle(name, present);
+        }
         // The group carries the display-mode class, mirroring libadwaita's
         // inline-view-switcher > toggle-group.{labels,icons,both} (:826-850).
         for (const mode of INLINE_VIEW_SWITCHER_DISPLAY_MODES) {

package/src/elements/adw-navigation-split-view.ts

@@ -2,31 +2,74 @@
 // visible when expanded; when `collapsed` it shows one pane at a time
 // (`show-content` decides which), mirroring Adw.NavigationSplitView's
 // push-navigation on narrow widths.
-// Attributes: collapsed, show-content, min-sidebar-width, max-sidebar-width,
-//   breakpoint (an Adwaita condition, e.g. "max-width: 720px", that collapses
-//   the view by itself — the counterpart to an Adw.Breakpoint add_setter()).
+//
+// Attributes: collapsed, show-content, sidebar-position, min-sidebar-width,
+//   max-sidebar-width, breakpoint (an Adwaita condition, e.g. "max-width: 720px",
+//   that collapses the view by itself — the counterpart to an Adw.Breakpoint
+//   add_setter()). A slotted pane may carry `tag`, which is
+//   `Adw.NavigationPage:tag`.
 // Slots: slot="sidebar", slot="content".
+//
+// The element used to toggle two CSS classes and nothing else, so THREE rules
+// from the C had no expression here at all: the navigation-stack ordering table
+// (a LONE child stays visible whatever `show-content` says; with
+// `sidebar-position: end` the CONTENT is the root page), the duplicate-tag
+// guard, and the `navigation.push` / `navigation.pop` routing that lets a nested
+// split view forward a push outwards. All three are `NavigationSplitViewState`
+// in `@gjsify/adwaita-core`, held to NAVIGATION_STACK_VECTORS,
+// NAVIGATION_SPLIT_VIEW_CRITICALS and NAVIGATION_ACTION_VECTORS — the last of
+// which had no consumer at all before this.
+//
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/navigationsplitview.md
+// Reference: refs/libadwaita/src/adw-navigation-split-view.c
 // Reference: refs/libadwaita/src/stylesheet/widgets/_sidebars.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import { DEFAULT_MAX_SIDEBAR_WIDTH, DEFAULT_MIN_SIDEBAR_WIDTH, resolveSidebarBounds } from '@gjsify/adwaita-core';
+import {
+    DEFAULT_MAX_SIDEBAR_WIDTH,
+    DEFAULT_MIN_SIDEBAR_WIDTH,
+    NavigationSplitViewState,
+    isSidebarAtVisualStart,
+    resolveSidebarBounds,
+    type AdwPackType,
+    type AdwTextDirection,
+    type NavigationActionResult,
+} from '@gjsify/adwaita-core';
 
 import { bindBreakpointSetter } from '../breakpoints.js';
 
+/** Detail of the `navigation-push` / `navigation-pop` delegation event. */
+export interface NavigationDelegateDetail {
+    /** The tag a `push` names; absent for a `pop`. */
+    tag?: string;
+    /** Set by an ancestor that handled it — the `return TRUE` of the C's routing. */
+    handled: boolean;
+}
+
 export class AdwNavigationSplitView extends HTMLElement {
     private _sidebarEl!: HTMLDivElement;
     private _contentEl!: HTMLDivElement;
     private _initialized = false;
     private _disposeBreakpoint: (() => void) | undefined;
+    /** The ordering table, the tag guard and the action routing (ADR 0004). */
+    private _state = new NavigationSplitViewState();
+    /** Re-entrancy guard for the `show-content` reflection. */
+    private _reflecting = false;
 
     static get observedAttributes() {
-        return ['collapsed', 'show-content', 'min-sidebar-width', 'max-sidebar-width', 'breakpoint'];
+        return [
+            'collapsed',
+            'show-content',
+            'sidebar-position',
+            'min-sidebar-width',
+            'max-sidebar-width',
+            'breakpoint',
+        ];
     }
 
     get collapsed(): boolean {
-        return this.hasAttribute('collapsed');
+        return this._initialized ? this._state.collapsed : this.hasAttribute('collapsed');
     }
 
     set collapsed(v: boolean) {
@@ -35,13 +78,49 @@ export class AdwNavigationSplitView extends HTMLElement {
 
     /** When collapsed, whether the content pane (true) or sidebar (false) shows. */
     get showContent(): boolean {
-        return this.hasAttribute('show-content');
+        return this._initialized ? this._state.showContent : this.hasAttribute('show-content');
     }
 
     set showContent(v: boolean) {
         this.toggleAttribute('show-content', v);
     }
 
+    /** Which side the sidebar is packed on — `start` (default) or `end`. */
+    get sidebarPosition(): AdwPackType {
+        return this.getAttribute('sidebar-position') === 'end' ? 'end' : 'start';
+    }
+
+    set sidebarPosition(value: AdwPackType) {
+        this.setAttribute('sidebar-position', value);
+    }
+
+    /** The sidebar page's tag of record, or `null`. */
+    get sidebarTag(): string | null {
+        return this._state.sidebarTag;
+    }
+
+    /** The content page's tag of record, or `null`. */
+    get contentTag(): string | null {
+        return this._state.contentTag;
+    }
+
+    /**
+     * `navigation.push` with `tag` — `navigation_push_cb` (:644-685).
+     *
+     * An unmatched tag DELEGATES to the parent before it may become a critical,
+     * which is how nested split views forward a push outwards; on this port that
+     * is a bubbling `navigation-push` event whose `detail.handled` an ancestor
+     * sets. Returns what the routing decided.
+     */
+    push(tag: string): NavigationActionResult {
+        return this._state.push(tag);
+    }
+
+    /** `navigation.pop` — `navigation_pop_cb` (:687-702). */
+    pop(): NavigationActionResult {
+        return this._state.pop();
+    }
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
@@ -58,11 +137,68 @@ export class AdwNavigationSplitView extends HTMLElement {
         for (const child of contentChildren) this._contentEl.appendChild(child);
 
         this.replaceChildren(this._sidebarEl, this._contentEl);
+
+        // Parse-time attributes are the CONSTRUCTION properties, for the same
+        // reason the overlay view treats them so: applying them as sequential
+        // setters would emit a transition for a state the markup simply declared.
+        this._state = new NavigationSplitViewState({
+            sidebarPosition: this.sidebarPosition,
+            collapsed: this.hasAttribute('collapsed'),
+            showContent: this.hasAttribute('show-content'),
+            // `g_critical` has no browser counterpart that a consumer can see;
+            // `console.error` is the one a developer reads, and the TEXT is the
+            // C's verbatim so a GTK bug report and a browser one say the same.
+            onCritical: (message) => console.error(message),
+            onDelegate: (action, tag) => {
+                const detail: NavigationDelegateDetail = { tag, handled: false };
+                this.dispatchEvent(new CustomEvent(`navigation-${action}`, { bubbles: true, detail }));
+                return detail.handled;
+            },
+        });
+        // Which children EXIST decides the stack, so the panes are mounted into
+        // the state, not merely into the DOM — a lone child stays visible
+        // whatever `show-content` says (:389-401), which two CSS classes cannot
+        // express.
+        this._state.setSidebar(sidebarChildren.length > 0 ? { tag: this._tagOf(sidebarChildren) } : null);
+        this._state.setContent(contentChildren.length > 0 ? { tag: this._tagOf(contentChildren) } : null);
+        this._state.subscribe(() => {
+            this._reflectShowContent();
+            this._syncClasses();
+        });
+
         this._syncWidth();
         this._syncClasses();
         this._syncBreakpoint();
     }
 
+    /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
+    private _tagOf(children: readonly Element[]): string | null {
+        for (const child of children) {
+            const tag = child.getAttribute('tag');
+            if (tag !== null) return tag;
+        }
+        return null;
+    }
+
+    /**
+     * Mirror the state's `showContent` onto the attribute, so the DOM keeps
+     * telling the truth after a `navigation.push` moved it.
+     *
+     * Guarded the way the overlay view's reflection is: writing the attribute
+     * re-enters `attributeChangedCallback`, which without the flag is a loop.
+     */
+    private _reflectShowContent() {
+        if (this._reflecting) return;
+        const wanted = this._state.showContent;
+        if (this.hasAttribute('show-content') === wanted) return;
+        this._reflecting = true;
+        try {
+            this.toggleAttribute('show-content', wanted);
+        } finally {
+            this._reflecting = false;
+        }
+    }
+
     disconnectedCallback() {
         this._disposeBreakpoint?.();
         this._disposeBreakpoint = undefined;
@@ -70,13 +206,20 @@ export class AdwNavigationSplitView extends HTMLElement {
 
     attributeChangedCallback(name: string) {
         if (!this._initialized) return;
-        if (name === 'breakpoint') this._syncBreakpoint();
-        else if (name === 'min-sidebar-width' || name === 'max-sidebar-width') this._syncWidth();
-        else {
-            this._syncClasses();
-            // Collapsing flips whether the sidebar is width-capped, so re-apply.
+        if (name === 'breakpoint') {
+            this._syncBreakpoint();
+            return;
+        }
+        if (name === 'min-sidebar-width' || name === 'max-sidebar-width') {
             this._syncWidth();
+            return;
         }
+        if (name === 'collapsed') this._state.setCollapsed(this.hasAttribute('collapsed'));
+        if (name === 'show-content') this._state.setShowContent(this.hasAttribute('show-content'));
+        if (name === 'sidebar-position') this._state.setSidebarPosition(this.sidebarPosition);
+        this._syncClasses();
+        // Collapsing flips whether the sidebar is width-capped, so re-apply.
+        this._syncWidth();
     }
 
     private _syncWidth() {
@@ -113,9 +256,41 @@ export class AdwNavigationSplitView extends HTMLElement {
         return Number.isFinite(value) ? value : fallback;
     }
 
+    /** The reading direction `start` / `end` resolve against (`get_start_or_end`, :220-227). */
+    private get _direction(): AdwTextDirection {
+        return getComputedStyle(this).direction === 'rtl' ? 'rtl' : 'ltr';
+    }
+
     private _syncClasses() {
-        this.classList.toggle('collapsed', this.collapsed);
-        this.classList.toggle('show-content', this.showContent);
+        const state = this._state;
+        this.classList.toggle('collapsed', state.collapsed);
+        this.classList.toggle('show-content', state.showContent);
+        this.classList.toggle('sidebar-end', state.sidebarPosition === 'end');
+        // The VISUAL side, which under RTL is the opposite of the logical one —
+        // it decides where the pane is drawn AND which edge its divider is on.
+        this.classList.toggle(
+            'sidebar-at-visual-start',
+            isSidebarAtVisualStart(state.sidebarPosition, this._direction),
+        );
+
+        // THE PANE STYLE CLASSES, and only while docked. libadwaita builds the
+        // two `.sidebar-pane` / `.content-pane` bins in the UNCOLLAPSED branch
+        // alone (:583-608); collapsed, both pages move into one AdwNavigationView
+        // and neither bin exists (:552-568) — so a collapsed sidebar is a full
+        // window page on the WINDOW background, not a sidebar-coloured one.
+        // Painting it `--sidebar-bg-color` at every width, as this did, is the
+        // same defect the overlay view has with `.overlay-pane`.
+        this._sidebarEl?.classList.toggle('sidebar-pane', !state.collapsed);
+        this._contentEl?.classList.toggle('content-pane', !state.collapsed);
+
+        // The STACK, not the two flags: `update_navigation_stack` (:342-405)
+        // keeps a LONE child visible whatever `show-content` says, and with
+        // `sidebar-position: end` the CONTENT is the root page — so the sidebar
+        // is PUSHED ON TOP of it rather than replacing it.
+        const { stack } = state.stack;
+        const visible = stack[stack.length - 1] ?? null;
+        if (this._sidebarEl) this._sidebarEl.dataset.paneVisible = String(!state.collapsed || visible === 'sidebar');
+        if (this._contentEl) this._contentEl.dataset.paneVisible = String(!state.collapsed || visible === 'content');
     }
 
     /** (Re)bind the `breakpoint` condition to `collapsed`. */