@gjsify/adwaita-web 0.55.0 → 0.57.0

package/src/gtksource/web-editor-driver.ts

@@ -0,0 +1,260 @@
+// The browser half of `GtkSource.View`: a `<textarea>` that owns the caret, selection, input,
+// IME and undo, with the highlight painted on a backdrop behind its transparent text and the
+// line numbers in a gutter beside it. The structure mirrors the Android driver
+// (`packages/nativescript-bridge/gtksource/src/native-editor.android.ts`): the platform edits
+// text natively, and this class reports what the user did to an `EditorHost`.
+//
+// NO WORD WRAP, as on Android: `wrap="off"` and `white-space: pre` keep every logical line on
+// one layout line, so the backdrop and the gutter stay aligned by a fixed line height.
+
+import type { EditorDriver, EditorHost, EditorLayout, EditorPalette, StyledRun } from '@gjsify/gtksource-core';
+import { digitCount, LineStore } from '@gjsify/gtksource-core';
+
+const GUTTER_PADDING_PX = 8;
+
+/** A signed ARGB int (the core's colour unit) as a CSS colour. */
+function cssColor(argb: number): string {
+    const alpha = ((argb >>> 24) & 0xff) / 255;
+    return `rgba(${(argb >>> 16) & 0xff}, ${(argb >>> 8) & 0xff}, ${argb & 0xff}, ${alpha})`;
+}
+
+export interface EditorParts {
+    readonly root: HTMLElement;
+    readonly area: HTMLTextAreaElement;
+    readonly backdrop: HTMLElement;
+    readonly gutter: HTMLElement;
+}
+
+export class WebEditorDriver implements EditorDriver {
+    private host: EditorHost | null = null;
+    private text = '';
+    private caret = 0;
+    private reported = { start: 0, end: 0 };
+    private layout: EditorLayout | null = null;
+    private readonly runs = new LineStore<readonly StyledRun[]>();
+    private scheduled = false;
+    private listening: Array<() => void> = [];
+    private palette: EditorPalette | null = null;
+    private attached = false;
+
+    constructor(private readonly parts: EditorParts) {}
+
+    bind(host: EditorHost): void {
+        this.host = host;
+    }
+
+    /** Starts listening to the textarea; the counterpart of the Android `attach()`. */
+    attach(): void {
+        if (this.listening.length > 0) return;
+        this.attached = true;
+        const { area, backdrop, gutter } = this.parts;
+        const on = <T extends EventTarget>(target: T, type: string, listener: EventListener) => {
+            target.addEventListener(type, listener);
+            this.listening.push(() => target.removeEventListener(type, listener));
+        };
+        on(area, 'input', () => this.onInput());
+        on(area, 'scroll', () => {
+            backdrop.scrollTop = area.scrollTop;
+            backdrop.scrollLeft = area.scrollLeft;
+            (gutter.firstElementChild as HTMLElement | null)?.style.setProperty(
+                'transform',
+                `translateY(${-area.scrollTop}px)`,
+            );
+        });
+        on(area, 'select', () => this.onSelection());
+        on(area, 'keyup', () => this.onSelection());
+        on(area, 'mouseup', () => this.onSelection());
+        on(area, 'keydown', (event) => this.onKey(event as KeyboardEvent));
+        // Firefox and Chromium fire `selectionchange` on different targets for a textarea.
+        on(area.ownerDocument, 'selectionchange', () => {
+            if (area.ownerDocument.activeElement === area) this.onSelection();
+        });
+        if (this.layout) this.applyLayout(this.layout);
+        if (this.palette) this.applyPalette(this.palette);
+        this.scheduleRender();
+    }
+
+    detach(): void {
+        this.attached = false;
+        for (const stop of this.listening.splice(0)) stop();
+    }
+
+    // --- what the user did -------------------------------------------------------------------
+
+    private onInput(): void {
+        const next = this.parts.area.value;
+        const prev = this.text;
+        let prefix = 0;
+        const shortest = Math.min(prev.length, next.length);
+        while (prefix < shortest && prev.charCodeAt(prefix) === next.charCodeAt(prefix)) prefix++;
+        let suffix = 0;
+        while (
+            suffix < shortest - prefix &&
+            prev.charCodeAt(prev.length - 1 - suffix) === next.charCodeAt(next.length - 1 - suffix)
+        ) {
+            suffix++;
+        }
+        this.text = next;
+        this.host?.onNativeEdit(prefix, prev.length - prefix - suffix, next.slice(prefix, next.length - suffix));
+        this.onSelection();
+        this.scheduleRender();
+    }
+
+    private onSelection(): void {
+        const { area } = this.parts;
+        const start = area.selectionStart ?? 0;
+        const end = area.selectionEnd ?? start;
+        if (start === this.reported.start && end === this.reported.end) return;
+        this.reported = { start, end };
+        this.caret = end;
+        this.host?.onNativeSelection(start, end);
+        this.scheduleRender();
+    }
+
+    /** `accepts-tab` is GTK's default; a textarea would move focus, so Tab inserts a tab. */
+    private onKey(event: KeyboardEvent): void {
+        if (event.key !== 'Tab' || event.shiftKey || event.ctrlKey || event.altKey || event.metaKey) return;
+        if (this.parts.area.readOnly) return;
+        event.preventDefault();
+        // `insertText` keeps the edit on the browser's own undo stack and fires `input`.
+        if (!this.parts.area.ownerDocument.execCommand('insertText', false, '\t')) {
+            const { area } = this.parts;
+            area.setRangeText('\t', area.selectionStart, area.selectionEnd, 'end');
+            this.onInput();
+        }
+    }
+
+    // --- what to show ------------------------------------------------------------------------
+
+    setText(text: string): void {
+        this.text = text;
+        this.parts.area.value = text;
+        this.runs.clear();
+        this.scheduleRender();
+    }
+
+    replaceRange(start: number, end: number, text: string): void {
+        const { area } = this.parts;
+        this.text = this.text.slice(0, start) + text + this.text.slice(end);
+        // 'preserve' leaves the selection to the session, which sets it explicitly afterwards.
+        area.setRangeText(text, start, end, 'preserve');
+        this.scheduleRender();
+    }
+
+    setSelection(start: number, end: number): void {
+        this.reported = { start, end };
+        this.caret = end;
+        this.parts.area.setSelectionRange(start, end);
+        this.scheduleRender();
+    }
+
+    setLineCount(): void {
+        this.scheduleRender();
+    }
+
+    setLayout(layout: EditorLayout): void {
+        this.layout = layout;
+        if (this.attached) this.applyLayout(layout);
+    }
+
+    /** Attributes and styles on the host wait for `attach()`: a custom element's constructor may not write them. */
+    private applyLayout(layout: EditorLayout): void {
+        const { root, area } = this.parts;
+        area.readOnly = !layout.editable;
+        root.classList.toggle('monospace', layout.monospace);
+        root.classList.toggle('show-line-numbers', layout.showLineNumbers);
+        root.classList.toggle('cursor-hidden', !layout.cursorVisible);
+        root.style.setProperty('--gsv-margin-left', `${layout.leftMargin}px`);
+        root.style.setProperty('--gsv-margin-right', `${layout.rightMargin}px`);
+        root.style.setProperty('--gsv-margin-top', `${layout.topMargin}px`);
+        root.style.setProperty('--gsv-margin-bottom', `${layout.bottomMargin}px`);
+        this.scheduleRender();
+    }
+
+    setPalette(palette: EditorPalette): void {
+        this.palette = palette;
+        if (this.attached) this.applyPalette(palette);
+    }
+
+    private applyPalette(palette: EditorPalette): void {
+        const { style } = this.parts.root;
+        style.setProperty('--gsv-fg', cssColor(palette.foreground));
+        style.setProperty('--gsv-bg', cssColor(palette.background));
+        style.setProperty('--gsv-selection', cssColor(palette.selectionBackground));
+        style.setProperty('--gsv-current-line', cssColor(palette.currentLineBackground));
+        style.setProperty('--gsv-number-fg', cssColor(palette.lineNumberForeground));
+        style.setProperty('--gsv-number-bg', cssColor(palette.lineNumberBackground));
+        style.setProperty('--gsv-current-number-fg', cssColor(palette.currentLineNumberForeground));
+        style.setProperty('--gsv-current-number-bg', cssColor(palette.currentLineNumberBackground));
+    }
+
+    spliceLines(first: number, removed: number, inserted: number): void {
+        this.runs.splice(first, removed, inserted);
+    }
+
+    paintLine(line: number, _lineStart: number, runs: readonly StyledRun[]): void {
+        this.runs.set(line, runs);
+        this.scheduleRender();
+    }
+
+    clearAll(): void {
+        this.runs.clear();
+        this.scheduleRender();
+    }
+
+    // --- painting ----------------------------------------------------------------------------
+
+    /** One repaint per task: a burst of `paintLine` calls from one edit costs one DOM rebuild. */
+    private scheduleRender(): void {
+        if (this.scheduled || !this.attached) return;
+        this.scheduled = true;
+        queueMicrotask(() => {
+            this.scheduled = false;
+            this.render();
+        });
+    }
+
+    private render(): void {
+        const { backdrop, gutter, root } = this.parts;
+        const lines = this.text.split('\n');
+        const highlight = this.layout?.highlightCurrentLine === true;
+        const caretLine = this.text.slice(0, this.caret).split('\n').length - 1;
+
+        const rows: HTMLElement[] = [];
+        const numbers: HTMLElement[] = [];
+        lines.forEach((line, index) => {
+            const row = document.createElement('div');
+            row.className = highlight && index === caretLine ? 'gsv-line current' : 'gsv-line';
+            let at = 0;
+            for (const run of this.runs.get(index) ?? []) {
+                if (run.start > at) row.append(line.slice(at, run.start));
+                const span = document.createElement('span');
+                span.textContent = line.slice(run.start, run.end);
+                const { style } = run;
+                if (style.foreground !== undefined) span.style.color = cssColor(style.foreground);
+                if (style.background !== undefined) span.style.backgroundColor = cssColor(style.background);
+                if (style.bold) span.style.fontWeight = 'bold';
+                if (style.italic) span.style.fontStyle = 'italic';
+                const decorations = [style.underline ? 'underline' : '', style.strikethrough ? 'line-through' : ''];
+                span.style.textDecoration = decorations.filter(Boolean).join(' ');
+                row.append(span);
+                at = run.end;
+            }
+            if (at < line.length) row.append(line.slice(at));
+            rows.push(row);
+
+            const number = document.createElement('div');
+            number.className = highlight && index === caretLine ? 'gsv-number current' : 'gsv-number';
+            number.textContent = String(index + 1);
+            numbers.push(number);
+        });
+        backdrop.replaceChildren(...rows);
+        const column = document.createElement('div');
+        column.className = 'gsv-numbers';
+        column.append(...numbers);
+        column.style.transform = `translateY(${-this.parts.area.scrollTop}px)`;
+        gutter.replaceChildren(column);
+        root.style.setProperty('--gsv-gutter-width', `${digitCount(lines.length) + 0}ch`);
+        root.style.setProperty('--gsv-gutter-padding', `${GUTTER_PADDING_PX}px`);
+    }
+}

