@gjsify/adwaita-core 0.47.0 → 0.49.0

package/lib/types/adjustment.d.ts

@@ -0,0 +1,198 @@
+/**
+ * A normalised portable adjustment — what an `adjustment` property holds on every surface.
+ *
+ * The six numbers of `Gtk.Adjustment`, under its own field names. Every one is finite, and
+ * the invariants {@link normalizeAdjustment} establishes hold: `upper >= lower`,
+ * `pageSize >= 0`, `stepIncrement > 0`, and `value` inside {@link adjustmentRange}.
+ */
+export interface AdwAdjustment {
+    /** The current value, within `[lower, upper - pageSize]`. */
+    value: number;
+    /** The minimum value. */
+    lower: number;
+    /** The maximum value — reduced by {@link AdwAdjustment.pageSize} for what a value may reach. */
+    upper: number;
+    /** How far one stepper press moves the value. */
+    stepIncrement: number;
+    /** How far one page press (Page Up/Down) moves the value. */
+    pageIncrement: number;
+    /** The size of the visible page; zero for a scalar value such as a spin row's. */
+    pageSize: number;
+}
+/**
+ * What an `adjustment` property ACCEPTS: any subset of {@link AdwAdjustment}, with the rest
+ * taken from {@link ADW_ADJUSTMENT_DEFAULTS} (or, for {@link SpinState.configure}, from what
+ * the adjustment already holds).
+ *
+ * A bare number is NOT accepted, and the omission is deliberate: an adjustment addressed by
+ * one number would be its `value`, and `value` is a property of its own on every widget that
+ * takes an adjustment. Accepting it here would make `adjustment={3}` and `value={3}` two
+ * spellings of one write.
+ */
+export type AdwAdjustmentInput = Partial<AdwAdjustment>;
+/**
+ * The range every surface falls back to, and the one figure in this module that is OURS
+ * rather than GTK's — see the file header for why 0…100 step 1 rather than GTK's 0…0 step 0.
+ */
+export declare const ADW_ADJUSTMENT_DEFAULTS: AdwAdjustment;
+/**
+ * The closed interval a value may occupy: `[lower, upper - pageSize]`.
+ *
+ * The upper end is `set_value`'s documented "effective range … from lower to
+ * upper - page_size", floored at `lower` so a page larger than the range yields the single
+ * point `lower` rather than an inverted interval.
+ */
+export declare function adjustmentRange(adjustment: AdwAdjustment): [number, number];
+/**
+ * `value` clamped into {@link adjustmentRange}.
+ *
+ * The two non-finite inputs are NOT one case, and separating them is a repair rather than a
+ * refinement. `±Infinity` carries a DIRECTION, so it clamps to the bound it is heading for,
+ * which is what `set_value`'s "clamped to lie between lower and upper" says. `NaN` carries
+ * none and lands on the lower bound. The `SpinState` this replaces coerced both to 0 before
+ * clamping, which is only harmless while 0 is inside the range: on `[-5, -1]` it turned a
+ * `NaN` write into `-1`, the MAXIMUM. `adjustment.spec.ts` holds that case.
+ */
+export declare function clampAdjustmentValue(adjustment: AdwAdjustment, value: number): number;
+/**
+ * `value` clamped and then moved to the nearest tick — the arithmetic behind
+ * `snap-to-ticks`.
+ *
+ * `AdwSpinRow:snap-to-ticks` (and `GtkSpinButton`'s before it) is documented as "whether
+ * erroneous values are automatically changed to the nearest step", and the ticks are the
+ * step grid counted FROM THE LOWER BOUND — a range of `[1, 10]` with a step of 3 has ticks
+ * at 1, 4, 7 and 10, not at 3, 6, 9.
+ *
+ * THE TICK INDEX IS WHAT IS CLAMPED, not the value it produces, and the difference is a
+ * whole tick wide. Clamping the value lands on the upper BOUND whenever that bound is not
+ * itself a tick — `[0, 10]` step 4 answered `10`, which is off the grid `0, 4, 8` by two —
+ * so the function promised the nearest step and returned something that was not a step at
+ * all. An upper bound off the grid is simply not reachable by snapping; that is what
+ * snapping to ticks means. The slider row's own `_snap` had the same defect before this
+ * arithmetic had a name (`Math.min(this._max, …)`), so this is a repair and not a port.
+ *
+ * It is a function rather than a mode on {@link SpinState} because only one renderer needs
+ * it: a stepper moves BY the step and can never land between ticks, while a dragged slider
+ * lands wherever the finger left it.
+ */
+export declare function snapAdjustmentValue(adjustment: AdwAdjustment, value: number): number;
+/**
+ * Fill an authored adjustment out to a whole one.
+ *
+ * Total: every field falls back to `base` (the defaults unless a caller passes what it
+ * already holds), and the invariants are established rather than assumed — `upper` cannot
+ * sit below `lower`, `pageSize` cannot be negative, `stepIncrement` cannot be zero (a step
+ * of zero is a stepper that cannot move, which is GTK's default and not a usable one), and
+ * `value` is clamped last, against the range the other five just described.
+ */
+export declare function normalizeAdjustment(input?: AdwAdjustmentInput | null, base?: AdwAdjustment): AdwAdjustment;
+/**
+ * The MARKUP door: a JSON attribute → the fields it authored.
+ *
+ * It yields a PARTIAL and not a whole adjustment, and that is what makes attribute order
+ * irrelevant: `adjustment='{"upper":20}'` moves the upper bound and leaves the value where
+ * it is, whichever attribute the parser reached first. A door that answered with a whole
+ * adjustment would carry `value: 0` into every such write and silently reset the row —
+ * the ordering hazard `spin-row.gtk.tsx` records for the GTK renderer, arriving through
+ * markup instead of through props.
+ *
+ * Total in every failure mode, and they are all an author slip rather than a state the
+ * element may refuse to upgrade in: absent, unparseable, and well-formed JSON that is not an
+ * object (an array, a number, `null`) each yield `{}` — no field authored, nothing moves.
+ * The same door `parseListModel` and `parseMenuModel` open for their values, for the same
+ * reason and on the same surfaces.
+ *
+ * A key that is not one of the six is DROPPED rather than carried into the state, so a typo
+ * (`{"min":1}`) does not travel as a property the value does not have.
+ */
+export declare function parseAdjustment(raw: string | null | undefined): AdwAdjustmentInput;
+/** Payload of a {@link SpinState} value change. */
+export interface SpinStateChange {
+    /** The new value (already clamped into {@link adjustmentRange}). */
+    value: number;
+    /** True for a stepper press ({@link SpinState.increment}/{@link SpinState.decrement}); false for a programmatic set or a re-clamp. */
+    interactive: boolean;
+}
+/** Subscriber for {@link SpinState} value changes — `Gtk.Adjustment::value-changed`. */
+export type SpinStateListener = (change: SpinStateChange) => void;
+/** Subscriber for {@link SpinState} RANGE changes — `Gtk.Adjustment::changed`. */
+export type SpinStateRangeListener = (adjustment: AdwAdjustment) => void;
+/**
+ * An adjustment that can be watched — the portable `Gtk.Adjustment` OBJECT to
+ * {@link AdwAdjustment}'s value.
+ *
+ * It keeps the two signals apart exactly as GTK does, because a renderer needs them apart:
+ * `value-changed` redraws a label, `changed` re-sizes a slider's track. {@link subscribe}
+ * is the first, {@link subscribeChanged} the second, and {@link configure} may emit both.
+ *
+ * The `interactive` flag on the value signal is OURS and has no GTK counterpart, because on
+ * GTK the two callers are different objects: the widget writes the adjustment on a stepper
+ * press and the application writes it programmatically, and a renderer here is both. It
+ * mirrors `Adw.SpinRow`'s observable behaviour — a programmatic set refreshes the display
+ * without the row re-emitting `notify::value`, a stepper press emits.
+ *
+ * WHAT IT DOES NOT HAVE is GTK's five individual setters (`set_lower`, `set_upper`, …).
+ * They exist in C because there is no record literal there; here the whole range arrives as
+ * one value, and `gtk_adjustment_configure`'s own documented reason for existing — it
+ * compresses the notifications "into one" — is the shape this class already has.
+ */
+export declare class SpinState {
+    private _adjustment;
+    /**
+     * Whether a value has ever been WRITTEN — by a setter, a stepper, or a `configure`
+     * carrying one.
+     *
+     * Until one has, the value is not a value: it is wherever the bottom of the range is,
+     * and it follows a bound that moves. After one has, a moved bound RE-CLAMPS it, which
+     * is the documented behaviour and a different thing. Without the flag the two are
+     * indistinguishable, and a fresh row configured to `[-100, -50]` opened at -50 — the
+     * maximum, from an author who wrote no value at all.
+     *
+     * A WRITE PLACES THE VALUE EVEN WHEN THE NUMBER DOES NOT MOVE: `setValue(0)` on a row
+     * already at 0 has still said where the value belongs, and a later range move re-clamps
+     * it rather than re-seeding it. The two exceptions are the two writes that say nothing —
+     * a non-finite value, and a stepper press at the end of the range that moves nothing.
+     */
+    private _valueSet;
+    private readonly _listeners;
+    private readonly _rangeListeners;
+    /** Subscribe to value changes (`value-changed`). Returns an unsubscribe function. */
+    subscribe(listener: SpinStateListener): () => void;
+    /** Subscribe to range changes (`changed`). Returns an unsubscribe function. */
+    subscribeChanged(listener: SpinStateRangeListener): () => void;
+    private _emit;
+    private _emitChanged;
+    private _bump;
+    /** The whole adjustment. A snapshot: mutating it does not reach this object. */
+    get adjustment(): AdwAdjustment;
+    /** The current value (always within {@link adjustmentRange}). */
+    get value(): number;
+    /**
+     * Replace the range (and optionally the value) — `gtk_adjustment_configure`.
+     *
+     * Unwritten fields keep what the adjustment already holds, so a caller may move one
+     * bound without restating the rest. Emits `changed` when any of the five range fields
+     * moved and `value-changed` when the value did — including a value that moved only
+     * because a bound came under it, which notifies `interactive: false`.
+     *
+     * Returns whether anything changed at all.
+     */
+    configure(input: AdwAdjustmentInput | null | undefined): boolean;
+    /** Programmatic value set — clamp, notify `interactive: false` on change. Returns whether it changed. */
+    setValue(value: number): boolean;
+    /**
+     * The same set, as a USER-driven change — notifies `interactive: true`.
+     *
+     * {@link increment} and {@link decrement} are the stepper's interactions and move BY the
+     * step; this is the DRAGGED one, which lands wherever the finger left it.
+     * `ComboState.select` is the same pair on the same reasoning: one method per caller,
+     * rather than a flag every caller has to remember to pass.
+     *
+     * Returns whether it changed.
+     */
+    setValueInteractive(value: number): boolean;
+    /** Step up by `stepIncrement`, clamped. Notifies `interactive: true` on change. Returns whether it changed. */
+    increment(): boolean;
+    /** Step down by `stepIncrement`, clamped. Notifies `interactive: true` on change. Returns whether it changed. */
+    decrement(): boolean;
+}

