@gtkx/react 0.21.0 → 1.0.0-rc.2

package/src/hooks/use-merged-refs.ts

@@ -0,0 +1,64 @@
+import { isRecord } from "@gtkx/utils";
+import { type Ref, type RefCallback, useMemo } from "react";
+
+type PossibleRef<T> = Ref<T> | undefined;
+type RefCleanup<T> = ReturnType<RefCallback<T>>;
+type CleanupMap<T> = Map<PossibleRef<T>, Exclude<RefCleanup<T>, void>>;
+
+function assignRef<T>(ref: PossibleRef<T>, value: T): RefCleanup<T> {
+    if (typeof ref === "function") {
+        return ref(value);
+    }
+
+    if (isRecord(ref) && "current" in ref) {
+        ref.current = value;
+    }
+}
+
+function collectCleanup<T>(cleanupMap: CleanupMap<T>, ref: PossibleRef<T>, node: T | null): void {
+    const cleanup = assignRef(ref, node);
+
+    if (cleanup) {
+        cleanupMap.set(ref, cleanup);
+    }
+}
+
+function cleanupRef<T>(cleanupMap: CleanupMap<T>, ref: PossibleRef<T>): void {
+    const cleanup = cleanupMap.get(ref);
+
+    if (cleanup && typeof cleanup === "function") {
+        cleanup();
+    } else {
+        assignRef(ref, null);
+    }
+}
+
+function applyRefs<T>(cleanupMap: CleanupMap<T>, refs: PossibleRef<T>[], node: T | null): RefCleanup<T> {
+    for (const ref of refs) {
+        collectCleanup(cleanupMap, ref, node);
+    }
+
+    if (cleanupMap.size === 0) {
+        return;
+    }
+
+    return () => {
+        for (const ref of refs) {
+            cleanupRef(cleanupMap, ref);
+        }
+
+        cleanupMap.clear();
+    };
+}
+
+function mergeRefs<T>(...refs: PossibleRef<T>[]): RefCallback<T> {
+    const cleanupMap: CleanupMap<T> = new Map();
+
+    return (node: T | null): RefCleanup<T> => applyRefs(cleanupMap, refs, node);
+}
+
+function useMergedRef<T>(first: PossibleRef<T>, second: PossibleRef<T>): RefCallback<T> {
+    return useMemo(() => mergeRefs(first, second), [first, second]);
+}
+
+export { assignRef, mergeRefs, useMergedRef };

package/src/hooks/use-object-value.ts

@@ -0,0 +1,54 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type { SignalHandler } from "@gtkx/runtime";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { type RefProp, resolveRefProp } from "../utils/ref-prop.js";
+
+type ObjectValueCache<T extends GObject.Object, V> = {
+    object: T | null;
+    signal: string;
+    value: V;
+};
+
+function useObjectValue<T extends GObject.Object, V>(
+    object: RefProp<T>,
+    signal: string,
+    read: (object: T | null) => V,
+): V {
+    const resolved = resolveRefProp(object);
+    const cacheRef = useRef<ObjectValueCache<T, V> | null>(null);
+
+    const subscribe = useCallback(
+        (onStoreChange: () => void): (() => void) => {
+            if (resolved === null) {
+                return (): void => undefined;
+            }
+
+            const handler: SignalHandler = () => {
+                cacheRef.current = null;
+                onStoreChange();
+            };
+
+            resolved.on(signal, handler);
+
+            return () => resolved.off(signal, handler);
+        },
+        [resolved, signal],
+    );
+
+    const getSnapshot = (): V => {
+        const cache = cacheRef.current;
+
+        if (cache !== null && cache.object === resolved && cache.signal === signal) {
+            return cache.value;
+        }
+
+        const value = read(resolved);
+        cacheRef.current = { object: resolved, signal, value };
+
+        return value;
+    };
+
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+export { useObjectValue };

package/src/hooks/use-parent-window.ts

@@ -0,0 +1,11 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type Context, createContext, use } from "react";
+
+const ParentWindowContext: Context<Gtk.Window | null> = createContext<Gtk.Window | null>(null);
+
+/**
+ * Returns the `Gtk.Window` provided by the nearest window ancestor, or `null` when there is none.
+ */
+const useParentWindow = (): Gtk.Window | null => use(ParentWindowContext);
+
+export { ParentWindowContext, useParentWindow };

