@wix/agent-skills 1.16.3 → 1.17.0

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

@@ -1,516 +0,0 @@
-# Component API
-
-Rules and patterns for props structure, elementProps, data types, file structure, containers, data-driven components, and array props.
-
----
-
-## Should This Use elementProps or CSS?
-
-```
-Is this element a named part (carries a global class string)?
-│
-├─ YES
-│   └─ ✅ It gets an elementProps entry — spread it + merge its className.
-│         Add config fields inside the entry only as needed
-│         (data, direction, event handlers).
-│
-└─ NO → purely visual/decorative non-part
-        (icons, separators, decorations, layout wrappers,
-         elements only hidden/shown via CSS)
-    └─ ❌ CSS class only — no elementProps entry
-```
-
----
-
-## Rules
-
-### Component Props Structure
-
-```typescript
-interface ComponentProps {
-  // Identity
-  id?: string;
-  className?: string;
-
-  // Mandatory features (from @wix/editor-react-types)
-  direction?: Direction;
-  a11y?: A11y; // ALL ARIA attributes come through this (ariaLabel, role, etc.)
-
-  // Component-specific props (NO children unless container-type - see container rules below)
-  label?: string;
-  items?: Array<ItemType>;
-  // ... from specification
-  // NEVER add: ariaLabel, ariaDescribedBy, role, etc. - use a11y prop instead
-
-  // Sub-component configuration (only if needed - see elementProps rules)
-  elementProps?: {
-    [partName]?: {
-      [configProp]?: string | boolean | number; // Only include if element needs config beyond className
-      direction?: Direction;
-    };
-  };
-}
-```
-
-### Propagate `elementProps` to inner elements
-
-`elementProps` is a map keyed by the manifest's inner-element keys; each entry
-carries that element's `className` (the editor sets it — this is how design
-states reach the element) plus any data.
-
-**Every named inner element — every element that carries a global class
-string — gets an `elementProps` entry, and you spread that entry onto the
-element.** This is mandatory, even when the element needs no other config:
-without it the editor cannot style that element or drive its states.
-
-How `className` gets merged depends on what the element is:
-
-- **Raw HTML element** (`<button>`, `<li>`, `<div>`): merge
-  `elementProps?.<key>.className` inline, alongside the global string and module
-  class — there's no component to do it.
-- **Sub-component built with this skill** (`<Inner/>`): the spread alone is
-  enough. `className` rides along inside it, and the sub-component merges it onto
-  its own root (every skill component merges its incoming `className`). Don't
-  merge it again at the call site.
-
-```tsx
-interface PlanCardProps {
-  className?: string;
-  elementProps?: {
-    cta?: { className?: string; href?: string };
-  };
-}
-
-// Raw HTML element — spread + merge className inline.
-// Note: the elementProps key is the short part name (`cta`), while the global
-// class is prefixed with the component name (`plan-card-cta`). Keep them as-is.
-<button {...elementProps?.cta} className={classNames('plan-card-cta', styles.cta, elementProps?.cta?.className)}>
-  {label}
-</button>
-
-// Sub-component built with this skill — spread is enough (it merges className itself):
-<PlanRow {...elementProps?.planRow} />
-```
-
-**Non-parts** (module-class-only elements: icons, decorations, separators,
-layout wrappers — no global class) get no entry. Style them with CSS.
-
-**Inside each entry**, add only the config the element needs (data, direction,
-event handlers). Never add a bare `className?` as the *only* field to decide
-whether an element qualifies — `className` always flows through; the entry
-exists because the element is a named part.
-
-### What Qualifies as a Part
-
-See [`PARTS.md`](PARTS.md) for root election (Step 0), the mandatory filter, and full rules. The root gets no `elementProps` entry — its `className`, `a11y`, and `direction` arrive as top-level props.
-
-### Derived values are not props
-
-If a displayed value can be computed with a simple pure function from
-other props and/or internal state, compute it internally — don't
-expose it as a prop. Expose only the source inputs (use numeric types
-when arithmetic is needed: `price: number`, not `price: string`).
-
-**Example:** subtotal = `price × quantity` → computed inside the component, not a prop.
-
-### Data-Driven Components (NO children in exported props)
-
-- Component's **exported interface** must NOT accept `children` prop
-- ALL content MUST come through explicit named props (see "Derived values" above for what stays internal):
-  - Text (labels, placeholders, messages) → `label`, `text`, `placeholder`, etc.
-  - Media (images, videos, icons) → `imageSrc`, `videoUrl`, `iconName`, etc.
-  - Links (URLs, hrefs) → `link`, `href`, `url`, etc.
-  - Collections (list items, options, menu items) → `items`, `options`, `menuItems`, etc.
-- **Internal implementation** can use children for composition between sub-components
-- Hardcoded values are ONLY for fallback defaults when props are undefined
-
-**Exception — Container-type components:** Components whose purpose is to wrap arbitrary child elements (e.g., BoxContainer) MAY accept `children: React.ReactNode`. This applies only to structural containers — data-driven leaf components (Button, Tabs, Accordion, etc.) must NOT use `children`.
-
-### Array Props: Data on Parent Only
-
-When the parent component defines an array prop (e.g., `items`), child/item components receive a single item directly. They do NOT redeclare the data structure in their own props.
-
-### Active-item components (one body visible at a time)
-
-Apply when the UI shows **one array item body at a time** (tabs, slideshow,
-steps). Skip for always-visible lists, multi-select, or multi-expand accordion.
-
-- Each item needs **`name: string`** — Studio hat labels (not `label` or other keys).
-- Pair the array with **`ActiveItemIndex<'arrayPropName'>`** from
-  `@wix/react-component-utils`; the type param must match the array prop name.
-  Default the index to `0` in `defaultProps`.
-- Render **all** item bodies (`.map`); toggle visibility with `--active` +
-  `display: none` on inactive panels (functional visibility — see
-  [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md)), plus `aria-hidden` and `inert` on
-  inactive bodies.
-- Keyboard navigation between triggers; ARIA roles per
-  [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
-
-```typescript
-import type { ActiveItemIndex } from '@wix/react-component-utils';
-
-export type ItemType = { name: string; body: string };
-
-export type MyComponentProps = {
-  items: Array<ItemType>;
-  activeItem: ActiveItemIndex<'items'>;
-};
-
-export const defaultProps = {
-  items: [{ name: 'Item 1', body: '…' }],
-  activeItem: 0,
-} satisfies Omit<MyComponentProps, 'id' | 'className'>;
-```
-
-### Array Element Types: Always Objects with Named Keys
-
-Array elements MUST be objects with named keys. This enables stable item identity (each item can carry its own `id`/`key`), non-breaking extension (new fields can be added later without changing the prop signature), and semantic naming (each value has meaning instead of being an opaque scalar).
-
-**Allowed forms:**
-
-- Inline object literal: `Array<{ key: ValueType, ... }>`
-- Named interface where the interface itself is an object with named keys (e.g. `Array<AccordionItem>` is OK because `AccordionItem` is `{ name, content }`)
-
-**Never allowed as the array element:**
-
-- Primitives: `Array<string>`, `Array<number>`, `Array<boolean>`
-- Leaf data types from `@wix/editor-react-types`: `Array<Image>`, `Array<Link>`, `Array<Video>`, `Array<Audio>`, `Array<VectorArt>`, `Array<RichText>`. Wrap them in an object instead.
-- Nested arrays:  `Array<Array<{cover: image, caption: string}>>` `Array<{items: Array<image>, caption: string}>`
-
-**❌ Wrong:**
-
-```typescript
-tags: Array<string>;
-prices: Array<number>;
-flags: Array<boolean>;
-images: Array<Image>;
-links: Array<Link>;
-nestedArrays: Array<Array<any>>
-```
-
-**✅ Correct:**
-
-```typescript
-tags: Array<{ label: string }>;
-prices: Array<{ amount: number }>;
-flags: Array<{ enabled: boolean }>;
-gallery: Array<{ image: Image, caption?: string }>;
-links: Array<{ link: Link, label: string }>;
-items: Array<AccordionItem>; // AccordionItem is { name, content }
-```
-
-### Container Components (Blackbox Content)
-
-When a component specification indicates a "container" or "slot" area where users can add nested content, use `React.ReactNode` for that content prop.
-
-**When to use `React.ReactNode` for a content prop:**
-
-- The specification describes a "container" or "content area"
-- Users should be able to add arbitrary nested components
-- The component doesn't control what goes inside that area
-
-**RTL Support:** Elements that render `React.ReactNode` content MUST have `dir="ltr"` to prevent RTL inheritance from the parent component. See [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
-
-### Component Data Types
-
-When creating TypeScript interfaces for component props, use types from `@wix/editor-react-types` for more complex types, to see the allowed type from this library, look at the following file `node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts`:
-
-```typescript
-import type { Link } from "@wix/editor-react-types"; // Reference at node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts
-```
-
-For **function event handler props** (`onClick`, `onDblClick`, `onChange`, `onFocus`, `onBlur`, `onMouseIn`, `onMouseOut`) and custom callbacks, follow [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md). Key rules:
-
-- Use the exact SDK prop names from that file — the manifest system recognizes them
-- Wire them to the correct DOM events (note: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`)
-- Custom callbacks not tied to DOM events use `() => void` (no React event parameter)
-
-### External resources are forbidden
-
-All resources rendered or fetched by the component (images, icons, fonts,
-videos, audio, JSON data, etc.) MUST come from Wix services. Never reference
-or call external (non-Wix) hosts — no `unsplash.com`, `placehold.co`,
-`picsum.photos`, third-party CDN icon sets, or any custom backend the user
-hasn't asked for. This rule covers both `src`/`href` attributes and any
-runtime fetching.
-
-Allowed image hosts: `static.wixstatic.com` (and other `*.wixstatic.com`
-subdomains). Allowed data: values supplied through props (populated by the
-editor) or imported local assets bundled with the component.
-
-### Default values for `Image` props
-
-Image defaults belong in the `<componentName>.props.ts` file's exported
-`defaultProps` constant (consumed by `withDefaults(Component, defaultProps)` in
-`component.tsx`). Use a Wix-hosted image from the Free-from-Wix public
-media catalog and populate **only** `uri`, `url`, and `alt` — leave
-`width`, `height`, `focalPoint`, etc. unset so the editor fills them when
-the user picks a real image.
-
-By default, use the canonical fallback URL from the examples below for
-every `Image` default (`url` and `uri` derived from the same `fileName`).
-**Only when the user explicitly asks for different/better default images**,
-fetch candidates from the Wix Free-from-Wix catalog:
-
-```
-GET https://publicmedia.wix.com/public/light_items?guid=bca5cb9f-45d2-4b11-8d6c-c9a7e7bd2873%3Aglobal%3Awix&pageSize=20&pageNumber=1&language=en&tags=free&mediaType=picture
-```
-
-The endpoint is unauthenticated. Pick an item whose `displayTags` /
-`title` fit the component's purpose, then build the `Image` default from
-its `fileName`:
-
-- `url` → `` `https://static.wixstatic.com/media/${fileName}` ``
-- `uri` → `fileName`
-- `alt` → a short human description (use the item's `title` or
-  `displayTags`)
-
-Do not call this endpoint when the user hasn't asked for it — the
-canonical fallback URL is fine for unattended scaffolds.
-
-**Default image pool — use a different image for each slot:**
-
-| # | fileName | Description |
-|---|----------|-------------|
-| 1 | `11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg` | Tropical beach aerial |
-| 2 | `11062b_73f31c7e7d3544c69dc8ecd8d34c5717~mv2.jpg` | Dead Sea landscape |
-| 3 | `11062b_3682ebfcb08e4da5b3168b62819a1e68~mv2.jpg` | Palm tree sunset |
-| 4 | `11062b_45e67783d39c4963ab9e4fc418173233~mv2.jpg` | Abstract pink waves |
-| 5 | `11062b_4c11f014b0d04948b2e6f554076bc40a~mv2.jpg` | Coastal village aerial |
-
-When a component needs **more than one** image default, cycle through
-the pool above so every slot gets a visually distinct image. For a
-single image, use image #1.
-
-**Single `Image` prop:**
-
-```typescript
-export const defaultProps = {
-  image: {
-    url: "https://static.wixstatic.com/media/11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-    uri: "11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-    alt: "Default image",
-  },
-} as const satisfies Omit<ExampleComponentProps, "id" | "className">;
-```
-
-**Array of objects with an `Image` field:**
-
-```typescript
-export const defaultProps = {
-  cards: [
-    {
-      title: "First card",
-      image: {
-        url: "https://static.wixstatic.com/media/11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-        uri: "11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-        alt: "First card image",
-      },
-    },
-    {
-      title: "Second card",
-      image: {
-        url: "https://static.wixstatic.com/media/11062b_73f31c7e7d3544c69dc8ecd8d34c5717~mv2.jpg",
-        uri: "11062b_73f31c7e7d3544c69dc8ecd8d34c5717~mv2.jpg",
-        alt: "Second card image",
-      },
-    },
-  ],
-} as const satisfies Omit<ExampleComponentProps, "id" | "className">;
-```
-
-**Inline fallback for HTML `src` / `href`:** when rendering a raw HTML
-attribute that takes a URL (`<img src>`, `<source src>`, `<video poster>`,
-`<a href>` for an image link, etc.) and the value could be empty, fall
-back to the same Wix-hosted URL — never to an external host or a relative
-path that doesn't exist:
-
-```tsx
-<img
-  src={
-    image?.url ||
-    "https://static.wixstatic.com/media/11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg"
-  }
-  alt={image?.alt || "Default image"}
-/>
-```
-
-### Component File Splitting
-
-Split logical UI pieces into separate named components. Never write inline JSX blocks for distinct complex UI pieces.
-
-**File structure for complex components (many subcomponents):**
-
-```
-ComponentName/
-├── components/                 # Subcomponents folder
-│   ├── SubComponent1/
-│   │   ├── SubComponent1.tsx
-│   │   ├── SubComponent1.module.scss
-│   │   └── index.ts
-│   └── SubComponent2/
-│       ├── SubComponent2.tsx
-│       └── index.ts
-├── hooks/                      # Custom hooks folder
-│   ├── index.ts
-│   └── useCustomHook.ts
-```
-
-**When to extract a sub-component:**
-
-- JSX block represents a logical complex unit (button, control, section, item)
-- Component has its own props interface
-- Logic is reusable or testable independently
-- Block has more than 15-20 lines of JSX
-
----
-
-## Patterns
-
-### Data-Driven Pattern
-
-**❌ Wrong:**
-
-```typescript
-export interface ButtonProps {
-  children: React.ReactNode;  // ❌
-}
-<Button>Click Me</Button>
-```
-
-**✅ Correct:**
-
-```typescript
-export interface ButtonProps {
-  label?: string;
-  icon?: string;
-}
-<Button label={label} icon={icon} />
-```
-
-Component controls rendering internally:
-
-```typescript
-const List = ({ items }) => (
-  <div>
-    {items.map(item => (
-      <ListItem key={item.id}>{item.label}</ListItem>
-    ))}
-  </div>
-);
-```
-
-### Array Props Pattern
-
-Parent defines array structure, child receives single item:
-
-```typescript
-// Parent
-interface ParentProps {
-  items: Array<AccordionItem>;  // Array defined here
-}
-
-interface AccordionItem {
-  name: string;
-  content: React.ReactNode;
-}
-
-// Child receives single item
-interface ChildProps {
-  item: AccordionItem & { id: string };  // Single item
-  isOpen?: boolean;
-}
-
-// Parent maps
-items.map((item, index) => (
-  <Child key={index} item={{ ...item, id: index.toString() }} />
-))
-```
-
-### Container Components Pattern
-
-For "container" or "slot" areas, use `React.ReactNode`:
-
-```typescript
-interface AccordionItem {
-  name: string;
-  content: React.ReactNode;  // Users add any content here
-}
-
-// Render
-{items.map((item, index) => (
-  <div key={index} dir="ltr">
-    {typeof item.content === 'function' ? item.content({}) : item.content}
-  </div>
-))}
-```
-
----
-
-## Common Mistakes
-
-### Using children prop in exported interface
-
-**❌ Wrong:**
-
-```typescript
-export interface CardProps {
-  children: React.ReactNode;  // ❌ children + React.ReactNode both forbidden
-}
-<Card><CardHeader>Title</CardHeader></Card>
-```
-
-**✅ Correct:**
-
-```typescript
-export interface CardProps {
-  title: string;
-  content: React.ReactNode;
-}
-<Card title="Title" content={<div>Content</div>} />
-```
-
-### Adding elementProps for CSS-only elements
-
-**❌ Wrong:**
-
-```typescript
-elementProps?: {
-  icon?: { className?: string; }  // ❌ Only className
-  separator?: { className?: string; }  // ❌ Only className
-}
-```
-
-**✅ Correct:**
-
-```typescript
-// No elementProps for purely visual elements (including conditionally displayed)
-// Style via CSS classes directly
-```
-
-**Why:** Don't declare a `className?:` field — `className` already flows through each named inner element's `elementProps` entry (see "Propagate `elementProps` to inner elements"). Conditional display is controlled via CSS, not React props.
-
-### Using T[] array syntax
-
-Use `Array<T>` over `T[]`.
-
-**❌ Wrong:**
-
-```typescript
-interface ComponentProps {
-  items: Item[]; // ❌ Wrong syntax
-  tags: string[]; // ❌ Wrong syntax
-  tags: Array<string>; // ❌ Element must be an object with named keys
-}
-```
-
-**✅ Correct:**
-
-```typescript
-interface ComponentProps {
-  items: Array<Item>; // ✅ Correct syntax
-  tags: Array<{ label: string }>; // ✅ Element is an object with named keys
-}
-```
-
-See also: [Array Element Types: Always Objects with Named Keys](#array-element-types-always-objects-with-named-keys) — items must be objects with named keys.