@gjsify/adwaita-core 0.54.0 → 0.56.0

package/lib/types/list-view.d.ts

@@ -0,0 +1,276 @@
+import type { DataGridTrack } from './data-grid.js';
+import { type AdwComboOption, type AdwListItemsChanged } from './list.js';
+/**
+ * Which `Gtk.SelectionModel` wraps the view's model, as a WORD.
+ *
+ * GTK composes the three — `Gtk.NoSelection`, `Gtk.SingleSelection`, `Gtk.MultiSelection`
+ * — around a `Gio.ListModel` and hands the result to `GtkListView:model`. ADR 0046
+ * declined that layering as a portable VALUE and ADR 0089 keeps the declination, so what
+ * crosses here is the choice rather than the wrapper: one of three nicks, on the widget.
+ *
+ * `single` is the default because it is the one a `Gtk.ListView` is built with in every
+ * upstream example, and because a view that answers no click at all is the surprising one.
+ */
+export type AdwListSelectionMode = 'none' | 'single' | 'multiple';
+/** An unknown mode is `single`, the way an unknown enum nick falls back to a default. */
+export declare function normalizeListSelectionMode(raw: unknown): AdwListSelectionMode;
+/**
+ * What a factory is handed for ONE item — `GtkListItem`'s three readable properties that
+ * a renderer actually binds against (`item`, `position`, `selected`).
+ *
+ * `GtkListItem` carries five more (`activatable`, `focusable`, `selectable`, `child`, and
+ * the two accessible strings). They are the LIST's business rather than the item's
+ * content: the view decides whether a row can be activated, so making them inputs to the
+ * factory would offer a per-item answer the view then overrides.
+ */
+export interface AdwListItemContext {
+    /** The model item at {@link position}. */
+    readonly item: AdwComboOption;
+    /** Where the item sits in the model. */
+    readonly position: number;
+    /** Whether the view has this position selected. */
+    readonly selected: boolean;
+}
+/**
+ * `GtkSignalListItemFactory`'s `setup` + `bind`, as one call.
+ *
+ * GTK keeps them apart because it RECYCLES row widgets while scrolling: setup builds,
+ * bind refills, and a view of ten thousand items holds two hundred widgets. This port
+ * builds a node per item and splices ({@link ListViewState}), so there is nothing to
+ * recycle and nothing for the split to buy — and a factory that is one function is a
+ * factory an author can write inline.
+ *
+ * Generic in the node so the seam is not a DOM one: `@gjsify/adwaita-web` instantiates it
+ * at `Node`, and a renderer with another node type takes the same interface.
+ */
+export type AdwListItemFactory<TNode> = (context: AdwListItemContext) => TNode;
+/** One positional selection, normalised: ascending, no duplicates. */
+export type AdwListSelection = readonly number[];
+/** What a click (or a Space press) on a row means, in `gtk_list_base_select_item`'s words. */
+export interface AdwListSelectStep {
+    /** `<Ctrl>` — toggle this row rather than replacing the selection. */
+    readonly modify?: boolean;
+    /** `<Shift>` — extend from the anchor to this row. */
+    readonly extend?: boolean;
+}
+/** The selection plus the position a later `extend` measures from. */
+export interface AdwListSelectResult {
+    /** The next selection, ascending. */
+    readonly selection: number[];
+    /** Where the next `extend` starts — GTK's `priv->selected` tracker. */
+    readonly anchor: number;
+}
+/**
+ * One click on row `position` → the selection that follows it.
+ *
+ * This is `gtk_list_base_select_item` (gtklistbase.c:374-446) with the selection model's
+ * answer folded in, because on this surface the two are not separable: GTK asks the model
+ * and falls back when it says no, and the three models say different things.
+ *
+ * The C, step for step:
+ *
+ *   · a position outside the model is ignored — `pos >= n_items` returns early;
+ *   · `extend` asks the model for a RANGE from the anchor. With `modify` the range takes
+ *     the anchor's own state (select the span if the anchor is selected, unselect it
+ *     otherwise); without, it is a plain `select_range(…, TRUE)` — unselect the rest;
+ *   · a range the model refuses falls THROUGH to the single-item path, which is why
+ *     Shift+click in single mode just moves the selection rather than doing nothing:
+ *     `GtkSingleSelection` has no `select_range`;
+ *   · `modify` alone toggles — except that `gtk_single_selection_unselect_item` refuses
+ *     while `autoselect` is on (gtksingleselection.c:160-173, and `autoselect` defaults
+ *     TRUE), so Ctrl+click on the SELECTED row in single mode leaves it selected;
+ *   · plain click selects exclusively;
+ *   · and the anchor moves to `pos` in every case the function does not return early
+ *     from — it is the last statement of the function, after the range branch.
+ *
+ * `none` answers every step with the empty selection: `GtkNoSelection` implements the
+ * interface by returning FALSE from each of the four mutators.
+ */
+export declare function listViewSelect(selection: AdwListSelection, anchor: number, position: number, length: number, mode: AdwListSelectionMode, step?: AdwListSelectStep): AdwListSelectResult;
+/** `list.select-all` — refused by every model but `GtkMultiSelection`. */
+export declare function listViewSelectAll(length: number, mode: AdwListSelectionMode): number[];
+/** A selection subscriber — the positions, and whether a USER produced them. */
+export type ListViewSelectionListener = (change: ListViewSelectionChange) => void;
+/** What a selection subscriber is handed. */
+export interface ListViewSelectionChange {
+    /** The selected positions, ascending. */
+    readonly selection: AdwListSelection;
+    /** False for a programmatic write, the way `ComboStateChange.interactive` reads. */
+    readonly interactive: boolean;
+}
+/** An items subscriber — one `Gio.ListModel::items-changed` per model assignment. */
+export type ListViewItemsListener = (change: AdwListItemsChanged) => void;
+/**
+ * The model + selection a view holds — headless (ADR 0004, ADR 0089).
+ *
+ * `ComboState` is the same shape one widget over and is NOT reused: it holds ONE index
+ * because `Adw.ComboRow:selected` is one `guint`, and widening it to a set would put a
+ * multi-selection vocabulary on a widget that has none. What the two DO share is already
+ * shared — the item vocabulary, the splice, and the autoselect clamp all live in
+ * `list.ts` and both classes call them.
+ *
+ * THE MODEL IS COPIED IN BOTH DIRECTIONS, for the reason ADR 0046 § 3 measured on
+ * `ComboState`: the splice is computed by COMPARING the assigned model against the stored
+ * one, so a shared array or a shared item makes both sides read the new value and answer
+ * "nothing changed" — silently, because there is nothing to throw.
+ */
+export declare class ListViewState {
+    private _model;
+    private _selection;
+    private _anchor;
+    private _mode;
+    private readonly _itemListeners;
+    private readonly _selectionListeners;
+    /** Subscribe to MODEL changes — one splice per {@link setModel}. Returns an unsubscribe. */
+    subscribeItems(listener: ListViewItemsListener): () => void;
+    /** Subscribe to SELECTION changes. Returns an unsubscribe. */
+    subscribeSelection(listener: ListViewSelectionListener): () => void;
+    /** The list model, as a COPY — see the class header. */
+    get model(): AdwComboOption[];
+    /** How many items the model holds (`g_list_model_get_n_items`). */
+    get count(): number;
+    /** The selected positions, ascending, as a copy. */
+    get selection(): number[];
+    /** Which selection model the view behaves as. */
+    get selectionMode(): AdwListSelectionMode;
+    /**
+     * Replace the model: emit the splice that turns the old one into the new, then drop
+     * any selected position the new model does not have.
+     *
+     * A VIEW DOES NOT AUTOSELECT, and that is the one place this class deliberately
+     * differs from `ComboState`. `clampListSelection` is `GtkSingleSelection`'s
+     * `autoselect`, which exists so a combo row always has a value to SHOW; a list view
+     * has no inline value and GTK's own `GtkMultiSelection` keeps nothing selected after
+     * a model it cannot map. So positions are filtered, not clamped.
+     */
+    setModel(model: readonly AdwComboOption[] | null | undefined): void;
+    /** `Gtk.SelectionModel` choice. Narrowing it drops what the new mode cannot hold. */
+    setSelectionMode(mode: AdwListSelectionMode): void;
+    /** Whether `position` is selected. */
+    isSelected(position: number): boolean;
+    /**
+     * One click or Space on `position` — {@link listViewSelect} applied to this state.
+     *
+     * Returns whether the selection CHANGED, which is what gates a notify: the anchor
+     * moves on every accepted step and is not itself observable, so reporting it would
+     * make a repeat click on one row look like a selection change.
+     */
+    selectItem(position: number, step?: AdwListSelectStep, interactive?: boolean): boolean;
+    /** `list.select-all`. */
+    selectAll(interactive?: boolean): boolean;
+    /** `list.unselect-all`. */
+    unselectAll(interactive?: boolean): boolean;
+    /** Programmatic assignment — out-of-range positions are dropped, as a model replacement drops them. */
+    setSelection(positions: Iterable<number>, interactive?: boolean): boolean;
+    /** The context a factory is handed for `position`, or null past the end of the model. */
+    itemContext(position: number): AdwListItemContext | null;
+    private _applySelection;
+    private _emitSelection;
+}
+/** `GtkGridView:max-columns`' default — `DEFAULT_MAX_COLUMNS` (gtkgridview.c:42). */
+export declare const ADW_GRID_VIEW_MAX_COLUMNS = 7;
+/** `GtkGridView:min-columns`' default — the ParamSpec's own (gtkgridview.c:1164-1167). */
+export declare const ADW_GRID_VIEW_MIN_COLUMNS = 1;
+/**
+ * How many columns a grid lays out in `forSize` pixels — `gtk_grid_view_compute_n_columns`
+ * (gtkgridview.c:619-641).
+ *
+ * The arithmetic is upstream's, including the `+ spacing` on both sides, which is what
+ * makes the LAST column need no trailing gap, and the integer division, which the C calls
+ * out as deliberate ("rounding down is exactly what we want here").
+ *
+ * `MAX (1, …)` in the denominator is kept: an item that measures zero would otherwise
+ * divide by zero, and the C asserts the result is positive.
+ *
+ * The clamp order is `CLAMP (n, min, max)` as written, so `max < min` answers `min` for a
+ * narrow view and `max` for a wide one — the asymmetry the property's own documentation
+ * describes from one side only ("if this number is smaller than min-columns, that value is
+ * used instead", gtkgridview.c:1147-1157).
+ */
+export declare function gridViewColumns(forSize: number, itemSize: number, spacing: number, minColumns?: number, maxColumns?: number): number;
+/**
+ * Which half of a portable item a column draws, for a column that declares no factory.
+ *
+ * A `GtkColumnViewColumn` has no such property: upstream a column draws whatever its
+ * FACTORY pulls off the item, and the item is an arbitrary GObject. A portable item is
+ * `AdwComboOption` — `value` and `label`, and nothing else by contract (ADR 0046 § 2) —
+ * so a column that wants to draw without a factory has exactly these two choices, and
+ * `key` is the declarative door onto them. Anything else is a `factory`, which is the
+ * same thing GTK requires of every column.
+ */
+export type AdwListItemField = 'label' | 'value';
+/** `item[field]`, with the field clamped — the one place a column's `key` is resolved. */
+export declare function listItemField(item: AdwComboOption, field: AdwListItemField): string;
+/**
+ * One `Gtk.ColumnViewColumn`, in plain data.
+ *
+ * Every other member IS a GTK property; `key` is the exception and {@link AdwListItemField}
+ * says why. `id` is kept beside it rather than derived from it because it is a real
+ * property with a different job — it is what `Gtk.ColumnView` persists a column layout by
+ * — and because two columns over the same field are a legitimate thing to author.
+ */
+export interface AdwColumnViewColumn {
+    /** Which portable field this column draws when it has no factory. */
+    key: AdwListItemField;
+    /** `Gtk.ColumnViewColumn:title` — the header text. Defaults to {@link key}. */
+    title?: string;
+    /** `Gtk.ColumnViewColumn:id`. Defaults to {@link key}. */
+    id?: string;
+    /** `Gtk.ColumnViewColumn:expand` — take a share of the extra width. */
+    expand?: boolean;
+    /** `Gtk.ColumnViewColumn:fixed-width`, in pixels. `-1` is "not fixed", as in C. */
+    fixedWidth?: number;
+    /** `Gtk.ColumnViewColumn:visible`. */
+    visible?: boolean;
+    /** Whether the header sorts — the portable stand-in for a non-null `Gtk.Sorter`. */
+    sortable?: boolean;
+}
+/** Which column a column view is sorted by, and in which direction. */
+export interface AdwColumnViewSort {
+    /** The sorted column's {@link AdwColumnViewColumn.id}. */
+    readonly column: string;
+    /** `Gtk.SortType.DESCENDING` — the sorter's `inverted` flag. */
+    readonly descending: boolean;
+}
+/** `fixed-width`'s "no fixed width" sentinel (`gtk_column_view_column_set_fixed_width`). */
+export declare const ADW_COLUMN_VIEW_NO_FIXED_WIDTH = -1;
+/**
+ * Raw authored columns → stable descriptors. TOTAL, for the reason
+ * `normalizeComboOptions` is: the doors it reaches are a property assignment and a markup
+ * attribute, and an author's typo must not take the widget down.
+ *
+ * An entry with no `key` is DROPPED rather than defaulted — a column that draws no field
+ * is an empty strip a reader cannot tell from a layout bug, and `normalizeDataGridColumns`
+ * answers the identical input the identical way.
+ */
+export declare function normalizeColumnViewColumns(raw: unknown): AdwColumnViewColumn[];
+/** The MARKUP door: a JSON attribute → normalised columns. Total in both failure modes. */
+export declare function parseColumnViewColumns(raw: string | null | undefined): AdwColumnViewColumn[];
+/**
+ * A click on a sortable header → the sort that follows it —
+ * `gtk_column_view_sorter_add_column` (gtkcolumnviewsorter.c:294-344).
+ *
+ * The rule is two lines of that function: if the clicked column is ALREADY the primary
+ * sorter, `inverted` flips; otherwise the column becomes primary, ascending. A column
+ * with no sorter is refused (`sorter == NULL` returns FALSE), which is what `sortable`
+ * stands in for here.
+ *
+ * The secondary sorters upstream keeps in a sequence are not modelled: they are reachable
+ * only through `GtkColumnViewSorter`'s own API, never through a header click, and a
+ * portable multi-key sort would need the comparators this surface does not carry.
+ */
+export declare function columnViewSort(current: AdwColumnViewSort | null, column: AdwColumnViewColumn): AdwColumnViewSort | null;
+/**
+ * The column tracks a column view lays out — in `data-grid.ts`'s renderer-neutral
+ * {@link DataGridTrack}, reused rather than restated.
+ *
+ * The two widgets answer the SAME question (which track is pinned, which absorbs the
+ * slack) from two property names, and `AdwDataGrid` is where that vocabulary already
+ * lives. What differs is only the mapping: `fixed-width` is a pixel number rather than a
+ * CSS length, and `expand` is a boolean share rather than a weight — GTK divides the extra
+ * width evenly among the expanding columns, so every one of them is `1fr`.
+ *
+ * A view with NO expanding column gets `auto` throughout, which leaves the trailing space
+ * unclaimed exactly as `gtk_column_view_measure` does.
+ */
+export declare function columnViewTracks(columns: readonly AdwColumnViewColumn[]): DataGridTrack[];

