@gjsify/adwaita-core 0.31.0 → 0.32.0

package/lib/types/about-dialog.d.ts

@@ -0,0 +1,391 @@
+/** One `LicenseInfo` row — the struct at adw-about-dialog.c:206-210. */
+export interface AdwLicenseInfo {
+    /** The translatable licence name, `null` for `unknown` and `custom`. */
+    name: string | null;
+    /** The canonical licence URL, hardcoded (never translated). */
+    url: string | null;
+    /** The SPDX identifier AppStream metadata is matched against. */
+    spdxId: string | null;
+}
+/**
+ * `GtkLicense` as the INDEX into {@link ADW_LICENSES}, which is what the C
+ * actually uses it as (`gtk_license_info[license_type]`, :649-650).
+ *
+ * The order and the row contents come from the vendored table
+ * (adw-about-dialog.c:215-252) plus its static assertion that the last index is
+ * `GTK_LICENSE_0BSD` (:256). The member SPELLINGS come from the `Gtk.License`
+ * enum in `@girs/gtk-4.0`, generated from the GTK GIR — `refs/gtk` is not
+ * vendored in this repo, so there is no GTK C file to cite for them.
+ */
+export declare const GTK_LICENSE: {
+    readonly UNKNOWN: 0;
+    readonly CUSTOM: 1;
+    readonly GPL_2_0: 2;
+    readonly GPL_3_0: 3;
+    readonly LGPL_2_1: 4;
+    readonly LGPL_3_0: 5;
+    readonly BSD: 6;
+    readonly MIT_X11: 7;
+    readonly ARTISTIC: 8;
+    readonly GPL_2_0_ONLY: 9;
+    readonly GPL_3_0_ONLY: 10;
+    readonly LGPL_2_1_ONLY: 11;
+    readonly LGPL_3_0_ONLY: 12;
+    readonly AGPL_3_0: 13;
+    readonly AGPL_3_0_ONLY: 14;
+    readonly BSD_3: 15;
+    readonly APACHE_2_0: 16;
+    readonly MPL_2_0: 17;
+    readonly '0BSD': 18;
+};
+/** A `GtkLicense` value, i.e. a valid index into {@link ADW_LICENSES}. */
+export type AdwLicenseType = (typeof GTK_LICENSE)[keyof typeof GTK_LICENSE];
+/**
+ * The 19 `gtk_license_info` rows in enum order (adw-about-dialog.c:215-252).
+ *
+ * Indices 0 and 1 are all-`null` on purpose: `unknown` shows nothing and
+ * `custom` takes its text from the `license` property, so neither has a name,
+ * a URL or an SPDX id to match. A renderer that skipped them would shift every
+ * later licence by two.
+ */
+export declare const ADW_LICENSES: ReadonlyArray<AdwLicenseInfo>;
+/** One deprecated-SPDX alias — the `LicenseAlias` struct at :258-261. */
+export interface AdwLicenseAlias {
+    /** The retired SPDX id apps still ship in their AppStream metadata. */
+    spdxId: string;
+    /** The `GtkLicense` it resolves to. */
+    licenseType: AdwLicenseType;
+}
+/**
+ * The two deprecated SPDX ids (:264-267).
+ *
+ * Both map to the `-only` variant, not the `-or-later` one — the bare
+ * `GPL-2.0` predates the split and meant "version 2", so resolving it to
+ * `GPL-2.0-or-later` would silently widen an app's stated licence.
+ */
+export declare const ADW_LICENSE_ALIASES: ReadonlyArray<AdwLicenseAlias>;
+/**
+ * The licence preamble (:648), with `%s` for the URL and `%s` for the name, in
+ * that order.
+ *
+ * Translatable as a whole; the two `%s` are filled with a HARDCODED url and a
+ * SEPARATELY translated name (:645-647). It contains Pango markup, which the
+ * Legal page renders as such — a renderer that escapes it shows the user raw
+ * `<a href=…>`.
+ */
+export declare const ADW_LICENSE_WARRANTY_TEMPLATE = "This application comes with absolutely no warranty. See the <a href=\"%s\">%s</a> for details.";
+/**
+ * Whether `value` is inside the `gtk_license_info` bounds — the setter's
+ * `g_return_if_fail` (:3401-3402).
+ *
+ * The integer test has no counterpart in the C, where the parameter is already
+ * a `GtkLicense`; here the value arrives from an attribute or JSON, and a
+ * fractional index would read `undefined` out of the table instead of being
+ * rejected.
+ */
+export declare function isLicenseType(value: number): value is AdwLicenseType;
+/**
+ * The `GtkLicense` an AppStream `project_license` SPDX id resolves to, or
+ * `null` when nothing matches — the two lookup loops at :1226-1239.
+ *
+ * The exact-match loop runs over the WHOLE table including indices 0 and 1,
+ * whose `spdxId` is `null` and therefore never equal to a real id. The alias
+ * loop runs afterwards and can override the first, which only matters for ids
+ * that are in both lists — today none are.
+ *
+ * The caller's remaining step is NOT folded in here because it is stateful:
+ * `populate_from_appdata` falls back to `custom` only when the dialog's licence
+ * type is still `unknown` after both loops (:1241-1242), which depends on what
+ * was set before, not on the id.
+ */
+export declare function licenseTypeForSpdxId(spdxId: string): AdwLicenseType | null;
+/**
+ * `get_license_text` (:635-651) — the text the Legal page shows for a licence.
+ *
+ * Three cases, and the difference between the first two is what a renderer gets
+ * wrong: `unknown` returns NULL, meaning the Legal page shows NO licence at all,
+ * while `custom` returns the raw `license` string, which may itself be empty.
+ * Both look like "nothing" on screen; only the second still contributes a legal
+ * section when a copyright is set.
+ */
+export declare function licenseText(licenseType: AdwLicenseType, license: string): string | null;
+/** The `license` / `license-type` pair, as a renderer holds it. */
+export interface AdwLicenseState {
+    /** `license` — the custom licence text. Empty string, never null (:2044). */
+    license: string;
+    /** `license-type` — the `GtkLicense`. */
+    licenseType: AdwLicenseType;
+}
+/** The `GParamSpec` defaults: `""` (:2044) and `unknown` (:2032). */
+export declare const ADW_LICENSE_DEFAULTS: Readonly<AdwLicenseState>;
+/** The GObject property names the two licence setters notify. */
+export type AdwLicenseNotify = 'license' | 'license-type';
+/** What one licence setter did: the new state, and what it notified. */
+export interface AdwLicenseTransition {
+    /** The state after the call — the same object contents when nothing changed. */
+    state: AdwLicenseState;
+    /** Whether the setter got past its early-out. */
+    changed: boolean;
+    /** The `g_object_notify_by_pspec` calls, in emission order. */
+    notify: ReadonlyArray<AdwLicenseNotify>;
+}
+/**
+ * `adw_about_dialog_set_license_type` (:3396-3416).
+ *
+ * Setting any type other than `custom` CLEARS the custom licence text to `""`
+ * (:3407-3408) — the two properties are one state, not two. Both are notified
+ * (:3414-3415) whether or not the string actually moved.
+ *
+ * An out-of-range value is rejected outright (`g_return_if_fail`, :3401-3402),
+ * which is a no-op, not a clamp: the state keeps whatever it had.
+ */
+export declare function setLicenseType(state: AdwLicenseState, licenseType: number): AdwLicenseTransition;
+/**
+ * `adw_about_dialog_set_license` (:3459-3480).
+ *
+ * Setting a licence text forces the type to `custom` (:3472) — but only after
+ * the early-out on an UNCHANGED string (:3466-3467), which makes the pair
+ * asymmetric in a way that is easy to miss: with the text already `""`, setting
+ * `""` again does NOT switch the type to `custom`, so an app trying to clear a
+ * `GPL-3.0` licence by assigning the empty string keeps the GPL text on screen.
+ */
+export declare function setLicense(state: AdwLicenseState, license: string): AdwLicenseTransition;
+/** One parsed credit line — `parse_person`'s three out-parameters, plus the URI. */
+export interface AdwCreditPerson {
+    /** The displayed row title: everything before the link, `g_strstrip`ped. */
+    name: string;
+    /**
+     * The link as it appears in the source string, or `null` when the line has
+     * none.
+     *
+     * `''` and `null` are DIFFERENT states: the C tests `if (link)` on a
+     * pointer, so the empty string produced by `"Ada <>"` is still a link and
+     * still makes the row an `AdwLinkRow`.
+     */
+    link: string | null;
+    /** `*q1 == '<'` (:521) — whether the link came out of angle brackets. */
+    isEmail: boolean;
+    /** `add_credits_section`'s final URI (:571-580): `mailto:` + link, or the link. */
+    uri: string | null;
+}
+/**
+ * `parse_person` (:490-534) — split one credit line into a name and a link.
+ *
+ * Every index here is compared with `>= 0`, never for truthiness: a `<` or a
+ * `http://` at position 0 is a valid non-NULL pointer in the C and a falsy `0`
+ * in JS, so `"<ada@x.org>"` and `"https://x.org"` — a person with no name — are
+ * exactly where a truthiness port silently produces the unparsed line instead.
+ */
+export declare function parseCreditPerson(person: string): AdwCreditPerson;
+/**
+ * The two untranslated `translator-credits` sentinels (:604-605).
+ *
+ * Apps mark the literal string `"translator-credits"` as translatable and each
+ * locale replaces it with its own translator list; in an untranslated locale it
+ * comes back unchanged, and showing THAT to the user is the bug this guards.
+ * The underscore spelling is the older gettext convention and is still checked.
+ */
+export declare const ADW_TRANSLATOR_CREDITS_SENTINELS: ReadonlyArray<string>;
+/**
+ * The translator names for a `translator-credits` value — `g_strsplit (…, "\n",
+ * 0)` past the sentinel guard (:603-608).
+ *
+ * `g_strsplit` returns an EMPTY vector for the empty string, where JS
+ * `''.split('\n')` returns `['']`. The difference is visible: the C shows no
+ * "Translated by" section at all, a `split()`-based port shows the section with
+ * one blank row in it. Blank INTERIOR lines are kept, because `g_strsplit` keeps
+ * them and `add_credits_section` only skips NULL pointers, not empty strings
+ * (:557-558).
+ */
+export declare function translatorCreditsPeople(value: string | null | undefined): string[];
+/** The five built-in credit section titles, in `update_credits` order (:610-619). */
+export declare const ADW_CREDITS_SECTION_TITLES: {
+    readonly developers: "Code by";
+    readonly designers: "Design by";
+    readonly artists: "Artwork by";
+    readonly documenters: "Documentation by";
+    readonly translators: "Translated by";
+};
+/** An app-provided extra section (`add_credit_section`, :3239-3259). */
+export interface AdwCreditsSectionInput {
+    /** The section heading. Nullable in the C signature (:3240). */
+    title: string | null;
+    /** The raw credit lines, each in `parse_person` syntax. */
+    people: ReadonlyArray<string>;
+}
+/** One assembled credits group. */
+export interface AdwCreditsSection {
+    /** The `AdwPreferencesGroup` title (:549). */
+    title: string | null;
+    /** The parsed rows, in source order. */
+    people: ReadonlyArray<AdwCreditPerson>;
+}
+/** The credit inputs `update_credits` reads (:593-627). */
+export interface AdwCreditsInput {
+    developers?: ReadonlyArray<string>;
+    designers?: ReadonlyArray<string>;
+    artists?: ReadonlyArray<string>;
+    documenters?: ReadonlyArray<string>;
+    /** The raw `translator-credits` string, sentinels and all. */
+    translatorCredits?: string | null;
+    /** Extra sections, in `add_credit_section` call order (:3252). */
+    creditSections?: ReadonlyArray<AdwCreditsSectionInput>;
+}
+/**
+ * `update_credits` (:593-633) — the Credits page, as a list of groups.
+ *
+ * A section with no people is not "an empty group", it is NO group:
+ * `add_credits_section` returns before creating one (:545-546). The order is
+ * fixed — developers, designers, artists, documenters, translators, then the
+ * app's own sections in the order they were added — and it is not alphabetical
+ * or configurable.
+ *
+ * One C quirk is deliberately NOT reproduced: `add_credit_section` sets
+ * `credits_box` visible unconditionally (:3256), even when the section it just
+ * tried to add was empty and nothing was created — so an
+ * `add_credit_section ("Backers", {NULL})` leaves GTK with a Credits row that
+ * opens a blank page. That is an artefact of mutating a widget tree
+ * incrementally, not a derivation; recomputing from the sections, as
+ * `update_credits` itself does (:629-630), is the same rule without the stale
+ * flag.
+ */
+export declare function creditsSections(input?: AdwCreditsInput): AdwCreditsSection[];
+/**
+ * The row and page labels from the template, mnemonic markers intact.
+ *
+ * They are here because the visibility table below names these exact widgets
+ * and a renderer has to be able to draw them. `_` is a GTK accelerator marker
+ * in every ROW title (`use-underline=True` on each) and NOT in the page titles;
+ * a renderer without an accelerator layer runs the row titles through
+ * `stripMnemonic`.
+ *
+ * `dialogTitle` is the one that gets invented: the main page's title is bound
+ * to `AdwDialog:title`, whose template default is the bare word "About"
+ * (adw-about-dialog.ui:6, :19) — not "About <app name>". The application NAME
+ * appears separately, in the header revealer that fades in on scroll (:29-31).
+ */
+export declare const ADW_ABOUT_DIALOG_LABELS: {
+    readonly dialogTitle: "About";
+    readonly whatsNewRow: "What’s _New";
+    readonly detailsRow: "_Details";
+    readonly websiteRow: "_Website";
+    readonly supportRow: "_Support Questions";
+    readonly issueRow: "_Report an Issue";
+    readonly troubleshootingRow: "_Troubleshooting";
+    readonly creditsRow: "_Credits";
+    readonly legalRow: "_Legal";
+    readonly acknowledgementsRow: "_Acknowledgements";
+    readonly whatsNewPage: "What’s New";
+    readonly detailsPage: "Details";
+    readonly troubleshootingPage: "Troubleshooting";
+    readonly creditsPage: "Credits";
+    readonly legalPage: "Legal";
+    readonly acknowledgementsPage: "Acknowledgements";
+};
+/** Everything the visibility derivation reads. */
+export interface AdwAboutDialogProps {
+    /** `application-icon` (:2313-2314). */
+    applicationIcon: string;
+    /** `application-name` (:2376-2377). */
+    applicationName: string;
+    /** `developer-name` (:2426-2427). */
+    developerName: string;
+    /** `version` (:2476). */
+    version: string;
+    /** `comments` — Details-page body text. */
+    comments: string;
+    /** `website` — shown on the MAIN page or the Details page, never both. */
+    website: string;
+    /** `support-url` — a MAIN-page row (:1128). */
+    supportUrl: string;
+    /** `issue-url` — a MAIN-page row (:1129). */
+    issueUrl: string;
+    /** `debug-info` — an app-supplied blob; only its emptiness is derived (:1126). */
+    debugInfo: string;
+    /** `release-notes`; non-empty is the whole `whats_new_row` rule (:1020-1021). */
+    releaseNotes: string;
+    /** Whether `add_link` was ever called (:2820). */
+    hasCustomLinks: boolean;
+    /** Whether `credits_box` ended up with children (:629-630). */
+    hasCredits: boolean;
+    /** Whether `legal_box` ended up with children (:745-746). */
+    hasLegal: boolean;
+    /** Whether `add_acknowledgement_section` was ever called (:3297). */
+    hasAcknowledgements: boolean;
+}
+/** Which widgets `update_details`/`update_support`/`update_credits_legal_group` show. */
+export interface AdwAboutDialogVisibility {
+    /** Main page: the 128px app icon (:2313-2314). */
+    appIcon: boolean;
+    /** Main page: the title-1 app name (:2376-2377). */
+    appName: boolean;
+    /** Main page: the developer line (:2426-2427). */
+    developerName: boolean;
+    /** Main page: the version pill (:2476). */
+    version: boolean;
+    /** Main page: the first group (:1116-1118). */
+    detailsGroup: boolean;
+    /** Main page: "What's New" (:1020-1021, :1087, :1099). */
+    whatsNewRow: boolean;
+    /** Main page: "Details", the row that pushes the subpage (:1115). */
+    detailsRow: boolean;
+    /** Main page: "Website", shown only when the Details page has nothing else (:1112). */
+    websiteRow: boolean;
+    /** Main page: the support group (:1131-1132). */
+    supportGroup: boolean;
+    /** Main page: "Support Questions" (:1128). */
+    supportRow: boolean;
+    /** Main page: "Report an Issue" (:1129). */
+    issueRow: boolean;
+    /** Main page: "Troubleshooting" (:1130). */
+    troubleshootingRow: boolean;
+    /** Main page: the Credits/Legal/Acknowledgements group (:483-486). */
+    creditsLegalGroup: boolean;
+    /** Main page: "Credits", bound to `credits_box` (.ui:198). */
+    creditsRow: boolean;
+    /** Main page: "Legal", bound to `legal_box` (.ui:215). */
+    legalRow: boolean;
+    /** Main page: "Acknowledgements", bound to `acknowledgements_box` (.ui:233). */
+    acknowledgementsRow: boolean;
+    /** Details page: the comments label (:1111). */
+    commentsLabel: boolean;
+    /** Details page: the links group (:1114). */
+    linksGroup: boolean;
+    /** Details page: "Website", the other half of the either/or (:1113). */
+    detailsWebsiteRow: boolean;
+}
+/**
+ * `update_details` (:1102-1119) + `update_support` (:1121-1133) +
+ * `update_credits_legal_group` (:480-487), as one truth table.
+ *
+ * The three rules a port does not arrive at by guessing:
+ *
+ *  1. **Website is not a Details-page trigger.** `show_details` is
+ *     `has_comments || has_custom_links` (:1108) — website is deliberately
+ *     absent. A dialog with only a website and nothing else keeps the website
+ *     on the MAIN page (:1112) and offers no Details row at all, because a
+ *     subpage holding one link is worse than the link.
+ *  2. **The website row exists twice**, once per page, and exactly one of the
+ *     two is visible (:1112-1113). They are separate widgets in the template
+ *     (`website_row` .ui:133, `details_website_row` .ui:347).
+ *  3. **Support and issue links live on the MAIN page** (.ui:146-186, :1128-1129),
+ *     not on Details. Only comments and links (website + `add_link`) are on the
+ *     Details page. The browser renderer put all three link rows on Details,
+ *     which buried the issue tracker one navigation step deeper than GTK.
+ *
+ * `hasCustomLinks` is a latch in the C — `add_link` sets it and nothing clears
+ * it (:2820) — so a renderer passes "has any extra link ever been added", not
+ * "does the links group currently have children".
+ */
+export declare function aboutDialogVisibility(props?: Partial<AdwAboutDialogProps>): AdwAboutDialogVisibility;
+/**
+ * Whether the Legal page has anything on it — `append_legal_section`'s two
+ * early-outs collapsed for the DEFAULT section (:666-671, :682-687).
+ *
+ * The section is dropped when the copyright is empty AND the licence text is
+ * empty-or-absent; `force_title` is FALSE for the app's own section (:740), so
+ * there is no title-only case here. Note the licence half goes through
+ * {@link licenseText}, which means a `custom` type with an empty string
+ * contributes nothing while a `GPL-3.0` type always does.
+ */
+export declare function legalSectionVisible(copyright: string, licenseType: AdwLicenseType, license: string): boolean;

