@gjsify/adwaita-web 0.31.0 → 0.32.0

package/src/elements/adw-overlay-split-view.ts

@@ -1,35 +1,85 @@
 // <adw-overlay-split-view> — Responsive sidebar that docks or overlays content.
 // Reference: Adw.OverlaySplitView from libadwaita.
 // Docs: refs/adwaita-web/adwaita-web/docs/widgets/overlaysplitview.md
+//
+// `breakpoint` takes an Adwaita condition (e.g. "max-width: 720px") and drives
+// `collapsed` from the element's own box — the browser counterpart to an
+// Adw.Breakpoint with an add_setter(), so the sidebar overlays on narrow widths
+// without the application wiring a media query itself.
+
+import {
+    DEFAULT_MAX_SIDEBAR_WIDTH,
+    DEFAULT_MIN_SIDEBAR_WIDTH,
+    DEFAULT_SIDEBAR_WIDTH_FRACTION,
+    OverlaySplitViewState,
+    resolveSidebarBounds,
+    type AdwPackType,
+} from '@gjsify/adwaita-core';
+
+import { bindBreakpointSetter } from '../breakpoints.js';
+
+/**
+ * Read a boolean attribute the way a GTK property with a TRUE default has to be
+ * read: absence means the default, not false.
+ *
+ * HTML boolean attributes are presence-only, which can only ever express a FALSE
+ * default — so `show-sidebar` used to start hidden while `Adw.OverlaySplitView`
+ * starts shown (adw-overlay-split-view.c:974-976). `show-sidebar="false"` is the
+ * explicit off switch.
+ */
+function readTriStateAttr(element: Element, name: string, fallback: boolean): boolean {
+    const raw = element.getAttribute(name);
+    if (raw === null) return fallback;
+    return raw !== 'false' && raw !== '0';
+}
 
 export class AdwOverlaySplitView extends HTMLElement {
     private _initialized = false;
     private _sidebarEl!: HTMLDivElement;
     private _contentEl!: HTMLDivElement;
     private _backdropEl!: HTMLDivElement;
+    private _disposeBreakpoint: (() => void) | undefined;
+    /**
+     * The single source of truth for the property interplay, shared with the
+     * NativeScript renderer (ADR 0004). The element owns the attributes and the
+     * painting; every rule about what `collapsed` + `show-sidebar` + `pin-sidebar`
+     * MEAN together lives in core, held to `OVERLAY_COLLAPSE_VECTORS`.
+     */
+    private _state = new OverlaySplitViewState();
+    /** Re-entrancy guard for {@link _reflectShowSidebar}. */
+    private _reflecting = false;
 
+    /**
+     * Every attribute {@link _readAttribute} handles must be listed here — an
+     * unobserved attribute never reaches `attributeChangedCallback`, so its branch
+     * is DEAD after construction. `pin-sidebar` was missing, which made the
+     * property that suppresses the collapse coupling settable only in the markup
+     * a parser saw: `view.setAttribute('pin-sidebar', '')` did nothing at all.
+     */
     static get observedAttributes() {
         return [
             'show-sidebar',
             'collapsed',
+            'pin-sidebar',
             'sidebar-position',
             'min-sidebar-width',
             'max-sidebar-width',
             'sidebar-width-fraction',
+            'breakpoint',
         ];
     }
 
     get showSidebar(): boolean {
-        return this.hasAttribute('show-sidebar');
+        return this._state.showSidebar;
     }
 
     set showSidebar(v: boolean) {
-        if (v) this.setAttribute('show-sidebar', '');
-        else this.removeAttribute('show-sidebar');
+        // `false` has to be spelled out — absence means the libadwaita default.
+        this.setAttribute('show-sidebar', v ? '' : 'false');
     }
 
     get collapsed(): boolean {
-        return this.hasAttribute('collapsed');
+        return this._state.collapsed;
     }
 
     set collapsed(v: boolean) {
@@ -37,16 +87,23 @@ export class AdwOverlaySplitView extends HTMLElement {
         else this.removeAttribute('collapsed');
     }
 
+    // The three defaults come from the widget, not from an app's taste: 180 /
+    // 280 / 0.25 (adw-overlay-split-view.c:1036-1075). They used to be 280 /
+    // 400 / 0.30 here, which are the values the three.js and canvas2d showcases
+    // set EXPLICITLY in their `.blp` — so an app's preference had been copied
+    // into the widget. The visible cost was in the storybook, whose whole
+    // purpose is a 1:1 comparison: the GTK story takes the real defaults and the
+    // browser story took these, so the two sides showed different sidebars.
     get minSidebarWidth(): number {
-        return parseFloat(this.getAttribute('min-sidebar-width') || '280');
+        return parseFloat(this.getAttribute('min-sidebar-width') || String(DEFAULT_MIN_SIDEBAR_WIDTH));
     }
 
     get maxSidebarWidth(): number {
-        return parseFloat(this.getAttribute('max-sidebar-width') || '400');
+        return parseFloat(this.getAttribute('max-sidebar-width') || String(DEFAULT_MAX_SIDEBAR_WIDTH));
     }
 
     get sidebarWidthFraction(): number {
-        return parseFloat(this.getAttribute('sidebar-width-fraction') || '0.30');
+        return parseFloat(this.getAttribute('sidebar-width-fraction') || String(DEFAULT_SIDEBAR_WIDTH_FRACTION));
     }
 
     connectedCallback() {
@@ -83,18 +140,95 @@ export class AdwOverlaySplitView extends HTMLElement {
         this.append(this._sidebarEl, this._contentEl, this._backdropEl);
 
         // Apply initial state
+        // The attributes present at parse time ARE the construction options —
+        // `Adw.OverlaySplitView` is built with its properties, it is not built
+        // and then mutated. Applying them as sequential setters instead would
+        // fire the collapse transition and auto-hide a sidebar that the markup
+        // explicitly asked to keep shown.
+        this._state = new OverlaySplitViewState({
+            collapsed: this.hasAttribute('collapsed'),
+            showSidebar: readTriStateAttr(this, 'show-sidebar', true),
+            pinSidebar: this.hasAttribute('pin-sidebar'),
+            sidebarPosition: this.getAttribute('sidebar-position') === 'end' ? 'end' : ('start' as AdwPackType),
+        });
+        this._reflectShowSidebar();
         this._syncClasses();
         this._syncSidebarWidth();
+        this._syncBreakpoint();
+    }
+
+    disconnectedCallback() {
+        this._disposeBreakpoint?.();
+        this._disposeBreakpoint = undefined;
     }
 
     attributeChangedCallback(_name: string, _old: string | null, _val: string | null) {
         if (!this._initialized) return;
+        if (_name === 'breakpoint') {
+            this._syncBreakpoint();
+            return;
+        }
+        this._readAttribute(_name);
         this._syncClasses();
         if (_name === 'min-sidebar-width' || _name === 'max-sidebar-width' || _name === 'sidebar-width-fraction') {
             this._syncSidebarWidth();
         }
     }
 
+    /**
+     * Push ONE attribute into the state, then reflect back what the state made
+     * of it.
+     *
+     * Per-attribute rather than a re-read of all of them, because `show-sidebar`
+     * is a value the state ALSO owns: collapsing auto-hides an unpinned sidebar,
+     * and a blanket re-read would immediately clobber that decision with the
+     * stale attribute.
+     */
+    private _readAttribute(name: string) {
+        const state = this._state;
+        // `pin-sidebar` defaults FALSE (adw-overlay-split-view.c:990-992), so it
+        // is an ordinary presence attribute; `show-sidebar` below is the one that
+        // cannot be, and `sidebar-position` is an enum defaulting to 'start'.
+        if (name === 'pin-sidebar') state.setPinSidebar(this.hasAttribute('pin-sidebar'));
+        if (name === 'sidebar-position') {
+            const position = this.getAttribute('sidebar-position');
+            state.setSidebarPosition(position === 'end' ? 'end' : ('start' as AdwPackType));
+        }
+        if (name === 'show-sidebar') {
+            state.setShowSidebar(readTriStateAttr(this, 'show-sidebar', true));
+        }
+        // Last: it can change `show-sidebar`, so it must not be overwritten after.
+        if (name === 'collapsed') state.setCollapsed(this.hasAttribute('collapsed'));
+        this._reflectShowSidebar();
+    }
+
+    /**
+     * Mirror the state's `showSidebar` back onto the attribute, so the DOM keeps
+     * telling the truth after an auto-hide.
+     *
+     * Guarded: writing the attribute re-enters `attributeChangedCallback`, and
+     * without the flag that is an infinite reflection loop rather than a render.
+     */
+    private _reflectShowSidebar() {
+        if (this._reflecting) return;
+        const wanted = this._state.showSidebar ? '' : 'false';
+        if (this.getAttribute('show-sidebar') === wanted) return;
+        this._reflecting = true;
+        try {
+            this.setAttribute('show-sidebar', wanted);
+        } finally {
+            this._reflecting = false;
+        }
+    }
+
+    /** (Re)bind the `breakpoint` condition to `collapsed`. */
+    private _syncBreakpoint() {
+        this._disposeBreakpoint?.();
+        this._disposeBreakpoint = bindBreakpointSetter(this, this.getAttribute('breakpoint'), (active) => {
+            this.collapsed = active;
+        });
+    }
+
     openSidebar() {
         this.showSidebar = true;
         this.dispatchEvent(new CustomEvent('sidebar-toggled', { detail: { isVisible: true } }));
@@ -115,11 +249,18 @@ export class AdwOverlaySplitView extends HTMLElement {
     }
 
     private _syncClasses() {
-        this.classList.toggle('collapsed', this.collapsed);
-        this.classList.toggle('show-sidebar', this.showSidebar);
-        const pos = this.getAttribute('sidebar-position') || 'start';
-        this.classList.toggle('sidebar-start', pos === 'start');
-        this.classList.toggle('sidebar-end', pos === 'end');
+        const state = this._state;
+        this.classList.toggle('collapsed', state.collapsed);
+        this.classList.toggle('show-sidebar', state.showSidebar);
+        this.classList.toggle('sidebar-start', state.sidebarPosition === 'start');
+        this.classList.toggle('sidebar-end', state.sidebarPosition === 'end');
+
+        // Derived, not re-decided here: the shield only exists while collapsed
+        // AND revealed, and each pane is reachable by keyboard only when it is
+        // the one on screen.
+        if (this._backdropEl) this._backdropEl.hidden = !state.shieldVisible;
+        this._sidebarEl?.setAttribute('aria-hidden', String(!state.sidebarFocusable));
+        this._contentEl?.setAttribute('aria-hidden', String(!state.contentFocusable));
 
         // In docked mode, use negative margin to collapse sidebar space
         // while keeping the sidebar's intrinsic width (slide animation).
@@ -135,8 +276,17 @@ export class AdwOverlaySplitView extends HTMLElement {
 
     private _syncSidebarWidth() {
         if (!this._sidebarEl) return;
-        this._sidebarEl.style.minWidth = `${this.minSidebarWidth}px`;
-        this._sidebarEl.style.maxWidth = `${this.maxSidebarWidth}px`;
+        // Normalise through the core rather than writing the raw attributes:
+        // libadwaita never lets `max` fall below `min`, and CSS resolves that
+        // conflict the other way round (min-width wins over max-width), so an
+        // inverted pair would render differently here than in GTK.
+        const bounds = resolveSidebarBounds(
+            { minSidebarWidth: this.minSidebarWidth, maxSidebarWidth: this.maxSidebarWidth },
+            0,
+            { ceil: true },
+        );
+        this._sidebarEl.style.minWidth = `${bounds.min}px`;
+        this._sidebarEl.style.maxWidth = `${bounds.max}px`;
         this._sidebarEl.style.width = `${this.sidebarWidthFraction * 100}%`;
     }
 }

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