@gjsify/adwaita-core 0.36.0 → 0.37.0

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

@@ -1,12 +1,9 @@
 /**
- * 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.
+ * Input shape for a page. `title` omitted falls back to `name`
+ * ({@link resolvePageTitle}, a deliberate deviation from `add_internal`, which leaves
+ * the title NULL); `icon` is a GTK icon NAME normalized by
+ * {@link normalizeIconName}; `visible` defaults to `true`. `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. */
@@ -27,12 +24,10 @@ export interface AdwViewStackPageSpec<T = unknown> {
     useUnderline?: 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.
+ * 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 switcher code that reads `page.icon.length`
+ * relies on.
  */
 export interface AdwViewStackPageInfo<T = unknown> {
     /** Stable id used by `visible-child-name` and by a bound switcher. */
@@ -64,57 +59,42 @@ export interface ViewStackStateChange<T = unknown> {
     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.
+     * {@link ViewStackState.setVisibleName}, `false` for an auto-pick from `addPage` /
+     * `setPageVisible`. libadwaita notifies on BOTH — the flag lets a switcher suppress
+     * its own feedback loop, not a renderer 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.
+ * The title a page renders with: `title` when given, else the page `name`. A named
+ * function because it is a DEVIATION from C, where `add_internal` stores a NULL title
+ * and a native `AdwViewSwitcher` then renders no label. 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.
+ * A GTK icon name reduced to its renderer-neutral form: `''` for absent or unusable,
+ * and a single anchored `-symbolic` suffix stripped. The strip is end-anchored and
+ * applied ONCE, so `go-symbolic-next` survives intact and `go-next-symbolic-symbolic`
+ * loses only the last suffix.
  *
- * `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 belongs HERE, not in each caller: a name that is not one token
+ * cannot be one CSS class, and interpolating `icon-name="a b"` into
+ * `.adw-icon--<name>` injected a stray `b` class onto the icon node. Unusable names
+ * resolve to "no icon" so the renderer's absent-icon path takes over.
  *
- * 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.
+ * Consequence: a reverse-DNS APPLICATION icon name (`org.gnome.Builder`) is not a
+ * token and normalizes to `''` — it never had a mask class either, since
+ * `.adw-icon--org.gnome.Builder` parses as three classes.
  */
 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.
+ * 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, and holds no
+ * timer or global, so an instance is a plain value a test can drive step by step.
  */
 export declare class ViewStackState<T = unknown> {
     private readonly _pages;
@@ -128,54 +108,45 @@ export declare class ViewStackState<T = unknown> {
     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). */
+    /** `set_visible_child (self, NULL)`'s scan for the first VISIBLE page. */
     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). */
+    /** Number of pages — `adw_view_stack_pages_get_n_items`. */
     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 `===`.
+     * Index of the FIRST page named `name`, or `-1` — `find_page_for_name`. 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.
+     * `adw_view_stack_pages_is_selected`. 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}.
+     * Selects it only when nothing is selected yet AND the page is visible (`add_page`),
+     * notifying with `interactive: false` as C does. A duplicate name is accepted (C
+     * warns but still adds) 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).
+     * `Adw.ViewStack` has no insert-at-position API of its own; this is the
+     * generalisation of {@link addPage} (now `insertPage(spec, count)`) that
+     * `Adw.TabView` needs, whose `attach_page` is `g_list_store_insert` plus the same
+     * auto-select-when-nothing-is-selected rule.
      *
-     * 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.
+     * 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;
@@ -183,26 +154,23 @@ export declare class ViewStackState<T = unknown> {
      * 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.
+     * Remove-then-insert, as `adw_tab_view_reorder_page` and
+     * `adw_tab_view_set_page_pinned` do — 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.
+     * Emits NOTHING: C reorders without calling `set_selected_page`, and only the list
+     * model reports the change (`page-reordered`).
      */
     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.
+     * When the removed page was the visible one the selection becomes `-1` and NOTHING is
+     * emitted: `stack_remove` clears `visible_child` directly and never calls
+     * `set_visible_child`, 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". */
@@ -210,25 +178,22 @@ export declare class ViewStackState<T = unknown> {
     /**
      * 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.
+     * 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, so `1.5` is not a position that can exist. The hidden-page
+     * clause is C's `if (gtk_widget_get_visible (page->widget))`.
      */
     setVisibleIndex(index: number, interactive?: boolean): boolean;
-    /** Name of the visible page, `''` when none — C returns NULL (adw-view-stack.c:2379-2385). */
+    /** Name of the visible page, `''` when none — C returns NULL. */
     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
+     * `null`/`undefined` is a SILENT no-op — C returns before the lookup and therefore
+     * before its warning. An unknown name is a no-op that records a {@link diagnostics}
+     * entry (C's `g_warning`). An EMPTY name is a legal lookup that matches a page
+     * literally named `''`: `find_page_for_name` compares with `g_strcmp0`, which
      * special-cases only NULL.
      */
     setVisibleName(name: string | null | undefined, interactive?: boolean): boolean;
@@ -241,38 +206,31 @@ export declare class ViewStackState<T = unknown> {
      * 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.
+     * Implements `update_child_visible`: making a page visible while NOTHING is selected
+     * selects it; hiding the selected page runs `set_visible_child (self, NULL)`, whose
+     * scan takes the first still-visible page — and selects nothing, notifying with index
+     * `-1`, when there is none. Setting the flag to its current value returns early.
      *
-     * 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.
+     * 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.
+     * 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`. Duplicate names are
+     * legal and first-match-wins, so a `visibleChildName` that 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.
+     * Every diagnostic C would have printed as a `g_warning`, in order — the unknown-name
+     * lookups and the duplicate-name adds. Data rather than stderr so a test can assert on
+     * the class.
      */
     get diagnostics(): readonly string[];
 }