@wix/agent-skills 1.18.0 → 1.18.2

package/skills/wix-app/references/dashboard-page/COLLECTION_TOOLKIT.md

@@ -34,9 +34,9 @@ Everything below is a real name in the installed `@wix/patterns`. Confirm the pr
 | A fixed in-memory option list for a filter | `useStaticListFilterCollection` |
 | Sorting | `Sortable Columns`, `MultiLevelSorting` |
 
-**Ask for several names at once.** `docs`, `types` and `exports` all take a list — `types ComputedQuery OffsetQuery RangeItem`, `exports page form router` — and each call is a full model turn, so five one-name calls cost five turns for one call's worth of answer. `exports` with no argument lists the 31 entry points; that is a one-off orientation, not something to re-run.
+**Read the index once, then go straight to files.** `dist/dts-bundle/index.json` answers every name in this table in a single read — resolve it once per session and keep it, rather than re-reading it per lookup. Each entry names the exact file to open next.
 
-**A factory or hook's doc is often empty where its signature should be** — `docs idNameArrayFilter` prints an `## API` heading with nothing under it, because the props table only exists for components. Ask `types idNameArrayFilter` instead and you get the signature: `<T extends { id: string; name: string }>(params?) => ArrayFilterState<T>`. That applies to every `use…` hook and every `…Filter` factory in the table above, and it is the difference between knowing the name and being able to call it.
+**A factory or hook's doc is often empty where its signature should be** — the props table is generated for components, so `idNameArrayFilter`'s doc shows an `## API` heading with nothing under it. Its bundle has the signature: `<T extends { id: string; name: string }>(params?) => ArrayFilterState<T>`. That holds for every `use…` hook and every `…Filter` factory in the table above, and it is the difference between knowing a name and being able to call it — so for these, read the bundle the index names, not the doc.
 
 **A filter must narrow the result.** Declare it in the collection hook's `filters` map and read it inside `fetchData`, so the value reaches the query. Filter UI that renders but never changes the rows is a defect that looks like a feature — and it is the failure mode these components exist to prevent.
 
@@ -49,7 +49,7 @@ Everything below is a real name in the installed `@wix/patterns`. Confirm the pr
 | **Expanded row** | A couple of extra fields, no separate workspace needed. | The collection's own row expansion |
 | **Picker / bulk confirm** | Choosing records, or confirming an action on many. | `PickerModal` + `usePickerModal`, `bulkActionModal` |
 