package/lib/types/about-dialog.spec.d.ts

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

package/lib/types/action-row.d.ts

@@ -0,0 +1,270 @@
+/** A title/subtitle label pair with the visibility the bindings give it. */
+export interface AdwRowLabels {
+    /** The title label's text — `''` for an unset title, never `null`. */
+    title: string;
+    /** `string_is_not_empty(title)` — adw-action-row.ui:49-53. */
+    titleVisible: boolean;
+    /** The subtitle label's text — `''` for an unset subtitle. */
+    subtitle: string;
+    /** `string_is_not_empty(subtitle)` — adw-action-row.ui:71-75. */
+    subtitleVisible: boolean;
+}
+/** What a row knows about its two labels. */
+export interface AdwRowLabelInput {
+    /** `AdwPreferencesRow:title`. */
+    title?: string | null;
+    /** `AdwActionRow:subtitle`. */
+    subtitle?: string | null;
+}
+/**
+ * The title/subtitle labels of any Adwaita row, with the `visible` each binding
+ * computes.
+ *
+ * Exported on its own — not just as part of {@link ActionRowState} — because the
+ * rows that already have a core state machine of their OWN (`Adw.ComboRow`,
+ * `Adw.ExpanderRow`, `Adw.SpinRow` via `rows.ts`) still render this pair, and
+ * every one of them had hand-rolled it.
+ */
+export declare function deriveRowLabels(input: AdwRowLabelInput): AdwRowLabels;
+/** Everything a renderer needs to paint an `Adw.ActionRow`. */
+export interface ActionRowRenderState extends AdwRowLabels {
+    /**
+     * `GtkListBoxRow:activatable` — whether a click activates the row at all.
+     * `False` in the template (adw-action-row.ui:5) and raised by an activatable
+     * widget rather than by the row itself.
+     */
+    activatable: boolean;
+}
+/**
+ * `Adw.ActionRow`: two labels plus the `activatable-widget` coupling.
+ *
+ * The coupling is the part no port had, and it is counter-intuitive twice over.
+ *
+ * (1) Setting an activatable widget does not set `activatable = TRUE`; it binds
+ * the WIDGET's `sensitive` onto the row's `activatable` with
+ * `G_BINDING_SYNC_CREATE` (adw-action-row.c:729-732). So handing the row an
+ * INSENSITIVE widget leaves the row unactivatable, and later flipping that
+ * widget's `sensitive` flips the row with it, for as long as the binding lives.
+ *
+ * (2) Clearing the widget only UNBINDS (`g_clear_pointer (&priv->
+ * activatable_binding, g_binding_unbind)`, C:709); it never writes `activatable`
+ * back. The row therefore STAYS activatable after its widget is taken away —
+ * which the class documentation states outright ("unsetting it won't change the
+ * row's activatability", C:28-30). A port that models this as
+ * `activatable = hasActivatableWidget` gets the sticky case exactly backwards.
+ *
+ * `TWidget` is whatever the renderer calls a widget — a DOM element, an NS
+ * `View`. Core only ever compares it by identity and hands it back.
+ */
+export declare class ActionRowState<TWidget = unknown> {
+    private _title;
+    private _subtitle;
+    private _activatableWidget;
+    private _activatable;
+    private _widgetSensitive;
+    /** The current render snapshot. */
+    get state(): ActionRowRenderState;
+    /** `AdwPreferencesRow:title`. */
+    get title(): string;
+    /** Set the title. Returns whether it changed (the `notify::title` gate). */
+    setTitle(title: string | null | undefined): boolean;
+    /** `AdwActionRow:subtitle`. */
+    get subtitle(): string;
+    /** Set the subtitle. Returns whether it changed (the `notify::subtitle` gate). */
+    setSubtitle(subtitle: string | null | undefined): boolean;
+    /** `AdwActionRow:activatable-widget` — `null` when unset. */
+    get activatableWidget(): TWidget | null;
+    /**
+     * `adw_action_row_set_activatable_widget` (C:696-741).
+     *
+     * `sensitive` is the widget's own `GtkWidget:sensitive` at the moment of the
+     * set, which `G_BINDING_SYNC_CREATE` copies straight into `activatable`
+     * (C:729-732); it defaults to `true` because a freshly built widget is
+     * sensitive. Passing `null` unbinds and LEAVES `activatable` alone (C:709).
+     *
+     * Returns whether the widget changed — the `notify::activatable-widget` gate
+     * (C:740, guarded by the identity early-return at C:706-707).
+     */
+    setActivatableWidget(widget: TWidget | null, sensitive?: boolean): boolean;
+    /**
+     * The live half of the binding: the activatable widget's `sensitive` is now
+     * `sensitive`. Safe to call unconditionally — a renderer that re-reads the
+     * widget rather than being told is the normal case on both ports.
+     *
+     * Two things make it a no-op, and both are the C's:
+     *   - no widget is set, so `g_clear_pointer (…, g_binding_unbind)` (C:709)
+     *     already took the binding away;
+     *   - the value is unchanged, so `gtk_widget_set_sensitive` early-returned
+     *     and `notify::sensitive` — the only thing a GBinding listens to — never
+     *     fired. Without this half, a re-assertion of the value the widget
+     *     already had would silently undo a direct write to `activatable`.
+     *
+     * Returns whether `activatable` changed.
+     */
+    setActivatableWidgetSensitive(sensitive: boolean): boolean;
+    /** `GtkListBoxRow:activatable`. */
+    get activatable(): boolean;
+    /**
+     * Set `activatable` directly.
+     *
+     * Legal even while a binding is live: `g_object_bind_property` without
+     * `G_BINDING_BIDIRECTIONAL` is one-way, so GTK lets the write land and the
+     * next `sensitive` change overwrites it. Kept faithful rather than guarded —
+     * a port that refused the write would diverge from every application that
+     * sets `activatable` in a `.ui` file.
+     *
+     * Returns whether it changed.
+     */
+    setActivatable(activatable: boolean): boolean;
+    /**
+     * `adw_action_row_activate_real` (C:297-307): forward the activation to the
+     * activatable widget, then emit `activated`.
+     *
+     * Returns the widget to forward to, or `null`. The caller emits `activated`
+     * UNCONDITIONALLY afterwards — C:306 is outside the `if`, and
+     * `adw_action_row_activate` is public API (adw-action-row.h:90) with no
+     * `activatable` check of its own. The `activatable` gate lives one level up,
+     * in GtkListBox, which does not emit `row-activated` for an unactivatable
+     * row; a renderer's CLICK handler is where that check belongs.
+     */
+    activate(): TWidget | null;
+}
+/**
+ * `Adw.SwitchRow`: one boolean, and the notify rule the two ports disagreed on.
+ *
+ * `adw_switch_row_set_active` (C:216-228) early-returns when the value is
+ * unchanged and otherwise writes the slider, whose `notify::active` runs
+ * `slider_notify_active_cb` (C:66-77) — which updates the a11y `checked` state
+ * and emits `notify::active` on the ROW. That callback is the ONLY notify path,
+ * and it cannot see where the change came from, so a programmatic set notifies
+ * exactly like a drag on the handle.
+ *
+ * Both renderers had half of it: `@gjsify/adwaita-web` emitted only from the
+ * checkbox's `change` event, which the DOM does not fire for a programmatic
+ * `.checked =`, so `row.active = true` was silent; `@gjsify/adwaita-nativescript`
+ * re-emitted from `checkedChange`, which NS DOES fire on a programmatic write,
+ * so it notified. One widget, one C source, two opposite answers.
+ *
+ * There is deliberately NO `interactive` flag (the `SpinState`/`ComboState`
+ * shape): adding one would be an abstraction that actively contradicts C:66-77.
+ */
+export declare class SwitchRowState {
+    private _active;
+    /** `Adw.SwitchRow:active`. */
+    get active(): boolean;
+    /**
+     * `adw_switch_row_set_active` (C:216-228). Returns whether it changed —
+     * i.e. whether the renderer must emit `notify::active`. The `!!is_active`
+     * normalisation is C:222.
+     */
+    setActive(active: boolean): boolean;
+    /**
+     * The row was activated (clicked, or <kbd>Enter</kbd>) — invert the state.
+     *
+     * `adw_switch_row_init` makes the row activatable and points the
+     * activatable-widget at the slider (C:160-162), so an activation is
+     * forwarded to the `GtkSwitch` and toggles it; the class docs state the
+     * outcome directly ("When activated, the row will invert its active state.
+     * The user can control the switch by activating the row or by dragging on
+     * the switch handle", C:23-27). Neither port did this — the row's text was
+     * dead and only the handle worked.
+     *
+     * Always returns `true`: inverting a boolean always changes it.
+     */
+    activate(): boolean;
+}
+/**
+ * `Adw.ButtonRow` is ALWAYS activatable — `<property name="activatable">True
+ * </property>` in the template (adw-button-row.ui:5), with no setter, no
+ * property and the class documentation saying so in one line
+ * ("`AdwButtonRow` is always activatable.", adw-button-row.c:31).
+ *
+ * Exported as data because the browser renderer had INVENTED an
+ * `activatable="false"` opt-out, and a passing test pinned it.
+ */
+export declare const BUTTON_ROW_ACTIVATABLE = true;
+/** Everything a renderer needs to paint an `Adw.ButtonRow`. */
+export interface ButtonRowRenderState {
+    /** `AdwPreferencesRow:title` — `''` when unset. */
+    title: string;
+    /** `string_is_not_empty(title)` — adw-button-row.ui:34-38. */
+    titleVisible: boolean;
+    /** `AdwButtonRow:start-icon-name` — `''` when unset (C:209-210). */
+    startIconName: string;
+    /** `string_is_not_empty(start_image.icon-name)` — adw-button-row.ui:20-24. */
+    startIconVisible: boolean;
+    /** `AdwButtonRow:end-icon-name` — `''` when unset (C:221-222). */
+    endIconName: string;
+    /** `string_is_not_empty(end_image.icon-name)` — adw-button-row.ui:55-59. */
+    endIconVisible: boolean;
+    /** Always {@link BUTTON_ROW_ACTIVATABLE}. */
+    activatable: true;
+}
+/**
+ * `Adw.ButtonRow`: a centered title between two optional symbolic icons.
+ *
+ * The second icon is the lift: `AdwButtonRow:end-icon-name` (C:213-223, with
+ * `adw_button_row_set_end_icon_name` at C:342-352 and the image bound at
+ * adw-button-row.ui:52-65) has existed since libadwaita 1.6 and neither renderer
+ * had it — so the "Open in Files ›" shape that the property exists for could not
+ * be expressed at all.
+ *
+ * Both icon setters go through `g_set_str`, which returns FALSE for an unchanged
+ * value and thereby gates the notify (C:309-312, C:348-351). `g_set_str (&s,
+ * NULL)` stores NULL, but every read is `string_is_not_empty`-guarded and the
+ * pspec default is `""`, so `''` is the faithful TS spelling of both.
+ */
+export declare class ButtonRowState {
+    private _title;
+    private _startIconName;
+    private _endIconName;
+    /** The current render snapshot. */
+    get state(): ButtonRowRenderState;
+    /** `AdwPreferencesRow:title`. */
+    get title(): string;
+    /** Set the title. Returns whether it changed. */
+    setTitle(title: string | null | undefined): boolean;
+    /** `AdwButtonRow:start-icon-name`. */
+    get startIconName(): string;
+    /** `adw_button_row_set_start_icon_name` (C:303-313). Returns whether it changed. */
+    setStartIconName(iconName: string | null | undefined): boolean;
+    /** `AdwButtonRow:end-icon-name`. */
+    get endIconName(): string;
+    /** `adw_button_row_set_end_icon_name` (C:342-352). Returns whether it changed. */
+    setEndIconName(iconName: string | null | undefined): boolean;
+}
+/** Everything a renderer needs to paint an `Adw.WindowTitle`. */
+export type WindowTitleRenderState = AdwRowLabels;
+/**
+ * `Adw.WindowTitle`: the same two labels, one level out of the boxed list.
+ *
+ * Three rules, two lines each, and neither renderer had any of them: the TITLE
+ * label is hidden when the title is empty (C:207-208 — the `.ui` even starts it
+ * `visible=False`, adw-window-title.ui:15), a set to the CURRENT value returns
+ * early (C:203-204, C:244-245), and a real change notifies (C:210, C:251).
+ *
+ * DIVERGENCE, deliberate: setting `null` over an already-empty value does NOT
+ * notify here, where libadwaita does. Its guard is `g_strcmp0 (gtk_label_get_label
+ * (…), title)` and `gtk_label_get_label` never returns NULL, so `g_strcmp0 ("",
+ * NULL)` is 1 — the early return is skipped, the label is re-set to the same
+ * `""`, and `notify::title` fires for a no-op. That is an artefact of a
+ * NULL-vs-`""` pointer comparison, not a designed behaviour; both renderers
+ * carry `null` for "attribute absent" and `''` for `title=""`, and emitting a
+ * change notification for the difference between them would be noise. The
+ * normalisation happens BEFORE the comparison, and `WINDOW_TITLE_VECTORS` pins
+ * the divergence rather than hiding it.
+ */
+export declare class WindowTitleState {
+    private _title;
+    private _subtitle;
+    /** The current render snapshot. */
+    get state(): WindowTitleRenderState;
+    /** `Adw.WindowTitle:title`. */
+    get title(): string;
+    /** `adw_window_title_set_title` (C:197-211). Returns whether it changed. */
+    setTitle(title: string | null | undefined): boolean;
+    /** `Adw.WindowTitle:subtitle`. */
+    get subtitle(): string;
+    /** `adw_window_title_set_subtitle` (C:238-252). Returns whether it changed. */
+    setSubtitle(subtitle: string | null | undefined): boolean;
+}

package/lib/types/action-row.spec.d.ts

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