@gtkx/react 0.19.0 → 0.21.0

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.19.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/ffi": "0.19.0",
-    "@gtkx/gir": "0.19.0"
+    "@gtkx/ffi": "0.21.0",
+    "@gtkx/gir": "0.21.0"
   },
   "devDependencies": {
     "@types/react-reconciler": "^0.33.0"
@@ -49,6 +49,7 @@
     "react": "^19"
   },
   "scripts": {
-    "build": "tsc -b && cp ../../README.md ."
+    "build": "tsc -b && cp ../../README.md .",
+    "typecheck": "tsc -b --emitDeclarationOnly"
   }
 }

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

@@ -0,0 +1,140 @@
+import type * as Adw from "@gtkx/ffi/adw";
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { createElement, Fragment, type ReactNode, type Ref, useReducer, useRef } from "react";
+import type {
+    AdwComboRowProps,
+    GtkColumnViewProps,
+    GtkDropDownProps,
+    GtkGridViewProps,
+    GtkListViewProps,
+} from "../generated/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>;
+type GenericDropDownProps<T, S> = Omit<GtkDropDownProps, keyof DropDownProps> & DropDownProps<T, S>;
+type GenericComboRowProps<T, S> = Omit<AdwComboRowProps, keyof DropDownProps> & DropDownProps<T, S>;
+type GenericColumnViewProps<T, S> = Omit<GtkColumnViewProps, "items" | "renderHeader"> & {
+    items?: ListItem<T, S>[];
+    renderHeader?: ((item: S) => ReactNode) | null;
+};
+
+function useListHandle() {
+    const [, rerender] = useReducer((x: number) => x + 1, 0);
+    const boundItemsRef = useRef<BoundItem[]>([]);
+    const headerBoundItemsRef = useRef<BoundItem[]>([]);
+    return { rerender, boundItemsRef, headerBoundItemsRef };
+}
+
+function renderListElement(intrinsicName: string, handle: ReturnType<typeof useListHandle>, props: object): ReactNode {
+    const { rerender, boundItemsRef, headerBoundItemsRef } = handle;
+
+    const portals: ReactNode[] = [];
+    for (const [content, container, key] of boundItemsRef.current) {
+        portals.push(createPortal(content, container, key));
+    }
+    for (const [content, container, key] of headerBoundItemsRef.current) {
+        portals.push(createPortal(content, container, key));
+    }
+
+    return createElement(
+        Fragment,
+        null,
+        createElement(intrinsicName, {
+            ...(props as Record<string, unknown>),
+            __boundItemsRef: boundItemsRef,
+            __rerender: rerender,
+            __headerBoundItemsRef: headerBoundItemsRef,
+        }),
+        ...portals,
+    );
+}
+
+/**
+ * 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);
+}
+
+/** @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 {
+    return renderListElement("AdwComboRow", useListHandle(), props);
+}

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);
 }