package/lib/types/list-view.spec.d.ts

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

package/lib/types/sidebar.d.ts

@@ -26,6 +26,15 @@ export interface AdwSidebarItemSpec {
     visible?: boolean;
     /** Whether the row can be activated — bound to `row:sensitive`. Default true. */
     enabled?: boolean;
+    /**
+     * The row's INDICATOR — `AdwSidebarItem`'s suffix bin as `AdwViewSwitcherSidebar`
+     * drives it (`update_badge`, adw-view-switcher-sidebar.c:133-181). `libadwaita`'s own
+     * sidebar leaves the suffix alone; the switcher sidebar puts an unread dot or a badge
+     * count there, and `Adw.Sidebar` itself never does.
+     */
+    badgeNumber?: number;
+    /** Whether that indicator is drawn in the attention colour (`.needs-attention`). */
+    needsAttention?: boolean;
 }
 /**
  * A titled group of rows — the value half of `AdwSidebarSection`.

package/lib/types/tab-view.d.ts

@@ -22,6 +22,12 @@ export interface AdwTabPageSpec<T = unknown> {
     title?: string | null;
     /** Tooltip; falls back to the title when empty ({@link tabTooltip}). */
     tooltip?: string | null;
+    /**
+     * `AdwTabPage:keyword` — the string the tab overview's SEARCH matches on besides the
+     * title and the tooltip ("Use keywords to search in e.g. page URLs in a web browser",
+     * adw-tab-overview.c:1646-1648).
+     */
+    keyword?: string | null;
     /** GTK icon name shown in the tab, or `null` for none. */
     icon?: string | null;
     /** Icon shown in the indicator slot (`AdwTabPage:indicator-icon`), or `null`. */
@@ -44,6 +50,8 @@ export interface AdwTabPageState<T = unknown> {
     readonly title: string;
     /** Tooltip, already coerced from `null` to `''`. Empty means "use the title". */
     readonly tooltip: string;
+    /** `AdwTabPage:keyword` — the search term beside the title and tooltip ({@link tabSearchMatches}). */
+    readonly keyword: string;
     /** GTK icon name, or `null` when the page has none. */
     readonly icon: string | null;
     readonly indicatorIcon: string | null;
@@ -208,6 +216,23 @@ export declare function tabTooltip(page: Pick<AdwTabPageState, 'tooltip' | 'titl
  * one that escaped the title would show the escapes.
  */
 export declare function tabTooltipIsMarkup(page: Pick<AdwTabPageState, 'tooltip'>): boolean;
+/**
+ * Whether a page SURVIVES the tab overview's search terms — the predicate behind
+ * `AdwTabGrid`'s three `GtkStringFilter`s (adw-tab-grid.c:3532-3539: a property
+ * expression over `title`, `tooltip` and `keyword`, combined with a `GtkMultiFilter`,
+ * which is a logical AND of the three).
+ *
+ * `GtkStringFilter`'s defaults decide the rest (gtkstringfilter.c:276,297): match mode
+ * SUBSTRING and case folding ON, with both sides run through `g_utf8_normalize` first.
+ * An EMPTY property never matches — `gtk_string_filter_prepare` returns NULL for it
+ * (:76-77) — which is why a page with no tooltip does not match every term, and an
+ * EMPTY term set matches everything (`has_search`, :93-98).
+ *
+ * The DOM has neither `g_utf8_normalize` nor full case folding. `String.normalize('NFKC')`
+ * is the same normalisation step and `toLocaleLowerCase()` the case folding for the
+ * scripts this gallery ships; the search therefore matches the C rule, not a locale's.
+ */
+export declare function tabSearchMatches(page: Pick<AdwTabPageState, 'title' | 'tooltip' | 'keyword'>, terms: string): boolean;
 /**
  * What a tab paints in its icon + indicator slots (`update_icons`).
  *
@@ -551,6 +576,8 @@ export declare class TabViewState<T = unknown> {
     setPageTitle(id: string, title: string | null): boolean;
     /** Set a page's tooltip; `null` becomes `''`. */
     setPageTooltip(id: string, tooltip: string | null): boolean;
+    /** Set a page's search keyword; `null` becomes `''` (`adw_tab_page_set_keyword`). */
+    setPageKeyword(id: string, keyword: string | null): boolean;
     /** Set a page's icon name, `null` for none (`adw_tab_page_set_icon`). */
     setPageIcon(id: string, icon: string | null): boolean;
     /** Set a page's indicator icon, `null` for none. */

package/lib/types/tags.d.ts

@@ -37,7 +37,7 @@ export declare const attributeOf: (prop: string) => string;
  */
 export declare const propertyOf: (name: string) => string;
 /**
- * `GtkWidget`'s four margins, as the CSS property each one is — `start`/`end` the LOGICAL
+ * `GtkWidget`'s four margins, as the CSS property each is — `start`/`end` the LOGICAL
  * edges `gtk_widget_set_margin_start` documents, `top`/`bottom` physical as in GTK.
  *
  * A markup renderer writes them as inline style, because an attribute cannot carry a length
@@ -46,3 +46,45 @@ export declare const propertyOf: (name: string) => string;
  * `./markup.ts`, whose markup has to parse back to exactly what that builder made.
  */
 export declare const GTK_WIDGET_MARGIN_CSS: Readonly<Record<string, string>>;
+/**
+ * `GtkWidget:hexpand` / `vexpand`, the two booleans whose `false` is an AUTHORED answer: the
+ * attribute's absence says "not written", and a widget that expands by default
+ * (`<gtk-scrolled-window>`) needs the author's `false` to stop. A renderer writes `true` as
+ * the bare attribute and `false` as `hexpand="false"`, which the stylesheet reads.
+ */
+export declare const GTK_WIDGET_EXPAND: readonly ["hexpand", "vexpand"];
+/**
+ * `GtkWidget:width-request` / `height-request`, as the CSS minimum each one is. A size request
+ * is a MINIMUM in GTK (`gtk_widget_set_size_request`: the widget is never measured below it,
+ * and its natural size still wins when larger), so `min-*` is the same sentence and `width`
+ * would claim an exactness GTK does not give. -1 is the pspec's "not set".
+ */
+export declare const GTK_WIDGET_SIZE_CSS: Readonly<Record<string, string>>;
+/**
+ * The inline-style declaration an authored GtkWidget length property stands for, or
+ * `undefined` when `attribute` is not one. `null` is a size request of -1: the author said
+ * "unset", so nothing is written (and an earlier value is to be cleared).
+ */
+export declare function widgetLengthStyle(attribute: string, value: string | number | boolean): readonly [property: string, length: string | null] | undefined;
+/**
+ * Kebab-case attribute names of GTK boolean properties that default to TRUE.
+ * These are VALUE-BASED: `attr="false"` means false, absent means true (the default).
+ * Style classes like `flat`/`round`/`compact` are PRESENCE-BASED and NOT in this set.
+ * ADR 0049, ADR 0034 own the presence vs. value split.
+ *
+ * @deprecated Use {@link isValueBasedBooleanAttr} instead. This flat set cannot express
+ *   that the same attribute name (e.g. `revealed`) is value-based for one widget
+ *   (`gtk-action-bar`) but presence-based for another (`adw-banner`).
+ */
+export declare const VALUE_BASED_BOOLEAN_ATTRS: Set<string>;
+/**
+ * Whether the given attribute on the given widget tag is VALUE-BASED.
+ *
+ * Value-based means: `attr="false"` spells false, absent spells the default (TRUE).
+ * Presence-based means: the attribute's PRESENCE spells true, absence spells false.
+ *
+ * @param tagName The element's tag name (e.g. `adw-banner`, `gtk-action-bar`).
+ * @param attrName The kebab-case attribute name (e.g. `revealed`, `can-pop`).
+ * @returns True if the attribute should be written as `attr="true"|"false"`.
+ */
+export declare function isValueBasedBooleanAttr(tagName: string, attrName: string): boolean;

package/lib/types/tree-expander.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a `Gtk.TreeListRow` tells the expander — depth, expandability, expanded state.
+ *
+ * `gtk_tree_list_row_get_depth` is 0 for a root row, so a three-level tree runs 0, 1, 2 —
+ * and `is_expandable` is independent of `expanded`: a collapsed row whose children the
+ * model has not built yet is still expandable.
+ */
+export interface AdwTreeExpanderRow {
+    /** `gtk_tree_list_row_get_depth` — 0 at the root. */
+    readonly depth: number;
+    /** `gtk_tree_list_row_is_expandable`. */
+    readonly expandable: boolean;
+    /** `Gtk.TreeListRow:expanded`. */
+    readonly expanded: boolean;
+}
+/** The three properties that shape the expander, in GTK's own defaults. */
+export interface AdwTreeExpanderOptions {
+    /** `Gtk.TreeExpander:hide-expander` — default FALSE. */
+    readonly hideExpander?: boolean;
+    /** `Gtk.TreeExpander:indent-for-depth` — default TRUE (gtktreeexpander.c:750). */
+    readonly indentForDepth?: boolean;
+    /** `Gtk.TreeExpander:indent-for-icon` — default TRUE (gtktreeexpander.c:749). */
+    readonly indentForIcon?: boolean;
+}
+/** What the expander node is, when there is one. */
+export type AdwTreeExpanderIcon = 'none' | 'collapsed' | 'expanded';
+/** The subtree one expander draws, as counts rather than nodes. */
+export interface AdwTreeExpanderLayout {
+    /** How many `indent` nodes precede the expander/child. */
+    readonly indents: number;
+    /** The `expander` node's state — `none` when the row draws no expander at all. */
+    readonly expander: AdwTreeExpanderIcon;
+    /** `GTK_ACCESSIBLE_PROPERTY_LEVEL`, which "is >= 1" (gtktreeexpander.c:264). */
+    readonly level: number;
+}
+/**
+ * The nodes one expander draws — `gtk_tree_expander_update_for_list_row`
+ * (gtktreeexpander.c:166-265), as a pure function.
+ *
+ * Read off the C in its own order, because the order is where the subtlety is:
+ *
+ *   1. `depth = indent_for_depth ? row.depth : 0`. Turning the property off does not hide
+ *      the expander, it only stops the INDENT growing with the level;
+ *   2. an expander node exists when the row `is_expandable` AND `hide-expander` is off,
+ *      and carries `:checked` when the row is expanded — which is also the
+ *      `aria-expanded` state;
+ *   3. with NO expander, `indent_for_icon` adds ONE to the depth, so a leaf lines up with
+ *      its expandable siblings' content instead of sitting an icon-width to their left.
+ *      It is the only place the count differs from the level, and it applies to a
+ *      hide-expander row as much as to a leaf;
+ *   4. `level` is `depth + 1` and is computed AFTER that increment, so a leaf at depth 0
+ *      with `indent-for-icon` on reports level 2. That is upstream's arithmetic, not a
+ *      transcription slip: the C writes `depth + 1` at the end of the same block.
+ *
+ * A null row is `EMPTY_LAYOUT`: GTK unparents every indent and the expander, leaving the
+ * child alone, and resets the expanded state.
+ */
+export declare function treeExpanderLayout(row: AdwTreeExpanderRow | null | undefined, options?: AdwTreeExpanderOptions): AdwTreeExpanderLayout;
+/** What a key press on an expander asks for. */
+export type AdwTreeExpanderAction = 'expand' | 'collapse' | 'toggle' | 'none';
+/** The modifier state a shortcut is read against. */
+export interface AdwTreeExpanderKeyState {
+    /** `GDK_CONTROL_MASK`. */
+    readonly ctrlKey?: boolean;
+    /** `GDK_SHIFT_MASK`. */
+    readonly shiftKey?: boolean;
+    /** Right-to-left text direction, which swaps the two arrows. */
+    readonly rtl?: boolean;
+}
+/**
+ * One key press → the `listitem.*` action it maps to (gtktreeexpander.c:654-691).
+ *
+ * `+` and `*` expand, `-` and `/` collapse, Ctrl+Space toggles; the arrows expand or
+ * collapse with Shift or Ctrl+Shift, in the direction the locale reads
+ * (`expand_collapse_right` is EXPAND in LTR). The keypad duplicates upstream declares
+ * (`KP_Add`, `KP_Multiply`, …) need no entry: a browser reports the same `key` value for
+ * a keypad `+` as for the main one, and distinguishing them would need `code`.
+ *
+ * Backspace — "go to parent row" — is `#if 0` in the C and is therefore not here either.
+ */
+export declare function treeExpanderAction(key: string, state?: AdwTreeExpanderKeyState): AdwTreeExpanderAction;
+/** Apply an action to an expanded flag — `listitem.expand`/`collapse`/`toggle-expand`. */
+export declare function treeExpanderExpanded(expanded: boolean, action: AdwTreeExpanderAction): boolean;

package/lib/types/tree-expander.spec.d.ts

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

package/lib/types/view-stack.d.ts

@@ -22,6 +22,13 @@ export interface AdwViewStackPageSpec<T = unknown> {
     needsAttention?: boolean;
     /** `AdwViewStackPage:use-underline`. Defaults to `false`. */
     useUnderline?: boolean;
+    /**
+     * `AdwViewStackPage:starts-section` — the page opens a NEW section, which is what
+     * `AdwViewSwitcherSidebar` groups on (`populate_sidebar`, adw-view-switcher-sidebar.c:225-243).
+     */
+    startsSection?: boolean;
+    /** `AdwViewStackPage:section-title` — the heading of the section this page opens. */
+    sectionTitle?: string | null;
 }
 /**
  * A resolved page descriptor, as a bound switcher reads it. `title` and `icon` are
@@ -46,6 +53,10 @@ export interface AdwViewStackPageInfo<T = unknown> {
     readonly needsAttention: boolean;
     /** `AdwViewStackPage:use-underline` — whether the title carries a mnemonic. */
     readonly useUnderline: boolean;
+    /** `AdwViewStackPage:starts-section` — whether this page opens a new section. */
+    readonly startsSection: boolean;
+    /** `AdwViewStackPage:section-title`, `''` when the page declares none. */
+    readonly sectionTitle: string;
 }
 /** Payload of a selection change. */
 export interface ViewStackStateChange<T = unknown> {

package/lib/types/view-switcher.d.ts

@@ -70,6 +70,13 @@ export interface AdwViewSwitcherPage {
     badgeNumber: number;
     /** `AdwViewStackPage:needs-attention` — default `false`, i.e. no dot. */
     needsAttention: boolean;
+    /**
+     * `AdwViewStackPage:starts-section` — default `false`. Only
+     * {@link viewSwitcherSidebarSections} reads it; every other switcher is flat.
+     */
+    startsSection: boolean;
+    /** `AdwViewStackPage:section-title` — the heading of the section the page opens. */
+    sectionTitle: string | null;
 }
 /** What a caller has to supply for a page: the name, plus whatever it knows. */
 export interface AdwViewSwitcherPageInit extends Partial<AdwViewSwitcherPage> {
@@ -92,6 +99,27 @@ export declare function createViewSwitcherPage(init: AdwViewSwitcherPageInit): A
 export declare function viewSwitcherPageFromStackPage(page: AdwViewStackPageInfo): AdwViewSwitcherPage;
 /** {@link viewSwitcherPageFromStackPage} over a whole page list. */
 export declare function viewSwitcherPagesFromStack(pages: readonly AdwViewStackPageInfo[]): AdwViewSwitcherPage[];
+/** One section of a {@link viewSwitcherSidebarSections} grouping. */
+export interface ViewSwitcherSidebarSection {
+    /** `AdwViewStackPage:section-title` of the page that OPENED the section. */
+    readonly title: string;
+    /** The pages in it, in stack order. Never empty — C only appends a section it filled. */
+    readonly pages: readonly AdwViewSwitcherPage[];
+}
+/**
+ * `populate_sidebar` (adw-view-switcher-sidebar.c:225-243), which is the ONE thing that
+ * makes `AdwViewSwitcherSidebar` a switcher: every other Adw switcher is one flat row of
+ * buttons, and this one groups a stack's pages into `AdwSidebarSection`s.
+ *
+ * Two rules, both of them C:
+ *   · a page with `starts-section` OPENS a section; the page BEFORE it is flushed first,
+ *     and the FIRST page opens one whatever it says — the `!section` test is C's own
+ *     (`if (!section || adw_view_stack_page_get_starts_section (page))`, :232);
+ *   · the heading is the opening page's `section-title`, bound with `G_BINDING_SYNC_CREATE`
+ *     (:237), so a page that opens a section WITHOUT a title gets the separator header —
+ *     the same empty-title rule `AdwSidebar`'s own sections follow.
+ */
+export declare function viewSwitcherSidebarSections(pages: readonly AdwViewSwitcherPage[]): ViewSwitcherSidebarSection[];
 /**
  * `update_button`'s visibility rule: `visible && (title != NULL || icon_name != NULL)`.
  * The empty string is NOT NULL, so `title: ''` still yields a button; `undefined` is read

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.54.0",
+    "version": "0.56.0",
     "description": "Headless Adwaita widget behavior (breakpoint condition grammar + apply/unapply state machine, color-scheme observable, avatar derivation) shared by the web and NativeScript Adwaita renderers — pure TS, no platform imports",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -58,8 +58,8 @@
         "headless"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.54.0",
-        "@gjsify/unit": "^0.54.0",
+        "@gjsify/cli": "^0.56.0",
+        "@gjsify/unit": "^0.56.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },