@gjsify/gtk-host 0.48.0 → 0.49.0

package/lib/types/types.d.ts

@@ -107,13 +107,32 @@ export type HostNode = HostElement | HostText | HostAnchor;
  * accepts the very same append in silence at exit 0 — re-testing this on a bare
  * box "disproves" it and puts the append back.
  *
+ * THE ABORT IS THE LOUD HALF OF A CLASS, and its quiet half arrives through the
+ * same door (ADR 0054). MEASURED on the same libraries, one process per case:
+ * `box.append(new Gtk.Window())` with the box rooted is **exit 0, silent**, and
+ * afterwards `win.get_parent()` is the box while `win.get_root()` is the window
+ * ITSELF — a `GtkRoot` with a parent, which is a contradiction GTK states nowhere.
+ * Presenting that window then draws it as a toplevel AND leaves it in the box's
+ * child list, so the container measures and allocates a window. One node kind
+ * aborts, its neighbour says nothing; both are the same question answered wrong,
+ * so both are answered here.
+ *
  * So the descriptor declares the axis, and `policies.ts` is the only reader.
  * `parented` is every other widget and is what an ABSENT `placement` means; the
  * union still cannot be forgotten because there is exactly one normaliser
  * (`placementOf`) and every switch over it ends in `unhandledPlacement`.
  */
 export type NodePlacement = 
-/** The parent's `ChildPolicy` places it. Every widget but the dialog family. */
+/**
+ * The parent's `ChildPolicy` places it — every widget but the two families below.
+ *
+ * DECLARING it is not the same as leaving it out, and the difference is an
+ * escape hatch rather than a nicety: the host refuses a node whose CLASS says
+ * it cannot be parented (`unparentableChild`), and that refusal fires only
+ * where the descriptor is SILENT. A consumer whose own widget trips the
+ * structural oracle — a `present(parent)` method on a widget that really is a
+ * child — writes this arm and is placed by its parent again.
+ */
 {
     readonly kind: 'parented';
 }
@@ -141,6 +160,44 @@ export type NodePlacement =
     readonly kind: 'portal';
     readonly present: string;
     readonly close: string;
+}
+/**
+ * The node IS a root: `present()` / `destroy()`, and no parent anywhere.
+ *
+ * WHAT SEPARATES IT FROM A PORTAL IS THE ARITY, and that is a fact about the
+ * two libraries rather than a convention: measured, `adw_dialog_present` takes
+ * 1 argument and `gtk_window_present` takes 0. A portal has two positions in
+ * the tree and the parent is what joins them; a toplevel has ONE, its own, so
+ * there is nothing to present it against. `descriptorProblems()` holds both
+ * arities, so the two arms cannot be swapped by a copy/paste.
+ *
+ * MEMBERSHIP IS `Gtk.Root`, measured with `GObject.type_is_a` and not read
+ * from documentation — `GtkWindow` and `AdwApplicationWindow` down to
+ * `GtkPrintUnixDialog`. It is GTK's own word for "this widget is a toplevel",
+ * which is why the generic code asks it instead of forming a second opinion,
+ * and `placement.spec.ts` is where the membership is walked and counted.
+ *
+ * `close: 'destroy'` IS THE FORCED ONE, the same choice the portal arm makes
+ * and for the same measured reason. On GTK 4.22.4: `gtk_window_close()` emits
+ * `close-request`, and a handler returning TRUE leaves the window mapped and
+ * visible — which is exactly how an application vetoes a user's close. An
+ * unmount is not a user request, so the conditional call is the wrong one;
+ * `gtk_window_destroy()` takes it down regardless. Both are silent on a window
+ * that was never presented (measured), so the host needs no "is it up?" probe.
+ *
+ * AND THE FORCED CALL IS TERMINAL HERE, which is where this arm stops being a
+ * copy of the portal one. MEASURED: `present()` after either `close()` or
+ * `destroy()` answers `Gtk-WARNING **: A window is shown after it has been
+ * destroyed. This will leave the window in an inconsistent state.` — GTK4's
+ * default `close-request` handler destroys the window, so `close()` is a
+ * conditional destroy rather than a hide. A retracted toplevel is therefore
+ * gone for good, and a re-mount is a fresh widget (which is what `rebuild`
+ * already does for a construct-only write).
+ */
+ | {
+    readonly kind: 'toplevel';
+    readonly present: string;
+    readonly close: string;
 };
 export type PolicyKind = 'none' | 'single' | 'ordered' | 'indexed' | 'slotted' | 'keyed' | 'coords';
 /**
@@ -176,12 +233,52 @@ export type ChildPolicy = {
     remove: string;
     reorder: 'native' | 'remove-all';
 }
-/** `Gtk.ListBox`/`Gtk.FlowBox`: index-addressed, and the parent addresses a WRAPPER row. */
+/**
+ * `Gtk.ListBox`/`Gtk.FlowBox`: index-addressed, and the parent addresses a WRAPPER row.
+ *
+ * `perLineCap` names a property the host keeps EQUAL TO THE CHILD COUNT, and
+ * `Gtk.FlowBox:max-children-per-line` is the only one. It is a cap, so every
+ * value at or above the child count lays the children out identically — and
+ * that equivalence is exactly what hid the cost, because GTK MEASURES THE CAP
+ * RATHER THAN THE CHILDREN.
+ *
+ * MEASURED on GTK 4.22.4, one `Gtk.FlowBox` holding TWO children, per
+ * HEIGHT-FOR-WIDTH measure — `measure(VERTICAL, 400)`, which is the one a
+ * container in a window asks for:
+ *
+ * | cap | 7 | 64 | 1024 | 8192 | 32768 | 65535 |
+ * | --- | --- | --- | --- | --- | --- | --- |
+ * | ms | 0.021 | 0.025 | 0.43 | 18.6 | 391.5 | 1393.2 |
+ *
+ * Quadratic in the cap, so "as many as fit" spelled as G_MAXUINT cost a second
+ * and a half to measure two chips, and a real application froze its main loop
+ * for 12.7 s at startup over five two-child rows. The ORIENTATION is part of
+ * the claim and not a detail: `measure(HORIZONTAL, -1)` stays under 0.1 ms at
+ * every one of those caps, so a re-measurement that asks for the width alone
+ * reproduces none of this.
+ *
+ * The cap is wrong in the ANSWER too, not only in what the answer costs.
+ * Natural width is `content + column-spacing × (cap - 1)` — measured, exactly,
+ * over five caps — so a cap above the child count `n` carries
+ * `column-spacing × (cap - n)` px of gaps that do not exist. 12 children at
+ * `column-spacing: 8`: 683 px natural at a cap of 12 and 524 867 px at 65535,
+ * the excess exactly 8 × 65 523. At `column-spacing: 0` there is no difference
+ * at all, which is how a pinned cap passed for as long as it did.
+ *
+ * The child count is the exact answer rather than a smaller cap chosen to be
+ * safe: a line can never hold more children than exist, so it forbids nothing
+ * G_MAXUINT allowed, and it is the largest value that costs nothing.
+ *
+ * An AUTHORED value wins. `<GtkFlowBox maxChildrenPerLine={3}>` is someone
+ * asking for three per line, and a sync that overwrote it would be the same
+ * silent kind of wrong this field exists to remove.
+ */
  | {
     kind: 'indexed';
     insert: string;
     remove: string;
     wrap: 'list-box-row' | 'flow-box-child' | null;
+    perLineCap?: string;
 }
 /**
  * `Adw.HeaderBar`, `Adw.ToolbarView`, `Adw.ActionRow`: named attachment points.

package/lib/types/vue-components.d.ts

@@ -33,11 +33,11 @@
  * resolve goes unchecked.
  */
 import type { DefineComponent } from '@vue/runtime-core';
