@gjsify/adwaita-web 0.31.0 → 0.32.0

package/src/elements/adw-popover.ts

@@ -0,0 +1,283 @@
+// <adw-popover> — the elevated surface that pops up next to an anchor, the web
+// counterpart of GtkPopover as libadwaita styles it. It is the ONE popover in
+// this package: `<adw-menu-button>`, `<adw-drop-down>` and `<adw-split-button>`
+// each used to build their own, and no two agreed. The surface disagreed (12px /
+// 12px / 9px radius against libadwaita's 15px; two correct three-layer shadows
+// and one invented two-layer one) and so did the behaviour — the split button
+// had neither Escape dismissal nor arrow-key navigation, while the other two
+// spelled the same wrap arithmetic out twice.
+//
+// The dismissal + keyboard state machine lives in `@gjsify/adwaita-core`
+// ({@link PopoverState}, {@link resolvePopoverKey}, ADR 0004); this element owns
+// the DOM: the surface node, the document-level listeners, focus movement, and
+// the `open` attribute reflection.
+//
+// PLACEMENT IS CSS, NOT SCRIPT. `_popover.scss` positions the surface off the
+// `position` / `align` attributes; nothing here measures a rect or flips on
+// overflow, exactly as the three copies never did. Core carries no positioner
+// for the same reason — see the module header of `adwaita-core/src/popover.ts`.
+//
+// Attributes:
+//   open      — boolean; reflects (and drives) the visible state.
+//   position  — bottom | top | start | end (default bottom) — which side of the
+//               anchor the surface sits on. `GtkPopover:position`'s own
+//               autohide/has-arrow semantics are NOT verifiable in this tree
+//               (refs/gtk is empty, libadwaita vendors no adw-popover.c), so only
+//               the placement axis is modelled.
+//   align     — start | end (default start) — which edge it lines up with.
+//   role      — menu | listbox (default menu) — the ARIA role of the surface.
+//               An a11y fact ONLY; it does not pick the surface variant, see
+//               `menu` below.
+//   menu      — boolean; libadwaita's `.menu` STYLE CLASS on the popover node
+//               (0 padding on the contents, `$menu_margin` on the item box —
+//               _menus.scss:58-66), opt-in exactly as it is in GTK.
+//               DO NOT infer it from `role`: `GtkDropDown`'s popover is a
+//               `popover.menu` too (`dropdown { popover.menu { … } }`,
+//               _dropdowns.scss:22) while its rows are `option`s, not
+//               `menuitem`s. Tying the surface to the role gets that backwards
+//               and pads the drop-down like a bare content popover.
+// Properties:
+//   open      — whether the popover is showing (get/set).
+//   anchor    — the element the surface is positioned against and returns focus
+//               to. Defaults to `parentElement` (get/set).
+//   items     — the navigable rows, in DOM order (get). Used for keyboard moves.
+// Methods (GtkPopover's own vocabulary):
+//   popup()   — show it.  popdown() — hide it.
+// Events:
+//   `notify::open` (CustomEvent, bubbles, detail = { open }) — mirrors the
+//     GObject property-notify; fires on every change, programmatic included.
+//   `popover-item-activated` (CustomEvent, bubbles, detail = { index }) — a row
+//     was chosen by keyboard. Click activation stays the row's own listener.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_popovers.scss:7-28 (popover > contents)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss:58-66, :134-156 (popover.menu, modelbutton)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { PopoverState, resolvePopoverKey } from '@gjsify/adwaita-core';
+
+/** Which side of the anchor the surface sits on. */
+export type AdwPopoverPosition = 'bottom' | 'top' | 'start' | 'end';
+
+/** Which edge of the anchor the surface lines up with. */
+export type AdwPopoverAlign = 'start' | 'end';
+
+/** The ARIA role of the surface — it decides the row role consumers give their items. */
+export type AdwPopoverRole = 'menu' | 'listbox';
+
+const POSITIONS: readonly AdwPopoverPosition[] = ['bottom', 'top', 'start', 'end'];
+const ALIGNS: readonly AdwPopoverAlign[] = ['start', 'end'];
+const ROLES: readonly AdwPopoverRole[] = ['menu', 'listbox'];
+
+/** The row selector keyboard navigation walks. */
+const ITEM_SELECTOR = '.adw-popover-item';
+
+export class AdwPopover extends HTMLElement {
+    private readonly _state = new PopoverState();
+    private _anchor: HTMLElement | null = null;
+    private _initialized = false;
+    /** Guards the `open` attribute↔property loop, which would otherwise recurse. */
+    private _reflecting = false;
+
+    private _onDocumentPointerDown = (event: Event): void => {
+        const target = event.target as Node;
+        if (this.contains(target)) return;
+        // A click on the anchor is the anchor's own toggle — closing here too
+        // would close and immediately reopen (or reopen and immediately close).
+        if (this.anchor?.contains(target) === true) return;
+        this._state.dismiss();
+    };
+
+    private _onDocumentKeyDown = (event: KeyboardEvent): void => {
+        if (event.key !== 'Escape') return;
+        // Captured at the document, so a nested popover's Escape does not also
+        // close its parent.
+        event.stopPropagation();
+        this._state.dismiss();
+        this.anchor?.focus();
+    };
+
+    static get observedAttributes() {
+        return ['open', 'position', 'align', 'role', 'menu'];
+    }
+
+    /** Whether the popover is showing. */
+    get open(): boolean {
+        return this._state.open;
+    }
+
+    set open(value: boolean) {
+        if (value) this._state.popup();
+        else this._state.popdown();
+    }
+
+    /**
+     * The element the surface is positioned against and hands focus back to.
+     * Defaults to `parentElement`, which is the common case: the popover is the
+     * last child of the widget that owns it.
+     */
+    get anchor(): HTMLElement | null {
+        return this._anchor ?? this.parentElement;
+    }
+
+    set anchor(value: HTMLElement | null) {
+        this._anchor = value;
+    }
+
+    /** Which side of the anchor the surface sits on. */
+    get position(): AdwPopoverPosition {
+        const value = this.getAttribute('position');
+        return POSITIONS.includes(value as AdwPopoverPosition) ? (value as AdwPopoverPosition) : 'bottom';
+    }
+
+    set position(value: AdwPopoverPosition) {
+        this.setAttribute('position', value);
+    }
+
+    /** Which edge of the anchor the surface lines up with. */
+    get align(): AdwPopoverAlign {
+        const value = this.getAttribute('align');
+        return ALIGNS.includes(value as AdwPopoverAlign) ? (value as AdwPopoverAlign) : 'start';
+    }
+
+    set align(value: AdwPopoverAlign) {
+        this.setAttribute('align', value);
+    }
+
+    /** The surface's ARIA role. */
+    get popoverRole(): AdwPopoverRole {
+        const value = this.getAttribute('role');
+        return ROLES.includes(value as AdwPopoverRole) ? (value as AdwPopoverRole) : 'menu';
+    }
+
+    /** The navigable rows, in DOM order. Hidden rows are skipped — a filtered list navigates what it shows. */
+    get items(): HTMLElement[] {
+        return [...this.querySelectorAll<HTMLElement>(ITEM_SELECTOR)].filter((item) => !item.hidden);
+    }
+
+    /** Show the popover — `gtk_popover_popup()`. */
+    popup(): void {
+        this._state.popup();
+    }
+
+    /** Hide the popover — `gtk_popover_popdown()`. */
+    popdown(): void {
+        this._state.popdown();
+    }
+
+    /** Subscribe to open-state changes. Returns an unsubscribe function. */
+    subscribe(listener: (open: boolean) => void): () => void {
+        return this._state.subscribe((change) => listener(change.open));
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this.classList.add('adw-popover');
+        if (!this.hasAttribute('role')) this.setAttribute('role', 'menu');
+        // The `menu` variant is NOT defaulted or inferred here — it is GTK's
+        // `.menu` style class, and the widget that owns the popover is what adds
+        // it, as in the C. See the attribute docs above for why role is the
+        // wrong thing to key it off.
+
+        this.addEventListener('keydown', (event) => this._onKeyDown(event));
+        this._state.subscribe((change) => this._onStateChange(change.open));
+
+        // The `open` attribute may already be present in server-rendered markup.
+        if (this.hasAttribute('open')) this._state.popup();
+        this._render();
+    }
+
+    disconnectedCallback() {
+        this._unbindDocument();
+    }
+
+    attributeChangedCallback(name: string, _previous: string | null, value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'open') {
+            if (this._reflecting) return;
+            if (value !== null) this._state.popup();
+            else this._state.popdown();
+            return;
+        }
+        if (name === 'role' && value === null) {
+            // A removed role falls back to the default rather than leaving the
+            // surface unlabelled to assistive tech.
+            this.setAttribute('role', 'menu');
+            return;
+        }
+        this._render();
+    }
+
+    // ── internals ──────────────────────────────────────────────────────────
+
+    private _onStateChange(open: boolean): void {
+        if (open) this._bindDocument();
+        else this._unbindDocument();
+
+        this._reflecting = true;
+        if (open) this.setAttribute('open', '');
+        else this.removeAttribute('open');
+        this._reflecting = false;
+
+        this._render();
+        this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open } }));
+    }
+
+    private _bindDocument(): void {
+        document.addEventListener('pointerdown', this._onDocumentPointerDown);
+        // Capture, so Escape reaches us before a focused child swallows it.
+        document.addEventListener('keydown', this._onDocumentKeyDown, true);
+    }
+
+    private _unbindDocument(): void {
+        document.removeEventListener('pointerdown', this._onDocumentPointerDown);
+        document.removeEventListener('keydown', this._onDocumentKeyDown, true);
+    }
+
+    private _render(): void {
+        this.hidden = !this._state.open;
+        this.dataset.position = this.position;
+        this.dataset.align = this.align;
+    }
+
+    /**
+     * Arrow/Home/End/Enter/Space inside the surface. The arithmetic is core's
+     * ({@link resolvePopoverKey}); this only maps its answer onto the DOM.
+     *
+     * Escape is NOT handled here — it is bound at the document in capture phase
+     * so it works no matter where focus sits, including a search entry inside
+     * the popover.
+     */
+    private _onKeyDown(event: KeyboardEvent): void {
+        if (!this._state.open) return;
+        const items = this.items;
+        const active = document.activeElement as HTMLElement | null;
+        const currentIndex = active === null ? -1 : items.indexOf(active);
+        const hasSearch = this.querySelector('input, textarea') !== null;
+
+        const { action, index } = resolvePopoverKey(event.key, {
+            itemCount: items.length,
+            currentIndex,
+            hasSearch,
+        });
+
+        if (action === 'focus') {
+            event.preventDefault();
+            items[index]?.focus();
+            return;
+        }
+        if (action === 'activate') {
+            // preventDefault BEFORE the synthetic click: a focused <button>
+            // activates natively on Enter (keydown) and Space (keyup), so
+            // without it the row would fire twice.
+            event.preventDefault();
+            items[index]?.click();
+            this.dispatchEvent(new CustomEvent('popover-item-activated', { bubbles: true, detail: { index } }));
+        }
+        // 'close' arrives through the document capture handler; 'none' is not ours.
+    }
+}
+
+customElements.define('adw-popover', AdwPopover);

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

