@gtkx/animated 1.2.2

package/src/apply-animated-values.ts

@@ -0,0 +1,116 @@
+import type { Lookup } from "@react-spring/types";
+import * as Gtk from "@gtkx/gi/gtk";
+import { applyStyle, applyWrite } from "@gtkx/react/internal";
+import { coerceObjectProperty } from "@gtkx/runtime";
+
+const setterCache: WeakMap<object, Map<string, boolean>> = new WeakMap();
+
+const hasSetterInChain = (prototype: object | null, name: string): boolean => {
+    for (let current = prototype; current !== null; current = Object.getPrototypeOf(current) as object | null) {
+        const descriptor = Object.getOwnPropertyDescriptor(current, name);
+
+        if (descriptor !== undefined) {
+            return descriptor.set !== undefined;
+        }
+    }
+
+    return false;
+};
+
+const hasSetter = (instance: object, name: string): boolean => {
+    const prototype = Object.getPrototypeOf(instance) as object | null;
+
+    if (prototype === null) {
+        return false;
+    }
+
+    let known = setterCache.get(prototype);
+
+    if (known === undefined) {
+        known = new Map();
+        setterCache.set(prototype, known);
+    }
+
+    let isWritable = known.get(name);
+
+    if (isWritable === undefined) {
+        isWritable = hasSetterInChain(prototype, name);
+        known.set(name, isWritable);
+    }
+
+    return isWritable;
+};
+
+const isText = (value: unknown): value is string | number => typeof value === "string" || typeof value === "number";
+
+const getText = (value: unknown): string | null => {
+    if (isText(value)) {
+        return String(value);
+    }
+
+    if (!Array.isArray(value)) {
+        return null;
+    }
+
+    const texts = value.map((item) => getText(item));
+
+    return texts.every((item) => item !== null) ? texts.join("") : null;
+};
+
+const didApplyText = (instance: object, value: unknown): boolean => {
+    const text = getText(value);
+
+    if (text === null || !(instance instanceof Gtk.Label)) {
+        return false;
+    }
+
+    applyWrite(() => {
+        instance.setLabel(text);
+    });
+
+    return true;
+};
+
+const didApplyStyle = (instance: object, value: unknown): boolean => {
+    if (!(instance instanceof Gtk.Widget)) {
+        return false;
+    }
+
+    applyStyle(instance, value);
+
+    return true;
+};
+
+const didApplyValue = (instance: object, name: string, value: unknown): boolean => {
+    if (name === "children") {
+        return didApplyText(instance, value);
+    }
+
+    if (name === "style") {
+        return didApplyStyle(instance, value);
+    }
+
+    if (!hasSetter(instance, name)) {
+        return false;
+    }
+
+    applyWrite(() => {
+        Reflect.set(instance, name, coerceObjectProperty(instance, name, value));
+    });
+
+    return true;
+};
+
+const didApplyAnimatedValues = (instance: object, values: Lookup): boolean => {
+    let isApplied = true;
+
+    for (const name in values) {
+        if (!didApplyValue(instance, name, values[name])) {
+            isApplied = false;
+        }
+    }
+
+    return isApplied;
+};
+
+export { didApplyAnimatedValues };

package/src/bootstrap.ts

@@ -0,0 +1,12 @@
+import { Globals } from "@react-spring/core";
+import { colors, createStringInterpolator } from "@react-spring/shared";
+import { trackReducedMotion } from "./reduced-motion.js";
+import { requestFrame } from "./request-frame.js";
+
+Globals.assign({
+    colors,
+    createStringInterpolator,
+    requestAnimationFrame: requestFrame,
+});
+
+trackReducedMotion();

package/src/index.ts

