@gtkx/ffi 0.9.4 → 0.10.0

package/README.md

@@ -1,47 +1,43 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/HEAD/logo.svg" alt="GTKX Logo" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/main/logo.svg" alt="GTKX" width="80" height="80">
 </p>
 
 <h1 align="center">GTKX</h1>
 
 <p align="center">
-  <strong>Build native GTK4 desktop apps with React</strong>
+  <strong>Build native GTK4 desktop applications with React and TypeScript.</strong>
 </p>
 
 <p align="center">
-  <a href="https://eugeniodepalo.github.io/gtkx">Documentation</a> ·
-  <a href="#quick-start">Quick Start</a> ·
-  <a href="#examples">Examples</a> ·
-  <a href="#contributing">Contributing</a>
+  <a href="https://www.npmjs.com/package/@gtkx/react"><img src="https://img.shields.io/npm/v/@gtkx/react.svg" alt="npm version"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/actions"><img src="https://img.shields.io/github/actions/workflow/status/eugeniodepalo/gtkx/ci.yml" alt="CI"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/discussions"><img src="https://img.shields.io/badge/discussions-GitHub-blue" alt="GitHub Discussions"></a>
 </p>
 
 ---
 
-GTKX lets you build native Linux desktop applications using React and TypeScript. Write familiar React code that renders as native GTK4 widgets—no Electron, no web views.
-
-## Features
-
-- **React** — Hooks, state, props, and components you already know
-- **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
-- **Testing** — Testing Library-style `screen`, `userEvent`, and queries
+GTKX lets you write Linux desktop applications using React. Your components render as native GTK4 widgets through a Rust FFI bridge—no webviews, no Electron, just native performance with the developer experience you already know.
 
 ## Quick Start
 
 ```bash
-npx @gtkx/cli@latest create my-app
+npx @gtkx/cli create my-app
 cd my-app
 npm run dev
 ```
 
-Edit your code and see changes instantly—no restart needed.
-
-### Example
+## Example
 
 ```tsx
-import { render, ApplicationWindow, Box, Button, quit } from "@gtkx/react";
+import {
+  GtkApplicationWindow,
+  GtkBox,
+  GtkButton,
+  GtkLabel,
+  quit,
+  render,
+} from "@gtkx/react";
 import * as Gtk from "@gtkx/ffi/gtk";
 import { useState } from "react";
 
@@ -49,67 +45,59 @@ const App = () => {
   const [count, setCount] = useState(0);
 
   return (
-    <ApplicationWindow title="Counter" onCloseRequest={quit}>
-      <Box orientation={Gtk.Orientation.VERTICAL} spacing={12}>
-        {`Count: ${count}`}
-        <Button label="Increment" onClicked={() => setCount((c) => c + 1)} />
-      </Box>
-    </ApplicationWindow>
+    <GtkApplicationWindow
+      title="Counter"
+      defaultWidth={300}
+      defaultHeight={200}
+      onCloseRequest={quit}
+    >
+      <GtkBox
+        orientation={Gtk.Orientation.VERTICAL}
+        spacing={20}
+        valign={Gtk.Align.CENTER}
+      >
+        <GtkLabel label={`Count: ${count}`} cssClasses={["title-1"]} />
+        <GtkButton label="Increment" onClicked={() => setCount((c) => c + 1)} />
+      </GtkBox>
+    </GtkApplicationWindow>
   );
 };
 
-render(<App />, "org.example.Counter");
+render(<App />, "com.example.counter");
 ```
 
-## Styling
-
-```tsx
-import { css } from "@gtkx/css";
-import { Button } from "@gtkx/react";
-
-const primary = css`
-  padding: 16px 32px;
-  border-radius: 24px;
-  background: linear-gradient(135deg, #3584e4, #9141ac);
-  color: white;
-`;
-
-<Button label="Click me" cssClasses={[primary]} />;
-```
-
-## Testing
-
-```tsx
-import { cleanup, render, screen, userEvent } from "@gtkx/testing";
-import * as Gtk from "@gtkx/ffi/gtk";
-
-afterEach(() => cleanup());
+## Features
 
-test("increments count", async () => {
-  await render(<App />);
+- **React 19** — Hooks, concurrent features, and the component model you know
+- **Native GTK4 widgets** — Real native controls, not web components in a webview
+- **Adwaita support** — Modern GNOME styling with Libadwaita components
+- **Hot Module Replacement** — Fast refresh during development
+- **TypeScript first** — Full type safety with auto-generated bindings
+- **CSS-in-JS styling** — Familiar styling patterns adapted for GTK
+- **Testing utilities** — Component testing similar to Testing Library
 
-  const button = await screen.findByRole(Gtk.AccessibleRole.BUTTON, {
-    name: "Increment",
-  });
+## Examples
 
-  await userEvent.click(button);
+Explore complete applications in the [`examples/`](./examples) directory:
 
-  await screen.findByText("Count: 1");
-});
-```
+- **[gtk-demo](./examples/gtk-demo)** — Full replica of the official GTK demo app
+- **[hello-world](./examples/hello-world)** — Minimal application showing a counter
+- **[todo](./examples/todo)** — Full-featured todo application with Adwaita styling and testing
+- **[deploying](./examples/deploying)** — Example of packaging and distributing a GTKX app
 
-## Requirements
+## Documentation
 
-- Node.js 20+ (Deno support experimental)
-- GTK4 Runtime (`gtk4` on Fedora, `libgtk-4-1` on Ubuntu)
+Visit [https://eugeniodepalo.github.io/gtkx](https://eugeniodepalo.github.io/gtkx/) for the full documentation.
 
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome! Please see the [contributing guidelines](./CONTRIBUTING.md) and check out the [good first issues](https://github.com/eugeniodepalo/gtkx/labels/good%20first%20issue).
+
+## Community
 
-- [Report a bug](https://github.com/eugeniodepalo/gtkx/issues/new?template=bug_report.md)
-- [Request a feature](https://github.com/eugeniodepalo/gtkx/issues/new?template=feature_request.md)
+- [GitHub Discussions](https://github.com/eugeniodepalo/gtkx/discussions) — Questions, ideas, and general discussion
+- [Issue Tracker](https://github.com/eugeniodepalo/gtkx/issues) — Bug reports and feature requests
 
 ## License
 
-[MPL-2.0](LICENSE)
+[MPL-2.0](./LICENSE)

package/dist/batch.d.ts

@@ -1,29 +1,71 @@
 import { type Arg, type Type } from "@gtkx/native";
 /**
- * Begins batching mode for FFI calls.
- * Batching is nestable - each beginBatch pushes a new queue onto the stack.
- * While in batch mode, void calls are queued instead of executed immediately.
+ * Begins a new FFI call batch.
+ *
+ * Batching queues multiple FFI calls and executes them together in a single
+ * native round-trip, reducing overhead. Batches can be nested.
+ *
+ * @example
+ * ```tsx
+ * beginBatch();
+ * widget.setVisible(true);
+ * widget.setSensitive(true);
+ * endBatch(); // Executes both calls in one FFI round-trip
+ * ```
+ *
+ * @see {@link endBatch} for executing batched calls
+ * @see {@link batch} for a convenient wrapper
  */
 export declare const beginBatch: () => void;
 /**
- * Checks if batching mode is currently active.
- * @returns true if batching is active, false otherwise
+ * Checks if currently inside a batch context.
+ *
+ * @returns `true` if {@link beginBatch} was called without a matching {@link endBatch}
  */
 export declare const isBatching: () => boolean;
 /**
- * Ends the current batch level and executes its queued FFI calls.
- * If nested inside another batch, the calls are executed immediately
- * rather than being merged into the parent batch.
+ * Ends the current batch and executes all queued FFI calls.
+ *
+ * Must be paired with a preceding {@link beginBatch} call.
+ *
+ * @see {@link beginBatch} for starting a batch
+ * @see {@link batch} for a convenient wrapper
  */
 export declare const endBatch: () => void;
 /**
- * Calls a native GTK function via FFI.
- * When batching is active and the return type is void, the call is queued
- * for batch execution instead of being executed immediately.
- * @param library - The shared library name (e.g., "libgtk-4.so.1")
- * @param symbol - The C function symbol name to call
- * @param args - Array of argument descriptors with types and values
- * @param returnType - Type descriptor for the return value
- * @returns The return value from the native function
+ * Discards all pending batched calls without executing them.
+ *
+ * Used for error recovery when batched operations should be abandoned.
+ */
+export declare const discardAllBatches: () => void;
+/**
+ * Makes an FFI call, batching it if inside a batch context.
+ *
+ * Calls with void return type are queued for batching. Calls with return
+ * values are executed immediately since the result is needed.
+ *
+ * @param library - Shared library name (e.g., "libgtk-4.so.1")
+ * @param symbol - Function symbol name
+ * @param args - Function arguments
+ * @param returnType - Expected return type
+ * @returns The function return value, or undefined for void calls
  */
 export declare const call: (library: string, symbol: string, args: Arg[], returnType: Type) => unknown;
+/**
+ * Executes a function with automatic batching.
+ *
+ * Wraps the function in {@link beginBatch}/{@link endBatch} calls.
+ *
+ * @param fn - Function to execute with batching
+ * @returns The function's return value
+ *
+ * @example
+ * ```tsx
+ * batch(() => {
+ *   widget.setVisible(true);
+ *   widget.setSensitive(true);
+ *   widget.setCssClasses(["active"]);
+ * });
+ * ```
+ */
+export declare const batch: <T extends (...args: unknown[]) => unknown>(fn: T) => ReturnType<T>;

package/dist/batch.js

@@ -1,24 +1,40 @@
 import { batchCall, call as nativeCall } from "@gtkx/native";
 const batchStack = [];
 /**
- * Begins batching mode for FFI calls.
- * Batching is nestable - each beginBatch pushes a new queue onto the stack.
- * While in batch mode, void calls are queued instead of executed immediately.
+ * Begins a new FFI call batch.
+ *
+ * Batching queues multiple FFI calls and executes them together in a single
+ * native round-trip, reducing overhead. Batches can be nested.
+ *
+ * @example
+ * ```tsx
+ * beginBatch();
+ * widget.setVisible(true);
+ * widget.setSensitive(true);
+ * endBatch(); // Executes both calls in one FFI round-trip
+ * ```
+ *
+ * @see {@link endBatch} for executing batched calls
+ * @see {@link batch} for a convenient wrapper
  */
 export const beginBatch = () => {
     batchStack.push([]);
 };
 /**
- * Checks if batching mode is currently active.
- * @returns true if batching is active, false otherwise
+ * Checks if currently inside a batch context.
+ *
+ * @returns `true` if {@link beginBatch} was called without a matching {@link endBatch}
  */
 export const isBatching = () => {
     return batchStack.length > 0;
 };
 /**
- * Ends the current batch level and executes its queued FFI calls.
- * If nested inside another batch, the calls are executed immediately
- * rather than being merged into the parent batch.
+ * Ends the current batch and executes all queued FFI calls.
+ *
+ * Must be paired with a preceding {@link beginBatch} call.
+ *
+ * @see {@link beginBatch} for starting a batch
+ * @see {@link batch} for a convenient wrapper
  */
 export const endBatch = () => {
     const queue = batchStack.pop();
@@ -29,14 +45,25 @@ export const endBatch = () => {
     }
 };
 /**
- * Calls a native GTK function via FFI.
- * When batching is active and the return type is void, the call is queued
- * for batch execution instead of being executed immediately.
- * @param library - The shared library name (e.g., "libgtk-4.so.1")
- * @param symbol - The C function symbol name to call
- * @param args - Array of argument descriptors with types and values
- * @param returnType - Type descriptor for the return value
- * @returns The return value from the native function
+ * Discards all pending batched calls without executing them.
+ *
+ * Used for error recovery when batched operations should be abandoned.
+ */
+export const discardAllBatches = () => {
+    batchStack.length = 0;
+    endBatch();
+};
+/**
+ * Makes an FFI call, batching it if inside a batch context.
+ *
+ * Calls with void return type are queued for batching. Calls with return
+ * values are executed immediately since the result is needed.
+ *
+ * @param library - Shared library name (e.g., "libgtk-4.so.1")
+ * @param symbol - Function symbol name
+ * @param args - Function arguments
+ * @param returnType - Expected return type
+ * @returns The function return value, or undefined for void calls
  */
 export const call = (library, symbol, args, returnType) => {
     const currentQueue = batchStack[batchStack.length - 1];
@@ -46,3 +73,29 @@ export const call = (library, symbol, args, returnType) => {
     }
     return nativeCall(library, symbol, args, returnType);
 };
+/**
+ * Executes a function with automatic batching.
+ *
+ * Wraps the function in {@link beginBatch}/{@link endBatch} calls.
+ *
+ * @param fn - Function to execute with batching
+ * @returns The function's return value
+ *
+ * @example
+ * ```tsx
+ * batch(() => {
+ *   widget.setVisible(true);
+ *   widget.setSensitive(true);
+ *   widget.setCssClasses(["active"]);
+ * });
+ * ```
+ */
+export const batch = (fn) => {
+    beginBatch();
+    try {
+        return fn();
+    }
+    finally {
+        endBatch();
+    }
+};