@wix/agent-skills 1.31.2 → 1.32.0

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

@@ -3,7 +3,7 @@
 Use this reference when a named part changes appearance through interaction or
 a selectable value. A design state styles an element differently for an
 eligible interaction (`hover`, `focus`, `disabled`, `invalid`) or per a
-selectable value in its data (`selected`, `active`, `open`, …). Author states
+selectable value in its data (`selected`, `active`, `checked`, …). Author states
 in the component's `.tsx` and `.module.css`.
 
 ## Contents
@@ -24,9 +24,9 @@ in the component's `.tsx` and `.module.css`.
 | Input field — `select`/`textarea`; `input` except `hidden`/`button`/`submit`/`reset`/`image`; or an input-widget `role` (`checkbox`/`radio`/`switch`/`slider`/`spinbutton`/`textbox`/`searchbox`/`combobox`/`listbox`) | `focus` |
 | Other interactive element whose editable focus appearance the user explicitly requests | `focus` |
 | Disableable — `button`/`input`/`select`/`textarea`/`fieldset` or a disableable role | `disabled` (+ `invalid` for `input`/`select`/`textarea`) |
-| Has a selectable/variant value in its data — `selected`/`active`/`current`/`open`/`expanded`/`checked`/`featured` | that custom state |
-| Whole component opens/collapses (expandable panel, disclosure, dropdown, drawer), even when a click toggles it | root `isOpen` prop state — see §6 |
-| None of the above | no states — resting style only |
+| Has a selectable/variant value in its data — `selected`/`active`/`current`/`checked`/`featured` | that custom state |
+| Whole component opens/collapses or reveals content (expandable panel, disclosure, dropdown, drawer, popup, tooltip) on click, hover or focus | root `isOpen` state, no part `open` state (§6) |
+| None of the above, incl. a non-interactive root or part | no states, and no `:hover`/`:active`/`:focus` rules, even decorative; resting style only |
 
 An explicit `role` overrides the tag's implicit semantics: `<input role="button">`
 is a non-input control, while `<div role="checkbox">` is an input field.
@@ -37,8 +37,7 @@ unless the user explicitly requests editable focus styling. A control that
 restyles its own outline, background, or border must still carry a standalone
 `:focus-visible` rule as its keyboard affordance.
 
-A custom state may also be driven by a root-level boolean prop (e.g.
-`isFeatured`) instead of by markup or item data — see §5. For an active-item
+A root-level boolean prop can also drive a custom state (§5). For an active-item
 component, drive each item's `--active` class by comparing its index with the
 active-index prop rather than storing a per-item boolean.
 
@@ -47,7 +46,7 @@ active-index prop rather than storing a per-item boolean.
 Flat: the element's own global class + `--<state>`. Because inner-part
 global classes are prefixed with the component name, the state class is prefixed too —
 e.g. `pricing-card-cta--hover`, `pricing-card-plan-row--selected`. Never bare
-(`cta--hover` would collide with other components on the page) and never
+(`cta--hover` collides with other components) and never
 nested (`card__row--selected`).
 
 ## 3. Author CSS
@@ -56,7 +55,7 @@ Put the resting value in the bare class; put only the state override in the
 state selector. When both set the same property, write the state selector
 **before** the bare class. Manifest generation can otherwise record the state
 value as the part's resting `defaultValue`, even though runtime CSS renders
-correctly. The state selector still wins at runtime through its specificity.
+correctly.
 
 - **Native design state** — pair the pseudo-class with the `:global` modifier.
   Every exposed native state needs both selectors in the same rule; do not
@@ -101,34 +100,34 @@ The local static accessibility scan cannot measure rendered color contrast.
 - **Native** — render the correct interactive element (`<button>`, an
   interactive `role`, or a handler). No custom state class is needed, but the
   element must still satisfy the accessibility contract for its semantics.
