@gjsify/adwaita-core 0.31.0 → 0.33.0

package/lib/types/conformance/tab-view.d.ts

@@ -0,0 +1,449 @@
+/** A page as a vector declares it. */
+export interface TabViewVectorPage {
+    /** The page id — the platform-neutral stand-in for the `AdwTabPage` pointer. */
+    id: string;
+    /** Tab label; omitted means `''`. */
+    title?: string;
+    /** Whether the page is seeded into the pinned prefix. */
+    pinned?: boolean;
+    /** Id of the page this one was opened from (`AdwTabPage:parent`). */
+    parentId?: string;
+}
+/** One operation a vector applies after its pages are seeded. */
+export type TabViewVectorOp = {
+    readonly kind: 'select';
+    readonly id: string | null;
+} | {
+    readonly kind: 'selectNth';
+    readonly n: number;
+} | {
+    readonly kind: 'selectPrevious';
+} | {
+    readonly kind: 'selectNext';
+} | {
+    readonly kind: 'selectFirst';
+} | {
+    readonly kind: 'selectLast';
+} | {
+    readonly kind: 'cycleNext';
+} | {
+    readonly kind: 'cyclePrevious';
+} | {
+    readonly kind: 'addPage';
+    readonly page: TabViewVectorPage;
+    readonly parentId: string | null;
+} | {
+    readonly kind: 'insertPage';
+    readonly page: TabViewVectorPage;
+    readonly position: number;
+} | {
+    readonly kind: 'prependPage';
+    readonly page: TabViewVectorPage;
+} | {
+    readonly kind: 'appendPage';
+    readonly page: TabViewVectorPage;
+} | {
+    readonly kind: 'insertPinnedPage';
+    readonly page: TabViewVectorPage;
+    readonly position: number;
+} | {
+    readonly kind: 'prependPinnedPage';
+    readonly page: TabViewVectorPage;
+} | {
+    readonly kind: 'appendPinnedPage';
+    readonly page: TabViewVectorPage;
+} | {
+    readonly kind: 'setPinned';
+    readonly id: string;
+    readonly pinned: boolean;
+} | {
+    readonly kind: 'closePage';
+    readonly id: string;
+} | {
+    readonly kind: 'closePageFinish';
+    readonly id: string;
+    readonly confirm: boolean;
+} | {
+    readonly kind: 'closeOtherPages';
+    readonly id: string;
+} | {
+    readonly kind: 'closePagesBefore';
+    readonly id: string;
+} | {
+    readonly kind: 'closePagesAfter';
+    readonly id: string;
+} | {
+    readonly kind: 'detach';
+    readonly id: string;
+} | {
+    readonly kind: 'reorder';
+    readonly id: string;
+    readonly position: number;
+} | {
+    readonly kind: 'reorderBackward';
+    readonly id: string;
+} | {
+    readonly kind: 'reorderForward';
+    readonly id: string;
+} | {
+    readonly kind: 'reorderFirst';
+    readonly id: string;
+} | {
+    readonly kind: 'reorderLast';
+    readonly id: string;
+} | {
+    readonly kind: 'setTitle';
+    readonly id: string;
+    readonly title: string | null;
+};
+/** One expected selection notification, in the order it is emitted. */
+export interface TabViewVectorSelection {
+    /** Id of the newly-selected page, `null` when the view emptied. */
+    selectedId: string | null;
+    /** Its index, `-1` when the view emptied. */
+    selectedIndex: number;
+    /** The previously-selected id, `null` when there was none. */
+    previousId: string | null;
+    /** `true` only for an explicit selection; every model-driven pick is `false`. */
+    interactive: boolean;
+}
+/** One expected page-list notification. */
+export interface TabViewVectorPagesChange {
+    /** Which kind of change. */
+    kind: 'attached' | 'detached' | 'reordered' | 'pinned' | 'updated';
+    /** The page it happened to. */
+    id: string;
+    /** Its index after the change. */
+    position: number;
+    /** Its index before the change, `-1` for `'attached'`. */
+    previousPosition: number;
+}
+/**
+ * How the `close-page` handler behaves for the whole row.
+ *
+ * `'default'` reproduces libadwaita's own default handler, `close_page_cb`'s
+ * `close_page_finish (self, page, !adw_tab_page_get_pinned (page))`
+ * (adw-tab-view.c:1986-1993) — the suites install a RECORDING wrapper around it
+ * so the close-attempt order is observable, and the core suite additionally
+ * replays the row with NO handler at all to prove the built-in default agrees.
+ * `'defer'` holds every page in the closing state so `closePageFinish` decides.
+ */
+export type TabViewVectorHandler = 'default' | 'defer';
+/** One end-to-end tab-view expectation. */
+export interface TabViewVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The C function + lines it is derived from. */
+    derivedFrom: string;
+    /** The pages, seeded in this order (pinned ones via appendPinnedPage, parented ones via addPage). */
+    pages: readonly TabViewVectorPage[];
+    /** How close requests are answered. Defaults to `'default'`. */
+    handler?: TabViewVectorHandler;
+    /** Selection changes emitted WHILE the pages are seeded (the auto-select), in order. */
+    setupChanges: readonly TabViewVectorSelection[];
+    /** Operations applied after the pages exist. */
+    ops: readonly TabViewVectorOp[];
+    /**
+     * Return value of each op, in order — `null` for the ops that return nothing.
+     * Asserted by the core and NativeScript suites; the browser suite drives the
+     * same operations through element methods and asserts the DOM instead.
+     */
+    opResults: readonly (boolean | number | null)[];
+    /** Selection changes emitted BY the ops, in order. */
+    changes: readonly TabViewVectorSelection[];
+    /** Page-list changes emitted by the ops, in order. Asserted only when present. */
+    pagesChanges?: readonly TabViewVectorPagesChange[];
+    /** Ids the close handler was asked about, in order. Asserted only when present. */
+    closeAttempts?: readonly string[];
+    /** Final page order. */
+    order: readonly string[];
+    /** Final pinned-prefix length. */
+    nPinnedPages: number;
+    /** Final selected id, `null` for none. */
+    selectedId: string | null;
+    /** Final selected index, `-1` for none. */
+    selectedIndex: number;
+    /** Ids still awaiting a `closePageFinish`. Asserted only when present. */
+    closing?: readonly string[];
+    /** Expected `diagnostics` (C's `g_return_if_fail` texts), when the row exercises them. */
+    diagnostics?: readonly string[];
+}
+/**
+ * `Adw.TabView`'s selection, close protocol, partition and ordering, end to end.
+ *
+ * Read the `rule` of a row before changing it: most of them encode behaviour
+ * NEITHER port had, and several encode behaviour a port had backwards.
+ */
+export declare const TAB_VIEW_VECTORS: ReadonlyArray<TabViewVector>;
+/**
+ * The surface a vector driver needs.
+ *
+ * Deliberately STRUCTURAL and named exactly as `TabViewState` names things, so
+ * all three suites hand their subject straight to {@link applyTabViewOp} with no
+ * translation layer: the core suite passes a `TabViewState`, the NativeScript
+ * suite passes the state its widget delegates to, and the browser suite passes
+ * the `<adw-tab-view>` element itself. A renderer that cannot be passed here has
+ * stopped being a thin adapter, which is the thing these vectors exist to catch.
+ */
+export interface TabViewVectorTarget {
+    /** The ordered pages — only the three fields a vector reads. */
+    readonly pages: readonly {
+        readonly id: string;
+        readonly title: string;
+        readonly pinned: boolean;
+    }[];
+    /** Length of the pinned prefix. */
+    readonly nPinnedPages: number;
+    /** Selected page id, `null` when the view is empty. */
+    readonly selectedId: string | null;
+    /** Selected index, `-1` when the view is empty. */
+    readonly selectedIndex: number;
+    /** Whether a close request for `id` is awaiting confirmation. */
+    isClosing(id: string): boolean;
+    setSelectedPage(id: string | null): boolean;
+    selectNthPage(n: number): boolean;
+    selectPreviousPage(): boolean;
+    selectNextPage(): boolean;
+    selectFirstPage(): boolean;
+    selectLastPage(): boolean;
+    cycleNextPage(): boolean;
+    cyclePreviousPage(): boolean;
+    addPage(spec: {
+        id: string;
+        title?: string | null;
+    }, parentId: string | null): number;
+    insertPage(spec: {
+        id: string;
+        title?: string | null;
+    }, position: number): number;
+    prependPage(spec: {
+        id: string;
+        title?: string | null;
+    }): number;
+    appendPage(spec: {
+        id: string;
+        title?: string | null;
+    }): number;
+    insertPinnedPage(spec: {
+        id: string;
+        title?: string | null;
+    }, position: number): number;
+    prependPinnedPage(spec: {
+        id: string;
+        title?: string | null;
+    }): number;
+    appendPinnedPage(spec: {
+        id: string;
+        title?: string | null;
+    }): number;
+    setPagePinned(id: string, pinned: boolean): number;
+    closePage(id: string): boolean;
+    closePageFinish(id: string, confirm: boolean): boolean;
+    closeOtherPages(id: string): void;
+    closePagesBefore(id: string): void;
+    closePagesAfter(id: string): void;
+    detachPage(id: string): unknown;
+    reorderPage(id: string, position: number): boolean;
+    reorderBackward(id: string): boolean;
+    reorderForward(id: string): boolean;
+    reorderFirst(id: string): boolean;
+    reorderLast(id: string): boolean;
+    setPageTitle(id: string, title: string | null): boolean;
+}
+/**
+ * Seed a vector's pages, choosing the insertion call each page's declaration
+ * implies: a pinned page through `appendPinnedPage` (so the pinned prefix builds up
+ * in declaration order), a parented one through `addPage` (so the position is
+ * DERIVED, which is itself under test), everything else through `append`.
+ *
+ * Every vector's declared order is also the order this produces — the core suite
+ * asserts that right after seeding, which is what turns the fixtures themselves
+ * into a test of `adw_tab_view_add_page`'s position derivation.
+ */
+export declare function seedTabViewPages(target: TabViewVectorTarget, pages: readonly TabViewVectorPage[]): void;
+/**
+ * Apply one vector operation, returning what it returned — `null` for the ops
+ * that return nothing, so a vector's `opResults` stays a flat, comparable list.
+ */
+export declare function applyTabViewOp(target: TabViewVectorTarget, op: TabViewVectorOp): boolean | number | null;
+/** The page ids in order — what every vector's `order` is compared against. */
+export declare function tabViewOrder(target: TabViewVectorTarget): string[];
+/** Which of a vector's pages are still awaiting a `closePageFinish`, in page order. */
+export declare function tabViewClosing(target: TabViewVectorTarget): string[];
+/** One `successorAfterClose` expectation — the close-successor kernel on its own. */
+export interface TabSuccessorVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The C lines it is derived from. */
+    derivedFrom: string;
+    /** The page list. */
+    pages: readonly TabViewVectorPage[];
+    /** The page being closed. */
+    closingId: string;
+    /** The currently-selected id. */
+    selectedId: string | null;
+    /** Who ends up selected — `null` when the view empties. */
+    successorId: string | null;
+}
+/**
+ * `select_previous_page` (adw-tab-view.c:1857-1897) with no view around it.
+ *
+ * These are the same rules the end-to-end rows exercise, stated as pure inputs
+ * so a failure names the RULE rather than the script that reached it.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (TAB_VIEW_VECTORS)
+ */
+export declare const TAB_SUCCESSOR_VECTORS: ReadonlyArray<TabSuccessorVector>;
+/** One `isDescendantOfPage` expectation. */
+export interface TabDescendantVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The page list. */
+    pages: readonly TabViewVectorPage[];
+    /** The candidate descendant. */
+    pageId: string | null;
+    /** The candidate ancestor. */
+    parentId: string;
+    /** Whether the walk reaches the ancestor. */
+    descendant: boolean;
+}
+/** `is_descendant_of` (adw-tab-view.c:1735-1742).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (TAB_VIEW_VECTORS)
+ */
+export declare const TAB_DESCENDANT_VECTORS: ReadonlyArray<TabDescendantVector>;
+/** One `tabsRevealed` expectation. */
+export interface TabsRevealedVector {
+    /** `AdwTabBar:autohide`. */
+    autohide: boolean;
+    /** `adw_tab_view_get_n_pages`. */
+    nPages: number;
+    /** `adw_tab_view_get_n_pinned_pages`. */
+    nPinnedPages: number;
+    /** `adw_tab_view_get_is_transferring_page`. */
+    isTransferringPage: boolean;
+    /** Whether the bar shows its tabs. */
+    revealed: boolean;
+    /** What this row pins down. */
+    rule: string;
+}
+/**
+ * `update_autohide_cb` (adw-tab-bar.c:142-164), verbatim:
+ * `!autohide || n_tabs > 1 || n_pinned_tabs >= 1 || is_transferring_page`.
+ */
+export declare const TABS_REVEALED_VECTORS: ReadonlyArray<TabsRevealedVector>;
+/** One `tabCloseVisible` expectation. */
+export interface TabCloseVisibleVector {
+    /** Pointer is over the tab. */
+    hovering: boolean;
+    /** The tab is not clipped by the bar's scroll region. */
+    fullyVisible: boolean;
+    /** The tab is selected. */
+    selected: boolean;
+    /** The tab is being dragged. */
+    dragging: boolean;
+    /** The tab is pinned. */
+    pinned: boolean;
+    /** Whether the close button shows. */
+    visible: boolean;
+    /** What this row pins down. */
+    rule: string;
+}
+/**
+ * `update_state`'s `show_close` (adw-tab.c:124) plus the pinned gate applied at
+ * construction (adw-tab.c:645-650). Each port shipped a different single term of
+ * this — web showed it always, NS only on the selected tab.
+ */
+export declare const TAB_CLOSE_VISIBLE_VECTORS: ReadonlyArray<TabCloseVisibleVector>;
+/** One `tabTooltip` expectation. */
+export interface TabTooltipVector {
+    /** `AdwTabPage:tooltip`. */
+    tooltip: string;
+    /** `AdwTabPage:title`. */
+    title: string;
+    /** What the tab shows. */
+    text: string;
+    /** Whether that text is Pango markup rather than plain text. */
+    markup: boolean;
+    /** What this row pins down. */
+    rule: string;
+}
+/**
+ * `update_tooltip` (adw-tab.c:137-146): a non-empty tooltip wins and is set as
+ * MARKUP; an empty one falls back to the title, set as TEXT.
+ *
+ * WHO DRIVES THIS TABLE: only the core suite — and that is a GAP, not a reason.
+ * "Neither port has tooltips at all" was true when this was written and is not
+ * any more: the browser sets `tab.title = tabTooltip(page)`
+ * (`elements/adw-tab-view.ts`) and NativeScript re-exports it as
+ * `tabTooltipText` (`widgets/tab-view-state.ts`), so BOTH renderers consume
+ * these rows today and neither is held to them. Both surfaces are readable from
+ * their own suites, so wiring them is a loop, not new capability.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (TAB_VIEW_VECTORS — both ports consume the derivation, which this header once denied)
+ */
+export declare const TAB_TOOLTIP_VECTORS: ReadonlyArray<TabTooltipVector>;
+/** One `tabIconState` expectation. */
+export interface TabIconStateVector {
+    /** `AdwTabPage:icon`. */
+    icon: string | null;
+    /** `AdwTabPage:indicator-icon`. */
+    indicatorIcon: string | null;
+    /** `AdwTabPage:loading`. */
+    loading: boolean;
+    /** `AdwTabPage:pinned`. */
+    pinned: boolean;
+    /** `AdwTabView:default-icon`. */
+    defaultIcon: string | null;
+    /** The icon actually painted, `null` for none. */
+    resolvedIcon: string | null;
+    /** Whether a spinner replaces the icon image. */
+    spinner: boolean;
+    /** Whether the icon slot shows. */
+    iconVisible: boolean;
+    /** Whether the indicator slot shows. */
+    indicatorVisible: boolean;
+    /** What this row pins down. */
+    rule: string;
+}
+/** `update_icons` (adw-tab.c:171-198). */
+export declare const TAB_ICON_STATE_VECTORS: ReadonlyArray<TabIconStateVector>;
+/** One page-descriptor normalization expectation. */
+export interface TabPageDescriptorVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The C property it is derived from. */
+    derivedFrom: string;
+    /** The declared page. */
+    spec: {
+        id: string;
+        title?: string | null;
+        tooltip?: string | null;
+        icon?: string | null;
+        indicatorIcon?: string | null;
+        loading?: boolean;
+        needsAttention?: boolean;
+    };
+    /** Resolved `title`. */
+    title: string;
+    /** Resolved `tooltip`. */
+    tooltip: string;
+    /** Resolved `icon`. */
+    icon: string | null;
+    /** Resolved `indicatorIcon`. */
+    indicatorIcon: string | null;
+    /** Resolved `loading`. */
+    loading: boolean;
+    /** Resolved `needsAttention`. */
+    needsAttention: boolean;
+}
+/**
+ * What a declared page resolves to.
+ *
+ * The `null → ''` coercions are `g_set_str (&self->title, title ? title : "")`
+ * (adw-tab-view.c:3021) and its tooltip twin (:3064). The icon fields do NOT
+ * coerce: "no icon" is a state `tabIconState` branches on, so `null` has to
+ * survive.
+ *
+ * CORE-ONLY: GAP — a descriptor normaliser neither element routes its page input through. Tracked in #1072
+ */
+export declare const TAB_PAGE_DESCRIPTOR_VECTORS: ReadonlyArray<TabPageDescriptorVector>;

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