package/src/hooks/use-property.ts

@@ -0,0 +1,23 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import { kebabCase } from "@gtkx/utils";
+import type { RefProp } from "../utils/ref-prop.js";
+import { useObjectValue } from "./use-object-value.js";
+
+type Properties<T extends GObject.Object> = NonNullable<T["__properties__"]>;
+type PropertyName<T extends GObject.Object> = keyof Properties<T> & keyof T;
+
+/**
+ * Subscribes to a GObject property and returns its current value, re-rendering when the property changes.
+ *
+ * @param object The GObject (or ref to one) whose property to observe.
+ * @param propertyName The camelCase name of a readable property on the object.
+ * @returns The current property value, or `undefined` when the object is not resolved.
+ */
+function useProperty<T extends GObject.Object, P extends PropertyName<T>>(
+    object: RefProp<T>,
+    propertyName: P & string,
+): T[P] | undefined {
+    return useObjectValue(object, `notify::${kebabCase(propertyName)}`, (obj) => obj?.[propertyName]);
+}
+
+export { useProperty, type PropertyName };

package/src/hooks/use-setting.ts

@@ -0,0 +1,34 @@
+import * as Gio from "@gtkx/gi/gio";
+import { useMemo } from "react";
+import {
+    resolveSettingAccessor,
+    type SettingsSchema,
+    type SettingsSchemaKeys,
+    type SettingValue,
+} from "../utils/settings.js";
+import { useObjectValue } from "./use-object-value.js";
+
+type UseSettingsProps<K extends SettingsSchemaKeys> = Pick<SettingsSchema<K>, "id" | "path">;
+
+const useSettings = <K extends SettingsSchemaKeys>({ id, path }: UseSettingsProps<K>): Gio.Settings =>
+    useMemo(() => (path ? new Gio.Settings({ schema: id, path }) : Gio.Settings.new(id)), [id, path]);
+
+/**
+ * Reads and writes a single key of a GSettings schema, re-rendering when the stored value changes.
+ *
+ * @param schema The schema reference identifying the settings backend.
+ * @param key The key within the schema to read and write.
+ * @returns A tuple of the current value and a setter that persists a new value.
+ */
+function useSetting<K extends SettingsSchemaKeys, P extends keyof K>(
+    schema: SettingsSchema<K>,
+    key: P & string,
+): [SettingValue<K, P>, (value: SettingValue<K, P>) => void] {
+    const settings = useSettings({ id: schema.id, path: schema.path });
+    const accessor = resolveSettingAccessor(settings, schema, key);
+    const value = useObjectValue(settings, `changed::${key}`, () => accessor.get());
+
+    return [value, accessor.set];
+}
+
+export { useSettings, useSetting };

package/src/hooks/use-signal.ts

