@gjsify/adwaita-web 0.36.0 → 0.37.0

package/src/elements/adw-tab-view.ts

@@ -4,56 +4,37 @@
 // headerbar-colored strip, with the selected chip raised onto the view
 // background.
 //
-// The MODEL is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link TabViewState}, shared with the NativeScript twin and specced by the
-// conformance vectors in `@gjsify/adwaita-core/conformance`. This element is the
-// DOM half only: it turns declared markup into pages, builds and MOVES tab
-// chips, toggles visibility, reflects the selection to an attribute, re-emits
-// changes as DOM events, and maps key chords onto the state machine.
+// The MODEL is HEADLESS, in `@gjsify/adwaita-core`'s {@link TabViewState}
+// (ADR 0004), shared with the NativeScript twin and specced by
+// `@gjsify/adwaita-core/conformance`. This element is the DOM half only.
 //
-// What the lift fixed here, all of it C-derived:
-//   - `close-page` removed NOTHING, so every close was permanently denied. The
-//     default now closes a non-pinned page and denies a pinned one, exactly as
-//     `close_page_cb` does (adw-tab-view.c:1986-1993), and the event is
-//     CANCELABLE so `preventDefault()` defers the close until
-//     `closePageFinish()` — the "save before closing?" seam that did not exist.
-//   - `selected="99"` CLAMPED to the last page and `selected="-1"` to the first;
-//     libadwaita ignores both (:2145, :4126-4134).
-//   - `view.selected = 2` changed the visible page and fired nothing, while a
-//     tab click fired; C notifies on every path (:1854).
-//   - `<adw-tab-page>` declared `observedAttributes = ['title']` with no
-//     `attributeChangedCallback` behind it, so the declaration was dead and a
-//     title could never change. Titles, tooltips, icons and the loading state
-//     are now live, as `AdwTab` keeps them (adw-tab.c:930-931).
-//   - the bar hid on `pages <= 1` with no pinned clause, so a single PINNED tab
-//     hid the bar where libadwaita keeps it (adw-tab-bar.c:163).
-//   - the close button was always visible; it now follows `tabCloseVisible`
-//     (adw-tab.c:124 + the pinned gate at :645-650).
-//   - a roving tabindex was installed with NOTHING wired to move it, so every
-//     inactive tab was keyboard-unreachable under role=tablist.
+// The C rules that are not visible in the DOM code:
+//   - closing defaults to closing a non-pinned page and DENYING a pinned one
+//     (`close_page_cb`).
+//   - an out-of-range `selected` is IGNORED, not clamped, and every path notifies,
+//     property sets included.
+//   - the bar stays up for a single PINNED tab.
+//   - the close affordance follows `tabCloseVisible` (three terms plus a pinned
+//     gate), and titles/tooltips/icons/loading stay live.
+//
+// Pages are declared as <adw-tab-page> children — the element itself becomes the
+// panel, so its attributes stay live — or added imperatively. The roving tabindex
+// must keep moving: under `role=tablist` a frozen one leaves every inactive tab
+// keyboard-unreachable.
+//
+// MODIFICATION: Adw.TabBar defaults `autohide` TRUE (`DEFAULT_TAB_AUTOHIDE`); an
+// HTML boolean attribute cannot express a TRUE default, so `autohide` is opt-in
+// here. `no-close` is web-specific, for static tab sets such as documentation
+// command tabs.
+//
+// Events (all CustomEvent, all bubbling): `notify::selected-page`
+// (`{ selected, selectedId, previousId, interactive }`); `close-page`
+// (`{ index, id }`), CANCELABLE and one per close ATTEMPT, where
+// `preventDefault()` holds the page open until `closePageFinish(id, confirm)`;
+// and `page-attached` / `page-detached` / `page-reordered` / `page-pinned` /
+// `page-updated` (`{ id, position, previousPosition }`), one per page-list change
+// so a bound tab bar can move ONE chip instead of rebuilding.
 //
