@wix/agent-skills 1.16.2 → 1.17.0

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

@@ -0,0 +1,27 @@
+# Manifest Build Errors
+
+Use this reference only when `npx wix build` or `npx wix generate manifest`
+exits with an error. Read the error name from the first token before the colon
+(`IoError:`, `ParseError:`, or `NotFoundError:`), then apply the matching fix.
+
+| Error | Fix |
+| --- | --- |
+| `IoError: Failed to load compiled bundle` | Re-run `npx wix build`; fix any TypeScript/build errors it reports first |
+| `IoError: Failed to access component "X" from compiled bundle` | Corrupted artifact — delete `dist/`, re-run `npx wix build` from scratch |
+| `IoError: CSS selector matching failed for "X"` | Fix invalid selector syntax in `<componentName>.module.css` |
+| `IoError: Component "X" render produced no root element` | Component returns null or bare text — ensure it always renders a root JSX element |
+| `IoError` (render phase, no other pattern) | SSR crash — remove browser-only APIs (`window`, `document`, `localStorage`) used at render time; ensure props have defaults |
+| `NotFoundError: File not found` | Restore the missing source file or fix its registered/imported path; do not re-scaffold an existing component |
+| `NotFoundError: Component "X" was not found as a named export` | Confirm `component.tsx` has a default export and re-run `npx wix build` |
+| `ParseError: Failed to parse TypeScript config` | Fix `tsconfig.json`; run `npx tsc --noEmit` to surface the error |
+| `ParseError: Failed to extract component types from "X"` | TypeScript error in the component — run `npx tsc --noEmit` and fix |
+| `ParseError: Failed to compile "<file.scss>"` | SCSS syntax error — line/column is in the error message |
+| `ParseError: Failed to parse CSS file for component "X"` | CSS syntax error in `.module.css` — line/column is in the error message |
+
+After each fix, re-run `npx wix build && npx wix generate manifest` to confirm.
+
+## Checklist
+
+- [ ] The fix matches the reported error name and message.
+- [ ] Build errors are resolved before manifest generation is retried.
+- [ ] Both build and manifest generation pass after the fix.

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

@@ -1,39 +1,60 @@
-# What Qualifies as a Part
+# Named Parts and Root Election
 
-## Step 0 — Elect the root element
+Use this reference to choose the component root and decide which inner elements
+receive independent editor controls.
 
-The root always becomes the component's editor element: it carries the `'<component-name>'` global class and gets a name and design capabilities either way. So elect a root that deserves them, before enumerating inner parts.
+## Elect the Root First
 
-- ✅ **The component reduces to one meaningful element** (a single control, link, media surface, or list) — that element **is** the root. It takes `id`, `dir`, the `fallbackDirection` class, the merged `className`, the `a11y` spread, `'<component-name>'`, and the root CSS rule. All of these are attributes and classes, so they sit on a `<button>` or `<a>` exactly as on a `<div>` — needing them is never a reason to add a wrapper.
-- ✅ **The elected root is the root, not an inner part** — it carries the **unprefixed** `'<component-name>'` class and gets no `elementProps` entry. A single-control component therefore has exactly one named part: its root.
-- ❌ **Wrapper `<div>` holding only root plumbing** — the editor element is then a transparent box and the real element is demoted to a nested part. A root wrapper is justified only when it lays out two or more sibling parts, is the sizing/scroll/clipping container, or hosts a root-level prop-triggered state ([`DESIGN-STATES.md`](DESIGN-STATES.md) §5). Anchoring absolutely positioned decoration is not a justification — `position: relative` works on any element.
-- **Stutter test** — a part class repeating the component's own noun (`confetti-button-button`) means the wrapper took the root's name. Collapse it and promote the real element.
+The root is always the component's editor element. It carries the unprefixed
+`'<component-name>'` global class and receives top-level `id`, `className`,
+`direction`, and `a11y`. It never has an `elementProps` entry.
 
-## Inner parts
+- If the component reduces to one meaningful control, link, media surface, or
+  list, make that semantic element the root.
+- Add a wrapper root only when it lays out multiple sibling parts, owns
+  sizing/scrolling/clipping, or hosts a root-level prop-triggered state.
+- Do not add a wrapper solely to hold root props or position decoration.
+- If an inner part name stutters (`confetti-button-button`), the real semantic
+  element probably should have been the root.
 
-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:
+## Identify Named Inner Parts
 
-- **CSS properties** — styling controls (fill, typography, border, etc.)
-- **Data** — content bindings (text, image, link, etc.)
+A named inner part is an element whose styling or data/content a site owner
+would plausibly control independently in the editor. It receives:
 
-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.
+- one prefixed global class: `'<component-name>-<part-name>'`
+- one CSS Module class
+- one matching `elementProps` entry, spread onto the element
 
-## Mandatory filter — apply to every candidate element
+Apply this filter to every candidate:
 
-- ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part, it's a **design state** of a part. Implement it per [`DESIGN-STATES.md`](DESIGN-STATES.md): native states from interactive markup; custom states as a flat global modifier on the element's own (component-name-prefixed) class (e.g. `carousel-slide--active`, toggled in JSX) plus a `:global(.carousel-slide--active)` CSS rule. The modifier is a state, 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. **Exception — interactive HTML elements (`<button>`, `<a>`, `<input>`) are never excluded by this criterion.** They always carry an independent styling surface: background, border, border-radius, hover/focus states, color, and typography are all meaningfully tunable per element in the editor. Apply this exclusion only to purely static structural elements (layout wrappers, grouping containers, decorative dividers). This makes an interactive element a named part **when it is an inner element** — if it is the elected root (Step 0), it is already named by `'<component-name>'` and must not be given a prefixed inner-part class as well.
-- ❌ **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).
+- A state or variant (`selected`, `active`, `open`, `disabled`) is not a part.
+  Implement it as a prefixed design-state modifier on the affected part.
+- A hidden and shown version of the same element is one part, not two.
+- A grouping or layout-only wrapper is not a part.
+- A static child whose styling and data are fully owned by its parent is not a
+  part. For example, an image whose source and appearance both belong to its
+  carousel slide can remain module-class-only.
+- An inner interactive element (`button`, `a`, `input`, and equivalent semantic
+  controls) is a named part because it has an independent interaction and
+  styling surface.
+- Positional duplicates such as previous/next buttons are one part when they
+  share the same semantic editor surface. Distinguish position with data or a
+  module-only helper class, not separate part names.
 
-## Sanity check — apply after producing the parts list
+## Sanity Check
 
-Before finalising, verify each proposed part against its parent:
+For each candidate, ask:
 
-> Would the editor controls generated for this part be a strict subset of its parent's controls?
+> Would the controls for this element 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 usually better.
+If yes, remove the part. Then check the root in reverse: if it has one child part
+and no independent surface, remove the wrapper and promote the child.
 
-Then run the same question in reverse, on the root: if the root has exactly one child part and no editor surface of its own, it is a plumbing wrapper — delete it and promote the child per Step 0.
+## Checklist
 
+- [ ] The root is the component's best semantic element.
+- [ ] The root has no `elementProps` entry or duplicate prefixed part class.
+- [ ] Each inner part offers independent data or styling control.
+- [ ] Every named inner part has global/module classes and `elementProps` wiring.
+- [ ] States, wrappers, decorations, and positional variants are not extra parts.

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

@@ -1,203 +1,87 @@
 # Props vs CSS
 
-Rules and patterns for handling visual/layout properties that vary by breakpoint.
+Use this reference to decide whether a value belongs in the public React
+contract, component logic, or editable CSS.
 
----
+## Decision Table
 
-## Should This Be a React Prop or CSS?
+| Value controls | Put it in | Examples |
+| --- | --- | --- |
+| User-authored content or data | React prop | `label`, `items`, `image`, `link` |
+| Stable runtime behavior | React prop | `disabled`, `required`, `autoPlay`, `loop` |
+| Value derived from props or state | Component logic | subtotal, active count, formatted label |
+| Appearance or layout | CSS | spacing, alignment, orientation, icon position |
+| Breakpoint-specific visibility | CSS/editor controls | show label, compact layout, mobile visibility |
+| Direction | React prop plus logical CSS | `direction?: Direction` |
 
-```
-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`
+Ask in this order:
 
-### Critical: ALL Show/Hide Toggles Are Visual/Layout Properties
+1. Can the value be derived? Compute it internally.
+2. Does it select content or stable behavior? Use a prop.
+3. Could a site owner reasonably vary it by breakpoint? Use CSS/editor controls.
+4. Otherwise, keep visual and layout choices in CSS.
 
-Props like `showProgressBar`, `showVolumeControls`, `showTimeDisplay`, `showNavigation`, `showControls` are visual display decisions that CANNOT be props.
+## Visibility Rules
 
-**Why:** Show/hide decisions affect layout and users need breakpoint control:
+Do not add `showLabel`, `showIcon`, `hideOnMobile`, `displayMode`, or similar
+props for purely presentational visibility. Render the named part and let the
+editor control that part per breakpoint.
 
-- 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
+Use this pattern:
 
 ```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;
-}
+<div
+  {...elementProps?.progressBar}
+  className={classNames(
+    'audio-player-progress-bar',
+    styles.progressBar,
+    elementProps?.progressBar?.className,
+  )}
+>
+  {/* progress UI */}
+</div>
 ```
 
-### 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
+Do not interpret this rule as "never conditionally render." Conditional output
+is valid when data, semantics, or runtime behavior requires it—for example an
+empty-state message, a loading branch, or content that does not exist.
 
-**Rule of thumb:** If the prop name starts with `show*`, `hide*`, `display*` → It's CSS-only.
+Behavior-critical visibility may also be a prop when visibility itself changes
+the interaction contract. `pauseButtonVisibility` in an autoplaying component
+is the canonical exception: the editor preview must be able to force the
+play/pause control visible.
 
-**Examples:**
+## 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)
+### Content and Behavior Props
 
----
-
-## 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
-}
+```ts
+export type AudioPlayerProps = {
+  title?: string;
+  audioUrl?: string;
+  disabled?: boolean;
+  autoPlay?: boolean;
+};
 ```
 
-### Correct: Always Render, Users Control Visibility
-
-**❌ Wrong — show/hide as props:**
+### Visual Decisions Kept Out of 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>}
+```ts
+// Do not add these to the public contract:
+// showIcon?: boolean
+// orientation?: 'horizontal' | 'vertical'
+// compact?: boolean
+// hideOnMobile?: boolean
 ```
 
-**✅ Correct — always render, users control visibility:**
-
-```typescript
-interface AudioPlayerProps {
-  audioUrl: string;     // ✅ Content data only
-  title?: string;       // ✅ Content data
-  artist?: string;      // ✅ Content data
-}
+Define their resting appearance in the CSS Module and expose independently
+editable elements as named parts with global/module classes and `elementProps`
+wiring.
 
-// Always render all elements
-<div className={styles.progressBar}>...</div>
-<div className={styles.volumeControls}>...</div>
-<div className={styles.trackInfo}>...</div>
+## Checklist
 
-// 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
-}
-```
+- [ ] Props represent authored data or stable behavior.
+- [ ] Derived values are computed internally.
+- [ ] Visual and layout choices live in CSS.
+- [ ] Breakpoint visibility uses a named part, not a show/hide prop.
+- [ ] Conditional rendering is used only for real data, semantic, or behavioral branches.