@@ -5,11 +5,21 @@
 // shows the dialog title and a trailing close button.
 //
 // Pages are declared as <adw-preferences-page> children (each with optional
-// `title` / `icon-name` attributes + arbitrary group content); the dialog
-// snapshots them at connect time and stacks their content in the scrolled body.
+// `title` / `icon-name` / `name` / `use-underline` attributes + arbitrary group
+// content) and are moved — as ELEMENTS, keeping their identity — into the
+// scrolled body. `add(page)` accepts one at any later time, mirroring
+// adw_preferences_dialog_add.
 // (Adw shows a view-switcher when there is more than one page and the window is
-// wide; the web port renders the pages stacked, matching the single-page common
-// case the storybook exercises.)
+// wide, and shows exactly one page at a time; the web port renders the pages
+// stacked, matching the single-page common case the storybook exercises. The
+// page COLLECTION model — visible-page, visible-page-name, the auto-pick —
+// belongs to Adw.ViewStack and is available as `ViewStackState` in
+// @gjsify/adwaita-core when this port grows a switcher.)
+//
+// `search(query)` implements the dialog's search over those pages: the corpus,
+// the filter and the `page → group` result subtitles all come from
+// @gjsify/adwaita-core, so the browser and NativeScript dialogs return the same
+// results for the same tree.
 //
 // Like Adw.Dialog the dialog starts hidden; `present()` / setting the `open`
 // attribute reveals it. It is dismissed by Escape, by clicking the scrim, or by
