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

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/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}` };
+};

package/design/token-sheet.ts

@@ -0,0 +1,87 @@
+import { Drawing, html } from './define-call';
+
+export type TokenSheetOptions = {
+  title: string;
+  note?: string;
+  scope?: string;
+  css: string;
+  sample: string;
+  sampleOf: (name: string) => string;
+  sampleClass?: string;
+  only?: (name: string) => boolean;
+  pixels?: boolean;
+  styles?: string;
+  setup?: (root: HTMLElement) => void;
+};
+
+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-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)); }
+  .ts-value { 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); overflow-wrap: anywhere; }
+  .ts-sample { display: flex; align-items: center; min-width: 0; }
+  .ts-probe { position: absolute; left: 0; top: 0; height: 0; visibility: hidden; }
+`;
+
+const tokenNamesOf = (css: string, only: (name: string) => boolean) => [
+  ...new Set([...css.matchAll(/^\s*--([\w-]+):/gmu)].map(([, name]) => name ?? '').filter(only)),
+];
+
+const fillTokenValues = (root: HTMLElement, pixels: boolean) => {
+  const sheet = root.querySelector<HTMLElement>('.ts-root') ?? root;
+  const style = getComputedStyle(sheet);
+  const probe = sheet.querySelector<HTMLElement>('.ts-probe');
+
+  for (const cell of sheet.querySelectorAll<HTMLElement>('[data-token]')) {
+    const value = style.getPropertyValue(`--${cell.dataset['token']}`).trim();
+    let suffix = '';
+    if (pixels && probe && /^[\d.]+rem$/u.test(value)) {
+      probe.style.width = value;
+      suffix = ` · ${Math.round(probe.getBoundingClientRect().width * 10) / 10}px`;
+    }
+    cell.textContent = value + suffix;
+  }
+};
+
+/**
+ * Draws a foundation sheet: a sample panel, then one row per custom property declared in `css` (narrowed by `only`)
+ * with its value as the drawing resolves it, in px too for rem values when `pixels` is set.
+ * `scope` adds classes to the sheet root, so tokens scoped to a theme class resolve; `note` is markup under the title.
+ */
+export const tokenSheet = ({
+  title,
+  note,
+  scope,
+  css,
+  sample,
+  sampleOf,
+  sampleClass = '',
+  only = () => true,
+  pixels = false,
+  styles = '',
+  setup,
+}: TokenSheetOptions): Drawing => ({
+  body: html`<div class="ts-root${scope ? ` ${scope}` : ''}">
+    <h2 class="ts-title">${title}</h2>
+    ${note && html`<p class="ts-note">${note}</p>`}
+    <section class="ts-panel ${sampleClass}">${sample}</section>
+    <ul class="ts-panel ts-list">
+      ${tokenNamesOf(css, only)
+        .map(
+          (name) =>
+            html`<li class="ts-row">
+              <span class="ts-name">--${name}</span><span class="ts-value" data-token="${name}"></span
+              ><span class="ts-sample">${sampleOf(name)}</span>
+            </li>`,
+        )
+        .join('')}
+    </ul>
+    <span class="ts-probe"></span>
+  </div>`,
+  styles: `${SHEET_STYLES}${styles}`,
+  setup: [(root: HTMLElement) => fillTokenValues(root, pixels), ...(setup ? [setup] : [])],
+});

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-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 });
+};