@gjsify/adwaita-core 0.32.0 → 0.33.0

package/lib/types/conformance/entry-row.d.ts

@@ -123,6 +123,8 @@ export interface EntryRowGuardVector {
  * setter early-outs on an unchanged value (C:984, :1198, :1247, :1339), while
  * the private `adw_entry_row_set_show_indicator` (C:1281-1296) deliberately has
  * NO equality check and re-derives unconditionally.
+ *
+ * CORE-ONLY: GAP — the browser element discards the setter’s boolean, so the guard has no observable answer. Tracked in #1072
  */
 export declare const ENTRY_ROW_GUARD_VECTORS: ReadonlyArray<EntryRowGuardVector>;
 /** One mutation in a password-entry-row scenario. */

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

@@ -10,8 +10,8 @@ export { BUTTON_CONTENT_DEFAULT_VECTORS, BUTTON_CONTENT_ELLIPSIZE_VECTORS, BUTTO
 export type { ButtonContentDefaultVector, ButtonContentEllipsizeVector, ButtonContentIconVector, ButtonContentLabelVector, ButtonContentStyleTargetVector, ButtonContentTextVector, } from './button-content.js';
 export { RADIO_GROUP_VECTORS } from './checks.js';
 export type { RadioGroupStep, RadioGroupVector } from './checks.js';
-export { COMBO_SELECTION_VECTORS } from './rows.js';
-export type { ComboSelectionStep, ComboSelectionVector } from './rows.js';
+export { COMBO_CHOOSER_VECTORS, COMBO_SELECTION_VECTORS } from './rows.js';
+export type { ComboChooserVector, ComboSelectionStep, ComboSelectionVector } from './rows.js';
 export { VIEW_STACK_ICON_NAME_VECTORS, VIEW_STACK_PAGE_VECTORS, VIEW_STACK_VECTORS } from './view-stack.js';
 export type { ViewStackIconNameVector, ViewStackPageDescriptorVector, ViewStackVector, ViewStackVectorChange, ViewStackVectorOp, ViewStackVectorPage, } from './view-stack.js';
 export { NAVIGATION_VIEW_VECTORS, collectNavigationState, navigationEventLog, runNavigationSteps, } from './navigation-view.js';
@@ -40,5 +40,7 @@ export { BOTTOM_SHEET_CLOSE_VECTORS, BOTTOM_SHEET_PRESENTATION_VECTORS, runBotto
 export type { BottomSheetCloseVector, BottomSheetPresentationAdapter, BottomSheetPresentationStep, BottomSheetPresentationVector, } from './dialog.js';
 export { POPOVER_KEY_VECTORS, POPOVER_SURFACE_VECTORS } from './popover.js';
 export type { PopoverKeyVector, PopoverSurfaceVariant, PopoverSurfaceVector } from './popover.js';
-export { ADW_WRAP_BOX_DEFAULT_ALIGN, ADW_WRAP_BOX_DEFAULT_JUSTIFY, ADW_WRAP_BOX_DEFAULT_JUSTIFY_LAST_LINE, ADW_WRAP_BOX_DEFAULT_SPACING, WRAP_BOX_LINE_VECTORS, WRAP_BOX_SPACING_NOTIFY_VECTORS, WRAP_BOX_SPACING_VECTORS, } from './wrap-box.js';
-export type { WrapBoxJustify, WrapBoxLineLayout, WrapBoxLineVector, WrapBoxSpacingNotifyVector, WrapBoxSpacingVector, } from './wrap-box.js';
+export { SPINNER_ARC_ENVELOPE, SPINNER_ARC_PHASE_VECTORS, SPINNER_ARC_TOLERANCE, SPINNER_CONSTANT_VECTORS, } from './spinner.js';
+export type { SpinnerArcShapeVector, SpinnerConstantVector } from './spinner.js';
+export { WRAP_BOX_CHILD_ORDER_VECTORS, WRAP_BOX_LENGTH_VECTORS, WRAP_BOX_LINE_VECTORS, WRAP_BOX_NATURAL_LENGTH_VECTORS, WRAP_BOX_NOTIFY_PROPERTIES, WRAP_BOX_POLICY_VECTORS, WRAP_BOX_SPACING_NOTIFY_VECTORS, WRAP_BOX_SPACING_VECTORS, } from './wrap-box.js';
+export type { WrapBoxChildOrderVector, WrapBoxLengthVector, WrapBoxLineVector, WrapBoxNaturalLengthVector, WrapBoxPolicyVector, WrapBoxSpacingNotifyVector, WrapBoxSpacingVector, } from './wrap-box.js';

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

@@ -52,5 +52,7 @@ export interface PopoverKeyVector {
  * The rows that matter are the ones where the copies were WRONG rather than
  * merely duplicated: ArrowUp from an unfocused list (both computed `n - 2`), and
  * Home/End while a search entry owns the caret (the drop-down stole both).
+ *
+ * CORE-ONLY: GAP — `adw-popover` calls `resolvePopoverKey` on keydown but publishes no readable outcome for a spec to compare. Tracked in #1072
  */
 export declare const POPOVER_KEY_VECTORS: ReadonlyArray<PopoverKeyVector>;

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

@@ -40,6 +40,8 @@ export interface CaseFoldVector {
  * silently fails to match — in German, Greek and any text with a typographic
  * ligature. None of it is visible in an ASCII test suite, which is exactly why
  * the rows are here.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (PREFERENCES_SEARCH_VECTORS)
  */
 export declare const CASE_FOLD_VECTORS: ReadonlyArray<CaseFoldVector>;
 /** One `stripMarkup` expectation. */
@@ -58,6 +60,8 @@ export interface StripMarkupVector {
  * `null` is not an error case to be smoothed over: it is the branch where C
  * logs a `g_critical` and KEEPS the unparsed string, so every `null` row below
  * is a row that must stay searchable under its literal spelling.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (PREFERENCES_SEARCH_VECTORS)
  */
 export declare const STRIP_MARKUP_VECTORS: ReadonlyArray<StripMarkupVector>;
 /** One `stripMnemonic` expectation. */
@@ -72,6 +76,8 @@ export interface StripMnemonicVector {
 /**
  * `adw_strip_mnemonic` (adw-widget-utils.c:685-703) — `g_markup_escape_text`
  * followed by `pango_parse_markup` with `accel_marker = '_'`.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (PREFERENCES_SEARCH_VECTORS)
  */
 export declare const STRIP_MNEMONIC_VECTORS: ReadonlyArray<StripMnemonicVector>;
 /** One `makeComparable` expectation. */
@@ -91,6 +97,8 @@ export interface MakeComparableVector {
  * The defaults matter as much as the rows: `use-markup` defaults to TRUE
  * (adw-preferences-row.c:185-188) and `use-underline` to FALSE (:155-158), so
  * an ordinary row's title IS markup-parsed and is NOT mnemonic-stripped.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (PREFERENCES_SEARCH_VECTORS)
  */
 export declare const MAKE_COMPARABLE_VECTORS: ReadonlyArray<MakeComparableVector>;
 /** One `rowMatchesQuery` expectation. */
@@ -104,7 +112,9 @@ export interface RowMatchVector {
     /** Why this row exists. */
     rule: string;
 }
-/** `filter_search_results` (adw-preferences-dialog.c:125-153). */
+/** `filter_search_results` (adw-preferences-dialog.c:125-153).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (PREFERENCES_SEARCH_VECTORS)
+ */
 export declare const ROW_MATCH_VECTORS: ReadonlyArray<RowMatchVector>;
 /** One `collectSearchRows` expectation. */
 export interface SearchCorpusVector {
@@ -124,6 +134,8 @@ export interface SearchCorpusVector {
  * Dropping any clause is invisible — nothing errors, the search just quietly
  * indexes the wrong set — which is why these rows are separate from the
  * end-to-end ones.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (PREFERENCES_SEARCH_VECTORS)
  */
 export declare const SEARCH_CORPUS_VECTORS: ReadonlyArray<SearchCorpusVector>;
 /** One `createSearchRowSubtitle` expectation. */
@@ -135,7 +147,9 @@ export interface SearchRowSubtitleVector {
     /** Why this row exists. */
     rule: string;
 }
-/** `create_search_row_subtitle` (adw-preferences-dialog.c:168-234). */
+/** `create_search_row_subtitle` (adw-preferences-dialog.c:168-234).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (PREFERENCES_SEARCH_VECTORS)
+ */
 export declare const SEARCH_ROW_SUBTITLE_VECTORS: ReadonlyArray<SearchRowSubtitleVector>;
 /**
  * The page tree both renderer suites materialise into real widgets.

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

@@ -49,3 +49,26 @@ export interface ComboSelectionVector {
  * replaced. That first change is in `emitted` for exactly that reason.
  */
 export declare const COMBO_SELECTION_VECTORS: ReadonlyArray<ComboSelectionVector>;
+/** One `presentsChooser` expectation. */
+export interface ComboChooserVector {
+    /** How many options the model holds. */
+    count: number;
+    /** Whether the arrow is drawn and the row is activatable. */
+    presentsChooser: boolean;
+    /** The rule this row pins down. */
+    rule: string;
+}
+/**
+ * `model_changed` (adw-combo-row.c:187-195) — one predicate, `n_items > 1`,
+ * driving BOTH `gtk_widget_set_visible (arrow_box, …)` and
+ * `gtk_list_box_row_set_activatable (row, …)`.
+ *
+ * A row with one option or none has nothing to choose, so it stops presenting
+ * itself as a chooser. Neither port did this: a NativeScript `AdwComboRow` with
+ * a single option still showed its chevron and opened an `action()` sheet with
+ * one entry, and the browser element behaved the same way.
+ *
+ * `Gtk.DropDown` is deliberately NOT covered — it keeps its arrow at any count,
+ * which is why this lives on the combo ROW rather than in the shared chooser.
+ */
+export declare const COMBO_CHOOSER_VECTORS: ReadonlyArray<ComboChooserVector>;

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

@@ -0,0 +1,66 @@
+/** How close two radian values have to be to count as equal. */
+export declare const SPINNER_ARC_TOLERANCE = 1e-9;
+/**
+ * The arc lengths actually DRAWN, in radians — measured over one cycle at 200k
+ * samples, not read off the constants.
+ *
+ * The distinction matters and is easy to get wrong: `MAX_ARC_LENGTH` is
+ * `pi * 0.9` (162 degrees), and both `get_arc_start` and `get_arc_end` lerp
+ * TOWARDS it — but each then subtracts the drift term
+ * `angle * MAX_ARC_LENGTH / cycle_length`, which is what makes the figure
+ * advance around the circle. The two ends drift together, so the visible arc
+ * peaks at **102.8 degrees**, not 162. Reading the constant as the drawn length
+ * is the obvious mistake; issue #1066 made it in its own summary table.
+ *
+ * The MINIMUM is exactly `MIN_ARC_LENGTH`, because the drift is zero at the
+ * cycle boundary where the arc is shortest.
+ */
+export declare const SPINNER_ARC_ENVELOPE: {
+    /** Exactly `MIN_ARC_LENGTH` — 2.7 degrees, at the cycle boundary. */
+    readonly min: number;
+    /** 102.815... degrees. Asserted to a tolerance, not to the last digit. */
+    readonly max: 1.794463;
+    /** How far a measured extreme may sit from the value above. */
+    readonly tolerance: 0.0001;
+};
+/**
+ * `get_arc_start` / `get_arc_end` (adw-spinner-paintable.c:109-145) at the four
+ * corners of one cycle, plus the resting pose.
+ *
+ * The lengths are DERIVED from the C's own constants rather than typed in: the
+ * point of the rows is which MOMENT each is, and a hand-copied radian would be a
+ * second reading of the same arithmetic the implementation does. What they pin
+ * is the shape — that the arc is shortest at the cycle boundary, longest around
+ * the extend/contract handover, and never leaves `[MIN_ARC_LENGTH,
+ * MAX_ARC_LENGTH]`.
+ */
+export interface SpinnerArcShapeVector {
+    /** Fraction of one arc cycle, 0..1. */
+    phase: number;
+    /** What happens here. */
+    rule: string;
+}
+/** The moments worth naming in one arc cycle.  *
+ * CORE-ONLY: the arc is drawn per frame from `spinnerArc`, and a renderer can only show the RESULT — the browser suite asserts the drawn envelope and the round caps, which is the observable half
+ */
+export declare const SPINNER_ARC_PHASE_VECTORS: ReadonlyArray<SpinnerArcShapeVector>;
+/** One "is this constant what the C says" expectation. */
+export interface SpinnerConstantVector {
+    /** The constant's name in the C. */
+    name: string;
+    /** Its value, as a multiple of pi where the C writes one. */
+    value: number;
+    /** Where it is defined and what the ports had instead. */
+    rule: string;
+}
+/**
+ * The `#define`s at adw-spinner-paintable.c:18-33 and adw-spinner.c:14-15.
+ *
+ * A constant table looks redundant next to the implementation until you read the
+ * `rule` column: five of these seven were WRONG or absent in a shipping port,
+ * and a table is what makes "the port picked its own number" fail a test rather
+ * than look like a design choice.
+ *
+ * CORE-ONLY: a table OF constants: what a renderer can show is the geometry they produce, which the browser suite asserts through SPINNER_GEOMETRY/SIZE_VECTORS
+ */
+export declare const SPINNER_CONSTANT_VECTORS: ReadonlyArray<SpinnerConstantVector>;

package/lib/types/conformance/split-button.d.ts

@@ -113,6 +113,8 @@ export declare const SPLIT_BUTTON_DIRECTION_VECTORS: ReadonlyArray<SplitButtonDi
  * demonstrated OVERRIDE rather than an assertion. Holding both means a reader can
  * see the two values and the two selectors side by side, and a renderer that
  * reaches for the wrong one fails a test that names which widget it is drawing.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (SPLIT_BUTTON_DIRECTION_VECTORS)
  */
 export declare const MENU_BUTTON_DIRECTION_VECTORS: ReadonlyArray<SplitButtonDirectionVector>;
 /** One `update_state` expectation. */
@@ -132,6 +134,8 @@ export interface SplitButtonRootStateVector {
  * `update_state` (adw-split-button.c:118-143) — an OR-fold of both halves onto
  * the root, which is what `splitbutton.flat:active/:checked` styles
  * (_buttons.scss:542-549).
+ *
+ * CORE-ONLY: GAP — two of its three axes are hardcoded in the renderer, so there is nothing to vary. Tracked in #1072
  */
 export declare const SPLIT_BUTTON_ROOT_STATE_VECTORS: ReadonlyArray<SplitButtonRootStateVector>;
 /** One `parseMenuEntries` expectation. */

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

@@ -1,4 +1,5 @@
-import type { AdwLengthUnit, AdwPackType, AdwTextDirection, NavigationActionResult, NavigationStackPlan, OverlaySplitViewLayout, SidebarWidthSpec, SplitViewPaneRect } from '../split-view.js';
+import type { AdwLengthUnit } from '../length-unit.js';
+import type { AdwPackType, AdwTextDirection, NavigationActionResult, NavigationStackPlan, OverlaySplitViewLayout, SidebarWidthSpec, SplitViewPaneRect } from '../split-view.js';
 /** One `adwLengthToPx` expectation. */
 export interface AdwLengthUnitVector {
     unit: AdwLengthUnit;
@@ -10,7 +11,9 @@ export interface AdwLengthUnitVector {
     /** Why this row exists. */
     rule: string;
 }
-/** `adw_length_unit_to_px` (adw-length-unit.c:72-81). */
+/** `adw_length_unit_to_px` (adw-length-unit.c:72-81).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (SIDEBAR_BOUNDS_VECTORS, which both renderers drive)
+ */
 export declare const ADW_LENGTH_UNIT_VECTORS: ReadonlyArray<AdwLengthUnitVector>;
 /** One `glibClamp` expectation. */
 export interface GlibClampVector {
@@ -27,6 +30,8 @@ export interface GlibClampVector {
  * The inverted rows are the point: `Math.min(high, Math.max(low, x))` returns
  * `high` there, and `allocate_uncollapsed` reaches inverted bounds whenever the
  * content pane's own minimum leaves less room than `min-sidebar-width`.
+ *
+ * CORE-ONLY: GLib’s CLAMP itself — a primitive with no widget surface; every widget that reaches it does so through a table that IS driven
  */
 export declare const GLIB_CLAMP_VECTORS: ReadonlyArray<GlibClampVector>;
 /** One `resolveSidebarBounds` expectation. */
@@ -83,6 +88,8 @@ export interface NaturalSidebarWidthVector {
 /**
  * `measure_uncollapsed`'s sidebar estimate (adw-navigation-split-view.c:260-262,
  * adw-overlay-split-view.c:554-556) — the sidebar's OWN natural width is ignored.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (SIDEBAR_WIDTH_VECTORS)
  */
 export declare const NATURAL_SIDEBAR_WIDTH_VECTORS: ReadonlyArray<NaturalSidebarWidthVector>;
 /** One `measureSplitViewHorizontal` expectation. */
@@ -103,6 +110,8 @@ export interface SplitViewMeasureVector {
  *
  * This is the container minimum neither renderer had — which is why in both of them
  * the content pane shrinks to nothing instead of the window refusing to get narrower.
+ *
+ * CORE-ONLY: the container minimum lands as `min-width: min-content` on the content pane, which is CSS’s own spelling of the same rule — there is no computed number of ours to compare. Asserted in the renderer as "the pane is not crushable" instead
  */
 export declare const SPLIT_VIEW_MEASURE_VECTORS: ReadonlyArray<SplitViewMeasureVector>;
 /** One `layoutNavigationSplitView` expectation. */
@@ -144,7 +153,9 @@ export interface TagsConflictVector {
     conflict: boolean;
     rule: string;
 }
-/** `tags_equal` (adw-navigation-split-view.c:413-429). */
+/** `tags_equal` (adw-navigation-split-view.c:413-429).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (the tag guard, driven through NAVIGATION_ACTION_VECTORS and the refusal tests in both renderer suites)
+ */
 export declare const TAGS_CONFLICT_VECTORS: ReadonlyArray<TagsConflictVector>;
 /** One `resolveNavigationStack` expectation. */
 export interface NavigationStackVector {

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

@@ -290,6 +290,8 @@ export interface TabSuccessorVector {
  *
  * 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. */
@@ -305,7 +307,9 @@ export interface TabDescendantVector {
     /** Whether the walk reaches the ancestor. */
     descendant: boolean;
 }
-/** `is_descendant_of` (adw-tab-view.c:1735-1742). */
+/** `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 {
@@ -374,6 +378,8 @@ export interface TabTooltipVector {
  * `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. */
@@ -437,5 +443,7 @@ export interface TabPageDescriptorVector {
  * (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/wrap-box.d.ts

@@ -1,59 +1,8 @@
-/**
- * `Adw.WrapBox:child-spacing` and `:line-spacing` defaults, in px.
- *
- * Both are `g_param_spec_int (…, 0, G_MAXINT, 0, …)` — adw-wrap-box.c:285-287
- * and :393-395. The NativeScript port defaulted BOTH to 6 DIPs, so identical
- * markup was looser on a phone than in the browser.
- */
-export declare const ADW_WRAP_BOX_DEFAULT_SPACING = 0;
-/**
- * `Adw.WrapBox:align` default (adw-wrap-box.c:335-337).
- *
- * Declared `g_param_spec_float (…, 0, 1, 0, …)`, so GObject validates an
- * out-of-range value back into `[0, 1]` on set.
- */
-export declare const ADW_WRAP_BOX_DEFAULT_ALIGN = 0;
-/** `Adw.WrapBox:justify` default — `ADW_JUSTIFY_NONE` (adw-wrap-box.c:364-366). */
-export declare const ADW_WRAP_BOX_DEFAULT_JUSTIFY = "none";
-/** `Adw.WrapBox:justify-last-line` default — `FALSE` (adw-wrap-box.c:379-381). */
-export declare const ADW_WRAP_BOX_DEFAULT_JUSTIFY_LAST_LINE = false;
-/** `AdwJustifyMode` — the three values of `Adw.WrapBox:justify`. */
-export type WrapBoxJustify = 'none' | 'fill' | 'spread';
-/** What a renderer has to do with a line's leftover space. */
-export interface WrapBoxLineLayout {
-    /**
-     * The justify mode that governs THIS line, after the last-line gate. It is
-     * the widget's `justify` for every line except the final one, and for the
-     * final one only when `justify-last-line` is set
-     * (adw-wrap-layout.c:397-400, :705-706).
-     */
-    justify: WrapBoxJustify;
-    /**
-     * Whether the CHILDREN absorb the leftover (`allocated_size` grows to
-     * `available_size`, adw-wrap-layout.c:336-341). CSS: `flex-grow` on the
-     * items.
-     */
-    growChildren: boolean;
-    /**
-     * Whether the GAPS absorb the leftover — children keep `minimum_size` and
-     * are spread apart by `size_delta` (adw-wrap-layout.c:338-339, :752-757).
-     * CSS: `justify-content: space-between`.
-     */
-    growGaps: boolean;
-    /**
-     * The MAIN-axis offset factor applied to the whole line block when nothing
-     * grows: `widget_offset += roundf (length_delta * align)`
-     * (adw-wrap-layout.c:717-725). 0 packs the line at the start of the main
-     * axis, 1 at its end. Meaningless — and reported as 0 — as soon as the line
-     * is justified, because C only computes `length_delta` inside
-     * `if (!justify_line)`.
-     */
-    align: number;
-}
+import type { AdwWrapBoxJustify, AdwWrapPolicy, WrapBoxLineLayout } from '../wrap-box.js';
 /** One row of the decision table. */
 export interface WrapBoxLineVector {
     /** The widget's `justify` property. */
-    justify: WrapBoxJustify;
+    justify: AdwWrapBoxJustify;
     /** The widget's `justify-last-line` property. */
     justifyLastLine: boolean;
     /** The widget's `align` property, already validated into `[0, 1]`. */
@@ -132,3 +81,105 @@ export interface WrapBoxSpacingNotifyVector {
  * `notify::child-spacing` for a value libadwaita had normalised away.
  */
 export declare const WRAP_BOX_SPACING_NOTIFY_VECTORS: ReadonlyArray<WrapBoxSpacingNotifyVector>;
+/**
+ * Every `notify::` an `Adw.WrapBox` emits — the thirteen installed pspecs
+ * (adw-wrap-box.c:284-495) plus the overridden `orientation` (:497).
+ *
+ * The count is the assertion. C notifies on all fourteen; the browser port
+ * notified on TWO (`child-spacing`, `line-spacing`) and the NativeScript port on
+ * none, so a consumer binding to any other property was watching a signal that
+ * could not fire. A roster is the only shape that fails when a property is ADDED
+ * without its notification, which is how the first twelve went missing.
+ */
+export declare const WRAP_BOX_NOTIFY_PROPERTIES: readonly string[];
+/** One `wrap-policy` → child-shrink expectation. */
+export interface WrapBoxPolicyVector {
+    /** The authored value. Anything not in the enum leaves the property at its default. */
+    value: unknown;
+    /** The stored policy. */
+    policy: AdwWrapPolicy;
+    /** The `flex-shrink` a child gets — `FlexboxLayout.setFlexShrink` on NativeScript. */
+    flexShrink: number;
+    /** The rule this row pins down. */
+    rule: string;
+}
+/**
+ * `Adw.WrapBox:wrap-policy` (adw-wrap-box.c:476-495).
+ *
+ * The default is `natural`, which is the RESTRICTIVE one: a line wraps as soon
+ * as the next child would not fit at its natural size. `minimum` packs harder by
+ * squeezing children down to their minimum first. Both renderers had neither, so
+ * they inherited whatever their flex container defaults to — and CSS defaults
+ * `flex-shrink` to 1, i.e. to `minimum`, the value libadwaita does NOT default to.
+ */
+export declare const WRAP_BOX_POLICY_VECTORS: ReadonlyArray<WrapBoxPolicyVector>;
+/** One length-unit conversion expectation. */
+export interface WrapBoxLengthVector {
+    /** The property value, in `unit`. */
+    value: number;
+    /** The authored unit. Anything outside the enum falls back to the `px` default. */
+    unit: unknown;
+    /** The `gtk-xft-dpi` the renderer reports. */
+    dpi: number;
+    /** The resolved pixel length. */
+    px: number;
+    /** The rule this row pins down. */
+    rule: string;
+}
+/**
+ * `adw_length_unit_to_px` as the three wrap-box length properties reach it
+ * (adw-wrap-layout.c:554-565, :798-804).
+ *
+ * The wrap box defaults its units to `px` where the split views default to `sp`
+ * (adw-wrap-box.c:300-305) — the same helper, two different defaults, which is
+ * why the fallback is the caller's argument and not the helper's.
+ */
+export declare const WRAP_BOX_LENGTH_VECTORS: ReadonlyArray<WrapBoxLengthVector>;
+/** One `natural-line-length` normalisation expectation. */
+export interface WrapBoxNaturalLengthVector {
+    /** The authored value. */
+    value: unknown;
+    /** The stored length, `-1` when unset. */
+    length: number;
+    /** The rule this row pins down. */
+    rule: string;
+}
+/**
+ * `Adw.WrapBox:natural-line-length` — `g_param_spec_int (…, -1, G_MAXINT, -1, …)`
+ * (adw-wrap-box.c:438-441).
+ *
+ * `-1` means UNSET, not "zero length", so it is the landing place for everything
+ * out of range: a GObject setter would have refused those and left the property
+ * where it was, and unset is where it was born.
+ */
+export declare const WRAP_BOX_NATURAL_LENGTH_VECTORS: ReadonlyArray<WrapBoxNaturalLengthVector>;
+/** One `insert_child_after` / `reorder_child_after` expectation. */
+export interface WrapBoxChildOrderVector {
+    /** Which operation is being resolved. */
+    op: 'insert-after' | 'reorder-after';
+    /** The box's children before the call. */
+    children: readonly string[];
+    /** The child being placed. */
+    child: string;
+    /** The sibling to place it after, or `null` for the FIRST position. */
+    sibling: string | null;
+    /** The children afterwards, or `null` when the call is refused. */
+    result: readonly string[] | null;
+    /** The rule this row pins down. */
+    rule: string;
+}
+/**
+ * `adw_wrap_box_insert_child_after` (adw-wrap-box.c:1283-1300) and
+ * `adw_wrap_box_reorder_child_after` (:1315-1332), both of which delegate to
+ * `gtk_widget_insert_after (child, self, sibling)`.
+ *
+ * The counter-intuitive rule is the NULL sibling: it inserts at the FIRST
+ * position, not the last. Reading it as "append" is the obvious misreading and a
+ * silent one — the child lands somewhere plausible. Neither renderer had any of
+ * this API, so there was nothing to misread yet, which is the good time to pin it.
+ *
+ * The refusals are the C's `g_return_if_fail`s: an insert wants the child
+ * unparented, a reorder wants it already a child, the sibling must belong to this
+ * box, and `child == sibling` is an explicit early return in both (:1297, :1329).
+ */
+export declare const WRAP_BOX_CHILD_ORDER_VECTORS: ReadonlyArray<WrapBoxChildOrderVector>;

package/lib/types/easing.d.ts

@@ -0,0 +1,21 @@
+/** `adw_lerp` (adw-animation-util.c:23-27) — `a * (1 - t) + b * t`. */
+export declare function adwLerp(a: number, b: number, t: number): number;
+/**
+ * The inverse: where `r` sits between `a` and `b`, as a 0..1 fraction.
+ *
+ * Not a libadwaita function — C writes the division inline — but it is the same
+ * expression at every call site, and naming it is what keeps the two directions
+ * from drifting apart.
+ */
+export declare function inverseLerp(a: number, b: number, r: number): number;
+/** `ease_out_cubic` (adw-easing.c) — `(t - 1)^3 + 1`. */
+export declare function easeOutCubic(t: number): number;
+/**
+ * `ease_in_out_sine` (adw-easing.c:276-281) — `-0.5 * (cos(pi * t) - 1)`, with
+ * the duration argument at its only used value, 1.
+ *
+ * This is the curve the spinner's arc breathes on, at BOTH ends: `get_arc_start`
+ * eases the extend phase and `get_arc_end` the contract phase
+ * (adw-spinner-paintable.c:121, :141).
+ */
+export declare function easeInOutSine(t: number): number;

package/lib/types/index.d.ts

@@ -20,7 +20,7 @@ export { AdwToast, AdwToastQueue, DEFAULT_TOAST_TIMEOUT } from './toast.js';
 export type { AdwToastOptions, AdwToastQueueHandlers, AdwToastQueueOptions, ToastScheduler, ToastTimerHandle, } from './toast.js';
 export { AdwAlertResponses, BottomSheetPresentation, resolveBottomSheetClose } from './dialog.js';
 export type { AdwAlertResponse, AdwResponseAppearance, AdwResponseOptions, BottomSheetCloseOutcome, BottomSheetCloseSource, BottomSheetCloseState, BottomSheetPresentationListener, BottomSheetPresentationOptions, BottomSheetTeardownCallback, OrderedConfirmResponses, } from './dialog.js';
-export { ComboState, ExpanderState, SpinState, ToggleGroupState, normalizeComboOptions } from './rows.js';
+export { ADW_COMBO_NO_SELECTION, ComboState, ExpanderState, SpinState, ToggleGroupState, normalizeComboOptions, } from './rows.js';
 export type { AdwComboOption, AdwComboOptionInput, ComboStateChange, ComboStateListener, ExpanderStateListener, SpinStateChange, SpinStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
 export { glibClamp, gStrStrip, stringIsNotEmpty } from './glib.js';
 export { ViewStackState, normalizeIconName, resolvePageTitle } from './view-stack.js';
@@ -31,8 +31,13 @@ export { ADW_SIDEBAR_NO_SELECTION, SidebarState, adjustSidebarSelection, clampSi
 export type { AdwSidebarItemSpec, AdwSidebarMode, AdwSidebarSectionSpec, SidebarActivation, SidebarFlatItem, SidebarHeaderSpec, SidebarItemFilter, SidebarSelectionChange, SidebarStateListener, } from './sidebar.js';
 export { CAPS_LOCK_ICON_NAME, CAPS_LOCK_TOOLTIP, EMPTY_ANIMATION_DURATION_MS, ENTRY_ROW_APPLY_ICON_NAME, ENTRY_ROW_APPLY_TOOLTIP, ENTRY_ROW_EDIT_ICON_NAME, ENTRY_ROW_MAX_LENGTH_LIMIT, ENTRY_ROW_TITLE_SPACING, EntryRowState, PASSWORD_CONCEAL_ICON_NAME, PASSWORD_CONCEAL_LABEL, PASSWORD_REVEAL_ICON_NAME, PASSWORD_REVEAL_LABEL, PasswordEntryRowState, clampEntryText, entryTextLength, } from './entry-row.js';
 export type { EntryRowActivation, EntryRowRenderState, EntryRowStateListener, PasswordEntryRowRenderState, PasswordEntryRowStateListener, } from './entry-row.js';
-export { ADW_SWIPE_BORDER, DEFAULT_DPI, DEFAULT_MAX_SIDEBAR_WIDTH, DEFAULT_MIN_SIDEBAR_WIDTH, DEFAULT_SIDEBAR_WIDTH_FRACTION, DEFAULT_SIDEBAR_WIDTH_UNIT, INSTANT_SPLIT_VIEW_ANIMATOR, NAVIGATION_SPLIT_VIEW_CRITICALS, NavigationSplitViewState, OverlaySplitViewState, adwLengthToPx, isSidebarAtVisualStart, layoutNavigationSplitView, layoutOverlaySplitView, measureSplitViewHorizontal, resolveNaturalSidebarWidth, resolveNavigationAction, resolveNavigationSidebarWidth, resolveNavigationStack, resolveOverlaySidebarWidth, resolveSidebarBounds, resolveSwipeArea, resolveSwipeRelease, resolveSwipeSnapPoints, resolveSwipeStart, swipeCancelProgress, tagsConflict, } from './split-view.js';
-export type { AdwLengthUnit, AdwPackType, AdwTextDirection, NavigationActionInput, NavigationActionResult, NavigationPageRef, NavigationSplitViewChange, NavigationSplitViewHandlers, NavigationSplitViewLayout, NavigationSplitViewListener, NavigationSplitViewOptions, NavigationSplitViewProperty, NavigationStackPlan, OverlaySplitViewChange, OverlaySplitViewLayout, OverlaySplitViewListener, OverlaySplitViewOptions, OverlaySplitViewProperty, SidebarBounds, SidebarWidthInput, SidebarWidthSpec, SplitViewAnimation, SplitViewAnimationRequest, SplitViewAnimator, SplitViewMeasureInput, SplitViewPane, SplitViewPaneRect, SwipeReleasePlan, } from './split-view.js';
+export { adwLerp, easeInOutSine, easeOutCubic, inverseLerp } from './easing.js';
+export { ADW_SPINNER_CYCLES_PER_LOOP, ADW_SPINNER_CYCLE_LENGTH, ADW_SPINNER_CONTRACT_DISTANCE, ADW_SPINNER_EXTEND_DISTANCE, ADW_SPINNER_IDLE_DISTANCE, ADW_SPINNER_MAX_ARC_LENGTH, ADW_SPINNER_MIN_ARC_LENGTH, ADW_SPINNER_N_CYCLES, ADW_SPINNER_OVERLAP_DISTANCE, ADW_SPINNER_SPIN_DURATION_MS, ADW_SPINNER_START_ANGLE, ADW_SPINNER_STILL_PROGRESS, ADW_SPINNER_TRACK_OPACITY, normalizeSpinnerAngle, spinnerArc, spinnerArcEnd, spinnerArcStart, spinnerProgressAt, } from './spinner.js';
+export type { SpinnerArc } from './spinner.js';
+export { ADW_LENGTH_UNITS, DEFAULT_DPI, adwLengthToPx, normalizeLengthUnit } from './length-unit.js';
+export type { AdwLengthUnit } from './length-unit.js';
+export { ADW_SWIPE_BORDER, DEFAULT_MAX_SIDEBAR_WIDTH, DEFAULT_MIN_SIDEBAR_WIDTH, DEFAULT_SIDEBAR_WIDTH_FRACTION, DEFAULT_SIDEBAR_WIDTH_UNIT, INSTANT_SPLIT_VIEW_ANIMATOR, NAVIGATION_SPLIT_VIEW_CRITICALS, NavigationSplitViewState, OverlaySplitViewState, isSidebarAtVisualStart, layoutNavigationSplitView, layoutOverlaySplitView, measureSplitViewHorizontal, resolveNaturalSidebarWidth, resolveNavigationAction, resolveNavigationSidebarWidth, resolveNavigationStack, resolveOverlaySidebarWidth, resolveSidebarBounds, resolveSwipeArea, resolveSwipeRelease, resolveSwipeSnapPoints, resolveSwipeStart, swipeCancelProgress, tagsConflict, } from './split-view.js';
+export type { AdwPackType, AdwTextDirection, NavigationActionInput, NavigationActionResult, NavigationPageRef, NavigationSplitViewChange, NavigationSplitViewHandlers, NavigationSplitViewLayout, NavigationSplitViewListener, NavigationSplitViewOptions, NavigationSplitViewProperty, NavigationStackPlan, OverlaySplitViewChange, OverlaySplitViewLayout, OverlaySplitViewListener, OverlaySplitViewOptions, OverlaySplitViewProperty, SidebarBounds, SidebarWidthInput, SidebarWidthSpec, SplitViewAnimation, SplitViewAnimationRequest, SplitViewAnimator, SplitViewMeasureInput, SplitViewPane, SplitViewPaneRect, SwipeReleasePlan, } from './split-view.js';
 export { DEFAULT_DROPDOWN_TOOLTIP, SPLIT_BUTTON_DISABLED_OPACITY, SplitButtonState, isSplitButtonDirection, menuButtonArrowIcon, menuButtonPopupDirection, parseMenuEntries, resolveDropdownTooltip, splitButtonArrowIcon, splitButtonPopupDirection, splitButtonRootState, splitButtonStyleClasses, } from './split-button.js';
 export type { AdwArrowIcon, AdwMenuEntry, SplitButtonChange, SplitButtonContentMode, SplitButtonDirection, SplitButtonHalfState, SplitButtonListener, SplitButtonProperty, SplitButtonStyleClass, } from './split-button.js';
 export { DEFAULT_INDICATOR_DESCRIPTION_STRINGS, INLINE_VIEW_SWITCHER_DISPLAY_MODES, VIEW_SWITCHER_BADGE_LIMIT, VIEW_SWITCHER_DRAG_SWITCH_DELAY, VIEW_SWITCHER_FALLBACK_ICON, VIEW_SWITCHER_NO_SELECTION, VIEW_SWITCHER_POLICIES, ViewSwitcherBarState, ViewSwitcherDragSwitch, ViewSwitcherState, buildInlineToggles, buildViewSwitcherButtons, createViewSwitcherPage, inlineToggleTooltip, isInlineViewSwitcherDisplayMode, isViewSwitcherButtonVisible, isViewSwitcherPolicy, pageIndexForToggle, shouldRevealViewSwitcherBar, stripMnemonic, toggleIndexForPage, viewSwitcherBadgeLabel, viewSwitcherButtonOrientation, viewSwitcherIconName, viewSwitcherIndicatorDescription, viewSwitcherLabel, viewSwitcherPageFromStackPage, viewSwitcherPagesFromStack, } from './view-switcher.js';
@@ -47,3 +52,5 @@ export { ADW_CLAMP_DEFAULTS, ADW_CLAMP_SIZE_CLASSES, ADW_SPINNER_MAX_SIZE, ADW_S
 export type { AdwClampSizeClass, AdwMeasurement, AdwToolbarStyle, ClampAllocation, ClampParams, ClampThresholds, SpinnerGeometry, ToolbarViewAllocateInput, ToolbarViewAllocation, ToolbarViewClassInput, ToolbarViewClasses, ToolbarViewContentForSize, ToolbarViewContentForSizeInput, ToolbarViewMeasureInput, } from './chrome.js';
 export { POPOVER_ITEM_RADIUS, POPOVER_MENU_PADDING, POPOVER_PADDING, POPOVER_RADIUS, PopoverState, resolvePopoverKey, } from './popover.js';
 export type { PopoverKeyAction, PopoverKeyContext, PopoverKeyResolution, PopoverStateChange, PopoverStateListener, } from './popover.js';
+export { ADW_WRAP_BOX_DEFAULT_ALIGN, ADW_WRAP_BOX_DEFAULT_JUSTIFY, ADW_WRAP_BOX_DEFAULT_JUSTIFY_LAST_LINE, ADW_WRAP_BOX_DEFAULT_LENGTH_UNIT, ADW_WRAP_BOX_DEFAULT_PACK_DIRECTION, ADW_WRAP_BOX_DEFAULT_SPACING, ADW_WRAP_BOX_DEFAULT_WRAP_POLICY, ADW_WRAP_BOX_JUSTIFY_MODES, ADW_WRAP_BOX_NATURAL_LINE_LENGTH_UNSET, ADW_WRAP_BOX_PACK_DIRECTIONS, ADW_WRAP_POLICIES, normalizeNaturalLineLength, normalizeWrapBoxAlign, normalizeWrapBoxJustify, normalizeWrapBoxLengthUnit, normalizeWrapBoxPackDirection, normalizeWrapBoxSpacing, normalizeWrapPolicy, resolveWrapBoxChildOrder, resolveWrapBoxLine, wrapBoxLengthToPx, wrapPolicyFlexShrink, } from './wrap-box.js';
+export type { AdwWrapBoxJustify, AdwWrapBoxOrientation, AdwWrapBoxPackDirection, AdwWrapPolicy, WrapBoxChildOrderOp, WrapBoxLineLayout, } from './wrap-box.js';

package/lib/types/length-unit.d.ts

@@ -0,0 +1,24 @@
+/** `AdwLengthUnit` — the unit a scale-aware length is written in. */
+export type AdwLengthUnit = 'px' | 'pt' | 'sp';
+/** The three units, for validating an attribute against the C enum. */
+export declare const ADW_LENGTH_UNITS: readonly AdwLengthUnit[];
+/** The dpi `adw_length_unit_to_px` falls back to when `gtk-xft-dpi` is unset. */
+export declare const DEFAULT_DPI = 96;
+/**
+ * `adw_length_unit_to_px` (adw-length-unit.c:57-82) — convert `value` to pixels.
+ *
+ * `pt` and `sp` both scale with the text-scale factor, which GTK reads from
+ * `gtk-xft-dpi`; a renderer that has no such setting passes the default 96, where
+ * `sp` is a pixel passthrough and `pt` is the familiar 4/3 ratio.
+ */
+export declare function adwLengthToPx(unit: AdwLengthUnit, value: number, dpi?: number): number;
+/**
+ * An authored unit → the enum value, or the caller's default.
+ *
+ * A GObject enum property REJECTS an out-of-range value and keeps what it had;
+ * a renderer reading an HTML attribute or an XML layout has no such gate, so the
+ * unusable value has to land somewhere deliberate. `fallback` is the property's
+ * own default, which differs between the widgets that use this vocabulary — the
+ * split views default to `sp`, the wrap box to `px`.
+ */
+export declare function normalizeLengthUnit(value: unknown, fallback: AdwLengthUnit): AdwLengthUnit;

package/lib/types/rows.d.ts

@@ -55,9 +55,24 @@ export type AdwComboOptionInput = string | {
  * reached for.
  */
 export declare function normalizeComboOptions(raw: ReadonlyArray<AdwComboOptionInput> | null | undefined): AdwComboOption[];
+/**
+ * The "no item is selected" index — the TS mirror of `GTK_INVALID_LIST_POSITION`
+ * (`AdwComboRow:selected`'s default and empty value, adw-combo-row.c:593-596,
+ * :809-810).
+ *
+ * libadwaita spells it `G_MAXUINT` because the property is a `guint`; `-1` is the
+ * idiomatic TS sentinel and the spelling {@link ADW_SIDEBAR_NO_SELECTION} already
+ * uses for the same GTK constant.
+ *
+ * It exists because an EMPTY model and a model whose first item happens to have
+ * an empty label were previously indistinguishable: both reported index 0 with
+ * `selectedValue === ''`. A renderer that wants to draw a placeholder had nothing
+ * to test.
+ */
+export declare const ADW_COMBO_NO_SELECTION = -1;
 /** Payload of a {@link ComboState} change. */
 export interface ComboStateChange {
-    /** The (new) selected index. */
+    /** The (new) selected index, or {@link ADW_COMBO_NO_SELECTION}. */
     selected: number;
     /** The selected option's `value` (or `''` when out of range). */
     value: string;
@@ -87,14 +102,40 @@ export declare class ComboState {
     /** The selectable options. */
     get options(): AdwComboOption[];
     /**
-     * Replace the options. Resets the selection to 0 when the current index no
-     * longer fits (mirroring `Adw.ComboRow`), then notifies (`interactive: false`)
-     * so the renderer re-syncs the inline value label (the label may change even at
-     * the same index).
+     * Replace the options, then notify (`interactive: false`) so the renderer
+     * re-syncs the inline value label — which may change even at an unchanged
+     * index, because the label is read out of the MODEL.
+     *
+     * Replacing the model re-runs autoselect, so an index the new one does not
+     * have falls back to 0 — including the sentinel, which is how a row recovers
+     * a selection when its model grows. An EMPTY model has no 0 to fall back to
+     * and lands on {@link ADW_COMBO_NO_SELECTION}; that case is the one both
+     * ports used to spell as index 0.
+     *
+     * The check is `hasIndex`, not `selected >= length`: the sentinel is BELOW
+     * the range, so the one-sided comparison left a `-1` in place and a model
+     * that had been emptied and refilled came back with nothing selected.
      */
     setOptions(options: AdwComboOption[]): void;
-    /** The selected option index (may sit past the options length — {@link selectedValue} then is `''`). */
+    /**
+     * The selected option index, or {@link ADW_COMBO_NO_SELECTION}.
+     *
+     * May also sit PAST the options length: {@link setSelectedIndex} is
+     * deliberately permissive, mirroring a `guint` property that takes any
+     * position. {@link selectedValue} reads `''` in both cases, which is why the
+     * sentinel is what distinguishes "nothing selected" from "an empty label".
+     */
     get selectedIndex(): number;
+    /**
+     * Whether the row presents itself as a CHOOSER — `model_changed`
+     * (adw-combo-row.c:187-195) makes the arrow visible and the row activatable
+     * on `n_items > 1` and hides both otherwise.
+     *
+     * One item or none is not a choice, so `Adw.ComboRow` stops looking like one:
+     * no chevron, and tapping does nothing. Neither port did this, so a
+     * single-option row showed its arrow and opened a chooser with one entry.
+     */
+    get presentsChooser(): boolean;
     /** Programmatic index set — notifies `interactive: false`. Returns whether it changed. */
     setSelectedIndex(index: number): boolean;
     /** The selected option's `value`, or `''` when out of range. */