@gtkx/react 0.9.1 → 0.9.2

package/README.md

@@ -22,7 +22,7 @@ GTKX lets you build native Linux desktop applications using React and TypeScript
 ## Features
 
 - **React** — Hooks, state, props, and components you already know
-- **Hot Reload** — Edit code and see changes instantly via Vite
+- **HMR** — Edit code and see changes instantly via Vite
 - **Native** — Direct FFI bindings to GTK4 via Rust and libffi
 - **CLI** — `npx @gtkx/cli@latest create` scaffolds a ready-to-go project
 - **CSS-in-JS** — Emotion-style `css` template literals for GTK styling
@@ -41,14 +41,7 @@ Edit your code and see changes instantly—no restart needed.
 ### Example
 
 ```tsx
-import {
-  render,
-  ApplicationWindow,
-  Box,
-  Button,
-  Label,
-  quit,
-} from "@gtkx/react";
+import { render, ApplicationWindow, Box, Button, quit } from "@gtkx/react";
 import * as Gtk from "@gtkx/ffi/gtk";
 import { useState } from "react";
 
@@ -58,7 +51,7 @@ const App = () => {
   return (
     <ApplicationWindow title="Counter" onCloseRequest={quit}>
       <Box orientation={Gtk.Orientation.VERTICAL} spacing={12}>
-        <Label label={`Count: ${count}`} />
+        {`Count: ${count}`}
         <Button label="Increment" onClicked={() => setCount((c) => c + 1)} />
       </Box>
     </ApplicationWindow>
@@ -84,8 +77,6 @@ const primary = css`
 <Button label="Click me" cssClasses={[primary]} />;
 ```
 
-GTK also provides built-in classes like `suggested-action`, `destructive-action`, `card`, and `heading`.
-
 ## Testing
 
 ```tsx
