@gjsify/adwaita-web 0.31.0 → 0.33.0

package/src/elements/adw-checks.ts

@@ -0,0 +1,299 @@
+// <adw-checkbox> and <adw-radio> — the two form-control primitives, in ONE
+// module, for the same reason `scss/_checks.scss` is one partial: upstream
+// merges them (`refs/libadwaita/src/stylesheet/widgets/_checks.scss` has no
+// `_radio.scss` beside it), and everything but the corner radius, the glyph and
+// the group is shared. `refs/adwaita-web` split them into two files and the two
+// promptly drifted apart.
+//
+// WHAT LIVES IN `@gjsify/adwaita-core`, AND WHAT DOES NOT
+//
+// The checkbox has no core class: it is one boolean plus a third state, which
+// ADR 0004 calls out as too trivial to model. What IS core is the pair of
+// pieces a second renderer would otherwise re-invent:
+//
+//   - {@link RadioGroupState} — group exclusivity. The browser gives the inner
+//     `<input type="radio" name="…">` exclusivity for free, and STOPS THERE: it
+//     unchecks the sibling INPUT and leaves the sibling `<adw-radio>` host's
+//     `checked` attribute — the published state, and the selector
+//     `_checks.scss` paints from — stale, so a group left to the browser draws
+//     two selected radios. The shared state is what repaints the loser.
+//   - {@link resolveCheckState} — indeterminate outranks checked, which is read
+//     off the cascade in `_checks.scss:79-81` and is what `aria-checked` needs.
+//
+// WHAT IS NOT VERIFIABLE IN THIS TREE. `GtkCheckButton` is a GTK widget:
+// `refs/gtk` is EMPTY here and libadwaita vendors no `adw-checkbox.c`, so its
+// group semantics (`gtk_check_button_set_group`, whether a fresh group starts
+// with a member active) and the exact meaning of `GtkCheckButton:inconsistent`
+// are NOT verifiable and are not guessed at. Where a rule was needed the HTML
+// one is used and cited as such — clearing `indeterminate` on activation is the
+// HTML pre-click activation step, not a reading of GTK.
+//
+// NAMING. The state attribute is `checked`, not GtkCheckButton's `active`:
+// these elements wrap a real `<input>`, `checked` is the spelling every author
+// already writes, and it is what the stylesheet selects on. The published event
+// follows the attribute (`notify::checked`), not the GObject property.
+//
+// Attributes (both):
+//   checked       — boolean; reflects (and drives) the checked state.
+//   indeterminate — boolean; the third state, drawn as a dash. Outranks checked.
+//   disabled      — boolean; the control does not respond and is dimmed.
+//   label         — the text beside the indicator. When absent, the element's
+//                   existing child nodes become the label (so a server-rendered
+//                   `<adw-checkbox>Enable</adw-checkbox>` upgrades intact).
+// Attributes (<adw-radio> only):
+//   name          — the group. Exclusivity is scoped to it, exactly as `name`
+//                   scopes `<input type="radio">` — including the empty case:
+//                   HTML forms a radio button group only from a NON-EMPTY name,
+//                   so a nameless radio checks itself and unchecks nothing.
+//   value         — this member's value. Defaults to the label text, so a group
+//                   written without values still has distinguishable members.
+// Properties: checked / indeterminate / disabled / label (+ name / value).
+// Events:
+//   `notify::checked` (CustomEvent, bubbles, detail = { checked }) — fires on
+//     every change, programmatic included, on EVERY member a radio pick moves.
+//
+// A11Y: the inner input carries the role (native `checkbox` / `radio`) and an
+// explicit `aria-checked` derived from {@link resolveCheckState}, so the
+// indeterminate state announces as `mixed` for BOTH — HTML has a native mixed
+// checkbox (`input.indeterminate`) but no mixed radio.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_checks.scss
+// Reference: refs/adwaita-web/adwaita-web/scss/{_checkbox,_radio}.scss
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Copyright (c) 2025 csm (adwaita-web). MIT License.
+// Modifications: Implemented as Web Components for @gjsify/adwaita-web.
+
+import { RadioGroupState, resolveCheckState } from '@gjsify/adwaita-core';
+
+/**
+ * The document's radio groups. ONE registry, as global as a bare
+ * `<input type="radio" name="x">` outside a form is — two independent groups
+ * therefore need two names.
+ */
+const radioGroups = new RadioGroupState();
+
+/** The markup + state shared by `<adw-checkbox>` and `<adw-radio>`. */
+abstract class AdwCheckBase extends HTMLElement {
+    protected _input!: HTMLInputElement;
+    protected _indicator!: HTMLSpanElement;
+    protected _label!: HTMLSpanElement;
+    private _initialized = false;
+
+    /** `checkbox` or `radio` — the native control this element is built around. */
+    protected abstract get inputType(): 'checkbox' | 'radio';
+
+    /** What a click / Space / arrow key on the control means for this kind. */
+    protected abstract activate(): void;
+
+    /** Whether the control is checked. */
+    get checked(): boolean {
+        return this.hasAttribute('checked');
+    }
+
+    set checked(value: boolean) {
+        // `toggleAttribute` with a force flag is a no-op when the attribute
+        // already holds that state, so re-setting the current value mutates
+        // nothing and the notify never runs.
+        this.toggleAttribute('checked', !!value);
+    }
+
+    /** Whether the control is in the third, inconsistent state. */
+    get indeterminate(): boolean {
+        return this.hasAttribute('indeterminate');
+    }
+
+    set indeterminate(value: boolean) {
+        this.toggleAttribute('indeterminate', !!value);
+    }
+
+    /** Whether the control is inert. */
+    get disabled(): boolean {
+        return this.hasAttribute('disabled');
+    }
+
+    set disabled(value: boolean) {
+        this.toggleAttribute('disabled', !!value);
+    }
+
+    /** The label text beside the indicator. */
+    get label(): string {
+        return this.getAttribute('label') ?? this._label?.textContent ?? '';
+    }
+
+    set label(value: string) {
+        this.setAttribute('label', value);
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            this.onConnected();
+            return;
+        }
+        this._initialized = true;
+
+        // Captured BEFORE the element takes over its own children: a
+        // server-rendered `<adw-checkbox>Enable</adw-checkbox>` keeps its text.
+        const authored = [...this.childNodes];
+
+        this._input = document.createElement('input');
+        this._input.type = this.inputType;
+        this._input.className = 'adw-check-input';
+
+        this._indicator = document.createElement('span');
+        this._indicator.className = 'adw-check-indicator';
+
+        this._label = document.createElement('span');
+        this._label.className = 'adw-check-label';
+        const authoredLabel = this.getAttribute('label');
+        if (authoredLabel === null) this._label.append(...authored);
+        else this._label.textContent = authoredLabel;
+
+        this.replaceChildren(this._input, this._indicator, this._label);
+
+        // Keyboard (Space, and the arrow keys that move within a radio group)
+        // and a direct programmatic `input.click()` both surface as `change`.
+        this._input.addEventListener('change', () => this.activate());
+
+        // The indicator and the label cover the control; the input is 0x0, so
+        // every pointer click lands on one of them. A click that DID reach the
+        // input is already handled above — activating again would undo it.
+        this.addEventListener('click', (event) => {
+            if (this.disabled) return;
+            if (event.target === this._input) return;
+            this.activate();
+        });
+
+        this.onConnected();
+        this.render();
+    }
+
+    disconnectedCallback() {
+        this.onDisconnected();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        if (name === 'label') {
+            this._label.textContent = this.getAttribute('label') ?? '';
+        }
+        this.render();
+        if (name === 'checked') {
+            this.dispatchEvent(
+                new CustomEvent('notify::checked', { bubbles: true, detail: { checked: this.checked } }),
+            );
+        }
+    }
+
+    /** Extra wiring for a subclass on connect. */
+    protected onConnected(): void {}
+
+    /** Extra teardown for a subclass on disconnect. */
+    protected onDisconnected(): void {}
+
+    protected render(): void {
+        const state = resolveCheckState(this.checked, this.indeterminate);
+        this._input.checked = state === 'checked';
+        this._input.indeterminate = state === 'indeterminate';
+        // Explicit, because HTML has a native mixed CHECKBOX (the property
+        // above) but no mixed radio — this is the one spelling that announces
+        // the third state for both.
+        this._input.setAttribute('aria-checked', state === 'indeterminate' ? 'mixed' : String(state === 'checked'));
+        this._input.disabled = this.disabled;
+        this._label.hidden = this._label.childNodes.length === 0;
+    }
+}
+
+/** The Adwaita checkbox — `checkbutton > check` as a custom element. */
+export class AdwCheckbox extends AdwCheckBase {
+    static get observedAttributes() {
+        return ['checked', 'indeterminate', 'disabled', 'label'];
+    }
+
+    protected get inputType(): 'checkbox' {
+        return 'checkbox';
+    }
+
+    protected activate(): void {
+        // HTML's pre-click activation steps clear `indeterminate` before the
+        // toggle, so a user can always reach a definite state. That rule is the
+        // HTML spec's, not a reading of GtkCheckButton:inconsistent, whose
+        // behaviour is not verifiable in this tree.
+        this.indeterminate = false;
+        this.checked = !this.checked;
+    }
+}
+
+/** The Adwaita radio — `checkbutton > radio`, exclusive within its `name`. */
+export class AdwRadio extends AdwCheckBase {
+    private _unsubscribe: (() => void) | null = null;
+
+    static get observedAttributes() {
+        return ['checked', 'indeterminate', 'disabled', 'label', 'name', 'value'];
+    }
+
+    protected get inputType(): 'radio' {
+        return 'radio';
+    }
+
+    /** The group this member belongs to. */
+    get name(): string {
+        return this.getAttribute('name') ?? '';
+    }
+
+    set name(value: string) {
+        this.setAttribute('name', value);
+    }
+
+    /**
+     * This member's value. Falls back to the label text so a group authored
+     * without values still has members the group state can tell apart.
+     */
+    get value(): string {
+        return this.getAttribute('value') ?? this.label.trim();
+    }
+
+    set value(value: string) {
+        this.setAttribute('value', value);
+    }
+
+    protected activate(): void {
+        this.indeterminate = false;
+        // An UNNAMED radio is not in a group — HTML forms a radio button group
+        // only from a non-empty `name`, so a nameless one checks itself and
+        // never unchecks anything. Without this guard every nameless radio in
+        // the document would join one `''` group and fight over it.
+        if (this.name === '') {
+            this.checked = true;
+            return;
+        }
+        // The pick goes through the shared state, never straight onto this
+        // element: the member that LOSES the selection is a different element
+        // and only the state knows which one it is.
+        radioGroups.select(this.name, this.value);
+    }
+
+    protected onConnected(): void {
+        this._input.name = this.name;
+        if (this.name === '') return; // ungrouped — nothing to subscribe to
+        this._unsubscribe ??= radioGroups.subscribe((change) => {
+            if (change.name !== this.name) return;
+            this.checked = change.selected === this.value;
+        });
+        // A member declared checked seeds the group, so the first user pick
+        // knows what it is deselecting.
+        if (this.checked) radioGroups.select(this.name, this.value);
+    }
+
+    protected onDisconnected(): void {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+    }
+
+    protected render(): void {
+        super.render();
+        this._input.name = this.name;
+    }
+}
+
+customElements.define('adw-checkbox', AdwCheckbox);
+customElements.define('adw-radio', AdwRadio);

