@ethlete/cli 3.0.0-next.23 → 3.0.0-next.25

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/morph.ts

@@ -0,0 +1,67 @@
+const keyOf = (node: Node) =>
+  node instanceof Element
+    ? `${node.nodeName}#${node.id}#${node.getAttribute('data-et-key') ?? ''}`
+    : `${node.nodeType}`;
+
+const morphAttributes = (from: Element, to: Element) => {
+  for (const { name } of [...from.attributes]) if (!to.hasAttribute(name)) from.removeAttribute(name);
+
+  for (const { name, value } of [...to.attributes])
+    if (from.getAttribute(name) !== value) from.setAttribute(name, value);
+};
+
+const morphNode = (from: Node, to: Node) => {
+  if (from instanceof Element && to instanceof Element) {
+    morphAttributes(from, to);
+    morphChildren(
+      from instanceof HTMLTemplateElement ? from.content : from,
+      to instanceof HTMLTemplateElement ? to.content : to,
+    );
+  } else if (from.nodeValue !== to.nodeValue) {
+    from.nodeValue = to.nodeValue;
+  }
+};
+
+const morphChildren = (from: Node, to: Node) => {
+  let cursor = from.firstChild;
+
+  for (const next of [...to.childNodes]) {
+    const key = keyOf(next);
+    let match: ChildNode | null = cursor;
+
+    while (match && keyOf(match) !== key) match = match.nextSibling;
+
+    if (match) {
+      while (cursor && cursor !== match) {
+        const removed: ChildNode = cursor;
+
+        cursor = cursor.nextSibling;
+        removed.remove();
+      }
+
+      morphNode(match, next);
+      cursor = match.nextSibling;
+    } else {
+      from.insertBefore(next, cursor);
+    }
+  }
+
+  while (cursor) {
+    const removed: ChildNode = cursor;
+
+    cursor = cursor.nextSibling;
+    removed.remove();
+  }
+};
+
+/**
+ * Turns the children of `root` into `markup` by changing only what differs: attributes, text, and the nodes that
+ * appear or go. A node is kept when its tag, `id` and `data-et-key` match one at the same place, so its CSS
+ * transitions run and a node that appears gets `@starting-style`.
+ */
+export const morph = (root: Element, markup: string) => {
+  const parsed = root.ownerDocument.createElement('template');
+
+  parsed.innerHTML = markup;
+  morphChildren(root, parsed.content);
+};

package/design/motion-runtime.ts

@@ -0,0 +1,407 @@
+import { Motion, MotionContext, PartRule } from './define-part';
+import { morph } from './morph';
+
+/** The time of a motion in ms from its start: `at` runs `fn` once `now` reaches `ms`, `advance` moves time on. */
+export type MotionClock = {
+  now: () => number;
+  at: (ms: number, fn: () => void) => void;
+  advance: (ms: number) => void;
+};
+
+/** A clock that only moves when `advance` is called, so a caller can pause and step a motion. */
+export const manualClock = (): MotionClock => {
+  let time = 0;
+  let queue: { ms: number; fn: () => void }[] = [];
+
+  return {
+    now: () => time,
+    at: (ms, fn) => {
+      queue.push({ ms, fn });
+    },
+    advance: (ms) => {
+      const target = time + ms;
+
+      for (;;) {
+        const due = queue.reduce<{ ms: number; fn: () => void } | null>(
+          (first, task) => (task.ms <= target && (!first || task.ms < first.ms) ? task : first),
+          null,
+        );
+
+        if (!due) break;
+
+        queue = queue.filter((task) => task !== due);
+        time = Math.max(time, due.ms);
+        due.fn();
+      }
+
+      time = target;
+    },
+  };
+};
+
+/** A clock that follows real time while it has work, one step per animation frame. */
+export const realTimeClock = (
+  frame: (step: () => void) => void = (step) => requestAnimationFrame(step),
+  wall: () => number = () => performance.now(),
+): MotionClock => {
+  const clock = manualClock();
+  let waiting = 0;
+  let last: number | null = null;
+
+  const tick = () => {
+    const now = wall();
+
+    clock.advance(now - (last ?? now));
+    last = now;
+
+    if (waiting > 0) frame(tick);
+    else last = null;
+  };
+
+  return {
+    ...clock,
+    at: (ms, fn) => {
+      waiting++;
+      clock.at(ms, () => {
+        waiting--;
+        fn();
+      });
+
+      if (last === null) {
+        last = wall();
+        frame(tick);
+      }
+    },
+  };
+};
+
+/** The same sequence in every run: mulberry32 from a fixed seed. */
+export const seededRandom = (seed = 1) => {
+  let state = seed >>> 0;
+
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+
+    let value = Math.imul(state ^ (state >>> 15), 1 | state);
+
+    value ^= value + Math.imul(value ^ (value >>> 7), 61 | value);
+
+    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+  };
+};
+
+const measure = (root: Element) => {
+  const rects = [...root.querySelectorAll('*')].map((element) => element.getBoundingClientRect());
+  const copy = root.cloneNode(true) as Element;
+  const copies = [...copy.querySelectorAll('*')];
+
+  return (selector: string) => {
+    const found = copy.querySelector(selector);
+    const rect = found ? rects[copies.indexOf(found)] : undefined;
+
+    if (!rect) throw new Error(`design-explore: ctx.rect("${selector}") matches nothing in the from state`);
+
+    return rect;
+  };
+};
+
+/**
+ * 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, transitioned }: StateSwitch): Promise<void> => {
+  const rect = motion?.play ? measure(root) : null;
+  const apply = () => morph(root, markup);
+  const play = () => {
+    if (!motion?.play || !rect) return;
+
+    const time = clock ?? realTimeClock();
+    const ctx: MotionContext = { at: (ms, fn) => time.at(ms, fn), random: seededRandom(), rect };
+
+    motion.play(ctx);
+  };
+  const document = root.ownerDocument;
+
+  if (motion?.viewTransition && typeof document.startViewTransition === 'function') {
+    const transition = document.startViewTransition(apply);
+
+    transitioned?.(transition);
+
+    return transition.updateCallbackDone.then(play);
+  }
+
+  apply();
+  play();
+
+  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. */
+export type SteppedMotion = {
+  seek: (ms: number) => 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 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;
+
+      animation.pause();
+      started.set(animation, trackOf(animation, start));
+    }
+  };
+
+  const pose = (ms: number) => {
+    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);
+        },
+        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.
+ */
+export type PartRules = {
+  state: string;
+  rules: PartRule[];
+  motions?: Record<string, Motion>;
+  render: (state: string) => string | Promise<string>;
+  clock?: () => MotionClock;
+  switched?: (state: string) => void;
+  failed?: (error: unknown) => void;
+};
+
+/**
+ * Runs the rules of a part in `root`: an event that matches a rule's `on`, such as `click .open`, morphs the part to the
+ * rule's state with the motion it names. Switches run one after another. Returns a function that stops the rules.
+ */
+export const runRules = (root: HTMLElement, part: PartRules) => {
+  let current = part.state;
+  let queue = Promise.resolve();
+  const types = [...new Set(part.rules.map((rule) => rule.on.trim().split(/\s+/u)[0] ?? ''))].filter(Boolean);
+
+  const go = (rule: PartRule) => {
+    queue = queue
+      .then(() => (rule.to === current ? null : part.render(rule.to)))
+      .then((markup) => {
+        if (markup === null) return;
+
+        current = rule.to;
+
+        return switchState({
+          root,
+          markup,
+          motion: rule.motion ? part.motions?.[rule.motion] : undefined,
+          clock: part.clock?.(),
+        }).then(() => part.switched?.(rule.to));
+      })
+      .catch((error: unknown) => (part.failed ?? console.error)(error));
+  };
+
+  const listener = (event: Event) => {
+    const target = event.target instanceof Element ? event.target : null;
+    const rule = part.rules.find((entry) => {
+      const [type = '', ...rest] = entry.on.trim().split(/\s+/u);
+      const selector = rest.join(' ');
+
+      if (type !== event.type) return false;
+      if (!selector) return true;
+
+      const matched = target?.closest(selector);
+
+      return matched ? root.contains(matched) : false;
+    });
+
+    if (rule) go(rule);
+  };
+
+  for (const type of types) root.addEventListener(type, listener);
+
+  return () => {
+    for (const type of types) root.removeEventListener(type, listener);
+  };
+};

