@wix/agent-skills 1.0.0

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

@@ -0,0 +1,170 @@
+# Component Directionality (RTL/LTR)
+
+Rules and patterns for direction support in Editor React components.
+
+---
+
+## Rules
+
+Direction support is mandatory for every component. The pattern uses native HTML `dir` attributes for standards-compliant, accessible directionality support, with mandatory fallback classes on root components.
+
+### Direction Resolution
+
+```typescript
+const subComponentDirection = elementProps?.subComponent?.direction;
+```
+
+- Sub-component directions only applied when explicitly set (to override inherited direction)
+- When undefined: inherits direction from parent via CSS inheritance
+- Root component always gets fallback class
+
+### Direction Anti-Patterns
+
+```scss
+/* ❌ Don't use CSS variables for direction */
+.component { direction: var(--component-direction, ltr); }
+```
+
+```tsx
+/* ❌ Don't use conditional logic for fallback class */
+className={classNames({
+  [styles.fallbackDirection]: !direction
+})}
+```
+
+### RTL in SCSS
+
+Use logical CSS properties — never physical `left`/`right`-only layouts. See §2.1 below.
+
+---
+
+## Patterns
+
+### Root Element Pattern
+
+Apply on main component only:
+
+```typescript
+<div
+  dir={direction}
+  className={classNames(
+    styles.root,
+    className,
+    styles.fallbackDirection,
+  )}
+>
+```
+
+```scss
+.fallbackDirection:not([dir]) {
+  direction: var(--wix-opt-in-direction);
+}
+```
+
+**Imports:**
+
+```typescript
+import type { Direction } from '@wix/editor-react-types';
+```
+
+### Child Element Direction
+
+Only when explicitly specified:
+
+```typescript
+const labelDirection = elementProps?.label?.direction;
+
+<span
+  dir={labelDirection}
+>
+```
+
+### Runtime Direction Checking
+
+**Environment Service (for site direction):**
+
+Use service when direction drives JavaScript behavior (keyboard navigation, animation logic, conditional rendering).
+
+```typescript
+import { useService } from '@wix/services-manager-react';
+import { EnvironmentDefinition } from '@wix/environment-service/definition';
+
+const environmentService = useService(EnvironmentDefinition);
+const siteDirection = environmentService.getLanguageDirection();
+const isRTL = siteDirection === 'rtl';
+```
+
+**Fallback chain (for child components):**
+
+```typescript
+const isRTL = (direction || parentDirection || siteDirection) === 'rtl';
+```
+
+**CSS Variable**
+
+Use css variable `--wix-opt-in-direction-multiplier` when direction only affects visual appearance (transforms, spacing, layout):
+
+```scss
+.scrollButton {
+  scale: var(--wix-opt-in-direction-multiplier, 1) 1;
+}
+```
+
+### RTL Support — Use Logical CSS Properties
+
+**✅ Correct:**
+
+```scss
+.element {
+  inset-inline-start: 0; // Instead of left
+  inset-inline-end: 0; // Instead of right
+  padding-inline-start: 8px; // Instead of padding-left
+  margin-inline-end: 4px; // Instead of margin-right
+}
+```
+
+**❌ Wrong:**
+
+```scss
+.element {
+  padding-left: 8px;
+  [dir='rtl'] & {
+    padding-right: 8px; // Manual RTL - avoid
+  }
+}
+```
+
+Use logical CSS properties (e.g., `margin-inline-start` not `margin-left`) for RTL support.
+
+---
+
+## Common Mistake: Manual RTL Handling
+
+**❌ Wrong:**
+
+```scss
+.element {
+  padding-left: 8px;
+  [dir='rtl'] & {
+    padding-right: 8px; // Manual overrides
+  }
+}
+```
+
+**✅ Correct:**
+
+```scss
+.element {
+  padding-inline-start: 8px; // Auto RTL/LTR
+}
+```
+
+## Container Components and RTL Inheritance
+
+Elements that render `React.ReactNode` content MUST have `dir="ltr"` to prevent RTL inheritance from the parent component:
+
+```tsx
+<Accordion.Content dir="ltr">
+  {item.content} {/* React.ReactNode */}
+</Accordion.Content>
+```

