@gtkx/react 1.0.0-rc.3 → 1.0.0

package/src/utils/accessible-props.ts

@@ -1,64 +1,111 @@
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
 import type { Props } from "../reconciler/registry.js";
-import { deleteAccessibleMetadata, setAccessibleMetadata } from "./accessible-metadata.js";
 
 /**
  * Accessibility props available on every widget. Each member maps to a GTK4 accessible attribute
  * (a `Gtk.AccessibleProperty`, `Gtk.AccessibleState`, or `Gtk.AccessibleRelation`) and is applied
- * to the widget's accessible interface; setting a member to `undefined` resets that attribute to its default.
+ * to the widget's accessible interface. Setting a member to `null` or `undefined`, or dropping it from the
+ * props, resets that attribute to its default.
  */
 type AccessibleProps = {
+    /** How the widget completes the text being typed into it. */
     accessibleAutocomplete?: Gtk.AccessibleAutocomplete | null | undefined;
+    /** Longer description announced after the label. */
     accessibleDescription?: string | null | undefined;
+    /** Whether activating the widget opens a popup. */
     accessibleHasPopup?: boolean | null | undefined;
+    /** Keyboard shortcuts that activate the widget. */
     accessibleKeyShortcuts?: string | null | undefined;
+    /** Short name announced for the widget. */
     accessibleLabel?: string | null | undefined;
+    /** Depth of the widget within a hierarchy of headings, list items, or tree rows. */
     accessibleLevel?: number | null | undefined;
+    /** Whether the widget blocks interaction with everything behind it. */
     accessibleModal?: boolean | null | undefined;
+    /** Whether the text input accepts more than one line. */
     accessibleMultiLine?: boolean | null | undefined;
+    /** Whether more than one of the widget's items can be selected at a time. */
     accessibleMultiSelectable?: boolean | null | undefined;
+    /** Whether the widget arranges its items horizontally or vertically. */
     accessibleOrientation?: Gtk.Orientation | null | undefined;
+    /** Hint announced while the input is empty. */
     accessiblePlaceholder?: string | null | undefined;
+    /** Whether the value can be read but not changed. */
     accessibleReadOnly?: boolean | null | undefined;
+    /** Whether a value has to be supplied before the form can be submitted. */
     accessibleRequired?: boolean | null | undefined;
+    /** Wording that replaces the default announcement of the widget's role. */
     accessibleRoleDescription?: string | null | undefined;
+    /** Direction the widget's items are sorted in. */
     accessibleSort?: Gtk.AccessibleSort | null | undefined;
+    /** Upper bound of the widget's value range. */
     accessibleValueMax?: number | null | undefined;
+    /** Lower bound of the widget's value range. */
     accessibleValueMin?: number | null | undefined;
+    /** Current value within the widget's range. */
     accessibleValueNow?: number | null | undefined;
+    /** Wording announced in place of the numeric value. */
     accessibleValueText?: string | null | undefined;
+    /** Help text describing how to use the widget. */
     accessibleHelpText?: string | null | undefined;
+    /** Whether the widget is still loading and its content may yet change. */
     accessibleBusy?: boolean | null | undefined;
+    /** Checked state of a check button or menu item, which may be mixed. */
     accessibleChecked?: Gtk.AccessibleTristate | null | undefined;
+    /** Whether the widget is visible but cannot be edited or operated. */
     accessibleDisabled?: boolean | null | undefined;
+    /** Whether the content the widget discloses is showing. */
     accessibleExpanded?: boolean | null | undefined;
+    /** Whether the widget is kept out of the accessibility tree. */
     accessibleHidden?: boolean | null | undefined;
+    /** Whether the entered value fails validation, and in what way. */
     accessibleInvalid?: Gtk.AccessibleInvalidState | null | undefined;
+    /** Pressed state of a toggle button, which may be mixed. */
     accessiblePressed?: Gtk.AccessibleTristate | null | undefined;
+    /** Whether the widget is selected within its container. */
     accessibleSelected?: boolean | null | undefined;
+    /** Whether the link has already been followed. */
     accessibleVisited?: boolean | null | undefined;
-    accessibleActiveDescendant?: Gtk.Widget | null | undefined;
+    /** Descendant that holds the focus while the widget itself keeps it. */
+    accessibleActiveDescendant?: Gtk.Accessible | null | undefined;
+    /** Total number of columns in the table, including any that are not rendered. */
     accessibleColCount?: number | null | undefined;
+    /** One-based column position of the cell within its table. */
     accessibleColIndex?: number | null | undefined;
+    /** Wording announced in place of the numeric column position. */
     accessibleColIndexText?: string | null | undefined;
+    /** Number of columns the cell spans. */
     accessibleColSpan?: number | null | undefined;
-    accessibleControls?: Gtk.Widget[] | null | undefined;
-    accessibleDescribedBy?: Gtk.Widget[] | null | undefined;
-    accessibleDetails?: Gtk.Widget[] | null | undefined;
-    accessibleErrorMessage?: Gtk.Widget[] | null | undefined;
-    accessibleFlowTo?: Gtk.Widget[] | null | undefined;
-    accessibleLabelledBy?: Gtk.Widget[] | null | undefined;
-    accessibleOwns?: Gtk.Widget[] | null | undefined;
+    /** Widgets whose content or presence this widget controls. */
+    accessibleControls?: Gtk.Accessible[] | null | undefined;
+    /** Widgets that describe this one. */
+    accessibleDescribedBy?: Gtk.Accessible[] | null | undefined;
+    /** Widgets holding extended detail about this one. */
+    accessibleDetails?: Gtk.Accessible[] | null | undefined;
+    /** Widgets holding the message that explains why the value is invalid. */
+    accessibleErrorMessage?: Gtk.Accessible[] | null | undefined;
+    /** Widgets to read next, overriding the default reading order. */
+    accessibleFlowTo?: Gtk.Accessible[] | null | undefined;
+    /** Widgets that label this one. */
+    accessibleLabelledBy?: Gtk.Accessible[] | null | undefined;
+    /** Widgets this one owns that the widget hierarchy does not already imply. */
+    accessibleOwns?: Gtk.Accessible[] | null | undefined;
+    /** One-based position of the widget within its set. */
     accessiblePosInSet?: number | null | undefined;
+    /** Total number of rows in the table, including any that are not rendered. */
     accessibleRowCount?: number | null | undefined;
+    /** One-based row position of the cell within its table. */
     accessibleRowIndex?: number | null | undefined;
+    /** Wording announced in place of the numeric row position. */
     accessibleRowIndexText?: string | null | undefined;
+    /** Number of rows the cell spans. */
     accessibleRowSpan?: number | null | undefined;
+    /** Total number of items in the set the widget belongs to. */
     accessibleSetSize?: number | null | undefined;
 };
 
-type AccessibleValueType = "string" | "boolean" | "int" | "double" | "object" | "list";
+type AccessibleValueType = "string" | "boolean" | "optionalBoolean" | "int" | "double" | "object" | "list";
 
 type AccessiblePropertyDescriptor = {
     kind: "property";
@@ -104,12 +151,12 @@ const ACCESSIBLE_PROP_MAP: Record<keyof AccessibleProps, AccessibleDescriptor> =
     accessibleBusy: buildState(Gtk.AccessibleState.BUSY, "boolean"),
     accessibleChecked: buildState(Gtk.AccessibleState.CHECKED, "int"),
     accessibleDisabled: buildState(Gtk.AccessibleState.DISABLED, "boolean"),
-    accessibleExpanded: buildState(Gtk.AccessibleState.EXPANDED, "int"),
+    accessibleExpanded: buildState(Gtk.AccessibleState.EXPANDED, "optionalBoolean"),
     accessibleHidden: buildState(Gtk.AccessibleState.HIDDEN, "boolean"),
     accessibleInvalid: buildState(Gtk.AccessibleState.INVALID, "int"),
     accessiblePressed: buildState(Gtk.AccessibleState.PRESSED, "int"),
-    accessibleSelected: buildState(Gtk.AccessibleState.SELECTED, "int"),
-    accessibleVisited: buildState(Gtk.AccessibleState.VISITED, "int"),
+    accessibleSelected: buildState(Gtk.AccessibleState.SELECTED, "optionalBoolean"),
+    accessibleVisited: buildState(Gtk.AccessibleState.VISITED, "optionalBoolean"),
     accessibleActiveDescendant: buildRelation(Gtk.AccessibleRelation.ACTIVE_DESCENDANT, "object"),
     accessibleColCount: buildRelation(Gtk.AccessibleRelation.COL_COUNT, "int"),
     accessibleColIndex: buildRelation(Gtk.AccessibleRelation.COL_INDEX, "int"),
@@ -166,6 +213,11 @@ const buildValue = (descriptor: AccessibleDescriptor, jsValue: unknown): GObject
                 v.setBoolean(jsValue as boolean);
             });
         }