package/design/spring.ts

@@ -0,0 +1,53 @@
+/** A spring as a CSS easing: `easing` is a `linear(...)` function, `duration` the ms until it settles; as a string, `<duration>ms <easing>`. */
+export type Spring = { easing: string; duration: number; toString: () => string };
+
+const SETTLED = 0.001;
+const LONGEST_MS = 10000;
+
+const positionOf = (damping: number, frequency: number) => {
+  const natural = 2 * Math.PI * frequency;
+
+  if (damping < 1) {
+    const damped = natural * Math.sqrt(1 - damping * damping);
+    const decay = damping * natural;
+
+    return (seconds: number) =>
+      1 - Math.exp(-decay * seconds) * (Math.cos(damped * seconds) + (decay / damped) * Math.sin(damped * seconds));
+  }
+
+  if (damping === 1) return (seconds: number) => 1 - Math.exp(-natural * seconds) * (1 + natural * seconds);
+
+  const root = Math.sqrt(damping * damping - 1);
+  const slow = -natural * (damping - root);
+  const fast = -natural * (damping + root);
+
+  return (seconds: number) => 1 - (fast * Math.exp(slow * seconds) - slow * Math.exp(fast * seconds)) / (fast - slow);
+};
+
+/**
+ * Samples a spring that moves from 0 to 1 at rest, for a motion token in `foundations`, e.g.
+ * `--motion-capsule: ${spring({ damping: 0.6, frequency: 2 })}`. `damping` is the damping ratio (below 1 it
+ * overshoots) and `frequency` the undamped frequency in Hz.
+ */
+export const spring = (options: { damping: number; frequency: number }): Spring => {
+  const { damping, frequency } = options;
+
+  if (!(damping > 0) || !(frequency > 0) || !Number.isFinite(damping) || !Number.isFinite(frequency))
+    throw new Error(
+      `design-explore: spring() needs a damping and a frequency above 0, got ${damping} and ${frequency}`,
+    );
+
+  const position = positionOf(damping, frequency);
+  let last = 0;
+
+  for (let ms = 0; ms <= LONGEST_MS; ms++) if (Math.abs(1 - position(ms / 1000)) >= SETTLED) last = ms;
+
+  const duration = Math.max(1, last + 1);
+  const count = Math.min(200, Math.max(10, Math.ceil(duration / 16)));
+  const points = Array.from({ length: count + 1 }, (_, index) =>
+    index === count ? 1 : Math.round(position(((index / count) * duration) / 1000) * 10000) / 10000,
+  );
+  const easing = `linear(${points.join(', ')})`;
+
+  return { easing, duration, toString: () => `${duration}ms ${easing}` };
+};