@gjsify/adwaita-core 0.36.0 → 0.38.0

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

@@ -1,42 +1,31 @@
 /**
  * The four mutually exclusive content slots of the action half. `'empty'` is the
- * initial state — `label`, `icon-name` and `child` are all `NULL`
- * (adw-split-button.c:311-352).
+ * initial state — `label`, `icon-name` and `child` are all `NULL`.
  */
 export type SplitButtonContentMode = 'empty' | 'label' | 'icon' | 'child';
-/** `GtkArrowType` as a string union. Default `'down'` (adw-split-button.c:420). */
+/** `GtkArrowType` as a string union. Default `'down'`. */
 export type SplitButtonDirection = 'none' | 'up' | 'down' | 'left' | 'right';
 /**
- * Every symbolic icon an `arrow` node can be given `-gtk-icon-source` for
- * (_buttons.scss:451-469 plus the `splitbutton` override at :621-623).
- *
- * A union rather than `string` so a renderer's glyph→asset table is TOTAL: an
- * `Adwaita` release that introduces a sixth glyph breaks the renderers at COMPILE
- * time instead of painting a blank arrow at runtime.
+ * Every symbolic icon an `arrow` node can be given `-gtk-icon-source` for. A union rather
+ * than `string` so a renderer's glyph→asset table is TOTAL: an Adwaita release that adds a
+ * sixth glyph breaks the renderers at COMPILE time instead of painting a blank arrow at
+ * runtime.
  */
 export type AdwArrowIcon = 'open-menu-symbolic' | 'pan-down-symbolic' | 'pan-up-symbolic' | 'pan-start-symbolic' | 'pan-end-symbolic';
 /** A root style class `update_style_classes` puts on the `splitbutton` node. */
 export type SplitButtonStyleClass = 'image-button' | 'text-button';
 /**
- * The GObject property names this widget notifies.
- *
- * Carried in {@link SplitButtonChange.notified} so a renderer can re-emit
- * `notify::*` with the same sequence the upstream suite asserts: one mutation
- * emits SEVERAL notifications inside a single freeze/thaw
- * (adw-split-button.c:671-681), and that sequence cannot be reconstructed from
- * the final state alone.
- *
- * `can-shrink` is deliberately absent — see the module note on deferred scope.
+ * The GObject property names this widget notifies, carried in
+ * {@link SplitButtonChange.notified} so a renderer can re-emit `notify::*` with the same
+ * sequence the upstream suite asserts: one mutation emits SEVERAL notifications inside a
+ * single freeze/thaw, and that sequence cannot be reconstructed from the final state alone.
  */
 export type SplitButtonProperty = 'label' | 'icon-name' | 'child' | 'use-underline' | 'menu-model' | 'popover' | 'direction' | 'dropdown-tooltip';
 /**
  * One `GMenuModel` item: a label plus the detailed action it invokes, i.e. what
- * `Gio.Menu.append (label, action)` produces (adw-split-button.c:385-388).
- *
- * `id` and `icon` are the existing menu-button extras from the two renderers, so
- * all four menu call sites in the workspace can converge on ONE type. The name
- * is family-neutral on purpose: `Adw.MenuButton` needs exactly this and must be
- * able to adopt it without a rename.
+ * `Gio.Menu.append (label, action)` produces. `id` and `icon` are the renderers'
+ * menu-button extras, so every menu call site can converge on ONE type; the name is
+ * family-neutral because `Adw.MenuButton` needs exactly this.
  */
 export interface AdwMenuEntry {
     /** Display label. */
@@ -80,29 +69,23 @@ export interface SplitButtonHalfState {
     /** The `keyboard-activating` CSS class GTK sets during a keyboard press. */
     keyboardActivating: boolean;
 }
-/** The translatable default dropdown tooltip (adw-split-button.c:531-532, :1049-1050). */
+/** The translatable default dropdown tooltip. */
 export declare const DEFAULT_DROPDOWN_TOOLTIP = "More Options";
 /** Adwaita's `--disabled-opacity`, for renderers that dim rather than desaturate. */
 export declare const SPLIT_BUTTON_DISABLED_OPACITY = 0.5;
 /**
- * `update_style_classes` as a pure function (adw-split-button.c:145-165).
- *
- * Both branches test the FIRST CHARACTER, not truthiness of the value: `''` is a
- * perfectly good label — non-`NULL`, so `get_label()` returns it and
- * `get_icon_name()` is `NULL` — yet `label[0]` is NUL, so it carries no
- * `text-button` class. `'  '` does carry it, and renders two spaces: nothing in
- * the C path trims.
+ * `update_style_classes` as a pure function. Both branches test the FIRST CHARACTER, not
+ * truthiness: `''` is a perfectly good label — non-`NULL`, so `get_label()` returns it and
+ * `get_icon_name()` is `NULL` — yet `label[0]` is NUL, so it carries no `text-button`
+ * class. `' '` does carry it and renders two spaces; nothing in the C path trims.
  */
 export declare function splitButtonStyleClasses(label: string | null, iconName: string | null): readonly SplitButtonStyleClass[];
 /**
- * The dropdown tooltip to actually show, and whether it is markup
- * (adw-split-button.c:1044-1051).
- *
+ * The dropdown tooltip to actually show, and whether it is markup.
  * `has_dropdown_tooltip = tooltip && *tooltip` — a non-empty value goes through
- * `gtk_widget_set_tooltip_markup` (Pango markup), an empty one restores the
- * translated default as plain TEXT. The distinction is not cosmetic: a renderer
- * that escapes the markup branch, or that leaves the accessible name empty on
- * the default branch, is a different widget.
+ * `gtk_widget_set_tooltip_markup` (Pango markup), an empty one restores the translated
+ * default as plain TEXT. Not cosmetic: a renderer that escapes the markup branch, or
+ * leaves the accessible name empty on the default branch, is a different widget.
  */
 export declare function resolveDropdownTooltip(tooltip: string): {
     text: string;
@@ -110,71 +93,53 @@ export declare function resolveDropdownTooltip(tooltip: string): {
 };
 /**
  * The arrow glyph a PLAIN `menubutton` draws for a direction — `none` is the
- * `open-menu-symbolic` hamburger (_buttons.scss:454-456).
- *
- * Use {@link splitButtonArrowIcon} for the dropdown half of a split button, which
- * the stylesheet gives a different `none`.
+ * `open-menu-symbolic` hamburger. Use {@link splitButtonArrowIcon} for the dropdown half
+ * of a split button, which the stylesheet gives a different `none`.
  */
 export declare function menuButtonArrowIcon(direction: SplitButtonDirection): AdwArrowIcon;
 /**
- * The arrow glyph a SPLIT BUTTON's dropdown half draws for a direction — `none`
- * is `pan-down-symbolic`, per the `splitbutton` override at _buttons.scss:621-623.
+ * The arrow glyph a SPLIT BUTTON's dropdown half draws — `none` is `pan-down-symbolic`,
+ * per the stylesheet's `splitbutton` override.
  */
 export declare function splitButtonArrowIcon(direction: SplitButtonDirection): AdwArrowIcon;
 /**
- * Where the popup is placed: `'none'` behaves the same as `'down'`
- * (adw-split-button.c:415).
- *
- * PLACEMENT IS NOT A SPLIT-BUTTON RULE, unlike the glyph. `adw_split_button_set_direction`
- * is a pass-through to `gtk_menu_button_set_direction` (:997) and the getter reads
- * it straight back off the same `GtkMenuButton` (:971) — the split button stores
- * nothing and overrides nothing here, so `none → down` is `GtkMenuButton`'s own
- * behaviour. {@link menuButtonPopupDirection} is therefore this very function
- * rather than a second copy of it.
+ * Where the popup is placed: `'none'` behaves the same as `'down'`. Placement is NOT a
+ * split-button rule, unlike the glyph: `adw_split_button_set_direction` is a pass-through
+ * to `gtk_menu_button_set_direction` and the getter reads it straight back off the same
+ * `GtkMenuButton`, so `none → down` is `GtkMenuButton`'s own behaviour and
+ * {@link menuButtonPopupDirection} is this very function rather than a copy.
  */
 export declare function splitButtonPopupDirection(direction: SplitButtonDirection): Exclude<SplitButtonDirection, 'none'>;
 /**
  * Where a plain `menubutton` places its popup — deliberately an ALIAS of
- * {@link splitButtonPopupDirection}, not a copy.
- *
- * The two arrow-glyph functions differ because the stylesheet overrides the glyph
- * per widget; placement has no such override, and pinning that as reference
- * equality (`menuButtonPopupDirection === splitButtonPopupDirection`) is a claim a
- * test can hold, where a duplicated body would only be a claim a comment makes.
+ * {@link splitButtonPopupDirection}, so that the "placement has no per-widget override"
+ * claim is reference equality a test can hold rather than a comment.
  */
 export declare const menuButtonPopupDirection: typeof splitButtonPopupDirection;
 /** Whether `value` names a `GtkArrowType`, for parsing a renderer attribute. */
 export declare function isSplitButtonDirection(value: unknown): value is SplitButtonDirection;
 /**
- * `update_state` as a pure fold (adw-split-button.c:118-143).
- *
- * The two halves are separate widgets, but the state the STYLESHEET keys off
- * sits on the root: `splitbutton.flat:checked` shades the whole control and
- * hides the separator while the menu is open (_buttons.scss:542-549). Neither
- * renderer folded it, so both showed a per-half highlight only.
+ * `update_state` as a pure fold. The two halves are separate widgets, but the state the
+ * STYLESHEET keys off sits on the root: `splitbutton.flat:checked` shades the whole control
+ * and hides the separator while the menu is open.
  */
 export declare function splitButtonRootState(action: SplitButtonHalfState, dropdown: SplitButtonHalfState): {
     active: boolean;
     checked: boolean;
 };
 /**
- * Parse a JSON menu attribute into entries.
- *
- * Total by construction — malformed JSON, a non-array root and entries without a
- * `label` key all yield `[]` / are dropped — because the input is author-written
- * markup and a typo must not take the widget down with it. Replaces the two
- * byte-identical copies in `adw-split-button.ts` and `adw-menu-button.ts`.
+ * Parse a JSON menu attribute into entries. Total by construction — malformed JSON, a
+ * non-array root and entries without a `label` key all yield `[]` / are dropped — because
+ * the input is author-written markup and a typo must not take the widget down with it.
  */
 export declare function parseMenuEntries(json: string | null | undefined): AdwMenuEntry[];
 /**
  * The whole `Adw.SplitButton` state machine: content mode, use-underline,
- * menu-model/popover exclusivity, direction, dropdown tooltip and the popup flag.
- *
- * Every mutator returns whether it changed anything and notifies only on a real
- * change, like `ComboState`/`SpinState`. What this class adds over those is
- * {@link SplitButtonChange.notified}: an ORDERED property list, because a single
- * `set_label()` can emit `notify::icon-name`, `notify::child` and `notify::label`
- * in that order and the upstream suite counts them.
+ * menu-model/popover exclusivity, direction, dropdown tooltip and the popup flag. Every
+ * mutator returns whether it changed anything and notifies only on a real change, like
+ * `ComboState`/`SpinState`, plus {@link SplitButtonChange.notified}: an ORDERED property
+ * list, because a single `set_label()` can emit `notify::icon-name`, `notify::child` and
+ * `notify::label` in that order and the upstream suite counts them.
  */
 export declare class SplitButtonState {
     private _mode;
@@ -196,20 +161,16 @@ export declare class SplitButtonState {
     /** The label, or `null` unless {@link mode} is `'label'`. */
     get label(): string | null;
     /**
-     * Set the label, clearing `icon-name` and `child`
-     * (adw-split-button.c:661-682).
-     *
-     * A non-string is rejected outright and changes nothing, mirroring
-     * `g_return_if_fail (label != NULL)` at :666 — there is no "unset the label"
-     * path in C, clearing it is a side effect of setting another slot.
+     * Set the label, clearing `icon-name` and `child`. A non-string is rejected outright,
+     * mirroring `g_return_if_fail (label != NULL)` — there is no "unset the label" path in
+     * C, clearing it is a side effect of setting another slot.
      */
     setLabel(label: string): boolean;
     /** The icon name, or `null` unless {@link mode} is `'icon'`. */
     get iconName(): string | null;
     /**
-     * Set the icon name, clearing `label` and `child`
-     * (adw-split-button.c:749-771). A non-string is rejected — `g_return_if_fail
-     * (icon_name != NULL)` at :754.
+     * Set the icon name, clearing `label` and `child`. A non-string is rejected —
+     * `g_return_if_fail (icon_name != NULL)`.
      */
     setIconName(iconName: string): boolean;
     /**
@@ -218,12 +179,9 @@ export declare class SplitButtonState {
      */
     get child(): object | null;
     /**
-     * Set (or clear, with `null`) the child, clearing `label` and `icon-name`
-     * (adw-split-button.c:799-824).
-     *
-     * This is also the only way to reach `'empty'` again from a filled slot, and
-     * it is how a renderer expresses "no content" — `setChild(null)` on a fresh
-     * state is correctly a no-op (:806-807).
+     * Set (or clear, with `null`) the child, clearing `label` and `icon-name`. The only way
+     * back to `'empty'` from a filled slot, and how a renderer expresses "no content" —
+     * `setChild(null)` on a fresh state is correctly a no-op.
      */
     setChild(child: object | null | undefined): boolean;
     /** The root style classes for the current content. */
@@ -231,74 +189,61 @@ export declare class SplitButtonState {
     /** Whether an underline in the label marks a mnemonic. */
     get useUnderline(): boolean;
     /**
-     * Set the mnemonic flag (adw-split-button.c:709-721). `!!`-normalised at :715,
-     * so a truthy non-boolean stores `true` and a following `setUseUnderline(true)`
-     * is correctly a no-op.
-     *
-     * Only the PROPERTY lives here. The `_S` → underlined-S derivation belongs to
-     * `GtkLabel`, not to this widget or its test — see the module note on
-     * deferred scope.
+     * Set the mnemonic flag, `!!`-normalised as C does, so a truthy non-boolean stores
+     * `true` and a following `setUseUnderline(true)` is correctly a no-op. Only the
+     * PROPERTY lives here; the `_S` → underlined-S derivation belongs to `GtkLabel`.
      */
     setUseUnderline(value: boolean): boolean;
     /** The menu entries, or `null` when no menu model is set. */
     get menuModel(): readonly AdwMenuEntry[] | null;
     /**
-     * Set the menu model, dissociating any popover (adw-split-button.c:906-916,
-     * :397-398) and replacing it with the model-derived one.
+     * Set the menu model, dissociating any popover and replacing it with the model-derived
+     * one.
      *
-     * DELIBERATE NORMALISATION: an EMPTY list is stored as "no menu model". C can
-     * hold a non-`NULL` but empty `GMenu`, which leaves the dropdown live and
-     * pops up an empty popover — but neither renderer can construct that state
-     * (one parses a JSON array, the other takes a label list), so the two cases
-     * are the same input here, and collapsing them is what makes "no menu ⇒
-     * insensitive dropdown" (:376-378) hold from a renderer's point of view. The
-     * `@gjsify/adwaita-web` bug this kills was a click on a menu-less split
-     * button opening an empty, fully styled popover.
+     * DELIBERATE NORMALISATION: an EMPTY list is stored as "no menu model". C can hold a
+     * non-`NULL` but empty `GMenu`, which leaves the dropdown live and pops up an empty
+     * popover — but no renderer can construct that state (one parses a JSON array, another
+     * takes a label list), so collapsing the two is what makes "no menu ⇒ insensitive
+     * dropdown" hold from a renderer's point of view.
      */
     setMenuModel(entries: readonly AdwMenuEntry[] | null | undefined): boolean;
     /** The popover: the one the app set, or the model-derived stand-in, or `null`. */
     get popover(): object | null;
     /**
-     * Set the popover, dissociating any menu model (adw-split-button.c:946-956,
-     * :390-398).
-     *
-     * The cleared property is notified before the set one, the order
-     * `set_label`/`set_icon_name`/`set_child` use throughout this widget
-     * (:671-681). GtkMenuButton's own internal ordering is not observable from
-     * the upstream suite, which only counts per-property notifications.
+     * Set the popover, dissociating any menu model. The cleared property is notified before
+     * the set one, the order `set_label()`/`set_icon_name`/`set_child` use throughout this
+     * widget; GtkMenuButton's own internal ordering is not observable from the upstream
+     * suite, which only counts per-property notifications.
      */
     setPopover(popover: object | null | undefined): boolean;
     /**
-     * Whether the dropdown half is live. "If the menu model is `NULL`, the
-     * dropdown is disabled" (adw-split-button.c:376-378) and the same for the
-     * popover (:394-396) — with neither, GtkMenuButton is insensitive.
+     * Whether the dropdown half is live: with neither a menu model nor a popover,
+     * GtkMenuButton is insensitive.
      */
     get dropdownEnabled(): boolean;
     /** The direction the popup opens in, and the arrow points. */
     get direction(): SplitButtonDirection;
-    /** Set the direction (adw-split-button.c:988-1000). An unknown value is rejected. */
+    /** Set the direction. An unknown value is rejected. */
     setDirection(direction: SplitButtonDirection): boolean;
     /** The arrow glyph for the current direction, with the split button's `none`. */
     get arrowIcon(): AdwArrowIcon;
     /**
-     * The dropdown tooltip as SET — `''` while unset, never `null`
-     * (adw-split-button.c:1017-1018). Pass it through
+     * The dropdown tooltip as SET — `''` while unset, never `null`. Pass it through
      * {@link resolveDropdownTooltip} to get what should actually be shown.
      */
     get dropdownTooltip(): string;
     /**
-     * Set the dropdown tooltip (adw-split-button.c:1034-1054). The guard compares
-     * against the GETTER (:1041-1042), which already reports `''` when unset — so
-     * clearing an unset tooltip notifies nothing, while clearing a set one does
-     * notify and RESTORES the default rather than blanking the tooltip.
+     * Set the dropdown tooltip. C's guard compares against the GETTER, which already reports
+     * `''` when unset, so clearing an unset tooltip notifies nothing while clearing a set
+     * one notifies and RESTORES the default rather than blanking the tooltip.
      */
     setDropdownTooltip(tooltip: string): boolean;
     /** Whether the menu is popped up. */
     get open(): boolean;
     private _setOpen;
-    /** Pop the menu up programmatically — `adw_split_button_popup` (:1062-1068). */
+    /** Pop the menu up programmatically — `adw_split_button_popup`. */
     openMenu(): boolean;
-    /** Dismiss the menu programmatically — `adw_split_button_popdown` (:1076-1082). */
+    /** Dismiss the menu programmatically — `adw_split_button_popdown`. */
     closeMenu(): boolean;
     /** The dropdown half was activated by the user; flips the menu open/closed. */
     toggleMenu(): boolean;
@@ -306,10 +251,9 @@ export declare class SplitButtonState {
      * Activate a menu entry BY POSITION and dismiss the menu, returning the entry
      * (or `null` for an out-of-range index).
      *
-     * Position is the addressing a `GMenuModel` actually uses — each item carries
-     * its own detailed action (adw-split-button.c:385-388). Resolving a choice by
-     * LABEL, as the NativeScript port did, silently dispatches the first of two
-     * identically named entries and cannot tell an entry called `Cancel` from a
+     * Position is the addressing a `GMenuModel` actually uses — each item carries its own
+     * detailed action. Resolving a choice by LABEL instead silently dispatches the first of
+     * two identically named entries and cannot tell an entry called `Cancel` from a
      * dismissed sheet.
      */
     activateMenuEntry(index: number): AdwMenuEntry | null;