@gjsify/adwaita-core 0.30.0 → 0.32.0

package/lib/types/sidebar.d.ts

@@ -0,0 +1,308 @@
+/**
+ * The "no item is selected" index — the TS mirror of `GTK_INVALID_LIST_POSITION`
+ * (`adw_sidebar_init`, adw-sidebar.c:2862).
+ *
+ * libadwaita spells it `G_MAXUINT` because `AdwSidebar:selected` is a `guint`;
+ * `-1` is the idiomatic TS sentinel and, being `G_MAXUINT` mod 2^32, it makes
+ * {@link adjustSidebarSelection}'s arithmetic agree with the C code bit for bit.
+ */
+export declare const ADW_SIDEBAR_NO_SELECTION = -1;
+/**
+ * How a sidebar looks and behaves — `AdwSidebarMode` (adw-sidebar.h).
+ *
+ * `'sidebar'` is a flat navigation list with a persistent, VISIBLE selection;
+ * `'page'` is a page of boxed lists where "the selection is invisible and only
+ * tracked to determine the initially selected item once switched back"
+ * (adw-sidebar.c:2948-2951). The tracked index is identical in both.
+ */
+export type AdwSidebarMode = 'sidebar' | 'page';
+/** One selectable row — the value half of `AdwSidebarItem`. */
+export interface AdwSidebarItemSpec {
+    /** Row title. Defaults to `''` in libadwaita (adw-sidebar-item.c:419). */
+    title: string;
+    /** Optional second line. Absent and `''` are the same thing. */
+    subtitle?: string;
+    /** Symbolic icon name, e.g. `'folder-symbolic'`. Absent means no icon. */
+    iconName?: string;
+    /** Whether the row is rendered at all — bound to `row:visible` (adw-sidebar.c:1382). Default true. */
+    visible?: boolean;
+    /** Whether the row can be activated — bound to `row:sensitive` (adw-sidebar.c:1383). Default true. */
+    enabled?: boolean;
+}
+/**
+ * A titled group of rows — the value half of `AdwSidebarSection`.
+ *
+ * An absent or empty title selects the `'separator'` header instead of the
+ * `'title'` one (`update_header_page_cb`, adw-sidebar.c:1449-1455).
+ */
+export interface AdwSidebarSectionSpec {
+    /** Group heading. Absent/empty renders a separator instead. */
+    title?: string;
+    /** The group's rows, in order. */
+    items: readonly AdwSidebarItemSpec[];
+}
+/** One entry of the flattened item model. */
+export interface SidebarFlatItem {
+    /**
+     * The flat index `adw_sidebar_item_get_index` returns — the section's first
+     * index plus the local one (adw-sidebar-item.c:1040). It stays in the
+     * UNFILTERED space even when the item came out of a filtered walk, because
+     * libadwaita keeps the selection on `items_model` and the row list on
+     * `filtered_items` (adw-sidebar.c:2866, :2177-2180).
+     */
+    index: number;
+    /** Index of the owning section. */
+    sectionIndex: number;
+    /** Index of the item WITHIN its section (`adw_sidebar_item_get_section_index`). */
+    sectionItemIndex: number;
+    /** The item as declared — same object identity, so `selectedItem === spec` holds. */
+    item: AdwSidebarItemSpec;
+    /** `string_is_not_empty(title)` — the title label's visibility (adw-sidebar.c:1411-1412). */
+    titleVisible: boolean;
+    /** `string_is_not_empty(subtitle)` (adw-sidebar.c:1420-1421). */
+    subtitleVisible: boolean;
+    /** `notify_icon_cb`'s `icon_name && *icon_name` (adw-sidebar.c:1303). */
+    iconVisible: boolean;
+}
+/** The header libadwaita draws above one RENDERED section. */
+export interface SidebarHeaderSpec {
+    /** Index of the section this header belongs to. */
+    sectionIndex: number;
+    /** Which page of the header stack shows — `'title'` or `'separator'` (adw-sidebar.c:1449-1455). */
+    kind: 'title' | 'separator';
+    /** The section title (`''` for a separator header). */
+    title: string;
+    /** True only for the section owning the FIRST rendered row — the `.first` class (adw-sidebar.c:1526). */
+    first: boolean;
+}
+/** Payload of a `notify::selected` re-emit. */
+export interface SidebarSelectionChange {
+    /** The new selected index, or {@link ADW_SIDEBAR_NO_SELECTION}. */
+    selected: number;
+    /** The index it moved away from. */
+    previous: number;
+    /** `adw_sidebar_get_selected_item` — `undefined` when nothing is selected. */
+    item: AdwSidebarItemSpec | undefined;
+    /** True only for {@link SidebarState.activate} (a row click); false for programmatic changes. */
+    interactive: boolean;
+}
+/** Result of {@link SidebarState.activate}. */
+export interface SidebarActivation {
+    /** The index that was clicked, echoed back unchanged. */
+    index: number;
+    /**
+     * Whether a row was actually activated. False when `index` addresses no
+     * rendered, enabled row — libadwaita's callbacks run off an existing,
+     * sensitive `GtkListBoxRow`, so there is nothing to activate otherwise.
+     */
+    activated: boolean;
+    /** Whether the selection moved. `activated && !selectionChanged` is a re-click of the current row. */
+    selectionChanged: boolean;
+}
+/** Per-instance subscriber, same shape as `ComboStateListener` (rows.ts:114). */
+export type SidebarStateListener = (change: SidebarSelectionChange) => void;
+/**
+ * The TS stand-in for `GtkFilter` on `AdwSidebar:filter` (adw-sidebar.c:3127).
+ *
+ * Decides only what is RENDERED and whether the sidebar counts as empty — never
+ * the selection index space, which counts the unfiltered model.
+ */
+export type SidebarItemFilter = (item: AdwSidebarItemSpec, index: number) => boolean;
+/**
+ * The out-of-range rule, and the one all three implementations disagreed on:
+ * anything that is not a valid position becomes NO SELECTION — never the
+ * nearest in-range index.
+ *
+ * `adw_sidebar_set_selected` (adw-sidebar.c:3028-3029) is literally
+ * `if (selected >= self->n_items) selected = GTK_INVALID_LIST_POSITION;`. A
+ * negative input agrees with that for free: as a `guint`, `-7` is `4294967289`,
+ * which is `>= n_items` for any real sidebar.
+ *
+ * Non-integers and `NaN` are rejected rather than truncated. C cannot express
+ * them, so there is no ground truth to copy; rejecting is the reading that
+ * matches "not a valid position is no position", and it is what stops
+ * `sidebar.selected = 1.5` from leaving the NativeScript port highlighting no
+ * row while reporting a selection.
+ */
+export declare function clampSidebarSelection(index: number, count: number): number;
+/**
+ * Where the selection lands after the item model spliced — `items_changed_cb`
+ * (adw-sidebar.c:2246-2284), which neither renderer implemented.
+ *
+ * Four cases, in the C code's order:
+ *   1. `0 → n` auto-selects index 0 and notifies (adw-sidebar.c:2270-2273);
+ *   2. a splice covering the selected index clears it (adw-sidebar.c:2275-2278);
+ *   3. a splice at or before it shifts by `added - removed` (adw-sidebar.c:2280-2283);
+ *   4. a splice after it changes nothing.
+ *
+ * The comparisons run in the UNSIGNED domain (`>>> 0`) because that is where C
+ * runs them: with no selection, `selected` is `G_MAXUINT`, so case 2 can never
+ * fire and case 3 wraps. That wraparound is REPRODUCED, not repaired — inserting
+ * two items above a selection-less sidebar genuinely selects index 1 in GTK, and
+ * a renderer that "fixed" it would stop matching the toolkit it mirrors.
+ */
+export declare function adjustSidebarSelection(selected: number, oldCount: number, newCount: number, position: number, removed: number, added: number): number;
+/**
+ * Flatten the sections into the item model, the way `items_changed_cb`'s section
+ * walk does: `set_first_index (section, current); current += get_n_items (section)`
+ * (adw-sidebar.c:2261-2267).
+ *
+ * `sectionFirstIndex[i]` is `adw_sidebar_section_get_first_index` for section
+ * `i` — a zero-item section advances nothing, so it shares its successor's index.
+ *
+ * With a `filter`, `items` is the RENDERED subset while every `index` stays in
+ * the unfiltered space; `sectionFirstIndex` is likewise unfiltered.
+ */
+export declare function flattenSidebarItems(sections: readonly AdwSidebarSectionSpec[], filter?: SidebarItemFilter | null): {
+    items: SidebarFlatItem[];
+    sectionFirstIndex: number[];
+};
+/**
+ * The headers that actually get drawn, in render order.
+ *
+ * In sidebar mode a header is a property OF A ROW (`gtk_list_box_row_set_header`,
+ * adw-sidebar.c:1563), so a section with no rows contributes none; in page mode
+ * the group's `visible` is bound to `filtered n-items > 0` (adw-sidebar.c:1780-1781),
+ * which comes to the same thing. Either way it is the sections that RENDER
+ * something that produce headers — not the declared section list, which is what
+ * the web port used and why an empty leading section drew a stray separator.
+ *
+ * The section owning the first rendered row gets `first: true`; when that
+ * section has no title its header is bound to `string_is_not_empty(title)` and
+ * therefore invisible (adw-sidebar.c:1521-1527), so it is omitted entirely.
+ */
+export declare function sidebarHeaders(sections: readonly AdwSidebarSectionSpec[], filter?: SidebarItemFilter | null): SidebarHeaderSpec[];
+/**
+ * The sidebar state machine both renderers drive.
+ *
+ * Programmatic changes ({@link setSelected}, {@link setSections},
+ * {@link insertSection}, {@link removeSectionAt}, {@link removeAllSections})
+ * notify with `interactive: false`; {@link activate} — the row click — notifies
+ * with `interactive: true` and applies the selection BEFORE reporting the
+ * activation, matching GtkListBox's `row-selected`-then-`row-activated` order
+ * (adw-sidebar.c:2188-2191) and page mode's `set_selected`-then-emit
+ * (`boxed_row_activated_cb`, adw-sidebar.c:1672-1673).
+ */
+export declare class SidebarState {
+    private _mode;
+    private _sections;
+    private _filter;
+    private _selected;
+    private _items;
+    private _sectionFirstIndex;
+    private _visibleItems;
+    private _headers;
+    private readonly _listeners;
+    /** Subscribe to selection changes. Returns an unsubscribe function. */
+    subscribe(listener: SidebarStateListener): () => void;
+    private _emit;
+    /** Store an already-derived index; notify only on a real change (adw-sidebar.c:3031-3032). */
+    private _applySelected;
+    /** Recompute everything derived from `sections` + `filter`. */
+    private _invalidate;
+    /** The current look/behaviour. Defaults to `'sidebar'` (adw-sidebar.c:2860). */
+    get mode(): AdwSidebarMode;
+    /**
+     * Switch mode. Returns whether it changed — `adw_sidebar_set_mode` early-returns
+     * on the current value (adw-sidebar.c:2968-2969). Never touches the selection.
+     */
+    setMode(mode: AdwSidebarMode): boolean;
+    /**
+     * Whether the selection is PAINTED. Page mode tracks the selection but shows
+     * no selected row: its rows are plain `AdwActionRow`s in a boxed list
+     * (`create_boxed_row`, adw-sidebar.c:1676) and the mode is documented as
+     * "the selection is invisible, but still tracked" (adw-sidebar.c:2948-2951).
+     */
+    get selectionVisible(): boolean;
+    /** The declared sections. */
+    get sections(): readonly AdwSidebarSectionSpec[];
+    /**
+     * Replace every section at once — the renderers' "here is my whole tree" call.
+     *
+     * Equivalent to `adw_sidebar_remove_all()` followed by appending each section,
+     * i.e. two splices: everything removed (which clears the selection via
+     * adw-sidebar.c:2275-2278) and everything added (which re-runs the `0 → n`
+     * auto-select of index 0 at adw-sidebar.c:2270-2273). They are coalesced into
+     * ONE notification, because one property write should produce one change.
+     */
+    setSections(sections: readonly AdwSidebarSectionSpec[]): void;
+    /**
+     * Insert a section, returning the index it landed at.
+     *
+     * `adw_sidebar_insert` appends when `position` is negative OR at/past the end
+     * (adw-sidebar.c:3358-3364) — so on a two-section sidebar, positions `-1`,
+     * `2` and `5` all append, and position `2` is NOT an "insert at 2".
+     */
+    insertSection(section: AdwSidebarSectionSpec, position: number): number;
+    /**
+     * Remove the section at `index`. Returns false for an index that addresses no
+     * section — `adw_sidebar_remove` warns and returns when the section is not
+     * found (adw-sidebar.c:3387-3393), changing nothing.
+     */
+    removeSectionAt(index: number): boolean;
+    /** `adw_sidebar_remove_all` (adw-sidebar.c:3417) — one splice removing every item. */
+    removeAllSections(): void;
+    /**
+     * Re-derive the item model after an ITEM's own properties changed in place.
+     *
+     * libadwaita has no such call because it does not need one: title, subtitle
+     * and icon are live `g_object_bind_property` bindings straight onto the
+     * labels (adw-sidebar.c:1409-1421) and `notify::icon-name` goes to
+     * `notify_icon_cb` (:1393-1397) — none of them runs through
+     * `items_changed_cb`, so the selection cannot move. This method is the same
+     * contract for renderers that hand `SidebarState` mutable specs: the derived
+     * flags are recomputed, the selection is untouched, nothing is emitted.
+     * Both ports ignored post-construction item changes entirely.
+     */
+    refresh(): void;
+    /** `adw_sidebar_get_section` — `undefined` past the end (adw-sidebar.c:3297-3298). */
+    sectionAt(index: number): AdwSidebarSectionSpec | undefined;
+    /** `adw_sidebar_section_get_first_index` — 0 for a section that is not in this sidebar. */
+    sectionFirstIndex(sectionIndex: number): number;
+    /** Number of items in the UNFILTERED model — the selection index space (adw-sidebar.c:2255). */
+    get count(): number;
+    /** The full flattened item model, in flat-index order. */
+    get items(): readonly SidebarFlatItem[];
+    /** `adw_sidebar_get_item` — `undefined` for `index >= n_items` (adw-sidebar.c:3256). */
+    itemAt(index: number): AdwSidebarItemSpec | undefined;
+    /** The current item filter, or `null`. */
+    get filter(): SidebarItemFilter | null;
+    /**
+     * Set the item filter — `adw_sidebar_set_filter` (adw-sidebar.c:3127-3139).
+     *
+     * It only swaps the filter on the `GtkFilterListModel`; the selection is
+     * never re-derived, so a selected item that filters out stays selected.
+     */
+    setFilter(filter: SidebarItemFilter | null): void;
+    /** The items that pass the filter — the rows a renderer actually builds. */
+    get visibleItems(): readonly SidebarFlatItem[];
+    /** The headers to draw, derived from the sections that render at least one row. */
+    get headers(): readonly SidebarHeaderSpec[];
+    /**
+     * The `.empty` / placeholder state — `update_placeholder` counts the FILTERED
+     * model (adw-sidebar.c:1828, :1839-1842), so a fully filtered-out sidebar is
+     * empty even though its selection index space is not.
+     */
+    get isEmpty(): boolean;
+    /** The selected flat index, or {@link ADW_SIDEBAR_NO_SELECTION}. */
+    get selected(): number;
+    /** `adw_sidebar_get_selected_item` (adw-sidebar.c:3092). */
+    get selectedItem(): AdwSidebarItemSpec | undefined;
+    /**
+     * Programmatic selection — {@link clampSidebarSelection} then notify with
+     * `interactive: false`. Returns whether it changed.
+     */
+    setSelected(index: number): boolean;
+    /**
+     * A row click. Selects (notifying `interactive: true` if that moved) and then
+     * reports the activation, which libadwaita emits on EVERY click including a
+     * re-click of the already-selected row (`row_activated_cb`, adw-sidebar.c:1601-1612).
+     * That unconditional emit is how re-tapping the current row reveals the content
+     * pane of a split view (adw-sidebar.c:73-75) — the NativeScript port had no
+     * activation path at all, so that gesture did nothing there.
+     *
+     * A row that is filtered out, `visible: false`, or `enabled: false` is not
+     * activatable: it either has no `GtkListBoxRow` or has an insensitive one.
+     */
+    activate(index: number): SidebarActivation;
+}

package/lib/types/sidebar.spec.d.ts

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

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;