@swiftbrowser/web 0.1.0

package/src/animation.ts

@@ -0,0 +1,521 @@
+/**
+ * Animation for the ops protocol (docs/ops-protocol.md, "Phase 3 additions").
+ *
+ * The renderer records what a render pass did (which elements were updated,
+ * what their styles were before, which were inserted, which were removed and
+ * where they were) and hands the record to the `Animator` at `commit`. When
+ * the commit carries an `animation` (`withAnimation`) or an element's
+ * `animationToken` changed in an `update` (`.animation(_:value:)`), the
+ * Animator animates the changes of that pass with the Web Animations API:
+ *
+ * - style changes (opacity, colors, border radius, font size, transform and
+ *   filter; frames are tweened from the layout engine's boxes) tween from
+ *   the recorded value to the new one;
+ * - inserted elements play their `transition` forwards;
+ * - removed elements leave a visual clone (stripped of element ids) at their
+ *   old position which plays the `transition` backwards and is then dropped.
+ *
+ * `Animation` maps to CSS easings; `spring` becomes a `linear()` easing
+ * sampled from a damped spring where supported.
+ */
+
+import type { Animation, Edge, Transition, TransitionPart } from './protocol';
+import { ghostClone } from './ghost';
+
+/**
+ * Style properties tweened between the value before the pass and after.
+ * Geometry (left/top/width/height) is animated from the layout engine's
+ * frames instead (see `FrameChange`).
+ */
+export const ANIMATED_PROPERTIES = [
+  'opacity',
+  'backgroundColor',
+  'color',
+  'borderRadius',
+  'fontSize',
+  // Phase 6 visual effects (offset / rotation / scale, shadow).
+  'transform',
+  'filter',
+] as const;
+export type AnimatedProperty = (typeof ANIMATED_PROPERTIES)[number];
+
+export type StyleSnapshot = Partial<Record<AnimatedProperty, string>>;
+
+export interface UpdatedRecord {
+  el: HTMLElement;
+  /** Computed values before the update (null when the element was not rendered). */
+  before: StyleSnapshot | null;
+  /** `animationToken` changed in this pass; `animation` is the subtree's. */
+  tokenChanged: boolean;
+  animation?: Animation;
+}
+
+export interface RemovedRecord {
+  el: HTMLElement;
+  /** Ancestors (nearest first) at the time of removal, for token lookup. */
+  ancestors: HTMLElement[];
+  /** Position relative to the animation root, before removal. */
+  rect: DOMRect | null;
+  transition: Transition | undefined;
+}
+
+export interface PassRecord {
+  updated: Map<HTMLElement, UpdatedRecord>;
+  /** Elements attached by `insert` in this pass that were detached before. */
+  inserted: Set<HTMLElement>;
+  removed: RemovedRecord[];
+}
+
+export function emptyPass(): PassRecord {
+  return { updated: new Map(), inserted: new Set(), removed: [] };
+}
+
+export interface FrameRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** An element whose layout box changed in the pass (`from` is null for a new element). */
+export interface FrameChange {
+  el: HTMLElement;
+  kind: string;
+  from: FrameRect | null;
+  to: FrameRect;
+}
+
+export const DEFAULT_DURATION = 0.35;
+export const EASE_IN_OUT = 'cubic-bezier(0.42, 0, 0.58, 1)';
+export const EASE_IN = 'cubic-bezier(0.42, 0, 1, 1)';
+export const EASE_OUT = 'cubic-bezier(0, 0, 0.58, 1)';
+/** Samples of the spring curve in a `linear()` easing. */
+export const SPRING_SAMPLES = 60;
+
+const supportsLinearEasing: boolean =
+  typeof CSS !== 'undefined' && typeof CSS.supports === 'function'
+    ? CSS.supports('animation-timing-function', 'linear(0, 0.5, 1)')
+    : false;
+
+export interface Timing {
+  /** Milliseconds. */
+  duration: number;
+  delay: number;
+  easing: string;
+  /**
+   * Phase 8 `Animation.repeat`: how many times the tween plays (Infinity for
+   * `forever`); absent for a plain animation (WAAPI's default of 1).
+   */
+  iterations?: number;
+  /** Phase 8: `alternate` when the repeat autoreverses; absent otherwise. */
+  direction?: PlaybackDirection;
+}
+
+/**
+ * CSS timing for a protocol `Animation`. The `repeat` fields apply to the
+ * style and frame tweens of a commit (`Animator.animateChanges` /
+ * `animateFrame`); transitions play once, see `baseTiming`.
+ */
+export function timingFor(animation: Animation | undefined): Timing {
+  const a = animation ?? { type: 'default' };
+  const duration = Math.max(0, (a.duration ?? DEFAULT_DURATION) * 1000);
+  const delay = Math.max(0, (a.delay ?? 0) * 1000);
+  const timing: Timing = { duration, delay, easing: easingFor(a) };
+  const repeat = a.repeat;
+  if (repeat && typeof repeat === 'object') {
+    if (repeat.count === 'forever') timing.iterations = Infinity;
+    else if (typeof repeat.count === 'number' && Number.isFinite(repeat.count) && repeat.count > 0) {
+      timing.iterations = repeat.count;
+    }
+    if (repeat.autoreverses === true && timing.iterations !== undefined) timing.direction = 'alternate';
+  }
+  return timing;
+}
+
+/** `timing` without its repeat: enter / exit transitions play once. */
+export function baseTiming(timing: Timing): Timing {
+  return { duration: timing.duration, delay: timing.delay, easing: timing.easing };
+}
+
+/** CSS `animation-timing-function` for a protocol `Animation`. */
+export function easingFor(animation: Animation | undefined): string {
+  switch (animation?.type) {
+    case 'linear':
+      return 'linear';
+    case 'easeIn':
+      return EASE_IN;
+    case 'easeOut':
+      return EASE_OUT;
+    case 'spring':
+      return supportsLinearEasing
+        ? springEasing(animation.duration ?? 0.5, animation.bounce ?? 0)
+        : EASE_IN_OUT;
+    case 'default':
+    case 'easeInOut':
+    default:
+      return EASE_IN_OUT;
+  }
+}
+
+/**
+ * `linear()` easing of a damped spring with SwiftUI's `Spring(duration:bounce:)`
+ * parameterization: natural frequency ω = 2π / duration, damping ratio
+ * ζ = 1 − bounce (so bounce 0 is critically damped and 0.3 overshoots). The
+ * curve is sampled at `SPRING_SAMPLES` points over the perceptual duration,
+ * by which time the spring has settled to within ~1%.
+ */
+export function springEasing(duration: number, bounce: number, samples = SPRING_SAMPLES): string {
+  const d = duration > 0 ? duration : 0.5;
+  const zeta = Math.min(1, Math.max(0, 1 - bounce));
+  const omega = (2 * Math.PI) / d;
+  const points: string[] = [];
+  for (let i = 0; i < samples; i++) {
+    const t = (i / (samples - 1)) * d;
+    points.push(springPosition(t, omega, zeta).toFixed(4));
+  }
+  points[0] = '0';
+  points[samples - 1] = '1';
+  return `linear(${points.join(', ')})`;
+}
+
+function springPosition(t: number, omega: number, zeta: number): number {
+  if (zeta >= 1) {
+    // Critically damped.
+    return 1 - Math.exp(-omega * t) * (1 + omega * t);
+  }
+  const omegaD = omega * Math.sqrt(1 - zeta * zeta);
+  const envelope = Math.exp(-zeta * omega * t);
+  return 1 - envelope * (Math.cos(omegaD * t) + ((zeta * omega) / omegaD) * Math.sin(omegaD * t));
+}
+
+// ---------------------------------------------------------------------------
+// Transitions
+// ---------------------------------------------------------------------------
+
+/** SwiftUI's default transition for views inserted or removed with animation. */
+export const DEFAULT_TRANSITION: Transition = { kind: 'opacity' };
+
+interface TransitionFrame {
+  opacity?: number;
+  transform?: string;
+}
+
+/** Keyframe of the "gone" state of a transition (enter start / exit end). */
+export function transitionStart(transition: Transition | undefined, exit: boolean): TransitionFrame {
+  const acc: { opacity?: number; transforms: string[] } = { transforms: [] };
+  collectTransition(transition ?? DEFAULT_TRANSITION, exit, acc, 0);
+  const frame: TransitionFrame = {};
+  if (acc.opacity !== undefined) frame.opacity = acc.opacity;
+  if (acc.transforms.length) frame.transform = acc.transforms.join(' ');
+  return frame;
+}
+
+/** Nesting limit for `asymmetric` parts (they may nest; a malformed cycle must not recurse forever). */
+const MAX_TRANSITION_DEPTH = 8;
+
+function collectTransition(
+  transition: Transition,
+  exit: boolean,
+  acc: { opacity?: number; transforms: string[] },
+  depth: number,
+): void {
+  if (depth > MAX_TRANSITION_DEPTH) return;
+  const parts: TransitionPart[] = Array.isArray(transition) ? transition : [transition];
+  for (const part of parts) {
+    if (!part || typeof part !== 'object') continue;
+    switch (part.kind) {
+      case 'opacity':
+        acc.opacity = 0;
+        break;
+      case 'scale':
+        acc.opacity = 0;
+        acc.transforms.push(`scale(${part.scale ?? 0.5})`);
+        break;
+      case 'slide':
+        // In from the leading edge, out through the trailing edge.
+        acc.transforms.push(edgeTranslation(exit ? 'trailing' : 'leading'));
+        break;
+      case 'move':
+        acc.transforms.push(edgeTranslation(part.edge ?? 'bottom'));
+        break;
+      case 'offset':
+        acc.transforms.push(`translate(${part.x ?? 0}px, ${part.y ?? 0}px)`);
+        break;
+      case 'asymmetric': {
+        // Phase 6: `.asymmetric(insertion:removal:)` plays one transition
+        // when the view appears and another when it disappears.
+        const chosen = exit ? part.removal : part.insertion;
+        if (chosen) collectTransition(chosen, exit, acc, depth + 1);
+        break;
+      }
+      case 'identity':
+      default:
+        break;
+    }
+  }
+}
+
+function edgeTranslation(edge: Edge): string {
+  switch (edge) {
+    case 'top':
+      return 'translateY(-100%)';
+    case 'bottom':
+      return 'translateY(100%)';
+    case 'leading':
+      return 'translateX(-100%)';
+    case 'trailing':
+    default:
+      return 'translateX(100%)';
+  }
+}
+
+function isIdentity(frame: TransitionFrame): boolean {
+  return frame.opacity === undefined && frame.transform === undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Animator
+// ---------------------------------------------------------------------------
+
+export const EXIT_CLONE_CLASS = 'sb-exit-clone';
+
+export interface AnimatorOptions {
+  /** Kinds (by `data-sb-kind`) that animate their own enter/exit (navigation, sheets). */
+  selfAnimatingKinds?: ReadonlySet<string>;
+}
+
+export class Animator {
+  /** The element clones of removed elements are appended to (the screen). */
+  private readonly root: HTMLElement;
+  private readonly selfAnimating: ReadonlySet<string>;
+
+  constructor(root: HTMLElement, options: AnimatorOptions = {}) {
+    this.root = root;
+    this.selfAnimating = options.selfAnimatingKinds ?? new Set();
+  }
+
+  /** Computed values of the animated properties, or null when not rendered. */
+  snapshot(el: HTMLElement): StyleSnapshot | null {
+    if (!el.isConnected) return null;
+    const cs = getComputedStyle(el);
+    if (cs.display === 'none') return null;
+    const snap: StyleSnapshot = {};
+    for (const prop of ANIMATED_PROPERTIES) snap[prop] = cs[prop];
+    return snap;
+  }
+
+  /** Rectangle of `el` relative to the animation root. */
+  rectOf(el: HTMLElement): DOMRect | null {
+    if (!el.isConnected) return null;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return null;
+    const base = this.root.getBoundingClientRect();
+    return new DOMRect(r.left - base.left, r.top - base.top, r.width, r.height);
+  }
+
+  /**
+   * Animate the pass. `commitAnimation` is the commit's own animation
+   * (`withAnimation`); subtrees whose `animationToken` changed use their own
+   * animation instead, as `.animation(_:value:)` overrides the transaction.
+   */
+  commit(pass: PassRecord, commitAnimation: Animation | undefined, frames: readonly FrameChange[] = []): void {
+    const tokenRoots = new Map<HTMLElement, Animation | undefined>();
+    for (const [el, rec] of pass.updated) {
+      if (rec.tokenChanged) tokenRoots.set(el, rec.animation);
+    }
+    if (!commitAnimation && tokenRoots.size === 0) return;
+
+    const animationFor = (chain: Iterable<HTMLElement>): Animation | undefined | false => {
+      for (const el of chain) {
+        if (tokenRoots.has(el)) return tokenRoots.get(el) ?? { type: 'default' };
+      }
+      return commitAnimation ?? false;
+    };
+
+    // Style changes.
+    for (const [el, rec] of pass.updated) {
+      if (!rec.before || !el.isConnected) continue;
+      const animation = animationFor(ancestorsAndSelf(el));
+      if (animation === false) continue;
+      this.animateChanges(el, rec.before, animation);
+    }
+
+    // Frame changes: tween left/top/width/height from the previous box. The
+    // inline values are relative to the parent's origin, so apply the delta.
+    for (const change of frames) {
+      const { el, from, to } = change;
+      if (!from || !el.isConnected || pass.inserted.has(el)) continue;
+      if (this.selfAnimating.has(change.kind)) continue;
+      const animation = animationFor(ancestorsAndSelf(el));
+      if (animation === false) continue;
+      this.animateFrame(el, from, to, animation);
+    }
+
+    // Inserted elements: only subtree roots (a nested fade would compound).
+    for (const el of pass.inserted) {
+      if (!el.isConnected || pass.updated.has(el)) continue;
+      if (hasAncestorIn(el, pass.inserted)) continue;
+      if (this.selfAnimating.has(el.dataset['sbKind'] ?? '')) continue;
+      const animation = animationFor(ancestorsAndSelf(el));
+      if (animation === false) continue;
+      this.enter(el, transitionOf(el), animation);
+    }
+
+    // Removed elements: leave a clone that plays the transition backwards.
+    for (const rec of pass.removed) {
+      if (!rec.rect) continue;
+      if (this.selfAnimating.has(rec.el.dataset['sbKind'] ?? '')) continue;
+      const animation = animationFor([rec.el, ...rec.ancestors]);
+      if (animation === false) continue;
+      this.exit(rec, animation);
+    }
+  }
+
+  /** Tween every animated property whose computed value changed. */
+  animateChanges(el: HTMLElement, before: StyleSnapshot, animation: Animation | undefined): void {
+    const after = this.snapshot(el);
+    if (!after) return;
+    const from: Keyframe = {};
+    const to: Keyframe = {};
+    let changed = false;
+    for (const prop of ANIMATED_PROPERTIES) {
+      const a = before[prop];
+      const b = after[prop];
+      if (a === undefined || b === undefined || a === b) continue;
+      from[prop] = a;
+      to[prop] = b;
+      changed = true;
+    }
+    if (!changed) return;
+    const timing = timingFor(animation);
+    el.animate([from, to], { ...timing, fill: 'none' });
+  }
+
+  /** Tween an element's box from its previous layout frame to the current one. */
+  animateFrame(el: HTMLElement, from: FrameRect, to: FrameRect, animation: Animation | undefined): void {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const dw = to.width - from.width;
+    const dh = to.height - from.height;
+    if (!dx && !dy && !dw && !dh) return;
+    const left = parseFloat(el.style.left) || 0;
+    const top = parseFloat(el.style.top) || 0;
+    const start: Keyframe = {};
+    const end: Keyframe = {};
+    if (dx) {
+      start['left'] = `${left - dx}px`;
+      end['left'] = `${left}px`;
+    }
+    if (dy) {
+      start['top'] = `${top - dy}px`;
+      end['top'] = `${top}px`;
+    }
+    if (dw) {
+      start['width'] = `${from.width}px`;
+      end['width'] = `${to.width}px`;
+    }
+    if (dh) {
+      start['height'] = `${from.height}px`;
+      end['height'] = `${to.height}px`;
+    }
+    const timing = timingFor(animation);
+    el.animate([start, end], { ...timing, fill: 'none' });
+  }
+
+  /** Play `transition` forwards on a freshly inserted element. */
+  enter(el: HTMLElement, transition: Transition | undefined, animation: Animation | undefined): void {
+    const start = transitionStart(transition, false);
+    if (isIdentity(start)) return;
+    const from: Keyframe = {};
+    const to: Keyframe = {};
+    if (start.opacity !== undefined) {
+      from['opacity'] = start.opacity;
+      to['opacity'] = 1;
+    }
+    if (start.transform !== undefined) {
+      // A box with its own transform (offset, rotation, scale) keeps it: the
+      // transition's transform is applied on top of it.
+      const own = el.style.transform;
+      from['transform'] = own ? `${own} ${start.transform}` : start.transform;
+      to['transform'] = own || 'none';
+    }
+    const timing = baseTiming(timingFor(animation));
+    el.animate([from, to], { ...timing, fill: 'backwards' });
+  }
+
+  /**
+   * Re-insert a visual clone of a removed element at its old position and
+   * play its transition backwards; the clone is dropped when done.
+   */
+  exit(rec: RemovedRecord, animation: Animation | undefined): HTMLElement | null {
+    const end = transitionStart(rec.transition, true);
+    if (isIdentity(end) || !rec.rect) return null;
+    const clone = ghostClone(rec.el);
+    clone.classList.add(EXIT_CLONE_CLASS);
+    clone.setAttribute('aria-hidden', 'true');
+    clone.toggleAttribute('inert', true);
+    const s = clone.style;
+    s.position = 'absolute';
+    s.left = `${rec.rect.left}px`;
+    s.top = `${rec.rect.top}px`;
+    s.width = `${rec.rect.width}px`;
+    s.height = `${rec.rect.height}px`;
+    s.margin = '0';
+    s.pointerEvents = 'none';
+    this.root.append(clone);
+
+    const from: Keyframe = {};
+    const to: Keyframe = {};
+    if (end.opacity !== undefined) {
+      from['opacity'] = getComputedStyle(clone).opacity;
+      to['opacity'] = end.opacity;
+    }
+    if (end.transform !== undefined) {
+      const own = clone.style.transform;
+      from['transform'] = own || 'none';
+      to['transform'] = own ? `${own} ${end.transform}` : end.transform;
+    }
+    const timing = baseTiming(timingFor(animation));
+    const anim = clone.animate([from, to], { ...timing, fill: 'forwards' });
+    const done = (): void => clone.remove();
+    anim.finished.then(done, done);
+    window.setTimeout(done, timing.duration + timing.delay + 100);
+    return clone;
+  }
+}
+
+/** Transitions are stored by the renderer per element (see `setTransition`). */
+const TRANSITIONS = new WeakMap<HTMLElement, Transition>();
+
+export function setTransition(el: HTMLElement, transition: Transition | undefined): void {
+  if (transition) TRANSITIONS.set(el, transition);
+  else TRANSITIONS.delete(el);
+}
+
+/**
+ * The transition of a subtree root: its own, or the one on a single-child
+ * chain of `styled` boxes below it (`Text.transition(.opacity).padding()`
+ * is `styled{padding} > styled{transition} > text`), else the default.
+ */
+export function transitionOf(root: HTMLElement): Transition | undefined {
+  let el: HTMLElement | null = root;
+  while (el) {
+    const own = TRANSITIONS.get(el);
+    if (own) return own;
+    if (!el.classList.contains('sb-styled')) break;
+    const next: Element | null = el.firstElementChild;
+    el = next instanceof HTMLElement && el.children.length === 1 ? next : null;
+  }
+  return undefined;
+}
+
+function* ancestorsAndSelf(el: HTMLElement): Generator<HTMLElement> {
+  for (let node: HTMLElement | null = el; node; node = node.parentElement) yield node;
+}
+
+function hasAncestorIn(el: HTMLElement, set: ReadonlySet<HTMLElement>): boolean {
+  for (let node = el.parentElement; node; node = node.parentElement) {
+    if (set.has(node)) return true;
+  }
+  return false;
+}

package/src/assets.ts

@@ -0,0 +1,86 @@
+/**
+ * Asset catalog manifest (docs/ops-protocol.md, "Phase 5 additions").
+ *
+ * An Xcode asset catalog (`Examples/<App>/Assets.xcassets`) holds the images
+ * and colors a SwiftUI app refers to by name (`Image("dough/plain-full")`,
+ * `Color("dough/plain-bg")`). The Swift side only ever sends the name; the
+ * dev server and the build turn every catalog into one JSON manifest plus the
+ * image files (plugins/asset-catalogs.ts), and the page fetches the manifest
+ * before loading the app. The layout engine reads intrinsic sizes from it,
+ * the renderer resolves `src` and color values.
+ *
+ * This module is shared by the browser code and the Node plugin, so it must
+ * stay free of DOM and Node APIs.
+ */
+
+export type AssetImageKind = 'image' | 'symbol';
+
+export interface AssetImage {
+  /** Absolute URL path of the image file (`/catalog/<App>/<file>`). */
+  src: string;
+  /** Intrinsic size in points (pixel size ÷ `scale`). Irrelevant for `symbol`. */
+  width: number;
+  height: number;
+  /** Scale of the file the manifest picked (2 for `@2x`), so pixels = points × scale. */
+  scale: number;
+  /** `image` for an `.imageset`; `symbol` for an `.symbolset` (an SVG drawn as a template). */
+  kind: AssetImageKind;
+}
+
+export interface AssetColor {
+  /** CSS color for the light appearance (`rgba(r, g, b, a)`). */
+  light: string;
+  /** CSS color for the dark appearance; absent when the colorset has none. */
+  dark?: string;
+}
+
+export interface AssetCatalog {
+  /** Keyed by catalog name, namespaced with `/` (`dough/plain-full`). */
+  images: Record<string, AssetImage>;
+  colors: Record<string, AssetColor>;
+}
+
+/** The catalog of an app without one (and of the mock app). */
+export const EMPTY_CATALOG: Readonly<AssetCatalog> = Object.freeze({ images: {}, colors: {} });
+
+/** URL directory under which manifests and files are served. */
+export const CATALOG_DIR = 'catalog';
+
+/** URL path of an app's manifest (`/catalog/<App>.json`). */
+export function catalogPath(app: string): string {
+  return `/${CATALOG_DIR}/${app}.json`;
+}
+
+/**
+ * File name an asset is served under: the namespaced name with every `/`
+ * replaced by `__`, plus the extension (`dough__plain-full.png`). Flattening
+ * keeps every file of a catalog in one directory.
+ */
+export function assetFileName(name: string, ext: string): string {
+  // `/` becomes `__`; spaces and anything else outside [A-Za-z0-9_.-] become
+  // `_`, so the served path needs no URL encoding and matches the request
+  // pattern the dev middleware accepts.
+  return `${name.replace(/\//g, '__').replace(/[^A-Za-z0-9_.-]/g, '_')}.${ext}`;
+}
+
+/** URL path of an asset file (`/catalog/<App>/dough__plain-full.png`). */
+export function assetFilePath(app: string, name: string, ext: string): string {
+  return `/${CATALOG_DIR}/${app}/${assetFileName(name, ext)}`;
+}
+
+/**
+ * CSS custom property that carries a catalog color: `--sb-asset-color-<slug>`.
+ * The slug keeps letters, digits, `-` and `_`; `/` becomes `__` (like file
+ * names) and anything else `_`.
+ */
+export function assetColorVar(name: string): string {
+  const slug = name.replace(/\//g, '__').replace(/[^A-Za-z0-9_-]/g, '_');
+  return `--sb-asset-color-${slug}`;
+}
+
+/** Cheap structural check for a fetched manifest; anything else is treated as empty. */
+export function isAssetCatalog(value: unknown): value is AssetCatalog {
+  if (typeof value !== 'object' || value === null) return false;
+  const { images, colors } = value as { images?: unknown; colors?: unknown };
+  return typeof images === 'object' && images !== null && typeof colors === 'object' && colors !== null;
+}