-A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md). A row the user cannot open is the second most common failure after the missing aggregate.
+A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md); for the create route itself — registering it, and the four params that differ from the edit call — [ENTITY_PAGE_TOOLKIT.md § Create route](ENTITY_PAGE_TOOLKIT.md#create-route). A row the user cannot open is the second most common failure after the missing aggregate.
 
 **Form state on an entity page** comes from `@wix/patterns/form` — `useForm` for the form, `useController` for a single field. That subpath re-exports `@wix/bex-core/form`, which wraps `react-hook-form`, so its API is react-hook-form's and only a handful of its names appear in the patterns docs: `FieldValues`, `ControllerProps` and most of the rest are documented by react-hook-form, not here. `Read <pkgRoot>/dist/dts-bundle/exports/form.d.ts` to see what the subpath actually gives you.
 
@@ -57,10 +57,11 @@ A dialog that creates, updates or displays one listed record is **not** a dashbo
 
 | Need | Component |
 | --- | --- |
-| Row actions | `PrimaryActions`, `SecondaryActions`, `More Actions`, `deleteSecondaryAction` |
-| Page-level button | `PrimaryPageButton`, `PrimaryActionButton` |
+| Page header actions | `PrimaryActions`, `SecondaryActions`, `More Actions` — passed to the page header's `primaryAction`, `secondaryActions` and `moreActions` slots |
+| Table toolbar button | `PrimaryActionButton` — the table's own `primaryActionButton` prop |
+| Row actions | `deleteSecondaryAction`, in the row's `actionCell` |
 | Acting on a multi-row selection | `MultiBulkActionToolbar`, `bulkActionModal` |
-| Immediate feedback, then reconcile | `useOptimisticActions`, `CollectionOptimisticActions` |
+| Immediate feedback, then reconcile | `useOptimisticActions(state.collection)` ✅ — not `useOptimisticActions(state)` ❌: `useTableCollection()` returns `TableState<T, F>`, and the hook takes the `CollectionState<T, F>` that state exposes as `state.collection`. Returns `CollectionOptimisticActions` |
 | A banner above the table | `TableTopNotification` |
 
 ## The states that are not the happy path

package/skills/wix-app/references/dashboard-page/ENTITY_PAGE_TOOLKIT.md

@@ -26,10 +26,29 @@ const state = useEntityPage<Shift, ShiftFormFields>({
       .updateShift(shiftId, { ...form.getValues(), ...widgetsFormData })
       .then((updatedEntity) => ({ updatedEntity })),
   form,
-  parentPath: '/shifts',
+  parentPath: '/',
 });
 ```
 
+**`parentPath` is relative to the router's own mount point — the dashboard page's
+own root, not the page's `route` value.** A dashboard page scaffolded with
+`{"route": "shifts"}` is served at `/dashboard/shifts`, but `PatternsReactRouter`
+still sees its own location start fresh at `/` inside that page — so `parentPath`,
+every `PatternsReactRoute`'s `path`, and the `path` passed to
+`navigateToEntityPage()` / `navigateToCollectionPage()` must never repeat the
+page's own `route`/name. `parentPath: '/shifts'` on a page whose `route` is
+`"shifts"` is the single most common way this gets copied wrong — it looks like a
+reasonable guess (name the parent after the page) and compiles, but the
+collection route it points back to is registered at `path="/"`, not
+`path="/shifts"`, so `parentPath` must match that: `'/'`. See [Create
+route](#create-route) below for the full route registration.
+
+From **1.465.0** the library's own docs state this rule — `PatternsReactRouter.md`,
+`usePatternsNavigate.md` and `useEntityPage.md`'s **Create route**. On an older
+install they don't, and their examples *demonstrate* the mistake
+(`navigateToEntityPage({ path: '/shifts/new' })`, `navigateToCollectionPage({ path:
+'/entities' })`); prefer this rule over what those examples show.
+
 `EntityPage` and `useEntityPage` are **root** exports. `@wix/patterns/page` holds `CollectionPage` and `WidgetsFormProvider` only, so importing the entity page from there is `TS2305: has no exported member` — the collection page and the entity page do not live in the same place. `Read <pkgRoot>/dist/dts-bundle/exports/page.d.ts` to see what that subpath actually gives you.
 
 ## Name both generics
@@ -54,9 +73,22 @@ Reaching for a `values`-shaped key on the `onSave` argument is the usual first g
 
 ## The params are a `Pick`
 
-`UseEntityPageParams` picks a fixed set off `EntityPageStateParams` — `fetch`, `onSave`, `saveSuccessToast`, `saveErrorToast`, `deleteAction`, `transformEntityToCollectionItem`, `isNewEntity`, `form`, `parentPageId`, `parentPath`, `parentReferrer`, `schemaSource`. Anything outside that list is an excess-property error on the object literal. `container` is the common guess and is not one of them: the hook calls `useWixPatternsContainer()` itself.
+`UseEntityPageParams` picks a fixed set off `EntityPageStateParams` — `fetch`, `onSave`, `saveSuccessToast`, `saveErrorToast`, `deleteAction`, `transformEntityToCollectionItem`, `isNewEntity` (create vs edit — [Create route](#create-route)), `form`, `parentPageId`, `parentPath`, `parentReferrer`, `schemaSource`. Anything outside that list is an excess-property error on the object literal. `container` is the common guess and is not one of them: the hook calls `useWixPatternsContainer()` itself.
+
+Confirm the shape rather than guessing — the hook's doc ends by pointing at the bundle rather than tabulating props, because props tables only exist for components. `Read <pkgRoot>/dist/dts-bundle/index.json`, then `Read` the bundled `.d.ts` for each of `useEntityPage`, `UseEntityPageParams`, and `OnSaveParams` at exactly the `file` path the index gives.
+
+## Create route
+
+The example above is edit-only. "Add new" is an `EntityPage` too, and it is not the same call with the id left out. Four things differ, and three of them fail silently if you guess:
+
+- The route is its own `PatternsReactRoute type="createEntity"`. One component can serve both entity routes; the route is what tells them apart.
+- `navigateToEntityPage({ path })` — omit `entity`. It exists so the header can render a title before the fetch resolves, and a create route has no record to give it. A placeholder is worse than nothing: until `fetch` resolves it *is* `state.entity`.
+- `fetch` is required on the create route too, and `{ entity: undefined }` is the create case built into its return type — not a loading state, and there is no `fetch`-less variant.
+- `isNewEntity` is the only param that tells the page which route it is on. Omitted, a create page that seeds defaults through `fetch` is announced to the collection as an *update*: the collection changes a row it does not have, the new record never appears in the list, and the only trace is a `Fetched page info for updated entity not found` console error.
 
-Confirm the shape rather than guessing — the hook's doc has an empty API section, because props tables only exist for components. `Read <pkgRoot>/dist/dts-bundle/index.json`, then `Read` the bundled `.d.ts` for each of `useEntityPage`, `UseEntityPageParams`, and `OnSaveParams` at exactly the `file` path the index gives.
+`Read <pkgRoot>/dist/docs/useEntityPage.md` before writing one — its **Create route** section carries the worked component that serves both routes off one `useParams` answer, and the `boolean | (() => boolean)` getter form for `isNewEntity`.
+
+**If that file has no `Create route` heading, the installed `@wix/patterns` predates 1.464.0.** Upgrade and re-read rather than working around it: on those versions `navigateToEntityPage` types `entity` as required, so omitting it does not compile, and passing the placeholder that satisfies it is the failure the bullet above describes.
 
 ## Around the call
 
@@ -64,10 +96,45 @@ Confirm the shape rather than guessing — the hook's doc has an empty API secti
 | --- | --- |
 | Getting here from the collection page | `usePatternsNavigate()` → `navigateToEntityPage({ path, entity })` |
 | Registering the route | `PatternsReactRoute` inside `PatternsReactRouter` |
-| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` |
+| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` — `useController`, never `register` |
 | Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
 | The fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
 
+Every `path` in that first row — the route's own `path`, `parentPath`, and the `path` argument to `navigateToEntityPage`/`navigateToCollectionPage` — is relative to the page's own root, never to its `route`/name. See the `parentPath` note under [The call](#the-call) above; it is the same rule everywhere a path appears in this table.
+
 `@wix/patterns/form` re-exports `@wix/bex-core/form`, which wraps `react-hook-form` — so `form.getValues()`, `form.reset()` and the rest are react-hook-form's API, documented there rather than in the patterns docs.
 
+## Binding a field: `useController`, never `register`
+
+`register` returns props for a plain `<input>`, and WDS components are not one. Two ways it fails:
+
+`<Input {...register('qty')} />` does not compile — `register` always returns `min`/`max` as `string | number`, whatever options you passed, and WDS types them `number | undefined`. The error names `InputProps`, which reads like a WDS bug and isn't.
+
+`<Input ref={register('qty').ref} />` **does** compile and is wrong. `Input`'s `ref` is its imperative handle (`Ref<InputImperativeActions>`); `register`'s ref is `(instance: any) => void`, so it accepts that and binds the handle rather than the `<input>`. The field never registers, validation never sees it, and nothing reports it.
+
+Bind through value/onChange instead:
+
+```tsx
+import { useController, useForm } from '@wix/patterns/form';
+import { FormField, Input } from '@wix/design-system';
+
+type ProductForm = { name: string; qty: number };
+
+function NameField({ form }: { form: ReturnType<typeof useForm<ProductForm>> }) {
+  const { field, fieldState } = useController({
+    name: 'name',
+    control: form.control,
+    rules: { required: 'Name is required' },
+  });
+
+  return (
+    <FormField label="Name" required status={fieldState.error ? 'error' : undefined} statusMessage={fieldState.error?.message}>
+      <Input value={field.value} onChange={field.onChange} onBlur={field.onBlur} />
+    </FormField>
+  );
+}
+```
+
+Rules live in `rules`, not on the WDS component. If you need `register` for a DOM concern such as input masking, `Input` takes `inputRef?: React.Ref<HTMLInputElement>` — pass the ref there, never to `ref`.
+
 A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md).

package/skills/wix-app/references/dashboard-page/PATTERNS_BUNDLE_READING.md

@@ -1,14 +1,54 @@
 # Reading `@wix/patterns` Bundles and Docs
 
-> **Scope.** You are here because a lookup in `dist/dts-bundle/index.json` or
-> `dist/docs/index.json` gave you an entry and you are about to open the file it names. Getting to that index in the first
-> place — resolving the package root, the version floor, the docs lookup, and the rule
+> **Precondition: an index entry.** Every path below is the `file` (or `bundle`) field of an entry
+> in `<pkgRoot>/dist/dts-bundle/index.json` or `<pkgRoot>/dist/docs/index.json`. If you haven't
+> read that index this session, you have no path to open — read it before anything else here.
+> Getting to it — resolving the package root, the version floor, the docs lookup, and the rule
 > against browsing `node_modules` by hand — is in
 > [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md). Nothing here replaces those steps.
 
+## Read the index once, then open its files in one call
+
+One index read covers the whole page. So name every symbol you plan to write — components, hooks,
+state types, prop types — look them all up in the index you now hold, and open what it named in a
+single call with one `Read` per file:
+
+```
+call 1   Read <pkgRoot>/dist/docs/index.json
+         Read <pkgRoot>/dist/dts-bundle/index.json
+
+call 2   Read <pkgRoot>/dist/docs/Table.md                            <- docs entry's `file`
+         Read <pkgRoot>/dist/docs/useTableCollection.md
+         Read <pkgRoot>/dist/dts-bundle/components/Table.d.ts         <- its `bundle`
+         Read <pkgRoot>/dist/dts-bundle/hooks/useTableCollection.d.ts
+         Read <pkgRoot>/dist/dts-bundle/types/TableState.d.ts         <- bundle entry's `file`
+```
+
+Two calls, not twenty-two — and nothing is lost by batching, because there is nothing to learn
+between the files: every path came out of the same index and `bytes` already told you each size.
+The same files opened one per call re-send the whole conversation once per file, which is where a
+lookup session's token cost actually goes. Batch the follow-ups the same way: when a doc names an
+example file, or a stub names another bundle (below), collect them and read them together.
+
+## Where props live
+
+From `@wix/patterns` **1.460.0** onward a doc does not repeat props that the bundle already
+describes. Which one holds them is stated in the doc's own index entry:
+
+| `dist/docs/index.json` entry | where the props are |
+| --- | --- |
+| has a `bundle` field | that bundle — the doc's `### Props` is a pointer to it, on purpose |
+| no `bundle` field | the doc's own `### Props` table, as before |
+
+Roughly 74 of 167 docs point at a bundle and 62 still carry a table, so expect both. When a doc
+says `Read \`dist/dts-bundle/...\``, that **is** the props answer — read the named file rather
+than treating the doc as incomplete. The bundle is the better source anyway: it keeps the
+`extends` clause with its exclusions, so `Omit<PopoverMenuItemProps, 'text' | 'prefixIcon' | 'onClick'>` tells
+you what you do *not* inherit, which the old doc link did not.
+
 ## Types the docs don't cover
 
-The docs cover components and props, not the types those props use — `Filter<T>`, `RangeItem<T>`, `CursorQuery`, a `...Props` interface. `Read <pkgRoot>/dist/dts-bundle/index.json`, look up the type name, then `Read <pkgRoot>/dist/dts-bundle/<entry.file>` using exactly the `file` path the index gives — **never reconstruct the path from the name**; bundles are nested one directory per kind (`components/Table.d.ts`, `hooks/useForm.d.ts`, `types/RangeItem.d.ts`, …), so guessing `<Name>.d.ts` at the top level is wrong by construction.
+The same bundles also hold the types those props use — `Filter<T>`, `RangeItem<T>`, `CursorQuery`, a `...Props` interface. `Read <pkgRoot>/dist/dts-bundle/index.json`, look up the type name, then `Read <pkgRoot>/dist/dts-bundle/<entry.file>` using exactly the `file` path the index gives — **never reconstruct the path from the name**; bundles are nested one directory per kind (`components/Table.d.ts`, `hooks/useForm.d.ts`, `types/RangeItem.d.ts`, …), so guessing `<Name>.d.ts` at the top level is wrong by construction.
 
 Several of these types (`RangeItem`, `Filter`, `CursorQuery`, the filter factory functions) actually live in `@wix/bex-core` — the bundle already resolves and inlines the real declaration, so you get the full shape with no deep, undeclared `@wix/bex-core/dist/types/...` path to chase. Still always import it from `@wix/patterns`, per the index's `importPath` field, never from wherever the bundle says it's really declared.
 
@@ -32,9 +72,24 @@ An empty body with a **"Produced by"** note means: call that hook or factory to
 
 A stub saying **"cut here because it has its own bundle"** means the same thing for a shape you *do* write: it wasn't copied in twice, so look the name up and read its own file.
 
-Every bundle fits in a single read; the index's `bytes` field says how big before you open it. So a bundle is never partially shown — if something looks missing, it was cut on purpose and the stub names where to find it.
+Every bundle fits in a single read; the index's `bytes` field says how big before you open it. So a bundle is never partially shown — if something looks missing, it was cut on purpose. Both stubs above name where to find it.
+
+### The one that doesn't: a bare `import`
+
+A plain `import { X } from '<module>'` at the top of a bundle, with no note attached, is the third shape you will meet — and unlike the two above it does **not** tell you where to look. What to do depends on the path, not the name:
+
+**A normal entry point** — `react`, `react-hook-form`, `history`, `@wix/design-system`. Resolve it the ordinary way. For `@wix/design-system` names use the `wix-design-system` skill; don't read WDS files directly.
+
+**A deep internal path** — `@wix/design-system/dist/types/DropdownLayout`, `@wix/bex-utils/@wix/bi-logger-os-data/v2/types`. This is an upstream defect: the bundle recorded where the type is *declared* instead of where it is exported. Two things follow, and the second is the one that saves you time:
+
+- Never import that path in your own code, and don't go read the file it points at. It is not a public entry point, and the name is often not re-exported from the package root either — `DropdownLayoutOption` is not exported from `@wix/design-system`, so there is no shorter import to substitute.
+- You usually don't need the declaration at all. Where the type is a **prop you fill in** — WDS option shapes like `SingleSelectFilter`'s and `AutoCompleteFilter`'s `items` — look the *component* up in the `wix-design-system` skill and use the shape its docs show. Where it is a **pass-through you never construct** — the BI logger params behind optional fields like `biAdditionalInfo` — pass what the patterns doc shows, or omit it; it is optional.
+
+If a name you genuinely need stays unresolved after that, stop and say so, and name the bundle and the exact import path that dead-ended. Do not guess a shape and do not go spelunking in `node_modules` — a wrong guess compiles here and breaks at runtime, which is worse than the missing type.
+
+A handful of names carry `"status": "unreachable"` — plus `"unexported": true` from **1.465.0** — with a message saying not to import them (the `...BaseProps` interfaces a component's props `extends`). Read those for the props they contribute; don't write an import for them.
 
-A handful of names carry `"status": "unreachable"` with a message saying not to import them (the `...BaseProps` interfaces a component's props `extends`). Read those for the props they contribute; don't write an import for them.
+`status` also carries `"deprecated"`, and there the `statusMessage` names the replacement — `PrimaryPageButton` says *"Use `PrimaryActions` component instead."* Check it before you commit to a name — nothing else in the lookup path will stop you, since a deprecated component still compiles and still renders. If the index calls a name deprecated, use what its message names instead.
 
 ## Subpath entry points
 
@@ -49,4 +104,9 @@ Links to `https://www.docs.wixdesignsystem.com/` are external (Wix Design System
 ## Tips
 
 - **Compound components** have separate docs per sub-part: `CollectionPage.md`, `CollectionPage.Header.md`, `CollectionPage.Content.md`.
-- **Hook docs** list configuration options as props in the API table.
+- **Hook docs** list configuration options as props — in the API table when the doc has no
+  `bundle` field, otherwise in the bundle it points at.
+- **Heavy examples live beside the doc.** A variation whose code was long is written out
+  separately, and the doc keeps the heading, the description and an exact path:
+  `Example code: read \`dist/docs/ToolbarFilters/apply-changes.tsx\``. Read that path only if you
+  need that particular variation — the heading and description are usually enough to choose.

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

@@ -25,7 +25,7 @@ import type { A11y, Direction } from '@wix/editor-react-types';
 import { convertA11yKeysToHtmlFormat } from '@wix/react-component-utils';
 
 export type TabsProps = {
-  id?: string;
+  id: string;
   className?: string;
   direction?: Direction;
   a11y?: A11y;

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

@@ -1,8 +1,7 @@
 # Animated Components
 
-Use this reference when the component's primary content is a **playable
-animation**—a Lottie/JSON animation, an animated GIF/SVG, a canvas/WebGL loop,
-or a video-like surface.
+Use this reference when the component's primary content **auto-advances or plays**
+— a slideshow/carousel/slider; a Lottie/JSON animation; an animated GIF/SVG, a canvas/WebGL loop, a video-like surface; or similar content a visitor should be able to start or stop.
 
 Every such component must ship an on-stage **play/pause button**.
 
@@ -22,7 +21,7 @@ Apply automatically — without being asked — whenever the component has an
 `autoPlay` prop **or** its primary content is a **startable / loopable**
 animation a visitor would reasonably want to start or stop:
 
-- Any component with an `autoPlay` prop (gallery, slider, carousel, etc.)
+- Slideshow, carousel, slider, or gallery that advances slides/cards
 - Lottie / JSON vector animations
 - Animated GIFs or animated SVGs
 - Canvas / WebGL animation loops
@@ -40,6 +39,8 @@ implementation detail.
    automatically, `loop` only when repeat behavior is supported, and
    `pauseButtonVisibility` for the on-stage control. When editing, preserve
    existing playback prop names and add only the missing safety contract.
+   Carousels, sliders, slideshows, and galleries **must** define `autoPlay`
+   (default `true`).
 2. **Playback state** — `isPlaying` + `handlePause` / `handleResume`
 3. **Play/pause button** — overlay `<button>` with inline SVG icon and CSS
    positioning; it must be a named part with `elementProps` wiring, a hover
@@ -57,7 +58,7 @@ able to force the safety control visible.
 import type { A11y, Direction } from '@wix/editor-react-types';
 
 export interface MyAnimationProps {
-  id?: string;
+  id: string;
   className?: string;
   direction?: Direction;
   a11y?: A11y;
@@ -215,7 +216,9 @@ Add `useIsEditMode` to the existing `@wix/react-component-utils` import. Then
 edit only the body of the existing `ComponentNamePreview` function — add the
 `isEditMode` check and gate the autoplay props. Do not touch the
 `withFallbackPlaceholder` call, the `withDefaults` export, or any other part
-of the file.
+of the file. The composition must keep `withDefaults` outside
+`withFallbackPlaceholder`, whether the calls are nested inline or assigned to
+component variables.
 
 ```tsx
 const ComponentNamePreview: FC<ComponentProps<typeof Component>> = (props) => {

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

@@ -25,7 +25,7 @@ Use this shape:
 import type { A11y, Direction } from '@wix/editor-react-types';
 
 export type PlanCardProps = {
-  id?: string;
+  id: string;
   className?: string;
   direction?: Direction;
   a11y?: A11y;
@@ -53,9 +53,8 @@ Rules:
 
 ## Numeric Range Constraints
 
-For a new or changed numeric prop, use inline `@min` and `@max` JSDoc tags when
-the value has a fixed domain. Manifest generation reads the tags; no extension
-override is needed.
+Use inline `@min` and `@max` JSDoc tags for fixed-domain numeric props. Manifest
+generation reads the tags automatically.
 
 ```ts
 export type RatingProps = {
@@ -64,21 +63,17 @@ export type RatingProps = {
 };
 ```
 
-Use fixed bounds for ratings, percentages, playback speed, columns, and similar
-domains. Omit them for arbitrary counts, free-form prices, or an active index
-whose upper bound depends on the current collection.
+Use fixed bounds for ratings, percentages, playback speed, columns, etc. Omit
+for open-ended values or indices tied to a dynamic collection.
 
 ## Named Parts and `elementProps`
 
-Treat an independently editable inner element as a named part, then apply one
-consistent wiring rule:
+Treat an independently editable inner element as a named part. Wiring rules:
 
-- The elected root receives top-level `id`, `className`, `direction`, and `a11y`;
-  it has no `elementProps` entry.
-- Every named inner part has an `elementProps` entry, even when `className` is
-  the only injected field it currently needs.
-- Structural or decorative non-parts have no `elementProps` entry and use only a
-  CSS Module class.
+- Root receives top-level `id`, `className`, `direction`, `a11y` — no
+  `elementProps` entry.
+- Every named inner part has an `elementProps` entry (even if only `className`
+  is needed); structural/decorative non-parts use only a CSS Module class.
 
 On a raw HTML element, spread the entry and explicitly merge its injected
 `className`. Keep the entry key short while prefixing the global class with the
@@ -108,79 +103,62 @@ Do not merge the same class at both the call site and the sub-component root.
 
 ## Content and Data
 
-### Derived Values
-
-Compute a value internally when a small pure expression can derive it from
-props or state. For example, expose `price` and `quantity`; compute `subtotal`.
-Use numeric types when arithmetic is required.
+Compute derived values internally when a small pure expression can derive them
+from props or state (e.g. expose `price` and `quantity`; compute `subtotal`; use
+numeric types when arithmetic is required).
 
 ### Data-Driven Components
 
-Export named content props rather than `children` for leaf components:
-
-- text: `label`, `title`, `placeholder`
-- media: `image`, `video`, `icon`
-- links: `link`, `href`
-- collections: `items`, `options`, `menuItems`
-
-Internal sub-components may still use `children` for composition.
+Export named content props rather than `children` for leaf components — text
+(`label`, `title`, `placeholder`), media (`image`, `video`, `icon`), links
+(`link`, `href`), collections (`items`, `options`, `menuItems`). Internal
+sub-components may still use `children` for composition.
 
 ### Container Components
 
-Use `React.ReactNode` only when the specification defines a container or slot
-that accepts arbitrary nested components. Put `dir="ltr"` on the element that
-renders each `ReactNode` value so nested content does not inherit the component's
-direction.
+Use `React.ReactNode` only for containers or slots accepting arbitrary nested
+components. Put `dir="ltr"` on elements rendering `ReactNode` so nested content
+does not inherit the component's direction.
 
 ### Array Props
 
-Array elements must be objects with named keys. This provides stable identity,
-semantic field names, and room for non-breaking extension.
+Array elements must be objects with named keys for semantics and extensibility.
 
 ```ts
 type GalleryProps = {
-  images: Array<{ id: string; image: Image; caption?: string }>;
-  tags: Array<{ id: string; label: string }>;
+  images: Array<{ image: Image; caption?: string }>;
+  tags: Array<{ label: string }>;
 };
 ```
 
-Do not export arrays of primitives, leaf Wix data types, or nested arrays:
-
-```ts
-// Avoid:
-// Array<string>
-// Array<Image>
-// Array<Array<Item>>
-// Array<{ items: Array<Image> }>
-```
+Do not export `Array<string>`, `Array<Image>`, `Array<Array<T>>`, or nested
+arrays inside items.
 
-The parent owns the array. Item sub-components receive one item rather than
-redeclaring the collection. Use a stable item identifier as the React key; do
-not synthesize identity from the array index when stable identity is available.
+The parent owns the array. Item sub-components receive one item, not the
+collection. Do not add an `id` field for React keys—use the item's semantic
+named fields instead. Prefer: (1) a stable unique field (`value`, `uri`, `label`, …), (2)
+else slug a user-facing string (`name`, `label`), (3) else the array index.
 
-### Active-Item Components
+## Active-Item Components
 
-Apply this contract when an array-driven UI shows one item body at a time, such
-as tabs, slides, or steps. Skip it for always-visible lists, multi-select UIs,
-and multi-expand accordions.
+Apply this contract when an array-driven UI shows one item body at a time (tabs,
+slides, steps). Skip for always-visible lists, multi-select, or multi-expand.
 
-- Give every item a `name: string`; Studio uses `name` for hat-selector labels.
-- Pair the array prop with `ActiveItemIndex<'arrayPropName'>` from
-  `@wix/react-component-utils`. The type argument must exactly match the array
-  prop name, and `defaultProps` must initialize the index to `0`.
-- Render every body with `.map()`. Mark the active body with a prefixed
-  `--active` state class, hide inactive bodies with functional CSS visibility,
-  and apply `aria-hidden` and `inert` to inactive content.
-- Provide keyboard navigation between triggers and the matching ARIA pattern.
+- Every item needs `name: string` (used for hat-selector labels).
+- **Import and use `ActiveItemIndex<'arrayPropName'>`** from
+  `@wix/react-component-utils`. The type argument must match the array prop name
+  exactly, and `defaultProps` must set the index to `0`.
+- Render all bodies with `.map()`. Active body gets --active; inactive bodies get functional CSS visibility, aria-hidden, and inert.
+- Provide keyboard navigation and the matching ARIA pattern.
 
 ```ts
 import type { A11y, Direction } from '@wix/editor-react-types';
 import type { ActiveItemIndex } from '@wix/react-component-utils';
 
-export type Step = { id: string; name: string; body: string };
+export type Step = { name: string; body: string };
 
 export type StepsProps = {
-  id?: string;
+  id: string;
   className?: string;
   direction?: Direction;
   a11y?: A11y;
@@ -189,30 +167,26 @@ export type StepsProps = {
 };
 
 export const defaultProps = {
-  steps: [{ id: 'first', name: 'Step 1', body: 'First step' }],
+  steps: [{ name: 'Step 1', body: 'First step' }],
   activeItem: 0,
 } satisfies Omit<StepsProps, 'id' | 'className'>;
 ```
 
 ### Wix Data Types
 
-Use types such as `Image`, `Link`, `Video`, `Audio`, `VectorArt`, and `RichText`
-from `@wix/editor-react-types`. Inspect
-`node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts` when you
-need the supported schema types.
+Use `Image`, `Link`, `Video`, `Audio`, `VectorArt`, `RichText` from
+`@wix/editor-react-types`. See `node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts` for the full list.
 
 ## Defaults and Resources
 
 Export `defaultProps` from `<component-name>.props.ts`. Both `component.tsx` and
-the extension consume this object; do not duplicate fallback values in JSX.
+the extension consume this object; never duplicate fallbacks in JSX.
 
-Rendered media and runtime data must come from Wix-hosted services, local
-bundled assets, or values supplied through props. Do not silently introduce an
-external host or third-party runtime dependency.
+All rendered media must come from Wix-hosted services, local assets, or props.
+No external hosts or third-party runtime dependencies.
 
-For an `Image` default, populate only `uri`, `url`, and `alt`. Let the editor
-populate dimensions and focal-point metadata after the site owner chooses an
-image.
+For `Image` defaults, populate only `uri`, `url`, and `alt`; the editor fills
+dimensions and focal-point metadata.
 
 ```ts
 export const defaultProps = {
@@ -224,9 +198,8 @@ export const defaultProps = {
 } as const satisfies Omit<ExampleComponentProps, 'id' | 'className'>;
 ```
 
-Use distinct Wix-hosted defaults for multiple image slots. Keep fallback data in
-`defaultProps` so rendering reads the resolved prop instead of hardcoding a
-second fallback in JSX.
+Use distinct Wix-hosted defaults per image slot; keep all fallback data in
+`defaultProps` so rendering never hardcodes a second fallback in JSX.
 
 Use this pool in order, cycling only when more than five defaults are needed:
 
@@ -238,14 +211,12 @@ Use this pool in order, cycling only when more than five defaults are needed:
 | 4 | `11062b_45e67783d39c4963ab9e4fc418173233~mv2.jpg` | Abstract pink waves |
 | 5 | `11062b_4c11f014b0d04948b2e6f554076bc40a~mv2.jpg` | Coastal village aerial |
 
-For one image, use entry 1. For multiple slots, use a different entry for each
-slot so the defaults are visually distinct.
+For one image use entry 1; for multiple slots use a different entry each.
 
 ## Internal File Splitting
 
-Split a logical, independently understandable unit when doing so makes the main
-component easier to read or test. Keep internal files within the scaffolded
-component folder and use `.module.css`, matching the package convention.
+Split independently understandable units when it makes the main component easier
+to read or test. Keep internal files in the component folder using `.module.css`.
 
 ```text
 component-name/
@@ -264,12 +235,11 @@ Do not extract tiny fragments merely to satisfy a line-count threshold.
 
 ## Checklist
 
-- [ ] Identity, direction, and accessibility contracts are present.
-- [ ] Props contain authored data or stable behavior; derived values stay internal.
-- [ ] New or changed fixed-domain numeric props use `@min` and `@max`.
-- [ ] Every named inner part has `elementProps` wiring and merged classes.
-- [ ] Leaf components avoid exported `children`.
-- [ ] Array elements are named objects with stable identity.
+- [ ] Identity, direction, a11y, and SDK callbacks follow the public props shape.
+- [ ] Props hold authored data/behavior; derived values stay internal.
+- [ ] Fixed-domain numeric props use `@min`/`@max` JSDoc tags.
+- [ ] Named inner parts have `elementProps` wiring; leaf components avoid exported `children`.
 - [ ] One-body-visible arrays use the active-item contract and render all bodies.
-- [ ] Defaults have one source of truth in the props file.
+- [ ] Array elements are objects with semantic named fields. No separate `id` field added to item types; React keys use item fields (stable unique → slug → index), not a typed `id`.
+- [ ] Defaults live only in the props file (no JSX fallbacks).
 - [ ] Resources are Wix-hosted, prop-supplied, or locally bundled.

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

@@ -9,14 +9,30 @@ The Wix CLI scaffold generates `component.preview.tsx` and wires its URL into
 the extension's editor resource. It includes `withDefaults`,
 `withFallbackPlaceholder`, required-data fields, and the root class name.
 
-Keep the wrapper structure and synchronize its values:
+Keep the wrapper structure and synchronize its values. The renderer detects
+preview defaults only when `withDefaults` wraps the result of
+`withFallbackPlaceholder`. The calls may be nested directly:
+
+```tsx
+export default withDefaults(
+  withFallbackPlaceholder(ComponentPreview, {
+    requiredDataFields: ['animationUrl'],
+    rootClassName: 'component-root',
+  }),
+  defaultProps,
+);
+```
 
 - Wrap the preview adapter when one exists; otherwise wrap `Component`.
 - In `requiredDataFields`, normally use only the one prop crucial to meaningful
   rendering, such as `animationUrl`. Use more only when each is essential.
 - Set `rootClassName` to the elected root's exact global class, not `styles.root`.
 
-Never remove `withFallbackPlaceholder`.
+Never remove either wrapper, export `withFallbackPlaceholder(...)` directly, or
+invert their order. Preserve the equivalent of
+`withDefaults(withFallbackPlaceholder(...), defaultProps)` even when editing
+the preview component or fallback options. Assigning either wrapped component
+to a variable is valid as long as that outer-to-inner order stays intact.
 
 ## Detect Editor Design Mode
 
@@ -40,12 +56,15 @@ timers, or network activity while a site owner is designing.
 For autoplaying components, force autoplay off in editor design mode and keep
 the live/preview prop values unchanged.
 
-Export the adapter through `withFallbackPlaceholder` and synchronize its data
-field and root class.
+Pass the adapter to `withFallbackPlaceholder`, then pass that wrapped component
+to `withDefaults`. This may be written inline as shown above or through component
+variables. Synchronize the data field and root class either way.
 
 ## Checklist
 
 - [ ] Generated wrappers target the preview adapter when one exists.
+- [ ] The default export resolves to `withDefaults` outside
+      `withFallbackPlaceholder`, whether inline or through component variables.
 - [ ] Normally one crucial data field and the exact root global class are set.
 - [ ] The extension still loads the preview URL as its editor resource.
 - [ ] `useIsEditMode()` is called inside a component.