@wix/agent-skills 1.20.1 → 1.21.0

package/skills/wix-app/references/SITE_PLUGIN.md

@@ -5,7 +5,7 @@ Site plugins are custom elements that integrate into predefined **slots** within
 
 ## Scaffold
 
-Use `wix generate --params` with `extensionType: SITE_PLUGIN`. `slotId` is `<componentId>:<slotId>` — the colon-joined widget component ID and slot ID. Run `wix schema generate --type SITE_PLUGIN` to list the available `slotId` values (each `anyOf` entry has the slot's human-readable title). The CLI generates the folder, the plugin `.tsx`, the settings panel `.tsx`, the builder file, the UUID, the logo SVG, and the `src/extensions.ts` registration.
+Use `wix generate --params` with `extensionType: SITE_PLUGIN`. `slotId` is `<componentId>:<slotId>` — the colon-joined widget component ID and slot ID. Run `wix schema generate --type SITE_PLUGIN` to list the available `slotId` values. The CLI generates the folder, the plugin `.tsx`, the settings panel `.tsx`, the builder file, the UUID, the logo SVG, and the `src/extensions.ts` registration.
 
 ## Architecture
 
@@ -43,49 +43,21 @@ Site plugins use native `HTMLElement` custom elements:
 ```typescript
 // my-site-plugin.tsx
 class MyElement extends HTMLElement {
-  static get observedAttributes() {
-    return ['display-name'];
-  }
-
-  constructor() {
-    super();
-  }
-
-  connectedCallback() {
-    this.render();
-  }
-
-  attributeChangedCallback() {
-    this.render();
-  }
+  static get observedAttributes() { return ['display-name']; }
+  connectedCallback() { this.render(); }
+  attributeChangedCallback() { this.render(); }
 
   render() {
     const displayName = this.getAttribute('display-name') || "Your Plugin's Title";
-
-    this.innerHTML = `
-      <div style="font-size: 16px; padding: 16px; border: 1px solid #ccc; border-radius: 8px; margin: 16px;">
-        <h2>${displayName}</h2>
-        <hr />
-        <p>
-          This is a Site Plugin generated by Wix CLI.<br />
-          Edit your element's code to change this text.
-        </p>
-      </div>
-    `;
+    this.innerHTML = `<div style="padding: 16px;"><h2>${displayName}</h2></div>`;
   }
 }
 
 export default MyElement;
 ```
 
-**Key Points:**
+**Key Points** (beyond the structure already listed under [Architecture](#architecture)):
 
-- Extend `HTMLElement` class directly
-- Define `observedAttributes` static getter to list reactive attributes
-- Attributes use **kebab-case** (e.g., `display-name`, `bg-color`)
-- Implement `connectedCallback()` for initial render
-- Implement `attributeChangedCallback()` to re-render when attributes change
-- Use inline styles via template strings
 - Use `this.getAttribute('attribute-name')` to read attribute values
 - Wix handles `define()` for you — do NOT call `customElements.define()` in your code
 
@@ -93,30 +65,22 @@ export default MyElement;
 
 ```typescript
 // my-site-plugin.panel.tsx
-import React, { type FC, useState, useEffect, useCallback } from 'react';
+import { type FC, useState, useEffect, useCallback, type ChangeEvent } from 'react';
 import { widget } from '@wix/editor';
-import {
-  SidePanel,
-  WixDesignSystemProvider,
-  Input,
-  FormField,
-} from '@wix/design-system';
+import { SidePanel, WixDesignSystemProvider, Input, FormField } from '@wix/design-system';
 import '@wix/design-system/styles.global.css';
 
 const Panel: FC = () => {
-  const [displayName, setDisplayName] = useState<string>('');
+  const [displayName, setDisplayName] = useState('');
 
   useEffect(() => {
-    widget.getProp('display-name')
-      .then(displayName => setDisplayName(displayName || "Your Plugin's Title"))
-      .catch(error => console.error('Failed to fetch display-name:', error));
-  }, [setDisplayName]);
+    widget.getProp('display-name').then(v => setDisplayName(v || "Your Plugin's Title"));
+  }, []);
 
-  const handleDisplayNameChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
-    const newDisplayName = event.target.value;
-    setDisplayName(newDisplayName);
-    widget.setProp('display-name', newDisplayName);
-  }, [setDisplayName]);
+  const handleDisplayNameChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
+    setDisplayName(e.target.value);
+    widget.setProp('display-name', e.target.value);
+  }, []);
 
   return (
     <WixDesignSystemProvider>
@@ -124,12 +88,7 @@ const Panel: FC = () => {
         <SidePanel.Content noPadding stretchVertically>
           <SidePanel.Field>
             <FormField label="Display Name">
-              <Input
-                type="text"
-                value={displayName}
-                onChange={handleDisplayNameChange}
-                aria-label="Display Name"
-              />
+              <Input type="text" value={displayName} onChange={handleDisplayNameChange} aria-label="Display Name" />
             </FormField>
           </SidePanel.Field>
         </SidePanel.Content>
@@ -141,13 +100,9 @@ const Panel: FC = () => {
 export default Panel;
 ```
 
-**Key Points:**
+**Key Points** (beyond the structure already listed under [Architecture](#architecture)):
 
-- Prop names in `widget.getProp()` and `widget.setProp()` use **kebab-case** (e.g., `"display-name"`)
-- Always update both local state AND widget prop in onChange handlers
-- Widget properties are bound to custom element attributes — changes automatically update the corresponding attribute
-- Wrap content in `WixDesignSystemProvider > SidePanel > SidePanel.Content`
-- Use WDS components from `@wix/design-system`
+- Always update both local state AND widget prop in the same onChange handler
 - Import `@wix/design-system/styles.global.css` for styles
 - Include `aria-label` for accessibility
 
@@ -160,28 +115,17 @@ Site plugin settings panels can use `inputs.selectColor()` and `inputs.selectFon
 Opens the Wix color picker with theme colors, gradients, and more — **NOT** a basic HTML `<input type="color">`.
 
 ```typescript
-import React, { type FC } from 'react';
+import { type FC } from 'react';
 import { inputs } from '@wix/editor';
 import { FormField, Box, FillPreview, SidePanel } from '@wix/design-system';
 
-interface ColorPickerFieldProps {
-  label: string;
-  value: string;
-  onChange: (value: string) => void;
-}
+interface ColorPickerFieldProps { label: string; value: string; onChange: (value: string) => void; }
 
-export const ColorPickerField: FC<ColorPickerFieldProps> = ({
-  label,
-  value,
-  onChange,
-}) => (
+export const ColorPickerField: FC<ColorPickerFieldProps> = ({ label, value, onChange }) => (
   <SidePanel.Field>
     <FormField label={label}>
       <Box width="30px" height="30px">
-        <FillPreview
-          fill={value}
-          onClick={() => inputs.selectColor(value, { onChange: (val) => { if (val) onChange(val); } })}
-        />
+        <FillPreview fill={value} onClick={() => inputs.selectColor(value, { onChange: (val) => val && onChange(val) })} />
       </Box>
     </FormField>
   </SidePanel.Field>
@@ -190,78 +134,21 @@ export const ColorPickerField: FC<ColorPickerFieldProps> = ({
 
 ### FontPickerField
 
-Opens the Wix font picker with font family, size, bold, italic, and other typography features.
+Opens the Wix font picker (family, size, bold, italic). Same shape as `ColorPickerField` above, with a `Button`+`Text` trigger instead of `FillPreview`, calling `inputs.selectFont(value, { onChange })` instead of `selectColor`. Value type: `{ font: string; textDecoration: string }`.
 
-```typescript
-import React, { type FC } from 'react';
-import { inputs } from '@wix/editor';
-import { FormField, Button, Text, SidePanel } from '@wix/design-system';
-
-interface FontValue {
-  font: string;
-  textDecoration: string;
-}
-
-interface FontPickerFieldProps {
-  label: string;
-  value: FontValue;
-  onChange: (value: FontValue) => void;
-}
-
-export const FontPickerField: FC<FontPickerFieldProps> = ({
-  label,
-  value,
-  onChange,
-}) => (
-  <SidePanel.Field>
-    <FormField label={label}>
-      <Button
-        size="small"
-        priority="secondary"
-        onClick={() => inputs.selectFont(value, { onChange: (val) => onChange({ font: val.font, textDecoration: val.textDecoration || "" }) })}
-        fullWidth
-      >
-        <Text size="small" ellipsis>Change Font</Text>
-      </Button>
-    </FormField>
-  </SidePanel.Field>
-);
-```
-
-**Important:**
-- Always use `inputs.selectColor()` from `@wix/editor` with `FillPreview` — do NOT use `<Input type="color">`
-- Always use `inputs.selectFont()` from `@wix/editor` with the callback pattern `inputs.selectFont(value, { onChange })`
-- Import `inputs` from `@wix/editor` (not from `@wix/sdk`)
-
-## Attribute Naming Convention
-
-Site plugins use **kebab-case** consistently for HTML attributes:
-
-| File                              | Convention | Example                            |
-| --------------------------------- | ---------- | ---------------------------------- |
-| `<plugin>.tsx` (getAttribute)     | kebab-case | `this.getAttribute('display-name')` |
-| `<plugin>.tsx` (observedAttributes) | kebab-case | `['display-name', 'bg-color']`     |
-| `<plugin>.panel.tsx` (widget API) | kebab-case | `widget.getProp('display-name')`   |
+**Important:** always go through `inputs` from `@wix/editor` (never `<Input type="color">`, never `@wix/sdk`) with the `{ onChange }` callback pattern shown above.
 
 ## References
 
 | Topic | Reference |
 | --- | --- |
 | Complete Examples | [EXAMPLES.md](site-plugin/EXAMPLES.md) |
-| Slots (App IDs, runtime APIs, design guidelines, multiple placements) | [SLOTS.md](site-plugin/SLOTS.md) — run `wix schema generate --type SITE_PLUGIN` for the authoritative `slotId` enum |
+| Slots (App IDs, runtime APIs, design guidelines, multiple placements) | [SLOTS.md](site-plugin/SLOTS.md) |
 | WDS Components | the `wix-design-system` skill |
 
 ## Available Slots
 
-Site plugins integrate into predefined slots in Wix business solutions. Each slot is identified by:
-
-- **appDefinitionId**: The ID of the Wix app (e.g., Stores, Bookings)
-- **widgetId**: The ID of the page containing the slot
-- **slotId**: The specific slot identifier
-
-Common placement areas include product pages (Wix Stores), checkout and side cart (Wix eCommerce), booking pages (Wix Bookings), service pages, event pages, and blog post pages.
-
-For App Definition IDs, per-slot runtime APIs, design guidelines, and placement constraints, see [SLOTS.md](site-plugin/SLOTS.md). Run `wix schema generate --type SITE_PLUGIN` for the authoritative `slotId` enum.
+Site plugins integrate into predefined slots — product pages (Wix Stores), checkout and side cart (Wix eCommerce), booking pages (Wix Bookings), service pages, event pages, and blog post pages. See [SLOTS.md](site-plugin/SLOTS.md) for the App Definition IDs, per-slot runtime APIs, and design guidelines.
 
 ## Checkout Plugins
 
@@ -269,52 +156,27 @@ If you are building a plugin for the **checkout page**, it may not support autom
 
 ## Examples
 
-For complete examples with all three required files (plugin component, settings panel, extension configuration), see [EXAMPLES.md](site-plugin/EXAMPLES.md).
-
-**Example use cases:**
-
-- **Best Seller Badge** - Customizable badge on product pages with text and color settings
-- **Booking Confirmation** - Custom confirmation message for booking pages
-- **Product Reviews Summary** - Star rating and review count display
-- **Data-Driven Plugin** - Plugin with Wix Data API integration and editor environment handling
+For complete examples with all three required files (plugin component, settings panel, extension configuration) — including a product-page badge, a booking confirmation message, a review-count display, and a Wix Data-driven plugin — see [EXAMPLES.md](site-plugin/EXAMPLES.md).
 
 ## Best Practices
 
 ### Implementation Guidelines
 
-- **Use inline styles** - CSS imports are not supported in custom elements
-- **Handle editor environment** - Show placeholders when in editor mode for data-dependent plugins
-- **Do not call `define()`** - Wix handles `customElements.define()` for you automatically
-- **Validate all input** - Check required props are present
-- **Follow naming conventions** - kebab-case for all attributes and widget API
-- **Keep plugins focused** - Each plugin should do one thing well
-- **Test in multiple slots** - If supporting multiple placements, test each one
-- **Support both Stores versions** - Include placements for both old and new Wix Stores product pages for maximum compatibility
+- **Handle the editor environment** - show placeholders when in editor mode for data-dependent plugins (see [Editor Sandboxing](#editor-sandboxing) below)
+- **Support both Stores versions** - include placements for both old and new Wix Stores product pages for maximum compatibility
 
 ### Editor Sandboxing
 
-Site plugins are sandboxed when rendered in the editor. This means they're treated as if they come from a different domain, which impacts access to browser storage APIs.
-
-**Restricted APIs in the editor:**
-- `localStorage` and `sessionStorage` (Web Storage API)
-- `document.cookie` (Cookie Store API)
-- IndexedDB API
-- Cache API
+Site plugins are sandboxed when rendered in the editor — treated as if from a different domain, which blocks `localStorage`/`sessionStorage`, `document.cookie`, IndexedDB, and the Cache API.
 
-**How to handle sandboxing:**
-
-Use the `viewMode()` function from `@wix/site-window` to check the current mode before accessing restricted APIs:
+Check the mode with `viewMode()` from `@wix/site-window` before touching any of those. That package isn't part of the CLI's default scaffolded `package.json` — install it first (`npm install @wix/site-window`), or the build fails with `Rollup failed to resolve import "@wix/site-window"`:
 
 ```typescript
 import { window as wixWindow } from '@wix/site-window';
 
-const viewMode = await wixWindow.viewMode();
-
-if (viewMode === 'Site') {
+if ((await wixWindow.viewMode()) === 'Site') {
   const item = localStorage.getItem('myKey');
-} else {
-  // Mock storage or modify API usage for editor mode
-}
+} // else: mock storage or skip, in editor mode
 ```
 
 ### Using Wix SDK Modules in Site Plugins
@@ -322,33 +184,23 @@ if (viewMode === 'Site') {
 Site plugins can import and use Wix SDK modules directly — you do NOT need `createClient()`. The Wix runtime provides the client context automatically.
 
 ```typescript
-// ✅ CORRECT — Import SDK modules directly
+// ✅ CORRECT — import directly, no createClient needed
 import { items } from "@wix/data";
-import { currentCartV2 } from "@wix/ecom";
-import { products } from "@wix/stores";
 
 class MyPlugin extends HTMLElement {
   async loadData() {
-    // Call SDK methods directly — no createClient needed
     const result = await items.query("MyCollection").find();
-    const { cart } = await currentCartV2.getCurrentCart();
-    const productList = await products.queryProducts().limit(10).find();
   }
 }
 ```
 
-```typescript
-// ❌ WRONG — Do NOT use createClient in site plugins
-import { createClient } from "@wix/sdk";
-const wixClient = createClient({ modules: { items, products } });
-await wixClient.items.query(...); // Wrong — API surface differs through client
-```
+The same applies to any other Wix SDK module (`@wix/ecom`, `@wix/stores`, etc. — see the table below for three specific calls). Do **not** wrap them in `createClient({ modules: {...} })` from `@wix/sdk` — that API surface differs from the direct-import one shown above, and site plugins don't need it.
 
 ### Identity of SDK Calls in Site Plugins
 
 A plugin runs as the **site visitor or member**, never as the app — see [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) before routing any SDK call out to a backend endpoint.
 
-The three calls above are correct exactly as written, and each for a different reason:
+Each of these three calls is correct to call directly, exactly as written, and each for a different reason:
 
 | Call | Why it works directly |
 | --- | --- |
@@ -356,9 +208,3 @@ The three calls above are correct exactly as written, and each for a different r
 | `currentCartV2.getCurrentCart()` | Resolves the cart from the caller's session. Elevating it would return the app's cart, not the visitor's |
 | `products.queryProducts()` | Catalog base fields are public. `MERCHANT_DATA` and non-visible products are withheld unless the app holds `SCOPE.STORES.PRODUCT_READ_ADMIN` — don't request them from a plugin |
 
-### Performance Considerations
-
-- Keep bundle size small - plugins load on user-facing pages
-- Avoid heavy computations on initial render
-- Lazy load data when possible
-- Use efficient re-rendering patterns

package/skills/wix-app/references/app-tools/TOOLS.md

@@ -25,6 +25,7 @@ export default extensions.appTools({
   tools: [
     {
       methodName: 'get-order-status',
+      displayName: 'Get Order Status',
       description: 'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order. Use this tool when a collaborator or customer asks where their order is, whether it has shipped, when it will arrive, or needs a tracking number. Requires a valid orderId.',
       requestSchema: {
         type: 'object',
@@ -52,9 +53,10 @@ export default extensions.appTools({
 | --- | --- | --- | --- |
 | `methodName` | `string` | Yes | Unique word identifying the tool. Used to route calls in the service plugin handler. 1–30 characters. |
 | `description` | `string` | Yes | Natural-language description the AI assistant uses to decide when to invoke this tool. Write it like a prompt: state what the tool does, list the user intents or trigger phrases that should activate it, and describe what it returns. A narrow one-liner reduces relevance matching — prefer 2–4 sentences covering intent, triggers, and output. 10–1000 characters. |
+| `displayName` | `string` | No | Human-readable name for the tool, shown in AI agent UIs. 2–50 characters. The CLI's generated stub always fills this in — keep it when you replace the stub tool. |
 | `requestSchema` | `Record<string, any>` | No | JSON Schema describing the tool's request payload. The AI assistant uses this for context — it is NOT validated by Wix at call time. |
 | `responseSchema` | `Record<string, any>` | No | JSON Schema describing the tool's response payload. |
-| `activated` | `boolean` | Yes | Only tools with `activated: true` are called by the AI assistant. |
+| `activated` | `boolean` | No | Only tools with `activated: true` are called by the AI assistant. **Defaults to `false` if omitted** — there's no build-time or generate-time error for leaving it out, so a forgotten `activated` silently produces a tool the assistant will never call. Always set it explicitly. |
 
 ## Important Constraints
 

package/skills/wix-app/references/custom-element-widget/SETTINGS_PANEL.md

@@ -32,3 +32,24 @@ Wrap each picker in the standard `<SidePanel.Field><FormField label={label}>…<
 </Button>
 ```
 
+## Date & Time Fields
+
+Use WDS `DatePicker` and `TimeInput` directly (no `@wix/editor` picker dialog involved) — but their `onChange` shapes differ, verified against the installed package's own types:
+
+| Field | Value type | `onChange` signature |
+|---|---|---|
+| `DatePicker` | `Date` | `(date: Date) => void` — receives the date directly |
+| `TimeInput` | `Date \| null` | `({ date }: { date: Date \| null }) => void` — receives a **destructured object**, not the date directly |
+
+```typescript
+import { FormField, DatePicker, TimeInput } from '@wix/design-system';
+
+<FormField label="Target date">
+  <DatePicker value={targetDate} onChange={(date) => onDateChange(date)} />
+</FormField>
+
+<FormField label="Target time">
+  <TimeInput value={targetTime} onChange={({ date }) => onTimeChange(date)} />
+</FormField>
+```
+

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

@@ -141,6 +141,23 @@ dashboard.navigate(
 );
 ```
 
+## taxSettings()
+
+Ecom Extensions Dashboard Pages 'taxSettings()' destination builder for navigating to the Tax Settings dashboard page.
+
+**Request:**
+This method does not take any parameters.
+
+**Example:**
+```typescript
+import { dashboard } from "@wix/dashboard";
+import { pages } from "@wix/ecom/dashboard";
+
+dashboard.navigate(
+  pages.taxSettings(),
+);
+```
+
 ## orderRefund()
 
 Ecom Extensions Dashboard Pages 'orderRefund()' destination builder for navigating to the Order Refund dashboard page.

package/skills/wix-app/references/dashboard-plugin/SLOTS.md

@@ -66,8 +66,7 @@ Slots are UI placeholders on dashboard pages of Wix first-party business apps. E
   | Name | Type | Description |
   |------|------|-------------|
   | `staffResourceId` | String | Staff resource ID |
-  | `scheduleId` | String | Schedule ID |
-  | `timezone` | String | Time zone |
+  | `staffId` | String | Staff member ID |
 - **Multi-plugin:** Vertical, newest at top
 - **Use case:** Display staff availability analytics or performance metrics.
 
@@ -108,12 +107,12 @@ Slots are UI placeholders on dashboard pages of Wix first-party business apps. E
   | `onSuccess()` | `() => Promise<void>` | Progresses to the next modal after successful order update |
   | `onCancel()` | `() => void` | Progresses to the next modal without changes |
   | `menuOption` | Object | Data for the selected menu item |
-  | `menuOption.key` | String | `CHARGE_WITH_CREDIT_CARD`, `RECORD_ORDER_MANUAL_PAYMENT`, `CHARGE_WITH_INVOICE`, or `EXTENSION` |
+  | `menuOption.key` | String | `CHARGE_WITH_CREDIT_CARD`, `RECORD_ORDER_MANUAL_PAYMENT`, `CHARGE_WITH_INVOICE`, `CAPTURE_AUTHORIZED_PAYMENT`, `CREATE_AUTHORIZED_PAYMENT`, or `EXTENSION` |
   | `menuOption.componentId` | String | Component ID when `EXTENSION` key is triggered |
 - **Multi-plugin:** Sequential modals, each appearing before the default modal
 - **Use case:** Add items to an order such as additional services, notes, or booking fees like insurance.
 
-> **Note:** This slot also appears on the Wix eCommerce Order Page.
+> **Note:** This slot also appears on the [Wix eCommerce Order Page](#order-page--pre-collect-payment-modal).
 
 ### Booking List Page
 
@@ -145,24 +144,11 @@ Slots are UI placeholders on dashboard pages of Wix first-party business apps. E
 
 ### Order Page — Pre-Collect Payment Modal
 
-**Slot ID:** `b92f0e25-535f-4bef-b130-8e5abc85b2fe`
+**Slot ID:** `b92f0e25-535f-4bef-b130-8e5abc85b2fe` — the same slot as [Bookings Calendar Page — Pre-Collect Payment Modal](#calendar-page--pre-collect-payment-modal) above (same parameters, multi-plugin behavior, and modal mechanics).
 
 - **Dashboard path:** Sales > Orders > Order > Collect Payment
-- **Location:** Custom modal displayed before the default Collect Payment modal
-- **Parameters:**
-  | Name | Type | Description |
-  |------|------|-------------|
-  | `orderId` | String | Order ID |
-  | `onSuccess()` | `() => Promise<void>` | Progresses to the next modal after successful order update |
-  | `onCancel()` | `() => void` | Progresses to the next modal without changes |
-  | `menuOption` | Object | Data for the selected menu item |
-  | `menuOption.key` | String | `CHARGE_WITH_CREDIT_CARD`, `RECORD_ORDER_MANUAL_PAYMENT`, `CHARGE_WITH_INVOICE`, or `EXTENSION` |
-  | `menuOption.componentId` | String | Component ID when `EXTENSION` key is triggered |
-- **Multi-plugin:** Sequential modals, each appearing before the default modal
 - **Use case:** Add items to an order such as additional items, notes, or extra fees.
 
-> **Note:** This slot also appears on the Wix Bookings Calendar Page.
-
 ---
 
 ## Wix Events

package/skills/wix-app/references/site-plugin/EXAMPLES.md

@@ -221,7 +221,7 @@ export default function PluginSettingsPage() {
 
 ## Wix Data API Integration
 
-When using Wix Data API in plugins, handle the Wix Editor environment:
+When using Wix Data API in plugins, handle the Wix Editor environment. This example imports `@wix/site-window` — install it first (`npm install @wix/site-window`), since it's not part of the CLI's default scaffolded `package.json`:
 
 ```typescript
 import { items } from "@wix/data";