@gjsify/gtk-host 0.53.0 → 0.55.0

package/lib/types/host.d.ts

@@ -24,23 +24,22 @@ export declare function setEventHandler(el: HostElement, prop: string, next: ((.
 /**
  * The ARIA object, diffed against the one it replaces.
  *
- * ONE GROUPED PROP RATHER THAN 53 FLAT `aria*` ONES, and the reasons are measured rather
- * than aesthetic. (1) TypeScript exempts every hyphen-containing JSX attribute from
- * excess-property checking — the measurement `emit-types.mts` already records for the
- * kebab property spellings — so a flat `aria-labell` would be accepted in silence, while a
- * key inside a fresh object literal IS checked. (2) The ARIA names are not the widget's
- * properties and collide with them: `label`, `orientation`, `checked`, `expanded` and
- * `selected` are all both, and `orientation` is settable on a `GtkLabel` that implements no
- * `GtkOrientable` at all — one object keeps the two vocabularies apart by construction
- * instead of by prefix. (3) The other surface over this same vocabulary already spells it
- * this way: a `.blp` author writes `accessibility { label: "…"; }` (ADR 0034). (4) `setProp`
- * already has this shape for `layout` — a structured, non-ParamSpec prop routed to its own
- * mechanism — so this adds one reserved key to the host, not 53.
+ * ONE GROUPED PROP RATHER THAN 53 FLAT `aria*` ONES, for measured reasons. (1)
+ * TypeScript exempts every hyphen-containing JSX attribute from excess-property checking —
+ * the measurement `emit-types.mts` already records for the kebab property spellings — so a
+ * flat `aria-labell` would be accepted in silence, while a key inside a fresh object literal
+ * IS checked. (2) The ARIA names collide with the widget's own properties: `label`,
+ * `orientation`, `checked`, `expanded` and `selected` are all both, and `orientation` is
+ * settable on a `GtkLabel` that implements no `GtkOrientable` at all — one object keeps the
+ * two vocabularies apart by construction instead of by prefix. (3) The other surface over
+ * this vocabulary already spells it this way: a `.blp` author writes `accessibility {
+ * label: "…"; }` (ADR 0034). (4) `setProp` already has this shape for `layout`, so this adds
+ * one reserved key to the host, not 53.
  *
  * REFUSED ON THE CLASS, not on the widget: every framework builds bottom-up, so props are
  * authored long before materialisation, and asking the instance would report
- * `<gtk-string-list accessibility={…}>` from inside a later `materialize` rather than at the
- * call that wrote it.
+ * `<gtk-string-list accessibility={…}>` from inside a later `materialize` rather than at
+ * the call that wrote it.
  *
  * The plan is built BEFORE anything is recorded, for the reason the property path states:
  * `el.accessibility` is replayed verbatim by `replayInto`, so a refused value kept there
@@ -55,32 +54,23 @@ export declare function insert(node: HostNode, parent: HostElement, anchor?: Hos
 /**
  * TWO facts, not one: it says it is an element, and it carries a descriptor.
  *
- * `kind` alone is a plain string a GObject wrapper could carry; the descriptor is
- * what every host op actually dereferences. Checking both keeps the refusal from
- * being either paranoid or fooled.
+ * `kind` alone is a plain string a GObject wrapper could carry; the descriptor is what
+ * every host op actually dereferences. Checking both keeps the refusal from being either
+ * paranoid or fooled.
  *
- * Exported because the Vue adapter had these same two lines VERBATIM, and its own
- * comment said so — it needs the question before `adopt`, to tell a host parent
- * from the raw widget `<Teleport :to="el">` hands through. A predicate stated in
- * two places is a predicate that can disagree with itself about what a node is.
+ * Exported because the Vue adapter needs the question before `adopt`, to tell a host
+ * parent from the raw widget `<Teleport :to="el">` hands through.
  */
 export declare function isHostElement(value: unknown): value is HostElement;
 /**
  * Name a foreign value the way its owner would recognise it.
  *
- * ONE function, because there were two and each was wrong for the other's input.
- * The host's read `constructor.$gtype`, so it could not name a DOM element — the
- * single most likely thing to arrive from a Solid app that imported `<Dynamic>`
- * from `solid-js/web`. The Solid adapter's read `tagName`, so it answered
- * `a Object` for the GObject wrapper `<Teleport :to="el">` hands over. Both are
- * asking "what did I get instead of a node", so both answers belong to one place.
- *
- * ORDER IS LOAD-BEARING, and it is measured rather than reasoned: under gjs
- * 1.88.1 `({}).constructor.$gtype` EXISTS and `GObject.type_name` calls it
- * `JSObject`. So a `$gtype`-first version names every object literal — and every
- * DOM-ish stub, which is an object literal — `JSObject`, and the host's own
- * documented `a plain object` fallback was unreachable for exactly the shape it
- * names. `tagName` first, and `JSObject` treated as the absence of a GType.
+ * ORDER IS LOAD-BEARING, and it is measured rather than reasoned: under gjs 1.88.1
+ * `({}).constructor.$gtype` EXISTS and `GObject.type_name` calls it `JSObject`. A
+ * `$gtype`-first version would therefore name every object literal — and every DOM-ish
+ * stub, which is an object literal — `JSObject`, and the `a plain object` fallback would be
+ * unreachable for exactly the shape it names. `tagName` first, `JSObject` treated as the
+ * absence of a GType.
  */
 export declare function describeValue(value: unknown): string;
 /** Detach only — reversible. Frameworks move nodes; `remove` must not destroy one. */
@@ -88,30 +78,25 @@ export declare function remove(node: HostNode): void;
 /**
  * Destroy every child of `parent`, bounded.
  *
- * Exported because both adapters wrote their OWN `childSnapshot` to do exactly this
- * — byte-identical to each other, and both walking `next` raw. That is the one walk
- * the bound above exists to make unforgettable, and it is the walk where the
- * malformed link actually appears: `insert(node, parent, node)` is a defined DOM
- * no-op, so Solid's adjacent-swap fast path emits it against a CONTAINER's child
- * list. Unbounded, that is a hang rather than GTK's usual exit 0.
- *
- * This replaces a `clearContainer` that had no callers anywhere and DETACHED rather
- * than destroyed — the wrong half for every caller that wanted it, and a name React's
- * own HostConfig already uses for the destroying kind.
+ * Every walk over `next` goes through `childSnapshot` so the bound cannot be forgotten at a
+ * new call site, and this is the walk where the malformed link actually appears: `insert(
+ * node, parent, node)` is a defined DOM no-op, so Solid's adjacent-swap fast path emits it
+ * against a CONTAINER's child list. Unbounded, that is a hang rather than GTK's usual
+ * exit 0.
  */
 export declare function destroyChildren(parent: HostElement): void;
 /**
  * Disconnect a node's handlers WITHOUT touching the tree.
  *
- * The narrow half of `destroy`, and it exists because a framework can tell us "this
- * node is gone" while still holding its sibling links: Solid disposes a per-node
- * scope BEFORE its reconciler runs, and `reconcileArrays` opens with
- * `getNextSibling(last)`. Unlinking there made every trailing insertion append at
- * the end of the parent instead of before the marker.
+ * The narrow half of `destroy`, and it exists because a framework can tell us "this node is
+ * gone" while still holding its sibling links: Solid disposes a per-node scope BEFORE its
+ * reconciler runs, and `reconcileArrays` opens with `getNextSibling(last)`. Unlinking there
+ * made every trailing insertion append at the end of the parent instead of before the
+ * marker.
  *
- * The leak this closes is about handlers, not links — GJS blocks JS callbacks
- * during GC, so an undisconnected handler outlives its widget. The framework's own
- * `removeNode` still does the unlinking, in its own order.
+ * The leak this closes is about handlers, not links — GJS blocks JS callbacks during GC, so
+ * an undisconnected handler outlives its widget. The framework's own `removeNode` still
+ * does the unlinking, in its own order.
  */
 export declare function disconnectHandlers(el: HostElement): void;
 /**
@@ -128,43 +113,36 @@ export declare function destroy(node: HostNode): void;
 /**
  * Put a host tree inside an existing GTK container the application owns.
  *
- * The container is resolved through the SAME table as every other parent —
- * `nearestRegistered` walks the real type hierarchy, so an application's own
- * `GObject.registerClass` subclass inherits its ancestor's policy. Guessing a
- * method name here would be the generic `add` that GTK4 deliberately removed.
+ * The container is resolved through the SAME table as every other parent, so an
+ * application's own `GObject.registerClass` subclass inherits its ancestor's policy.
+ * Guessing a method name here would be the generic `add` that GTK4 deliberately removed.
  */
 export declare function mountRoot(el: HostElement, container: GObject.Object): void;
 /**
  * The materialised widget of a host node — for a `ref`, or for a test.
  *
- * ONE implementation. The Solid and React adapters each carried this function,
- * identical apart from two comment lines, and Vue carried none — so a Vue app had
- * no supported way to reach a widget at all and its only route was
- * `materialize()`, which is exactly the call the `destroyed` guard below exists to
- * intercept.
+ * ONE implementation, because a caller reaching `materialize()` directly is exactly what the
+ * `destroyed` guard below exists to intercept.
  *
- * The flag is exact and the obvious heuristic is not: `materialize` would happily
- * build a fresh, propertyless, unparented widget for a destroyed node — `destroy`
- * clears `props` and `layout` precisely so one cannot look re-materialisable — and
- * "no widget, not attached, no props" also describes a brand-new element.
+ * The flag is exact and the obvious heuristic is not: `materialize` would happily build a
+ * fresh, propertyless, unparented widget for a destroyed node — `destroy` clears `props`
+ * and `layout` precisely so one cannot look re-materialisable — and "no widget, not
+ * attached, no props" also describes a brand-new element.
  */
 export declare function widgetOf(node: HostNode): Gtk.Widget;
 /**
  * An off-screen container the host owns — the analogue of the DOM's detached `<div>`.
  *
- * `<KeepAlive>` and `<Suspense>` ask a renderer for one: `KeepAliveImpl.setup`
- * opens with `createElement("div")` and `SuspenseImpl` does the same for its
- * `hiddenContainer`. Forwarded as a TAG, "div" reached `lookupWidget` and threw
- * `unknown-tag` inside `callWithErrorHandling`, whose production arm is
- * `console.error` with no rethrow: `mount()` returned normally, the container held
- * zero children, GTK said nothing, exit 0.
- *
- * The Vue adapter answered that with `adopt(new Gtk.Box())` — the one runtime
- * `gi://` import and the one concrete widget class in any adapter, i.e. the widget
- * knowledge ADR 0027 § 7 forbids. Which widget backs it is the table's business
- * (`makeDetachedContainer`), and this op is what leaves the adapter with nothing to
- * know: the deactivated subtree is really unparented from the visible tree and
- * really held alive, so reactivating it moves the SAME widgets back.
+ * `<KeepAlive>` and `<Suspense>` ask a renderer for one: `KeepAliveImpl.setup` opens with
+ * `createElement("div")` and `SuspenseImpl` does the same for its `hiddenContainer`.
+ * Forwarded as a TAG, "div" reached `lookupWidget` and threw `unknown-tag` inside
+ * `callWithErrorHandling`, whose production arm is `console.error` with no rethrow:
+ * `mount()` returned normally, the container held zero children, GTK said nothing, exit 0.
+ *
+ * Which widget backs it is the table's business (`makeDetachedContainer`), and this op is
+ * what leaves the adapter with nothing to know — the widget knowledge ADR 0027 § 7 forbids.
+ * The deactivated subtree is really unparented from the visible tree and really held
+ * alive, so reactivating it moves the SAME widgets back.
  */
 export declare const createDetachedContainer: () => HostElement;
 /**