package/src/elements/adw-clamp.ts

@@ -1,27 +1,97 @@
-// <adw-clamp> — Constrains its child to a maximum width and centers it.
-// Attributes: maximum-size (px, default 600), tightening-threshold (unused;
-//   accepted for API parity with Adw.Clamp).
+// <adw-clamp> — Constrains its children to a maximum width and centers them.
+// Attributes: maximum-size (px, default 600), tightening-threshold (px, default 400).
+//
+// The clamp is NOT a `max-width`, which is what this element used to be. Adwaita
+// eases the child from "all the available width" into the cap across a tightening
+// region, and stamps a `small`/`medium`/`large` class on it — the arithmetic lives
+// in `@gjsify/adwaita-core` (`clampAllocate`) so this element and the NativeScript
+// widget produce the same width for the same viewport.
+//
+// The cap now sits on the CHILDREN, not on this element. The element has to keep
+// reporting the AVAILABLE width — it is what the curve is evaluated against — and
+// an element that caps itself reports the capped width back to its own
+// ResizeObserver, which is a feedback loop, not a measurement.
+//
+// `childMin` is passed as 0 rather than measured. libadwaita's
+// `lower = MAX (…, child_min)` says a child is never squeezed below its own
+// minimum, and the browser already applies that rule at the other end: `min-width`
+// wins over `max-width` (CSS 2.1 §10.4), so a child that declares a minimum keeps
+// it whatever cap this element writes. A child that declares none has a minimum of
+// 0, which is the value passed here — measuring `min-content` per child on every
+// resize would cost a synchronous reflow to arrive at the same layout.
+//
+// Reference: refs/libadwaita/src/adw-clamp-layout.c (child_size_from_clamp, allocate)
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/clamp.md
-// Reference: refs/libadwaita (Adw.Clamp)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { ADW_CLAMP_DEFAULTS, ADW_CLAMP_SIZE_CLASSES, clampAllocate, normalizeClampSize } from '@gjsify/adwaita-core';
+
 export class AdwClamp extends HTMLElement {
+    private _resize: ResizeObserver | null = null;
+    private _mutations: MutationObserver | null = null;
+
     static get observedAttributes() {
-        return ['maximum-size'];
+        return ['maximum-size', 'tightening-threshold'];
     }
 
     connectedCallback() {
-        this._sync();
+        // ResizeObserver delivers an initial observation on observe(), so the
+        // first allocation lands before paint without a separate seeding pass.
+        this._resize = new ResizeObserver(() => this._allocate());
+        this._resize.observe(this);
+        // Children appended AFTER connect are clamped too. Without this they
+        // would keep whatever width they came with — the same "evaluated once at
+        // connect time" bug the toolbar view's empty-bar handling still has.
+        this._mutations = new MutationObserver(() => this._allocate());
+        this._mutations.observe(this, { childList: true });
+        this._allocate();
+    }
+
+    disconnectedCallback() {
+        this._resize?.disconnect();
+        this._resize = null;
+        this._mutations?.disconnect();
+        this._mutations = null;
     }
 
     attributeChangedCallback() {
-        this._sync();
+        this._allocate();
     }
 
-    private _sync() {
-        const max = parseFloat(this.getAttribute('maximum-size') || '600');
-        this.style.maxWidth = `${max}px`;
+    private _allocate(): void {
+        const params = {
+            maximumSize: normalizeClampSize(this.getAttribute('maximum-size'), ADW_CLAMP_DEFAULTS.maximumSize),
+            tighteningThreshold: normalizeClampSize(
+                this.getAttribute('tightening-threshold'),
+                ADW_CLAMP_DEFAULTS.tighteningThreshold,
+            ),
+            childMin: 0,
+            childNat: 0,
+        };
+
+        const available = this.clientWidth;
+        const children = Array.from(this.children) as HTMLElement[];
+
+        // No box yet (disconnected, or measured before the first layout). GTK's
+        // equivalent is `for_size = -1`, where the child reports its natural size
+        // rather than being squeezed to nothing — so leave the children alone
+        // instead of capping them at 0 and collapsing the page.
+        if (available <= 0) {
+            for (const child of children) {
+                child.style.maxWidth = '';
+                child.style.marginInline = '';
+                for (const cls of ADW_CLAMP_SIZE_CLASSES) child.classList.remove(cls);
+            }
+            return;
+        }
+
+        const { childSize, sizeClass } = clampAllocate(available, params);
+        for (const child of children) {
+            child.style.maxWidth = `${childSize}px`;
+            child.style.marginInline = 'auto';
+            for (const cls of ADW_CLAMP_SIZE_CLASSES) child.classList.toggle(cls, cls === sizeClass);
+        }
     }
 }
 

package/src/elements/adw-combo-row.ts

@@ -17,7 +17,7 @@
 //   title/subtitle text column added to match Adw.ComboRow; the selection state
 //   machine composed from @gjsify/adwaita-core.
 
-import { ComboState } from '@gjsify/adwaita-core';
+import { ComboState, deriveRowLabels, normalizeComboOptions } from '@gjsify/adwaita-core';
 
 export class AdwComboRow extends HTMLElement {
     private _select!: HTMLSelectElement;
@@ -46,8 +46,10 @@ export class AdwComboRow extends HTMLElement {
 
         const items: string[] = JSON.parse(this.getAttribute('items') || '[]');
         // Seed the headless state BEFORE subscribing, so building the initial DOM
-        // below is not driven by a change notification.
-        this._state.setOptions(items.map((item) => ({ label: item, value: item })));
+        // below is not driven by a change notification. The string→descriptor
+        // mapping is core's: `<adw-drop-down>` had its own, richer copy, so the
+        // two selectors accepted different option vocabularies.
+        this._state.setOptions(normalizeComboOptions(items));
         this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
         const selectedIdx = this._state.selectedIndex;
 
@@ -83,6 +85,7 @@ export class AdwComboRow extends HTMLElement {
         this._state.subscribe((change) => {
             this._valueEl.textContent = change.label;
             if (this._select.selectedIndex !== change.selected) this._select.selectedIndex = change.selected;
+            this._syncChooser();
             if (!change.interactive) return;
             this.setAttribute('selected', String(change.selected));
             this.dispatchEvent(
@@ -99,6 +102,7 @@ export class AdwComboRow extends HTMLElement {
             this._state.select(this._select.selectedIndex);
         });
 
+        this._syncChooser();
         this._renderText();
     }
 
@@ -113,11 +117,32 @@ export class AdwComboRow extends HTMLElement {
         }
     }
 
+    /**
+     * `model_changed` (adw-combo-row.c:187-195) — one option or none is not a
+     * choice, so the arrow goes and the row stops being activatable.
+     *
+     * Both halves have to be expressed: `data-presents-chooser` gates the
+     * `.adw-row-value::after` mask in the stylesheet, and DISABLING the overlaid
+     * `<select>` is what makes the row inert — hiding the arrow alone would leave
+     * a row that still opens a one-entry popup on click.
+     */
+    private _syncChooser() {
+        const presents = this._state.presentsChooser;
+        this.dataset.presentsChooser = presents ? 'true' : 'false';
+        this._select.disabled = !presents;
+    }
+
     private _renderText() {
-        this._titleEl.textContent = this.getAttribute('title') ?? '';
-        const subtitle = this.getAttribute('subtitle') ?? '';
-        this._subtitleEl.textContent = subtitle;
-        this._subtitleEl.hidden = subtitle.length === 0;
+        // The `string_is_not_empty` label rule, from core — this block was one of
+        // six hand-rolled copies, all of which omitted the TITLE half.
+        const labels = deriveRowLabels({
+            title: this.getAttribute('title'),
+            subtitle: this.getAttribute('subtitle'),
+        });
+        this._titleEl.textContent = labels.title;
+        this._titleEl.hidden = !labels.titleVisible;
+        this._subtitleEl.textContent = labels.subtitle;
+        this._subtitleEl.hidden = !labels.subtitleVisible;
     }
 }