@@ -0,0 +1,60 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type { SignalHandler } from "@gtkx/runtime";
+import { useEffectEvent, useLayoutEffect } from "react";
+import { type RefProp, resolveRefProp } from "../utils/ref-prop.js";
+
+type Signals<T extends GObject.Object> = NonNullable<T["__signals__"]>;
+type SignalName<T extends GObject.Object> = keyof Signals<T> | `${keyof Signals<T> & string}::${string}`;
+
+type TypedSignalHandler<T extends GObject.Object, S extends string> = S extends keyof Signals<T>
+    ? Signals<T>[S]
+    : S extends `${infer TBase}::${string}`
+        ? TBase extends keyof Signals<T>
+            ? Signals<T>[TBase]
+            : SignalHandler
+        : SignalHandler;
+
+type UseSignalOptions = {
+    after?: boolean;
+    immediate?: boolean;
+};
+
+/**
+ * Connects a handler to a GObject signal for the lifetime of the component, reconnecting when the object changes.
+ *
+ * Each emission runs the handler from the latest render, so it does not have to be stable and a
+ * changing handler never reconnects the signal.
+ *
+ * @param object The GObject (or ref to one) to connect to.
+ * @param signal The signal name, optionally with a detail suffix.
+ * @param handler The callback invoked when the signal is emitted.
+ * @param options Connection options such as running after the default handler or invoking immediately.
+ */
+function useSignal<T extends GObject.Object, S extends SignalName<T> & string>(
+    object: RefProp<T>,
+    signal: S,
+    handler: TypedSignalHandler<T, S>,
+    { after = false, immediate = false }: UseSignalOptions = {},
+): void {
+    const emit = useEffectEvent(handler as SignalHandler);
+
+    useLayoutEffect(() => {
+        const resolved = resolveRefProp(object);
+
+        if (!resolved) {
+            return;
+        }
+
+        resolved.on(signal, emit, after);
+
+        if (immediate) {
+            emit();
+        }
+
+        return () => {
+            resolved.off(signal, emit);
+        };
+    }, [object, signal, after, immediate]);
+}
+
+export { useSignal, type SignalName, type TypedSignalHandler };

package/src/index.ts

@@ -1,14 +1,14 @@
-export { GtkxError } from "./errors.js";
-export * from "./jsx.js";
-export { createPortal } from "./portal.js";
-export { reconciler } from "./reconciler.js";
-export {
-    ApplicationContext,
-    quit,
-    render,
-    setHotReloading,
-    update,
-    useApplication,
-} from "./render.js";
-export { useProperty } from "./use-property.js";
-export { useSetting } from "./use-setting.js";
+import "./bootstrap.js";
+
+export { useApplication } from "./hooks/use-application.js";
+export { useBindSetting } from "./hooks/use-bind-setting.js";
+export { useParentWindow } from "./hooks/use-parent-window.js";
+export { useProperty } from "./hooks/use-property.js";
+export { useSetting } from "./hooks/use-setting.js";
+export { useSignal } from "./hooks/use-signal.js";
+export type { MenuItem, VflConstraints } from "./prop-types.js";
+export { type RootElement, rootElement } from "./reconciler/root-element.js";
+export { createPortal, createRoot, quit, type Root } from "./reconciler/root.js";
+export type { AccessibleProps } from "./utils/accessible-props.js";
+export type { RefProp } from "./utils/ref-prop.js";
+export type { SettingsSchema, SettingsSchemaKeys, SettingValue } from "./utils/settings.js";

package/src/internal.ts

@@ -0,0 +1,13 @@
+import "./bootstrap.js";
+
+export { createApplicationComponent } from "./components/application.js";
+export { createElementComponent } from "./components/element.js";
+export { createWindowComponent } from "./components/window.js";
+export { ApplicationContext } from "./hooks/use-application.js";
+export { useMergedRef } from "./hooks/use-merged-refs.js";
+export { useObjectValue } from "./hooks/use-object-value.js";
+export type * from "./prop-types.js";
+export { isRootElement } from "./reconciler/root-element.js";
+export { createReconcilerRoot, type ReconcilerRoot, setReconcilerErrorHandler } from "./reconciler/root.js";
+export { getAccessibleMetadata } from "./utils/accessible-metadata.js";
+export { type RefProp, resolveRefProp } from "./utils/ref-prop.js";

package/src/prop-types.ts

