@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/types.ts

@@ -0,0 +1,162 @@
+/**
+ * **Motion templates — the two contracts.** A motion template is an animation authored once (in
+ * `remotion-prototype/`, with Remotion) and shipped as data: markup, styles, a keyframe timeline and a
+ * content schema. The MOTION contract (`MotionContract`) belongs to the author and is never editable
+ * by an agent. The CONTENT contract (the template's `schema`) is the only thing an agent or a person
+ * fills: text slots, optional theme colours, optional scenes.
+ */
+export type Easing = 'linear' | 'hold' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'expo-out' | 'back-out';
+
+export type AnimatedProperty =
+  | 'x' | 'y' | 'rotate' | 'scale' | 'scaleX' | 'scaleY' // transform (px / deg / factor)
+  | 'left' | 'top' // position: left in % of the parent, top in px
+  | 'opacity' | 'blur' // blur in px
+  | 'clipRight' | 'clipLeft' // inset in % of the element
+  | 'color' // '#rrggbb', or a theme token name such as 'ink'
+  | 'fx'; // the id of an SVG filter the template's own markup defines, or 'none' (use the 'hold' easing)
+
+/** At scene-relative frame `f` the value is `v`; `e` is the easing INTO this keyframe. */
+export type Keyframe = { f: number; v: number | string; e?: Easing };
+
+export type Track = { target: string; property: AnimatedProperty; keyframes: Keyframe[] };
+
+/** `optional` scenes may be left out of the content; only trailing scenes may be optional. */
+export type SceneTimeline = { id: string; from: number; durationInFrames: number; optional?: boolean; tracks: Track[] };
+
+/**
+ * A canvas the template is laid out for. Content picks one by `aspectRatio`; the template's CSS
+ * lays it out through `[data-format="<id>"]` on the canvas. The first format is the default.
+ */
+export type MotionFormat = { id: string; aspectRatio: string; width: number; height: number };
+
+/**
+ * **A sequence template** plays a list from the content (`path`, e.g. `scenes`), one scene per item,
+ * in order. Each item picks author-defined options (`options`: field → allowed values); the runtime
+ * writes each choice as `data-<field>` on the item's scene, where the template's CSS reads it. The
+ * `motionField` choice names the `SceneTimeline` (in `scenes`) that animates the item.
+ *
+ * Item `i` lasts `rhythm[i]` frames (the last value repeats), but never less than its timeline's
+ * `durationInFrames`. Content therefore changes how many beats there are, never how a beat moves.
+ */
+export type MotionSequence = {
+  path: string;
+  minItems: number;
+  maxItems: number;
+  motionField: string;
+  options: Record<string, string[]>;
+  rhythm: number[];
+};
+
+export type MotionContract = {
+  template: string;
+  version: string;
+  fps: number;
+  /** The default canvas (the first format's, when there are formats). */
+  width: number;
+  height: number;
+  /** The reference length: the default content's. A sequence's real length depends on its item count. */
+  durationInFrames: number;
+  /** Fixed scenes; or, for a sequence template, one timeline per `sequence.motionField` value. */
+  scenes: SceneTimeline[];
+  formats?: MotionFormat[];
+  sequence?: MotionSequence;
+};
+
+/** A theme: colour tokens by name, each '#rrggbb'. Unset tokens keep the template's defaults. */
+export type MotionTheme = Record<string, string>;
+
+/** `path` is dotted; in a sequence, `scenes[].text` means that field of every item. */
+export type SlotSpec = {
+  path: string;
+  maxWords: number;
+  maxChars: number;
+  /** Width (px on the canvas) past which text is scaled down; `fitWidths` overrides it per format id. */
+  fitWidth: number;
+  fitWidths?: Record<string, number>;
+  /** May be left out. */
+  optional?: boolean;
+  /** Only allowed when these item options are chosen (e.g. `{ layout: ['stack'] }`). */
+  onlyWith?: Record<string, string[]>;
+  description: string;
+};
+
+/** One of a sequence item's choices, as the template describes it to people and agents. */
+export type ChoiceSpec = { field: string; default: string; description: string; values: { value: string; description: string }[] };
+
+export type ThemeTokenSpec = { token: string; default: string; description: string };
+
+/** Everything a runtime needs to play one template. Plain data — safe to JSON-serialise. */
+export type MotionTemplate = {
+  id: string;
+  version: string;
+  title: string;
+  description: string;
+  /** Content-free markup: `[data-content]` text slots, `[data-target]` animated nodes, `[data-scene]` layers. */
+  template: string;
+  /** The fixed design, including the theme tokens' default values. */
+  styles: string;
+  /** `stretch` is a CSS font-stretch keyword (e.g. `expanded`) for faces that need one to load. */
+  fonts: { family: string; weights: string[]; css: string; stretch?: string }[];
+  motion: MotionContract;
+  /** JSON Schema of the content contract. */
+  schema: Record<string, unknown>;
+  slots: SlotSpec[];
+  theme: ThemeTokenSpec[];
+  optionalScenes: string[];
+  /** Sequence templates: each item's choices (`motion.sequence.options`, described). */
+  choices?: ChoiceSpec[];
+  exampleContent: Record<string, unknown>;
+};
+
+/**
+ * **A configurable-motion template** (DECISIONS §25): an animation whose timing and motion are part
+ * of its declared schema. One canonical config — every value a typed control with a range or an
+ * approved enum — is edited the same way by people and agents; there is no separate motion contract.
+ * Drawn by Rive (replication-2: the file draws, the package engine decides each frame) or procedurally
+ * by React/DOM and rendered to video by Remotion (promo-product-showcase). Plain data.
+ */
+export type ConfigurableMotionControl = {
+  path: string;
+  group: string;
+  type: 'number' | 'integer' | 'boolean' | 'color' | 'enum' | 'text' | 'easing' | 'asset' | 'overrides';
+  default: unknown;
+  min?: number;
+  max?: number;
+  step?: number;
+  options?: readonly (string | number)[];
+  maxLength?: number;
+  minLength?: number;
+  /** `overrides`: the config paths a scene may set. */
+  allow?: readonly string[];
+  /** Set when the control is a field of every item of this list (the path reads `<list>[].<field>`). */
+  list?: string;
+  unit?: string;
+  description: string;
+  userEditable: boolean;
+  agentEditable: boolean;
+};
+export type ConfigurableMotionTemplate = {
+  id: string;
+  version: string;
+  kind: 'configurableMotion';
+  renderer: 'rive' | 'remotion';
+  title: string;
+  description: string;
+  /** Output frame rate of the reference; timing is authored in 60 fps motion frames. */
+  fps: number;
+  formats: MotionFormat[];
+  /** The reference config's length in output frames. */
+  durationInFrames: number;
+  groups: string[];
+  controls: readonly ConfigurableMotionControl[];
+  /** JSON Schema 2020-12 of the config. */
+  schema: Record<string, unknown>;
+  /** Named patches over the reference config. */
+  presets: Record<string, { description: string; patch: Record<string, unknown> }>;
+  /** Rive-drawn templates: the file and its contract. */
+  rive?: { file: string; artboard: string; stateMachine: string; viewModel: string };
+  /** Procedural templates rendered by Remotion: the project, its compositions and the reference props. */
+  remotion?: { project: string; compositions: string[]; reference: string };
+  /** The reference config. */
+  exampleContent: Record<string, unknown>;
+};

