@gjsify/adwaita-web 0.30.0 → 0.32.0

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

@@ -1,15 +1,51 @@
 // <adw-switch-row> — Row with a title/subtitle and a trailing toggle switch.
 // Attributes: title, subtitle, active (boolean)
 // Events: notify::active (CustomEvent, mirrors GJS GObject signal naming)
+//
+// The ACTIVE flag, its notify rule and the toggle-on-row-activation are HEADLESS
+// and live in `@gjsify/adwaita-core` (ADR 0004) as {@link SwitchRowState}; this
+// element composes it and keeps only the DOM render half — the checkbox, the
+// label column and the `notify::active` event.
+// `@gjsify/adwaita-nativescript` composes the same state, so both ports share one
+// behaviour. Two things this fixes, both from adw-switch-row.c:
+//   - a PROGRAMMATIC `row.active = true` now notifies. The DOM does not fire
+//     `change` for `.checked =`, so keying the event off the checkbox meant the
+//     row was silent — while the NativeScript port, whose `checkedChange` DOES
+//     fire on a programmatic write, notified. libadwaita has exactly one notify
+//     path (`slider_notify_active_cb`, C:66-77) and it cannot see the origin.
+//   - clicking the ROW toggles. `adw_switch_row_init` points the
+//     activatable-widget at the slider (C:160-162), so the title is part of the
+//     control; here only the handle itself worked.
+//
+// The TOGGLE itself is `<adw-switch>`. It used to be built here by hand —
+// `label.adw-switch > input[type=checkbox] + span.adw-switch-slider` — and
+// `<adw-expander-row>` built the identical thing, over a stylesheet block that
+// was a character-for-character copy of this row's.
+//
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
-//   title/subtitle text column added to match Adw.SwitchRow.
+//   title/subtitle text column added to match Adw.SwitchRow; the active state
+//   composed from @gjsify/adwaita-core; the toggle markup from <adw-switch>.
+
+import { SwitchRowState, deriveRowLabels } from '@gjsify/adwaita-core';
+
+// SIDE-EFFECT import, deliberately separate from the type import below: it is
+// what guarantees `adw-switch` is defined before this module's own
+// `customElements.define` can upgrade a server-rendered `<adw-switch-row>` and
+// build one. A combined `import { AdwSwitch }` would NOT do it — the binding is
+// only ever used in type position here, and this package compiles without
+// `verbatimModuleSyntax`, so TypeScript would elide the whole statement and take
+// the registration with it.
+import './adw-switch.js';
+import type { AdwSwitch } from './adw-switch.js';
 
 export class AdwSwitchRow extends HTMLElement {
-    private _checkbox!: HTMLInputElement;
+    private _switchEl!: AdwSwitch;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
+    /** The headless active flag + its notify rule (ADR 0004). */
+    private readonly _state = new SwitchRowState();
     private _initialized = false;
 
     static get observedAttributes() {
@@ -17,12 +53,13 @@ export class AdwSwitchRow extends HTMLElement {
     }
 
     get active(): boolean {
-        return this.hasAttribute('active');
+        return this._initialized ? this._state.active : this.hasAttribute('active');
     }
 
     set active(value: boolean) {
-        if (value) this.setAttribute('active', '');
-        else this.removeAttribute('active');
+        // Routed through the attribute so the declarative and imperative faces
+        // stay one code path; `attributeChangedCallback` drives the state.
+        this.toggleAttribute('active', !!value);
     }
 
     connectedCallback() {
@@ -37,42 +74,75 @@ export class AdwSwitchRow extends HTMLElement {
         this._subtitleEl.className = 'adw-row-subtitle';
         text.append(this._titleEl, this._subtitleEl);
 
-        const label = document.createElement('label');
-        label.className = 'adw-switch';
-        const input = document.createElement('input');
-        input.type = 'checkbox';
-        input.checked = this.hasAttribute('active');
-        const slider = document.createElement('span');
-        slider.className = 'adw-switch-slider';
-        label.append(input, slider);
-
-        this.replaceChildren(text, label);
-
-        this._checkbox = input;
-        this._checkbox.addEventListener('change', () => {
-            this.toggleAttribute('active', this._checkbox.checked);
-            this.dispatchEvent(
-                new CustomEvent('notify::active', {
-                    bubbles: true,
-                    detail: { active: this._checkbox.checked },
-                }),
-            );
+        this._switchEl = document.createElement('adw-switch') as AdwSwitch;
+
+        this.replaceChildren(text, this._switchEl);
+
+        this._state.setActive(this.hasAttribute('active'));
+        this._switchEl.active = this._state.active;
+        // `gtk_widget_class_set_accessible_role (…, GTK_ACCESSIBLE_ROLE_SWITCH)`
+        // plus the initial CHECKED state (adw-switch-row.c:147, :155-158).
+        this.setAttribute('role', 'switch');
+        this.setAttribute('aria-checked', String(this._state.active));
+
+        this._switchEl.addEventListener('notify::active', (event) => {
+            // The ROW is the public event surface — libadwaita has exactly one
+            // notify path for this property (`slider_notify_active_cb`, C:66-77).
+            // Letting the composed switch's own identically-named event escape
+            // would make every listener on the row see each toggle twice.
+            event.stopPropagation();
+            this._apply(this._state.setActive(this._switchEl.active));
+        });
+
+        // Activating the row inverts the state (adw-switch-row.c:23-27). A click
+        // that landed on the switch itself is already handled by the switch —
+        // toggling again here would immediately undo it.
+        this.addEventListener('click', (event) => {
+            if (event.target instanceof Node && this._switchEl.contains(event.target)) return;
+            this._apply(this._state.activate());
         });
 
         this._renderText();
     }
 
-    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+    attributeChangedCallback(name: string) {
         if (!this._initialized) return;
-        if (name === 'active') this._checkbox.checked = value !== null;
+        if (name === 'active') this._apply(this._state.setActive(this.hasAttribute('active')));
         else this._renderText();
     }
 
+    /**
+     * Push a state transition out to the DOM and emit `notify::active` — but
+     * only when something actually changed, which is the `g_object_notify`
+     * gate libadwaita puts on the same transition (C:224-225 → :76).
+     */
+    private _apply(changed: boolean) {
+        if (!changed) return;
+        // Idempotent on the switch's side too, so this write does not bounce
+        // back through the `notify::active` listener as a second transition.
+        this._switchEl.active = this._state.active;
+        this.toggleAttribute('active', this._state.active);
+        // The a11y state libadwaita updates alongside the notify (C:71-74).
+        this.setAttribute('aria-checked', String(this._state.active));
+        this.dispatchEvent(
+            new CustomEvent('notify::active', {
+                bubbles: true,
+                detail: { active: this._state.active },
+            }),
+        );
+    }
+
     private _renderText() {
-        this._titleEl.textContent = this.getAttribute('title') ?? '';
-        const subtitle = this.getAttribute('subtitle') ?? '';
+        const { title, titleVisible, subtitle, subtitleVisible } = deriveRowLabels({
+            title: this.getAttribute('title'),
+            subtitle: this.getAttribute('subtitle'),
+        });
+        this._titleEl.textContent = title;
+        // `string_is_not_empty` applies to the TITLE too (adw-action-row.ui:49-53,
+        // inherited — AdwSwitchRow derives from AdwActionRow, adw-switch-row.c:50).
+        this._titleEl.hidden = !titleVisible;
         this._subtitleEl.textContent = subtitle;
-        this._subtitleEl.hidden = subtitle.length === 0;
+        this._subtitleEl.hidden = !subtitleVisible;
     }
 }
 

package/src/elements/adw-switch.ts

@@ -0,0 +1,129 @@
+// <adw-switch> — the Adwaita toggle, as an element. A 44×24 track with a hidden
+// checkbox behind it and a knob that slides on `active`.
+//
+// WHY IT EXISTS: `<adw-switch-row>` and `<adw-expander-row>` each built
+// `label.adw-switch > input[type=checkbox] + span.adw-switch-slider` by hand, and
+// `_expander_row.scss:73-121` was a character-for-character copy of
+// `_switch_row.scss:15-63`. The cause was structural — `_switch_row.scss:9`
+// opened `adw-switch-row {` and nested everything inside it, so `.adw-switch` did
+// not exist outside a switch row and the expander could not reuse it. The styles
+// are now the unscoped `scss/_switch.scss` and the markup is here.
+//
+// NO CORE STATE MACHINE. The state is one boolean with no derivation, no
+// ordering and no notify subtlety beyond "on change" — ADR 0004 is explicit that
+// a widget with genuinely trivial behaviour does not get a core class, and the
+// `active` ATTRIBUTE is the state (`toggleAttribute` is idempotent by
+// definition, so "notify only on a real change" needs no guard of its own).
+// `GtkSwitch` does carry a two-phase `active`/`state` pair for async toggles,
+// but `refs/gtk` is EMPTY in this tree so that is unverifiable here, and neither
+// this port nor `@gjsify/adwaita-nativescript` models it — see the ROW's state
+// (`SwitchRowState`), which is where the notify rule that IS derived from C
+// lives.
+//
+// Attributes:
+//   active   — boolean; reflects (and drives) the toggled state.
+//   disabled — boolean; the control does not respond and is dimmed.
+// Properties:
+//   active   — the toggled state (get/set).
+//   disabled — whether the control is inert (get/set).
+// Events:
+//   `notify::active` (CustomEvent, bubbles, detail = { active }) — mirrors the
+//     GObject property-notify; fires on every change, programmatic included.
+//     A widget that COMPOSES this one and publishes its own `notify::active`
+//     (`<adw-switch-row>`) stops this one at the switch, so the row stays the
+//     single public event surface.
+//
+// A11Y: the checkbox is left bare — no `role="switch"` — because the widgets
+// that host one claim that role themselves (`adw_switch_row_init` sets
+// `GTK_ACCESSIBLE_ROLE_SWITCH` on the ROW, adw-switch-row.c:147), and a nested
+// second switch role would be announced twice. This is exactly the markup that
+// shipped inside the two rows before the extraction.
+//
+// Reference: refs/adwaita-web/adwaita-web/scss/_switch.scss
+// Reference: refs/libadwaita/src/stylesheet/widgets/_switch.scss
+// 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.
+
+export class AdwSwitch extends HTMLElement {
+    private _input!: HTMLInputElement;
+    private _slider!: HTMLSpanElement;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['active', 'disabled'];
+    }
+
+    /** Whether the switch is on. */
+    get active(): boolean {
+        return this.hasAttribute('active');
+    }
+
+    set active(value: boolean) {
+        // `toggleAttribute` with a force flag is a no-op when the attribute is
+        // already in the wanted state, so re-setting the current value mutates
+        // nothing and `attributeChangedCallback` — and therefore the notify —
+        // never runs. That idempotence is what a state class would otherwise be
+        // holding.
+        this.toggleAttribute('active', !!value);
+    }
+
+    /** Whether the switch is inert. */
+    get disabled(): boolean {
+        return this.hasAttribute('disabled');
+    }
+
+    set disabled(value: boolean) {
+        this.toggleAttribute('disabled', !!value);
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this.classList.add('adw-switch');
+
+        this._input = document.createElement('input');
+        this._input.type = 'checkbox';
+        this._slider = document.createElement('span');
+        this._slider.className = 'adw-switch-slider';
+        this.replaceChildren(this._input, this._slider);
+
+        // Keyboard (Space on the focused checkbox) and a direct programmatic
+        // `input.click()` both arrive here; the attribute is the state, so this
+        // just writes it and lets attributeChangedCallback do the rest.
+        this._input.addEventListener('change', () => {
+            this.active = this._input.checked;
+        });
+
+        // The slider covers the whole track (`inset: 0`), so every pointer click
+        // lands on it rather than on the 0×0 checkbox — this is the toggle the
+        // wrapping `<label>` used to provide for free. A click that DID reach the
+        // checkbox is already handled by the listener above; toggling again here
+        // would immediately undo it.
+        this.addEventListener('click', (event) => {
+            if (this.disabled) return;
+            if (event.target === this._input) return;
+            this.active = !this.active;
+        });
+
+        this._render();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        this._render();
+        if (name === 'active') {
+            this.dispatchEvent(new CustomEvent('notify::active', { bubbles: true, detail: { active: this.active } }));
+        }
+    }
+
+    private _render(): void {
+        const disabled = this.disabled;
+        this._input.checked = this.active;
+        this._input.disabled = disabled;
+        this.classList.toggle('disabled', disabled);
+    }
+}
+
+customElements.define('adw-switch', AdwSwitch);