@gjsify/adwaita-web 0.40.0 → 0.41.0

package/src/chrome.spec.ts

@@ -90,6 +90,92 @@ function mountToolbarView(topBarHeight: number, bottomBarHeight: number): { host
     return { host, view };
 }
 
+/**
+ * A widget mounted the way the docs site mounts a preview: a fixed-height flex
+ * row, the markup attached in ONE piece from an inert `<template>`.
+ *
+ * The template is not decoration. A nested composite (a split view holding
+ * toolbar views) upgraded child-by-child by the parser can lose its slotted
+ * children to an upgrade-order race, so both the docs site and these tests build
+ * the subtree first and attach it afterwards.
+ */
+function mountPreview(markup: string, height = 340, width = 640): HTMLElement {
+    const host = document.createElement('div');
+    host.style.cssText = `height: ${height}px; width: ${width}px; display: flex; overflow: hidden;`;
+    const template = document.createElement('template');
+    template.innerHTML = markup;
+    host.append(template.content.cloneNode(true));
+    document.body.append(host);
+    return host;
+}
+
+/** Rounded to the pixel it renders at, as `clampedWidth` does for the clamp. */
+function heightOf(el: Element | null): number {
+    return el ? Math.round(el.getBoundingClientRect().height) : -1;
+}
+
+/** The sidebar pane of the Navigation Split View preview (docs/adwaita/navigation.mdx). */
+const SIDEBAR_PANE_PREVIEW = `
+<adw-toolbar-view style="flex: 1;">
+  <adw-header-bar slot="top">
+    <adw-window-title slot="center" title="Mailboxes"></adw-window-title>
+  </adw-header-bar>
+  <adw-sidebar mode="sidebar" selected="0">
+    <adw-sidebar-section>
+      <adw-sidebar-item title="All Mail" subtitle="128 messages" icon-name="mail-unread-symbolic"></adw-sidebar-item>
+      <adw-sidebar-item title="Starred" subtitle="6 messages" icon-name="starred-symbolic"></adw-sidebar-item>
+      <adw-sidebar-item title="Drafts" subtitle="2 messages" icon-name="document-edit-symbolic"></adw-sidebar-item>
+      <adw-sidebar-item title="Archive" subtitle="512 messages" icon-name="folder-symbolic"></adw-sidebar-item>
+    </adw-sidebar-section>
+  </adw-sidebar>
+</adw-toolbar-view>`;
+
+/** The content pane of the same preview: a status page that centres itself. */
+const STATUS_PANE_PREVIEW = `
+<adw-toolbar-view style="flex: 1;">
+  <adw-header-bar slot="top">
+    <adw-window-title slot="center" title="All Mail"></adw-window-title>
+  </adw-header-bar>
+  <adw-status-page icon="mail-unread-symbolic" title="All Mail" description="Select a conversation from the list to read it here."></adw-status-page>
+</adw-toolbar-view>`;
+
+/**
+ * The root page of the Navigation View preview: a lone action button.
+ *
+ * A GTK button asked to sit in the middle of a ToolbarView says
+ * `halign/valign: CENTER`; the web spelling is a centring box around it, which is
+ * what the preview now carries. It used to carry a bare
+ * `class="adw-navigation-view-root-action"` matching no rule in any stylesheet.
+ */
+const ROOT_ACTION_PREVIEW = `
+<adw-toolbar-view style="flex: 1;">
+  <adw-header-bar slot="top">
+    <adw-window-title slot="center" title="Contacts"></adw-window-title>
+  </adw-header-bar>
+  <div style="display: flex; align-items: center; justify-content: center; width: 100%; height: 100%;">
+    <adw-button label="Open contact" pill suggested></adw-button>
+  </div>
+</adw-toolbar-view>`;
+
+/**
+ * A tab view in a toolbar view: the horizontal scroller the shading also reaches.
+ *
+ * `expand-tabs` is off on purpose, so enough tabs really do overflow the strip
+ * rather than being squeezed into it.
+ */
+const TAB_STRIP_PREVIEW = (pages: number): string => `
+<adw-toolbar-view style="flex: 1;">
+  <adw-header-bar slot="top">
+    <adw-window-title slot="center" title="Editor"></adw-window-title>
+  </adw-header-bar>
+  <adw-tab-view no-close="true">
+    ${Array.from(
+        { length: pages },
+        (_, i) => `<adw-tab-page title="A rather long tab title ${i}"><div>page ${i}</div></adw-tab-page>`,
+    ).join('')}
+  </adw-tab-view>
+</adw-toolbar-view>`;
+
 export const AdwChromeTest = async () => {
     await describe('adw-clamp allocation (AdwClampLayout conformance vectors)', async () => {
         // The browser resolves the child's own minimum through the normal `min-width`
@@ -389,4 +475,151 @@ export const AdwChromeTest = async () => {
             host.remove();
         });
     });
+
+    // `adw_toolbar_view_size_allocate` hands its ONE content widget the whole
+    // content rect; a widget that wants less says so with its own alignment.
+    // This port collected the content into a flex COLUMN, where an item that
+    // declares no `flex-grow` is content-sized instead, so the child stopped
+    // wherever its content did and the rest of the pane stayed empty.
+    await describe('adw-toolbar-view content allocation (size_allocate gives the content the whole rect)', async () => {
+        await it('stretches a lone content child past its own content height', async () => {
+            const host = mountPreview(SIDEBAR_PANE_PREVIEW);
+            await settle();
+            const area = host.querySelector('.adw-toolbar-view-content');
+            const sidebar = host.querySelector('adw-sidebar') as HTMLElement;
+
+            // The two discriminators, without which this passes on a broken build:
+            // the bar must really have taken height off the top, and the sidebar's
+            // own content must really be shorter than the area it has to fill,
+            // otherwise "child height == area height" is a coincidence. The rows are
+            // measured through the LIST, not through the sidebar's own scrollHeight:
+            // once the sidebar fills, its scrollHeight is its new height and the
+            // discriminator would have measured the fix instead of the content.
+            expect(heightOf(area) > 0 && heightOf(area) < 340).toBe(true);
+            expect(heightOf(sidebar.querySelector('.adw-sidebar-list')) < heightOf(area)).toBe(true);
+
+            expect(heightOf(sidebar)).toBe(heightOf(area));
+            host.remove();
+        });
+
+        await it('centres a status page in the pane rather than against its top bar', async () => {
+            const host = mountPreview(STATUS_PANE_PREVIEW);
+            await settle();
+            const area = host.querySelector('.adw-toolbar-view-content') as HTMLElement;
+            const status = host.querySelector('adw-status-page') as HTMLElement;
+
+            expect(heightOf(area) > 0 && heightOf(area) < 340).toBe(true);
+            expect(heightOf(status)).toBe(heightOf(area));
+
+            // What the reader actually sees, and the discriminator at the same time:
+            // an Adw.StatusPage centres its own column, so equal air above the icon
+            // and below the description is only reachable once it owns the whole
+            // pane. Top-aligned in the pane it measured 24px of padding above and
+            // some 60px of window background below.
+            const areaBox = area.getBoundingClientRect();
+            const above =
+                (status.querySelector('.adw-status-page-icon') as HTMLElement).getBoundingClientRect().top -
+                areaBox.top;
+            const description = status.querySelector('.adw-status-page-description') as HTMLElement;
+            const below = areaBox.bottom - description.getBoundingClientRect().bottom;
+            expect(Math.abs(above - below) <= 2).toBe(true);
+            host.remove();
+        });
+
+        await it('stretches a centring box and lets IT place the button, which keeps its own size', async () => {
+            const host = mountPreview(ROOT_ACTION_PREVIEW);
+            await settle();
+            const area = host.querySelector('.adw-toolbar-view-content') as HTMLElement;
+            const button = host.querySelector('adw-button') as HTMLElement;
+
+            expect(heightOf(area.firstElementChild)).toBe(heightOf(area));
+            // A pill button that grew to the pane's height would be the fill applied
+            // one level too deep. The alignment box exists precisely to absorb it.
+            expect(heightOf(button) > 0 && heightOf(button) < heightOf(area)).toBe(true);
+
+            const areaBox = area.getBoundingClientRect();
+            const buttonBox = button.getBoundingClientRect();
+            expect(Math.abs(buttonBox.top - areaBox.top - (areaBox.bottom - buttonBox.bottom)) <= 2).toBe(true);
+            expect(Math.abs(buttonBox.left - areaBox.left - (areaBox.right - buttonBox.right)) <= 2).toBe(true);
+            host.remove();
+        });
+    });
+
+    // The undershoot says "there IS content past this edge". A scroller whose
+    // content fits has none, so it must draw neither edge. That is the state the
+    // storybook got wrong for every scroller at rest, and the reason
+    // `scrollUndershootClasses` exists. Asserted here on a REAL scroller,
+    // because the core spec only ever sees the arithmetic.
+    await describe('adw-toolbar-view scroll shading (no undershoot where nothing can scroll)', async () => {
+        await it('leaves both edges clean while the content fits', async () => {
+            const host = mountPreview(SIDEBAR_PANE_PREVIEW);
+            await settle();
+            const area = host.querySelector('.adw-toolbar-view-content') as HTMLElement;
+
+            // Both scrollers under the view: the content area and the sidebar's own
+            // list, which is the node upstream shades (`AdwSidebar` wraps a
+            // GtkScrolledWindow) once the pane is tall enough to hold every row.
+            for (const el of [area, host.querySelector('adw-sidebar') as HTMLElement]) {
+                // The discriminator: the shading really is wired to this scroller, so
+                // "no undershoot class" is a decision and not a controller that never ran.
+                expect(el.classList.contains('adw-scroll-shaded')).toBe(true);
+                expect(el.scrollHeight).toBe(el.clientHeight);
+                expect(el.classList.contains('undershoot-top')).toBe(false);
+                expect(el.classList.contains('undershoot-bottom')).toBe(false);
+            }
+            host.remove();
+        });
+
+        await it('draws the top edge once there IS content past it', async () => {
+            // A status page, not the sidebar: a status page cannot scroll on its own,
+            // so the content area is the scroller and the shade belongs to it. And the
+            // TOP edge, because `update_undershoots` gates the bottom one on a bottom
+            // bar this view does not have, so asserting the bottom edge here would pass
+            // whatever the controller decided.
+            const host = mountPreview(STATUS_PANE_PREVIEW, 120);
+            await settle();
+            const area = host.querySelector('.adw-toolbar-view-content') as HTMLElement;
+            expect(area.scrollHeight > area.clientHeight).toBe(true);
+            expect(area.classList.contains('undershoot-top')).toBe(false);
+
+            // A REAL scroll, then the frames the `scroll` event is delivered in.
+            area.scrollTop = area.scrollHeight;
+            await settle();
+            await settle();
+            expect(area.classList.contains('undershoot-top')).toBe(true);
+
+            // ONE owner draws the shade. `undershoot-top` is also a documented
+            // libadwaita style class with its own inset host shadow in
+            // `_style_classes.scss`, so a scroller wearing the state class used to
+            // get that 6px blurred shadow UNDER the 1px line + 4px fade this package
+            // paints on the pseudo-element: the same edge, twice, in two sizes.
+            expect(getComputedStyle(area).boxShadow).toBe('none');
+            expect(getComputedStyle(area, '::before').boxShadow === 'none').toBe(false);
+            host.remove();
+        });
+
+        await it('leaves a horizontally overflowing tab strip its own hairline', async () => {
+            // The horizontal pair has no rule in `_scrolling.scss` at all, because
+            // neither AdwTabBox nor AdwCarousel has a `scrolledwindow` node for GTK to
+            // shade. The style class did have one, and it is `box-shadow` too — so an
+            // overflowing strip silently traded its `inset 0 -1px` bottom shade for an
+            // edge shadow libadwaita never draws there.
+            const wide = mountPreview(TAB_STRIP_PREVIEW(8), 260, 320);
+            const narrow = mountPreview(TAB_STRIP_PREVIEW(1), 260, 320);
+            await settle();
+            await settle();
+            const overflowing = wide.querySelector('.adw-tab-bar') as HTMLElement;
+            const fitting = narrow.querySelector('.adw-tab-bar') as HTMLElement;
+
+            // The two discriminators: the strip really does overflow, and the shading
+            // controller really did reach it. Without them this is two identical bars.
+            expect(overflowing.scrollWidth > overflowing.clientWidth).toBe(true);
+            expect(overflowing.classList.contains('undershoot-end')).toBe(true);
+            expect(fitting.scrollWidth).toBe(fitting.clientWidth);
+
+            expect(getComputedStyle(overflowing).boxShadow).toBe(getComputedStyle(fitting).boxShadow);
+            wide.remove();
+            narrow.remove();
+        });
+    });
 };

