create-gtkx 0.21.0

package/templates/claude/EXAMPLES.md.ejs

@@ -0,0 +1,790 @@
+# GTKX Code Examples
+
+## App Structure
+
+### Minimal App
+
+```tsx
+// src/index.tsx
+import { applicationId } from "virtual:gtkx-config";
+import { GtkApplication, GtkApplicationWindow, GtkLabel } from "@gtkx/jsx/gtk";
+import { createRoot, quit } from "@gtkx/react";
+
+const App = () => (
+    <GtkApplication applicationId={applicationId}>
+        <GtkApplicationWindow
+            title="Hello"
+            defaultWidth={400}
+            defaultHeight={300}
+            onCloseRequest={() => {
+                quit();
+                return true;
+            }}
+        >
+            <GtkLabel label="Hello, World!" />
+        </GtkApplicationWindow>
+    </GtkApplication>
+);
+
+createRoot().render(<App />);
+```
+
+The entry calls `createRoot().render()` directly (similar to `createRoot` in `react-dom`). The `<GtkApplication>` component constructs, registers, and activates the GTK application; pass its `applicationId` explicitly, reading the one declared in `gtkx.config.ts` from the `virtual:gtkx-config` module. `gtkx dev` restarts the Node process on entry-level changes so the top-level call only runs once per process life.
+
+### Modern Adwaita App
+
+```tsx
+import { applicationId } from "virtual:gtkx-config";
+import * as Gtk from "@gtkx/gi/gtk";
+import { AdwApplication, AdwApplicationWindow, AdwHeaderBar, AdwToolbarView, AdwWindowTitle, AdwStatusPage } from "@gtkx/jsx/adw";
+import { quit } from "@gtkx/react";
+import { GtkButton } from "@gtkx/jsx/gtk";
+
+const MainWindow = () => (
+    <AdwApplicationWindow
+        title="My App"
+        defaultWidth={800}
+        defaultHeight={600}
+        onCloseRequest={() => {
+            quit();
+            return true;
+        }}
+    >
+        <AdwToolbarView
+            addTopBar={
+                <AdwHeaderBar titleWidget={<AdwWindowTitle title="My App" subtitle="Welcome" />} />
+            }
+        >
+            <AdwStatusPage
+                iconName="applications-system-symbolic"
+                title="Welcome"
+                description="Get started with your GTKX app"
+                vexpand
+            >
+                <GtkButton label="Get Started" cssClasses={["suggested-action", "pill"]} halign={Gtk.Align.CENTER} />
+            </AdwStatusPage>
+        </AdwToolbarView>
+    </AdwApplicationWindow>
+);
+
+export const App = () => (
+    <AdwApplication applicationId={applicationId}>
+        <MainWindow />
+    </AdwApplication>
+);
+```
+
+---
+
+## State Management
+
+### Controlled Form
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkButton, GtkEntry, GtkGrid, GtkGridChild, GtkLabel } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+const LoginForm = () => {
+    const [email, setEmail] = useState("");
+    const [password, setPassword] = useState("");
+
+    const handleSubmit = () => {
+        console.log("Login:", { email, password });
+    };
+
+    return (
+        <GtkGrid rowSpacing={12} columnSpacing={12}>
+            <GtkGridChild column={0} row={0}>
+                <GtkLabel label="Email:" halign={Gtk.Align.END} />
+            </GtkGridChild>
+            <GtkGridChild column={1} row={0}>
+                <GtkEntry text={email} onChanged={(e) => setEmail(e.getText())} hexpand />
+            </GtkGridChild>
+            <GtkGridChild column={0} row={1}>
+                <GtkLabel label="Password:" halign={Gtk.Align.END} />
+            </GtkGridChild>
+            <GtkGridChild column={1} row={1}>
+                <GtkEntry text={password} onChanged={(e) => setPassword(e.getText())} visibility={false} hexpand />
+            </GtkGridChild>
+            <GtkGridChild column={0} row={2} columnSpan={2}>
+                <GtkButton label="Login" onClicked={handleSubmit} cssClasses={["suggested-action"]} halign={Gtk.Align.END} />
+            </GtkGridChild>
+        </GtkGrid>
+    );
+};
+```
+
+### List with CRUD Operations
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkBox, GtkButton, GtkEntry, GtkLabel, GtkListView, GtkScrolledWindow } from "@gtkx/jsx/gtk";
+import { useCallback, useState } from "react";
+
+interface Todo {
+    id: string;
+    text: string;
+}
+
+let nextId = 1;
+
+const TodoList = () => {
+    const [todos, setTodos] = useState<Todo[]>([]);
+    const [input, setInput] = useState("");
+
+    const addTodo = useCallback(() => {
+        if (!input.trim()) return;
+        setTodos((prev) => [...prev, { id: String(nextId++), text: input }]);
+        setInput("");
+    }, [input]);
+
+    const deleteTodo = useCallback((id: string) => {
+        setTodos((prev) => prev.filter((t) => t.id !== id));
+    }, []);
+
+    return (
+        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} marginStart={16} marginEnd={16} marginTop={16} marginBottom={16}>
+            <GtkBox spacing={8}>
+                <GtkEntry text={input} onChanged={(e) => setInput(e.getText())} hexpand placeholderText="New todo..." />
+                <GtkButton label="Add" onClicked={addTodo} cssClasses={["suggested-action"]} />
+            </GtkBox>
+            <GtkScrolledWindow vexpand cssClasses={["card"]}>
+                <GtkListView
+                    items={todos.map((todo) => ({ id: todo.id, value: todo }))}
+                    renderItem={(todo: Todo) => (
+                        <GtkBox spacing={8} marginStart={12} marginEnd={12} marginTop={8} marginBottom={8}>
+                            <GtkLabel label={todo.text} hexpand halign={Gtk.Align.START} />
+                            <GtkButton iconName="edit-delete-symbolic" cssClasses={["flat"]} onClicked={() => deleteTodo(todo.id)} />
+                        </GtkBox>
+                    )}
+                />
+            </GtkScrolledWindow>
+        </GtkBox>
+    );
+};
+```
+
+---
+
+## Navigation Patterns
+
+### Stack with Sidebar Navigation
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkLabel, GtkListView, GtkPaned, GtkScrolledWindow, GtkStack, GtkStackPage } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+interface Page {
+    id: string;
+    name: string;
+}
+
+const pages: Page[] = [
+    { id: "home", name: "Home" },
+    { id: "settings", name: "Settings" },
+    { id: "about", name: "About" },
+];
+
+const SidebarNav = () => {
+    const [currentPage, setCurrentPage] = useState("home");
+
+    return (
+        <GtkPaned
+            position={200}
+            startChild={
+                <GtkScrolledWindow cssClasses={["sidebar"]}>
+                    <GtkListView
+                        selected={[currentPage]}
+                        selectionMode={Gtk.SelectionMode.SINGLE}
+                        onSelectionChanged={(ids) => setCurrentPage(ids[0])}
+                        items={pages.map((page) => ({ id: page.id, value: page }))}
+                        renderItem={(page: Page) => (
+                            <GtkLabel label={page.name} halign={Gtk.Align.START} marginStart={12} marginTop={8} marginBottom={8} />
+                        )}
+                    />
+                </GtkScrolledWindow>
+            }
+            endChild={
+                <GtkStack visibleChildName={currentPage}>
+                    <GtkStackPage id="home"><GtkLabel label="Home Content" vexpand /></GtkStackPage>
+                    <GtkStackPage id="settings"><GtkLabel label="Settings Content" vexpand /></GtkStackPage>
+                    <GtkStackPage id="about"><GtkLabel label="About Content" vexpand /></GtkStackPage>
+                </GtkStack>
+            }
+        />
+    );
+};
+```
+
+### Header Bar with Back Navigation
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { quit } from "@gtkx/react";
+import { GtkApplicationWindow, GtkBox, GtkButton, GtkHeaderBar, GtkLabel, GtkStack, GtkStackPage } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+const AppWithNavigation = () => {
+    const [page, setPage] = useState("home");
+
+    return (
+        <GtkApplicationWindow
+            title="App"
+            defaultWidth={600}
+            defaultHeight={400}
+            onCloseRequest={() => {
+                quit();
+                return true;
+            }}
+            titlebar={
+                <GtkHeaderBar
+                    packStart={
+                        page !== "home" && <GtkButton iconName="go-previous-symbolic" onClicked={() => setPage("home")} />
+                    }
+                    titleWidget={<GtkLabel label={page === "home" ? "Home" : "Details"} cssClasses={["title"]} />}
+                />
+            }
+        >
+            <GtkStack visibleChildName={page}>
+                <GtkStackPage id="home">
+                    <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} vexpand halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER}>
+                        <GtkLabel label="Welcome" />
+                        <GtkButton label="Go to Details" onClicked={() => setPage("details")} />
+                    </GtkBox>
+                </GtkStackPage>
+                <GtkStackPage id="details">
+                    <GtkLabel label="Details Page Content" vexpand />
+                </GtkStackPage>
+            </GtkStack>
+        </GtkApplicationWindow>
+    );
+};
+```
+
+---
+
+## Settings Page
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { AdwPreferencesPage, AdwPreferencesGroup, AdwActionRow, AdwSwitchRow, AdwExpanderRow, AdwEntryRow } from "@gtkx/jsx/adw";
+import { GtkImage, GtkScrolledWindow } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+const SettingsPage = () => {
+    const [darkMode, setDarkMode] = useState(false);
+    const [notifications, setNotifications] = useState(true);
+    const [username, setUsername] = useState("");
+
+    return (
+        <GtkScrolledWindow vexpand>
+            <AdwPreferencesPage title="Settings">
+                <AdwPreferencesGroup title="Appearance">
+                    <AdwSwitchRow title="Dark Mode" subtitle="Use dark color scheme" active={darkMode} onNotifyActive={(active) => setDarkMode(active ?? false)} />
+                </AdwPreferencesGroup>
+
+                <AdwPreferencesGroup title="Account">
+                    <AdwEntryRow title="Username" text={username} onChanged={(e) => setUsername(e.getText())} />
+                    <AdwActionRow
+                        title="Profile"
+                        subtitle="Manage your profile"
+                        addSuffix={<GtkImage iconName="go-next-symbolic" valign={Gtk.Align.CENTER} />}
+                    />
+                </AdwPreferencesGroup>
+
+                <AdwPreferencesGroup title="Notifications">
+                    <AdwExpanderRow
+                        title="Notification Settings"
+                        subtitle="Configure alerts"
+                        addRow={
+                            <>
+                                <AdwSwitchRow title="Sound" active />
+                                <AdwSwitchRow title="Badges" active />
+                                <AdwSwitchRow title="Lock Screen" />
+                            </>
+                        }
+                    />
+                </AdwPreferencesGroup>
+            </AdwPreferencesPage>
+        </GtkScrolledWindow>
+    );
+};
+```
+
+---
+
+## Data Table with Sorting
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkColumnView, GtkColumnViewColumn, GtkLabel, GtkScrolledWindow } from "@gtkx/jsx/gtk";
+import { useMemo, useState } from "react";
+
+interface FileItem {
+    id: string;
+    name: string;
+    size: number;
+    modified: string;
+}
+
+const files: FileItem[] = [
+    { id: "1", name: "document.pdf", size: 1024, modified: "2024-01-15" },
+    { id: "2", name: "image.png", size: 2048, modified: "2024-01-14" },
+    { id: "3", name: "notes.txt", size: 512, modified: "2024-01-13" },
+];
+
+const FileTable = () => {
+    const [sortColumn, setSortColumn] = useState("name");
+    const [sortOrder, setSortOrder] = useState(Gtk.SortType.ASCENDING);
+
+    const sortedFiles = useMemo(() => {
+        const sorted = [...files].sort((a, b) => {
+            const aVal = a[sortColumn as keyof FileItem];
+            const bVal = b[sortColumn as keyof FileItem];
+            const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+            return sortOrder === Gtk.SortType.ASCENDING ? cmp : -cmp;
+        });
+        return sorted;
+    }, [sortColumn, sortOrder]);
+
+    const handleSort = (column: string, order: Gtk.SortType) => {
+        setSortColumn(column);
+        setSortOrder(order);
+    };
+
+    return (
+        <GtkScrolledWindow vexpand cssClasses={["card"]}>
+            <GtkColumnView
+                estimatedRowHeight={48}
+                sortColumn={sortColumn}
+                sortOrder={sortOrder}
+                onSortChanged={handleSort}
+                items={sortedFiles.map((file) => ({ id: file.id, value: file }))}
+            >
+                <GtkColumnViewColumn title="Name" id="name" expand sortable renderCell={(f: FileItem) => <GtkLabel label={f.name} />} />
+                <GtkColumnViewColumn title="Size" id="size" fixedWidth={100} sortable renderCell={(f: FileItem) => <GtkLabel label={`${f.size} KB`} />} />
+                <GtkColumnViewColumn title="Modified" id="modified" fixedWidth={120} sortable renderCell={(f: FileItem) => <GtkLabel label={f.modified} />} />
+            </GtkColumnView>
+        </GtkScrolledWindow>
+    );
+};
+```
+
+---
+
+## Menu with Keyboard Shortcuts
+
+Menus are data: `<GMenu>` takes an `items` array of `MenuEntry` objects whose `action` names reference `<GSimpleAction>` elements installed through the window's `addAction` prop.
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { quit } from "@gtkx/react";
+import { GMenu, GSimpleAction } from "@gtkx/jsx/gio";
+import { GtkApplicationWindow, GtkBox, GtkLabel, GtkMenuButton } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+const MenuDemo = () => {
+    const [lastAction, setLastAction] = useState<string | null>(null);
+
+    return (
+        <GtkApplicationWindow
+            title="Menu Demo"
+            onCloseRequest={() => {
+                quit();
+                return true;
+            }}
+            addAction={
+                <>
+                    <GSimpleAction name="new" onActivate={() => setLastAction("New")} accels="<Control>n" />
+                    <GSimpleAction name="open" onActivate={() => setLastAction("Open")} accels="<Control>o" />
+                    <GSimpleAction name="save" onActivate={() => setLastAction("Save")} accels="<Control>s" />
+                    <GSimpleAction name="export-pdf" onActivate={() => setLastAction("Export PDF")} />
+                    <GSimpleAction name="export-csv" onActivate={() => setLastAction("Export CSV")} />
+                    <GSimpleAction name="quit" onActivate={quit} accels="<Control>q" />
+                </>
+            }
+        >
+            <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} marginStart={16} marginEnd={16} marginTop={16} marginBottom={16}>
+                <GtkMenuButton
+                    label="File"
+                    halign={Gtk.Align.START}
+                    menuModel={
+                        <GMenu
+                            items={[
+                                { label: "_New", action: "win.new" },
+                                { label: "_Open", action: "win.open" },
+                                { label: "_Save", action: "win.save" },
+                                {
+                                    label: "Export",
+                                    submenu: [
+                                        { label: "As PDF", action: "win.export-pdf" },
+                                        { label: "As CSV", action: "win.export-csv" },
+                                    ],
+                                },
+                                { section: [{ label: "_Quit", action: "win.quit" }] },
+                            ]}
+                        />
+                    }
+                />
+                <GtkLabel label={`Last action: ${lastAction ?? "(none)"}`} />
+            </GtkBox>
+        </GtkApplicationWindow>
+    );
+};
+```
+
+---
+
+## Async Data Loading
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { AdwSpinner } from "@gtkx/jsx/adw";
+import { GtkBox, GtkLabel, GtkListView, GtkScrolledWindow } from "@gtkx/jsx/gtk";
+import { useEffect, useState } from "react";
+
+interface User {
+    id: string;
+    name: string;
+    email: string;
+}
+
+const AsyncList = () => {
+    const [users, setUsers] = useState<User[]>([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<string | null>(null);
+
+    useEffect(() => {
+        const fetchUsers = async () => {
+            try {
+                const response = await fetch("https://api.example.com/users");
+                const data = await response.json();
+                setUsers(data);
+            } catch (error) {
+                setError(error instanceof Error ? error.message : "Failed to load");
+            } finally {
+                setLoading(false);
+            }
+        };
+        fetchUsers();
+    }, []);
+
+    if (loading) {
+        return (
+            <GtkBox vexpand halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER}>
+                <AdwSpinner widthRequest={32} heightRequest={32} />
+            </GtkBox>
+        );
+    }
+
+    if (error) {
+        return <GtkLabel label={`Error: ${error}`} cssClasses={["error"]} vexpand halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER} />;
+    }
+
+    return (
+        <GtkScrolledWindow vexpand>
+            <GtkListView
+                items={users.map((user) => ({ id: user.id, value: user }))}
+                renderItem={(user: User) => (
+                    <GtkBox orientation={Gtk.Orientation.VERTICAL} marginStart={12} marginTop={8} marginBottom={8}>
+                        <GtkLabel label={user.name} halign={Gtk.Align.START} cssClasses={["heading"]} />
+                        <GtkLabel label={user.email} halign={Gtk.Align.START} cssClasses={["dim-label"]} />
+                    </GtkBox>
+                )}
+            />
+        </GtkScrolledWindow>
+    );
+};
+```
+
+---
+
+## Reusable Component Pattern
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
+import type { ReactNode } from "react";
+
+interface CardProps {
+    title: string;
+    children: ReactNode;
+    onAction?: () => void;
+    actionLabel?: string;
+}
+
+const Card = ({ title, children, onAction, actionLabel }: CardProps) => (
+    <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={8} cssClasses={["card"]} marginStart={12} marginEnd={12} marginTop={8} marginBottom={8}>
+        <GtkLabel label={title} cssClasses={["title-4"]} halign={Gtk.Align.START} />
+        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={4}>
+            {children}
+        </GtkBox>
+        {onAction && actionLabel && (
+            <GtkButton label={actionLabel} onClicked={onAction} halign={Gtk.Align.END} cssClasses={["flat"]} />
+        )}
+    </GtkBox>
+);
+
+const CardDemo = () => (
+    <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
+        <Card title="Welcome" actionLabel="Learn More" onAction={() => console.log("clicked")}>
+            <GtkLabel label="This is a reusable card component." wrap />
+        </Card>
+        <Card title="Features">
+            <GtkLabel label="Build native GTK apps with React." wrap />
+        </Card>
+    </GtkBox>
+);
+```
+
+---
+
+## Navigation with AdwNavigationView
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { quit } from "@gtkx/react";
+import { AdwApplicationWindow, AdwHeaderBar, AdwNavigationPage, AdwNavigationView, AdwToolbarView } from "@gtkx/jsx/adw";
+import { GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+const NavigationDemo = () => {
+    const [showSettings, setShowSettings] = useState(false);
+
+    return (
+        <AdwApplicationWindow
+            title="Navigation Demo"
+            defaultWidth={600}
+            defaultHeight={400}
+            onCloseRequest={() => {
+                quit();
+                return true;
+            }}
+        >
+            <AdwNavigationView
+                visiblePageTag={showSettings ? "settings" : "home"}
+                onPopped={() => setShowSettings(false)}
+            >
+                <AdwNavigationPage tag="home" title="Home">
+                    <AdwToolbarView addTopBar={<AdwHeaderBar />}>
+                        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER}>
+                            <GtkLabel label="Welcome!" cssClasses={["title-1"]} />
+                            <GtkButton label="Go to Settings" onClicked={() => setShowSettings(true)} cssClasses={["suggested-action"]} />
+                        </GtkBox>
+                    </AdwToolbarView>
+                </AdwNavigationPage>
+                {showSettings && (
+                    <AdwNavigationPage tag="settings" title="Settings">
+                        <AdwToolbarView addTopBar={<AdwHeaderBar />}>
+                            <GtkLabel label="Settings page content" vexpand />
+                        </AdwToolbarView>
+                    </AdwNavigationPage>
+                )}
+            </AdwNavigationView>
+        </AdwApplicationWindow>
+    );
+};
+```
+
+---
+
+## Sidebar/Content Split with AdwNavigationSplitView
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { quit } from "@gtkx/react";
+import { AdwActionRow, AdwApplicationWindow, AdwHeaderBar, AdwNavigationPage, AdwNavigationSplitView, AdwToolbarView } from "@gtkx/jsx/adw";
+import { GtkBox, GtkImage, GtkLabel, GtkListBox, GtkScrolledWindow } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+interface Item {
+    id: string;
+    title: string;
+    icon: string;
+}
+
+const items: Item[] = [
+    { id: "inbox", title: "Inbox", icon: "mail-unread-symbolic" },
+    { id: "starred", title: "Starred", icon: "starred-symbolic" },
+    { id: "sent", title: "Sent", icon: "mail-send-symbolic" },
+];
+
+const SplitViewDemo = () => {
+    const [selected, setSelected] = useState(items[0]);
+
+    return (
+        <AdwApplicationWindow
+            title="Split View Demo"
+            defaultWidth={800}
+            defaultHeight={500}
+            onCloseRequest={() => {
+                quit();
+                return true;
+            }}
+        >
+            <AdwNavigationSplitView
+                sidebarWidthFraction={0.33}
+                minSidebarWidth={200}
+                maxSidebarWidth={300}
+                sidebar={
+                    <AdwNavigationPage title="Mail">
+                        <AdwToolbarView addTopBar={<AdwHeaderBar />}>
+                            <GtkScrolledWindow vexpand>
+                                <GtkListBox
+                                    cssClasses={["navigation-sidebar"]}
+                                    onRowSelected={(row) => {
+                                        if (!row) return;
+                                        const item = items[row.getIndex()];
+                                        if (item) setSelected(item);
+                                    }}
+                                >
+                                    {items.map((item) => (
+                                        <AdwActionRow key={item.id} title={item.title} addPrefix={<GtkImage iconName={item.icon} />} />
+                                    ))}
+                                </GtkListBox>
+                            </GtkScrolledWindow>
+                        </AdwToolbarView>
+                    </AdwNavigationPage>
+                }
+                content={
+                    <AdwNavigationPage title={selected?.title ?? ""}>
+                        <AdwToolbarView addTopBar={<AdwHeaderBar />}>
+                            <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER} vexpand>
+                                <GtkImage iconName={selected?.icon ?? ""} iconSize={Gtk.IconSize.LARGE} />
+                                <GtkLabel label={selected?.title ?? ""} cssClasses={["title-2"]} />
+                            </GtkBox>
+                        </AdwToolbarView>
+                    </AdwNavigationPage>
+                }
+            />
+        </AdwApplicationWindow>
+    );
+};
+```
+
+---
+
+## File Browser with GtkListView (tree)
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkBox, GtkImage, GtkLabel, GtkListView, GtkScrolledWindow } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+interface FileNode {
+    id: string;
+    name: string;
+    isDirectory: boolean;
+    children?: FileNode[];
+}
+
+const files: FileNode[] = [
+    {
+        id: "src",
+        name: "src",
+        isDirectory: true,
+        children: [
+            { id: "src/app.tsx", name: "app.tsx", isDirectory: false },
+            { id: "src/index.tsx", name: "index.tsx", isDirectory: false },
+        ],
+    },
+    { id: "package.json", name: "package.json", isDirectory: false },
+];
+
+const FileBrowser = () => {
+    const [selected, setSelected] = useState<string | null>(null);
+
+    return (
+        <GtkScrolledWindow vexpand cssClasses={["card"]}>
+            <GtkListView
+                estimatedItemHeight={36}
+                vexpand
+                autoexpand={false}
+                selectionMode={Gtk.SelectionMode.SINGLE}
+                selected={selected ? [selected] : []}
+                onSelectionChanged={(ids) => setSelected(ids[0] ?? null)}
+                items={files.map((file) => ({
+                    id: file.id,
+                    value: file,
+                    children: file.children?.map((child) => ({ id: child.id, value: child })),
+                }))}
+                renderItem={(item: FileNode) => (
+                    <GtkBox spacing={8}>
+                        <GtkImage iconName={item.isDirectory ? "folder-symbolic" : "text-x-generic-symbolic"} />
+                        <GtkLabel label={item.name} halign={Gtk.Align.START} />
+                    </GtkBox>
+                )}
+            />
+        </GtkScrolledWindow>
+    );
+};
+```
+
+---
+
+## Stack with Programmatic Navigation
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkBox, GtkButton, GtkLabel, GtkStack, GtkStackPage } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+const StackNavigation = () => {
+    const [page, setPage] = useState("home");
+
+    return (
+        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
+            <GtkBox spacing={6} halign={Gtk.Align.CENTER}>
+                <GtkButton label="Home" onClicked={() => setPage("home")} />
+                <GtkButton label="Settings" onClicked={() => setPage("settings")} />
+            </GtkBox>
+            <GtkStack visibleChildName={page} onNotifyVisibleChildName={(name) => setPage(name ?? "home")} vexpand>
+                <GtkStackPage id="home">
+                    <GtkLabel label="Home Content" />
+                </GtkStackPage>
+                <GtkStackPage id="settings">
+                    <GtkLabel label="Settings Content" />
+                </GtkStackPage>
+            </GtkStack>
+        </GtkBox>
+    );
+};
+```
+
+---
+
+## Animated Card with Toggle
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { AdwSpringAnimation } from "@gtkx/animate";
+import { GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
+import { useState } from "react";
+
+const AnimatedCard = () => {
+    const [visible, setVisible] = useState(true);
+
+    return (
+        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} marginStart={16} marginEnd={16} marginTop={16} marginBottom={16}>
+            <GtkButton label={visible ? "Hide Card" : "Show Card"} onClicked={() => setVisible(!visible)} halign={Gtk.Align.START} />
+            {visible && (
+                <AdwSpringAnimation
+                    initial={{ opacity: 0, scale: 0.8, translateY: -20 }}
+                    animate={{ opacity: 1, scale: 1, translateY: 0 }}
+                    exit={{ opacity: 0, scale: 0.8, translateY: 20 }}
+                    damping={0.7}
+                    stiffness={200}
+                    animateOnMount
+                >
+                    <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={8} cssClasses={["card"]} marginStart={12} marginEnd={12} marginTop={8} marginBottom={8}>
+                        <GtkLabel label="Animated Card" cssClasses={["title-4"]} halign={Gtk.Align.START} />
+                        <GtkLabel label="This card animates in with a spring effect and fades out when dismissed." wrap />
+                    </GtkBox>
+                </AdwSpringAnimation>
+            )}
+        </GtkBox>
+    );
+};
+```