@gtkx/cli 0.11.0 → 0.12.0

package/templates/claude/SKILL.md.ejs

@@ -1,16 +1,16 @@
 ---
 name: developing-gtkx-apps
-description: Build GTK4 desktop applications with GTKX React framework. Use when creating GTKX components, working with GTK widgets, handling signals, or building Linux desktop UIs with React.
+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 is a React framework for building native GTK4 desktop applications on Linux. It uses a custom React reconciler to render React components as native GTK widgets.
+GTKX renders React components as native GTK4 widgets through a Rust FFI bridge.
 
 ## Quick Start
 
 ```tsx
-import { GtkApplicationWindow, GtkBox, GtkButton, GtkLabel, render, quit } from "@gtkx/react";
+import { GtkApplicationWindow, GtkBox, GtkButton, render, quit } from "@gtkx/react";
 import * as Gtk from "@gtkx/ffi/gtk";
 
 const App = () => (
@@ -25,346 +25,56 @@ const App = () => (
 render(<App />, "com.example.myapp");
 ```
 
-## Widget Patterns
+## Essential Patterns
 
-### Container Widgets
+### Layout
 
-**GtkBox** - Linear layout:
 ```tsx
 <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
-    First
-    Second
+    <GtkLabel label="Title" />
+    <GtkButton label="Click" onClicked={handleClick} />
 </GtkBox>
 ```
 
-**GtkGrid** - 2D positioning:
-```tsx
-<GtkGrid rowSpacing={10} columnSpacing={10}>
-    <GridChild column={0} row={0}>Top-left</GridChild>
-    <GridChild column={1} row={0} columnSpan={2}>Spans 2 columns</GridChild>
-</GtkGrid>
-```
-
-**GtkStack** - Page-based container:
-```tsx
-<GtkStack visibleChildName="page1">
-    <StackPage name="page1" title="Page 1">Content 1</StackPage>
-    <StackPage name="page2" title="Page 2">Content 2</StackPage>
-</GtkStack>
-```
-
-**GtkNotebook** - Tabbed container:
-```tsx
-<GtkNotebook>
-    <Notebook.Page label="Tab 1">
-        <Content1 />
-    </Notebook.Page>
-    <Notebook.Page label="Tab 2">
-        <Content2 />
-    </Notebook.Page>
-</GtkNotebook>
-```
-
-**GtkPaned** - Resizable split:
-```tsx
-<GtkPaned orientation={Gtk.Orientation.HORIZONTAL} position={280}>
-    <Slot for={GtkPaned} id="startChild">
-        <SideBar />
-    </Slot>
-    <Slot for={GtkPaned} id="endChild">
-        <MainContent />
-    </Slot>
-</GtkPaned>
-```
-
-### Virtual Scrolling Lists
-
-**ListView** - High-performance scrollable list with selection:
-```tsx
-<ListView<Item>
-    vexpand
-    selected={[selectedId]}
-    selectionMode={Gtk.SelectionMode.SINGLE}
-    onSelectionChanged={(ids) => setSelectedId(ids[0])}
-    renderItem={(item) => (
-        <GtkLabel label={item?.text ?? ""} />
-    )}
->
-    {items.map(item => (
-        <ListItem key={item.id} id={item.id} value={item} />
-    ))}
-</ListView>
-```
-
-**GridView** - Grid-based virtual scrolling:
-```tsx
-<GridView<Item>
-    vexpand
-    minColumns={2}
-    maxColumns={4}
-    renderItem={(item) => (
-        <GtkBox orientation={Gtk.Orientation.VERTICAL}>
-            <GtkImage iconName={item?.icon ?? "image-missing"} />
-            <GtkLabel label={item?.name ?? ""} />
-        </GtkBox>
-    )}
->
-    {items.map(item => (
-        <ListItem key={item.id} id={item.id} value={item} />
-    ))}
-</GridView>
-```
-
-**GtkColumnView** - Table with sortable columns:
-```tsx
-<GtkColumnView
-    sortColumn="name"
-    sortOrder={Gtk.SortType.ASCENDING}
-    onSortChange={handleSort}
->
-    <ColumnViewColumn<Item>
-        title="Name"
-        id="name"
-        expand
-        sortable
-        renderCell={(item) => (
-            <GtkLabel label={item?.name ?? ""} />
-        )}
-    />
-    {items.map(item => (
-        <ListItem key={item.id} id={item.id} value={item} />
-    ))}
-</GtkColumnView>
-```
-
-**GtkDropDown** - String selection dropdown with controlled state:
-```tsx
-<GtkDropDown selectedId={selectedId} onSelectionChanged={setSelectedId}>
-    {options.map(opt => (
-        <SimpleListItem key={opt.id} id={opt.id} value={opt.label} />
-    ))}
-</GtkDropDown>
-```
-
-**GtkOverlay** - Stack widgets on top of each other (first child is base):
-```tsx
-<GtkOverlay>
-    <GtkButton label="Notifications" />
-    <GtkLabel
-        label="3"
-        cssClasses={["badge"]}
-        halign={Gtk.Align.END}
-        valign={Gtk.Align.START}
-    />
-</GtkOverlay>
-```
-
-### GtkHeaderBar
-
-Pack widgets at start and end of the title bar using Slot or Pack components:
-```tsx
-<GtkHeaderBar>
-    <Pack.Start>
-        <GtkButton iconName="go-previous-symbolic" />
-    </Pack.Start>
-    <Slot for={GtkHeaderBar} id="titleWidget">
-        <GtkLabel label="My App" cssClasses={["title"]} />
-    </Slot>
-    <Pack.End>
-        <GtkMenuButton iconName="open-menu-symbolic" />
-    </Pack.End>
-</GtkHeaderBar>
-```
-
-### GtkActionBar
-
-Bottom bar with packed widgets:
-```tsx
-<GtkActionBar>
-    <Pack.Start>
-        <GtkButton label="Cancel" />
-    </Pack.Start>
-    <Pack.End>
-        <GtkButton label="Save" cssClasses={["suggested-action"]} />
-    </Pack.End>
-</GtkActionBar>
-```
-
 ### Controlled Input
 
-GtkEntry requires two-way binding:
 ```tsx
 const [text, setText] = useState("");
-
-<GtkEntry
-    text={text}
-    onChanged={(entry) => setText(entry.getText())}
-    placeholderText="Type here..."
-/>
+<GtkEntry text={text} onChanged={(e) => setText(e.getText())} />
 ```
 
-### Declarative Menus
+### Signals
 
-```tsx
-<GtkPopoverMenu>
-    <Menu.Section>
-        <Menu.Item
-            id="new"
-            label="New"
-            onActivate={handleNew}
-            accels="<Control>n"
-        />
-    </Menu.Section>
-    <Menu.Section>
-        <Menu.Submenu label="Export">
-            <Menu.Item id="pdf" label="PDF" onActivate={handleExportPdf} />
-            <Menu.Item id="csv" label="CSV" onActivate={handleExportCsv} />
-        </Menu.Submenu>
-    </Menu.Section>
-    <Menu.Section>
-        <Menu.Item id="quit" label="Quit" onActivate={quit} accels="<Control>q" />
-    </Menu.Section>
-</GtkPopoverMenu>
-```
-
-## Signal Handling
+GTK signals map to `on<SignalName>` props: `clicked` → `onClicked`, `toggled` → `onToggled`.
 
-GTK signals map to `on<SignalName>` props:
-- `clicked` → `onClicked`
-- `toggled` → `onToggled`
-- `changed` → `onChanged`
-- `notify::selected` → `onNotify` (with property name arg)
+### Widget Slots
 
