@gjsify/adwaita-web 0.11.0 → 0.13.0

package/src/elements/adw-carousel.ts

@@ -0,0 +1,321 @@
+// <adw-carousel> — a horizontally swipeable pager (the web counterpart of
+// Adw.Carousel). Pages are declared as direct children; the carousel lays them
+// out in a horizontal scroll-snap strip, tracks the fractional scroll position,
+// and exposes a `position` (fractional page index) + `n-pages`, mirroring the
+// AdwCarousel properties. Navigation: drag/scroll-snap (touch + trackpad),
+// optional scroll-wheel paging, and `scroll-to(index)`.
+//
+// Indicators are SEPARATE elements bound to a carousel (exactly as the native
+// Adw.CarouselIndicatorDots / Adw.CarouselIndicatorLines bind to an
+// Adw.Carousel via their `carousel` property): set `el.carousel = carouselEl`
+// or place a `for` attribute referencing the carousel's id. The indicator
+// listens to the carousel's `notify::position` / `notify::n-pages` events and
+// repaints; clicking an indicator scrolls the carousel to that page.
+//
+// adw-carousel
+//   Attributes: allow-scroll-wheel (bool, default present), allow-long-swipes
+//     (bool — a flick can skip multiple pages at once), position (number,
+//     fractional page index — reflected, settable to snap to a page).
+//   Events: `notify::position` (fractional scroll position changed),
+//     `notify::n-pages` (page count changed), `page-changed` (settled on a new
+//     page; `detail = { index }`) — mirroring the AdwCarousel signals the native
+//     story uses.
+// adw-carousel-indicator-dots / adw-carousel-indicator-lines
+//   Properties: carousel (the bound AdwCarousel element), or a `for` attribute
+//     with the carousel element's id.
+//
+// Reference: refs/libadwaita/src/adw-carousel.c (AdwCarousel behaviour)
+// Reference: refs/libadwaita/src/adw-carousel-indicator-dots.c
+//   (DOTS_RADIUS 3, DOTS_RADIUS_SELECTED 4, DOTS_OPACITY 0.3,
+//    DOTS_OPACITY_SELECTED 0.9, DOTS_SPACING 7)
+// Reference: refs/libadwaita/src/adw-carousel-indicator-lines.c
+//   (LINE_WIDTH 3, LINE_LENGTH 35, LINE_SPACING 5,
+//    LINE_OPACITY 0.3, LINE_OPACITY_ACTIVE 0.9)
+// Reference: refs/adwaita-web/adwaita-web/scss/_carousel_indicators.scss
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as Web Components for @gjsify/adwaita-web.
+
+/** Common surface an indicator binds to. The concrete element is AdwCarousel. */
+interface CarouselHost extends HTMLElement {
+    readonly nPages: number;
+    readonly position: number;
+    scrollToPage(index: number): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+}
+
+export class AdwCarousel extends HTMLElement implements CarouselHost {
+    private _trackEl!: HTMLDivElement;
+    private _pages: HTMLElement[] = [];
+    private _position = 0;
+    private _scrollRaf = 0;
+    private _wheelAccum = 0;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['allow-scroll-wheel', 'allow-long-swipes', 'position'];
+    }
+
+    /** Number of pages in the carousel. */
+    get nPages(): number {
+        return this._pages.length;
+    }
+
+    /** Fractional scroll position (0 = first page, 1 = second, …). */
+    get position(): number {
+        return this._position;
+    }
+
+    set position(value: number) {
+        const clamped = Math.min(Math.max(value, 0), Math.max(0, this.nPages - 1));
+        this.scrollToPage(Math.round(clamped));
+    }
+
+    /** Whether the scroll wheel navigates between pages. */
+    get allowScrollWheel(): boolean {
+        return this.hasAttribute('allow-scroll-wheel');
+    }
+
+    set allowScrollWheel(value: boolean) {
+        this.toggleAttribute('allow-scroll-wheel', value);
+    }
+
+    /** Whether a single flick can skip more than one page. */
+    get allowLongSwipes(): boolean {
+        return this.hasAttribute('allow-long-swipes');
+    }
+
+    set allowLongSwipes(value: boolean) {
+        this.toggleAttribute('allow-long-swipes', value);
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        // The declared children become the carousel's pages. Snapshot them
+        // before we move them into the scroll track.
+        this._pages = Array.from(this.children).filter((c): c is HTMLElement => c instanceof HTMLElement);
+
+        this._trackEl = document.createElement('div');
+        this._trackEl.className = 'adw-carousel-track';
+        for (const page of this._pages) {
+            const slot = document.createElement('div');
+            slot.className = 'adw-carousel-page';
+            slot.appendChild(page);
+            this._trackEl.appendChild(slot);
+        }
+        this.replaceChildren(this._trackEl);
+
+        this._trackEl.addEventListener('scroll', this._onScroll, { passive: true });
+        this._trackEl.addEventListener('wheel', this._onWheel, { passive: false });
+
+        // Surface the page count once the DOM is wired so indicators can paint.
+        this.dispatchEvent(new CustomEvent('notify::n-pages', { bubbles: true, detail: { nPages: this.nPages } }));
+        this._emitPosition();
+    }
+
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
+        if (!this._initialized) return;
+        if (name === 'position' && newValue !== null) {
+            const next = Number.parseInt(newValue, 10);
+            if (!Number.isNaN(next) && next !== Math.round(this._position)) this.scrollToPage(next);
+        }
+        // allow-scroll-wheel / allow-long-swipes are read live in the handlers.
+    }
+
+    /** Scroll (snap) to the page at `index`, clamped to the valid range. */
+    scrollToPage(index: number): void {
+        if (!this._trackEl) return;
+        const clamped = Math.min(Math.max(index, 0), Math.max(0, this.nPages - 1));
+        const slot = this._trackEl.children[clamped] as HTMLElement | undefined;
+        if (!slot) return;
+        this._trackEl.scrollTo({ left: slot.offsetLeft, behavior: 'smooth' });
+    }
+
+    private _onScroll = (): void => {
+        if (this._scrollRaf) return;
+        this._scrollRaf = requestAnimationFrame(() => {
+            this._scrollRaf = 0;
+            this._updatePositionFromScroll();
+        });
+    };
+
+    private _onWheel = (event: WheelEvent): void => {
+        if (!this.allowScrollWheel || this.nPages === 0) return;
+        // A horizontal scroll already pans the snap strip natively; only the
+        // vertical wheel needs translating into page steps (mirrors AdwCarousel,
+        // which lets vertical scrolling page a horizontal carousel).
+        if (Math.abs(event.deltaY) <= Math.abs(event.deltaX)) return;
+        event.preventDefault();
+        this._wheelAccum += event.deltaY;
+        const threshold = 40;
+        if (Math.abs(this._wheelAccum) < threshold) return;
+        const step = this._wheelAccum > 0 ? 1 : -1;
+        this._wheelAccum = 0;
+        const current = Math.round(this._position);
+        const target = this.allowLongSwipes ? current + step * 1 : current + step;
+        this.scrollToPage(target);
+    };
+
+    private _updatePositionFromScroll(): void {
+        if (!this._trackEl) return;
+        const slotWidth = this._slotWidth();
+        if (slotWidth <= 0) return;
+        const next = this._trackEl.scrollLeft / slotWidth;
+        const settledBefore = Math.round(this._position);
+        this._position = next;
+        this._emitPosition();
+        const settledAfter = Math.round(next);
+        // Snap landed cleanly on a page boundary → page-changed (within 0.02 of
+        // an integer index, matching a finished scroll-snap).
+        if (settledAfter !== settledBefore && Math.abs(next - settledAfter) < 0.02) {
+            this.dispatchEvent(new CustomEvent('page-changed', { bubbles: true, detail: { index: settledAfter } }));
+        }
+    }
+
+    private _slotWidth(): number {
+        const first = this._trackEl?.children[0] as HTMLElement | undefined;
+        return first ? first.offsetWidth : 0;
+    }
+
+    private _emitPosition(): void {
+        this.dispatchEvent(new CustomEvent('notify::position', { bubbles: true, detail: { position: this._position } }));
+    }
+}
+
+/** Shared base for the dot / line indicator elements. */
+abstract class AdwCarouselIndicator extends HTMLElement {
+    protected _carousel: CarouselHost | null = null;
+    protected _initialized = false;
+
+    static get observedAttributes() {
+        return ['for'];
+    }
+
+    /** The bound carousel. Mirrors AdwCarouselIndicator*'s `carousel` property. */
+    get carousel(): CarouselHost | null {
+        return this._carousel;
+    }
+
+    set carousel(value: CarouselHost | null) {
+        if (value === this._carousel) return;
+        this._detach();
+        this._carousel = value;
+        this._attach();
+    }
+
+    connectedCallback() {
+        this._initialized = true;
+        if (!this._carousel) this._resolveForAttr();
+        this._attach();
+        this._render();
+    }
+
+    disconnectedCallback() {
+        this._detach();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (name === 'for' && this._initialized) {
+            this._detach();
+            this._carousel = null;
+            this._resolveForAttr();
+            this._attach();
+            this._render();
+        }
+    }
+
+    private _resolveForAttr(): void {
+        const id = this.getAttribute('for');
+        if (!id) return;
+        const root = this.getRootNode() as Document | ShadowRoot;
+        const el = root.getElementById?.(id) ?? document.getElementById(id);
+        if (el instanceof AdwCarousel) this._carousel = el;
+    }
+
+    private _attach(): void {
+        if (!this._carousel || !this._initialized) return;
+        this._carousel.addEventListener('notify::position', this._onChange);
+        this._carousel.addEventListener('notify::n-pages', this._onChange);
+        this._render();
+    }
+
+    private _detach(): void {
+        if (!this._carousel) return;
+        this._carousel.removeEventListener('notify::position', this._onChange);
+        this._carousel.removeEventListener('notify::n-pages', this._onChange);
+    }
+
+    private _onChange = (): void => {
+        this._render();
+    };
+
+    protected nPages(): number {
+        return this._carousel?.nPages ?? 0;
+    }
+
+    protected position(): number {
+        return this._carousel?.position ?? 0;
+    }
+
+    protected goTo(index: number): void {
+        this._carousel?.scrollToPage(index);
+    }
+
+    protected abstract _render(): void;
+}
+
+export class AdwCarouselIndicatorDots extends AdwCarouselIndicator {
+    protected _render(): void {
+        renderIndicator(this, 'adw-carousel-dot', this.nPages(), this.position(), (i) => this.goTo(i));
+    }
+}
+
+export class AdwCarouselIndicatorLines extends AdwCarouselIndicator {
+    protected _render(): void {
+        renderIndicator(this, 'adw-carousel-line', this.nPages(), this.position(), (i) => this.goTo(i));
+    }
+}
+
+/**
+ * Shared rebuild for both indicator kinds: one child per page, the marker
+ * closest to the fractional position carries `.active`, and clicking scrolls
+ * the carousel. The dot/line look (size, growth, opacity ramp) is in SCSS; the
+ * `--adw-carousel-progress` custom property carries the per-marker proximity so
+ * the active marker can grow/brighten the way libadwaita lerps between the
+ * inactive and selected states.
+ */
+function renderIndicator(
+    host: HTMLElement,
+    markerClass: string,
+    nPages: number,
+    position: number,
+    onClick: (index: number) => void,
+): void {
+    if (host.childElementCount !== nPages) {
+        const markers: HTMLButtonElement[] = [];
+        for (let i = 0; i < nPages; i++) {
+            const marker = document.createElement('button');
+            marker.type = 'button';
+            marker.className = markerClass;
+            marker.setAttribute('aria-label', `Page ${i + 1}`);
+            marker.addEventListener('click', () => onClick(i));
+            markers.push(marker);
+        }
+        host.replaceChildren(...markers);
+    }
+    Array.from(host.children).forEach((child, i) => {
+        // Proximity in [0,1]: 1 on the focused page, ramping to 0 one page away
+        // (matches AdwCarousel's per-dot lerp progress = 1 - |position - i|).
+        const progress = Math.max(0, 1 - Math.abs(position - i));
+        const marker = child as HTMLElement;
+        marker.style.setProperty('--adw-carousel-progress', progress.toFixed(3));
+        marker.classList.toggle('active', progress > 0.5);
+        marker.setAttribute('aria-current', progress > 0.5 ? 'true' : 'false');
+    });
+}
+
+customElements.define('adw-carousel', AdwCarousel);
+customElements.define('adw-carousel-indicator-dots', AdwCarouselIndicatorDots);
+customElements.define('adw-carousel-indicator-lines', AdwCarouselIndicatorLines);

