@gtkx/react 0.1.21 → 0.1.23

package/README.md

@@ -1,391 +1,208 @@
-# @gtkx/react
+<p align="center">
+  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/HEAD/logo.svg" alt="GTKX Logo" width="128" height="128">
+</p>
 
-React integration layer for GTKX. This package provides a custom React reconciler that renders React components as native GTK4 widgets.
+<h1 align="center">GTKX</h1>
 
-## Installation
+<p align="center">
+  <strong>Build native GTK4 desktop applications with React and TypeScript</strong>
+</p>
 
-```bash
-pnpm add @gtkx/react react
-```
-
-### Peer Dependencies
+<p align="center">
+  <a href="https://eugeniodepalo.github.io/gtkx">Documentation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#examples">Examples</a>
+</p>
 
-- `react` ^19.0.0
+---
 
-### System Requirements
+GTKX bridges React's component model with GTK4's native widget system. Write familiar React code and render it as native Linux desktop applications with full access to GTK4 widgets, signals, and styling.
 
-- Linux with GTK4 libraries
-- Node.js 20+
-- Rust toolchain (for building `@gtkx/native`)
-
-```bash
-# Fedora
-sudo dnf install gtk4-devel
+## Features
 
-# Ubuntu/Debian
-sudo apt install libgtk-4-dev
-```
+- **React Components** — Use React hooks, state, and component patterns you already know
+- **Type-Safe** — Full TypeScript support with auto-generated types from GTK4 introspection data
+- **Native Performance** — Direct FFI bindings to GTK4 via Rust and libffi
+- **CSS-in-JS Styling** — Emotion-style `css` template literals for GTK widgets
+- **Testing Library** — Familiar `screen`, `userEvent`, and query APIs for testing components
 
 ## Quick Start
 
-```tsx
-import { ApplicationWindow, Button, Box, Label, quit, render } from "@gtkx/react";
-import * as Gtk from "@gtkx/ffi/gtk";
-import { useState } from "react";
-
-const Counter = () => {
-  const [count, setCount] = useState(0);
-
-  return (
-    <Box valign={Gtk.Align.CENTER} halign={Gtk.Align.CENTER} spacing={10}>
-      <Label.Root label={`Count: ${count}`} cssClasses={["title-2"]} />
-      <Button label="Increment" onClicked={() => setCount(c => c + 1)} />
-    </Box>
-  );
-};
-
-// Export app instance for use in dialogs
-export const app = render(
-  <ApplicationWindow title="My App" defaultWidth={800} defaultHeight={600} onCloseRequest={quit}>
-    <Counter />
-  </ApplicationWindow>,
-  "com.example.myapp"
-);
-```
-
-Run with:
-
 ```bash
-npx tsx src/index.tsx
-```
-
-## API
-
-### `render(element, applicationId)`
-
-Renders a React element tree as a GTK4 application. Returns the GTK Application instance.
-
-- `element` — Root React element (typically `ApplicationWindow`)
-- `applicationId` — Unique identifier in reverse-DNS format (e.g., `com.example.app`)
-
-```tsx
-export const app = render(<App />, "com.example.myapp");
-```
-
-### `quit()`
-
-Signals the application to close. Returns `false` (useful as a direct event handler for `onCloseRequest`).
-
-```tsx
-<ApplicationWindow onCloseRequest={quit}>...</ApplicationWindow>
-```
-
-### `createPortal(element)`
-
-Renders a React element outside the normal component tree (useful for dialogs).
-
-```tsx
-{showDialog && createPortal(<AboutDialog ... />)}
-```
-
-### `createRef()`
-
-Creates a reference for FFI output parameters.
-
-```tsx
-import { createRef } from "@gtkx/react";
-
-const ref = createRef();
-someGtkFunction(ref);
-console.log(ref.value);
-```
-
-## Widgets
-
-### Container Widgets
-
-**ApplicationWindow** — Main application window
-
-```tsx
-<ApplicationWindow title="Window Title" defaultWidth={800} defaultHeight={600} onCloseRequest={quit}>
-  {children}
-</ApplicationWindow>
-```
-
-**Box** — Arranges children in a row or column
-
-```tsx
-<Box orientation={Gtk.Orientation.VERTICAL} spacing={10}>
-  <Button label="First" />
-  <Button label="Second" />
-</Box>
-```
-
-**Grid** — Arranges children in a grid layout
-
-```tsx
-<Grid.Root columnSpacing={10} rowSpacing={10}>
-  <Grid.Child column={0} row={0}><Button label="(0,0)" /></Grid.Child>
-  <Grid.Child column={1} row={0}><Button label="(1,0)" /></Grid.Child>
-  <Grid.Child column={0} row={1} columnSpan={2}>
-    <Button label="Spans 2 columns" hexpand />
-  </Grid.Child>
-</Grid.Root>
-```
-
-**ScrolledWindow** — Adds scrollbars to content
-
-```tsx
-<ScrolledWindow vexpand hexpand>
-  <TextView />
-</ScrolledWindow>
-```
+# Install dependencies
+pnpm add @gtkx/react react
 
