@wix/agent-skills 1.0.0

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

@@ -0,0 +1,165 @@
+# 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. **Export `defaultProps` from `component.tsx`** so the extension file can import it.
+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 './component';
+
+// 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',
+  },
+});
+```