@gtkx/react 0.15.0 → 0.17.1

package/README.md

@@ -71,6 +71,7 @@ render(<App />, "com.example.counter");
 - **React 19** — Hooks, concurrent features, and the component model you know
 - **Native GTK4 widgets** — Real native controls, not web components in a webview
 - **Adwaita support** — Modern GNOME styling with Libadwaita components
+- **Declarative animations** — Framer Motion-like API using native Adwaita animations
 - **Hot Module Replacement** — Fast refresh during development
 - **TypeScript first** — Full type safety with auto-generated bindings
 - **CSS-in-JS styling** — Familiar styling patterns adapted for GTK

package/dist/animation/css-builder.d.ts

@@ -0,0 +1,3 @@
+import type { AnimatableProperties } from "./types.js";
+export declare const interpolate: (from: AnimatableProperties, to: AnimatableProperties, progress: number) => AnimatableProperties;
+export declare const buildCss: (className: string, props: AnimatableProperties) => string;

package/dist/animation/css-builder.js

@@ -0,0 +1,53 @@
+const getDefaultValue = (property) => {
+    switch (property) {
+        case "opacity":
+        case "scale":
+        case "scaleX":
+        case "scaleY":
+            return 1;
+        default:
+            return 0;
+    }
+};
+export const interpolate = (from, to, progress) => {
+    const result = {};
+    const allKeys = new Set([...Object.keys(from), ...Object.keys(to)]);
+    for (const key of allKeys) {
+        const fromVal = from[key] ?? getDefaultValue(key);
+        const toVal = to[key] ?? getDefaultValue(key);
+        result[key] = fromVal + (toVal - fromVal) * progress;
+    }
+    return result;
+};
+export const buildCss = (className, props) => {
+    const parts = [];
+    const transforms = [];
+    if (props.opacity !== undefined) {
+        parts.push(`opacity: ${props.opacity}`);
+    }
+    if (props.translateX !== undefined || props.translateY !== undefined) {
+        transforms.push(`translate(${props.translateX ?? 0}px, ${props.translateY ?? 0}px)`);
+    }
+    if (props.scale !== undefined) {
+        transforms.push(`scale(${props.scale})`);
+    }
+    else if (props.scaleX !== undefined || props.scaleY !== undefined) {
+        transforms.push(`scale(${props.scaleX ?? 1}, ${props.scaleY ?? 1})`);
+    }
+    if (props.rotate !== undefined) {
+        transforms.push(`rotate(${props.rotate}deg)`);
+    }
+    if (props.skewX !== undefined) {
+        transforms.push(`skewX(${props.skewX}deg)`);
+    }
+    if (props.skewY !== undefined) {
+        transforms.push(`skewY(${props.skewY}deg)`);
+    }
+    if (transforms.length > 0) {
+        parts.push(`transform: ${transforms.join(" ")}`);
+    }
+    if (parts.length === 0) {
+        return "";
+    }
+    return `.${className} { ${parts.join("; ")}; }`;
+};

package/dist/animation/types.d.ts

