@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/elements/gtk-drawing-area.ts

@@ -0,0 +1,303 @@
+// <gtk-drawing-area> — a blank widget you draw on. It owns no painting of its own: it
+// carries a SIZE, a CALLBACK and a resize notification, and everything you can see is
+// what the callback painted.
+//
+// WHAT THE C ACTUALLY DOES, IN FOUR PLACES (gtkdrawingarea.c):
+//
+//   · `gtk_drawing_area_measure` (:210-231) returns `content_width` / `content_height`
+//     as BOTH the minimum and the natural size of the matching orientation. A zero — the
+//     default — means the widget has no intrinsic size on that axis at all, so the parent
+//     decides; a non-zero one is a floor the parent cannot allocate below, not a fixed
+//     size. `_drawing.scss` spells that pair as `width`/`min-width`.
+//   · `gtk_drawing_area_size_allocate` (:233-238) does nothing but emit `::resize` with
+//     the new width and height. That is the whole allocation path: no re-measure, no
+//     re-layout, one signal.
+//   · `gtk_drawing_area_snapshot` (:240-267) returns early WITHOUT calling the draw
+//     function when none is set, appends a cairo region the size of the allocation and
+//     calls it with `width`/`height` from the allocation, not from the properties.
+//   · `gtk_drawing_area_set_draw_func` (:474-491) runs the previous `destroy` notifier,
+//     stores the triple and calls `gtk_widget_queue_draw`, so installing a function
+//     repaints. `set_draw_func(NULL)` is therefore a documented way to blank the widget.
+//
+// THE CALLBACK. GTK's is `(area, cr, width, height, user_data)`. The `user_data` /
+// `destroy` pair is what this renderer has no use for — a JS closure holds its own
+// captures and the garbage collector is the notifier — so the browser signature drops
+// both and the element keeps the first four in the C's order. Replacing a function is a
+// plain assignment; there is no second copy to leak, which is the only thing the
+// `destroy` notifier is for.
+//
+// LOGICAL PIXELS, ONCE. The cairo region GTK hands the callback is in the widget's LOGICAL
+// size (`:248-262` — the allocation, unscaled), and GTK scales the surface at composite
+// time. A `<canvas>` is a PIXEL buffer whose `width`/`height` attributes are its backing
+// store, so the element multiplies that by the device pixel ratio and scales the 2D
+// context by the same factor before calling in. The callback still draws in logical
+// pixels, which is the property an application port depends on.
+//
+// EACH FRAME STARTS EMPTY. GTK's renderer builds every frame into a fresh surface, so a
+// draw function that paints a background covers what was there; a canvas keeps its pixels
+// between frames, so the element clears the allocation before calling in. Without that a
+// second frame would composite over the first — the one difference a naive port shows and
+// the reason this is written down rather than left to the reader.
+//
+// A11Y: no role, and none invented. GtkDrawingArea is a blank widget with no accessible
+// role of its own, so naming one would add an interface GTK does not have. A drawing
+// area that shows text owes the screen reader a label from the application, which an
+// ordinary `aria-label` on the element already does.
+//
+// Events: `resize` (CustomEvent, bubbles, detail `{ width, height }` — GtkDrawingArea's
+// own signal, gtkdrawingarea.c:311-328) on the first allocation and every change of one,
+// and `notify::<prop>` (CustomEvent, bubbles, detail `{ <prop>: value }`) on a real change.
+//
+// Reference: refs/gtk/gtk/gtkdrawingarea.c
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { glibClamp } from '@gjsify/adwaita-core';
+
+/**
+ * `GtkDrawingAreaDrawFunc` with the `user_data` / `destroy` pair dropped — see the header.
+ *
+ * @param area the drawing area being painted, as the C's first argument
+ * @param cr a 2D context over the whole allocation, in logical pixels
+ * @param width the width of the allocation — NOT of `content-width`
+ * @param height the height of the allocation — NOT of `content-height`
+ */
+export type GtkDrawingAreaDrawFunc = (
+    area: GtkDrawingArea,
+    cr: CanvasRenderingContext2D,
+    width: number,
+    height: number,
+) => void;
+
+/** `G_MAXINT`, the top of `g_param_spec_int`'s range (:288-304). */
+const MAX_INT = 2147483647;
+
+/** A missing or unparseable attribute is `0`, which is also the GIR default. */
+function intAttribute(element: HTMLElement, name: string): number {
+    const raw = Number.parseInt(element.getAttribute(name) ?? '', 10);
+    return Number.isFinite(raw) ? raw : 0;
+}
+
+export class GtkDrawingArea extends HTMLElement {
+    private _canvas!: HTMLCanvasElement;
+    private _context: CanvasRenderingContext2D | null = null;
+    private _initialized = false;
+    private _drawFunc: GtkDrawingAreaDrawFunc | null = null;
+    /** The last allocation the draw function was called with, as `::resize` sees it. */
+    private _width = -1;
+    private _height = -1;
+    /** The last device pixel ratio the backing store was built for. */
+    private _scale = 1;
+    private _resize: ResizeObserver | null = null;
+    private _frame: number | null = null;
+
+    static get observedAttributes() {
+        return ['content-width', 'content-height'];
+    }
+
+    /** `Gtk.DrawingArea:content-width` — the minimum AND natural width. Defaults to 0. */
+    get contentWidth(): number {
+        return intAttribute(this, 'content-width');
+    }
+
+    set contentWidth(v: number) {
+        // The pspec range is 0…G_MAXINT (:290-294), so a write outside it is clamped
+        // rather than refused — which is what `set_property` does with the value.
+        this._write('content-width', String(glibClamp(Math.trunc(v) || 0, 0, MAX_INT)));
+    }
+
+    /** `Gtk.DrawingArea:content-height` — the minimum AND natural height. Defaults to 0. */
+    get contentHeight(): number {
+        return intAttribute(this, 'content-height');
+    }
+
+    set contentHeight(v: number) {
+        this._write('content-height', String(glibClamp(Math.trunc(v) || 0, 0, MAX_INT)));
+    }
+
+    /**
+     * Every GObject setter here returns early when the value is already right
+     * (gtkdrawingarea.c:373, :423), while `setAttribute` runs the reaction for a write
+     * that changes nothing — so the guard that makes "notify only on a real change" true
+     * for the numeric half is the same one `<gtk-level-bar>` uses.
+     */
+    private _write(name: string, value: string): void {
+        if (this.getAttribute(name) !== value) this.setAttribute(name, value);
+    }
+
+    /** `GtkDrawingAreaDrawFunc`, or `null` — GTK's default, which paints nothing (:251). */
+    get drawFunc(): GtkDrawingAreaDrawFunc | null {
+        return this._drawFunc;
+    }
+
+    set drawFunc(fn: GtkDrawingAreaDrawFunc | null) {
+        this.setDrawFunc(fn);
+    }
+
+    /**
+     * `gtk_drawing_area_set_draw_func` (gtkdrawingarea.c:474-491): store the function and
+     * `queue_draw`, which is what repaints. Passing `null` clears it, and the next
+     * snapshot leaves the widget blank — the C's early return at :251.
+     */
+    setDrawFunc(fn: GtkDrawingAreaDrawFunc | null): void {
+        this._drawFunc = fn;
+        this.queueDraw();
+    }
+
+    /**
+     * `gtk_widget_queue_draw` on this widget: the documented way to ask for the draw
+     * function to be called again (gtkdrawingarea.c:127-129).
+     *
+     * AND WHY IT IS NOT IMMEDIATE. `queue_draw` marks the window dirty and the frame clock
+     * draws it on the next frame, so a draw function that calls `queue_draw` keeps
+     * ANIMATING rather than recursing — and a 2D canvas drawn synchronously would turn the
+     * same application into a stack overflow. One animation frame is the browser's frame
+     * clock, and coalescing through it is what makes "paint from the function" a loop and
+     * not a crash. Several requests before the frame are one frame, as in the C.
+     */
+    queueDraw(): void {
+        if (!this._initialized || this._frame !== null) return;
+        this._frame = requestAnimationFrame(() => {
+            this._frame = null;
+            this._draw();
+        });
+    }
+
+    connectedCallback() {
+        if (this._initialized) {
+            // The teardown below released the observer on the way out, so a re-parent has
+            // to arm it again — see `scripts/check-adwaita-connect-rebind.mjs`.
+            this._observe();
+            return;
+        }
+        this._initialized = true;
+
+        this._canvas = document.createElement('canvas');
+        this._canvas.className = 'adw-drawing-area-canvas';
+        this._context = this._canvas.getContext('2d');
+        this.replaceChildren(this._canvas);
+        this._publishSize();
+        this._observe();
+    }
+
+    disconnectedCallback() {
+        this._resize?.disconnect();
+        this._resize = null;
+        if (this._frame !== null) cancelAnimationFrame(this._frame);
+        this._frame = null;
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        // A size property is a REQUEST, not a repaint: it changes the element's own box,
+        // the observer hears the allocation that follows, and the paint is redone then.
+        // `notify` fires either way, and the custom property the partial reads is
+        // republished first so the CSS floor moves with the property.
+        if (name === 'content-width' || name === 'content-height') this._publishSize();
+        this._notify(name);
+        if (name === 'content-width' || name === 'content-height') this.queueDraw();
+    }
+
+    /**
+     * `measure` returns one number per axis as the minimum AND the natural size
+     * (gtkdrawingarea.c:210-231), and CSS has a property for each half — so the element
+     * publishes the number once and `_drawing.scss` reads it twice. A zero removes the
+     * property rather than declaring `0px`, because `var(--adw-drawing-width, auto)` is
+     * how "no intrinsic size" is spelled.
+     */
+    private _publishSize(): void {
+        const size: [string, number][] = [
+            ['--adw-drawing-width', this.contentWidth],
+            ['--adw-drawing-height', this.contentHeight],
+        ];
+        for (const [property, value] of size) {
+            if (value > 0) this.style.setProperty(property, `${value}px`);
+            else this.style.removeProperty(property);
+        }
+    }
+
+    private _observe(): void {
+        if (this._resize) return;
+        // ResizeObserver delivers an initial observation on observe(), so the first draw
+        // lands without a separate seeding pass — the `::resize` signal GTK emits "once
+        // when the widget is realized" (:312-313).
+        this._resize = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const box = entry.borderBoxSize?.[0];
+                this._allocated(
+                    box ? box.inlineSize : entry.contentRect.width,
+                    box ? box.blockSize : entry.contentRect.height,
+                );
+            }
+        });
+        this._resize.observe(this);
+    }
+
+    /**
+     * `gtk_drawing_area_size_allocate` (:233-238) emits `::resize` and does nothing else —
+     * the signal IS the allocation path. The browser learns the allocation from the
+     * observer instead, so the signal is emitted from here, and only when the allocation
+     * really changed: GTK reaches `size_allocate` on every layout pass, and the signal
+     * is documented as firing "each time the widget is changed" (:312-314).
+     */
+    private _allocated(width: number, height: number): void {
+        const changed = width !== this._width || height !== this._height;
+        this._width = width;
+        this._height = height;
+        if (changed) {
+            this.dispatchEvent(new CustomEvent('resize', { bubbles: true, detail: { width, height } }));
+        }
+        this._draw();
+    }
+
+    /**
+     * One frame. `gtk_drawing_area_snapshot` (:240-267) measures the ALLOCATION, not the
+     * properties, and calls the function with it; the browser gets the allocation from the
+     * observer instead of from the snapshot, and the drawing itself is the 2D context the
+     * canvas already owns.
+     */
+    private _draw(): void {
+        if (!this._canvas || this._width < 0) return;
+        const width = this._width;
+        const height = this._height;
+        // The cairo region is the allocation unscaled (:248-262); the backing store is the
+        // same size in device pixels, and the context carries the ratio.
+        const scale = this._devicePixelRatio();
+        const pixelWidth = Math.round(width * scale);
+        const pixelHeight = Math.round(height * scale);
+        if (this._canvas.width !== pixelWidth) this._canvas.width = pixelWidth;
+        if (this._canvas.height !== pixelHeight) this._canvas.height = pixelHeight;
+        this._scale = scale;
+
+        const context = this._context;
+        if (!context) return;
+        // `setTransform` rather than `scale`, so a second frame does not compound the ratio.
+        context.setTransform(scale, 0, 0, scale, 0, 0);
+        // A fresh surface per frame, as GTK's renderer gives the callback.
+        context.clearRect(0, 0, width, height);
+
+        if (this._drawFunc) this._drawFunc(this, context, width, height);
+    }
+
+    /** The backing store is rebuilt when the display's ratio changes, not every frame. */
+    private _devicePixelRatio(): number {
+        return typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1;
+    }
+
+    /** The `notify::` detail for `name`: the PROPERTY, parsed, not the raw attribute. */
+    private _notify(name: string): void {
+        const value = name === 'content-width' ? this.contentWidth : this.contentHeight;
+        this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: value } }));
+    }
+
+    /** The last allocation, as `::resize` reported it — the spec reads it back. */
+    get allocation(): { width: number; height: number } {
+        return { width: this._width, height: this._height };
+    }
+
+    /** The ratio the backing store was built at, as the header describes. */
+    get pixelScale(): number {
+        return this._scale;
+    }
+}
+customElements.define('gtk-drawing-area', GtkDrawingArea);

