@gjsify/adwaita-core 0.51.1 → 0.53.0

package/lib/types/conformance/shared-trees.d.ts

@@ -1,9 +1,124 @@
-/** One node of an authored tree — the shape `ADWAITA_GALLERY_SHARED_TREES` is written in. */
+/**
+ * One node of an authored tree — the shape `ADWAITA_GALLERY_SHARED_TREES` is written in.
+ *
+ * THIS DECLARATION IS THE ORIGINAL. Every other spelling of the shape in this repository
+ * restates it — `scripts/adwaita-gallery-shared-trees.d.mts` for the plain-Node generators,
+ * `packages/infra/blueprint/src/shared-node.d.mts` for the projection, and more besides —
+ * each because it cannot import from here, each saying why in its own header.
+ * `scripts/check-shared-tree-shape.mjs` carries the list, holds every entry to this
+ * declaration field by field, and fails on a spelling that declares itself nowhere. So a
+ * field added here is added there too, or the gate says which field and where.
+ */
 export interface SharedTreeNode {
     /** A GIR class name, e.g. `AdwPreferencesGroup`. */
     tag: string;
+    /**
+     * The name this node is addressed by from OUTSIDE the tree.
+     *
+     * Renderer-neutral because every surface already has one — a GtkBuilder object id, a DOM
+     * `id`, a NativeScript `id` — and worth carrying although `bind` stays a refusal: measured
+     * in ADR 0066, EVERY id in this repository's shipped `.blp` is named by the sibling
+     * TypeScript through `InternalChildren` and NONE by a `bind` inside the file. A name read
+     * from outside is the component's addressing surface, not an input to a binding language.
+     */
+    id?: string;
+    /**
+     * On the ROOT node: the composite class this tree DEFINES, where `tag` is the type it
+     * extends.
+     *
+     * `template $GalleryHeaderBar : Adw.Bin` is `{ tag: 'AdwBin', template: 'GalleryHeaderBar' }`
+     * — two facts that a single tag cannot carry, which is why the root of every shipped `.blp`
+     * projected to its PARENT type and said nothing about the class the file is about. The value
+     * is what GtkBuilder writes as `<template class="…">`, so `emitGtkBuilderXml` and the
+     * projection can be held against each other on it — and are, by stage D's addressing arm.
+     */
+    template?: string;
+    /**
+     * Where in the parent this child goes — the placement, spelled as the GTK side spells it.
+     *
+     * ONE FIELD FOR TWO GtkBuilder CONSTRUCTS, and the conflation is the projection's, not a
+     * choice made here: `[start]` is `<child type="start">` and `content: …` is a
+     * property-valued child, and both land on this field, so it cannot be inverted (the
+     * Blueprint corpus's `expectations.mjs` states it as finding 1). A renderer therefore has
+     * to answer to both spellings of a placement it has — `gtk-host` derives the property name
+     * from its own `set_`-prefixed slot method, `<adw-header-bar>` names `title-widget` beside
+     * its own `center`.
+     *
+     * A SHARED TREE MAY CARRY ONE ONLY WHERE EVERY RENDERER SPELLS IT THE SAME. That is the
+     * corpus's no-alias admission rule applied to a placement, and it is narrow: a row's
+     * `prefix`/`suffix` qualify, a header bar's `start`/`title`/`end` do not
+     * (`startBox`/`titleWidget`/`endBox` on the NativeScript port), which is why those blocks
+     * are ledgered as `vocabulary` divergences. A renderer handed a name it has no destination
+     * for REFUSES and says which — the alternative was measured on a shipped `.blp`, where a
+     * `[top]` header bar landed in the content and the window title was then discarded by the
+     * bar's own construction, at exit 0.
+     */
     slot?: string;
     props?: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * Which of this node's `props` are marked for translation, keyed by the prop name.
+     *
+     * A present key means marked; `context` carries the message context `C_("noun", …)` gives
+     * one. BESIDE `props` and not inside it, because that is what the marking is wherever a
+     * surface has one: GtkBuilder writes `translatable="yes" context="noun"` as attributes NEXT
+     * to the value, and a marked value is still the same value. Widening `props` to a union
+     * would make every reader of a value narrow past something that is not one.
+     *
+     * Worth carrying although no renderer here translates: a caption whose marking was dropped
+     * looks finished and is unreachable by `xgettext`, which is the exact defect ADR 0033 gives
+     * as its reason for preferring a declarative template. ADR 0067 measures it and says why
+     * the file-level `translation-domain` is not a node fact and stays a loss.
+     */
+    translatable?: Readonly<Record<string, {
+        readonly context?: string;
+    }>>;
+    /**
+     * The style classes this node carries, as a list, in the order the source wrote them.
+     *
+     * ONE FIELD FOR TWO SPELLINGS, because they are one GTK property. Blueprint writes
+     * `styles ["flat", "circular"]` as a block and `css-classes: ["flat", "narrow"]` as a
+     * property value, and both set `GtkWidget:css-classes` — measured against the reference
+     * compiler, which writes the first as `<style><class name="flat"/></style>` and the second
+     * as a `<property>` whose text is NEWLINE-joined. A joined string in `props` would have to
+     * pick one of those two joins and could then not be held against the other golden, which is
+     * why the list is the field and not a string (ADR 0068 § 2).
+     *
+     * `styleClasses` and not `cssClasses`: ADR 0049 § 1 measured that name fatal on
+     * NativeScript, where `ViewBase` owns it as a live `Set` its CSS engine reads. So the field
+     * carries the name the three surfaces CAN share, and each driver maps it to its own door —
+     * the same arrangement `slot` already has, where GTK writes `<child type="start">` and the
+     * web writes `slot="start"`.
+     */
+    styleClasses?: readonly string[];
+    /**
+     * Blueprint's value-carrying extension blocks, one key per kind (ADR 0072).
+     *
+     * `strings` is `Gtk.StringList { strings [ … ] }`: GtkBuilder writes it as `<items>` and
+     * fills it through `gtk_string_list_append`. `responses` is `Adw.AlertDialog { responses
+     * [ … ] }`: filled through `adw_alert_dialog_add_response`, with `destructive`/`suggested`
+     * as the `appearance` and `disabled` as `enabled: false`. A string keeps its `_()` marking
+     * beside it, in the same `{ context? }` that `translatable` holds for a prop.
+     *
+     * A CLOSED SET. Every other extension (`menu`, `layout`, `marks`, `items`, …) stays a named
+     * loss of the projection, so no renderer meets a kind it has no door for.
+     */
+    extensions?: Readonly<{
+        strings?: readonly {
+            readonly value: string;
+            readonly translatable?: {
+                readonly context?: string;
+            };
+        }[];
+        responses?: readonly {
+            readonly id: string;
+            readonly label: string;
+            readonly translatable?: {
+                readonly context?: string;
+            };
+            readonly appearance?: 'suggested' | 'destructive';
+            readonly enabled?: boolean;
+        }[];
+    }>;
     children?: readonly SharedTreeNode[];
 }
 /**
@@ -64,12 +179,47 @@ export declare function authoredNodes(root: SharedTreeNode): {
 /**
  * The authored classes a realised tree must carry, in authored order.
  *
- * `tagOf` is the renderer's own spelling of a GIR class name — `hostTagOf` on the web, the
- * GIR name itself in GTK. Both drivers filter their real tree down to this list and compare
- * against it, so it lives here rather than in each of them: a driver deriving it privately
- * is a second walk, free to disagree with the one {@link subjectIndexOf} addresses into.
+ * `tagOf` is the renderer's own spelling of a GIR class name — `hostTagOf` from the sibling
+ * `@gjsify/adwaita-core/tags` on the web, the GIR name itself in GTK. Both drivers filter
+ * their real tree down to this list and compare against it, so it lives here rather than in
+ * each of them: a driver deriving it privately is a second walk, free to disagree with the
+ * one {@link subjectIndexOf} addresses into.
  */
 export declare function authoredTags(root: SharedTreeNode, tagOf?: (gtype: string) => string): string[];
+/** One authored placement: the node's address, and the slot it named. */
+export interface SharedTreePlacement {
+    /** The pre-order address {@link subjectIndexOf} reads, so a failure names a node. */
+    path: string;
+    /** The slot the tree authored, spelled the way every renderer admitting the block spells it. */
+    slot: string;
+}
+/**
+ * Every node of `root` that names a placement.
+ *
+ * WHAT THIS IS FOR. A driver comparing only the authored classes IN ORDER cannot see a
+ * slot at all: a child placed in the wrong slot of the right parent keeps every authored
+ * node in every authored position. ADR 0051 § Amendment 3 measured exactly that on the
+ * NativeScript port — two deliberate mis-placements, both GREEN — and the corpus authored
+ * no slot to catch it with until one did. This is the renderer-free half of the answer;
+ * what a driver DOES with it is its own, because "the child ended up in slot X" has no
+ * shared observable.
+ */
+export declare function sharedTreePlacements(root: SharedTreeNode): SharedTreePlacement[];
+/**
+ * The same tree with every placement dropped — what a renderer that never read `slot`
+ * builds.
+ *
+ * THE CONTROL, and it is why a placement assertion can be made without a per-widget table
+ * of where each slot lands. A driver builds the tree twice and asserts the two REALISED
+ * trees differ: with the slots honoured a suffix sits in its row's header, without them it
+ * sits wherever that parent's default placement puts it. Every builder here read only
+ * `tag`, `props` and `children`, so the two builds were byte-identical — which is the
+ * regression this control turns red.
+ *
+ * Fresh nodes all the way down, never the authored ones: a driver handed the corpus's own
+ * objects could edit what the next block builds.
+ */
+export declare function withoutPlacements(root: SharedTreeNode): SharedTreeNode;
 /**
  * Where the node an expectation is about sits in that filtered walk.
  *

package/lib/types/conformance/tags.d.ts

@@ -0,0 +1,46 @@
+/** One `hostTagOf` expectation — a class that resolves, or a name it must refuse. */
+export interface HostTagVector {
+    /** A GIR class name, or a string that is deliberately not one. */
+    gtype: string;
+    /** The kebab tag `hostTagOf` must return. Absent for a row that must throw instead. */
+    expected?: string;
+    /** The exact `Error#message` `hostTagOf` must throw. Absent for a row that must resolve. */
+    error?: string;
+    rule: string;
+}
+/**
+ * `hostTagOf` — GIR class name to kebab tag, and the refusal boundary.
+ *
+ * `AdwPreferencesGroup`/`AdwSwitchRow`/`GtkBox` pin the floor: one dash per word boundary,
+ * no acronym involved. `GtkGLArea`/`GtkATContext`/`GtkIMMulticontext` pin THE rule the floor
+ * cannot show — a run of two or more capitals closes at its LAST one, so `GL` stays one word
+ * and `Area` opens a new one, rather than `g-l-area`. `GtkPad2Btn` pins what a digit does:
+ * it is not an uppercase letter, so it ends a lower run exactly like a lowercase letter
+ * would, and the capital after it still opens a new word.
+ */
+export declare const HOST_TAG_VECTORS: ReadonlyArray<HostTagVector>;
+/** One `attributeOf` expectation. */
+export interface AttributeOfVector {
+    /** The authored property name, as an `AdwXyz`/`GtkXyz` prop is spelled in a `SharedTreeNode`. */
+    prop: string;
+    /** The attribute `attributeOf` must return. */
+    expected: string;
+    rule: string;
+}
+/**
+ * `attributeOf` — camelCase property name to kebab DOM attribute.
+ *
+ * Every capital gets its own dash, with no acronym awareness — see the header for why that
+ * boundary is out of scope for this table.
+ */
+export declare const ATTRIBUTE_OF_VECTORS: ReadonlyArray<AttributeOfVector>;
+/** One `propertyOf` expectation. */
+export interface PropertyOfVector {
+    /** A property name as a projected `.blp` spells it, or as a hand-authored tree does. */
+    name: string;
+    /** The member `propertyOf` must return. */
+    expected: string;
+    rule: string;
+}
+/** `propertyOf` — a GIR property name to the camel-case member a NativeScript widget declares. */
+export declare const PROPERTY_OF_VECTORS: ReadonlyArray<PropertyOfVector>;

package/lib/types/conformance/value-lists.d.ts

@@ -0,0 +1,19 @@
+import type { AdwResponseAppearance } from '../dialog.js';
+/** One registered response, as the built dialog reports it. */
+export interface ValueListResponse {
+    readonly id: string;
+    readonly label: string;
+    readonly appearance: AdwResponseAppearance;
+    readonly enabled: boolean;
+}
+/** One Blueprint source and what the widget it builds hands back. */
+export interface ValueListVector {
+    readonly rule: string;
+    /** The object, written after `using Gtk 4.0; using Adw 1;`. */
+    readonly blueprint: string;
+    /** The labels of the root's list model, in order — a combo row or a drop-down. */
+    readonly strings?: readonly string[];
+    /** The root dialog's responses, in the order they were added. */
+    readonly responses?: readonly ValueListResponse[];
+}
+export declare const VALUE_LIST_VECTORS: readonly ValueListVector[];

package/lib/types/dialog.d.ts

@@ -152,6 +152,127 @@ export interface BottomSheetCloseState {
  * Neither can fire on a closed sheet, so neither signals anything.
  */
 export declare function resolveBottomSheetClose(source: BottomSheetCloseSource, state: BottomSheetCloseState): BottomSheetCloseOutcome;
+/**
+ * Which affordance asked a bottom sheet to OPEN.
+ *
+ * libadwaita gives a user exactly ONE surface to open a sheet from — the bottom bar. Both
+ * doors into it are gated by `can-open`, and both are unreachable without a bar:
+ *
+ * - `'bottom-bar'`  — a click on the bar. The bin IS a `GtkButton`
+ *                     (adw-bottom-sheet.c:1203) whose own click gesture is put in
+ *                     `GTK_PHASE_NONE` by `disable_button_click` (:1209), so a pointer press
+ *                     runs `bottom_bar_released_cb` (:263-284) and a keyboard activation
+ *                     runs `bottom_bar_clicked_cb` (:402-407). Same verdict from both.
+ * - `'swipe'`       — an upward swipe off the bar (`prepare_cb`, :1052-1053).
+ * - `'drag-handle'` — the pill, decorative exactly as in the dismissal gate.
+ */
+export type BottomSheetOpenSource = 'bottom-bar' | 'swipe' | 'drag-handle';
+/**
+ * What a renderer must do about an open request. There is no `'open-attempt'`: libadwaita
+ * has no signal for a refused open, so a sheet that will not open is silent.
+ */
+export type BottomSheetOpenOutcome = 'open' | 'ignored';
+/**
+ * What {@link resolveBottomSheetOpen} decides from — the SAME four properties the chrome is
+ * derived from, which is the finding rather than a convenience: whether a user can open the
+ * sheet is exactly the question of whether the bar is on screen and not inert.
+ */
+export type BottomSheetOpenState = BottomSheetChromeState;
+/**
+ * The open decision table.
+ *
+ * Only ONE of the four inputs is a branch inside a callback — `can_open`. The other three
+ * are REACHABILITY, which is why a port that reads only the callbacks gets them wrong:
+ *
+ * - no bottom bar: the stack never switches to the bin (`show_bottom_bar` returns before the
+ *   switch, adw-bottom-sheet.c:294-295; `set_bottom_bar` puts `sheet_page` back, :1615-1616),
+ *   and the swipe area is a ZERO-HEIGHT rectangle at progress 0 because `bottom_bar_height`
+ *   is 0 (`get_swipe_area`, :1412-1433). Upstream states the consequence outright — `can-open`
+ *   "does nothing if [property@BottomSheet:bottom-bar] is not set" (:2013).
+ * - already open: `set_open (TRUE)` switches the stack away from the bin (:1701-1702), so
+ *   there is nothing to click, and `prepare_cb` reads an open sheet's gesture as a CLOSE
+ *   (:1050-1051) rather than a second open.
+ * - bar not revealed: at progress 0 `reveal_animation_done_cb` makes the whole sheet bin
+ *   child-invisible (:362-364, and the same expression at :341-343), so the bar is off screen.
+ *
+ * `can_open` itself is NOT reachability: the bin stays focusable and merely gains the `inert`
+ * style class (:2033-2036), which is why {@link BottomSheetChrome.bottomBarInert} is a class
+ * to paint rather than a widget to disable.
+ */
+export declare function resolveBottomSheetOpen(source: BottomSheetOpenSource, state: BottomSheetOpenState): BottomSheetOpenOutcome;
+/** Which of the sheet bin's two stack children is showing (`sheet_stack`). */
+export type BottomSheetLayer = 'sheet' | 'bottom-bar';
+/** What {@link resolveBottomSheetChrome} decides from. */
+export interface BottomSheetChromeState {
+    /** `AdwBottomSheet:open`. */
+    open: boolean;
+    /** `AdwBottomSheet:can-open`. */
+    canOpen: boolean;
+    /** Whether `AdwBottomSheet:bottom-bar` is set. */
+    hasBottomBar: boolean;
+    /** `AdwBottomSheet:reveal-bottom-bar`; absent means revealed. */
+    revealBottomBar?: boolean;
+    /** `AdwBottomSheet:modal`; absent means modal, the pspec default (adw-bottom-sheet.c:1128). */
+    modal?: boolean;
+}
+/** What a renderer has to put on screen for a given state. */
+export interface BottomSheetChrome {
+    /** Which stack child the sheet bin shows. */
+    layer: BottomSheetLayer;
+    /** Whether the sheet bin is on screen at all (`gtk_widget_set_child_visible`). */
+    surfaceVisible: boolean;
+    /** Whether the bar carries the `inert` style class — still clickable, just refusing. */
+    bottomBarInert: boolean;
+    /**
+     * Whether the dimming layer covers the content — the scrim a click on dismisses through
+     * the `'dimming'` source. Only a MODAL sheet has one on screen.
+     */
+    dimmed: boolean;
+}
+/**
+ * The bin's resting appearance: which child shows, whether the bin is on screen, and whether
+ * the bar looks inert.
+ *
+ * RESTING is the whole simplification. In C these follow `progress` across
+ * `CHILD_SWITCH_THRESHOLD` mid-animation (`open_animation_cb`, adw-bottom-sheet.c:322-330);
+ * with no spring animation the settled progress IS `open`, so `showing_bottom_bar` reduces to
+ * `!open` — which is also its init value (:1131) for a sheet that starts closed.
+ *
+ * The dimming reduces the same way. `set_open (TRUE)` makes it child-visible exactly when the
+ * sheet is modal (:1686-1687), `set_modal` re-applies that while the sheet is not settled closed
+ * (:1981-1982), and the close animation hides it once it settles (:338-339). At rest that is
+ * `open && modal`; the opacity ramp between is the animation this model does not run.
+ */
+export declare function resolveBottomSheetChrome(state: BottomSheetChromeState): BottomSheetChrome;
+/** What {@link resolveBottomSheetSwipeTracker} decides from. */
+export interface BottomSheetSwipeTrackerState {
+    /** `AdwBottomSheet:can-open`. */
+    canOpen: boolean;
+    /** `AdwBottomSheet:can-close`. */
+    canClose: boolean;
+    /** Whether `AdwBottomSheet:bottom-bar` is set. */
+    hasBottomBar: boolean;
+    /** `AdwBottomSheet:show-drag-handle`. */
+    showDragHandle: boolean;
+}
+/** The three `AdwSwipeTracker` settings `update_swipe_tracker` writes. */
+export interface BottomSheetSwipeTrackerConfig {
+    /** Whether the tracker recognises a gesture at all. */
+    enabled: boolean;
+    /** Whether a mouse drag counts, not only touch. */
+    allowMouseDrag: boolean;
+    /** Whether the gesture may overshoot below the closed position. */
+    lowerOvershoot: boolean;
+}
+/**
+ * `update_swipe_tracker` (adw-bottom-sheet.c:450-460) as a pure function.
+ *
+ * `enabled` is the line that decides whether a bottom sheet can be opened by gesture at all:
+ * `(can_open && bottom_bar != NULL) || can_close`. The `&& bottom_bar` conjunct is why
+ * `can-open` alone buys nothing — with no bar the only live arm is `can_close`, i.e. the
+ * tracker exists solely to CLOSE.
+ */
+export declare function resolveBottomSheetSwipeTracker(state: BottomSheetSwipeTrackerState): BottomSheetSwipeTrackerConfig;
 /** One entry in a {@link BottomSheetPresentation}'s teardown callback pair. */
 export type BottomSheetTeardownCallback = 'closing' | 'closed';
 /** Subscriber for {@link BottomSheetPresentation} `open` changes. */
@@ -180,10 +301,18 @@ export interface BottomSheetPresentationOptions {
  * still be closed using [property@BottomSheet:open]"); {@link requestClose} is the INTERACTIVE
  * path that runs the gate. Keeping them apart is what lets a locked sheet still be closed by
  * its owner.
+ *
+ * The same split holds the other way round: {@link requestOpen} is the user's path and runs
+ * {@link resolveBottomSheetOpen}, so a sheet with no bottom bar cannot be opened by a user at
+ * all, while its owner's `setOpen(true)` still works.
  */
 export declare class BottomSheetPresentation {
     private _open;
     private _canClose;
+    private _canOpen;
+    private _hasBottomBar;
+    private _revealBottomBar;
+    private _modal;
     private _hasBeenOpen;
     private readonly _listeners;
     private readonly _onClosing;
@@ -201,8 +330,36 @@ export declare class BottomSheetPresentation {
      * {@link setOpen}; `has_been_open` in the C source.
      */
     get hasBeenOpen(): boolean;
+    /** Whether the user may open the sheet from its bottom bar (`AdwBottomSheet:can-open`). */
+    get canOpen(): boolean;
+    /** Whether a bottom bar is set (`AdwBottomSheet:bottom-bar` is non-NULL). */
+    get hasBottomBar(): boolean;
+    /** Whether the bottom bar is revealed (`AdwBottomSheet:reveal-bottom-bar`). */
+    get revealBottomBar(): boolean;
+    /** Whether the sheet dims and blocks the content while open (`AdwBottomSheet:modal`). */
+    get modal(): boolean;
+    /** What the renderer has to show for the current state — {@link resolveBottomSheetChrome}. */
+    get chrome(): BottomSheetChrome;
     /** Set `can-close`. Returns whether it changed. */
     setCanClose(canClose: boolean): boolean;
+    /** Set `can-open`. Returns whether it changed. */
+    setCanOpen(canOpen: boolean): boolean;
+    /**
+     * Record whether a bottom bar is present. Returns whether it changed.
+     *
+     * A renderer calls this from wherever it adopts the bar widget — the C setter is where
+     * `update_swipe_tracker` is re-run (adw-bottom-sheet.c:1629), i.e. presence is an INPUT to
+     * the gates, not a rendering detail.
+     */
+    setHasBottomBar(hasBottomBar: boolean): boolean;
+    /**
+     * Set `modal`. Returns whether it changed. A sheet that is open changes its dimming at
+     * once, as `adw_bottom_sheet_set_modal` does (adw-bottom-sheet.c:1981-1982); `open` and
+     * the gates do not move, so nothing is notified here — the renderer repaints.
+     */
+    setModal(modal: boolean): boolean;
+    /** Set `reveal-bottom-bar`. Returns whether it changed. */
+    setRevealBottomBar(reveal: boolean): boolean;
     /**
      * The programmatic open/close — `adw_bottom_sheet_set_open`. Returns whether `open`
      * changed, i.e. whether a `notify::open` was emitted.
@@ -218,6 +375,12 @@ export declare class BottomSheetPresentation {
      * forwarded to the parent, or nothing at all.
      */
     requestClose(source: BottomSheetCloseSource): BottomSheetCloseOutcome;
+    /**
+     * Route an open affordance through {@link resolveBottomSheetOpen} and APPLY the outcome.
+     * `'ignored'` is the only other answer, and it is silent: libadwaita has no
+     * `open-attempt` counterpart to `close-attempt`, so a renderer emits nothing for it.
+     */
+    requestOpen(source: BottomSheetOpenSource): BottomSheetOpenOutcome;
     /**
      * The sheet has finished hiding — `open_animation_done_cb`'s teardown reduced to what a
      * renderer without a spring animation can observe. Fires `onClosed` and returns whether it

package/lib/types/gio-menu.d.ts

@@ -0,0 +1,46 @@
+import type { AdwMenuEntryInput, AdwMenuItemInput } from './menu.js';
+/**
+ * One menu item, built the way `g_menu_item_new` builds one.
+ *
+ * IT IS ITSELF A PORTABLE ENTRY — `implements AdwMenuItemInput` — so `append_item` pushes
+ * the instance and `normalizeMenuModel` reads its fields like any authored object. A
+ * separate internal shape would need a conversion the model does not ask for.
+ *
+ * Both halves are nullable, as they are in C: `g_menu_item_new(NULL, NULL)` is legal and
+ * produces an item carrying neither, which {@link normalizeMenuModel} drops rather than
+ * drawing an empty, unactionable row.
+ */
+export declare class GioMenuItem implements AdwMenuItemInput {
+    /** The user-visible string; ABSENT rather than `undefined` when the item has none. */
+    label?: string;
+    /** The DETAILED action name — `app.save-as`, `app.view::list` (ADR 0042 § divergence 2). */
+    action?: string;
+    constructor(label?: string | null, detailedAction?: string | null);
+    /** `g_menu_item_set_label`. `null` REMOVES the attribute, which is what C does. */
+    set_label(label: string | null): void;
+    /** `g_menu_item_set_detailed_action`, and `null` is `g_menu_item_set_action_and_target(…, NULL)`. */
+    set_detailed_action(detailedAction: string | null): void;
+}
+/**
+ * A menu under construction — `Gio.Menu`'s four append entry points over the portable model.
+ *
+ * `new GioMenu()` is empty, as `g_menu_new()` is. Every `append*` puts one entry on the end,
+ * and the instance IS the value a `menuModel` property takes.
+ */
+export declare class GioMenu extends Array<AdwMenuEntryInput> {
+    /** `g_menu_append` — the convenience C implements as `menu_item_new` + `append_item`. */
+    append(label: string | null, detailedAction?: string | null): void;
+    /** `g_menu_append_item`. */
+    append_item(item: GioMenuItem): void;
+    /**
+     * `g_menu_append_section` — the `section` LINK, whose items are drawn inline with a
+     * separator rather than behind a further click.
+     *
+     * The label is optional in C and stays optional here: a section with none is a plain
+     * group, and writing `label: null` onto the entry would be an attribute the model
+     * then has to ignore.
+     */
+    append_section(label: string | null, section: readonly AdwMenuEntryInput[]): void;
+    /** `g_menu_append_submenu` — the `submenu` LINK: a nested menu the user opens. */
+    append_submenu(label: string | null, submenu: readonly AdwMenuEntryInput[]): void;
+}

package/lib/types/gtk-adjustment.d.ts

@@ -0,0 +1,73 @@
+import type { AdwAdjustment, AdwAdjustmentInput } from './adjustment.js';
+/**
+ * What `new Gtk.Adjustment({ … })` takes: the GJS construct bag, which is exactly
+ * {@link AdwAdjustmentInput}.
+ *
+ * An ALIAS and not a second interface — the two would be one declaration copied, and the
+ * copy is the one that drifts when a seventh field arrives.
+ */
+export type GtkAdjustmentProps = AdwAdjustmentInput;
+/**
+ * A numeric range — `Gtk.Adjustment`'s six properties as a value an `adjustment` property
+ * takes.
+ *
+ * `new GtkAdjustment()` is `ADW_ADJUSTMENT_DEFAULTS` (0…100 step 1), which is the
+ * package's own default and NOT GTK's 0…0 step 0 — `adjustment.ts` says why in its header.
+ */
+export declare class GtkAdjustment implements AdwAdjustment {
+    /** The current value, within {@link adjustmentRange}. */
+    value: number;
+    /** The minimum value. */
+    lower: number;
+    /** The maximum value. */
+    upper: number;
+    /** How far one stepper press moves the value. */
+    stepIncrement: number;
+    /** How far one page press (Page Up/Down) moves the value. */
+    pageIncrement: number;
+    /** The size of the visible page; zero for a scalar value such as a spin row's. */
+    pageSize: number;
+    constructor(props?: GtkAdjustmentProps | null);
+    /**
+     * Re-establish the invariants around one authored change.
+     *
+     * The current six are the BASE, so a field nobody wrote keeps what it held instead of
+     * falling back to the package default — the same contract `SpinState.configure` has.
+     */
+    private _write;
+    /** `gtk_adjustment_configure` — all six at once, which is what C compresses into one. */
+    configure(value: number, lower: number, upper: number, step_increment: number, page_increment: number, page_size: number): void;
+    /** `gtk_adjustment_get_value`. */
+    get_value(): number;
+    /** `gtk_adjustment_set_value` — "clamped to lie between lower and upper". */
+    set_value(value: number): void;
+    /** `gtk_adjustment_get_lower`. */
+    get_lower(): number;
+    /** `gtk_adjustment_set_lower`. */
+    set_lower(lower: number): void;
+    /** `gtk_adjustment_get_upper`. */
+    get_upper(): number;
+    /** `gtk_adjustment_set_upper`. */
+    set_upper(upper: number): void;
+    /** `gtk_adjustment_get_step_increment`. */
+    get_step_increment(): number;
+    /** `gtk_adjustment_set_step_increment`. */
+    set_step_increment(step_increment: number): void;
+    /** `gtk_adjustment_get_page_increment`. */
+    get_page_increment(): number;
+    /** `gtk_adjustment_set_page_increment`. */
+    set_page_increment(page_increment: number): void;
+    /** `gtk_adjustment_get_page_size`. */
+    get_page_size(): number;
+    /** `gtk_adjustment_set_page_size`. */
+    set_page_size(page_size: number): void;
+    /**
+     * `gtk_adjustment_get_minimum_increment` — "the smaller of step increment and page
+     * increment", which is the GIR's own sentence.
+     *
+     * Total, with no zero case: `normalizeAdjustment` refuses a step of zero and carries
+     * the page increment with it, so both are positive here. C has to answer for the
+     * adjustment its own defaults produce, where either can be 0.
+     */
+    get_minimum_increment(): number;
+}

package/lib/types/gtk-adjustment.spec.d.ts

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

package/lib/types/gtk-string-list.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What `new Gtk.StringList({ … })` takes — the GJS spelling of the type's own
+ * construct-time properties.
+ *
+ * `strings` only. The other two `StringList` declares — `item-type` and `n-items` — are
+ * `GListModel`'s read-only pair, and a construct bag that accepted them would be offering
+ * a write the type does not have.
+ */
+export interface GtkStringListProps {
+    /** The strings the list starts with. */
+    strings?: readonly string[] | null;
+}
+/**
+ * A list of strings under construction — `Gtk.StringList`'s building half over a plain
+ * JS array.
+ *
+ * `new GtkStringList()` is empty, as `gtk_string_list_new(NULL)` is, and the instance IS
+ * the value a `model` property takes.
+ */
+export declare class GtkStringList extends Array<string> {
+    /** See the file header: `map`/`filter`/`slice` must not call this constructor. */
+    static get [Symbol.species](): ArrayConstructor;
+    constructor(props?: GtkStringListProps | null);
+    /**
+     * `Gtk.StringList:strings`, as the door an attribute reaches. GTK's property is
+     * construct-only, and a NativeScript XML template has no constructor call to pass it
+     * through: `<gtk:StringList strings='["Blue","Teal"]'>` assigns the JSON text to this
+     * member instead, on a list that is still empty. So it REPLACES the contents, as
+     * constructing with `{ strings }` would have filled them.
+     */
+    get strings(): string[];
+    set strings(value: readonly string[] | string);
+    /** `gtk_string_list_append`. */
+    append(string: string): void;
+    /**
+     * `gtk_string_list_take` — `append` without the copy.
+     *
+     * The copy is what the two differ by in C ("this variant … is convenient for
+     * formatting strings"), and JS strings are immutable, so here the two are one
+     * function. It exists so code ported from GJS keeps working rather than to say
+     * something `append` does not.
+     */
+    take(string: string): void;
+    /** `gtk_string_list_remove` — the string at `position`, which must be in range. */
+    remove(position: number): void;
+    /**
+     * `gtk_string_list_splice` AND `Array.prototype.splice`, which is the point.
+     *
+     * The two say the same thing and pass the additions differently: C takes ONE array of
+     * them, JS takes them as rest arguments. A list whose elements are strings can tell
+     * the two apart with no ambiguity — an element is never an array — so both spellings
+     * work and a `list.splice(1, 2, ['a', 'b'])` ported straight from GJS inserts two
+     * strings instead of silently inserting one array as an element.
+     *
+     * `nRemovals` omitted is `Array.prototype.splice`'s "to the end", which is a different
+     * thing from passing `undefined` — so it is spelled as the count that reaches the end,
+     * which `splice` clamps the same way for a negative `position` as the one-argument form
+     * does.
+     *
+     * Flattened by hand, not `Array.prototype.flatMap` (ES2019): this source is also
+     * type-checked through `@gjsify/gtk-host`'s type-surface gate, whose `tsconfig`s
+     * pin `lib` to ES2017 for reasons of their own (`type-tests/{jsx,react}/tsconfig.json`)
+     * — a method this file alone would happily target ES2020 for is invisible there.
+     */
+    splice(position: number, nRemovals?: number, ...additions: readonly (string | readonly string[])[]): string[];
+    /** `gtk_string_list_get_string` — `null` past the end, as C returns `NULL`. */
+    get_string(position: number): string | null;
+    /** `g_list_model_get_n_items`, which a `GtkStringList` answers with its length. */
+    get_n_items(): number;
+}

package/lib/types/gtk-string-list.spec.d.ts

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