@gjsify/adwaita-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,184 @@
+import type { MakeComparableOptions, PreferencesGroupHeaderInput, PreferencesGroupHeaderState, PreferencesSearchPage, PreferencesSearchRow, SearchRowSubtitleInput } from '../preferences.js';
+/** One `derivePreferencesGroupHeader` expectation. */
+export interface PreferencesGroupHeaderVector {
+    /** The group's title / description / suffix / row count. */
+    input: PreferencesGroupHeaderInput;
+    /** The five states C derives from it. */
+    state: PreferencesGroupHeaderState;
+    /**
+     * Set when the expectation only holds for a renderer that INTERPRETS Pango
+     * markup in its labels. Both current renderers paint the string verbatim
+     * and pass `useMarkup: false`, so their suites skip these rows rather than
+     * assert a rule they deliberately do not implement. Closing the
+     * markup-rendering gap is what retires the flag.
+     */
+    dependsOnMarkup?: boolean;
+    /** Why this row exists — the rule or the regression it pins down. */
+    rule: string;
+}
+/**
+ * `update_title_visibility` / `update_description_visibility` /
+ * `update_listbox_visibility` / `is_single_line` / `update_header_visibility`
+ * (adw-preferences-group.c:91-156).
+ */
+export declare const PREFERENCES_GROUP_HEADER_VECTORS: ReadonlyArray<PreferencesGroupHeaderVector>;
+/** One `defaultCaseFolder` expectation. */
+export interface CaseFoldVector {
+    /** The string being folded. */
+    text: string;
+    /** `g_utf8_casefold(text)` — Unicode FULL case folding. */
+    folded: string;
+    /** What a bare `toLowerCase()` returns, kept in the table as the trap. */
+    naiveLowerCase: string;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `g_utf8_casefold` (adw-preferences-dialog.c:101, :133).
+ *
+ * Every row where `folded !== naiveLowerCase` is a query a `toLowerCase()` port
+ * 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. */
+export interface StripMarkupVector {
+    /** The (already folded, in the real pipeline) markup string. */
+    markup: string;
+    /** The plain text, or `null` when `pango_parse_markup` fails. */
+    plain: string | null;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `pango_parse_markup (…, accel_marker 0, …)` as `make_comparable` calls it
+ * (adw-preferences-dialog.c:104-114).
+ *
+ * `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. */
+export interface StripMnemonicVector {
+    /** The label text with accel markers. */
+    text: string;
+    /** What `adw_strip_mnemonic` returns. */
+    stripped: string;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `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. */
+export interface MakeComparableVector {
+    /** The raw title or subtitle. */
+    source: string;
+    /** The row flags plus the title/subtitle `allowUnderline` distinction. */
+    options: MakeComparableOptions;
+    /** What the search compares against. */
+    comparable: string;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `make_comparable` (adw-preferences-dialog.c:96-123).
+ *
+ * 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. */
+export interface RowMatchVector {
+    /** The row being tested. */
+    row: PreferencesSearchRow;
+    /** What the user typed into the search entry. */
+    query: string;
+    /** Whether `filter_search_results` keeps the row. */
+    matches: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `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 {
+    /** The page tree being indexed. */
+    pages: readonly PreferencesSearchPage[];
+    /** The row titles the corpus contains, in order. */
+    titles: readonly string[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The three-filter chain: `adw_preferences_dialog_init`'s visible-page filter
+ * (:632-641) over `adw_preferences_page_get_rows`' `is_visible_group`
+ * (adw-preferences-page.c:831-834) over `adw_preferences_group_get_rows`'
+ * `row_has_title` (adw-preferences-group.c:736-740).
+ *
+ * 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. */
+export interface SearchRowSubtitleVector {
+    /** The matched row's ancestors, plus the visible-page count. */
+    input: SearchRowSubtitleInput;
+    /** The second line of the result row, `null` for none. */
+    subtitle: string | null;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `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.
+ *
+ * Chosen so every clause of the pipeline is exercised by at least one query:
+ * two visible pages (so subtitles carry the arrow) plus a hidden third, a hidden
+ * group, an untitled row, an action row with a searchable subtitle, an entry row
+ * whose subtitle must NOT be searched, a German title for the fold, and a
+ * markup title.
+ */
+export declare const PREFERENCES_SEARCH_PAGES: ReadonlyArray<PreferencesSearchPage>;
+/** One expected search result, as a renderer can read it off its own result row. */
+export interface PreferencesSearchExpectation {
+    /** The result row's title — copied verbatim from the matched row. */
+    title: string;
+    /** The result row's subtitle. */
+    subtitle: string | null;
+}
+/** One end-to-end `searchPreferences` expectation over {@link PREFERENCES_SEARCH_PAGES}. */
+export interface PreferencesSearchVector {
+    /** What the user typed. */
+    query: string;
+    /** The results, in corpus order. */
+    results: readonly PreferencesSearchExpectation[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The whole pipeline over {@link PREFERENCES_SEARCH_PAGES} — corpus, filter and
+ * subtitle at once. This is the table a renderer drives its own widgets with.
+ */
+export declare const PREFERENCES_SEARCH_VECTORS: ReadonlyArray<PreferencesSearchVector>;

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

@@ -0,0 +1,74 @@
+import type { AdwComboOption, ComboStateChange } from '../rows.js';
+/**
+ * One mutation in a combo scenario. DATA, not a closure: a renderer suite
+ * replays these against a real widget (set the options, pick from the chooser)
+ * and compares what the user would see.
+ */
+export type ComboSelectionStep = {
+    op: 'setOptions';
+    options: ReadonlyArray<AdwComboOption>;
+} | {
+    op: 'setSelectedIndex';
+    index: number;
+} | {
+    op: 'setSelectedValue';
+    value: string;
+} | {
+    op: 'select';
+    index: number;
+};
+/** One combo-selection scenario. */
+export interface ComboSelectionVector {
+    /** Short scenario name. */
+    name: string;
+    /** The mutations, applied in order to a fresh state. */
+    steps: readonly ComboSelectionStep[];
+    /** `selectedIndex` afterwards. */
+    selected: number;
+    /** `selectedValue` afterwards — `''` when the index sits outside the options. */
+    value: string;
+    /** `selectedLabel` afterwards — the text the inline value / button shows. */
+    label: string;
+    /**
+     * Every change the state emits, in order. This IS the renderer's feed: the
+     * label repaint comes off `label`, and the `notify::selected` re-emit is
+     * gated on `interactive`.
+     */
+    emitted: ReadonlyArray<ComboStateChange>;
+    /** Why this row exists — the rule or edge case it pins down. */
+    rule: string;
+}
+/**
+ * `adw_combo_row_set_selected` (adw-combo-row.c:772-789) and the notify chain it
+ * drives (:136-155, :157-185), 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
+ * 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.
+ */
+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/sidebar.d.ts

@@ -0,0 +1,182 @@
+import type { AdwSidebarItemSpec, AdwSidebarSectionSpec, SidebarHeaderSpec } from '../sidebar.js';
+/** One `clampSidebarSelection` expectation. */
+export interface SidebarClampVector {
+    /** The index handed to `AdwSidebar:selected`. */
+    index: number;
+    /** How many items the sidebar has (`n_items`). */
+    count: number;
+    /** What `selected` reads back as: the index itself, or `-1` for no selection. */
+    selected: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_sidebar_set_selected` (adw-sidebar.c:3028-3029):
+ * `if (selected >= self->n_items) selected = GTK_INVALID_LIST_POSITION;`
+ *
+ * The negative rows are not a TS invention — `selected` is a `guint`, so `-7`
+ * arrives as `4294967289`, which is `>= n_items`. The fractional/`NaN` rows are
+ * the generalisation to values C cannot express: not a valid position is no
+ * position. They are the inputs that used to be wrong — the web port truncated
+ * `"1.5"` to row 1 and the NativeScript port stored `1.5` verbatim, highlighting
+ * no row while reporting a selection.
+ */
+export declare const SIDEBAR_CLAMP_VECTORS: ReadonlyArray<SidebarClampVector>;
+/** One `adjustSidebarSelection` expectation — an `items-changed` splice. */
+export interface SidebarItemsChangedVector {
+    /** `selected` before the splice. */
+    selected: number;
+    /** `n_items` before the splice. */
+    oldCount: number;
+    /** `n_items` after the splice. */
+    newCount: number;
+    /** Flat index the splice starts at. */
+    position: number;
+    /** How many items were removed. */
+    removed: number;
+    /** How many items were added. */
+    added: number;
+    /** `selected` after `items_changed_cb` has run. */
+    expected: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `items_changed_cb` (adw-sidebar.c:2246-2284) — the derivation NEITHER port had.
+ *
+ * The last row documents libadwaita's unsigned wraparound: with no selection,
+ * `selected` is `G_MAXUINT`, so the "splice covers the selection" test can never
+ * fire and the shift branch computes `G_MAXUINT + added - removed`, which wraps
+ * into range. It is reproduced rather than repaired — a renderer that "fixed" it
+ * would stop matching the toolkit it mirrors.
+ */
+export declare const SIDEBAR_ITEMS_CHANGED_VECTORS: ReadonlyArray<SidebarItemsChangedVector>;
+/** One flattened-model expectation for a whole section list. */
+export interface SidebarModelVector {
+    /** Human-readable name, used as the test title. */
+    name: string;
+    /** The declared sections. */
+    sections: ReadonlyArray<AdwSidebarSectionSpec>;
+    /** `n_items` — the size of the selection index space. */
+    count: number;
+    /** `adw_sidebar_section_get_first_index` per section, in declaration order. */
+    sectionFirstIndex: ReadonlyArray<number>;
+    /** Every rendered row, in render order. */
+    flat: ReadonlyArray<{
+        index: number;
+        sectionIndex: number;
+        sectionItemIndex: number;
+        title: string;
+    }>;
+    /** The headers that get drawn, in render order. */
+    headers: ReadonlyArray<SidebarHeaderSpec>;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The flat index space (`items_changed_cb`'s section walk, adw-sidebar.c:2261-2267
+ * + `adw_sidebar_item_get_index`, adw-sidebar-item.c:1040) and the header
+ * derivation (`set_header_cb`/`create_header`, adw-sidebar.c:1532-1563, :1483-1530).
+ *
+ * The empty-leading-section rows are the ones the web port got wrong: it keyed
+ * `.first` and the hidden-separator case off the DECLARATION index, so an empty
+ * or fully-filtered first section drew a stray separator and cost section 1 the
+ * flush-to-top padding `.header.first > .heading` prescribes.
+ */
+export declare const SIDEBAR_MODEL_VECTORS: ReadonlyArray<SidebarModelVector>;
+/** One item-label-visibility expectation. */
+export interface SidebarItemFlagsVector {
+    /** The declared item. */
+    item: AdwSidebarItemSpec;
+    /** `string_is_not_empty(title)` (adw-sidebar.c:1411-1412). */
+    titleVisible: boolean;
+    /** `string_is_not_empty(subtitle)` (adw-sidebar.c:1420-1421). */
+    subtitleVisible: boolean;
+    /** `notify_icon_cb`'s `icon_name && *icon_name` (adw-sidebar.c:1303). */
+    iconVisible: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The three `string_is_not_empty` bindings, so renderers stop spelling
+ * `x.length === 0` themselves — and so the `'-symbolic'` row pins that icon
+ * visibility is decided on the RAW name, before any suffix stripping.
+ */
+export declare const SIDEBAR_ITEM_FLAG_VECTORS: ReadonlyArray<SidebarItemFlagsVector>;
+/** One activation (row click) expectation. */
+export interface SidebarActivationVector {
+    /** Human-readable name, used as the test title. */
+    name: string;
+    /** The declared sections. */
+    sections: ReadonlyArray<AdwSidebarSectionSpec>;
+    /** The selection to establish before clicking, applied through `setSelected`. */
+    initialSelected: number;
+    /** The flat index that is clicked. */
+    activate: number;
+    /** Whether a row was actually activated — the `activated` signal. */
+    activated: boolean;
+    /** Whether `notify::selected` fired. */
+    selectionChanged: boolean;
+    /** `selected` afterwards. */
+    selected: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The selection/activation split: `row-selected` fires only on a real change,
+ * `row-activated` fires on EVERY click (adw-sidebar.c:1585-1612), and page mode
+ * does the same thing in one callback (`boxed_row_activated_cb`, :1662-1674).
+ *
+ * The re-click row is the one that matters: it is the documented way to reveal
+ * the content pane of a split view (adw-sidebar.c:73-75), and the NativeScript
+ * port could not express it at all — its setter early-returned on an unchanged
+ * index and it emitted no activation signal.
+ */
+export declare const SIDEBAR_ACTIVATION_VECTORS: ReadonlyArray<SidebarActivationVector>;
+/** One filter / empty-state expectation. */
+export interface SidebarFilterVector {
+    /** Human-readable name, used as the test title. */
+    name: string;
+    /** The declared sections. */
+    sections: ReadonlyArray<AdwSidebarSectionSpec>;
+    /** Item titles the filter keeps; the suites build `(item) => keepTitles.includes(item.title)`. */
+    keepTitles: ReadonlyArray<string>;
+    /** `n_items` — UNCHANGED by the filter, because the selection counts the unfiltered model. */
+    count: number;
+    /** Flat indices of the rows that survive the filter, in render order. */
+    visibleIndices: ReadonlyArray<number>;
+    /** The headers that get drawn once the filter is applied. */
+    headers: ReadonlyArray<SidebarHeaderSpec>;
+    /** The `.empty` / placeholder state — computed from the FILTERED count. */
+    isEmpty: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_sidebar_set_filter` (adw-sidebar.c:3127-3139) feeds a `GtkFilterListModel`
+ * that only the row list and the placeholder see; the selection index space stays
+ * on the unfiltered `items_model` (adw-sidebar.c:2866 vs :2177-2180), and
+ * `update_placeholder` counts the filtered one (adw-sidebar.c:1828, :1839-1842).
+ *
+ * Neither port had a filter or a placeholder at all.
+ */
+export declare const SIDEBAR_FILTER_VECTORS: ReadonlyArray<SidebarFilterVector>;
+/** One mode expectation. */
+export interface SidebarModeVector {
+    /** The mode being set. */
+    mode: 'sidebar' | 'page';
+    /** Whether the selection is PAINTED in that mode. */
+    selectionVisible: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_sidebar_set_mode` (adw-sidebar.c:2960-2981) never touches `selected`:
+ * "In this mode, the selection is invisible and only tracked to determine the
+ * initially selected item once switched back to sidebar mode" (adw-sidebar.c:2948-2951).
+ *
+ * The web port painted its `.selected` highlight in BOTH modes; page mode builds
+ * plain `AdwActionRow`s in a boxed list (`create_boxed_row`, adw-sidebar.c:1676)
+ * and shows no selected row at all.
+ */
+export declare const SIDEBAR_MODE_VECTORS: ReadonlyArray<SidebarModeVector>;

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>;