create-gtkx 0.21.0

package/templates/claude/SKILL.md.ejs

@@ -0,0 +1,126 @@
+---
+name: developing-gtkx-apps
+description: Build GTK4 desktop applications with GTKX React framework. Use when creating React components that render as native GTK widgets, working with GTK4/Libadwaita UI, handling signals, virtual lists, menus, or building Linux desktop UIs.
+---
+
+# Developing GTKX Applications
+
+GTKX renders React components as native GTK4 widgets through a Rust FFI bridge.
+
+## Quick Start
+
+```tsx
+// src/index.tsx
+import { applicationId } from "virtual:gtkx-config";
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkApplication, GtkApplicationWindow, GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
+import { createRoot, quit } from "@gtkx/react";
+
+const App = () => (
+    <GtkApplication applicationId={applicationId}>
+        <GtkApplicationWindow
+            title="My App"
+            defaultWidth={800}
+            defaultHeight={600}
+            onCloseRequest={() => {
+                quit();
+                return true;
+            }}
+        >
+            <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
+                <GtkLabel label="Hello, GTKX!" />
+                <GtkButton label="Quit" onClicked={quit} />
+            </GtkBox>
+        </GtkApplicationWindow>
+    </GtkApplication>
+);
+
+createRoot().render(<App />);
+```
+
+The application id is passed explicitly; the `virtual:gtkx-config` module exposes each field of the resolved `gtkx.config.ts` as a named constant, so the `applicationId` declared there reaches the application through the prop. `createRoot().render()` is called once at module top-level — analogous to `createRoot` in `react-dom`. In dev, `gtkx dev` restarts the Node process whenever a non-component file changes, so this top-level call only ever runs once per process life.
+
+## Essential Patterns
+
+### Layout
+
+```tsx
+<GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
+    <GtkLabel label="Title" />
+    <GtkButton label="Click" onClicked={handleClick} />
+</GtkBox>
+```
+
+### Controlled Input
+
+```tsx
+const [text, setText] = useState("");
+<GtkEntry text={text} onChanged={(e) => setText(e.getText())} />
+```
+
+### Signals
+
+GTK signals map to `on<SignalName>` props: `clicked` → `onClicked`, `toggled` → `onToggled`.
+
+### Widget Slots
+
+Some widgets place children in specific slots. A slot is a plain prop on the widget element that accepts a React element; the value replaces the slot's single child:
+
+```tsx
+<GtkPaned startChild={<Sidebar />} endChild={<Content />} />
+```
+
+A project can expose additional widget-typed properties as slots through the `slots` map in `gtkx.config.ts`.
+
+### Container Slots (HeaderBar, ActionBar, ToolbarView, ActionRow, ExpanderRow)
+
+Packing slots are also plain props on the widget element (`packStart=`, `packEnd=`, `addTopBar=`, `addPrefix=`, …); each child is appended via the parent method the prop is named after (wrap several in a fragment):
+
+```tsx
+<GtkHeaderBar
+    packStart={<GtkButton iconName="go-previous-symbolic" />}
+    packEnd={<GtkMenuButton iconName="open-menu-symbolic" />}
+/>
+```
+
+A project can expose additional append methods as container slots through the `containerProps` map in `gtkx.config.ts`.
+
+### Animations
+
+Animations are first-class components, picked by physics model: `AdwSpringAnimation` (damping/stiffness/mass) or `AdwTimedAnimation` (duration/easing). Import the name from `@gtkx/animate`.
+
+```tsx
+<AdwSpringAnimation
+    initial={{ opacity: 0, scale: 0.8 }}
+    animate={{ opacity: 1, scale: 1 }}
+    damping={0.8}
+    stiffness={200}
+    animateOnMount
+>
+    <GtkLabel label="Animated!" />
+</AdwSpringAnimation>
+```
+
+```tsx
+<AdwTimedAnimation
+    initial={{ opacity: 0 }}
+    animate={{ opacity: 1 }}
+    duration={300}
+    easing={Adw.Easing.EASE_OUT_CUBIC}
+    animateOnMount
+>
+    <GtkLabel label="Fade in" />
+</AdwTimedAnimation>
+```
+
+## Key Constraints
+
+- GTK is single-threaded: all widget operations on main thread
+- GtkEntry requires two-way binding with `onChanged`
+- Virtual lists need stable object references (immutable data patterns)
+- Use `quit` from `@gtkx/react` to close the application
+
+## References
+
+For complete widget API, see [WIDGETS.md](WIDGETS.md).
+For code patterns and examples, see [EXAMPLES.md](EXAMPLES.md).