@gtkx/react 1.0.0-rc.2 → 1.0.0-rc.4

package/src/reconciler/text.ts

@@ -5,8 +5,9 @@ import { drain, indexBeforeOrEnd } from "@gtkx/utils";
 import type { ContentChild, ContentKind, ElementNode, ParentNode, TextNode } from "./node.js";
 import type { Props } from "./registry.js";
 import { ELEMENT_KIND, TEXT_KIND } from "./node.js";
+import { applyWrite } from "./signals.js";
 
-type OffsetResult = { found: boolean; offset: number };
+type OffsetResult = { wasFound: boolean; offset: number };
 
 type BufferBuild = {
     buffer: Gtk.TextBuffer;
@@ -75,14 +76,14 @@ const isTagElement = (node: ContentChild): node is ElementNode =>
 
 const stepOffset = (node: ContentChild, target: TextNode, offset: number): OffsetResult => {
     if (node === target) {
-        return { found: true, offset };
+        return { wasFound: true, offset };
     }
 
     if (isTagElement(node)) {
         return getOffset(node.content, target, offset);
     }
 
-    return { found: false, offset: offset + contentTextLength(node) };
+    return { wasFound: false, offset: offset + contentTextLength(node) };
 };
 
 const getOffset = (nodes: ContentChild[], target: TextNode, start: number): OffsetResult => {
@@ -91,14 +92,14 @@ const getOffset = (nodes: ContentChild[], target: TextNode, start: number): Offs
     for (const node of nodes) {
         const step = stepOffset(node, target, offset);
 
-        if (step.found) {
+        if (step.wasFound) {
             return step;
         }
 
         offset = step.offset;
     }
 
-    return { found: false, offset };
+    return { wasFound: false, offset };
 };
 
 const enclosingTagNodes = (node: TextNode): ElementNode[] => {
@@ -319,13 +320,15 @@ const rebuildBuffer = (node: ElementNode): void => {
         return;
     }
 
-    buffer.setText("", -1);
-    const build: BufferBuild = { buffer, view: node.bufferView, marks: [] };
-    insertContent(build, node.content);
+    applyWrite(() => {
+        buffer.setText("", -1);
+        const build: BufferBuild = { buffer, view: node.bufferView, marks: [] };
+        insertContent(build, node.content);
 
-    for (const mark of build.marks) {
-        placeMark(buffer, mark.node, mark.offset);
-    }
+        for (const mark of build.marks) {
+            placeMark(buffer, mark.node, mark.offset);
+        }
+    });
 };
 
 const rebuildLabel = (node: ElementNode): void => {
@@ -376,13 +379,17 @@ const didUpdateTextSurgically = (host: ElementNode, node: TextNode, oldText: str
 
     const located = getOffset(host.content, node, 0);
 
-    if (!located.found) {
+    if (!located.wasFound) {
         return false;
     }
 
     const start = located.offset;
-    buffer.delete(buffer.getIterAtOffset(start), buffer.getIterAtOffset(start + charLength(oldText)));
-    buffer.insert(buffer.getIterAtOffset(start), newText, -1);
+
+    applyWrite(() => {
+        buffer.delete(buffer.getIterAtOffset(start), buffer.getIterAtOffset(start + charLength(oldText)));
+        buffer.insert(buffer.getIterAtOffset(start), newText, -1);
+    });
+
     const startIter = buffer.getIterAtOffset(start);
     const endIter = buffer.getIterAtOffset(start + charLength(newText));
     applyEnclosingTags(buffer, node, startIter, endIter);

package/src/utils/accessible-metadata.ts

@@ -15,13 +15,6 @@ 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);
 

package/src/utils/accessible-props.ts

@@ -6,55 +6,103 @@ import { deleteAccessibleMetadata, setAccessibleMetadata } from "./accessible-me
 /**
  * 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;
+    /** Descendant that holds the focus while the widget itself keeps it. */
     accessibleActiveDescendant?: Gtk.Widget | 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;
+    /** Widgets whose content or presence this widget controls. */
     accessibleControls?: Gtk.Widget[] | null | undefined;
+    /** Widgets that describe this one. */
     accessibleDescribedBy?: Gtk.Widget[] | null | undefined;
+    /** Widgets holding extended detail about this one. */
     accessibleDetails?: Gtk.Widget[] | null | undefined;
+    /** Widgets holding the message that explains why the value is invalid. */
     accessibleErrorMessage?: Gtk.Widget[] | null | undefined;
+    /** Widgets to read next, overriding the default reading order. */
     accessibleFlowTo?: Gtk.Widget[] | null | undefined;
+    /** Widgets that label this one. */
     accessibleLabelledBy?: Gtk.Widget[] | null | undefined;
+    /** Widgets this one owns that the widget hierarchy does not already imply. */
     accessibleOwns?: Gtk.Widget[] | 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;
 };
 

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,19 @@
 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>;
 type SettingKindValue<S extends string> = S extends "enum" | "flags" ? number : VariantValue<S>;
+/** The JavaScript type key `P` holds: `number` for `enum` and `flags`, otherwise the unpacked GVariant. */
 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;
 };