@gjsify/adwaita-web 0.54.0 → 0.56.0

package/src/elements/gtk-search-bar.ts

@@ -0,0 +1,200 @@
+// <gtk-search-bar> — `Gtk.SearchBar`, the strip that reveals a search entry when search starts.
+//
+// IT IS A REVEALER, AND THE PROPERTY IS THE REVEALER'S. `GtkSearchBar` is
+// `searchbar > revealer > box > { child, button.close }` (gtksearchbar.c:66-81,368-390), and
+// `search-mode-enabled` IS `reveal-child` on that revealer (gtksearchbar.c:512-517,183-205)
+// — the C's own getter reads the revealer, not a flag. So one attribute decides both whether
+// the strip is shown and whether the search is on, which is what makes the element's state
+// a single boolean.
+//
+// WHAT TURNS IT ON, all four from the C: `search-mode-enabled` set by the application
+// (:512-517), typing into the connected editable (`input-intercepted`, :210-218), Escape on
+// a search entry (`stop-search`, :174-177) and the close button (:207-209). TWO things turn
+// it off, and the second is the C's own rule: hiding clears the entry's text
+// (`reveal_child_changed_cb`, :183-205), so a search that is dismissed leaves nothing behind.
+//
+// THE ENTRY IS THE CHILD, AND THE C IS EXPLICIT ABOUT WHICH KINDS. `connect_entry` takes any
+// `GtkEditable`, and `reveal_child_changed_cb` branches three ways: a `GtkEntry` is focused
+// without selecting, a `GtkSearchEntry` is focused outright, and anything else is only
+// cleared. A `searchbar` element therefore takes an ordinary editable child — a
+// `<gtk-search-entry>` when the port has one, a `<gtk-entry>` today — and focuses it.
+//
+// `key-capture-widget` is a WIDGET, so it is not an attribute: `keyCaptureWidget` is a
+// property, and the element listens on that element in the CAPTURE phase, which is the one
+// door GTK opens too ("the events are only 'captured' in the bubble phase",
+// gtksearchbar.c:525-540). A printable key then goes into the entry, which is what the C's
+// forward does ("the bar will be shown, and the entry populated with the entered text").
+//
+// A11y: `Gtk.SearchBar` uses `AccessibleRole.search` (gtksearchbar.c:390), so the host says
+// so. A collapsed strip is `inert`, which is the CSS-shaped form of GTK not mapping the
+// revealer's child at all (:368-390) — without it the entry would stay in the tab order of a
+// bar nobody can see.
+//
+// Reference: refs/gtk/gtk/gtksearchbar.c:66-81 (the node tree and the role), 174-218 (the
+//   four ways search starts and the two it stops), 237-390 (the pspecs, the revealer, the
+//   close button), 512-556 (search mode, close button, key capture)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_toolbars.scss:113-185 (searchbar)
+// Copyright (c) The GTK Team, GNOME contributors. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+export class GtkSearchBar extends HTMLElement {
+    private _box!: HTMLDivElement;
+    private _center!: HTMLDivElement;
+    private _close!: HTMLButtonElement;
+    private _initialized = false;
+    private _capture: HTMLElement | null = null;
+    private readonly _onCapturedKey = (event: KeyboardEvent): void => this._captureKey(event);
+    private readonly _onInput = (): void => this._revealFromTyping();
+
+    static get observedAttributes() {
+        return ['search-mode-enabled', 'show-close-button'];
+    }
+
+    /** `Gtk.SearchBar:search-mode-enabled` — the revealer's `reveal-child`. Defaults FALSE. */
+    get searchModeEnabled(): boolean {
+        return this.hasAttribute('search-mode-enabled');
+    }
+
+    set searchModeEnabled(value: boolean) {
+        this.toggleAttribute('search-mode-enabled', !!value);
+    }
+
+    /** `Gtk.SearchBar:show-close-button` — the `.close` button at the end of the box. */
+    get showCloseButton(): boolean {
+        return this.hasAttribute('show-close-button');
+    }
+
+    set showCloseButton(value: boolean) {
+        this.toggleAttribute('show-close-button', !!value);
+    }
+
+    /** `Gtk.SearchBar:key-capture-widget` — where printable keys start a search. */
+    get keyCaptureWidget(): HTMLElement | null {
+        return this._capture;
+    }
+
+    set keyCaptureWidget(widget: HTMLElement | null) {
+        if (this._capture === widget) return;
+        this._capture?.removeEventListener('keydown', this._onCapturedKey, true);
+        this._capture = widget;
+        this._capture?.addEventListener('keydown', this._onCapturedKey, true);
+    }
+
+    /** The editable the C's `connect_entry` would have bound: the first field inside the bar. */
+    get entry(): HTMLInputElement | HTMLTextAreaElement | null {
+        return this.querySelector<HTMLInputElement | HTMLTextAreaElement>('input, textarea');
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this.setAttribute('role', 'search');
+
+        this._center = document.createElement('div');
+        this._center.className = 'adw-search-bar-center';
+        // Whatever the author put inside the bar is the child, moved into the box's centre —
+        // the `GtkCenterBox` the C builds around it (gtksearchbar.c:378-386).
+        this._center.append(...this.childNodes);
+
+        this._close = document.createElement('button');
+        this._close.className = 'adw-search-bar-close';
+        this._close.type = 'button';
+        this._close.setAttribute('aria-label', 'Close search');
+        this._close.addEventListener('click', () => (this.searchModeEnabled = false));
+
+        this._box = document.createElement('div');
+        this._box.className = 'adw-search-bar-box';
+        this._box.append(this._center, this._close);
+        this.replaceChildren(this._box);
+
+        // `input-intercepted`: typing into the connected editable reveals the bar
+        // (gtksearchbar.c:210-218). Captured, because the editable may be nested two
+        // elements deep — a `<gtk-entry>` keeps its own `<input>`.
+        this.addEventListener('input', this._onInput);
+        this.addEventListener('keydown', (event) => {
+            if (event.key === 'Escape') this.searchModeEnabled = false;
+        });
+
+        this._render();
+    }
+
+    disconnectedCallback() {
+        this.keyCaptureWidget = null;
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, _value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'search-mode-enabled') {
+            this._applyReveal();
+            this.dispatchEvent(
+                new CustomEvent('notify::search-mode-enabled', {
+                    bubbles: true,
+                    detail: { searchModeEnabled: this.searchModeEnabled },
+                }),
+            );
+            return;
+        }
+        if (name === 'show-close-button') {
+            // The C notifies only when the button's visibility ACTUALLY changed
+            // (gtksearchbar.c:526-530), and `toggleAttribute` is idempotent, so an unchanged
+            // value never reaches here.
+            this._render();
+            this.dispatchEvent(
+                new CustomEvent('notify::show-close-button', {
+                    bubbles: true,
+                    detail: { showCloseButton: this.showCloseButton },
+                }),
+            );
+        }
+    }
+
+    private _render(): void {
+        const revealed = this.searchModeEnabled;
+        this.classList.toggle('revealed', revealed);
+        // A collapsed revealer's child is not mapped in GTK, so it is not focusable there
+        // either; `inert` is what says that without taking the strip out of the layout.
+        this._box.inert = !revealed;
+        this._close.hidden = !this.showCloseButton;
+    }
+
+    /**
+     * `reveal_child_changed_cb` (gtksearchbar.c:183-205): revealing focuses the entry,
+     * hiding clears it. Run on a real CHANGE only — at init the C's own notify fires before
+     * the handler is connected, so a child that arrives with the bar is left alone.
+     */
+    private _applyReveal(): void {
+        this._render();
+        const entry = this.entry;
+        if (entry === null) return;
+        if (this.searchModeEnabled) entry.focus();
+        else entry.value = '';
+    }
+
+    private _revealFromTyping(): void {
+        if (this.searchModeEnabled) return;
+        this.searchModeEnabled = true;
+        this.entry?.focus();
+    }
+
+    /**
+     * The key-capture path (gtksearchbar.c:525-556): a printable key on the capture widget
+     * opens the bar and goes into the entry, which is what forwarding the event does in the C.
+     * Modified keys and the functional keys are left alone — GTK forwards them, but a bar
+     * that opened on every arrow key would not be a search bar.
+     */
+    private _captureKey(event: KeyboardEvent): void {
+        if (event.defaultPrevented || event.ctrlKey || event.altKey || event.metaKey) return;
+        if (event.key.length !== 1) return;
+        const entry = this.entry;
+        this.searchModeEnabled = true;
+        if (entry === null) return;
+        event.preventDefault();
+        entry.focus();
+        const start = entry.selectionStart ?? entry.value.length;
+        const end = entry.selectionEnd ?? start;
+        entry.setRangeText(event.key, start, end, 'end');
+    }
+}
+
+customElements.define('gtk-search-bar', GtkSearchBar);

