@gtkx/animated 1.3.0

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 };

package/src/with-animated.tsx

@@ -0,0 +1,254 @@
+import type { Lookup } from "@react-spring/types";
+import { useMergedRef } from "@gtkx/react/internal";
+import {
+    addFluidObserver,
+    type FluidEvent,
+    type FluidValue,
+    getFluidValue,
+    hasFluidValue,
+    raf,
+    removeFluidObserver,
+    useForceUpdate,
+} from "@react-spring/shared";
+import { type ElementType, type ReactNode, type Ref, type RefObject, useLayoutEffect, useRef } from "react";
+import type { AnimatedComponent } from "./types.js";
+import { didApplyAnimatedValues } from "./apply-animated-values.js";
+import { trackReducedMotion } from "./reduced-motion.js";
+
+type AnimatedInput = { ref?: Ref<object> | undefined; [key: string]: unknown };
+type Wrappable = Exclude<ElementType, string>;
+type ObserverRef = { current: PropsObserver | null };
+
+const STYLE_PROP = "style";
+const cache: WeakMap<object, AnimatedComponent<Wrappable>> = new WeakMap();
+
+const getDisplayName = (component: Wrappable): string => {
+    const { displayName, name } = component as { displayName?: unknown; name?: unknown };
+
+    if (typeof displayName === "string" && displayName !== "") {
+        return displayName;
+    }
+
+    return typeof name === "string" && name !== "" ? name : "Anonymous";
+};
+
+const isFluidProp = (value: unknown): boolean => hasFluidValue(value) || isFluidArray(value);
+
+const isBlock = (value: unknown): value is Lookup =>
+    typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+
+function isFluidArray(value: unknown): value is unknown[] {
+    return Array.isArray(value) && value.some((item) => isFluidProp(item));
+}
+
+function isFluidStyle(value: unknown): value is Lookup {
+    return isBlock(value) && Object.values(value).some((item) => hasFluidValue(item) || isFluidStyle(item));
+}
+
+function resolveStyle(style: Lookup): Lookup {
+    const resolved: Lookup = {};
+
+    for (const name in style) {
+        const value: unknown = style[name];
+        const next: unknown = isFluidStyle(value) ? resolveStyle(value) : getFluidValue(value);
+        resolved[name] = next;
+    }
+
+    return resolved;
+}
+
+function resolveValue(value: unknown): unknown {
+    return isFluidArray(value) ? value.map((item) => resolveValue(item)) : getFluidValue(value);
+}
+
+const isFluidNamed = (name: string, value: unknown): boolean =>
+    isFluidProp(value) || (name === STYLE_PROP && isFluidStyle(value));
+
+const resolveNamed = (name: string, value: unknown): unknown =>
+    name === STYLE_PROP && isFluidStyle(value) ? resolveStyle(value) : resolveValue(value);
+
+const resolveProps = (props: Lookup, isAnimatedOnly: boolean): Lookup => {
+    const resolved: Lookup = {};
+
+    for (const name in props) {
+        const value: unknown = props[name];
+
+        if (isFluidNamed(name, value)) {
+            resolved[name] = resolveNamed(name, value);
+        } else if (!isAnimatedOnly) {
+            resolved[name] = value;
+        }
+    }
+
+    return resolved;
+};
+
+function collectEach(items: unknown[], dependencies: Set<FluidValue>): void {
+    for (const item of items) {
+        collectDependencies(item, dependencies);
+    }
+}
+
+function collectDependencies(value: unknown, dependencies: Set<FluidValue>): void {
+    if (hasFluidValue(value)) {
+        dependencies.add(value);
+    } else if (isFluidArray(value)) {
+        collectEach(value, dependencies);
+    } else if (isFluidStyle(value)) {
+        collectEach(Object.values(value), dependencies);
+    }
+}
+
+const collectNamed = (name: string, value: unknown, dependencies: Set<FluidValue>): void => {
+    if (isFluidNamed(name, value)) {
+        collectDependencies(value, dependencies);
+    }
+};
+
+const getDependencies = (props: Lookup): Set<FluidValue> => {
+    const dependencies: Set<FluidValue> = new Set();
+
+    for (const name in props) {
+        collectNamed(name, props[name], dependencies);
+    }
+
+    return dependencies;
+};
+
+const getFluidNames = (props: Lookup): Set<string> => {
+    const names: Set<string> = new Set();
+
+    for (const name in props) {
+        if (isFluidNamed(name, props[name])) {
+            names.add(name);
+        }
+    }
+
+    return names;
+};
+
+const observe = (observer: PropsObserver): void => {
+    for (const dependency of observer.dependencies) {
+        addFluidObserver(dependency, observer);
+    }
+};
+
+const unobserve = (observer: PropsObserver): void => {
+    for (const dependency of observer.dependencies) {
+        removeFluidObserver(dependency, observer);
+    }
+
+    raf.cancel(observer.update);
+};
+
+const useObserver = (observer: PropsObserver): void => {
+    const observerRef: ObserverRef = useRef<PropsObserver | null>(null);
+
+    useLayoutEffect(() => {
+        observerRef.current = observer;
+        observe(observer);
+
+        return () => {
+            if (observerRef.current === null) {
+                return;
+            }
+
+            unobserve(observerRef.current);
+            observerRef.current = null;
+        };
+    });
+};
+
+const collectStaticReplacements = (
+    props: Lookup,
+    previous: Set<string>,
+    current: Set<string>,
+    values: Lookup,
+): void => {
+    for (const name of previous) {
+        const value: unknown = props[name];
+
+        if (value !== undefined && !current.has(name)) {
+            values[name] = value;
+        }
+    }
+};
+
+const useCommitSync = (instanceRef: RefObject<object | null>, props: Lookup): void => {
+    const fluidNamesRef = useRef<Set<string>>(new Set());
+
+    useLayoutEffect(() => {
+        const previous = fluidNamesRef.current;
+        const current = getFluidNames(props);
+        fluidNamesRef.current = current;
+        trackReducedMotion();
+        const instance = instanceRef.current;
+
+        if (instance === null) {
+            return;
+        }
+
+        const values = resolveProps(props, true);
+        collectStaticReplacements(props, previous, current, values);
+        didApplyAnimatedValues(instance, values);
+    });
+};
+
+const useAnimatedUpdate = (instanceRef: RefObject<object | null>, props: Lookup): (() => void) => {
+    const forceUpdate = useForceUpdate();
+
+    return () => {
+        const instance = instanceRef.current;
+        const isApplied = instance !== null && didApplyAnimatedValues(instance, resolveProps(props, true));
+
+        if (!isApplied) {
+            forceUpdate();
+        }
+    };
+};
+
+const createAnimatedComponent = (Component: Wrappable): AnimatedComponent<Wrappable> => {
+    const Animated = ({ ref: givenRef, ...props }: AnimatedInput): ReactNode => {
+        const instanceRef = useRef<object | null>(null);
+        const ref = useMergedRef(givenRef, instanceRef);
+        const update = useAnimatedUpdate(instanceRef, props);
+        useObserver(new PropsObserver(update, getDependencies(props)));
+        useCommitSync(instanceRef, props);
+
+        return <Component {...resolveProps(props, false)} ref={ref} />;
+    };
+
+    Animated.displayName = `Animated(${getDisplayName(Component)})`;
+
+    return Animated as AnimatedComponent<Wrappable>;
+};
+
+function withAnimated<T extends Wrappable>(component: T): AnimatedComponent<T> {
+    let cached = cache.get(component);
+
+    if (cached === undefined) {
+        cached = createAnimatedComponent(component);
+        cache.set(component, cached);
+    }
+
+    return cached as AnimatedComponent<T>;
+}
+
+class PropsObserver {
+    readonly update: () => void;
+
+    readonly dependencies: Set<FluidValue>;
+
+    constructor(update: () => void, dependencies: Set<FluidValue>) {
+        this.update = update;
+        this.dependencies = dependencies;
+    }
+
+    eventObserved(event: FluidEvent): void {
+        if (event.type === "change") {
+            raf.write(this.update);
+        }
+    }
+}
+
+export { withAnimated };