@@ -0,0 +1,142 @@
+import type * as Gdk from "@gtkx/gi/gdk";
+import type * as GObject from "@gtkx/gi/gobject";
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { ReactNode } from "react";
+
+/** One entry of a `GMenu`'s `items` prop; `submenu` and `section` nest further menus. */
+type MenuItem = {
+    label?: string | null;
+    action?: string | null;
+    submenu?: MenuItem[];
+    section?: MenuItem[];
+};
+
+/** One Visual Format Language block applied to a `Gtk.ConstraintLayout`. */
+type VflConstraints = {
+    lines: string[];
+    hspacing?: number;
+    vspacing?: number;
+    views?: Map<string, Gtk.ConstraintTarget>;
+};
+
+/** One mark on a `Gtk.Scale`. */
+type ScaleMark = { value?: number; position: Gtk.PositionType; markup?: string | null };
+/** One labelled offset on a `Gtk.LevelBar`. */
+type LevelBarOffset = { name: string; value?: number };
+/** One credit section on a `Gtk.AboutDialog`. */
+type CreditSection = { sectionName: string; people: string[] };
+/** One accelerator binding on a `Gtk.Application`. */
+type ActionAccel = { detailedActionName: string; accels: string[] };
+/** The drag icon of a `Gtk.DragSource`, with its hotspot. */
+type DragSourceIcon = { paintable?: Gdk.Paintable | null; hotX?: number; hotY?: number };
+
+/** Props of an element that accepts children. */
+type ChildrenProps = {
+    children?: ReactNode;
+};
+
+type GtkWidgetProps = {
+    controllers?: ReactNode | null | undefined;
+    actionGroups?: ReactNode | null | undefined;
+} & ChildrenProps;
+
+type GActionGroupProps = {
+    prefix?: string | null | undefined;
+};
+
+type GActionMapProps = {
+    actions?: ReactNode | null | undefined;
+};
+
+type GMenuProps = {
+    items?: MenuItem[] | null | undefined;
+};
+
+type GtkShortcutControllerProps = {
+    shortcuts?: ReactNode | null | undefined;
+};
+
+type GtkOverlayProps = {
+    overlays?: ReactNode | null | undefined;
+} & ChildrenProps;
+
+type GtkConstraintLayoutProps = {
+    constraints?: ReactNode | null | undefined;
+    guides?: ReactNode | null | undefined;
+    vfl?: VflConstraints[] | null | undefined;
+};
+
+/** Props of `GtkTextChildAnchor`, which embeds either a child widget or a paintable in a text buffer. */
+type GtkTextChildAnchorProps = {
+    paintable?: Gdk.Paintable | null | undefined;
+} & ChildrenProps;
+
+type GtkHeaderBarProps = {
+    start?: ReactNode | null | undefined;
+    end?: ReactNode | null | undefined;
+};
+
+type GtkScaleProps = {
+    marks?: ScaleMark[] | null | undefined;
+};
+
+type GtkCalendarProps = {
+    markedDays?: number[] | null | undefined;
+};
+
+type GtkLevelBarProps = {
+    offsets?: LevelBarOffset[] | null | undefined;
+};
+
+type GtkSizeGroupProps = {
+    widgets?: Gtk.Widget[] | null | undefined;
+};
+
+type GtkAboutDialogProps = {
+    creditSections?: CreditSection[] | null | undefined;
+};
+
+type GtkApplicationProps = {
+    actionAccels?: ActionAccel[] | null | undefined;
+} & ChildrenProps;
+
+type GtkDropTargetProps = {
+    types?: GObject.Type[] | null | undefined;
+};
+
+type GtkDrawingAreaProps = {
+    drawFunc?: Gtk.DrawingAreaDrawFunc | null | undefined;
+};
+
+type GtkDragSourceProps = {
+    icon?: DragSourceIcon | null | undefined;
+};
+
+export {
+    type MenuItem,
+    type VflConstraints,
+    type ScaleMark,
+    type LevelBarOffset,
+    type CreditSection,
+    type ActionAccel,
+    type DragSourceIcon,
+    type ChildrenProps,
+    type GtkWidgetProps,
+    type GActionGroupProps,
+    type GActionMapProps,
+    type GMenuProps,
+    type GtkShortcutControllerProps,
+    type GtkOverlayProps,
+    type GtkTextChildAnchorProps,
+    type GtkConstraintLayoutProps,
+    type GtkHeaderBarProps,
+    type GtkScaleProps,
+    type GtkCalendarProps,
+    type GtkLevelBarProps,
+    type GtkSizeGroupProps,
+    type GtkAboutDialogProps,
+    type GtkApplicationProps,
+    type GtkDropTargetProps,
+    type GtkDrawingAreaProps,
+    type GtkDragSourceProps,
+};