create-gtkx 0.21.0

package/templates/claude/WIDGETS.md.ejs

@@ -0,0 +1,934 @@
+# GTKX Widget Reference
+
+## Imports
+
+Every element-like component is imported from its namespace module: `@gtkx/jsx/gtk` for GTK widgets (`GtkBox`, `GtkListView`, `GtkColumnView`, `GtkDrawingArea`, …), `@gtkx/jsx/adw` for Adwaita (`AdwHeaderBar`, `AdwComboRow`, …), and `@gtkx/jsx/gio` for Gio elements (`GMenu`, `GSimpleAction`). `@gtkx/react` provides `render`, `quit`, hooks (`useApplication`, `useProperty`, `useSetting`, `useSignal`, `useTickCallback`, `useAdjustment`), and shared types such as `MenuEntry` and `ListItem`. `@gtkx/animate` provides the animation components. Enums and classes come from `@gtkx/gi/<ns>` (e.g. `import * as Gtk from "@gtkx/gi/gtk"`).
+
+## Common Props (All Widgets)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `hexpand` / `vexpand` | boolean | Expand to fill available space |
+| `halign` / `valign` | `Gtk.Align.START \| CENTER \| END \| FILL` | Alignment |
+| `marginStart/End/Top/Bottom` | number | Margins in pixels |
+| `sensitive` | boolean | Enabled/disabled state |
+| `visible` | boolean | Visibility |
+| `cssClasses` | string[] | CSS classes for styling |
+| `widthRequest` / `heightRequest` | number | Minimum size |
+
+---
+
+## Containers
+
+### GtkBox
+Linear layout (horizontal or vertical).
+
+```tsx
+<GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
+    {children}
+</GtkBox>
+```
+
+### GtkGrid
+2D grid with explicit positioning using `GtkGridChild`.
+
+```tsx
+<GtkGrid rowSpacing={8} columnSpacing={12}>
+    <GtkGridChild column={0} row={0}><GtkLabel label="Name:" /></GtkGridChild>
+    <GtkGridChild column={1} row={0}><GtkEntry hexpand /></GtkGridChild>
+    <GtkGridChild column={0} row={1} columnSpan={2}><GtkButton label="Submit" /></GtkGridChild>
+</GtkGrid>
+```
+
+**GtkGridChild props:** `column`, `row`, `columnSpan`, `rowSpan`
+
+### GtkStack
+Page container, shows one child at a time. Drive the visible page with `visibleChildName`, matching a page's `id`.
+
+```tsx
+<GtkStack visibleChildName="page1" transitionType={Gtk.StackTransitionType.SLIDE_LEFT_RIGHT}>
+    <GtkStackPage id="page1" title="First" iconName="document-new">
+        <Content1 />
+    </GtkStackPage>
+    <GtkStackPage id="page2" title="Second">
+        <Content2 />
+    </GtkStackPage>
+</GtkStack>
+```
+
+**GtkStackPage props:** `id` (matches the stack's `visibleChildName`), `title`, `iconName`, `needsAttention`, `badgeNumber` (AdwViewStack only). `AdwViewStack` pairs with `AdwViewStackPage` the same way.
+
+### GtkNotebook
+Tabbed container with visible tabs.
+
+```tsx
+<GtkNotebook>
+    <GtkNotebookPage label="Tab 1"><Content1 /></GtkNotebookPage>
+    <GtkNotebookPage label="Tab 2" tabExpand tabFill><Content2 /></GtkNotebookPage>
+</GtkNotebook>
+```
+
+Custom tab widget via the `tabLabel` prop:
+```tsx
+<GtkNotebookPage
+    tabLabel={
+        <GtkBox spacing={4}>
+            <GtkImage iconName="folder-symbolic" />
+            <GtkLabel label="Files" />
+        </GtkBox>
+    }
+>
+    <Content />
+</GtkNotebookPage>
+```
+
+**GtkNotebookPage props:** `label`, `tabLabel`, `tabExpand`, `tabFill`
+
+### GtkPaned
+Resizable split with draggable divider. Pass the two panes through the `startChild` and `endChild` props.
+
+```tsx
+<GtkPaned position={280} shrinkStartChild={false} startChild={<Sidebar />} endChild={<MainContent />} />
+```
+
+### GtkOverlay
+Stack widgets on top of each other. First child is base layer, additional children need a `GtkOverlayChild` wrapper. Multiple children supported per overlay.
+
+```tsx
+<GtkOverlay>
+    <GtkButton label="Notifications" />
+    <GtkOverlayChild>
+        <GtkLabel label="3" cssClasses={["badge"]} halign={Gtk.Align.END} valign={Gtk.Align.START} />
+    </GtkOverlayChild>
+</GtkOverlay>
+```
+
+### GtkFixed
+Absolute positioning with optional 3D transforms. Use a `GtkFixedChild` wrapper for children.
+
+```tsx
+<GtkFixed>
+    <GtkFixedChild x={20} y={30}>
+        <GtkLabel label="Top Left" />
+    </GtkFixedChild>
+    <GtkFixedChild x={200} y={100} transform={someGskTransform}>
+        <GtkLabel label="Transformed" />
+    </GtkFixedChild>
+</GtkFixed>
+```
+
+**GtkFixedChild props:** `x`, `y` (pixel coordinates), `transform` (optional `Gsk.Transform`)
+
+### GtkScrolledWindow
+Scrollable container.
+
+```tsx
+<GtkScrolledWindow vexpand hscrollbarPolicy={Gtk.PolicyType.NEVER}>
+    <Content />
+</GtkScrolledWindow>
+```
+
+---
+
+## Virtual Lists
+
+All virtual list widgets use an `items` data prop and a `renderItem` function. Items are `{ id: string, value: T }` objects.
+
+### GtkListView
+High-performance scrollable list with selection.
+
+```tsx
+<GtkListView
+    estimatedItemHeight={48}
+    vexpand
+    selected={selectedId ? [selectedId] : []}
+    selectionMode={Gtk.SelectionMode.SINGLE}
+    onSelectionChanged={(ids) => setSelectedId(ids[0])}
+    items={items.map(item => ({ id: item.id, value: item }))}
+    renderItem={(item: Item) => <GtkLabel label={item.name} />}
+/>
+```
+
+### GtkGridView
+Grid-based virtual scrolling.
+
+```tsx
+<GtkGridView
+    estimatedItemHeight={100}
+    minColumns={2}
+    maxColumns={4}
+    items={items.map(item => ({ id: item.id, value: item }))}
+    renderItem={(item: Item) => (
+        <GtkBox orientation={Gtk.Orientation.VERTICAL}>
+            <GtkImage iconName={item.icon} />
+            <GtkLabel label={item.name} />
+        </GtkBox>
+    )}
+/>
+```
+
+### GtkColumnView
+Table with sortable columns.
+
+```tsx
+<GtkColumnView
+    estimatedRowHeight={48}
+    sortColumn="name"
+    sortOrder={Gtk.SortType.ASCENDING}
+    onSortChanged={handleSort}
+    items={items.map(item => ({ id: item.id, value: item }))}
+>
+    <GtkColumnViewColumn
+        title="Name"
+        id="name"
+        expand
+        resizable
+        sortable
+        renderCell={(item: Item) => <GtkLabel label={item.name} />}
+    />
+    <GtkColumnViewColumn
+        title="Size"
+        id="size"
+        fixedWidth={100}
+        renderCell={(item: Item) => <GtkLabel label={`${item.size} KB`} />}
+    />
+</GtkColumnView>
+```
+
+### GtkDropDown
+Selection dropdown.
+
+```tsx
+<GtkDropDown
+    selectedId={selectedId}
+    onSelectionChanged={setSelectedId}
+    items={options.map(opt => ({ id: opt.id, value: opt.label }))}
+/>
+```
+
+### GtkListView (tree mode)
+Hierarchical tree with expand/collapse. Items with nested `children` arrays trigger tree behavior.
+
+```tsx
+<GtkListView
+    estimatedItemHeight={48}
+    vexpand
+    autoexpand={false}
+    selectionMode={Gtk.SelectionMode.SINGLE}
+    selected={selectedId ? [selectedId] : []}
+    onSelectionChanged={(ids) => setSelectedId(ids[0])}
+    items={files.map(file => ({
+        id: file.id,
+        value: file,
+        children: file.children?.map(child => ({ id: child.id, value: child })),
+    }))}
+    renderItem={(item: FileNode, row) => (
+        <GtkBox spacing={8}>
+            <GtkImage iconName={item.isDirectory ? "folder-symbolic" : "text-x-generic-symbolic"} />
+            <GtkLabel label={item.name} />
+        </GtkBox>
+    )}
+/>
+```
+
+**ListItem data props:** `id`, `value`, `children` (nested items for tree mode), `hideExpander`, `indentForDepth`, `indentForIcon`, `section` (for sectioned lists)
+
+---
+
+## Inputs
+
+### GtkEntry
+Single-line text input. **Requires two-way binding.**
+
+```tsx
+const [text, setText] = useState("");
+<GtkEntry text={text} onChanged={(e) => setText(e.getText())} placeholderText="Enter text..." />
+```
+
+### GtkToggleButton
+Toggle button. Auto-prevents signal feedback loops.
+
+```tsx
+<GtkToggleButton active={isActive} onToggled={() => setIsActive(!isActive)} label="Toggle" />
+```
+
+### GtkCheckButton
+Checkbox.
+
+```tsx
+<GtkCheckButton active={checked} onToggled={() => setChecked(!checked)} label="Option" />
+```
+
+### GtkSwitch
+On/off switch.
+
+```tsx
+<GtkSwitch active={enabled} onStateSet={() => { setEnabled(!enabled); return true; }} />
+```
+
+### GtkSpinButton
+Numeric input with increment/decrement. Build the `adjustment` with the `useAdjustment` hook from `@gtkx/react`.
+
+```tsx
+const adjustment = useAdjustment({ value: count, lower: 0, upper: 100, stepIncrement: 1 });
+
+<GtkSpinButton adjustment={adjustment} onValueChanged={(self) => setCount(self.getValue())} />
+```
+
+### GtkScale
+Slider with an adjustment and optional marks.
+
+```tsx
+const adjustment = useAdjustment({ value: volume, lower: 0, upper: 100, stepIncrement: 1 });
+
+<GtkScale
+    drawValue
+    valuePos={Gtk.PositionType.TOP}
+    adjustment={adjustment}
+    onValueChanged={(self) => setVolume(self.getValue())}
+    marks={[
+        { value: 0, label: "Min", position: Gtk.PositionType.BOTTOM },
+        { value: 50, position: Gtk.PositionType.BOTTOM },
+        { value: 100, label: "Max", position: Gtk.PositionType.BOTTOM },
+    ]}
+/>
+```
+
+**`useAdjustment` config:** `value`, `lower`, `upper`, `stepIncrement`, `pageIncrement`, `pageSize`
+**ScaleMark type:** `{ value: number, position?: Gtk.PositionType, label?: string }`
+
+### GtkCalendar
+Date picker with markable days.
+
+```tsx
+<GtkCalendar
+    onDaySelected={(cal) => setDate(cal.getDate())}
+    markedDays={[15, 20, 25]}
+/>
+```
+
+### GtkLevelBar
+Progress/level indicator with customizable thresholds.
+
+```tsx
+<GtkLevelBar
+    value={0.6}
+    offsets={[
+        { id: "low", value: 0.25 },
+        { id: "high", value: 0.75 },
+        { id: "full", value: 1.0 },
+    ]}
+/>
+```
+
+**LevelBarOffset type:** `{ id: string, value: number }`
+
+---
+
+## Display
+
+### GtkLabel
+```tsx
+<GtkLabel label="Text" halign={Gtk.Align.START} wrap useMarkup />
+```
+
+### GtkButton
+```tsx
+<GtkButton label="Click" onClicked={handleClick} iconName="document-new-symbolic" />
+```
+
+### GtkImage
+```tsx
+<GtkImage iconName="folder-symbolic" pixelSize={48} />
+```
+
+---
+
+## Header & Action Bars
+
+### GtkHeaderBar
+Title bar with packed widgets. Pass packed widgets through the `packStart`/`packEnd` props and the title through `titleWidget`.
+
+```tsx
+<GtkHeaderBar
+    packStart={<GtkButton iconName="go-previous-symbolic" />}
+    titleWidget={<GtkLabel label="Title" cssClasses={["title"]} />}
+    packEnd={<GtkMenuButton iconName="open-menu-symbolic" />}
+/>
+```
+
+### GtkActionBar
+Bottom action bar.
+
+```tsx
+<GtkActionBar
+    packStart={<GtkButton label="Cancel" />}
+    packEnd={<GtkButton label="Save" cssClasses={["suggested-action"]} />}
+/>
+```
+
+---
+
+## Menus
+
+Menus are data. `<GMenu>` (from `@gtkx/jsx/gio`) takes an `items` array of `MenuEntry` objects (`{ label?, action?, submenu?, section? }`, exported by `@gtkx/react`). Each leaf entry triggers a named action; declare the actions as `<GSimpleAction>` elements (also from `@gtkx/jsx/gio`) through the window's `addAction` prop (scope `win.`) or as children of the application (scope `app.`).
+
+### GtkMenuButton with a menu model
+
+```tsx
+<GtkMenuButton
+    iconName="open-menu-symbolic"
+    menuModel={
+        <GMenu
+            items={[
+                { label: "_New", action: "win.new" },
+                { label: "_Open", action: "win.open" },
+                {
+                    label: "Export",
+                    submenu: [
+                        { label: "PDF", action: "win.export-pdf" },
+                        { label: "CSV", action: "win.export-csv" },
+                    ],
+                },
+                { section: [{ label: "_Quit", action: "app.quit" }] },
+            ]}
+        />
+    }
+/>
+```
+
+### Declaring the actions
+
+```tsx
+<GtkApplicationWindow
+    addAction={
+        <>
+            <GSimpleAction name="new" onActivate={handleNew} accels="<Control>n" />
+            <GSimpleAction name="open" onActivate={handleOpen} accels="<Control>o" />
+            <GSimpleAction name="export-pdf" onActivate={exportPdf} />
+            <GSimpleAction name="export-csv" onActivate={exportCsv} />
+        </>
+    }
+>
+    {/* ... */}
+</GtkApplicationWindow>
+```
+
+**MenuEntry fields:** `label` (underscore marks the mnemonic), `action` (detailed action name, e.g. `"win.open"`), `submenu` (nested `MenuEntry[]`), `section` (inline group of `MenuEntry[]`, with `label` as the heading)
+
+**GSimpleAction props:** `name` (required), `onActivate`, `accels` (e.g., `"<Control>n"`), `enabled`
+
+---
+
+## Windows
+
+### GtkApplicationWindow
+
+Handle `onCloseRequest` and return `true` to veto GTK's native close so React state unmounts the window.
+
+```tsx
+<GtkApplicationWindow
+    title="App"
+    defaultWidth={800}
+    defaultHeight={600}
+    onCloseRequest={() => {
+        quit();
+        return true;
+    }}
+>
+    <Content />
+</GtkApplicationWindow>
+```
+
+Custom titlebar:
+```tsx
+<GtkApplicationWindow ... titlebar={<GtkHeaderBar />}>
+    <Content />
+</GtkApplicationWindow>
+```
+
+---
+
+## Adwaita (Libadwaita)
+
+Import: `import * as Adw from "@gtkx/gi/adw";`
+
+### AdwApplicationWindow + AdwToolbarView
+Modern app structure.
+
+```tsx
+<AdwApplicationWindow
+    title="App"
+    defaultWidth={800}
+    defaultHeight={600}
+    onCloseRequest={() => {
+        quit();
+        return true;
+    }}
+>
+    <AdwToolbarView
+        addTopBar={
+            <AdwHeaderBar titleWidget={<AdwWindowTitle title="App" subtitle="Description" />} />
+        }
+        addBottomBar={<GtkActionBar />}
+    >
+        <MainContent />
+    </AdwToolbarView>
+</AdwApplicationWindow>
+```
+
+### AdwStatusPage
+Welcome, error, or empty state.
+
+```tsx
+<AdwStatusPage iconName="applications-system-symbolic" title="Welcome" description="Get started" vexpand>
+    <GtkButton label="Start" cssClasses={["suggested-action", "pill"]} halign={Gtk.Align.CENTER} />
+</AdwStatusPage>
+```
+
+### AdwBanner
+Dismissable notification.
+
+```tsx
+<AdwBanner title="Update available" buttonLabel="Dismiss" revealed={show} onButtonClicked={() => setShow(false)} />
+```
+
+### AdwPreferencesPage / AdwPreferencesGroup
+Settings UI.
+
+```tsx
+<AdwPreferencesPage title="Settings">
+    <AdwPreferencesGroup title="Appearance" description="Customize look">
+        <AdwSwitchRow title="Dark Mode" active={dark} onNotifyActive={(active) => setDark(active ?? false)} />
+        <AdwActionRow
+            title="Theme"
+            subtitle="Select color"
+            addPrefix={<GtkImage iconName="preferences-color-symbolic" />}
+            addSuffix={<GtkImage iconName="go-next-symbolic" valign={Gtk.Align.CENTER} />}
+        />
+    </AdwPreferencesGroup>
+</AdwPreferencesPage>
+```
+
+**ActionRow children:** Use the `addPrefix` prop for left widgets, `addSuffix` for right widgets, or the `activatableWidget` prop for a clickable suffix.
+
+### AdwExpanderRow
+Expandable settings row with optional action widget.
+
+```tsx
+<AdwExpanderRow
+    title="Advanced"
+    subtitle="More options"
+    addAction={<GtkButton iconName="emblem-system-symbolic" cssClasses={["flat"]} />}
+    addRow={
+        <>
+            <AdwSwitchRow title="Option 1" active />
+            <AdwSwitchRow title="Option 2" />
+        </>
+    }
+/>
+```
+
+**ExpanderRow slots:** the `addRow` prop for nested rows, the `addAction` prop for the header action widget. Direct children also work for simple cases.
+
+### AdwEntryRow / AdwPasswordEntryRow
+Input in list row.
+
+```tsx
+<AdwEntryRow title="Username" text={username} onChanged={(e) => setUsername(e.getText())} />
+<AdwPasswordEntryRow title="Password" />
+```
+
+### AdwToggleGroup
+Segmented button group for mutually exclusive options, built from `AdwToggle` children.
+
+```tsx
+const [mode, setMode] = useState("list");
+
+<AdwToggleGroup activeName={mode} onNotifyActiveName={(name) => setMode(name ?? "list")}>
+    <AdwToggle name="list" iconName="view-list-symbolic" tooltip="List View" />
+    <AdwToggle name="grid" iconName="view-grid-symbolic" tooltip="Grid View" />
+    <AdwToggle name="flow" label="Flow" />
+</AdwToggleGroup>
+```
+
+**ToggleGroup props:** `activeName`, `active` (index), `onNotifyActiveName`
+
+**AdwToggle props:** `name`, `label`, `iconName`, `tooltip`, `enabled`
+
+### AdwNavigationView
+Push/pop navigation. Each `AdwNavigationPage` carries a `tag`; the view pushes a page when it mounts and pops it when it unmounts. Drive the active page with `visiblePageTag` and react to back navigation through `onPopped`.
+
+```tsx
+const [detail, setDetail] = useState(false);
+
+<AdwNavigationView visiblePageTag={detail ? "details" : "home"} onPopped={() => setDetail(false)}>
+    <AdwNavigationPage tag="home" title="Home">
+        <GtkButton label="Go to Details" onClicked={() => setDetail(true)} />
+    </AdwNavigationPage>
+    {detail && (
+        <AdwNavigationPage tag="details" title="Details">
+            <GtkLabel label="Details content" />
+        </AdwNavigationPage>
+    )}
+</AdwNavigationView>
+```
+
+**AdwNavigationPage props:** `tag`, `title`, `canPop`. The header bar inside a page shows a back button automatically when there is a page to pop.
+
+### AdwNavigationSplitView
+Sidebar/content split layout for master-detail interfaces. Each pane is an `AdwNavigationPage` passed through the `sidebar` and `content` slot props.
+
+```tsx
+const [selected, setSelected] = useState(items[0]);
+
+<AdwNavigationSplitView
+    sidebarWidthFraction={0.33}
+    minSidebarWidth={200}
+    maxSidebarWidth={300}
+    sidebar={
+        <AdwNavigationPage title="Sidebar">
+            <AdwToolbarView addTopBar={<AdwHeaderBar />}>
+                <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} />)}
+                </GtkListBox>
+            </AdwToolbarView>
+        </AdwNavigationPage>
+    }
+    content={
+        <AdwNavigationPage title={selected?.title ?? ""}>
+            <AdwToolbarView addTopBar={<AdwHeaderBar />}>
+                <GtkLabel label={selected?.title ?? ""} />
+            </AdwToolbarView>
+        </AdwNavigationPage>
+    }
+/>
+```
+
+**Props:** `sidebarWidthFraction`, `minSidebarWidth`, `maxSidebarWidth`, `collapsed`, `showContent`, `sidebar`, `content`.
+**Selection:** Use `GtkListBox` with `onRowSelected` (single click) not `onRowActivated` (double click).
+
+### AdwAlertDialog
+Modern modal alert dialogs with response buttons.
+
+```tsx
+const [showDialog, setShowDialog] = useState(false);
+
+{showDialog && (
+    <AdwAlertDialog
+        heading="Delete File?"
+        body="This action cannot be undone."
+        onResponse={(id) => {
+            if (id === "delete") handleDelete();
+            setShowDialog(false);
+        }}
+        responses={[
+            { id: "cancel", label: "Cancel" },
+            { id: "delete", label: "Delete", appearance: Adw.ResponseAppearance.DESTRUCTIVE },
+        ]}
+    />
+)}
+```
+
+**Response descriptor:** `{ id, label, appearance? (SUGGESTED, DESTRUCTIVE), enabled? }`
+
+### GtkColorDialogButton / GtkFontDialogButton
+Color and font picker buttons. The dialog is declared as a slot element (`GtkColorDialog`/`GtkFontDialog`, from `@gtkx/jsx/gtk`); observe the picked value through the `notify::` prop.
+
+```tsx
+<GtkColorDialogButton
+    rgba={color}
+    dialog={<GtkColorDialog title="Select Color" modal withAlpha />}
+    onNotifyRgba={(value) => value && setColor(value)}
+/>
+<GtkFontDialogButton
+    fontDesc={font}
+    useFont
+    useSize
+    dialog={<GtkFontDialog title="Select Font" modal />}
+    onNotifyFontDesc={(value) => value && setFont(value)}
+/>
+```
+
+### Other Adwaita Widgets
+
+| Widget | Description |
+|--------|-------------|
+| `AdwClamp` | Limits content width (`maximumSize={600}`) |
+| `AdwAvatar` | User avatar (`size={48} text="Name" showInitials`) |
+| `AdwSpinner` | Loading indicator |
+| `AdwWindowTitle` | Title + subtitle for header bars |
+| `AdwButtonRow` | Button styled as list row |
+
+---
+
+## Animations
+
+Wrap widgets in `AdwTimedAnimation` (duration + easing) or `AdwSpringAnimation`
+(physics: damping, stiffness, mass) for declarative animations.
+
+Spring animation:
+```tsx
+<AdwSpringAnimation
+    initial={{ opacity: 0, scale: 0.8 }}
+    animate={{ opacity: 1, scale: 1 }}
+    damping={0.8}
+    stiffness={200}
+    mass={1}
+    animateOnMount
+    onAnimationComplete={() => console.log("done")}
+>
+    <GtkBox>...</GtkBox>
+</AdwSpringAnimation>
+```
+
+Timed animation:
+```tsx
+<AdwTimedAnimation
+    initial={{ opacity: 0 }}
+    animate={{ opacity: 1 }}
+    duration={300}
+    easing={Adw.Easing.EASE_OUT_CUBIC}
+    animateOnMount
+>
+    <GtkLabel label="Fade in" />
+</AdwTimedAnimation>
+```
+
+**Shared props:** `initial`, `animate`, `exit`, `animateOnMount`, `onAnimationStart`, `onAnimationComplete`
+
+**AdwSpringAnimation props:** `damping`, `stiffness`, `mass`, `initialVelocity`, `clamp`
+
+**AdwTimedAnimation props:** `duration`, `easing` (from `Adw.Easing`), `repeat`, `reverse`, `alternate`
+
+---
+
+## Drag and Drop
+
+Drag and drop uses the `GtkDragSource` and `GtkDropTarget` event controllers, attached through a widget's `addController` prop. `GtkDragSource` provides content from `onPrepare` and takes its drag icon through the `icon` object prop; `GtkDropTarget` declares accepted `types` and handles `onDrop`.
+
+```tsx
+import * as Gdk from "@gtkx/gi/gdk";
+import { Type, Value } from "@gtkx/gi/gobject";
+import { GtkBox, GtkButton, GtkDragSource, GtkDropTarget, GtkLabel } from "@gtkx/jsx/gtk";
+
+const DraggableButton = ({ label }: { label: string }) => (
+    <GtkButton
+        label={label}
+        addController={
+            <GtkDragSource
+                actions={Gdk.DragAction.COPY}
+                onPrepare={() => Gdk.ContentProvider.newForValue(Value.newFromString(label))}
+                icon={{ paintable: someTexture, hotX: 16, hotY: 16 }}
+            />
+        }
+    />
+);
+
+const DropZone = () => {
+    const [dropped, setDropped] = useState<string | null>(null);
+    return (
+        <GtkBox
+            addController={
+                <GtkDropTarget
+                    types={[Type.STRING]}
+                    actions={Gdk.DragAction.COPY}
+                    onDrop={(value: Value) => { setDropped(value.getString()); return true; }}
+                />
+            }
+        >
+            <GtkLabel label={dropped ?? "Drop here"} />
+        </GtkBox>
+    );
+};
+```
+
+**GtkDragSource props:** `actions`, `content`, `onPrepare`, `onDragBegin`, `onDragEnd`, `onDragCancel`, `icon` (`{ paintable, hotX?, hotY? }`)
+
+**GtkDropTarget props:** `types`, `actions`, `preload`, `onAccept`, `onEnter`, `onMotion`, `onLeave`, `onDrop`
+
+## GValue Factories
+
+Create typed values for drag-and-drop and signal emission:
+
+| Factory                        | Description                   |
+| ------------------------------ | ----------------------------- |
+| `Value.newFromString(str)`     | String values                 |
+| `Value.newFromDouble(num)`     | 64-bit floating point         |
+| `Value.newFromInt(num)`        | 32-bit signed integer         |
+| `Value.newFromBoolean(bool)`   | Boolean values                |
+| `Value.newFromObject(obj)`     | GObject instances             |
+| `Value.newFromBoxed(boxed)`    | Boxed types (Gdk.RGBA, etc.)  |
+| `Value.newFromEnum(gtype, n)`  | Enum values (requires GType)  |
+| `Value.newFromFlags(gtype, n)` | Flags values (requires GType) |
+
+Type constants for `types`: `Type.STRING`, `Type.INT`, `Type.DOUBLE`, `Type.BOOLEAN`, `Type.OBJECT`.
+
+## Custom Drawing
+
+Render custom graphics with `GtkDrawingArea` (from `@gtkx/jsx/gtk`) using the `drawFunc` prop, with the GIR signature `(self, cr, width, height)`:
+
+```tsx
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { Context } from "@gtkx/gi/cairo";
+import { GtkDrawingArea } from "@gtkx/jsx/gtk";
+
+const Canvas = () => {
+    const handleDraw = (self: Gtk.DrawingArea, cr: Context, width: number, height: number) => {
+        cr.setSourceRgb(0.2, 0.4, 0.8);
+        cr.rectangle(10, 10, width - 20, height - 20);
+        cr.fill();
+    };
+
+    return <GtkDrawingArea contentWidth={400} contentHeight={300} drawFunc={handleDraw} />;
+};
+```
+
+Changing the `drawFunc` callback identity automatically queues a redraw. Attach a `GtkGestureDrag` through the `addController` prop for interactive drawing.
+
+## Event Controllers
+
+Event controllers attach through any widget's `addController` prop (wrap several in a fragment). They are auto-generated from GTK's introspection data.
+
+```tsx
+<GtkBox
+    focusable
+    addController={
+        <>
+            <GtkEventControllerMotion
+                onEnter={(x, y) => console.log("Entered at", x, y)}
+                onMotion={(x, y) => setPosition({ x, y })}
+                onLeave={() => console.log("Left")}
+            />
+            <GtkEventControllerKey
+                onKeyPressed={(keyval, keycode, state) => {
+                    console.log("Key pressed:", keyval);
+                    return false;
+                }}
+            />
+            <GtkGestureClick onPressed={(nPress, x, y) => console.log("Clicked")} />
+        </>
+    }
+>
+    <GtkLabel label="Hover or type here" />
+</GtkBox>
+```
+
+**Input controllers:** `GtkEventControllerMotion`, `GtkEventControllerKey`, `GtkEventControllerScroll`, `GtkEventControllerFocus`
+
+**Gesture controllers:** `GtkGestureClick`, `GtkGestureDrag`, `GtkGestureLongPress`, `GtkGestureZoom`, `GtkGestureRotate`, `GtkGestureSwipe`, `GtkGestureStylus`, `GtkGesturePan`
+
+**Drag-and-drop:** `GtkDragSource`, `GtkDropTarget`, `GtkDropControllerMotion`
+
+## SearchBar
+
+```tsx
+const [searchActive, setSearchActive] = useState(false);
+
+<GtkSearchBar searchModeEnabled={searchActive} onNotifySearchModeEnabled={(enabled) => setSearchActive(enabled ?? false)}>
+    <GtkSearchEntry text={query} onSearchChanged={(entry) => setQuery(entry.getText())} />
+</GtkSearchBar>
+```
+
+The `onNotifySearchModeEnabled` callback fires when search mode changes (e.g., user presses Escape).
+
+## TextView / SourceView
+
+Text content lives in an explicit `GtkTextBuffer` element passed through the view's `buffer` prop. Text nodes are allowed only inside `GtkLabel` and buffer elements. Use `GtkTextTag` for formatting and `GtkTextAnchor` for embedded widgets.
+
+```tsx
+<GtkTextView
+    wrapMode={Gtk.WrapMode.WORD}
+    buffer={
+        <GtkTextBuffer
+            enableUndo
+            onChanged={(buffer) => {
+                const text = buffer.getText(buffer.getStartIter(), buffer.getEndIter(), false);
+                console.log(text);
+            }}
+        >
+            Normal text, <GtkTextTag id="bold" weight={Pango.Weight.BOLD}>bold</GtkTextTag>, and
+            <GtkTextAnchor><GtkButton label="Click" /></GtkTextAnchor> inline.
+        </GtkTextBuffer>
+    }
+/>
+```
+
+**GtkTextBuffer props:** `enableUndo`, `onChanged`, `onInsertText`, `onDeleteRange`, `onNotifyCanUndo`, `onNotifyCanRedo`
+
+**GtkTextTag props:** `id` (required), `priority`, `foreground`, `background`, `weight`, `style`, `underline`, `strikethrough`, `family`, `size`, `sizePoints`, `scale`, `justification`, `leftMargin`, `rightMargin`, `indent`, `editable`, `invisible`
+
+**GtkTextAnchor:** Embeds widgets inline with `children`
+
+**GtkTextPaintable:** Embeds images inline with the `paintable` prop
+
+`GtkSourceView` (from `@gtkx/jsx/gtksource`) pairs with `GtkSourceBuffer` the same way; language and style scheme objects come from `@gtkx/gi/gtksource`:
+
+```tsx
+import * as GtkSource from "@gtkx/gi/gtksource";
+import { GtkSourceBuffer, GtkSourceView } from "@gtkx/jsx/gtksource";
+
+<GtkSourceView
+    showLineNumbers
+    highlightCurrentLine
+    monospace
+    buffer={
+        <GtkSourceBuffer
+            language={GtkSource.LanguageManager.getDefault().getLanguage("typescript-jsx")}
+            styleScheme={GtkSource.StyleSchemeManager.getDefault().getScheme("Adwaita-dark")}
+            onChanged={(buffer) => setCode(buffer.getText(buffer.getStartIter(), buffer.getEndIter(), false))}
+        >
+            {code}
+        </GtkSourceBuffer>
+    }
+/>
+```
+
+**GtkSourceBuffer additional props:** `language`, `styleScheme`, `highlightSyntax`, `highlightMatchingBrackets`, `implicitTrailingNewline`, `onCursorMoved`, `onHighlightUpdated`
+
+## Keyboard Shortcuts
+
+Pass `<GtkShortcut>` elements through a `<GtkShortcutController>`'s `addShortcut` prop, and attach the controller through the widget's `addController` prop. Each shortcut pairs a `trigger` (`Gtk.ShortcutTrigger.parseString`) with an `action` (`Gtk.CallbackAction.new`, returning `true` when handled):
+
+```tsx
+<GtkBox
+    orientation={Gtk.Orientation.VERTICAL}
+    spacing={12}
+    focusable
+    addController={
+        <GtkShortcutController
+            scope={Gtk.ShortcutScope.LOCAL}
+            addShortcut={
+                <>
+                    <GtkShortcut
+                        trigger={Gtk.ShortcutTrigger.parseString("<Control>equal")}
+                        action={Gtk.CallbackAction.new(() => {
+                            setCount((c) => c + 1);
+                            return true;
+                        })}
+                    />
+                    <GtkShortcut
+                        trigger={Gtk.ShortcutTrigger.parseString("<Control>minus")}
+                        action={Gtk.CallbackAction.new(() => {
+                            setCount((c) => c - 1);
+                            return true;
+                        })}
+                    />
+                </>
+            }
+        />
+    }
+>
+    <GtkLabel label={`Count: ${count}`} />
+</GtkBox>
+```
+
+**Scopes:** `LOCAL` (attached widget focus), `MANAGED` (parent managed), `GLOBAL` (window-wide)
+
+**Trigger strings for `parseString`:** `<Control>s`, `<Control><Shift>s`, `<Alt>F4`, `<Primary>q`, `F5`
+
+**Multiple triggers:** combine with `Gtk.AlternativeTrigger.new(triggerA, triggerB)`