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

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

@@ -162,9 +162,14 @@ export type MotionTrack = {
   end: number | null;
 };
 
-/** A motion paused at its start: `seek` moves it forward to a time in ms, `tracks` lists what ran so far. */
+/**
+ * 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;
@@ -238,6 +243,7 @@ export const stepMotion = (options: {
   const cut = new Set<Animation>();
   const interrupt = motion.interrupt;
   let interrupted = false;
+  let released = false;
   let lastTask = 0;
   let ready: Promise<unknown> = Promise.resolve();
 
@@ -257,12 +263,14 @@ export const stepMotion = (options: {
     for (const animation of document.getAnimations()) {
       if (started.has(animation)) continue;
 
-      animation.pause();
+      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);
   };
@@ -318,6 +326,10 @@ export const stepMotion = (options: {
 
           pose(ms);
         },
+        now: () => clock.now(),
+        release: () => {
+          released = true;
+        },
         tracks: () => [...started.values()],
         end: () => Math.max(lastTask, ...[...started.values()].map((track) => track.end ?? 0)),
         bounds: () => {

package/design/motion-tokens.ts

@@ -0,0 +1,177 @@
+import { MotionTrack } from './motion-runtime';
+
+/** A CSS custom property declared on `:root`, with its computed value. */
+export type MotionToken = { name: string; value: string };
+
+/** A track with the names of the tokens whose value equals its duration or easing, in declaration order. */
+export type NamedMotionTrack = MotionTrack & { durationTokens?: string[]; easingTokens?: string[] };
+
+const KEYWORD_EASINGS: Record<string, string> = {
+  ease: 'cubic-bezier(0.25,0.1,0.25,1)',
+  'ease-in': 'cubic-bezier(0.42,0,1,1)',
+  'ease-out': 'cubic-bezier(0,0,0.58,1)',
+  'ease-in-out': 'cubic-bezier(0.42,0,0.58,1)',
+  'step-start': 'steps(1,jump-start)',
+  'step-end': 'steps(1,jump-end)',
+};
+
+const TIME = /^(-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(ms|s)$/u;
+const EASING_FUNCTION = /^(cubic-bezier|linear|steps)\((.*)\)$/u;
+
+const roundedOf = (value: number) => String(Math.round(value * 10000) / 10000);
+
+const msOf = (value: string) => {
+  const match = TIME.exec(value.trim().toLowerCase());
+
+  return match ? Number(match[1]) * (match[2] === 's' ? 1000 : 1) : null;
+};
+
+const linearOf = (body: string) => {
+  const points: { output: number; input: number | null }[] = [];
+
+  for (const stop of body.split(',')) {
+    const [output = '', ...inputs] = stop.trim().split(/\s+/u);
+    const value = Number(output);
+
+    if (output === '' || !Number.isFinite(value) || inputs.length > 2) return null;
+
+    const percents = inputs.map((input) => (input.endsWith('%') ? Number(input.slice(0, -1)) : Number.NaN));
+
+    if (percents.some((percent) => !Number.isFinite(percent))) return null;
+
+    if (percents.length === 0) points.push({ output: value, input: null });
+    for (const percent of percents) points.push({ output: value, input: percent });
+  }
+
+  if (points.length < 2) return null;
+
+  const first = points[0];
+  const last = points[points.length - 1];
+
+  if (first && first.input === null) first.input = 0;
+  if (last && last.input === null) last.input = Math.max(100, ...points.map((point) => point.input ?? 0));
+
+  let highest = 0;
+
+  for (const point of points) {
+    if (point.input !== null) point.input = Math.max(point.input, highest);
+    highest = point.input ?? highest;
+  }
+
+  for (let index = 1; index < points.length; index++) {
+    if (points[index]?.input !== null) continue;
+
+    const before = index - 1;
+    let after = index;
+
+    while (points[after]?.input === null) after++;
+
+    const from = points[before]?.input ?? 0;
+    const to = points[after]?.input ?? 100;
+
+    for (let gap = index; gap < after; gap++) {
+      const point = points[gap];
+
+      if (point) point.input = from + ((to - from) * (gap - before)) / (after - before);
+    }
+  }
+
+  return `linear(${points.map((point) => `${roundedOf(point.output)} ${roundedOf(point.input ?? 0)}%`).join(',')})`;
+};
+
+/** An easing in one spelling, so `ease` equals `cubic-bezier(.25, .1, .25, 1)`; `null` when it is not an easing. */
+export const normalisedEasingOf = (value: string): string | null => {
+  const easing = value.trim().toLowerCase().replace(/\s+/gu, ' ');
+
+  if (easing === 'linear') return 'linear';
+  if (KEYWORD_EASINGS[easing]) return KEYWORD_EASINGS[easing];
+
+  const match = EASING_FUNCTION.exec(easing);
+
+  if (!match) return null;
+
+  const [, kind = '', body = ''] = match;
+
+  if (kind === 'linear') return linearOf(body);
+
+  const args = body.split(',').map((arg) => arg.trim());
+
+  if (kind === 'steps') return args.length === 1 || args.length === 2 ? `steps(${args[0]},${args[1] ?? 'end'})` : null;
+
+  const numbers = args.map(Number);
+
+  return numbers.length === 4 && numbers.every(Number.isFinite)
+    ? `cubic-bezier(${numbers.map(roundedOf).join(',')})`
+    : null;
+};
+
+/** What a token stands for: a time, an easing, or both as a `spring()` token stores them (`<duration>ms linear(...)`). */
+const meaningOf = (value: string) => {
+  const trimmed = value.trim();
+  const ms = msOf(trimmed);
+
+  if (ms !== null) return { ms, easing: null };
+
+  const [head = '', ...rest] = trimmed.split(/\s+/u);
+  const leading = msOf(head);
+
+  if (leading !== null) {
+    const easing = normalisedEasingOf(rest.join(' '));
+
+    return easing ? { ms: leading, easing } : null;
+  }
+
+  const easing = normalisedEasingOf(trimmed);
+
+  return easing ? { ms: null, easing } : null;
+};
+
+/**
+ * Adds the names of the `tokens` whose value equals a track's duration (`durationTokens`) or easing (`easingTokens`),
+ * in the order of `tokens`; a field without a match is left out.
+ */
+export const withTokenNames = (track: MotionTrack, tokens: readonly MotionToken[]): NamedMotionTrack => {
+  const easing = normalisedEasingOf(track.easing);
+  const durationTokens: string[] = [];
+  const easingTokens: string[] = [];
+
+  for (const token of tokens) {
+    const meaning = meaningOf(token.value);
+
+    if (!meaning) continue;
+    if (meaning.ms !== null && Math.abs(meaning.ms - track.duration) < 0.001) durationTokens.push(token.name);
+    if (meaning.easing !== null && easing !== null && meaning.easing === easing) easingTokens.push(token.name);
+  }
+
+  return {
+    ...track,
+    ...(durationTokens.length ? { durationTokens } : {}),
+    ...(easingTokens.length ? { easingTokens } : {}),
+  };
+};
+
+const rootNamesOf = (rules: CSSRuleList, names: Set<string>) => {
+  for (const rule of [...rules]) {
+    if (rule instanceof CSSStyleRule && /^(:root|html)$/u.test(rule.selectorText.trim()))
+      for (const property of [...rule.style]) if (property.startsWith('--')) names.add(property);
+
+    if ('cssRules' in rule && rule.cssRules instanceof CSSRuleList) rootNamesOf(rule.cssRules, names);
+  }
+};
+
+/** The custom properties declared on `:root` in the stylesheets of `document`, in declaration order, as computed there. */
+export const rootTokensOf = (document: Document): MotionToken[] => {
+  const names = new Set<string>();
+
+  for (const sheet of [...document.styleSheets]) {
+    try {
+      rootNamesOf(sheet.cssRules, names);
+    } catch {
+      continue;
+    }
+  }
+
+  const computed = getComputedStyle(document.documentElement);
+
+  return [...names].map((name) => ({ name, value: computed.getPropertyValue(name).trim() }));
+};

package/design/token-sheet.ts

@@ -18,7 +18,7 @@ const SHEET_STYLES = `
   .ts-root { position: relative; display: flex; flex-direction: column; gap: var(--space-4, 1.6rem); width: 960px; padding: var(--space-6, 2.4rem); box-sizing: border-box; background: var(--surface, oklch(0.17 0 0)); color: var(--text, oklch(0.94 0 0)); font-family: var(--font-ui, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif); font-size: var(--text-md, 1.3rem); line-height: var(--text-md-line, 1.8rem); }
   .ts-title { margin: 0; font-size: var(--text-xl, 1.7rem); line-height: var(--text-xl-line, 2.2rem); font-weight: var(--weight-strong, 600); }
   .ts-note { margin: 0; max-width: 64rem; color: var(--text-muted, oklch(0.72 0 0)); }
-  .ts-panel { margin: 0; padding: var(--space-4, 1.6rem); background: var(--surface, oklch(0.17 0 0)); border: 1px solid var(--surface-border, oklch(0.34 0 0)); border-radius: var(--radius-control-lg, 1rem); }
+  .ts-panel { margin: 0; padding: var(--space-4, 1.6rem); border: 1px solid var(--surface-border, oklch(0.34 0 0)); border-radius: var(--radius-control-lg, 1rem); }
   .ts-list { list-style: none; display: flex; flex-direction: column; gap: var(--space-1, 0.4rem); }
   .ts-row { display: grid; grid-template-columns: 200px 240px 1fr; align-items: center; gap: var(--space-3, 1.2rem); min-height: var(--row, 2.4rem); }
   .ts-name { font-family: var(--font-code, ui-monospace, "SF Mono", Menlo, Consolas, monospace); font-size: var(--text-sm, 1.15rem); line-height: var(--text-sm-line, 1.6rem); color: var(--text-muted, oklch(0.72 0 0)); }

package/design/web/frame-fill.ts

@@ -0,0 +1,4 @@
+/** Paints `body` with the token `--<fill>` over the product's page colour, which shows when the product has no such token. */
+export const paintFill = (body: HTMLElement, fill: string) => {
+  body.style.backgroundImage = `linear-gradient(var(--${fill}), var(--${fill}))`;
+};

package/design/web/frame-fit.ts

@@ -0,0 +1,7 @@
+/** Sizes the frame root to its content; `padded` keeps a 16 px margin around it, which a bare compare shot leaves out. */
+export const fitRoot = (root: HTMLElement, options: { padded: boolean }) => {
+  root.ownerDocument.documentElement.style.overflow = 'hidden';
+  root.style.width = 'max-content';
+
+  if (options.padded) root.style.padding = '16px';
+};

package/design/web/frame-scheme.ts

@@ -0,0 +1,44 @@
+export type ColorScheme = 'light' | 'dark';
+
+const SCHEME_FEATURE = /\(\s*prefers-color-scheme\s*:\s*(light|dark)\s*\)/giu;
+
+/** `media` with each `prefers-color-scheme` feature replaced by one that always or never matches, as `scheme` decides. */
+export const pinnedMediaText = (media: string, scheme: ColorScheme) =>
+  media.replace(SCHEME_FEATURE, (_, wanted: string) =>
+    wanted.toLowerCase() === scheme ? '(width >= 0)' : '(width < 0)',
+  );
+
+const pinRules = (rules: CSSRuleList, scheme: ColorScheme) => {
+  for (const rule of Array.from(rules)) {
+    if (rule instanceof CSSMediaRule) {
+      const pinned = pinnedMediaText(rule.media.mediaText, scheme);
+
+      if (pinned !== rule.media.mediaText) rule.media.mediaText = pinned;
+    }
+
+    if ('cssRules' in rule) pinRules((rule as CSSGroupingRule).cssRules, scheme);
+  }
+};
+
+const pinSheets = (document: Document, scheme: ColorScheme) => {
+  for (const sheet of Array.from(document.styleSheets)) {
+    try {
+      pinRules(sheet.cssRules, scheme);
+    } catch {
+      // A cross-origin sheet hides its rules.
+    }
+  }
+};
+
+export const pinScheme = (document: Document, scheme: ColorScheme) => {
+  document.documentElement.style.colorScheme = scheme;
+  pinSheets(document, scheme);
+
+  new MutationObserver((records) => {
+    pinSheets(document, scheme);
+
+    for (const record of records)
+      for (const node of Array.from(record.addedNodes))
+        if (node instanceof HTMLLinkElement) node.addEventListener('load', () => pinSheets(document, scheme));
+  }).observe(document.head, { childList: true, subtree: true, characterData: true });
+};