-// Pages are declared as <adw-tab-page> children (the element itself becomes the
-// page panel, so its attributes stay live) or added imperatively.
-// Attributes:
-//   selected     — zero-based index of the visible page; out-of-range is IGNORED.
-//   autohide     — hide the tab bar when it has nothing to show. NB Adw.TabBar
-//     defaults this to TRUE (`DEFAULT_TAB_AUTOHIDE`); an HTML boolean attribute
-//     cannot, so this stays opt-in — a deliberate, citable inversion.
-//   expand-tabs  — tabs stretch to fill the bar evenly (Adw.TabBar `expand-tabs`).
-//   no-close     — render no close affordance; web-specific escape hatch for
-//     static tab sets such as documentation command tabs.
-// <adw-tab-page> attributes: page-id, title, tooltip, icon, indicator-icon,
-//   loading, needs-attention, pinned.
-// Events:
-//   `notify::selected-page` (CustomEvent, bubbles,
-//     detail = { selected, selectedId, previousId, interactive }).
-//   `close-page` (CustomEvent, bubbles, CANCELABLE,
-//     detail = { index, id }) — one per close ATTEMPT. `preventDefault()` holds
-//     the page open until `closePageFinish(id, confirm)`.
-//   `page-attached` / `page-detached` / `page-reordered` / `page-pinned` /
-//     `page-updated` (CustomEvent, bubbles,
-//     detail = { id, position, previousPosition }) — one per page-list change,
-//     so a bound tab bar can move ONE chip instead of rebuilding.
 // Reference: refs/libadwaita/src/adw-tab-view.c (AdwTabView behaviour)
 // Reference: refs/libadwaita/src/adw-tab-bar.c (AdwTabBar autohide)
 // Reference: refs/libadwaita/src/adw-tab.c (AdwTab chip)