@@ -42,16 +52,57 @@
 // Copyright (c) 2023-2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import type { PreferencesSearchResult, SearchPreferencesOptions } from '@gjsify/adwaita-core';
+import { searchPreferencesDom } from '../preferences-search.js';
+
 const DEFAULT_CONTENT_WIDTH = 640;
 
 /**
- * A single preferences page. Child of <adw-preferences-dialog>; consumed at
- * connect time. Carries optional `title` / `icon-name` attributes and any
+ * A single preferences page. Child of <adw-preferences-dialog>. Carries optional
+ * `title` / `icon-name` / `name` / `use-underline` attributes and any
  * <adw-preferences-group> content — mirrors Adw.PreferencesPage.
+ *
+ * The dialog keeps the page ELEMENT rather than hoisting its children out,
+ * because the page's identity is load-bearing: `adw_preferences_dialog_add`
+ * binds title / icon-name / name / use-underline / visible onto the view-stack
+ * page (adw-preferences-dialog.c:707-711), and `create_search_row_subtitle`
+ * needs the title back the moment a second page is visible.
  */
 export class AdwPreferencesPage extends HTMLElement {
     static get observedAttributes() {
-        return ['title', 'icon-name', 'open'];
+        return ['title', 'icon-name', 'name', 'use-underline', 'open'];
+    }
+
+    /** `adw_preferences_page_get_name` — the view-stack child name. */
+    get name(): string {
+        return this.getAttribute('name') ?? '';
+    }
+
+    set name(value: string) {
+        this.setAttribute('name', value);
+    }
+
+    /** `AdwPreferencesPage:icon-name`, shown by a view switcher. */
+    get iconName(): string {
+        return this.getAttribute('icon-name') ?? '';
+    }
+
+    set iconName(value: string) {
+        this.setAttribute('icon-name', value);
+    }
+
+    /** `AdwPreferencesPage:use-underline` — the title carries a mnemonic. */
+    get useUnderline(): boolean {
+        return this.hasAttribute('use-underline');
+    }
+
+    set useUnderline(value: boolean) {
+        this.toggleAttribute('use-underline', value);
+    }
+
+    /** The page's groups, in document order. */
+    get groups(): HTMLElement[] {
+        return Array.from(this.querySelectorAll('adw-preferences-group'));
     }
 }
 