-**Paned** — Resizable split container
+# For styling (optional)
+pnpm add @gtkx/css
 
-```tsx
-<Paned.Root wideHandle>
-  <Paned.StartChild>
-    <Box>{/* Left */}</Box>
-  </Paned.StartChild>
-  <Paned.EndChild>
-    <Box>{/* Right */}</Box>
-  </Paned.EndChild>
-</Paned.Root>
+# For testing (optional)
+pnpm add -D @gtkx/testing
 ```
 
-### Input Widgets
-
-**Button** — Clickable button
+Create your first app:
 
 ```tsx
-<Button label="Click me" onClicked={() => console.log("Clicked!")} />
-```
-
-**ToggleButton** — Button with on/off state
+// index.tsx
+import { render } from "@gtkx/react";
+import { App } from "./app.js";
 
-```tsx
-<ToggleButton.Root label={active ? "ON" : "OFF"} active={active} onToggled={() => setActive(a => !a)} />
+render(<App />, "org.example.MyApp");
 ```
 
-**CheckButton** — Checkbox with label
-
 ```tsx
-<CheckButton.Root label="Accept terms" active={checked} onToggled={() => setChecked(c => !c)} />
-```
+// app.tsx
+import { ApplicationWindow, Box, Button, Label, quit } from "@gtkx/react";
+import { Orientation } from "@gtkx/ffi/gtk";
+import { useState } from "react";
 