package/src/elements/adw-clamp.ts

@@ -0,0 +1,28 @@
+// <adw-clamp> — Constrains its child to a maximum width and centers it.
+// Attributes: maximum-size (px, default 600), tightening-threshold (unused;
+//   accepted for API parity with Adw.Clamp).
+// Reference: refs/adwaita-web/adwaita-web/docs/widgets/clamp.md
+// Reference: refs/libadwaita (Adw.Clamp)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+export class AdwClamp extends HTMLElement {
+    static get observedAttributes() {
+        return ['maximum-size'];
+    }
+
+    connectedCallback() {
+        this._sync();
+    }
+
+    attributeChangedCallback() {
+        this._sync();
+    }
+
+    private _sync() {
+        const max = parseFloat(this.getAttribute('maximum-size') || '600');
+        this.style.maxWidth = `${max}px`;
+    }
+}
+
+customElements.define('adw-clamp', AdwClamp);

package/src/elements/adw-combo-row.ts

@@ -1,19 +1,22 @@
-// <adw-combo-row> — Row with a label and dropdown select.
-// Attributes: title, items (JSON string[]), selected (index number)
+// <adw-combo-row> — Row with a title/subtitle and a dropdown select.
+// Attributes: title, subtitle, items (JSON string[]), selected (index number)
 // Events: notify::selected (CustomEvent, mirrors GJS GObject signal naming)
 // The native <select> is stretched invisibly over the row so clicking anywhere opens it.
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
-// Modifications: Reimplemented as Web Component for @gjsify/adwaita-web.
+// Modifications: Reimplemented as Web Component for @gjsify/adwaita-web;
+//   title/subtitle text column added to match Adw.ComboRow.
 
 export class AdwComboRow extends HTMLElement {
     private _select!: HTMLSelectElement;
     private _valueEl!: HTMLSpanElement;
+    private _titleEl!: HTMLSpanElement;
+    private _subtitleEl!: HTMLSpanElement;
     private _items: string[] = [];
     private _initialized = false;
 
     static get observedAttributes() {
-        return ['selected'];
+        return ['title', 'subtitle', 'selected'];
     }
 
     get selected(): number {
@@ -28,20 +31,21 @@ export class AdwComboRow extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const title = this.getAttribute('title') || '';
         this._items = JSON.parse(this.getAttribute('items') || '[]');
         const selectedIdx = parseInt(this.getAttribute('selected') || '0', 10);
 
-        // Title label
-        const titleEl = document.createElement('span');
-        titleEl.className = 'adw-row-title';
-        titleEl.textContent = title;
+        const text = document.createElement('div');
+        text.className = 'adw-row-text';
+        this._titleEl = document.createElement('span');
+        this._titleEl.className = 'adw-row-title';
+        this._subtitleEl = document.createElement('span');
+        this._subtitleEl.className = 'adw-row-subtitle';
+        text.append(this._titleEl, this._subtitleEl);
 
         // Visible selected value display
-        const valueEl = document.createElement('span');
-        valueEl.className = 'adw-row-value';
-        valueEl.textContent = this._items[selectedIdx] ?? '';
-        this._valueEl = valueEl;
+        this._valueEl = document.createElement('span');
+        this._valueEl.className = 'adw-row-value';
+        this._valueEl.textContent = this._items[selectedIdx] ?? '';
 
         // Hidden select overlaying the entire row
         const select = document.createElement('select');
@@ -53,9 +57,7 @@ export class AdwComboRow extends HTMLElement {
             select.appendChild(option);
         });
 
-        this.appendChild(titleEl);
-        this.appendChild(valueEl);
-        this.appendChild(select);
+        this.replaceChildren(text, this._valueEl, select);
 
         this._select = select;
         this._select.addEventListener('change', () => {
@@ -69,17 +71,27 @@ export class AdwComboRow extends HTMLElement {
                 }),
             );
         });
