@gjsify/adwaita-web 0.36.0 → 0.38.0

package/src/bottom-sheet.spec.ts

@@ -2,18 +2,15 @@
 // the core suite and the NativeScript renderer assert against
 // (`@gjsify/adwaita-core/conformance`).
 //
-// `Adw.BottomSheet` has four dismissal paths and they are four different gates.
-// This element used to route all of them through one `_attemptClose()`, which
-// meant: the drag handle closed the sheet (in libadwaita it is `can_target =
-// FALSE` and closes nothing), Escape on a closed-but-focused sheet did nothing
-// (libadwaita still signals `close-attempt`), and the `sheet.close` action on an
-// already-closed sheet did nothing (libadwaita forwards it to the parent).
-// Nothing failed, because nothing compared the element to the C source.
+// `Adw.BottomSheet` has four dismissal paths and they are four DIFFERENT gates, so one
+// shared `_attemptClose()` cannot express them: the drag handle is `can_target = FALSE`
+// and closes nothing; Escape on a closed-but-focused sheet still signals
+// `close-attempt`; and the `sheet.close` action on an already-closed sheet forwards to
+// the parent.
 //
-// Two element-local bugs are pinned here too, both from the same root cause —
-// the open STATE used to be read off the attribute rather than held:
-// `open="false"` rendered OPEN, and re-spelling the attribute fired a
-// `notify::open` carrying an unchanged payload.
+// The open STATE must be HELD, not read back off the attribute — reading it made
+// `open="false"` render OPEN and let a re-spelt attribute fire a `notify::open` with an
+// unchanged payload.
 import { describe, expect, it } from '@gjsify/unit';
 
 import type { AdwBottomSheet } from './elements/adw-bottom-sheet.js';
@@ -75,8 +72,8 @@ export const AdwBottomSheetTest = async () => {
                 });
 
                 expect(returned).toBe(outcome);
-                // The verdict must be VISIBLE, not just returned: a renderer that
-                // returns the right word and closes anyway is still wrong.
+                // The verdict must be VISIBLE, not just returned: returning the right word
+                // and closing anyway is still wrong.
                 expect(sheet.open).toBe(outcome === 'close' ? false : open);
                 expect(attempts).toBe(outcome === 'close-attempt' ? 1 : 0);
                 expect(delegated).toBe(outcome === 'delegate' ? 1 : 0);
