@gtkx/react 0.20.0 → 0.21.0

package/src/nodes/notebook-page.ts

@@ -161,11 +161,11 @@ export class NotebookPageNode extends VirtualNode<NotebookPageProps, WidgetNode<
         if (!page) return;
 
         if (this.props.tabExpand !== undefined) {
-            page.setTabExpand(this.props.tabExpand);
+            page.tabExpand = this.props.tabExpand;
         }
 
         if (this.props.tabFill !== undefined) {
-            page.setTabFill(this.props.tabFill);
+            page.tabFill = this.props.tabFill;
         }
     }
 

package/src/nodes/overlay-child.ts

@@ -1,6 +1,7 @@
 import * as Gtk from "@gtkx/ffi/gtk";
 import type { OverlayChildProps } from "../jsx.js";
 import type { Node } from "../node.js";
+import { isRemovable } from "./internal/predicates.js";
 import { hasChanged } from "./internal/props.js";
 import { VirtualNode } from "./virtual.js";
 import { WidgetNode } from "./widget.js";
@@ -32,6 +33,7 @@ export class OverlayChildNode extends VirtualNode<OverlayChildProps, WidgetNode<
         super.appendChild(child);
 
         if (this.parent) {
+            this.detachFromGtkParent(child);
             this.attachToParent(this.parent.container, child.container);
         }
     }
@@ -40,19 +42,12 @@ export class OverlayChildNode extends VirtualNode<OverlayChildProps, WidgetNode<
         super.insertBefore(child, before);
 
         if (this.parent) {
-            this.attachToParent(this.parent.container, child.container);
+            this.reinsertAllChildren();
         }
     }
 
     public override removeChild(child: WidgetNode): void {
-        if (this.parent) {
-            const widget = child.container;
-            const currentParent = widget.getParent();
-            if (currentParent && currentParent === this.parent.container) {
-                this.parent.container.removeOverlay(widget);
-            }
-        }
-
+        this.detachFromGtkParent(child);
         super.removeChild(child);
     }
 
@@ -98,6 +93,32 @@ export class OverlayChildNode extends VirtualNode<OverlayChildProps, WidgetNode<
         }
     }
 