@@ -61,6 +112,7 @@ export class AdwPreferencesDialog extends HTMLElement {
     private _dialogEl!: HTMLDivElement;
     private _titleEl!: HTMLSpanElement;
     private _bodyEl!: HTMLDivElement;
+    private _pagesEl!: HTMLDivElement;
     private _closeBtn!: HTMLButtonElement;
 
     static get observedAttributes() {
@@ -116,18 +168,66 @@ export class AdwPreferencesDialog extends HTMLElement {
         this.open = false;
     }
 
+    /**
+     * `adw_preferences_dialog_add` (adw-preferences-dialog.c:693-716) — add a
+     * page at ANY time.
+     *
+     * Before this the pages were snapshotted once, in `connectedCallback`; a
+     * page appended later stayed a sibling of the scrim and rendered OUTSIDE
+     * the dialog card. GTK and the NativeScript port both accept a page
+     * whenever it arrives.
+     */
+    add(page: AdwPreferencesPage): void {
+        this._pagesEl.appendChild(page);
+    }
+
+    /**
+     * `adw_preferences_dialog_remove` (:723-745). C logs
+     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a page it does not own;
+     * returning `false` is the same contract without a console write.
+     *
+     * NOT named `remove`: `ChildNode.remove()` already exists on every element
+     * and takes no arguments, so overriding it with a different signature makes
+     * the class un-assignable to `HTMLElement` — which `customElements.define`
+     * requires.
+     */
+    removePage(page: AdwPreferencesPage): boolean {
+        if (page.parentNode !== this._pagesEl) return false;
+        this._pagesEl.removeChild(page);
+        return true;
+    }
+
+    /** The dialog's pages, in add order. */
+    get pages(): AdwPreferencesPage[] {
+        return Array.from(this._pagesEl.querySelectorAll('adw-preferences-page')) as AdwPreferencesPage[];
+    }
+
+    /**
+     * The preferences search (`filter_search_results` +
+     * `create_search_row_subtitle`), over this dialog's live page subtree.
+     *
+     * The whole pipeline is `@gjsify/adwaita-core`'s, so this dialog and the
+     * NativeScript one answer identically for the same tree — including the
+     * three corpus filters (visible page → visible group → titled visible row)
+     * and the case fold that makes `strasse` find `Straße`.
+     *
+     * An empty query returns the WHOLE corpus, which is what C does and what
+     * makes the results list non-empty before the user types.
+     */
+    search(query: string, options?: SearchPreferencesOptions): PreferencesSearchResult<Element>[] {
+        return searchPreferencesDom(this._pagesEl, query, options);
+    }
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Snapshot the declared pages before taking over the subtree. Each page's
-        // content (its groups) is stacked in the scrolled body; any unwrapped
-        // children fall back to the body too (Adw.PreferencesDialog's buildable
-        // default adds a child as a page).
-        const pages = Array.from(this.querySelectorAll(':scope > adw-preferences-page')) as AdwPreferencesPage[];
-        const pageContent = pages.flatMap((page) => Array.from(page.childNodes));
-        const claimed = new Set<Node>([...pages, ...pageContent]);
-        const unwrapped = Array.from(this.childNodes).filter((node) => !claimed.has(node));
+        // Snapshot the declared children before taking over the subtree. The
+        // page ELEMENTS move into the body intact — their title / name /
+        // icon-name are what a search result subtitle and a view switcher read
+        // — and any unwrapped children follow them (Adw.PreferencesDialog's
+        // buildable default adds a child as a page).
+        const declared = Array.from(this.childNodes);
 
         // Full-cover scrim — clicking it dismisses the dialog (or raises
         // close-attempt when locked).
@@ -169,15 +269,14 @@ export class AdwPreferencesDialog extends HTMLElement {
 
         header.append(leading, this._titleEl, trailing);
 
-        // Scrolled body — a clamped column of the declared pages' content.
+        // Scrolled body — a clamped column of the declared pages.
         this._bodyEl = document.createElement('div');
         this._bodyEl.className = 'adw-preferences-dialog-body';
 
-        const clamp = document.createElement('div');
-        clamp.className = 'adw-preferences-dialog-pages';
-        for (const child of pageContent) clamp.appendChild(child);
-        for (const child of unwrapped) clamp.appendChild(child);
-        this._bodyEl.appendChild(clamp);
+        this._pagesEl = document.createElement('div');
+        this._pagesEl.className = 'adw-preferences-dialog-pages';
+        for (const child of declared) this._pagesEl.appendChild(child);
+        this._bodyEl.appendChild(this._pagesEl);
 
         this._dialogEl.append(header, this._bodyEl);