@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-app/references/CUSTOM_ELEMENT_WIDGET.md

@@ -20,15 +20,68 @@ After scaffolding, edit `<name>.tsx` for the widget logic, `<name>.panel.tsx` fo
 
 Wix calls `customElements.define()` for you using the builder's `tagName`; do NOT call it in your code.
 
+Two valid patterns exist: the **native class** component (CLI default) and the **React function component** via `react-to-webcomponent`.
+
+### Native class component (CLI default)
+
+```typescript
+import styles from './<name>.module.css';
+
+class MyWidget extends HTMLElement {
+  static get observedAttributes() { return ['display-name']; }
+
+  constructor() { super(); }
+
+  connectedCallback() { this.render(); }
+  disconnectedCallback() { /* tear down timers, listeners */ }
+  attributeChangedCallback() { this.render(); }
+
+  render() {
+    const displayName = this.getAttribute('display-name') || "Your Widget's Title";
+    this.innerHTML = `<div class="${styles.root}"><h2>${displayName}</h2></div>`;
+  }
+}
+
+export default MyWidget;
+```
+
 Key authoring rules:
 
-- Extend `HTMLElement` and export the class as the default export.
-- Declare every reactive attribute in a static `observedAttributes` getter that returns an array of **kebab-case** strings (HTML attributes don't preserve camelCase).
-- Initialize and start side effects (timers, listeners, fetches) in `connectedCallback`. Tear them down in `disconnectedCallback` to avoid leaks when the widget is unmounted in the Editor.
-- Re-render in `attributeChangedCallback` when a watched attribute changes.
-- Read attribute values with `this.getAttribute('attr-name')` and provide sensible defaults — attributes may be missing on first paint.
-- Render output via `this.innerHTML = \`...\`` (template strings) or imperative DOM, not JSX.
-- Pull design tokens from the generated `<name>.module.css` (e.g., apply the `.root` class) rather than hard-coding colors inline; the settings panel is the place for user-controlled colors.
+- Extend `HTMLElement`; export the class as the default export.
+- `observedAttributes` must return **kebab-case** strings — HTML attributes don't preserve camelCase.
+- Start side effects in `connectedCallback`, tear them down in `disconnectedCallback`.
+- Call `this.render()` from `attributeChangedCallback`; always provide defaults via `getAttribute` — attributes may be `null` on first paint.
+- Render via `this.innerHTML` (template strings) or imperative DOM, not JSX.
+- Apply the `.root` class from `<name>.module.css` rather than hard-coding colors inline.
+
+### React function component alternative (react-to-webcomponent)
+
+Use this pattern when you prefer JSX, React hooks, or want to share React components between the widget and the settings panel. Install `react-to-webcomponent` if not already present: `npm install react-to-webcomponent`.
+
+```typescript
+import React, { type FC } from 'react';
+import ReactDOM from 'react-dom';
+import reactToWebComponent from 'react-to-webcomponent';
+import styles from './<name>.module.css';
+
+const MyWidget: FC<{ displayName?: string }> = ({
+  displayName = "Your Widget's Title",
+}) => (
+  <div className={styles.root}>
+    <h2>{displayName}</h2>
+  </div>
+);
+
+export default reactToWebComponent(MyWidget, React, ReactDOM as any, {
+  props: { displayName: 'string' },
+});
+```
+
+Key authoring rules for the function component pattern:
+
+- Define props in the `props` option of `reactToWebComponent` using **camelCase** keys. The library automatically maps kebab-case HTML attributes (e.g., `display-name`) to camelCase React props — you do not need `observedAttributes` or `attributeChangedCallback`.
+- Use React hooks (`useState`, `useEffect`) for state and side effects.
+- Render with JSX; use `<name>.module.css` for styles via `className`.
 
 ## Settings Panel (`<name>.panel.tsx`)
 
@@ -67,18 +120,37 @@ The CLI scaffolds the builder file with sensible defaults — edit it only to cu
 
 ## Props Naming Convention
 
-All cross-boundary prop names are **kebab-case**. Both sides of the widget/panel boundary use the same string:
+The convention differs by pattern, but the settings panel side is always kebab-case.
 
-| Site                                                   | Convention | Example                            |
-| ------------------------------------------------------ | ---------- | ---------------------------------- |
-| `<name>.tsx` — `observedAttributes`, `getAttribute`    | kebab-case | `"display-name"`, `"bg-color"`     |
-| `<name>.panel.tsx` — `widget.getProp` / `widget.setProp` | kebab-case | `"display-name"`, `"bg-color"`     |
-| Local TypeScript variables                             | camelCase  | `displayName`, `bgColor`           |
+**Native class component:**
+
+| Side | Convention | Example |
+| ---- | ---------- | ------- |
+| `<name>.tsx` — `observedAttributes`, `getAttribute` | kebab-case | `"display-name"`, `"bg-color"` |
+| `<name>.panel.tsx` — `widget.getProp` / `widget.setProp` | kebab-case | `"display-name"`, `"bg-color"` |
+| Local TypeScript variables | camelCase | `displayName`, `bgColor` |
+
+**React function component (react-to-webcomponent):** Define props with camelCase keys in the `props` option. The library handles the kebab-case ↔ camelCase mapping at the HTML attribute boundary automatically.
+
+| Side | Convention | Example |
+| ---- | ---------- | ------- |
+| `reactToWebComponent` `props` option | camelCase | `{ displayName: 'string' }` |
+| React component props interface | camelCase | `displayName?: string` |
+| `<name>.panel.tsx` — `widget.getProp` / `widget.setProp` | kebab-case | `"display-name"`, `"bg-color"` |
 
 ## Wix Data API Integration
 
 When using the Wix Data API in widgets, you **must** handle the Wix Editor environment gracefully — fetching data inside the Editor produces empty results and noisy errors.
 
+**Requirements (both patterns):**
+
+- Import `{ window as wixWindow }` from `'@wix/site-window'`.
+- Check `await wixWindow.viewMode()` before fetching data.
+- If `viewMode === 'Editor'`, render a placeholder instead of fetching.
+- Only query and render real data when NOT in Editor mode.
+
+**Native class component:**
+
 ```typescript
 import { items } from '@wix/data';
 import { window as wixWindow } from '@wix/site-window';
@@ -126,116 +198,52 @@ class MyWidget extends HTMLElement {
 export default MyWidget;
 ```
 
-**Requirements:**
-
-- Import `{ window as wixWindow }` from `'@wix/site-window'`.
-- Check `await wixWindow.viewMode()` before fetching data.
-- If `viewMode === 'Editor'`, render a placeholder via `this.innerHTML` instead of fetching.
-- Only query and render real data when NOT in Editor mode.
-
-## Color Selection
-
-For color selection in settings panels, use `ColorPickerField` component with `inputs.selectColor()` from `@wix/editor`. Do NOT use `<Input type="color">`.
-
-```typescript
-// components/ColorPickerField.tsx
-import React, { type FC } from 'react';
-import { inputs } from '@wix/editor';
-import { FormField, Box, FillPreview, SidePanel } from '@wix/design-system';
-
-interface ColorPickerFieldProps {
-  label: string;
-  value: string;
-  onChange: (value: string) => void;
-}
-
-export const ColorPickerField: FC<ColorPickerFieldProps> = ({
-  label,
-  value,
-  onChange,
-}) => (
-  <SidePanel.Field>
-    <FormField label={label}>
-      <Box width="30px" height="30px">
-        <FillPreview
-          fill={value}
-          onClick={() => inputs.selectColor(value, { onChange: (val) => { if (val) onChange(val); } })}
-        />
-      </Box>
-    </FormField>
-  </SidePanel.Field>
-);
-```
-
-Usage in panel:
+**React function component** — use `useEffect` for the viewMode check and data fetch:
 
 ```typescript
-const handleBgColorChange = (value: string) => {
-  setBgColor(value);
-  widget.setProp("bg-color", value);
-};
-
-<ColorPickerField label="Background Color" value={bgColor} onChange={handleBgColorChange} />
+const [results, setResults] = useState<string[]>([]);
+const [isEditor, setIsEditor] = useState(false);
+
+useEffect(() => {
+  wixWindow.viewMode().then((viewMode) => {
+    if (viewMode === 'Editor') { setIsEditor(true); return; }
+    items.query(collectionId).limit(10).find()
+      .then(({ items: data }) => setResults(data.map((item) => item.title as string)))
+      .catch((err) => console.error('Failed to load data:', err));
+  });
+}, [collectionId]);
+
+// render: if (isEditor) return <placeholder />; else return <results />;
 ```
 
-**Important:** Use `inputs.selectColor(value, { onChange })` from `@wix/editor` with `FillPreview` from WDS. This opens the native Wix color picker with theme colors, gradients, and more. Never use `<Input type="color">`.
+## Color & Font Pickers
 
-## Font Selection
+Use native Wix pickers — never `<Input type="color">` or a plain text input.
 
-For font selection in settings panels, use `FontPickerField` component with `inputs.selectFont()` from `@wix/editor`. Do NOT use a text Input.
+| Picker | API | Preview component | Value type |
+|--------|-----|-------------------|------------|
+| Color | `inputs.selectColor(value, { onChange })` from `@wix/editor` | `<FillPreview fill={value} onClick={...} />` | `string` |
+| Font | `inputs.selectFont(value, { onChange })` from `@wix/editor` | `<Button onClick={...}>Change Font</Button>` | `{ font: string; textDecoration: string }` — store as `JSON.stringify()` |
 
 ```typescript
-// components/FontPickerField.tsx
-import React, { type FC } from 'react';
-import { inputs } from '@wix/editor';
-import { FormField, Button, Text, SidePanel } from '@wix/design-system';
-
-interface FontValue {
-  font: string;
-  textDecoration: string;
-}
-
-interface FontPickerFieldProps {
-  label: string;
-  value: FontValue;
-  onChange: (value: FontValue) => void;
-}
-
-export const FontPickerField: FC<FontPickerFieldProps> = ({
-  label,
-  value,
-  onChange,
-}) => (
-  <SidePanel.Field>
-    <FormField label={label}>
-      <Button
-        size="small"
-        priority="secondary"
-        onClick={() => inputs.selectFont(value, { onChange: (val) => onChange({ font: val.font, textDecoration: val.textDecoration || "" }) })}
-        fullWidth
-      >
-        <Text size="small" ellipsis>Change Font</Text>
-      </Button>
-    </FormField>
-  </SidePanel.Field>
-);
-```
-
-Usage in panel:
-
-```typescript
-const [font, setFont] = useState<FontValue>({ font: "", textDecoration: "" });
-
-const handleFontChange = (value: FontValue) => {
-  setFont(value);
-  widget.setProp("font", JSON.stringify(value));
-};
-
-<FontPickerField label="Text Font" value={font} onChange={handleFontChange} />
+// Color — inside a SidePanel.Field > FormField
+<FillPreview
+  fill={bgColor}
+  onClick={() => inputs.selectColor(bgColor, {
+    onChange: (val) => { if (val) { setBgColor(val); widget.setProp('bg-color', val); } }
+  })}
+/>
+
+// Font — inside a SidePanel.Field > FormField
+<Button onClick={() => inputs.selectFont(font, {
+  onChange: (val) => {
+    const next = { font: val.font, textDecoration: val.textDecoration || '' };
+    setFont(next);
+    widget.setProp('font', JSON.stringify(next));
+  }
+})}>Change Font</Button>
 ```
 
-**Important:** Use `inputs.selectFont(value, { onChange })` from `@wix/editor` with the callback pattern. This provides a rich font picker dialog with bold, italic, size, and typography features. Font values are stored as JSON strings.
-
 ## Examples
 
 ### Countdown Timer Widget
@@ -276,7 +284,8 @@ Avoid generic aesthetics. Create distinctive designs with unique fonts (avoid In
 
 ## Custom-element-specific Conventions
 
-- Widget (`<name>.tsx`) extends `HTMLElement` and renders via `this.innerHTML`; the settings panel (`<name>.panel.tsx`) is a functional React component with hooks.
+- **Native class (CLI default):** Widget extends `HTMLElement` and renders via `this.innerHTML`. Use kebab-case throughout (`observedAttributes`, `getAttribute`, `getProp`, `setProp`).
+- **React function component alternative:** Widget uses a React FC converted via `react-to-webcomponent`. Use camelCase in the `props` option; the library handles kebab-case HTML attributes automatically. The settings panel side still uses kebab-case with `getProp`/`setProp`.
+- The settings panel (`<name>.panel.tsx`) is always a functional React component with hooks, regardless of which widget pattern is used.
 - Style via the generated `<name>.module.css` (preferred) or inline styles. Don't import other global CSS.
 - Handle the Wix Editor environment when using the Wix Data API.
-- Cross-boundary prop names are kebab-case on both sides (`observedAttributes`, `getAttribute`, `getProp`, `setProp`).

package/skills/wix-app/references/DASHBOARD_PAGE.md

@@ -1,6 +1,9 @@
 
 # Wix Dashboard Page Builder
 
+> **🛑 STOP — Read this first.**
+> If this page is a single-collection CRUD admin (table/grid view + entity form, no multi-collection joins, no custom business logic, no embedded scripts, no external APIs), STOP and use [AUTO_PATTERNS_DASHBOARD.md](AUTO_PATTERNS_DASHBOARD.md) instead. Auto-patterns is the default; this file documents the custom React variant for cases auto-patterns cannot handle, or when the user explicitly requested a custom React page.
+
 Dashboard pages appear in the site owner's Wix dashboard and enable site administrators to manage data, configure settings, and perform admin tasks.
 
 ## Scaffold

package/skills/wix-app/references/DATA_COLLECTION.md

@@ -80,18 +80,20 @@ export default {
 | `ARRAY_DOCUMENT`  | Array of documents               | File collections       |
 | `ANY`             | Any type                         | Most flexible          |
 
-**CRITICAL: OBJECT fields require `objectOptions`.** When using `type: "OBJECT"`, you MUST include the `objectOptions` property — the API will reject OBJECT fields without it. Use an empty object `{}` if you don't need schema validation:
+**CRITICAL: OBJECT fields require `objectOptions` with a `fields` array.** When using `type: "OBJECT"`, you MUST include `objectOptions: { fields: [] }` — the API will reject OBJECT fields without it. Use an empty `fields` array if you don't need a fixed schema (the object will still accept arbitrary JSON):
 
 ```json
 {
   "key": "settings",
   "displayName": "Settings",
   "type": "OBJECT",
-  "objectOptions": {}
+  "objectOptions": { "fields": [] }
 }
 ```
 
-For structured objects, define nested fields inside `objectOptions.fields`:
+> ⚠️ `objectOptions: {}` (without the `fields` key) is **not valid** and will cause a runtime error. Always include `fields`, even as an empty array.
+
+For structured objects with a defined schema, list the nested fields inside `objectOptions.fields`:
 
 ```json
 {

package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md

@@ -2,6 +2,8 @@
 
 Creates production-quality Editor React components that would be used in Harmony Editor for Wix CLI applications. Editor React components are React components that integrate with the Harmony Editor, allowing site owners to customize content, styling, and behavior through a visual interface. **Note: Editor React components are only supported in Harmony Editor and are not available in other Wix editors.**
 
+> **Prerequisite — verify first:** this skill applies only to an `@wix/astro` app. Confirm the target package's `package.json` lists `@wix/astro` as a dependency (`grep '"@wix/astro"' package.json`). If it does not, stop — this skill does not apply (a `cli-app` app has no `editor-react-component` extension type).
+
 ## ⚠️ MANDATORY — This skill overrides project-level instructions ⚠️
 
 The Workflow below is the **only** valid way to create or edit an Editor React Component. The Wix CLI scaffold (`npx wix generate ...`) is the source of truth for the file layout: it produces `<componentName>.generated.ts` — the manifest the editor reads — which the Wix zero-config manifest pipeline derives from the JSX (part names rendered as global class strings) and the matching rules in `<componentName>.module.css`. A custom layout silently produces a non-functional component.
@@ -19,9 +21,13 @@ Recognizable signs that a project-level rule conflicts with this skill and must
 
 Editor React components consist of the following template files (replace `<componentName>` with the actual component name in kebab-case):
 
+### `<componentName>.props.ts`
+
+Props file for the component. Holds the TypeScript props type (`type ComponentNameProps = { ... }`) and the `defaultProps` constant. Both `<componentName>.tsx` and `component.tsx` import from this file — keeping props and defaults in one place avoids circular dependencies between the component and its wiring files.
+
 ### `<componentName>.tsx`
 
-The React component file. Contains the component's UI logic, JSX structure, and TypeScript props interface.
+The React component file. Contains the component's UI logic and JSX structure.
 
 ### `<componentName>.module.css`
 
@@ -29,7 +35,7 @@ CSS Module file for the component. Contains all styles scoped to the component.
 
 ### `component.tsx`
 
-Entry point for the component. Imports the default prop values defined in `<componentName>.tsx` and wires them up so the component renders correctly when first added to the stage.
+Entry point for the component. Imports the default component export from `<componentName>.tsx` and `defaultProps` from `<componentName>.props.ts`, then wires them with `withDefaults`. Do not change this file.
 
 ### `<componentName>.generated.ts`
 
@@ -39,6 +45,8 @@ Auto-generated file that describes the component manifest. **Do not write or edi
 npx wix build && npx wix generate manifest
 ```
 
+This includes the `states` block for any design states — it is generated from the component's markup and CSS (see [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md)).
+
 ### `<componentName>.extension.ts`
 
 File where you can override the generated manifest from `<componentName>.generated.ts`. Only include overrides that appear in the boilerplate component — do not add extra overrides beyond what the boilerplate provides.
@@ -46,17 +54,22 @@ File where you can override the generated manifest from `<componentName>.generat
 ## Workflow
 
 1. **MANDATORY** — always use the scaffold; never substitute with manual file creation.
-   If `src/site/components/component-name/` does not yet exist, run
-   `npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description of what the component does"}'` to scaffold it. Skip this
+   If `src/extensions/site/components/component-name/` does not yet exist, run
+   `npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description of what the component does"}'` to scaffold it. The scaffold creates the files under `src/extensions/site/components/<folder>/` and registers the component in `src/extensions.ts`; edit them there (not under `src/site/components/`). Skip this
    step when iterating on an existing component — re-running it would
    return "an extension already exist" error.
 2. Run the following script to verify that the component dependencies are installed properly:
-`[[ -d "node_modules/@wix/react-component-schema" && -d "node_modules/@wix/react-component-utils" && -d "node_modules/@wix/editor-react-types" ]] || ([ -f yarn.lock ] && yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types || npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types)`
+`[[ -d "node_modules/@wix/react-component-schema" && -d "node_modules/@wix/react-component-utils" && -d "node_modules/@wix/editor-react-types" ]] || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; { [ -f "$d/yarn.lock" ] && yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types; } || npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types; }`
 3. Edit the generated react and CSS files in
-   `src/site/components/ComponentName/`.
+   `src/extensions/site/components/component-name/`.
 4. Run `npx wix build && npx wix generate manifest` so the editor picks up
    the new/updated prop schema. This command regenerates manifest
-   parts for all components.
+   parts for all components. Design-states emission requires
+   `@wix/cli` ≥ 1.1.215 (native and class-triggered states work from
+   ≥ 1.1.210, but prop-triggered `ElementState` states need ≥ 1.1.215). If a
+   design state is missing from `<componentName>.generated.ts`, the installed
+   CLI is older than required — tell the user, and let them decide whether to
+   upgrade.
 5. Update `Component.extensions.ts` file according to [`editor-react-component/COMPONENT-CONFIGURATION.md`](editor-react-component/COMPONENT-CONFIGURATION.md)
 
 Reference: when modifying an _existing_ component, follow
@@ -69,12 +82,15 @@ Core rules and workflow: [`editor-react-component/REACT-GUIDELINES.md`](editor-r
 Topic-focused references (rules + patterns + common mistakes in one place):
 
 - [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) — ARIA/a11y rules and patterns
+- [`editor-react-component/DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) — Which design states a part supports (heuristic) and how to author them
 - [`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/SSR.md`](editor-react-component/SSR.md) — Server-side rendering rules (mandatory)
-- [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — CSS rules, remaining common mistakes
+- [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, remaining common mistakes
+- [`editor-react-component/ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md) — Play/pause controls for animated components (Lottie, GIF, autoPlay props)
+- [`editor-react-component/COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) — `component.preview.tsx` patterns and `useIsEditMode()` usage
 
 ## CSS guidelines
 
 Reference: [`editor-react-component/CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md).
+

package/skills/wix-app/references/SITE_PLUGIN.md

@@ -34,7 +34,7 @@ Settings panel shown in the Wix Editor sidebar:
 
 ### 3. Extension Builder (`<plugin-name>.extension.ts`)
 
-Generated by the CLI with placements, tagName, element/settings paths, marketData (name/description/logoUrl), and `installation.autoAdd`. Edit `marketData.description` and `installation.autoAdd` directly in this file after scaffolding if defaults don't match your needs.
+Generated by the CLI with placements, tagName, element/settings paths, marketData (name/description/logoUrl), and `installation.autoAdd`. Edit `marketData.description` and `installation.autoAdd` directly in this file after scaffolding if defaults don't match your needs. `marketData.description` must stay under 130 characters.
 
 ## Plugin Component Pattern