@wix/agent-skills 1.16.0 → 1.16.2

package/skills/wix-app/references/editor-react-component/FUNCTION-HANDLERS.md

@@ -0,0 +1,167 @@
+# 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<HTMLElement>) => 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<HTMLElement>) => 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 (
+    <div
+      onClick={onClick}
+      onDoubleClick={onDblClick}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      onMouseEnter={onMouseIn}
+      onMouseLeave={onMouseOut}
+    >
+      {/* ... */}
+    </div>
+  );
+};
+```
+
+### 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 <video onPlay={onPlay} onPause={onPause} onEnded={onEnded} />;
+};
+```
+
+---
+
+## Common Mistakes
+
+### Passing SDK prop name directly to DOM instead of remapping
+
+**❌ Wrong:**
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onMouseIn, onMouseOut, onDblClick } = props;
+  return (
+    <div
+      onMouseIn={onMouseIn} // ❌ not a valid React DOM prop
+      onMouseOut={onMouseOut} // ❌ not a valid React DOM prop
+      onDblClick={onDblClick} // ❌ not a valid React DOM prop
+    />
+  );
+};
+```
+
+**✅ Correct:**
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onMouseIn, onMouseOut, onDblClick } = props;
+  return (
+    <div
+      onMouseEnter={onMouseIn} // ✅ onMouseIn → onMouseEnter
+      onMouseLeave={onMouseOut} // ✅ onMouseOut → onMouseLeave
+      onDoubleClick={onDblClick} // ✅ onDblClick → onDoubleClick
+    />
+  );
+};
+```
+
+### Adding a React event parameter to custom callbacks
+
+**❌ Wrong:**
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
+  onEnded?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
+}
+```
+
+**✅ Correct:**
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: () => void; // ✅ no event param
+  onEnded?: () => void; // ✅ no event param
+}
+```
+
+**Why:** Custom callbacks are component-level notifications to the site owner, not DOM event forwarders. They carry no event object — the SDK passes no event to them.
+
+### Using the DOM event name as the SDK prop name
+
+**❌ Wrong:**
+
+```typescript
+interface MyComponentProps {
+  onDoubleClick?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+  onMouseEnter?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+  onMouseLeave?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+}
+```
+
+**✅ Correct:**
+
+```typescript
+interface MyComponentProps {
+  onDblClick?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+  onMouseIn?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+  onMouseOut?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+}
+```
+
+**Why:** The SDK prop names (`onDblClick`, `onMouseIn`, `onMouseOut`) are what ZeroConfig and the manifest system register. Using DOM names breaks the editor's event wiring.

package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md