@@ -0,0 +1,121 @@
+/** A page as a vector declares it — the input half of `AdwViewStackPageSpec`. */
+export interface ViewStackVectorPage {
+    /** The page name. */
+    name: string;
+    /** Explicit title; omitted means "fall back to the name". */
+    title?: string;
+    /** GTK icon name, pre-normalization. */
+    icon?: string;
+    /** `AdwViewStackPage:visible`; omitted means `true`. */
+    visible?: boolean;
+}
+/** One operation a vector applies after its pages are added. */
+export type ViewStackVectorOp = {
+    readonly kind: 'selectIndex';
+    readonly index: number;
+} | {
+    readonly kind: 'selectName';
+    readonly name: string | null | undefined;
+} | {
+    readonly kind: 'setPageVisible';
+    readonly name: string;
+    readonly visible: boolean;
+} | {
+    readonly kind: 'removePage';
+    readonly name: string;
+};
+/** One expected change notification, in the order it is emitted. */
+export interface ViewStackVectorChange {
+    /** Index of the newly-visible page, `-1` for none. */
+    index: number;
+    /** Its name, `''` for none. */
+    name: string;
+    /** Its title, `''` for none. */
+    title: string;
+    /** `true` only for an explicit select; every auto-pick is `false`. */
+    interactive: boolean;
+}
+/** One end-to-end view-stack expectation. */
+export interface ViewStackVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The C function + lines it is derived from. */
+    derivedFrom: string;
+    /** The pages, added in this order. */
+    pages: readonly ViewStackVectorPage[];
+    /** Changes emitted WHILE the pages are added (the auto-pick), in order. */
+    setupChanges: readonly ViewStackVectorChange[];
+    /** Operations applied after the pages exist. */
+    ops: readonly ViewStackVectorOp[];
+    /**
+     * Return value of each op, in order. Asserted by the core suite only — the
+     * renderers drive the same operations through property setters, which have
+     * no return value; what they assert is `changes` plus the final state.
+     */
+    opResults: readonly boolean[];
+    /** Changes emitted BY the ops, in order. */
+    changes: readonly ViewStackVectorChange[];
+    /** Final selected index, `-1` for none. */
+    visibleIndex: number;
+    /** Final selected name, `''` for none. */
+    visibleName: string;
+    /** Final selected title, `''` for none. */
+    visibleTitle: string;
+    /** Final page count. */
+    count: number;
+    /** Expected `duplicateNames`, when the row exercises them. */
+    duplicateNames?: readonly string[];
+    /** Expected `diagnostics` (C's `g_warning` texts), when the row exercises them. */
+    diagnostics?: readonly string[];
+}
+/**
+ * The selection state machine of `Adw.ViewStack`, end to end.
+ *
+ * Read the `rule` of each row before changing it: several encode behaviour that
+ * BOTH ports had wrong, and "fixing" the vector to match a renderer would undo
+ * the reason this table exists.
+ */
+export declare const VIEW_STACK_VECTORS: ReadonlyArray<ViewStackVector>;
+/** One page-descriptor normalization expectation. */
+export interface ViewStackPageDescriptorVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The C property it is derived from. */
+    derivedFrom: string;
+    /** The declared page. */
+    page: ViewStackVectorPage;
+    /** Resolved `title`. */
+    title: string;
+    /** Resolved `icon`. */
+    icon: string;
+    /** Resolved `visible`. */
+    visible: boolean;
+}
+/**
+ * What a declared page resolves to in `pages[i]` — the shape a bound switcher
+ * reads. `icon` is a NAME and is never `undefined`; the NS port used to store
+ * `undefined`, which the web switcher bar's `page.icon.length` would throw on.
+ */
+export declare const VIEW_STACK_PAGE_VECTORS: ReadonlyArray<ViewStackPageDescriptorVector>;
+/** One `normalizeIconName` expectation. */
+export interface ViewStackIconNameVector {
+    /** The declared `icon-name`. */
+    icon: string | null | undefined;
+    /** The normalized result. */
+    normalized: string;
+    /** What this row pins down. */
+    rule: string;
+}
+/**
+ * `normalizeIconName` — the one home for a `-symbolic` strip that appeared
+ * eleven times across the web package and zero times in NS, plus the token guard
+ * that appeared exactly ONCE (`<adw-split-button>`) and was missing from every
+ * other copy.
+ *
+ * The guard rows are not hypothetical: `<adw-menu-button>` interpolated the raw
+ * name into `class="adw-icon adw-menu-button-icon adw-icon--<name>"`, so
+ * `icon-name="a b"` shipped a stray `b` class — for its own icon and for every
+ * JSON menu entry's. NOTHING in the build was in a position to notice, because
+ * the one element that DID guard passed its own spec.
+ */
+export declare const VIEW_STACK_ICON_NAME_VECTORS: ReadonlyArray<ViewStackIconNameVector>;