@gjsify/adwaita-web 0.40.0 → 0.41.0

package/lib/types/elements/adw-carousel.d.ts

@@ -19,12 +19,21 @@ export declare class AdwCarousel extends HTMLElement implements CarouselHost {
     /** A declared `position` waiting for the track to have a width. */
     private _pendingPosition;
     private _pendingLayout;
+    /** Watches the carousel's own width, which caps the page size. */
+    private _layoutObserver;
     /**
      * `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;
+    /**
+     * 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;
     static get observedAttributes(): string[];
     constructor();
     get nPages(): number;
@@ -50,8 +59,14 @@ export declare class AdwCarousel extends HTMLElement implements CarouselHost {
     get spacing(): number;
     set spacing(value: number);
     connectedCallback(): void;
+    private _build;
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
     disconnectedCallback(): void;
+    /**
+     * 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;
     private _applyAttribute;
     /**
      * Scroll to `value`, waiting for the first layout when the track has no width yet:
@@ -95,6 +110,25 @@ export declare class AdwCarousel extends HTMLElement implements CarouselHost {
     private _insert;
     private _idOf;
     private _syncTrack;
+    /**
+     * 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;
     /**
      * 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`)
@@ -103,6 +137,20 @@ export declare class AdwCarousel extends HTMLElement implements CarouselHost {
      * from the allocation that adds the child; here it takes one write.
      */
     private _applyScrollFromModel;
+    /**
+     * 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;
     /**
      * `allow-long-swipes` in CSS: `scroll-snap-stop: always` forces the scroll to
      * stop at every page, which is exactly what the property being FALSE means —

package/lib/types/elements/adw-tab-view.d.ts

@@ -108,6 +108,17 @@ export declare class AdwTabView extends HTMLElement {
     private _insertTab;
     private _moveTab;
     private _refreshTab;
+    /**
+     * `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;
     /**
      * `tabCloseVisible`, with its pinned gate. `dragging` is constantly false — tab
      * drag-and-drop is compositor work and is not modelled — and `fullyVisible` is
@@ -117,6 +128,18 @@ export declare class AdwTabView extends HTMLElement {
     private _refreshCloseVisibility;
     private _onSelectionChange;
     private _applyActiveState;
+    /**
+     * `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;
     private _applyBarVisibility;
     private _reflectSelected;
     private _applySelectedAttribute;

package/lib/types/elements/adw-toolbar-view.d.ts

@@ -4,6 +4,14 @@ export declare class AdwToolbarView extends HTMLElement {
     private _bottomEl;
     private _initialized;
     private _resize;
+    /**
+     * 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;
     static get observedAttributes(): string[];
     /** The top-bar container — append header bars here imperatively. */
     get topBar(): HTMLDivElement;

package/lib/types/index.d.ts

@@ -2,6 +2,8 @@ import '@gjsify/adwaita-fonts';
 export { addBreakpoints, bindBreakpointSetter } from './breakpoints.js';
 export { ACCENT_BG_PROPERTY, ACCENT_PROPERTY, applyAdwaitaAccent, clearAdwaitaAccent, isAdwaitaDark, } from './accent.js';
 export type { ApplyAccentOptions } from './accent.js';
+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/lib/types/scroll-shading.d.ts

@@ -0,0 +1,56 @@
+/** 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 declare class AdwScrollShading {
+    private _root;
+    private _mutations;
+    private _resize;
+    /** The unclamped position per scroller, i.e. `priv->unclamped_vadj_value`. */
+    private _unclamped;
+    private _settleTimers;
+    /** Every scroller currently marked, so teardown and rescans can clear them. */
+    private _shaded;
+    private _pendingScan;
+    private _undershootEdges;
+    constructor(root: HTMLElement);
+    /**
+     * 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;
+    /** Start observing. Idempotent. */
+    connect(): void;
+    /** Stop observing and clear every class this instance set. */
+    disconnect(): void;
+    private _scheduleRefresh;
+    /** Re-scan for scrollers and re-derive every indicator. */
+    refresh(): void;
+    private _clear;
+    /** Re-derive the undershoot classes of one scroller from its current position. */
+    private _update;
+    private _onScroll;
+    /**
+     * 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;
+    private _applyOvershoot;
+    /** The nearest shaded scroller at or above a wheel target, root included. */
+    private _scrollerFor;
+}