@gtkx/ffi 0.3.2 → 0.3.4

package/README.md

@@ -5,239 +5,138 @@
 <h1 align="center">GTKX</h1>
 
 <p align="center">
-  <strong>Build native GTK4 desktop applications with React and TypeScript</strong>
+  <strong>Build native GTK4 desktop apps with React</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="#examples">Examples</a> ·
+  <a href="#contributing">Contributing</a>
 </p>
 
 ---
 
-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.
+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 Components** — Use React hooks, state, and component patterns you already know
-- **Hot Module Replacement** — Edit your code and see changes instantly, powered by Vite
-- **Native Performance** — Direct FFI bindings to GTK4 via Rust and libffi
-- **CLI & Scaffolding** — Get started in seconds with `npx @gtkx/cli@latest create`
-- **CSS-in-JS Styling** — Emotion-style `css` template literals for GTK widgets
-- **Testing Library** — Familiar `screen`, `userEvent`, and query APIs for testing components
+- **React** — Hooks, state, props, and components you already know
+- **Hot Reload** — 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
 
 ## Quick Start
 
-Create a new GTKX app with a single command:
-
-```bash
-npx @gtkx/cli@latest create
-```
-
-This launches an interactive wizard that sets up your project with TypeScript, your preferred package manager, and optional testing support.
-
-You can also pass options directly:
-
-```bash
-npx @gtkx/cli@latest create my-app --app-id com.example.myapp --pm pnpm --testing vitest
-```
-
-Then start developing with HMR:
-
 ```bash
+npx @gtkx/cli@latest create my-app
 cd my-app
 npm run dev
 ```
 
-Edit your code and see changes instantly without restarting the app!
-
-### Manual Setup
+Edit your code and see changes instantly—no restart needed.
 
-Alternatively, install packages directly:
-
-```bash
-npm install @gtkx/cli @gtkx/react @gtkx/ffi react
-npm install -D @types/react typescript
-```
-
-Create your first app:
+### Example
 
 ```tsx
+import { render, ApplicationWindow, Box, Button, Label, quit } from "@gtkx/react";
+import { Orientation } from "@gtkx/ffi/gtk";
 import { useState } from "react";
-import * as Gtk from "@gtkx/ffi/gtk";
-import { ApplicationWindow, Box, Button, Label, quit } from "@gtkx/react";
 
-export default function App() {
+const App = () => {
   const [count, setCount] = useState(0);
 
   return (
-    <ApplicationWindow
-      title="My App"
-      defaultWidth={400}
-      defaultHeight={300}
-      onCloseRequest={quit}
-    >
-      <Box
-        orientation={Gtk.Orientation.VERTICAL}
-        spacing={12}
-        marginStart={20}
-        marginEnd={20}
-        marginTop={20}
-        marginBottom={20}
-      >
+    <ApplicationWindow title="Counter" 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>
   );
-}
-
-export const appId = "org.example.MyApp";
-```
-
-```tsx
-import { render } from "@gtkx/react";
-import App, { appId } from "./app.js";
-
-render(<App />, appId);
-```
+};
 
-Run with HMR:
-
-```bash
-npx gtkx dev src/app.tsx
-```
-
-Or without HMR (production):
-
-```bash
-npx tsc -b && node dist/index.js
+render(<App />, "org.example.Counter");
 ```
 
 ## Styling
 
-Use `@gtkx/css` for CSS-in-JS styling:
-
 ```tsx
 import { css } from "@gtkx/css";
 import { Button } from "@gtkx/react";
 
-const primaryButton = css`
+const primary = css`
   padding: 16px 32px;
   border-radius: 24px;
   background: linear-gradient(135deg, #3584e4, #9141ac);
   color: white;
-  font-weight: bold;
 `;
 
-const MyButton = () => <Button label="Click me" cssClasses={[primaryButton]} />;
+<Button label="Click me" cssClasses={[primary]} />
 ```
 
-GTK also provides built-in CSS classes like `suggested-action`, `destructive-action`, `card`, and `heading`.
+GTK also provides built-in classes like `suggested-action`, `destructive-action`, `card`, and `heading`.
 
 ## Testing
 
-Use `@gtkx/testing` for Testing Library-style component tests:
-
 ```tsx