-## Widget References
+Some widgets require children in specific slots:
 
 ```tsx
-import { useRef } from "react";
-
-const entryRef = useRef<Gtk.Entry | null>(null);
-<GtkEntry ref={entryRef} />
-```
-
-## Portals
-
-```tsx
-import { createPortal } from "@gtkx/react";
-
-{createPortal(<GtkAboutDialog programName="My App" />)}
-```
-
-## Adwaita (Libadwaita) Widgets
-
-Import Adwaita widgets and enums:
-```tsx
-import * as Adw from "@gtkx/ffi/adw";
-import { AdwApplicationWindow, AdwHeaderBar, AdwToolbarView, Toolbar } from "@gtkx/react";
-```
-
-### AdwToolbarView
-Modern app layout with top/bottom bars:
-```tsx
-<AdwToolbarView>
-    <Toolbar.Top>
-        <AdwHeaderBar>
-            <Slot for={AdwHeaderBar} id="titleWidget">
-                <AdwWindowTitle title="App" subtitle="Description" />
-            </Slot>
-        </AdwHeaderBar>
-    </Toolbar.Top>
-    <MainContent />
-    <Toolbar.Bottom>
-        <GtkActionBar>...</GtkActionBar>
-    </Toolbar.Bottom>
-</AdwToolbarView>
-```
-
-### AdwApplicationWindow
-Modern application window:
-```tsx
-<AdwApplicationWindow title="My App" defaultWidth={800} defaultHeight={600} onCloseRequest={quit}>
-    <AdwToolbarView>...</AdwToolbarView>
-</AdwApplicationWindow>
-```
-
-### AdwStatusPage
-Welcome or empty state pages:
-```tsx
-<AdwStatusPage
-    iconName="applications-system-symbolic"
-    title="Welcome"
-    description="Get started with your app"
-    vexpand
-/>
-```
-
-### AdwBanner
-Dismissable notification banner:
-```tsx
-<AdwBanner
-    title="Update available!"
-    buttonLabel="Dismiss"
-    revealed={showBanner}
-    onButtonClicked={() => setShowBanner(false)}
-/>
-```
-
-### AdwPreferencesPage / AdwPreferencesGroup
-Settings UI layout:
-```tsx
-<AdwPreferencesPage title="Settings">
-    <AdwPreferencesGroup title="Appearance" description="Customize the look">
-        <AdwSwitchRow title="Dark Mode" active={dark} onActivate={() => setDark(!dark)} />
-        <AdwActionRow title="Theme" subtitle="Select color theme">
-            <Slot for={AdwActionRow} id="activatableWidget">
-                <GtkImage iconName="go-next-symbolic" />
-            </Slot>
-        </AdwActionRow>
-    </AdwPreferencesGroup>
-</AdwPreferencesPage>
-```
-
-### AdwExpanderRow
-Expandable row with nested content:
-```tsx
-<AdwExpanderRow title="Advanced" subtitle="More options">
-    <AdwSwitchRow title="Option 1" active />
-    <AdwSwitchRow title="Option 2" active={false} />
-</AdwExpanderRow>
-```
-
-### AdwEntryRow / AdwPasswordEntryRow
-Input fields in list rows:
-```tsx
-<AdwEntryRow title="Username" text={username} onChanged={(e) => setUsername(e.getText())} />
-<AdwPasswordEntryRow title="Password" />
+<GtkPaned orientation={Gtk.Orientation.HORIZONTAL}>
+    <Slot for={GtkPaned} id="startChild"><Sidebar /></Slot>
+    <Slot for={GtkPaned} id="endChild"><Content /></Slot>
+</GtkPaned>
 ```
 
-### AdwClamp
-Limit content width for readability:
-```tsx
-<AdwClamp maximumSize={600}>
-    <GtkBox>...</GtkBox>
-</AdwClamp>
-```
+### Packing (HeaderBar, ActionBar)
 
-### AdwAvatar
-User avatar with initials fallback:
 ```tsx
-<AdwAvatar size={48} text="John Doe" showInitials />
+<GtkHeaderBar>
+    <Pack.Start><GtkButton iconName="go-previous-symbolic" /></Pack.Start>
+    <Pack.End><GtkMenuButton iconName="open-menu-symbolic" /></Pack.End>
+</GtkHeaderBar>
 ```
 
-### AdwSpinner
-Loading indicator:
-```tsx
-{isLoading && <AdwSpinner widthRequest={32} heightRequest={32} />}
-```
+## Key Constraints
 
-## 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
 
-- **GTK is single-threaded**: All widget operations on main thread
-- **Virtual lists need immutable data**: Use stable object references
-- **GtkToggleButton auto-prevents feedback loops**: Safe for controlled state
-- **GtkEntry needs two-way binding**: Use `onChanged` to sync state
+## References
 
-For detailed widget reference, see [WIDGETS.md](WIDGETS.md).
-For code examples, see [EXAMPLES.md](EXAMPLES.md).
+For complete widget API, see [WIDGETS.md](WIDGETS.md).
+For code patterns and examples, see [EXAMPLES.md](EXAMPLES.md).