@@ -0,0 +1,110 @@
+import "./bootstrap.js";
+
+export { animated, type Animated } from "./animated.js";
+export { useReducedMotion } from "./reduced-motion.js";
+export type {
+    AnimatedComponent,
+    AnimatedElements,
+    AnimatedItems,
+    AnimatedProp,
+    AnimatedProps,
+    AnimatedStyle,
+} from "./types.js";
+export {
+    BailSignal,
+    config,
+    Controller,
+    createInterpolator,
+    easings,
+    FrameValue,
+    Globals,
+    inferTo,
+    Interpolation,
+    Spring,
+    SpringContext,
+    SpringRef,
+    SpringValue,
+    to,
+    Trail,
+    Transition,
+    update,
+    useChain,
+    useSpring,
+    useSpringRef,
+    useSprings,
+    useSpringValue,
+    useTrail,
+    useTransition,
+} from "@react-spring/core";
+export type {
+    AnimationConfig,
+    AnimationProps,
+    AnimationResult,
+    AsyncResult,
+    Change,
+    ControllerFlushFn,
+    ControllerProps,
+    ControllerUpdate,
+    EventProp,
+    ForwardProps,
+    GoalProp,
+    GoalValue,
+    GoalValues,
+    InferTo,
+    InlineToProps,
+    Interpolated,
+    Interpolator,
+    ItemKeys,
+    LoopProp,
+    MatchProp,
+    OnChange,
+    OnPause,
+    OnProps,
+    OnResolve,
+    OnRest,
+    OnResume,
+    OnStart,
+    PickAnimated,
+    ReservedEventProps,
+    ReservedProps,
+    SpringChain,
+    SpringComponentProps,
+    SpringConfig,
+    SpringProps,
+    SpringsUpdate,
+    SpringTo,
+    SpringToFn,
+    SpringUpdate,
+    SpringUpdateFn,
+    SpringValues,
+    Springify,
+    ToProps,
+    ToValues,
+    TrailComponentProps,
+    TransitionComponentProps,
+    TransitionFn,
+    TransitionFrom,
+    TransitionKey,
+    TransitionRenderFn,
+    TransitionState,
+    TransitionTo,
+    TransitionValues,
+    UseSpringProps,
+    UseSpringsProps,
+    UseTrailProps,
+    UseTransitionProps,
+    VelocityProp,
+} from "@react-spring/core";
+export type { FluidValue } from "@react-spring/shared";
+export type {
+    Animatable,
+    EasingFunction,
+    ExtrapolateType,
+    InterpolatorArgs,
+    InterpolatorConfig,
+    InterpolatorFactory,
+    InterpolatorFn,
+    Lookup,
+    OneOrMore,
+    UnknownProps,
+} from "@react-spring/types";

package/src/reduced-motion.ts

@@ -0,0 +1,82 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { Globals } from "@react-spring/core";
+import { useSyncExternalStore } from "react";
+
+type Listener = () => void;
+type Tracker = { settings: Gtk.Settings | null; isReduced: boolean | null };
+
+const REDUCED_MOTION_MINOR = 22;
+const tracker: Tracker = { settings: null, isReduced: null };
+const listeners: Set<Listener> = new Set();
+
+const hasReducedMotionSetting = (): boolean => Gtk.checkVersion(4, REDUCED_MOTION_MINOR, 0) === null;
+
+const isReduceMotionPreferred = (settings: Gtk.Settings): boolean =>
+    hasReducedMotionSetting() && settings.gtkInterfaceReducedMotion === Gtk.ReducedMotion.REDUCE;
+
+const sync = (): void => {
+    const { settings } = tracker;
+
+    if (settings === null) {
+        return;
+    }
+
+    const isReduced = !settings.gtkEnableAnimations || isReduceMotionPreferred(settings);
+    Globals.assign({ skipAnimation: !settings.gtkEnableAnimations });
+
+    if (isReduced === tracker.isReduced) {
+        return;
+    }
+
+    tracker.isReduced = isReduced;
+
+    for (const listener of listeners) {
+        listener();
+    }
+};
+
+const watch = (settings: Gtk.Settings): void => {
+    tracker.settings = settings;
+    settings.on("notify::gtk-enable-animations", sync);
+
+    if (hasReducedMotionSetting()) {
+        settings.on("notify::gtk-interface-reduced-motion", sync);
+    }
+
+    sync();
+};
+
+const trackReducedMotion = (): boolean | null => {
+    if (tracker.settings === null) {
+        const settings = Gtk.Settings.getDefault();
+
+        if (settings === null) {
+            return null;
+        }
+
+        watch(settings);
+    }
+
+    return tracker.isReduced;
+};
+
+const subscribe = (listener: Listener): (() => void) => {
+    listeners.add(listener);
+
+    return () => {
+        listeners.delete(listener);
+    };
+};
+
+/**
+ * Reports whether the desktop asks for less motion: `true` while GTK's `gtk-enable-animations`
+ * setting is off, which is when every spring already jumps straight to its target, and also while
+ * the `gtk-interface-reduced-motion` setting of GTK 4.22 asks to reduce motion, the preference
+ * behind the `prefers-reduced-motion` media query, which leaves springs running so that components
+ * can trade a slide for a fade themselves. Returns `null` until a display is open.
+ *
+ * @returns `true` when motion should be reduced, `false` when it should not, `null` when unknown.
+ */
+const useReducedMotion = (): boolean | null => useSyncExternalStore(subscribe, trackReducedMotion);
+
+export { trackReducedMotion, useReducedMotion };

package/src/request-frame.ts

@@ -0,0 +1,214 @@
+import * as GLib from "@gtkx/gi/glib";
+import * as Gtk from "@gtkx/gi/gtk";
+
+type FrameCallback = () => void;
+type Timer = ReturnType<typeof setTimeout>;
+type Driver = { widget: Gtk.Widget; tickId: number; stallSource: number };
+
+type Scheduler = {
+    callbacks: FrameCallback[];
+    driver: Driver | null;
+    fallbackTimer: Timer | null;
+    flushedAt: number;
+    isTicking: boolean;
+    stalledUntil: WeakMap<Gtk.Widget, number>;
+    ticks: number;
+};
+
+const FALLBACK_FRAME_MS = 16;
+const MIN_FRAME_MS = 1;
+const STALL_MS = 250;
+const STALL_COOLDOWN_MS = 1000;
+
+const scheduler: Scheduler = {
+    callbacks: [],
+    driver: null,
+    fallbackTimer: null,
+    flushedAt: 0,
+    isTicking: false,
+    stalledUntil: new WeakMap(),
+    ticks: 0,
+};
+
+const isSuspended = (widget: Gtk.Widget): boolean => widget instanceof Gtk.Window && widget.isSuspended();
+
+const hasClock = (widget: Gtk.Widget): boolean =>
+    widget.getMapped() && widget.getFrameClock() !== null && !isSuspended(widget);
+
+const isCoolingDown = (widget: Gtk.Widget): boolean => {
+    const until = scheduler.stalledUntil.get(widget);
+
+    if (until === undefined) {
+        return false;
+    }
+
+    if (performance.now() < until) {
+        return true;
+    }
+
+    scheduler.stalledUntil.delete(widget);
+
+    return false;
+};
+
+const findDriverWidget = (): Gtk.Widget | null => {
+    const candidates = Gtk.Window.listToplevels().filter((widget) => hasClock(widget));
+
+    return candidates.find((widget) => !scheduler.stalledUntil.has(widget)) ??
+        candidates.find((widget) => !isCoolingDown(widget)) ??
+        null;
+};
+
+const flush = (): void => {
+    const pending = scheduler.callbacks;
+    scheduler.callbacks = [];
+    scheduler.isTicking = true;
+    scheduler.flushedAt = performance.now();
+
+    try {
+        for (const callback of pending) {
+            callback();
+        }
+    } finally {
+        scheduler.isTicking = false;
+    }
+};
+
+const armStallSource = (): number => GLib.timeoutAdd(GLib.PRIORITY_DEFAULT_IDLE, STALL_MS, shouldRepeatStallCheck);
+
+const cancelStallSource = (driver: Driver): void => {
+    if (driver.stallSource === 0) {
+        return;
+    }
+
+    GLib.Source.remove(driver.stallSource);
+    driver.stallSource = 0;
+};
+
+const finishDriver = (driver: Driver): void => {
+    cancelStallSource(driver);
+    driver.widget.off("unmap", onDriverUnmapped);
+    scheduler.driver = null;
+};
+
+const releaseDriver = (driver: Driver): void => {
+    finishDriver(driver);
+    driver.widget.removeTickCallback(driver.tickId);
+};
+
+const flushThenArm = (): void => {
+    try {
+        flush();
+    } finally {
+        arm();
+    }
+};
+
+const shouldContinueTicking = (driver: Driver): boolean => {
+    if (scheduler.driver !== driver) {
+        arm();
+
+        return GLib.SOURCE_REMOVE;
+    }
+
+    if (scheduler.callbacks.length === 0) {
+        finishDriver(driver);
+
+        return GLib.SOURCE_REMOVE;
+    }
+
+    driver.stallSource = armStallSource();
+
+    return GLib.SOURCE_CONTINUE;
+};
+
+const shouldKeepTicking = (): boolean => {
+    const { driver } = scheduler;
+
+    if (driver === null) {
+        return GLib.SOURCE_REMOVE;
+    }
+
+    if (performance.now() - scheduler.flushedAt < MIN_FRAME_MS) {
+        return GLib.SOURCE_CONTINUE;
+    }
+
+    cancelStallSource(driver);
+    scheduler.ticks += 1;
+    scheduler.stalledUntil.delete(driver.widget);
+
+    try {
+        flush();
+    } catch (error) {
+        finishDriver(driver);
+        arm();
+        throw error;
+    }
+
+    return shouldContinueTicking(driver);
+};
+
+const onFallbackFrame = (): void => {
+    scheduler.fallbackTimer = null;
+    flushThenArm();
+};
+
+const armDriver = (widget: Gtk.Widget): void => {
+    const tickId = widget.addTickCallback(shouldKeepTicking);
+    scheduler.driver = { widget, tickId, stallSource: armStallSource() };
+    widget.on("unmap", onDriverUnmapped);
+};
+
+function shouldRepeatStallCheck(): boolean {
+    const { driver } = scheduler;
+
+    if (driver !== null) {
+        driver.stallSource = 0;
+        releaseDriver(driver);
+        scheduler.stalledUntil.set(driver.widget, performance.now() + STALL_COOLDOWN_MS);
+        flushThenArm();
+    }
+
+    return GLib.SOURCE_REMOVE;
+}
+
+function onDriverUnmapped(): void {
+    const { driver } = scheduler;
+
+    if (driver === null) {
+        return;
+    }
+
+    scheduler.stalledUntil.delete(driver.widget);
+    releaseDriver(driver);
+
+    if (!scheduler.isTicking) {
+        arm();
+    }
+}
+
+function arm(): void {
+    if (scheduler.callbacks.length === 0 || scheduler.driver !== null || scheduler.fallbackTimer !== null) {
+        return;
+    }
+
+    const widget = findDriverWidget();
+
+    if (widget === null) {
+        scheduler.fallbackTimer = setTimeout(onFallbackFrame, FALLBACK_FRAME_MS);
+
+        return;
+    }
+
+    armDriver(widget);
+}
+
+const requestFrame = (callback: FrameCallback): void => {
+    scheduler.callbacks.push(callback);
+
+    if (!scheduler.isTicking) {
+        arm();
+    }
+};
+
+export { requestFrame };

