@gjsify/adwaita-web 0.22.0 → 0.24.1

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

@@ -29,23 +29,27 @@
 //   `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.
+//
 // Reference: refs/libadwaita/src/adw-alert-dialog.c (AdwAlertDialog behaviour)
 // Reference: refs/libadwaita/src/adw-dialog.c (shared dialog base — Escape/close)
 // Reference: refs/libadwaita/src/stylesheet/widgets/_dialogs.scss (floating-sheet)
 // Reference: refs/adwaita-web/adwaita-web/scss/_dialog.scss (alert layout)
 // Copyright (c) 2022 Purism SPC / 2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
-// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
+// response model composed from @gjsify/adwaita-core.
+
+import { AdwAlertResponses } from '@gjsify/adwaita-core';
+import type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 
 /** Response button appearance — mirrors Adw.ResponseAppearance. */
-export type AdwResponseAppearance = 'default' | 'suggested' | 'destructive';
-
-interface ResponseInfo {
-    id: string;
-    label: string;
-    appearance: AdwResponseAppearance;
-    enabled: boolean;
-    button: HTMLButtonElement;
-}
+export type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 
 /**
  * A single response declared in markup. Child of <adw-alert-dialog>; its `id`
@@ -68,10 +72,10 @@ export class AdwAlertDialog extends HTMLElement {
     private _childEl!: HTMLDivElement;
     private _responseAreaEl!: HTMLDivElement;
 
-    private _responses: ResponseInfo[] = [];
-    private _byId = new Map<string, ResponseInfo>();
-    private _defaultResponse: string | null = null;
-    private _closeResponse = 'close';
+    /** The headless response registry + default/close semantics + resolution (ADR 0004). */
+    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).
@@ -121,7 +125,7 @@ export class AdwAlertDialog extends HTMLElement {
 
     /** The ID of the default response (its button is highlighted). */
     get defaultResponse(): string | null {
-        return this._defaultResponse;
+        return this._model.defaultResponse;
     }
 
     set defaultResponse(value: string | null) {
@@ -130,7 +134,7 @@ export class AdwAlertDialog extends HTMLElement {
 
     /** The ID passed to `response` when the dialog is dismissed. */
     get closeResponse(): string {
-        return this._closeResponse;
+        return this._model.closeResponse;
     }
 
     set closeResponse(value: string) {
@@ -202,6 +206,11 @@ 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).
+        this._model.heading = this.heading;
+        this._model.body = this.body;
+
         this._render();
     }
 
@@ -210,8 +219,12 @@ 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.
+            this._model.heading = this.heading;
             this.dispatchEvent(new CustomEvent('notify::heading', { bubbles: true, detail: { heading: this.heading } }));
         } else if (name === 'body') {
+            this._model.body = this.body;
             this.dispatchEvent(new CustomEvent('notify::body', { bubbles: true, detail: { body: this.body } }));
         } else if (name === 'open') {
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
@@ -226,7 +239,9 @@ export class AdwAlertDialog extends HTMLElement {
 
     /** Adds a response button with the given ID and label. */
     addResponse(id: string, label: string): void {
-        if (this._byId.has(id)) {
+        // 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(
                 `[adw-alert-dialog] Trying to add a response with id '${id}', but such a response already exists`,
@@ -238,12 +253,10 @@ export class AdwAlertDialog extends HTMLElement {
         button.type = 'button';
         button.className = 'adw-button adw-alert-dialog-response';
         button.textContent = label;
+        button.addEventListener('click', () => this._activateResponse(id));
 
-        const info: ResponseInfo = { id, label, appearance: 'default', enabled: true, button };
-        button.addEventListener('click', () => this._activateResponse(info));
-
-        this._responses.push(info);
-        this._byId.set(id, info);
+        this._model.addResponse(id, label);
+        this._buttons.set(id, button);
         if (this._responseAreaEl) this._responseAreaEl.appendChild(button);
         this._render();
     }
@@ -257,80 +270,94 @@ export class AdwAlertDialog extends HTMLElement {
 
     /** Removes a response. */
     removeResponse(id: string): void {
-        const info = this._byId.get(id);
-        if (!info) return;
-        info.button.remove();
-        this._responses = this._responses.filter((r) => r !== info);
-        this._byId.delete(id);
-        if (this._defaultResponse === id) this._defaultResponse = null;
+        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
+        // 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);
+        for (const response of survivors) {
+            rebuilt.addResponse(response.id, response.label, {
+                appearance: response.appearance,
+                enabled: response.enabled,
+            });
+        }
+        rebuilt.closeResponse = this._model.closeResponse;
+        rebuilt.defaultResponse = this._model.defaultResponse === id ? null : this._model.defaultResponse;
+        this._model = rebuilt;
         this._render();
     }
 
     /** Whether a response with the given ID exists. */
     hasResponse(id: string): boolean {
-        return this._byId.has(id);
+        return this._model.hasResponse(id);
     }
 
     /** Gets a response's label. */
     getResponseLabel(id: string): string | null {
-        return this._byId.get(id)?.label ?? null;
+        return this._model.responses.find((response) => response.id === id)?.label ?? null;
     }
 
     /** Sets a response's label. */
     setResponseLabel(id: string, label: string): void {
-        const info = this._byId.get(id);
-        if (!info) return;
-        info.label = label;
-        info.button.textContent = label;
+        const button = this._buttons.get(id);
+        if (!button) return;
+        // Re-adding a known id updates it in place (the core registry contract).
+        this._model.addResponse(id, label);
+        button.textContent = label;
     }
 
     /** Gets a response's appearance. */
     getResponseAppearance(id: string): AdwResponseAppearance | null {
-        return this._byId.get(id)?.appearance ?? 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 info = this._byId.get(id);
-        if (!info) return;
-        info.appearance = appearance;
-        info.button.classList.toggle('suggested-action', appearance === 'suggested');
-        info.button.classList.toggle('destructive-action', appearance === 'destructive');
+        const button = this._buttons.get(id);
+        if (!button) return;
+        this._model.setResponseAppearance(id, appearance);
+        button.classList.toggle('suggested-action', appearance === 'suggested');
+        button.classList.toggle('destructive-action', appearance === 'destructive');
     }
 
     /** Gets whether a response is enabled. */
     getResponseEnabled(id: string): boolean {
-        return this._byId.get(id)?.enabled ?? false;
+        return this._model.hasResponse(id) ? this._model.getResponseEnabled(id) : false;
     }
 
     /** Sets whether a response is enabled (disabled buttons can't be activated). */
     setResponseEnabled(id: string, enabled: boolean): void {
-        const info = this._byId.get(id);
-        if (!info) return;
-        info.enabled = enabled;
-        info.button.disabled = !enabled;
+        const button = this._buttons.get(id);
+        if (!button) return;
+        this._model.setResponseEnabled(id, enabled);
+        button.disabled = !enabled;
     }
 
     /** Sets the default response — its button is highlighted as the suggested one. */
     setDefaultResponse(id: string | null): void {
-        this._defaultResponse = id;
+        this._model.defaultResponse = id;
         this._render();
     }
 
     /** Sets the close response — emitted on dismissal (Escape / scrim click). */
     setCloseResponse(id: string): void {
-        this._closeResponse = id;
+        this._model.closeResponse = id;
     }
 
     // ── internals ──────────────────────────────────────────────────────────
 
     /** A response button was activated: close, then emit `response`. */
-    private _activateResponse(info: ResponseInfo): void {
-        if (!info.enabled) return;
+    private _activateResponse(id: string): void {
+        if (!this._model.getResponseEnabled(id)) return;
         this._blockCloseResponse = true;
         this.open = false;
         this._blockCloseResponse = false;
-        this._emitResponse(info.id);
+        // resolveById validates against the registry (the core resolve-to-chosen-id
+        // contract) and falls back to the close response.
+        this._emitResponse(this._model.resolveById(id));
     }
 
     /** Dismissal (Escape / scrim) — close, then emit the close-response. */
@@ -338,7 +365,8 @@ export class AdwAlertDialog extends HTMLElement {
         if (!this.open) return;
         this.open = false;
         if (this._blockCloseResponse) return;
-        this._emitResponse(this._closeResponse);
+        // No choice was made — the core model resolves that to the close response.
+        this._emitResponse(this._model.resolveById(null));
     }
 
     private _emitResponse(response: string): void {
@@ -347,9 +375,11 @@ export class AdwAlertDialog extends HTMLElement {
 
     /** Move focus to the default response button (or the first enabled one). */
     private _focusInitial(): void {
+        const defaultId = this._model.defaultResponse;
+        const firstEnabledId = this._model.responses.find((response) => response.enabled)?.id;
         const target =
-            (this._defaultResponse ? this._byId.get(this._defaultResponse)?.button : undefined) ??
-            this._responses.find((r) => r.enabled)?.button;
+            (defaultId ? this._buttons.get(defaultId) : undefined) ??
+            (firstEnabledId ? this._buttons.get(firstEnabledId) : undefined);
         target?.focus();
     }
 
@@ -369,14 +399,15 @@ export class AdwAlertDialog extends HTMLElement {
         // 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).
-        const horizontal = this.preferWideLayout && this._responses.length <= 2;
+        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.
-        for (const info of this._responses) {
-            const isDefault = info.id === this._defaultResponse && info.appearance === 'default';
-            info.button.classList.toggle('default-response', isDefault);
+        const defaultId = this._model.defaultResponse;
+        for (const response of this._model.responses) {
+            const isDefault = response.id === defaultId && response.appearance === 'default';
+            this._buttons.get(response.id)?.classList.toggle('default-response', isDefault);
         }
     }
 }

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

@@ -2,17 +2,30 @@
 // Attributes: title, subtitle, items (JSON string[]), selected (index number)
 // Events: notify::selected (CustomEvent, mirrors GJS GObject signal naming)
 // The native <select> is stretched invisibly over the row so clicking anywhere opens it.
+//
+// The SELECTION state machine (the options list, the two-way index↔value mapping,
+// the empty/out-of-range guards and the programmatic-vs-interactive notify split)
+// is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link ComboState};
+// this element composes it and keeps only the DOM render half — the <select>, the
+// inline value label and the `notify::selected` event.
+// `@gjsify/adwaita-nativescript` composes the same state machine, so both ports
+// share one behaviour.
+//
 // 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.ComboRow.
+//   title/subtitle text column added to match Adw.ComboRow; the selection state
+//   machine composed from @gjsify/adwaita-core.
+
+import { ComboState } from '@gjsify/adwaita-core';
 
 export class AdwComboRow extends HTMLElement {
     private _select!: HTMLSelectElement;
     private _valueEl!: HTMLSpanElement;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
-    private _items: string[] = [];
+    /** The headless options list + selectedIndex↔selectedValue state machine (ADR 0004). */
+    private readonly _state = new ComboState();
     private _initialized = false;
 
     static get observedAttributes() {
@@ -20,7 +33,7 @@ export class AdwComboRow extends HTMLElement {
     }
 
     get selected(): number {
-        return this._select ? this._select.selectedIndex : parseInt(this.getAttribute('selected') || '0', 10);
+        return this._initialized ? this._state.selectedIndex : parseInt(this.getAttribute('selected') || '0', 10);
     }
 
     set selected(value: number) {
@@ -31,8 +44,12 @@ export class AdwComboRow extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        this._items = JSON.parse(this.getAttribute('items') || '[]');
-        const selectedIdx = parseInt(this.getAttribute('selected') || '0', 10);
+        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 })));
+        this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
+        const selectedIdx = this._state.selectedIndex;
 
         const text = document.createElement('div');
         text.className = 'adw-row-text';
@@ -45,11 +62,11 @@ export class AdwComboRow extends HTMLElement {
         // Visible selected value display
         this._valueEl = document.createElement('span');
         this._valueEl.className = 'adw-row-value';
-        this._valueEl.textContent = this._items[selectedIdx] ?? '';
+        this._valueEl.textContent = this._state.selectedLabel;
 
         // Hidden select overlaying the entire row
         const select = document.createElement('select');
-        this._items.forEach((item, i) => {
+        items.forEach((item, i) => {
             const option = document.createElement('option');
             option.value = String(i);
             option.textContent = item;
@@ -60,27 +77,37 @@ export class AdwComboRow extends HTMLElement {
         this.replaceChildren(text, this._valueEl, select);
 
         this._select = select;
-        this._select.addEventListener('change', () => {
-            const idx = this._select.selectedIndex;
-            this._valueEl.textContent = this._items[idx] ?? '';
-            this.setAttribute('selected', String(idx));
+
+        // The core state drives the inline label + the <select> on every change,
+        // and the notify::selected event only on an interactive pick.
+        this._state.subscribe((change) => {
+            this._valueEl.textContent = change.label;
+            if (this._select.selectedIndex !== change.selected) this._select.selectedIndex = change.selected;
+            if (!change.interactive) return;
+            this.setAttribute('selected', String(change.selected));
             this.dispatchEvent(
                 new CustomEvent('notify::selected', {
                     bubbles: true,
-                    detail: { selected: idx },
+                    detail: { selected: change.selected },
                 }),
             );
         });
 
+        this._select.addEventListener('change', () => {
+            // A user pick — `select()` guards the no-op case and notifies
+            // `interactive`, so the subscriber emits notify::selected.
+            this._state.select(this._select.selectedIndex);
+        });
+
         this._renderText();
     }
 
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
         if (!this._initialized) return;
         if (name === 'selected') {
-            const idx = parseInt(value || '0', 10);
-            this._select.selectedIndex = idx;
-            this._valueEl.textContent = this._items[idx] ?? '';
+            // A programmatic set — the core state notifies `interactive: false`,
+            // so the subscriber re-syncs the display without emitting an event.
+            this._state.setSelectedIndex(parseInt(value || '0', 10));
         } else {
             this._renderText();
         }

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

@@ -10,10 +10,21 @@
 // Events: notify::expanded (CustomEvent), notify::enable-expansion (CustomEvent)
 //   — mirror Adw.ExpanderRow's GObject signal names so the same code path drives
 //   both the web and GTK renderers.
+//
+// The DISCLOSURE state (the expanded flag and its idempotent, notify-on-change
+// transitions) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
+// {@link ExpanderState}; this element composes it and keeps only the DOM render
+// half — the header/content markup, the `expanded` attribute reflection and the
+// `notify::expanded` event. `@gjsify/adwaita-nativescript` composes the same
+// state machine, so both ports share one behaviour.
+//
 // Reference: refs/adwaita-web/adwaita-web/scss/_expander_row.scss
 // Reference: refs/libadwaita/src/stylesheet/widgets/_expander-row.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
-// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
+// disclosure state machine composed from @gjsify/adwaita-core.
+
+import { ExpanderState } from '@gjsify/adwaita-core';
 
 export class AdwExpanderRow extends HTMLElement {
     private _headerEl!: HTMLDivElement;
@@ -25,19 +36,33 @@ export class AdwExpanderRow extends HTMLElement {
     private _contentEl!: HTMLDivElement;
     private _prefixEl!: HTMLDivElement;
     private _suffixEl!: HTMLDivElement;
+    /** The headless expanded/collapsed disclosure state machine (ADR 0004). */
+    private readonly _state = new ExpanderState();
     private _initialized = false;
 
+    constructor() {
+        super();
+        // Subscribed in the constructor (NOT connectedCallback) so a disclosure
+        // set before the element is connected still reflects to the attribute.
+        // The custom-element constructor rules allow this — nothing touches the
+        // DOM until the state actually changes.
+        this._state.subscribe((expanded) => {
+            if (expanded) this.setAttribute('expanded', '');
+            else this.removeAttribute('expanded');
+            if (this._initialized) this._render();
+        });
+    }
+
     static get observedAttributes() {
         return ['title', 'subtitle', 'expanded', 'enable-expansion', 'show-enable-switch'];
     }
 
     get expanded(): boolean {
-        return this.hasAttribute('expanded');
+        return this._state.expanded;
     }
 
     set expanded(value: boolean) {
-        if (value) this.setAttribute('expanded', '');
-        else this.removeAttribute('expanded');
+        this._state.setExpanded(value);
     }
 
     get enableExpansion(): boolean {
@@ -122,10 +147,14 @@ export class AdwExpanderRow extends HTMLElement {
         this._headerEl.addEventListener('click', (event) => {
             // Clicks on the enable switch toggle expansion-enable, not disclosure.
             if (this._enableLabel.contains(event.target as Node)) return;
-            this.expanded = !this.expanded;
-            this.dispatchEvent(
-                new CustomEvent('notify::expanded', { bubbles: true, detail: { expanded: this.expanded } }),
-            );
+            // The core state machine flips + reflects + re-renders; the event is
+            // emitted here so only a USER disclosure notifies (a programmatic
+            // `expanded = …` stays silent, as it always has on this port).
+            if (this._state.toggle()) {
+                this.dispatchEvent(
+                    new CustomEvent('notify::expanded', { bubbles: true, detail: { expanded: this.expanded } }),
+                );
+            }
         });
 
         this._enableSwitch.addEventListener('change', () => {
@@ -138,11 +167,18 @@ export class AdwExpanderRow extends HTMLElement {
             );
         });
 
+        // Seed the disclosure from the parsed markup — attributeChangedCallback
+        // is guarded until the element is initialized, so a declarative
+        // `expanded` attribute has to be adopted here.
+        this._state.setExpanded(this.hasAttribute('expanded'));
         this._render();
     }
 
-    attributeChangedCallback() {
-        if (this._initialized) this._render();
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        // The `expanded` attribute is the declarative face of the core state.
+        if (name === 'expanded') this._state.setExpanded(this.hasAttribute('expanded'));
+        this._render();
     }
 
     private _render() {