@gtkx/react 0.21.0 → 1.0.0-rc.2

package/src/utils/accessible-metadata.ts

@@ -0,0 +1,31 @@
+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 };

package/src/utils/accessible-props.ts

@@ -0,0 +1,279 @@
+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.
+ */
+type AccessibleProps = {
+    accessibleAutocomplete?: Gtk.AccessibleAutocomplete | null | undefined;
+    accessibleDescription?: string | null | undefined;
+    accessibleHasPopup?: boolean | null | undefined;
+    accessibleKeyShortcuts?: string | null | undefined;
+    accessibleLabel?: string | null | undefined;
+    accessibleLevel?: number | null | undefined;
+    accessibleModal?: boolean | null | undefined;
+    accessibleMultiLine?: boolean | null | undefined;
+    accessibleMultiSelectable?: boolean | null | undefined;
+    accessibleOrientation?: Gtk.Orientation | null | undefined;
+    accessiblePlaceholder?: string | null | undefined;
+    accessibleReadOnly?: boolean | null | undefined;
+    accessibleRequired?: boolean | null | undefined;
+    accessibleRoleDescription?: string | null | undefined;
+    accessibleSort?: Gtk.AccessibleSort | null | undefined;
+    accessibleValueMax?: number | null | undefined;
+    accessibleValueMin?: number | null | undefined;
+    accessibleValueNow?: number | null | undefined;
+    accessibleValueText?: string | null | undefined;
+    accessibleHelpText?: string | null | undefined;
+    accessibleBusy?: boolean | null | undefined;
+    accessibleChecked?: Gtk.AccessibleTristate | null | undefined;
+    accessibleDisabled?: boolean | null | undefined;
+    accessibleExpanded?: boolean | null | undefined;
+    accessibleHidden?: boolean | null | undefined;
+    accessibleInvalid?: Gtk.AccessibleInvalidState | null | undefined;
+    accessiblePressed?: Gtk.AccessibleTristate | null | undefined;
+    accessibleSelected?: boolean | null | undefined;
+    accessibleVisited?: boolean | null | undefined;
+    accessibleActiveDescendant?: Gtk.Widget | null | undefined;
+    accessibleColCount?: number | null | undefined;
+    accessibleColIndex?: number | null | undefined;
+    accessibleColIndexText?: string | null | undefined;
+    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;
+    accessiblePosInSet?: number | null | undefined;
+    accessibleRowCount?: number | null | undefined;
+    accessibleRowIndex?: number | null | undefined;
+    accessibleRowIndexText?: string | null | undefined;
+    accessibleRowSpan?: number | null | undefined;
+    accessibleSetSize?: number | null | undefined;
+};
+
+type AccessibleValueType = "string" | "boolean" | "int" | "double" | "object" | "list";
+
+type AccessiblePropertyDescriptor = {
+    kind: "property";
+    property: Gtk.AccessibleProperty;
+    type: AccessibleValueType;
+};
+
+type AccessibleStateDescriptor = {
+    kind: "state";
+    state: Gtk.AccessibleState;
+    type: AccessibleValueType;
+};
+
+type AccessibleRelationDescriptor = {
+    kind: "relation";
+    relation: Gtk.AccessibleRelation;
+    type: AccessibleValueType;
+};
+
+type AccessibleDescriptor = AccessiblePropertyDescriptor | AccessibleStateDescriptor | AccessibleRelationDescriptor;
+
+const ACCESSIBLE_PROP_MAP: Record<keyof AccessibleProps, AccessibleDescriptor> = {
+    accessibleAutocomplete: buildProperty(Gtk.AccessibleProperty.AUTOCOMPLETE, "int"),
+    accessibleDescription: buildProperty(Gtk.AccessibleProperty.DESCRIPTION, "string"),
+    accessibleHasPopup: buildProperty(Gtk.AccessibleProperty.HAS_POPUP, "boolean"),
+    accessibleKeyShortcuts: buildProperty(Gtk.AccessibleProperty.KEY_SHORTCUTS, "string"),
+    accessibleLabel: buildProperty(Gtk.AccessibleProperty.LABEL, "string"),
+    accessibleLevel: buildProperty(Gtk.AccessibleProperty.LEVEL, "int"),
+    accessibleModal: buildProperty(Gtk.AccessibleProperty.MODAL, "boolean"),
+    accessibleMultiLine: buildProperty(Gtk.AccessibleProperty.MULTI_LINE, "boolean"),
+    accessibleMultiSelectable: buildProperty(Gtk.AccessibleProperty.MULTI_SELECTABLE, "boolean"),
+    accessibleOrientation: buildProperty(Gtk.AccessibleProperty.ORIENTATION, "int"),
+    accessiblePlaceholder: buildProperty(Gtk.AccessibleProperty.PLACEHOLDER, "string"),
+    accessibleReadOnly: buildProperty(Gtk.AccessibleProperty.READ_ONLY, "boolean"),
+    accessibleRequired: buildProperty(Gtk.AccessibleProperty.REQUIRED, "boolean"),
+    accessibleRoleDescription: buildProperty(Gtk.AccessibleProperty.ROLE_DESCRIPTION, "string"),
+    accessibleSort: buildProperty(Gtk.AccessibleProperty.SORT, "int"),
+    accessibleValueMax: buildProperty(Gtk.AccessibleProperty.VALUE_MAX, "double"),
+    accessibleValueMin: buildProperty(Gtk.AccessibleProperty.VALUE_MIN, "double"),
+    accessibleValueNow: buildProperty(Gtk.AccessibleProperty.VALUE_NOW, "double"),
+    accessibleValueText: buildProperty(Gtk.AccessibleProperty.VALUE_TEXT, "string"),
+    accessibleHelpText: buildProperty(Gtk.AccessibleProperty.HELP_TEXT, "string"),
+    accessibleBusy: buildState(Gtk.AccessibleState.BUSY, "boolean"),
+    accessibleChecked: buildState(Gtk.AccessibleState.CHECKED, "int"),
+    accessibleDisabled: buildState(Gtk.AccessibleState.DISABLED, "boolean"),
+    accessibleExpanded: buildState(Gtk.AccessibleState.EXPANDED, "int"),
+    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"),
+    accessibleActiveDescendant: buildRelation(Gtk.AccessibleRelation.ACTIVE_DESCENDANT, "object"),
+    accessibleColCount: buildRelation(Gtk.AccessibleRelation.COL_COUNT, "int"),
+    accessibleColIndex: buildRelation(Gtk.AccessibleRelation.COL_INDEX, "int"),
+    accessibleColIndexText: buildRelation(Gtk.AccessibleRelation.COL_INDEX_TEXT, "string"),
+    accessibleColSpan: buildRelation(Gtk.AccessibleRelation.COL_SPAN, "int"),
+    accessibleControls: buildRelation(Gtk.AccessibleRelation.CONTROLS, "list"),
+    accessibleDescribedBy: buildRelation(Gtk.AccessibleRelation.DESCRIBED_BY, "list"),
+    accessibleDetails: buildRelation(Gtk.AccessibleRelation.DETAILS, "list"),
+    accessibleErrorMessage: buildRelation(Gtk.AccessibleRelation.ERROR_MESSAGE, "list"),
+    accessibleFlowTo: buildRelation(Gtk.AccessibleRelation.FLOW_TO, "list"),
+    accessibleLabelledBy: buildRelation(Gtk.AccessibleRelation.LABELLED_BY, "list"),
+    accessibleOwns: buildRelation(Gtk.AccessibleRelation.OWNS, "list"),
+    accessiblePosInSet: buildRelation(Gtk.AccessibleRelation.POS_IN_SET, "int"),
+    accessibleRowCount: buildRelation(Gtk.AccessibleRelation.ROW_COUNT, "int"),
+    accessibleRowIndex: buildRelation(Gtk.AccessibleRelation.ROW_INDEX, "int"),
+    accessibleRowIndexText: buildRelation(Gtk.AccessibleRelation.ROW_INDEX_TEXT, "string"),
+    accessibleRowSpan: buildRelation(Gtk.AccessibleRelation.ROW_SPAN, "int"),
+    accessibleSetSize: buildRelation(Gtk.AccessibleRelation.SET_SIZE, "int"),
+};
+
+function buildProperty(property: Gtk.AccessibleProperty, type: AccessibleValueType): AccessiblePropertyDescriptor {
+    return {
+        kind: "property",
+        property,
+        type,
+    };
+}
+
+function buildState(state: Gtk.AccessibleState, type: AccessibleValueType): AccessibleStateDescriptor {
+    return {
+        kind: "state",
+        state,
+        type,
+    };
+}
+
+function buildRelation(relation: Gtk.AccessibleRelation, type: AccessibleValueType): AccessibleRelationDescriptor {
+    return {
+        kind: "relation",
+        relation,
+        type,
+    };
+}
+
+const buildValue = (descriptor: AccessibleDescriptor, jsValue: unknown): GObject.Value => {
+    switch (descriptor.type) {
+        case "string": {
+            return GObject.buildValue(GObject.TYPE_STRING, (v) => {
+                v.setString(jsValue as string);
+            });
+        }
+        case "boolean": {
+            return GObject.buildValue(GObject.TYPE_BOOLEAN, (v) => {
+                v.setBoolean(jsValue as boolean);
+            });
+        }
+        case "int": {
+            return GObject.buildValue(GObject.TYPE_INT, (v) => {
+                v.setInt(jsValue as number);
+            });
+        }
+        case "double": {
+            return GObject.buildValue(GObject.TYPE_DOUBLE, (v) => {
+                v.setDouble(jsValue as number);
+            });
+        }
+        case "object": {
+            return GObject.buildValue(GObject.TYPE_OBJECT, (v) => {
+                v.setObject(jsValue as GObject.Object | null);
+            });
+        }
+        case "list": {
+            const list = Gtk.AccessibleList.newFromList(jsValue as Gtk.Widget[]);
+
+            return GObject.buildValue(Gtk.AccessibleList.prototype.__type__, (v) => {
+                v.setBoxed(list);
+            });
+        }
+    }
+};
+
+const isAccessibleProp = (name: string): name is keyof AccessibleProps =>
+    Object.hasOwn(ACCESSIBLE_PROP_MAP, name);
+
+function applyDescriptor(widget: Gtk.Accessible, descriptor: AccessibleDescriptor, newValue: unknown): void {
+    const value = buildValue(descriptor, newValue);
+
+    switch (descriptor.kind) {
+        case "property": {
+            widget.updateProperty([descriptor.property], [value]);
+            break;
+        }
+        case "state": {
+            widget.updateState([descriptor.state], [value]);
+            break;
+        }
+        case "relation": {
+            widget.updateRelation([descriptor.relation], [value]);
+            break;
+        }
+    }
+}
+
+function resetDescriptor(widget: Gtk.Accessible, descriptor: AccessibleDescriptor): void {
+    switch (descriptor.kind) {
+        case "property": {
+            widget.resetProperty(descriptor.property);
+            break;
+        }
+        case "state": {
+            widget.resetState(descriptor.state);
+            break;
+        }
+        case "relation": {
+            widget.resetRelation(descriptor.relation);
+            break;
+        }
+    }
+}
+
+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 => {
+    for (const name in newProps) {
+        if (!isAccessibleProp(name)) {
+            continue;
+        }
+
+        const newValue = newProps[name];
+
+        if (oldProps?.[name] !== newValue) {
+            applyChangedProp(widget, name, newValue);
+        }
+    }
+};
+
+const isRemovedAccessibleProp = (name: string, oldProps: Props, newProps: Props): name is keyof AccessibleProps =>
+    !Object.hasOwn(newProps, name) && isAccessibleProp(name) && oldProps[name] !== undefined;
+
+const resetRemovedProps = (widget: Gtk.Accessible, oldProps: Props, newProps: Props): void => {
+    for (const name in oldProps) {
+        if (!isRemovedAccessibleProp(name, oldProps, newProps)) {
+            continue;
+        }
+
+        resetDescriptor(widget, ACCESSIBLE_PROP_MAP[name]);
+        deleteAccessibleMetadata(widget, name);
+    }
+};
+
+const applyAccessibleProps = (widget: Gtk.Accessible, oldProps: Props | null, newProps: Props): void => {
+    applyChangedProps(widget, oldProps, newProps);
+
+    if (oldProps) {
+        resetRemovedProps(widget, oldProps, newProps);
+    }
+};
+
+export { isAccessibleProp, applyAccessibleProps, type AccessibleProps };