package/skills/wix-app/references/editor-react-component/EDIT-FLOW.md

@@ -0,0 +1,6 @@
+# React Site Component edition
+
+Always follow this exact workflow:
+
+1. Make changes in the component's code
+2. Run `npx wix build && npx wix generate manifest` (PascalCase)

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

@@ -0,0 +1,25 @@
+# What Qualifies as a Part
+
+A **named part** is an element that a site owner would plausibly want to control independently in the editor. Zero config scans global class names and creates an editor element for each one. Each editor element can surface:
+
+- **CSS properties** — styling controls (fill, typography, border, etc.)
+- **Data** — content bindings (text, image, link, etc.)
+
+An element deserves its own named part if a site owner would plausibly need to independently control either its styling **or** its data/content through the editor. Every named part gets exactly one global plain string class in JSX and one corresponding CSS rule. Elements that do not qualify should not get a global class.
+
+## Mandatory filter — apply to every candidate element
+
+- ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part. Implement as a BEM modifier class toggled in JSX (e.g. `image-carousel__slide--active`) and a single-class CSS rule. The modifier class is CSS-only; it is not a named part.
+- ❌ **Hidden/shown state of an existing part** — the hidden and shown states of a part are not separate parts. The element itself should be a named part (so the editor can control its visibility per breakpoint); creating an additional part to represent its hidden or shown variant is wrong.
+- ❌ **Pure grouping wrapper** — not a part. A `<div>` whose only role is to hold already-named siblings has no independent editor surface; let layout live in the parent's CSS.
+- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs.
+- ❌ **Positional duplicate** — not separate parts. Elements that are semantically identical and differ only in position (e.g. prev/next buttons) are one part; differentiate position with CSS (`:first-of-type` / `:last-of-type`, `data-` attribute, or `:nth-child`).
+- ✅ **Passes all checks** — a named part. Classify as **Semantic** (needs `elementProps`: data, behavior, direction, event handlers) or **Styling-only** (CSS class is sufficient).
+
+## Sanity check — apply after producing the parts list
+
+Before finalising, verify each proposed part against its parent:
+
+> Would the editor controls generated for this part be a strict subset of its parent's controls?
+
+If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usully better.

package/skills/wix-app/references/editor-react-component/PROPS-VS-CSS.md

@@ -0,0 +1,203 @@
+# Props vs CSS
+
+Rules and patterns for handling visual/layout properties that vary by breakpoint.
+
+---
+
+## Should This Be a React Prop or CSS?
+
+```
+Is this a content/data property?
+│
+├─ YES → Can it be derived from other props / internal state?
+│   │
+│   ├─ YES (subtotal = price × qty, fullName = first + last, etc.)
+│   │   └─ ❌ NOT a prop → compute internally
+│   │
+│   └─ NO (label, items, imageSrc, link, title, etc.)
+│       └─ ✅ React prop
+│
+└─ NO → Would a user want this to vary per breakpoint?
+    │
+    ├─ YES (showLabel, orientation, displayMode, iconPosition)
+    │   └─ ❌ NOT a prop → CSS only
+    │
+    └─ NO → Is it direction (RTL/LTR)?
+        │
+        ├─ YES
+        │   └─ ✅ React prop (internationalization)
+        │
+        └─ NO → Is it behavior (disabled, required)?
+            │
+            ├─ YES
+            │   └─ ✅ React prop
+            │
+            └─ NO
+                └─ ❌ NOT a prop → CSS only
+```
+
+---
+
+## Rules
+
+Components must distinguish between content/data and visual/layout properties:
+
+- **Content/Data** (same across all breakpoints) → React props ✅
+- **Visual/Layout** (vary by breakpoint) → CSS only, NOT props ❌
+
+### What CAN be props
+
+- Content data that stays the same: `label`, `items`, `imageSrc`, `link`, `title`
+- Behavior that's consistent: `disabled`, `required`, `searchable`, `multiple`
+
+### What CANNOT be props (must be CSS)
+
+- Visual display decisions: `showLabel`, `showIcon`, `displayMode`, `iconOnly`
+- Layout decisions: `orientation`, `alignment`, `compact`
+- Visibility toggles: `hideOnMobile`, `showOnDesktop`, `mobileView`
+
+### Critical: ALL Show/Hide Toggles Are Visual/Layout Properties
+
+Props like `showProgressBar`, `showVolumeControls`, `showTimeDisplay`, `showNavigation`, `showControls` are visual display decisions that CANNOT be props.
+
+**Why:** Show/hide decisions affect layout and users need breakpoint control:
+
+- Show progress bar on desktop, hide on mobile
+- Show cover art on desktop, hide on tablet
+- Show full controls on large screens, minimal on small screens
+
+**Pattern:** These look like "feature toggles" but they're actually "layout modes".
+
+**Exception:** `direction` (RTL/LTR) is a mandatory prop for internationalization, not a breakpoint-responsive property.
+
+**Critical Rule:** If a property should be customizable per breakpoint, it CANNOT be a React prop.
+
+### How to Implement
+
+Visibility/display properties can be overridden per breakpoint by the user via the editor — but, just like background colors, the component still authors the resting defaults in CSS:
+
+1. **Always render all elements** — No conditional rendering with props
+2. **Do NOT hardcode visibility-toggling display in CSS** (e.g. `display: none` to hide an element by default) — visibility is user-controlled per breakpoint. Layout `display` (`flex`, `grid`, etc.) on layout containers is fine and expected. Resting visual properties (background, color, border-radius, padding, font) DO belong in CSS — see `CSS-GUIDELINES.md`.
+3. **Visibility is user-controlled** — Users control what shows/hides per breakpoint via the editor
+
+```tsx
+// ✅ CORRECT: Always render
+<div className={styles.progressBar}>...</div>
+<div className={styles.volumeControls}>...</div>
+<div className={styles.trackInfo}>...</div>
+
+// SCSS: no `display: none` default — visibility is user-controlled per breakpoint
+.progressBar {
+  position: relative;
+}
+```
+
+### How to Identify
+
+Ask these questions in order:
+
+1. **"Would a user want this to vary per breakpoint?"** (mobile vs desktop vs tablet)
+   - If YES → CSS only, NOT a prop
+
+2. **"Does this control WHAT is displayed vs WHICH content to display?"**
+   - `showProgressBar` → Controls WHAT (layout decision) → CSS only
+   - `audioUrl` → Specifies WHICH audio file (content) → Prop is OK
+
+3. **"Does it change the visual appearance or layout?"**
+   - `showControls`, `orientation`, `alignment` → Visual/layout → CSS only
+   - `disabled`, `required`, `autoPlay` → Behavior (not visual) → Props are OK
+
+**Rule of thumb:** If the prop name starts with `show*`, `hide*`, `display*` → It's CSS-only.
+
+**Examples:**
+
+- ✅ **Visual properties:** Show/hide elements, display modes → CSS only
+- ✅ **Layout properties:** Orientation, alignment, spacing variations, flex/grid directions → CSS only
+- ❌ **Content properties:** Text, media URLs, links, data → Props are OK
+- ❌ **Internationalization:** RTL/LTR (`direction` prop) → Props are OK (not breakpoint-responsive)
+
+---
+
+## Patterns
+
+### Correct: Only Data as Props
+
+**❌ Wrong — visual properties as props:**
+
+```typescript
+interface ButtonProps {
+  showLabel?: boolean; // ❌ Breakpoint-customizable
+  showIcon?: boolean; // ❌ Breakpoint-customizable
+  displayMode?: 'icon-only' | 'label-only' | 'both'; // ❌
+  iconPosition?: 'left' | 'right'; // ❌ Layout
+  orientation?: 'horizontal' | 'vertical'; // ❌ Layout
+}
+```
+
+**✅ Correct — only data as props:**
+
+```typescript
+interface ButtonProps {
+  label: string; // ✅ Content data
+  icon: VectorArt; // ✅ Content data
+}
+```
+
+### Correct: Always Render, Users Control Visibility
+
+**❌ Wrong — show/hide as props:**
+
+```typescript
+interface AudioPlayerProps {
+  showProgressBar?: boolean;      // ❌ Layout decision
+  showVolumeControls?: boolean;   // ❌ Layout decision
+  showTimeDisplay?: boolean;      // ❌ Layout decision
+  showTrackInfo?: boolean;        // ❌ Layout decision
+}
+
+// Conditional rendering
+{showProgressBar && <div className={styles.progressBar}>...</div>}
+```
+
+**✅ Correct — always render, users control visibility:**
+
+```typescript
+interface AudioPlayerProps {
+  audioUrl: string;     // ✅ Content data only
+  title?: string;       // ✅ Content data
+  artist?: string;      // ✅ Content data
+}
+
+// Always render all elements
+<div className={styles.progressBar}>...</div>
+<div className={styles.volumeControls}>...</div>
+<div className={styles.trackInfo}>...</div>
+
+// SCSS: no `display: none` default — visibility is user-controlled per breakpoint
+.progressBar {
+  position: relative;
+}
+```
+
+---
+
+## Common Mistake: Adding Visual Toggle Props
+
+**❌ Wrong:**
+
+```typescript
+export interface ButtonProps {
+  showIcon?: boolean; // ❌ Breakpoint-customizable
+  iconPosition?: 'left' | 'right'; // ❌ Layout
+}
+```
+
+**✅ Correct:**
+
+```typescript
+export interface ButtonProps {
+  label: string;
+  icon: VectorArt;
+  // Visual variations via CSS
+}
+```

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

@@ -0,0 +1,167 @@
+# React Component Implementation Guide
+
+This guide defines rules and guidance on **how to implement** production-quality Editor React components for Wix CLI applications. Editor React components are React components that integrate with the Wix Editor, allowing site owners to customize content, styling, and behavior through a visual interface.
+
+**Topic reference files:**
+- [`PARTS.md`](PARTS.md) — What qualifies as a named part (mandatory filter)
+- [`ACCESSIBILITY.md`](ACCESSIBILITY.md) — ARIA/a11y rules and patterns
+- [`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
+- [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
+
+## React 18 features are not supported
+
+The Wix runtime does not currently support React 18 features. Stick
+to React 17-compatible APIs and avoid libraries that depend on
+React 18 features.
+
+# Part 0: Component Behavior Guide
+
+Understand the component and infer its behavior. Extract what is provided; use reasonable defaults for anything not specified.
+
+1. **Identity** — Component name.
+2. **Structure** — Identify named parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
+3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally.
+
+**Understanding → implementation (checklist):** For every part, decide `elementProps` vs CSS-only; build the props interface (data + behavior); wire interaction in React (`useState`, `useEffect`, refs, native event handlers); generate TS + CSS. Infer reasonable defaults where anything is unspecified.
+
+# Part 1: Standards & Conventions
+
+These are the mandatory patterns and conventions for all components.
+
+## 1.1 Mandatory Features
+
+Every component MUST include:
+
+### Direction Support (RTL/LTR)
+
+Direction support is mandatory — see [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
+
+### Accessibility ARIA Support
+
+See [`ACCESSIBILITY.md`](ACCESSIBILITY.md) for full rules and patterns.
+
+### TypeScript
+
+- All components must be fully typed
+- NO `any` types
+- Export all prop interfaces
+- Use proper React types (`React.FC`, `React.ReactNode`, etc.)
+- **Array type syntax:** Use `Array<T>` instead of `T[]` (e.g., `Array<Item>` not `Item[]`)
+- **Array element types:** `T` must be an object with named keys — `Array<{ key: ValueType, ... }>` or a named interface that is itself a keyed object. Never `Array<string>`, `Array<number>`, `Array<boolean>`, or `Array<DataType>` (`Image`, `Link`, `Video`, `Audio`, `VectorArt`, `RichText`, etc.). See [`COMPONENT-API.md`](COMPONENT-API.md) for full rules.
+- **Component function pattern:**
+  - Use inline arrow functions with `export const`
+  - Accept `props` as the argument (do NOT destructure in function signature)
+  - Destructure props inside the component body
+
+## 1.2 Implementation Standards
+
+### When to Use elementProps
+
+See [`COMPONENT-API.md`](COMPONENT-API.md) for full elementProps rules and the decision tree.
+
+### React & Runtime Standards
+
+All components MUST follow these patterns:
+
+**1. SSR-Safe Implementation**
+
+- NO browser APIs at module scope (window, document, navigator, etc.)
+- Guard browser APIs with typeof checks or useEffect
+- All browser-dependent logic must run client-side only
+
+See [`REACT-PATTERNS.md`](REACT-PATTERNS.md) §1.1 for code examples.
+
+**2. Clean Code**
+
+- NO TypeScript errors
+- NO unused variables or imports
+- NO comments in React component files — code should be self-documenting through clear naming
+- NO TODO comments in generated code
+- **Remove ALL comments from the final component** — including any comments from templates/examples
+
+**3. Data-Driven Components (NO children in exported props)**
+
+See [`COMPONENT-API.md`](COMPONENT-API.md) for full rules and patterns.
+
+**4. Breakpoint-Responsive Properties (NO props for visual variations)**
+
+See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) for full rules and patterns.
+
+**5. Reactive to Prop Changes**
+
+- Components MUST react to prop changes
+- If state is derived from props, use `useEffect` with prop dependencies
+- State initialized from props should update when props change
+
+**6. Event Handler Scope (Internal by Default)**
+
+Unless explicitly specified as a component capability/API in the specification, all event handlers are **internal** and NOT exposed as props.
+
+**Internal handlers (default):**
+
+- Used for component behavior (autoplay, animations, state management)
+- NOT exposed in the component's props interface
+
+**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
+
+**Child component handlers:**
+
+- Internal sub-components receive handlers from parent via props
+- These are still internal to the main component
+
+## 1.3 Implementation Workflow
+
+### Step 1: Analyze Component Parts
+
+For each part of the component, decide:
+
+**CSS class only if**:
+
+- ✅ Purely visual/decorative
+- ✅ No data or configuration needed
+- ✅ No direction override needed
+- ✅ No custom behavior needed
+
+**Use elementProps if**:
+
+- ✅ Needs data/content
+- ✅ Needs direction override
+- ✅ Has state or behavior
+- ✅ Needs event handlers
+
+See [`COMPONENT-API.md`](COMPONENT-API.md) and [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) for the decision trees.
+
+### Step 2: Build Props Interface
+
+Combine:
+
+1. Data/content props (from specification)
+2. Behavior props (from specification)
+3. Mandatory React props (direction, a11y, className, id)
+4. elementProps (only for parts that need it)
+
+### Step 3: Implement
+
+Follow Part 2 templates with mandatory patterns applied.
+
+# Part 2: CSS Rules
+
+All CSS authoring rules — root layout, naming, RTL, state styles,
+transitions, etc. — live in [`CSS-GUIDELINES.md`](CSS-GUIDELINES.md).
+
+See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.md) for the prop vs CSS vs `elementProps` decision trees.
+
+# Part 3: Examples & Reference
+
+## 3.1 Implementation Checklist
+
+**Phase 1: Analysis** — Parse information, map component structure (see Part 0)
+
+**Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards
+
+**Phase 3: Styles** — Apply Part 2 SCSS rules