package/src/elements/gtk-search-entry.ts

@@ -0,0 +1,172 @@
+// <gtk-search-entry> — a field for typing a query: a magnifying-glass leading while it is
+// empty, a clear button trailing once it is not, and a signal that waits until the user
+// STOPS typing.
+//
+// THE DELAY IS THE POINT, and it is a property: `search-delay` is 150 ms by default
+// (gtksearchentry.c:539-542, and `gtk_search_entry_init` sets the same, :847) and
+// `search-changed` fires once it has elapsed. C's `gtk_search_entry_changed` has one
+// asymmetry that is easy to lose — going EMPTY fires IMMEDIATELY and cancels any pending
+// timeout (:785-792), because an empty query is not a filter and waiting would make the
+// results flash. Only a non-empty change is queued, and each keystroke REPLACES the queue
+// (`reset_timeout`, :765-774).
+//
+// `Gtk.SearchEntry` is not a `Gtk.Entry` in C either (a sibling implementing `GtkEditable`),
+// and it EXTENDS `<gtk-entry>` here for the same reason `<gtk-password-entry>` does: the
+// browser has one `<input>` and `GtkEntry` owns it.
+//
+// KEYS: <kbd>Enter</kbd> is `activate`, <kbd>Escape</kbd> is `stop-search`,
+// <kbd>Ctrl</kbd>+<kbd>g</kbd> is `next-match` and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>g</kbd>
+// is `previous-match` — C's own default bindings (gtksearchentry.c:687-701). They are
+// keybinding SIGNALS, so they are dispatched as events for a host to handle rather than
+// acted on here.
+//
+// NOT PORTED: `key-capture-widget` (a `Gtk.Widget`, so a slot rather than an attribute, and
+// only meaningful inside a `Gtk.SearchBar` this renderer has no concept of);
+// `input-purpose` / `input-hints` / `activates-default` are in `KNOWN_GAPS`.
+//
+// A11Y: `Gtk.AccessibleRole.search_box` (gtksearchentry.c:704) is `role="searchbox"`.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_entries.scss:1-96 (entry.search)
+// Reference: refs/gtk/gtk/gtksearchentry.c (properties, signals, bindings, changed, init)
+// Copyright (c) GNOME contributors (libadwaita, GTK). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { createGtkImage, type GtkImage } from './gtk-image.js';
+
+import { GtkEntry } from './gtk-entry.js';
+
+/** `GtkSearchEntry:search-delay`'s default, in ms (gtksearchentry.c:539-542). */
+const DEFAULT_SEARCH_DELAY = 150;
+
+export class GtkSearchEntry extends GtkEntry {
+    private _searchIcon!: GtkImage;
+    private _clear!: HTMLButtonElement;
+    private _clearIcon!: GtkImage;
+    private _timeout: number | null = null;
+
+    static get observedAttributes(): string[] {
+        return [...GtkEntry.observedAttributes, 'search-delay'];
+    }
+
+    /** `GtkSearchEntry:search-delay` — ms from the last keypress to `search-changed`. */
+    get searchDelay(): number {
+        const declared = Number.parseInt(this.getAttribute('search-delay') ?? '', 10);
+        return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_SEARCH_DELAY;
+    }
+
+    set searchDelay(value: number) {
+        this.setAttribute('search-delay', String(value));
+    }
+
+    /** Whether there is text, which is what decides the two icons. */
+    private get _empty(): boolean {
+        return this._input ? this._input.value === '' : this.getAttribute('value') === '';
+    }
+
+    override connectedCallback(): void {
+        super.connectedCallback();
+
+        // C's `gtk_search_entry_init` search icon: presentational, always leading.
+        this._searchIcon = createGtkImage('system-search-symbolic', 'adw-search-entry-icon');
+
+        // `gtk_icon_release` empties the field (gtksearchentry.c:747-752).
+        this._clear = document.createElement('button');
+        this._clear.type = 'button';
+        this._clear.className = 'adw-button flat circular icon-only adw-search-entry-clear';
+        this._clearIcon = createGtkImage('edit-clear-symbolic', 'adw-search-entry-clear-icon');
+        this._clear.append(this._clearIcon);
+        this._clear.title = 'Clear Entry';
+        this._clear.setAttribute('aria-label', 'Clear Entry');
+        this._clear.addEventListener('click', () => {
+            this._input.value = '';
+            this._onChanged();
+            this._input.focus();
+        });
+        this._clear.addEventListener('mousedown', (event) => event.preventDefault());
+
+        this.replaceChildren(this._searchIcon, this._input, this._clear);
+        this.setAttribute('role', 'searchbox');
+
+        this._input.addEventListener('input', () => this._onChanged());
+        this._input.addEventListener('keydown', (event) => this._onKeyDown(event));
+        this._render();
+    }
+
+    override attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void {
+        super.attributeChangedCallback(name, oldValue, value);
+        // A pending timeout belongs to the delay that is being replaced: C's setter only
+        // notifies, and the NEXT change queues against the new one — but a timeout armed
+        // under the old delay must not fire on the new one, so it is dropped here.
+        if (name === 'search-delay' && this._clear) this._cancel();
+    }
+
+    override disconnectedCallback(): void {
+        this._cancel();
+        super.disconnectedCallback();
+    }
+
+    /**
+     * `gtk_search_entry_changed` (gtksearchentry.c:776-803) over `reset_timeout`.
+     *
+     * Empty is immediate and cancels; non-empty replaces the queue. `clearTimeout` before
+     * arming is `reset_timeout`'s `g_source_remove`, and without it two keystrokes would
+     * fire the signal twice.
+     */
+    private _onChanged(): void {
+        this._cancel();
+        if (this._empty) {
+            this._render();
+            this.dispatchEvent(new CustomEvent('search-changed', { bubbles: true, detail: { value: '' } }));
+            return;
+        }
+        this._render();
+        const delay = this.searchDelay;
+        // `g_timeout_add (0, …)` is an idle, not a no-op: it runs on the next iteration of
+        // the main loop, which is one turn of the event loop and not "immediately".
+        this._timeout = window.setTimeout(() => {
+            this._timeout = null;
+            this.dispatchEvent(
+                new CustomEvent('search-changed', { bubbles: true, detail: { value: this._input.value } }),
+            );
+        }, delay);
+    }
+
+    private _cancel(): void {
+        if (this._timeout === null) return;
+        clearTimeout(this._timeout);
+        this._timeout = null;
+    }
+
+    private _onKeyDown(event: KeyboardEvent): void {
+        switch (event.key) {
+            // `activate` is NOT handled here: `<gtk-entry>` already dispatches it on Enter,
+            // and C binds the same `activate` SIGNAL the inner `Gtk.Text` raises
+            // (activate_cb, gtksearchentry.c:816-821) — one signal, one dispatch.
+            case 'Escape':
+                event.preventDefault();
+                this.dispatchEvent(new CustomEvent('stop-search', { bubbles: true }));
+                break;
+            case 'g':
+                // C binds these on Apple to Meta and elsewhere to Control
+                // (gtksearchentry.c:678-696); a browser reports neither as `ctrlKey` on
+                // macOS, so both are accepted and the host decides which one it meant.
+                if (!event.ctrlKey && !event.metaKey) return;
+                event.preventDefault();
+                this.dispatchEvent(
+                    new CustomEvent(event.shiftKey ? 'previous-match' : 'next-match', { bubbles: true }),
+                );
+                break;
+            default:
+                return;
+        }
+    }
+
+    private _render(): void {
+        if (!this._clear) return;
+        // C toggles the CLEAR icon's visibility on the text; the search icon is always
+        // present and purely presentational.
+        this._clear.hidden = this._empty;
+    }
+}
+
+customElements.define('gtk-search-entry', GtkSearchEntry);