+    private detachFromGtkParent(child: WidgetNode): void {
+        const currentParent = child.container.getParent();
+        if (currentParent !== null) {
+            if (currentParent instanceof Gtk.Overlay) {
+                currentParent.removeOverlay(child.container);
+            } else if (isRemovable(currentParent)) {
+                currentParent.remove(child.container);
+            } else {
+                child.container.unparent();
+            }
+        }
+    }
+
+    private reinsertAllChildren(): void {
+        if (!this.parent) return;
+        const parent = this.parent.container;
+
+        for (const child of this.children) {
+            this.detachFromGtkParent(child);
+        }
+
+        for (const child of this.children) {
+            this.attachToParent(parent, child.container);
+        }
+    }
+
     private detachAllChildren(parent: Gtk.Overlay): void {
         for (const child of this.children) {
             const currentParent = child.container.getParent();

package/src/nodes/spin-row.ts

@@ -0,0 +1,72 @@
+import type * as Adw from "@gtkx/ffi/adw";
+import * as Gtk from "@gtkx/ffi/gtk";
+import type { AdjustableProps } from "../jsx.js";
+import { filterProps, hasChanged } from "./internal/props.js";
+import { WidgetNode } from "./widget.js";
+
+type SpinRowProps = AdjustableProps & {
+    onValueChanged?: ((value: number, self: Adw.SpinRow) => void) | null;
+};
+
+const OWN_PROPS = ["value", "lower", "upper", "stepIncrement", "pageIncrement", "pageSize", "onValueChanged"] as const;
+
+export class SpinRowNode extends WidgetNode<Adw.SpinRow, SpinRowProps> {
+    private adjustment: Gtk.Adjustment | null = null;
+
+    public override commitUpdate(oldProps: SpinRowProps | null, newProps: SpinRowProps): void {
+        super.commitUpdate(oldProps ? filterProps(oldProps, OWN_PROPS) : null, filterProps(newProps, OWN_PROPS));
+        this.applyOwnProps(oldProps, newProps);
+    }
+
+    private ensureAdjustment(props: SpinRowProps): Gtk.Adjustment {
+        if (!this.adjustment) {
+            this.adjustment = new Gtk.Adjustment(
+                props.value ?? 0,
+                props.lower ?? 0,
+                props.upper ?? 100,
+                props.stepIncrement ?? 1,
+                props.pageIncrement ?? 10,
+                props.pageSize ?? 0,
+            );
+
+            this.container.setAdjustment(this.adjustment);
+        }
+
+        return this.adjustment;
+    }
+
+    private applyOwnProps(oldProps: SpinRowProps | null, newProps: SpinRowProps): void {
+        const adjustment = this.ensureAdjustment(newProps);
+
+        if (hasChanged(oldProps, newProps, "onValueChanged")) {
+            const { onValueChanged } = newProps;
+            this.signalStore.set(
+                this,
+                this.container,
+                "notify::value",
+                onValueChanged ? (self: Adw.SpinRow) => onValueChanged(self.getValue(), self) : undefined,
+            );
+        }
+
+        if (!oldProps) return;
+
+        if (hasChanged(oldProps, newProps, "lower")) {
+            adjustment.setLower(newProps.lower ?? 0);
+        }
+        if (hasChanged(oldProps, newProps, "upper")) {
+            adjustment.setUpper(newProps.upper ?? 100);
+        }
+        if (hasChanged(oldProps, newProps, "stepIncrement")) {
+            adjustment.setStepIncrement(newProps.stepIncrement ?? 1);
+        }
+        if (hasChanged(oldProps, newProps, "pageIncrement")) {
+            adjustment.setPageIncrement(newProps.pageIncrement ?? 10);
+        }
+        if (hasChanged(oldProps, newProps, "pageSize")) {
+            adjustment.setPageSize(newProps.pageSize ?? 0);
+        }
+        if (hasChanged(oldProps, newProps, "value") && newProps.value !== undefined) {
+            adjustment.setValue(newProps.value);
+        }
+    }
+}

package/src/nodes/switch-row.ts

@@ -0,0 +1,26 @@
+import type * as Adw from "@gtkx/ffi/adw";
+import { hasChanged } from "./internal/props.js";
+import { WidgetNode } from "./widget.js";
+
+type SwitchRowProps = {
+    onActiveChanged?: ((active: boolean, self: Adw.SwitchRow) => void) | null;
+};
+
+export class SwitchRowNode extends WidgetNode<Adw.SwitchRow, SwitchRowProps> {
+    public override commitUpdate(oldProps: SwitchRowProps | null, newProps: SwitchRowProps): void {
+        super.commitUpdate(oldProps, newProps);
+        this.applyOwnProps(oldProps, newProps);
+    }
+
+    private applyOwnProps(oldProps: SwitchRowProps | null, newProps: SwitchRowProps): void {
+        if (hasChanged(oldProps, newProps, "onActiveChanged")) {
+            const { onActiveChanged } = newProps;
+            this.signalStore.set(
+                this,
+                this.container,
+                "notify::active",
+                onActiveChanged ? (self: Adw.SwitchRow) => onActiveChanged(self.getActive(), self) : undefined,
+            );
+        }
+    }
+}

package/src/nodes/text-anchor.ts

@@ -1,6 +1,7 @@
 import * as Gtk from "@gtkx/ffi/gtk";
 import type { TextAnchorProps } from "../jsx.js";
 import type { Node } from "../node.js";
+import { isRemovable } from "./internal/predicates.js";
 import { TEXT_OBJECT_REPLACEMENT, type TextContentParent } from "./text-content.js";
 import { isTextContentParent } from "./text-segment.js";
 import { VirtualNode } from "./virtual.js";
@@ -66,6 +67,14 @@ export class TextAnchorNode extends VirtualNode<TextAnchorProps, Node & TextCont
         super.appendChild(child);
 
         if (this.textView && this.anchor && child.container) {
+            const currentParent = child.container.getParent();
+            if (currentParent !== null) {
+                if (isRemovable(currentParent)) {
+                    currentParent.remove(child.container);
+                } else {
+                    child.container.unparent();
+                }
+            }
             this.textView.addChildAtAnchor(child.container, this.anchor);
         }
     }

package/src/nodes/text-tag.ts

@@ -8,45 +8,45 @@ import { TextPaintableNode } from "./text-paintable.js";
 import { isTextContentParent, TextSegmentNode } from "./text-segment.js";
 import { VirtualNode } from "./virtual.js";
 
-const STYLE_PROPS: Partial<Record<keyof TextTagProps, keyof Gtk.TextTag>> = {
+const STYLE_PROPS: Partial<Record<keyof TextTagProps, keyof Gtk.TextTag | string>> = {
     background: "setBackground",
-    backgroundFullHeight: "setBackgroundFullHeight",
+    backgroundFullHeight: "backgroundFullHeight",
     foreground: "setForeground",
-    family: "setFamily",
-    font: "setFont",
-    sizePoints: "setSizePoints",
-    size: "setSize",
-    scale: "setScale",
-    weight: "setWeight",
-    style: "setStyle",
-    stretch: "setStretch",
-    variant: "setVariant",
-    strikethrough: "setStrikethrough",
-    underline: "setUnderline",
-    overline: "setOverline",
-    rise: "setRise",
-    letterSpacing: "setLetterSpacing",
-    lineHeight: "setLineHeight",
-    leftMargin: "setLeftMargin",
-    rightMargin: "setRightMargin",
-    indent: "setIndent",
-    pixelsAboveLines: "setPixelsAboveLines",
-    pixelsBelowLines: "setPixelsBelowLines",
-    pixelsInsideWrap: "setPixelsInsideWrap",
-    justification: "setJustification",
-    direction: "setDirection",
-    wrapMode: "setWrapMode",
-    editable: "setEditable",
-    invisible: "setInvisible",
-    allowBreaks: "setAllowBreaks",
-    insertHyphens: "setInsertHyphens",
-    fallback: "setFallback",
-    accumulativeMargin: "setAccumulativeMargin",
+    family: "family",
+    font: "font",
+    sizePoints: "sizePoints",
+    size: "size",
+    scale: "scale",
+    weight: "weight",
+    style: "style",
+    stretch: "stretch",
+    variant: "variant",
+    strikethrough: "strikethrough",
+    underline: "underline",
+    overline: "overline",
+    rise: "rise",
+    letterSpacing: "letterSpacing",
+    lineHeight: "lineHeight",
+    leftMargin: "leftMargin",
+    rightMargin: "rightMargin",
+    indent: "indent",
+    pixelsAboveLines: "pixelsAboveLines",
+    pixelsBelowLines: "pixelsBelowLines",
+    pixelsInsideWrap: "pixelsInsideWrap",
+    justification: "justification",
+    direction: "direction",
+    wrapMode: "wrapMode",
+    editable: "editable",
+    invisible: "invisible",
+    allowBreaks: "allowBreaks",
+    insertHyphens: "insertHyphens",
+    fallback: "fallback",
+    accumulativeMargin: "accumulativeMargin",
     paragraphBackground: "setParagraphBackground",
-    showSpaces: "setShowSpaces",
-    textTransform: "setTextTransform",
-    fontFeatures: "setFontFeatures",
-    language: "setLanguage",
+    showSpaces: "showSpaces",
+    textTransform: "textTransform",
+    fontFeatures: "fontFeatures",
+    language: "language",
 };
 
 type TextTagParent = Node & TextContentParent;
@@ -225,10 +225,15 @@ export class TextTagNode
         for (const prop of Object.keys(STYLE_PROPS) as (keyof TextTagProps)[]) {
             if (hasChanged(oldProps, newProps, prop)) {
                 const value = newProps[prop];
-                const method = STYLE_PROPS[prop];
-                if (value !== undefined && method) {
-                    const setter = this.tag[method] as (value: unknown) => void;
-                    setter.call(this.tag, value);
+                const target = STYLE_PROPS[prop];
+                if (value !== undefined && target) {
+                    const tag = this.tag as unknown as Record<string, unknown>;
+                    const member = tag[target];
+                    if (typeof member === "function") {
+                        (member as (v: unknown) => void).call(this.tag, value);
+                    } else {
+                        tag[target] = value;
+                    }
                 }
             }
         }

package/src/nodes/toggle-group.ts

@@ -1,19 +1,41 @@
-import type * as Adw from "@gtkx/ffi/adw";
-import type { AdwToggleGroupProps } from "../jsx.js";
+import * as Adw from "@gtkx/ffi/adw";
+import type * as Gtk from "@gtkx/ffi/gtk";
+import type { AdwToggleGroupProps, ToggleProps } from "../jsx.js";
+import type { Container, Props } from "../types.js";
+import { createContainerWithProperties } from "./internal/construct.js";
 import { filterProps, hasChanged } from "./internal/props.js";
 import { WidgetNode } from "./widget.js";
 
-const OWN_PROPS = ["onActiveChanged"] as const;
+const DEFERRED_PROPS = ["activeName", "active"] as const;
+const OWN_PROPS = ["onActiveChanged", "toggles", ...DEFERRED_PROPS] as const;
 
-type ToggleGroupProps = Pick<AdwToggleGroupProps, (typeof OWN_PROPS)[number]>;
+type OwnProps = Pick<AdwToggleGroupProps, (typeof OWN_PROPS)[number]>;
 
-export class ToggleGroupNode extends WidgetNode<Adw.ToggleGroup, ToggleGroupProps> {
-    public override commitUpdate(oldProps: ToggleGroupProps | null, newProps: ToggleGroupProps): void {
-        super.commitUpdate(oldProps ? filterProps(oldProps, OWN_PROPS) : null, filterProps(newProps, OWN_PROPS));
-        this.applyOwnProps(oldProps, newProps);
+export class ToggleGroupNode extends WidgetNode<Adw.ToggleGroup, OwnProps> {
+    private managedToggles: Adw.Toggle[] = [];
+
+    public static override createContainer(props: Props, containerClass: typeof Gtk.Widget): Container | null {
+        const { activeName: _, active: __, ...rest } = props;
+        return createContainerWithProperties(containerClass, rest);
     }
 
-    private applyOwnProps(oldProps: ToggleGroupProps | null, newProps: ToggleGroupProps): void {
+    public override commitUpdate(oldProps: OwnProps | null, newProps: OwnProps): void {
+        if (hasChanged(oldProps, newProps, "toggles")) {
+            this.syncToggles(newProps.toggles ?? []);
+        }
+
+        super.commitUpdate(oldProps ? filterProps(oldProps, OWN_PROPS) : null, filterProps(newProps, OWN_PROPS));
+
+        if (hasChanged(oldProps, newProps, "activeName")) {
+            this.container.setActiveName(newProps.activeName ?? null);
+        }
+
+        if (hasChanged(oldProps, newProps, "active")) {
+            if (newProps.active != null) {
+                this.container.setActive(newProps.active);
+            }
+        }
+
         if (hasChanged(oldProps, newProps, "onActiveChanged")) {
             const callback = newProps.onActiveChanged;
             this.signalStore.set(
@@ -24,4 +46,36 @@ export class ToggleGroupNode extends WidgetNode<Adw.ToggleGroup, ToggleGroupProp
             );
         }
     }
+
+    public override detachDeletedInstance(): void {
+        this.clearToggles();
+        super.detachDeletedInstance();
+    }
+
+    private syncToggles(newToggles: ToggleProps[]): void {
+        this.clearToggles();
+
+        for (const toggleProps of newToggles) {
+            const toggle = new Adw.Toggle();
+            applyToggleProps(toggle, toggleProps);
+            this.container.add(toggle);
+            this.managedToggles.push(toggle);
+        }
+    }
+
+    private clearToggles(): void {
+        for (const toggle of this.managedToggles) {
+            this.container.remove(toggle);
+        }
+        this.managedToggles = [];
+    }
+}
+
+function applyToggleProps(toggle: Adw.Toggle, props: ToggleProps): void {
+    if (props.id != null) toggle.setName(props.id);
+    if (props.label != null) toggle.setLabel(props.label);
+    if (props.iconName != null) toggle.setIconName(props.iconName);
+    if (props.tooltip !== undefined) toggle.setTooltip(props.tooltip);
+    if (props.enabled !== undefined) toggle.setEnabled(props.enabled);
+    if (props.useUnderline !== undefined) toggle.setUseUnderline(props.useUnderline);
 }

package/src/nodes/widget.ts

@@ -297,23 +297,16 @@ export class WidgetNode<
     }
 
     private setProperty(key: string, value: unknown): void {
-        const propMeta = resolvePropMeta(this.container, key);
-        if (!propMeta) return;
+        const propName = resolvePropMeta(this.container, key);
+        if (!propName) return;
 
-        const [getterName, setterName] = propMeta;
-        const setter = this.container[setterName as keyof typeof this.container];
-        if (!setter || typeof setter !== "function") return;
+        const target = this.container as Record<string, unknown>;
 
-        if (getterName && findProperty(this.container, key) instanceof ParamSpecString) {
-            const getter = this.container[getterName as keyof typeof this.container];
-
-            if (getter && typeof getter === "function") {
-                const currentValue = getter.call(this.container);
-                if (currentValue === value) return;
-            }
+        if (findProperty(this.container, key) instanceof ParamSpecString) {
+            if (target[propName] === value) return;
         }
 
-        setter.call(this.container, value);
+        target[propName] = value;
     }
 
     private insertBeforeReorderable(container: ReorderableWidget, child: WidgetNode, before: WidgetNode): void {

package/src/registry.ts

@@ -5,7 +5,7 @@ import * as WebKit from "@gtkx/ffi/webkit";
 import type { Node } from "./node.js";
 import { AdjustableNode } from "./nodes/adjustable.js";
 
-import { AlertDialogResponseNode } from "./nodes/alert-dialog-response.js";
+import { AlertDialogNode } from "./nodes/alert-dialog.js";
 import { AnimationNode } from "./nodes/animation.js";
 import { ApplicationNode } from "./nodes/application.js";
 import { CalendarNode } from "./nodes/calendar.js";
@@ -35,14 +35,15 @@ import { SearchBarNode } from "./nodes/search-bar.js";
 import { ShortcutNode } from "./nodes/shortcut.js";
 import { SlotNode } from "./nodes/slot.js";
 import { SourceViewNode } from "./nodes/source-view.js";
+import { SpinRowNode } from "./nodes/spin-row.js";
 import { StackNode } from "./nodes/stack.js";
 import { StackPageNode } from "./nodes/stack-page.js";
+import { SwitchRowNode } from "./nodes/switch-row.js";
 import { TextAnchorNode } from "./nodes/text-anchor.js";
 import { TextPaintableNode } from "./nodes/text-paintable.js";
 import { TextSegmentNode } from "./nodes/text-segment.js";
 import { TextTagNode } from "./nodes/text-tag.js";
 import { TextViewNode } from "./nodes/text-view.js";
-import { ToggleNode } from "./nodes/toggle.js";
 import { ToggleGroupNode } from "./nodes/toggle-group.js";
 import { WebViewNode } from "./nodes/web-view.js";
 import { WidgetNode } from "./nodes/widget.js";
@@ -72,8 +73,7 @@ type NodeRegistryEntry = [RegistryKey, NodeClass];
 
 export const NODE_REGISTRY: NodeRegistryEntry[] = [
     ["ContainerSlot", ContainerSlotNode],
-    ["AlertDialogResponse", AlertDialogResponseNode],
-    ["Animation", AnimationNode],
+    [["AdwTimedAnimation", "AdwSpringAnimation"], AnimationNode],
     ["ColumnViewColumn", ColumnViewColumnNode],
     ["FixedChild", FixedChildNode],
     ["GridChild", GridChildNode],
@@ -89,14 +89,16 @@ export const NODE_REGISTRY: NodeRegistryEntry[] = [
     ["TextPaintable", TextPaintableNode],
     ["TextSegment", TextSegmentNode],
     ["TextTag", TextTagNode],
-    ["Toggle", ToggleNode],
     [Gtk.Application, ApplicationNode],
     [Gtk.EventController, EventControllerNode],
     [GtkSource.View, SourceViewNode],
     [Gtk.TextView, TextViewNode],
     [WebKit.WebView, WebViewNode],
+    [Adw.AlertDialog, AlertDialogNode],
     [Adw.Dialog, DialogNode],
     [Gtk.Window, WindowNode],
+    [Adw.SpinRow, SpinRowNode],
+    [Adw.SwitchRow, SwitchRowNode],
     [Gtk.Scale, ScaleNode],
     [Gtk.LevelBar, LevelBarNode],
     [Gtk.ScrolledWindow, ScrolledWindowNode],

package/src/types.ts

@@ -1,5 +1,6 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 
+/** @internal */
 export type Container = Gtk.Widget | Gtk.Application | Gtk.EventController | Gtk.ListItem | Gtk.ListHeader;
 
 export type Props = Record<string, unknown>;

package/src/use-property.ts

@@ -0,0 +1,58 @@
+import * as GObject from "@gtkx/ffi/gobject";
+import { useEffect, useState } from "react";
+
+type ReadableKey<T> = {
+    [K in keyof T]: K extends string ? (T[K] extends (...args: unknown[]) => unknown ? never : K) : never;
+}[keyof T];
+
+const toKebabCase = (str: string): string =>
+    str.replace(/[A-Z]/g, (c, i: number) => (i === 0 ? c.toLowerCase() : `-${c.toLowerCase()}`));
+
+/**
+ * Subscribes to a GObject property and returns its current value as React state.
+ *
+ * Connects to the `notify::property-name` signal on `obj` and re-renders
+ * whenever the property changes. The initial value is read synchronously
+ * at mount time. Disconnects automatically on unmount or when inputs change.
+ *
+ * When `obj` is `null` or `undefined`, the hook is inactive and returns
+ * `undefined`. This allows safe usage with nullable objects without
+ * violating React's rules of hooks.
+ *
+ * @param obj - The GObject instance to observe, or null/undefined to disable
+ * @param propertyName - The property name matching an ES6 accessor on the object
+ * @returns The current property value, or undefined when obj is null/undefined
+ *
+ * @example
+ * ```tsx
+ * const app = useApplication();
+ * const activeWindow = useProperty(app, "activeWindow");
+ * const title = useProperty(activeWindow, "title");
+ * ```
+ */
+export function useProperty<T extends GObject.Object, K extends ReadableKey<T>>(
+    obj: T | null | undefined,
+    propertyName: K,
+): T[K] | undefined {
+    const [value, setValue] = useState<T[K] | undefined>(() => (obj ? (obj[propertyName] as T[K]) : undefined));
+
+    useEffect(() => {
+        if (!obj) {
+            setValue(undefined);
+            return;
+        }
+
+        setValue(obj[propertyName] as T[K]);
+
+        const signal = `notify::${toKebabCase(propertyName as string)}`;
+        const handlerId = obj.connect(signal, () => {
+            setValue(obj[propertyName] as T[K]);
+        });
+
+        return () => {
+            GObject.signalHandlerDisconnect(obj, handlerId);
+        };
+    }, [obj, propertyName]);
+
+    return value;
+}

package/src/use-setting.ts

@@ -0,0 +1,96 @@
+import * as Gio from "@gtkx/ffi/gio";
+import * as GObject from "@gtkx/ffi/gobject";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+interface SettingTypeMap {
+    boolean: boolean;
+    int: number;
+    double: number;
+    string: string;
+    strv: string[];
+}
+
+type SettingType = keyof SettingTypeMap;
+
+const GETTERS: Record<SettingType, string> = {
+    boolean: "getBoolean",
+    int: "getInt",
+    double: "getDouble",
+    string: "getString",
+    strv: "getStrv",
+};
+
+const SETTERS: Record<SettingType, string> = {
+    boolean: "setBoolean",
+    int: "setInt",
+    double: "setDouble",
+    string: "setString",
+    strv: "setStrv",
+};
+
+type SettingAccessor = (key: string, value?: unknown) => unknown;
+
+function readSetting(settings: Gio.Settings, key: string, type: SettingType): unknown {
+    const getter = (settings as unknown as Record<string, SettingAccessor>)[GETTERS[type]] as SettingAccessor;
+    return getter.call(settings, key);
+}
+
+function writeSetting(settings: Gio.Settings, key: string, type: SettingType, value: unknown): void {
+    const setter = (settings as unknown as Record<string, SettingAccessor>)[SETTERS[type]] as SettingAccessor;
+    setter.call(settings, key, value);
+}
+
+/**
+ * Subscribes to a GSettings key and returns its current value alongside a
+ * setter, similar to `useState`.
+ *
+ * Creates a `Gio.Settings` instance for the given schema (stable across
+ * re-renders), connects to `changed::key`, and re-renders whenever the
+ * setting changes. The initial value is read synchronously at mount time.
+ * Calling the returned setter writes the new value to GSettings, which in
+ * turn triggers a re-render through the `changed` signal.
+ *
+ * @param schemaId - The GSettings schema ID (e.g. `"org.gnome.desktop.interface"`)
+ * @param key - The settings key in kebab-case (e.g. `"color-scheme"`)
+ * @param type - The value type, used to select the appropriate GSettings getter/setter
+ * @returns A `[value, setValue]` tuple kept in sync with the GSettings backend
+ *
+ * @example
+ * ```tsx
+ * const [colorScheme, setColorScheme] = useSetting("org.gnome.desktop.interface", "color-scheme", "string");
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const [fontSize, setFontSize] = useSetting("com.example.myapp", "font-size", "int");
+ * ```
+ */
+export function useSetting<T extends SettingType>(
+    schemaId: string,
+    key: string,
+    type: T,
+): [SettingTypeMap[T], (value: SettingTypeMap[T]) => void] {
+    const settings = useMemo(() => new Gio.Settings(schemaId), [schemaId]);
+    const [value, setValue] = useState<SettingTypeMap[T]>(() => readSetting(settings, key, type) as SettingTypeMap[T]);
+
+    useEffect(() => {
+        setValue(readSetting(settings, key, type) as SettingTypeMap[T]);
+
+        const handlerId = settings.connect(`changed::${key}`, () => {
+            setValue(readSetting(settings, key, type) as SettingTypeMap[T]);
+        });
+
+        return () => {
+            GObject.signalHandlerDisconnect(settings, handlerId);
+        };
+    }, [settings, key, type]);
+
+    const set = useCallback(
+        (newValue: SettingTypeMap[T]) => {
+            writeSetting(settings, key, type, newValue);
+        },
+        [settings, key, type],
+    );
+
+    return [value, set];
+}