@gjsify/adwaita-core 0.64.12-next.280 → 0.64.12

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

@@ -1,72 +1,117 @@
+import { GIR_TYPE, GObjectObject, type GType } from './gobject.js';
+/** `gtk_string_list_find`'s "not found" — `GTK_INVALID_LIST_POSITION`, a `guint` of all ones. */
+export declare const INVALID_LIST_POSITION = 4294967295;
 /**
- * What `new Gtk.StringList({ … })` takes — the GJS spelling of the type's own
- * construct-time properties.
+ * `Gtk.StringObject` — one string, as the `GObject` a `GListModel` is allowed to hand out.
  *
- * `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.
+ * It exists for the reason it exists in GTK: `g_list_model_get_item` returns a `GObject`, and a
+ * string is not one. Two objects holding the same string are NOT equal (measured), so identity
+ * here means "this entry of this list", never "this text".
+ */
+export declare class GtkStringObject extends GObjectObject {
+    static [GIR_TYPE]: string;
+    constructor(props?: Record<string, unknown> | null);
+    /** `gtk_string_object_new` — the only way to put a string in one. */
+    static new(string: string): GtkStringObject;
+    /**
+     * `Gtk.StringObject:string`.
+     *
+     * `null` on one built without a string: `new Gtk.StringObject().string` is `null`, measured,
+     * and the GIR's non-null typing describes only the items a list hands out.
+     */
+    get string(): string | null;
+    set string(_value: string);
+    /** `gtk_string_object_get_string`. */
+    get_string(): string | null;
+}
+/**
+ * What `new Gtk.StringList({ … })` takes.
+ *
+ * `strings` only, and CONSTRUCT-ONLY, as GTK declares it. The other two the type has —
+ * `item-type` and `n-items` — are `GListModel`'s read-only pair.
  */
 export interface GtkStringListProps {
     /** The strings the list starts with. */
-    strings?: readonly string[] | null;
+    strings?: readonly (string | null)[] | null;
 }
 /**
- * A list of strings under construction — `Gtk.StringList`'s building half over a plain
- * JS array.
+ * `Gtk.StringList` — a `Gio.ListModel` of {@link GtkStringObject}s.
  *
- * `new GtkStringList()` is empty, as `gtk_string_list_new(NULL)` is, and the instance IS
- * the value a `model` property takes.
+ * `new GtkStringList()` is empty, as `gtk_string_list_new(NULL)` is, and the instance is what
+ * every `model` property takes. It is NOT an array and nothing array-shaped reaches it.
  */
-export declare class GtkStringList extends Array<string> {
-    /** See the file header: `map`/`filter`/`slice` must not call this constructor. */
-    static get [Symbol.species](): ArrayConstructor;
+export declare class GtkStringList extends GObjectObject {
+    static [GIR_TYPE]: string;
+    /** Installed by the core from {@link ListModel}; declared here for the type alone. */
+    readonly get_item: (position: number) => GtkStringObject | null;
+    readonly get_item_type: () => GType;
+    readonly get_n_items: () => number;
+    readonly items_changed: (position: number, removed: number, added: number) => void;
     constructor(props?: GtkStringListProps | null);
     /** `gtk_string_list_new`: a list holding `strings`, or an empty one for `null`. */
-    static new(strings: readonly string[] | null): GtkStringList;
+    static new(strings: readonly (string | null)[] | null): GtkStringList;
     /**
-     * `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.
+     * `Gtk.StringList:strings` as GTK leaves it after construction: unreadable, and unwritable
+     * without saying so.
+     *
+     * Both halves are measured, not chosen. The property is construct-only, so GJS installs a
+     * getter that answers `undefined` and a setter GObject refuses — with a CRITICAL on stderr
+     * and NO exception, leaving the list exactly as it was. Omitting the pair would turn
+     * `list.strings = […]` into a silent own-property write that looks like it worked.
      */
-    get strings(): string[];
-    set strings(value: readonly string[] | string);
+    get strings(): undefined;
+    set strings(_value: readonly string[] | undefined);
+    /** `Gtk.StringList:item-type` — see the file header on why it is `GObject`. */
+    get item_type(): GType;
+    set item_type(_value: GType);
+    get itemType(): GType;
+    set itemType(_value: GType);
+    /** `Gtk.StringList:n-items` — the `ParamSpec`'s reader, and `get_n_items`'s answer. */
+    get n_items(): number;
+    set n_items(_value: number);
+    /** `vfunc_get_item_type` — what the interface's `get_item_type()` calls through to. */
+    vfunc_get_item_type(): GType;
+    /** `vfunc_get_n_items`. */
+    vfunc_get_n_items(): number;
+    /** `vfunc_get_item` — `null` past the end, as `g_list_model_get_item` returns `NULL`. */
+    vfunc_get_item(position: number): GtkStringObject | null;
     /** `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.
+     * 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.
+     * `gtk_string_list_splice(position, n_removals, additions)` — the C signature, all three
+     * arguments, additions as ONE array.
      *
-     * 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.
+     * Not `Array.prototype.splice`'s rest-argument form: this class is no longer an array, so the
+     * overload that used to serve both spellings would now be the subset inventing one. Each of
+     * the three refusals below is GJS's own, measured: a short call, a bare string where a strv
+     * belongs, and `undefined` in a slot that takes `null`.
      */
-    splice(position: number, nRemovals?: number, ...additions: readonly (string | readonly string[])[]): string[];
+    splice(position: number, nRemovals: number, additions: readonly (string | null)[] | null): void;
     /** `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;
+    /**
+     * `gtk_string_list_find` — the POSITION of the first equal string, GTK's meaning of the name,
+     * not `Array.prototype.find`'s. {@link INVALID_LIST_POSITION} when there is none.
+     */
+    find(string: string): number;
+    /**
+     * The one mutation, so the emission rule is written once: `items-changed` first, then
+     * `notify::n-items` and only when the count actually moved, and NEITHER when the splice
+     * removes nothing and adds nothing. All three measured; GTK's own
+     * `gtk_string_list_items_changed` is the same two lines.
+     *
+     * Out of range is a CRITICAL and a no-op, not an exception — `remove` past the end lands on
+     * the same assertion, because `gtk_string_list_remove` IS a splice in C.
+     */
+    private spliceItems;
 }

package/lib/types/index.d.ts

@@ -32,7 +32,7 @@ export { Toast, ToastOverlayQueue, ToastPriority } from './toast-object.js';
 export type { ToastOverlayQueueOptions } from './toast-object.js';
 export { AdwAlertResponses, BottomSheetPresentation, resolveBottomSheetChrome, resolveBottomSheetClose, resolveBottomSheetOpen, resolveBottomSheetSwipeTracker, } from './dialog.js';
 export type { AdwAlertResponse, AdwResponseAppearance, AdwResponseOptions, BottomSheetChrome, BottomSheetChromeState, BottomSheetCloseOutcome, BottomSheetCloseSource, BottomSheetCloseState, BottomSheetLayer, BottomSheetOpenOutcome, BottomSheetOpenSource, BottomSheetOpenState, BottomSheetPresentationListener, BottomSheetPresentationOptions, BottomSheetSwipeTrackerConfig, BottomSheetSwipeTrackerState, BottomSheetTeardownCallback, OrderedConfirmResponses, } from './dialog.js';
-export { ADW_COMBO_NO_SELECTION, clampListSelection, listItemsChanged, normalizeComboOptions, parseListModel, } from './list.js';
+export { ADW_COMBO_NO_SELECTION, listItemsChanged, normalizeComboOptions, parseListModel } from './list.js';
 export type { AdwComboOption, AdwComboOptionInput, AdwListItemsChanged, AdwListModel, AdwListModelInput, } from './list.js';
 export { ADW_COLUMN_VIEW_NO_FIXED_WIDTH, ADW_GRID_VIEW_MAX_COLUMNS, ADW_GRID_VIEW_MIN_COLUMNS, columnViewSort, columnViewTracks, gridViewColumns, listItemField, listViewSelect, listViewSelectAll, ListViewState, normalizeColumnViewColumns, normalizeListSelectionMode, parseColumnViewColumns, } from './list-view.js';
 export type { AdwColumnViewColumn, AdwColumnViewSort, AdwListItemContext, AdwListItemFactory, AdwListItemField, AdwListSelectStep, AdwListSelection, AdwListSelectionMode, AdwListSelectResult, ListViewItemsListener, ListViewSelectionChange, ListViewSelectionListener, } from './list-view.js';
@@ -46,17 +46,19 @@ export { ADW_ADJUSTMENT_DEFAULTS, adjustmentRange, clampAdjustmentValue, normali
 export type { AdwAdjustment, AdwAdjustmentInput, SpinStateChange, SpinStateListener, SpinStateRangeListener, } from './adjustment.js';
 export { GtkAdjustment } from './gtk-adjustment.js';
 export type { GtkAdjustmentProps } from './gtk-adjustment.js';
-export { GtkStringList } from './gtk-string-list.js';
+export { GtkStringList, GtkStringObject, INVALID_LIST_POSITION } from './gtk-string-list.js';
 export type { GtkStringListProps } from './gtk-string-list.js';
+export { GjsifyOptionList, GjsifyOptionObject, readModelWrite } from './option-list.js';
+export type { GjsifyOptionListProps } from './option-list.js';
 export { ComboState, ExpanderState, ToggleGroupState, keptToggles, toggleIndexOfName } from './rows.js';
-export type { ComboItemsListener, ComboStateChange, ComboStateListener, ExpanderStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
+export type { ComboItemsListener, ComboNotify, ComboNotifyListener, ComboStateChange, ComboStateListener, ComboWatchableModel, ExpanderStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
 export { DEFAULT_BOX_SPACING, normalizeBoxOrientation, normalizeBoxSpacing } from './box.js';
 export type { BoxOrientation } from './box.js';
 export { DEFAULT_LABEL_ELLIPSIZE, DEFAULT_LABEL_LINES, DEFAULT_LABEL_MAX_WIDTH_CHARS, DEFAULT_LABEL_WIDTH_CHARS, DEFAULT_LABEL_WRAP_MODE, DEFAULT_LABEL_XALIGN, DEFAULT_LABEL_YALIGN, LABEL_ELLIPSIZE_MODES, LABEL_JUSTIFICATIONS, LABEL_WRAP_MODES, labelDisplayText, labelEffectiveLines, labelEllipsizeOverflowValue, labelMarkupIsUnparseable, labelWidthCharsExtent, labelYalignAlignItems, normalizeLabelEllipsize, normalizeLabelJustify, normalizeLabelLines, normalizeLabelMaxWidthChars, normalizeLabelWidthChars, normalizeLabelWrapMode, normalizeLabelXalign, normalizeLabelYalign, } from './label.js';
 export type { LabelAlignItems, LabelEllipsizeMode, LabelJustification, LabelWidthCharsExtent, LabelWrapMode, } from './label.js';
 export { glibClamp, gStrStrip, stringIsNotEmpty } from './glib.js';
 export { AppLaunchContext as GdkAppLaunchContext, ContentFormats, ContentProvider, Clipboard, Display, createGdk, widgetDisplayMembers, } from './gdk.js';
-export { CURRENT_TIME, CssProvider, EventControllerKey, GDK_KEYS, GtkSettings, IconTheme, STYLE_PROVIDER_PRIORITY_APPLICATION, STYLE_PROVIDER_PRIORITY_FALLBACK, STYLE_PROVIDER_PRIORITY_SETTINGS, STYLE_PROVIDER_PRIORITY_THEME, STYLE_PROVIDER_PRIORITY_USER, createGtkPlatform, keyvalOfKey, widgetControllerMembers, } from './gtk-platform.js';
+export { CURRENT_TIME, CssProvider, EventControllerKey, GDK_KEYS, GtkSettings, IconTheme, STYLE_PROVIDER_PRIORITY_APPLICATION, STYLE_PROVIDER_PRIORITY_FALLBACK, STYLE_PROVIDER_PRIORITY_SETTINGS, STYLE_PROVIDER_PRIORITY_THEME, STYLE_PROVIDER_PRIORITY_USER, createGtkPlatform, deliverKeyToControllers, keyvalOfKey, widgetControllerMembers, } from './gtk-platform.js';
 export type { GtkPlatform, HostKeyEvent, PlatformHost } from './gtk-platform.js';
 export { iconLookupNames, lookupResourceIcon } from './icon-theme-resources.js';
 export type { IconDirection, ResourceIconMatch, ResourceIconRequest } from './icon-theme-resources.js';
@@ -130,7 +132,7 @@ export { ADW_WRAP_BOX_DEFAULT_ALIGN, ADW_WRAP_BOX_DEFAULT_JUSTIFY, ADW_WRAP_BOX_
 export type { AdwWrapBoxJustify, AdwWrapBoxOrientation, AdwWrapBoxPackDirection, AdwWrapPolicy, WrapBoxChildFlex, WrapBoxChildOrderOp, WrapBoxFlexInput, WrapBoxFlexStyle, WrapBoxLineLayout, } from './wrap-box.js';
 export { ADW_SOURCE_6502_DIRECTIVES, ADW_SOURCE_6502_LINE_COMMENT, ADW_SOURCE_6502_OPCODES, ADW_SOURCE_6502_REGISTERS, ADW_SOURCE_6502_TOKEN_ROLES, ADW_SOURCE_HEX_STRIDE, ADW_SOURCE_PALETTE_DARK, ADW_SOURCE_PALETTE_LIGHT, ADW_SOURCE_SYNTAX_ROLES, classifyAsm6502Word, formatHexAddress, formatLineNumber, stripSourceWhitespace, tokenizeAsm6502, } from './source.js';
 export type { AdwSourcePalette, AdwSourceSyntaxRole, AdwSourceTokenClass, AdwSourceTokenStream } from './source.js';
-export { GObjectObject, META_SYMBOLS, ParamFlags, ParamSpec, Value, TYPE_BOOLEAN, TYPE_DOUBLE, TYPE_INT, TYPE_STRING, TYPE_UINT, UnsupportedGObjectError, bindProperties, connectInstance, constructRegistered, createClosure, createGObject, disconnectInstance, emitInstance, gobjectEngineName, notifyInstance, PURE_JS_ENGINE, registeredClassOf, registerBaseClass, STOP_EMISSION, usePureJsGObjectEngine, type StoppableEmitter, UNLOCKED_VFUNCS, GIR_TYPE, } from './gobject.js';
+export { GObjectObject, ListModel, META_SYMBOLS, ParamFlags, ParamSpec, Value, TYPE_BOOLEAN, TYPE_DOUBLE, TYPE_INT, TYPE_OBJECT, TYPE_STRING, TYPE_UINT, UnsupportedGObjectError, bindProperties, connectInstance, constructRegistered, createClosure, createGObject, disconnectInstance, emitInstance, gobjectEngineName, notifyInstance, PURE_JS_ENGINE, refuseForeignInterfaces, registeredClassOf, registerBaseClass, STOP_EMISSION, usePureJsGObjectEngine, type StoppableEmitter, UNLOCKED_VFUNCS, GIR_TYPE, } from './gobject.js';
 export { ApplicationFlags, ApplicationInhibitFlags, GioApplicationBase, GtkApplicationBase, withGtkApplication, defineWindowApplicationMembers, dispatchAccelerator, isValidApplicationId, } from './application.js';
 export { CloseRequestState, HandledAccumulator, WindowMemberState, stepDefaultSize } from './window-members.js';
 export type { CloseOutcome, CloseRequestSteps, DefaultSizeProperty, DefaultSizeStep, WindowCommon, WindowMemberInit, WindowMemberProperty, } from './window-members.js';
@@ -139,9 +141,9 @@ export type { Accelerator } from './accelerators.js';
 export type { ApplicationHost, GtkApplicationMembers, GtkApplicationConstructor } from './application.js';
 export { ActionRegistry, SimpleAction, actionRegistryOf, activateWidgetAction, applicationOfWindow, findActionGroup, insertActionGroup, installActionMap, linkWindow, SimpleActionGroup, } from './gio-actions.js';
 export type { ActionActivateHandler, ActionGroupLike, ActionLike, SimpleActionProps } from './gio-actions.js';
-export type { Binding, BindingFlag, BlueprintTemplate, BuiltTemplate, ClassLike, ClassMeta, GObjectConstructor, GObjectDoor, GObjectInstance, GObjectNamespace, GType, ParamKind, RegisterClass, RegisteredClass, SignalHandler, SignalMeta, TemplateScope, } from './gobject.js';
+export type { Binding, BindingFlag, BlueprintTemplate, BuiltTemplate, ClassLike, ClassMeta, GInterface, GObjectConstructor, GObjectDoor, GObjectInstance, GObjectNamespace, GType, ParamKind, RegisterClass, RegisteredClass, SignalHandler, SignalMeta, TemplateScope, } from './gobject.js';
 export { engineForTarget, registerGObjectEngine, registeredEngine, resetRegisteredEngine } from './engine.js';
-export type { EngineTarget, ForeignClassMeta, ForeignProperty, ForeignPropertyKind, ForeignSignal, GObjectEngine, } from './engine.js';
+export type { EngineTarget, ForeignClassMeta, ForeignObjectProperty, ForeignProperty, ForeignPropertyKind, ForeignScalarKind, ForeignScalarProperty, ForeignSignal, GObjectEngine, } from './engine.js';
 export { MAXUINT32, buildFilenamev, getCurrentDir, getSystemDataDirs } from './glib-paths.js';
 export { uriEscapeString } from './glib-uri.js';
 export { computeLanguageNames, languageNamesFromTags, localeFromLanguageTag } from './glib-language.js';

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

@@ -138,10 +138,10 @@ export declare class ListViewState {
      * 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.
+     * differs from `ComboState`, whose model write resets the selection to 0:
+     * `GtkSingleSelection:autoselect` 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 reset.
      */
     setModel(model: readonly AdwComboOption[] | null | undefined): void;
     /** `Gtk.SelectionModel` choice. Narrowing it drops what the new mode cannot hold. */

package/lib/types/list.d.ts

@@ -16,8 +16,34 @@ export type AdwComboOptionInput = string | {
 };
 /** A normalised portable list model — what a `model` property holds on every surface. */
 export type AdwListModel = ReadonlyArray<AdwComboOption>;
-/** What a `model` property ACCEPTS: the widened form of {@link AdwListModel}. */
-export type AdwListModelInput = ReadonlyArray<AdwComboOptionInput>;
+/**
+ * The two methods this module needs off a REAL model — `g_list_model_get_n_items` and
+ * `g_list_model_get_item`, nothing else.
+ *
+ * Duck-typed on purpose. This module is pure data and must not import `Gtk.StringList`, which
+ * is a GObject and would drag the whole object system into every surface that only wants to
+ * normalise items. `Gio.ListModel` IS these two methods, so matching them is matching the
+ * interface rather than guessing at a class.
+ */
+export interface AdwListModelSource {
+    /** `g_list_model_get_n_items`. */
+    get_n_items(): number;
+    /** `g_list_model_get_item` — `null` past the end. */
+    get_item(position: number): unknown;
+}
+/**
+ * What {@link normalizeComboOptions} ACCEPTS: the widened form of {@link AdwListModel}, plus a
+ * real {@link AdwListModelSource}.
+ *
+ * IT IS THE NORMALISER'S INPUT TYPE AND NOT A PROPERTY TYPE, which is the whole of what ADR
+ * 0122 § 6 changed about it. `Adw.ComboRow:model` and `Gtk.DropDown:model` are a
+ * `Gio.ListModel` and nothing else now — an array assigned to either is a `TypeError` naming
+ * the type. The union stays because the AUTHORED vocabulary is still both: a JSON markup
+ * attribute parses to an array, a `Gtk.StringList` handed to `GjsifyOptionList` is a model,
+ * and both arrive here on their way to becoming descriptors. The arms are the two forms a
+ * caller can WRITE DOWN, not the two values a property will take.
+ */
+export type AdwListModelInput = ReadonlyArray<AdwComboOptionInput> | AdwListModelSource;
 /**
  * Raw authored items → the stable `{ value, label }` descriptors every list surface
  * works with.
@@ -28,6 +54,11 @@ export type AdwListModelInput = ReadonlyArray<AdwComboOptionInput>;
  * by `undefined`. ONE home for the rule, so no two list widgets can accept two different
  * item vocabularies.
  *
+ * A REAL `Gio.ListModel` is read through {@link AdwListModelSource}, and its items through the
+ * same three rules as any other entry: a `Gtk.StringObject` arrives as the string it holds,
+ * anything else falls to the descriptor rule it already matches or does not. There is no
+ * fourth vocabulary for items that came out of a model rather than out of an array.
+ *
  * TOTAL — it throws for no input. The doors this reaches are a property assignment and a
  * markup attribute, and an author's typo must not take the widget down.
  */
@@ -55,23 +86,6 @@ export declare function parseListModel(raw: string | null | undefined): AdwCombo
  * draw a placeholder has nothing to test.
  */
 export declare const ADW_COMBO_NO_SELECTION = -1;
-/**
- * Where a selection lands after the model under it was REPLACED.
- *
- * `GtkSingleSelection` autoselects, so a position the new model does not have falls back
- * to 0 — including the sentinel, which is how a widget recovers a selection when its model
- * grows. An EMPTY model has no 0 to fall back to and lands on
- * {@link ADW_COMBO_NO_SELECTION}.
- *
- * The test is membership and not `selected >= length`: the sentinel is BELOW the range, so
- * a one-sided comparison leaves a `-1` in place and a model that was emptied and refilled
- * comes back with nothing selected.
- *
- * Lifted out of `ComboState.setModel` so a second list widget cannot re-derive it. The
- * cross-renderer rule it encodes was already conformance data — `conformance/rows.ts`
- * carries it as "the ports' shared answer" — it just had no name of its own.
- */
-export declare function clampListSelection(selected: number, length: number): number;
 /**
  * One positional change — `Gio.ListModel::items-changed`'s own three parameters.
  *

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

@@ -0,0 +1,128 @@
+import { GObjectObject, type GType } from './gobject.js';
+import { type AdwComboOption, type AdwComboOptionInput } from './list.js';
+import type { ComboWatchableModel } from './rows.js';
+/**
+ * One selectable item, as the `GObject` a `GListModel` is allowed to hand out.
+ *
+ * Both properties are READ-ONLY, and that is not caution: an item is what a model contains, and
+ * a model reports a content change through `items-changed`. A writable `label` would let the
+ * text under a selection move with nothing emitted, which is the failure
+ * `GtkStringObject`'s read-only `string` exists to prevent.
+ *
+ * It deliberately has NO `string` property. `readListModel` unwraps an item that has one as a
+ * bare string — that is `Gtk.StringObject`'s shape — and an option that answered to it would
+ * lose its `value` on the way out, which is the whole reason this type exists.
+ */
+export declare class GjsifyOptionObject extends GObjectObject {
+    constructor(props?: Record<string, unknown> | null);
+    /** An item holding `value` and `label` — the only way to put either in one. */
+    static new(value: string, label: string): GjsifyOptionObject;
+    /** An item for one authored entry, through the normaliser every surface already shares. */
+    static fromInput(entry: AdwComboOptionInput): GjsifyOptionObject;
+    /** The value this item is addressed by. */
+    get value(): string;
+    set value(_value: string);
+    /** The text this item draws as. */
+    get label(): string;
+    set label(_value: string);
+    /** The descriptor this item holds, as a COPY — nothing hands out the stored record. */
+    toOption(): AdwComboOption;
+}
+/** What `new GjsifyOptionList({ … })` takes. */
+export interface GjsifyOptionListProps {
+    /** The options the list starts with, in any form {@link normalizeComboOptions} accepts. */
+    options?: readonly AdwComboOptionInput[] | null;
+}
+/**
+ * A `Gio.ListModel` of {@link GjsifyOptionObject}s — what a `model` property holds once the
+ * array door is closed.
+ *
+ * `new GjsifyOptionList()` is empty. The instance is a GObject with a real identity, so a
+ * `model` write that assigns the SAME list again is the no-op GTK makes it, and
+ * `row.model === list` answers true.
+ */
+export declare class GjsifyOptionList extends GObjectObject {
+    /** Installed by the core from {@link ListModel}; declared here for the type alone. */
+    readonly get_item: (position: number) => GjsifyOptionObject | null;
+    readonly get_item_type: () => GType;
+    readonly get_n_items: () => number;
+    readonly items_changed: (position: number, removed: number, added: number) => void;
+    constructor(props?: GjsifyOptionListProps | null);
+    /** A list holding `options`, or an empty one for `null` — the markup door's constructor. */
+    static new(options: readonly AdwComboOptionInput[] | null): GjsifyOptionList;
+    /** The item type, which here is the specific one: this list holds nothing else. */
+    get item_type(): GType;
+    set item_type(_value: GType);
+    get itemType(): GType;
+    set itemType(_value: GType);
+    /** `n-items` — the `ParamSpec`'s reader, and `get_n_items`'s answer. */
+    get n_items(): number;
+    set n_items(_value: number);
+    /** `vfunc_get_item_type` — what the interface's `get_item_type()` calls through to. */
+    vfunc_get_item_type(): GType;
+    /** `vfunc_get_n_items`. */
+    vfunc_get_n_items(): number;
+    /** `vfunc_get_item` — `null` past the end, as `g_list_model_get_item` returns `NULL`. */
+    vfunc_get_item(position: number): GjsifyOptionObject | null;
+    /** The descriptors this list holds, as copies — the form every renderer draws from. */
+    toOptions(): AdwComboOption[];
+    /** One more option at the end. */
+    append(option: AdwComboOptionInput): void;
+    /** The option at `position`, which must be in range. */
+    remove(position: number): void;
+    /**
+     * `g_list_store_splice(position, n_removals, additions)` — the C signature, all three
+     * arguments, additions as ONE array, so a hundred-item replacement is one emission.
+     *
+     * Out of range is a CRITICAL and a no-op rather than an exception, which is the shape
+     * `Gtk.StringList` measured for the same call: this door is reachable from a markup
+     * attribute, and an author's slip must not take the widget down.
+     */
+    splice(position: number, nRemovals: number, additions: readonly AdwComboOptionInput[] | null): void;
+    /**
+     * The POSITION of the first option with this value, {@link INVALID_LIST_POSITION} when there
+     * is none — `gtk_string_list_find`'s meaning of the name, over the half a descriptor is
+     * addressed by.
+     */
+    find(value: string): number;
+    /**
+     * Replace the contents with `next` IN PLACE, as the ONE splice that turns one into the
+     * other — {@link listItemsChanged}'s minimal range.
+     *
+     * This is the markup door's update path and it keeps the list's IDENTITY, which is what
+     * makes it different from a `model` write. Re-parsing an attribute must not look to the
+     * widget like a new model: a model REPLACEMENT re-runs autoselect and resets the selection
+     * to 0 (ADR 0122 § 4, measured), while appending one option to the end of the list the
+     * widget already holds moves nothing. An author editing `model='[…]'` means the second.
+     */
+    reconcile(next: readonly AdwComboOptionInput[] | null): void;
+    /** The one mutation, so the emission rule is written once. See the file header. */
+    private spliceItems;
+}
+/**
+ * What a write to a `model` property reads as — the ONE door, for all four surfaces.
+ *
+ * ADR 0122 § 6 makes `model` an object property over `Gio.ListModel`, and § 5 leaves the JSON
+ * markup attribute open, so every `model` setter in this repository has the same three-way
+ * answer to give. It is written here once because it was about to be written four times:
+ *
+ *   - a real model — anything with `get_n_items` and `get_item`, which is what
+ *     {@link AdwListModelSource}'s docblock argues is the test — is handed through by IDENTITY,
+ *     so `widget.model === model` holds as it is measured to in libadwaita;
+ *   - `null` / `undefined` is the "no model" write, which notifies `model` alone;
+ *   - a STRING is the markup attribute, parsed and reconciled into `authored` — the surface's
+ *     OWN list, whose identity survives the edit so an author appending one option to
+ *     `model='[…]'` gets one splice instead of a replacement that resets the selection;
+ *   - anything else, an ARRAY above all, is a `TypeError`.
+ *
+ * THE REFUSAL IS THE PROPERTY'S, not a second opinion: the message comes out of
+ * {@link checkPropertyValue} against `model`'s own ParamSpec, which is where GJS's measured
+ * wording lives. Reaching it is already the failure case, and it always throws for a value that
+ * gets that far — the one thing it accepts is a registered implementor of `Gio.ListModel`, and
+ * the interface installs the two getters the duck test above just failed to find.
+ *
+ * The duck test and not `checkPropertyValue` alone, because a REAL `Gio.ListStore` reached
+ * through node-gi (ADR 0104) is no registered class of this subset and `implementsInterface`
+ * would refuse it — and handing one to `Adw.ComboRow:model` is the whole point of having it.
+ */
+export declare function readModelWrite(value: unknown, authored: GjsifyOptionList): ComboWatchableModel | null;

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

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