@glissade/core 0.17.1 → 0.18.0-pre.0

package/dist/index.d.ts

@@ -240,9 +240,38 @@ interface TweenOpts<T = unknown> {
   /** Explicit start value — sugar for fromTo; required ergonomics for string targets. */
   from?: T;
 }
+/** The shared tween shape applied to every staggered target (§2.6 stagger sugar). */
+interface StaggerSpec<T = unknown> {
+  to: T;
+  /** Explicit start value — routes each target through `fromTo` when present. */
+  from?: T;
+  duration?: number;
+  ease?: EaseSpec;
+}
+/**
+ * Stagger placement. `each` is the per-rank delay (seconds, number-only in v1).
+ * `from` picks the anchor the cascade ranks outward from (GSAP parity); `at`
+ * places the whole group's base position (defaults to the chain end).
+ */
+interface StaggerOpts {
+  each: number;
+  from?: 'start' | 'end' | 'center' | 'edges' | number;
+  at?: Position;
+}
 interface TimelineBuilder {
   to<T>(target: TweenTarget, value: T, opts?: TweenOpts<T>): TimelineBuilder;
   fromTo<T>(target: TweenTarget, from: T, to: T, opts?: TweenOpts<T>): TimelineBuilder;
+  /**
+   * Build-time sugar: loop the shipped `to`/`fromTo` emission over `targets`,
+   * cascading each by a per-rank delay. Emits keys byte-identical to N
+   * hand-authored offset tweens. The `from` anchor ranks targets over their
+   * array index i (n = targets.length, c = (n-1)/2): `'start'` → i; `'end'` →
+   * (n-1)-i; `'center'` → round(|i-c|); `'edges'` → round(c-|i-c|); numeric k →
+   * round(|i-k|). Delay d_i = rank_i * each, inserted at `base + d_i` where
+   * `base = resolvePosition(opts.at)`. The group reads as one block to a
+   * following `'<'`/`'>'`/`'+='` step.
+   */
+  stagger<T>(targets: TweenTarget[], spec: StaggerSpec<T>, opts: StaggerOpts): TimelineBuilder;
   /** Hold key: the value snaps at the resolved position (§2.6). */
   set<T>(target: TweenTarget, value: T, opts?: {
     at?: Position;
@@ -392,4 +421,4 @@ interface CheckpointedSim {
 }
 declare function bakeCheckpointed<W, S = W>(cfg: CheckpointedBakeConfig<W, S>): CheckpointedSim;
 //#endregion
-export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, BindTypeMismatchError, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type ColorStop, type CompiledTimeline, type CoverageReport, type CurveSampler, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type FontFaceRef, type FontMode, type FontRegistry, type FontUsage, FontValidationError, type GainEnvelope, type GradientInterpolation, type HandoffKind, type Json, type Key, type KeyOpts, type Marker, type MergeResult, type MeshInterpolation, type MeshPaint, type MeshPoint, type MissingGlyphs, type OkLab, type OrphanReason, type Paint, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type ResolvedFace, type RetargetSpring, type Rgba, type Rng, type Scheduler, type SidecarDoc, type SidecarDocV1, type SidecarOrphan, type SidecarTimelineEntry, type SidecarTrackEntry, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValidateFontsOptions, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Component, type Vec2Signal, WriteDuringEvaluationError, assignKeyIds, audioOffsetSamples, bake, bakeCheckpointed, batch, beginReadPhase, bindTimeline, booleanType, buildFontRegistry, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, deleteSidecarTrack, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, hashKeys, inReadPhase, inferValueType, isDurationEditable, isEditableNodeId, isExemptFamily, key, lerpColor, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, paintType, parseCmap, parseColor, pathType, random, registerValueType, reprOf, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setScheduler, setSidecarTrack, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, synchronousScheduler, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };
+export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, BindTypeMismatchError, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type ColorStop, type CompiledTimeline, type CoverageReport, type CurveSampler, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type FontFaceRef, type FontMode, type FontRegistry, type FontUsage, FontValidationError, type GainEnvelope, type GradientInterpolation, type HandoffKind, type Json, type Key, type KeyOpts, type Marker, type MergeResult, type MeshInterpolation, type MeshPaint, type MeshPoint, type MissingGlyphs, type OkLab, type OrphanReason, type Paint, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type ResolvedFace, type RetargetSpring, type Rgba, type Rng, type Scheduler, type SidecarDoc, type SidecarDocV1, type SidecarOrphan, type SidecarTimelineEntry, type SidecarTrackEntry, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, type StaggerOpts, type StaggerSpec, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValidateFontsOptions, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Component, type Vec2Signal, WriteDuringEvaluationError, assignKeyIds, audioOffsetSamples, bake, bakeCheckpointed, batch, beginReadPhase, bindTimeline, booleanType, buildFontRegistry, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, deleteSidecarTrack, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, hashKeys, inReadPhase, inferValueType, isDurationEditable, isEditableNodeId, isExemptFamily, key, lerpColor, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, paintType, parseCmap, parseColor, pathType, random, registerValueType, reprOf, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setScheduler, setSidecarTrack, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, synchronousScheduler, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/dist/index.js

@@ -643,6 +643,36 @@ function buildTimeline(build, init = {}) {
 			insertions[insertions.length - 1].explicitFrom = from;
 			return builder;
 		},
+		stagger(targets, spec, opts) {
+			const n = targets.length;
+			const base = resolvePosition(opts.at);
+			const c = (n - 1) / 2;
+			const rankOf = (i) => {
+				const f = opts.from ?? "start";
+				if (f === "start") return i;
+				if (f === "end") return n - 1 - i;
+				if (f === "center") return Math.round(Math.abs(i - c));
+				if (f === "edges") return Math.round(c - Math.abs(i - c));
+				return Math.round(Math.abs(i - f));
+			};
+			const duration = spec.duration ?? 1;
+			let maxDelay = 0;
+			const tweenOpts = (d) => ({
+				at: base + d,
+				...spec.duration !== void 0 ? { duration: spec.duration } : {},
+				...spec.ease !== void 0 ? { ease: spec.ease } : {}
+			});
+			for (let i = 0; i < n; i++) {
+				const d = rankOf(i) * opts.each;
+				if (d > maxDelay) maxDelay = d;
+				const t = targets[i];
+				if (spec.from !== void 0) builder.fromTo(t, spec.from, spec.to, tweenOpts(d));
+				else builder.to(t, spec.to, tweenOpts(d));
+			}
+			prevStart = base;
+			prevEnd = base + maxDelay + duration;
+			return builder;
+		},
 		set(target, value, opts = {}) {
 			const start = resolvePosition(opts.at);
 			insertions.push({

package/package.json

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