-- **Custom** — toggle the global state class from the element's data. Every
-  state class toggled in TSX needs a matching `:global()` rule in §3; without
-  one the manifest generator silently drops the state.
+- **Custom** — toggle the global state class from the element's data, except
+  for open/collapsed content (§6). Every state class toggled in TSX needs a
+  matching `:global()` rule in §3; without one the manifest generator silently
+  drops the state.
 - **Inner elements** — every named inner element gets an `elementProps` entry;
   spread it so editor-driven states reach it. On a raw HTML element also merge
   `elementProps?.<key>.className` inline; on a skill-built sub-component the
-  spread alone suffices (it merges `className` itself). The `elementProps` key
-  stays the **short** part name (`cta`) even though the element's global class
-  is prefixed (`pricing-card-cta`) — don't rename the key to match the class.
+  spread alone suffices (it merges `className` itself). The key is the global
+  class in camelCase (`COMPONENT-CONTRACT.md`).
 
 Wire native and custom states as follows:
 
 ```tsx
 <button
   type="button"
-  {...elementProps?.cta}
-  className={classNames('pricing-card-cta', styles.cta, elementProps?.cta?.className)}
+  {...elementProps?.pricingCardCta}
+  className={classNames('pricing-card-cta', styles.cta, elementProps?.pricingCardCta?.className)}
 >
   {label}
 </button>
 
 <li
-  {...elementProps?.planRow}
+  {...elementProps?.pricingCardPlanRow}
   className={classNames(
     'pricing-card-plan-row',
     styles.planRow,
     row.selected && 'pricing-card-plan-row--selected',
-    elementProps?.planRow?.className,
+    elementProps?.pricingCardPlanRow?.className,
   )}
 >
   {row.label}
@@ -143,10 +142,9 @@ A **prop-triggered** state is a custom state switched by a single boolean
 whole component's appearance — e.g. `isLoading`, `isFeatured`.
 
 Mark the prop with the `ElementState<boolean>` type from
-`@wix/react-component-utils`. It is an identity alias — the prop still behaves
-as a plain `boolean` at runtime and stays a normal boolean in the component's
-data — but the manifest generator detects the marker and emits a custom state
-on the **root element**.
+`@wix/react-component-utils`. It is an identity alias (a plain `boolean` at
+runtime and in data); the manifest generator detects the marker and emits a
+custom state on the **root element**.
 
 ```tsx
 import type { ElementState } from '@wix/react-component-utils';
@@ -178,39 +176,41 @@ Rules:
 ```
 
 Prefer a native state (interactive markup) or a class trigger (per-item data
-such as `row.selected`) whenever one fits — those are the common cases and work
-at any depth. Reach for a prop trigger only for a root-level boolean switch
-or an open/collapsed toggle (§6).
+such as `row.selected`) whenever one fits; both work at any depth. Reach for a
+prop trigger only for a root-level boolean switch.
 
 ## 6. Expose Open/Collapsed Toggles
 
-For a component that opens or collapses, expose its state to the editor even
-when a click toggles it. `useState` alone gives the manifest no state picker.
-For one-of-many item bodies, use the active-item contract instead.
+Expose the open state of a component that opens, collapses or reveals content
+on click, hover or focus. `useState` alone, or a CSS `:hover`/`:focus-within`
+reveal, gives the editor no state picker. For one-of-many item bodies, use the
+active-item contract instead.
 
 - Add `isOpen?: ElementState<boolean>` and set `isOpen: false` in
-  `defaultProps`.
-- Seed and resync internal state from the prop; clicks update internal state.
+  `defaultProps`. Keep it props-only (§5).
+- Seed and resync internal state from the prop; clicks, pointer enter/leave and
+  focus/blur update it.
 - Always render the collapsible content; hide it with CSS plus `aria-hidden`
   and `inert` when closed. Never mount it with `open && …`.
-- Style the open state with inner-part classes
-  (`<component-name>-content--open`) and matching `:global()` rules, not only
-  inline styles or refs measured during render.
-- Keep the root state props-only for the on-stage picker (§5).
+- Style the open look with a module class (`open && styles.contentOpen`), not
+  only inline styles or render-time refs.
+- Never toggle a `:global()` class for it (`--open`, `--visible`, …) on the
+  root or any part: each adds an "Open" design-panel state beside the on-stage
+  picker.
 
 ```tsx
 const [open, setOpen] = React.useState(Boolean(isOpen));
 React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
 
 <div
