diff --git a/.changeset/deprecate-animation-helpers.md b/.changeset/deprecate-animation-helpers.md new file mode 100644 index 00000000..d590a19d --- /dev/null +++ b/.changeset/deprecate-animation-helpers.md @@ -0,0 +1,13 @@ +--- +"@effex/dom": patch +--- + +Deprecate five under-used animation helpers with `@deprecated` JSDoc tags. All continue to work — they'll be removed in a future major. + +- `staggerEased` — compose your own: `(index, total) => easingFn(index / (total - 1)) * totalDurationMs` +- `delay` — use `Effect.delay(effect, ms)` directly +- `sequence` — use `Effect.all([...], { concurrency: 1 })` directly +- `parallel` — use `Effect.all([...], { concurrency: "unbounded" })` directly +- `calculateStaggerDelay` — was only ever an internal helper; not re-exported by anything downstream + +These wrapped effect combinators without adding real value beyond a slightly shorter name; the framework should be a thin layer over Effect rather than shadow its stdlib. diff --git a/packages/dom/src/Animation/index.ts b/packages/dom/src/Animation/index.ts index 5a41b512..cc67ffeb 100644 --- a/packages/dom/src/Animation/index.ts +++ b/packages/dom/src/Animation/index.ts @@ -70,6 +70,8 @@ export const staggerFromCenter = (delayMs: number): StaggerFunction => { * @param totalDurationMs - Total duration for all staggers to complete * @param easingFn - Easing function (0-1 input, 0-1 output) * + * @deprecated Compose your own — `(index, total) => easingFn(index / (total - 1)) * totalDurationMs`. Will be removed in a future major. + * * @example * ```ts * // Ease-out: items near the end have smaller delays between them @@ -99,6 +101,8 @@ export const staggerEased = ( /** * Add a delay before running an effect. * + * @deprecated Use `Effect.delay(effect, ms)` directly. Will be removed in a future major. + * * @example * ```ts * yield* delay(200, runEnterAnimation(element, options)) @@ -112,6 +116,8 @@ export const delay = ( /** * Run multiple animation effects in sequence. * + * @deprecated Use `Effect.all([...], { concurrency: 1 })` directly. Will be removed in a future major. + * * @example * ```ts * yield* sequence( @@ -127,6 +133,8 @@ export const sequence = ( /** * Run multiple animation effects in parallel. * + * @deprecated Use `Effect.all([...], { concurrency: "unbounded" })` directly. Will be removed in a future major. + * * @example * ```ts * yield* parallel( @@ -144,6 +152,8 @@ export const parallel = ( /** * Calculate stagger delay for a given index. * Handles both numeric values and stagger functions. + * + * @deprecated Internal helper — no longer part of the public API. Will be removed in a future major. */ export const calculateStaggerDelay = ( stagger: number | StaggerFunction | undefined,