@gjsify/adwaita-web 0.13.2 → 0.15.1

package/src/elements/adw-view-stack.ts

@@ -0,0 +1,174 @@
+// <adw-view-stack> — A standalone, named-page CONTENT container: the web
+// counterpart of Adw.ViewStack decoupled from any switcher. It holds a set of
+// named pages and shows exactly one at a time; a paired <adw-view-switcher-bar>
+// (or an adaptive header-bar switcher) binds to it and drives the selection.
+// This is the piece the web package lacked — it already had switchers that own
+// their own pages (<adw-view-switcher>, <adw-inline-view-switcher>) but no
+// standalone stack a separate switcher can drive.
+//
+// Pages are declared as <adw-view-stack-page> children with `name`, `title` and
+// `icon-name` attributes (their own children become the page body), OR added
+// imperatively with `add(content, name, title?, icon?)`. The first page added
+// is shown automatically.
+//
+// Attributes:
+//   visible-child-name — the name of the page to show. Reading/writing it stays
+//     in sync with the `visibleChildName` property so an adaptive layout can
+//     drive the stack declaratively (mirrors the Adw.ViewStack GObject prop).
+// Properties (mirroring Adw.ViewStack):
+//   pages               — readonly page descriptors ({ name, title, icon, element }).
+//   visibleChildName    — name of the visible page ('' when empty).
+//   visibleChildIndex   — zero-based index of the visible page (bounds-guarded).
+//   visibleChild        — the visible page's content element (or null).
+// Methods:
+//   add(content, name, title?, icon?) — append a page; returns its descriptor.
+//   addTitled(content, name, title)   — Adw.ViewStack.add_titled convenience.
+// Events:
+//   `notify::visible-child` (CustomEvent, bubbles, detail = { index, name, title })
+//     when the visible page CHANGES — mirrors Adw.ViewStack's visible-child
+//     notify. It does NOT fire for the initial/auto-shown page or on add().
+// Reference: refs/libadwaita/src/adw-view-stack.c (AdwViewStack behaviour)
+// Reference: packages/nativescript-bridge/adwaita/src/widgets/adw-view-stack.ts (NS twin)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+/** A page descriptor exposed via `pages` (consumed by a bound switcher bar). */
+export interface AdwViewStackPageInfo {
+    /** Stable id used by visibleChildName + switcher binding. */
+    name: string;
+    /** Human-facing title shown by a bound switcher. */
+    title: string;
+    /** Symbolic icon name (no `-symbolic` suffix), or '' for none. */
+    icon: string;
+    /** The page's content container (the visibility-toggled node). */
+    element: HTMLElement;
+}
+
+export class AdwViewStack extends HTMLElement {
+    private _pages: AdwViewStackPageInfo[] = [];
+    private _visibleIndex = 0;
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['visible-child-name'];
+    }
+
+    /** All pages in declaration/add order. A bound switcher reads this. */
+    get pages(): readonly AdwViewStackPageInfo[] {
+        return this._pages;
+    }
+
+    /** Zero-based index of the visible page. Out-of-range/same values no-op. */
+    get visibleChildIndex(): number {
+        return this._visibleIndex;
+    }
+
+    set visibleChildIndex(value: number) {
+        if (!Number.isFinite(value) || value < 0 || value >= this._pages.length) return;
+        if (value === this._visibleIndex) return;
+        this._visibleIndex = value;
+        this._apply(true);
+    }
+
+    /** Name of the visible page, or '' when the stack is empty. */
+    get visibleChildName(): string {
+        return this._pages[this._visibleIndex]?.name ?? '';
+    }
+
+    set visibleChildName(name: string) {
+        const index = this._pages.findIndex((p) => p.name === name);
+        if (index >= 0) this.visibleChildIndex = index;
+    }
+
+    /** The visible page's content element, or null when empty. */
+    get visibleChild(): HTMLElement | null {
+        return this._pages[this._visibleIndex]?.element ?? null;
+    }
+
+    connectedCallback() {
+        if (this._initialized) return;
+        this._initialized = true;
+
+        // Snapshot the declared <adw-view-stack-page> children before we take
+        // over the subtree — their name / title / icon-name + child nodes become
+        // the pages. Wrapping each page's content lets us toggle exactly one.
+        const declared = Array.from(this.querySelectorAll(':scope > adw-view-stack-page')) as HTMLElement[];
+        const wrappers = declared.map((pageEl, index) => {
+            const name = pageEl.getAttribute('name') ?? `page-${index}`;
+            const title = pageEl.getAttribute('title') ?? name;
+            const icon = (pageEl.getAttribute('icon-name') ?? '').replace(/-symbolic$/, '');
+            const element = document.createElement('div');
+            element.className = 'adw-view-stack-child';
+            element.dataset.name = name;
+            for (const child of Array.from(pageEl.childNodes)) element.appendChild(child);
+            return { name, title, icon, element };
+        });
+
+        this._pages = wrappers;
+        this.replaceChildren(...wrappers.map((p) => p.element));
+
+        // A declared `visible-child-name` selects the initial page; otherwise the
+        // first page is auto-visible (matching Adw.ViewStack + the NS twin).
+        const initialName = this.getAttribute('visible-child-name');
+        const initialIndex = initialName ? this._pages.findIndex((p) => p.name === initialName) : -1;
+        this._visibleIndex = initialIndex >= 0 ? initialIndex : 0;
+        this._apply(false);
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'visible-child-name' && value !== null && value !== this.visibleChildName) {
+            this.visibleChildName = value;
+        }
+    }
+
+    /**
+     * Append a page. The FIRST page added becomes visible automatically; later
+     * pages are added hidden. Mirrors Adw.ViewStack.add()/the NS twin's add().
+     */
+    add(content: HTMLElement, name: string, title?: string, icon?: string): AdwViewStackPageInfo {
+        content.classList.add('adw-view-stack-child');
+        content.dataset.name = name;
+        const page: AdwViewStackPageInfo = {
+            name,
+            title: title ?? name,
+            icon: (icon ?? '').replace(/-symbolic$/, ''),
+            element: content,
+        };
+        this._pages.push(page);
+        this.appendChild(content);
+        // Keep exactly one page shown without emitting (add is not a user change).
+        this._apply(false);
+        return page;
+    }
+
+    /** Convenience alias mirroring Adw.ViewStack.add_titled() (no icon). */
+    addTitled(content: HTMLElement, name: string, title: string): AdwViewStackPageInfo {
+        return this.add(content, name, title);
+    }
+
+    private _apply(emit: boolean): void {
+        this._pages.forEach((page, index) => {
+            const isVisible = index === this._visibleIndex;
+            page.element.classList.toggle('active-view', isVisible);
+            page.element.hidden = !isVisible;
+        });
+        // Reflect the current selection to the attribute (without re-entering the
+        // guarded callback — the value already matches, so it no-ops).
+        const current = this.visibleChildName;
+        if (current && this.getAttribute('visible-child-name') !== current) {
+            this.setAttribute('visible-child-name', current);
+        }
+        if (emit) {
+            const page = this._pages[this._visibleIndex];
+            this.dispatchEvent(
+                new CustomEvent('notify::visible-child', {
+                    bubbles: true,
+                    detail: { index: this._visibleIndex, name: page?.name ?? '', title: page?.title ?? '' },
+                }),
+            );
+        }
+    }
+}
+
+customElements.define('adw-view-stack', AdwViewStack);

package/src/elements/adw-view-switcher-bar.ts

@@ -0,0 +1,168 @@
+// <adw-view-switcher-bar> — The narrow BOTTOM bar of icon-over-label buttons
+// bound to an <adw-view-stack>, the web counterpart of Adw.ViewSwitcherBar. It
+// owns no pages of its own: it reads the bound stack's `pages`, renders one
+// homogeneous icon-over-label button per page, and is two-way synced to the
+// stack's visible child — tapping a button sets the stack's visible page, and a
+// change to the stack (from anywhere) re-highlights the matching button. The
+// active button's label is accent-coloured (via the `.active` CSS class).
+//
+// A `revealed` flag lets an adaptive layout flip the bar on/off: shown on narrow
+// screens, hidden on wide ones where a header-bar <adw-view-switcher> takes over
+// (mirrors Adw.ViewSwitcherBar `reveal` driven by an Adw.Breakpoint).
+//
+// Attributes:
+//   stack     — the id of the <adw-view-stack> to drive (like <label for>).
+//   revealed  — boolean; when absent the bar is hidden (matches `reveal`).
+// Properties (mirroring Adw.ViewSwitcherBar):
+//   stack     — the bound AdwViewStack element (get/set; set also accepts an id).
+//   revealed  — whether the bar is shown (get/set).
+// Methods:
+//   setStack(stack) — bind to a stack element (or null); rebuilds the buttons.
+//   refresh()       — rebuild the buttons after late page adds to the stack.
+// Reference: refs/libadwaita/src/adw-view-switcher-bar.c (AdwViewSwitcherBar)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_view-switcher.scss (.narrow policy)
+// Reference: packages/nativescript-bridge/adwaita/src/widgets/adw-view-switcher-bar.ts (NS twin)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import type { AdwViewStack } from './adw-view-stack.js';
+
+export class AdwViewSwitcherBar extends HTMLElement {
+    private _barEl!: HTMLDivElement;
+    private _buttons: HTMLButtonElement[] = [];
+    private _stack: AdwViewStack | null = null;
+    private _revealed = false;
+    private _initialized = false;
+    private _onStackNotify = (): void => this._syncActive();
+
+    static get observedAttributes() {
+        return ['stack', 'revealed'];
+    }
+
+    /** The bound stack element, or null when unbound. */
+    get stack(): AdwViewStack | null {
+        return this._stack;
+    }
+
+    set stack(value: AdwViewStack | string | null) {
+        this.setStack(this._resolveStack(value));
+    }
+
+    /** Whether the bar is revealed (shown). Hidden when false. */
+    get revealed(): boolean {
+        return this._revealed;
+    }
+
+    set revealed(value: boolean) {
+        if (value) this.setAttribute('revealed', '');
+        else this.removeAttribute('revealed');
+    }
+
+    connectedCallback() {
+        if (!this._initialized) {
+            this._initialized = true;
+            this._barEl = document.createElement('div');
+            this._barEl.className = 'adw-view-switcher-bar-box';
+            this._barEl.setAttribute('role', 'tablist');
+            this.replaceChildren(this._barEl);
+        }
+        this._revealed = this.hasAttribute('revealed');
+        this._applyRevealed();
+        // Resolve the `stack` id ref now that the element is in the document — the
+        // referenced stack is normally earlier in the DOM (content above a bottom
+        // bar), so its pages are ready.
+        const ref = this.getAttribute('stack');
+        if (ref && !this._stack) this.setStack(this._resolveStack(ref));
+        else this._syncActive();
+    }
+
+    disconnectedCallback() {
+        if (this._stack) this._stack.removeEventListener('notify::visible-child', this._onStackNotify);
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, value: string | null) {
+        if (!this._initialized) return;
+        if (name === 'revealed') {
+            this._revealed = this.hasAttribute('revealed');
+            this._applyRevealed();
+            return;
+        }
+        if (name === 'stack') {
+            this.setStack(this._resolveStack(value));
+        }
+    }
+
+    /** Bind to a stack element (or null). Unbinds the previous one and rebuilds. */
+    setStack(stack: AdwViewStack | null): void {
+        if (this._stack) this._stack.removeEventListener('notify::visible-child', this._onStackNotify);
+        this._stack = stack;
+        if (stack) stack.addEventListener('notify::visible-child', this._onStackNotify);
+        this._rebuild();
+    }
+
+    /** Rebuild the buttons — call after adding pages to the bound stack. */
+    refresh(): void {
+        this._rebuild();
+    }
+
+    private _resolveStack(value: AdwViewStack | string | null): AdwViewStack | null {
+        if (value === null) return null;
+        if (typeof value === 'string') {
+            return (document.getElementById(value) as AdwViewStack | null) ?? null;
+        }
+        return value;
+    }
+
+    private _rebuild(): void {
+        if (!this._initialized) return;
+        this._barEl.replaceChildren();
+        this._buttons = [];
+        const pages = this._stack?.pages ?? [];
+
+        pages.forEach((page, index) => {
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.className = 'adw-view-switcher-bar-button';
+            button.setAttribute('role', 'tab');
+
+            const iconEl = document.createElement('span');
+            iconEl.className = `adw-icon adw-view-switcher-bar-icon${page.icon ? ` adw-icon--${page.icon}` : ''}`;
+            iconEl.setAttribute('aria-hidden', 'true'); // decorative (mask-image only)
+            iconEl.hidden = page.icon.length === 0;
+
+            const labelEl = document.createElement('span');
+            labelEl.className = 'adw-view-switcher-bar-label';
+            labelEl.textContent = page.title;
+            labelEl.hidden = page.title.length === 0;
+
+            button.append(iconEl, labelEl);
+            // An icon-only button (no title) needs an accessible name.
+            if (page.icon && !page.title) button.setAttribute('aria-label', page.icon);
+
+            button.addEventListener('click', () => {
+                if (this._stack) this._stack.visibleChildIndex = index;
+            });
+
+            this._barEl.appendChild(button);
+            this._buttons.push(button);
+        });
+
+        this._syncActive();
+    }
+
+    private _syncActive(): void {
+        const selected = this._stack?.visibleChildIndex ?? -1;
+        this._buttons.forEach((button, index) => {
+            const isActive = index === selected;
+            button.classList.toggle('active', isActive);
+            button.setAttribute('aria-selected', String(isActive));
+            button.tabIndex = isActive ? 0 : -1;
+        });
+    }
+
+    private _applyRevealed(): void {
+        this.hidden = !this._revealed;
+    }
+}
+
+customElements.define('adw-view-switcher-bar', AdwViewSwitcherBar);

package/src/index.ts

@@ -53,6 +53,11 @@ export { AdwCarousel, AdwCarouselIndicatorDots, AdwCarouselIndicatorLines } from
 export { AdwTabPage, AdwTabView } from './elements/adw-tab-view.js';
 export { AdwViewSwitcher, AdwViewSwitcherPage } from './elements/adw-view-switcher.js';
 export { AdwInlineViewSwitcher, AdwViewStackPage } from './elements/adw-inline-view-switcher.js';
+export { AdwViewStack } from './elements/adw-view-stack.js';
+export type { AdwViewStackPageInfo } from './elements/adw-view-stack.js';
+export { AdwViewSwitcherBar } from './elements/adw-view-switcher-bar.js';
+export { AdwMenuButton } from './elements/adw-menu-button.js';
+export type { AdwMenuItem } from './elements/adw-menu-button.js';
 export { AdwNavigationPage, AdwNavigationView } from './elements/adw-navigation-view.js';
 export { AdwBottomSheet, AdwBottomSheetContent, AdwBottomSheetSheet } from './elements/adw-bottom-sheet.js';
 export { AdwSidebar, AdwSidebarItem, AdwSidebarSection } from './elements/adw-sidebar.js';