Merge branch 'master' of github.com:wix/interact into documentation-finalize

Author: ameerf-wix

CHANGELOG.md

@@ -81,7 +81,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/interact
 
-### [2.6.0] - unreleased
+### [2.5.6] - 2026-08-13
 
 #### Added
 
@@ -91,13 +91,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 #### Changed
 
 - `generate(config, options?)`: the second argument now accepts an options bag — `{ useFirstChild?, plugins? }` — exported as the `GenerateOptions` (#275)
-- CSS property names may be authored in either camelCase or kebab-case in `transition.styleProperties`, `transitionProperties` and `keyframeEffect.keyframes`; state-effect properties are normalized to kebab-case for the generated CSS (state rules and the `transition:` shorthand) and keyframes to camelCase for WAAPI
+- CSS property names may be authored in either camelCase or kebab-case in `transition.styleProperties`, `transitionProperties` and `keyframeEffect.keyframes`; state-effect properties are normalized to kebab-case for the generated CSS (state rules and the `transition:` shorthand) and keyframes to camelCase for WAAPI (#281)
 
 #### Fixed
 
-- camelCase property names in `transition.styleProperties` / `transitionProperties` are now normalized to kebab-case
-- CSS custom properties in keyframes (e.g. `--fooBar`) are no longer lower-cased when emitted into `@keyframes`
-- Vendor-prefixed keyframe properties (e.g. `webkitTextStroke`) now emit a valid CSS property name (`-webkit-text-stroke`)
+- camelCase property names in `transition.styleProperties` / `transitionProperties` are now normalized to kebab-case (#281)
+- CSS custom properties in keyframes (e.g. `--fooBar`) are no longer lower-cased when emitted into `@keyframes` (#281)
+- Vendor-prefixed keyframe properties (e.g. `webkitTextStroke`) now emit a valid CSS property name (`-webkit-text-stroke`) (#281)
 
 ### [2.5.5] - 2026-07-29
 
@@ -311,15 +311,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/motion
 
-### [Unreleased]
+### [2.1.9] - 2026-08-13
 
 #### Added
 
-- `toCSSPropertyName()`, `toWAAPIPropertyName()` and `normalizeKeyframes()` utilities for converting CSS property names between their CSS and WAAPI forms
+- `toCSSPropertyName()`, `toWAAPIPropertyName()` and `normalizeKeyframes()` utilities for converting CSS property names between their CSS and WAAPI forms (#281)
 
 #### Changed
 
-- Keyframe property names may be authored in either camelCase or kebab-case and are normalized to WAAPI's camelCase on every animation path — `keyframeEffect`, presets, and effects registered via `registerEffects()`
+- Keyframe property names may be authored in either camelCase or kebab-case and are normalized to WAAPI's camelCase on every animation path — `keyframeEffect`, presets, and effects registered via `registerEffects()` (#281)
 
 ### [2.1.8] - 2026-07-29
 

packages/interact-validate/README.md

@@ -125,7 +125,7 @@ const ExperienceSchema = z.object({
 });
 ```
 
-> `InteractConfigSchema` carries a `.transform()`, so a successful `.parse()` returns the config augmented with an internal `warnings` array (`validateInteractConfig` consumes that for you). `customEffect` and function-valued `offsetEasing` are accepted as opaque functions and not deep-validated. Interactions and effects also accept `$`-prefixed plugin fields (e.g. `$splitText`) — config routed to `Interact.use()` plugins. Their schemas use `.catchall(z.unknown())` + a key check rather than `.strict()`: `$`-prefixed fields are accepted with opaque values, while any non-prefixed unknown key is still rejected as `SCHEMA_UNRECOGNIZED_KEYS`.
+> `InteractConfigSchema` carries a `.transform()`, so a successful `.parse()` returns the config augmented with an internal `warnings` array (`validateInteractConfig` consumes that for you). `customEffect` and function-valued `offsetEasing` are accepted as opaque functions and not deep-validated (a function `offsetEasing` does raise the `FUNCTION_OFFSET_EASING` warning, since `generate()` cannot compile it to CSS). Interactions and effects also accept `$`-prefixed plugin fields (e.g. `$splitText`) — config routed to `Interact.use()` plugins. Their schemas use `.catchall(z.unknown())` + a key check rather than `.strict()`: `$`-prefixed fields are accepted with opaque values, while any non-prefixed unknown key is still rejected as `SCHEMA_UNRECOGNIZED_KEYS`.
 
 ## Severity model
 
@@ -149,6 +149,7 @@ Every issue is `'error'` or `'warning'`. `valid` is `true` **iff** no `'error'`
 | `POINTER_AXIS`           | `POINTER_AXIS_IGNORED`                                                      | warning          |
 | `CSS_PROPERTY_NAME`      | `INVALID_CSS_PROPERTY_NAME`                                                 | warning          |
 | `VIEW_INSET`             | `INVALID_INSET`                                                             | warning          |
+| `OFFSET_EASING`          | `FUNCTION_OFFSET_EASING`                                                    | warning          |
 
 Set a category to `'off'` to drop those issues, or `'warning'` / `'error'` to set their severity. **All other codes** (every `SCHEMA_*`, numeric, effect-source, and referential code) are not in a category and **cannot** be silenced or re-leveled via `severityOverrides` — they always emit at their built-in severity. Precedence: `'off'` first (drops the issue), then a `'warning'`/`'error'` override, then `strict` (forces the rest to `'error'`).
 
@@ -214,6 +215,7 @@ These encode statically-detectable authoring pitfalls from the trigger rule file
 | `POINTER_AXIS_IGNORED`                 | `pointerMove` `params.axis` set on a `namedEffect`/`customEffect` (axis only applies to `keyframeEffect`).                                  | `POINTER_AXIS`           |
 | `INVALID_CSS_PROPERTY_NAME`            | A keyframe or state-effect property name is neither camelCase nor kebab-case (both are accepted).                                           | `CSS_PROPERTY_NAME`      |
 | `INVALID_INSET`                        | `viewEnter` `params.inset` is not 1–4 CSS lengths/percentages.                                                                              | `VIEW_INSET`             |
+| `FUNCTION_OFFSET_EASING`               | A sequence's `offsetEasing` is a function, so `generate()` omits that sequence from the generated CSS.                                      | `OFFSET_EASING`          |
 
 ## Usage recipes
 

packages/interact-validate/src/errors.ts

@@ -33,6 +33,7 @@ const RULE_CODE_MAP: Record<string, string> = {
   POINTER_AXIS_IGNORED: 'POINTER_AXIS',
   INVALID_CSS_PROPERTY_NAME: 'CSS_PROPERTY_NAME',
   INVALID_INSET: 'VIEW_INSET',
+  FUNCTION_OFFSET_EASING: 'OFFSET_EASING',
 };
 
 export function finalize(

packages/interact-validate/src/semantic/collectSemanticWarnings.ts

@@ -4,6 +4,7 @@
 // `collectSemanticWarnings` (consumed by the schema `transform`).
 
 import type { Path, SemanticIssue, AnyConfig, Visitors } from '../types';
+import { checkFunctionOffsetEasing } from './cssGeneration';
 import { checkCSSPropertyNames, checkInvalidInset } from './cssSyntax';
 import { checkSameElementRetrigger, checkHitAreaShift } from './fouc';
 import {
@@ -86,6 +87,7 @@ export function collectSemanticWarnings(config: AnyConfig): SemanticIssue[] {
           ? { ...((config.sequences ?? {})[sequenceId] ?? {}), ...sequence }
           : sequence;
       warnings.push(...checkSameElementRetrigger(path, resolvedSequence, owner));
+      warnings.push(...checkFunctionOffsetEasing(path, sequence));
     },
   });
 

packages/interact-validate/src/semantic/cssGeneration.ts

@@ -0,0 +1,20 @@
+import type { Path, SemanticIssue, AnySequence } from '../types';
+
+// `generate()` compiles a sequence's stagger into a `calc()` delay driven by
+// `--motion-<sequenceId>-index` custom properties, so `offsetEasing` has to be a string it can
+// turn into CSS math. A `(p: number) => number` function has no CSS equivalent, and the whole
+// sequence is dropped from the generated CSS — it still animates once Interact initializes, but
+// nothing is pre-rendered, so a `viewEnter` sequence loses its FOUC-prevention rules.
+export function checkFunctionOffsetEasing(path: Path, sequence: AnySequence): SemanticIssue[] {
+  if (typeof sequence.offsetEasing !== 'function') return [];
+
+  return [
+    {
+      code: 'custom',
+      params: { domainCode: 'FUNCTION_OFFSET_EASING' },
+      path: [...path, 'offsetEasing'],
+      message:
+        'A function `offsetEasing` cannot be expressed in CSS, so `generate()` omits this sequence from the generated CSS (an entrance sequence loses FOUC prevention). Use a named easing, `cubic-bezier(...)`, or `linear(...)`.',
+    },
+  ];
+}

packages/interact-validate/src/types.ts

@@ -53,6 +53,7 @@ export type AnyEffect = {
 export type AnySequence = {
   triggerType?: string;
   sequenceId?: string;
+  offsetEasing?: string | ((...args: unknown[]) => unknown);
   effects?: AnyEffect[];
   conditions?: string[];
 };

packages/interact-validate/test/rules/hitAreaShift.spec.ts

@@ -33,7 +33,7 @@ describe('hitAreaShift — HIT_AREA_SHIFT', () => {
     expect(result.valid).toBe(true);
   });
 
-  it('warns for a pointerMove keyframeEffect with a scale transform (default hitArea: self)', () => {
+  it('does not warns for a pointerMove keyframeEffect with a scale transform (default hitArea: root)', () => {
     const result = validateInteractConfig({
       interactions: [
         {
@@ -48,7 +48,7 @@ describe('hitAreaShift — HIT_AREA_SHIFT', () => {
         },
       ],
     });
-    expect(result.errors.some((e) => e.code === CODE)).toBe(true);
+    expect(result.errors.some((e) => e.code === CODE)).toBe(false);
   });
 
   describe('no warning for the documented valid patterns', () => {

packages/interact-validate/test/rules/offsetEasing.spec.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import { validateInteractConfig } from '../../src';
+
+const EFFECTS = [{ namedEffect: { type: 'FadeIn' }, duration: 400 }];
+
+describe('offsetEasing', () => {
+  describe('FUNCTION_OFFSET_EASING (warning)', () => {
+    it('warns on an inline sequence with a function offsetEasing', () => {
+      const result = validateInteractConfig({
+        interactions: [
+          {
+            key: 'el',
+            trigger: 'viewEnter',
+            sequences: [{ offset: 100, offsetEasing: (p: number) => p ** 2, effects: EFFECTS }],
+          },
+        ],
+      });
+      const err = result.errors.find((e) => e.code === 'FUNCTION_OFFSET_EASING');
+
+      expect(err).toBeDefined();
+      expect(err?.severity).toBe('warning');
+      expect(err?.path).toEqual(['interactions', 0, 'sequences', 0, 'offsetEasing']);
+      expect(result.valid).toBe(true);
+    });
+
+    it('warns once, at the definition, for a referenced registry sequence', () => {
+      const result = validateInteractConfig({
+        sequences: {
+          stagger: { offset: 100, offsetEasing: (p: number) => p ** 2, effects: EFFECTS },
+        },
+        interactions: [
+          { key: 'el', trigger: 'viewEnter', sequences: [{ sequenceId: 'stagger' }] },
+          { key: 'el2', trigger: 'viewEnter', sequences: [{ sequenceId: 'stagger' }] },
+        ],
+      });
+      const errs = result.errors.filter((e) => e.code === 'FUNCTION_OFFSET_EASING');
+
+      expect(errs).toHaveLength(1);
+      expect(errs[0].path).toEqual(['sequences', 'stagger', 'offsetEasing']);
+    });
+
+    it('warns when a reference overrides a string easing with a function', () => {
+      const result = validateInteractConfig({
+        sequences: { stagger: { offset: 100, offsetEasing: 'quadIn', effects: EFFECTS } },
+        interactions: [
+          {
+            key: 'el',
+            trigger: 'viewEnter',
+            sequences: [{ sequenceId: 'stagger', offsetEasing: (p: number) => p ** 2 }],
+          },
+        ],
+      });
+      const errs = result.errors.filter((e) => e.code === 'FUNCTION_OFFSET_EASING');
+
+      expect(errs).toHaveLength(1);
+      expect(errs[0].path).toEqual(['interactions', 0, 'sequences', 0, 'offsetEasing']);
+    });
+
+    it.each(['linear', 'quadIn', 'cubic-bezier(0.25, 0.1, 0.25, 1)', 'linear(0, 0.5 50%, 1)'])(
+      'does not warn for the string easing %s',
+      (offsetEasing) => {
+        const result = validateInteractConfig({
+          interactions: [
+            {
+              key: 'el',
+              trigger: 'viewEnter',
+              sequences: [{ offset: 100, offsetEasing, effects: EFFECTS }],
+            },
+          ],
+        });
+
+        expect(result.errors.filter((e) => e.code === 'FUNCTION_OFFSET_EASING')).toHaveLength(0);
+      },
+    );
+
+    it('does not warn when offsetEasing is omitted', () => {
+      const result = validateInteractConfig({
+        interactions: [
+          {
+            key: 'el',
+            trigger: 'viewEnter',
+            sequences: [{ offset: 100, effects: EFFECTS }],
+          },
+        ],
+      });
+
+      expect(result.errors.filter((e) => e.code === 'FUNCTION_OFFSET_EASING')).toHaveLength(0);
+    });
+  });
+
+  describe('OFFSET_EASING rule category', () => {
+    const config = {
+      interactions: [
+        {
+          key: 'el',
+          trigger: 'viewEnter',
+          sequences: [{ offset: 100, offsetEasing: (p: number) => p ** 2, effects: EFFECTS }],
+        },
+      ],
+    };
+
+    it('can be silenced via severityOverrides', () => {
+      const result = validateInteractConfig(config, {
+        severityOverrides: { OFFSET_EASING: 'off' },
+      });
+
+      expect(result.errors.filter((e) => e.code === 'FUNCTION_OFFSET_EASING')).toHaveLength(0);
+    });
+
+    it('can be demoted to info', () => {
+      const result = validateInteractConfig(config, {
+        severityOverrides: { OFFSET_EASING: 'info' },
+      });
+
+      expect(result.errors.find((e) => e.code === 'FUNCTION_OFFSET_EASING')?.severity).toBe('info');
+    });
+
+    it('is promoted to an error by strict', () => {
+      const result = validateInteractConfig(config, { strict: true });
+
+      expect(result.errors.find((e) => e.code === 'FUNCTION_OFFSET_EASING')?.severity).toBe(
+        'error',
+      );
+      expect(result.valid).toBe(false);
+    });
+  });
+});

packages/interact/docs/api/types.md

@@ -772,8 +772,8 @@ type SequenceOptionsConfig = {
 
 - `delay` - Base delay (ms) applied to all effects in the sequence. Default: `0`.
 - `offset` - Stagger interval (ms) between consecutive effects. Default: `0`.
-- `offsetEasing` - Easing function or named string for offset distribution (`'linear'`, `'quadIn'`, `'sineOut'`, etc.). Default: `linear`.
-- `sequenceId` - Optional ID for referencing a reusable sequence from `InteractConfig.sequences`.
+- `offsetEasing` - Easing function or named string for offset distribution (`'linear'`, `'quadIn'`, `'sineOut'`, etc.). Default: `linear`. Only string easings can be compiled into generated CSS — a function excludes the sequence from `generate()`'s output. See [Stagger in Generated CSS](../guides/sequences.md#stagger-in-generated-css).
+- `sequenceId` - Optional ID for referencing a reusable sequence from `InteractConfig.sequences`. Also names the `--motion-<sequenceId>-index` custom properties that carry the stagger in generated CSS. Defaults to `seq-<interactionIndex>-<sequenceIndex>`, derived from the config position so CSS generation and the runtime agree.
 - `conditions` - Optional array of condition IDs. When set, the sequence is only active when all conditions match.
 - `triggerType` - Controls play behavior for event trigger sequences (`hover`, `click`, `activate`, `interest`, `viewEnter`). Same values as `TimeEffect.triggerType`: `'once'` (default for viewEnter), `'alternate'` (default for hover/click), `'repeat'`, `'state'`.
 

packages/interact/docs/examples/list-patterns.md

@@ -904,6 +904,10 @@ Different `offsetEasing` values produce distinct stagger patterns:
 { offset: 80, offsetEasing: 'sineOut' }
 ```
 
+Any string easing works — named keys, `cubic-bezier(...)`, or `linear(...)`. Keep it a string rather than a
+function if the list should also be staggered by generated CSS; see
+[Stagger in Generated CSS](../guides/sequences.md#stagger-in-generated-css).
+
 ### 20. Reusable Sequences with `sequenceId`
 
 Define a sequence once, reference it from multiple interactions: