diff --git a/skills/wix-app/references/EDITOR_REACT_COMPONENT.md b/skills/wix-app/references/EDITOR_REACT_COMPONENT.md index a8f452a1..e7a63c41 100644 --- a/skills/wix-app/references/EDITOR_REACT_COMPONENT.md +++ b/skills/wix-app/references/EDITOR_REACT_COMPONENT.md @@ -58,6 +58,7 @@ Topic-focused references (rules + patterns + common mistakes in one place): - [`editor-react-component/DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) — RTL/LTR rules and patterns - [`editor-react-component/PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) — What should be a React prop vs CSS - [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props +- [`editor-react-component/FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) — Standard SDK event handler props, DOM wiring, custom callbacks - [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, remaining common mistakes ## CSS guidelines diff --git a/skills/wix-app/references/editor-react-component/COMPONENT-API.md b/skills/wix-app/references/editor-react-component/COMPONENT-API.md index 60e7f23b..06bb6751 100644 --- a/skills/wix-app/references/editor-react-component/COMPONENT-API.md +++ b/skills/wix-app/references/editor-react-component/COMPONENT-API.md @@ -163,6 +163,11 @@ When creating TypeScript interfaces for component props, use types from `@wix/ed import type { Link } from "@wix/editor-react-types"; // Reference at node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts ``` +For **function event handler props** (onClick, onDblClick, onChange, onFocus, onBlur, onMouseIn, onMouseOut) and custom callbacks, follow [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md). Key rules: +- Use the exact SDK prop names from that file — the manifest system recognizes them +- Wire them to the correct DOM events (note: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`) +- Custom callbacks not tied to DOM events use `() => void` (no React event parameter) + ### External resources are forbidden All resources rendered or fetched by the component (images, icons, fonts, diff --git a/skills/wix-app/references/editor-react-component/FUNCTION-HANDLERS.md b/skills/wix-app/references/editor-react-component/FUNCTION-HANDLERS.md new file mode 100644 index 00000000..16f4cfac --- /dev/null +++ b/skills/wix-app/references/editor-react-component/FUNCTION-HANDLERS.md @@ -0,0 +1,169 @@ +# Function Event Handlers + +Rules and patterns for adding function event handler props to an Editor React component's TypeScript interface, wiring them to DOM events, and declaring custom callbacks. + +--- + +## Rules + +### Standard SDK Event Handlers + +These are the standard event handler props the editor SDK exposes to site owners. Use the exact prop names — ZeroConfig and the manifest system recognize them. + +| Prop name | React DOM event | Type | +| ------------ | --------------- | ------------------------------------- | +| `onClick` | `onClick` | `(event: React.MouseEvent) => void` | +| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void` | +| `onChange` | `onChange` | `(event: React.ChangeEvent) => void` | +| `onFocus` | `onFocus` | `(event: React.FocusEvent) => void` | +| `onBlur` | `onBlur` | `(event: React.FocusEvent) => void` | +| `onMouseIn` | `onMouseEnter` | `(event: React.MouseEvent) => void` | +| `onMouseOut` | `onMouseLeave` | `(event: React.MouseEvent) => void` | + +Three props have a **name mismatch** between the SDK prop and the DOM event: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`. + +### Declaring Standard Handler Props + +Declare standard handlers inline with the exact SDK prop names and React event types: + +```typescript +interface MyComponentProps { + label?: string; + onClick?: (event: React.MouseEvent) => void; + onDblClick?: (event: React.MouseEvent) => void; + onChange?: (event: React.ChangeEvent) => void; + onFocus?: (event: React.FocusEvent) => void; + onBlur?: (event: React.FocusEvent) => void; + onMouseIn?: (event: React.MouseEvent) => void; + onMouseOut?: (event: React.MouseEvent) => void; +} +``` + +Only declare handlers the component actually exposes. Do not add all seven if the component only handles two. + +### Wiring Standard Handlers to DOM Events + +Destructure the props and pass them to the correct DOM event — applying the name mappings: + +```typescript +export const MyComponent = (props: MyComponentProps) => { + const { onClick, onDblClick, onFocus, onBlur, onMouseIn, onMouseOut } = props; + return ( +
+ {/* ... */} +
+ ); +}; +``` + +### Custom Callbacks + +Component-specific callbacks that do not correspond to a DOM event (e.g., `onPlay`, `onPause`, `onEnded`, `onTimeupdate`) are **not** standard SDK event handlers. Type them as `() => void` — no React event parameter: + +```typescript +interface VideoPlayerProps { + onPlay?: () => void; + onPause?: () => void; + onEnded?: () => void; +} +``` + +Pass them directly to the underlying element — no name remapping needed: + +```typescript +export const VideoPlayer = (props: VideoPlayerProps) => { + const { onPlay, onPause, onEnded } = props; + return ( +