@gjsify/adwaita-web 0.54.0 → 0.56.0

package/src/elements/gtk-switch.ts

@@ -4,19 +4,28 @@
 // The styles are the UNSCOPED `scss/_switch.scss`, so `.adw-switch` exists outside a
 // switch row and `<adw-expander-row>` can reuse it instead of copying the block.
 //
-// NO CORE STATE MACHINE. The state is one boolean with no derivation, no ordering and no
-// notify subtlety beyond "on change" — ADR 0004 is explicit that trivial behaviour gets
-// no core class, and the `active` ATTRIBUTE is the state (`toggleAttribute` is idempotent,
-// so "notify only on a real change" needs no guard). `GtkSwitch` does carry a two-phase
-// `active`/`state` pair for async toggles, but `refs/gtk` is an uninitialized submodule
-// here so that is unverifiable, and neither this port nor
-// `@gjsify/adwaita-nativescript` models it. The notify rule that IS derived from C lives
-// in the ROW's `SwitchRowState`.
+// NO CORE STATE MACHINE. The state is two booleans with no derivation, no ordering and
+// no notify subtlety beyond "on change" — ADR 0004 is explicit that trivial behaviour
+// gets no core class — and each is the ATTRIBUTE, `toggleAttribute` being idempotent, so
+// "notify only on a real change" needs no guard. The notify rule that IS derived from C
+// lives in the ROW's `SwitchRowState`.
 //
-// `notify::active` (CustomEvent, bubbles, detail `{ active }`) fires on every change,
-// programmatic included. A widget that COMPOSES this one and publishes its own
-// `notify::active` (`<adw-switch-row>`) stops this one at the switch, so the row stays
-// the single public event surface.
+// THE TWO BOOLEANS ARE NOT THE SAME THING, and that is the whole of `GtkSwitch`:
+// `active` is where the USER put the switch, `state` is what the thing being switched
+// currently IS (gtkswitch.c:39-43). `set_active` emits `::state-set` with the new value
+// and the DEFAULT HANDLER sets `state` to it (:800, :558), so by default the two track
+// each other — that is why a declarative `active` still paints the trough. An
+// application that changes the backend separately connects to `::state-set`, returns
+// TRUE to stop the default handler and calls `set_state` when the real change lands
+// (:637-654); then `active` moves and `state` does not, which is exactly the delayed
+// case. So the handler is not modelled as a cancellable signal — it is modelled as its
+// DEFAULT, plus the attribute an application writes, which is the one half a custom
+// element can express.
+//
+// WHICH ONE IS PAINTED: libadwaita's `switch:checked` (refs/libadwaita/src/stylesheet/
+// widgets/_switch.scss:41-55), and GTK sets that state flag from `state`, not from
+// `active` (gtkswitch.c:853-856). So the trough colour follows `state` and the knob
+// position follows `active`, which is the two-phase picture the C describes.
 //
 // A11Y: the checkbox is left bare — no `role="switch"` — because the widgets that host
 // one claim that role themselves (`adw_switch_row_init` sets
@@ -25,6 +34,7 @@
 //
 // Reference: refs/adwaita-web/adwaita-web/scss/_switch.scss
 // Reference: refs/libadwaita/src/stylesheet/widgets/_switch.scss
+// Reference: refs/gtk/gtk/gtkswitch.c:26-72,558,637-654,779-810,840-859
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Copyright (c) 2025 csm (adwaita-web). MIT License.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
@@ -35,7 +45,7 @@ export class GtkSwitch extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['active', 'disabled', 'unfocusable'];
+        return ['active', 'state', 'disabled', 'unfocusable'];
     }
 
     /**
@@ -54,17 +64,26 @@ export class GtkSwitch extends HTMLElement {
         this.toggleAttribute('unfocusable', !!value);
     }
 
-    /** Whether the switch is on. */
+    /** Whether the user put the switch ON. Drives the knob. */
     get active(): boolean {
         return this.hasAttribute('active');
     }
 
     set active(value: boolean) {
-        // `toggleAttribute` with a force flag is a no-op when the attribute already holds
-        // the wanted state, so re-setting the current value never runs
-        // `attributeChangedCallback` and never notifies. That idempotence is what a state
-        // class would otherwise hold.
+        // `gtk_switch_set_active` emits `::state-set` and the DEFAULT handler runs
+        // `set_state` (gtkswitch.c:800, :558), so writing one writes the other. That is
+        // what keeps a declarative `active` painting the accent trough.
         this.toggleAttribute('active', !!value);
+        this.state = this.active;
+    }
+
+    /** `Gtk.Switch:state` — what the switched thing currently is. Drives the trough. */
+    get state(): boolean {
+        return this.hasAttribute('state');
+    }
+
+    set state(value: boolean) {
+        this.toggleAttribute('state', !!value);
     }
 
     /** Whether the switch is inert. */
