@ethlete/cli 3.0.0-next.24 → 3.0.0-next.26

package/design/mark-part.ts

@@ -5,6 +5,11 @@ const SKIPPED = /^(?:\s+|<!--[\s\S]*?-->|<(style|script)\b[\s\S]*?<\/\1\s*>|<lin
 const TAG = /^<[a-zA-Z][\w:-]*/;
 const ATTRIBUTES = /^(?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*/;
 const MARK = /(\sdata-et-part=")([^"]*)"/;
+const SLOT = /(\sdata-et-slot=")([^"]*)"/;
+const TAG_AT = /<[a-zA-Z][\w:-]*/y;
+const ATTRIBUTES_AT = new RegExp(ATTRIBUTES.source.slice(1), 'y');
+const RAW_TEXT = new Set(['script', 'style', 'textarea', 'title']);
+const MAX_PROP_DEPTH = 4;
 
 const attributesAtOf = (body: string) => {
   let at = 0;
@@ -43,10 +48,82 @@ export const forceBody = (body: string, interaction: Interaction) => {
   return `${body.slice(0, attributesAt)}${forced}${body.slice(attributesAt)}`;
 };
 
+/** Adds `key` to `data-et-slot` on every element of `markup`: the markup a host passes into the part `key` through its props. */
+export const markSlot = (markup: string, key: string) => {
+  let marked = '';
+  let at = 0;
+
+  for (let open = markup.indexOf('<'); open >= 0; open = markup.indexOf('<', at)) {
+    if (markup.startsWith('<!--', open)) {
+      const close = markup.indexOf('-->', open + 4);
+      const end = close < 0 ? markup.length : close + 3;
+
+      marked += markup.slice(at, end);
+      at = end;
+      continue;
+    }
+
+    TAG_AT.lastIndex = open;
+    const tag = TAG_AT.exec(markup);
+
+    if (!tag) {
+      marked += markup.slice(at, open + 1);
+      at = open + 1;
+      continue;
+    }
+
+    const attributesAt = open + tag[0].length;
+
+    ATTRIBUTES_AT.lastIndex = attributesAt;
+    const attributes = ATTRIBUTES_AT.exec(markup)?.[0] ?? '';
+    const slot = SLOT.exec(attributes);
+
+    if (slot) {
+      const valueEnd = attributesAt + slot.index + (slot[1]?.length ?? 0) + (slot[2]?.length ?? 0);
+
+      marked += `${markup.slice(at, valueEnd)} ${key}`;
+      at = valueEnd;
+    } else {
+      marked += `${markup.slice(at, attributesAt)} data-et-slot="${key}"`;
+      at = attributesAt;
+    }
+
+    const name = tag[0].slice(1).toLowerCase();
+
+    if (RAW_TEXT.has(name)) {
+      const close = markup.toLowerCase().indexOf(`</${name}`, attributesAt);
+      const end = close < 0 ? markup.length : close;
+
+      marked += markup.slice(at, end);
+      at = end;
+    }
+  }
+
+  return marked + markup.slice(at);
+};
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype;
+
+const slotProps = (value: unknown, { key, depth = 0 }: { key: string; depth?: number }): unknown => {
+  const inner = { key, depth: depth + 1 };
+
+  if (typeof value === 'string') return /<[a-zA-Z]/.test(value) ? markSlot(value, key) : value;
+  if (depth >= MAX_PROP_DEPTH) return value;
+  if (Array.isArray(value)) return value.map((item) => slotProps(item, inner));
+  if (isPlainObject(value))
+    return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, slotProps(item, inner)]));
+
+  return value;
+};
+
 const markDrawing = <TDrawing extends Drawing>(drawn: TDrawing, key: string): TDrawing =>
   typeof drawn?.body === 'string' ? { ...drawn, body: markBody(drawn.body, key) } : drawn;
 
-/** The part with a `render` that marks the first element of each drawing as the root of the part `key`. */
+/**
+ * The part with a `render` that marks the first element of each drawing as the root of the part `key`, and every
+ * element of the markup its props pass in as slotted into `key`.
+ */
 export const markPart = <TProps, TState extends string>(
   part: Part<TProps, TState>,
   key: string,
@@ -58,7 +135,7 @@ export const markPart = <TProps, TState extends string>(
   return {
     ...part,
     render: (props: TProps, options?: RenderOptions) => {
-      const drawn = render.call(part, props, options);
+      const drawn = render.call(part, slotProps(props, { key }) as TProps, options);
 
       return drawn instanceof Promise ? drawn.then((done) => markDrawing(done, key)) : markDrawing(drawn, key);
     },

package/design/motion-drive.ts

@@ -0,0 +1,215 @@
+import { SteppedMotion } from './motion-runtime';
+
+/** What the Studio timeline posts into a live frame to drive a motion of its part. */
+export type MotionDriveMessage =
+  | { type: 'design-explore:motion-start'; motion: string; reduced: boolean }
+  | { type: 'design-explore:motion-seek'; ms: number; rate: number }
+  | { type: 'design-explore:motion-play'; ms: number; rate: number }
+  | { type: 'design-explore:motion-stop' };
+
+/** What a live frame posts back once a motion started, or failed to. */
+export type MotionDriveReply =
+  | { type: 'design-explore:motion-ready'; motion: string }
+  | { type: 'design-explore:motion-failed'; motion: string; error: string };
+
+const TAIL_MS = 30000;
+
+const isTime = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+const isRate = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value > 0;
+
+/** The drive message `data` holds, or `null` for any other message. */
+export const motionDriveMessageOf = (data: unknown): MotionDriveMessage | null => {
+  if (typeof data !== 'object' || data === null) return null;
+
+  const message = data as Record<string, unknown>;
+
+  switch (message['type']) {
+    case 'design-explore:motion-start':
+      return typeof message['motion'] === 'string'
+        ? { type: message['type'], motion: message['motion'], reduced: message['reduced'] === true }
+        : null;
+    case 'design-explore:motion-seek':
+    case 'design-explore:motion-play':
+      return isTime(message['ms']) && isRate(message['rate'])
+        ? { type: message['type'], ms: message['ms'], rate: message['rate'] }
+        : null;
+    case 'design-explore:motion-stop':
+      return { type: message['type'] };
+    default:
+      return null;
+  }
+};
+
+const REDUCED_FEATURE = /\(\s*prefers-reduced-motion\s*(?::\s*(reduce|no-preference)\s*)?\)/g;
+const ALWAYS = '(min-width: 0px)';
+const NEVER = '(max-width: -1px)';
+
+type MediaHolder = CSSRule & { media: MediaList };
+
+const mediaRulesOf = (rules: CSSRuleList): MediaHolder[] =>
+  [...rules].flatMap((rule) =>
+    'cssRules' in rule
+      ? [...('media' in rule ? [rule as MediaHolder] : []), ...mediaRulesOf((rule as CSSGroupingRule).cssRules)]
+      : [],
+  );
+
+const sheetRulesOf = (sheet: CSSStyleSheet) => {
+  try {
+    return mediaRulesOf(sheet.cssRules);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Makes every `prefers-reduced-motion` media rule of `document` match as if the user asked for `reduced` motion, and
+ * returns a function that puts the rules back. Scripts that call `matchMedia` still see the real preference.
+ */
+export const emulateReducedMotion = (document: Document, reduced: boolean) => {
+  const changed = [...document.styleSheets].flatMap(sheetRulesOf).flatMap((rule) => {
+    const original = rule.media.mediaText;
+    const emulated = original.replace(REDUCED_FEATURE, (_, value?: string) =>
+      (value === 'no-preference' ? !reduced : reduced) ? ALWAYS : NEVER,
+    );
+
+    if (emulated === original) return [];
+
+    rule.media.mediaText = emulated;
+
+    return [{ rule, original }];
+  });
+
+  return () => {
+    for (const { rule, original } of changed) rule.media.mediaText = original;
+  };
+};
+
+/**
+ * Drives a motion in a live frame from drive messages: `start` (re)starts the motion from its `from` state, a seek
+ * pauses every animation of the document at that time, play runs the motion's clock and animations at `rate`, and
+ * stop resumes every animation at 1x. `released` hears each stop.
+ */
+export const createMotionDriver = (options: {
+  document: Document;
+  start: (motion: string, reduced: boolean) => Promise<SteppedMotion>;
+  reply: (reply: MotionDriveReply) => void;
+  released?: () => void;
+  frame?: (step: (time: number) => void) => unknown;
+}) => {
+  const { document, reply } = options;
+  const frame = options.frame ?? ((step: (time: number) => void) => requestAnimationFrame(step));
+  let started: { motion: string; reduced: boolean } | null = null;
+  let stepped: SteppedMotion | null = null;
+  let loop = 0;
+  let queue: Promise<void> = Promise.resolve();
+
+  const holdAll = (rate: number) => {
+    for (const animation of document.getAnimations()) {
+      animation.pause();
+      animation.playbackRate = rate;
+    }
+  };
+
+  const resumeAll = () => {
+    for (const animation of document.getAnimations()) {
+      const end = animation.effect?.getComputedTiming().endTime;
+
+      animation.playbackRate = 1;
+
+      if (typeof end === 'number' && Number.isFinite(end) && Number(animation.currentTime ?? 0) >= end)
+        animation.finish();
+      else animation.play();
+    }
+  };
+
+  const run = (play: { motion: SteppedMotion; from: number; rate: number; step: () => void }) => {
+    const { motion, rate, step } = play;
+    const id = ++loop;
+    let time = play.from;
+    let last: number | null = null;
+
+    const tick = (now: number) => {
+      if (id !== loop) return;
+
+      time += (now - (last ?? now)) * rate;
+      last = now;
+      motion.seek(Math.min(time, TAIL_MS));
+      step();
+
+      if (time < TAIL_MS) frame(tick);
+    };
+
+    frame(tick);
+  };
+
+  const moveTo = (ms: number): Promise<SteppedMotion | null> => {
+    if (!stepped || !started) return Promise.resolve(null);
+    if (ms >= stepped.now()) {
+      stepped.seek(ms);
+
+      return Promise.resolve(stepped);
+    }
+
+    return options.start(started.motion, started.reduced).then((restarted) => {
+      stepped = restarted;
+      restarted.seek(ms);
+
+      return restarted;
+    });
+  };
+
+  const handled = (message: MotionDriveMessage): Promise<void> => {
+    loop++;
+
+    switch (message.type) {
+      case 'design-explore:motion-start':
+        started = { motion: message.motion, reduced: message.reduced };
+        stepped = null;
+
+        return options.start(message.motion, message.reduced).then(
+          (motion) => {
+            stepped = motion;
+            reply({ type: 'design-explore:motion-ready', motion: message.motion });
+          },
+          (error: unknown) =>
+            reply({
+              type: 'design-explore:motion-failed',
+              motion: message.motion,
+              error: error instanceof Error ? error.message : String(error),
+            }),
+        );
+      case 'design-explore:motion-seek':
+        return moveTo(message.ms).then((motion) => {
+          if (motion) holdAll(message.rate);
+        });
+      case 'design-explore:motion-play':
+        return moveTo(message.ms).then((motion) => {
+          if (!motion) return;
+
+          holdAll(message.rate);
+          run({ motion, from: message.ms, rate: message.rate, step: () => holdAll(message.rate) });
+        });
+      case 'design-explore:motion-stop': {
+        const motion = stepped;
+
+        if (!motion) return Promise.resolve();
+
+        motion.release();
+        resumeAll();
+        options.released?.();
+        run({ motion, from: motion.now(), rate: 1, step: () => undefined });
+
+        return Promise.resolve();
+      }
+    }
+  };
+
+  return {
+    handle: (message: MotionDriveMessage) => {
+      queue = queue.then(() => handled(message)).catch(() => undefined);
+
+      return queue;
+    },
+  };
+};

package/design/motion-runtime.ts

@@ -105,14 +105,23 @@ const measure = (root: Element) => {
   };
 };
 
-/** What a switch of `root` to `markup` does: `motion` names its `play` and `viewTransition`, `clock` the time `ctx.at` runs on. */
-export type StateSwitch = { root: Element; markup: string; motion?: Motion; clock?: MotionClock };
+/**
+ * What a switch of `root` to `markup` does: `motion` names its `play` and `viewTransition`, `clock` the time `ctx.at`
+ * runs on, and `transitioned` hears the View Transition when one starts.
+ */
+export type StateSwitch = {
+  root: Element;
+  markup: string;
+  motion?: Motion;
+  clock?: MotionClock;
+  transitioned?: (transition: ViewTransition) => void;
+};
 
 /**
  * Morphs `root` to `markup`, inside a View Transition when the motion asks for one and the browser has it, then runs
  * the motion's `play`. `ctx.rect` measures in the DOM before the morph. Resolves once `play` has run.
  */
-export const switchState = ({ root, markup, motion, clock }: StateSwitch): Promise<void> => {
+export const switchState = ({ root, markup, motion, clock, transitioned }: StateSwitch): Promise<void> => {
   const rect = motion?.play ? measure(root) : null;
   const apply = () => morph(root, markup);
   const play = () => {
@@ -125,8 +134,13 @@ export const switchState = ({ root, markup, motion, clock }: StateSwitch): Promi
   };
   const document = root.ownerDocument;
 
-  if (motion?.viewTransition && typeof document.startViewTransition === 'function')
-    return document.startViewTransition(apply).updateCallbackDone.then(play);
+  if (motion?.viewTransition && typeof document.startViewTransition === 'function') {
+    const transition = document.startViewTransition(apply);
+
+    transitioned?.(transition);
+
+    return transition.updateCallbackDone.then(play);
+  }
 
   apply();
   play();
@@ -134,6 +148,211 @@ export const switchState = ({ root, markup, motion, clock }: StateSwitch): Promi
   return Promise.resolve();
 };
 
+/** One animation of a motion, in ms from the start of the motion. `iterations` and `end` are `null` when it never ends. */
+export type MotionTrack = {
+  element: string;
+  kind: 'transition' | 'animation' | 'script';
+  name?: string;
+  properties: string[];
+  start: number;
+  delay: number;
+  duration: number;
+  iterations: number | null;
+  easing: string;
+  end: number | null;
+};
+
+/**
+ * A motion paused at its start: `seek` moves it forward to a time in ms, `tracks` lists what ran so far. `release`
+ * stops pausing and posing its animations, so a later `seek` only runs its `ctx.at` steps.
+ */
+export type SteppedMotion = {
+  seek: (ms: number) => void;
+  now: () => number;
+  release: () => void;
+  tracks: () => MotionTrack[];
+  end: () => number;
+  bounds: () => MotionBox;
+};
+
+/** A rectangle in page coordinates. */
+export type MotionBox = { left: number; top: number; right: number; bottom: number };
+
+const KEYFRAME_FIELDS = new Set(['offset', 'computedOffset', 'easing', 'composite']);
+
+const elementOf = (element: Element | null | undefined) =>
+  element?.hasAttribute('data-et-key')
+    ? `[data-et-key="${element.getAttribute('data-et-key')}"]`
+    : element
+      ? [
+          element.tagName.toLowerCase(),
+          element.id ? `#${element.id}` : '',
+          ...[...element.classList].map((name) => `.${name}`),
+        ].join('')
+      : '';
+
+const trackOf = (animation: Animation, start: number): MotionTrack => {
+  const effect = animation.effect as KeyframeEffect | null;
+  const timing = effect?.getComputedTiming();
+  const keyframes = effect && typeof effect.getKeyframes === 'function' ? effect.getKeyframes() : [];
+  const own = effect?.getTiming().easing ?? 'linear';
+  const keyed = keyframes.find((frame) => frame.easing && frame.easing !== 'linear')?.easing;
+  const iterations = timing?.iterations ?? 1;
+  const endTime = Number(timing?.endTime ?? 0);
+  const properties = [
+    ...new Set(
+      keyframes.flatMap((frame) =>
+        Object.keys(frame)
+          .filter((field) => !KEYFRAME_FIELDS.has(field))
+          .map((field) => field.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)),
+      ),
+    ),
+  ];
+  const kind = 'transitionProperty' in animation ? 'transition' : 'animationName' in animation ? 'animation' : 'script';
+
+  return {
+    element: `${elementOf(effect?.target)}${effect?.pseudoElement ?? ''}`,
+    kind,
+    ...(kind === 'animation' ? { name: String((animation as CSSAnimation).animationName) } : {}),
+    properties: kind === 'transition' ? [String((animation as CSSTransition).transitionProperty)] : properties,
+    start,
+    delay: Number(timing?.delay ?? 0),
+    duration: Number(timing?.duration ?? 0),
+    iterations: Number.isFinite(iterations) ? iterations : null,
+    easing: own === 'linear' ? (keyed ?? own) : own,
+    end: Number.isFinite(endTime) ? start + endTime : null,
+  };
+};
+
+/**
+ * Switches `root` to `markup` with `motion` as `switchState` does, on a manual clock, and pauses every animation it
+ * starts, so a caller can step through the motion and draw it at any time from its start. A motion with `interrupt`
+ * switches back to `reverse.markup` at that time, with `reverse.motion` (its `ctx.at` counts from the interrupt and a
+ * View Transition is not used); a forward `ctx.at` step after it is dropped and a cancelled animation ends there.
+ */
+export const stepMotion = (options: {
+  root: Element;
+  markup: string;
+  motion: Motion;
+  reverse?: { markup: string; motion?: Motion };
+}): Promise<SteppedMotion> => {
+  const { root, markup, motion, reverse } = options;
+  const document = root.ownerDocument;
+  const clock = manualClock();
+  const started = new Map<Animation, MotionTrack>();
+  const cut = new Set<Animation>();
+  const interrupt = motion.interrupt;
+  let interrupted = false;
+  let released = false;
+  let lastTask = 0;
+  let ready: Promise<unknown> = Promise.resolve();
+
+  if (interrupt !== undefined && !reverse)
+    throw new Error('design-explore: a motion with interrupt needs the markup of its from state to switch back to');
+
+  const collect = (start: number) => {
+    for (const animation of started.keys()) {
+      const track = started.get(animation);
+
+      if (cut.has(animation) || animation.playState !== 'idle' || !track) continue;
+
+      cut.add(animation);
+      track.end = Math.min(track.end ?? start, start);
+    }
+
+    for (const animation of document.getAnimations()) {
+      if (started.has(animation)) continue;
+
+      if (!released) animation.pause();
+      started.set(animation, trackOf(animation, start));
+    }
+  };
+
+  const pose = (ms: number) => {
+    if (released) return;
+
+    for (const [animation, track] of started)
+      if (!cut.has(animation)) animation.currentTime = Math.max(0, ms - track.start);
+  };
+
+  const timedFrom = (offset: number, live: () => boolean): MotionClock => ({
+    ...clock,
+    at: (ms, fn) =>
+      clock.at(offset + ms, () => {
+        if (!live()) return;
+
+        lastTask = Math.max(lastTask, offset + ms);
+        pose(offset + ms);
+        fn();
+        collect(offset + ms);
+      }),
+  });
+  const timed = timedFrom(0, () => !interrupted);
+
+  return switchState({
+    root,
+    markup,
+    motion,
+    clock: timed,
+    transitioned: (transition) => {
+      ready = transition.ready.catch(() => undefined);
+    },
+  })
+    .then(() => ready)
+    .then(() => {
+      collect(0);
+
+      if (interrupt !== undefined && reverse) {
+        clock.at(interrupt, () => {
+          interrupted = true;
+          lastTask = Math.max(lastTask, interrupt);
+          pose(interrupt);
+          void switchState({
+            root,
+            markup: reverse.markup,
+            motion: reverse.motion ? { ...reverse.motion, viewTransition: false } : undefined,
+            clock: timedFrom(interrupt, () => true),
+          });
+          collect(interrupt);
+        });
+      }
+
+      return {
+        seek: (ms) => {
+          if (ms < clock.now())
+            throw new Error(`design-explore: a motion steps forward only, from ${clock.now()} ms to ${ms} ms`);
+
+          clock.advance(ms - clock.now());
+
+          pose(ms);
+        },
+        now: () => clock.now(),
+        release: () => {
+          released = true;
+        },
+        tracks: () => [...started.values()],
+        end: () => Math.max(lastTask, ...[...started.values()].map((track) => track.end ?? 0)),
+        bounds: () => {
+          const view = document.defaultView;
+          const boxes = [
+            root,
+            ...[...started.keys()].map((animation) => (animation.effect as KeyframeEffect | null)?.target),
+          ]
+            .filter((element): element is Element => !!element)
+            .map((element) => element.getBoundingClientRect())
+            .filter((rect, index) => index === 0 || rect.width > 0 || rect.height > 0);
+
+          return {
+            left: Math.min(...boxes.map((rect) => rect.left)) + (view?.scrollX ?? 0),
+            top: Math.min(...boxes.map((rect) => rect.top)) + (view?.scrollY ?? 0),
+            right: Math.max(...boxes.map((rect) => rect.right)) + (view?.scrollX ?? 0),
+            bottom: Math.max(...boxes.map((rect) => rect.bottom)) + (view?.scrollY ?? 0),
+          };
+        },
+      };
+    });
+};
+
 /**
  * How `runRules` reaches the part: the state drawn first, its `rules` and `motions`, and the markup of a state. `clock`
  * makes the clock of each switch, `switched` hears each finished switch and `failed` each error.