@gjsify/adwaita-web 0.39.0 → 0.41.0

package/src/bottom-sheet.spec.ts

@@ -201,6 +201,93 @@ export const AdwBottomSheetTest = async () => {
             sheet.remove();
         });
 
+        await it('a dismissed sheet re-opens, through either toggle spelling', () => {
+            // Reported as "the sheet never comes back": a preview that mounts open, gets
+            // dismissed by a scrim click, and then stays closed. Every other case here
+            // stops at its FIRST close, so a close path that latched (a listener torn
+            // down and never re-attached, a state that only travels one way) could have
+            // kept the suite green. The two spellings are the two a host actually
+            // writes: `sheet.open = !sheet.open`, and `toggleAttribute('open')` (what the
+            // storybook story uses), which only works while the element keeps reflecting
+            // the state back onto the attribute.
+            const sheet = document.createElement('adw-bottom-sheet') as AdwBottomSheet;
+            // `open="true"`, not a bare `open`: that is what Astro's MDX compiler emits
+            // for the documentation preview, so it is the markup that gets upgraded.
+            sheet.setAttribute('open', 'true');
+            sheet.innerHTML =
+                '<adw-bottom-sheet-content><button id="under">Under</button></adw-bottom-sheet-content>' +
+                '<adw-bottom-sheet-sheet><button id="inside">Inside</button></adw-bottom-sheet-sheet>';
+            document.body.appendChild(sheet);
+            expect(sheet.open).toBe(true);
+
+            const payloads: boolean[] = [];
+            sheet.addEventListener('notify::open', (event) => {
+                payloads.push((event as CustomEvent).detail.open);
+            });
+
+            dimming(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(false);
+            expect(sheet.hasAttribute('open')).toBe(false);
+
+            sheet.open = true;
+            expect(sheet.open).toBe(true);
+            expect(sheet.hasAttribute('open')).toBe(true);
+            expect(sheet.classList.contains('open')).toBe(true);
+            // The scrim has to become interactive again, or the sheet is dismissible
+            // exactly once even though the state reopened.
+            expect(dimming(sheet).classList.contains('visible')).toBe(true);
+
+            sheet.toggleAttribute('open');
+            expect(sheet.open).toBe(false);
+            sheet.toggleAttribute('open');
+            expect(sheet.open).toBe(true);
+
+            expect(payloads).toStrictEqual([false, true, false, true]);
+            sheet.remove();
+        });
+
+        await it('survives the template-clone mount the docs preview uses, and reopens from it', () => {
+            // Every other case here builds the sheet with createElement, so the element
+            // is upgraded before it has children. The documentation site never does
+            // that: it clones an inert <template> and appends the whole subtree in ONE
+            // insertion, so the sheet is constructed, gets its attributes and is
+            // connected while the same walk is still upgrading its descendants, and its
+            // connectedCallback moves those descendants into the content/sheet layers
+            // mid-walk. That is the mount the reported "the sheet never comes back" was
+            // seen in, and the toggle button has to come back out of it wired and
+            // reachable or the preview has no way back from a scrim dismissal.
+            const tpl = document.createElement('template');
+            tpl.innerHTML =
+                '<adw-bottom-sheet open="true" modal="true" can-close="true">' +
+                '<adw-bottom-sheet-content><adw-button pill>Toggle sheet</adw-button></adw-bottom-sheet-content>' +
+                '<adw-bottom-sheet-sheet><button id="inside">Inside</button></adw-bottom-sheet-sheet>' +
+                '</adw-bottom-sheet>';
+            const stage = document.createElement('div');
+            document.body.appendChild(stage);
+            stage.append(tpl.content.cloneNode(true));
+
+            const sheet = stage.querySelector('adw-bottom-sheet') as AdwBottomSheet;
+            expect(sheet.open).toBe(true);
+
+            const toggle = sheet.querySelector('.adw-bottom-sheet-content adw-button') as HTMLElement;
+            expect(toggle).toBeTruthy();
+            expect(insideSheet(sheet).id).toBe('inside');
+            // What the page binds: a listener on the custom element, driven by a click
+            // on the inner native button.
+            toggle.addEventListener('click', () => sheet.toggleAttribute('open'));
+            const inner = toggle.querySelector('button') as HTMLElement;
+
+            dimming(sheet).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(false);
+
+            inner.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+            expect(sheet.open).toBe(true);
+            expect(sheet.classList.contains('open')).toBe(true);
+            expect(dimming(sheet).classList.contains('visible')).toBe(true);
+
+            stage.remove();
+        });
+
         await it('a dimming click on a CLOSED sheet does nothing and signals nothing', () => {
             // The scrim is `can_target = open`, so it is not reachable at all — unlike
             // Escape, it does not signal.

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-button.ts

@@ -9,15 +9,12 @@
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // icon node is <adw-icon>.
 
+import { buttonStyleClasses } from '@gjsify/adwaita-core';
+
 import { createAdwIcon } from './adw-icon.js';
 
-const VARIANT_CLASSES: Record<string, string> = {
-    flat: 'flat',
-    suggested: 'suggested-action',
-    destructive: 'destructive-action',
-    circular: 'circular',
-    pill: 'pill',
-};
+/** The boolean attributes that select a style class; the mapping lives in the core. */
+const STYLE_ATTRIBUTES = ['flat', 'suggested', 'destructive', 'circular', 'pill'] as const;
 
 export class AdwButton extends HTMLElement {
     private _button!: HTMLButtonElement;
@@ -50,9 +47,10 @@ export class AdwButton extends HTMLElement {
     private _render() {
         const btn = this._button;
         btn.className = 'adw-button';
-        for (const [attr, cls] of Object.entries(VARIANT_CLASSES)) {
-            if (this.hasAttribute(attr)) btn.classList.add(cls);
-        }
+        // The attribute → class mapping is `@gjsify/adwaita-core`'s, so this element
+        // and the NativeScript one cannot disagree about which classes exist —
+        // `circular` was in this table and missing from that one.
+        btn.classList.add(...buttonStyleClasses(STYLE_ATTRIBUTES.filter((attr) => this.hasAttribute(attr))));
 
         const icon = this.getAttribute('icon');
         const label = (this.getAttribute('label') ?? this._label).trim();

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-entry.ts

@@ -1,18 +1,33 @@
 // <adw-entry> — Adwaita single-line text entry (e.g. a browser URL bar).
-// Attributes: value, placeholder, type, disabled.
-// Property: value (get/set, proxies the inner input).
+// Attributes: value, placeholder, type, disabled, maxlength.
+// Properties: value (get/set, proxies the inner input), maxLength, textLength.
 // Events: native `input` bubbles from the inner input; `activate` (CustomEvent)
 //   fires on Enter — mirroring Gtk.Entry's `activate` signal.
+//
+// The character arithmetic is HEADLESS and lives in `@gjsify/adwaita-core`
+// (ADR 0004): `entryTextLength` counts CODE POINTS and `clampEntryText` truncates
+// on them. `@gjsify/adwaita-nativescript`'s AdwEntry has composed the same two
+// since it shipped; this element counted nothing at all, so the same consumer
+// got a max length on one renderer and none on the other — and the native
+// `maxlength` attribute would not have closed the gap, because the browser
+// counts UTF-16 code units: `'🔒é'` is 2 characters to GTK and to NativeScript,
+// and 3 to `input.maxLength`. That is why the clamp is applied here rather than
+// handed to the platform.
+//
 // Reference: refs/libadwaita/src/stylesheet/widgets/_entries.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
-// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
+// length arithmetic composed from @gjsify/adwaita-core.
+
+import { ENTRY_ROW_MAX_LENGTH_LIMIT, clampEntryText, entryTextLength } from '@gjsify/adwaita-core';
 
 export class AdwEntry extends HTMLElement {
     private _input!: HTMLInputElement;
     private _initialized = false;
+    private _maxLength = 0;
 
     static get observedAttributes() {
-        return ['value', 'placeholder', 'type', 'disabled'];
+        return ['value', 'placeholder', 'type', 'disabled', 'maxlength'];
     }
 
     get value(): string {
@@ -20,8 +35,26 @@ export class AdwEntry extends HTMLElement {
     }
 
     set value(v: string) {
-        if (this._input) this._input.value = v;
-        else this.setAttribute('value', v);
+        const clamped = clampEntryText(v ?? '', this._maxLength);
+        if (this._input) this._input.value = clamped;
+        else this.setAttribute('value', clamped);
+    }
+
+    /** `Gtk.Entry:max-length` — 0 means unlimited. Counted in CODE POINTS. */
+    get maxLength(): number {
+        return this._maxLength;
+    }
+
+    set maxLength(value: number) {
+        this._maxLength = Number.isFinite(value)
+            ? Math.min(ENTRY_ROW_MAX_LENGTH_LIMIT, Math.max(0, Math.trunc(value)))
+            : 0;
+        if (this._input) this._input.value = clampEntryText(this._input.value, this._maxLength);
+    }
+
+    /** `Gtk.Entry:text-length` — code points, not UTF-16 units. */
+    get textLength(): number {
+        return entryTextLength(this.value);
     }
 
     /** The inner native input (for focus/selection). */
@@ -33,12 +66,20 @@ export class AdwEntry extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
+        this.maxLength = Number(this.getAttribute('maxlength') ?? 0);
+
         const input = document.createElement('input');
         input.className = 'adw-entry';
         input.type = this.getAttribute('type') || 'text';
-        input.value = this.getAttribute('value') ?? '';
+        input.value = clampEntryText(this.getAttribute('value') ?? '', this._maxLength);
         input.placeholder = this.getAttribute('placeholder') ?? '';
         input.disabled = this.hasAttribute('disabled');
+        // Typing past the limit is clamped here, on the way in — the same place
+        // NativeScript clamps it, so both renderers refuse the same character.
+        input.addEventListener('input', () => {
+            const clamped = clampEntryText(input.value, this._maxLength);
+            if (clamped !== input.value) input.value = clamped;
+        });
         input.addEventListener('keydown', (e) => {
             if (e.key === 'Enter') {
                 this.dispatchEvent(new CustomEvent('activate', { bubbles: true, detail: { value: input.value } }));
@@ -50,8 +91,12 @@ export class AdwEntry extends HTMLElement {
     }
 
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (name === 'maxlength') {
+            this.maxLength = Number(value ?? 0);
+            return;
+        }
         if (!this._input) return;
-        if (name === 'value') this._input.value = value ?? '';
+        if (name === 'value') this._input.value = clampEntryText(value ?? '', this._maxLength);
         else if (name === 'placeholder') this._input.placeholder = value ?? '';
         else if (name === 'type') this._input.type = value || 'text';
         else if (name === 'disabled') this._input.disabled = value !== null;