@gjsify/adwaita-web 0.31.0 → 0.32.0

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

@@ -6,19 +6,42 @@
 // Header-suffix: any child carrying `slot="header-suffix"` is hoisted into the
 //   trailing edge of the header instead of the boxed list — mirroring
 //   Adw.PreferencesGroup's `header-suffix` property / buildable type.
+//
+// The five visibility states (title, description, header, `single-line`,
+// listbox) are NOT derived here: they come from
+// `derivePreferencesGroupHeader` in `@gjsify/adwaita-core`, which both this
+// element and the NativeScript group delegate to (ADR 0004). This element used
+// to compute two of the five by hand and was missing the other three — no
+// `single-line` class, and a `.boxed-list` card that stayed painted (with its
+// full-width `box-shadow` hairline) over an empty group.
+//
+// Reference: refs/libadwaita/src/adw-preferences-group.c
+//   (update_title_visibility, update_listbox_visibility, is_single_line,
+//    update_header_visibility, adw_preferences_group_add)
 // Reference: refs/libadwaita/src/adw-preferences-group.ui (header_box layout)
 // Reference: refs/adwaita-web/adwaita-web/scss/_preferences.scss
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
-//   description line + header-suffix slot added to match Adw.PreferencesGroup.
+//   description line + header-suffix slot added to match Adw.PreferencesGroup;
+//   header/listbox state delegated to @gjsify/adwaita-core.
+
+import { derivePreferencesGroupHeader } from '@gjsify/adwaita-core';
+
+/** A child that asked to sit in the header rather than in the boxed list. */
+function isHeaderSuffix(node: Node): boolean {
+    return node instanceof Element && node.getAttribute('slot') === 'header-suffix';
+}
 
 export class AdwPreferencesGroup extends HTMLElement {
+    private _headerEl!: HTMLDivElement;
     private _titleEl!: HTMLSpanElement;
     private _descriptionEl!: HTMLSpanElement;
     private _suffixEl!: HTMLDivElement;
+    private _listboxEl!: HTMLDivElement;
     private _initialized = false;
+    private _observer: MutationObserver | null = null;
 
     static get observedAttributes() {
         return ['title', 'description'];
@@ -33,22 +56,52 @@ export class AdwPreferencesGroup extends HTMLElement {
         else this.removeAttribute('description');
     }
 
+    /**
+     * `adw_preferences_group_add` (adw-preferences-group.c:396-411): a row goes
+     * into the boxed list, a `header-suffix` child into the header.
+     *
+     * Exposed as a method AND wired to a `MutationObserver` on the host, because
+     * both spellings occur: `group.addRow(row)` in code, `group.append(row)` in
+     * a framework's rendering. Before this, a child appended after connect
+     * stayed a bare child of the host — outside the card, and invisible to the
+     * row count that decides whether the card is painted at all.
+     */
+    addRow(child: Node): void {
+        if (isHeaderSuffix(child)) this._suffixEl.appendChild(child);
+        else this._listboxEl.appendChild(child);
+        this._renderHeader();
+    }
+
+    /**
+     * `adw_preferences_group_remove` (:421-440). C logs
+     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a child it does not
+     * own; returning `false` is the same contract without a console write.
+     */
+    removeRow(child: Node): boolean {
+        const parent = child.parentNode;
+        if (parent !== this._listboxEl && parent !== this._suffixEl) return false;
+        parent.removeChild(child);
+        this._renderHeader();
+        return true;
+    }
+
     connectedCallback() {
-        if (this._initialized) return;
+        if (this._initialized) {
+            this._observeHost();
+            return;
+        }
         this._initialized = true;
 
         const children = Array.from(this.childNodes);
         // Children opting into the header-suffix slot are hoisted to the
         // trailing edge of the header; everything else goes into the boxed list.
-        const suffixChildren = children.filter(
-            (child) => child instanceof Element && child.getAttribute('slot') === 'header-suffix',
-        );
+        const suffixChildren = children.filter(isHeaderSuffix);
         const rowChildren = children.filter((child) => !suffixChildren.includes(child));
 
         // Header: a flex row with a title/description label column on the left
         // and the optional header-suffix on the trailing edge.
-        const header = document.createElement('div');
-        header.className = 'adw-preferences-group-header';
+        this._headerEl = document.createElement('div');
+        this._headerEl.className = 'adw-preferences-group-header';
 
         const labels = document.createElement('div');
         labels.className = 'adw-preferences-group-labels';
@@ -63,38 +116,91 @@ export class AdwPreferencesGroup extends HTMLElement {
 
         this._suffixEl = document.createElement('div');
         this._suffixEl.className = 'adw-preferences-group-suffix';
-        suffixChildren.forEach((child) => this._suffixEl.appendChild(child));
+        for (const child of suffixChildren) this._suffixEl.appendChild(child);
 
-        header.append(labels, this._suffixEl);
+        this._headerEl.append(labels, this._suffixEl);
 
         // Boxed list container — the remaining children move into it.
-        const listbox = document.createElement('div');
-        listbox.className = 'adw-preferences-group-listbox';
-        rowChildren.forEach((child) => listbox.appendChild(child));
+        this._listboxEl = document.createElement('div');
+        this._listboxEl.className = 'adw-preferences-group-listbox';
+        for (const child of rowChildren) this._listboxEl.appendChild(child);
 
-        this.replaceChildren(header, listbox);
+        this.replaceChildren(this._headerEl, this._listboxEl);
 
         this._renderHeader();
+        this._observeHost();
+    }
+
+    disconnectedCallback() {
+        // The observer holds this element alive through the host node; drop it
+        // with the connection that created it, not at some later "cleanup".
+        this._observer?.disconnect();
+        this._observer = null;
     }
 
     attributeChangedCallback() {
         if (this._initialized) this._renderHeader();
     }
 
+    /**
+     * Adopt children appended to the HOST after the subtree was built, so
+     * `group.append(row)` behaves like `adw_preferences_group_add`.
+     *
+     * C gets this for free — `gtk_widget_observe_children` on the listbox drives
+     * `update_listbox_visibility` through `items-changed`
+     * (adw-preferences-group.c:335-339) — and a DOM element needs the observer
+     * to have the same rule hold over time rather than only at connect.
+     */
+    private _observeHost(): void {
+        if (this._observer) return;
+        this._observer = new MutationObserver((records) => {
+            for (const record of records) {
+                // Only the HOST's own children need re-homing. Records from the
+                // listbox are the CONSEQUENCE of that move; re-adopting them
+                // would append each row a second time and reorder the list.
+                if (record.target !== this) continue;
+                for (const node of record.addedNodes) {
+                    if (!(node instanceof Element)) continue;
+                    if (node === this._headerEl || node === this._listboxEl) continue;
+                    this.addRow(node);
+                }
+            }
+            // A removal straight out of the listbox still changes the row count.
+            this._renderHeader();
+        });
+        this._observer.observe(this, { childList: true });
+        this._observer.observe(this._listboxEl, { childList: true });
+    }
+
     private _renderHeader() {
         const title = this.getAttribute('title') ?? '';
-        this._titleEl.textContent = title;
-        this._titleEl.hidden = title.length === 0;
-
         const description = this.getAttribute('description') ?? '';
+
+        this._titleEl.textContent = title;
         this._descriptionEl.textContent = description;
-        this._descriptionEl.hidden = description.length === 0;
 
-        // The header only takes space when it carries a title, a description or
-        // a suffix — an empty group has no header padding, like Adw's.
-        const hasSuffix = this._suffixEl.childElementCount > 0;
-        const headerEl = this._titleEl.parentElement?.parentElement;
-        if (headerEl) headerEl.hidden = title.length === 0 && description.length === 0 && !hasSuffix;
+        const state = derivePreferencesGroupHeader({
+            title,
+            description,
+            hasHeaderSuffix: this._suffixEl.childElementCount > 0,
+            // The RAW child count, matching `gtk_widget_observe_children` — a
+            // row with an empty title still keeps the card painted.
+            rowCount: this._listboxEl.childElementCount,
+            // The labels are `textContent`, not markup: what is displayed IS the
+            // attribute value, so visibility must be judged on the raw string.
+            // libadwaita's labels are `use-markup=True`; rendering Pango markup
+            // in the browser is a separate, still-open gap, and half-closing it
+            // here would hide a title this element visibly renders.
+            useMarkup: false,
+        });
+
+        this._titleEl.hidden = !state.titleVisible;
+        this._descriptionEl.hidden = !state.descriptionVisible;
+        this._headerEl.hidden = !state.headerVisible;
+        // `single-line` is not cosmetic: the stylesheet keys the header's
+        // min-height / margin-bottom off it.
+        this._headerEl.classList.toggle('single-line', state.singleLine);
+        this._listboxEl.hidden = !state.listboxVisible;
     }
 }
 

package/src/elements/adw-progress-bar.ts

@@ -0,0 +1,189 @@
+// <adw-progress-bar> — the DETERMINATE progress indicator, and the partner to
+// <adw-spinner>, which only ever covers "busy, no idea how long".
+//
+// NO CORE STATE MACHINE. The whole behaviour is `CLAMP(fraction, 0, 1)` plus a
+// pulsing flag — ADR 0004 is explicit that a widget with genuinely trivial
+// behaviour does not get a core class, and the clamp itself is already shared:
+// `glibClamp` (GLib's CLAMP, high bound tested FIRST) comes from
+// `@gjsify/adwaita-core`. Nothing was added there for this element.
+//
+// WHAT IS NOT VERIFIABLE IN THIS TREE. `GtkProgressBar` is a GTK widget:
+// `refs/gtk` is EMPTY here and libadwaita vendors no `adw-progress-bar.c`, so
+// `gtk_progress_bar_pulse()`'s step semantics — the `pulse-step` default, how
+// the block reflects at the ends, whether it resets `fraction` — are NOT
+// verifiable and are NOT reproduced. What ships instead is the web idiom the
+// vendored port uses: a CSS keyframe animation that runs while `pulsing` is set
+// (scss/_progress_bar.scss, which cites which half came from which source), so
+// {@link AdwProgressBar.pulse} ENTERS that state and is idempotent afterwards
+// rather than advancing an offset nothing here could check. The
+// default `show-text` label — `NN%` — is likewise this port's, not a
+// reproduction of GTK's format string.
+//
+// Attributes:
+//   fraction   — 0…1, clamped. How much of the bar is filled.
+//   pulsing    — boolean; indeterminate. The block bounces instead of filling.
+//   show-text  — boolean; reveal the text node under the bar.
+//   text       — the text to show. Defaults to the fraction as a percentage.
+//   inverted   — boolean; fill from the far end.
+//   osd        — boolean; libadwaita's `.osd` STYLE CLASS — a 2px troughless bar
+//                for under a header bar (_progress-bar.scss:59-83).
+//   disabled   — boolean; dims the widget.
+// Properties:
+//   fraction / pulsing / showText / text / inverted / osd / disabled (get/set).
+// Methods:
+//   pulse()    — switch to indeterminate. GtkProgressBar's own vocabulary; see
+//                the caveat above for how far the resemblance goes.
+//
+// A11Y: `role="progressbar"` with `aria-valuemin`/`aria-valuemax` fixed at 0/1
+// and `aria-valuenow` carrying the clamped fraction. While pulsing,
+// `aria-valuenow` is REMOVED — that is how ARIA spells "indeterminate", and a
+// stale value there would be announced as real progress.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_progress-bar.scss
+// Reference: refs/adwaita-web/adwaita-web/scss/_progressbar.scss (the indeterminate animation only)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Copyright (c) 2025 csm (adwaita-web). MIT License.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { glibClamp } from '@gjsify/adwaita-core';
+
+export class AdwProgressBar extends HTMLElement {
+    private _trough!: HTMLSpanElement;
+    private _progress!: HTMLSpanElement;
+    private _text!: HTMLSpanElement;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['fraction', 'pulsing', 'show-text', 'text', 'inverted', 'osd', 'disabled'];
+    }
+
+    /** How much of the bar is filled, 0…1. Always the CLAMPED value. */
+    get fraction(): number {
+        const raw = Number.parseFloat(this.getAttribute('fraction') ?? '');
+        // A missing or unparseable attribute is 0, GtkProgressBar's default —
+        // NOT NaN, which would reach the width and the a11y value.
+        if (!Number.isFinite(raw)) return 0;
+        return glibClamp(raw, 0, 1);
+    }
+
+    set fraction(value: number) {
+        this.setAttribute('fraction', String(value));
+    }
+
+    /** Whether the bar is indeterminate. */
+    get pulsing(): boolean {
+        return this.hasAttribute('pulsing');
+    }
+
+    set pulsing(value: boolean) {
+        this.toggleAttribute('pulsing', !!value);
+    }
+
+    /** Whether the text node is shown. */
+    get showText(): boolean {
+        return this.hasAttribute('show-text');
+    }
+
+    set showText(value: boolean) {
+        this.toggleAttribute('show-text', !!value);
+    }
+
+    /** The shown text. Falls back to the fraction as a percentage. */
+    get text(): string {
+        const explicit = this.getAttribute('text');
+        if (explicit !== null) return explicit;
+        return `${Math.round(this.fraction * 100)}%`;
+    }
+
+    set text(value: string) {
+        this.setAttribute('text', value);
+    }
+
+    /** Whether the bar fills from the far end. */
+    get inverted(): boolean {
+        return this.hasAttribute('inverted');
+    }
+
+    set inverted(value: boolean) {
+        this.toggleAttribute('inverted', !!value);
+    }
+
+    /** Whether the `.osd` hairline variant is used. */
+    get osd(): boolean {
+        return this.hasAttribute('osd');
+    }
+
+    set osd(value: boolean) {
+        this.toggleAttribute('osd', !!value);
+    }
+
+    /** Whether the widget is dimmed. */
+    get disabled(): boolean {
+        return this.hasAttribute('disabled');
+    }
+
+    set disabled(value: boolean) {
+        this.toggleAttribute('disabled', !!value);
+    }
+
+    /**
+     * Switch the bar to indeterminate — GtkProgressBar's method name for the
+     * same intent. See the module header: the bouncing block is a CSS animation
+     * here, so this ENTERS the state and repeat calls are no-ops; GTK's
+     * `pulse-step` arithmetic is not verifiable in this tree and is not faked.
+     */
+    pulse(): void {
+        this.pulsing = true;
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this._trough = document.createElement('span');
+        this._trough.className = 'adw-progress-bar-trough';
+        this._progress = document.createElement('span');
+        this._progress.className = 'adw-progress-bar-progress';
+        this._trough.appendChild(this._progress);
+
+        this._text = document.createElement('span');
+        this._text.className = 'adw-progress-bar-text';
+
+        this.replaceChildren(this._trough, this._text);
+
+        this.setAttribute('role', 'progressbar');
+        this.setAttribute('aria-valuemin', '0');
+        this.setAttribute('aria-valuemax', '1');
+
+        this._render();
+    }
+
+    attributeChangedCallback() {
+        if (!this._initialized) return;
+        this._render();
+    }
+
+    private _render(): void {
+        const fraction = this.fraction;
+        const pulsing = this.pulsing;
+
+        // `> trough.empty > progress { all: unset }` (_progress-bar.scss:85) —
+        // the indicator has to VANISH at 0, not draw a rounded stub. A pulsing
+        // bar is never empty: its block is what says "working".
+        const empty = !pulsing && fraction === 0;
+        this._trough.classList.toggle('empty', empty);
+        // The inline width is dropped in both the pulsing and the empty case, so
+        // the rules that own the indicator there — the keyframes, and
+        // `all: unset` — are not fighting an inline declaration they cannot win
+        // against (inline styles beat any author rule, `all: unset` included).
+        this._progress.style.width = pulsing || empty ? '' : `${fraction * 100}%`;
+
+        this._text.textContent = this.text;
+        this._text.hidden = !this.showText;
+
+        if (pulsing) this.removeAttribute('aria-valuenow');
+        else this.setAttribute('aria-valuenow', String(fraction));
+    }
+}
+
+customElements.define('adw-progress-bar', AdwProgressBar);