@wix/agent-skills 1.16.3 → 1.17.0

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

@@ -1,225 +0,0 @@
-# Component Configuration
-
-After scaffolding the component and running `npx wix build && npx wix generate manifest`,
-configure the component's behavior in the editor by writing **partial
-manifest overrides** in the component's hand-edited extension file
-(`<ComponentName>.extension.ts`). That file imports the auto-generated
-manifest and spreads it; specific fields are overridden inline. Re-running
-this command regenerates each `<ComponentName>.generated.ts`
-companion but never touches the overrides authored in the extension file.
-
----
-
-## 1. Verifying that height sizing type meets user needs
-
-Set `installation.initialSize.height.sizingType` based on whether the
-component's own content decides how tall it is.
-
-### Heuristic — one question
-
-**Does the component's own content decide how tall it is?**
-
-- **Yes — height should grow with text the user types or children they drop inside** → `LAYOUT.SIZING_TYPE.content`. Omit `pixels`.
-- **No — the component is a framed visual** (a graphic, an embedded media surface, a form control with a standard height, an empty placeholder) → `LAYOUT.SIZING_TYPE.pixels`. Provide a `pixels` default that matches its natural visual size.
-
-**Tiebreaker:** if a designer would drag a handle to set the height, it's `pixels`. If the height should just fit whatever is inside, it's `content`.
-
-### Where to write the override
-
-```ts
-import { extensions } from '@wix/astro/builders';
-import { LAYOUT } from '@wix/react-component-schema';
-import { manifest } from './ComponentName.generated';
-
-const componentExtension = extensions.editorReactComponent({
-  // …other fields…
-  installation: {
-    initialSize: {
-      width: {
-        sizingType: LAYOUT.SIZING_TYPE.pixels,
-        pixels: 250,
-      },
-      height: {
-        sizingType: LAYOUT.SIZING_TYPE.updateMe,
-      },
-    },
-  },
-});
-```
-
-### Examples
-
-**Content-driven** (`LAYOUT.SIZING_TYPE.content`) — testimonial card,
-FAQ accordion, pricing tier, blog-post body, list/grid of arbitrary
-children:
-
-```ts
-height: {
-  sizingType: LAYOUT.SIZING_TYPE.content,
-}
-```
-
-**Framed visual** (`LAYOUT.SIZING_TYPE.pixels`) — hero banner with a
-fixed image, video embed, color-picker swatch grid, OTP input, empty
-placeholder slot:
-
-```ts
-height: {
-  sizingType: LAYOUT.SIZING_TYPE.pixels,
-  pixels: 320,
-}
-```
-
----
-
-## 2. Verifying that resize direction meets user needs
-
-Set `editorElement.layout.resizeDirection` based on which axes the
-designer should be able to control with a drag handle. Allow an axis
-if dragging it produces a meaningful, intended change. Disallow it if
-dragging would do nothing visible or would break the component's
-identity.
-
-### Heuristic — which axes are meaningful?
-
-| Choice | When to use |
-|--------|-------------|
-| `horizontalAndVertical` | Content fills or stretches in both axes. Hero, carousel, gallery, card grid, embed, form control, any framed visual. **Default for most components.** |
-| `horizontal` | Height is rigid/intrinsic — cannot meaningfully stretch. Breadcrumb, tag row, nav bar, single-line input, slider rail. |
-| `vertical` | Width is rigid/intrinsic. Vertical stack, ribbon, sidebar rail. |
-| `aspectRatio` | Distortion breaks identity — logo, illustration, animation. |
-| `none` | Size fully owned by a parent layout. Never for top-level components. |
-
-**Tiebreaker:** if a drag handle on an axis would feel inert or wrong
-to a designer, take it away.
-
-### Where to write the override
-
-```ts
-import { extensions } from '@wix/astro/builders';
-import { LAYOUT } from '@wix/react-component-schema';
-import { manifest } from './ComponentName.generated';
-
-const componentExtension = extensions.editorReactComponent({
-  // …other fields…
-  editorElement: {
-    ...manifest.editorElement,
-    layout: {
-      resizeDirection: LAYOUT.RESIZE_DIRECTION._selectedResizeDirection_,
-    },
-  },
-});
-```
-
-### Examples
-
-```ts
-// hero, carousel, gallery, card grid, embed, form
-resizeDirection: LAYOUT.RESIZE_DIRECTION.horizontalAndVertical,
-
-// breadcrumb, tag row, nav bar, slider rail
-resizeDirection: LAYOUT.RESIZE_DIRECTION.horizontal,
-
-// logo, illustration, animation
-resizeDirection: LAYOUT.RESIZE_DIRECTION.aspectRatio,
-```
-
----
-
-## 3. Wiring defaults into the manifest
-
-1. **Define and export `defaultProps` from `<componentName>.props.ts`** — this is the single source of truth used by both `component.tsx` and the extension file.
-2. **Import `componentUrl` from `'./component.tsx?url'`** (the wrapped component), not from `'./ComponentName.tsx?url'` (the raw component).
-3. **Wrap `editorElement` with `withEditorElementDefaults`** using the same `defaultProps`.
-
-```ts
-import { withEditorElementDefaults } from '@wix/react-component-utils';
-import componentUrl from './component.tsx?url';
-import { defaultProps } from './<componentName>.props';
-
-// in the extension:
-editorElement: withEditorElementDefaults({
-  ...manifest.editorElement,
-}, defaultProps),
-resources: {
-  ...manifest.resources,
-  client: { componentUrl },
-},
-```
-
----
-
-## 4. Enabling automatic installation on Harmony editor
-
-**Always include `"staticContainer": "HOMEPAGE"`** in `installation` so the
-component is automatically installed on the Harmony editor.
-
-```ts
-const componentExtension = extensions.editorReactComponent({
-  // …other fields…
-  installation: {
-    // …other fields…
-    staticContainer: 'HOMEPAGE',
-  },
-});
-```
-
----
-
-## 5. Adding range constraints for numeric props
-
-The zero-config pipeline reads `@min` and `@max` JSDoc tags on numeric props and
-emits them as `number: { min, max }` in the generated manifest. Add these tags
-directly on the prop in the component's props interface — no extension file
-override is needed.
-
-### Heuristic — does this number have a fixed domain?
-
-| Scenario | Action |
-|----------|--------|
-| Rating 0–5, column count 1–6, items per row 1–4 | Add `@min` / `@max` |
-| Volume 0–100, playback speed 0.5–5, autoplay delay 0.5–30 | Add `@min` / `@max` |
-| Geo coordinates, zoom level | Add `@min` / `@max` |
-| Arbitrary count, free-form price, unconstrained input | Omit — leave as `number` |
-| Semantic index (active tab, active slide, active item) | Omit — upper bound is driven by the component's own item count, not a fixed domain |
-
-### How to write the tags
-
-Add `@min` and `@max` inline in the JSDoc comment for the prop in `<componentName>.props.ts`:
-
-```ts
-export interface RatingWidgetProps {
-  /** @min 0 @max 5 */
-  rating: number;
-}
-```
-
-Zero-config picks these up during `npx wix build && npx wix generate manifest`
-and emits:
-
-```ts
-rating: {
-  dataType: 'number',
-  number: { min: '0', max: '5' },
-}
-```
-
-### Examples
-
-```ts
-// Star rating 0–5
-/** @min 0 @max 5 */
-rating: number;
-
-// Volume 0–100
-/** @min 0 @max 100 */
-volume: number;
-
-// Playback speed 0.5–5
-/** @min 0.5 @max 5 */
-speed: number;
-
-// Column count 1–6
-/** @min 1 @max 6 */
-columns: number;
-```

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