+
+        this._renderText();
     }
 
     attributeChangedCallback(name: string, _old: string | null, value: string | null) {
-        if (name === 'selected' && this._select) {
+        if (!this._initialized) return;
+        if (name === 'selected') {
             const idx = parseInt(value || '0', 10);
             this._select.selectedIndex = idx;
-            if (this._valueEl) {
-                this._valueEl.textContent = this._items[idx] ?? '';
-            }
+            this._valueEl.textContent = this._items[idx] ?? '';
+        } else {
+            this._renderText();
         }
     }
+
+    private _renderText() {
+        this._titleEl.textContent = this.getAttribute('title') ?? '';
+        const subtitle = this.getAttribute('subtitle') ?? '';
+        this._subtitleEl.textContent = subtitle;
+        this._subtitleEl.hidden = subtitle.length === 0;
+    }
 }
 
 customElements.define('adw-combo-row', AdwComboRow);

package/src/elements/adw-entry-row.ts

@@ -0,0 +1,69 @@
+// <adw-entry-row> — A boxed-list row that is itself a text entry: the title
+// floats as a label and the editable text sits inline on the row.
+// Attributes: title, text.
+// Property: text (get/set, proxies the inner input).
+// Events: `changed` (CustomEvent) on every edit — mirrors Adw.EntryRow's
+//   `changed` signal so it drives the same code path as the GTK renderer.
+// Reference: refs/adwaita-web/adwaita-web/docs/widgets/entryrow.md
+// Reference: refs/libadwaita/src/stylesheet/widgets/_entries.scss
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+export class AdwEntryRow extends HTMLElement {
+    private _input!: HTMLInputElement;
+    private _titleEl!: HTMLSpanElement;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['title', 'text'];
+    }
+
+    get text(): string {
+        return this._input ? this._input.value : (this.getAttribute('text') ?? '');
+    }
+
+    set text(value: string) {
+        if (this._input) this._input.value = value;
+        else this.setAttribute('text', value);
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        this._titleEl = document.createElement('span');
+        this._titleEl.className = 'adw-row-title';
+        this._titleEl.textContent = this.getAttribute('title') ?? '';
+
+        this._input = document.createElement('input');
+        this._input.className = 'adw-entry-row-input';
+        this._input.type = 'text';
+        this._input.value = this.getAttribute('text') ?? '';
+        this._input.addEventListener('input', () => {
+            this.dispatchEvent(new CustomEvent('changed', { bubbles: true, detail: { text: this._input.value } }));
+        });
+
+        // Title floats as a small label above the value (the filled
+        // Adw.EntryRow look), both left-aligned in a text column.
+        const text = document.createElement('div');
+        text.className = 'adw-entry-row-text';
+        text.append(this._titleEl, this._input);
+
+        // Trailing edit affordance, mirroring Adw.EntryRow's pencil; clicking
+        // it focuses the entry.
+        const edit = document.createElement('span');
+        edit.className = 'adw-row-edit adw-icon adw-icon--document-edit';
+        edit.setAttribute('aria-hidden', 'true');
+        edit.addEventListener('click', () => this._input.focus());
+
+        this.replaceChildren(text, edit);
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'title') this._titleEl.textContent = value ?? '';
+        else if (name === 'text' && this._input.value !== (value ?? '')) this._input.value = value ?? '';
+    }
+}
+
+customElements.define('adw-entry-row', AdwEntryRow);

