@caperjs/solid 0.7.0

package/src/AnimatedShow.test.tsx

@@ -0,0 +1,146 @@
+import gsap from 'gsap';
+import PixiPlugin from 'gsap/PixiPlugin';
+import * as PIXI from 'pixi.js';
+import { Container } from 'pixi.js';
+import { createSignal } from 'solid-js';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { AnimatedShow } from './AnimatedShow';
+import { createElement, render } from './renderer';
+
+// GSAP normally advances its root timeline from requestAnimationFrame, which
+// happy-dom fires on a real clock — nothing to assert against. Detach the root
+// from the ticker once and step it by hand instead, so every test owns time.
+let now = 0;
+
+beforeAll(() => {
+  // Caper's GSAPPlugin does this at app bootstrap; nothing bootstraps here, and
+  // `AnimatedShow` animates through `pixi: {...}` vars. PixiPlugin looks for
+  // `window.PIXI`, which no bundled app has — hence the explicit handover.
+  gsap.registerPlugin(PixiPlugin);
+  PixiPlugin.registerPIXI(PIXI);
+  gsap.ticker.remove(gsap.updateRoot);
+  now = gsap.ticker.time;
+});
+
+function advance(seconds: number) {
+  now += seconds;
+  gsap.updateRoot(now);
+}
+
+/** Mount an `<AnimatedShow>` into a detached container and hand back the seams. */
+function mount(initial: boolean, props: { enter?: gsap.TweenVars; exit?: gsap.TweenVars } = {}) {
+  const stage = createElement('container');
+  const [open, setOpen] = createSignal(initial);
+
+  const dispose = render(
+    () => (
+      <AnimatedShow when={open} enter={props.enter} exit={props.exit}>
+        <sprite />
+      </AnimatedShow>
+    ),
+    stage,
+  );
+
+  const wrapper = stage.children[0] as Container;
+  return { stage, wrapper, setOpen, dispose, childCount: () => wrapper.children.length };
+}
+
+describe('AnimatedShow', () => {
+  it('mounts children and animates them in when it opens', () => {
+    const { wrapper, setOpen, childCount, dispose } = mount(false);
+    expect(childCount()).toBe(0);
+
+    setOpen(true);
+    expect(childCount()).toBe(1);
+    expect(wrapper.alpha).toBe(0);
+    expect(wrapper.scale.x).toBeCloseTo(0.85, 5);
+
+    // Default enter runs for 0.25s.
+    advance(0.4);
+    expect(wrapper.alpha).toBe(1);
+    expect(wrapper.scale.x).toBeCloseTo(1, 5);
+    expect(wrapper.scale.y).toBeCloseTo(1, 5);
+
+    dispose();
+  });
+
+  it('keeps children mounted through the exit, then unmounts them', () => {
+    const { wrapper, setOpen, childCount, dispose } = mount(true);
+    expect(childCount()).toBe(1);
+
+    setOpen(false);
+    expect(childCount()).toBe(1);
+
+    // Default exit runs for 0.2s.
+    advance(0.1);
+    expect(childCount()).toBe(1);
+    expect(wrapper.alpha).toBeGreaterThan(0);
+    expect(wrapper.alpha).toBeLessThan(1);
+
+    advance(0.2);
+    expect(childCount()).toBe(0);
+
+    dispose();
+  });
+
+  it('cancels the pending unmount when it re-opens mid-exit', () => {
+    const { wrapper, setOpen, childCount, dispose } = mount(true);
+
+    setOpen(false);
+    advance(0.1);
+    expect(childCount()).toBe(1);
+
+    setOpen(true);
+    expect(childCount()).toBe(1);
+
+    // Long past the point the exit would have finished and unmounted.
+    advance(0.1);
+    expect(childCount()).toBe(1);
+    advance(1);
+    expect(childCount()).toBe(1);
+    expect(wrapper.alpha).toBe(1);
+
+    dispose();
+  });
+
+  it('disposes cleanly mid-animation', () => {
+    const { wrapper, setOpen, dispose } = mount(false);
+
+    setOpen(true);
+    advance(0.1);
+    // Still in flight: moved off the start, not yet parked on the end value.
+    // (The default `back.out` ease overshoots, so "not 1" is the honest check.)
+    const mid = wrapper.alpha;
+    expect(mid).toBeGreaterThan(0);
+    expect(mid).not.toBe(1);
+
+    expect(() => dispose()).not.toThrow();
+    expect(() => advance(1)).not.toThrow();
+    // Cleanup killed the animation, so the node is frozen where it stood.
+    expect(wrapper.alpha).toBe(mid);
+  });
+
+  it("runs a custom exit's own onComplete before unmounting", () => {
+    let childrenWhenCalled = -1;
+    const onComplete = vi.fn(() => {
+      childrenWhenCalled = wrapper.children.length;
+    });
+    const { wrapper, setOpen, childCount, dispose } = mount(true, {
+      exit: { pixi: { alpha: 0 }, duration: 0.5, onComplete },
+    });
+
+    setOpen(false);
+    advance(0.3);
+    expect(onComplete).not.toHaveBeenCalled();
+    expect(childCount()).toBe(1);
+
+    advance(0.3);
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(childrenWhenCalled).toBe(1);
+    expect(childCount()).toBe(0);
+    expect(wrapper.alpha).toBe(0);
+
+    dispose();
+  });
+});

