@gjsify/adwaita-web 0.31.0 → 0.33.0

package/src/elements/adw-password-entry-row.ts

@@ -1,120 +1,142 @@
-// <adw-password-entry-row> — A boxed-list entry row tailored for secrets: the
-// title floats as a label, the editable text is masked, and a trailing peek
-// button toggles between hiding and revealing the contents. A specialization of
-// <adw-entry-row> (Adw.PasswordEntryRow extends Adw.EntryRow).
-// Attributes: title, text, revealed (boolean — show the contents in clear text).
-// Property: text (get/set, proxies the inner input); revealed (get/set).
-// Events: `changed` (CustomEvent) on every edit — mirrors Adw.EntryRow's
-//   `changed` signal so it drives the same code path as the GTK renderer.
-//   `notify::revealed` (CustomEvent) when the peek toggle flips visibility.
+// <adw-password-entry-row> — An entry row tailored for secrets: the value is
+// masked, a trailing peek button reveals it, and a warning shows while Caps Lock
+// is engaged.
+//
+// It now EXTENDS `<adw-entry-row>`, as `AdwPasswordEntryRow` extends
+// `AdwEntryRow` in the C (adw-password-entry-row.c:50). This file used to be a
+// near copy-paste of `adw-entry-row.ts` — a normalized diff showed the
+// connectedCallback and attributeChangedCallback bodies were the same code — so
+// every entry-row fix had to be made twice and one of the two always drifted.
+// What is left here is only what the C subclass adds: the masked input, the peek
+// toggle, and the caps-lock source.
+//
+// The reveal/caps-lock DERIVATION is HEADLESS and lives in
+// `@gjsify/adwaita-core` (ADR 0004) as {@link PasswordEntryRowState}, which
+// composes the parent's `EntryRowState` exactly like the C drives its
+// parent through `adw_entry_row_set_show_indicator`. Two rules fall out of it
+// that neither port had: peeking suppresses the caps-lock warning, and so does
+// losing focus.
+//
+// Attributes: everything `<adw-entry-row>` observes, plus `revealed`.
+// Properties: `revealed`, `capsLockOn` (+ everything inherited).
+// Events: `notify::revealed` — only on a REAL change. The old implementation
+//   fired it on every `setAttribute`, including a redundant one, because
+//   attributeChangedCallback runs for a same-value write; the core's setter
+//   guard (the house rule at adw-entry-row.c:984/:1198/:1247) is what fixes it.
+//
+// Reference: refs/libadwaita/src/adw-password-entry-row.c
 // Reference: refs/adwaita-web/adwaita-web/docs/widgets/passwordentryrow.md
-// Reference: refs/libadwaita/src/adw-password-entry-row.c (peek toggle: the
-//   view-reveal / view-conceal symbolic swap; CSS node `row` carries `.entry`
-//   and `.password` style classes).
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-export class AdwPasswordEntryRow extends HTMLElement {
-    private _input!: HTMLInputElement;
-    private _titleEl!: HTMLSpanElement;
-    private _toggle!: HTMLButtonElement;
-    private _toggleIcon!: HTMLSpanElement;
-    private _initialized = false;
+import { PasswordEntryRowState, type PasswordEntryRowRenderState } from '@gjsify/adwaita-core';
 
-    static get observedAttributes() {
-        return ['title', 'text', 'revealed'];
-    }
+import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+
+import { AdwEntryRow } from './adw-entry-row.js';
+
+export class AdwPasswordEntryRow extends AdwEntryRow {
+    /** The headless peek + caps-lock derivation, composing the parent row's state. */
+    private readonly _password = new PasswordEntryRowState(this._state);
+    private _toggle!: HTMLButtonElement;
+    private _toggleIcon!: AdwIcon;
 
-    get text(): string {
-        return this._input ? this._input.value : (this.getAttribute('text') ?? '');
+    static get observedAttributes(): string[] {
+        return [...AdwEntryRow.observedAttributes, 'revealed'];
     }
 
-    set text(value: string) {
-        if (this._input) this._input.value = value;
-        else this.setAttribute('text', value);
+    // `_password_entry_row.scss` scopes its rules to `.adw-password-entry-row-*`,
+    // so the inherited DOM builder must name the parts that way.
+    protected override get _classPrefix(): string {
+        return 'adw-password-entry-row';
     }
 
-    /** Whether the contents are shown in clear text (peek toggle is engaged). */
+    /** Whether the contents are shown in clear text (`GtkText:visibility`). */
     get revealed(): boolean {
-        return this.hasAttribute('revealed');
+        return this._password.revealed;
     }
 
     set revealed(value: boolean) {
-        if (value) this.setAttribute('revealed', '');
-        else this.removeAttribute('revealed');
+        this._password.setRevealed(value);
     }
 
-    connectedCallback() {
-        if (this._initialized) return;
-        this._initialized = true;
+    /** Whether Caps Lock is engaged, as last observed from a keyboard event. */
+    get capsLockOn(): boolean {
+        return this._password.capsLockOn;
+    }
 
-        this._titleEl = document.createElement('span');
-        this._titleEl.className = 'adw-row-title';
-        this._titleEl.textContent = this.getAttribute('title') ?? '';
+    /**
+     * Feed the platform's Caps Lock state in — GDK gets it from the keyboard
+     * device (adw-password-entry-row.c:111-115). Public because a host that
+     * knows better than `KeyboardEvent.getModifierState` (a virtual keyboard, a
+     * test) can drive it directly.
+     */
+    setCapsLockOn(on: boolean): void {
+        this._password.setCapsLockOn(on);
+    }
 
-        this._input = document.createElement('input');
-        this._input.className = 'adw-password-entry-row-input';
-        // Masked by default — Adw.PasswordEntryRow sets GTK_INPUT_PURPOSE_PASSWORD
-        // and starts with visibility off.
-        this._input.type = this.hasAttribute('revealed') ? 'text' : 'password';
-        this._input.value = this.getAttribute('text') ?? '';
+    protected override _onConnected(): void {
+        // `gtk_text_set_visibility (…, FALSE)` + GTK_INPUT_PURPOSE_PASSWORD (C:158-160).
+        this._input.type = 'password';
         this._input.autocomplete = 'off';
-        this._input.addEventListener('input', () => {
-            this.dispatchEvent(new CustomEvent('changed', { bubbles: true, detail: { text: this._input.value } }));
-        });
-
-        // Title floats as a small label above the masked value, both left-aligned
-        // in a column (the filled Adw.EntryRow look).
-        const text = document.createElement('div');
-        text.className = 'adw-password-entry-row-text';
-        text.append(this._titleEl, this._input);
 
-        // Trailing peek toggle — a flat icon button, vertically centred. Swaps
-        // between the reveal / conceal symbolics like the native widget.
         this._toggle = document.createElement('button');
-        this._toggle.className = 'adw-button flat circular icon-only adw-password-entry-row-toggle';
         this._toggle.type = 'button';
-        this._toggleIcon = document.createElement('span');
-        this._toggleIcon.setAttribute('aria-hidden', 'true');
-        this._toggle.appendChild(this._toggleIcon);
-        this._toggle.addEventListener('click', () => {
-            this.revealed = !this.revealed;
+        this._toggle.className = `adw-button flat circular icon-only ${this._classPrefix}-toggle`;
+        this._toggleIcon = createAdwIcon(null);
+        this._toggle.append(this._toggleIcon);
+        this._toggle.addEventListener('click', () => this._password.togglePeek());
+        // C:152 — installed through add_suffix, so it is the FIRST suffix and a
+        // consumer's own suffix lands after it instead of replacing it.
+        this.addSuffix(this._toggle);
+
+        // GDK reads caps lock off the keyboard device; the browser exposes it
+        // only on keyboard events, so those are the source here.
+        const readCapsLock = (event: KeyboardEvent) => this._password.setCapsLockOn(event.getModifierState('CapsLock'));
+        this._input.addEventListener('keydown', readCapsLock);
+        this._input.addEventListener('keyup', readCapsLock);
+
+        // The indicator icon + tooltip are set once at init (C:169-171); their
+        // canonical names come from the core so both ports spell them alike.
+        const initial = this._password.state;
+        this.setIndicatorIconName(initial.indicatorIconName);
+        this.setIndicatorTooltip(initial.indicatorTooltip);
+
+        // Seed from the attribute BEFORE subscribing, so the first paint emits no
+        // `notify::revealed`.
+        if (this.hasAttribute('revealed')) this._password.setRevealed(this.getAttribute('revealed') !== 'false');
+        this._renderPassword(this._password.state);
+        this._password.subscribe((state) => {
+            this._renderPassword(state);
+            this.dispatchEvent(
+                new CustomEvent('notify::revealed', { bubbles: true, detail: { revealed: state.revealed } }),
+            );
         });
-
-        // Trailing edit pencil (before the peek toggle), mirroring native.
-        const edit = document.createElement('span');
-        edit.className = 'adw-row-edit adw-icon adw-icon--document-edit';
-        edit.setAttribute('aria-hidden', 'true');
-        edit.addEventListener('click', () => this._input.focus());
-
-        this.replaceChildren(text, edit, this._toggle);
-        this._renderRevealed();
     }
 
-    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
-        if (!this._initialized) return;
-        if (name === 'title') {
-            this._titleEl.textContent = value ?? '';
-        } else if (name === 'text') {
-            if (this._input.value !== (value ?? '')) this._input.value = value ?? '';
-        } else if (name === 'revealed') {
-            this._renderRevealed();
-            this.dispatchEvent(
-                new CustomEvent('notify::revealed', { bubbles: true, detail: { revealed: this.revealed } }),
-            );
+    override attributeChangedCallback(name: string, oldValue: string | null, value: string | null) {
+        if (name !== 'revealed') {
+            super.attributeChangedCallback(name, oldValue, value);
+            return;
         }
+        if (!this._initialized) return;
+        // The core guard makes this idempotent, which is what keeps the reflection
+        // in `_renderPassword` from bouncing back as a second notification.
+        this._password.setRevealed(value !== null && value !== 'false');
     }
 
-    private _renderRevealed() {
-        const revealed = this.revealed;
-        this._input.type = revealed ? 'text' : 'password';
-        // view-conceal when revealed (offer to hide), view-reveal when masked.
-        const icon = revealed ? 'view-conceal' : 'view-reveal';
-        this._toggleIcon.className = `adw-icon adw-icon--${icon}`;
-        const labelText = revealed ? 'Hide Password' : 'Show Password';
-        this._toggle.title = labelText;
-        this._toggle.setAttribute('aria-label', labelText);
-        this._toggle.setAttribute('aria-pressed', String(revealed));
+    /** `notify_visibility_cb` (C:62-81), applied to the DOM. */
+    private _renderPassword(state: PasswordEntryRowRenderState): void {
+        this._input.type = state.revealed ? 'text' : 'password';
+        // The libadwaita name travels in `data-icon-name`; the mask class is the
+        // curated @gjsify/adwaita-icons spelling of the same symbolic.
+        this._toggleIcon.dataset.iconName = state.peekIconName;
+        this._toggleIcon.iconName = state.peekIconName;
+        this._toggle.title = state.peekLabel;
+        this._toggle.setAttribute('aria-label', state.peekLabel);
+        this._toggle.setAttribute('aria-pressed', String(state.revealed));
+        if (state.revealed) this.setAttribute('revealed', '');
+        else this.removeAttribute('revealed');
     }
 }
 

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);