@gjsify/adwaita-web 0.32.0 → 0.33.0

package/src/elements/adw-spinner.ts

@@ -1,45 +1,189 @@
 // <adw-spinner> — A continuously-spinning loading indicator.
-// Attributes: size (px; the measured minimum, 16, when absent or unusable).
+// Attributes: size (px; the BOX, floored at the measured minimum 16).
 //
-// The ring geometry is `Adw.Spinner`'s, not a guess: the diameter and the stroke
-// come from `@gjsify/adwaita-core`'s `spinnerGeometry`, which is
-// `AdwSpinnerPaintable`'s `radius = min(floor(min(w, h) / 2), 32)` with
-// `lineWidth = diameter / 8`. This element used to default to 24px and stroke
-// `max(2, round(size / 12))`, which draws 2px where Adwaita draws 3px at 24, 4px
-// against 6px at 48 and 5px against 8px at 64 — the ring was visibly thinner than
-// GTK's at every size above the minimum.
+// THE BOX AND THE RING ARE DIFFERENT THINGS. `adw_spinner_measure`
+// (adw-spinner.c:78-81) reports MIN_SIZE as both minimum and natural and has no
+// upper bound — `MAX_SIZE` at :15 is defined and never referenced — while
+// `adw_spinner_snapshot` (:95-99) hands the widget's real width and height to
+// the paintable, which caps only `radius` (adw-spinner-paintable.c:343) and
+// still centres on the box (:349-351). So `size="200"` occupies 200px of layout
+// and draws a 64px ring in the middle. This element used to BE the ring, which
+// is why its suite asserted the opposite of the core's `SPINNER_SIZE_VECTORS`.
 //