package/lib/types/adjustment.spec.d.ts

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

package/lib/types/avatar.d.ts

@@ -103,3 +103,18 @@ export declare function avatarFontSize(size: number, measured: {
  * this). Returns a `#rrggbb` string.
  */
 export declare function flattenAvatarGradient(color: AdwAvatarColor): string;
+/**
+ * The box the FALLBACK ICON gets inside an avatar of `size`, in the renderer's own
+ * length unit (CSS px on the web, DIPs on NativeScript).
+ *
+ * `adw_avatar_set_size` sizes the icon itself —
+ * `gtk_image_set_pixel_size (self->icon, size / 2)`
+ * (refs/libadwaita/src/adw-avatar.c:756#gtk_image_set_pixel_size) — so this is a
+ * PORTED number, not a chosen one. `size` is an `int` there, so `/` truncates.
+ *
+ * The stylesheet was the wrong place to look for it, and looking only there is how
+ * the web renderer arrived at a hand-typed `size * 0.55`: `_avatar.scss` really does
+ * carry no icon rule, which reads as "libadwaita says nothing" right up until the C
+ * is read. 0.55 drew the glyph ~10% larger than GTK does at every size.
+ */
+export declare function avatarIconSize(size: number): number;

package/lib/types/conformance/adjustment.d.ts

@@ -0,0 +1,33 @@
+import type { AdwAdjustment, AdwAdjustmentInput } from '../adjustment.js';
+/** One authored range + value, and where the value lands. */
+export interface AdjustmentAuthoredVector {
+    /** What this row pins down. */
+    rule: string;
+    /** What the author wrote for the range. */
+    input: AdwAdjustmentInput;
+    /** The whole adjustment it normalises to. */
+    adjustment: AdwAdjustment;
+}
+export declare const ADJUSTMENT_AUTHORED_VECTORS: ReadonlyArray<AdjustmentAuthoredVector>;
+/** One JSON attribute, and the fields it authored. */
+export interface AdjustmentParseVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The attribute as written. */
+    raw: string | null;
+    /** The fields it names — and ONLY those. */
+    input: AdwAdjustmentInput;
+}
+export declare const ADJUSTMENT_PARSE_VECTORS: ReadonlyArray<AdjustmentParseVector>;
+/** One dragged value, and the tick it lands on. */
+export interface AdjustmentSnapVector {
+    /** What this row pins down. */
+    rule: string;
+    /** The range being dragged through. */
+    input: AdwAdjustmentInput;
+    /** Where the drag landed. */
+    from: number;
+    /** The tick it snaps to. */
+    snapped: number;
+}
+export declare const ADJUSTMENT_SNAP_VECTORS: ReadonlyArray<AdjustmentSnapVector>;

