@gtkx/react 0.19.0 → 0.21.0

package/src/jsx.ts

@@ -5,16 +5,8 @@ import type * as Gsk from "@gtkx/ffi/gsk";
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type * as GtkSource from "@gtkx/ffi/gtksource";
 import type * as Pango from "@gtkx/ffi/pango";
-import type { ReactElement, ReactNode } from "react";
-import { createElement } from "react";
-import type {
-    AdwComboRowProps as IntrinsicAdwComboRowProps,
-    GtkColumnViewProps as IntrinsicGtkColumnViewProps,
-    GtkDropDownProps as IntrinsicGtkDropDownProps,
-    GtkGridViewProps as IntrinsicGtkGridViewProps,
-    GtkListViewProps as IntrinsicGtkListViewProps,
-    WidgetSlotNames,
-} from "./generated/jsx.js";
+import type { ReactNode } from "react";
+import type { WidgetSlotNames } from "./generated/jsx.js";
 
 /**
  * CSS properties that can be animated on a widget.
@@ -42,14 +34,41 @@ export type AnimatableProperties = {
     skewY?: number;
 };
 
+/** @internal */
+type AnimationBaseProps = {
+    /** Initial property values before animation starts, or `false` to skip initial state */
+    initial?: AnimatableProperties | false;
+    /** Target property values to animate towards */
+    animate?: AnimatableProperties;
+    /** Property values to animate to when the component unmounts */
+    exit?: AnimatableProperties;
+    /** Whether to animate from `initial` to `animate` when first mounted (default: false) */
+    animateOnMount?: boolean;
+    /** Callback fired when an animation begins */
+    onAnimationStart?: () => void;
+    /** Callback fired when an animation completes */
+    onAnimationComplete?: () => void;
+    /** The child widget to animate (must be a single GTK widget) */
+    children?: ReactNode;
+};
+
 /**
- * Transition configuration for timed (duration-based) animations.
+ * Props for a timed (duration-based) animation using Adw.TimedAnimation.
  *
- * @see {@link https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.TimedAnimation.html Adw.TimedAnimation}
+ * @example
+ * ```tsx
+ * <AdwTimedAnimation
+ *   initial={{ opacity: 0 }}
+ *   animate={{ opacity: 1 }}
+ *   duration={300}
+ *   easing={Adw.Easing.EASE_OUT_CUBIC}
+ *   animateOnMount
+ * >
+ *   <GtkLabel label="Fade in" />
+ * </AdwTimedAnimation>
+ * ```
  */
-export type TimedTransition = {
-    /** Discriminant: duration-based animation with easing curves */
-    mode: "timed";
+export type AdwTimedAnimationProps = AnimationBaseProps & {
     /** Animation duration in milliseconds (default: 300) */
     duration?: number;
     /** Easing function for the animation curve (default: EASE_OUT_CUBIC) */
@@ -65,16 +84,22 @@ export type TimedTransition = {
 };
 
 /**
- * Transition configuration for spring (physics-based) animations.
- *
- * Spring animations simulate a mass attached to a spring, providing natural-feeling motion.
- * The animation settles when the spring reaches equilibrium.
+ * Props for a spring (physics-based) animation using Adw.SpringAnimation.
  *
- * @see {@link https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.SpringAnimation.html Adw.SpringAnimation}
+ * @example
+ * ```tsx
+ * <AdwSpringAnimation
+ *   initial={{ scale: 0.9, opacity: 0 }}
+ *   animate={{ scale: 1, opacity: 1 }}
+ *   damping={0.8}
+ *   stiffness={200}
+ *   animateOnMount
+ * >
+ *   <GtkButton label="Spring in" />
+ * </AdwSpringAnimation>
+ * ```
  */
-export type SpringTransition = {
-    /** Discriminant: physics-based spring animation */
-    mode: "spring";
+export type AdwSpringAnimationProps = AnimationBaseProps & {
     /** Damping ratio controlling oscillation decay (default: 1, critically damped) */
     damping?: number;
     /** Spring stiffness in N/m affecting animation speed (default: 100) */
@@ -90,51 +115,9 @@ export type SpringTransition = {
 };
 
 /**
- * Discriminated union of all transition configurations.
- *
- * The `mode` field determines the animation type:
- * - `"timed"`: Duration-based animation with easing curves (uses {@link Adw.TimedAnimation})
- * - `"spring"`: Physics-based spring animation (uses {@link Adw.SpringAnimation})
- */
-export type AnimationTransition = TimedTransition | SpringTransition;
-
-/**
- * Props for the Animation component.
- *
- * Provides a declarative API for animating widget properties using either
- * timed (duration-based) or spring (physics-based) animations.
- *
- * @example
- * ```tsx
- * <x.Animation
- *   initial={{ opacity: 0, translateY: -20 }}
- *   animate={{ opacity: 1, translateY: 0 }}
- *   exit={{ opacity: 0, translateY: 20 }}
- *   transition={{ mode: "spring", damping: 0.8, stiffness: 200 }}
- *   animateOnMount
- * >
- *   <GtkLabel label="Animated content" />
- * </x.Animation>
- * ```
+ * @internal Union type used by the AnimationNode internally.
  */
-export type AnimationProps = {
-    /** Initial property values before animation starts, or `false` to skip initial state */
-    initial?: AnimatableProperties | false;
-    /** Target property values to animate towards */
-    animate?: AnimatableProperties;
-    /** Property values to animate to when the component unmounts */
-    exit?: AnimatableProperties;
-    /** Transition configuration including animation mode and parameters */
-    transition?: AnimationTransition;
-    /** Whether to animate from `initial` to `animate` when first mounted (default: false) */
-    animateOnMount?: boolean;
-    /** Callback fired when an animation begins */
-    onAnimationStart?: () => void;
-    /** Callback fired when an animation completes */
-    onAnimationComplete?: () => void;
-    /** The child widget to animate (must be a single GTK widget) */
-    children?: ReactNode;
-};
+export type AnimationProps = AdwTimedAnimationProps | AdwSpringAnimationProps;
 
 /**
  * Props for the Shortcut virtual element.
@@ -341,7 +324,7 @@ export type LevelBarOffset = {
 /**
  * Props for slot-based child positioning.
  *
- * @see {@link Slot} for type-safe slot usage
+ * Used internally by compound components with slot props (e.g. `titleWidget` on `AdwHeaderBar`).
  */
 export type SlotProps = {
     /** The slot identifier */
@@ -350,22 +333,6 @@ export type SlotProps = {
     children?: ReactNode;
 };
 
-/**
- * Type mapping widgets to their valid container slot method names.
- *
- * Each key is a JSX element name and each value is a union of method names
- * that can be used as the `id` prop on `x.ContainerSlot`.
- */
-export type ContainerSlotNames = {
-    AdwActionRow: "addPrefix" | "addSuffix";
-    AdwEntryRow: "addPrefix" | "addSuffix";
-    AdwExpanderRow: "addPrefix" | "addSuffix" | "addRow" | "addAction";
-    AdwHeaderBar: "packStart" | "packEnd";
-    AdwToolbarView: "addTopBar" | "addBottomBar";
-    GtkActionBar: "packStart" | "packEnd";
-    GtkHeaderBar: "packStart" | "packEnd";
-};
-
 /**
  * Props for method-based container slot child positioning.
  */
@@ -377,50 +344,41 @@ export type ContainerSlotProps = {
 };
 
 /**
- * Props for items in a GtkListView, GtkGridView, or GtkColumnView.
+ * A data item for list/grid/column views and dropdowns.
  *
- * When used inside a GtkListView, items can be nested to create tree hierarchies.
- * Tree-specific props (`indentForDepth`, `indentForIcon`, `hideExpander`) only
- * apply when items are used inside a GtkListView with nested children.
+ * Uses a discriminated union on the `section` field:
+ * - Regular items have `value: T` and optional tree-mode properties
+ * - Section headers have `value: S`, `section: true`, and required `children`
  *
- * @typeParam T - The type of data associated with this list item
- */
-export type ListItemProps<T = unknown> = {
-    /** Unique identifier for this item */
-    id: string;
-    /** The data value for this item */
-    value: T;
-    /** Whether to indent based on tree depth (default: true) */
-    indentForDepth?: boolean;
-    /** Whether to indent for expander icon width */
-    indentForIcon?: boolean;
-    /** Whether to hide the expand/collapse arrow */
-    hideExpander?: boolean;
-    /** Nested list items (children of this item in a tree) */
-    children?: ReactNode;
-};
-
-/**
- * Props for section headers in a GtkListView, GtkGridView, or GtkColumnView.
+ * Mode is detected from data shape:
+ * - Any item has `section: true` → section mode
+ * - Any item has non-empty `children` (without `section`) → tree mode
+ * - Otherwise → flat mode
  *
- * Wraps ListItems to group them into sections. When used with `renderHeader`,
- * the view displays a header at the top of each section.
- *
- * @typeParam T - The type of data associated with this section header
+ * @typeParam T - The type of data for regular items
+ * @typeParam S - The type of data for section headers
  */
-export type ListSectionProps<T = unknown> = {
-    /** Unique identifier for this section */
-    id: string;
-    /** The data value passed to `renderHeader` for this section */
-    value: T;
-    /** ListItem children belonging to this section */
-    children?: ReactNode;
-};
+export type ListItem<T = unknown, S = unknown> =
+    | {
+          id: string;
+          value: T;
+          section?: false | undefined;
+          children?: ListItem<T, S>[];
+          hideExpander?: boolean;
+          indentForDepth?: boolean;
+          indentForIcon?: boolean;
+      }
+    | {
+          id: string;
+          value: S;
+          section: true;
+          children: ListItem<T, S>[];
+      };
 
 /**
  * Props for positioning children within a GtkGrid.
  *
- * @see {@link GridChild} for usage
+ * Used by `GtkGrid.Child` compound component.
  */
 export type GridChildProps = {
     /** Content to place in the grid cell */
@@ -438,7 +396,7 @@ export type GridChildProps = {
 /**
  * Props for positioning children within a GtkFixed.
  *
- * @see {@link FixedChild} for usage
+ * Used by `GtkFixed.Child` compound component.
  */
 export type FixedChildProps = {
     /** Content to place in the fixed container */
@@ -456,7 +414,7 @@ export type FixedChildProps = {
  *
  * @typeParam T - The type of data for each row
  *
- * @see {@link ColumnViewColumn} for usage
+ * Used by `GtkColumnView.Column` compound component.
  */
 export type ColumnViewColumnProps<T = unknown> = {
     /** Column header text */
@@ -474,7 +432,7 @@ export type ColumnViewColumnProps<T = unknown> = {
     /** Whether this column is visible */
     visible?: boolean;
     /** Function to render the cell content for each row */
-    renderCell: (item: T | null) => ReactNode;
+    renderCell: (item: T) => ReactNode;
     /** Menu items for the column header context menu */
     children?: ReactNode;
 };
@@ -504,7 +462,7 @@ export type NotebookPageTabProps = {
 /**
  * Props for pages within a Stack or ViewStack.
  *
- * @see {@link StackPage} for usage
+ * Used by `GtkStack.Page` and `AdwViewStack.Page` compound components.
  */
 export type StackPageProps = {
     /** Content to place in the stack page */
@@ -528,7 +486,7 @@ export type StackPageProps = {
 /**
  * Props for menu items.
  *
- * @see {@link Menu} for building menus
+ * Used by menu compound components like `GtkMenuButton.MenuItem`.
  */
 export type MenuItemProps = {
     /** Unique identifier for this menu item */
@@ -609,7 +567,7 @@ export type ToggleProps = {
  *
  * Each response represents a button the user can click to dismiss the dialog.
  *
- * @see {@link x.AlertDialogResponse} for usage
+ * Used by `AdwAlertDialog.Response` compound component.
  */
 export type AlertDialogResponseProps = {
     /** Unique response ID (used in response signal and for default/close response) */
@@ -622,7 +580,11 @@ export type AlertDialogResponseProps = {
     enabled?: boolean;
 };
 
-type NavigationPageBaseProps = {
+/**
+ * Base props shared by all navigation page declarations, regardless
+ * of the parent container (NavigationView or NavigationSplitView).
+ */
+export type NavigationPageBaseProps = {
     /** Display title for the navigation page */
     title?: string;
     /** Whether the page can be popped from the navigation stack */
@@ -631,6 +593,22 @@ type NavigationPageBaseProps = {
     children?: ReactNode;
 };
 
+/**
+ * Props for a navigation page inside an `AdwNavigationView`.
+ *
+ * The `id` serves as the page tag for navigation history.
+ */
+export type NavigationViewPageProps = NavigationPageBaseProps & { id: string };
+
+/**
+ * Props for a navigation page inside an `AdwNavigationSplitView`.
+ *
+ * The `id` is narrowed to the valid slot positions of the split view.
+ */
+export type NavigationSplitViewPageProps = NavigationPageBaseProps & {
+    id: WidgetSlotNames["AdwNavigationSplitView"];
+};
+
 /**
  * Props for the NavigationPage virtual element with type-safe targeting.
  *
@@ -685,9 +663,12 @@ export type TextBufferProps = {
     onCanRedoChanged?: ((canRedo: boolean) => void) | null;
 };
 
+/** @internal */
 type BaseListViewProps = {
     /** Estimated item height in pixels for virtualization */
     estimatedItemHeight?: number;
+    /** Estimated item width in pixels for virtualization */
+    estimatedItemWidth?: number;
     /** Array of selected item IDs */
     selected?: string[] | null;
     /** Callback fired when the selection changes */
@@ -696,34 +677,52 @@ type BaseListViewProps = {
     selectionMode?: Gtk.SelectionMode | null;
 };
 
+/**
+ * Props for the {@link GtkListView} compound component.
+ *
+ * Extends the shared list-view base props with item data, a render
+ * callback, optional tree expansion, and section header rendering.
+ */
 export type ListViewProps<T = unknown, S = unknown> = BaseListViewProps & {
+    /** Data items to display in the list */
+    items?: ListItem<T, S>[];
     /** Function to render each list item. The `row` parameter provides tree state for hierarchical lists. */
-    renderItem: (item: T | null, row?: Gtk.TreeListRow | null) => ReactNode;
+    renderItem: (item: T, row?: Gtk.TreeListRow | null) => ReactNode;
     /** Whether to automatically expand new tree rows (default: false) */
     autoexpand?: boolean;
-    /** Function to render section headers when using ListSection children */
-    renderHeader?: ((item: S | null) => ReactNode) | null;
+    /** Function to render section headers when items contain section entries */
+    renderHeader?: ((item: S) => ReactNode) | null;
 };
 
+/**
+ * Props for the {@link GtkGridView} compound component.
+ *
+ * Extends the shared list-view base props with item data and a
+ * render callback for each grid cell.
+ */
 export type GridViewProps<T = unknown> = BaseListViewProps & {
+    /** Data items to display in the grid */
+    items?: ListItem<T>[];
     /** Function to render each grid item */
-    renderItem: (item: T | null) => ReactNode;
+    renderItem: (item: T) => ReactNode;
 };
 
 /**
  * Props shared by single-selection dropdown widgets (GtkDropDown, AdwComboRow).
  */
 export type DropDownProps<T = unknown, S = unknown> = {
+    /** Data items to display in the dropdown */
+    items?: ListItem<T, S>[];
     /** ID of the currently selected item */
     selectedId?: string | null;
     /** Callback fired when the selected item changes */
     onSelectionChanged?: ((id: string) => void) | null;
     /** Function to render each item. Sets the primary factory, used for both button and popup list unless overridden by renderListItem. */
-    renderItem?: ((item: T | null) => ReactNode) | null;
+    renderItem?: ((item: T) => ReactNode) | null;
     /** Function to render items in the popup list only, overriding renderItem for the list. */
-    renderListItem?: ((item: T | null) => ReactNode) | null;
-    /** Function to render section headers when using ListSection children */
-    renderHeader?: ((item: S | null) => ReactNode) | null;
+    renderListItem?: ((item: T) => ReactNode) | null;
+    /** Function to render section headers when items contain section entries */
+    renderHeader?: ((item: S) => ReactNode) | null;
 };
 
 /**
@@ -759,413 +758,6 @@ export type AdjustableProps = {
     onValueChanged?: ((value: number, self: Gtk.Range | Gtk.ScaleButton | Gtk.SpinButton | Adw.SpinRow) => void) | null;
 };
 
-/**
- * GTKX-specific intrinsic elements and components.
- *
- * This namespace provides React components for GTK layout, lists, menus, and slots
- * that are specific to GTKX (not direct GTK widget bindings).
- *
- * @example
- * ```tsx
- * import { x, GtkHeaderBar, GtkDropDown } from "@gtkx/react";
- *
- * <GtkHeaderBar>
- *   <x.Slot for={GtkHeaderBar} id="titleWidget">
- *     <GtkLabel label="App Title" />
- *   </x.Slot>
- * </GtkHeaderBar>
- *
- * <GtkDropDown>
- *   <x.ListItem id="opt1" value="Option 1" />
- *   <x.ListItem id="opt2" value="Option 2" />
- * </GtkDropDown>
- * ```
- */
-export const x = {
-    /**
-     * Type-safe slot component for placing children in named widget slots.
-     *
-     * GTK widgets often have named slots for specific child positions (e.g., titleWidget,
-     * startWidget). This component provides type-safe access to those slots.
-     *
-     * @example
-     * ```tsx
-     * <GtkHeaderBar>
-     *   <x.Slot for={GtkHeaderBar} id="titleWidget">
-     *     <GtkLabel label="App Title" />
-     *   </x.Slot>
-     * </GtkHeaderBar>
-     * ```
-     */
-    Slot<W extends keyof WidgetSlotNames>(props: {
-        for: W;
-        id: WidgetSlotNames[W];
-        children?: ReactNode;
-    }): ReactElement {
-        return createElement("Slot", { id: props.id }, props.children);
-    },
-
-    /**
-     * Element type for pages within a GtkStack or AdwViewStack.
-     *
-     * @example
-     * ```tsx
-     * <GtkStack page="page1">
-     *   <x.StackPage id="page1" title="First Page">
-     *     <GtkLabel label="Content 1" />
-     *   </x.StackPage>
-     * </GtkStack>
-     * ```
-     */
-    StackPage: "StackPage" as const,
-
-    /**
-     * Element type for positioning children within a GtkGrid.
-     *
-     * @example
-     * ```tsx
-     * <GtkGrid>
-     *   <x.GridChild column={0} row={0}>
-     *     <GtkLabel label="Top Left" />
-     *   </x.GridChild>
-     * </GtkGrid>
-     * ```
-     */
-    GridChild: "GridChild" as const,
-
-    /**
-     * Element type for positioning children within a GtkFixed.
-     *
-     * @example
-     * ```tsx
-     * <GtkFixed>
-     *   <x.FixedChild x={20} y={30}>
-     *     <GtkLabel label="Positioned at (20, 30)" />
-     *   </x.FixedChild>
-     * </GtkFixed>
-     * ```
-     */
-    FixedChild: "FixedChild" as const,
-
-    /**
-     * Element type for a page within a GtkNotebook (tabbed interface).
-     *
-     * @example
-     * ```tsx
-     * <GtkNotebook>
-     *   <x.NotebookPage label="Tab 1">
-     *     <GtkLabel label="Content 1" />
-     *   </x.NotebookPage>
-     * </GtkNotebook>
-     * ```
-     */
-    NotebookPage: "NotebookPage" as const,
-
-    /**
-     * Element type for a custom widget as the page tab label.
-     */
-    NotebookPageTab: "NotebookPageTab" as const,
-
-    /**
-     * Element type for items in a GtkListView, GtkGridView, or GtkColumnView.
-     *
-     * Items can be nested to create tree hierarchies inside a GtkListView.
-     *
-     * @example
-     * ```tsx
-     * // Flat list
-     * <GtkListView renderItem={(item) => <GtkLabel label={item.name} />}>
-     *   <x.ListItem id="1" value={{ name: "Item 1" }} />
-     * </GtkListView>
-     *
-     * // Tree list (nested items)
-     * <GtkListView renderItem={(item, row) => <GtkLabel label={item.name} />} autoexpand>
-     *   <x.ListItem id="parent" value={{ name: "Parent" }}>
-     *     <x.ListItem id="child" value={{ name: "Child" }} />
-     *   </x.ListItem>
-     * </GtkListView>
-     * ```
-     */
-    ListItem<T = unknown>(props: ListItemProps<T>): ReactElement {
-        return createElement("ListItem", props, props.children);
-    },
-
-    /**
-     * Component for defining section headers in list/grid views.
-     *
-     * Wraps ListItems to group them into sections with headers.
-     * Requires `renderHeader` on the parent view to render the header content.
-     *
-     * @example
-     * ```tsx
-     * <GtkGridView
-     *   renderItem={(item) => <GtkLabel label={item.name} />}
-     *   renderHeader={(header) => <GtkLabel label={header.title} />}
-     * >
-     *   <x.ListSection id="section1" value={{ title: "Section 1" }}>
-     *     <x.ListItem id="a" value={{ name: "Item A" }} />
-     *     <x.ListItem id="b" value={{ name: "Item B" }} />
-     *   </x.ListSection>
-     * </GtkGridView>
-     * ```
-     */
-    ListSection<T = unknown>(props: ListSectionProps<T>): ReactElement {
-        return createElement("ListSection", props, props.children);
-    },
-
-    /**
-     * Component for defining columns in a ColumnView (table widget).
-     *
-     * @example
-     * ```tsx
-     * <GtkColumnView>
-     *   <x.ColumnViewColumn
-     *     id="name"
-     *     title="Name"
-     *     expand
-     *     renderCell={(item) => <GtkLabel label={item?.name ?? ""} />}
-     *   />
-     * </GtkColumnView>
-     * ```
-     */
-    ColumnViewColumn<T = unknown>(props: ColumnViewColumnProps<T>): ReactElement {
-        return createElement("ColumnViewColumn", props, props.children);
-    },
-
-    /**
-     * Type-safe container slot for placing children via parent widget methods.
-     *
-     * Unlike `x.Slot` (which uses property setters for single-child slots),
-     * `x.ContainerSlot` calls attachment methods that support multiple children
-     * (e.g., `addPrefix()`, `packStart()`, `addTopBar()`).
-     *
-     * The `for` prop provides TypeScript type narrowing for the `id` prop
-     * and is not used at runtime.
-     *
-     * @example
-     * ```tsx
-     * <AdwToolbarView>
-     *   <x.ContainerSlot for={AdwToolbarView} id="addTopBar">
-     *     <AdwHeaderBar />
-     *   </x.ContainerSlot>
-     * </AdwToolbarView>
-     *
-     * <GtkHeaderBar>
-     *   <x.ContainerSlot for={GtkHeaderBar} id="packStart">
-     *     <GtkButton label="Back" />
-     *   </x.ContainerSlot>
-     * </GtkHeaderBar>
-     *
-     * <AdwActionRow title="Setting">
-     *   <x.ContainerSlot for={AdwActionRow} id="addPrefix">
-     *     <GtkCheckButton />
-     *   </x.ContainerSlot>
-     * </AdwActionRow>
-     * ```
-     */
-    ContainerSlot<W extends keyof ContainerSlotNames>(props: {
-        for: W;
-        id: ContainerSlotNames[W];
-        children?: ReactNode;
-    }): ReactElement {
-        return createElement("ContainerSlot", { id: props.id }, props.children);
-    },
-
-    /**
-     * Element type for overlay children positioned above the main content.
-     *
-     * @example
-     * ```tsx
-     * <GtkOverlay>
-     *   <GtkImage file="background.png" />
-     *   <x.OverlayChild>
-     *     <GtkLabel label="Overlaid text" />
-     *   </x.OverlayChild>
-     * </GtkOverlay>
-     * ```
-     */
-    OverlayChild: "OverlayChild" as const,
-
-    /**
-     * A clickable menu item with action.
-     *
-     * @example
-     * ```tsx
-     * <GtkMenuButton>
-     *   <x.MenuItem id="open" label="Open" onActivate={handleOpen} />
-     * </GtkMenuButton>
-     * ```
-     */
-    MenuItem: "MenuItem" as const,
-
-    /**
-     * A section grouping related menu items.
-     *
-     * @example
-     * ```tsx
-     * <GtkMenuButton>
-     *   <x.MenuSection label="File">
-     *     <x.MenuItem id="open" label="Open" onActivate={handleOpen} />
-     *   </x.MenuSection>
-     * </GtkMenuButton>
-     * ```
-     */
-    MenuSection: "MenuSection" as const,
-
-    /**
-     * A submenu containing nested items.
-     *
-     * @example
-     * ```tsx
-     * <GtkMenuButton>
-     *   <x.MenuSubmenu label="Export">
-     *     <x.MenuItem id="pdf" label="As PDF" onActivate={exportPdf} />
-     *   </x.MenuSubmenu>
-     * </GtkMenuButton>
-     * ```
-     */
-    MenuSubmenu: "MenuSubmenu" as const,
-
-    /**
-     * Declarative text tag for styling text content.
-     *
-     * Wrap text content with a TextTag to apply styling. Tags can be nested.
-     *
-     * @example
-     * ```tsx
-     * <GtkTextView>
-     *     Normal <x.TextTag id="bold" weight={Pango.Weight.BOLD}>
-     *       bold <x.TextTag id="red" foreground="red">and red</x.TextTag>
-     *     </x.TextTag> text.
-     * </GtkTextView>
-     * ```
-     */
-    TextTag: "TextTag" as const,
-
-    /**
-     * Declarative anchor for embedding widgets in text flow.
-     *
-     * The anchor is placed at the current position in the text.
-     *
-     * @example
-     * ```tsx
-     * <GtkTextView>
-     *     Click here: <x.TextAnchor>
-     *       <GtkButton label="Click me" />
-     *     </x.TextAnchor> to continue.
-     * </GtkTextView>
-     * ```
-     */
-    TextAnchor: "TextAnchor" as const,
-
-    /**
-     * Declarative inline paintable for embedding images/icons in text flow.
-     *
-     * The paintable is placed at the current position in the text.
-     *
-     * @example
-     * ```tsx
-     * <GtkTextView>
-     *     Click the icon <x.TextPaintable paintable={iconPaintable} /> to continue.
-     * </GtkTextView>
-     * ```
-     */
-    TextPaintable: "TextPaintable" as const,
-
-    /**
-     * A toggle button for an AdwToggleGroup.
-     *
-     * @example
-     * ```tsx
-     * <AdwToggleGroup>
-     *   <x.Toggle id="list" iconName="view-list-symbolic" />
-     *   <x.Toggle id="grid" iconName="view-grid-symbolic" />
-     * </AdwToggleGroup>
-     * ```
-     */
-    Toggle: "Toggle" as const,
-
-    /**
-     * A response button for an AdwAlertDialog.
-     *
-     * @example
-     * ```tsx
-     * <AdwAlertDialog
-     *   heading="Delete File?"
-     *   body="This cannot be undone."
-     *   defaultResponse="cancel"
-     *   closeResponse="cancel"
-     * >
-     *   <x.AlertDialogResponse id="cancel" label="Cancel" />
-     *   <x.AlertDialogResponse id="delete" label="Delete" appearance={Adw.ResponseAppearance.DESTRUCTIVE} />
-     * </AdwAlertDialog>
-     * ```
-     */
-    AlertDialogResponse: "AlertDialogResponse" as const,
-
-    /**
-     * Type-safe page component for AdwNavigationView or AdwNavigationSplitView.
-     *
-     * The `for` prop is required and determines valid `id` values:
-     * - `AdwNavigationView`: any string (page tags for navigation history)
-     * - `AdwNavigationSplitView`: `"content"` or `"sidebar"` (slot positions)
-     *
-     * @example
-     * ```tsx
-     * // In NavigationView - id can be any string
-     * <AdwNavigationView history={["home"]}>
-     *   <x.NavigationPage for={AdwNavigationView} id="home" title="Home">
-     *     <GtkLabel label="Welcome!" />
-     *   </x.NavigationPage>
-     * </AdwNavigationView>
-     *
-     * // In NavigationSplitView - id is narrowed to "content" | "sidebar"
-     * <AdwNavigationSplitView>
-     *   <x.NavigationPage for={AdwNavigationSplitView} id="sidebar" title="Sidebar">
-     *     <GtkLabel label="Sidebar" />
-     *   </x.NavigationPage>
-     *   <x.NavigationPage for={AdwNavigationSplitView} id="content" title="Content">
-     *     <GtkLabel label="Content" />
-     *   </x.NavigationPage>
-     * </AdwNavigationSplitView>
-     * ```
-     */
-    NavigationPage: "NavigationPage" as const,
-
-    /**
-     * A keyboard shortcut definition.
-     *
-     * Must be a child of `<GtkShortcutController>`.
-     *
-     * @example
-     * ```tsx
-     * <x.Shortcut trigger="<Control>s" onActivate={save} />
-     * <x.Shortcut trigger={["F5", "<Control>r"]} onActivate={refresh} />
-     * <x.Shortcut trigger="Escape" onActivate={cancel} disabled={!canCancel} />
-     * ```
-     */
-    Shortcut: "Shortcut" as const,
-
-    /**
-     * Declarative animation wrapper using Adw.TimedAnimation or Adw.SpringAnimation.
-     *
-     * Provides framer-motion-inspired API for animating child widgets.
-     *
-     * @example
-     * ```tsx
-     * <x.Animation
-     *   initial={{ opacity: 0, scale: 0.9 }}
-     *   animate={{ opacity: 1, scale: 1 }}
-     *   transition={{ mode: "spring", damping: 0.8, stiffness: 200 }}
-     *   animateOnMount
-     * >
-     *   <GtkButton label="Animated Button" />
-     * </x.Animation>
-     * ```
-     */
-    Animation: "Animation" as const,
-};
-
 interface StackProps {
     /** ID of the currently visible page */
     page?: string | null;
@@ -1175,14 +767,13 @@ declare global {
     namespace React {
         namespace JSX {
             interface IntrinsicElements {
-                AlertDialogResponse: AlertDialogResponseProps;
-                Animation: AnimationProps;
+                Slot: SlotProps;
+                AdwTimedAnimation: AdwTimedAnimationProps;
+                AdwSpringAnimation: AdwSpringAnimationProps;
                 ContainerSlot: ContainerSlotProps;
                 ColumnViewColumn: ColumnViewColumnProps;
                 FixedChild: FixedChildProps;
                 GridChild: GridChildProps;
-                ListItem: ListItemProps;
-                ListSection: ListSectionProps;
                 MenuItem: MenuItemProps;
                 MenuSection: MenuSectionProps;
                 MenuSubmenu: MenuSubmenuProps;
@@ -1194,7 +785,6 @@ declare global {
                 TextTag: TextTagProps;
 
                 StackPage: StackPageProps;
-                Toggle: ToggleProps;
                 NavigationPage: NavigationPageProps;
                 Shortcut: ShortcutProps;
             }
@@ -1202,6 +792,13 @@ declare global {
     }
 }
 
+/**
+ * Accessibility attribute props mixed into every widget.
+ *
+ * Maps to the GTK `GtkAccessible` interface properties, states,
+ * and relations, allowing assistive technologies to query widget
+ * semantics.
+ */
 export type AccessibleProps = {
     accessibleAutocomplete?: Gtk.AccessibleAutocomplete;
     accessibleDescription?: string;
@@ -1282,6 +879,11 @@ declare module "./generated/jsx.js" {
         onValueChanged?: ((value: number, self: Adw.SpinRow) => void) | null;
     }
 
+    interface AdwSwitchRowProps {
+        /** Callback fired when the switch row active state changes */
+        onActiveChanged?: ((active: boolean, self: Adw.SwitchRow) => void) | null;
+    }
+
     interface GtkCalendarProps {
         /** Array of day numbers (1-31) to display as marked */
         markedDays?: number[] | null;
@@ -1316,6 +918,8 @@ declare module "./generated/jsx.js" {
     interface GtkGridViewProps extends GridViewProps {}
 
     interface GtkColumnViewProps {
+        /** Data items to display in the column view */
+        items?: ListItem[];
         /** Array of selected row IDs */
         selected?: string[] | null;
         /** Callback fired when the selection changes */
@@ -1330,7 +934,7 @@ declare module "./generated/jsx.js" {
         onSortChanged?: ((column: string | null, order: Gtk.SortType) => void) | null;
         /** Estimated row height in pixels for virtualization */
         estimatedRowHeight?: number | null;
-        /** Function to render section headers when using ListSection children */
+        /** Function to render section headers when items contain section entries */
         renderHeader?: ((item: unknown) => ReactNode) | null;
     }
 
@@ -1361,8 +965,8 @@ declare module "./generated/jsx.js" {
     }
 
     interface GtkDrawingAreaProps {
-        /** Callback fired when the drawing area needs to be redrawn */
-        onDraw?: ((cr: cairo.Context, width: number, height: number, self: Gtk.DrawingArea) => void) | null;
+        /** Render function called when the drawing area needs to be redrawn. Changing this reference automatically queues a redraw. */
+        render?: ((cr: cairo.Context, width: number, height: number, self: Gtk.DrawingArea) => void) | null;
     }
 
     interface GtkColorDialogButtonProps extends DialogButtonProps {
@@ -1394,6 +998,13 @@ declare module "./generated/jsx.js" {
     interface AdwToggleGroupProps {
         /** Callback fired when the active toggle changes */
         onActiveChanged?: ((active: number, activeName: string | null) => void) | null;
+        /** Declarative toggle definitions for the group */
+        toggles?: ToggleProps[];
+    }
+
+    interface AdwAlertDialogProps {
+        /** Declarative response button definitions for the dialog */
+        responses?: AlertDialogResponseProps[];
     }
 
     interface GtkDragSourceProps {
@@ -1411,37 +1022,12 @@ declare module "./generated/jsx.js" {
     }
 }
 
-export function GtkListView<T = unknown, S = unknown>(
-    props: Omit<IntrinsicGtkListViewProps, keyof ListViewProps> & ListViewProps<T, S> & { children?: ReactNode },
-): ReactElement {
-    return createElement("GtkListView", props);
-}
-
-export function GtkGridView<T = unknown>(
-    props: Omit<IntrinsicGtkGridViewProps, keyof GridViewProps> & GridViewProps<T> & { children?: ReactNode },
-): ReactElement {
-    return createElement("GtkGridView", props);
-}
+export { AdwComboRow, GtkColumnView, GtkDropDown, GtkGridView, GtkListView } from "./components/list.js";
+export * from "./generated/compounds.js";
 
-export function GtkDropDown<T = unknown, S = unknown>(
-    props: Omit<IntrinsicGtkDropDownProps, keyof DropDownProps> & DropDownProps<T, S> & { children?: ReactNode },
-): ReactElement {
-    return createElement("GtkDropDown", props);
-}
-
-export function AdwComboRow<T = unknown, S = unknown>(
-    props: Omit<IntrinsicAdwComboRowProps, keyof DropDownProps> & DropDownProps<T, S> & { children?: ReactNode },
-): ReactElement {
-    return createElement("AdwComboRow", props);
-}
-
-export function GtkColumnView<T = unknown>(
-    props: Omit<IntrinsicGtkColumnViewProps, "renderHeader"> & {
-        renderHeader?: ((item: T | null) => ReactNode) | null;
-        children?: ReactNode;
-    },
-): ReactElement {
-    return createElement("GtkColumnView", props);
-}
+/** JSX intrinsic element name for timed (duration-based) Adwaita animations. */
+export const AdwTimedAnimation = "AdwTimedAnimation" as const;
+/** JSX intrinsic element name for spring-physics-based Adwaita animations. */
+export const AdwSpringAnimation = "AdwSpringAnimation" as const;
 
 export * from "./generated/jsx.js";