-**Switch** — On/off toggle (must return `true` from `onStateSet`)
+export const App = () => {
+  const [count, setCount] = useState(0);
 
-```tsx
-<Switch
-  active={enabled}
-  onStateSet={(self, state) => {
-    setEnabled(state);
-    return true;
-  }}
-/>
+  return (
+    <ApplicationWindow
+      title="My App"
+      defaultWidth={400}
+      defaultHeight={300}
+      onCloseRequest={quit}
+    >
+      <Box orientation={Orientation.VERTICAL} spacing={12} margin={20}>
+        <Label.Root label={`Count: ${count}`} />
+        <Button
+          label="Increment"
+          onClicked={() => setCount((c) => c + 1)}
+        />
+      </Box>
+    </ApplicationWindow>
+  );
+};
 ```
 
-**Entry** — Single-line text input
+Run with:
 
-```tsx
-<Entry placeholderText="Enter text..." />
-<PasswordEntry placeholderText="Password..." />
-<SearchEntry placeholderText="Search..." />
+```bash
+pnpm tsx index.tsx
 ```
 
-**SpinButton** — Numeric input with increment/decrement
-
-```tsx
-// Adjustment args: value, lower, upper, stepIncrement, pageIncrement, pageSize
-const adjustment = useMemo(() => new Gtk.Adjustment(50, 0, 100, 1, 10, 0), []);
-<SpinButton adjustment={adjustment} onValueChanged={(self) => setValue(self.getValue())} />
-```
+## Styling
 
-**Scale** — Horizontal or vertical slider
+Use `@gtkx/css` for CSS-in-JS styling:
 
 ```tsx
-<Scale hexpand drawValue adjustment={adjustment} onValueChanged={(self) => setValue(self.getValue())} />
-```
+import { css } from "@gtkx/css";
+import { Button } from "@gtkx/react";
 
-### Display Widgets
+const primaryButton = css`
+  padding: 16px 32px;
+  border-radius: 24px;
+  background: linear-gradient(135deg, #3584e4, #9141ac);
+  color: white;
+  font-weight: bold;
+`;
 
-**Label** — Text display
-
-```tsx
-<Label.Root label="Hello, World!" cssClasses={["title-2"]} />
+const MyButton = () => (
+  <Button label="Click me" cssClasses={[primaryButton]} />
+);
 ```
 
-**ProgressBar** — Progress indicator
+GTK also provides built-in CSS classes like `suggested-action`, `destructive-action`, `card`, and `heading`.
 
-```tsx
-<ProgressBar fraction={0.5} showText />
-```
+## Testing
 
-**Spinner** — Loading indicator
+Use `@gtkx/testing` for Testing Library-style component tests:
 
 ```tsx
-<Spinner spinning={isLoading} />
-```
+import { cleanup, render, screen, userEvent, fireEvent } from "@gtkx/testing";
+import { AccessibleRole } from "@gtkx/ffi/gtk";
+import { afterEach, describe, expect, it } from "vitest";
+import { App } from "./app.js";
 
-### Layout Widgets
+describe("Counter", () => {
+  afterEach(() => cleanup());
 
-**HeaderBar** — Title bar with buttons
+  it("increments count when clicking button", async () => {
+    render(<App />);
 
-```tsx
-<HeaderBar.Root>
-  <HeaderBar.TitleWidget>
-    <Label.Root label="App Title" />
-  </HeaderBar.TitleWidget>
-</HeaderBar.Root>
-```
+    const button = await screen.findByRole(AccessibleRole.BUTTON, {
+      name: "Increment",
+    });
+    await userEvent.click(button);
 
-**CenterBox** — Positions children at start, center, and end
+    await screen.findByText("Count: 1");
+  });
 
-```tsx
-<CenterBox.Root>
-  <CenterBox.StartWidget><Button label="Left" /></CenterBox.StartWidget>
-  <CenterBox.CenterWidget><Label.Root label="Center" /></CenterBox.CenterWidget>
-  <CenterBox.EndWidget><Button label="Right" /></CenterBox.EndWidget>
-</CenterBox.Root>
-```
+  it("can also use fireEvent for synchronous events", async () => {
+    render(<App />);
 
-### List Widgets
+    const button = await screen.findByRole(AccessibleRole.BUTTON, {
+      name: "Increment",
+    });
+    fireEvent.click(button);
 
-**ListBox** — Simple vertical list
-
-```tsx
-<ListBox selectionMode={Gtk.SelectionMode.SINGLE}>
-  <ListBoxRow><Label.Root label="Item 1" /></ListBoxRow>
-  <ListBoxRow><Label.Root label="Item 2" /></ListBoxRow>
-</ListBox>
-```
-
-**DropDown** — Dropdown selector
-
-```tsx
-<DropDown.Root
-  itemLabel={(item) => item.name}
-  onSelectionChanged={(item, index) => setSelected(item)}
->
-  {items.map(item => <DropDown.Item key={item.id} item={item} />)}
-</DropDown.Root>
+    await screen.findByText("Count: 1");
+  });
+});
 ```
 
-**ListView** — Virtualized list for large datasets
+### Available APIs
 
-```tsx
-<ListView.Root renderItem={(item) => {
-  if (!item) return new Gtk.Box();
-  return new Gtk.Label({ label: item.name });
-}}>
-  {items.map(item => <ListView.Item item={item} key={item.id} />)}
-</ListView.Root>
-```
+**Queries** - Find elements in the rendered tree:
+- `getBy*` / `getAllBy*` - Throws if not found
+- `queryBy*` / `queryAllBy*` - Returns null/empty array if not found
+- `findBy*` / `findAllBy*` - Async, waits for element
 
-### Dialog Widgets
+Query types: `ByRole`, `ByText`, `ByLabelText`, `ByTestId`
 
-**AboutDialog** — Application about dialog (React component)
+**User Interactions**:
+- `userEvent.click(element)` - Simulate click
+- `userEvent.dblClick(element)` - Simulate double click
+- `userEvent.type(element, text)` - Type text into input
+- `userEvent.clear(element)` - Clear input text
+- `userEvent.setup()` - Create reusable instance
 
-```tsx
-{showAbout && createPortal(
-  <AboutDialog
-    programName="My App"
-    version="1.0.0"
-    onCloseRequest={() => { setShowAbout(false); return false; }}
-  />
-)}
-```
+**Low-level Events**:
+- `fireEvent(element, signalName)` - Emit any GTK signal
+- `fireEvent.click(element)` - Emit clicked signal
+- `fireEvent.activate(element)` - Emit activate signal
 
-**Async Dialogs** — AlertDialog, FileDialog, ColorDialog, FontDialog (imperative)
+**Utilities**:
+- `waitFor(callback)` - Wait for condition
+- `waitForElementToBeRemoved(element)` - Wait for element removal
 
-```tsx
-import { app } from "./index.js";
-
-const openFile = async () => {
-  const dialog = new Gtk.FileDialog();
-  dialog.setTitle("Open File");
-  try {
-    const file = await dialog.open(app.getActiveWindow());
-    console.log(file.getPath());
-  } catch {
-    // Cancelled
-  }
-};
-```
+## Examples
 
-## Named Slots
+### Counter
 
-Some GTK widgets have named child positions, handled via compound components:
+A minimal counter app demonstrating state management:
 
-```tsx
-<Frame.Root>
-  <Frame.LabelWidget>
-    <Label.Root label="Custom Label" />
-  </Frame.LabelWidget>
-  <Frame.Child>
-    <Box>{/* Content */}</Box>
-  </Frame.Child>
-</Frame.Root>
-
-<Expander.Root label="Click to expand">
-  <Expander.Child>
-    <Box>Hidden content</Box>
-  </Expander.Child>
-</Expander.Root>
+```bash
+turbo start --filter=counter-example
 ```
 
-## Using GTK Enums
+### GTK4 Demo
 
-Import enums from `@gtkx/ffi/gtk`:
+A comprehensive showcase of GTK4 widgets and features:
 
-```tsx
-import * as Gtk from "@gtkx/ffi/gtk";
-
-<Box orientation={Gtk.Orientation.VERTICAL} />
-<ListBox selectionMode={Gtk.SelectionMode.SINGLE} />
-<Revealer transitionType={Gtk.RevealerTransitionType.SLIDE_DOWN} />
+```bash
+turbo start --filter=gtk4-demo
 ```
 
-## Hooks Support
-
-Standard React hooks work as expected:
-
-```tsx
-import { useState, useEffect, useRef } from "react";
+## Packages
 
-const Counter = () => {
-  const [count, setCount] = useState(0);
+| Package | Description |
+|---------|-------------|
+| [@gtkx/react](packages/react) | React reconciler and JSX components |
+| [@gtkx/ffi](packages/ffi) | TypeScript FFI bindings for GTK4 |
+| [@gtkx/native](packages/native) | Rust native module for FFI bridge |
+| [@gtkx/css](packages/css) | CSS-in-JS styling for GTK widgets |
+| [@gtkx/testing](packages/testing) | Testing utilities for GTKX components |
+| [@gtkx/gir](packages/gir) | GObject Introspection parser for codegen |
 
-  useEffect(() => {
-    console.log(`Count: ${count}`);
-  }, [count]);
+## Requirements
 
-  return (
-    <Box spacing={10}>
-      <Label.Root label={`Count: ${count}`} />
-      <Button label="Increment" onClicked={() => setCount(c => c + 1)} />
-    </Box>
-  );
-};
-```
-
-## Architecture
-
-```
-┌─────────────────────────────────┐
-│     Your React Application      │
-├─────────────────────────────────┤
-│   @gtkx/react (React Reconciler) │
-├─────────────────────────────────┤
-│   @gtkx/ffi (TypeScript FFI)    │
-├─────────────────────────────────┤
-│   @gtkx/native (Rust Bridge)    │
-├─────────────────────────────────┤
-│         GTK4 / GLib             │
-└─────────────────────────────────┘
-```
+- Node.js 20+
+- GTK4 development libraries
+- Linux (GTK4 is Linux-native)
 
 ## License
 
-[MPL-2.0](../../LICENSE)
+[MPL-2.0](LICENSE)

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

@@ -1,5 +1,5 @@
 import type { GirClass, GirNamespace, TypeMapper } from "@gtkx/gir";
-export interface JsxGeneratorOptions {
+interface JsxGeneratorOptions {
     prettierConfig?: unknown;
 }
 export declare class JsxGenerator {
@@ -35,3 +35,4 @@ export declare class JsxGenerator {
     private generateJsxNamespace;
     private formatCode;
 }
+export {};

package/dist/codegen/jsx-generator.js

@@ -478,6 +478,7 @@ ${widgetPropsContent}
                 isListWidget(widget.name) ||
                 isDropDownWidget(widget.name) ||
                 isGridWidget(widget.name);
+            const docComment = widget.doc ? formatDoc(widget.doc).trimEnd() : "";
             if (hasMeaningfulSlots) {
                 const valueMembers = [
                     `Root: "${widgetName}.Root" as const`,
@@ -486,10 +487,20 @@ ${widgetPropsContent}
                     ...(isDropDownWidget(widget.name) ? [`Item: "${widgetName}.Item" as const`] : []),
                     ...(isGridWidget(widget.name) ? [`Child: "${widgetName}.Child" as const`] : []),
                 ];
-                lines.push(`export const ${widgetName} = {\n\t${valueMembers.join(",\n\t")},\n};`);
+                if (docComment) {
+                    lines.push(`${docComment}\nexport const ${widgetName} = {\n\t${valueMembers.join(",\n\t")},\n};`);
+                }
+                else {
+                    lines.push(`export const ${widgetName} = {\n\t${valueMembers.join(",\n\t")},\n};`);
+                }
             }
             else {
-                lines.push(`export const ${widgetName} = "${widgetName}" as const;`);
+                if (docComment) {
+                    lines.push(`${docComment}\nexport const ${widgetName} = "${widgetName}" as const;`);
+                }
+                else {
+                    lines.push(`export const ${widgetName} = "${widgetName}" as const;`);
+                }
             }
         }
         return `${lines.join("\n")}\n`;

package/dist/predicates.d.ts

@@ -1,13 +1,14 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
-export interface Appendable extends Gtk.Widget {
+interface Appendable extends Gtk.Widget {
     append(child: unknown): void;
 }
-export interface SingleChild extends Gtk.Widget {
+interface SingleChild extends Gtk.Widget {
     setChild(child: unknown): void;
 }
-export interface Removable extends Gtk.Widget {
+interface Removable extends Gtk.Widget {
     remove(child: unknown): void;
 }
 export declare const isAppendable: (widget: Gtk.Widget) => widget is Appendable;
 export declare const isSingleChild: (widget: Gtk.Widget) => widget is SingleChild;
 export declare const isRemovable: (widget: Gtk.Widget) => widget is Removable;
+export {};

package/dist/reconciler.d.ts

@@ -8,7 +8,7 @@ type SuspenseInstance = never;
 type PublicInstance = Gtk.Widget;
 type FormInstance = never;
 type ReconcilerInstance = ReactReconciler.Reconciler<Container, Node, TextInstance, SuspenseInstance, FormInstance, PublicInstance>;
-export declare class Reconciler {
+declare class Reconciler {
     private instance;
     private app;
     constructor();

package/dist/reconciler.js

@@ -3,7 +3,7 @@ import React from "react";
 import ReactReconciler from "react-reconciler";
 import { createNode } from "./factory.js";
 import { WidgetWrapper } from "./nodes/widget.js";
-export class Reconciler {
+class Reconciler {
     instance;
     app = null;
     constructor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/react",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Build GTK4 desktop applications with React and TypeScript",
   "keywords": [
     "gtk",
@@ -40,17 +40,17 @@
   ],
   "dependencies": {
     "react-reconciler": "0.33.0",
-    "@gtkx/ffi": "0.1.21"
+    "@gtkx/ffi": "0.1.23"
   },
   "devDependencies": {
-    "@gtkx/gir": "0.1.21"
+    "@gtkx/gir": "0.1.23"
   },
   "peerDependencies": {
     "react": "^19"
   },
   "scripts": {
-    "build": "tsc -b",
+    "build": "tsc -b && cp ../../README.md .",
     "codegen": "tsx scripts/codegen.ts",
-    "test": "xvfb-run -a vitest run"
+    "test": "GDK_BACKEND=x11 xvfb-run -a vitest run"
   }
 }