@cardstack/choreo 0.0.0 → 0.1.0-unstable.0

package/dist/steps.js

@@ -0,0 +1,831 @@
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+import { at } from './anchors.js';
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+
+const providers = new WeakMap();
+/** unnamed crossings still need a stable, unique inner anchor name */
+let crossings = 0;
+/** the steps directly inside an element, in document order; a nested <Choreo> is another region's */
+function collect(el) {
+  const out = [];
+  for (const child of Array.from(el.children)) {
+    if (child.hasAttribute('data-choreo')) {
+      continue;
+    }
+    const provider = providers.get(child);
+    if (provider) {
+      out.push(provider.node());
+    } else {
+      out.push(...collect(child));
+    }
+  }
+  return out;
+}
+/**
+ * args that are the step's own; every other named arg is a property to animate.
+ * `rotate` is NOT here although Move has a `@rotate` arg: on a Tween or
+ * Spring it is a property (Keynote's Spin), and Move never reads its props.
+ */
+const RESERVED = new Set(['align', 'at', 'by', 'delay', 'duration', 'ease', 'fill', 'from', 'name', 'of', 'order', 'path', 'read', 'repeat', 'repeatType', 'rest', 'shadow', 'size', 'space', 'spring', 'stagger', 'swap', 'to', 'times']);
+/** the pre-seconds spellings, kept only to fail loudly with the new name */
+const RENAMED = {
+  crossfade: '@swap',
+  ms: '@duration (in seconds)',
+  overlap: '@stagger (in seconds)'
+};
+function propsOf(args) {
+  const props = {};
+  for (const key of Object.keys(args)) {
+    if (args[key] === undefined) {
+      continue;
+    }
+    if (RENAMED[key]) {
+      throw new Error(`choreo: @${key} was renamed — use ${RENAMED[key]}`);
+    }
+    if (!RESERVED.has(key)) {
+      props[key] = args[key];
+    }
+  }
+  return props;
+}
+/**
+ * The template speaks seconds, as Motion does; the compiler's clock is ms.
+ * A composite step writes node literals, which are BELOW that boundary —
+ * so it converts its own seconds args here, and `undefined` stays
+ * `undefined` so an unset arg still means "take the default".
+ */
+function toMs(seconds) {
+  // the conditional return type is the whole point — a required `ms` field
+  // takes toMs(x) without a null check when x is a number — and TypeScript
+  // cannot verify a conditional return from inside, so the cast is the
+  // price of stating it
+  return seconds === undefined ? undefined : seconds * 1000;
+}
+const msOf = toMs;
+/** the args every step shares — a composite step extends this */
+
+/** …and the args of a step that names sprites */
+
+/**
+ * The base every step is built on, and the public seam for a COMPOSITE
+ * step — a new word in the timeline that expands into the built-in
+ * vocabulary. `c.Crossing` is one, and is written in nothing but this.
+ *
+ * Subclass it, implement `node()`, and render the component anywhere
+ * inside a `<Choreo>`: the region reads the tree back in document order
+ * and your node takes its place in it.
+ *
+ * ```gts
+ * export class Reveal extends StepComponent<StepArgs & { rise?: number }> {
+ *   node(): TimelineNode {
+ *     const { of, name, rise = 12 } = this.args;
+ *     return {
+ *       at: this.args.at,
+ *       children: [
+ *         { kind: 'tween', generic: true, of, ms: 240, props: { opacity: [0, 1] } },
+ *         { kind: 'tween', generic: true, of, ms: 240, props: { y: [rise, 0] } },
+ *       ],
+ *       kind: 'parallel',
+ *       name,
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * **`node()` is called on every pass**, and its result is fingerprinted to
+ * decide whether an edited timeline replays the run. So it must be pure
+ * and cheap: no measurement, no DOM writes, no tracked writes (a tracked
+ * write re-renders, which replays the pass, which calls `node()`). And
+ * because functions in the tree are compared by identity, a `node()` that
+ * allocates a fresh closure per call declares an edit on every pass —
+ * hoist property functions to module scope.
+ *
+ * Two conventions worth keeping: mark children `generic: true` so a
+ * sibling step can claim a sprite away from your defaults (the yield
+ * rule, §4.7), and derive any inner `name` from your own `@name` so two
+ * of your step in one timeline do not collide.
+ */
+class StepComponent extends Component {
+  mark = modifier(el => {
+    providers.set(el, this);
+    return () => providers.delete(el);
+  });
+  static {
+    setComponentTemplate(precompileTemplate("<span hidden data-choreo-step {{this.mark}}></span>", {
+      strictMode: true
+    }), this);
+  }
+}
+class Tween extends StepComponent {
+  node() {
+    const {
+      of,
+      by,
+      duration,
+      ease,
+      delay,
+      order,
+      repeat,
+      repeatType,
+      times
+    } = this.args;
+    return {
+      at: this.args.at,
+      by,
+      delay: msOf(delay),
+      ease,
+      kind: 'tween',
+      name: this.args.name,
+      ms: duration * 1000,
+      of,
+      order,
+      props: propsOf(this.args),
+      repeat,
+      repeatType,
+      times,
+      stagger: msOf(this.args.stagger)
+    };
+  }
+}
+class Spring extends StepComponent {
+  node() {
+    const {
+      of,
+      by,
+      spring,
+      delay,
+      order
+    } = this.args;
+    return {
+      at: this.args.at,
+      by,
+      delay: msOf(delay),
+      kind: 'spring',
+      name: this.args.name,
+      of,
+      order,
+      props: propsOf(this.args),
+      spring,
+      stagger: msOf(this.args.stagger)
+    };
+  }
+}
+class Move extends StepComponent {
+  node() {
+    const {
+      of,
+      duration,
+      ease,
+      delay,
+      path,
+      rotate,
+      space,
+      spring,
+      size,
+      swap,
+      from,
+      to,
+      stagger
+    } = this.args;
+    propsOf(this.args); // no properties — evaluated for the renamed-arg errors
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      ease,
+      from,
+      kind: 'move',
+      name: this.args.name,
+      ms: msOf(duration),
+      of,
+      path,
+      rotate,
+      size,
+      space,
+      spring,
+      stagger: msOf(stagger),
+      swap,
+      to
+    };
+  }
+}
+class Hold extends StepComponent {
+  node() {
+    const {
+      of,
+      duration,
+      delay,
+      fill,
+      stagger
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      fill,
+      kind: 'hold',
+      name: this.args.name,
+      ms: msOf(duration),
+      of,
+      props: propsOf(this.args),
+      stagger: msOf(stagger)
+    };
+  }
+}
+/**
+ * `<c.Wait />` — a hole in a sequence. It has no subject: `@of` is accepted
+ * (a wait can be laddered across sprites with `@stagger`) but never needed.
+ */
+class Wait extends StepComponent {
+  node() {
+    const {
+      of,
+      duration,
+      delay,
+      stagger
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      kind: 'wait',
+      name: this.args.name,
+      ms: duration * 1000,
+      of,
+      stagger: msOf(stagger)
+    };
+  }
+}
+/**
+ * `<c.Perform />` — a semantic command on the timeline (§C4). It occupies
+ * an instant, positioned like any step (sequence order, `@at`, `@delay`),
+ * and carries `@action` (required), `@target` and `@payload` to the
+ * region's dispatcher (`<Choreo @onPerform>`). The fold's law: forward
+ * playback dispatches it once as the clock crosses it; a seek past it
+ * includes it; a seek before it resets the host and replays the remaining
+ * prefix. Commands are idempotent statements of state — `lightbox.open`,
+ * never `lightbox.toggle`.
+ */
+class Perform extends StepComponent {
+  node() {
+    const {
+      action,
+      delay,
+      payload,
+      target
+    } = this.args;
+    return {
+      action,
+      at: this.args.at,
+      delay: msOf(delay),
+      kind: 'perform',
+      name: this.args.name,
+      payload,
+      target
+    };
+  }
+}
+/**
+ * `<c.Scroll />` — animate the sprite's scroll container so the sprite lands
+ * at `@align`; occupies the sequence like any step (§6.1).
+ */ /**
+    * `<c.Attach @region @duration />` — drive another region's run over a
+    * window of this one's clock. Positioned like any step (sequence order,
+    * `@at`, `@delay`); `@in` and `@rate` map the window onto the child's own
+    * seconds; `@end` says what happens past it; `@exact` refuses a child
+    * that cannot be driven exactly (a spring, a follow).
+    */
+class Attach extends StepComponent {
+  node() {
+    const {
+      delay,
+      duration,
+      end,
+      exact,
+      rate,
+      region
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      end,
+      exact,
+      in: this.args.in,
+      kind: 'attach',
+      ms: duration * 1000,
+      name: this.args.name,
+      rate,
+      region
+    };
+  }
+}
+class Scroll extends StepComponent {
+  node() {
+    const {
+      of,
+      align,
+      duration,
+      delay,
+      stagger
+    } = this.args;
+    return {
+      align,
+      at: this.args.at,
+      delay: msOf(delay),
+      kind: 'scroll',
+      ms: msOf(duration),
+      name: this.args.name,
+      of,
+      stagger: msOf(stagger)
+    };
+  }
+}
+/**
+ * `<c.Raise />` — promote the sprites to the region's elevated layer for the
+ * span of its block (or `@duration`): above every stacking context and clip
+ * in the region, with measured continuity both ways. `@shadow` casts on the
+ * layer below (§6.3).
+ */
+class Raise extends StepComponent {
+  node() {
+    const {
+      of,
+      duration,
+      delay,
+      shadow,
+      stagger
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      kind: 'raise',
+      ms: msOf(duration),
+      name: this.args.name,
+      of,
+      shadow,
+      stagger: msOf(stagger)
+    };
+  }
+}
+/**
+ * `<c.Camera />` — the region's frame as a step (§6.3): `@zoom` / `@x` /
+ * `@y` animate the scene, `@origin` aims the zoom at a sprite, `@steady`
+ * names sprites that keep their size against it (damped by default).
+ * `@fit` is the other, more common shape — dive on this sprite and CENTRE
+ * it, zoom and pan computed from rest-layout geometry (`@margin` sets the
+ * share of the frame it fills); pass `null` to fit nothing: back to rest.
+ */
+class Camera extends StepComponent {
+  node() {
+    const {
+      duration,
+      ease,
+      delay,
+      fit,
+      margin,
+      origin,
+      spring,
+      steady
+    } = this.args;
+    const {
+      x,
+      y,
+      zoom
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      ease,
+      fit,
+      kind: 'camera',
+      margin,
+      ms: msOf(duration),
+      name: this.args.name,
+      of: this.args.of ?? {},
+      origin,
+      spring,
+      steady,
+      x,
+      y,
+      zoom
+    };
+  }
+}
+/**
+ * `<c.Camera3D @yaw={{-24}} @pitch={{-6}} @dolly={{0.9}} />` — the shot,
+ * for a scene Choreo is not the one drawing.
+ *
+ * `c.Camera` moves the region's own frame, which is a 2D transform on real
+ * DOM. A 3D scene has no such frame: its camera belongs to whatever is
+ * rendering it. So this step carries the POSE and nothing else — yaw and
+ * pitch in degrees, dolly as a multiple of the host's own framing — and
+ * the region hands it to `@onCamera3D` every frame it changes. The host
+ * applies it to three.js, to a CSS 3D stage, to anything that takes three
+ * numbers.
+ *
+ * What Choreo keeps is the part it is actually good at: the pose is a pure
+ * function of the clock, so a scrub lands the shot exactly where playing
+ * there would, and a preset expands into this one seekable cue rather than
+ * a second scheduler.
+ *
+ * `@by` makes it relative — added to the pose in force when the cue
+ * starts, the way `Pan` and `SlowZoom` are relative — so a drift composes
+ * with whatever shot preceded it.
+ */
+class Camera3D extends StepComponent {
+  node() {
+    const {
+      by,
+      delay,
+      dolly,
+      duration,
+      ease,
+      look,
+      pitch,
+      settle,
+      spring,
+      tension,
+      through,
+      x,
+      y,
+      yaw
+    } = this.args;
+    return {
+      at: this.args.at,
+      by,
+      delay: msOf(delay),
+      dolly,
+      ease,
+      kind: 'camera3d',
+      look,
+      ms: msOf(duration),
+      name: this.args.name,
+      of: this.args.of ?? {},
+      pitch,
+      settle,
+      spring,
+      tension,
+      through,
+      x,
+      y,
+      yaw
+    };
+  }
+}
+/* ---- the direction vocabulary (notes/choreo-composition.md C5) ----
+   Presets expand into the SAME seekable camera cue — sugar, never a new
+   runtime primitive. Frame and Aim are absolute (computed from measured
+   geometry at compile); Pan and SlowZoom are RELATIVE, resolved against
+   the pose in force when the cue starts, so they compose with whatever
+   shot preceded them and reconstruct under random access like any cue. */ /**
+                                                                           * `<c.Frame @of={{c.id 'hero'}} @padding={{0.8}} />` — fit-and-centre the
+                                                                           * target: the fit camera under its editorial name. `@padding` is the
+                                                                           * share of the frame the target fills on whichever axis fits first.
+                                                                           */
+class Frame extends StepComponent {
+  node() {
+    const {
+      duration,
+      ease,
+      delay,
+      of,
+      padding,
+      spring,
+      steady
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      ease,
+      fit: of,
+      kind: 'camera',
+      margin: padding,
+      ms: msOf(duration),
+      name: this.args.name,
+      of: {},
+      spring,
+      steady
+    };
+  }
+}
+/**
+ * `<c.Aim @of={{c.id 'hero'}} />` — recentre the picture on the target
+ * with the zoom HELD: the reframe that does not change magnification.
+ */
+class Aim extends StepComponent {
+  node() {
+    const {
+      duration,
+      ease,
+      delay,
+      of,
+      spring,
+      steady
+    } = this.args;
+    return {
+      aim: of,
+      at: this.args.at,
+      delay: msOf(delay),
+      ease,
+      kind: 'camera',
+      ms: msOf(duration),
+      name: this.args.name,
+      of: {},
+      spring,
+      steady
+    };
+  }
+}
+/**
+ * `<c.Pan @x={{40}} @y={{-20}} />` — shift the picture by exactly this
+ * many pixels from wherever it stands. Relative on purpose: a pan after
+ * any shot means "from here", not "to there".
+ */
+class Pan extends StepComponent {
+  node() {
+    const {
+      duration,
+      ease,
+      delay,
+      spring,
+      steady,
+      x,
+      y
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      ease,
+      kind: 'camera',
+      ms: msOf(duration),
+      name: this.args.name,
+      of: {},
+      panBy: {
+        x,
+        y
+      },
+      spring,
+      steady
+    };
+  }
+}
+/**
+ * `<c.SlowZoom @by={{1.05}} @duration={{2}} />` — multiply the zoom in
+ * force: the push-in (or, below 1, the pull-back) that gives a hold its
+ * life. The aim in force is kept, so it pushes toward what the previous
+ * shot was looking at.
+ */
+class SlowZoom extends StepComponent {
+  node() {
+    const {
+      by,
+      duration,
+      ease,
+      delay,
+      spring,
+      steady
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      ease,
+      kind: 'camera',
+      ms: msOf(duration),
+      name: this.args.name,
+      of: {},
+      spring,
+      steady,
+      zoomBy: by
+    };
+  }
+}
+/**
+ * `<c.Tether />` — geometry continuously derived from sprites (§6.1):
+ * `@path` receives both endpoints' region-relative boxes every frame and
+ * returns the path data the wire draws.
+ */
+class Tether extends StepComponent {
+  node() {
+    const {
+      duration,
+      delay,
+      from,
+      path,
+      to
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(delay),
+      from,
+      kind: 'tether',
+      ms: msOf(duration),
+      name: this.args.name,
+      of: this.args.of,
+      path,
+      to
+    };
+  }
+}
+/**
+ * `<c.Crossing />` — the canned scene crossing (§4.7): what only the old
+ * scene had fades as the flight lifts off, everything paired flies (skins
+ * swapping per `@swap`), and what only the new scene has fades in near the
+ * settle. One step in the template; a whole overlapped score on the clock —
+ * Keynote's Magic Move does not wait for the dissolve to finish before the
+ * movers leave, and a crossing that does reads as three acts, not one.
+ *
+ * It is also the reference COMPOSITE step, and deliberately written in
+ * nothing but the public seam (`StepComponent`, `toMs`, `at`, and node
+ * literals): if this needed a privilege an author could not have, the
+ * contract on `StepComponent` would be a lie.
+ */
+class Crossing extends StepComponent {
+  /**
+  * The flight is addressable from outside — `{{at 'page:flight' 0.5}}`
+  * for a step that wants to ride the move itself. Derived from this
+  * crossing's own `@name` rather than fixed, so two crossings in one
+  * timeline do not collide over it; unnamed, it takes a per-instance
+  * number, which is stable for the life of the component and so does not
+  * disturb the tree fingerprint between passes.
+  */
+  flightName = `${this.args.name ?? `crossing-${++crossings}`}:flight`;
+  node() {
+    const {
+      arrive = 0.22,
+      duration,
+      ease,
+      leave = 0.18,
+      overlap = 0.7,
+      size = 'crop',
+      spring,
+      swap
+    } = this.args;
+    const FLIGHT = this.flightName;
+    return {
+      at: this.args.at,
+      delay: toMs(this.args.delay),
+      name: this.args.name,
+      children: [{
+        generic: true,
+        kind: 'tween',
+        ms: toMs(leave),
+        of: {
+          onstage: true,
+          type: 'departed'
+        },
+        props: {
+          opacity: 0
+        }
+      }, {
+        ease,
+        generic: true,
+        kind: 'move',
+        ms: toMs(duration),
+        name: FLIGHT,
+        of: {
+          type: 'received'
+        },
+        // iOS's rule: uniform scale matched by cover, the aspect mismatch
+        // cropped by the interpolating window — never a stretch, and
+        // never layout (a receiver animating real width/height reflows
+        // its whole row for the flight). Overridable; the default stays
+        // crop so a crossing in a grid cannot stretch the row.
+        size,
+        spring,
+        swap
+      }, {
+        generic: true,
+        kind: 'hold',
+        of: {
+          type: 'received'
+        },
+        props: {
+          zIndex: 2
+        }
+      }, {
+        at: at(FLIGHT, overlap),
+        generic: true,
+        kind: 'tween',
+        ms: toMs(arrive),
+        of: {
+          onstage: true,
+          type: 'inserted'
+        },
+        props: {
+          opacity: [0, 1]
+        }
+      }],
+      kind: 'parallel'
+    };
+  }
+}
+/**
+ * `<c.Follow />` — a value DERIVED from the scene rather than interpolated
+ * between two keyframes (§4.10). `@to` names what to read; `@read` gets
+ * the pass's measurements every frame — each source's resting boxes
+ * (`from`, `to`) and its composed position this frame (`now`), plus the
+ * follower's own `rest` — and returns the properties to write; `@rest`
+ * says what those properties are when nothing is driving them, so a
+ * measure pass can put the element back.
+ *
+ * ```gts
+ * <c.Follow @of={{c.id 'badge'}} @to={{c.id 'card'}}
+ *           @read={{corner}} @rest={{hash x=0 y=0}} />
+ * ```
+ *
+ * `@read` never sees the live page. Everything it is handed was measured
+ * by the pass or composed from the run's own values, so it cannot read
+ * back what it wrote last frame and it cannot force a style recalculation
+ * mid-move — pure by construction, and correct under interruption because
+ * a replacement pass re-measures (docs/postmortem-follow.md).
+ *
+ * Three things it is not: it is not accelerated (a derived value is
+ * computed on the main thread, every frame — the price, and the same one
+ * `c.Tether` pays); it may not write layout, only transform, opacity and
+ * filter; and `@read` must still be a pure function of its context,
+ * because the run is scrubbable in both directions and a value with
+ * memory could not be sought back to.
+ */
+class Follow extends StepComponent {
+  node() {
+    const {
+      duration,
+      of,
+      read,
+      rest,
+      to
+    } = this.args;
+    return {
+      at: this.args.at,
+      delay: msOf(this.args.delay),
+      kind: 'follow',
+      ms: msOf(duration),
+      name: this.args.name,
+      of,
+      read,
+      rest,
+      stagger: msOf(this.args.stagger),
+      to
+    };
+  }
+}
+/**
+ * `<c.Gate />` — park the run until `c.advance()`; `@delay` opens it by
+ * itself after that many seconds (§4.1). A gate is a pause, and a pause is
+ * a total order: it may only stand in a sequence that no parallel contains.
+ */
+class Gate extends Component {
+  node() {
+    return {
+      kind: 'gate',
+      ms: msOf(this.args.delay)
+    };
+  }
+  mark = modifier(el => {
+    providers.set(el, this);
+    return () => providers.delete(el);
+  });
+  static {
+    setComponentTemplate(precompileTemplate("<span hidden data-choreo-step {{this.mark}}></span>", {
+      strictMode: true
+    }), this);
+  }
+}
+/**
+ * A block is a step's equal to the anchor system: it takes `@name`, `@at`
+ * and `@delay` on the same terms, so a composite step — a `node()` that
+ * returns a block — is something the rest of the score can point at.
+ */
+class BlockComponent extends Component {
+  el;
+  node() {
+    return {
+      at: this.args.at,
+      children: this.el ? collect(this.el) : [],
+      delay: msOf(this.args.delay),
+      kind: this.kind,
+      name: this.args.name
+    };
+  }
+  mark = modifier(el => {
+    this.el = el;
+    providers.set(el, this);
+    return () => {
+      providers.delete(el);
+      this.el = undefined;
+    };
+  });
+  static {
+    setComponentTemplate(precompileTemplate("<span hidden data-choreo-block {{this.mark}}>{{yield}}</span>", {
+      strictMode: true
+    }), this);
+  }
+}
+class Sequence extends BlockComponent {
+  kind = 'sequence';
+}
+class Parallel extends BlockComponent {
+  kind = 'parallel';
+}
+
+export { Aim, Attach, Camera, Camera3D, Crossing, Follow, Frame, Gate, Hold, Move, Pan, Parallel, Perform, Raise, Scroll, Sequence, SlowZoom, Spring, StepComponent, Tether, Tween, Wait, collect, toMs };
+//# sourceMappingURL=steps.js.map