package/src/elements/adw-carousel.ts

@@ -27,7 +27,7 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as Web Components for @gjsify/adwaita-web.
 
-import { CarouselState } from '@gjsify/adwaita-core';
+import { CarouselState, carouselPageAllocation } from '@gjsify/adwaita-core';
 import type { CarouselScrollRequest, CarouselScrollSource, CarouselStateChange } from '@gjsify/adwaita-core';
 
 /** Common surface an indicator binds to. The concrete element is AdwCarousel. */
@@ -79,12 +79,21 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
     /** A declared `position` waiting for the track to have a width. */
     private _pendingPosition: number | null = null;
     private _pendingLayout: ResizeObserver | undefined;
+    /** Watches the carousel's own width, which caps the page size. */
+    private _layoutObserver: ResizeObserver | undefined;
     /**
      * `interactive` for the scroll now in flight: the flag of the request that
      * started it, or `null` for a scroll we did not start — which is a user drag,
      * and therefore interactive.
      */
     private _pendingInteractive: boolean | null = null;
+    /**
+     * The page an issued scroll is travelling TO, `null` once it has arrived:
+     * `self->animation_target_child`. Held as the page's ID and not its index, for the
+     * same reason C holds a widget, since an insert or a reorder in between moves the
+     * index while the target page stays the target.
+     */
+    private _scrollTargetId: string | null = null;
 
     static get observedAttributes() {
         return ['allow-scroll-wheel', 'allow-long-swipes', 'interactive', 'spacing', 'position'];
@@ -159,7 +168,13 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
     }
 
     connectedCallback() {
-        if (this._initialized) return;
+        if (!this._initialized) this._build();
+        // Re-armed on every connect, because `disconnectedCallback` drops it: a
+        // carousel moved into another parent has a new width to follow.
+        this._observeLayout();
+    }
+
+    private _build(): void {
         this._initialized = true;
 
         this._trackEl = document.createElement('div');
@@ -200,6 +215,28 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         // A pending declared position watches the track for its first layout; a
         // carousel removed before that must not keep the observer alive.
         this._cancelPendingPosition();
+        this._layoutObserver?.disconnect();
+        this._layoutObserver = undefined;
+    }
+
+    /**
+     * Re-run the page allocation whenever the carousel's own width changes: the page
+     * size is capped by it, so a resize can turn a peek into a full-width page and back.
+     */
+    private _observeLayout(): void {
+        if (this._layoutObserver) return;
+        this._layoutObserver = new ResizeObserver(() => {
+            // Only when the PITCH changed. The scroll offset is `position * distance`,
+            // so a resize that leaves the page size alone leaves the offset meaning
+            // exactly what it meant. Re-applying it unconditionally rewound every scroll
+            // still in flight: the observer's first delivery lands in the same frame as
+            // the wheel or drag that started one, and the model only learns the new
+            // offset from the scroll event that has not arrived yet.
+            if (this._allocatePages()) this._applyScrollFromModel();
+        });
+        // The BORDER box: the inset is written as track padding, and observing the
+        // content box would report that write back to us as a resize.
+        this._layoutObserver.observe(this._trackEl, { box: 'border-box' });
     }
 
     private _applyAttribute(name: string, value: string | null): void {
@@ -378,9 +415,64 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
             }
         });
         this._applySnapStop();