-  {...elementProps?.content}
+  {...elementProps?.infoPanelContent}
   aria-hidden={!open}
   {...(!open && { inert: '' })}
   className={classNames(
     'info-panel-content',
     styles.content,
-    open && 'info-panel-content--open',
-    elementProps?.content?.className,
+    open && styles.contentOpen,
+    elementProps?.infoPanelContent?.className,
   )}
 >
   <p>{text}</p>
@@ -219,7 +219,7 @@ React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
 
 ```css
 .content { display: none; }
-.content:global(.info-panel-content--open) { display: block; }
+.contentOpen { display: block; }
 ```
 
 ## Checklist
@@ -233,4 +233,5 @@ React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
 - [ ] Every state class toggled in TSX has a matching `:global()` CSS rule.
 - [ ] `ElementState<boolean>` is used only for a component-level root state.
 - [ ] An open/collapsed component exposes a props-only `isOpen` root state,
-      syncs internal state from it, and always renders its content.
+      syncs internal state from it, always renders its content, and adds no
+      `--open` class anywhere.

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

@@ -24,13 +24,14 @@ would plausibly control independently in the editor. It receives:
 
 - one prefixed global class: `'<component-name>-<part-name>'`
 - one CSS Module class
-- one matching `elementProps` entry, spread onto the element. Declare `a11y` on
-  the entry only when the part reads `ariaLabel`, and destructure it out before
-  spreading (see `ACCESSIBILITY.md`)
+- one matching `elementProps` entry, keyed by the camelCase of its global class
+  and spread onto the element. Declare `a11y` on the entry only when the part
+  reads `ariaLabel`, and destructure it out before spreading (see
+  `ACCESSIBILITY.md`)
 
 Apply this filter to every candidate:
 
-- A state or variant (`selected`, `active`, `open`, `disabled`) is not a part.
+- A state or variant (`selected`, `active`, `checked`, `disabled`) is not a part.
   Implement it as a prefixed design-state modifier on the affected part.
 - A hidden and shown version of the same element is one part, not two.
 - A grouping or layout-only wrapper is not a part. A wrapper that isn't
@@ -49,9 +50,10 @@ The manifest generator can silently omit a named part behind conditional JSX.
 Keep an editor-controlled part mounted in the render it inspects. Hide it with
 CSS driven by a data attribute, or disable it when it should remain visible.
 After generating the manifest, confirm that its `elements` include every
-intended named part.
+intended named part and that each `elementProps.<key>` read in code equals the
+camelCase of that part's global class.
 
-## Plausibility Check
+## Sanity Check
 
 For each candidate, ask:
 

package/skills/wix-app/references/editor-react-component/PROPS-VS-CSS.md