package/src/motion/typesurface/TypeSurfaceCanvas.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { useEffect, useRef, useState, type CSSProperties } from 'react';
+import { sanitizeTypeSurface, type TypeSurfaceConfig } from './config';
+import { drawDebugOverlay, TypeSurfaceRenderer, type TSDebug } from './renderer';
+import { configAt } from './timeline';
+
+export type TypeSurfaceCanvasProps = {
+  config: TypeSurfaceConfig;
+  /** 0–1 along the timeline. Omit to draw the config as-is (every stage complete). */
+  progress?: number;
+  /** For time-driven motion (fabric breeze, bottle turn). */
+  timeMs?: number;
+  debug?: TSDebug;
+  className?: string;
+  style?: CSSProperties;
+  /** Called with the renderer once it exists (picking, export). */
+  onRenderer?: (r: TypeSurfaceRenderer | null) => void;
+};
+
+/**
+ * **One typography × surface experiment, drawn.** Pure with respect to its props: the same config,
+ * progress and time always draw the same picture, so a playground, a scrubber or a video render can
+ * drive it.
+ */
+export function TypeSurfaceCanvas({ config, progress, timeMs = 0, debug, className, style, onRenderer }: TypeSurfaceCanvasProps) {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const overlay = useRef<HTMLCanvasElement>(null);
+  const renderer = useRef<TypeSurfaceRenderer | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [tick, setTick] = useState(0);
+  const { config: safe, invalid } = sanitizeTypeSurface(config);
+
+  useEffect(() => {
+    if (!canvas.current) return;
+    const r = new TypeSurfaceRenderer(canvas.current);
+    if (!r.ok) { setError(r.error); return; }
+    renderer.current = r;
+    onRenderer?.(r);
+    const ro = new ResizeObserver(() => setTick((t) => t + 1));
+    ro.observe(canvas.current);
+    const fonts = () => setTick((t) => t + 1);
+    document.fonts?.addEventListener?.('loadingdone', fonts);
+    return () => {
+      ro.disconnect();
+      document.fonts?.removeEventListener?.('loadingdone', fonts);
+      r.dispose();
+      renderer.current = null;
+      onRenderer?.(null);
+    };
+  }, []);
+
+  const drawn = progress === undefined ? safe : configAt(safe, progress);
+  useEffect(() => {
+    const r = renderer.current;
+    if (!r) return;
+    try {
+      r.render(drawn, timeMs, debug);
+      const o = overlay.current?.getContext('2d');
+      if (o) drawDebugOverlay(o, r, debug ?? {});
+    } catch (e) {
+      setError((e as Error).message);
+    }
+  });
+
+  return (
+    <div className={className} style={{ position: 'relative', ...style }} data-ts-invalid={invalid.join(' ') || undefined} data-tick={tick}>
+      <canvas ref={canvas} style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', display: 'block' }} aria-label={`“${safe.text}” on ${safe.surface.type}`} role="img" />
+      <canvas ref={overlay} style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', pointerEvents: 'none' }} aria-hidden />
+      {error ? <p role="alert" style={{ position: 'absolute', inset: 0, margin: 0, display: 'grid', placeItems: 'center', padding: 16, textAlign: 'center' }}>{error}</p> : null}
+    </div>
+  );
+}