@wix/agent-skills 1.0.0

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

@@ -0,0 +1,138 @@
+# Accessibility (ARIA)
+
+Rules and patterns for ARIA accessibility support in Editor React components.
+
+---
+
+## Rules
+
+### All ARIA Attributes Through the `a11y` Prop
+
+- **NEVER** add individual ARIA properties like `ariaLabel?: string`, `ariaDescribedBy?: string`, `role?: string`, etc. to a component's props interface.
+- **ALL** accessibility attributes MUST come through the `a11y?: A11y` prop.
+- The `A11y` type includes: `ariaLabel`, `ariaDescribedBy`, `ariaLabelledBy`, `role`, `ariaHidden`, `ariaLive`, and all other ARIA attributes.
+- Users provide ARIA values through the `a11y` prop: `<Component a11y={{ ariaLabel: "..." }} />`
+
+### ARIA Label Rules
+
+ARIA labels are user-facing content and must NEVER be hardcoded as string literals in JSX.
+
+**Three patterns (in order of preference):**
+
+1. **No aria-label (preferred)** — Visible text content is sufficient:
+
+   ```tsx
+   <Button>Play</Button> // Visible text ✅
+   ```
+
+2. **User-configurable** — Via a11y prop (for root or element-specific labels, per requirements):
+
+   ```tsx
+   // User provides: <ComponentName a11y={{ ariaLabel: "Background music" }} />
+   // Component applies to root (using the a11y-to-HTML conversion utility):
+   {...(a11y && convertA11yKeysToHtmlFormat(a11y))}
+
+   // Or for inner elements (if requirements specify):
+   // elementProps.button.a11y gets passed to the button element
+   ```
+
+3. **System-required** — Via constants.ts (when requirements specify non-configurable label):
+
+   ```tsx
+   // constants.ts
+   export const ARIA_LABELS = {
+     playButton: 'Play audio',
+     muteButton: 'Mute audio',
+   } as const;
+
+   // component.tsx
+   import { ARIA_LABELS } from './constants';
+   <Button aria-label={ARIA_LABELS.playButton}>▶</Button>;
+   ```
+
+**❌ NEVER hardcode string literals:**
+
+```tsx
+// ❌ WRONG - hardcoded strings
+<Button aria-label="Play">▶</Button>
+<Button aria-label={isPlaying ? "Pause" : "Play"}>▶</Button>
+<Slider aria-label="Volume" />
+```
+
+**Why this matters:**
+
+- Hardcoded strings cannot be translated or customized
+- User-provided labels take precedence when available
+- Constants allow centralized management and potential future translation
+
+### Detecting Icon-Only Interactive Elements
+
+**Icon-only elements require aria-labels.** Detect with this checklist:
+
+| Element Content       | Needs aria-label? | Example                                   |
+| --------------------- | ----------------- | ----------------------------------------- |
+| Visible text only     | ❌ No             | `<Button>Play</Button>`                   |
+| Icon component + text | ❌ No             | `<Button><PlayIcon />Play</Button>`       |
+| Icon/emoji only       | ✅ YES            | `<Button>▶</Button>`                     |
+| Image only            | ✅ YES            | `<Button><img src="play.png" /></Button>` |
+| SVG only              | ✅ YES            | `<Button><svg>...</svg></Button>`         |
+
+**Critical:** If button/link contains ONLY visual elements (icons, emojis, images, SVG) with NO text node, it MUST have aria-label from constants.
+
+**Pattern for dynamic labels:**
+
+```tsx
+// constants.ts
+export const ARIA_LABELS = {
+  playButton: 'Play audio',
+  pauseButton: 'Pause audio',
+} as const;
+
+// component.tsx
+<Button
+  aria-label={isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton}
+>
+  {isPlaying ? '⏸' : '▶'}
+</Button>;
+```
+
+---
+
+## Common Mistake: Individual ARIA Properties Instead of A11y Type
+
+**❌ Wrong:**
+
+```typescript
+import type { Direction } from '@wix/editor-react-types';
+
+export interface TabsProps {
+  id?: string;
+  className?: string;
+  direction?: Direction;
+  ariaLabel?: string; // ❌ Individual ARIA prop
+  ariaDescribedBy?: string; // ❌ Individual ARIA prop
+  role?: string; // ❌ Individual ARIA prop
+}
+```
+
+**✅ Correct:**
+
+```typescript
+import type { A11y, Direction } from '@wix/editor-react-types';
+import { convertA11yKeysToHtmlFormat } from '@wix/react-component-utils';
+
+export interface TabsProps {
+  id?: string;
+  className?: string;
+  direction?: Direction;
+  a11y?: A11y;  // ✅ All ARIA attributes through this prop
+}
+
+// Usage:
+<Tabs a11y={{ ariaLabel: "Navigation", role: "navigation" }} />
+
+// In component:
+{...(a11y && convertA11yKeysToHtmlFormat(a11y))}
+```
+
+**Why:** The `A11y` type from `@wix/editor-react-types` provides a standardized way to handle ALL ARIA attributes (ariaLabel, ariaDescribedBy, ariaLabelledBy, role, ariaHidden, ariaLive, etc.). Individual ARIA props fragment the API and make it harder to use.

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

@@ -0,0 +1,454 @@
+# 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?
+
+```
+Does this element need:
+- Configuration/data beyond styling
+- Direction override
+- State management
+- Event handlers
+
+│
+├─ YES
+│   └─ ✅ Use elementProps
+│
+└─ NO → Is it purely visual/decorative (including conditionally displayed)?
+    │
+    ├─ YES (icons, separators, decorations, elements only hidden/shown via CSS)
+    │   └─ ❌ CSS class only (no elementProps)
+    │
+    └─ NO
+        └─ Re-evaluate: likely needs elementProps
+```
+
+---
+
+## 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;
+    };
+  };
+}
+```
+
+### When to Use elementProps
+
+**Use `elementProps`** for parts that need:
+
+- Configuration/data beyond just styling
+- Direction override
+- State management
+- Event handlers
+
+**DO NOT use `elementProps`** for:
+
+- Elements with only visual styling (use CSS classes)
+- Elements where conditional display is the only requirement (visibility controlled via CSS for per-breakpoint hiding, not React props)
+- Elements that would only have `className` — skip them entirely
+- Icons, decorations, separators
+
+**Minimal elementProps rule:** If an element would only have `className?: string` in elementProps, do NOT include it.
+
+### What Qualifies as a Part
+
+See [`PARTS.md`](PARTS.md) for the mandatory filter and full rules.
+
+### 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.
+
+### 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
+```
+
+### 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 component file's exported `defaultProps`
+constant (the one 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:** If element only has `className` (even if it can be hidden/shown via CSS), skip elementProps entirely. 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.