+        this._allocatePages();
         this._applyScrollFromModel();
     }
 
+    /**
+     * Size the pages as `adw_carousel_size_allocate` does, and centre the strip in the
+     * carousel.
+     *
+     * A page is NOT the carousel's width. Every page is allocated the same size, the
+     * largest natural one capped at the carousel (adw-carousel.c:748-765), and the strip
+     * is drawn at an offset of `-(width - child_width) / 2` (:801), so whatever is left
+     * over shows the previous and next page at the two edges. The `flex: 0 0 100%` this
+     * replaces reproduced only the case where nothing is left over: the 440px pages of
+     * the Carousel story sat in a 480px carousel with both neighbours entirely off
+     * screen, where GTK shows 20px of each.
+     *
+     * The inset is track PADDING paired with `scroll-snap-align: center`, which is what
+     * keeps `scrollLeft = position * distance` true either way: page i then snaps at
+     * `inset + i * distance + pageSize / 2 - available / 2`, and the two insets cancel.
+     *
+     * Returns whether the page size, and with it the scroll pitch, actually moved.
+     */
+    private _allocatePages(): boolean {
+        const slots = [...this._slots.values()];
+        if (slots.length === 0) return false;
+
+        // What the pages are laid out at RIGHT NOW, read before the reset below. "Did
+        // the pitch change" has to be answered from the DOM rather than from a
+        // remembered write, or the first pass over an already-correct layout counts as
+        // a change and moves a scroll that had no reason to move.
+        const before = slots[0]!.getBoundingClientRect().width;
+
+        // Measure against the FULL-width allocation: a page whose content is
+        // `width: 100%` reports back whatever the slot currently is, so measuring it
+        // inside an already narrowed slot would shrink the pages again on every pass.
+        this._trackEl.style.removeProperty('padding-inline');
+        for (const slot of slots) slot.style.removeProperty('flex-basis');
+
+        const available = this._trackEl.clientWidth;
+        if (!(available > 0)) return false;
+
+        // `natural` only: CSS has already resolved a page's own `min-width` and every
+        // spelling of "fill the carousel" into the width it renders at, so there is no
+        // separate minimum or hexpand left for the renderer to pass.
+        const measurements = slots.map((slot) => ({
+            natural: (slot.firstElementChild as HTMLElement | null)?.getBoundingClientRect().width ?? 0,
+        }));
+        const { pageSize, leadingInset } = carouselPageAllocation(available, measurements);
+        // A page that measures nothing yet (an image still loading, a font not
+        // applied) would collapse the whole strip; the full-width fallback stands
+        // until the resize that gives it a size.
+        if (!(pageSize > 0)) return false;
+
+        for (const slot of slots) slot.style.flexBasis = `${pageSize}px`;
+        if (leadingInset > 0) this._trackEl.style.paddingInline = `${leadingInset}px`;
+        return Math.round(pageSize) !== Math.round(before);
+    }
+
     /**
      * Put the scroll offset back where the model says it is, instantly. A page revealed
      * at or before the current one moves the position with it (`shift_position`)
@@ -391,7 +483,29 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
     private _applyScrollFromModel(): void {
         const distance = this._distance();
         if (!(distance > 0)) return;
-        this._trackEl.scrollTo({ left: this._state.position * distance, behavior: 'instant' });
+        this._trackEl.scrollTo({ left: this._restorePosition() * distance, behavior: 'instant' });
+    }
+
+    /**
+     * Which position that write must aim at. Normally the model's, but a scroll still
+     * in flight has not reached the model yet: `scrollTo` only ASKS, and `position`
+     * catches up from the `scroll` event a frame later. Re-applying the stale position
+     * there parks the carousel back where it started and swallows the scroll, which is
+     * how `<adw-carousel position="2">` lost its page: the pending-position observer
+     * and the layout observer are delivered in ONE resize pass, so the very first
+     * allocation landed on a scroll it had just issued.
+     *
+     * `size_allocate` reaches the same moment and re-aims rather than rewinds: it
+     * pushes the recomputed snap point of `animation_target_child` into the running
+     * animation (adw-carousel.c:786-788).
+     */
+    private _restorePosition(): number {
+        if (this._scrollTargetId === null) return this._state.position;
+        const index = this._state.ids.indexOf(this._scrollTargetId);
+        // The target page was removed while the scroll ran; the model's position is
+        // then the only thing left that means anything.
+        if (index < 0) return this._state.position;
+        return this._state.snapPointOf(index) ?? this._state.position;
     }
 
     /**
@@ -416,6 +530,7 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         const distance = this._distance();
         if (!(distance > 0)) return;
         this._pendingInteractive = request.interactive;
+        this._scrollTargetId = this._state.ids[request.index] ?? null;
         // `offset = distance * position`, NOT `slot.offsetLeft` — that is measured from
         // the nearest POSITIONED ancestor and coincides with the scroll offset only by
         // accident.
@@ -454,7 +569,9 @@ export class AdwCarousel extends HTMLElement implements CarouselHost {
         // `scroll_animation_done_cb` has an animation to tell it the scroll
         // finished; scroll-snap has only the offset, so the core stands ARRIVAL
         // at a snap point in for it.
-        if (this._state.settleIfArrived()) this._pendingInteractive = null;
+        if (!this._state.settleIfArrived()) return;
+        this._pendingInteractive = null;
+        this._scrollTargetId = null;
     }
 
     private _onStateChange(change: CarouselStateChange): void {

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';