@gjsify/adwaita-core 0.36.0 → 0.37.0

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

@@ -2,11 +2,11 @@
 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. */
+    /** `string_is_not_empty(title)`, bound from `adw-action-row.ui`. */
     titleVisible: boolean;
     /** The subtitle label's text — `''` for an unset subtitle. */
     subtitle: string;
-    /** `string_is_not_empty(subtitle)` — adw-action-row.ui:71-75. */
+    /** `string_is_not_empty(subtitle)`, bound from `adw-action-row.ui`. */
     subtitleVisible: boolean;
 }
 /** What a row knows about its two labels. */
@@ -18,43 +18,38 @@ export interface AdwRowLabelInput {
 }
 /**
  * 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.
+ * computes. Exported on its own — not just as part of {@link ActionRowState} — because
+ * the rows that have a core state machine of their OWN (`Adw.ComboRow`,
+ * `Adw.ExpanderRow`, `Adw.SpinRow` via `rows.ts`) still render this pair.
  */
 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.
+     * `GtkListBoxRow:activatable` — whether a click activates the row at all. `False`
+     * in the template and raised by an activatable widget, not 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.
+ * `Adw.ActionRow`: two labels plus the `activatable-widget` coupling, which 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.
+ * (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`. So
+ * handing the row an INSENSITIVE widget leaves the row unactivatable, and later
+ * flipping that widget's `sensitive` flips the row with it, 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.
+ * (2) Clearing the widget only UNBINDS
+ * (`g_clear_pointer (&priv->activatable_binding, g_binding_unbind)`); it never writes
+ * `activatable` back, so the row STAYS activatable after its widget is taken away —
+ * which the class documentation states outright ("unsetting it won't change the row's
+ * activatability"). Modelling 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.
+ * `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;
@@ -75,29 +70,27 @@ export declare class ActionRowState<TWidget = unknown> {
     /** `AdwActionRow:activatable-widget` — `null` when unset. */
     get activatableWidget(): TWidget | null;
     /**
-     * `adw_action_row_set_activatable_widget` (C:696-741).
+     * `adw_action_row_set_activatable_widget`.
      *
-     * `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).
+     * `sensitive` is the widget's own `GtkWidget:sensitive` at the moment of the set,
+     * which `G_BINDING_SYNC_CREATE` copies straight into `activatable`; it defaults to
+     * `true` because a freshly built widget is sensitive. Passing `null` unbinds and
+     * LEAVES `activatable` alone.
      *
-     * Returns whether the widget changed — the `notify::activatable-widget` gate
-     * (C:740, guarded by the identity early-return at C:706-707).
+     * Returns whether the widget changed — the `notify::activatable-widget` gate, which
+     * the C guards with an identity early-return.
      */
     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`.
+     * `sensitive`. Safe to call unconditionally. Two things make it a no-op, both the
+     * C's:
+     *   - no widget is set, so `g_clear_pointer (…, g_binding_unbind)` 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, re-asserting the value the widget already had would
+     *     silently undo a direct write to `activatable`.
      *
      * Returns whether `activatable` changed.
      */
@@ -105,97 +98,84 @@ export declare class ActionRowState<TWidget = unknown> {
     /** `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.
+     * 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. Refusing 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`.
+     * `adw_action_row_activate_real`: 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.
+     * UNCONDITIONALLY afterwards — the C's `g_signal_emit` sits outside the `if`, and
+     * `adw_action_row_activate` is public API 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.SwitchRow`: one boolean and its notify rule.
  *
- * `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.
+ * `adw_switch_row_set_active` early-returns when the value is unchanged and otherwise
+ * writes the slider, whose `notify::active` runs `slider_notify_active_cb` — 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. That is also why there is
+ * deliberately NO `interactive` flag here (the `SpinState`/`ComboState` shape): it would
+ * be an abstraction the C contradicts.
  *
- * 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.
+ * The DOM makes this easy to get wrong: `<input>`'s `change` event does not fire for a
+ * programmatic `.checked =`, so a renderer that only re-emits `change` is silent for
+ * `row.active = true`.
  */
 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.
+     * `adw_switch_row_set_active`. Returns whether it changed — i.e. whether the renderer
+     * must emit `notify::active`. The `!!is_active` normalisation is the C's.
      */
     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.
+     * `adw_switch_row_init` makes the row activatable and points the activatable-widget
+     * at the slider, 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") — the whole row is the target, not just the handle.
      *
      * 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.
+ * `Adw.ButtonRow` is ALWAYS activatable — `<property name="activatable">True</property>`
+ * in the template, with no setter and no property, and the class documentation saying so
+ * in one line ("`AdwButtonRow` is always activatable."). Exported as data so a renderer
+ * cannot invent an `activatable="false"` opt-out.
  */
 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. */
+    /** `string_is_not_empty(title)`. */
     titleVisible: boolean;
-    /** `AdwButtonRow:start-icon-name` — `''` when unset (C:209-210). */
+    /** `AdwButtonRow:start-icon-name` — `''` when unset. */
     startIconName: string;
-    /** `string_is_not_empty(start_image.icon-name)` — adw-button-row.ui:20-24. */
+    /** `string_is_not_empty(start_image.icon-name)`. */
     startIconVisible: boolean;
-    /** `AdwButtonRow:end-icon-name` — `''` when unset (C:221-222). */
+    /** `AdwButtonRow:end-icon-name` — `''` when unset. */
     endIconName: string;
-    /** `string_is_not_empty(end_image.icon-name)` — adw-button-row.ui:55-59. */
+    /** `string_is_not_empty(end_image.icon-name)`. */
     endIconVisible: boolean;
     /** Always {@link BUTTON_ROW_ACTIVATABLE}. */
     activatable: true;
@@ -203,16 +183,11 @@ export interface ButtonRowRenderState {
 /**
  * `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.
+ * `AdwButtonRow:end-icon-name` has existed since libadwaita 1.6 and is what the
+ * "Open in Files ›" shape needs. Both icon setters go through `g_set_str`, which returns
+ * FALSE for an unchanged value and thereby gates the notify; `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;
@@ -226,33 +201,28 @@ export declare class ButtonRowState {
     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. */
+    /** `adw_button_row_set_start_icon_name`. 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. */
+    /** `adw_button_row_set_end_icon_name`. 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).
+ * `Adw.WindowTitle`: the same two labels, one level out of the boxed list. Three rules —
+ * the TITLE label is hidden when the title is empty (the `.ui` even starts it
+ * `visible=False`), a set to the CURRENT value returns early, and a real change notifies.
  *
- * 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.
+ * 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=""`.
+ * The normalisation happens BEFORE the comparison, and `WINDOW_TITLE_VECTORS` pins the
+ * divergence rather than hiding it.
  */
 export declare class WindowTitleState {
     private _title;
@@ -261,10 +231,10 @@ export declare class WindowTitleState {
     get state(): WindowTitleRenderState;
     /** `Adw.WindowTitle:title`. */
     get title(): string;
-    /** `adw_window_title_set_title` (C:197-211). Returns whether it changed. */
+    /** `adw_window_title_set_title`. 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. */
+    /** `adw_window_title_set_subtitle`. Returns whether it changed. */
     setSubtitle(subtitle: string | null | undefined): boolean;
 }

package/lib/types/avatar.d.ts

@@ -17,35 +17,31 @@ export declare const AVATAR_COLORS: ReadonlyArray<AdwAvatarColor>;
 /**
  * GLib's `g_str_hash` — the DJB2 variant `h = h * 33 + c`, as `guint32`.
  *
- * Two details decide whether the avatar colour matches GTK, and both were wrong
- * in the renderer copies this replaces: `c` is a **`signed char` of the UTF-8
- * encoding**, not a UTF-16 code unit, so bytes ≥ 0x80 contribute NEGATIVE values
- * (`"Jörg Schröder"` picked colour 5 instead of 13); and the C loop stops at the
- * first NUL byte, so an embedded `\0` truncates the input.
+ * Two details decide whether the avatar colour matches GTK: `c` is a **`signed char` of
+ * the UTF-8 encoding**, not a UTF-16 code unit, so bytes ≥ 0x80 contribute NEGATIVE
+ * values; and the C loop stops at the first NUL byte, so an embedded `\0` truncates the
+ * input.
  */
 export declare function gStrHash(text: string): number;
 /**
- * The initials `Adw.Avatar` shows for `text`: the first character, plus the
- * character following the LAST space if there is one.
+ * The initials `Adw.Avatar` shows for `text`: the first character, plus the character
+ * following the LAST space if there is one.
  *
- * Mirrors `extract_initials_from_text` step for step — upcase, then strip, then
- * NFC-normalise, then take code points (never UTF-16 units, so an astral first
- * letter survives). Only a literal ASCII space separates the two initials, so
- * `"Ada\tLovelace"` yields `"A"`, exactly as GTK does.
+ * Mirrors `extract_initials_from_text` step for step — upcase, strip, NFC-normalise,
+ * then take code points (never UTF-16 units, so an astral first letter survives). Only a
+ * literal ASCII space separates the two initials, so `"Ada\tLovelace"` yields `"A"`.
  *
- * Returns `''` for a blank name. libadwaita instead emits a one-NUL-byte label
- * there, because its caller only guards the RAW text against being empty; an
- * empty string is the sane rendering of the same "no initials" state.
+ * Returns `''` for a blank name, where libadwaita emits a one-NUL-byte label because its
+ * caller only guards the RAW text against being empty.
  */
 export declare function avatarInitials(text: string): string;
 /**
  * The 1-based colour class (`color1`…`color14`) `Adw.Avatar` assigns to `text`,
  * i.e. `set_class_color`'s `(g_str_hash (text) % NUMBER_OF_COLORS) + 1`.
  *
- * `null` for a blank name: libadwaita picks a RANDOM class there, so no value is
- * derivable from the name. A renderer that wants that behaviour calls
- * {@link randomAvatarColorClass}; one that paints nothing without initials — as
- * both current renderers do — can ignore the `null`.
+ * `null` for a blank name: libadwaita picks a RANDOM class there, so no value is derivable
+ * from the name. {@link randomAvatarColorClass} is that behaviour; a renderer that paints
+ * nothing without initials can ignore the `null`.
  */
 export declare function avatarColorClass(text: string): number | null;
 /**
@@ -64,13 +60,12 @@ export declare function avatarColor(text: string): AdwAvatarColor;
 /** Which of the three mutually exclusive things an avatar shows. */
 export type AdwAvatarMode = 'image' | 'initials' | 'icon';
 /**
- * `update_visibility` (adw-avatar.c:117): a custom image wins outright,
- * otherwise initials show when they were asked for and the name is non-empty,
- * otherwise the fallback icon.
+ * `update_visibility`: a custom image wins outright, otherwise initials show when they
+ * were asked for and the name is non-empty, otherwise the fallback icon.
  *
- * The gate is the length of the TEXT, not of the derived initials — a
- * whitespace-only name is in `'initials'` mode with a blank label, where a
- * renderer keying on the initials would fall back to the icon instead.
+ * The gate is the length of the TEXT, not of the derived initials — a whitespace-only name
+ * is in `'initials'` mode with a blank label, where a renderer keying on the initials
+ * would fall back to the icon instead.
  */
 export declare function avatarMode(input: {
     hasCustomImage: boolean;
@@ -79,26 +74,24 @@ export declare function avatarMode(input: {
 }): AdwAvatarMode;
 /**
  * The largest font size that still fits the initials inside the circle
- * (`update_font_size`, adw-avatar.c:221-227): the biggest square inscribed in
- * the circle, `size / 1.4142`, less a size-proportional padding
- * `max(size * 0.4 - 5, 0)`.
+ * (`update_font_size`): the biggest square inscribed in the circle, `size / 1.4142`, less
+ * a size-proportional padding `max(size * 0.4 - 5, 0)`.
  *
- * Monotonically increasing in `size`. A renderer that cannot measure text can
- * use this alone and stay inside libadwaita's bound — which the browser
- * renderer's old `size * (size < 32 ? 0.5 : 0.4)` did not: at size 31 it asked
- * for 15.5px against a 14.5px cap, then DROPPED to 12.8px at size 32.
+ * Monotonically increasing in `size`, which a breakpoint-style approximation
+ * (`size * (size < 32 ? 0.5 : 0.4)`) is not — that one both exceeds the cap and DROPS as
+ * the avatar grows. A renderer that cannot measure text can use this alone and stay
+ * inside libadwaita's bound.
  */
 export declare function avatarMaxFontSize(size: number): number;
 /**
  * The font size `Adw.Avatar` gives the initials label, given the label's
  * measured box: `height * (max / width)`, clamped to `[0, max]`.
  *
- * Text measurement is the one genuinely renderer-specific input, so it is
- * injected — the same seam style as `ToastScheduler`. Only the ASPECT RATIO of
- * the measurement matters (the formula scales it against the cap), so a renderer
- * may measure at any font size it likes, exactly as Pango's reset-then-measure
- * does. A non-positive width means "not laid out yet"; the cap is then the only
- * defensible answer.
+ * Text measurement is the one genuinely renderer-specific input, so it is injected (the
+ * `ToastScheduler` seam style). Only the ASPECT RATIO matters — the formula scales it
+ * against the cap — so a renderer may measure at any font size it likes, as Pango's
+ * reset-then-measure does. A non-positive width means "not laid out yet", and the cap is
+ * then the only defensible answer.
  */
 export declare function avatarFontSize(size: number, measured: {
     width: number;

package/lib/types/banner.d.ts

@@ -1,16 +1,11 @@
-/**
- * `AdwBannerButtonStyle` as a string union — the two enum nicks
- * (adw-banner.c:23-35, Since 1.7).
- */
+/** `AdwBannerButtonStyle` as a string union — the two enum nicks (since libadwaita 1.7). */
 export type AdwBannerButtonStyle = 'default' | 'suggested';
 /** Both `AdwBannerButtonStyle` members, in enum order. */
 export declare const ADW_BANNER_BUTTON_STYLES: readonly AdwBannerButtonStyle[];
 /**
- * Every style class `button-style` MANAGES on the banner button.
- *
- * A renderer swaps within this set and leaves every other class alone — the C
- * only ever adds or removes `suggested-action` (:766, :769), it never rewrites
- * the button's class list.
+ * Every style class `button-style` MANAGES on the banner button. A renderer swaps
+ * within this set and leaves every other class alone — the C only ever adds or
+ * removes `suggested-action`, it never rewrites the class list.
  */
 export declare const ADW_BANNER_BUTTON_STYLE_CLASSES: readonly string[];
 /** The five `Adw.Banner` properties, as a renderer holds them. */
@@ -26,79 +21,56 @@ export interface AdwBannerProps {
     /** `button-style` — grey (`'default'`) or `.suggested-action`. */
     buttonStyle: AdwBannerButtonStyle;
 }
-/**
- * The property defaults a freshly constructed `Adw.Banner` has, straight from
- * the `GParamSpec`s.
- *
- * Two of these are the whole reason this module exists, and both are easy to get
- * backwards from the rendered widget rather than from the source: `revealed` is
- * FALSE (:456-459) and `use-markup` is TRUE (:422-425).
- */
+/** The property defaults of a freshly constructed `Adw.Banner`, from the `GParamSpec`s. */
 export declare const ADW_BANNER_DEFAULTS: Readonly<AdwBannerProps>;
 /** Whether `value` is one of the two `AdwBannerButtonStyle` nicks. */
 export declare function isBannerButtonStyle(value: unknown): value is AdwBannerButtonStyle;
 /**
- * The button style for a renderer-supplied string — an HTML attribute, an XML
- * property, a JSON config.
+ * The button style for a renderer-supplied string — an HTML attribute, an XML property,
+ * a JSON config.
  *
- * Anything that is not a nick becomes `'default'`. That is NOT the C setter's
- * behaviour and cannot be: `adw_banner_set_button_style` guards the ENUM range
- * (:756-757) and returns without changing anything, because by the time it runs
- * the value is already an `AdwBannerButtonStyle`. A string never becomes one, so
- * there is nothing to keep — falling back to the property default is what
- * GObject itself does when an invalid nick reaches `g_object_set`.
+ * MODIFICATION: anything that is not a nick becomes `'default'`, where
+ * `adw_banner_set_button_style` guards the ENUM range and keeps the old value. It can
+ * afford to, because by then the value already IS an `AdwBannerButtonStyle`; a string
+ * never becomes one, so there is nothing to keep. Falling back to the property default
+ * is what `g_object_set` does with an invalid nick.
  */
 export declare function parseBannerButtonStyle(value: string | null | undefined): AdwBannerButtonStyle;
 /**
  * The style classes the banner button carries for `style` —
- * `adw_banner_set_button_style`'s switch (:764-774).
+ * `adw_banner_set_button_style`'s switch.
  */
 export declare function bannerButtonStyleClasses(style: AdwBannerButtonStyle): readonly string[];
 /**
  * Whether the action button is shown: `gtk_widget_set_visible (button, label &&
- * label[0])` (:663).
- *
- * The test is on the FIRST CHARACTER, so it is not a trim and not a truthiness
- * check on the trimmed value — `" "` is a one-character label and its button is
- * shown, blank-looking though it is. A renderer that trimmed here would silently
- * drop a button GTK draws.
+ * label[0])` — FIRST CHARACTER, not a trim, so `" "` is a label and its button is
+ * shown. A renderer that trimmed would drop a button GTK draws.
  */
 export declare function bannerButtonVisible(label: string | null | undefined): boolean;
 /**
- * The text painted on the action button.
- *
- * The template pins the button to `use-underline=True` (adw-banner.ui:33) and
- * exposes no property to turn it off, so an `_` in `button-label` is ALWAYS an
- * accelerator marker — `"_Resume"` reads `Resume` with an underlined R. A
- * renderer with no accelerator layer wants the marker gone, which is what
- * {@link stripMnemonic} returns.
- *
- * The TITLE deliberately has no counterpart here: the same template pins the
- * title label to `use-underline=False` (adw-banner.ui:20), so a title keeps
- * every underscore it was given. Passing a title through this function would be
- * a bug, not a symmetry.
+ * The text painted on the action button. The template pins the button to
+ * `use-underline=True` with no property to turn it off, so `_` in `button-label` is
+ * ALWAYS an accelerator marker. The TITLE has no counterpart on purpose: the same
+ * template pins it to `use-underline=False`, so a title keeps its underscores and
+ * passing one through this function is a bug, not a symmetry.
  */
 export declare function bannerButtonText(label: string): string;
 /** What one banner derivation tells a renderer to draw. */
 export interface AdwBannerRenderState {
-    /** Whether the strip is on screen (`GtkRevealer:reveal-child`, :817). */
+    /** Whether the strip is on screen (`GtkRevealer:reveal-child`). */
     revealed: boolean;
     /** Whether {@link AdwBannerProps.title} is to be read as Pango markup. */
     useMarkup: boolean;
-    /** Whether the action button is in the tree (:663). */
     buttonVisible: boolean;
     /** The button's label with mnemonic markers removed. */
     buttonText: string;
-    /** The style classes `button-style` puts on the button (:764-774). */
+    /** The style classes `button-style` puts on the button. */
     buttonClasses: readonly string[];
 }
 /**
  * The full render state for a banner, filling every unset property from
- * {@link ADW_BANNER_DEFAULTS}.
- *
- * Takes a `Partial` on purpose: a renderer reading attributes has "not set" as a
- * real state, and the whole point of this module is that "not set" resolves to
- * the libadwaita default rather than to whatever the renderer's field
- * initialiser happened to be.
+ * {@link ADW_BANNER_DEFAULTS}. `Partial` on purpose: a renderer reading attributes
+ * has "not set" as a real state, and it must resolve to the libadwaita default
+ * rather than to a field initialiser.
  */
 export declare function bannerRenderState(props?: Partial<AdwBannerProps>): AdwBannerRenderState;

package/lib/types/breakpoint.d.ts

@@ -39,10 +39,9 @@ export interface AdwBreakpointHandlers {
     onUnapply?: () => void;
 }
 /**
- * A single responsive breakpoint: a condition plus apply/unapply callbacks.
- * Mirrors `Adw.Breakpoint`. Drive {@link evaluate} from your renderer's size
- * source (e.g. `addBreakpoints` in `@gjsify/adwaita-nativescript`, or a
- * `ResizeObserver` in a browser renderer).
+ * A single responsive breakpoint: a condition plus apply/unapply callbacks, mirroring
+ * `Adw.Breakpoint`. Drive {@link evaluate} from the renderer's size source (`addBreakpoints`
+ * in `@gjsify/adwaita-nativescript`, a `ResizeObserver` in a browser renderer).
  */
 export declare class AdwBreakpoint {
     /** The parsed condition (null when an invalid string was passed). */
@@ -53,9 +52,9 @@ export declare class AdwBreakpoint {
     /** Whether the condition is currently satisfied (apply has fired, not unapply). */
     get applied(): boolean;
     /**
-     * Re-evaluate against `size`, firing apply / unapply ONLY on a state change
-     * (so a steady stream of layout passes doesn't re-run the callbacks). Returns
-     * the post-evaluation applied state. A null condition never applies.
+     * Re-evaluate against `size`, firing apply / unapply ONLY on a state change, so a steady
+     * stream of layout passes does not re-run the callbacks. Returns the post-evaluation
+     * applied state; a null condition never applies.
      */
     evaluate(size: BreakpointSize): boolean;
 }