package/src/AnimatedShow.tsx

@@ -0,0 +1,87 @@
+// `<Show>` unmounts the instant its condition flips, which is fine for a scene
+// graph and terrible for a popup. `<AnimatedShow>` keeps the node on stage until
+// its exit animation finishes, so conditional UI can enter and leave gracefully
+// without the caller writing a single imperative line.
+
+import gsap from 'gsap';
+import type { Container } from 'pixi.js';
+import { createEffect, createMemo, createSignal, on, onCleanup, Show, untrack } from 'solid-js';
+
+/** Where an entering node starts from, before it animates to `enter`. */
+const ENTER_FROM: gsap.TweenVars = { pixi: { alpha: 0, scale: 0.85 } };
+const ENTER_TO: gsap.TweenVars = { pixi: { alpha: 1, scale: 1 }, duration: 0.25, ease: 'back.out(1.7)' };
+const EXIT_TO: gsap.TweenVars = { pixi: { alpha: 0, scale: 0.85 }, duration: 0.2, ease: 'power2.in' };
+
+/**
+ * Conditional UI with enter / exit animations.
+ *
+ * ```tsx
+ * <AnimatedShow when={open}>
+ *   <container>…</container>
+ * </AnimatedShow>
+ * ```
+ *
+ * Custom `enter` / `exit` are plain GSAP vars — put target properties in a
+ * `pixi: {...}` block (`{ pixi: { y: 20, alpha: 0 }, duration: 0.3 }`).
+ * There is no `fallback` — the whole point is that the node outlives the flag.
+ *
+ * Requires GSAP's PixiPlugin, which caper's `GSAPPlugin` registers during app
+ * bootstrap. This package deliberately does not register it itself; outside a
+ * booted `Application` (tests, standalone use) call
+ * `gsap.registerPlugin(PixiPlugin)` yourself first.
+ */
+export function AnimatedShow(props: {
+  when: boolean | (() => boolean);
+  children: any;
+  enter?: gsap.TweenVars;
+  exit?: gsap.TweenVars;
+}) {
+  const open = createMemo(() => (typeof props.when === 'function' ? props.when() : props.when));
+  // Trails `open`: goes true immediately, goes false only once the exit is done.
+  const [mounted, setMounted] = createSignal(untrack(open));
+
+  let wrapper: Container | undefined;
+  let animation: gsap.core.Tween | undefined;
+
+  const stop = () => {
+    animation?.kill();
+    animation = undefined;
+  };
+
+  createEffect(
+    on(
+      open,
+      (isOpen) => {
+        const node = wrapper;
+        if (!node) return;
+        // Killing first is what makes rapid toggling safe: the exit's
+        // `onComplete` can no longer unmount a node that is entering again.
+        stop();
+
+        if (isOpen) {
+          setMounted(true);
+          gsap.set(node, ENTER_FROM);
+          animation = gsap.to(node, props.enter ?? ENTER_TO);
+        } else {
+          const exit = props.exit ?? EXIT_TO;
+          animation = gsap.to(node, {
+            ...exit,
+            onComplete: () => {
+              (exit.onComplete as (() => void) | undefined)?.();
+              setMounted(false);
+            },
+          });
+        }
+      },
+      { defer: true },
+    ),
+  );
+
+  onCleanup(stop);
+
+  return (
+    <container ref={(el: Container) => (wrapper = el)}>
+      <Show when={mounted()}>{props.children}</Show>
+    </container>
+  );
+}

package/src/Composable.test.ts

@@ -0,0 +1,214 @@
+import { Application } from '@caperjs/core';
+import { Graphics, Sprite } from 'pixi.js';
+import { createSignal } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Composable, ComposableContainer, ComposableScene, type Composes } from './Composable';
+import { createElement, insertNode, spread } from './renderer';
+
+/**
+ * Caper's `Container` reaches for the Application singleton on `added`,
+ * `removed` and `destroy`. Only the members those paths touch are stubbed.
+ */
+function stubApplication() {
+  const ticker = { add: vi.fn(), remove: vi.fn(), addOnce: vi.fn() };
+  const layout = { update: vi.fn(), _updateSize: vi.fn(), updateLayout: vi.fn() };
+  const onResize = { connect: vi.fn(() => ({ disconnect: vi.fn() })), disconnect: vi.fn() };
+  (Application as any).instance = {
+    config: { useLayout: true },
+    ticker,
+    onResize,
+    animation: { killAll: vi.fn() },
+    renderer: { layout },
+  };
+  return { ticker, layout, onResize };
+}
+
+beforeEach(() => {
+  stubApplication();
+});
+
+afterEach(() => {
+  (Application as any).instance = undefined;
+});
+
+/** A stand-in for the stage — a plain host node, not itself composable. */
+function stage() {
+  return createElement('container');
+}
+
+class Composed extends ComposableContainer implements Composes {
+  public compose() {
+    return createElement('sprite');
+  }
+}
+
+describe('Composable', () => {
+  it('mounts compose() on the first add, not at construction', () => {
+    const view = new Composed();
+    expect(view.children).toEqual([]);
+
+    stage().addChild(view);
+
+    expect(view.children).toHaveLength(1);
+    expect(view.children[0]).toBeInstanceOf(Sprite);
+  });
+
+  it('mounts once — removing and re-adding does not duplicate the tree', () => {
+    const parent = stage();
+    const view = new Composed();
+
+    parent.addChild(view);
+    const mounted = view.children[0];
+
+    parent.removeChild(view);
+    parent.addChild(view);
+
+    expect(view.children).toEqual([mounted]);
+  });
+
+  it('keeps props reactive after mount', () => {
+    const [x, setX] = createSignal(0);
+
+    class Moving extends ComposableContainer implements Composes {
+      public compose() {
+        const node = createElement('sprite');
+        spread(
+          node,
+          {
+            get x() {
+              return x();
+            },
+          },
+          true,
+        );
+        return node;
+      }
+    }
+
+    const view = new Moving();
+    stage().addChild(view);
+
+    const node = view.children[0] as Sprite;
+    expect(node.x).toBe(0);
+
+    setX(25);
+    expect(node.x).toBe(25);
+  });
+
+  it('disposes the solid root on destroy, so updates stop', () => {
+    const [x, setX] = createSignal(0);
+
+    class Moving extends ComposableContainer implements Composes {
+      public compose() {
+        const node = createElement('sprite');
+        spread(
+          node,
+          {
+            get x() {
+              return x();
+            },
+          },
+          true,
+        );
+        return node;
+      }
+    }
+
+    const view = new Moving();
+    stage().addChild(view);
+
+    const node = view.children[0] as Sprite;
+    setX(25);
+    expect(node.x).toBe(25);
+
+    expect(() => view.destroy()).not.toThrow();
+
+    setX(99);
+    expect(node.x).toBe(25);
+  });
+
+  it('destroys children without a double-destroy error', () => {
+    const view = new Composed();
+    stage().addChild(view);
+    const node = view.children[0] as Sprite;
+
+    expect(() => view.destroy({ children: true })).not.toThrow();
+    expect(node.destroyed).toBe(true);
+    expect(view.destroyed).toBe(true);
+  });
+
+  it('mounts a composed child that a composed parent inserts', () => {
+    class Child extends ComposableContainer implements Composes {
+      public compose() {
+        return createElement('graphics');
+      }
+    }
+
+    class Parent extends ComposableContainer implements Composes {
+      public compose() {
+        const root = createElement('container');
+        insertNode(root, new Child());
+        return root;
+      }
+    }
+
+    const view = new Parent();
+    stage().addChild(view);
+
+    const root = view.children[0];
+    const child = root.children[0] as Child;
+    expect(child).toBeInstanceOf(Child);
+    expect(child.children[0]).toBeInstanceOf(Graphics);
+  });
+
+  it('leaves a subclass without compose() completely alone', () => {
+    class Plain extends ComposableContainer {}
+
+    const view = new Plain();
+    expect(() => stage().addChild(view)).not.toThrow();
+    expect(view.children).toEqual([]);
+    expect(() => view.destroy()).not.toThrow();
+  });
+
+  it('still mounts when a subclass overrides added() without calling super', () => {
+    class Rude extends ComposableContainer implements Composes {
+      public addedRan = false;
+
+      public added() {
+        this.addedRan = true;
+      }
+
+      public compose() {
+        return createElement('sprite');
+      }
+    }
+
+    const view = new Rude();
+    stage().addChild(view);
+
+    expect(view.addedRan).toBe(true);
+    expect(view.children).toHaveLength(1);
+    expect(view.children[0]).toBeInstanceOf(Sprite);
+  });
+
+  it('applies to any display base, including Scene', () => {
+    class Screen extends ComposableScene implements Composes {
+      public compose() {
+        return createElement('sprite');
+      }
+    }
+
+    const view = new Screen();
+    stage().addChild(view);
+
+    expect(view.children).toHaveLength(1);
+    // `Scene.destroy()` takes no arguments — the mixin has to mirror that.
+    expect(() => view.destroy()).not.toThrow();
+  });
+
+  it('is exported as a mixin usable on other bases', () => {
+    expect(typeof Composable).toBe('function');
+    expect(new (Composable(ComposableContainer))()).toBeInstanceOf(ComposableContainer);
+  });
+});