@@ -120,9 +117,9 @@ export const AdwBottomSheetTest = async () => {
 
     await describe('adw-bottom-sheet open attribute semantics', async () => {
         await it('open="false" renders CLOSED', () => {
-            // The getter used to be `hasAttribute('open')` while every other
-            // boolean used `!== 'false'`, so one element carried two conventions.
-            // adw-bottom-sheet.c:1670 — `open = !!open` on a strict gboolean.
+            // `hasAttribute('open')` for the getter while every other boolean uses
+            // `!== 'false'` gives one element two conventions.
+            // adw-bottom-sheet.c — `open = !!open` on a strict gboolean.
             const sheet = document.createElement('adw-bottom-sheet') as AdwBottomSheet;
             sheet.setAttribute('open', 'false');
             document.body.appendChild(sheet);
@@ -141,10 +138,9 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('re-spelling the attribute fires no spurious notify::open', () => {
-            // The old callback guarded only `oldValue === newValue` and then
-            // dispatched unconditionally, so `open=""` → `open="open"` fired a
-            // second notification carrying an UNCHANGED payload.
-            // adw-bottom-sheet.c:1672-1682 returns before notifying.
+            // Guarding only on `oldValue === newValue` lets `open=""` → `open="open"` fire
+            // a second notification carrying an UNCHANGED payload.
+            // adw-bottom-sheet.c returns before notifying.
             const sheet = mountSheet();
             const payloads: boolean[] = [];
             sheet.addEventListener('notify::open', (event) => {
@@ -170,9 +166,8 @@ export const AdwBottomSheetTest = async () => {
 
     await describe('adw-bottom-sheet affordances', async () => {
         await it('the drag handle is decorative — not focusable, not a button, closes nothing', () => {
-            // gtk_widget_set_can_focus/can_target (self->drag_handle, FALSE)
-            // — adw-bottom-sheet.c:1197-1198. This element used to give it
-            // role="button", tabindex=0 and a click-to-close handler.
+            // `gtk_widget_set_can_focus/can_target (self->drag_handle, FALSE)` — so no
+            // role="button", no tabindex=0 and no click-to-close handler.
             const sheet = mountSheet();
             sheet.open = true;
             const handle = dragHandle(sheet);
@@ -207,8 +202,8 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('a dimming click on a CLOSED sheet does nothing and signals nothing', () => {
-            // The scrim is `can_target = open` (adw-bottom-sheet.c:1692), so it
-            // is not reachable at all — unlike Escape, it does not signal.
+            // The scrim is `can_target = open`, so it is not reachable at all — unlike
+            // Escape, it does not signal.
             const sheet = mountSheet();
             sheet.canClose = false;
             const { attempts } = recordSignals(sheet, () => {
@@ -228,10 +223,9 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('Escape on a CLOSED but focused sheet still raises close-attempt', () => {
-            // maybe_close_cb's emit is the fallthrough for every case that is not
-            // (can_close && open) — adw-bottom-sheet.c:393-399. This element
-            // guarded it away twice (once in the key handler, once in
-            // `_attemptClose`), so the corner was unreachable.
+            // `maybe_close_cb`'s emit is the fallthrough for every case that is NOT
+            // (can_close && open); guarding it away in the key handler and in
+            // `_attemptClose` makes the corner unreachable.
             const sheet = mountSheet();
             const { attempts } = recordSignals(sheet, () => {
                 insideSheet(sheet).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
@@ -254,9 +248,9 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('sheet.close on an already-closed sheet delegates upward', () => {
-            // sheet_close_cb activates the PARENT's `sheet.close` action instead
-            // of doing nothing — adw-bottom-sheet.c:382-385. A bubbling event is
-            // the DOM equivalent, so an enclosing sheet/dialog can act on it.
+            // `sheet_close_cb` activates the PARENT's `sheet.close` action rather than
+            // doing nothing; a bubbling event is the DOM equivalent, so an enclosing
+            // sheet or dialog can act on it.
             const sheet = mountSheet();
             const host = sheet.parentElement as HTMLElement;
             let seenOnAncestor = 0;
@@ -278,10 +272,10 @@ export const AdwBottomSheetTest = async () => {
         });
 
         await it('consumes the slot wrappers instead of leaving them in the content', () => {
-            // `<child type="sheet">` is GtkBuilder markup — nothing of it survives
-            // into the widget tree (adw-bottom-sheet.c:1278-1293). The emptied
-            // <adw-bottom-sheet-sheet> / <adw-bottom-sheet-content> wrappers used
-            // to fall through to `unslotted` and land in the content layer.
+            // `<child type="sheet">` is GtkBuilder markup and nothing of it survives into
+            // the widget tree, so the emptied <adw-bottom-sheet-sheet> /
+            // <adw-bottom-sheet-content> wrappers must not fall through to `unslotted` and
+            // land in the content layer.
             const sheet = mountSheet();
             const content = sheet.querySelector('.adw-bottom-sheet-content') as HTMLElement;
             expect(Array.from(content.children).map((el) => el.tagName.toLowerCase())).toStrictEqual(['button']);

package/src/breakpoints.ts

@@ -8,10 +8,9 @@
 // `ResizeObserver` — which this module supplies under the same name, so the two
 // ports read alike.
 //
-// Until this existed, `adwaita-web` was the only one of the three renderers with
-// no size source at all: `<adw-navigation-split-view collapsed>` was a manual
-// attribute the application had to flip itself, so the same markup that adapts
-// on GTK and on NativeScript stayed frozen in one layout in the browser.
+// Without a size source `<adw-navigation-split-view collapsed>` is a manual attribute the
+// application has to flip itself, and markup that adapts on GTK and on NativeScript stays
+// frozen in one layout in the browser.
 //
 // Reference: refs/libadwaita/src/adw-breakpoint.c
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
@@ -21,19 +20,17 @@ import { AdwBreakpoint } from '@gjsify/adwaita-core';
 /**
  * Drive `breakpoints` from `element`'s own box, and return a dispose function.
  *
- * `ResizeObserver` delivers an initial observation on `observe()`, so the
- * breakpoints settle on the correct state before first paint — no flash of the
- * wrong layout, and no separate seeding pass.
- *
- * The size read is the BORDER box in CSS pixels, the browser's counterpart to
- * the `sp`/DIP units an Adwaita condition is written in.
+ * `ResizeObserver` delivers an initial observation on `observe()`, so the breakpoints
+ * settle on the correct state before first paint — no flash of the wrong layout, no
+ * separate seeding pass. The size read is the BORDER box in CSS pixels, the browser's
+ * counterpart to the `sp`/DIP units an Adwaita condition is written in.
  */
 export function addBreakpoints(element: Element, breakpoints: readonly AdwBreakpoint[]): () => void {
     const observer = new ResizeObserver((entries) => {
         const entry = entries[entries.length - 1];
         if (!entry) return;
-        // borderBoxSize is the spec'd path; contentRect is the fallback for the
-        // shape older engines report.
+        // borderBoxSize is the spec'd path; contentRect is the fallback for the shape older
+        // engines report.
         const box = entry.borderBoxSize?.[0];
         const size = box
             ? { width: box.inlineSize, height: box.blockSize }
@@ -45,13 +42,13 @@ export function addBreakpoints(element: Element, breakpoints: readonly AdwBreakp
 }
 
 /**
- * Wire a `breakpoint="<condition>"` attribute to a boolean setter, the browser
- * equivalent of an `Adw.Breakpoint` with one `add_setter()` call.
+ * Wire a `breakpoint="<condition>"` attribute to a boolean setter, the browser equivalent
+ * of an `Adw.Breakpoint` with one `add_setter()` call. Returns a dispose function; call it
+ * before re-binding and on disconnect.
  *
- * Returns a dispose function; call it before re-binding and on disconnect.
- * A missing or unparsable condition binds nothing and returns a no-op, leaving
- * whatever the attribute already says untouched — an element must not silently
- * flip state because its condition had a typo.
+ * A missing or unparsable condition binds nothing and returns a no-op, leaving whatever
+ * the attribute already says untouched — an element must not silently flip state because
+ * its condition had a typo.
  */
 export function bindBreakpointSetter(
     element: Element,

package/src/chrome.spec.ts

@@ -2,16 +2,12 @@
 // <adw-spinner> and <adw-toolbar-view> — driven by the SAME vectors the
 // NativeScript renderer asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// Each of the three used to answer a question libadwaita had already answered,
-// and answered it differently from the NativeScript port: the clamp was a plain
-// `max-width` with no tightening and a `maximum-size="0"` that collapsed the
-// child to nothing, the spinner defaulted to 24px and stroked a 2px ring where
-// Adwaita strokes 3px, and the toolbar view carried none of the four style
-// classes at all. Nothing failed, because nothing compared them.
+// Each of the three answered a question libadwaita had already answered, and answered it
+// differently from the NativeScript port: clamp tightening and `maximum-size="0"`, the
+// spinner's default size and 3px stroke, and the toolbar view's four style classes.
 //
-// Sizes are driven by really resizing a host element and awaiting a real
-// ResizeObserver delivery, the same way `breakpoints.spec.ts` does — never by
-// faking one.
+// Sizes are driven by really resizing a host element and awaiting a real ResizeObserver
+// delivery, as `breakpoints.spec.ts` does — never by faking one.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { ADW_SPINNER_MIN_SIZE, ADW_SPINNER_TRACK_OPACITY, spinnerGeometry } from '@gjsify/adwaita-core';
@@ -54,8 +50,8 @@ function mountClamp(available: number): {
     const { host, resize } = mountSized(available);
     const clamp = document.createElement('adw-clamp');
     const child = document.createElement('div');
-    // A bare block child fills the clamp and is capped by the max-width the
-    // element writes — the same shape every story uses.
+    // A bare block child fills the clamp and is capped by the max-width the element
+    // writes — the shape every story uses.
     child.textContent = 'clamped';
     clamp.appendChild(child);
     host.appendChild(clamp);
@@ -96,9 +92,8 @@ function mountToolbarView(topBarHeight: number, bottomBarHeight: number): { host
 
 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` cascade, so only the rows that pass a zero child minimum
-        // describe what this element can be held to.
+        // The browser resolves the child's own minimum through the normal `min-width`
+        // cascade, so only rows with a zero child minimum describe this element.
         const vectors = CLAMP_ALLOCATE_VECTORS.filter((v) => v.params.childMin === 0);
 
         for (const { availableSize, params, childSize, sizeClass, offset, rule } of vectors) {
@@ -110,7 +105,7 @@ export const AdwChromeTest = async () => {
 
                 expect(clampedWidth(child)).toBe(childSize);
                 expect(sizeClassOf(child)).toBe(sizeClass);
-                // `margin-inline: auto` splits the remainder evenly; libadwaita
+                // `margin-inline: auto` splits the remainder evenly where libadwaita
                 // truncates, so the two can differ by half a pixel.
                 const leading = child.getBoundingClientRect().left - clamp.getBoundingClientRect().left;
                 expect(Math.abs(leading - offset) <= 1).toBe(true);
@@ -120,8 +115,7 @@ export const AdwChromeTest = async () => {
         }
 
         await it('follows the viewport instead of pinning the child to the maximum', async () => {
-            // The NativeScript twin's bug in browser form: a narrow clamp must
-            // hand the child ALL of the available width, not the cap.
+            // A narrow clamp hands the child ALL of the available width, not the cap.
             const { host, clamp, child, resize } = mountClamp(1000);
             await settle();
             expect(clampedWidth(child)).toBe(600);
@@ -132,8 +126,6 @@ export const AdwChromeTest = async () => {
         });
 
         await it('honours tightening-threshold, which the element used to ignore', async () => {
-            // The storybook has exposed this control all along and only the GTK
-            // pane responded to it.
             const { host, clamp, child } = mountClamp(700);
             clamp.setAttribute('maximum-size', '600');
             clamp.setAttribute('tightening-threshold', '400');
@@ -323,7 +315,7 @@ export const AdwChromeTest = async () => {
 
         await it('KEEPS SPINNING under reduced motion — a frozen busy indicator reads as a hang', () => {
             // libadwaita opts the spinner out of the animation setting on purpose
-            // (adw-spinner-paintable.c:537). The old stylesheet had
+            //. The old stylesheet had
             // `@media (prefers-reduced-motion: reduce) { animation: none }`, so
             // this asserts the ABSENCE of any CSS animation to switch off: the
             // arc is driven per frame from JS and cannot be disabled by a query.
@@ -345,7 +337,7 @@ export const AdwChromeTest = async () => {
             expect(arc.getAttribute('stroke-dashoffset')).not.toBe(first);
 
             // Unmapping removes it from the shared ticker — `widget_map_cb`
-            // (adw-spinner-paintable.c:181-185) is what plays the animation, so
+            // is what plays the animation, so
             // an off-screen spinner burns nothing.
             spinner.remove();
             const parked = arc.getAttribute('stroke-dashoffset');