@@ -109,9 +100,8 @@ test("increments count", async () => {
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 20+ (Deno support experimental)
 - GTK4 Runtime (`gtk4` on Fedora, `libgtk-4-1` on Ubuntu)
-- Linux
 
 ## Contributing
 

package/dist/batch.d.ts

@@ -1,20 +1,5 @@
 type FlushCallback = () => void;
-/**
- * Marks the beginning of a React reconciler commit phase.
- * While in commit, flush callbacks are deferred until endCommit is called.
- * Supports nested commits through depth tracking.
- */
 export declare const beginCommit: () => void;
-/**
- * Marks the end of a React reconciler commit phase.
- * Executes all pending flush callbacks that were deferred during the commit
- * only when the outermost commit ends (depth reaches 0).
- * If called without a matching beginCommit, resets the state (useful for test cleanup).
- */
 export declare const endCommit: () => void;
-/**
- * Schedules a callback to be executed, deferring it if currently in a commit phase.
- * This ensures GTK state updates happen after React has finished its batch of changes.
- */
 export declare const scheduleFlush: (callback: FlushCallback) => void;
 export {};

package/dist/batch.js

@@ -2,20 +2,9 @@ const state = {
     depth: 0,
     pendingFlushes: new Set(),
 };
-/**
- * Marks the beginning of a React reconciler commit phase.
- * While in commit, flush callbacks are deferred until endCommit is called.
- * Supports nested commits through depth tracking.
- */
 export const beginCommit = () => {
     state.depth++;
 };
-/**
- * Marks the end of a React reconciler commit phase.
- * Executes all pending flush callbacks that were deferred during the commit
- * only when the outermost commit ends (depth reaches 0).
- * If called without a matching beginCommit, resets the state (useful for test cleanup).
- */
 export const endCommit = () => {
     if (state.depth <= 0) {
         state.depth = 0;
@@ -32,10 +21,6 @@ export const endCommit = () => {
         });
     }
 };
-/**
- * Schedules a callback to be executed, deferring it if currently in a commit phase.
- * This ensures GTK state updates happen after React has finished its batch of changes.
- */
 export const scheduleFlush = (callback) => {
     if (state.depth > 0) {
         state.pendingFlushes.add(callback);

package/dist/codegen/jsx-generator.d.ts

@@ -1,24 +1,11 @@
 import type { GirClass, GirNamespace, TypeMapper, TypeRegistry } from "@gtkx/gir";
-/**
- * Configuration options for the JSX type generator.
- */
 type JsxGeneratorOptions = {
-    /** Optional Prettier configuration for formatting output. */
     prettierConfig?: unknown;
 };
-/**
- * Result of the JSX generation containing both public and internal files.
- */
 type JsxGeneratorResult = {
-    /** Public JSX types and components for user consumption. */
     jsx: string;
-    /** Internal metadata for reconciler use (not exported to users). */
     internal: string;
 };
-/**
- * Generates JSX type definitions for React components from GTK widget classes.
- * Creates TypeScript interfaces for props and augments React's JSX namespace.
- */
 export declare class JsxGenerator {
     private typeMapper;
     private typeRegistry;
@@ -30,19 +17,8 @@ export declare class JsxGenerator {
     private widgetSignalNames;
     private currentNamespace;
     private widgetNamespaceMap;
-    /**
-     * Creates a new JSX generator.
-     * @param typeMapper - TypeMapper for converting GIR types to TypeScript
-     * @param typeRegistry - TypeRegistry for cross-namespace type resolution
-     * @param classMap - Combined class map with fully qualified names
-     * @param options - Generator configuration options
-     */
     constructor(typeMapper: TypeMapper, typeRegistry: TypeRegistry, classMap: Map<string, GirClass>, options?: JsxGeneratorOptions);
-    /**
-     * Generates JSX type definitions for all widgets in the given namespaces.
-     * @param namespaces - The parsed GIR namespaces (GTK must be first)
-     * @returns Generated TypeScript code as public jsx.ts and internal.ts files
-     */
+    private formatDoc;
     generate(namespaces: GirNamespace[]): Promise<JsxGeneratorResult>;
     private generateImports;
     private generateInternalImports;

package/dist/codegen/jsx-generator.js

@@ -1,4 +1,4 @@
-import { toCamelCase, toPascalCase } from "@gtkx/gir";
+import { formatDoc as formatDocBase, toCamelCase, toPascalCase } from "@gtkx/gir";
 import { format } from "prettier";
 const LIST_WIDGETS = new Set(["ListView", "GridView"]);
 const COLUMN_VIEW_WIDGET = "ColumnView";
@@ -40,34 +40,6 @@ const isNotebookWidget = (widgetName) => widgetName === NOTEBOOK_WIDGET;
 const isStackWidget = (widgetName) => STACK_WIDGETS.has(widgetName);
 const isPopoverMenuWidget = (widgetName) => widgetName === POPOVER_MENU_WIDGET;
 const isToolbarViewWidget = (widgetName) => widgetName === TOOLBAR_VIEW_WIDGET;
-const sanitizeDoc = (doc) => {
-    let result = doc;
-    result = result.replace(/<picture[^>]*>[\s\S]*?<\/picture>/gi, "");
-    result = result.replace(/<img[^>]*>/gi, "");
-    result = result.replace(/<source[^>]*>/gi, "");
-    result = result.replace(/!\[[^\]]*\]\([^)]+\.png\)/gi, "");
-    result = result.replace(/<kbd>([^<]*)<\/kbd>/gi, "`$1`");
-    result = result.replace(/<kbd>/gi, "`");
-    result = result.replace(/<\/kbd>/gi, "`");
-    result = result.replace(/\[([^\]]+)\]\([^)]+\.html[^)]*\)/gi, "$1");
-    result = result.replace(/@(\w+)\s/g, "`$1` ");
-    result = result.replace(/<(\/?)(child|object|property|signal|template)>/gi, "`<$1$2>`");
-    return result.trim();
-};
-const formatDoc = (doc, indent = "") => {
-    if (!doc)
-        return "";
-    const sanitized = sanitizeDoc(doc);
-    if (!sanitized)
-        return "";
-    const lines = sanitized.split("\n").map((line) => line.trim());
-    const firstLine = lines[0] ?? "";
-    if (lines.length === 1 && firstLine.length < 80) {
-        return `${indent}/** ${firstLine} */\n`;
-    }
-    const formattedLines = lines.map((line) => `${indent} * ${line}`);
-    return `${indent}/**\n${formattedLines.join("\n")}\n${indent} */\n`;
-};
 const isWidgetSubclass = (typeName, classMap, visited = new Set()) => {
     const className = typeName.includes(".") ? typeName.split(".")[1] : typeName;
     if (!className || visited.has(className))
@@ -80,10 +52,6 @@ const isWidgetSubclass = (typeName, classMap, visited = new Set()) => {
         return true;
     return cls.parent ? isWidgetSubclass(cls.parent, classMap, visited) : false;
 };
-/**
- * Generates JSX type definitions for React components from GTK widget classes.
- * Creates TypeScript interfaces for props and augments React's JSX namespace.
- */
 export class JsxGenerator {
     typeMapper;
     typeRegistry;
@@ -95,24 +63,18 @@ export class JsxGenerator {
     widgetSignalNames = new Set();
     currentNamespace = "";
     widgetNamespaceMap = new Map();
-    /**
-     * Creates a new JSX generator.
-     * @param typeMapper - TypeMapper for converting GIR types to TypeScript
-     * @param typeRegistry - TypeRegistry for cross-namespace type resolution
-     * @param classMap - Combined class map with fully qualified names
-     * @param options - Generator configuration options
-     */
     constructor(typeMapper, typeRegistry, classMap, options = {}) {
         this.typeMapper = typeMapper;
         this.typeRegistry = typeRegistry;
         this.classMap = classMap;
         this.options = options;
     }
-    /**
-     * Generates JSX type definitions for all widgets in the given namespaces.
-     * @param namespaces - The parsed GIR namespaces (GTK must be first)
-     * @returns Generated TypeScript code as public jsx.ts and internal.ts files
-     */
+    formatDoc(doc, indent = "") {
+        return formatDocBase(doc, indent, {
+            namespace: this.currentNamespace,
+            escapeXmlTags: true,
+        });
+    }
     async generate(namespaces) {
         for (const ns of namespaces) {
             for (const iface of ns.interfaces) {
@@ -181,7 +143,7 @@ ${widgetPropsContent}
     }
     generateWidgetPropsContent(widgetClass) {
         const lines = [];
-        const widgetDoc = widgetClass?.doc ? formatDoc(widgetClass.doc) : "";
+        const widgetDoc = widgetClass?.doc ? this.formatDoc(widgetClass.doc) : "";
         if (widgetDoc) {
             lines.push(widgetDoc.trimEnd());
         }
@@ -191,7 +153,7 @@ ${widgetPropsContent}
                 const propName = toCamelCase(prop.name);
                 const tsType = this.toJsxPropertyType(this.typeMapper.mapType(prop.type).ts, "Gtk");
                 if (prop.doc) {
-                    lines.push(formatDoc(prop.doc, "\t").trimEnd());
+                    lines.push(this.formatDoc(prop.doc, "\t").trimEnd());
                 }
                 lines.push(`\t${propName}?: ${tsType};`);
             }
@@ -199,7 +161,7 @@ ${widgetPropsContent}
                 lines.push("");
                 for (const signal of widgetClass.signals) {
                     if (signal.doc) {
-                        lines.push(formatDoc(signal.doc, "\t").trimEnd());
+                        lines.push(this.formatDoc(signal.doc, "\t").trimEnd());
                     }
                     lines.push(`\t${this.generateSignalHandler(signal, "Widget")}`);
                 }
@@ -354,7 +316,7 @@ ${widgetPropsContent}
             const isRequiredByConstructor = requiredCtorParams.has(prop.name);
             const isRequired = isRequiredByConstructor;
             if (prop.doc) {
-                lines.push(formatDoc(prop.doc, "\t").trimEnd());
+                lines.push(this.formatDoc(prop.doc, "\t").trimEnd());
             }
             lines.push(`\t${propName}${isRequired ? "" : "?"}: ${tsType};`);
         }
@@ -377,7 +339,7 @@ ${widgetPropsContent}
             lines.push("");
             for (const signal of specificSignals) {
                 if (signal.doc) {
-                    lines.push(formatDoc(signal.doc, "\t").trimEnd());
+                    lines.push(this.formatDoc(signal.doc, "\t").trimEnd());
                 }
                 lines.push(`\t${this.generateSignalHandler(signal, widget.name)}`);
             }
@@ -716,7 +678,7 @@ ${widgetPropsContent}
                 isNotebookWidget(widget.name) ||
                 isStackWidget(widget.name) ||
                 isPopoverMenuWidget(widget.name);
-            const docComment = widget.doc ? formatDoc(widget.doc).trimEnd() : "";
+            const docComment = widget.doc ? this.formatDoc(widget.doc).trimEnd() : "";
             if (hasMeaningfulSlots) {
                 if (isListWidget(widget.name) ||
                     isColumnViewWidget(widget.name) ||

package/dist/factory.d.ts

@@ -1,13 +1,6 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { Node } from "./node.js";
 import { type ROOT_NODE_CONTAINER } from "./nodes/root.js";
-/**
- * Generic props type for React component properties passed to GTK nodes.
- */
 export type Props = Record<string, unknown>;
 export { ROOT_NODE_CONTAINER } from "./nodes/root.js";
-/**
- * Creates a Node instance for the given JSX element type.
- * Matches the type against registered node classes and initializes with props.
- */
 export declare const createNode: (type: string, props: Props, widget?: Gtk.Widget | typeof ROOT_NODE_CONTAINER) => Node;

package/dist/factory.js

@@ -63,10 +63,6 @@ const CONTAINER_NODES = [
     HeaderBarNode,
 ];
 const NODE_CLASSES = [RootNode, ...VIRTUAL_NODES, ...SPECIALIZED_NODES, ...CONTAINER_NODES, WidgetNode];
-/**
- * Creates a Node instance for the given JSX element type.
- * Matches the type against registered node classes and initializes with props.
- */
 export const createNode = (type, props, widget) => {
     for (const NodeClass of NODE_CLASSES) {
         if (NodeClass.matches(type, widget)) {

package/dist/fiber-root.d.ts

@@ -1,8 +1,3 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type Reconciler from "react-reconciler";
-/**
- * Creates a new fiber root container for rendering React elements.
- * @param container - Optional GTK widget to use as the container. If not provided,
- *                    uses the ROOT_NODE_CONTAINER sentinel for virtual roots.
- */
 export declare const createFiberRoot: (container?: Gtk.Widget) => Reconciler.FiberRoot;

package/dist/fiber-root.js

@@ -1,10 +1,5 @@
 import { ROOT_NODE_CONTAINER } from "./factory.js";
 import { reconciler } from "./reconciler.js";
-/**
- * Creates a new fiber root container for rendering React elements.
- * @param container - Optional GTK widget to use as the container. If not provided,
- *                    uses the ROOT_NODE_CONTAINER sentinel for virtual roots.
- */
 export const createFiberRoot = (container) => {
     const instance = reconciler.getInstance();
     return instance.createContainer(container ?? ROOT_NODE_CONTAINER, 0, null, false, null, "", (error) => console.error("Fiber root render error:", error), () => { }, () => { }, () => { }, null);