package/src/index.ts

@@ -81,7 +81,7 @@ export type { AdwUndershootEdges } from './scroll-shading.js';
 // spec itself — has a route to it that is not a `.spec.ts` import; see that file's header
 // for why `mountSharedTree` and not `buildSharedTree` alone is the instantiation half.
 export { buildSharedTree, mountSharedTree } from './shared-tree-builder.js';
-export type { MountedSharedTree, SizeSource } from './shared-tree-builder.js';
+export type { MountOptions, MountedSharedTree, SizeSource } from './shared-tree-builder.js';
 export { registerTemplateClass } from './template-classes.js';
 
 // The stylesheet compiles a chosen SUBSET of `@gjsify/adwaita-icons` (the whole set is
@@ -119,6 +119,16 @@ export * as Gtk from './namespace/gtk.js';
 // program here as on GJS — `./namespace/gio.ts` says what does not go in it.
 export * as Gio from './namespace/gio.js';
 
+// GLib's timers (`idle_add`, `timeout_add`, `source_remove`): `./namespace/glib.ts` says what is absent.
+export * as GLib from './namespace/glib.js';
+
+// The fourth, and the one that makes an unmodified GNOME component class run (ADR 0096): the GObject
+// subset, `registerClass` first. `./namespace/gobject.ts` says what it is.
+export * as GObject from './namespace/gobject.js';
+
+// GtkSource (ADR 0094 amendment): `GtkSource.View` over `@gjsify/gtksource-core`, `./namespace/gtksource.ts`.
+export * as GtkSource from './namespace/gtksource.js';
+
 // WHAT DID NOT MOVE INTO THE NAMESPACE, and the rule that decides it. A member exists
 // for an element whose GIR tag names a real widget; `WEB_ELEMENT_ALIGNMENT` declares the
 // rest `webOnly`, meaning no widget in the reference vocabulary stands behind it, so