-import { cleanup, render, screen, userEvent, fireEvent } from "@gtkx/testing";
+import { cleanup, render, screen, userEvent } from "@gtkx/testing";
 import { AccessibleRole } from "@gtkx/ffi/gtk";
-import { App } from "./app.js";
 
-afterEach(async () => {
-  await cleanup();
-});
+afterEach(() => cleanup());
 
-test("increments count when clicking button", async () => {
+test("increments count", async () => {
   await render(<App />);
 
-  const button = await screen.findByRole(AccessibleRole.BUTTON, {
-    name: "Increment",
-  });
+  const button = await screen.findByRole(AccessibleRole.BUTTON, { name: "Increment" });
   await userEvent.click(button);
 
   await screen.findByText("Count: 1");
 });
-
-test("can also use fireEvent for low-level signals", async () => {
-  await render(<App />);
-
-  const button = await screen.findByRole(AccessibleRole.BUTTON, {
-    name: "Increment",
-  });
-  fireEvent(button, "clicked");
-
-  await screen.findByText("Count: 1");
-});
 ```
 
-### Available APIs
-
-**Queries** - Find elements in the rendered tree (all async):
-
-- `findBy*` / `findAllBy*` - Waits for element to appear
-
-Query types: `ByRole`, `ByText`, `ByLabelText`, `ByTestId`
-
-**User Interactions**:
+Queries: `findByRole`, `findByText`, `findByLabelText`, `findByTestId`
 
-- `userEvent.click(element)` - Simulate click
-- `userEvent.dblClick(element)` - Simulate double click
-- `userEvent.activate(element)` - Activate element (e.g., press Enter in input)
-- `userEvent.type(element, text)` - Type text into input
-- `userEvent.clear(element)` - Clear input text
-- `userEvent.tab(element, options?)` - Simulate Tab navigation
-- `userEvent.selectOptions(element, values)` - Select options in ComboBox/ListBox
-- `userEvent.deselectOptions(element, values)` - Deselect options in ListBox
-
-**Low-level Events**:
-
-- `fireEvent(element, signalName, ...args)` - Emit any GTK signal with optional arguments
-
-**Utilities**:
-
-- `waitFor(callback)` - Wait for condition
-- `waitForElementToBeRemoved(element)` - Wait for element removal
+User events: `click`, `dblClick`, `type`, `clear`, `tab`, `selectOptions`
 
 ## Examples
 
-### GTK4 Demo
-
-A comprehensive showcase of GTK4 widgets and features:
+| Example | Description |
+| ------- | ----------- |
+| [gtk4-demo](examples/gtk4-demo) | Widget showcase |
+| [todo](examples/todo) | Todo app with tests |
 
 ```bash
-cd examples/gtk4-demo
-pnpm dev
-```
-
-### Todo App
-
-A todo app demonstrating `@gtkx/testing` with realistic component tests:
-
-```bash
-cd examples/todo
-pnpm dev
-pnpm test
+cd examples/gtk4-demo && pnpm dev
 ```
 
 ## Packages
 
-| Package                           | Description                                        |
-| --------------------------------- | -------------------------------------------------- |
-| [@gtkx/cli](packages/cli)         | CLI for creating and developing GTKX apps with HMR |
-| [@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           |
+| Package | Description |
+| ------- | ----------- |
+| [@gtkx/cli](packages/cli) | CLI with HMR dev server |
+| [@gtkx/react](packages/react) | React reconciler and JSX components |
+| [@gtkx/ffi](packages/ffi) | TypeScript bindings for GTK4/GLib/GIO |
+| [@gtkx/native](packages/native) | Rust native module (libffi bridge) |
+| [@gtkx/css](packages/css) | CSS-in-JS styling |
+| [@gtkx/testing](packages/testing) | Testing utilities |
+| [@gtkx/gir](packages/gir) | GObject Introspection parser |
 
 ## Requirements
 
 - Node.js 20+
-- GTK4
-- Linux (GTK4 is Linux-native)
+- GTK4 (`gtk4-devel` on Fedora, `libgtk-4-dev` on Ubuntu)
+- Linux
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+- [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)
+- [Read the Code of Conduct](CODE_OF_CONDUCT.md)
 
 ## License
 

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

@@ -29,7 +29,7 @@ export declare class CodeGenerator {
     private usesAlloc;
     private usesNativeError;
     private usesGetObject;
-    private usesRegisterClass;
+    private usesRegisterType;
     private usesSignalMeta;
     private usedEnums;
     private usedRecords;

package/dist/codegen/ffi-generator.js

@@ -224,7 +224,7 @@ export class CodeGenerator {
     usesAlloc = false;
     usesNativeError = false;
     usesGetObject = false;
-    usesRegisterClass = false;
+    usesRegisterType = false;
     usesSignalMeta = false;
     usedEnums = new Set();
     usedRecords = new Set();
@@ -346,7 +346,7 @@ export class CodeGenerator {
         this.usesAlloc = false;
         this.usesNativeError = false;
         this.usesGetObject = false;
-        this.usesRegisterClass = false;
+        this.usesRegisterType = false;
         this.usesSignalMeta = false;
         this.usedEnums.clear();
         this.usedRecords.clear();
@@ -434,8 +434,8 @@ export class CodeGenerator {
         }
         sections.push("}");
         if (cls.glibTypeName) {
-            this.usesRegisterClass = true;
-            sections.push(`\nregisterClass(${className});`);
+            this.usesRegisterType = true;
+            sections.push(`\nregisterType(${className});`);
         }
         if (signalMetaConstant) {
             const classDefIndex = sections.findIndex((s) => s.startsWith("export class "));
@@ -572,14 +572,12 @@ export class CodeGenerator {
         }
         let current = cls.parent ? classMap.get(cls.parent) : undefined;
         while (current) {
-            // Collect signals from the current parent class first
             for (const signal of current.signals) {
                 if (!seenNames.has(signal.name)) {
                     allSignals.push(signal);
                     seenNames.add(signal.name);
                 }
             }
-            // Then check if this parent has a cross-namespace grandparent
             if (current.parent?.includes(".")) {
                 return { signals: allSignals, hasCrossNamespaceParent: true };
             }
@@ -1111,6 +1109,8 @@ ${allArgs ? `${allArgs},` : ""}
                 lines.push(`    if (ptr === null) return null;`);
             }
             if (isCyclic) {
+                // For cyclic types, return a minimal NativeObject wrapper. Cast is necessary
+                // because the full type interface isn't available without circular imports.
                 lines.push(`    return { id: ptr } as unknown as ${baseReturnType};`);
             }
             else {
@@ -1263,6 +1263,8 @@ ${allArgs ? `${allArgs},` : ""}
                 kind: "class",
             });
         }
+        // Signal handler catch-all overload must use `any` for compatibility with typed overloads.
+        // The typed overloads have specific return types, and unknown is not assignable to them.
         signalOverloads.push(`  ${methodName}(signal: string, handler: (...args: any[]) => any, after?: boolean): number;`);
         this.usesType = true;
         this.usesGetObject = true;
@@ -1376,8 +1378,8 @@ ${allArgs ? `${allArgs},` : ""}
         sections.push(this.generateRecordFields(record.fields, record.methods));
         sections.push("}");
         if (record.glibTypeName) {
-            this.usesRegisterClass = true;
-            sections.push(`\nregisterClass(${recordName});`);
+            this.usesRegisterType = true;
+            sections.push(`\nregisterType(${recordName});`);
         }
         const imports = this.generateImports(recordName);
         return this.formatCode(imports + sections.join("\n"));
@@ -1872,8 +1874,8 @@ ${indent}  }`;
             ffiImports.push("NativeError");
         if (this.usesGetObject)
             ffiImports.push("getObject");
-        if (this.usesRegisterClass)
-            ffiImports.push("registerClass");
+        if (this.usesRegisterType)
+            ffiImports.push("registerType");
         if (ffiImports.length > 0) {
             lines.push(`import { ${ffiImports.join(", ")} } from "@gtkx/ffi";`);
         }

package/dist/generated/cairo/context.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class Context {
     static glibTypeName = "CairoContext";
     id;
@@ -9,4 +9,4 @@ export class Context {
         return null;
     }
 }
-registerClass(Context);
+registerType(Context);

package/dist/generated/cairo/device.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class Device {
     static glibTypeName = "CairoDevice";
     id;
@@ -9,4 +9,4 @@ export class Device {
         return null;
     }
 }
-registerClass(Device);
+registerType(Device);

package/dist/generated/cairo/font-face.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class FontFace {
     static glibTypeName = "CairoFontFace";
     id;
@@ -9,4 +9,4 @@ export class FontFace {
         return null;
     }
 }
-registerClass(FontFace);
+registerType(FontFace);

package/dist/generated/cairo/font-options.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class FontOptions {
     static glibTypeName = "CairoFontOptions";
     id;
@@ -9,4 +9,4 @@ export class FontOptions {
         return null;
     }
 }
-registerClass(FontOptions);
+registerType(FontOptions);

package/dist/generated/cairo/glyph.js

@@ -1,5 +1,5 @@
 import { alloc, read, write } from "@gtkx/native";
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class Glyph {
     static glibTypeName = "CairoGlyph";
     id;
@@ -35,4 +35,4 @@ export class Glyph {
         write(this.id, { type: "float", size: 64 }, 16, value);
     }
 }
-registerClass(Glyph);
+registerType(Glyph);

package/dist/generated/cairo/pattern.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class Pattern {
     static glibTypeName = "CairoPattern";
     id;
@@ -9,4 +9,4 @@ export class Pattern {
         return null;
     }
 }
-registerClass(Pattern);
+registerType(Pattern);

package/dist/generated/cairo/rectangle-int.js

@@ -1,5 +1,5 @@
 import { alloc, read, write } from "@gtkx/native";
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class RectangleInt {
     static glibTypeName = "CairoRectangleInt";
     id;
@@ -43,4 +43,4 @@ export class RectangleInt {
         write(this.id, { type: "int", size: 32, unsigned: false }, 12, value);
     }
 }
-registerClass(RectangleInt);
+registerType(RectangleInt);

package/dist/generated/cairo/rectangle.js

@@ -1,5 +1,5 @@
 import { alloc, read, write } from "@gtkx/native";
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class Rectangle {
     static glibTypeName = "CairoRectangle";
     id;
@@ -43,4 +43,4 @@ export class Rectangle {
         write(this.id, { type: "float", size: 64 }, 24, value);
     }
 }
-registerClass(Rectangle);
+registerType(Rectangle);

package/dist/generated/cairo/region.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class Region {
     static glibTypeName = "CairoRegion";
     id;
@@ -9,4 +9,4 @@ export class Region {
         return null;
     }
 }
-registerClass(Region);
+registerType(Region);

package/dist/generated/cairo/scaled-font.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class ScaledFont {
     static glibTypeName = "CairoScaledFont";
     id;
@@ -9,4 +9,4 @@ export class ScaledFont {
         return null;
     }
 }
-registerClass(ScaledFont);
+registerType(ScaledFont);

package/dist/generated/cairo/surface.js

@@ -1,4 +1,4 @@
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class Surface {
     static glibTypeName = "CairoSurface";
     id;
@@ -9,4 +9,4 @@ export class Surface {
         return null;
     }
 }
-registerClass(Surface);
+registerType(Surface);

package/dist/generated/cairo/text-cluster.js

@@ -1,5 +1,5 @@
 import { alloc, read, write } from "@gtkx/native";
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 export class TextCluster {
     static glibTypeName = "CairoTextCluster";
     id;
@@ -27,4 +27,4 @@ export class TextCluster {
         write(this.id, { type: "int", size: 32, unsigned: false }, 4, value);
     }
 }
-registerClass(TextCluster);
+registerType(TextCluster);

package/dist/generated/gdk/app-launch-context.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { getObject, registerClass } from "@gtkx/ffi";
+import { getObject, registerType } from "@gtkx/ffi";
 import * as Gio from "../gio/index.js";
 /**
  * Handles launching an application in a graphical context.
@@ -169,4 +169,4 @@ export class AppLaunchContext extends Gio.AppLaunchContext {
         ], { type: "int", size: 64, unsigned: true });
     }
 }
-registerClass(AppLaunchContext);
+registerType(AppLaunchContext);

package/dist/generated/gdk/button-event.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { registerClass } from "@gtkx/ffi";
+import { registerType } from "@gtkx/ffi";
 import { Event } from "./event.js";
 /** An event related to a button on a pointer device. */
 export class ButtonEvent extends Event {
@@ -30,4 +30,4 @@ export class ButtonEvent extends Event {
         ], { type: "int", size: 32, unsigned: true });
     }
 }
