@gjsify/adwaita-core 0.31.0 → 0.32.0

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

@@ -0,0 +1,186 @@
+/** One `string_is_not_empty` expectation. */
+export interface LabelVisibilityVector {
+    /** The label's text — `null` stands for "property unset / attribute absent". */
+    text: string | null;
+    /** Whether the bound label is visible. */
+    visible: boolean;
+    /** Why this row exists — the rule or edge case it pins down. */
+    rule: string;
+}
+/**
+ * `string_is_not_empty` (adw-action-row.c:112-117 ≡ adw-button-row.c:92-97,
+ * inlined at adw-window-title.c:208 and :249).
+ *
+ * Applies to the TITLE and to the subtitle alike — the bindings are two copies
+ * of the same closure (adw-action-row.ui:49-53 and :71-75). The title half is
+ * what every port dropped: a row with `title=""` kept a zero-height but
+ * line-height-consuming label, and `<adw-window-title>` reserved a title line in
+ * every header bar that only had a subtitle.
+ *
+ * `' '` is the canary row. The C never trims — `string && string[0]` reads ONE
+ * byte — so a single space is a VISIBLE label. A port reaching for
+ * `value.trim().length` passes every other row here and fails this one.
+ */
+export declare const LABEL_VISIBILITY_VECTORS: ReadonlyArray<LabelVisibilityVector>;
+/** One step of an {@link ActionRowActivationVector}. */
+export type ActionRowStep = 
+/** `adw_action_row_set_activatable_widget` — `widget` is an opaque id, `null` clears. */
+{
+    op: 'set-activatable-widget';
+    widget: string | null;
+    sensitive?: boolean;
+}
+/**
+ * The bound widget's `GtkWidget:sensitive` was WRITTEN with this value —
+ * not necessarily changed. A write of the value it already holds is a
+ * deliberate case: `gtk_widget_set_sensitive` early-returns on it, so
+ * `notify::sensitive` never fires and the GBinding propagates nothing.
+ */
+ | {
+    op: 'set-widget-sensitive';
+    sensitive: boolean;
+}
+/** A direct write to `GtkListBoxRow:activatable`. */
+ | {
+    op: 'set-activatable';
+    activatable: boolean;
+};
+/** One `activatable-widget` ↔ `activatable` expectation. */
+export interface ActionRowActivationVector {
+    /** What the scenario is called. */
+    name: string;
+    /** The steps to run against a fresh row, in order. */
+    steps: readonly ActionRowStep[];
+    /** `GtkListBoxRow:activatable` afterwards. */
+    activatable: boolean;
+    /** `AdwActionRow:activatable-widget` afterwards, by id. */
+    activatableWidget: string | null;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_action_row_set_activatable_widget` (adw-action-row.c:696-741).
+ *
+ * The two rows that decide whether a port read the C or guessed it:
+ * `insensitive-widget-does-not-activate` (the binding is `sensitive` →
+ * `activatable` with `G_BINDING_SYNC_CREATE`, C:729-732 — NOT a constant TRUE),
+ * and `unsetting-keeps-activatable` (clearing only unbinds, C:709, so the flag
+ * stays where the binding last left it — stated outright at C:28-30).
+ */
+export declare const ACTION_ROW_ACTIVATION_VECTORS: ReadonlyArray<ActionRowActivationVector>;
+/** One step of a {@link SwitchRowNotifyVector}. */
+export type SwitchRowStep = 
+/** `adw_switch_row_set_active` — a PROGRAMMATIC set. */
+{
+    op: 'set-active';
+    active: boolean;
+}
+/** The row itself was activated (clicked / <kbd>Enter</kbd>). */
+ | {
+    op: 'activate-row';
+};
+/** One `notify::active` expectation. */
+export interface SwitchRowNotifyVector {
+    /** What the scenario is called. */
+    name: string;
+    /** The steps to run against a fresh row, in order. */
+    steps: readonly SwitchRowStep[];
+    /** `Adw.SwitchRow:active` afterwards. */
+    active: boolean;
+    /** The `active` value carried by each `notify::active`, in emission order. */
+    emitted: readonly boolean[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_switch_row_set_active` (C:216-228) → `slider_notify_active_cb` (C:66-77).
+ *
+ * `programmatic-set-notifies` is the row the two renderers answered differently:
+ * the notify is emitted by the SLIDER's own `notify::active`, which fires
+ * whatever wrote it, so there is no programmatic-vs-interactive split to model.
+ * `activate-row-toggles` is the row NEITHER had: `adw_switch_row_init` points
+ * the activatable-widget at the slider (C:160-162) and the class docs spell out
+ * the result (C:23-27).
+ */
+export declare const SWITCH_ROW_NOTIFY_VECTORS: ReadonlyArray<SwitchRowNotifyVector>;
+/** One `Adw.ButtonRow` icon expectation. */
+export interface ButtonRowIconVector {
+    /** `AdwButtonRow:start-icon-name`. */
+    startIconName: string | null;
+    /** `AdwButtonRow:end-icon-name`. */
+    endIconName: string | null;
+    /** Whether the leading `image.icon.start` shows (adw-button-row.ui:20-24). */
+    startIconVisible: boolean;
+    /** Whether the trailing `image.icon.end` shows (adw-button-row.ui:55-59). */
+    endIconVisible: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The two icons of `Adw.ButtonRow` (C:201-223), each bound through the same
+ * `string_is_not_empty` closure as the title.
+ *
+ * `end-icon-name` has existed since 1.6 and was missing from BOTH renderers, so
+ * every row with a trailing chevron had to be faked with a suffix widget the
+ * widget does not have.
+ */
+export declare const BUTTON_ROW_ICON_VECTORS: ReadonlyArray<ButtonRowIconVector>;
+/** One "is this row activatable" expectation. */
+export interface ButtonRowActivatableVector {
+    /** The `activatable` markup/property a caller supplies, if any. */
+    declared: string | null;
+    /** Whether the row activates. Always `true`. */
+    activatable: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `Adw.ButtonRow` is always activatable — `adw-button-row.ui:5` sets it TRUE in
+ * the template, `adw-button-row.c:31` documents it in one line, and the class
+ * exposes no property, no setter and no getter for it (the whole public surface
+ * is C:270-352: `new`, and the two icon-name pairs).
+ *
+ * The vector exists because the browser renderer had invented an
+ * `activatable="false"` opt-out — and `adw-button-row.spec.ts` PINNED the
+ * invention with a passing test, which is worse than not testing it: it made the
+ * divergence look like a decision. A row that reads its own attribute is a row
+ * that has to be told to ignore it.
+ */
+export declare const BUTTON_ROW_ACTIVATABLE_VECTORS: ReadonlyArray<ButtonRowActivatableVector>;
+/** One step of a {@link WindowTitleVector}. */
+export type WindowTitleStep = {
+    op: 'set-title';
+    value: string | null;
+} | {
+    op: 'set-subtitle';
+    value: string | null;
+};
+/** One `Adw.WindowTitle` expectation. */
+export interface WindowTitleVector {
+    /** What the scenario is called. */
+    name: string;
+    /** The steps to run against a fresh window title, in order. */
+    steps: readonly WindowTitleStep[];
+    /** The title text afterwards. */
+    title: string;
+    /** Whether the title label is visible (C:207-208). */
+    titleVisible: boolean;
+    /** The subtitle text afterwards. */
+    subtitle: string;
+    /** Whether the subtitle label is visible (C:248-249). */
+    subtitleVisible: boolean;
+    /** Which property each `notify::*` named, in emission order. */
+    notified: readonly ('title' | 'subtitle')[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_window_title_set_title` / `_set_subtitle` (C:197-211, C:238-252).
+ *
+ * `null-over-empty-is-silent` is the one DIVERGENCE in this file, and it is
+ * deliberate: libadwaita would notify there, because its guard compares a
+ * never-NULL `gtk_label_get_label` against a possibly-NULL argument and
+ * `g_strcmp0 ("", NULL)` is 1. `WindowTitleState` (`../action-row.ts`) carries
+ * the reasoning for why the port normalises before comparing.
+ */
+export declare const WINDOW_TITLE_VECTORS: ReadonlyArray<WindowTitleVector>;

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

@@ -0,0 +1,61 @@
+/** One `avatarInitials` expectation. */
+export interface AvatarInitialsVector {
+    /** The `Adw.Avatar:text` value. */
+    text: string;
+    /** What `extract_initials_from_text` produces for it. */
+    initials: string;
+    /** Why this row exists — the rule or edge case it pins down. */
+    rule: string;
+}
+/**
+ * `extract_initials_from_text` (adw-avatar.c:85) — the first character, plus the
+ * character after the LAST ASCII space when there is one.
+ */
+export declare const AVATAR_INITIALS_VECTORS: ReadonlyArray<AvatarInitialsVector>;
+/** One colour-derivation expectation. */
+export interface AvatarColorVector {
+    /** The `Adw.Avatar:text` value. */
+    text: string;
+    /** `g_str_hash(text)` as `guint32` — verified against the real GLib symbol. */
+    hash: number;
+    /** `set_class_color`'s `(g_str_hash (text) % 14) + 1`, i.e. the `color{n}` CSS class. */
+    colorClass: number;
+}
+/** One `avatarMaxFontSize` expectation. */
+export interface AvatarFontSizeVector {
+    /** `Adw.Avatar:size`, the circle diameter. */
+    size: number;
+    /** `sqr_size - padding` for that diameter, rounded to 2dp for the table. */
+    maxFontSize: number;
+    /** What the browser renderer's old heuristic asked for, before this landed. */
+    legacyWebGuess: number;
+}
+/**
+ * `update_font_size`'s cap (adw-avatar.c:221-227) — the inscribed square
+ * `size / 1.4142` less `max(size * 0.4 - 5, 0)`.
+ *
+ * `legacyWebGuess` is kept in the table on purpose: it is `size * (size < 32 ?
+ * 0.5 : 0.4)`, which OVERFLOWS the cap at 28, 30, 31 and every size from 64 up
+ * (the initials spilled out of the circle), and is not even monotonic — it asked
+ * for 16px at size 31 and 13px at size 32.
+ */
+export declare const AVATAR_FONT_SIZE_VECTORS: ReadonlyArray<AvatarFontSizeVector>;
+/** One `avatarMode` expectation. */
+export interface AvatarModeVector {
+    hasCustomImage: boolean;
+    showInitials: boolean;
+    text: string;
+    mode: 'image' | 'initials' | 'icon';
+    rule: string;
+}
+/** `update_visibility` (adw-avatar.c:117). */
+export declare const AVATAR_MODE_VECTORS: ReadonlyArray<AvatarModeVector>;
+/**
+ * `g_str_hash` + `set_class_color` (adw-avatar.c:143).
+ *
+ * The non-ASCII rows are the ones that matter: GLib hashes the UTF-8 bytes as
+ * `signed char`, so a port reading UTF-16 code units picks a different colour
+ * for every accented name. `"Jörg Schröder"` is the canary — it landed on
+ * `color6` before this table existed, where GTK paints `color14`.
+ */
+export declare const AVATAR_COLOR_VECTORS: ReadonlyArray<AvatarColorVector>;

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

@@ -0,0 +1,91 @@
+/** One property-default expectation. */
+export interface BannerDefaultVector {
+    /** The `Adw.Banner` property name, as GObject spells it. */
+    property: 'title' | 'button-label' | 'revealed' | 'use-markup' | 'button-style';
+    /** The `GParamSpec` default. */
+    value: string | boolean;
+    /** Why this row exists — the rule or edge case it pins down. */
+    rule: string;
+}
+/**
+ * The five `GParamSpec` defaults (adw-banner.c:391-459).
+ *
+ * `revealed: false` and `useMarkup: true` are the two that were wrong in the
+ * ports. `@gjsify/adwaita-nativescript` initialised `_revealed = true` and its
+ * constructor never wrote `visibility`, so a banner showed itself on a device
+ * and stayed hidden in the browser; both ports made `use-markup` opt-in, and the
+ * browser element's comment claimed that WAS the C default.
+ */
+export declare const BANNER_DEFAULT_VECTORS: ReadonlyArray<BannerDefaultVector>;
+/** One button-visibility expectation. */
+export interface BannerButtonVisibleVector {
+    /** The `button-label` value, or `null` for the `NULL` the C setter accepts. */
+    label: string | null;
+    /** Whether `gtk_widget_set_visible` is handed a true value (:663). */
+    visible: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_banner_set_button_label` (:663) — `gtk_widget_set_visible (button, label
+ * && label[0])`.
+ *
+ * A FIRST-CHARACTER test. The whitespace rows are the ones that matter: a
+ * renderer that trimmed before testing would hide a button GTK draws.
+ */
+export declare const BANNER_BUTTON_VISIBLE_VECTORS: ReadonlyArray<BannerButtonVisibleVector>;
+/** One button-label text expectation. */
+export interface BannerButtonTextVector {
+    /** The `button-label` value. */
+    label: string;
+    /** What a renderer without an accelerator layer paints. */
+    text: string;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The banner button's text after mnemonic resolution.
+ *
+ * The template pins the BUTTON to `use-underline=True` (adw-banner.ui:33) with
+ * no property to turn it off, and pins the TITLE label to `use-underline=False`
+ * (adw-banner.ui:20). So the same underscore is an accelerator marker in the
+ * button and a literal in the title — which is why there is no title
+ * counterpart to this table. Neither port stripped anything.
+ */
+export declare const BANNER_BUTTON_TEXT_VECTORS: ReadonlyArray<BannerButtonTextVector>;
+/** One `button-style` → style-class expectation. */
+export interface BannerButtonStyleVector {
+    /** The `AdwBannerButtonStyle` nick. */
+    style: 'default' | 'suggested';
+    /** The classes on the button node (:764-774). */
+    classes: readonly string[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_banner_set_button_style`'s switch (:764-774) — the property adds or
+ * removes exactly one class and touches nothing else.
+ *
+ * Present in this vendored source since 1.7 (:34) and in NEITHER renderer, so a
+ * banner asking for a suggested action button got a grey one in both.
+ */
+export declare const BANNER_BUTTON_STYLE_VECTORS: ReadonlyArray<BannerButtonStyleVector>;
+/** One `button-style` attribute-parsing expectation. */
+export interface BannerButtonStyleParseVector {
+    /** The renderer-level string — an HTML attribute, an XML property. */
+    input: string | null;
+    /** The `AdwBannerButtonStyle` it resolves to. */
+    style: 'default' | 'suggested';
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * Turning a renderer-supplied STRING into the enum.
+ *
+ * Not a C behaviour and cannot be: `adw_banner_set_button_style` range-guards an
+ * `AdwBannerButtonStyle` it has already been handed (:756-757), so an
+ * unrepresentable string never reaches it. Falling back to the property default
+ * is what `g_object_set` does with an invalid nick, and it is the only answer
+ * that keeps the two renderers agreeing on the same markup.
+ */
+export declare const BANNER_BUTTON_STYLE_PARSE_VECTORS: ReadonlyArray<BannerButtonStyleParseVector>;

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

@@ -0,0 +1,110 @@
+/** One property-default expectation. */
+export interface ButtonContentDefaultVector {
+    /** The `AdwButtonContent` property name, as GObject spells it. */
+    property: 'icon-name' | 'label' | 'use-underline' | 'can-shrink';
+    /** The `GParamSpec` default. */
+    value: string | boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/** The four `GParamSpec` defaults (adw-button-content.c:229-272). */
+export declare const BUTTON_CONTENT_DEFAULT_VECTORS: ReadonlyArray<ButtonContentDefaultVector>;
+/** One icon-name resolution expectation. */
+export interface ButtonContentIconVector {
+    /** The `icon-name` value. */
+    iconName: string;
+    /** The name the `GtkImage` is actually set from (:355-358). */
+    resolved: string;
+    /** Whether the resolved name is the empty-slot fallback rather than an app value. */
+    isFallback: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_button_content_set_icon_name` (:355-358).
+ *
+ * THE DOCS AND THE CODE DISAGREE AND THIS TABLE FOLLOWS THE CODE. Both doc
+ * comments say an empty `icon-name` means the icon "is not shown" (:228 on the
+ * property, :343 on the setter). Nothing in the widget hides it:
+ * `gtk_widget_set_visible` is called on the LABEL only (:300, :398), `init` sets
+ * the image to `image-missing` while `icon_name` is still `""` (:284, :294), and
+ * the setter re-applies that fallback for every empty value (:355-356). So a
+ * default-constructed `AdwButtonContent` draws the broken-image glyph, and both
+ * ports — which followed the prose and hid the icon — are the ones that diverge.
+ * Encoding the prose would have pinned their guess under the word "conformance".
+ */
+export declare const BUTTON_CONTENT_ICON_VECTORS: ReadonlyArray<ButtonContentIconVector>;
+/** One label-slot expectation. */
+export interface ButtonContentLabelVector {
+    /** The `label` value. */
+    label: string;
+    /** Whether the label node is in the tree (:398). */
+    visible: boolean;
+    /** Whether the icon takes the box's free space (:399). */
+    iconExpands: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_button_content_set_label` (:398-399) — the two calls it makes, both keyed
+ * on `label[0]` and therefore exact complements.
+ */
+export declare const BUTTON_CONTENT_LABEL_VECTORS: ReadonlyArray<ButtonContentLabelVector>;
+/** One label-text expectation. */
+export interface ButtonContentTextVector {
+    /** The `label` value. */
+    label: string;
+    /** The `use-underline` value. */
+    useUnderline: boolean;
+    /** What a renderer without an accelerator layer paints. */
+    text: string;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_button_content_set_use_underline` (:442) applied to the label.
+ *
+ * Absent from both ports, and it is the property the class docs single out —
+ * "handles … connecting the mnemonic to the button automatically" (:42-43). The
+ * default is FALSE (:253-256), so an underscore in an unconfigured button
+ * content is a LITERAL, unlike the banner's action button.
+ */
+export declare const BUTTON_CONTENT_TEXT_VECTORS: ReadonlyArray<ButtonContentTextVector>;
+/** One `can-shrink` expectation. */
+export interface ButtonContentEllipsizeVector {
+    /** The `can-shrink` value. */
+    canShrink: boolean;
+    /** The label's `PangoEllipsizeMode` (:489-491). */
+    ellipsize: 'none' | 'end';
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_button_content_set_can_shrink` (:489-491), which the getter reads back as
+ * `ellipsize != PANGO_ELLIPSIZE_NONE` (:462).
+ *
+ * The browser port had this; the NativeScript port had no such property, so the
+ * shared story's `canShrink` control did nothing there.
+ */
+export declare const BUTTON_CONTENT_ELLIPSIZE_VECTORS: ReadonlyArray<ButtonContentEllipsizeVector>;
+/** One style-class targeting expectation. */
+export interface ButtonContentStyleTargetVector {
+    /** The ancestor chain, NEAREST first, as `adw_button_content_root` walks it. */
+    ancestors: ReadonlyArray<'button' | 'menu-button' | 'split-button' | 'other'>;
+    /** Index into {@link ancestors} that receives `image-text-button`, or `null`. */
+    target: number | null;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_button_content_root` (:108-116) — nearest `GtkButton`, then ONE
+ * substitution: if that button's DIRECT parent is an `AdwSplitButton`, the class
+ * moves to the split button (:112-113).
+ *
+ * Neither renderer applied the class to anything at all, so every row here is a
+ * new assertion rather than a pinned behaviour. The split-button row is the one
+ * with a CSS consequence beyond padding: the class on the `splitbutton` node
+ * selects `splitbutton.image-text-button > button` (_buttons.scss:499-507),
+ * which is a different declaration block from the plain-button one.
+ */
+export declare const BUTTON_CONTENT_STYLE_TARGET_VECTORS: ReadonlyArray<ButtonContentStyleTargetVector>;