package/src/elements/gtk-separator.ts

@@ -0,0 +1,52 @@
+// <gtk-separator> — a one-pixel rule between two groups of widgets.
+//
+// ONE property, `orientation`, which is `GtkOrientable`'s: `horizontal` (the default) draws a
+// line that runs ACROSS, `vertical` one that runs DOWN. Parsed by the same
+// `normalizeBoxOrientation` as `<gtk-box>`, because both read one GtkOrientable property and
+// an unknown value means the default in both.
+//
+// The element carries the orientation twice, as GTK does: the attribute is the property, and
+// a `horizontal` / `vertical` CLASS on the host is the CSS state `separator.spacer.horizontal`
+// selects on (`_separator.scss`). `.spacer` is libadwaita's style class for a gap that draws
+// nothing, so it is the author's to set (`class="spacer"`, a `.blp`'s `styles ["spacer"]`).
+//
+// A11Y: `role="separator"` with `aria-orientation`, GtkSeparator's own role.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_misc.scss (separator)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { normalizeBoxOrientation, type BoxOrientation } from '@gjsify/adwaita-core';
+
+export class GtkSeparator extends HTMLElement {
+    static get observedAttributes() {
+        return ['orientation'];
+    }
+
+    /** `GtkOrientable:orientation` — `horizontal` (the default) or `vertical`. */
+    get orientation(): BoxOrientation {
+        return normalizeBoxOrientation(this.getAttribute('orientation'));
+    }
+
+    set orientation(value: BoxOrientation) {
+        this.setAttribute('orientation', value);
+    }
+
+    connectedCallback() {
+        this.setAttribute('role', 'separator');
+        this._render();
+    }
+
+    attributeChangedCallback() {
+        if (this.isConnected) this._render();
+    }
+
+    private _render(): void {
+        const orientation = this.orientation;
+        this.classList.toggle('horizontal', orientation === 'horizontal');
+        this.classList.toggle('vertical', orientation === 'vertical');
+        this.setAttribute('aria-orientation', orientation);
+    }
+}
+
+customElements.define('gtk-separator', GtkSeparator);