-// Reference: refs/libadwaita/src/adw-spinner.c (MIN_SIZE, adw_spinner_measure)
-// Reference: refs/libadwaita/src/adw-spinner-paintable.c (MAX_RADIUS, calculate_line_width)
-// Reference: refs/adwaita-web/adwaita-web/scss/_spinner.scss
+// THE ARC IS NOT A ROTATING QUARTER-CIRCLE. It extends, overlaps, contracts and
+// idles on an ease-in-out-sine while the figure turns; the arithmetic is
+// `@gjsify/adwaita-core`'s `spinnerArc`, shared with the vectors that judge it.
+// Expressing that needs a per-frame value, so this element draws an SVG arc and
+// advances it from one module-level ticker — not one timer per spinner. CSS
+// keyframes cannot express it: a `border-top-color` chase is a fixed 90 degrees,
+// which is what this element drew for its whole life.
+//
+// IT KEEPS SPINNING UNDER REDUCED MOTION. `adw_spinner_paintable_set_widget`
+// calls `adw_animation_set_follow_enable_animations_setting (…, FALSE)` (:537)
+// — deliberately, because a frozen busy indicator reads as a hang. The old
+// `@media (prefers-reduced-motion: reduce) { animation: none }` did exactly that.
+//
+// Reference: refs/libadwaita/src/adw-spinner.c (MIN_SIZE, adw_spinner_measure, the a11y role)
+// Reference: refs/libadwaita/src/adw-spinner-paintable.c (the animation + geometry)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import { resolveSpinnerSize, spinnerGeometry } from '@gjsify/adwaita-core';
+import {
+    ADW_SPINNER_STILL_PROGRESS,
+    ADW_SPINNER_TRACK_OPACITY,
+    resolveSpinnerSize,
+    spinnerArc,
+    spinnerGeometry,
+    spinnerProgressAt,
+} from '@gjsify/adwaita-core';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/**
+ * Every mapped spinner, driven by ONE `requestAnimationFrame` loop.
+ *
+ * The C animates per widget off the frame clock, which costs nothing extra
+ * because the clock is already ticking. A browser has no such clock, so the
+ * equivalent is one shared rAF: N spinners on a page must not mean N loops, and
+ * the loop must not exist at all while none are mapped.
+ */
+const mapped = new Set<AdwSpinner>();
+let frameHandle = 0;
+
+function tick(now: number): void {
+    for (const spinner of mapped) spinner.drawAt(now);
+    frameHandle = mapped.size > 0 ? requestAnimationFrame(tick) : 0;
+}
+
+function startTicking(): void {
+    if (frameHandle === 0 && mapped.size > 0) frameHandle = requestAnimationFrame(tick);
+}
 
 export class AdwSpinner extends HTMLElement {
     static get observedAttributes() {
         return ['size'];
     }
 
+    private _svg: SVGSVGElement | null = null;
+    private _track: SVGCircleElement | null = null;
+    private _arc: SVGCircleElement | null = null;
+    /** Path length of the ring, so the dash arithmetic is done once per resize. */
+    private _circumference = 0;
+    /** Ring radius in px — the dash lengths are arc-length, i.e. radians × r. */
+    private _radius = 0;
+    /** The timestamp this spinner was mapped at, so its progress starts at 0. */
+    private _origin: number | null = null;
+
     connectedCallback() {
-        this._sync();
+        this._build();
+        // `widget_map_cb` (adw-spinner-paintable.c:181-185) plays the animation
+        // on MAP, not on construction: an off-screen spinner burns nothing.
+        mapped.add(this);
+        this._origin = null;
+        startTicking();
+    }
+
+    disconnectedCallback() {
+        mapped.delete(this);
     }
 
     attributeChangedCallback() {
         this._sync();
     }
 
-    private _sync() {
-        // The element IS the ring, so it takes the DRAWN diameter rather than the
-        // requested box: a request below 16 is not representable (GTK never
-        // allocates below a widget's minimum) and one above 64 draws a 64px ring,
-        // which is Adwaita's documented "never larger than 64×64".
+    /**
+     * Draw the frame for `now`, in `requestAnimationFrame` timebase.
+     *
+     * Public because the shared ticker is a module-level function rather than a
+     * method — and because a test needs to place the spinner at a known moment
+     * without waiting for real frames.
+     */
+    drawAt(now: number): void {
+        if (this._origin === null) this._origin = now;
+        this._paint(spinnerProgressAt(now - this._origin));
+    }
+
+    private _build(): void {
+        if (this._svg) return;
+        const svg = document.createElementNS(SVG_NS, 'svg');
+        svg.setAttribute('fill', 'none');
+        // The ring is decorative; the ROLE is on the host, per adw-spinner.c:124.
+        svg.setAttribute('aria-hidden', 'true');
+
+        const track = document.createElementNS(SVG_NS, 'circle');
+        track.setAttribute('stroke', 'currentColor');
+        // `CIRCLE_OPACITY` of the WIDGET's colour (adw-spinner-paintable.c:367-369),
+        // not a hardcoded grey — so the track follows the text colour everywhere.
+        track.setAttribute('stroke-opacity', String(ADW_SPINNER_TRACK_OPACITY));
+
+        const arc = document.createElementNS(SVG_NS, 'circle');
+        arc.setAttribute('stroke', 'currentColor');
+        // `GSK_LINE_CAP_ROUND` (adw-spinner-paintable.c:354). The port's
+        // `border-top-color` ends were square-cut, visible from 48px up.
+        arc.setAttribute('stroke-linecap', 'round');
+
+        svg.append(track, arc);
+        this._svg = svg;
+        this._track = track;
+        this._arc = arc;
+        this.replaceChildren(svg);
+
+        // `gtk_widget_class_set_accessible_role (…, PROGRESS_BAR)` (adw-spinner.c:124)
+        // and `GTK_ACCESSIBLE_STATE_BUSY, TRUE` (:139-141). A repo-wide grep for
+        // either found ZERO hits before this: screen readers announced nothing.
+        this.setAttribute('role', 'progressbar');
+        this.setAttribute('aria-busy', 'true');
+
+        this._sync();
+    }
+
+    /** Re-derive the box, the ring and the stroke from the `size` attribute. */
+    private _sync(): void {
+        const svg = this._svg;
+        const track = this._track;
+        const arc = this._arc;
+        if (!svg || !track || !arc) return;
+
         const size = resolveSpinnerSize(this.getAttribute('size'));
         const { diameter, lineWidth } = spinnerGeometry(size, size);
-        this.style.width = `${diameter}px`;
-        this.style.height = `${diameter}px`;
-        this.style.borderWidth = `${lineWidth}px`;
+        // THE BOX: whatever was asked for, floored at the measured minimum.
+        this.style.width = `${size}px`;
+        this.style.height = `${size}px`;
+        // THE RING: capped at 64, centred by the host's flex box.
+        svg.setAttribute('width', String(diameter));
+        svg.setAttribute('height', String(diameter));
+        svg.setAttribute('viewBox', `0 0 ${diameter} ${diameter}`);
+
+        // The stroke is centred on the path, so the circle sits half a stroke in
+        // — `radius - line_width / 2` (adw-spinner-paintable.c:364).
+        const radius = (diameter - lineWidth) / 2;
+        this._radius = radius;
+        this._circumference = 2 * Math.PI * radius;
+        for (const circle of [track, arc]) {
+            circle.setAttribute('cx', String(diameter / 2));
+            circle.setAttribute('cy', String(diameter / 2));
+            circle.setAttribute('r', String(radius));
+            circle.setAttribute('stroke-width', String(lineWidth));
+        }
+        // A resize while unmapped still has to leave a drawable frame behind:
+        // the resting pose, which is what a paintable without an animation draws.
+        this._paint(this._origin === null ? ADW_SPINNER_STILL_PROGRESS : this._lastProgress);
+    }
+
+    /** The progress the last painted frame used, so a resize can repaint it. */
+    private _lastProgress = ADW_SPINNER_STILL_PROGRESS;
+
+    private _paint(progress: number): void {
+        const arc = this._arc;
+        if (!arc || this._radius <= 0) return;
+        this._lastProgress = progress;
+        const { end, length } = spinnerArc(progress);
+        const drawn = length * this._radius;
+        arc.setAttribute('stroke-dasharray', `${drawn} ${Math.max(this._circumference - drawn, 0)}`);
+        // An SVG circle's path starts at 3 o'clock and runs clockwise, which is
+        // the same origin and direction the C's angles use — so a radian is a
+        // path distance and the dash only has to be shifted to `end`.
+        arc.setAttribute('stroke-dashoffset', String(-end * this._radius));
     }
 }
 

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

@@ -513,6 +513,19 @@ export class AdwTabView extends HTMLElement {
         const icon = createAdwIcon(null, 'adw-tab-icon');
         tab.appendChild(icon);
 
+        // `AdwTabPage:loading` swaps the icon image for an `AdwSpinnerPaintable`
+        // — the SAME paintable `Adw.Spinner` uses (`update_icons`,
+        // adw-tab.c:172-190). So this is a real `<adw-spinner>` in the icon's
+        // slot, not a ring drawn again in CSS: the stylesheet used to restate
+        // the border, the grey and the 0.8s under a comment claiming it was
+        // "not a second copy of them", and it inherited every spinner defect
+        // independently.
+        const spinner = document.createElement('adw-spinner');
+        spinner.className = 'adw-tab-spinner';
+        spinner.setAttribute('size', '16');
+        spinner.hidden = true;
+        tab.appendChild(spinner);
+
         const label = document.createElement('span');
         label.className = 'adw-tab-title';
         tab.appendChild(label);
@@ -588,9 +601,14 @@ export class AdwTabView extends HTMLElement {
         const icon = tab.querySelector('.adw-tab-icon') as AdwIcon | null;
         if (icon) {
             icon.iconName = icons.icon;
-            icon.classList.toggle('loading', icons.spinner);
-            icon.hidden = !icons.iconVisible;
+            // The two occupy the same slot and are never both visible: C
+            // REPLACES the image's contents rather than stacking a second node.
+            icon.hidden = !icons.iconVisible || icons.spinner;
         }
+        const spinner = tab.querySelector('.adw-tab-spinner') as HTMLElement | null;
+        // The spinner is mounted only while it spins, so an idle tab holds no
+        // element in the shared rAF ticker.
+        if (spinner) spinner.hidden = !(icons.spinner && icons.iconVisible);
         const indicator = tab.querySelector('.adw-tab-indicator') as AdwIcon | null;
         if (indicator) {
             indicator.iconName = page.indicatorIcon;

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

@@ -168,6 +168,7 @@ export class AdwViewStack extends HTMLElement {
         this.appendChild(content);
         this._applyVisibility();
         this._reflectName();
+        this._emitItemsChanged();
         return page;
     }
 
@@ -188,6 +189,7 @@ export class AdwViewStack extends HTMLElement {
         content?.remove();
         this._applyVisibility();
         this._reflectName();
+        this._emitItemsChanged();
         return true;
     }
 
@@ -200,9 +202,28 @@ export class AdwViewStack extends HTMLElement {
     setPageVisible(name: string, visible: boolean): boolean {
         const moved = this._state.setPageVisible(name, visible);
         this._applyVisibility();
+        // A visibility flip changes what the pages MODEL reports, which is what
+        // `update_bar_revealed` counts (adw-view-switcher-bar.c:340) — hiding
+        // the second-to-last visible page must retract the bar.
+        this._emitItemsChanged();
         return moved;
     }
 
+    /**
+     * The pages model's `items-changed`, which the DOM stack had no counterpart
+     * for at all.
+     *
+     * `AdwViewSwitcherBar` re-runs `update_bar_revealed` on it
+     * (adw-view-switcher-bar.c:340) and `AdwViewSwitcher` rebinds its buttons
+     * (adw-view-switcher.c:258-263). Both ports listened only on
+     * `notify::visible-child`, so adding a page or hiding a non-selected one
+     * left `revealed` — and the button row — stale, with a manual `refresh()`
+     * as the documented workaround.
+     */
+    private _emitItemsChanged(): void {
+        this.dispatchEvent(new CustomEvent('items-changed', { bubbles: true, detail: { count: this.pages.length } }));
+    }
+
     private _onStateChange(change: ViewStackStateChange<HTMLElement>): void {
         this._applyVisibility();
         this._reflectName();

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

@@ -147,11 +147,13 @@ export class AdwViewSwitcherBar extends HTMLElement {
     }
 
     /**
-     * Rebuild the buttons — needed after pages were added to the bound stack
-     * WITHOUT changing its selection. A page add that does move the selection
-     * (the first one) notifies and rebuilds on its own. libadwaita rebuilds on
-     * the pages model's `items-changed` (adw-view-switcher.c:258-263), which the
-     * DOM stack has no counterpart for yet.
+     * Rebuild the buttons by hand.
+     *
+     * Kept as public API — a consumer that mutates a page in place still has a
+     * way to say so — but no longer the ONLY way: the stack emits
+     * `items-changed` now and this bar binds it, which is the mechanism
+     * libadwaita uses (adw-view-switcher-bar.c:340,
+     * adw-view-switcher.c:258-263).
      */
     refresh(): void {
         this._rebuild();
@@ -163,10 +165,16 @@ export class AdwViewSwitcherBar extends HTMLElement {
 
     private _bindStack(): void {
         this._stack?.addEventListener('notify::visible-child', this._onStackNotify);
+        // `update_bar_revealed` runs on the pages model's `items-changed` too
+        // (adw-view-switcher-bar.c:340), which is the half that was missing: a
+        // page added without moving the selection, or a non-selected page
+        // hidden, changes the COUNT the reveal is decided from.
+        this._stack?.addEventListener('items-changed', this._onStackNotify);
     }
 
     private _unbindStack(): void {
         this._stack?.removeEventListener('notify::visible-child', this._onStackNotify);
+        this._stack?.removeEventListener('items-changed', this._onStackNotify);
     }
 
     private _resolveStack(value: AdwViewStack | string | null): AdwViewStack | null {

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

@@ -56,6 +56,7 @@ import {
     buildViewSwitcherButtons,
     isViewSwitcherPolicy,
 } from '@gjsify/adwaita-core';
+import type { ViewSwitcherScheduler } from '@gjsify/adwaita-core';
 // Aliased because `AdwViewSwitcherPage` is already this module's page ELEMENT —
 // the custom element the package has always exported under that name.
 import type {
@@ -82,18 +83,50 @@ interface PageNodes {
     body: HTMLDivElement;
 }
 
-/** A single page. Children of <adw-view-switcher>; consumed at connect time. */
-export class AdwViewSwitcherPage extends HTMLElement {
-    static get observedAttributes() {
-        return ['name', 'title', 'icon-name', 'badge-number', 'needs-attention', 'use-underline'];
-    }
-}
+/**
+ * A single page. Children of `<adw-view-switcher>`; consumed at connect time.
+ *
+ * Deliberately carries NO `observedAttributes`. It used to declare six of them
+ * and no `attributeChangedCallback`, which is a dead declaration — the browser
+ * computes the list and has nowhere to deliver to — so changing `badge-number`,
+ * `title`, `icon-name` or `needs-attention` after connect did nothing at all,
+ * where C rebinds on every page `notify` (adw-view-switcher.c:184-193, :223).
+ *
+ * A callback could not fix it either: the switcher consumes these elements at
+ * connect and `replaceChildren`s them away, so a detached page has no `closest`
+ * to reach its owner through. The switcher watches them with a `MutationObserver`
+ * instead, which keeps working after the detach and needs nothing from this class.
+ */
+export class AdwViewSwitcherPage extends HTMLElement {}
 
 export class AdwViewSwitcher 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 _barEl!: HTMLDivElement;
     private _contentEl!: HTMLDivElement;
     private _nodes: PageNodes[] = [];
+    /** The page ELEMENTS, kept because the switcher detaches them from the tree. */
+    private _declared: HTMLElement[] = [];
+    private _pageObserver: MutationObserver | undefined;
     private _policy: AdwViewSwitcherPolicy = 'narrow';
     private _initialized = false;
 
@@ -105,7 +138,6 @@ export class AdwViewSwitcher extends HTMLElement {
         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));
     }
 
     /** The policy controlling the button layout ('wide' | 'narrow'). */
@@ -153,7 +185,15 @@ export class AdwViewSwitcher extends HTMLElement {
     }
 
     connectedCallback() {
-        if (this._initialized) return;
+        if (this._initialized) {
+            // Re-entering a document. `disconnectedCallback` drops the page
+            // observer on the way out, and this early return used to skip
+            // rebuilding it — so a switcher that had merely been MOVED (a
+            // slideshow slide, a client-side route change) stopped noticing
+            // page attribute changes for good, and did it silently.
+            this._watchPages();
+            return;
+        }
 
         // `:scope >` rather than a subtree scan: an unscoped query let an outer
         // switcher adopt the pages of a nested one, since both use the same tag.
@@ -172,6 +212,8 @@ export class AdwViewSwitcher extends HTMLElement {
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-view-switcher-content';
 
+        this._declared = declared;
+        this._watchPages();
         this._nodes = declared.map((pageEl, index) => this._buildPage(pageEl, index));
         this._barEl.append(...this._nodes.map((nodes) => nodes.button));
         this._contentEl.append(...this._nodes.map((nodes) => nodes.body));
@@ -193,6 +235,41 @@ export class AdwViewSwitcher extends HTMLElement {
         // A drag that leaves with the element would otherwise switch pages after
         // the widget is gone; C drops the source in dispose the same way.
         this._state.cancelDrag();
+        this._pageObserver?.disconnect();
+        this._pageObserver = undefined;
+    }
+
+    /**
+     * Re-read every declared page and push it into the state.
+     *
+     * Called by `AdwViewSwitcherPage.attributeChangedCallback`, which is what
+     * makes a runtime `badge-number` change reach the button. `setPages` keeps
+     * the selection where it can, so this is a repaint and not a reset.
+     */
+    refreshPages(): void {
+        if (!this._initialized) return;
+        this._state.setPages(this._declared.map((pageEl) => readSwitcherPage(pageEl)));
+        this._render();
+    }
+
+    /**
+     * Watch the declared pages for attribute changes.
+     *
+     * A `MutationObserver` rather than an `attributeChangedCallback` on the page:
+     * the switcher consumes those elements at connect and `replaceChildren`s them
+     * out of the tree, so a detached page cannot find its owner — but an observer
+     * bound to it keeps firing. This is the DOM's `notify::` on
+     * `AdwViewStackPage`, which the C's `update_button` handler binds per page
+     * (adw-view-switcher.c:184-193).
+     *
+     * It delivers on a MICROTASK where GTK's notify is synchronous. That is the
+     * DOM's contract for watching a node, it is invisible to a user, and nothing
+     * in this element reads the button 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) {
@@ -239,8 +316,23 @@ export class AdwViewSwitcher extends HTMLElement {
             this._state.setSelected(index);
         });
         // GtkDropControllerMotion's enter/leave, which drive TIMEOUT_EXPAND.
-        button.addEventListener('dragenter', () => this._state.dragEnter(index));
-        button.addEventListener('dragleave', () => this._state.dragLeave(index));
+        //
+        // The `relatedTarget` test is the whole point: this button contains an
+        // icon and a label, and the DOM fires `dragleave` + `dragenter` when the
+        // pointer crosses BETWEEN them. `ViewSwitcherDragSwitch.leave` clears the
+        // dwell timer and `enter` re-arms a fresh 500ms, so a drag that merely
+        // slid from the icon to the label restarted the countdown and the page
+        // never switched. C has one `GtkDropControllerMotion` per BUTTON
+        // (adw-view-switcher-button.c:79-96), which has no such internal edges —
+        // `relatedTarget` containment is that same "did we really leave" test.
+        button.addEventListener('dragenter', (event) => {
+            if (button.contains((event as DragEvent).relatedTarget as Node | null)) return;
+            this._state.dragEnter(index);
+        });
+        button.addEventListener('dragleave', (event) => {
+            if (button.contains((event as DragEvent).relatedTarget as Node | null)) return;
+            this._state.dragLeave(index);
+        });
 
         const body = document.createElement('div');
         body.className = 'adw-view-switcher-page';