@@ -31,11 +31,11 @@ Use this pattern:
 
 ```tsx
 <div
-  {...elementProps?.progressBar}
+  {...elementProps?.audioPlayerProgressBar}
   className={classNames(
     'audio-player-progress-bar',
     styles.progressBar,
-    elementProps?.progressBar?.className,
+    elementProps?.audioPlayerProgressBar?.className,
   )}
 >
   {/* progress UI */}
@@ -51,6 +51,26 @@ the interaction contract. `pauseButtonVisibility` in an autoplaying component
 is the canonical exception: the editor preview must be able to force the
 play/pause control visible.
 
+## Lists of Groups
+
+When each item of a list holds its own list, the Manage panel can't edit the inner list. Use fixed
+groups instead and map them internally:
+
+- Give each group flat top-level fields named after the group, so Manage
+  Items shows "Starters Dishes", not "Dishes 1".
+- For a requested range ("2 to 5 sections"), create the maximum and add a
+  count prop that shows the first N.
+- Group order is fixed. If the user asks to reorder groups, don't add an
+  order, slot, key or label field or a separate array to emulate it; say in
+  your reply that groups can't be reordered.
+
+```ts
+// startersTitle: string; startersDishes: Array<Dish>
+// /** @min 2 @max 5 */ sectionCount: number
+// Not: sections: Array<{ dishes: Array<Dish> }>, starters: Section,
+// or sections: Array<{ slot: number }> with dishes1…dishes5
+```
+
 ## Examples
 
 ### Content and Behavior Props

package/skills/wix-app/scripts/scan-a11y-eslint.cjs

@@ -61,19 +61,23 @@ const SDK_HANDLER_PROPS = {
   onDoubleClick: 'onDblClick',
   onMouseEnter: 'onMouseIn',
   onMouseLeave: 'onMouseOut',
+  onFocus: 'onFocus',
+  onBlur: 'onBlur',
 };
 const isSdkRoot = (tag) => /\bid=\{\s*(?:props\.)?id\s*\}/.test(tag);
 
-/** Every handler on the tag forwards its SDK prop, `onClick={onClick}` or `onMouseEnter={props.onMouseIn}`; anything else makes the root a control. */
+const getHandlerAttributes = (tag) => [...tag.matchAll(/\b(on[A-Z]\w*)=\{([^}]*)\}/g)];
+
+/** `onClick={onClick}` or `onMouseEnter={props.onMouseIn}`. */
+function isSdkForward(name, value) {
+  const sdkProp = SDK_HANDLER_PROPS[name];
+  return Boolean(sdkProp) && value.trim().replace(/^props\./, '') === sdkProp;
+}
+
+/** Every handler on the tag forwards its SDK prop; anything else makes the root a control. */
 function forwardsOnlySdkHandlers(tag) {
-  const handlers = [...tag.matchAll(/\b(on[A-Z]\w*)=\{([^}]*)\}/g)];
-  return (
-    handlers.length > 0 &&
-    handlers.every(([, name, value]) => {
-      const sdkProp = SDK_HANDLER_PROPS[name];
-      return Boolean(sdkProp) && value.trim().replace(/^props\./, '') === sdkProp;
-    })
-  );
+  const handlers = getHandlerAttributes(tag);
+  return handlers.length > 0 && handlers.every(([, name, value]) => isSdkForward(name, value));
 }
 
 const PASSIVE_AUTOPLAY_HANDLERS = new Set([
@@ -85,11 +89,26 @@ const PASSIVE_AUTOPLAY_HANDLERS = new Set([
   'onBlurCapture',
 ]);
 
-/** Carousel roots observe hover/focus to pause autoplay; these handlers do not activate the region. */
+/**
+ * Carousel roots observe hover and focus to pause autoplay; these handlers do not activate
+ * the region. A root needs both, so hover-only roots stay flagged. SDK forwards may sit
+ * beside them; any other handler makes the root a control.
+ */
 function pausesAutoplayOnly(tag) {
-  if (!isSdkRoot(tag) || !tag.includes('data-pause-button-visibility=')) return false;
-  const handlers = [...tag.matchAll(/\b(on[A-Z]\w*)=\{[^}]*\}/g)];
-  return handlers.length > 0 && handlers.every(([, name]) => PASSIVE_AUTOPLAY_HANDLERS.has(name));
+  if (!isSdkRoot(tag)) return false;
+  const handlers = getHandlerAttributes(tag);
+  // `onMouseEnter={onMouseIn}`, `onMouseEnter={onMouseEnter}` or `onFocus={onFocus}` forwards a prop; it is not a pause observer.
+  const isPauseObserver = (name, value) =>
+    PASSIVE_AUTOPLAY_HANDLERS.has(name) &&
+    !isSdkForward(name, value) &&
+    value.trim().replace(/^props\./, '') !== name;
+  const hasPauseObserver = (pattern) =>
+    handlers.some(([, name, value]) => pattern.test(name) && isPauseObserver(name, value));
+  return (
+    hasPauseObserver(/^onMouse/) &&
+    hasPauseObserver(/^on(?:Focus|Blur)/) &&
+    handlers.every(([, name, value]) => isPauseObserver(name, value) || isSdkForward(name, value))
+  );
 }
 
 /** Roles whose native element cannot express a styled component. */
@@ -112,9 +131,13 @@ function roleHasNoNativeTag(tag) {
  */
 const EXEMPTIONS = [
   {
-    // ANIMATED-COMPONENTS.md requires the noninteractive carousel root to
-    // observe hover and focus so autoplay stops while a visitor is using it.
-    rules: new Set(['jsx-a11y/no-noninteractive-element-interactions']),
+    // ANIMATED-COMPONENTS.md requires the carousel root to observe hover and
+    // focus so autoplay pauses while a visitor is using it.
+    rules: new Set([
+      'jsx-a11y/click-events-have-key-events',
+      'jsx-a11y/no-noninteractive-element-interactions',
+      'jsx-a11y/no-static-element-interactions',
+    ]),
     tag: pausesAutoplayOnly,
   },
   {

package/skills/wix-app/scripts/sdk-curated.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "about": "Choices no SDK index can make. sdk-lookup.cjs prints a rule when one of its entities matches. `choice: site` means the namespace depends on the site, not on the install.",
+  "rules": [
+    {
+      "entities": ["product", "products", "catalog"],
+      "namespaces": ["products", "productsV3"],
+      "choice": "site",
+      "note": "Call catalogVersioning.getCatalogVersion() first: V3 sites use productsV3, V1 sites use products. Support both paths, and request both scope sets plus SCOPE.STORES.CATALOG_READ_LIMITED. To search by name, V3 has productsV3.searchProducts() (queryProducts cannot filter on name); V1 has no search method, and its builder takes name only with startsWith.",
+      "source": "SKILL.md (Stores), references/STORES_VERSIONING.md, references/stores/QUERY.md"
+    },
+    {
+      "entities": ["inventory"],
+      "namespaces": ["inventory", "inventoryItemsV3"],
+      "choice": "site",
+      "note": "Call catalogVersioning.getCatalogVersion() first: V3 sites use inventoryItemsV3, V1 sites use inventory. Request both scope sets.",
+      "source": "references/STORES_VERSIONING.md"
+    },
+    {
+      "entities": ["refund", "refunds"],
+      "namespaces": ["orders", "orderTransactions", "refunds"],
+      "choice": { "prefer": "orders", "intents": ["search", "read"] },
+      "note": "Refunded orders: orders.searchOrders with a paymentStatus filter, then orderTransactions.listTransactionsForMultipleOrders(ids) once for the visible page. Refund events are the exception: they live in @wix/payments (namespace refunds), not in @wix/ecom.",
+      "source": "references/dashboard-page/DATA_SOURCES.md, references/backend-event/COMMON-EVENTS.md"
+    },
+    {
+      "entities": ["location", "locations"],
+      "namespaces": ["locations"],
+      "note": "queryLocations is admin-only although its scope is SCOPE.DC-MULTILOCATION.READ-LOCATIONS: route it to a backend endpoint and elevate it there.",
+      "source": "moved from SKILL.md (Identity and Elevation Requirement), which links here"
+    },
+    {
+      "entities": ["member", "members"],
+      "namespaces": ["members"],
+      "note": "getMember and queryMembers withhold PRIVATE members from visitor and member callers: never elevate them to fill a sparse result.",
+      "source": "SKILL.md (Identity and Elevation Requirement)"
+    },
+    {
+      "entities": ["cart", "currentcart"],
+      "namespaces": ["currentCartV2", "cartV2"],
+      "note": "currentCartV2.addLineItemsToCurrentCart is visitor-callable although its scope is SCOPE.ECOM.MANAGE-ADMIN. Never elevate it.",
+      "source": "moved from SKILL.md (Identity and Elevation Requirement), which links here"
+    }
+  ]
+}