@gtkx/react 0.20.0 → 0.21.0

package/dist/use-setting.js

@@ -0,0 +1,68 @@
+import * as Gio from "@gtkx/ffi/gio";
+import * as GObject from "@gtkx/ffi/gobject";
+import { useCallback, useEffect, useMemo, useState } from "react";
+const GETTERS = {
+    boolean: "getBoolean",
+    int: "getInt",
+    double: "getDouble",
+    string: "getString",
+    strv: "getStrv",
+};
+const SETTERS = {
+    boolean: "setBoolean",
+    int: "setInt",
+    double: "setDouble",
+    string: "setString",
+    strv: "setStrv",
+};
+function readSetting(settings, key, type) {
+    const getter = settings[GETTERS[type]];
+    return getter.call(settings, key);
+}
+function writeSetting(settings, key, type, value) {
+    const setter = settings[SETTERS[type]];
+    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(schemaId, key, type) {
+    const settings = useMemo(() => new Gio.Settings(schemaId), [schemaId]);
+    const [value, setValue] = useState(() => readSetting(settings, key, type));
+    useEffect(() => {
+        setValue(readSetting(settings, key, type));
+        const handlerId = settings.connect(`changed::${key}`, () => {
+            setValue(readSetting(settings, key, type));
+        });
+        return () => {
+            GObject.signalHandlerDisconnect(settings, handlerId);
+        };
+    }, [settings, key, type]);
+    const set = useCallback((newValue) => {
+        writeSetting(settings, key, type, newValue);
+    }, [settings, key, type]);
+    return [value, set];
+}
+//# sourceMappingURL=use-setting.js.map

package/dist/use-setting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-setting.js","sourceRoot":"","sources":["../src/use-setting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,eAAe,CAAC;AACrC,OAAO,KAAK,OAAO,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAYlE,MAAM,OAAO,GAAgC;IACzC,OAAO,EAAE,YAAY;IACrB,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,IAAI,EAAE,SAAS;CAClB,CAAC;AAEF,MAAM,OAAO,GAAgC;IACzC,OAAO,EAAE,YAAY;IACrB,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,IAAI,EAAE,SAAS;CAClB,CAAC;AAIF,SAAS,WAAW,CAAC,QAAsB,EAAE,GAAW,EAAE,IAAiB;IACvE,MAAM,MAAM,GAAI,QAAuD,CAAC,OAAO,CAAC,IAAI,CAAC,CAAoB,CAAC;IAC1G,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,YAAY,CAAC,QAAsB,EAAE,GAAW,EAAE,IAAiB,EAAE,KAAc;IACxF,MAAM,MAAM,GAAI,QAAuD,CAAC,OAAO,CAAC,IAAI,CAAC,CAAoB,CAAC;IAC1G,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,UAAU,CACtB,QAAgB,EAChB,GAAW,EACX,IAAO;IAEP,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAoB,GAAG,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAsB,CAAC,CAAC;IAEnH,SAAS,CAAC,GAAG,EAAE;QACX,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAsB,CAAC,CAAC;QAEhE,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,GAAG,EAAE,EAAE,GAAG,EAAE;YACvD,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAsB,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,EAAE;YACR,OAAO,CAAC,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACzD,CAAC,CAAC;IACN,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IAE1B,MAAM,GAAG,GAAG,WAAW,CACnB,CAAC,QAA2B,EAAE,EAAE;QAC5B,YAAY,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAChD,CAAC,EACD,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CACxB,CAAC;IAEF,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACxB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/react",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Build GTK4 desktop applications with React and TypeScript",
   "keywords": [
     "gtkx",
@@ -39,8 +39,8 @@
   ],
   "dependencies": {
     "react-reconciler": "^0.33.0",
-    "@gtkx/gir": "0.20.0",
-    "@gtkx/ffi": "0.20.0"
+    "@gtkx/ffi": "0.21.0",
+    "@gtkx/gir": "0.21.0"
   },
   "devDependencies": {
     "@types/react-reconciler": "^0.33.0"

package/src/components/compound.tsx

@@ -0,0 +1,57 @@
+import { createElement, type ReactNode } from "react";
+
+type ContainerSlotChild = (props: { children?: ReactNode }) => ReactNode;
+
+/**
+ * Creates a compound child component that delegates to a ContainerSlot
+ * with a specific method name.
+ *
+ * @param methodName - The container slot method name (e.g., "packStart", "addPrefix")
+ */
+export function createContainerSlotChild(methodName: string): ContainerSlotChild {
+    return (props: { children?: ReactNode }): ReactNode => {
+        return createElement("ContainerSlot", { id: methodName }, props.children);
+    };
+}
+
+/**
+ * Creates a compound child component that delegates to an existing
+ * virtual node intrinsic element.
+ *
+ * @param intrinsicName - The intrinsic element name (e.g., "StackPage", "GridChild")
+ */
+export function createVirtualChild<P extends Record<string, unknown>>(
+    intrinsicName: string,
+): (props: P & { children?: ReactNode }) => ReactNode {
+    return (props: P & { children?: ReactNode }): ReactNode => {
+        return createElement(intrinsicName, props, props.children);
+    };
+}
+
+/**
+ * Creates a compound child component for NavigationPage that automatically
+ * sets the `for` discriminant based on the parent widget type.
+ *
+ * @param forValue - The `for` discriminant value (e.g., "AdwNavigationView")
+ */
+export function createNavigationPageChild<P extends Record<string, unknown>>(
+    forValue: string,
+): (props: P & { children?: ReactNode }) => ReactNode {
+    return (props: P & { children?: ReactNode }): ReactNode => {
+        return createElement("NavigationPage", { ...props, for: forValue }, props.children);
+    };
+}
+
+/**
+ * Creates a compound child component for menu items that delegates to
+ * an existing menu intrinsic element.
+ *
+ * @param intrinsicName - "MenuItem", "MenuSection", or "MenuSubmenu"
+ */
+export function createMenuChild<P extends Record<string, unknown>>(
+    intrinsicName: string,
+): (props: P & { children?: ReactNode }) => ReactNode {
+    return (props: P & { children?: ReactNode }): ReactNode => {
+        return createElement(intrinsicName, props, props.children);
+    };
+}

package/src/components/list.tsx

@@ -8,9 +8,19 @@ import type {
     GtkGridViewProps,
     GtkListViewProps,
 } from "../generated/jsx.js";
-import type { DropDownProps, GridViewProps, ListItem, ListViewProps } from "../jsx.js";
+import type {
+    ColumnViewColumnProps,
+    DropDownProps,
+    GridViewProps,
+    ListItem,
+    ListViewProps,
+    MenuItemProps,
+    MenuSectionProps,
+    MenuSubmenuProps,
+} from "../jsx.js";
 import type { BoundItem } from "../nodes/internal/bound-item.js";
 import { createPortal } from "../portal.js";
+import { createMenuChild } from "./compound.js";
 
 type GenericListViewProps<T, S> = Omit<GtkListViewProps, keyof ListViewProps> & ListViewProps<T, S>;
 type GenericGridViewProps<T> = Omit<GtkGridViewProps, keyof GridViewProps> & GridViewProps<T>;
@@ -52,30 +62,77 @@ function renderListElement(intrinsicName: string, handle: ReturnType<typeof useL
     );
 }
 
+/**
+ * Virtualized scrollable list that renders items from a flat or tree data model.
+ *
+ * Wraps `GtkListView` with React-managed item rendering via portals,
+ * supporting single/multi selection, section headers, and tree expansion.
+ */
 export function GtkListView<T = unknown, S = unknown>(
     props: GenericListViewProps<T, S> & { children?: ReactNode; ref?: Ref<Gtk.ListView> },
 ): ReactNode {
     return renderListElement("GtkListView", useListHandle(), props);
 }
 
+/**
+ * Virtualized scrollable grid that renders items in a multi-column layout.
+ *
+ * Wraps `GtkGridView` with React-managed item rendering via portals,
+ * supporting single/multi selection.
+ */
 export function GtkGridView<T = unknown>(
     props: GenericGridViewProps<T> & { children?: ReactNode; ref?: Ref<Gtk.GridView> },
 ): ReactNode {
     return renderListElement("GtkGridView", useListHandle(), props);
 }
 
-export function GtkColumnView<T = unknown, S = unknown>(
+/** @internal */
+function GtkColumnViewBase<T = unknown, S = unknown>(
     props: GenericColumnViewProps<T, S> & { children?: ReactNode; ref?: Ref<Gtk.ColumnView> },
 ): ReactNode {
     return renderListElement("GtkColumnView", useListHandle(), props);
 }
 
+/**
+ * Multi-column sortable list with React-managed cell rendering.
+ *
+ * Wraps `GtkColumnView` with portal-based factories. Use the
+ * `GtkColumnView.Column` compound component to define columns,
+ * and the `MenuItem` / `MenuSection` / `MenuSubmenu` compounds
+ * for the column header context menu.
+ */
+export const GtkColumnView: typeof GtkColumnViewBase & {
+    Column: <T = unknown>(props: ColumnViewColumnProps<T>) => ReactNode;
+    MenuItem: (props: MenuItemProps) => ReactNode;
+    MenuSection: (props: MenuSectionProps) => ReactNode;
+    MenuSubmenu: (props: MenuSubmenuProps) => ReactNode;
+} = Object.assign(GtkColumnViewBase, {
+    Column: <T = unknown>(props: ColumnViewColumnProps<T>): ReactNode =>
+        createElement("ColumnViewColumn", props, props.children),
+    MenuItem: createMenuChild<MenuItemProps>("MenuItem"),
+    MenuSection: createMenuChild<MenuSectionProps>("MenuSection"),
+    MenuSubmenu: createMenuChild<MenuSubmenuProps>("MenuSubmenu"),
+});
+
+/**
+ * Single-selection dropdown widget with React-managed item rendering.
+ *
+ * Wraps `GtkDropDown` with portal-based factories, supporting custom
+ * item templates, separate list-item templates, and section headers.
+ */
 export function GtkDropDown<T = unknown, S = unknown>(
     props: GenericDropDownProps<T, S> & { children?: ReactNode; ref?: Ref<Gtk.DropDown> },
 ): ReactNode {
     return renderListElement("GtkDropDown", useListHandle(), props);
 }
 
+/**
+ * Libadwaita combo row with React-managed item rendering.
+ *
+ * Wraps `AdwComboRow` with portal-based factories, providing a
+ * preferences-style dropdown row with custom item templates and
+ * section headers.
+ */
 export function AdwComboRow<T = unknown, S = unknown>(
     props: GenericComboRowProps<T, S> & { children?: ReactNode; ref?: Ref<Adw.ComboRow> },
 ): ReactNode {

package/src/components/slot-widget.tsx

@@ -0,0 +1,46 @@
+import { createElement, type ReactNode } from "react";
+
+type SlotPropValue = ReactNode | null | undefined;
+
+/**
+ * Creates a function component for a widget that has named property slots.
+ *
+ * The returned component extracts slot props (ReactNode values), forwards
+ * remaining props to the underlying intrinsic element, and appends internal
+ * Slot children for each non-null slot prop.
+ *
+ * @param intrinsicName - The intrinsic element name (e.g., "GtkWindow")
+ * @param slotNames - Array of camelCase slot prop names (e.g., ["titlebar", "startChild"])
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Props interfaces don't satisfy Record<string, unknown>
+export function createSlotWidget<P = any>(
+    intrinsicName: string,
+    slotNames: readonly string[],
+): (props: P & { children?: ReactNode }) => ReactNode {
+    const slotSet = new Set(slotNames);
+
+    return (props: P & { children?: ReactNode }): ReactNode => {
+        const forwardedProps: Record<string, unknown> = {};
+        const slotChildren: ReactNode[] = [];
+        const propsRecord = props as Record<string, unknown>;
+
+        for (const key in propsRecord) {
+            if (slotSet.has(key)) {
+                const value = propsRecord[key] as SlotPropValue;
+                if (value != null) {
+                    slotChildren.push(createElement("Slot", { key: `__slot_${key}`, id: key }, value));
+                }
+            } else {
+                forwardedProps[key] = propsRecord[key];
+            }
+        }
+
+        const { children } = props;
+
+        if (slotChildren.length > 0) {
+            return createElement(intrinsicName, forwardedProps, children, ...slotChildren);
+        }
+
+        return createElement(intrinsicName, forwardedProps, children);
+    };
+}

package/src/errors.ts

@@ -1,3 +1,9 @@
+/**
+ * Error subclass thrown by the GTKX reconciler and rendering pipeline.
+ *
+ * Carries optional context about the widget type that failed and the
+ * React component stack at the point of failure.
+ */
 export class GtkxError extends Error {
     constructor(
         message: string,
@@ -32,14 +38,9 @@ export function formatRenderError(error: unknown, widgetType?: string): GtkxErro
         return error;
     }
 
-    if (error instanceof Error) {
-        console.error("[formatRenderError] Original error stack:", error.stack);
-    }
-
     const message = error instanceof Error ? error.message : String(error);
-    const formattedMessage = widgetType ? `Failed to render ${widgetType}: ${message}` : `Render error: ${message}`;
 
-    return new GtkxError(formattedMessage, widgetType);
+    return new GtkxError(message, widgetType);
 }
 
 export function formatBoundaryError(error: unknown): GtkxError {
@@ -48,5 +49,5 @@ export function formatBoundaryError(error: unknown): GtkxError {
     }
 
     const message = error instanceof Error ? error.message : String(error);
-    return new GtkxError(`Error caught by boundary: ${message}`);
+    return new GtkxError(message);
 }