package/src/keyboard-operable.spec.ts

@@ -622,21 +622,57 @@ export const AdwKeyboardOperableTest = async () => {
             // Prose cannot hold that: this line fails the commit that adds it.
             // `<adw-inline-view-switcher>` has the same gap (status/open-todos/README.md).
             // `active-name` joined the list without touching the axis: it picks a toggle.
-            expect([...AdwToggleGroup.observedAttributes]).toStrictEqual(['active', 'active-name', 'flat', 'round']);
+            // `sensitive` joined it for the same reason — it gates every button's `disabled`,
+            // never the axis. `keyboard-operable.spec.ts` below now pins the roving walk
+            // against a disabled toggle, which is what made that attribute safe to add.
+            expect([...AdwToggleGroup.observedAttributes]).toStrictEqual([
+                'active',
+                'active-name',
+                'flat',
+                'round',
+                'sensitive',
+            ]);
         });
 
         await it('adw-toggle has no state a roving walk would have to skip', async () => {
-            // `<adw-toggle-group>` passes its buttons to `attachRovingFocus` UNFILTERED,
-            // which is only safe while no `<adw-toggle>` attribute can produce a disabled
-            // or hidden button. That is a decision recorded in two comments and a ledger
-            // entry, and this is the line that fails when it stops being true — the first
-            // disabled toggle is otherwise a `focus()` the browser refuses, with nothing
-            // in the walk to step over it. Grow this list and add the filter and its spec
-            // in the same change (status/open-todos/README.md, `<adw-toggle>` has no `enabled`).
+            // `<adw-toggle-group>` FILTERS its buttons for `attachRovingFocus`, which is only
+            // necessary once some `<adw-toggle>` attribute can produce a disabled button.
+            // `enabled` is that attribute (`AdwToggle:enabled`), so this list is now the
+            // record of WHICH attributes can — `hidden` cannot, and no other one can.
+            // Grow it and the filter has to grow with it: an unskipped disabled toggle is a
+            // `focus()` the browser refuses, with nothing in the walk to step over it. The
+            // skip itself is pinned in the case below.
             //
-            // `tooltip` joined the list and is NOT a counterexample: it sets `title` and
-            // `aria-label`, which change neither reachability nor rendering.
-            expect([...AdwToggle.observedAttributes]).toStrictEqual(['label', 'icon-name', 'tooltip']);
+            // `tooltip` is not a counterexample: it sets `title` and `aria-label`, which
+            // change neither reachability nor rendering.
+            expect([...AdwToggle.observedAttributes]).toStrictEqual(['label', 'icon-name', 'tooltip', 'enabled']);
+        });
+
+        await it('adw-toggle-group arrow skips a disabled toggle', async () => {
+            // `AdwToggle:enabled` reached the web element with #1818, and the filter
+            // `roving-focus.ts` asks of every caller is the price of it — the same obligation
+            // `<adw-sidebar>` already pays ("arrow skips a disabled row", above). A disabled
+            // `<button>` cannot take focus, so leaving it in the walk strands the user on a
+            // `focus()` the browser refuses.
+            withWidget(
+                () => {
+                    const el = document.createElement('adw-toggle-group');
+                    el.innerHTML =
+                        '<adw-toggle label="One"></adw-toggle>' +
+                        '<adw-toggle label="Two" enabled="false"></adw-toggle>' +
+                        '<adw-toggle label="Three"></adw-toggle>';
+                    return el;
+                },
+                (el) => {
+                    const items = rovingCase('adw-toggle-group').items(el);
+                    expect(items.length).toBe(3);
+                    expect((items[1] as HTMLButtonElement).disabled).toBe(true);
+
+                    items[0].focus();
+                    press(items[0], 'ArrowRight');
+                    expect(document.activeElement).toBe(items[2]);
+                },
+            );
         });
 
         await it('adw-toggle-group notifies once per arrow, through the click path', async () => {

package/src/menu-actions.spec.ts

@@ -0,0 +1,47 @@
+// ADR 0097 §§ 1, 3 on the browser: the action resolution from the owning `gtk-menu-button`, and a
+// tree's menus reaching its `menuModel`.
+import {
+    MENU_ACTION_VECTORS,
+    MENU_TREE_VECTORS,
+    driveMenuActionVectors,
+    registryMenuActionScene,
+    type SharedTreeNode,
+} from '@gjsify/adwaita-core/conformance';
+import { describe, expect, it } from '@gjsify/unit';
+
+import { parentOfElement } from './application.js';
+import { buildSharedTree } from './shared-tree-builder.js';
+import type { GtkMenuButton } from './elements/gtk-menu-button.js';
+
+const made: Element[] = [];
+
+export const MenuActionsTest = async () => {
+    expect(MENU_ACTION_VECTORS.length > 0).toBe(true);
+    await driveMenuActionVectors(
+        'adwaita-web (gtk-menu-button)',
+        registryMenuActionScene(() => {
+            const outer = document.createElement('div');
+            const button = document.createElement('gtk-menu-button');
+            outer.append(button);
+            document.body.append(outer);
+            made.push(outer);
+            return { outer, button };
+        }, parentOfElement),
+        { describe, it, expect },
+    );
+
+    await describe('adwaita-web: menus in a shared tree (ADR 0097 § 1)', async () => {
+        for (const { result, rule, tree } of MENU_TREE_VECTORS) {
+            await it(rule, () => {
+                const node = tree as unknown as SharedTreeNode;
+                if ('refused' in result) {
+                    expect(() => buildSharedTree(node)).toThrow(result.refused);
+                    return;
+                }
+                const button = buildSharedTree(node) as unknown as GtkMenuButton;
+                expect(button.menuModel.map((entry) => entry.kind).join(',')).toBe(result.kinds.join(','));
+            });
+        }
+    });
+    for (const element of made.splice(0)) element.remove();
+};

package/src/namespace/adw.ts

@@ -109,3 +109,4 @@ export { AdwViewSwitcherBar as ViewSwitcherBar } from '../elements/adw-view-swit
 export { AdwWindow as Window } from '../elements/adw-window.js';
 export { AdwWindowTitle as WindowTitle } from '../elements/adw-window-title.js';
 export { AdwWrapBox as WrapBox } from '../elements/adw-wrap-box.js';
+export { AdwApplication as Application } from '../application.js';

package/src/namespace/gio.ts

@@ -17,3 +17,5 @@
 // unheld vocabulary.
 
 export { GioMenu as Menu, GioMenuItem as MenuItem } from '@gjsify/adwaita-core';
+export { SimpleAction, ApplicationFlags } from '@gjsify/adwaita-core';
+export { GioApplication as Application } from '../application.js';

package/src/namespace/glib.ts

@@ -0,0 +1,22 @@
+// The GLib half of the vocabulary: the main-loop sources a GNOME app schedules work with —
+// `idle_add`, `timeout_add`, `source_remove` and the `PRIORITY_*` / `SOURCE_*` constants. The
+// behaviour lives once in `@gjsify/adwaita-core` (`glib-timers.ts`, which states where a host
+// event loop cannot honour GLib); this file is the namespace door over the host's `setTimeout`.
+//
+// A TRUE SUBSET: everything else in GLib (`MainLoop`, `Source`, `timeout_add_seconds`, `Bytes`,
+// `build_filenamev`, …) is absent, and the `gi://GLib` arm refuses it by name.
+
+import { createGLibTimers } from '@gjsify/adwaita-core';
+
+const glib = createGLibTimers();
+
+export const PRIORITY_HIGH = glib.PRIORITY_HIGH;
+export const PRIORITY_DEFAULT = glib.PRIORITY_DEFAULT;
+export const PRIORITY_HIGH_IDLE = glib.PRIORITY_HIGH_IDLE;
+export const PRIORITY_DEFAULT_IDLE = glib.PRIORITY_DEFAULT_IDLE;
+export const PRIORITY_LOW = glib.PRIORITY_LOW;
+export const SOURCE_REMOVE = glib.SOURCE_REMOVE;
+export const SOURCE_CONTINUE = glib.SOURCE_CONTINUE;
+export const idle_add = glib.idle_add;
+export const timeout_add = glib.timeout_add;
+export const source_remove = glib.source_remove;

package/src/namespace/gobject.ts

@@ -0,0 +1,37 @@
+// The GObject half of `@gjsify/adwaita-web`'s vocabulary (ADR 0096) — `GObject.registerClass`,
+// `GObject.ParamSpec` and the rest of the subset, the way `./adw.ts` and `./gtk.ts` export their
+// members. `export * as GObject from './namespace/gobject.js'` in `src/index.ts` makes it the
+// namespace. Everything is the core's (`@gjsify/adwaita-core`); this port supplies only the door
+// to custom elements, in `../gobject-door.ts`.
+//
+// `Object` is re-exported under its GIR name, so it is bound to a local first: a module-level
+// `export const Object` would shadow the global one for this file.
+
+import { createGObject } from '@gjsify/adwaita-core';
+
+import { webDoor } from '../gobject-door.js';
+
+const gobject = createGObject(webDoor);
+
+const GObjectObject = gobject.Object;
+
+export { GObjectObject as Object };
+export const registerClass = gobject.registerClass;
+export const type_ensure = gobject.type_ensure;
+export const ParamSpec = gobject.ParamSpec;
+export const ParamFlags = gobject.ParamFlags;
+export const TYPE_STRING = gobject.TYPE_STRING;
+export const TYPE_BOOLEAN = gobject.TYPE_BOOLEAN;
+export const TYPE_INT = gobject.TYPE_INT;
+export const TYPE_UINT = gobject.TYPE_UINT;
+export const TYPE_DOUBLE = gobject.TYPE_DOUBLE;
+export const GTypeName = gobject.GTypeName;
+export const GTypeFlags = gobject.GTypeFlags;
+export const interfaces = gobject.interfaces;
+export const properties = gobject.properties;
+export const signals = gobject.signals;
+export const requires = gobject.requires;
+export const __gtkTemplate__ = gobject.__gtkTemplate__;
+export const __gtkCssName__ = gobject.__gtkCssName__;
+export const __gtkChildren__ = gobject.__gtkChildren__;
+export const __gtkInternalChildren__ = gobject.__gtkInternalChildren__;

package/src/namespace/gtk-enums.ts

@@ -0,0 +1,15 @@
+// The plain GTK enums an application reads off `Gtk` — `Gtk.PolicyType`, `Gtk.TextDirection` and
+// `Gtk.TextWindowType`, as value tables. The numbers are the typelib's (GIR declaration order),
+// and the same tables the NativeScript port publishes.
+//
+// Reference: refs/gtk gtk/gtkenums.h (GtkPolicyType, GtkTextDirection), gtk/gtktextview.h (GtkTextWindowType)
+// Copyright (c) The GTK Team. LGPLv2.1+.
+
+/** `Gtk.PolicyType`: `ALWAYS` 0, `AUTOMATIC` 1, `NEVER` 2, `EXTERNAL` 3. */
+export const PolicyType = Object.freeze({ ALWAYS: 0, AUTOMATIC: 1, NEVER: 2, EXTERNAL: 3 } as const);
+
+/** `Gtk.TextDirection`: `NONE` 0, `LTR` 1, `RTL` 2. */
+export const TextDirection = Object.freeze({ NONE: 0, LTR: 1, RTL: 2 } as const);
+
+/** `Gtk.TextWindowType`: `WIDGET` 1, `TEXT` 2, `LEFT` 3, `RIGHT` 4, `TOP` 5, `BOTTOM` 6. */
+export const TextWindowType = Object.freeze({ WIDGET: 1, TEXT: 2, LEFT: 3, RIGHT: 4, TOP: 5, BOTTOM: 6 } as const);

package/src/namespace/gtk.ts

@@ -21,6 +21,7 @@
 // are the same write and nothing in this package had to learn a second input shape.
 
 export { GtkAdjustment as Adjustment } from '@gjsify/adwaita-core';
+export { PolicyType, TextDirection, TextWindowType } from './gtk-enums.js';
 export { GtkAboutDialog as AboutDialog } from '../elements/gtk-about-dialog.js';
 export { GtkActionBar as ActionBar } from '../elements/gtk-action-bar.js';
 export { GtkApplicationWindow as ApplicationWindow } from '../elements/gtk-application-window.js';
@@ -95,3 +96,4 @@ export { GtkWindow as Window } from '../elements/gtk-window.js';
 export { GtkWindowControls as WindowControls } from '../elements/gtk-window-controls.js';
 export { GtkViewport as Viewport } from '../elements/gtk-viewport.js';
 export { GtkWindowHandle as WindowHandle } from '../elements/gtk-window-handle.js';
+export { GtkApplication as Application } from '../application.js';

package/src/namespace/gtksource.ts

@@ -0,0 +1,9 @@
+// The GtkSource vocabulary of `@gjsify/adwaita-web` (ADR 0094 amendment): `GtkSource.View`,
+// `Buffer`, `LanguageManager`, `StyleSchemeManager`, over `@gjsify/gtksource-core`, the same names
+// the NativeScript port publishes. `export * as GtkSource from './namespace/gtksource.js'` in
+// `src/index.ts` makes it the namespace the `gi://GtkSource` arm answers from.
+//
+// A TRUE SUBSET: GtkSource's gutters, completion, search and the rest are absent, and the arm
+// refuses each by name.
+export { Buffer, Language, LanguageManager, StyleScheme, StyleSchemeManager, init } from '@gjsify/gtksource-core';
+export { GtkSourceView as View } from '../gtksource/gtk-source-view.js';

package/src/row-line-clamp.ts

@@ -0,0 +1,74 @@
+// Row line-clamping utilities — shared by adw-action-row, adw-switch-row,
+// adw-combo-row, adw-spin-row, adw-expander-row.
+//
+// The clamping uses the package's established pattern: CSS custom properties
+// (--adw-row-title-lines, --adw-row-subtitle-lines) + a class toggle
+// (.adw-row-clamp on the text container). See gtk-label.ts for the same
+// pattern with --gtk-label-lines and .adw-label-clamp.
+//
+// Upstream semantics (AdwActionRow, AdwExpanderRow):
+//   - title-lines / subtitle-lines default to 0
+//   - 0 = unlimited lines (wrap freely, no ellipsis)
+//   - n > 0 = clamp to n lines with ellipsis
+//   - Negative values are invalid per the pspec (range 0..G_MAXINT) and
+//     treated as 0 (unlimited) — the property system clamps them.
+
+export interface RowLineClampConfig {
+    titleEl: HTMLElement;
+    subtitleEl: HTMLElement;
+    textContainerEl: HTMLElement; // The element that gets .adw-row-clamp
+    getTitleLines: () => number;
+    getSubtitleLines: () => number;
+}
+
+/**
+ * Apply or remove line clamping based on title-lines/subtitle-lines values.
+ * Uses CSS custom properties and class toggle (not inline styles).
+ */
+export function applyRowLineClamp(config: RowLineClampConfig): void {
+    const { titleEl, subtitleEl, textContainerEl, getTitleLines, getSubtitleLines } = config;
+
+    const titleLines = getTitleLines();
+    const subtitleLines = getSubtitleLines();
+
+    const titleClamped = titleLines > 0;
+    const subtitleClamped = subtitleLines > 0;
+    const anyClamped = titleClamped || subtitleClamped;
+
+    // Toggle the clamping class on the text container
+    textContainerEl.classList.toggle('adw-row-clamp', anyClamped);
+
+    // Set custom properties for the clamp line counts
+    if (titleClamped) {
+        titleEl.style.setProperty('--adw-row-title-lines', String(titleLines));
+    } else {
+        titleEl.style.removeProperty('--adw-row-title-lines');
+    }
+
+    if (subtitleClamped) {
+        subtitleEl.style.setProperty('--adw-row-subtitle-lines', String(subtitleLines));
+    } else {
+        subtitleEl.style.removeProperty('--adw-row-subtitle-lines');
+    }
+
+    // The ellipsize overflow is shared (end ellipsis for all non-none modes)
+    // Set it on the text container so the clamp rule can read it
+    if (anyClamped) {
+        textContainerEl.style.setProperty('--adw-row-ellipsize-overflow', 'ellipsis');
+    } else {
+        textContainerEl.style.removeProperty('--adw-row-ellipsize-overflow');
+    }
+}
+
+/**
+ * Parse a lines attribute value following AdwActionRow semantics:
+ * - Missing/null/empty → 0 (unlimited)
+ * - Invalid/non-numeric → 0 (unlimited)
+ * - n > 0 → n (clamp to n lines)
+ * - n <= 0 → 0 (unlimited; pspec range is 0..G_MAXINT)
+ */
+export function parseRowLinesAttribute(value: string | null): number {
+    if (value === null || value === '') return 0;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}