-registerClass(ButtonEvent);
+registerType(ButtonEvent);

package/dist/generated/gdk/cairo-context.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { getObject, registerClass } from "@gtkx/ffi";
+import { getObject, registerType } from "@gtkx/ffi";
 import { DrawContext } from "./draw-context.js";
 /**
  * Represents the platform-specific draw context.
@@ -69,4 +69,4 @@ export class CairoContext extends DrawContext {
         ], { type: "int", size: 64, unsigned: true });
     }
 }
-registerClass(CairoContext);
+registerType(CairoContext);

package/dist/generated/gdk/cicp-params.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { NativeError, getObject, registerClass } from "@gtkx/ffi";
+import { NativeError, getObject, registerType } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
 /**
  * Contains the parameters that define a colorstate with cicp parameters.
@@ -204,4 +204,4 @@ export class CicpParams extends GObject.GObject {
         ], { type: "int", size: 64, unsigned: true });
     }
 }
-registerClass(CicpParams);
+registerType(CicpParams);

package/dist/generated/gdk/clipboard.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { NativeError, getObject, registerClass } from "@gtkx/ffi";
+import { NativeError, getObject, registerType } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
 /**
  * Represents data shared between applications or inside an application.
@@ -366,4 +366,4 @@ export class Clipboard extends GObject.GObject {
         ], { type: "int", size: 64, unsigned: true });
     }
 }
-registerClass(Clipboard);
+registerType(Clipboard);

package/dist/generated/gdk/color-state.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { getObject, registerClass } from "@gtkx/ffi";
+import { getObject, registerType } from "@gtkx/ffi";
 /**
  * Provides information to interpret colors and pixels in a variety of ways.
  *
@@ -252,4 +252,4 @@ export class ColorState {
         ], { type: "undefined" });
     }
 }
-registerClass(ColorState);
+registerType(ColorState);

package/dist/generated/gdk/content-deserializer.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { getObject, registerClass } from "@gtkx/ffi";
+import { getObject, registerType } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
 /**
  * Deserializes content received via inter-application data transfers.
@@ -201,4 +201,4 @@ export class ContentDeserializer extends GObject.GObject {
         ], { type: "int", size: 64, unsigned: true });
     }
 }
-registerClass(ContentDeserializer);
+registerType(ContentDeserializer);

package/dist/generated/gdk/content-formats-builder.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { getObject, registerClass } from "@gtkx/ffi";
+import { getObject, registerType } from "@gtkx/ffi";
 /** Creates `GdkContentFormats` objects. */
 export class ContentFormatsBuilder {
     static glibTypeName = "GdkContentFormatsBuilder";
@@ -159,4 +159,4 @@ export class ContentFormatsBuilder {
         ], { type: "undefined" });
     }
 }
-registerClass(ContentFormatsBuilder);
+registerType(ContentFormatsBuilder);

package/dist/generated/gdk/content-formats.js

@@ -1,5 +1,5 @@
 import { call } from "@gtkx/native";
-import { getObject, registerClass } from "@gtkx/ffi";
+import { getObject, registerType } from "@gtkx/ffi";
 /**
  * Used to advertise and negotiate the format of content.
  *
@@ -515,4 +515,4 @@ export class ContentFormats {
         ], { type: "undefined" });
     }
 }
-registerClass(ContentFormats);
+registerType(ContentFormats);