@@ -1,6 +0,0 @@
-# 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/REACT-PATTERNS.md

@@ -1,95 +0,0 @@
-# React Component Patterns
-
-Code patterns and common mistakes for Editor React components.
-
-# Part 1: Implementation Patterns
-
-## 1.1 SSR-Safe Implementation
-
-Avoid browser-only APIs at module scope or during render; use them inside `useEffect` with `typeof window !== 'undefined'`.
-
-**❌ Wrong:**
-
-```typescript
-const userAgent = window.navigator.userAgent;
-```
-
-**✅ Correct:**
-
-```typescript
-useEffect(() => {
-  if (typeof window !== "undefined") {
-    const userAgent = window.navigator.userAgent;
-  }
-}, []);
-```
-
-## 1.2 Element Visibility (Platform-Managed)
-
-See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — element visibility is platform-managed; always render all elements, no conditional rendering.
-
----
-
-# Part 2: CSS/SCSS Rules
-
-Authoritative SCSS rules: `REACT-GUIDELINES.md` Part 2. For RTL/logical CSS patterns, see [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
-
-## 2.1 What NOT to Include
-
-```scss
-// ❌ NEVER include:
-
-// Transitions/Animations
-transition: all 0.3s;        // ❌
-animation: fadeIn 0.5s;      // ❌
-```
-
-> Design states (`hover`, `focus`, `selected`, …) are authored per
-> [`DESIGN-STATES.md`](DESIGN-STATES.md).
-
----
-
-# Part 3: Common Mistakes
-
-## 3.1 Custom-state classes
-
-For a custom design state, toggle the element's **global** state class from
-its data in JSX (e.g. `isSelected && 'pricing-card-row--selected'`, using the
-component-name-prefixed class) — don't express it as a module-scoped class. State styling lives in [`DESIGN-STATES.md`](DESIGN-STATES.md).
-
-## 3.2 Browser APIs at module scope
-
-**❌ Wrong:**
-
-```typescript
-const isMobile = window.innerWidth < 768; // ❌ SSR breaks
-```
-
-**✅ Correct:**
-
-```typescript
-useEffect(() => {
-  if (typeof window !== "undefined") {
-    setIsMobile(window.innerWidth < 768);
-  }
-}, []);
-```
-
-## 3.3 Use semantic HTML for collection-style UI
-
-For lists, breadcrumbs, tabs, menus, and similar collection-style UI, render the underlying semantic HTML directly (`<ol>`/`<ul>` + `<li>`, `<nav>`, `<button role="tab">`, etc.) and own the keyboard / ARIA wiring in your own React code.
-
-```tsx
-<ol className="breadcrumbs">
-  <li>
-    <a href="/">Home</a>
-  </li>
-  <li>
-    <span aria-hidden="true">/</span>
-    <a href="/products">Products</a>
-  </li>
-</ol>
-```
-
-Handle separators with CSS pseudo-elements or inside each item.
-