package/src/Composable.ts

@@ -0,0 +1,84 @@
+// The `compose()` contract: a display object declares its members by returning
+// JSX, that tree is mounted ONCE the first time the object hits the stage, and
+// signals do every update after that — no re-render, no diff.
+
+import { Container, Constructor, Scene } from '@caperjs/core';
+import type { DestroyOptions } from 'pixi.js';
+
+import type { PixiNode } from './renderer';
+import { render } from './renderer';
+
+/**
+ * What `compose()` hands back. `unknown` for now so this file stays JSX-free;
+ * it becomes the real element type when `jsx.d.ts` lands.
+ */
+export type Composed = unknown;
+
+/**
+ * The optional contract a `Composable` subclass opts into. Declared separately
+ * from the mixin (rather than merged onto it) so the mixin never claims a
+ * `compose` member of its own — the runtime just checks for one.
+ *
+ * @example
+ * ```tsx
+ * class HealthBar extends ComposableContainer implements Composes {
+ *   compose() {
+ *     return <text text="100 HP" />;
+ *   }
+ * }
+ * ```
+ */
+export interface Composes {
+  compose(): Composed;
+}
+
+/**
+ * Give a display class the `compose()` contract.
+ *
+ * The mixin adds no public members, so the returned constructor keeps `Base`'s
+ * own type — `compose()` is declared by the subclass via {@link Composes}.
+ *
+ * @param Base - The display class to make composable.
+ */
+export function Composable<TBase extends Constructor<any>>(Base: TBase): TBase {
+  return class extends Base {
+    private __composeDispose?: () => void;
+    private __composed = false;
+
+    constructor(...args: any[]) {
+      super(...args);
+      // Mount off Pixi's native 'added' event rather than the `added()` hook:
+      // subclasses routinely override `added()` without calling `super.added()`,
+      // which would silently skip the mount. Core's own lifecycle listens to the
+      // same event, so this coexists with it (and runs after it).
+      this.once('added', this.__mountCompose);
+    }
+
+    destroy(options?: DestroyOptions): void {
+      // Dispose the reactive graph first. Solid's disposal stops effects but does
+      // not detach the nodes it created — `super.destroy()` handles those, so
+      // there is no double-destroy path here.
+      this.__composeDispose?.();
+      this.__composeDispose = undefined;
+      super.destroy(options);
+    }
+
+    private __mountCompose() {
+      if (this.__composed) return;
+      this.__composed = true;
+      const host = this as Partial<Composes>;
+      if (typeof host.compose !== 'function') return;
+      // `Base` is only known as `Constructor<any>` here, so `this` has to be
+      // asserted into the renderer's host-node type.
+      this.__composeDispose = render(() => host.compose!() as PixiNode, this as unknown as PixiNode);
+    }
+  } as unknown as TBase;
+}
+
+/** A caper {@link Container} that can declare its members with JSX. */
+export const ComposableContainer = Composable(Container);
+export type ComposableContainer = InstanceType<typeof ComposableContainer>;
+
+/** A caper {@link Scene} that can declare its members with JSX. */
+export const ComposableScene = Composable(Scene);
+export type ComposableScene = InstanceType<typeof ComposableScene>;

package/src/animated.test.ts

@@ -0,0 +1,94 @@
+import gsap from 'gsap';
+import { createRoot, createSignal } from 'solid-js';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { animated } from './animated';
+
+// GSAP normally advances its root timeline from requestAnimationFrame, which
+// happy-dom fires on a real clock — nothing to assert against. Detach the root
+// from the ticker once and step it by hand instead, so every test owns time.
+let now = 0;
+
+beforeAll(() => {
+  gsap.ticker.remove(gsap.updateRoot);
+  now = gsap.ticker.time;
+});
+
+function advance(seconds: number) {
+  now += seconds;
+  gsap.updateRoot(now);
+}
+
+/**
+ * Mount `animated` in its own reactive owner. Solid flushes effects only once
+ * the root body returns, so the source has to be driven from outside — inside,
+ * the deferred effect would not be listening yet.
+ */
+function mount(initial: number, opts?: { duration?: number; ease?: string }) {
+  const [source, setSource] = createSignal(initial);
+  let shown!: () => number;
+  const dispose = createRoot((d) => {
+    shown = animated(source, opts);
+    return d;
+  });
+  return { shown: () => shown(), setSource, dispose };
+}
+
+describe('animated', () => {
+  it('starts at the source value and does not animate on mount', () => {
+    const { shown, dispose } = mount(100);
+
+    expect(shown()).toBe(100);
+    advance(1);
+    expect(shown()).toBe(100);
+
+    dispose();
+  });
+
+  it('glides toward a new source value and settles on it', () => {
+    const { shown, setSource, dispose } = mount(0);
+
+    setSource(100);
+    // Still at the old value: no frame has rendered yet.
+    expect(shown()).toBe(0);
+
+    advance(0.1);
+    const mid = shown();
+    expect(mid).toBeGreaterThan(0);
+    expect(mid).toBeLessThan(100);
+
+    // Default duration is 0.35s.
+    advance(0.5);
+    expect(shown()).toBe(100);
+
+    dispose();
+  });
+
+  it('honours a custom duration', () => {
+    const { shown, setSource, dispose } = mount(0, { duration: 2, ease: 'none' });
+
+    setSource(100);
+
+    advance(1);
+    expect(shown()).toBeCloseTo(50, 1);
+
+    advance(1.1);
+    expect(shown()).toBe(100);
+
+    dispose();
+  });
+
+  it('stops animating once its owner is disposed', () => {
+    const { shown, setSource, dispose } = mount(0);
+
+    setSource(100);
+    advance(0.1);
+    const mid = shown();
+    expect(mid).toBeGreaterThan(0);
+    expect(mid).toBeLessThan(100);
+
+    dispose();
+    advance(1);
+    expect(shown()).toBe(mid);
+  });
+});

package/src/animated.ts

@@ -0,0 +1,39 @@
+// A "gliding" signal: same read shape as any other accessor, but it eases toward
+// its source instead of snapping to it. The binding stays declarative —
+// `x={slid()}` — and nothing in the view knows an animation is running.
+
+import gsap from 'gsap';
+import { createEffect, createSignal, on, onCleanup, untrack } from 'solid-js';
+
+/**
+ * Follow `source` smoothly.
+ *
+ * Must be called inside a reactive owner (a component body or a `compose()`),
+ * because it registers an `onCleanup` to kill its animation.
+ *
+ * ```ts
+ * const barWidth = animated(() => hp() / 100);
+ * <graphics scale={{ x: barWidth(), y: 1 }} />
+ * ```
+ */
+export function animated(source: () => number, opts?: { duration?: number; ease?: string }): () => number {
+  const start = untrack(source);
+  const [value, setValue] = createSignal(start);
+
+  // gsap animates plain object properties, so the accessor's current value lives
+  // on this proxy and is mirrored into the signal on every frame.
+  const proxy = { v: start };
+
+  const animateTo = gsap.quickTo(proxy, 'v', {
+    duration: opts?.duration ?? 0.35,
+    ease: opts?.ease ?? 'power2.out',
+    onUpdate: () => setValue(proxy.v),
+  });
+
+  // `defer: true` skips the initial run, so mounting doesn't animate from nowhere.
+  createEffect(on(source, (next) => animateTo(next), { defer: true }));
+
+  onCleanup(() => animateTo.tween.kill());
+
+  return value;
+}