package/lib/types/conformance/avatar.d.ts

@@ -38,6 +38,22 @@ export interface AvatarFontSizeVector {
  * circle), and is not even monotonic — 16px at size 31, 13px at size 32.
  */
 export declare const AVATAR_FONT_SIZE_VECTORS: ReadonlyArray<AvatarFontSizeVector>;
+/** One `avatarIconSize` expectation. */
+export interface AvatarIconSizeVector {
+    /** `Adw.Avatar:size`, the circle diameter. */
+    size: number;
+    /** `gtk_image_set_pixel_size (self->icon, size / 2)` — C integer division. */
+    iconSize: number;
+}
+/**
+ * `adw_avatar_set_size`'s icon extent (adw-avatar.c:756).
+ *
+ * The table exists because the number was invented once: both renderers drew the
+ * fallback glyph at `round(size * 0.55)`, agreeing with each other and with nothing
+ * else, on the written grounds that libadwaita had no number to port. Odd sizes are
+ * here because `size` is an `int` in the C and `/` truncates.
+ */
+export declare const AVATAR_ICON_SIZE_VECTORS: ReadonlyArray<AvatarIconSizeVector>;
 /** One `avatarMode` expectation. */
 export interface AvatarModeVector {
     hasCustomImage: boolean;

package/lib/types/conformance/index.d.ts

@@ -1,7 +1,7 @@
 export { ABOUT_DIALOG_CREDITS_LEGAL_VECTORS, ABOUT_DIALOG_DETAILS_VECTORS, ABOUT_DIALOG_HEADER_VECTORS, ABOUT_DIALOG_LABEL_VECTORS, ABOUT_DIALOG_SUPPORT_VECTORS, CREDITS_SECTIONS_VECTORS, CREDIT_PERSON_VECTORS, LEGAL_SECTION_VECTORS, LICENSE_INFO_VECTORS, LICENSE_SETTER_VECTORS, LICENSE_SPDX_VECTORS, LICENSE_TEXT_VECTORS, TRANSLATOR_CREDITS_VECTORS, } from './about-dialog.js';
 export type { AboutDialogCreditsLegalVector, AboutDialogDetailsVector, AboutDialogHeaderVector, AboutDialogLabelVector, AboutDialogSupportVector, CreditPersonVector, CreditsSectionsVector, LegalSectionVector, LicenseInfoVector, LicenseSetterStep, LicenseSetterVector, LicenseSpdxVector, LicenseTextVector, TranslatorCreditsVector, } from './about-dialog.js';
-export { AVATAR_COLOR_VECTORS, AVATAR_FONT_SIZE_VECTORS, AVATAR_INITIALS_VECTORS, AVATAR_MODE_VECTORS, } from './avatar.js';
-export type { AvatarColorVector, AvatarFontSizeVector, AvatarInitialsVector, AvatarModeVector } from './avatar.js';
+export { AVATAR_COLOR_VECTORS, AVATAR_FONT_SIZE_VECTORS, AVATAR_ICON_SIZE_VECTORS, AVATAR_INITIALS_VECTORS, AVATAR_MODE_VECTORS, } from './avatar.js';
+export type { AvatarColorVector, AvatarFontSizeVector, AvatarIconSizeVector, AvatarInitialsVector, AvatarModeVector, } from './avatar.js';
 export { ACTION_ROW_ACTIVATION_VECTORS, BUTTON_ROW_ACTIVATABLE_VECTORS, BUTTON_ROW_ICON_VECTORS, LABEL_VISIBILITY_VECTORS, SWITCH_ROW_NOTIFY_VECTORS, WINDOW_TITLE_VECTORS, } from './action-row.js';
 export type { ActionRowActivationVector, ActionRowStep, ButtonRowActivatableVector, ButtonRowIconVector, LabelVisibilityVector, SwitchRowNotifyVector, SwitchRowStep, WindowTitleStep, WindowTitleVector, } from './action-row.js';
 export { BANNER_BUTTON_STYLE_PARSE_VECTORS, BANNER_BUTTON_STYLE_VECTORS, BANNER_BUTTON_TEXT_VECTORS, BANNER_BUTTON_VISIBLE_VECTORS, BANNER_DEFAULT_VECTORS, } from './banner.js';
@@ -24,8 +24,14 @@ export { ENTRY_MAX_LENGTH_VECTORS, ENTRY_ROW_ACTIVATION_VECTORS, ENTRY_ROW_GUARD
 export type { EntryMaxLengthVector, EntryRowActivationVector, EntryRowGuardVector, EntryRowStateVector, EntryRowStep, EntryTextLengthVector, PasswordEntryRowStep, PasswordEntryRowVector, PasswordRevealGuardVector, } from './entry-row.js';
 export { ADW_LENGTH_UNIT_VECTORS, GLIB_CLAMP_VECTORS, NATURAL_SIDEBAR_WIDTH_VECTORS, NAVIGATION_ACTION_VECTORS, NAVIGATION_SPLIT_VIEW_LAYOUT_VECTORS, NAVIGATION_STACK_VECTORS, OVERLAY_COLLAPSE_VECTORS, OVERLAY_SPLIT_VIEW_LAYOUT_VECTORS, OVERLAY_SWIPE_AREA_VECTORS, OVERLAY_SWIPE_CANCEL_VECTORS, OVERLAY_SWIPE_RELEASE_VECTORS, OVERLAY_SWIPE_SNAP_POINT_VECTORS, OVERLAY_SWIPE_START_VECTORS, SIDEBAR_BOUNDS_VECTORS, SIDEBAR_WIDTH_VECTORS, SPLIT_VIEW_MEASURE_VECTORS, TAGS_CONFLICT_VECTORS, } from './split-view.js';
 export type { AdwLengthUnitVector, GlibClampVector, NaturalSidebarWidthVector, NavigationActionVector, NavigationLayoutVector, NavigationStackVector, OverlayCollapseVector, OverlayLayoutVector, OverlaySplitViewSnapshot, SidebarBoundsVector, SidebarWidthVector, SplitViewMeasureVector, SwipeAreaVector, SwipeCancelVector, SwipeReleaseVector, SwipeSnapPointVector, SwipeStartVector, TagsConflictVector, } from './split-view.js';
-export { MENU_BUTTON_DIRECTION_VECTORS, SPLIT_BUTTON_CONTENT_VECTORS, SPLIT_BUTTON_DIRECTION_VECTORS, SPLIT_BUTTON_DROPDOWN_VECTORS, SPLIT_BUTTON_MENU_ACTIVATION_VECTORS, SPLIT_BUTTON_MENU_PARSE_VECTORS, SPLIT_BUTTON_ROOT_STATE_VECTORS, SPLIT_BUTTON_STYLE_CLASS_VECTORS, SPLIT_BUTTON_TOOLTIP_VECTORS, } from './split-button.js';
-export type { SplitButtonContentStep, SplitButtonContentVector, SplitButtonDirectionVector, SplitButtonDropdownVector, SplitButtonMenuActivationVector, SplitButtonMenuParseVector, SplitButtonRootStateVector, SplitButtonStyleClassVector, SplitButtonTooltipVector, } from './split-button.js';
+export { MENU_BUTTON_DIRECTION_VECTORS, SPLIT_BUTTON_CONTENT_VECTORS, SPLIT_BUTTON_DIRECTION_VECTORS, SPLIT_BUTTON_DROPDOWN_VECTORS, SPLIT_BUTTON_MENU_ACTIVATION_VECTORS, SPLIT_BUTTON_ROOT_STATE_VECTORS, SPLIT_BUTTON_STYLE_CLASS_VECTORS, SPLIT_BUTTON_TOOLTIP_VECTORS, } from './split-button.js';
+export type { SplitButtonContentStep, SplitButtonContentVector, SplitButtonDirectionVector, SplitButtonDropdownVector, SplitButtonMenuActivationVector, SplitButtonRootStateVector, SplitButtonStyleClassVector, SplitButtonTooltipVector, } from './split-button.js';
+export { ADJUSTMENT_AUTHORED_VECTORS, ADJUSTMENT_PARSE_VECTORS, ADJUSTMENT_SNAP_VECTORS } from './adjustment.js';
+export type { AdjustmentAuthoredVector, AdjustmentParseVector, AdjustmentSnapVector } from './adjustment.js';
+export { LIST_ITEMS_CHANGED_VECTORS, LIST_MODEL_OWNERSHIP_VECTORS, LIST_NORMALIZE_VECTORS, LIST_PARSE_VECTORS, LIST_SELECTION_CLAMP_VECTORS, TAB_PAGES_ITEMS_CHANGED_VECTORS, applyListReadback, replayTabPagesAsSplices, } from './list.js';
+export type { ListItemsChangedVector, ListModelOwnershipVector, ListNormalizeVector, ListParseVector, ListReadbackOp, ListSelectionClampVector, TabPagesItemsChangedVector, } from './list.js';
+export { MENU_DETAILED_ACTION_VECTORS, MENU_FLATTEN_VECTORS, MENU_ITEM_STATE_VECTORS, MENU_NORMALIZE_VECTORS, MENU_PARSE_VECTORS, MENU_REFUSAL_VECTORS, } from './menu.js';
+export type { MenuDetailedActionVector, MenuFlatRowVector, MenuFlattenVector, MenuItemStateVector, MenuNormalizeVector, MenuParseVector, MenuRefusalVector, } from './menu.js';
 export { INLINE_TOGGLE_VECTORS, INLINE_TOOLTIP_VECTORS, VIEW_SWITCHER_BADGE_VECTORS, VIEW_SWITCHER_BAR_REVEAL_VECTORS, VIEW_SWITCHER_BAR_VECTORS, VIEW_SWITCHER_BUTTON_VECTORS, VIEW_SWITCHER_BUTTON_VISIBILITY_VECTORS, VIEW_SWITCHER_DRAG_VECTORS, VIEW_SWITCHER_ICON_VECTORS, VIEW_SWITCHER_MNEMONIC_VECTORS, VIEW_SWITCHER_REBUILD_VECTORS, VIEW_SWITCHER_SELECTION_VECTORS, createViewSwitcherClock, } from './view-switcher.js';
 export type { ExpectedInlineToggle, ExpectedViewSwitcherButton, InlineToggleVector, InlineTooltipVector, MnemonicVector, ViewSwitcherBadgeVector, ViewSwitcherBarRevealVector, ViewSwitcherBarSnapshot, ViewSwitcherBarStep, ViewSwitcherBarVector, ViewSwitcherButtonVector, ViewSwitcherButtonVisibilityVector, ViewSwitcherClock, ViewSwitcherDragStep, ViewSwitcherDragVector, ViewSwitcherIconVector, ViewSwitcherRebuildVector, ViewSwitcherSelectionVector, ViewSwitcherVectorChange, ViewSwitcherVectorOp, ViewSwitcherVectorPage, } from './view-switcher.js';
 export { TABS_REVEALED_VECTORS, TAB_CLOSE_VISIBLE_VECTORS, TAB_DESCENDANT_VECTORS, TAB_ICON_STATE_VECTORS, TAB_PAGE_DESCRIPTOR_VECTORS, TAB_SUCCESSOR_VECTORS, TAB_TOOLTIP_VECTORS, TAB_VIEW_VECTORS, applyTabViewOp, seedTabViewPages, tabViewClosing, tabViewOrder, } from './tab-view.js';
@@ -54,3 +60,5 @@ export { BREAKPOINT_PICK_VECTORS, BREAKPOINT_TRANSITION_VECTORS } from './breakp
 export type { BreakpointPickVector, BreakpointTransitionVector } from './breakpoint-bin.js';
 export { HEADER_BAR_PACK_VECTORS, HEADER_BAR_TITLE_SOURCE_VECTORS, HEADER_BAR_TITLE_WIDGET_VECTORS, } from './header-bar.js';
 export type { HeaderBarPackVector, HeaderBarTitleSourceVector, HeaderBarTitleWidgetVector } from './header-bar.js';
+export { SHARED_TREE_BLOCKS_WITHOUT_EXPECTATIONS, SHARED_TREE_TABLES, authoredNodes, authoredTags, reachedTables, sharedTreeExpectations, subjectIndexOf, } from './shared-trees.js';
+export type { SharedTreeExpectation, SharedTreeNode, SharedTreeObservable } from './shared-trees.js';

package/lib/types/conformance/list.d.ts

@@ -0,0 +1,171 @@
+import type { AdwComboOption, AdwListItemsChanged, AdwListModel, AdwListModelInput } from '../list.js';
+import type { TabViewPagesChange } from '../tab-view.js';
+/** One {@link normalizeComboOptions} expectation. */
+export interface ListNormalizeVector {
+    input: AdwListModelInput;
+    model: AdwListModel;
+    rule: string;
+}
+/**
+ * Authored input → the normalised model.
+ *
+ * The browser suite drives `LIST_NORMALIZE_VECTORS` through the real `model` property of
+ * `<adw-combo-row>` and of `<gtk-drop-down>`, every row of it, and core drives the
+ * function.
+ *
+ * The NativeScript widgets take the same input and NOTHING there asserts it. That
+ * package's specs reach `ComboState` and never the widget class, for the reason
+ * `drop-down.spec.ts`' own header gives, and the gap is filed in `status/open-todos.md`
+ * under "The NativeScript list-model setter is held by core's vectors, not by a widget
+ * test". This docblock used to say "every surface that takes a `model` … must answer
+ * these rows: … the NativeScript widgets through theirs", which reads as coverage for a
+ * surface that answers none of them — the shape #1072 was about, one file further in
+ * than any arm of `check-adwaita-conformance-drivers.mjs` looks (its claim arms begin at
+ * a citation, and that sentence named no table).
+ */
+export declare const LIST_NORMALIZE_VECTORS: ReadonlyArray<ListNormalizeVector>;
+/** One {@link parseListModel} expectation — the JSON attribute door. */
+export interface ListParseVector {
+    /** The attribute value exactly as authored. */
+    attribute: string;
+    model: AdwListModel;
+    rule: string;
+}
+/**
+ * The `model` ATTRIBUTE → the normalised model. TOTAL: no row throws.
+ *
+ * An attribute is markup, parsed while the element upgrades, so a throw is reported as an
+ * uncaught page error nobody can handle — the reasoning ADR 0042 § 6 records for the menu
+ * attribute on the same elements.
+ *
+ * The browser suite drives `LIST_PARSE_VECTORS` through the live `model` attribute of
+ * `<adw-combo-row>` and of `<gtk-drop-down>`. Two elements for one parser because the
+ * parser is not what breaks: the row's `attributeChangedCallback` branch is, and it was
+ * missing for that element's whole life (#1525).
+ */
+export declare const LIST_PARSE_VECTORS: ReadonlyArray<ListParseVector>;
+/** One {@link listItemsChanged} expectation. */
+export interface ListItemsChangedVector {
+    previous: AdwListModel;
+    next: AdwListModel;
+    /** The single splice, or `null` where GTK would emit no signal at all. */
+    change: AdwListItemsChanged | null;
+    /**
+     * How many item views a renderer must carry over UNTOUCHED — `previous.length` minus
+     * what the splice removes. A rebuild scores 0 on every row with a non-zero figure
+     * here, which is the whole difference this table measures.
+     */
+    survivors: number;
+    rule: string;
+}
+/**
+ * Model replacement → the one `items-changed` it emits.
+ *
+ * The shared prefix and the shared suffix are kept and everything between them is the
+ * change, which is `g_list_store_splice`'s shape.
+ */
+export declare const LIST_ITEMS_CHANGED_VECTORS: ReadonlyArray<ListItemsChangedVector>;
+/** What a caller does to the array it read back out of a `model` accessor. */
+export type ListReadbackOp = 'append' | 'relabel-first' | 'remove-first';
+/** One read-mutate-assign expectation — see {@link LIST_MODEL_OWNERSHIP_VECTORS}. */
+export interface ListModelOwnershipVector {
+    initial: AdwListModel;
+    /**
+     * Which array the caller mutates: the one `model` handed BACK, or the one they
+     * assigned and kept. Two doors into the same failure, and closing one leaves the other.
+     */
+    source: 'readback' | 'input';
+    op: ListReadbackOp;
+    /** Whether the mutated array is assigned back to `model` afterwards. */
+    assign: boolean;
+    /** The model the surface holds when the row is done. */
+    model: AdwListModel;
+    /** The splice the surface emits, or `null` where it emits none. */
+    itemsChanged: AdwListItemsChanged | null;
+    /** Item views carried over untouched — `initial.length` when nothing happened. */
+    survivors: number;
+    rule: string;
+}
+/**
+ * WHO OWNS THE ARRAY a `model` accessor hands back — read, mutate, assign.
+ *
+ * The browser suite drives `LIST_MODEL_OWNERSHIP_VECTORS` through `<adw-combo-row>` and
+ * `<gtk-drop-down>`, and core drives it through `ComboState` itself, which is the surface
+ * where BOTH doors are reachable: the element setters run `normalizeComboOptions` and so
+ * close the input door on their own, while `ComboState.setModel` takes a normalised model
+ * straight from a caller.
+ *
+ * THE ROWS EXIST BECAUSE THE SPLICE MADE THIS A SILENT FAILURE. Under the full rebuild
+ * every assignment redrew the list, so an aliased array was invisible; the splice decides
+ * what to redraw by COMPARING the assignment against the stored model, and an alias makes
+ * both sides read the new value — "nothing changed", nothing drawn, no error. `append`
+ * with `assign` is the pattern that regressed, `relabel-first` is the same failure one
+ * level down through a shared descriptor (which is why the copy is per ITEM and not just
+ * per array), and the `assign: false` row is the invariant the other two rest on: what a
+ * caller holds is THEIRS, so touching it moves nothing until they hand it back.
+ */
+export declare const LIST_MODEL_OWNERSHIP_VECTORS: ReadonlyArray<ListModelOwnershipVector>;
+/**
+ * The caller-side half of one {@link LIST_MODEL_OWNERSHIP_VECTORS} row: mutate the array a
+ * `model` accessor handed back, IN PLACE, and hand the same array back.
+ *
+ * In place and returning its argument is the whole point — a helper that built a new array
+ * would test the pattern that never broke.
+ */
+export declare function applyListReadback(model: AdwComboOption[], op: ListReadbackOp): AdwComboOption[];
+/** One {@link clampListSelection} expectation. */
+export interface ListSelectionClampVector {
+    selected: number;
+    length: number;
+    result: number;
+    rule: string;
+}
+/**
+ * Where a selection lands after the model under it was replaced.
+ *
+ * The browser suite drives `LIST_SELECTION_CLAMP_VECTORS` through `<adw-combo-row>` and
+ * through that element only. `<gtk-drop-down>` REFUSES an out-of-range `selected` set
+ * outright — its published contract, with `ComboState.hasIndex` as the shared bounds — so
+ * the starting index these rows replace cannot be put on that element in the first place.
+ * One row is narrower than the vector even on the row, and `adw-row-state.spec.ts` says
+ * so in place.
+ */
+export declare const LIST_SELECTION_CLAMP_VECTORS: ReadonlyArray<ListSelectionClampVector>;
+/** One {@link tabViewItemsChanged} expectation, with the order it replays. */
+export interface TabPagesItemsChangedVector {
+    change: TabViewPagesChange;
+    itemsChanged: AdwListItemsChanged;
+    /** The page order before the change. */
+    before: readonly string[];
+    /** The page order after it — what {@link replayTabPagesAsSplices} must reproduce. */
+    after: readonly string[];
+    rule: string;
+}
+/**
+ * `TabViewPagesChange` → the portable `items-changed`, and what replaying it does to the
+ * order.
+ *
+ * The `before`/`after` pair is why these rows are worth having: a mapping asserted only
+ * against three numbers proves the arithmetic and not the CLAIM, which is that the
+ * portable signal carries everything a renderer needs to follow the collection.
+ *
+ * CORE-ONLY: the inputs are `TAB_VIEW_VECTORS`' own `pagesChanges`, which both renderer
+ * tab-view suites drive — each replays the changes ITS real widget emitted through
+ * {@link replayTabPagesAsSplices} and compares the result against the order that widget
+ * ended on, so the mapping is covered on both renderers under that table's name. Rows
+ * here are the hand-written edges (a move in each direction, a pin) that a fixture may or
+ * may not reach, so they are asserted against the function directly rather than left to
+ * whichever ops the tab-view fixtures happen to contain.
+ */
+export declare const TAB_PAGES_ITEMS_CHANGED_VECTORS: ReadonlyArray<TabPagesItemsChangedVector>;
+/**
+ * Replay page changes as splices over an order — the reconstruction that makes the
+ * portable signal's sufficiency measurable.
+ *
+ * It uses nothing but {@link tabViewItemsChanged}'s three numbers and the change's `id`,
+ * which is exactly what a GTK consumer has: `items-changed` gives the RANGE and the
+ * consumer re-reads the model over it. Both renderer tab-view suites feed it the changes
+ * their real widget emitted and compare against the order that widget ended on, so a
+ * mapping that quietly loses a page fails there and not only here.
+ */
+export declare function replayTabPagesAsSplices(order: readonly string[], changes: readonly TabViewPagesChange[]): string[];

package/lib/types/conformance/menu.d.ts

@@ -0,0 +1,118 @@
+import type { AdwMenuActions, AdwMenuInput, AdwMenuItem, AdwMenuItemState, AdwMenuModel, AdwMenuPath } from '../menu.js';
+/** One {@link normalizeMenuModel} expectation. */
+export interface MenuNormalizeVector {
+    input: AdwMenuInput;
+    model: AdwMenuModel;
+    rule: string;
+}
+/**
+ * Authored input → the normalised tree.
+ *
+ * The first row is the shape the whole ADR is about: one menu value carrying a section,
+ * a detailed action with a target, an icon and a submenu — everything the three surfaces
+ * used to spell three different ways, or not at all.
+ */
+export declare const MENU_NORMALIZE_VECTORS: ReadonlyArray<MenuNormalizeVector>;
+/** One {@link parseMenuModel} expectation — the `menu` attribute door. */
+export interface MenuParseVector {
+    /** The raw attribute (or `null` when absent). */
+    json: string | null;
+    model: AdwMenuModel;
+    rule: string;
+}
+/**
+ * Menu-attribute parsing. Total: nothing an author can type may prevent the widget
+ * upgrading, which is why every malformed row below yields a menu rather than a throw.
+ */
+export declare const MENU_PARSE_VECTORS: ReadonlyArray<MenuParseVector>;
+/** One expected row of a {@link flattenMenu} walk. */
+export interface MenuFlatRowVector {
+    /** The label the row draws. */
+    label: string;
+    path: AdwMenuPath;
+    separated: boolean;
+}
+/** One {@link flattenMenu} expectation. */
+export interface MenuFlattenVector {
+    model: AdwMenuModel;
+    rows: readonly MenuFlatRowVector[];
+    rule: string;
+}
+/**
+ * The rows a one-list-at-a-time surface draws, and where a separator goes.
+ *
+ * A separator NEVER leads: a rule above nothing is a line at the top of the menu, which
+ * is what a naive "a section starts, so separate" rule produces for a menu whose first
+ * entry is a section.
+ */
+export declare const MENU_FLATTEN_VECTORS: ReadonlyArray<MenuFlattenVector>;
+/** One {@link parseDetailedAction} expectation, and what GIO makes of the same string. */
+export interface MenuDetailedActionVector {
+    detailed: string;
+    /** What the display-side splitter answers. It never throws. */
+    name: string;
+    target?: string;
+    /**
+     * Whether `g_action_parse_detailed_name` ACCEPTS the string.
+     *
+     * The load-bearing field, and the reason this table is driven twice. The splitter is
+     * lenient by design — it runs on a menu that has already been accepted, so it
+     * answers something for every input — and reading its answer as "this is a legal
+     * action name" is exactly the mistake that let `'app.x('` through to
+     * `g_menu_item_set_detailed_action`, which ABORTS the process on it. `false` rows
+     * are asserted to be REFUSED by `@gjsify/gtk-host`'s `buildGioMenu`; `true` rows are
+     * asserted to survive a round trip through a real `Gio.Menu`.
+     */
+    gioValid: boolean;
+    rule: string;
+}
+/**
+ * CORE-ONLY: the SPLITTER's answers are never read by a renderer — they exist for
+ * MENU_ITEM_STATE_VECTORS, which both renderer suites drive through the widget's action
+ * state, and a target that does not come off leaves every radio item reading `normal`.
+ * The `gioValid` half IS driven against a real implementation, by
+ * packages/framework/gtk-host/src/menu.spec.ts — the GTK host rather than an Adwaita
+ * port, so this gate does not count it as a renderer, and holds the PATH instead.
+ *
+ * `g_action_parse_detailed_name`'s two forms, the strings that are neither, and what the
+ * display-side splitter answers for each.
+ *
+ * IT IS DRIVEN TWICE, and the second drive is what the first cut was missing: the core
+ * suite asserts {@link parseDetailedAction}, and `@gjsify/gtk-host`'s menu suite sends
+ * every row through `buildGioMenu`. Without the second, this table DECLARED `'app.x('`
+ * legal while nothing ever handed it to GIO — and GIO answers a malformed name with
+ * `g_error()`, a SIGABRT no `catch` can see. A vector nobody drives against the real
+ * implementation is the shape `conformance/index.ts` warns about, one layer down.
+ */
+export declare const MENU_DETAILED_ACTION_VECTORS: ReadonlyArray<MenuDetailedActionVector>;
+/** One {@link resolveMenuItemState} expectation. */
+export interface MenuItemStateVector {
+    item: AdwMenuItem;
+    actions: AdwMenuActions;
+    state: AdwMenuItemState;
+    rule: string;
+}
+/**
+ * Where `enabled` and `checked` come from, which is NOT the menu.
+ *
+ * Every row cites `gtkmenutrackeritem.c`, because the whole table exists to show that a
+ * portable model carrying `enabled: false` on an item would be inventing a field
+ * `GMenuModel` has not got — and would then have nowhere to put it when the model is
+ * handed to a real `Gio.Menu`.
+ */
+export declare const MENU_ITEM_STATE_VECTORS: ReadonlyArray<MenuItemStateVector>;
+/** One {@link menuRefusals} expectation. */
+export interface MenuRefusalVector {
+    model: AdwMenuModel;
+    /** The paths that must be refused, in walk order. */
+    paths: readonly AdwMenuPath[];
+    rule: string;
+}
+/**
+ * What a surface without `gtk_popover_menu_add_child` will not draw.
+ *
+ * Every row is asserted for the WEB and NATIVESCRIPT surfaces (which refuse `custom`)
+ * and for GTK (which refuses nothing), so the table also pins down that the GTK path
+ * accepts every model the other two do.
+ */
+export declare const MENU_REFUSAL_VECTORS: ReadonlyArray<MenuRefusalVector>;

package/lib/types/conformance/rows.d.ts

@@ -5,8 +5,8 @@ import type { AdwComboOption, ComboStateChange } from '../rows.js';
  * and compares what the user would see.
  */
 export type ComboSelectionStep = {
-    op: 'setOptions';
-    options: ReadonlyArray<AdwComboOption>;
+    op: 'setModel';
+    model: ReadonlyArray<AdwComboOption>;
 } | {
     op: 'setSelectedIndex';
     index: number;
@@ -40,7 +40,7 @@ export interface ComboSelectionVector {
  * drives, plus the two port answers the C leaves open (see
  * the module header).
  *
- * Note that EVERY scenario starts with a `setOptions`, which is itself an
+ * Note that EVERY scenario starts with a `setModel`, which is itself an
  * emission: the model is what the label is read out of, so a renderer that
  * repaints only on a selection change draws a stale value after the list is
  * replaced. That first change is in `emitted` for exactly that reason.