+        case "optionalBoolean": {
+            return GObject.buildValue(GObject.TYPE_INT, (v) => {
+                v.setInt(jsValue === true ? 1 : 0);
+            });
+        }
         case "int": {
             return GObject.buildValue(GObject.TYPE_INT, (v) => {
                 v.setInt(jsValue as number);
@@ -182,7 +234,7 @@ const buildValue = (descriptor: AccessibleDescriptor, jsValue: unknown): GObject
             });
         }
         case "list": {
-            const list = Gtk.AccessibleList.newFromList(jsValue as Gtk.Widget[]);
+            const list = Gtk.AccessibleList.newFromList(jsValue as Gtk.Accessible[]);
 
             return GObject.buildValue(Gtk.AccessibleList.prototype.__type__, (v) => {
                 v.setBoxed(list);
@@ -233,24 +285,18 @@ function resetDescriptor(widget: Gtk.Accessible, descriptor: AccessibleDescripto
 const applyChangedProp = (widget: Gtk.Accessible, name: keyof AccessibleProps, newValue: unknown): void => {
     if (newValue == null) {
         resetDescriptor(widget, ACCESSIBLE_PROP_MAP[name]);
-        deleteAccessibleMetadata(widget, name);
     } else {
         applyDescriptor(widget, ACCESSIBLE_PROP_MAP[name], newValue);
-        setAccessibleMetadata(widget, name, newValue);
     }
 };
 
-const applyChangedProps = (widget: Gtk.Accessible, oldProps: Props | null, newProps: Props): void => {
+const applyChangedProps = (widget: Gtk.Accessible, newProps: Props): void => {
     for (const name in newProps) {
         if (!isAccessibleProp(name)) {
             continue;
         }
 
-        const newValue = newProps[name];
-
-        if (oldProps?.[name] !== newValue) {
-            applyChangedProp(widget, name, newValue);
-        }
+        applyChangedProp(widget, name, newProps[name]);
     }
 };
 
@@ -264,12 +310,11 @@ const resetRemovedProps = (widget: Gtk.Accessible, oldProps: Props, newProps: Pr
         }
 
         resetDescriptor(widget, ACCESSIBLE_PROP_MAP[name]);
-        deleteAccessibleMetadata(widget, name);
     }
 };
 
 const applyAccessibleProps = (widget: Gtk.Accessible, oldProps: Props | null, newProps: Props): void => {
-    applyChangedProps(widget, oldProps, newProps);
+    applyChangedProps(widget, newProps);
 
     if (oldProps) {
         resetRemovedProps(widget, oldProps, newProps);

package/src/utils/ref-prop.ts

@@ -9,12 +9,6 @@ type RefProp<T extends object> = T | RefObject<T | null> | null | undefined;
 const isRefObject = <T extends object>(value: T | RefObject<T | null>): value is RefObject<T | null> =>
     typeof value === "object" && "current" in value;
 
-/**
- * Resolves a {@link RefProp} to the concrete object it points at, or null when it is absent or unresolved.
- *
- * @param prop The target object, a ref to one, or null/undefined.
- * @returns The resolved object, or null.
- */
 const resolveRefProp = <T extends object>(prop: RefProp<T>): T | null => {
     if (prop === null || prop === undefined) {
         return null;

package/src/utils/settings.ts

@@ -1,13 +1,20 @@
 import type * as Gio from "@gtkx/gi/gio";
 import { packVariant, parseVariantType, unpackVariant, type VariantValue } from "./variant.js";
 
+/** Maps each key of a GSettings schema to its kind: a GVariant type string, or `enum` or `flags`. */
 type SettingsSchemaKeys = Record<string, string>;
+/** Value type a key kind stands for: `number` for `enum` and `flags`, otherwise the unpacked GVariant. */
 type SettingKindValue<S extends string> = S extends "enum" | "flags" ? number : VariantValue<S>;
+/** Value type of key `P`, looked up by its kind in schema `K`, that reads and writes of that key take. */
 type SettingValue<K extends SettingsSchemaKeys, P extends keyof K> = SettingKindValue<K[P] & string>;
 
+/** A GSettings schema, as described by the modules GTKX generates from a project's `.gschema.xml` files. */
 type SettingsSchema<K extends SettingsSchemaKeys = SettingsSchemaKeys> = {
+    /** Schema id it is looked up by, such as `org.gtkx.Example`. */
     id: string;
+    /** Path a relocatable schema is instantiated at, or `null` to use the schema's own path. */
     path: string | null;
+    /** Kind of every key the schema declares, which types reads and writes of that key. */
     keys: K;
 };
 

package/src/utils/variant.ts

@@ -1,26 +1,45 @@
 import * as GLib from "@gtkx/gi/glib";
 
+/** JavaScript type every GVariant basic type code unpacks to. */
 type BasicValueMap = {
+    /** Boolean, held as a single byte reading 0 or 1. */
     b: boolean;
+    /** Unsigned byte. */
     y: number;
+    /** Signed 16-bit integer. */
     n: number;
+    /** Unsigned 16-bit integer. */
     q: number;
+    /** Signed 32-bit integer. */
     i: number;
+    /** Unsigned 32-bit integer. */
     u: number;
+    /** Index into the file descriptor list a message carries. */
     h: number;
+    /** Double precision floating point number. */
     d: number;
+    /** Signed 64-bit integer. */
     x: bigint;
+    /** Unsigned 64-bit integer. */
     t: bigint;
+    /** UTF-8 string, under no further constraint on what it holds. */
     s: string;
+    /** D-Bus object path. */
     o: string;
+    /** GVariant type signature. */
     g: string;
+    /** Boxed variant holding a value of any type. */
     v: GLib.Variant;
 };
 
+/** Single-character code of one of the GVariant basic types in {@link BasicValueMap}. */
 type BasicCode = keyof BasicValueMap;
+/** Parses the element type of an array, yielding the array type it produces and the rest of the string. */
 type ParseArray<S extends string> = Parse<S> extends [infer V, infer R extends string] ? [V[], R] : never;
+/** Parses the element type of a maybe, yielding the nullable type it produces and the rest of the string. */
 type ParseMaybe<S extends string> = Parse<S> extends [infer V, infer R extends string] ? [V | null, R] : never;
 
+/** Collects tuple member types into `Acc` up to the closing parenthesis, yielding them and the rest of the string. */
 type ParseTuple<S extends string, Acc extends unknown[]> = S extends `)${infer Rest}`
     ? [Acc, Rest]
     : [Parse<S>] extends [never]
@@ -29,8 +48,10 @@ type ParseTuple<S extends string, Acc extends unknown[]> = S extends `)${infer R
                 ? ParseTuple<R, [...Acc, V]>
                 : never;
 
+/** Types a dictionary entry key can hold. */
 type DictKey = string | number | bigint | boolean;
 
+/** Parses the key and value types of a dictionary entry, yielding them and the rest of the string after its brace. */
 type ParsePair<S extends string> =
     Parse<S> extends [infer K, infer R1 extends string]
         ? Parse<R1> extends [infer V, infer R2 extends string]
@@ -42,16 +63,26 @@ type ParsePair<S extends string> =
             : never
         : never;
 
+/**
+ * Parses a dictionary entry into the collection an array of those entries unpacks to, a record for string keys and a
+ * `Map` otherwise, plus the rest of the string.
+ */
 type ParseDict<S extends string> =
     ParsePair<S> extends [infer K, infer V, infer R extends string]
         ? [[K] extends [string] ? Record<string, V> : Map<K, V>, R]
         : never;
 
+/** Parses a standalone dictionary entry into a key and value pair, yielding it and the rest of the string. */
 type ParseEntry<S extends string> =
     ParsePair<S> extends [infer K, infer V, infer R extends string] ? [[K, V], R] : never;
 
+/** Parses what follows an `a` as a dictionary when it opens an entry, and as a plain array otherwise. */
 type ParseArrayOrDict<S extends string> = S extends `{${infer Rest}` ? ParseDict<Rest> : ParseArray<S>;
 
+/**
+ * Parses the type at the head of `S`, yielding the JavaScript type it unpacks to and the rest of the string, or
+ * `never` when the string is malformed.
+ */
 type Parse<S extends string> = S extends `a${infer Rest}`
     ? ParseArrayOrDict<Rest>
     : S extends `m${infer Rest}`
@@ -66,6 +97,7 @@ type Parse<S extends string> = S extends `a${infer Rest}`
                         : never
                     : never;
 
+/** JavaScript type a variant of type string `S` unpacks to, or `unknown` when `S` is not one complete type. */
 type VariantValue<S extends string> = [Parse<S>] extends [never]
     ? unknown
     : Parse<S> extends [infer V, ""]
@@ -365,4 +397,4 @@ const packVariant = (node: VariantTypeNode, value: unknown): GLib.Variant => {
     }
 };
 
-export { parseVariantType, unpackVariant, packVariant, type VariantValue, type VariantTypeNode };
+export { parseVariantType, unpackVariant, packVariant, type VariantValue };

package/dist/utils/accessible-metadata.d.ts

@@ -1,12 +0,0 @@
-declare const setAccessibleMetadata: (widget: object, name: string, value: unknown) => void;
-declare const deleteAccessibleMetadata: (widget: object, name: string) => void;
-/**
- * Returns the last value applied for an accessible prop on a widget, or null when none was applied.
- *
- * @param widget The widget to read from.
- * @param name The accessible prop name.
- * @returns The last applied value, or null.
- */
-declare const getAccessibleMetadata: (widget: object, name: string) => unknown;
-export { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };
-//# sourceMappingURL=accessible-metadata.d.ts.map

package/dist/utils/accessible-metadata.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"accessible-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/accessible-metadata.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,qBAAqB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,OAAO,OAAO,KAAG,IAS7E,CAAC;AAEF,QAAA,MAAM,wBAAwB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,IAEhE,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,qBAAqB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,OAI7D,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/utils/accessible-metadata.js

@@ -1,25 +0,0 @@
-const metadataStore = new WeakMap();
-const setAccessibleMetadata = (widget, name, value) => {
-    let entries = metadataStore.get(widget);
-    if (entries === undefined) {
-        entries = new Map();
-        metadataStore.set(widget, entries);
-    }
-    entries.set(name, value);
-};
-const deleteAccessibleMetadata = (widget, name) => {
-    metadataStore.get(widget)?.delete(name);
-};
-/**
- * Returns the last value applied for an accessible prop on a widget, or null when none was applied.
- *
- * @param widget The widget to read from.
- * @param name The accessible prop name.
- * @returns The last applied value, or null.
- */
-const getAccessibleMetadata = (widget, name) => {
-    const value = metadataStore.get(widget)?.get(name);
-    return value === undefined ? null : value;
-};
-export { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };
-//# sourceMappingURL=accessible-metadata.js.map

package/dist/utils/accessible-metadata.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"accessible-metadata.js","sourceRoot":"","sources":["../../src/utils/accessible-metadata.ts"],"names":[],"mappings":"AAAA,MAAM,aAAa,GAA0C,IAAI,OAAO,EAAE,CAAC;AAE3E,MAAM,qBAAqB,GAAG,CAAC,MAAc,EAAE,IAAY,EAAE,KAAc,EAAQ,EAAE;IACjF,IAAI,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAExC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QACpB,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,wBAAwB,GAAG,CAAC,MAAc,EAAE,IAAY,EAAQ,EAAE;IACpE,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,qBAAqB,GAAG,CAAC,MAAc,EAAE,IAAY,EAAW,EAAE;IACpE,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9C,CAAC,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,CAAC","sourcesContent":["const metadataStore: WeakMap<object, Map<string, unknown>> = new WeakMap();\n\nconst setAccessibleMetadata = (widget: object, name: string, value: unknown): void => {\n    let entries = metadataStore.get(widget);\n\n    if (entries === undefined) {\n        entries = new Map();\n        metadataStore.set(widget, entries);\n    }\n\n    entries.set(name, value);\n};\n\nconst deleteAccessibleMetadata = (widget: object, name: string): void => {\n    metadataStore.get(widget)?.delete(name);\n};\n\n/**\n * Returns the last value applied for an accessible prop on a widget, or null when none was applied.\n *\n * @param widget The widget to read from.\n * @param name The accessible prop name.\n * @returns The last applied value, or null.\n */\nconst getAccessibleMetadata = (widget: object, name: string): unknown => {\n    const value = metadataStore.get(widget)?.get(name);\n\n    return value === undefined ? null : value;\n};\n\nexport { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };\n"]}

package/src/utils/accessible-metadata.ts

@@ -1,31 +0,0 @@
-const metadataStore: WeakMap<object, Map<string, unknown>> = new WeakMap();
-
-const setAccessibleMetadata = (widget: object, name: string, value: unknown): void => {
-    let entries = metadataStore.get(widget);
-
-    if (entries === undefined) {
-        entries = new Map();
-        metadataStore.set(widget, entries);
-    }
-
-    entries.set(name, value);
-};
-
-const deleteAccessibleMetadata = (widget: object, name: string): void => {
-    metadataStore.get(widget)?.delete(name);
-};
-
-/**
- * Returns the last value applied for an accessible prop on a widget, or null when none was applied.
- *
- * @param widget The widget to read from.
- * @param name The accessible prop name.
- * @returns The last applied value, or null.
- */
-const getAccessibleMetadata = (widget: object, name: string): unknown => {
-    const value = metadataStore.get(widget)?.get(name);
-
-    return value === undefined ? null : value;
-};
-
-export { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };