@gjsify/adwaita-core 0.31.0 → 0.32.0

package/lib/types/view-stack.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Input shape for a page.
+ *
+ * `title` omitted falls back to `name` ({@link resolvePageTitle} — a deliberate
+ * deviation from `add_internal`, adw-view-stack.c:1170-1172, which leaves the
+ * title NULL); `icon` is a GTK icon NAME (`PAGE_PROP_ICON_NAME`, :393-396)
+ * normalized by {@link normalizeIconName}; `visible` defaults to `true`
+ * (`adw_view_stack_page_init`, :475-479). `content` is the renderer's opaque
+ * node — an `HTMLElement` on web, a NativeScript `View` on NS.
+ */
+export interface AdwViewStackPageSpec<T = unknown> {
+    /** Stable id used by `visible-child-name` and by a bound switcher. */
+    name: string;
+    /** Human-facing title; falls back to `name` when absent. `null` is absent — it is what `getAttribute` returns. */
+    title?: string | null;
+    /** GTK icon name; a single trailing `-symbolic` is stripped. `null` is absent. */
+    icon?: string | null;
+    /** The renderer's page node. */
+    content?: T;
+    /** Whether the page participates in selection at all. Defaults to `true`. */
+    visible?: boolean;
+}
+/**
+ * A resolved page descriptor, as a bound switcher reads it.
+ *
+ * `title` and `icon` are already normalized so no renderer repeats the fallback,
+ * and `icon` is `''` when absent — never `undefined`, which is what the web
+ * switcher bar's `page.icon.length` has always assumed and the NS port used to
+ * violate.
+ */
+export interface AdwViewStackPageInfo<T = unknown> {
+    /** Stable id used by `visible-child-name` and by a bound switcher. */
+    readonly name: string;
+    /** Human-facing title, already resolved against `name`. */
+    readonly title: string;
+    /** Normalized GTK icon name, `''` when the page has none. */
+    readonly icon: string;
+    /** The renderer's page node, `undefined` for a headless page. */
+    readonly content: T | undefined;
+    /** Whether the page can be selected — `AdwViewStackPage:visible`. */
+    readonly visible: boolean;
+}
+/** Payload of a selection change. */
+export interface ViewStackStateChange<T = unknown> {
+    /** Index of the newly-visible page, `-1` when nothing is selected. */
+    index: number;
+    /** Its name, `''` when nothing is selected. */
+    name: string;
+    /** Its title, `''` when nothing is selected. */
+    title: string;
+    /** Its descriptor, `undefined` when nothing is selected. */
+    page: AdwViewStackPageInfo<T> | undefined;
+    /**
+     * `true` for an explicit {@link ViewStackState.setVisibleIndex} /
+     * {@link ViewStackState.setVisibleName}; `false` for an auto-pick from
+     * `addPage` / `setPageVisible`. libadwaita notifies on BOTH
+     * (adw-view-stack.c:1038-1039) — the flag exists so a switcher can suppress
+     * its own feedback loop, not so a renderer can drop the notification.
+     */
+    interactive: boolean;
+}
+/** Subscriber for {@link ViewStackState} changes. */
+export type ViewStackStateListener<T = unknown> = (change: ViewStackStateChange<T>) => void;
+/**
+ * The title a page renders with: `title` when given, else the page `name`.
+ *
+ * Pinned as a named function precisely because it is a DEVIATION from C —
+ * `add_internal` (adw-view-stack.c:1170-1172) stores a NULL title and a native
+ * `AdwViewSwitcher` then renders no label. Both ports independently chose the
+ * name fallback; this makes it ONE documented decision instead of two
+ * coincidentally-identical `title ?? name` expressions. An explicitly empty
+ * title stays empty — only an absent one falls back.
+ */
+export declare function resolvePageTitle(title: string | null | undefined, name: string): string;
+/**
+ * A GTK icon name reduced to its renderer-neutral form: `''` for absent or
+ * unusable, and a single anchored `-symbolic` suffix stripped.
+ *
+ * `AdwViewStackPage:icon-name` is a NAME string (adw-view-stack.c:393-396,
+ * :1887-1912), not markup. The strip is end-anchored and applied ONCE, so
+ * `go-symbolic-next` survives intact and `go-next-symbolic-symbolic` loses only
+ * the last suffix.
+ *
+ * THE TOKEN GUARD IS PART OF THE NORMALIZATION, not the caller's job. It had
+ * been written exactly once — in `<adw-split-button>` — while the other 22
+ * `.adw-icon--<name>` construction sites in `@gjsify/adwaita-web` built the
+ * class without it, so `icon-name="a b"` interpolated into
+ * `class="adw-icon adw-icon--a b"` and injected a stray `b` class onto the icon
+ * node. That was live on `<adw-menu-button>`, for its own icon AND for every
+ * JSON menu entry's. A name that cannot be one token cannot be one class, so it
+ * resolves to "no icon" and the renderer's absent-icon path takes over.
+ *
+ * Consequence worth knowing: a reverse-DNS APPLICATION icon name
+ * (`org.gnome.Builder`) is not a token and normalizes to `''`. It never had a
+ * mask class either — `.adw-icon--org.gnome.Builder` parses as three classes —
+ * so this turns a silently blank icon into an explicitly absent one.
+ */
+export declare function normalizeIconName(icon: string | null | undefined): string;
+/**
+ * The ordered page list of an `Adw.ViewStack` plus its visible-child selection,
+ * with the C guard / ordering / fallback rules applied once for every renderer.
+ *
+ * `T` is the renderer's page-content type; the state machine never looks inside
+ * it. Nothing here is a timer or a global, so an instance is a plain value a
+ * test can drive step by step.
+ */
+export declare class ViewStackState<T = unknown> {
+    private readonly _pages;
+    private _visibleIndex;
+    private readonly _listeners;
+    private readonly _diagnostics;
+    /** Cached frozen projection of {@link pages}; dropped on any structural change. */
+    private _pagesView;
+    /** Subscribe to selection changes. Returns an unsubscribe function. */
+    subscribe(listener: ViewStackStateListener<T>): () => void;
+    private _emit;
+    /** Bounds-safe lookup — indexing is not enough, `_visibleIndex` is `-1` when empty. */
+    private _pageAt;
+    /** `set_visible_child (self, NULL)`'s scan for the first VISIBLE page (adw-view-stack.c:961-974). */
+    private _firstVisibleIndex;
+    private _record;
+    /** All pages in add order — a frozen projection, so a switcher cannot mutate the model. */
+    get pages(): readonly AdwViewStackPageInfo<T>[];
+    /** Number of pages — `adw_view_stack_pages_get_n_items` (adw-view-stack.c:582-588). */
+    get count(): number;
+    /**
+     * Index of the FIRST page named `name`, or `-1` — `find_page_for_name`
+     * (adw-view-stack.c:891-906). An exact, unnormalized compare: `g_strcmp0`
+     * walks UTF-8 bytes, so the NFC and NFD spellings of a name are different
+     * names in C exactly as they are under JS `===`.
+     */
+    indexOfName(name: string): number;
+    /**
+     * Whether the page at `position` is the selected one —
+     * `adw_view_stack_pages_is_selected` (adw-view-stack.c:659-672). An
+     * out-of-range position is simply not selected, never an error.
+     */
+    isSelected(position: number): boolean;
+    /**
+     * Append a page and return its descriptor.
+     *
+     * Selects it only when nothing is selected yet AND the page is visible
+     * (`add_page`, adw-view-stack.c:1149-1151), notifying `interactive: false`
+     * — which is what C does (:1038-1039) and what both ports skipped, forcing
+     * every bound switcher to call `refresh()` by hand. A duplicate name is
+     * accepted (C warns but still adds, :1115-1126 + :1136) and recorded in
+     * {@link duplicateNames}.
+     */
+    addPage(spec: AdwViewStackPageSpec<T>): AdwViewStackPageInfo<T>;
+    /**
+     * Insert a page at `position`, or `null` when `position` is not an integer in
+     * `[0, count]`.
+     *
+     * `Adw.ViewStack` has no insert-at-position API of its own — this is the
+     * generalisation of {@link addPage}, which is now `insertPage(spec, count)`,
+     * so there is ONE insertion path rather than two that can drift. It exists
+     * because `Adw.TabView` is an ordered page list with the same
+     * selection-follows-the-page semantics and needs it: `attach_page` is
+     * literally `g_list_store_insert (self->children, position, page)`
+     * (adw-tab-view.c:1748), and `insert_page` then auto-selects the new page
+     * when nothing is selected (:1953-1954) — the same rule `add_page` applies
+     * here (adw-view-stack.c:1149-1151).
+     *
+     * Inserting BEFORE the current selection shifts that selection's index up by
+     * one and notifies nothing: C holds a page pointer, so the selected page is
+     * unchanged and only its position moved.
+     */
+    insertPage(spec: AdwViewStackPageSpec<T>, position: number): AdwViewStackPageInfo<T> | null;
+    private _insertRecord;
+    /**
+     * Move the page at `from` to index `to`, keeping the SELECTION on whichever
+     * page it was already on. Returns whether anything moved.
+     *
+     * Remove-then-insert, exactly as `adw_tab_view_reorder_page` does
+     * (adw-tab-view.c:4553-4556) and as `adw_tab_view_set_page_pinned` does when
+     * it re-orders a page across the pinned boundary (:4065-4073) — so `to` is an
+     * index in the list WITHOUT the moved page, which is what makes
+     * `set_page_pinned`'s `new_pos = n_pinned_pages` land where C lands.
+     *
+     * Emits NOTHING: C reorders without ever calling `set_selected_page`, and
+     * only the list model reports the change (`page-reordered`, :4561). A caller
+     * that needs to hear about it owns that observable.
+     */
+    movePage(from: number, to: number): boolean;
+    /**
+     * Remove the first page named `name`. Returns whether anything was removed.
+     *
+     * When the removed page was the visible one the selection becomes `-1` and
+     * NOTHING is emitted: `stack_remove` clears `visible_child` directly
+     * (adw-view-stack.c:1202-1203) and never calls `set_visible_child` on that
+     * path, so there is no re-pick and no notification. Removing any OTHER page
+     * keeps the same page selected — C holds a pointer, so the selection follows
+     * the page and only its index shifts.
+     */
+    removePage(name: string): boolean;
+    /** Index of the visible page, `-1` when none — distinct from "page 0 is selected". */
+    get visibleIndex(): number;
+    /**
+     * Select by index. Returns whether the selection changed.
+     *
+     * Rejects — as a silent no-op that emits nothing — a non-integer, a
+     * negative, an out-of-range, the already-selected, and a non-`visible`
+     * index. `Number.isInteger` rather than `Number.isFinite` is the point:
+     * `adw_view_stack_pages_select_item` takes a `guint` position
+     * (adw-view-stack.c:675-683), so `1.5` is not a position that can exist —
+     * both ports used to accept it and blank the entire stack. The hidden-page
+     * clause is `if (gtk_widget_get_visible (page->widget))` at :2367.
+     */
+    setVisibleIndex(index: number, interactive?: boolean): boolean;
+    /** Name of the visible page, `''` when none — C returns NULL (adw-view-stack.c:2379-2385). */
+    get visibleName(): string;
+    /**
+     * Select by name. Returns whether the selection changed.
+     *
+     * `null`/`undefined` is a SILENT no-op — C returns before the lookup and
+     * therefore before its warning (adw-view-stack.c:2404-2405). An unknown name
+     * is a no-op that records a {@link diagnostics} entry (C's `g_warning` at
+     * :2410). An EMPTY name is a legal lookup that matches a page literally
+     * named `''`: `find_page_for_name` compares with `g_strcmp0` (:901), which
+     * special-cases only NULL.
+     */
+    setVisibleName(name: string | null | undefined, interactive?: boolean): boolean;
+    /** The visible page's descriptor, or `undefined` — renderers read `.content` off it. */
+    get visiblePage(): AdwViewStackPageInfo<T> | undefined;
+    /** Title of the visible page, `''` when none — what a header bar mirrors. */
+    get visibleTitle(): string;
+    /**
+     * Flip a page's `visible` flag. Returns whether the SELECTION moved (not
+     * whether the flag changed) — the renderer already knows it asked for the
+     * flip; what it cannot derive is the fallback.
+     *
+     * Implements `update_child_visible` (adw-view-stack.c:1061-1082): making a
+     * page visible while NOTHING is selected selects it (:1069-1070); hiding the
+     * selected page runs `set_visible_child (self, NULL)`, whose scan takes the
+     * first still-visible page (:961-974) — and selects nothing, notifying with
+     * index `-1`, when there is none. Setting the flag to its current value
+     * returns early, as `adw_view_stack_page_set_visible` does.
+     *
+     * DEVIATION, deliberate: C keeps TWO flags (`AdwViewStackPage:visible` and
+     * the child widget's own `gtk_widget_get_visible`) and its NULL-scan
+     * consults only the widget one, so clearing `page->visible` on a page that
+     * is FIRST in the list re-picks that same page and returns without
+     * notifying. A renderer has one notion of "shown", so this collapses to one
+     * flag — matching C's `gtk_widget_set_visible (child, FALSE)` path, where
+     * the scan does skip the hidden page.
+     */
+    setPageVisible(name: string, visible: boolean): boolean;
+    /**
+     * Names that occur more than once in the CURRENT page list, in the order
+     * their first repeat was added.
+     *
+     * The mechanism replacing C's `g_warning` (adw-view-stack.c:1122, :1789):
+     * duplicate names are legal and first-match-wins, but a developer whose
+     * `visibleChildName` silently resolves to the wrong page needs the class to
+     * be visible somewhere. Derived from the model rather than logged, so
+     * removing the duplicate clears it.
+     */
+    get duplicateNames(): readonly string[];
+    /**
+     * Every diagnostic C would have printed as a `g_warning`, in order — the
+     * unknown-name lookups and the duplicate-name adds. Both ports swallow these
+     * entirely; keeping them as data lets a test assert on the class instead of
+     * on stderr.
+     */
+    get diagnostics(): readonly string[];
+}

package/lib/types/view-stack.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;