@glissade/core 0.18.0-pre.2 → 0.18.0-pre.3

package/dist/clips.d.ts

@@ -1,4 +1,4 @@
-import { T as ValueTypeId, Y as EaseSpec, r as Track, t as Key } from "./track.js";
+import { D as Vec2, T as ValueTypeId, Y as EaseSpec, r as Track, t as Key } from "./track.js";
 import { r as TweenTarget } from "./targetRef.js";
 
 //#region src/clip.d.ts
@@ -182,20 +182,63 @@ declare function morph(from: Box, to: Box, targets: MorphTargets, opts: MorphOpt
 declare class PresenceError extends Error {
   constructor(message: string);
 }
+/**
+ * An inline ENTER/EXIT literal (0.18 sugar): a terse alternative to hand-building
+ * a `clip({channels})`. `transitionToClip` compiles it to the SAME `Clip` an author
+ * would write by hand, so presence() then runs UNCHANGED on the result — the inline
+ * spelling is byte-INDISTINGUISHABLE from the hand-authored clip path.
+ *
+ * Conventions mirror clipStdlib (`slideIn`/`popIn`): a scalar `offset` slides that
+ * magnitude in along `edge` (default 'bottom' = slide up from below); a scalar
+ * `scale` broadcasts to a Vec2; OMITTING `opacity` emits NO opacity channel so
+ * presence()'s synthesized rise/fall takes over (matching the Clip path exactly).
+ */
+interface PresenceTransition {
+  /** Opacity endpoints [from,to]. OMIT to rely on presence()'s synthesized rise/fall. */
+  opacity?: [number, number];
+  /**
+   * Slide displacement. A scalar slides that magnitude along `edge`; a single Vec2
+   * is the displaced point (animates to/from [0,0]); a [Vec2,Vec2] is explicit
+   * endpoints. Omit for no position channel.
+   */
+  offset?: number | Vec2 | [Vec2, Vec2];
+  /** Slide edge for a scalar `offset` (clipStdlib convention). Default 'bottom'. */
+  edge?: SlideEdge;
+  /** Scale endpoints. A scalar pair broadcasts each value to a Vec2 (popIn convention). */
+  scale?: [number, number] | [Vec2, Vec2];
+  /** Transition length in seconds. Default = the presence DEFAULT_FADE (0.3). */
+  dur?: number;
+  /** Arriving ease of every channel's last segment. */
+  ease?: EaseSpec;
+}
 interface PresenceOpts {
   /** Wall-clock second the node ENTERS (becomes visible). */
-  show: number;
+  show?: number;
   /** Wall-clock second the node has fully EXITED (the exit LANDS here). */
-  hide: number;
-  /** Entrance clip (default = a plain opacity fade-in 0→1, ~0.3s). */
-  enter?: Clip;
-  /** Exit clip (default = a plain opacity fade-out 1→0, ~0.3s). Back-timed to land on `hide`. */
-  exit?: Clip;
+  hide?: number;
+  /** Alias for `{ show: window[0], hide: window[1] }`. */
+  window?: [number, number];
+  /** Entrance clip, or an inline transition literal (default = a plain opacity fade-in 0→1, ~0.3s). */
+  enter?: Clip | PresenceTransition;
+  /** Exit clip, or an inline transition literal (default = a plain opacity fade-out 1→0, ~0.3s). Back-timed to land on `hide`. */
+  exit?: Clip | PresenceTransition;
   /** Forwarded to `enter.apply` (speed / per-channel overrides). */
   enterOpts?: ApplyOpts;
   /** Forwarded to `exit.apply` (speed / per-channel overrides). */
   exitOpts?: ApplyOpts;
 }
+/**
+ * Compile an inline `PresenceTransition` literal into the SAME `Clip` an author
+ * would hand-write — an opacity channel (only when `opacity` is given), a position
+ * channel from `offset`+`edge` (slideIn convention), and a scale channel (scalar
+ * broadcast to Vec2, popIn convention). presence() then runs UNCHANGED on it.
+ *
+ * `dir` selects the slide direction: an `enter` slides FROM the edge-displaced
+ * point TO [0,0]; an `exit` slides FROM [0,0] TO the edge-displaced point (so a
+ * back-timed exit reads as the inverse of the entrance). For an explicit
+ * `[Vec2,Vec2]` offset the endpoints are used verbatim (no direction flip).
+ */
+declare function transitionToClip(t: PresenceTransition, dir: 'enter' | 'exit'): Clip;
 interface PresenceResult {
   /** Reconciled tracks: the opacity guard (fused with enter/exit opacity keys) + any non-opacity channels. */
   tracks: Track[];
@@ -213,4 +256,4 @@ interface PresenceResult {
  */
 declare function presence(nodeId: TweenTarget, opts: PresenceOpts): PresenceResult;
 //#endregion
-export { type ApplyOpts, type ApplyOpts as ClipApplyOpts, type Box, type ChannelOverride, type Clip, type ClipChannel, ClipError, type ClipListDelay, type ClipListOpts, type ClipResult, type ClipSpec, type ClipTarget, type DurationOpts, MorphError, type MorphOpts, type MorphResult, type MorphTargets, PresenceError, type PresenceOpts, type PresenceResult, type SlideEdge, clip, clipList, driftLoop, morph, popIn, presence, pulse, slideIn };
+export { type ApplyOpts, type ApplyOpts as ClipApplyOpts, type Box, type ChannelOverride, type Clip, type ClipChannel, ClipError, type ClipListDelay, type ClipListOpts, type ClipResult, type ClipSpec, type ClipTarget, type DurationOpts, MorphError, type MorphOpts, type MorphResult, type MorphTargets, PresenceError, type PresenceOpts, type PresenceResult, type PresenceTransition, type SlideEdge, clip, clipList, driftLoop, morph, popIn, presence, pulse, slideIn, transitionToClip };

package/dist/clips.js

@@ -398,6 +398,82 @@ function defaultExit() {
 		keys: [key(0, 1), key(DEFAULT_FADE, 0)]
 	} } });
 }
