@girs/builder-1.0 4.7.0 → 4.9.0

package/README.md

@@ -4,7 +4,7 @@
 ![version](https://img.shields.io/npm/v/@girs/builder-1.0)
 ![downloads/week](https://img.shields.io/npm/dw/@girs/builder-1.0)
 
-GJS TypeScript type definitions for Builder-1.0 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v4.7.0.
+GJS TypeScript type definitions for Builder-1.0 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v4.9.0.
 
 This package contains type declarations only. It ships no runtime code, so it adds
 nothing to your program and works with any bundler or none at all.

package/builder-1.0-vocabulary.d.ts

@@ -226,6 +226,82 @@ export const CHILD_HOLDERS: readonly string[];
 /** Enum GType -> the nicks this surface offers. */
 export const ENUM_NICKS: Readonly<Record<string, readonly string[]>>;
 
+/**
+ * `<enum GType>.<nick>` -> the integer GObject registers for it, from GIR's `value`.
+ *
+ * Position in `ENUM_NICKS` is NOT this number. Counting is wrong on 6 of the 129 enums a
+ * GTK 4 vocabulary carries -- 104 in Gtk-4.0 and 25 in Adw-1: `GtkResponseType` runs -1 to -11, `GtkTextWindowType` starts
+ * at 1, `GtkOrdering` and `GtkConstraintRelation` are -1/0/1, `GtkAlign` has two names
+ * on one value, and `GtkConstraintStrength.required` is 1001001000 where counting says 0.
+ *
+ * Read from the same GIR as the nicks, deliberately. A consumer reading the numbers off an
+ * installed typelib instead has two provenances for one table, and then cannot tell a
+ * missing number from a host older than the vocabulary.
+ */
+export const ENUM_VALUES: Readonly<Record<string, number>>;
+
+/**
+ * The `<enum GType>.<nick>` entries GIR marks `deprecated="1"`.
+ *
+ * Two names on one value is how GObject spells an alias -- `GTK_ALIGN_BASELINE` and
+ * `GTK_ALIGN_BASELINE_FILL` are both 4, and both keep a `ENUM_VALUES` entry. The pairing
+ * is visible in the numbers; which name is the old one is not, and this is that fact --
+ * where GIR states it. It usually does not: 4 registered-enum members across the 718 GIRs
+ * carry the attribute, and 179 of the 182 value-sharing pairs carry it on neither half, so
+ * absence from this list means GIR is silent, not that the nick is the current one.
+ */
+export const ENUM_DEPRECATED: readonly string[];
+
+/**
+ * `<enum GType>.<nick>` -> the raw GIR `value` no number could be read from.
+ *
+ * The declared remainder, so that every nick in `ENUM_NICKS` is in `ENUM_VALUES` or in
+ * here and a drop cannot be silent. Two shapes reach it: a symbolic or absent value (Vala
+ * writes `(null)`, a char enum writes a letter) and an integer past
+ * `Number.MAX_SAFE_INTEGER`, where a literal would lose precision and stop being the
+ * GIR's number. Empty for Gtk, Adw, GLib and Gio.
+ */
+export const ENUM_VALUES_UNREADABLE: Readonly<Record<string, string>>;
+
+/**
+ * `<bitfield GType>.<nick>` -> the integer GObject registers for that one member.
+ *
+ * `ENUM_NICKS` carries no bitfield, because GObject cannot resolve a nick SET; that says
+ * nothing about a single member's number, and the number is what a host without GI needs.
+ * 21 writable widget properties in Gtk-4.0 and Adw-1 are bitfield-typed and are declared
+ * bare `number` -- `GtkEntry:input-hints`, `GtkPopoverMenu:flags`, `AdwTabView:shortcuts`
+ * among them. Counting is worst here: 95 of 121 Gtk-4.0 bitfield members disagree with their
+ * position, against 29 of 685 enumeration members.
+ *
+ * Combine with `|` as GObject does. There is no nick table to pair this with, so a name
+ * here is resolvable and a SET still is not.
+ */
+export const FLAG_VALUES: Readonly<Record<string, number>>;
+
+/** `<bitfield GType>.<nick>` -> the raw GIR `value` no number could be read from. */
+export const FLAG_VALUES_UNREADABLE: Readonly<Record<string, string>>;
+
+/**
+ * `<declaration GType>.<property>` -> the GType of that property's enum or bitfield.
+ *
+ * The join the value tables need and nothing else here carries. A host with no GI has a
+ * property name and a nick and needs a number; `ENUM_VALUES` is keyed by ENUM GType, and
+ * only this says which enum a property is. Keyed by DECLARATION like `OWN_PROPS`, so it is
+ * read at every link of a `DECLS` chain — `orientation` belongs to `GtkOrientable`, not
+ * to the `GtkBox` a caller starts from.
+ *
+ * Present only where the property's OWN type is the enum: an array of them, or a union that
+ * merely mentions one, would be an entry a consumer resolves wrongly.
+ *
+ * The GType named here is not always one THIS module gives numbers for. A nick vocabulary is
+ * emitted once, by the namespace that owns the enum, so `AdwComboRow.search-match-mode` names
+ * `GtkStringFilterMatchMode` and its rows are in `@girs/gtk-4.0/vocabulary` — 57 of the 438
+ * entries in a full run resolve only with the owner's vocabulary loaded beside this one. An
+ * owner with no vocabulary of its own (Gdk, Pango) is inlined here instead, so every entry
+ * resolves against SOME module.
+ */
+export const PROP_ENUMS: Readonly<Record<string, string>>;
+
 /** Widget GType -> slot name -> the method that may adopt a child there. */
 export const SLOT_CANDIDATES: Readonly<Record<string, Readonly<Record<string, string>>>>;
 

package/builder-1.0-vocabulary.js

@@ -48,6 +48,84 @@ export const ENUM_NICKS = {
     GbViewGridSplit: ['left', 'right', 'move-left', 'move-right'],
 };
 
+// The number behind each of those nicks, read from GIR's own `value` attribute.
+//
+// It ships because position in `ENUM_NICKS` is not the value and a consumer with no
+// typelib has no other way to learn it: a surface without GI still has to hand GObject an
+// integer. The alternative a consumer reaches for first is counting, and counting is wrong
+// on 6 of the 129 enums a GTK 4 vocabulary carries (104 in Gtk-4.0, 25 in Adw-1) --
+// `GtkResponseType` runs -1 down to
+// -11, `GtkTextWindowType` starts at 1, and `GtkConstraintStrength.required` is
+// 1001001000 where counting answers 0.
+//
+// Same provenance as the nicks above, which is the point: a consumer that reads the numbers
+// from an INSTALLED library instead gets two provenances for one table, and a member the
+// vocabulary describes but the host predates then looks like a missing number rather than a
+// version gap.
+export const ENUM_VALUES = {
+    'GbViewGridSplit.left': 1,
+    'GbViewGridSplit.move-left': 3,
+    'GbViewGridSplit.move-right': 4,
+    'GbViewGridSplit.right': 2,
+};
+
+// The nicks GIR marks `deprecated="1"`.
+//
+// Two members of one enum may share a value -- that is how GObject spells an alias, and
+// `GTK_ALIGN_BASELINE` and `GTK_ALIGN_BASELINE_FILL` are both 4. `ENUM_VALUES` keeps
+// both names, so nothing is lost, and this is what says which of the two a number should be
+// spelled back as. Stated rather than derived: the pairing is visible in the values, the
+// DIRECTION is not.
+//
+// Read it as evidence, not as a negative: 4 registered-enum members in the 718 GIRs carry
+// the attribute at all, and 179 of the 182 value-sharing pairs carry it on neither half.
+// A nick missing from here is a nick GIR says nothing about, not a nick GIR calls current.
+export const ENUM_DEPRECATED = [];
+
+// The declared remainder: nicks whose GIR `value` is not a number this can carry.
+//
+// Every nick in `ENUM_NICKS` is in `ENUM_VALUES` or here -- a nick in neither would be a
+// silent drop. GIR carries two shapes no integer holds: a symbolic or absent value (Vala
+// writes `(null)`, a char enum writes a letter) and an integer past
+// `Number.MAX_SAFE_INTEGER`. The value kept here is the raw attribute, so the entry says
+// WHAT was unreadable rather than only that something was. Measured over the 718 GIRs in
+// ts-for-gir's `girs/`: 32 of 34096 registered-enum members, none in Gtk, Adw, GLib or Gio.
+export const ENUM_VALUES_UNREADABLE = {};
+
+// The number behind each member of a registered BITFIELD, keyed the same way.
+//
+// `ENUM_NICKS` refuses a bitfield because GObject cannot resolve a nick SET, and that
+// reason says nothing about one member's number. 21 writable widget properties in Gtk-4.0
+// and Adw-1 are bitfield-typed -- `GtkEntry:input-hints`, `GtkPopoverMenu:flags`,
+// `AdwTabView:shortcuts`, ... -- and they are typed bare `number`, so a host without GI
+// has nothing to compute one from. Counting is worst exactly here: 95 of 121 Gtk-4.0
+// bitfield members disagree with their position, against 29 of 685 enumeration members.
+//
+// A table of its own rather than more rows in `ENUM_VALUES`, so that "every nick in
+// `ENUM_NICKS` has a number or a declared reason" stays a claim about one set.
+export const FLAG_VALUES = {};
+
+// The same declared remainder for the bitfields. Every one of the 13 members in ts-for-gir's
+// `girs/` whose value is past `Number.MAX_SAFE_INTEGER` is a bitfield member (Fwupd, Qmi),
+// so this is the table that shape actually reaches.
+export const FLAG_VALUES_UNREADABLE = {};
+
+// Declaration GType + property name -> the GType of that property's enum or bitfield.
+//
+// Without it the value tables above are half an answer. A host with no GI knows it must set
+// `orientation` to the number behind the nick `vertical`; `ENUM_VALUES` is keyed
+// `GtkOrientation.vertical`, and nothing else says that `orientation` is a
+// `GtkOrientation`. Deriving it is not available: `never` is a member of several Gtk enums,
+// and choosing between them produces a wrong number rather than a missing one.
+//
+// Only where the property's OWN type is the enum. An array of them and a union that mentions
+// one are both entries a consumer would resolve wrongly, so neither is written.
+//
+// A GType named here has numbers in SOME vocabulary, not necessarily this one: the namespace
+// that OWNS an enum publishes it, so 57 of the 438 entries a full run emits want the owner's
+// vocabulary loaded too. Owners that emit none (Gdk, Pango) are inlined into the tables above.
+export const PROP_ENUMS = {};
+
 export const SLOT_CANDIDATES = {
     GbViewGrid: {
         'stack-after': 'add_stack_after',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@girs/builder-1.0",
-    "version": "4.7.0",
+    "version": "4.9.0",
     "description": "GJS TypeScript type definitions for Builder-1.0",
     "type": "module",
     "module": "builder-1.0.js",
@@ -36,27 +36,27 @@
       "test": "tsc --project tsconfig.json"
     },
     "dependencies": {
-      "@girs/gjs": "^4.7.0",
-      "@girs/peas-1.0": "^4.7.0",
-      "@girs/gio-2.0": "^4.7.0",
-      "@girs/gobject-2.0": "^4.7.0",
-      "@girs/glib-2.0": "^4.7.0",
-      "@girs/gmodule-2.0": "^4.7.0",
-      "@girs/girepository-3.0": "^4.7.0",
-      "@girs/ide-1.0": "^4.7.0",
-      "@girs/template-1.0": "^4.7.0",
-      "@girs/json-1.0": "^4.7.0",
-      "@girs/gtksource-3.0": "^4.7.0",
-      "@girs/gtk-3.0": "^4.7.0",
-      "@girs/xlib-2.0": "^4.7.0",
-      "@girs/gdk-3.0": "^4.7.0",
-      "@girs/cairo-1.0": "^4.7.0",
-      "@girs/pango-1.0": "^4.7.0",
-      "@girs/harfbuzz-0.0": "^4.7.0",
-      "@girs/freetype2-2.0": "^4.7.0",
-      "@girs/gdkpixbuf-2.0": "^4.7.0",
-      "@girs/atk-1.0": "^4.7.0",
-      "@girs/dazzle-1.0": "^4.7.0"    },
+      "@girs/gjs": "^4.9.0",
+      "@girs/peas-1.0": "^4.9.0",
+      "@girs/gio-2.0": "^4.9.0",
+      "@girs/gobject-2.0": "^4.9.0",
+      "@girs/glib-2.0": "^4.9.0",
+      "@girs/gmodule-2.0": "^4.9.0",
+      "@girs/girepository-3.0": "^4.9.0",
+      "@girs/ide-1.0": "^4.9.0",
+      "@girs/template-1.0": "^4.9.0",
+      "@girs/json-1.0": "^4.9.0",
+      "@girs/gtksource-3.0": "^4.9.0",
+      "@girs/gtk-3.0": "^4.9.0",
+      "@girs/xlib-2.0": "^4.9.0",
+      "@girs/gdk-3.0": "^4.9.0",
+      "@girs/cairo-1.0": "^4.9.0",
+      "@girs/pango-1.0": "^4.9.0",
+      "@girs/harfbuzz-0.0": "^4.9.0",
+      "@girs/freetype2-2.0": "^4.9.0",
+      "@girs/gdkpixbuf-2.0": "^4.9.0",
+      "@girs/atk-1.0": "^4.9.0",
+      "@girs/dazzle-1.0": "^4.9.0"    },
     "devDependencies": {
       "typescript": "*"
     },