@gjsify/adwaita-web 0.36.0 → 0.37.0

package/src/elements/adw-alert-dialog.ts

@@ -17,10 +17,9 @@
 //   open       (boolean — whether the dialog is shown; default closed)
 //   prefer-wide-layout (boolean — lay responses out horizontally when they fit)
 //
-// Buttons are stacked vertically by default (the Adw.AlertDialog default at
-// medium sizes) and laid out horizontally when prefer-wide-layout is set and
-// there are no more than two of them — mirroring the libadwaita measure/allocate
-// heuristic in spirit.
+// Buttons are stacked vertically by default (the Adw.AlertDialog default at medium
+// sizes) and laid out horizontally when prefer-wide-layout is set and there are no more
+// than two of them — the libadwaita measure/allocate heuristic in spirit, not to the px.
 //
 // Events:
 //   `response` (CustomEvent, bubbles, `detail = { response }`) when a response
@@ -29,13 +28,10 @@
 //   `notify::heading` / `notify::body` / `notify::open` (CustomEvent, bubbles)
 //     mirroring the matching GObject properties.
 //
-// The RESPONSE MODEL — the response registry (id/label/appearance/enabled), the
-// default/close-response semantics and the resolve-to-chosen-id contract — is
-// HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link AdwAlertResponses}; this element composes it and keeps only the DOM
-// render half: the scrim + floating sheet, one `<button>` per registered
-// response, and the `response` event. `@gjsify/adwaita-nativescript` composes the
-// same model, so both ports share one behaviour.
+// The RESPONSE MODEL — the registry (id/label/appearance/enabled), the
+// default/close-response semantics and the resolve-to-chosen-id contract — is HEADLESS
+// and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link AdwAlertResponses}, composed
+// by `@gjsify/adwaita-nativescript` too. This element keeps only the DOM render half.
 //
 // Reference: refs/libadwaita/src/adw-alert-dialog.c (AdwAlertDialog behaviour)
 // Reference: refs/libadwaita/src/adw-dialog.c (shared dialog base — Escape/close)