package/src/types.ts

@@ -0,0 +1,64 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type * as elements from "@gtkx/jsx";
+import type { FluidValue } from "@react-spring/shared";
+import type { ComponentPropsWithRef, ElementType, FunctionComponent, Ref } from "react";
+
+/** An array-valued prop whose items may each be a spring or an interpolation, such as mixed text children. */
+type AnimatedItems<T> = [Exclude<Extract<T, Iterable<unknown>>, string>] extends [never]
+    ? never
+    : Exclude<Extract<T, Iterable<unknown>>, string> extends Iterable<infer Item>
+        ? Iterable<AnimatedProp<Item>>
+        : never;
+
+/** A prop value that an animated component also accepts as a spring or an interpolation. */
+type AnimatedProp<T> = T | FluidValue<Exclude<T, undefined>> | AnimatedItems<Exclude<T, undefined>>;
+
+/**
+ * A `style` object whose declarations may each be a spring or an interpolation, nested blocks
+ * included, so the object a spring hook returns can be handed to `style` as it is.
+ */
+type AnimatedStyle<T> = {
+    [K in keyof T]: T[K] extends string | number | undefined | null
+        ? AnimatedProp<T[K]>
+        : AnimatedProp<T[K]> | AnimatedStyle<NonNullable<T[K]>>;
+};
+
+/**
+ * The props of an animated component: every prop of the wrapped component, each also accepting a
+ * {@link FluidValue} such as a `SpringValue` or an `Interpolation`, while `ref` and `key` keep
+ * their original types.
+ */
+type AnimatedProps<Props extends object> = {
+    [P in keyof Props]: P extends "key" | "ref"
+        ? Props[P]
+        : P extends "style"
+            ? AnimatedProp<Props[P]> | AnimatedStyle<NonNullable<Props[P]>>
+            : AnimatedProp<Props[P]>;
+};
+
+/** A component returned by {@link animated}: the wrapped component with animated props. */
+type AnimatedComponent<T extends Exclude<ElementType, string>> = FunctionComponent<
+    AnimatedProps<ComponentPropsWithRef<T>>
+>;
+
+/**
+ * The widget components of the generated `@gtkx/jsx` store, keyed by element name, each wrapped as
+ * an {@link AnimatedComponent}. Only components whose `ref` exposes a `Gtk.Widget` subclass are
+ * included, so `animated.GtkLabel` is available while non-widget elements such as `GtkAdjustment`
+ * are wrapped explicitly through the `animated(...)` call instead.
+ */
+type AnimatedElements = {
+    readonly [K in keyof typeof elements as (typeof elements)[K] extends Exclude<ElementType, string>
+        ? ComponentPropsWithRef<(typeof elements)[K]> extends { ref?: Ref<infer Instance> | undefined }
+            ? [NonNullable<Instance>] extends [never]
+                    ? never
+                    : NonNullable<Instance> extends Gtk.Widget
+                        ? K
+                        : never
+            : never
+        : never]: (typeof elements)[K] extends Exclude<ElementType, string>
+        ? AnimatedComponent<(typeof elements)[K]>
+        : never;
+};
+
+export type { AnimatedComponent, AnimatedElements, AnimatedItems, AnimatedProp, AnimatedProps, AnimatedStyle };