package/src/utils/ref-prop.ts

@@ -0,0 +1,30 @@
+import type { RefObject } from "react";
+
+/**
+ * A way to reach a GObject: the object itself, a ref object whose `current` is the object or null,
+ * or null or undefined when the target is absent.
+ */
+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;
+    }
+
+    if (isRefObject(prop)) {
+        return prop.current;
+    }
+
+    return prop;
+};
+
+export { resolveRefProp, type RefProp };

package/src/utils/settings.ts

@@ -0,0 +1,69 @@
+import type * as Gio from "@gtkx/gi/gio";
+import { packVariant, parseVariantType, unpackVariant, type VariantValue } from "./variant.js";
+
+type SettingsSchemaKeys = Record<string, string>;
+type SettingKindValue<S extends string> = S extends "enum" | "flags" ? number : VariantValue<S>;
+type SettingValue<K extends SettingsSchemaKeys, P extends keyof K> = SettingKindValue<K[P] & string>;
+
+type SettingsSchema<K extends SettingsSchemaKeys = SettingsSchemaKeys> = {
+    id: string;
+    path: string | null;
+    keys: K;
+};
+
+type SettingAccessor<T = unknown> = {
+    get: (settings: Gio.Settings, key: string) => T;
+    set: (settings: Gio.Settings, key: string, value: T) => void;
+};
+
+type ResolvedSettingAccessor<K extends SettingsSchemaKeys, P extends keyof K> = {
+    get: () => SettingValue<K, P>;
+    set: (value: SettingValue<K, P>) => void;
+};
+
+const ACCESSORS: Record<string, SettingAccessor<number> | undefined> = {
+    enum: {
+        get: (settings: Gio.Settings, key: string) => settings.getEnum(key),
+        set: (settings: Gio.Settings, key: string, value: number) => {
+            settings.setEnum(key, value);
+        },
+    },
+    flags: {
+        get: (settings: Gio.Settings, key: string) => settings.getFlags(key),
+        set: (settings: Gio.Settings, key: string, value: number) => {
+            settings.setFlags(key, value);
+        },
+    },
+};
+
+const defaultAccessor = (kind: string): SettingAccessor => {
+    const node = parseVariantType(kind);
+
+    return {
+        get: (settings: Gio.Settings, key: string) => unpackVariant(node, settings.getValue(key)),
+        set: (settings: Gio.Settings, key: string, value: unknown) => {
+            settings.setValue(key, packVariant(node, value));
+        },
+    };
+};
+
+const resolveSettingAccessor = <K extends SettingsSchemaKeys, P extends keyof K>(
+    settings: Gio.Settings,
+    schema: SettingsSchema<K>,
+    key: P & string,
+): ResolvedSettingAccessor<K, P> => {
+    const kind = schema.keys[key];
+
+    if (kind === undefined) {
+        throw new Error(`Key "${key}" is not defined in schema "${schema.id}"`);
+    }
+
+    const accessor = (ACCESSORS[kind] ?? defaultAccessor(kind)) as SettingAccessor<SettingValue<K, P>>;
+
+    return {
+        get: accessor.get.bind(null, settings, key),
+        set: accessor.set.bind(null, settings, key),
+    };
+};
+
+export { resolveSettingAccessor, type SettingsSchemaKeys, type SettingValue, type SettingsSchema };