@gjsify/adwaita-core 0.31.0 → 0.33.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/spinner.d.ts

@@ -0,0 +1,117 @@
+/** `SPIN_DURATION_MS` (adw-spinner-paintable.c:20) — one full turn. */
+export declare const ADW_SPINNER_SPIN_DURATION_MS = 1200;
+/**
+ * `START_ANGLE` (adw-spinner-paintable.c:21) — a fixed phase offset added to
+ * both arc ends (:379-380), so the figure does not start at 3 o'clock.
+ *
+ * Neither port had it, which is a constant rotation error rather than a wrong
+ * speed — invisible in a still frame, visible against a GTK spinner beside it.
+ */
+export declare const ADW_SPINNER_START_ANGLE: number;
+/**
+ * `CIRCLE_OPACITY` (adw-spinner-paintable.c:22) — the track is the WIDGET's
+ * colour at 15%, not a hardcoded grey.
+ *
+ * The browser port used `rgba(127, 127, 127, 0.25)`: too dark, and
+ * hue-independent, so a spinner on a coloured background lost its track
+ * relationship entirely.
+ */
+export declare const ADW_SPINNER_TRACK_OPACITY = 0.15;
+/** `MIN_ARC_LENGTH` (:24) — GSK refuses to draw an arc shorter than this. */
+export declare const ADW_SPINNER_MIN_ARC_LENGTH: number;
+/** `MAX_ARC_LENGTH` (:25) — the LERP TARGET, 162°. The drawn arc peaks at 102.8°. */
+export declare const ADW_SPINNER_MAX_ARC_LENGTH: number;
+/** `IDLE_DISTANCE` (:26). */
+export declare const ADW_SPINNER_IDLE_DISTANCE: number;
+/** `OVERLAP_DISTANCE` (:27). */
+export declare const ADW_SPINNER_OVERLAP_DISTANCE: number;
+/** `EXTEND_DISTANCE` (:28). */
+export declare const ADW_SPINNER_EXTEND_DISTANCE: number;
+/** `CONTRACT_DISTANCE` (:29). */
+export declare const ADW_SPINNER_CONTRACT_DISTANCE: number;
+/**
+ * `N_CYCLES` (:33) — how many full TURNS the animation runs before repeating.
+ *
+ * The C states the constraint it satisfies: the cycle length
+ * `IDLE + EXTEND + CONTRACT - OVERLAP` must divide `N_CYCLES * 2pi` exactly, or
+ * the arc would jump when the animation loops. It does — 53 turns is 40 arc
+ * cycles — and {@link ADW_SPINNER_CYCLES_PER_LOOP} is that quotient, asserted
+ * rather than assumed.
+ */
+export declare const ADW_SPINNER_N_CYCLES = 53;
+/**
+ * One arc cycle, in radians of base angle:
+ * `IDLE_DISTANCE + EXTEND_DISTANCE + CONTRACT_DISTANCE - OVERLAP_DISTANCE`
+ * (adw-spinner-paintable.c:112, :130).
+ */
+export declare const ADW_SPINNER_CYCLE_LENGTH: number;
+/** Whole arc cycles per animation loop — an integer, which is the C's constraint. */
+export declare const ADW_SPINNER_CYCLES_PER_LOOP: number;
+/**
+ * The base angle a NON-animating spinner is drawn at — `EXTEND_DISTANCE -
+ * OVERLAP_DISTANCE / 2` (adw-spinner-paintable.c:375-376), i.e. `pi * 0.75`.
+ *
+ * Reached whenever there is no animation object: before the paintable has a
+ * widget, and in a still frame. Both ports left the resting pose undefined, so a
+ * spinner that had not started yet drew whatever its keyframe origin happened to
+ * be.
+ */
+export declare const ADW_SPINNER_STILL_PROGRESS: number;
+/**
+ * `normalize_angle` (adw-spinner-paintable.c:97-107) — fold into `[0, 2pi]`.
+ *
+ * The C loops rather than taking a modulo, and the boundary follows: it stops at
+ * `angle > G_PI * 2`, so exactly `2pi` is left alone where a modulo would give 0.
+ */
+export declare function normalizeSpinnerAngle(angle: number): number;
+/**
+ * `get_arc_start` (adw-spinner-paintable.c:109-125) — the trailing end of the
+ * arc, relative to the base angle.
+ *
+ * The `- angle * MAX_ARC_LENGTH / l` term is the drift that makes the arc
+ * advance around the circle as it breathes; without it the figure would pulse in
+ * place.
+ */
+export declare function spinnerArcStart(angle: number): number;
+/**
+ * `get_arc_end` (adw-spinner-paintable.c:127-145) — the leading end.
+ *
+ * Its phase is offset by `EXTEND_DISTANCE - OVERLAP_DISTANCE`: the end only
+ * starts moving once the start has extended past the overlap, which is what
+ * makes the arc grow before it slides.
+ */
+export declare function spinnerArcEnd(angle: number): number;
+/** The two ends of the drawn arc, in radians clockwise from 3 o'clock. */
+export interface SpinnerArc {
+    /** Trailing end, folded into `[0, 2pi]`. */
+    start: number;
+    /** Leading end, folded into `[0, 2pi]`. */
+    end: number;
+    /**
+     * Arc length along the circle, `start - end` unwrapped into `(0, 2pi]`.
+     *
+     * The segment runs from `end` to `start` (`gsk_path_builder_add_segment
+     * (builder, circle, &end_point, &start_point)`, :395) — the naming is the C's
+     * and it is the opposite way round from what "start" suggests.
+     */
+    length: number;
+}
+/**
+ * The arc for a base angle — `adw_spinner_paintable_snapshot_with_weight`
+ * (adw-spinner-paintable.c:373-383).
+ *
+ * `progress` is the animation's value: 0 at the start of a loop, rising linearly
+ * to `N_CYCLES * 2pi`. A renderer that has no animation passes
+ * {@link ADW_SPINNER_STILL_PROGRESS}.
+ */
+export declare function spinnerArc(progress: number): SpinnerArc;
+/**
+ * The animation's value after `elapsedMs` — `adw_timed_animation_new (widget, 0,
+ * N_CYCLES * 2pi, SPIN_DURATION_MS * N_CYCLES, target)` with `ADW_LINEAR` easing
+ * and `repeat_count = 0`, i.e. forever (adw-spinner-paintable.c:532-540).
+ *
+ * A linear ramp over the whole loop reduces to one turn per
+ * {@link ADW_SPINNER_SPIN_DURATION_MS}; the loop length only decides where it
+ * restarts, and it restarts at a point the arc phase agrees with.
+ */
+export declare function spinnerProgressAt(elapsedMs: number): number;

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

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