@@ -9,6 +9,7 @@ This guide defines rules and guidance on **how to implement** production-quality
 - [`DIRECTIONALITY.md`](DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
+- [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md) — Standard SDK event handler props, DOM wiring, custom callbacks
 - [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
 - [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
@@ -110,7 +111,7 @@ Unless explicitly specified as a component capability/API in the specification,
 **External handlers (only when specified):**
 
 - Only expose handlers that are explicitly listed as component capabilities
-- Example: If specification says "onClick callback for external control", then add `onClick?: () => void` to props
+- Use the standard SDK prop names and DOM wiring rules from [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md)
 
 **Child component handlers:**
 
@@ -170,4 +171,3 @@ See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.
 **Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data ([`DESIGN-STATES.md`](DESIGN-STATES.md))
 
 **Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md)). If the request uses the words **branded**, **themed**, or **brand-aware**, also apply [`BRANDED-COMPONENTS.md`](BRANDED-COMPONENTS.md) before writing CSS.
-

package/skills/wix-app/references/editor-react-component/SITE-CONTEXT-HOOKS.md

@@ -0,0 +1,187 @@
+# Site Context Hooks
+
+Rules and patterns for reading **runtime site context** in Editor React
+components — the site's page tree, the current URL, the language direction, and
+editor mode. None of these can be carried by a prop.
+
+All of them come from hooks in `@wix/react-component-utils`, already a base
+dependency. No additional install is needed, but the hooks require
+`@wix/react-component-utils` ≥ 1.12.0.
+
+---
+
+## When this applies
+
+Apply only when the component genuinely needs live site context:
+
+- **The component reflects where the visitor is in the site** — breadcrumbs,
+  "you are here" indicators. Not navigation menus: the site owner authors those,
+  and their items need not necessarily be site pages, so they take a
+  `MenuItems` prop
+- **The component needs the page's own URL** — share buttons, copy-link,
+  canonical links, QR codes
+- **Language direction drives JavaScript** — keyboard navigation, transform or
+  animation math, conditional rendering
+- **Behavior must differ inside the editor** — suppressing autoplay, network
+  calls, or timers while the site owner is designing
+
+The test is whether the site owner **authors** the data. A hook reports state the
+owner cannot write — which page is being rendered, what the site's URL is. Data
+the owner chooses belongs in props, even when it happens to point at site
+pages — see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and
+[`COMPONENT-API.md`](COMPONENT-API.md). Purely visual RTL needs no hook
+either — use logical CSS properties, see
+[`DIRECTIONALITY.md`](DIRECTIONALITY.md).
+
+---
+
+## Rules
+
+### The Available Hooks
+
+| Hook | Returns | Use for |
+| --- | --- | --- |
+| `usePages()` | `Readonly<Record<string, PageConfig>>` | Every page on the site, keyed by page id |
+| `useCurrentPageId()` | `string` | Id of the page being rendered |
+| `useMainPageId()` | `string` | Id of the site's homepage |
+| `useSiteUrl()` | `string` | The site's public base URL |
+| `useCurrentUrl()` | `string` | Full URL of the page being rendered |
+| `useLanguageDirection()` | `'ltr' \| 'rtl'` | The site's language direction |
+| `useIsEditMode()` | `boolean` | `true` in editor design mode — see [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) |
+| `useReducedMotion()` | `boolean` | `true` when the OS requests reduced motion — see [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) |
+
+All import from the same place:
+
+```typescript
+import { usePages, useCurrentPageId, useSiteUrl } from '@wix/react-component-utils';
+```
+
+Each returns a plain value, so there is nothing to unwrap or guard. They are
+React hooks — call them at the top of the component or hook body, never at module
+scope, inside a callback, or conditionally.
+
+### Read Values During Render
+
+Hook values are read on the server too, so their results are part of the server
+markup — see [`SSR.md`](SSR.md). Use the value directly.
+
+**✅ Correct:**
+
+```tsx
+const siteUrl = useSiteUrl();
+```
+
+**❌ Wrong — empty on the server, then a hydration mismatch:**
+
+```tsx
+const resolvedUrl = useSiteUrl();
+const [siteUrl, setSiteUrl] = useState('');
+useEffect(() => setSiteUrl(resolvedUrl), []);
+```
+
+---
+
+## Patterns
+
+### Walking the Page Tree
+
+`usePages()` returns a map keyed by page id. Three things to get right:
+
+- **The map key is the page id** — the values carry no `id` field.
+- **`parentPageId` is absent for top-level pages** — treat those as children of
+  `useMainPageId()` when walking upward.
+- **`popup: true` pages are lightboxes**, not navigable pages. Filter them out of
+  breadcrumbs, menus, and page pickers.
+
+```tsx
+import { usePages, useCurrentPageId, useMainPageId } from '@wix/react-component-utils';
+
+export const useBreadcrumbTrail = (): Array<{ id: string; label: string }> => {
+  const pages = usePages();
+  const currentPageId = useCurrentPageId();
+  const mainPageId = useMainPageId();
+
+  const trail: Array<{ id: string; label: string }> = [];
+  const visited = new Set<string>();
+  let pageId: string | undefined = currentPageId;
+
+  while (pageId && !visited.has(pageId) && pages[pageId]) {
+    visited.add(pageId);
+    const page = pages[pageId]!;
+    if (!page.popup) {
+      trail.push({ id: pageId, label: page.title });
+    }
+    // Pages without parentPageId are top-level children of the homepage.
+    pageId = pageId === mainPageId ? undefined : (page.parentPageId ?? mainPageId);
+  }
+
+  return trail.reverse();
+};
+```
+
+The `visited` set is not optional — a misconfigured site can produce a parent
+cycle, and an unguarded walk hangs the render.
+
+### Building a Link to a Page
+
+Join a page's `path` onto `useSiteUrl()`. The base URL may or may not carry a
+trailing slash, so normalize before joining:
+
+```typescript
+const buildPageUrl = (path: string, siteUrl: string): string => {
+  const base = siteUrl.replace(/\/$/, '');
+  return path ? `${base}/${path}` : base;
+};
+```
+
+### Direction-Dependent Logic
+
+Resolve the component's own `direction` prop first, then fall back to the site:
+
+```typescript
+import type { Direction } from '@wix/editor-react-types';
+import { useLanguageDirection } from '@wix/react-component-utils';
+
+export const useResolvedDirection = (direction?: Direction): Direction => {
+  // Call unconditionally — `direction ?? useLanguageDirection()` would
+  // short-circuit and skip the hook whenever the prop is set.
+  const siteDirection = useLanguageDirection() as Direction;
+  return direction ?? siteDirection;
+};
+```
+
+Use the resolved value for **logic only** — arrow-key handling, transform sign,
+scroll direction:
+
+```tsx
+const isRTL = useResolvedDirection(direction) === 'rtl';
+
+const onKeyDown = (event: React.KeyboardEvent) => {
+  const forward = isRTL ? 'ArrowLeft' : 'ArrowRight';
+  if (event.key === forward) {
+    focusNext();
+  }
+};
+```
+
+---
+
+## Common Mistake: Direction Logic Instead of Logical CSS
+
+Calling `useLanguageDirection()` to pick between physical CSS properties.
+
+**❌ Wrong:**
+
+```tsx
+const isRTL = useLanguageDirection() === 'rtl';
+
+<div style={{ paddingLeft: isRTL ? 0 : 8, paddingRight: isRTL ? 8 : 0 }} />
+```
+
+**✅ Correct:**
+
+```scss
+.element {
+  padding-inline-start: 8px; // Auto RTL/LTR, no hook needed
+}
+```