-import type { VueAttributes, WithOnce, WithPortableMenu } from './attrs.js';
+import type { VueAttributes, WithOnce, WithPortableValues } from './attrs.js';
 import type { WidgetPropsByGType, WidgetPropsVueAliases } from './generated/props.js';
 type VueWidgetProps = WidgetPropsByGType & WidgetPropsVueAliases;
 export type GtkGlobalComponents = {
-    [K in keyof VueWidgetProps]: DefineComponent<WithOnce<WithPortableMenu<VueWidgetProps[K]>> & VueAttributes>;
+    [K in keyof VueWidgetProps]: DefineComponent<WithOnce<WithPortableValues<VueWidgetProps[K]>> & VueAttributes>;
 };
 declare module '@vue/runtime-core' {
     interface GlobalComponents extends GtkGlobalComponents {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gtk-host",
-    "version": "0.48.0",
+    "version": "0.49.0",
     "description": "Framework-agnostic GTK4/Adwaita host: the element model UI-framework renderers bind to",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -80,7 +80,9 @@
         "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
         "test:gjs": "gjsify run test.gjs.mjs",
         "test:gjs-on-node": "gjsify run build:gjsify && gjsify run build:test:node && node dist/test.node.mjs",
-        "generate": "gjsify build src/generator/main.mts --app gjs --outfile tmp/generate.gjs.mjs && gjsify run tmp/generate.gjs.mjs -- --out src/generated && gjsify format src/generated"
+        "generate": "gjsify build src/generator/main.mts --app gjs --outfile tmp/generate.gjs.mjs && gjsify run tmp/generate.gjs.mjs -- --out src/generated && gjsify format src/generated",
+        "generate:enum-values": "gjs -m ../../../scripts/generate-enum-values.mjs",
+        "generate:methods": "gjs -m ../../../scripts/generate-widget-methods.mjs"
     },
     "keywords": [
         "gjs",
@@ -99,7 +101,7 @@
         "@girs/gtk-4.0": "4.6.0",
         "@girs/pango-1.0": "4.6.0",
         "@girs/pangocairo-1.0": "4.6.0",
-        "@gjsify/adwaita-core": "^0.48.0"
+        "@gjsify/adwaita-core": "^0.49.0"
     },
     "peerDependencies": {
         "@vue/runtime-core": "^3.5.0",
@@ -122,10 +124,10 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.48.0",
+        "@gjsify/cli": "^0.49.0",
         "@vue/runtime-core": "^3.5.0",
         "solid-js": "^1.9.0",
-        "@gjsify/unit": "^0.48.0",
+        "@gjsify/unit": "^0.49.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",