@@ -0,0 +1,120 @@
+import type { Easing } from "@gtkx/ffi/adw";
+import type { ReactNode } from "react";
+/**
+ * The type of animation to use.
+ *
+ * - `"timed"`: Duration-based animation with easing curves (uses {@link Adw.TimedAnimation})
+ * - `"spring"`: Physics-based spring animation (uses {@link Adw.SpringAnimation})
+ */
+export type AnimationMode = "timed" | "spring";
+/**
+ * A numeric value that can be animated.
+ */
+export type AnimatableValue = number;
+/**
+ * CSS properties that can be animated on a widget.
+ *
+ * All transforms are applied via GTK CSS and rendered through the widget's style context.
+ */
+export type AnimatableProperties = {
+    /** Opacity from 0 (fully transparent) to 1 (fully opaque) */
+    opacity?: AnimatableValue;
+    /** Horizontal translation in pixels (positive moves right) */
+    translateX?: AnimatableValue;
+    /** Vertical translation in pixels (positive moves down) */
+    translateY?: AnimatableValue;
+    /** Uniform scale factor (1 = original size, 2 = double size) */
+    scale?: AnimatableValue;
+    /** Horizontal scale factor */
+    scaleX?: AnimatableValue;
+    /** Vertical scale factor */
+    scaleY?: AnimatableValue;
+    /** Rotation angle in degrees (positive rotates clockwise) */
+    rotate?: AnimatableValue;
+    /** Horizontal skew angle in degrees */
+    skewX?: AnimatableValue;
+    /** Vertical skew angle in degrees */
+    skewY?: AnimatableValue;
+};
+/**
+ * Transition configuration for timed (duration-based) animations.
+ *
+ * @see {@link https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.TimedAnimation.html Adw.TimedAnimation}
+ */
+export type TimedTransition = {
+    /** Animation duration in milliseconds (default: 300) */
+    duration?: number;
+    /** Easing function for the animation curve (default: EASE_OUT_CUBIC) */
+    easing?: Easing;
+    /** Delay before starting the animation in milliseconds */
+    delay?: number;
+    /** Number of times to repeat the animation (0 = no repeat, -1 = infinite) */
+    repeat?: number;
+    /** Whether to play the animation in reverse */
+    reverse?: boolean;
+    /** Whether to alternate direction on each repeat */
+    alternate?: boolean;
+};
+/**
+ * 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.
+ *
+ * @see {@link https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.SpringAnimation.html Adw.SpringAnimation}
+ */
+export type SpringTransition = {
+    /** Damping ratio controlling oscillation decay (default: 1, critically damped) */
+    damping?: number;
+    /** Spring stiffness in N/m affecting animation speed (default: 100) */
+    stiffness?: number;
+    /** Virtual mass in kg affecting momentum (default: 1) */
+    mass?: number;
+    /** Initial velocity to apply at animation start */
+    initialVelocity?: number;
+    /** Whether to clamp the animation value to prevent overshooting */
+    clamp?: boolean;
+    /** Delay before starting the animation in milliseconds */
+    delay?: number;
+};
+/**
+ * Props for the Animation component.
+ *
+ * Provides a declarative API for animating widget properties using either
+ * timed (duration-based) or spring (physics-based) animations.
+ *
+ * @typeParam M - The animation mode, either `"timed"` or `"spring"`
+ *
+ * @example
+ * ```tsx
+ * <x.Animation
+ *   mode="spring"
+ *   initial={{ opacity: 0, translateY: -20 }}
+ *   animate={{ opacity: 1, translateY: 0 }}
+ *   exit={{ opacity: 0, translateY: 20 }}
+ *   animateOnMount
+ * >
+ *   <GtkLabel label="Animated content" />
+ * </x.Animation>
+ * ```
+ */
+export type AnimationProps<M extends AnimationMode = AnimationMode> = {
+    /** Animation type: `"timed"` for duration-based or `"spring"` for physics-based */
+    mode: M;
+    /** 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 (type depends on mode) */
+    transition?: M extends "timed" ? TimedTransition : SpringTransition;
+    /** 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;
+};

package/dist/errors.js

@@ -25,6 +25,9 @@ export function formatRenderError(error, widgetType) {
     if (error instanceof GtkxError) {
         return error;
     }
+    if (error instanceof Error) {
+        console.error("[formatRenderError] Original error stack:", error.stack);
+    }
     const message = error instanceof Error ? error.message : String(error);
     const formattedMessage = widgetType ? `Failed to render ${widgetType}: ${message}` : `Render error: ${message}`;
     return new GtkxError(formattedMessage, widgetType);

package/dist/factory.d.ts

@@ -1,4 +1,5 @@
 import type { Node } from "./node.js";
-import type { Container, Props } from "./types.js";
+import type { Container, ContainerClass, Props } from "./types.js";
 import "./nodes/index.js";
-export declare const createNode: (typeName: string, props: Props, existingContainer?: Container, rootContainer?: Container) => Node;
+export declare const resolveContainerClass: (type: string) => ContainerClass | null;
+export declare const createNode: (typeName: string, props: Props, existingContainer: Container | undefined, rootContainer: Container) => Node;

package/dist/factory.js

@@ -1,7 +1,7 @@
 import { NAMESPACE_REGISTRY } from "./generated/registry.js";
 import { NODE_CLASSES } from "./registry.js";
 import "./nodes/index.js";
-const resolveContainerClass = (type) => {
+export const resolveContainerClass = (type) => {
     for (const [prefix, namespace] of NAMESPACE_REGISTRY) {
         if (type.startsWith(prefix)) {
             const className = type.slice(prefix.length);

package/dist/fiber-root.js

@@ -1,5 +1,5 @@
 import { reconciler } from "./reconciler.js";
 export const createFiberRoot = (container) => {
     const instance = reconciler.getInstance();
-    return instance.createContainer(container, 1, null, false, null, "", (error) => console.error("Fiber root render error:", error), () => { }, () => { }, () => { }, null);
+    return instance.createContainer(container, 1, null, false, null, "", (error) => console.error("Fiber root render error:", error), () => { }, () => { }, () => { });
 };

package/dist/generated/internal.d.ts

@@ -23,8 +23,35 @@ export declare const POPOVER_MENU_CLASSES: readonly [typeof Gtk.MenuButton, type
 export declare const PACK_INTERFACE_METHODS: string[];
 /** Methods that define the prefix/suffix interface (Adwaita action rows). */
 export declare const PREFIX_SUFFIX_INTERFACE_METHODS: string[];
+/** Methods that define the adjustable interface (widgets with GtkAdjustment). */
+export declare const ADJUSTABLE_INTERFACE_METHODS: string[];
 /** Constructor parameters for each widget type, derived from GIR analysis. */
 export declare const CONSTRUCTOR_PROPS: Record<string, string[]>;
 export declare const PROPS: Record<string, Record<string, [string | null, string]>>;
-/** Signal names for each widget type, derived from CodegenWidgetMeta. */
+/** Signal names for widgets and controllers, derived from CodegenMeta. */
 export declare const SIGNALS: Record<string, Set<string>>;
+/** Map from JSX element name to controller class. */
+export declare const CONTROLLER_CLASSES: {
+    GtkDragSource: typeof Gtk.DragSource;
+    GtkDropControllerMotion: typeof Gtk.DropControllerMotion;
+    GtkDropTarget: typeof Gtk.DropTarget;
+    GtkDropTargetAsync: typeof Gtk.DropTargetAsync;
+    GtkEventControllerFocus: typeof Gtk.EventControllerFocus;
+    GtkEventControllerKey: typeof Gtk.EventControllerKey;
+    GtkEventControllerLegacy: typeof Gtk.EventControllerLegacy;
+    GtkEventControllerMotion: typeof Gtk.EventControllerMotion;
+    GtkEventControllerScroll: typeof Gtk.EventControllerScroll;
+    GtkGestureClick: typeof Gtk.GestureClick;
+    GtkGestureDrag: typeof Gtk.GestureDrag;
+    GtkGestureLongPress: typeof Gtk.GestureLongPress;
+    GtkGesturePan: typeof Gtk.GesturePan;
+    GtkGestureRotate: typeof Gtk.GestureRotate;
+    GtkGestureSingle: typeof Gtk.GestureSingle;
+    GtkGestureStylus: typeof Gtk.GestureStylus;
+    GtkGestureSwipe: typeof Gtk.GestureSwipe;
+    GtkGestureZoom: typeof Gtk.GestureZoom;
+    GtkPadController: typeof Gtk.PadController;
+    GtkShortcutController: typeof Gtk.ShortcutController;
+};
+/** Constructor props for controllers that require them. */
+export declare const CONTROLLER_CONSTRUCTOR_PROPS: Record<string, string[]>;

package/dist/generated/internal.js

@@ -23,6 +23,8 @@ export const POPOVER_MENU_CLASSES = [Gtk.MenuButton, Gtk.PopoverMenu, Gtk.Popove
 export const PACK_INTERFACE_METHODS = ["packStart", "packEnd", "remove"];
 /** Methods that define the prefix/suffix interface (Adwaita action rows). */
 export const PREFIX_SUFFIX_INTERFACE_METHODS = ["addPrefix", "addSuffix", "remove"];
+/** Methods that define the adjustable interface (widgets with GtkAdjustment). */
+export const ADJUSTABLE_INTERFACE_METHODS = ["getAdjustment", "setAdjustment", "getValue"];
 /** Constructor parameters for each widget type, derived from GIR analysis. */
 export const CONSTRUCTOR_PROPS = {
     AdwAlertDialog: ["heading", "body"],
@@ -399,7 +401,6 @@ export const PROPS = {
     GtkColumnView: {
         enableRubberband: ["getEnableRubberband", "setEnableRubberband"],
         headerFactory: ["getHeaderFactory", "setHeaderFactory"],
-        model: ["getModel", "setModel"],
         reorderable: ["getReorderable", "setReorderable"],
         rowFactory: ["getRowFactory", "setRowFactory"],
         showColumnSeparators: ["getShowColumnSeparators", "setShowColumnSeparators"],
@@ -429,7 +430,6 @@ export const PROPS = {
         factory: ["getFactory", "setFactory"],
         headerFactory: ["getHeaderFactory", "setHeaderFactory"],
         listFactory: ["getListFactory", "setListFactory"],
-        model: ["getModel", "setModel"],
         searchMatchMode: ["getSearchMatchMode", "setSearchMatchMode"],
         selected: ["getSelected", "setSelected"],
         useSubtitle: ["getUseSubtitle", "setUseSubtitle"],
@@ -464,7 +464,6 @@ export const PROPS = {
         factory: ["getFactory", "setFactory"],
         headerFactory: ["getHeaderFactory", "setHeaderFactory"],
         listFactory: ["getListFactory", "setListFactory"],
-        model: ["getModel", "setModel"],
         searchMatchMode: ["getSearchMatchMode", "setSearchMatchMode"],
         selected: ["getSelected", "setSelected"],
         showArrow: ["getShowArrow", "setShowArrow"],
@@ -653,7 +652,6 @@ export const PROPS = {
     },
     GtkGraphicsOffload: {
         blackBackground: ["getBlackBackground", "setBlackBackground"],
-        child: ["getChild", "setChild"],
         enabled: ["getEnabled", "setEnabled"],
     },
     GtkGrid: {
@@ -666,10 +664,8 @@ export const PROPS = {
     },
     GtkGridView: {
         enableRubberband: ["getEnableRubberband", "setEnableRubberband"],
-        factory: ["getFactory", "setFactory"],
         maxColumns: ["getMaxColumns", "setMaxColumns"],
         minColumns: ["getMinColumns", "setMinColumns"],
-        model: ["getModel", "setModel"],
         singleClickActivate: ["getSingleClickActivate", "setSingleClickActivate"],
         tabBehavior: ["getTabBehavior", "setTabBehavior"],
     },
@@ -831,9 +827,7 @@ export const PROPS = {
     },
     GtkListView: {
         enableRubberband: ["getEnableRubberband", "setEnableRubberband"],
-        factory: ["getFactory", "setFactory"],
         headerFactory: ["getHeaderFactory", "setHeaderFactory"],
-        model: ["getModel", "setModel"],
         showSeparators: ["getShowSeparators", "setShowSeparators"],
         singleClickActivate: ["getSingleClickActivate", "setSingleClickActivate"],
         tabBehavior: ["getTabBehavior", "setTabBehavior"],
@@ -888,7 +882,6 @@ export const PROPS = {
     },
     AdwNavigationPage: {
         canPop: ["getCanPop", "setCanPop"],
-        child: ["getChild", "setChild"],
         tag: ["getTag", "setTag"],
         title: ["getTitle", "setTitle"],
     },
@@ -1035,7 +1028,6 @@ export const PROPS = {
         orientation: ["getOrientation", "setOrientation"],
     },
     GtkRange: {
-        adjustment: ["getAdjustment", "setAdjustment"],
         fillLevel: ["getFillLevel", "setFillLevel"],
         inverted: ["getInverted", "setInverted"],
         restrictToFillLevel: ["getRestrictToFillLevel", "setRestrictToFillLevel"],
@@ -1056,7 +1048,6 @@ export const PROPS = {
         valuePos: ["getValuePos", "setValuePos"],
     },
     GtkScaleButton: {
-        adjustment: ["getAdjustment", "setAdjustment"],
         hasFrame: ["getHasFrame", "setHasFrame"],
         icons: [null, "setIcons"],
         value: ["getValue", "setValue"],
@@ -1144,7 +1135,6 @@ export const PROPS = {
     },
     GtkSpinButton: {
         activatesDefault: ["getActivatesDefault", "setActivatesDefault"],
-        adjustment: ["getAdjustment", "setAdjustment"],
         climbRate: ["getClimbRate", "setClimbRate"],
         digits: ["getDigits", "setDigits"],
         numeric: ["getNumeric", "setNumeric"],
@@ -1210,8 +1200,6 @@ export const PROPS = {
         transitionDuration: ["getTransitionDuration", "setTransitionDuration"],
         transitionType: ["getTransitionType", "setTransitionType"],
         vhomogeneous: ["getVhomogeneous", "setVhomogeneous"],
-        visibleChild: ["getVisibleChild", "setVisibleChild"],
-        visibleChildName: ["getVisibleChildName", "setVisibleChildName"],
     },
     GtkStackSidebar: {
         stack: ["getStack", "setStack"],
@@ -1349,7 +1337,6 @@ export const PROPS = {
     GtkTextView: {
         acceptsTab: ["getAcceptsTab", "setAcceptsTab"],
         bottomMargin: ["getBottomMargin", "setBottomMargin"],
-        buffer: ["getBuffer", "setBuffer"],
         cursorVisible: ["getCursorVisible", "setCursorVisible"],
         editable: ["getEditable", "setEditable"],
         extraMenu: ["getExtraMenu", "setExtraMenu"],
@@ -1463,8 +1450,6 @@ export const PROPS = {
         hhomogeneous: ["getHhomogeneous", "setHhomogeneous"],
         transitionDuration: ["getTransitionDuration", "setTransitionDuration"],
         vhomogeneous: ["getVhomogeneous", "setVhomogeneous"],
-        visibleChild: ["getVisibleChild", "setVisibleChild"],
-        visibleChildName: ["getVisibleChildName", "setVisibleChildName"],
     },
     AdwViewSwitcher: {
         policy: ["getPolicy", "setPolicy"],
@@ -1520,8 +1505,46 @@ export const PROPS = {
         wrapReverse: ["getWrapReverse", "setWrapReverse"],
         orientation: ["getOrientation", "setOrientation"],
     },
+    GtkDragSource: {
+        actions: ["getActions", "setActions"],
+        content: ["getContent", "setContent"],
+    },
+    GtkDropTarget: {
+        actions: ["getActions", "setActions"],
+        preload: ["getPreload", "setPreload"],
+    },
+    GtkDropTargetAsync: {
+        actions: ["getActions", "setActions"],
+        formats: ["getFormats", "setFormats"],
+    },
+    GtkEventController: {
+        name: ["getName", "setName"],
+        propagationLimit: ["getPropagationLimit", "setPropagationLimit"],
+        propagationPhase: ["getPropagationPhase", "setPropagationPhase"],
+    },
+    GtkEventControllerScroll: {
+        flags: ["getFlags", "setFlags"],
+    },
+    GtkGestureLongPress: {
+        delayFactor: ["getDelayFactor", "setDelayFactor"],
+    },
+    GtkGesturePan: {
+        orientation: ["getOrientation", "setOrientation"],
+    },
+    GtkGestureSingle: {
+        button: ["getButton", "setButton"],
+        exclusive: ["getExclusive", "setExclusive"],
+        touchOnly: ["getTouchOnly", "setTouchOnly"],
+    },
+    GtkGestureStylus: {
+        stylusOnly: ["getStylusOnly", "setStylusOnly"],
+    },
+    GtkShortcutController: {
+        mnemonicModifiers: ["getMnemonicsModifiers", "setMnemonicsModifiers"],
+        scope: ["getScope", "setScope"],
+    },
 };
-/** Signal names for each widget type, derived from CodegenWidgetMeta. */
+/** Signal names for widgets and controllers, derived from CodegenMeta. */
 export const SIGNALS = {
     GtkWidget: new Set([
         "destroy",
@@ -1537,6 +1560,7 @@ export const SIGNALS = {
         "state-flags-changed",
         "unmap",
         "unrealize",
+        "notify",
     ]),
     GtkWindow: new Set(["activate-default", "activate-focus", "close-request", "enable-debugging", "keys-changed"]),
     AdwAboutDialog: new Set(["activate-link"]),
@@ -1842,4 +1866,55 @@ export const SIGNALS = {
         "user-message-received",
         "web-process-terminated",
     ]),
+    GtkDragSource: new Set(["drag-begin", "drag-cancel", "drag-end", "prepare"]),
+    GtkDropControllerMotion: new Set(["enter", "leave", "motion"]),
+    GtkDropTarget: new Set(["accept", "drop", "enter", "leave", "motion"]),
+    GtkDropTargetAsync: new Set(["accept", "drag-enter", "drag-leave", "drag-motion", "drop"]),
+    GtkEventController: new Set(["notify"]),
+    GtkEventControllerFocus: new Set(["enter", "leave"]),
+    GtkEventControllerKey: new Set(["im-update", "key-pressed", "key-released", "modifiers"]),
+    GtkEventControllerLegacy: new Set(["event"]),
+    GtkEventControllerMotion: new Set(["enter", "leave", "motion"]),
+    GtkEventControllerScroll: new Set(["decelerate", "scroll", "scroll-begin", "scroll-end"]),
+    GtkGesture: new Set(["begin", "cancel", "end", "sequence-state-changed", "update"]),
+    GtkGestureClick: new Set(["pressed", "released", "stopped", "unpaired-release"]),
+    GtkGestureDrag: new Set(["drag-begin", "drag-end", "drag-update"]),
+    GtkGestureLongPress: new Set(["cancelled", "pressed"]),
+    GtkGesturePan: new Set(["pan"]),
+    GtkGestureRotate: new Set(["angle-changed"]),
+    GtkGestureStylus: new Set(["down", "motion", "proximity", "up"]),
+    GtkGestureSwipe: new Set(["swipe"]),
+    GtkGestureZoom: new Set(["scale-changed"]),
+    GtkShortcutController: new Set(["items-changed"]),
+};
+/** Map from JSX element name to controller class. */
+export const CONTROLLER_CLASSES = {
+    GtkDragSource: Gtk.DragSource,
+    GtkDropControllerMotion: Gtk.DropControllerMotion,
+    GtkDropTarget: Gtk.DropTarget,
+    GtkDropTargetAsync: Gtk.DropTargetAsync,
+    GtkEventControllerFocus: Gtk.EventControllerFocus,
+    GtkEventControllerKey: Gtk.EventControllerKey,
+    GtkEventControllerLegacy: Gtk.EventControllerLegacy,
+    GtkEventControllerMotion: Gtk.EventControllerMotion,
+    GtkEventControllerScroll: Gtk.EventControllerScroll,
+    GtkGestureClick: Gtk.GestureClick,
+    GtkGestureDrag: Gtk.GestureDrag,
+    GtkGestureLongPress: Gtk.GestureLongPress,
+    GtkGesturePan: Gtk.GesturePan,
+    GtkGestureRotate: Gtk.GestureRotate,
+    GtkGestureSingle: Gtk.GestureSingle,
+    GtkGestureStylus: Gtk.GestureStylus,
+    GtkGestureSwipe: Gtk.GestureSwipe,
+    GtkGestureZoom: Gtk.GestureZoom,
+    GtkPadController: Gtk.PadController,
+    GtkShortcutController: Gtk.ShortcutController,
+};
+/** Constructor props for controllers that require them. */
+export const CONTROLLER_CONSTRUCTOR_PROPS = {
+    GtkDropTarget: ["actions"],
+    GtkDropTargetAsync: ["actions", "formats"],
+    GtkEventControllerScroll: ["flags"],
+    GtkGesturePan: ["orientation"],
+    GtkPadController: ["pad"],
 };