package/src/elements/adw-entry.ts

@@ -0,0 +1,61 @@
+// <adw-entry> — Adwaita single-line text entry (e.g. a browser URL bar).
+// Attributes: value, placeholder, type, disabled.
+// Property: value (get/set, proxies the inner input).
+// Events: native `input` bubbles from the inner input; `activate` (CustomEvent)
+//   fires on Enter — mirroring Gtk.Entry's `activate` signal.
+// Reference: refs/libadwaita/src/stylesheet/widgets/_entries.scss
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+export class AdwEntry extends HTMLElement {
+    private _input!: HTMLInputElement;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['value', 'placeholder', 'type', 'disabled'];
+    }
+
+    get value(): string {
+        return this._input ? this._input.value : (this.getAttribute('value') ?? '');
+    }
+
+    set value(v: string) {
+        if (this._input) this._input.value = v;
+        else this.setAttribute('value', v);
+    }
+
+    /** The inner native input (for focus/selection). */
+    get input(): HTMLInputElement {
+        return this._input;
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        const input = document.createElement('input');
+        input.className = 'adw-entry';
+        input.type = this.getAttribute('type') || 'text';
+        input.value = this.getAttribute('value') ?? '';
+        input.placeholder = this.getAttribute('placeholder') ?? '';
+        input.disabled = this.hasAttribute('disabled');
+        input.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter') {
+                this.dispatchEvent(new CustomEvent('activate', { bubbles: true, detail: { value: input.value } }));
+            }
+        });
+
+        this._input = input;
+        this.replaceChildren(input);
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._input) return;
+        if (name === 'value') this._input.value = value ?? '';
+        else if (name === 'placeholder') this._input.placeholder = value ?? '';
+        else if (name === 'type') this._input.type = value || 'text';
+        else if (name === 'disabled') this._input.disabled = value !== null;
+    }
+}
+
+customElements.define('adw-entry', AdwEntry);