+/** A `PresenceTransition` is a plain bag; a `Clip` carries `apply`. Discriminate on that. */
+function isClip(t) {
+	return typeof t.apply === "function";
+}
+/** Is a value a Vec2 ([number, number])? */
+function isVec2(v) {
+	return Array.isArray(v);
+}
+/**
+* Compile an inline `PresenceTransition` literal into the SAME `Clip` an author
+* would hand-write — an opacity channel (only when `opacity` is given), a position
+* channel from `offset`+`edge` (slideIn convention), and a scale channel (scalar
+* broadcast to Vec2, popIn convention). presence() then runs UNCHANGED on it.
+*
+* `dir` selects the slide direction: an `enter` slides FROM the edge-displaced
+* point TO [0,0]; an `exit` slides FROM [0,0] TO the edge-displaced point (so a
+* back-timed exit reads as the inverse of the entrance). For an explicit
+* `[Vec2,Vec2]` offset the endpoints are used verbatim (no direction flip).
+*/
+function transitionToClip(t, dir) {
+	const d = t.dur ?? DEFAULT_FADE;
+	const ease = t.ease;
+	const channels = {};
+	if (t.opacity !== void 0) {
+		const [from, to] = t.opacity;
+		channels.opacity = {
+			path: "opacity",
+			keys: [key(0, from), key(d, to, ...easeArg(ease))]
+		};
+	}
+	if (t.offset !== void 0) {
+		const [from, to] = offsetEndpoints(t.offset, t.edge ?? "bottom", dir);
+		channels.offset = {
+			path: "position",
+			keys: [key(0, from), key(d, to, ...easeArg(ease))]
+		};
+	}
+	if (t.scale !== void 0) {
+		const [from, to] = scaleEndpoints(t.scale);
+		channels.scale = {
+			path: "scale",
+			keys: [key(0, from), key(d, to, ...easeArg(ease))]
+		};
+	}
+	return clip({ channels });
+}
+/** Spread-arg helper: pass `ease` to `key()` only when defined (no `undefined` arg). */
+function easeArg(ease) {
+	return ease !== void 0 ? [ease] : [];
+}
+/** Edge → unit displacement direction (matches clipStdlib's slideIn `from` vectors). */
+function edgeVec(edge, dist) {
+	return edge === "left" ? [-dist, 0] : edge === "right" ? [dist, 0] : edge === "top" ? [0, -dist] : [0, dist];
+}
+/**
+* Resolve the `offset` field to position [from, to] endpoints. A scalar slides that
+* magnitude along `edge`; a single Vec2 is the displaced point; a [Vec2,Vec2] is
+* verbatim endpoints. enter goes displaced→[0,0]; exit goes [0,0]→displaced.
+*/
+function offsetEndpoints(offset, edge, dir) {
+	if (Array.isArray(offset) && isVec2(offset[0])) return offset;
+	const displaced = isVec2(offset) ? offset : edgeVec(edge, offset);
+	const origin = [0, 0];
+	return dir === "enter" ? [displaced, origin] : [origin, displaced];
+}
+/** Resolve the `scale` field to [from, to] Vec2 endpoints (scalar pair → broadcast). */
+function scaleEndpoints(scale) {
+	const [a, b] = scale;
+	const broadcast = (v) => isVec2(v) ? v : [v, v];
+	return [broadcast(a), broadcast(b)];
+}
+/** Normalize an enter/exit option (Clip or inline literal) to a Clip. */
+function resolveTransition(t, dir, fallback) {
+	if (t === void 0) return fallback();
+	return isClip(t) ? t : transitionToClip(t, dir);
+}
 /** Effective duration of a clip after a speed multiplier (`apply` divides every t by speed). */
 function effectiveDuration(c, opts) {
 	return c.duration / (opts?.speed ?? 1);
@@ -430,12 +506,14 @@ function partitionOpacity(tracks, opacityTarget) {
 *   presence('card', { show: 1, hide: 5 })  // fade in at 1, fade out to land on 5
 */
 function presence(nodeId, opts) {
-	const { show, hide } = opts;
+	const show = opts.show ?? opts.window?.[0];
+	const hide = opts.hide ?? opts.window?.[1];
+	if (show === void 0 || hide === void 0) throw new PresenceError(`presence() needs a window: pass { show, hide } or { window: [show, hide] }`);
 	const opacityTarget = resolveTweenTarget(typeof nodeId === "string" ? `${nodeId}/opacity` : nodeId);
 	const lastSlash = opacityTarget.lastIndexOf("/");
 	const nodeIdStr = lastSlash < 0 ? opacityTarget : opacityTarget.slice(0, lastSlash);
-	const enter = opts.enter ?? defaultEnter();
-	const exit = opts.exit ?? defaultExit();
+	const enter = resolveTransition(opts.enter, "enter", defaultEnter);
+	const exit = resolveTransition(opts.exit, "exit", defaultExit);
 	const enterRes = enter.apply(nodeIdStr, show, opts.enterOpts);
 	const enterEnd = show + effectiveDuration(enter, opts.enterOpts);
 	const exitDur = effectiveDuration(exit, opts.exitOpts);
@@ -479,4 +557,4 @@ function presence(nodeId, opts) {
 	};
 }
 //#endregion
-export { ClipError, MorphError, PresenceError, clip, clipList, driftLoop, morph, popIn, presence, pulse, slideIn };
+export { ClipError, MorphError, PresenceError, clip, clipList, driftLoop, morph, popIn, presence, pulse, slideIn, transitionToClip };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/core",
-  "version": "0.18.0-pre.2",
+  "version": "0.18.0-pre.3",
   "description": "glissade core: signals, tracks, timeline document, evaluation, easing, springs, seeded RNG. Zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {