@gjsify/adwaita-web 0.39.0 → 0.41.0

package/src/elements/adw-header-bar.ts

@@ -1,22 +1,37 @@
 // <adw-header-bar> — Adwaita header bar with centered title and start/end button slots.
+//
+// The derived centre is an `<adw-window-title>`, which is what `Adw.HeaderBar`
+// itself puts there (`adw-header-bar.c`: the title widget it creates when none is
+// given IS an `AdwWindowTitle`). It used to be a bare span with
+// `textContent = title ?? ''`, and that span carried none of the three rules the
+// window title already held in `@gjsify/adwaita-core`: an EMPTY title still
+// reserved a blank line, re-setting the same value repainted, and there was no
+// subtitle at all. So a header bar could not show what its own NativeScript twin
+// could, and the fix is delegation rather than a fourth copy of the derivation.
+//
+// Reference: refs/libadwaita/src/adw-header-bar.c
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web.
 
+// Registers <adw-window-title>: the derived centre is one, so importing the bar
+// alone must still define it.
+import './adw-window-title.js';
+
 export class AdwHeaderBar extends HTMLElement {
     private _initialized = false;
     private _startEl: HTMLDivElement | null = null;
     private _centerEl: HTMLDivElement | null = null;
     private _endEl: HTMLDivElement | null = null;
     /**
-     * The generated title span, or `null` when a `slot="center"` title-widget
-     * took the centre. `Adw.HeaderBar` has the same either/or: setting
-     * `title-widget` replaces the derived `AdwWindowTitle` outright.
+     * The derived `<adw-window-title>`, or `null` when a `slot="center"`
+     * title-widget took the centre. `Adw.HeaderBar` has the same either/or:
+     * setting `title-widget` replaces the derived `AdwWindowTitle` outright.
      */
-    private _titleEl: HTMLSpanElement | null = null;
+    private _titleEl: HTMLElement | null = null;
 
     static get observedAttributes() {
-        return ['title'];
+        return ['title', 'subtitle'];
     }
 
     /** The start (left) section container — append buttons/widgets here. */
@@ -56,7 +71,7 @@ export class AdwHeaderBar extends HTMLElement {
         if (centerChildren.length > 0) {
             for (const child of centerChildren) this._centerEl.appendChild(child);
         } else {
-            this._titleEl = document.createElement('span');
+            this._titleEl = document.createElement('adw-window-title');
             this._titleEl.className = 'adw-header-bar-title';
             this._centerEl.appendChild(this._titleEl);
         }
@@ -77,15 +92,23 @@ export class AdwHeaderBar extends HTMLElement {
      * kept whatever it was created with. `Adw.HeaderBar`'s derived title widget
      * is bound to the property and re-renders on every change.
      */
-    attributeChangedCallback(name: string) {
-        if (this._initialized && name === 'title') this._renderTitle();
+    attributeChangedCallback() {
+        if (this._initialized) this._renderTitle();
     }
 
     private _renderTitle() {
         // A `slot="center"` widget replaced the derived title, so there is
         // nothing for the attribute to write to — the same either/or as
         // `Adw.HeaderBar:title-widget`.
-        if (this._titleEl) this._titleEl.textContent = this.getAttribute('title') ?? '';
+        if (!this._titleEl) return;
+        // Forwarded as ATTRIBUTES, so the window title's own change detection and
+        // empty-string collapse do the work. Removing rather than writing `''`
+        // keeps "unset" distinguishable from "set to empty" on the child.
+        for (const name of ['title', 'subtitle']) {
+            const value = this.getAttribute(name);
+            if (value === null) this._titleEl.removeAttribute(name);
+            else this._titleEl.setAttribute(name, value);
+        }
     }
 }
 

package/src/elements/adw-menu-button.ts

@@ -20,8 +20,8 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import { isSplitButtonDirection, menuButtonPopupDirection } from '@gjsify/adwaita-core';
-import type { SplitButtonDirection } from '@gjsify/adwaita-core';
+import { isSplitButtonDirection, menuButtonPopupDirection, parseMenuEntries } from '@gjsify/adwaita-core';
+import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `adw-popover` is defined before this module's `customElements.define` can upgrade a
@@ -34,12 +34,15 @@ import type { AdwPopover } from './adw-popover.js';
 
 import { createAdwIcon } from './adw-icon.js';
 
-/** A menu entry. `id` defaults to `label` on activation; `icon` is optional. */
-export interface AdwMenuItem {
-    id?: string;
-    label: string;
-    icon?: string;
-}
+/**
+ * A menu entry — `@gjsify/adwaita-core`'s {@link AdwMenuEntry}, re-exported under the
+ * name this element has always used.
+ *
+ * It used to be a SECOND declaration of the same shape, and the NativeScript menu
+ * button declared a THIRD that was missing `icon` entirely. One type, so a consumer
+ * writing menu entries writes the same object for either renderer.
+ */
+export type AdwMenuItem = AdwMenuEntry;
 
 /**
  * Where the popover sits, per `GtkArrowType`. `menuButtonPopupDirection` folds `none`
@@ -152,18 +155,16 @@ export class AdwMenuButton extends HTMLElement {
         this._render();
     }
 
+    /**
+     * The `menu` attribute, through the core parser the split button already used.
+     *
+     * The copy this replaces was weaker in a way markup can reach: it kept `id` and
+     * `icon` WHATEVER their runtime type, so `{"label":"Open","id":7}` produced an
+     * entry whose `id` is a number in a field typed `string` — and `id` is what the
+     * activation event reports. The core parser keeps only string-typed extras.
+     */
     private _parseMenuAttr(): AdwMenuItem[] {
-        const raw = this.getAttribute('menu');
-        if (!raw) return [];
-        try {
-            const parsed: unknown = JSON.parse(raw);
-            if (!Array.isArray(parsed)) return [];
-            return parsed
-                .filter((e): e is AdwMenuItem => typeof e === 'object' && e !== null && 'label' in e)
-                .map((e) => ({ id: e.id, label: String(e.label), icon: e.icon }));
-        } catch {
-            return [];
-        }
+        return parseMenuEntries(this.getAttribute('menu'));
     }
 
     private _onPopoverToggled(open: boolean): void {

package/src/elements/adw-status-page.ts

@@ -7,6 +7,8 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon node is <adw-icon>.
 
+import { stringIsNotEmpty } from '@gjsify/adwaita-core';
+
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 export class AdwStatusPage extends HTMLElement {
@@ -51,13 +53,16 @@ export class AdwStatusPage extends HTMLElement {
         this._iconEl.iconName = this.getAttribute('icon');
         this._iconEl.hidden = this._iconEl.resolvedIconName === '';
 
+        // `string_is_not_empty` from the core, not a local `.length === 0`: the same
+        // closure the NativeScript port binds its labels to, and the reason a title of
+        // `'   '` stays VISIBLE — it reads the first byte, it never trims.
         const title = this.getAttribute('title') ?? '';
         this._titleEl.textContent = title;
-        this._titleEl.hidden = title.length === 0;
+        this._titleEl.hidden = !stringIsNotEmpty(title);
 
         const description = this.getAttribute('description') ?? '';
         this._descEl.textContent = description;
-        this._descEl.hidden = description.length === 0;
+        this._descEl.hidden = !stringIsNotEmpty(description);
 
         this._childEl.hidden = this._childEl.childElementCount === 0;
     }

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

@@ -57,6 +57,9 @@ export type AdwTabViewPageSpec = AdwTabPageSpec<HTMLElement>;
 /** The live `<adw-tab-page>` properties, each mapped onto a state setter. */
 const PAGE_ATTRIBUTES = ['title', 'tooltip', 'icon', 'indicator-icon', 'loading', 'needs-attention', 'pinned'];
 
+/** `SPACING`: the slack `scroll_to_tab_full` allows before it scrolls (adw-tab-box.c:24). */
+const TAB_SPACING = 5;
+
 /**
  * A single page. Declared as a child of <adw-tab-view>; the element itself becomes the
  * page panel, so its attributes keep driving the tab after connect — a renderer that
@@ -581,6 +584,20 @@ export class AdwTabView extends HTMLElement {
         this._refreshCloseVisibility(id);
     }
 
+    /**
+     * `get_tab_position` in the BAR's scroll space: how far the chip sits from the
+     * strip's scroll origin, the one coordinate both `scroll_to_tab_full` and
+     * `update_visible` compare against the adjustment.
+     *
+     * Never `offsetLeft`. Nothing in this widget is positioned, so a chip's offsetParent
+     * is whichever positioned ancestor the HOST page happens to have; a tab view that
+     * merely sits indented then measured every chip against the wrong origin and
+     * reported all of them clipped.
+     */
+    private _tabPosition(tab: HTMLElement): number {
+        return tab.getBoundingClientRect().left - this._barEl.getBoundingClientRect().left + this._barEl.scrollLeft;
+    }
+
     /**
      * `tabCloseVisible`, with its pinned gate. `dragging` is constantly false — tab
      * drag-and-drop is compositor work and is not modelled — and `fullyVisible` is
@@ -595,8 +612,14 @@ export class AdwTabView extends HTMLElement {
         if (!close) return;
 
         const barLeft = this._barEl.scrollLeft;
-        const fullyVisible =
-            tab.offsetLeft >= barLeft && tab.offsetLeft + tab.offsetWidth <= barLeft + this._barEl.clientWidth;
+        const pos = this._tabPosition(tab);
+        // `update_visible` (adw-tab-box.c:769-797). C also demands SPACING of slack on
+        // both sides; that term is deliberately NOT transplanted, because it is not
+        // slack there either: the allocation loop starts the first tab at `pos = SPACING`
+        // and puts SPACING between tabs (:3270-3286), so `pos - SPACING >= value` is
+        // exactly "flush against the leading edge". This strip has no such gaps, so the
+        // same term would report the first chip clipped and hide its close button.
+        const fullyVisible = pos >= barLeft && pos + tab.offsetWidth <= barLeft + this._barEl.clientWidth;
         close.hidden = !tabCloseVisible({
             hovering: this._hovered.has(id),
             fullyVisible,
@@ -608,6 +631,7 @@ export class AdwTabView extends HTMLElement {
 
     private _onSelectionChange(change: TabViewSelectionChange): void {
         this._applyActiveState();
+        this._scrollSelectedTabIntoBar();
         this._reflectSelected();
         this.dispatchEvent(
             new CustomEvent('notify::selected-page', {
@@ -641,6 +665,34 @@ export class AdwTabView extends HTMLElement {
         }
     }
 
+    /**
+     * `scroll_to_tab_full` (adw-tab-box.c:928-961), called on every selection the way
+     * `select_page` calls it (:1728): bring the selected chip inside the BAR's own
+     * scroll window, padded by half of whichever is smaller, the chip or the leftover.
+     *
+     * The bar is the only thing C ever scrolls for a tab: `scroll_to_tab_full` writes
+     * `self->adjustment`, the strip's own adjustment, and nothing else. The DOM has no
+     * such narrow API: `focus()` and `scrollIntoView()` both walk EVERY scrollable
+     * ancestor up to the window. So this moves `scrollLeft` by hand, and the focus call
+     * below passes `preventScroll`.
+     */
+    private _scrollSelectedTabIntoBar(): void {
+        const id = this._state.selectedId;
+        const tab = id === null ? undefined : this._tabs.get(id);
+        if (!tab) return;
+        const pageSize = this._barEl.clientWidth;
+        const width = tab.offsetWidth;
+        // Unmeasured (detached, or still inside connectedCallback): nothing to scroll to.
+        if (pageSize <= 0 || width <= 0) return;
+
+        const value = this._barEl.scrollLeft;
+        const pos = this._tabPosition(tab);
+        const padding = Math.min(width, pageSize - width) / 2;
+        if (pos - TAB_SPACING < value) this._barEl.scrollLeft = pos - padding;
+        else if (pos + width + TAB_SPACING > value + pageSize)
+            this._barEl.scrollLeft = pos + width + padding - pageSize;
+    }
+
     private _applyBarVisibility(): void {
         const revealed = tabsRevealed({
             autohide: this.autohide,
@@ -710,9 +762,17 @@ export class AdwTabView extends HTMLElement {
         event.preventDefault();
         // Roving tabindex: the newly-active tab is the only focusable one, so
         // focus has to travel with it or the next keypress goes nowhere.
+        //
+        // `preventScroll` because a bare `focus()` scrolls every scrollable ancestor
+        // up to and including the WINDOW, while C only ever moves the tab strip
+        // (`scroll_to_tab_full` writes `self->adjustment`, adw-tab-box.c:928-961).
+        // Measured in a long documentation page: one ArrowRight took the window from
+        // y=1800 to y=8367, i.e. switching a tab yanked the whole document to the widget.
+        // `_scrollSelectedTabIntoBar` (already run by the selection change) is the
+        // strip-local scroll that is supposed to happen instead.
         if (inBar) {
             const id = this._state.selectedId;
-            if (id !== null) this._tabs.get(id)?.focus();
+            if (id !== null) this._tabs.get(id)?.focus({ preventScroll: true });
         }
     }
 

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

@@ -30,6 +30,7 @@ import {
     parseToolbarStyle,
     toolbarViewClasses,
 } from '@gjsify/adwaita-core';
+import { AdwScrollShading } from '../scroll-shading.js';
 
 export class AdwToolbarView extends HTMLElement {
     private _topEl!: HTMLDivElement;
@@ -37,6 +38,14 @@ export class AdwToolbarView extends HTMLElement {
     private _bottomEl!: HTMLDivElement;
     private _initialized = false;
     private _resize: ResizeObserver | null = null;
+    /**
+     * The scroll indicators for every scroller under this view.
+     *
+     * Owned HERE and not by a scroller widget, because upstream scopes them here:
+     * `toolbarview.undershoot-top scrolledwindow` shades whatever scrolls inside,
+     * however deeply nested — a split view's two panes included.
+     */
+    private _shading: AdwScrollShading | null = null;
 
     static get observedAttributes() {
         return ['top-bar-style', 'bottom-bar-style', 'extend-content-to-top-edge', 'extend-content-to-bottom-edge'];
@@ -87,6 +96,10 @@ export class AdwToolbarView extends HTMLElement {
 
         // `update_undershoots` runs from size_allocate, so the classes have to
         // follow the bars' real heights rather than a one-shot read.
+        // Before `_syncClasses`, which hands it the two undershoot flags it gates on.
+        this._shading = new AdwScrollShading(this._contentEl);
+        this._shading.connect();
+
         this._resize = new ResizeObserver(() => this._syncClasses());
         this._resize.observe(this._topEl);
         this._resize.observe(this._bottomEl);
@@ -96,6 +109,8 @@ export class AdwToolbarView extends HTMLElement {
     disconnectedCallback() {
         this._resize?.disconnect();
         this._resize = null;
+        this._shading?.disconnect();
+        this._shading = null;
     }
 
     attributeChangedCallback() {
@@ -117,6 +132,13 @@ export class AdwToolbarView extends HTMLElement {
             this._topEl.classList.toggle(cls, topBar.includes(cls));
             this._bottomEl.classList.toggle(cls, bottomBar.includes(cls));
         }
+
+        // The same two flags reach the scrollers, where the shade is actually
+        // drawn — a raised bar brings its own shadow and must not get a second one.
+        this._shading?.setUndershootEdges({
+            top: view.includes('undershoot-top'),
+            bottom: view.includes('undershoot-bottom'),
+        });
     }
 }
 

package/src/index.ts

@@ -34,6 +34,12 @@ export {
 } from './accent.js';
 export type { ApplyAccentOptions } from './accent.js';
 
+// GtkScrolledWindow's undershoot/overshoot indicators. `adw-toolbar-view` drives
+// this itself; exported so a consumer that owns its own chrome can shade a scroller
+// without one.
+export { AdwScrollShading } from './scroll-shading.js';
+export type { AdwUndershootEdges } from './scroll-shading.js';
+
 export { AdwAvatar } from './elements/adw-avatar.js';
 export { AdwBanner } from './elements/adw-banner.js';
 export { AdwCard } from './elements/adw-card.js';

package/src/scroll-shading.ts

@@ -0,0 +1,255 @@
+// Browser wiring for GtkScrolledWindow's edge indicators — the DOM half of
+// `@gjsify/adwaita-core`'s `scrolling.ts`, which owns the arithmetic.
+//
+// WHY a discovery pass and not a widget. GTK has a `scrolledwindow` node, so the
+// stylesheet can say `toolbarview.undershoot-top scrolledwindow` and be done. The
+// browser has no such element — any block with `overflow: auto` is one — so the
+// equivalent scope has to be computed. The scope is deliberately the same as
+// upstream's: a DESCENDANT selector, so a toolbar view shades EVERY scroller under
+// it, not only the one it directly wraps. That is what makes the storybook's three
+// panes (story list, preview, controls) each shade themselves independently.
+//
+// WHY the top and bottom indicators share one pseudo-element each. Undershoot and
+// overshoot at the same edge are mutually exclusive by construction: an undershoot
+// says content is hidden past the edge, an overshoot says the position is past it,
+// and `overshootDistance` is 0 for as long as `isScrolledFromStart` is true. One
+// box per edge, switched by which state is live.
+//
+// WHY sticky. The indicator has to stay welded to the scrollport edge while the
+// content moves under it, and it must consume no layout. `position: sticky` plus a
+// negative margin equal to its height is the only combination that does both — an
+// absolutely-positioned child of a scroll container scrolls away with the content.
+// The one constraint this leaves: a scroller that is itself a flex/grid container
+// with a `gap` pays that gap once for the pseudo-element. Scrollers are wrappers,
+// so this has not bitten; a scroller with a gap should move it to an inner box.
+//
+// Reference: refs/gtk/gtk/gtkscrolledwindow.c
+// Reference: refs/libadwaita/src/stylesheet/widgets/_scrolling.scss
+// Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+.
+
+import {
+    ADW_OVERSHOOT_SETTLE_MS,
+    ADW_UNDERSHOOT_CLASSES,
+    accumulateOvershoot,
+    overshootDistance,
+    type ScrollAdjustment,
+    scrollUndershootClasses,
+} from '@gjsify/adwaita-core';
+
+/** Marks a scroller adwaita-web has taken over, so the stylesheet can target it. */
+const SHADED_CLASS = 'adw-scroll-shaded';
+
+/** The custom property carrying the live overshoot size, in px. */
+const OVERSHOOT_PROPERTY = '--adw-overshoot';
+
+/** Which edge is currently overshooting, as a state class. */
+const OVERSHOOT_CLASSES = ['overshoot-top', 'overshoot-bottom'] as const;
+
+/**
+ * `overflow` values that make a box a scrollport.
+ *
+ * `overlay` is a WebKit alias for `auto` that a browser may still report from
+ * author CSS even though it is removed from the spec, so a scroller written that
+ * way is one and has to be treated as one.
+ */
+const SCROLLABLE_OVERFLOW = new Set(['auto', 'scroll', 'overlay']);
+
+/** Per-axis adjustments as the DOM reports them. */
+function adjustmentsOf(el: HTMLElement): { vertical?: ScrollAdjustment; horizontal?: ScrollAdjustment } {
+    const style = getComputedStyle(el);
+    const vertical = SCROLLABLE_OVERFLOW.has(style.overflowY)
+        ? { value: el.scrollTop, lower: 0, upper: el.scrollHeight, pageSize: el.clientHeight }
+        : undefined;
+    const horizontal = SCROLLABLE_OVERFLOW.has(style.overflowX)
+        ? { value: el.scrollLeft, lower: 0, upper: el.scrollWidth, pageSize: el.clientWidth }
+        : undefined;
+    return { vertical, horizontal };
+}
+
+/** Whether a box scrolls on either axis at all. */
+function isScroller(el: HTMLElement): boolean {
+    const style = getComputedStyle(el);
+    return SCROLLABLE_OVERFLOW.has(style.overflowY) || SCROLLABLE_OVERFLOW.has(style.overflowX);
+}
+
+/**
+ * A wheel delta in CSS pixels, whatever unit the event chose to speak in.
+ *
+ * `deltaMode` is not decoration — Firefox reports `DOM_DELTA_LINE` (3-ish per
+ * detent) where Chrome reports pixels (100-ish per detent), so an unconverted
+ * delta makes the overshoot two orders of magnitude smaller on one browser. The
+ * line height is the conventional 16px default scaled by the browser's own
+ * three-lines-per-detent step.
+ */
+function wheelDeltaPx(event: WheelEvent, port: number): number {
+    if (event.deltaMode === WheelEvent.DOM_DELTA_LINE) return event.deltaY * 16;
+    if (event.deltaMode === WheelEvent.DOM_DELTA_PAGE) return event.deltaY * port;
+    return event.deltaY;
+}
+
+/** Which vertical edges may draw an undershoot — a toolbar view's own two flags. */
+export interface AdwUndershootEdges {
+    /** `undershoot-top` on the view: the top bar is flat and was allocated a height. */
+    top: boolean;
+    /** `undershoot-bottom` on the view. */
+    bottom: boolean;
+}
+
+/**
+ * Keeps every scroller under a root marked with its live edge indicators.
+ *
+ * One instance per toolbar view. Scroll and wheel are listened for in the CAPTURE
+ * phase on the root: `scroll` does not bubble, but capture propagation runs down
+ * the whole path regardless, so one pair of listeners covers scrollers that appear
+ * later without re-binding per element.
+ */
+export class AdwScrollShading {
+    private _root: HTMLElement;
+    private _mutations: MutationObserver | null = null;
+    private _resize: ResizeObserver | null = null;
+    /** The unclamped position per scroller, i.e. `priv->unclamped_vadj_value`. */
+    private _unclamped = new WeakMap<HTMLElement, number>();
+    private _settleTimers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>();
+    /** Every scroller currently marked, so teardown and rescans can clear them. */
+    private _shaded = new Set<HTMLElement>();
+    private _pendingScan = 0;
+    private _undershootEdges: AdwUndershootEdges = { top: true, bottom: true };
+
+    constructor(root: HTMLElement) {
+        this._root = root;
+    }
+
+    /**
+     * Which edges may draw an UNDERSHOOT. The overshoot glow is not gated: upstream
+     * draws it on every `scrolledwindow`, while the undershoot is what a toolbar
+     * view turns on for a flat bar and off for a raised one, which has its own
+     * shadow (`update_undershoots`).
+     */
+    setUndershootEdges(edges: AdwUndershootEdges): void {
+        if (edges.top === this._undershootEdges.top && edges.bottom === this._undershootEdges.bottom) return;
+        this._undershootEdges = { ...edges };
+        for (const el of this._shaded) this._update(el);
+    }
+
+    /** Start observing. Idempotent. */
+    connect(): void {
+        if (this._mutations) return;
+        this._root.addEventListener('scroll', this._onScroll, { capture: true, passive: true });
+        this._root.addEventListener('wheel', this._onWheel, { capture: true, passive: true });
+        // A rescan reads the computed overflow of every descendant, so it is coalesced
+        // to one per frame: replacing a story fires a mutation record per node.
+        this._mutations = new MutationObserver(() => this._scheduleRefresh());
+        this._mutations.observe(this._root, { childList: true, subtree: true });
+        this._resize = new ResizeObserver(() => this._scheduleRefresh());
+        this._resize.observe(this._root);
+        this.refresh();
+    }
+
+    /** Stop observing and clear every class this instance set. */
+    disconnect(): void {
+        this._root.removeEventListener('scroll', this._onScroll, { capture: true });
+        this._root.removeEventListener('wheel', this._onWheel, { capture: true });
+        this._mutations?.disconnect();
+        this._mutations = null;
+        this._resize?.disconnect();
+        this._resize = null;
+        if (this._pendingScan) cancelAnimationFrame(this._pendingScan);
+        this._pendingScan = 0;
+        for (const el of this._shaded) this._clear(el);
+        this._shaded.clear();
+    }
+
+    private _scheduleRefresh(): void {
+        if (this._pendingScan) return;
+        this._pendingScan = requestAnimationFrame(() => {
+            this._pendingScan = 0;
+            this.refresh();
+        });
+    }
+
+    /** Re-scan for scrollers and re-derive every indicator. */
+    refresh(): void {
+        const found = new Set<HTMLElement>();
+        // The ROOT counts: a toolbar view whose content area scrolls on its own is
+        // the common case, and `querySelectorAll` never returns the element it was
+        // called on.
+        if (isScroller(this._root)) found.add(this._root);
+        for (const el of this._root.querySelectorAll<HTMLElement>('*')) {
+            if (isScroller(el)) found.add(el);
+        }
+        for (const el of this._shaded) {
+            if (!found.has(el)) this._clear(el);
+        }
+        this._shaded = found;
+        for (const el of found) this._update(el);
+    }
+
+    private _clear(el: HTMLElement): void {
+        el.classList.remove(SHADED_CLASS, ...ADW_UNDERSHOOT_CLASSES, ...OVERSHOOT_CLASSES);
+        el.style.removeProperty(OVERSHOOT_PROPERTY);
+    }
+
+    /** Re-derive the undershoot classes of one scroller from its current position. */
+    private _update(el: HTMLElement): void {
+        el.classList.add(SHADED_CLASS);
+        const live = scrollUndershootClasses(adjustmentsOf(el));
+        for (const cls of ADW_UNDERSHOOT_CLASSES) {
+            const allowed =
+                (cls !== 'undershoot-top' || this._undershootEdges.top) &&
+                (cls !== 'undershoot-bottom' || this._undershootEdges.bottom);
+            el.classList.toggle(cls, allowed && live.includes(cls));
+        }
+    }
+
+    private _onScroll = (event: Event): void => {
+        const el = event.target;
+        if (el instanceof HTMLElement && this._shaded.has(el)) this._update(el);
+    };
+
+    /**
+     * The overshoot half. A browser scroll container clamps at its edge and reports
+     * nothing further, so the push past it is read off the wheel deltas the
+     * container could not consume — which is exactly the value upstream keeps in
+     * `unclamped_vadj_value` and clamps one overshoot distance out.
+     */
+    private _onWheel = (event: WheelEvent): void => {
+        const el = event.target instanceof HTMLElement ? this._scrollerFor(event.target) : null;
+        if (!el) return;
+        const { vertical } = adjustmentsOf(el);
+        if (!vertical) return;
+
+        const previous = this._unclamped.get(el) ?? vertical.value;
+        // A scroll that landed back inside the range resets the accumulator: the
+        // position the user pushed from is the real one again.
+        const base = overshootDistance(previous, vertical) === 0 ? vertical.value : previous;
+        const next = accumulateOvershoot(base, wheelDeltaPx(event, vertical.pageSize), vertical);
+        this._unclamped.set(el, next);
+        this._applyOvershoot(el, overshootDistance(next, vertical));
+
+        // Spring back once the wheel STOPS, not between two detents of one gesture.
+        clearTimeout(this._settleTimers.get(el));
+        this._settleTimers.set(
+            el,
+            setTimeout(() => {
+                this._unclamped.set(el, el.scrollTop);
+                this._applyOvershoot(el, 0);
+            }, ADW_OVERSHOOT_SETTLE_MS),
+        );
+    };
+
+    private _applyOvershoot(el: HTMLElement, distance: number): void {
+        el.classList.toggle('overshoot-top', distance < 0);
+        el.classList.toggle('overshoot-bottom', distance > 0);
+        if (distance === 0) el.style.removeProperty(OVERSHOOT_PROPERTY);
+        else el.style.setProperty(OVERSHOOT_PROPERTY, `${Math.abs(distance)}px`);
+    }
+
+    /** The nearest shaded scroller at or above a wheel target, root included. */
+    private _scrollerFor(target: HTMLElement): HTMLElement | null {
+        for (let el: HTMLElement | null = target; el; el = el.parentElement) {
+            if (this._shaded.has(el)) return el;
+            if (el === this._root) break;
+        }
+        return null;
+    }
+}