@@ -69,20 +50,18 @@ import type { AdwTabPageSpec, AdwTabPageState, TabViewPagesChange, TabViewSelect
 
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
-/** A page descriptor as `pages` exposes it. */
 export type AdwTabViewPage = AdwTabPageState<HTMLElement>;
 
-/** The page spec the imperative insertion methods take. */
 export type AdwTabViewPageSpec = AdwTabPageSpec<HTMLElement>;
 
 /** The live `<adw-tab-page>` properties, each mapped onto a state setter. */
 const PAGE_ATTRIBUTES = ['title', 'tooltip', 'icon', 'indicator-icon', 'loading', 'needs-attention', 'pinned'];
 
 /**
- * A single page. Declared as a child of <adw-tab-view>; the element itself
- * becomes the page panel, so its attributes keep driving the tab after connect —
- * the old implementation moved the children out and discarded the element, which
- * is why its `observedAttributes` declaration had nothing to act on.
+ * A single page. Declared as a child of <adw-tab-view>; the element itself becomes the
+ * page panel, so its attributes keep driving the tab after connect — a renderer that
+ * moves the children out and discards the element leaves `observedAttributes` with
+ * nothing to act on.
  */
 export class AdwTabPage extends HTMLElement {
     static get observedAttributes() {
@@ -136,8 +115,6 @@ export class AdwTabView extends HTMLElement {
         this._state.subscribe((change) => this._onSelectionChange(change));
     }
 
-    // --- Declarative surface ------------------------------------------------
-
     /** Zero-based index of the visible page, `-1` when the view is empty. */
     get selected(): number {
         return this._state.selectedIndex;
@@ -160,7 +137,6 @@ export class AdwTabView extends HTMLElement {
         else this.removeAttribute('autohide');
     }
 
-    /** Whether tabs stretch to fill the bar evenly (Adw.TabBar `expand-tabs`). */
     get expandTabs(): boolean {
         return this.hasAttribute('expand-tabs');
     }
@@ -250,17 +226,14 @@ export class AdwTabView extends HTMLElement {
 
     // --- Model surface (thin delegations to TabViewState) --------------------
 
-    /** All pages in order. */
     get pages(): readonly AdwTabViewPage[] {
         return this._state.pages;
     }
 
-    /** Number of pages. */
     get nPages(): number {
         return this._state.nPages;
     }
 
-    /** Length of the pinned prefix. */
     get nPinnedPages(): number {
         return this._state.nPinnedPages;
     }
@@ -275,7 +248,6 @@ export class AdwTabView extends HTMLElement {
         return this._state.selectedIndex;
     }
 
-    /** The selected page's panel element, or `null`. */
     get selectedContent(): HTMLElement | null {
         return this._state.selectedPage?.content ?? null;
     }
@@ -426,8 +398,6 @@ export class AdwTabView extends HTMLElement {
         return this._state.diagnostics;
     }
 
-    // --- Adoption -----------------------------------------------------------
-
     private _adoptDeclaredPage(pageEl: AdwTabPage): void {
         // The declared element IS the panel — attributes stay live on it, which
         // is what makes `<adw-tab-page title>` observable at all.
@@ -461,8 +431,6 @@ export class AdwTabView extends HTMLElement {
         return `tab-${this._generatedIds}`;
     }
 
-    // --- Rendering ----------------------------------------------------------
-
     private _onPagesChange(change: TabViewPagesChange): void {
         switch (change.kind) {
             case 'attached': {
@@ -507,19 +475,16 @@ export class AdwTabView extends HTMLElement {
         tab.setAttribute('role', 'tab');
         tab.dataset.pageId = page.id;
 
-        // Decorative mask-image nodes — <adw-icon> carries the convention (and
-        // the `-symbolic` strip, which is that convention and not C: the name
-        // reaches `GtkImage` untouched there).
+        // Decorative mask-image nodes — <adw-icon> carries the convention, including the
+        // `-symbolic` strip, which is ours and not C's: there the name reaches
+        // `GtkImage` untouched.
         const icon = createAdwIcon(null, 'adw-tab-icon');
         tab.appendChild(icon);
 
-        // `AdwTabPage:loading` swaps the icon image for an `AdwSpinnerPaintable`
-        // — the SAME paintable `Adw.Spinner` uses (`update_icons`,
-        // adw-tab.c:172-190). So this is a real `<adw-spinner>` in the icon's
-        // slot, not a ring drawn again in CSS: the stylesheet used to restate
-        // the border, the grey and the 0.8s under a comment claiming it was
-        // "not a second copy of them", and it inherited every spinner defect
-        // independently.
+        // `AdwTabPage:loading` swaps the icon image for an `AdwSpinnerPaintable` — the
+        // SAME paintable `Adw.Spinner` uses (`update_icons`). So this is a real
+        // `<adw-spinner>` in the icon's slot, not a ring drawn again in CSS: a CSS copy
+        // inherits every spinner defect independently.
         const spinner = document.createElement('adw-spinner');
         spinner.className = 'adw-tab-spinner';
         spinner.setAttribute('size', '16');
@@ -532,9 +497,10 @@ export class AdwTabView extends HTMLElement {
 
         tab.appendChild(createAdwIcon(null, 'adw-tab-indicator'));
 
-        // Close affordance — a small flat button drawn with a CSS "×" glyph (no
-        // symbolic close icon ships in @gjsify/adwaita-icons). `can-focus=False`
-        // in adw-tab.ui:72, so it stays out of the tab order here too.
+        // Close affordance — a small flat button drawn with a CSS "×" glyph, because
+        // `window-close` has no mask class: it is not in the ICONS map in
+        // `scripts/build-scss.mjs` that generates them. `can-focus=False` in C, so it
+        // stays out of the tab order here too.
         const close = document.createElement('button');
         close.type = 'button';
         close.className = 'adw-tab-close';
@@ -567,7 +533,6 @@ export class AdwTabView extends HTMLElement {
         this._refreshTab(page.id);
     }
 
-    /** Remove-then-insert, the same shape the model's own reorder has. */
     private _moveTab(id: string, position: number): void {
         const tab = this._tabs.get(id);
         if (tab) {
@@ -588,10 +553,9 @@ export class AdwTabView extends HTMLElement {
 
         const label = tab.querySelector('.adw-tab-title') as HTMLElement | null;
         if (label) label.textContent = page.title;
-        // The tooltip is Pango MARKUP when the page sets one of its own
-        // (adw-tab.c:141-146). The DOM `title` attribute is a TEXT sink, so the
-        // markup is shown verbatim rather than being pushed through an HTML sink
-        // — a renderer that interpreted it would be executing page-supplied markup.
+        // The tooltip is Pango MARKUP when the page sets one of its own. The DOM `title`
+        // attribute is a TEXT sink, so the markup is shown verbatim rather than pushed
+        // through an HTML sink — interpreting it would execute page-supplied markup.
         tab.title = tabTooltip(page);
         tab.classList.toggle('pinned', page.pinned);
         tab.classList.toggle('needs-attention', page.needsAttention);
@@ -618,10 +582,10 @@ export class AdwTabView extends HTMLElement {
     }
 
     /**
-     * `tabCloseVisible` (adw-tab.c:124 + the pinned gate at :645-650). `dragging`
-     * is constantly false — tab drag-and-drop is compositor work and is not
-     * modelled — and `fullyVisible` is measured against the bar's scroll window,
-     * which is exactly what the C term means for a horizontally scrolled bar.
+     * `tabCloseVisible`, with its pinned gate. `dragging` is constantly false — tab
+     * drag-and-drop is compositor work and is not modelled — and `fullyVisible` is
+     * measured against the bar's scroll window, which is what the C term means for a
+     * horizontally scrolled bar.
      */
     private _refreshCloseVisibility(id: string): void {
         const page = this._state.getPage(id);
@@ -700,23 +664,18 @@ export class AdwTabView extends HTMLElement {
 
     private _applySelectedAttribute(value: string): void {
         const index = Number.parseInt(value, 10);
-        // An unparseable value is IGNORED rather than treated as 0: the old
-        // `Number.isNaN(raw) ? 0 : clamp(raw)` made `selected="oops"` select the
-        // first page, and `selected="99"` the last, where libadwaita refuses both
-        // (adw-tab-view.c:2145, :4126-4134).
+        // An unparseable value is IGNORED rather than treated as 0, and an out-of-range
+        // one is refused rather than clamped: libadwaita refuses both, so
+        // `selected="oops"` must not select the first page nor `selected="99"` the last.
         if (Number.isNaN(index)) return;
         this._state.selectNthPage(index);
     }
 
-    // --- Keyboard -----------------------------------------------------------
-
     /**
-     * The `Adw.TabView` shortcut table (`init_shortcuts`, adw-tab-view.c:2192+),
-     * plus the ArrowLeft/ArrowRight movement `role=tablist` promises.
-     *
-     * Ctrl+Tab WRAPS and Ctrl+Page-Up/Down does not — the same `last` flag that
-     * separates them in `select_page_cb` (:2017-2041). Alt+0 is page index 9,
-     * because pages count from 0 (:2149-2150).
+     * The `Adw.TabView` shortcut table (`init_shortcuts`), plus the ArrowLeft/ArrowRight
+     * movement `role=tablist` promises. Ctrl+Tab WRAPS and Ctrl+Page-Up/Down does not —
+     * the same `last` flag that separates them in `select_page_cb`. Alt+0 is page index
+     * 9, because pages count from 0.
      */
     private _onKeyDown(event: KeyboardEvent): void {
         const inBar = event.target instanceof Node && this._barEl.contains(event.target);
@@ -758,10 +717,10 @@ export class AdwTabView extends HTMLElement {
     }
 
     /**
-     * The `close-page` seam. A CANCELABLE DOM event is the idiomatic spelling of
-     * the C signal's return value: letting it through takes libadwaita's default
-     * (`!pinned`, adw-tab-view.c:1990-1991), and `preventDefault()` defers the
-     * close until the app calls {@link closePageFinish}.
+     * The `close-page` seam. A CANCELABLE DOM event is the idiomatic spelling of the C
+     * signal's return value: letting it through takes libadwaita's default (`!pinned`),
+     * and `preventDefault()` defers the close until the app calls
+     * {@link closePageFinish}.
      */
     private _requestClose(page: AdwTabViewPage): boolean | 'defer' {
         const proceed = this.dispatchEvent(

package/src/elements/adw-toast-overlay.ts

@@ -1,15 +1,11 @@
-// <adw-toast-overlay> — Adwaita toast notification overlay.
-// The web counterpart of Adw.ToastOverlay: it wraps arbitrary content and shows
-// transient `.adw-toast` banners (the Adw.Toast equivalent — a title, an
-// optional action button and a close affordance) layered over the bottom of its
-// own bounds.
+// <adw-toast-overlay> — the web counterpart of Adw.ToastOverlay: wraps arbitrary
+// content and shows transient toast strips (title, optional action button, close
+// affordance) layered over the bottom of its own bounds.
 //
-// The QUEUE — Adw.ToastOverlay's one-at-a-time policy, the FIFO ordering and the
-// auto-dismiss lifecycle — is HEADLESS and lives in `@gjsify/adwaita-core` (ADR
-// 0004) as {@link AdwToastQueue}; this element composes it and keeps only the DOM
-// render half: building the `.adw-toast` strip on `onShow`, tearing it down on
-// `onHide`, and the enter/exit CSS transitions. `@gjsify/adwaita-nativescript`
-// composes the same core queue, so both ports share one behaviour.
+// The QUEUE — the one-at-a-time policy, FIFO ordering and auto-dismiss lifecycle —
+// is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link AdwToastQueue};
+// this element composes it and keeps only the DOM half: build the strip on `onShow`,
+// tear it down on `onHide`, run the enter/exit transitions.
 //
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Reference: refs/adwaita-web/adwaita-web/scss/_toast.scss, _toast_overlay.scss
@@ -41,7 +37,11 @@ export interface AdwToastOptions {
 /** Default toast lifetime in SECONDS — this element's public unit (Adw.Toast:timeout). */
 const DEFAULT_TIMEOUT_SECONDS = 5;
 
-/** Exit-transition budget in ms; must stay in sync with `.adw-toast.hiding` in `_toast.scss`. */
+/**
+ * Fallback budget in ms for the exit transition: must stay at or above the
+ * `.adw-toast.hiding` transition-duration in `_toast.scss` (0.15s today), because it
+ * only fires when `transitionend` does not.
+ */
 const TOAST_EXIT_MS = 300;
 
 /** The default timing seam: the browser's own timers. */
@@ -73,9 +73,9 @@ export class AdwToastOverlay extends HTMLElement {
             },
             onShow: (toast) => this._mountToast(toast),
             // The core queue fires `onHide` BEFORE it shifts the next toast in, so
-            // `pending > 0` here means another toast takes this slot immediately:
-            // detach without the exit transition so exactly one strip is ever in
-            // the DOM. A last toast fades out instead.
+            // `pending > 0` here means another toast takes this slot immediately: detach
+            // without the exit transition, keeping exactly one strip in the DOM. A last
+            // toast fades out instead.
             onHide: () => this._unmountToast(this._queue.pending > 0),
         });
     }
@@ -84,8 +84,8 @@ export class AdwToastOverlay extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Adopt the declared children as the wrapped content (the Adw.ToastOverlay
-        // :child) and layer a dedicated toast container over the bottom edge.
+        // The declared children become the wrapped content (Adw.ToastOverlay:child);
+        // the toast container is layered over the bottom edge.
         const content = document.createElement('div');
         content.className = 'adw-toast-overlay-content';
         for (const child of Array.from(this.childNodes)) content.appendChild(child);
@@ -121,16 +121,12 @@ export class AdwToastOverlay extends HTMLElement {
     }
 
     /**
-     * Show a toast notification — the web equivalent of Adw.ToastOverlay.add_toast()
-     * with a freshly-built Adw.Toast.
+     * Show a toast — the web equivalent of Adw.ToastOverlay.add_toast() with a
+     * freshly-built Adw.Toast. Only ONE toast is visible at a time; this one shows
+     * immediately when the slot is free, otherwise it waits its turn.
      *
-     * Like Adw.ToastOverlay, only ONE toast is visible at a time: this one shows
-     * immediately when the slot is free, otherwise it waits its turn behind the
-     * toasts already queued.
-     *
-     * @param title   The text to display.
-     * @param options Either a timeout in milliseconds (legacy shorthand) or an
-     *                {@link AdwToastOptions} bag (title text already supplied here).
+     * `options` is either an {@link AdwToastOptions} bag or, as a legacy shorthand, a
+     * timeout in MILLISECONDS.
      */
     addToast(title: string, options: number | AdwToastOptions = {}): void {
         // Ensure the toast container exists even if addToast() races a not-yet
@@ -187,8 +183,7 @@ export class AdwToastOverlay extends HTMLElement {
             el.appendChild(button);
         }
 
-        // Close affordance — a CSS-drawn "×" (no symbolic close icon ships in the
-        // curated @gjsify/adwaita-icons set), mirroring adw-tab-view's .adw-tab-close.
+        // Close affordance: a CSS-drawn "×", as in adw-tab-view's close button.
         const close = document.createElement('button');
         close.type = 'button';
         close.className = 'adw-toast-close-button';
@@ -206,10 +201,9 @@ export class AdwToastOverlay extends HTMLElement {
     }
 
     /**
-     * Detach the mounted strip — the DOM half of the queue's `onHide`.
-     *
-     * @param immediate Skip the exit transition because the next queued toast is
-     *                  about to take this slot (keeps exactly one strip mounted).
+     * Detach the mounted strip — the DOM half of the queue's `onHide`. `immediate`
+     * skips the exit transition because the next queued toast is about to take this
+     * slot, which is what keeps exactly one strip mounted.
      */
     private _unmountToast(immediate: boolean): void {
         const el = this._currentEl;
@@ -224,9 +218,8 @@ export class AdwToastOverlay extends HTMLElement {
         el.classList.remove('visible');
         el.classList.add('hiding');
         el.addEventListener('transitionend', () => el.remove(), { once: true });
-        // Fallback if transitionend doesn't fire (e.g. reduced motion). Routed
-        // through the injected scheduler so the whole lifecycle is deterministic
-        // when a fake clock is installed.
+        // Fallback for when transitionend does not fire (reduced motion). Routed through
+        // the injected scheduler so the lifecycle stays deterministic under a fake clock.
         this._scheduler.schedule(() => {
             if (el.parentNode) el.remove();
         }, TOAST_EXIT_MS);

package/src/elements/adw-toggle-group.ts

@@ -1,20 +1,13 @@
-// <adw-toggle-group> — A linked set of toggle buttons where exactly one is
-// active at a time (the web counterpart of Adw.ToggleGroup). Toggles are
-// declared as <adw-toggle> children with `label` and/or `icon-name` attributes;
-// the group renders them inside an inner container, tracks the active index, and
-// recolors the active toggle with the Adwaita active-toggle accent.
-// Attributes: active (zero-based index of the active toggle, default 0), and the
-//   style flags flat / round (mirroring the Adw.ToggleGroup `.flat` / `.round`
-//   style classes).
-// Events: `notify::active` (CustomEvent, bubbles, `detail = { active }`) when the
-//   active toggle changes — mirrors the Adw.ToggleGroup `active` GObject property.
+// <adw-toggle-group> — the web counterpart of Adw.ToggleGroup: a linked set of toggle
+// buttons where exactly one is active. Toggles are `<adw-toggle>` children carrying
+// `label` and/or `icon-name`, and the `flat` / `round` attributes mirror the upstream
+// `.flat` / `.round` style classes. `notify::active` (CustomEvent, bubbles, detail
+// `{ active }`) mirrors the `active` GObject property.
 //
-// The SELECTION state machine (the segment list plus the guarded, no-op-on-same
-// active index) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link ToggleGroupState}; this element composes it and keeps only the DOM render
-// half — building the buttons, the active pill / `aria-pressed` reflection, and
-// the `notify::active` event. `@gjsify/adwaita-nativescript` composes the same
-// state machine, so both ports share one behaviour.
+// The SELECTION state machine (the segment list plus the guarded, no-op-on-same active
+// index) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
+// {@link ToggleGroupState}; this element keeps only the DOM half — the buttons, the active
+// pill / `aria-pressed` reflection and the event.
 //
 // Reference: refs/libadwaita/src/adw-toggle-group.c (AdwToggleGroup behaviour)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_toggle-group.scss