@@ -76,16 +72,14 @@ export class AdwAlertDialog extends HTMLElement {
     private _model = new AdwAlertResponses();
     /** The rendered button per registered response id (the DOM half of the model). */
     private readonly _buttons = new Map<string, HTMLButtonElement>();
-    // Set while a response is being emitted from a button so the close handler
-    // does not also fire the close-response (mirrors AdwAlertDialog's
-    // block_close_response flag).
+    // Set while a response is being emitted from a button, so the close handler does not
+    // also fire the close-response (AdwAlertDialog's `block_close_response`).
     private _blockCloseResponse = false;
 
     static get observedAttributes() {
         return ['heading', 'body', 'open', 'prefer-wide-layout'];
     }
 
-    /** The heading of the dialog. */
     get heading(): string {
         return this.getAttribute('heading') ?? '';
     }
@@ -94,7 +88,6 @@ export class AdwAlertDialog extends HTMLElement {
         this.setAttribute('heading', value);
     }
 
-    /** The body text of the dialog. */
     get body(): string {
         return this.getAttribute('body') ?? '';
     }
@@ -103,7 +96,6 @@ export class AdwAlertDialog extends HTMLElement {
         this.setAttribute('body', value);
     }
 
-    /** Whether the dialog is currently shown. */
     get open(): boolean {
         return this.hasAttribute('open');
     }
@@ -145,18 +137,16 @@ export class AdwAlertDialog extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Snapshot any declared <adw-alert-response> children before we take
+        // Declared <adw-alert-response> children are snapshotted before the element takes
         // over the subtree; everything else becomes the extra child.
         const declared = Array.from(this.querySelectorAll(':scope > adw-alert-response')) as AdwAlertResponse[];
         const declaredSet = new Set<Node>(declared);
         const extraChildren = Array.from(this.childNodes).filter((n) => !declaredSet.has(n));
 
-        // The fixed full-cover scrim. Clicking it dismisses the dialog.
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-alert-dialog-scrim';
         this._scrimEl.addEventListener('click', () => this._dismiss());
 
-        // The centred dialog box.
         this._dialogEl = document.createElement('div');
         this._dialogEl.className = 'adw-alert-dialog-box';
         this._dialogEl.setAttribute('role', 'alertdialog');
@@ -164,7 +154,6 @@ export class AdwAlertDialog extends HTMLElement {
         // Clicks inside the box must not bubble to the scrim's dismiss handler.
         this._dialogEl.addEventListener('click', (event) => event.stopPropagation());
 
-        // The scrolled message area (heading + body + extra child).
         const messageArea = document.createElement('div');
         messageArea.className = 'adw-alert-dialog-message';
 
@@ -180,15 +169,14 @@ export class AdwAlertDialog extends HTMLElement {
 
         messageArea.append(this._headingEl, this._bodyEl, this._childEl);
 
-        // The response button area.
         this._responseAreaEl = document.createElement('div');
         this._responseAreaEl.className = 'adw-alert-dialog-responses';
 
         this._dialogEl.append(messageArea, this._responseAreaEl);
         this.replaceChildren(this._scrimEl, this._dialogEl);
 
-        // Escape dismisses the dialog when open (mirrors the AdwDialog Escape
-        // shortcut → close-response).
+        // Escape dismisses the dialog when open (the AdwDialog Escape shortcut →
+        // close-response).
         this.addEventListener('keydown', (event) => {
             if (event.key === 'Escape' && this.open) {
                 event.stopPropagation();
@@ -196,7 +184,6 @@ export class AdwAlertDialog extends HTMLElement {
             }
         });
 
-        // Adopt declared responses now that the response area exists.
         for (const el of declared) {
             const id = el.getAttribute('id');
             if (!id) continue;
@@ -206,8 +193,8 @@ export class AdwAlertDialog extends HTMLElement {
             if (el.getAttribute('enabled') === 'false') this.setResponseEnabled(id, false);
         }
 
-        // Seed the headless model's text from the parsed markup (the attributes
-        // stay the source of truth for what is rendered).
+        // Seed the headless model's text from the parsed markup; the attributes stay the
+        // source of truth for what is rendered.
         this._model.heading = this.heading;
         this._model.body = this.body;
 
@@ -219,8 +206,8 @@ export class AdwAlertDialog extends HTMLElement {
         if (oldValue === newValue) return;
         this._render();
         if (name === 'heading') {
-            // Keep the headless model a complete description of the dialog; the
-            // attribute stays the source of truth for the rendered heading.
+            // Keep the headless model a complete description of the dialog; the attribute
+            // stays the source of truth for the rendered heading.
             this._model.heading = this.heading;
             this.dispatchEvent(
                 new CustomEvent('notify::heading', { bubbles: true, detail: { heading: this.heading } }),
@@ -239,10 +226,9 @@ export class AdwAlertDialog extends HTMLElement {
         this.open = true;
     }
 
-    /** Adds a response button with the given ID and label. */
     addResponse(id: string, label: string): void {
-        // The core registry UPDATES a duplicate id in place; AdwAlertDialog
-        // refuses it, so the guard stays here.
+        // The core registry UPDATES a duplicate id in place; AdwAlertDialog refuses it,
+        // so the guard stays here.
         if (this._model.hasResponse(id)) {
             // Mirror AdwAlertDialog's g_critical without throwing.
             console.warn(
@@ -270,13 +256,12 @@ export class AdwAlertDialog extends HTMLElement {
         }
     }
 
-    /** Removes a response. */
     removeResponse(id: string): void {
         if (!this._model.hasResponse(id)) return;
         this._buttons.get(id)?.remove();
         this._buttons.delete(id);
         // `AdwAlertResponses` exposes no removal (a gap against
-        // adw_alert_dialog_remove_response), so the registry is rebuilt from the
+        // `adw_alert_dialog_remove_response`), so the registry is rebuilt from the
         // survivors — core stays the single owner of the response state.
         const survivors = this._model.responses.filter((response) => response.id !== id);
         const rebuilt = new AdwAlertResponses(this._model.heading, this._model.body);
@@ -292,17 +277,14 @@ export class AdwAlertDialog extends HTMLElement {
         this._render();
     }
 
-    /** Whether a response with the given ID exists. */
     hasResponse(id: string): boolean {
         return this._model.hasResponse(id);
     }
 
-    /** Gets a response's label. */
     getResponseLabel(id: string): string | null {
         return this._model.responses.find((response) => response.id === id)?.label ?? null;
     }
 
-    /** Sets a response's label. */
     setResponseLabel(id: string, label: string): void {
         const button = this._buttons.get(id);
         if (!button) return;
@@ -311,12 +293,10 @@ export class AdwAlertDialog extends HTMLElement {
         button.textContent = label;
     }
 
-    /** Gets a response's appearance. */
     getResponseAppearance(id: string): AdwResponseAppearance | null {
         return this._model.hasResponse(id) ? this._model.getResponseAppearance(id) : null;
     }
 
-    /** Sets a response's appearance (default / suggested / destructive). */
     setResponseAppearance(id: string, appearance: AdwResponseAppearance): void {
         const button = this._buttons.get(id);
         if (!button) return;
@@ -325,7 +305,6 @@ export class AdwAlertDialog extends HTMLElement {
         button.classList.toggle('destructive-action', appearance === 'destructive');
     }
 
-    /** Gets whether a response is enabled. */
     getResponseEnabled(id: string): boolean {
         return this._model.hasResponse(id) ? this._model.getResponseEnabled(id) : false;
     }
@@ -349,16 +328,13 @@ export class AdwAlertDialog extends HTMLElement {
         this._model.closeResponse = id;
     }
 
-    // ── internals ──────────────────────────────────────────────────────────
-
-    /** A response button was activated: close, then emit `response`. */
     private _activateResponse(id: string): void {
         if (!this._model.getResponseEnabled(id)) return;
         this._blockCloseResponse = true;
         this.open = false;
         this._blockCloseResponse = false;
-        // resolveById validates against the registry (the core resolve-to-chosen-id
-        // contract) and falls back to the close response.
+        // `resolveById` validates against the registry and falls back to the close
+        // response.
         this._emitResponse(this._model.resolveById(id));
     }
 
@@ -398,14 +374,13 @@ export class AdwAlertDialog extends HTMLElement {
 
         this._childEl.hidden = this._childEl.childElementCount === 0;
 
-        // Layout: stack vertically by default; lay out horizontally only when
-        // prefer-wide-layout is set and there are at most two responses (the
-        // AdwAlertDialog heuristic for keeping wide buttons readable).
+        // Horizontal only when prefer-wide-layout is set AND there are at most two
+        // responses — the AdwAlertDialog heuristic for keeping wide buttons readable.
         const horizontal = this.preferWideLayout && this._model.responses.length <= 2;
         this._responseAreaEl.classList.toggle('horizontal', horizontal);
 
-        // Reflect the default response on its button (suggested highlight) unless
-        // the response already carries an explicit appearance.
+        // The default response gets the suggested highlight unless it already carries an
+        // explicit appearance.
         const defaultId = this._model.defaultResponse;
         for (const response of this._model.responses) {
             const isDefault = response.id === defaultId && response.appearance === 'default';

package/src/elements/adw-avatar.ts

@@ -1,20 +1,23 @@
-// <adw-avatar> — A round avatar showing initials derived from a name (with a
-// colour picked from the name), or a symbolic fallback icon.
+// <adw-avatar> — A round avatar showing a custom image, initials derived from a
+// name (with a colour picked from the name), or a symbolic fallback icon.
 // Attributes: text, size (px, default 48), show-initials (boolean),
-//   icon (symbolic fallback name, with or without -symbolic).
+//   icon (symbolic fallback name, with or without -symbolic),
+//   custom-image (an image URL — `Adw.Avatar:custom-image` is a GdkPaintable,
+//   and a URL is what a browser draws one from).
 // Reference: refs/adwaita-web/adwaita-web/scss/_avatar.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // fallback icon node is <adw-icon>.
 //
-// The two derivations — initials from the name, and the palette colour the name
-// hashes to — are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link avatarInitials} / {@link avatarColor}; this element only paints them.
-// They used to be a local copy that had drifted from both libadwaita and the
-// NativeScript renderer (single-word names rendered TWO letters here and one
-// there, and accented names picked the wrong colour in both). The shared
-// vectors in `@gjsify/adwaita-core/conformance` now pin this element to the C
-// source — see `src/adw-avatar.spec.ts`.
+// The two derivations — initials from the name, and the palette colour the name hashes to
+// — are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004) as {@link avatarInitials} /
+// {@link avatarColor}; this element only paints them. The shared vectors in
+// `@gjsify/adwaita-core/conformance` pin it to the C source — see `src/adw-avatar.spec.ts`.
+//
+// `custom-image` was UNPORTED until #1049's follow-up: this element passed
+// `hasCustomImage: false` unconditionally, so the `image` branch of `update_visibility`
+// (adw-avatar.c:117-125) — the branch that wins over both others — could not be reached,
+// and the vector row covering it had nothing to drive.
 
 import { avatarColor, avatarFontSize, avatarInitials, avatarMaxFontSize, avatarMode } from '@gjsify/adwaita-core';
 
@@ -23,10 +26,11 @@ import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 export class AdwAvatar extends HTMLElement {
     private _textEl!: HTMLSpanElement;
     private _iconEl!: AdwIcon;
+    private _imageEl!: HTMLImageElement;
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['text', 'size', 'show-initials', 'icon'];
+        return ['text', 'size', 'show-initials', 'icon', 'custom-image'];
     }
 
     connectedCallback() {
@@ -38,7 +42,14 @@ export class AdwAvatar extends HTMLElement {
 
         this._iconEl = createAdwIcon(null, 'adw-avatar-icon');
 
-        this.replaceChildren(this._textEl, this._iconEl);
+        this._imageEl = document.createElement('img');
+        this._imageEl.className = 'adw-avatar-custom-image';
+        // The image is the avatar's own presentation, not content of its own —
+        // the accessible name comes from the surrounding row, as in GTK where
+        // the custom image is a plain GtkImage inside the widget.
+        this._imageEl.alt = '';
+
+        this.replaceChildren(this._textEl, this._iconEl, this._imageEl);
         this._render();
     }
 
@@ -52,15 +63,29 @@ export class AdwAvatar extends HTMLElement {
         this.style.height = `${size}px`;
 
         const text = this.getAttribute('text') ?? '';
+        const customImage = this.getAttribute('custom-image') ?? '';
         // The gate is the TEXT, not the derived initials — `update_visibility`
         // keeps a whitespace-only name in initials mode with a blank label.
         const mode = avatarMode({
-            hasCustomImage: false,
+            hasCustomImage: customImage.length > 0,
             showInitials: this.hasAttribute('show-initials'),
             text,
         });
 
-        if (mode === 'initials') {
+        this._imageEl.hidden = mode !== 'image';
+        if (mode === 'image') {
+            // Only touch `src` when it changed: re-assigning the same URL
+            // restarts the load and flashes the avatar on every unrelated
+            // attribute change.
+            if (this._imageEl.getAttribute('src') !== customImage) this._imageEl.src = customImage;
+            // No gradient behind an image: `set_class_color` still runs in the C,
+            // but nothing of it is visible, and leaving it would show through a
+            // transparent PNG.
+            this.style.backgroundImage = '';
+            this.style.color = '';
+            this._textEl.hidden = true;
+            this._iconEl.hidden = true;
+        } else if (mode === 'initials') {
             const { fg, start, stop } = avatarColor(text);
             this.style.backgroundImage = `linear-gradient(${start}, ${stop})`;
             this.style.color = fg;

package/src/elements/adw-banner.ts

@@ -1,18 +1,14 @@
-// <adw-banner> — A full-width strip carrying a single in-context message and an
-// optional action button.
-// Attributes: title, button-label, revealed (boolean), use-markup (boolean),
-//   button-style ("default" | "suggested").
-// Events: `button-clicked` (CustomEvent) when the action button is pressed.
+// <adw-banner> — a full-width strip carrying a single in-context message and an optional
+// action button. `button-style` is `"default" | "suggested"`, and `button-clicked`
+// (CustomEvent) fires when the button is pressed.
 //
-// The defaults and the derivations come from `@gjsify/adwaita-core` (ADR 0004),
-// so this element and `@gjsify/adwaita-nativescript` answer the same markup the
-// same way. They used not to: `revealed` was opt-in here and initialised TRUE
-// there, and neither renderer had `button-style` (Since 1.7) or stripped the
-// mnemonic marker the template pins onto the button (adw-banner.ui:33).
+// The defaults and the derivations (including stripping the mnemonic marker the upstream
+// template pins onto the button label) come from `@gjsify/adwaita-core` (ADR 0004), so
+// this element and the NativeScript one answer the same markup the same way.
 //
 // Reference: refs/libadwaita/src/adw-banner.c (AdwBanner)
 // Reference: refs/libadwaita/src/adw-banner.ui
-// Reference: refs/libadwaita/src/stylesheet/widgets/_toolbars.scss (banner :243-262)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_toolbars.scss (banner)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
@@ -57,7 +53,7 @@ export class AdwBanner extends HTMLElement {
     private _render() {
         const title = this.getAttribute('title') ?? '';
         // DELIBERATE DEPARTURE FROM THE C DEFAULT. `Adw.Banner:use-markup`
-        // defaults to TRUE (adw-banner.c:422-425) and `@gjsify/adwaita-core`
+        // defaults to TRUE and `@gjsify/adwaita-core`
         // carries that as the spec value — but Pango markup is not HTML. Pango
         // has a fixed tag set and no scripting; `innerHTML` will run an
         // `onerror` handler. Adopting the C default here would turn every
@@ -65,27 +61,27 @@ export class AdwBanner extends HTMLElement {
         // in GTK, so on this renderer markup is OPT-IN and the default is text.
         // The opt-in is the developer asserting the title is trusted.
         // The title label carries `use-underline=False` in the template
-        // (adw-banner.ui:20), so its underscores are literal — no stripping here.
+        //, so its underscores are literal — no stripping here.
         if (this.hasAttribute('use-markup')) this._titleEl.innerHTML = title;
         else this._titleEl.textContent = title;
 
-        // `label && label[0]` (:663) — a first-character test, so a label of
+        // `label && label[0]` — a first-character test, so a label of
         // spaces still shows a button. The template pins the BUTTON to
-        // `use-underline=True` (adw-banner.ui:33), so the painted text drops the
+        // `use-underline=True`, so the painted text drops the
         // mnemonic markers the attribute keeps.
         const buttonLabel = this.getAttribute('button-label') ?? '';
         this._button.textContent = bannerButtonText(buttonLabel);
         this._button.hidden = !bannerButtonVisible(buttonLabel);
 
-        // `button-style` (Since 1.7, :443-447) adds or removes exactly one class
-        // (:764-774) — swap within the managed set so nothing else is touched.
+        // `button-style` (Since 1.7) adds or removes exactly one class
+        // — swap within the managed set so nothing else is touched.
         const style = parseBannerButtonStyle(this.getAttribute('button-style'));
         const applied = bannerButtonStyleClasses(style);
         for (const cls of ADW_BANNER_BUTTON_STYLE_CLASSES) {
             this._button.classList.toggle(cls, applied.includes(cls));
         }
 
-        // `revealed` (default FALSE, :456-459) slides the strip in/out.
+        // `revealed` (default FALSE) slides the strip in/out.
         this.classList.toggle('revealed', this.hasAttribute('revealed'));
     }
 }

package/src/elements/adw-bottom-sheet.ts

@@ -5,18 +5,14 @@
 // layer covers the content and dismisses the sheet on click (unless `can-close`
 // is false, in which case a close attempt is signalled instead).
 //
-// The open/closed state and the dismissal gate are NOT implemented here: they
-// live in `@gjsify/adwaita-core` as `BottomSheetPresentation` +
-// `resolveBottomSheetClose`, ported from the C source and shared with
-// `@gjsify/adwaita-nativescript` (ADR 0004). This element owns only the DOM.
-// Three things changed when it moved:
-//   - `open="false"` now means CLOSED. The old getter was `hasAttribute('open')`
-//     while every other boolean used `!== 'false'`, so one element carried two
-//     incompatible conventions and `<adw-bottom-sheet open="false">` rendered
-//     open (adw-bottom-sheet.c:1670 — `open = !!open` on a strict gboolean).
-//   - `notify::open` follows the STATE, not the attribute VALUE. Rewriting the
-//     attribute to another truthy spelling no longer fires a notification
-//     carrying an unchanged payload (adw-bottom-sheet.c:1672-1682).
+// The open/closed state and the dismissal gate are NOT implemented here: they live in
+// `@gjsify/adwaita-core` as `BottomSheetPresentation` + `resolveBottomSheetClose`,
+// ported from the C source and shared with `@gjsify/adwaita-nativescript` (ADR 0004).
+// This element owns only the DOM. Three rules are easy to get wrong:
+//   - `open="false"` means CLOSED, like every other boolean here — C's setter is
+//     `open = !!open` on a strict gboolean, so `hasAttribute` is the wrong test.
+//   - `notify::open` follows the STATE, not the attribute VALUE, so rewriting the
+//     attribute to another truthy spelling notifies nobody.
 //   - the drag handle is decorative, not a close button — see below.
 //
 // Children are declared as <adw-bottom-sheet-content> (the persistent content)
@@ -38,10 +34,9 @@
 //     state changes — mirrors the Adw.BottomSheet `open` GObject property.
 //   `close-attempt` (CustomEvent, bubbles) when a dismissal is attempted that the
 //     sheet refuses — mirrors the Adw.BottomSheet `close-attempt` signal.
-//   `sheet.close` (CustomEvent, bubbles) when the sheet.close action is used on
-//     an ALREADY-closed sheet, so an enclosing sheet/dialog can handle it — the
-//     DOM equivalent of `gtk_widget_activate_action (parent, "sheet.close")`
-//     (adw-bottom-sheet.c:382-385).
+//   `sheet.close` (CustomEvent, bubbles) when the sheet.close action is used on an
+//     ALREADY-closed sheet, so an enclosing sheet/dialog can handle it — the DOM
+//     equivalent of `gtk_widget_activate_action (parent, "sheet.close")`.
 //
 // Reference: refs/libadwaita/src/adw-bottom-sheet.c (AdwBottomSheet behaviour)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_bottom-sheet.scss
@@ -72,7 +67,6 @@ export class AdwBottomSheet extends HTMLElement {
         return ['open', 'modal', 'can-close', 'show-drag-handle'];
     }
 
-    /** Whether the sheet is revealed. */
     get open(): boolean {
         return this._state.open;
     }
@@ -81,7 +75,6 @@ export class AdwBottomSheet extends HTMLElement {
         this._setOpen(!!value);
     }
 
-    /** Whether the content is dimmed + blocked while the sheet is open. */
     get modal(): boolean {
         return this._boolAttr('modal', true);
     }
@@ -99,7 +92,6 @@ export class AdwBottomSheet extends HTMLElement {
         this._setBoolAttr('can-close', value);
     }
 
-    /** Whether the overlaid drag handle is shown. */
     get showDragHandle(): boolean {
         return this._boolAttr('show-drag-handle', true);
     }
@@ -109,14 +101,13 @@ export class AdwBottomSheet extends HTMLElement {
     }
 
     /**
-     * Route a dismissal affordance through the shared gate and act on the
-     * verdict: close, raise `close-attempt`, forward `sheet.close` to an
-     * ancestor, or do nothing. The element calls this for the dimming layer and
-     * Escape; a close button inside the sheet calls it with `'close-button'`.
+     * Route a dismissal affordance through the shared gate and act on the verdict: close,
+     * raise `close-attempt`, forward `sheet.close` to an ancestor, or do nothing. Called
+     * for the dimming layer and Escape; a close button inside the sheet passes
+     * `'close-button'`.
      *
-     * The verdict differs per source — a locked sheet signals a scrim click but
-     * swallows a swipe, and the drag handle never closes anything. See
-     * `resolveBottomSheetClose` in `@gjsify/adwaita-core`.
+     * The verdict differs PER SOURCE — a locked sheet signals a scrim click but swallows
+     * a swipe, and the drag handle never closes anything (`resolveBottomSheetClose`).
      */
     requestClose(source: BottomSheetCloseSource): BottomSheetCloseOutcome {
         const outcome = this._state.requestClose(source);
@@ -132,37 +123,30 @@ export class AdwBottomSheet extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Snapshot declared children before taking over the subtree. The sheet
-        // and content are placed by slot; anything unslotted falls back to the
+        // The sheet and content are placed by slot; anything unslotted falls back to the
         // content (the AdwBottomSheet GtkBuildable default).
         const claimed = new Set<Node>();
         const sheetChildren = this._collectSlot('adw-bottom-sheet-sheet', 'sheet', claimed);
         const contentChildren = this._collectSlot('adw-bottom-sheet-content', 'content', claimed);
         const unslotted = Array.from(this.childNodes).filter((n) => !claimed.has(n));
 
-        // Persistent content layer.
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-bottom-sheet-content';
         for (const child of contentChildren) this._contentEl.appendChild(child);
         for (const child of unslotted) this._contentEl.appendChild(child);
 
-        // Dimming layer — covers the content while the sheet is open (modal).
-        // Clicking it dismisses the sheet (or raises close-attempt when locked).
         this._dimmingEl = document.createElement('div');
         this._dimmingEl.className = 'adw-bottom-sheet-dimming';
         this._dimmingEl.addEventListener('click', () => this.requestClose('dimming'));
 
-        // The slide-up sheet with its overlaid drag handle.
         this._sheetEl = document.createElement('div');
         this._sheetEl.className = 'adw-bottom-sheet-sheet';
 
-        // libadwaita builds the handle with can_focus = FALSE and
-        // can_target = FALSE (adw-bottom-sheet.c:1197-1198): it is a decorative
-        // pill that cannot be clicked or focused at all. Its only behavioural
-        // role is elsewhere — `allow_mouse_drag = show_drag_handle || bottom_bar`
-        // (adw-bottom-sheet.c:455-457). This element used to give it
-        // role="button", tabindex=0 and a click-to-close handler, which is the
-        // one behaviour it provably does not have.
+        // libadwaita builds the handle with can_focus = FALSE and can_target = FALSE: a
+        // decorative pill that cannot be clicked or focused at all. Its only behavioural
+        // role is elsewhere — `allow_mouse_drag = show_drag_handle || bottom_bar`. Giving
+        // it role="button" and a click-to-close handler is the one behaviour it provably
+        // does not have.
         this._dragHandleEl = document.createElement('div');
         this._dragHandleEl.className = 'adw-bottom-sheet-drag-handle';
         this._dragHandleEl.setAttribute('aria-hidden', 'true');
@@ -175,12 +159,11 @@ export class AdwBottomSheet extends HTMLElement {
 
         this.replaceChildren(this._contentEl, this._dimmingEl, this._sheetEl);
 
-        // Escape → maybe_close_cb (adw-bottom-sheet.c:389-400). In GTK the
-        // shortcut sits on the sheet itself, so it fires exactly while the sheet
-        // has focus — INCLUDING while the sheet is closed, which is the corner
-        // that still emits `close-attempt`. This port has no focus transfer into
-        // the sheet, so an open sheet counts as the focused surface and a closed
-        // one only when focus is still inside its (off-screen) body.
+        // Escape → `maybe_close_cb`. In GTK the shortcut sits on the sheet itself, so it
+        // fires exactly while the sheet has focus — INCLUDING while the sheet is closed,
+        // which is the corner that still emits `close-attempt`. This port has no focus
+        // transfer into the sheet, so an open sheet counts as the focused surface and a
+        // closed one only when focus is still inside its (off-screen) body.
         this.addEventListener('keydown', (event) => {
             if (event.key !== 'Escape') return;
             if (!this.open && !this._sheetEl.contains(event.target as Node)) return;
@@ -188,9 +171,8 @@ export class AdwBottomSheet extends HTMLElement {
             this.requestClose('escape');
         });
 
-        // Adopt whatever the author declared, then start mirroring state changes
-        // back out. Seeding before the subscription keeps the initial value
-        // silent, as an attribute set during upgrade has always been.
+        // Seeding BEFORE the subscription keeps the initial value silent, which is what
+        // an attribute set during upgrade must be.
         this._state.setCanClose(this._boolAttr('can-close', true));
         this._state.setOpen(this._boolAttr('open', false));
         this._state.subscribe((open) => {
@@ -234,13 +216,10 @@ export class AdwBottomSheet extends HTMLElement {
         this.classList.toggle('modal', this.modal);
         this.classList.toggle('has-drag-handle', this.showDragHandle);
 
-        // The dimming layer is only meaningful while modal; it fades in with the
-        // sheet and is non-interactive when closed.
         this._dimmingEl.classList.toggle('visible', open && this.modal);
         this._dragHandleEl.hidden = !this.showDragHandle;
     }
 
-    /** Mirror the state onto the `open` attribute (the CSS + markup hook). */
     private _reflectOpen(open: boolean): void {
         this._reflecting = true;
         if (open) this.setAttribute('open', '');
@@ -265,7 +244,7 @@ export class AdwBottomSheet extends HTMLElement {
      *
      * The `<adw-bottom-sheet-sheet>` / `<adw-bottom-sheet-content>` wrappers are
      * markup, not widgets — GtkBuilder's `<child type="sheet">` leaves nothing in
-     * the tree (adw-bottom-sheet.c:1278-1293) — so the wrapper itself is claimed
+     * the tree — so the wrapper itself is claimed
      * too. It used to fall through to `unslotted` and be appended to the content
      * layer, leaving an empty custom element behind after its children were
      * pulled out.