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

Author: ameerf-wix

.github/workflows/release-splittext.yml

@@ -80,6 +80,14 @@ jobs:
       - name: Build splittext package
         run: yarn workspace @wix/splittext build
 
+      # @wix/interact is a devDependency used only by the plugin-bridge integration test —
+      # splittext itself neither builds nor runs against it (note the build step above runs first).
+      - name: Build motion package (test-only dependency of @wix/interact)
+        run: yarn workspace @wix/motion build
+
+      - name: Build interact package (test-only dependency)
+        run: yarn workspace @wix/interact build
+
       - name: Test splittext package
         run: yarn workspace @wix/splittext test
 

CHANGELOG.md

@@ -10,6 +10,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/splittext
 
+### [0.2.0] - unreleased
+
+#### Added
+
+- `@wix/splittext/plugin` entry points: `splitTextPlugin` for `Interact.use()`, and `splitTextStyle` for `generate()` (#275)
+- `hideUntilReady`: `splitTextStyle` hides the container until the runtime split sets `data-splittext-ready` (#275)
+
 ### [0.1.2] - 2026-07-14
 
 #### Added
@@ -26,6 +33,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/interact-validate
 
+### [0.2.0] - unreleased
+
+#### Added
+
+- Plugin fields: `$`-prefixed keys on interactions and effects are accepted; every other unknown key is still reported as `SCHEMA_UNRECOGNIZED_KEYS` (#275)
+
+#### Changed
+
+- `KEYFRAME_PROP_NOT_CAMEL_CASE` (rule category `KEYFRAME_STYLE`) is replaced by `INVALID_CSS_PROPERTY_NAME` (rule category `CSS_PROPERTY_NAME`): both camelCase and kebab-case CSS property names are valid input, so only names that are neither are reported, and the check now covers `transition.styleProperties` / `transitionProperties` names in addition to `keyframeEffect` keyframes
+- `severityOverrides` keyed on `KEYFRAME_STYLE` are now silently ignored. Rename the key to `CSS_PROPERTY_NAME` to keep an override in effect
+
 ### [0.1.2] - 2026-07-29
 
 #### Added
@@ -63,6 +81,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/interact
 
+### [2.6.0] - unreleased
+
+#### Added
+
+- Generic plugin bridge: `Interact.use(name, plugin)` registers a plugin, and a `$<name>` field on an interaction or effect (#275)
+- `generate()` accepts a `plugins` option — a map of plugin name → build-time style generator (#275)
+
+#### 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
+
+#### 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`)
+
 ### [2.5.5] - 2026-07-29
 
 #### Fixed
@@ -275,6 +311,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/motion
 
+### [Unreleased]
+
+#### Added
+
+- `toCSSPropertyName()`, `toWAAPIPropertyName()` and `normalizeKeyframes()` utilities for converting CSS property names between their CSS and WAAPI forms
+
+#### 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()`
+
 ### [2.1.8] - 2026-07-29
 
 #### Added

apps/demo/package.json

@@ -7,11 +7,11 @@
     "dev": "vite",
     "build": "tsc && vite build",
     "preview": "vite preview",
-    "lint": "tsc --noEmit",
-    "test": "vitest run"
+    "lint": "tsc --noEmit"
   },
   "dependencies": {
     "@wix/interact": "^2.5.5",
+    "@wix/splittext": "^0.1.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },

apps/demo/src/plugins/splitText.ts

@@ -0,0 +1,29 @@
+/**
+ * Demo-side glue for the reusable `@wix/splittext` Interact plugin.
+ *
+ * The plugin itself now lives in `@wix/splittext/plugin`, which ships WITHOUT a dependency on
+ * `@wix/interact` so the two packages stay decoupled. This file is where the demo — the one place
+ * that depends on BOTH — "resolves the typing":
+ *
+ *  1. It binds the package's structurally-typed callbacks to Interact's real `InteractPlugin` /
+ *     `InteractPluginStyleGenerator` contract. The assignments below double as a compile-time
+ *     check that `@wix/splittext/plugin` stays compatible with `@wix/interact`.
+ *  2. It ties the `$splitText` config field to {@link SplitTextPluginConfig} via declaration
+ *     merging on `InteractPluginConfigMap`, so demo configs get autocomplete + checking.
+ */
+import type { InteractPlugin, InteractPluginStyleGenerator } from '@wix/interact';
+import {
+  splitTextPlugin as splitTextPluginImpl,
+  splitTextStyle as splitTextStyleImpl,
+  type SplitTextPluginConfig,
+} from '@wix/splittext/plugin';
+
+export const splitTextPlugin: InteractPlugin = splitTextPluginImpl;
+export const splitTextStyle: InteractPluginStyleGenerator = splitTextStyleImpl;
+export type { SplitTextPluginConfig };
+
+declare module '@wix/interact' {
+  interface InteractPluginConfigMap {
+    splitText: SplitTextPluginConfig;
+  }
+}

apps/demo/tsconfig.json

@@ -8,7 +8,8 @@
       "@/*": ["./src/*"],
       "@wix/interact/web": ["../../packages/interact/src/web"],
       "@wix/interact/react": ["../../packages/interact/src/react"],
-      "@wix/interact": ["../../packages/interact/src/index"]
+      "@wix/interact": ["../../packages/interact/src/index"],
+      "@wix/splittext/plugin": ["../../packages/splittext/dist/types/plugin/index"]
     }
   },
   "include": ["src"],

apps/playground/SPEC.md

@@ -339,7 +339,7 @@ For authoring custom `keyframeEffect` animations (`{ name: string; keyframes: Ke
   - Optional `offset` (0–1, step 0.01) — shown for 3+ keyframes
   - CSS property/value rows with text inputs
   - Property name autocomplete via `<datalist>` (opacity, transform, background-color, clip-path, filter, border-radius, etc.)
-  - Kebab-case input auto-converts to camelCase on blur (Web Animations API requirement)
+  - Kebab-case input auto-converts to camelCase on blur (display preference — Interact accepts either casing)
   - Add/remove property rows (min 1 per keyframe)
 - **Add Keyframe** button — appends an empty keyframe
 - Remove keyframe button (min 1 keyframe enforced)

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.
+> `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`.
 
 ## Severity model
 
@@ -147,7 +147,7 @@ Every issue is `'error'` or `'warning'`. `valid` is `true` **iff** no `'error'`
 | `STATE_EFFECT`           | `EMPTY_STYLE_PROPERTIES`, `STATE_REMOVE_WITHOUT_EFFECT_ID`                  | warning          |
 | `RECOMMENDED_FILL`       | `RECOMMENDED_FILL_BOTH`                                                     | info             |
 | `POINTER_AXIS`           | `POINTER_AXIS_IGNORED`                                                      | warning          |
-| `KEYFRAME_STYLE`         | `KEYFRAME_PROP_NOT_CAMEL_CASE`                                              | warning          |
+| `CSS_PROPERTY_NAME`      | `INVALID_CSS_PROPERTY_NAME`                                                 | warning          |
 | `VIEW_INSET`             | `INVALID_INSET`                                                             | 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'`).
@@ -212,7 +212,7 @@ These encode statically-detectable authoring pitfalls from the trigger rule file
 | `RECOMMENDED_FILL_BOTH`                | A scrubbed (`viewProgress`/`pointerMove`) or toggling (`alternate`/`repeat`/`state`) effect omits `fill: 'both'`.                           | `RECOMMENDED_FILL`       |
 | `RECOMMENDED_FILL_BACKWARDS`           | A `viewEnter` + `once` named/keyframe effect targeting another element or using a same-element delay omits `fill: 'backwards'` or `'both'`. | `RECOMMENDED_FILL`       |
 | `POINTER_AXIS_IGNORED`                 | `pointerMove` `params.axis` set on a `namedEffect`/`customEffect` (axis only applies to `keyframeEffect`).                                  | `POINTER_AXIS`           |
-| `KEYFRAME_PROP_NOT_CAMEL_CASE`         | A `keyframeEffect` property name is kebab-case (not WAAPI camelCase).                                                                       | `KEYFRAME_STYLE`         |
+| `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`             |
 
 ## Usage recipes

packages/interact-validate/src/errors.ts

@@ -31,7 +31,7 @@ const RULE_CODE_MAP: Record<string, string> = {
   RECOMMENDED_FILL_BOTH: 'RECOMMENDED_FILL',
   RECOMMENDED_FILL_BACKWARDS: 'RECOMMENDED_FILL',
   POINTER_AXIS_IGNORED: 'POINTER_AXIS',
-  KEYFRAME_PROP_NOT_CAMEL_CASE: 'KEYFRAME_STYLE',
+  INVALID_CSS_PROPERTY_NAME: 'CSS_PROPERTY_NAME',
   INVALID_INSET: 'VIEW_INSET',
 };
 

packages/interact-validate/src/schema/effects.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { Keyframe, RangeOffset } from './primitives';
+import { withPluginFields } from './plugins';
 
 export const StateActionType = z.enum(['add', 'remove', 'toggle', 'clear']);
 export const TimeTriggerType = z.enum(['once', 'repeat', 'alternate', 'state']);
@@ -132,19 +133,19 @@ const EffectBase = {
   conditions: z.array(z.string().min(1)).optional(),
 };
 
-export const StateEffect = TransitionEffectSourceBase.extend({
-  ...EffectBase,
-  stateAction: StateActionType.optional(),
-})
-  .strict()
-  .check(checkExactlyOneTransition);
-export const StateEffectRef = TransitionEffectSourceBase.extend({
-  ...EffectBase,
-  effectId: z.string().min(1),
-  stateAction: StateActionType.optional(),
-})
-  .strict()
-  .check(checkAtMostOneTransition);
+export const StateEffect = withPluginFields(
+  TransitionEffectSourceBase.extend({
+    ...EffectBase,
+    stateAction: StateActionType.optional(),
+  }),
+).check(checkExactlyOneTransition);
+export const StateEffectRef = withPluginFields(
+  TransitionEffectSourceBase.extend({
+    ...EffectBase,
+    effectId: z.string().min(1),
+    stateAction: StateActionType.optional(),
+  }),
+).check(checkAtMostOneTransition);
 
 const AnimationEffectBase = {
   ...EffectBase,
@@ -167,57 +168,57 @@ const pointerMoveEffectFields = {
   transitionEasing: z.enum(['linear', 'hardBackOut', 'easeOut', 'elastic', 'bounce']).optional(),
 };
 
-export const TimeEffect = EffectSourceBase.extend({
-  ...AnimationEffectBase,
-  iterations: TimeIterations,
-  duration: z.number().nonnegative(),
-  delay: z.number().nonnegative().optional(),
-  triggerType: TimeTriggerType.optional(),
-})
-  .strict()
-  .check(checkExactlyOneEffectSource);
-export const TimeEffectRef = EffectSourceBase.extend({
-  ...AnimationEffectBase,
-  iterations: TimeIterations,
-  effectId: z.string().min(1),
-  duration: z.number().nonnegative().optional(),
-  delay: z.number().nonnegative().optional(),
-  triggerType: TimeTriggerType.optional(),
-})
-  .strict()
-  .check(checkAtMostOneEffectSource);
-
-export const ViewProgressEffect = EffectSourceBase.extend({
-  ...AnimationEffectBase,
-  iterations: ScrubIterations,
-  ...viewProgressEffectFields,
-})
-  .strict()
-  .check(checkExactlyOneEffectSource);
-export const ViewProgressEffectRef = EffectSourceBase.extend({
-  ...AnimationEffectBase,
-  iterations: ScrubIterations,
-  effectId: z.string().min(1),
-  ...viewProgressEffectFields,
-})
-  .strict()
-  .check(checkAtMostOneEffectSource);
-
-export const PointerMoveEffect = EffectSourceBase.extend({
-  ...AnimationEffectBase,
-  iterations: ScrubIterations,
-  ...pointerMoveEffectFields,
-})
-  .strict()
-  .check(checkExactlyOneEffectSource);
-export const PointerMoveEffectRef = EffectSourceBase.extend({
-  ...AnimationEffectBase,
-  iterations: ScrubIterations,
-  effectId: z.string().min(1),
-  ...pointerMoveEffectFields,
-})
-  .strict()
-  .check(checkAtMostOneEffectSource);
+export const TimeEffect = withPluginFields(
+  EffectSourceBase.extend({
+    ...AnimationEffectBase,
+    iterations: TimeIterations,
+    duration: z.number().nonnegative(),
+    delay: z.number().nonnegative().optional(),
+    triggerType: TimeTriggerType.optional(),
+  }),
+).check(checkExactlyOneEffectSource);
+export const TimeEffectRef = withPluginFields(
+  EffectSourceBase.extend({
+    ...AnimationEffectBase,
+    iterations: TimeIterations,
+    effectId: z.string().min(1),
+    duration: z.number().nonnegative().optional(),
+    delay: z.number().nonnegative().optional(),
+    triggerType: TimeTriggerType.optional(),
+  }),
+).check(checkAtMostOneEffectSource);
+
+export const ViewProgressEffect = withPluginFields(
+  EffectSourceBase.extend({
+    ...AnimationEffectBase,
+    iterations: ScrubIterations,
+    ...viewProgressEffectFields,
+  }),
+).check(checkExactlyOneEffectSource);
+export const ViewProgressEffectRef = withPluginFields(
+  EffectSourceBase.extend({
+    ...AnimationEffectBase,
+    iterations: ScrubIterations,
+    effectId: z.string().min(1),
+    ...viewProgressEffectFields,
+  }),
+).check(checkAtMostOneEffectSource);
+
+export const PointerMoveEffect = withPluginFields(
+  EffectSourceBase.extend({
+    ...AnimationEffectBase,
+    iterations: ScrubIterations,
+    ...pointerMoveEffectFields,
+  }),
+).check(checkExactlyOneEffectSource);
+export const PointerMoveEffectRef = withPluginFields(
+  EffectSourceBase.extend({
+    ...AnimationEffectBase,
+    iterations: ScrubIterations,
+    effectId: z.string().min(1),
+    ...pointerMoveEffectFields,
+  }),
+).check(checkAtMostOneEffectSource);
 
 export const ScrubEffect = z.union([ViewProgressEffect, PointerMoveEffect]);
 export const ScrubEffectRef = z.union([ViewProgressEffectRef, PointerMoveEffectRef]);