@@ -77,7 +96,10 @@ export class GtkSwitch extends HTMLElement {
     }
 
     connectedCallback() {
-        if (this._initialized) return;
+        if (this._initialized) {
+            this._render();
+            return;
+        }
         this._initialized = true;
 
         this.classList.add('adw-switch');
@@ -88,6 +110,12 @@ export class GtkSwitch extends HTMLElement {
         this._slider.className = 'adw-switch-slider';
         this.replaceChildren(this._input, this._slider);
 
+        // An `active` written before the element was connected is the same write GTK
+        // sees at construction time, so the default `::state-set` handler has already
+        // run by the time anyone looks: catch `state` up here (gtkswitch.c:682-757 gives
+        // `state` and `is_active` the same FALSE default and no attribute to reconcile).
+        if (this.active) this.state = true;
+
         // Keyboard (Space on the focused checkbox) and a programmatic `input.click()` both
         // arrive here; the attribute is the state, so this writes it and lets
         // attributeChangedCallback do the rest.
@@ -112,6 +140,8 @@ export class GtkSwitch extends HTMLElement {
         this._render();
         if (name === 'active') {
             this.dispatchEvent(new CustomEvent('notify::active', { bubbles: true, detail: { active: this.active } }));
+        } else if (name === 'state') {
+            this.dispatchEvent(new CustomEvent('notify::state', { bubbles: true, detail: { state: this.state } }));
         }
     }
 
@@ -121,6 +151,9 @@ export class GtkSwitch extends HTMLElement {
         this._input.disabled = disabled;
         if (this.unfocusable) this._input.tabIndex = -1;
         else this._input.removeAttribute('tabindex');
+        // The `:checked` state flag GTK raises from `state` (gtkswitch.c:853-856), which
+        // is the selector libadwaita paints the accent trough from.
+        this.classList.toggle('checked', this.state);
         this.classList.toggle('disabled', disabled);
     }
 }

package/src/elements/gtk-text-view.ts

@@ -0,0 +1,290 @@
+// <gtk-text-view> — `Gtk.TextView`, GTK's multi-line editable text widget.
+//
+// THE TEXT IS THE BUFFER, AND A BUFFER IS NOT AN ATTRIBUTE. `Gtk.TextView` has no `text`
+// property of its own: the text lives in a `Gtk.TextBuffer` handed over by `set_buffer`
+// (gtktextview.c), which is why an authored tree cannot carry one and the gallery block
+// for this widget is refused a static tree. Here the buffer's text is the light-DOM text of
+// the element, read once when it connects, plus a `text` attribute for the programmatic
+// door — the same shape `<gtk-entry>` has with `value`.
+//
+// `wrap-mode` and `justification` are Pango's, so they reach real CSS mechanisms rather
+// than being declared unreachable: `JUSTIFY_TEXT_ALIGN` answers the justification through
+// Pango's switch, which `<gtk-label>` reads for the same enum
+// (`Gtk.TextView:justification` and `Gtk.Label:justify` are one), and `wrap-mode` becomes
+// `white-space` plus the break CSS offers. `monospace` is libadwaita's own `.monospace`
+// class rather than a font stack written here again.
+//
+// THE FOUR PARAGRAPH SPACINGS ARE NOT PORTED, one reason: `indent`, `pixels-above-lines`,
+// `pixels-below-lines` and `pixels-inside-wrap` are Pango's PARAGRAPH model — a document
+// with paragraph breaks this widget does not have. CSS has one `line-height` for every
+// line, so there is no value of it that spaces paragraphs apart from the lines inside
+// them, and a `<textarea>` has no paragraphs to tell apart. They are declared in
+// `check-adwaita-element-properties.mjs` rather than silently dropped. The four MARGINS
+// are the other half of that pspec family and DO have a CSS mechanism: GTK's own property
+// doc says it — "this property is confusingly named. In CSS terms, the value set here is
+// padding" (gtktextview.c:1050-1057) — so they are `padding` here.
+//
+// `accepts-tab` is GTK's default (TRUE: Tab inserts a tab character,
+// gtktextview.c:1147-1151), which is the opposite of a browser's — so this element
+// intercepts Tab and inserts one rather than letting the UA move focus, and
+// `accepts-tab="false"` gives the UA its default back.
+//
+// A11y: GTK gives the widget `AccessibleRole.text_box` (gtktextview.c:1949), and the
+// native `<textarea>` this element builds already carries exactly that role — the host
+// does not repeat it, because a `role="textbox"` wrapping another textbox is worse for a
+// screen reader than no role at all.
+//
+// NOT PORTED, one line each: `im-module`, `input-hints` and `input-purpose` (the input
+// method and the on-screen keyboard it steers — a browser owns its own), and `overwrite`
+// (a mode that draws a block cursor and makes every keystroke replace the next character,
+// where a native text control overwrites an existing selection and exposes no mode
+// besides).
+//
+// Reference: refs/gtk/gtk/gtktextview.c:983-1201 (the pspecs and their defaults),
+//   1050-1057 (margins ARE padding), 1147-1151 (`accepts-tab` defaults TRUE),
+//   1949 (the `textbox` role), 3540-3600 (justification)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_views.scss:1-45 (`%view`, `textview`)
+// Copyright (c) The GTK Team, GNOME contributors. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { normalizeLabelJustify, type LabelJustification } from '@gjsify/adwaita-core';
+
+import { JUSTIFY_TEXT_ALIGN } from './justification.js';
+
+/** `Gtk.WrapMode`'s four nicks, in enum order — Pango's enum, and the DEFAULT is `none`. */
+const WRAP_MODES = ['none', 'char', 'word', 'word-char'] as const;
+
+type TextViewWrapMode = (typeof WRAP_MODES)[number];
+
+/**
+ * `Gtk.TextView:wrap-mode` from its nick, at Pango's own default of `none`.
+ *
+ * NOT `normalizeLabelWrapMode`, which reads the same enum but for `Gtk.Label`, whose
+ * pspec default is `word` and which has no `none` member to hold: reusing it here would
+ * wrap a text view that was asked not to, on every unknown value.
+ */
+function normalizeWrapMode(value: string | null): TextViewWrapMode {
+    return (WRAP_MODES as readonly string[]).includes(value ?? '') ? (value as TextViewWrapMode) : 'none';
+}
+
+/** `Gtk.TextView:wrap-mode` as the two CSS mechanisms it maps onto. */
+const WRAP_WHITE_SPACE: Record<TextViewWrapMode, string> = {
+    none: 'pre',
+    word: 'pre-wrap',
+    'word-char': 'pre-wrap',
+    char: 'pre-wrap',
+};
+
+export class GtkTextView extends HTMLElement {
+    private _area!: HTMLTextAreaElement;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return [
+            'text',
+            'editable',
+            'wrap-mode',
+            'justification',
+            'monospace',
+            'accepts-tab',
+            'cursor-visible',
+            'top-margin',
+            'bottom-margin',
+            'left-margin',
+            'right-margin',
+        ];
+    }
+
+    /** The buffer's text — the light-DOM text of the element, then whatever is typed. */
+    get text(): string {
+        return this._area ? this._area.value : (this.getAttribute('text') ?? this._seedText());
+    }
+
+    set text(value: string) {
+        if (this._area) this._area.value = value ?? '';
+        else this.setAttribute('text', value ?? '');
+    }
+
+    /** `Gtk.TextView:editable` — defaults TRUE, so the attribute carries a VALUE. */
+    get editable(): boolean {
+        return this._bool('editable', true);
+    }
+
+    set editable(value: boolean) {
+        this._setBool('editable', value, true);
+    }
+
+    /** `Gtk.TextView:wrap-mode` — where a line may break. Defaults to `none`, no wrapping. */
+    get wrapMode(): TextViewWrapMode {
+        return normalizeWrapMode(this.getAttribute('wrap-mode'));
+    }
+
+    set wrapMode(value: TextViewWrapMode) {
+        this.setAttribute('wrap-mode', value);
+    }
+
+    /** `Gtk.TextView:justification` — how the lines align with each other. Defaults `left`. */
+    get justification(): LabelJustification {
+        return normalizeLabelJustify(this.getAttribute('justification'));
+    }
+
+    set justification(value: LabelJustification) {
+        this.setAttribute('justification', value);
+    }
+
+    /** `Gtk.TextView:monospace` — whether the text is drawn in a monospace font. */
+    get monospace(): boolean {
+        return this._bool('monospace', false);
+    }
+
+    set monospace(value: boolean) {
+        this._setBool('monospace', value, false);
+    }
+
+    /** `Gtk.TextView:accepts-tab` — whether Tab inserts a tab character. Defaults TRUE. */
+    get acceptsTab(): boolean {
+        return this._bool('accepts-tab', true);
+    }
+
+    set acceptsTab(value: boolean) {
+        this._setBool('accepts-tab', value, true);
+    }
+
+    /** `Gtk.TextView:cursor-visible` — whether the insertion cursor is drawn. Defaults TRUE. */
+    get cursorVisible(): boolean {
+        return this._bool('cursor-visible', true);
+    }
+
+    set cursorVisible(value: boolean) {
+        this._setBool('cursor-visible', value, true);
+    }
+
+    /** `Gtk.TextView:top-margin` — pixels of blank space above the text, in `padding`. */
+    get topMargin(): number {
+        return this._margin('top-margin');
+    }
+
+    set topMargin(value: number) {
+        this.setAttribute('top-margin', String(value));
+    }
+
+    /** `Gtk.TextView:bottom-margin` — pixels of blank space below the text. */
+    get bottomMargin(): number {
+        return this._margin('bottom-margin');
+    }
+
+    set bottomMargin(value: number) {
+        this.setAttribute('bottom-margin', String(value));
+    }
+
+    /** `Gtk.TextView:left-margin` — pixels of blank space to the left of the text. */
+    get leftMargin(): number {
+        return this._margin('left-margin');
+    }
+
+    set leftMargin(value: number) {
+        this.setAttribute('left-margin', String(value));
+    }
+
+    /** `Gtk.TextView:right-margin` — pixels of blank space to the right of the text. */
+    get rightMargin(): number {
+        return this._margin('right-margin');
+    }
+
+    set rightMargin(value: number) {
+        this.setAttribute('right-margin', String(value));
+    }
+
+    /** The inner native textarea, for focus and selection. */
+    get textarea(): HTMLTextAreaElement {
+        return this._area;
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        const area = document.createElement('textarea');
+        area.className = 'adw-text-view';
+        // The `text` attribute wins over the light-DOM text, because an attribute is the
+        // explicit write and the light text is only what the author put where the buffer goes.
+        area.value = this.getAttribute('text') ?? this._seedText();
+        area.spellcheck = false;
+        area.addEventListener('input', () => this._emitChanged());
+        area.addEventListener('keydown', (event) => {
+            if (event.key !== 'Tab' || !this.acceptsTab) return;
+            event.preventDefault();
+            const start = area.selectionStart ?? area.value.length;
+            const end = area.selectionEnd ?? start;
+            // `setRangeText` does not fire `input`, so the insertion GTK reports through the
+            // buffer's `changed` is dispatched here instead.
+            area.setRangeText('\t', start, end, 'end');
+            this._emitChanged();
+        });
+
+        this._area = area;
+        this.replaceChildren(area);
+        this._render();
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'text') this._area.value = value ?? '';
+        else if (name === 'editable') this._area.readOnly = !this.editable;
+        this._render();
+    }
+
+    private _render(): void {
+        const wrapMode = this.wrapMode;
+        const area = this._area;
+        area.style.whiteSpace = WRAP_WHITE_SPACE[wrapMode];
+        // `word-char` falls back to a CHARACTER break only where a word will not fit, which
+        // is what `overflow-wrap: anywhere` means; `char` breaks anywhere, `word-break`.
+        area.style.wordBreak = wrapMode === 'char' ? 'break-all' : 'normal';
+        area.style.overflowWrap = wrapMode === 'word-char' ? 'anywhere' : 'normal';
+        area.style.textAlign = JUSTIFY_TEXT_ALIGN[this.justification];
+        area.style.caretColor = this.cursorVisible ? '' : 'transparent';
+        this.classList.toggle('monospace', this.monospace);
+        // The margins are custom properties the stylesheet ADDS to its own padding, because
+        // GTK's doc says they are applied in addition to the theme's padding
+        // (gtktextview.c:1050-1057) — writing `padding` from here would replace it.
+        area.style.setProperty('--adw-text-view-margin-top', `${this.topMargin}px`);
+        area.style.setProperty('--adw-text-view-margin-end', `${this.rightMargin}px`);
+        area.style.setProperty('--adw-text-view-margin-bottom', `${this.bottomMargin}px`);
+        area.style.setProperty('--adw-text-view-margin-start', `${this.leftMargin}px`);
+    }
+
+    /** The buffer's text before the inner control exists: the light-DOM text, or the attribute. */
+    private _seedText(): string {
+        return this.textContent;
+    }
+
+    /**
+     * `Gtk.TextBuffer:changed`, the signal a text view's edits travel on. The buffer is a
+     * separate GObject here (its text is the element's), so its `changed` is the one event
+     * this widget has to re-emit.
+     */
+    private _emitChanged(): void {
+        this.dispatchEvent(new CustomEvent('changed', { bubbles: true, detail: { text: this._area.value } }));
+    }
+
+    /** A boolean pspec read the way its default decides an attribute can spell it. */
+    private _bool(name: string, fallback: boolean): boolean {
+        const raw = this.getAttribute(name);
+        return raw === null ? fallback : raw !== 'false';
+    }
+
+    /** {@link _bool}'s writer: the pspec default is left unwritten, anything else is written. */
+    private _setBool(name: string, value: boolean, fallback: boolean): void {
+        if (value === fallback) this.removeAttribute(name);
+        else this.setAttribute(name, value ? 'true' : 'false');
+    }
+
+    /** A pixel margin, floored at 0 like every `g_param_spec_int` with a zero minimum. */
+    private _margin(name: string): number {
+        const parsed = Number.parseInt(this.getAttribute(name) ?? '', 10);
+        return Number.isFinite(parsed) ? Math.max(0, parsed) : 0;
+    }
+}
+
+customElements.define('gtk-text-view', GtkTextView);

package/src/elements/gtk-text.ts

@@ -0,0 +1,219 @@
+// <gtk-text> — `Gtk.Text`, the single-line text widget GTK builds every entry out of.
+//
+// WHY IT EXISTS ALONGSIDE <gtk-entry>. `Gtk.Text` is "the common implementation of
+// single-line text editing that is shared between Gtk.Entry, Gtk.PasswordEntry,
+// Gtk.SpinButton" (gtktext.c:78-91), and its own `<gtk-text>` surface is what an author
+// reaches when there is no entry AROUND it — a bare single-line field with a placeholder
+// and a length limit. GTK gives that widget `AccessibleRole.none`, "which causes it to be
+// skipped for accessibility … expected to be used as a delegate for a GtkEditable
+// implementation" (gtktext.c:199-205); standing alone it IS the field, so the inner
+// native input carries the textbox role here. That is a DECLARED divergence, and it is
+// the only one about accessibility.
+//
+// THE LENGTH ARITHMETIC IS HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004):
+// `clampEntryText` truncates on CODE POINTS, the same helper `<gtk-entry>` uses. The
+// native `maxlength` attribute would not have closed the gap, because the browser counts
+// UTF-16 code units — `'🔒é'` is 2 characters to GTK and 3 to `input.maxLength`.
+//
+// `visibility` IS A VALUE, NOT A PRESENCE: its pspec default is TRUE (gtktext.c:1778),
+// so a bare `visibility` attribute would mean the same thing as leaving it off, and
+// `editable` has the same default. `readBooleanAttribute` below reads both the HTML way
+// (absent → the pspec default, an explicit `="false"` → off) and is what decides which
+// spelling a boolean of this widget can carry.
+//
+// NOT PORTED, one line each, and declared in `check-adwaita-element-properties.mjs`:
+// `activates-default` (GTK additionally activates the toplevel's default widget, and a
+// document has none — `activate`, the signal Return is bound to at gtktext.c:1517-1520,
+// fires either way), `enable-emoji-completion` (an Emoji chooser a browser has none of),
+// `im-module` / `input-hints` / `input-purpose` (the input method and the on-screen
+// keyboard it steers), `invisible-char` / `invisible-char-set` (GTK picks the masking
+// glyph — `'*'`, the pspec default `42`, or a blank when only the flag is set,
+// gtktext.c:2318-2322 — where a masked native input draws U+2022 and exposes no choice),
+// `overwrite-mode` (a mode that draws a block cursor and makes every keystroke replace
+// the next character; a native input overwrites an existing selection and no mode
+// besides), and `truncate-multiline` (a single-line input drops every newline from a
+// paste, so the property has nothing left to switch).
+//
+// Reference: refs/gtk/gtk/gtktext.c:78-91,1517-1520,155-167,2270-2322,2588-2611,
+//   3605-3607,5742-5767,7400-7420
+// Reference: refs/libadwaita/src/stylesheet/widgets/_views.scss:1-18,20-45 (`%view`, `text`)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_entries.scss:19-28 (placeholder, block cursor)
+// Copyright (c) The GTK Team, GNOME contributors. LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the length
+//   arithmetic composed from @gjsify/adwaita-core.
+
+import { ENTRY_ROW_MAX_LENGTH_LIMIT, clampEntryText, entryTextLength } from '@gjsify/adwaita-core';
+
+export class GtkText extends HTMLElement {
+    private _input!: HTMLInputElement;
+    private _initialized = false;
+    private _maxLength = 0;
+
+    static get observedAttributes() {
+        return ['text', 'editable', 'placeholder-text', 'max-length', 'visibility', 'propagate-text-width'];
+    }
+
+    /** `Gtk.Editable:text` — the buffer's contents, which is what the field shows. */
+    get text(): string {
+        return this._input ? this._input.value : (this.getAttribute('text') ?? '');
+    }
+
+    set text(value: string) {
+        const clamped = clampEntryText(value ?? '', this._maxLength);
+        if (this._input) this._input.value = clamped;
+        else this.setAttribute('text', clamped);
+        this._resizeToText();
+    }
+
+    /** `Gtk.Editable:editable` — defaults TRUE, so the attribute carries a VALUE. */
+    get editable(): boolean {
+        return readBooleanAttribute(this, 'editable', true);
+    }
+
+    set editable(value: boolean) {
+        writeBooleanAttribute(this, 'editable', value, true);
+    }
+
+    /** `Gtk.Text:placeholder-text` — shown while the field is empty and unfocused. */
+    get placeholderText(): string {
+        return this.getAttribute('placeholder-text') ?? '';
+    }
+
+    set placeholderText(value: string) {
+        this.setAttribute('placeholder-text', value ?? '');
+    }
+
+    /** `Gtk.Text:max-length` — 0 means unlimited. Counted in CODE POINTS. */
+    get maxLength(): number {
+        return this._maxLength;
+    }
+
+    set maxLength(value: number) {
+        this._maxLength = Number.isFinite(value)
+            ? Math.min(ENTRY_ROW_MAX_LENGTH_LIMIT, Math.max(0, Math.trunc(value)))
+            : 0;
+        if (this._input) this._input.value = clampEntryText(this._input.value, this._maxLength);
+    }
+
+    /** `Gtk.Text:visibility` — FALSE masks the contents (the "password mode"). Defaults TRUE. */
+    get visibility(): boolean {
+        return readBooleanAttribute(this, 'visibility', true);
+    }
+
+    set visibility(value: boolean) {
+        writeBooleanAttribute(this, 'visibility', value, true);
+    }
+
+    /**
+     * `Gtk.Text:propagate-text-width` — whether the widget grows and shrinks with its
+     * content. GTK re-measures the Pango layout on every insertion and deletion while it
+     * is set (gtktext.c:2588-2600,3605-3607,3639-3640); a native input has the same
+     * mechanism, its `size`, which is why this is a real mapping and not a measurement.
+     */
+    get propagateTextWidth(): boolean {
+        return readBooleanAttribute(this, 'propagate-text-width', false);
+    }
+
+    set propagateTextWidth(value: boolean) {
+        writeBooleanAttribute(this, 'propagate-text-width', value, false);
+    }
+
+    /** `gtk_text_get_text_length` — code points, not UTF-16 units. */
+    get textLength(): number {
+        return entryTextLength(this.text);
+    }
+
+    /** The inner native input, for focus and selection. */
+    get input(): HTMLInputElement {
+        return this._input;
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this._maxLength = Number(this.getAttribute('max-length') ?? 0);
+        const input = document.createElement('input');
+        input.className = 'adw-text';
+        input.type = this.visibility ? 'text' : 'password';
+        input.value = clampEntryText(this.getAttribute('text') ?? '', this._maxLength);
+        input.placeholder = this.placeholderText;
+        input.readOnly = !this.editable;
+        // Typing past the limit is clamped here, on the way in, so the field and the
+        // buffer agree — the same place `<gtk-entry>` clamps.
+        input.addEventListener('input', () => {
+            const clamped = clampEntryText(input.value, this._maxLength);
+            if (clamped !== input.value) input.value = clamped;
+            this._resizeToText();
+        });
+        input.addEventListener('keydown', (event) => {
+            if (event.key !== 'Enter') return;
+            this.dispatchEvent(new CustomEvent('activate', { bubbles: true, detail: { text: input.value } }));
+        });
+
+        this._input = input;
+        this.replaceChildren(input);
+        this._render();
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) {
+            // Before the inner input exists `max-length` is still read: it decides what the
+            // input is built with, so `_initialized` alone would drop a limit set in markup.
+            if (name === 'max-length') this._maxLength = Number(value ?? 0);
+            return;
+        }
+        if (name === 'text') this._input.value = clampEntryText(value ?? '', this._maxLength);
+        else if (name === 'placeholder-text') this._input.placeholder = value ?? '';
+        else if (name === 'max-length') {
+            this._maxLength = Number(value ?? 0);
+            this._input.value = clampEntryText(this._input.value, this._maxLength);
+        } else if (name === 'editable') this._input.readOnly = !this.editable;
+        else if (name === 'visibility') this._input.type = this.visibility ? 'text' : 'password';
+        this._resizeToText();
+        this._reflectReadOnly();
+    }
+
+    private _render(): void {
+        this._resizeToText();
+        this._reflectReadOnly();
+    }
+
+    /**
+     * `text[.read-only]` (gtktext.c:155-167) is the node class a read-only text carries,
+     * and libadwaita never styles it — it is a selector hook. GTK's own `set_editable`
+     * adds the class on the way TO editable (gtktext.c:5762-5767), which is the inverse of
+     * what the node documentation above it describes; the DOCUMENTED rule is what a node
+     * author can rely on, so that is the one applied here.
+     */
+    private _reflectReadOnly(): void {
+        this.classList.toggle('read-only', !this.editable);
+    }
+
+    private _resizeToText(): void {
+        const propagate = this.propagateTextWidth;
+        this.classList.toggle('propagate-text-width', propagate);
+        // Only ever RAISED: `size` is a limited-to-positive-range IDL attribute, so
+        // restoring it to the UA default means leaving it alone.
+        if (this._input && propagate) this._input.size = Math.max(1, entryTextLength(this._input.value));
+    }
+}
+
+/**
+ * A boolean GObject property, read the way its pspec default decides an attribute can
+ * spell it: absent is the default, a bare attribute is TRUE, and `="false"` is the opt-out.
+ * `Gtk.Text:visibility` and `Gtk.Editable:editable` both default TRUE, so neither can be
+ * carried by presence alone.
+ */
+function readBooleanAttribute(element: HTMLElement, name: string, fallback: boolean): boolean {
+    const value = element.getAttribute(name);
+    return value === null ? fallback : value !== 'false';
+}
+
+/** {@link readBooleanAttribute}'s writer: the default is left unwritten, anything else is. */
+function writeBooleanAttribute(element: HTMLElement, name: string, value: boolean, fallback: boolean): void {
+    if (value === fallback) element.removeAttribute(name);
+    else element.setAttribute(name, value ? 'true' : 'false');
+}
+
+customElements.define('gtk-text', GtkText);