package/src/elements/gtk-editable-label.ts

@@ -0,0 +1,204 @@
+// <gtk-editable-label> — `GtkEditableLabel`, a label you click and edit in place.
+//
+// IT IS A STACK, NOT A FIELD. The C builds `stack > { label, entry }`, puts a
+// `Gtk.Text` in the entry slot, and `editing` IS "the entry is the stack's visible child"
+// (gtkeditablelabel.c:319-331,595-599). Two elements therefore stand for one widget, and
+// which of them shows is the whole of its state — `.editing` on the host is the class the
+// C adds and removes around every transition (gtkeditablelabel.c:609-663), and it is what
+// libadwaita's `editablelabel > stack > text` selector keys on.
+//
+// THE KEYS ARE THE BEHAVIOUR. Enter on the label starts editing; Enter in the entry COMMITS
+// (the drafted text becomes the label's); Escape in the entry DISCARDS it (the entry is
+// reset to what the label says, gtkeditablelabel.c:637-656). A click on the label starts
+// editing — the gesture is on the LABEL, not on the widget (gtkeditablelabel.c:193-215,
+// 351-353) — and focus leaving the widget commits after the C's 100 ms grace period, which
+// exists so a focus move INSIDE the widget is not read as leaving
+// (gtkeditablelabel.c:293-318). `editable` FALSE stops editing without committing and
+// refuses to start it (gtkeditablelabel.c:414-427).
+//
+// `text` is `Gtk.Editable:text`, what the label shows. While the entry is visible it holds a
+// DRAFT, which is why the C syncs the label from `notify::text` only while it is not
+// editing (gtkeditablelabel.c:237-248) and why a discarded edit resets the entry rather
+// than the label.
+//
+// A11y: GTK declares no role for this widget (`gtkeditablelabel.c` calls no
+// `set_accessible_role`) and makes it focusable (gtkeditablelabel.c:320), so the host owns
+// the tab stop while it shows the label and the entry holds it while it edits.
+//
+// NOT PORTED, one line each, declared in `check-adwaita-element-properties.mjs`: the
+// drag-and-drop target and source (GTK drops a string onto the label and drags its text out,
+// gtkeditablelabel.c:250-291), the context menu (a `Gtk.PopoverMenu` over a right click,
+// gtkeditablelabel.c:145-190) and `Gtk.Editable`'s undo stack (`enable-undo`, which no
+// attribute can carry and a native input does not expose).
+//
+// Reference: refs/gtk/gtk/gtkeditablelabel.c:40-95 (the node tree and the keys),
+//   193-215,237-248,293-331,414-427,609-663 (gesture, text sync, focus grace, editable,
+//   start/stop editing)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_labels.scss:1-11,90-97
+//   (`label {}`, `editablelabel > stack > text`)
+// Copyright (c) The GTK Team, GNOME contributors. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+/** The C's grace period between a focus leaving the widget and the commit it triggers. */
+const FOCUS_OUT_GRACE_MS = 100;
+
+export class GtkEditableLabel extends HTMLElement {
+    private _label!: HTMLSpanElement;
+    private _entry!: HTMLInputElement;
+    private _initialized = false;
+    private _grace: ReturnType<typeof setTimeout> | null = null;
+
+    static get observedAttributes() {
+        return ['text', 'editable', 'editing'];
+    }
+
+    /** `Gtk.Editable:text` — what the label shows, which is the committed draft. */
+    get text(): string {
+        return this.getAttribute('text') ?? '';
+    }
+
+    set text(value: string) {
+        this.setAttribute('text', value ?? '');
+    }
+
+    /** `Gtk.Editable:editable` — defaults TRUE. FALSE refuses to start editing. */
+    get editable(): boolean {
+        const raw = this.getAttribute('editable');
+        return raw === null ? true : raw !== 'false';
+    }
+
+    set editable(value: boolean) {
+        if (value) this.removeAttribute('editable');
+        else this.setAttribute('editable', 'false');
+    }
+
+    /**
+     * `GtkEditableLabel:editing` — TRUE while the entry is the stack's visible child, so it
+     * is the ATTRIBUTE as on every other boolean here. Setting it is what starts or stops
+     * editing, because the C's property setter does exactly that (gtkeditablelabel.c:406-411).
+     */
+    get editing(): boolean {
+        return this.hasAttribute('editing');
+    }
+
+    set editing(value: boolean) {
+        this.toggleAttribute('editing', !!value);
+    }
+
+    /** `gtk_editable_label_start_editing` — refused while `editable` is FALSE, as in the C. */
+    startEditing(): void {
+        if (!this.editable) return;
+        this.editing = true;
+    }
+
+    /**
+     * `gtk_editable_label_stop_editing` — `commit` decides whether the drafted text becomes
+     * the label's; FALSE resets the entry to the label instead (gtkeditablelabel.c:637-656).
+     */
+    stopEditing(commit = false): void {
+        if (!this.editing) return;
+        if (commit) this.setAttribute('text', this._entry.value);
+        this.editing = false;
+    }
+
+    /** The inner native entry, for focus and selection. */
+    get entry(): HTMLInputElement {
+        return this._entry;
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this._label = document.createElement('span');
+        this._label.className = 'adw-editable-label-label';
+        this._label.addEventListener('click', () => this.startEditing());
+
+        this._entry = document.createElement('input');
+        this._entry.className = 'adw-editable-label-entry';
+        this._entry.type = 'text';
+        // The C moves focus onto the entry to start editing and back onto the widget to stop
+        // (gtkeditablelabel.c:614,652), so the host is the tab stop only while it shows the
+        // label — otherwise a Tab would walk through two controls for one widget.
+        this._entry.tabIndex = -1;
+        this._entry.addEventListener('keydown', (event) => {
+            if (event.key === 'Enter') {
+                event.preventDefault();
+                // Consumed here: Enter in the entry is its `activate` signal
+                // (gtkeditablelabel.c:232-234), and letting it reach the widget would start
+                // editing again the moment the commit stopped it.
+                event.stopPropagation();
+                this.stopEditing(true);
+            } else if (event.key === 'Escape') {
+                event.preventDefault();
+                event.stopPropagation();
+                this.stopEditing(false);
+            }
+        });
+
+        this.replaceChildren(this._label, this._entry);
+        // Enter and Space start editing as a KEY BINDING of the WIDGET, not of the label node
+        // inside it (gtkeditablelabel.c:54-63), so the listener is on the host.
+        this.addEventListener('keydown', (event) => {
+            if (this.editing || (event.key !== 'Enter' && event.key !== ' ')) return;
+            event.preventDefault();
+            this.startEditing();
+        });
+        // Leaving the WIDGET is what commits, not leaving the entry, and the C waits out its
+        // grace period first so a focus move WITHIN the widget is not read as leaving it.
+        this.addEventListener('focusout', (event) => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && this.contains(next)) return;
+            if (this._grace !== null) clearTimeout(this._grace);
+            this._grace = setTimeout(() => {
+                this._grace = null;
+                if (this.editing) this.stopEditing(true);
+            }, FOCUS_OUT_GRACE_MS);
+        });
+
+        this._render();
+    }
+
+    disconnectedCallback() {
+        if (this._grace !== null) clearTimeout(this._grace);
+        this._grace = null;
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        switch (name) {
+            case 'text':
+                // The label's text only follows the property while nothing is being drafted,
+                // which is the condition `text_changed` tests in the C.
+                if (!this.editing) this._render();
+                break;
+            case 'editable':
+                if (value === 'false') this.stopEditing(false);
+                break;
+            case 'editing':
+                this._render();
+                if (this.editing) this._entry.focus();
+                else this.focus();
+                this.dispatchEvent(
+                    new CustomEvent('notify::editing', { bubbles: true, detail: { editing: this.editing } }),
+                );
+                break;
+        }
+    }
+
+    private _render(): void {
+        const editing = this.editing;
+        this.classList.toggle('editing', editing);
+        this._label.hidden = editing;
+        this._entry.hidden = !editing;
+        this._label.textContent = this.text;
+        this._entry.value = this.text;
+        // The tab stop FOLLOWS the state: the widget is focusable while it shows the label
+        // and hands the focus to the entry while it edits (gtkeditablelabel.c:614,652), so
+        // a Tab never reaches a control the user cannot see.
+        if (editing) this.removeAttribute('tabindex');
+        else this.setAttribute('tabindex', '0');
+    }
+}
+
+customElements.define('gtk-editable-label', GtkEditableLabel);