@gjsify/adwaita-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,316 @@
+/**
+ * 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).
+ */
+export type SplitButtonContentMode = 'empty' | 'label' | 'icon' | 'child';
+/** `GtkArrowType` as a string union. Default `'down'` (adw-split-button.c:420). */
+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.
+ */
+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.
+ */
+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.
+ */
+export interface AdwMenuEntry {
+    /** Display label. */
+    label: string;
+    /** Detailed action name, e.g. `app.save-as`. */
+    action?: string;
+    /** Stable identifier, defaulting to {@link label} on activation. */
+    id?: string;
+    /** Symbolic icon name for the item. */
+    icon?: string;
+}
+/** Payload of a {@link SplitButtonState} notification. */
+export interface SplitButtonChange {
+    /** Which content slot is filled. */
+    mode: SplitButtonContentMode;
+    /** The label, or `null` unless {@link mode} is `'label'`. */
+    label: string | null;
+    /** The icon name, or `null` unless {@link mode} is `'icon'`. */
+    iconName: string | null;
+    /** The child widget — the app's in `'child'` mode, an opaque internal node in `'label'`/`'icon'` mode. */
+    child: object | null;
+    /** The root style classes after this change. */
+    styleClasses: readonly SplitButtonStyleClass[];
+    /** Whether the dropdown half is live (a menu model or a popover is set). */
+    dropdownEnabled: boolean;
+    /** Whether the menu is popped up. */
+    open: boolean;
+    /** The `notify::*` properties C emits for this one mutation, in emission order. */
+    notified: readonly SplitButtonProperty[];
+    /** True for a user gesture ({@link SplitButtonState.toggleMenu} / {@link SplitButtonState.activateMenuEntry}). */
+    interactive: boolean;
+}
+/** Subscriber for {@link SplitButtonState} changes. */
+export type SplitButtonListener = (change: SplitButtonChange) => void;
+/** The GTK state flags of one half of the control, as booleans. */
+export interface SplitButtonHalfState {
+    /** `GTK_STATE_FLAG_ACTIVE` — the half is pressed. */
+    active: boolean;
+    /** `GTK_STATE_FLAG_CHECKED` — for the arrow half, the menu is open. */
+    checked: boolean;
+    /** 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). */
+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.
+ */
+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).
+ *
+ * `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.
+ */
+export declare function resolveDropdownTooltip(tooltip: string): {
+    text: string;
+    markup: boolean;
+};
+/**
+ * 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`.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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`.
+ */
+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.
+ */
+export declare class SplitButtonState {
+    private _mode;
+    private _label;
+    private _iconName;
+    private _child;
+    private _useUnderline;
+    private _menuModel;
+    private _popover;
+    private _direction;
+    private _dropdownTooltip;
+    private _open;
+    private readonly _listeners;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: SplitButtonListener): () => void;
+    private _emit;
+    /** Which content slot is filled. */
+    get mode(): SplitButtonContentMode;
+    /** 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.
+     */
+    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.
+     */
+    setIconName(iconName: string): boolean;
+    /**
+     * The child widget: the app's own in `'child'` mode, the opaque internal
+     * content node in `'label'`/`'icon'` mode, `null` when empty.
+     */
+    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).
+     */
+    setChild(child: object | null | undefined): boolean;
+    /** The root style classes for the current content. */
+    get styleClasses(): readonly SplitButtonStyleClass[];
+    /** 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.
+     */
+    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.
+     *
+     * 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.
+     */
+    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.
+     */
+    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.
+     */
+    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. */
+    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
+     * {@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.
+     */
+    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). */
+    openMenu(): boolean;
+    /** Dismiss the menu programmatically — `adw_split_button_popdown` (:1076-1082). */
+    closeMenu(): boolean;
+    /** The dropdown half was activated by the user; flips the menu open/closed. */
+    toggleMenu(): boolean;
+    /**
+     * 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
+     * dismissed sheet.
+     */
+    activateMenuEntry(index: number): AdwMenuEntry | null;
+}

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

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