@wix/agent-skills 1.0.0

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

@@ -0,0 +1,157 @@
+
+# Wix Dashboard Menu Plugin Builder
+
+Creates dashboard menu plugin extensions for Wix CLI applications. Dashboard menu plugins are menu items that integrate into predefined **menu slots** on dashboard pages managed by Wix first-party business apps (Wix Stores, Wix Bookings, Wix Blog, Wix eCommerce, Wix Events, Wix CRM, Wix Restaurants).
+
+When clicked, a dashboard menu plugin either **navigates to a dashboard page** or **opens a dashboard modal**.
+
+Dashboard menu plugins are configuration-only extensions — they do NOT have a React component file.
+
+
+## Quick Start Checklist
+
+Follow these steps in order when creating a dashboard menu plugin:
+
+1. [ ] Identify the target menu slot ID — see [Slot Lookup Table](#slot-lookup-table) below, then read only the relevant vertical file
+2. [ ] Create plugin folder: `src/extensions/dashboard/menu-plugins/<plugin-name>/`
+3. [ ] Create `<plugin-name>.extension.ts` with `extensions.dashboardMenuPlugin()` and unique UUID
+4. [ ] Configure the `action` field to either navigate to a dashboard page or open a modal
+5. [ ] Update `src/extensions.ts` to import and use the new extension
+
+## Architecture
+
+Dashboard menu plugins operate as **click-to-action** menu items. They:
+
+1. Appear as labeled items with an icon in a menu slot on a Wix app's dashboard page
+2. When clicked, perform one of two actions:
+   - **Navigate to a dashboard page** — redirects to a specified dashboard page
+   - **Open a dashboard modal** — displays a specified dashboard modal
+
+## Files and Code Structure
+
+Dashboard menu plugins live under `src/extensions/dashboard/menu-plugins/`. Each plugin has its own folder containing a single file.
+
+```
+src/extensions/dashboard/menu-plugins/
+└── <plugin-name>/
+    └── <plugin-name>.extension.ts   # Builder configuration
+```
+
+> **Note:** This is the default folder structure created by the CLI. You can move the file to any location within the `src/` folder and update the references in your `extension.ts` file.
+
+## Plugin Builder Configuration
+
+### File: `<plugin-name>.extension.ts`
+
+```typescript
+import { extensions } from "@wix/astro/builders";
+
+export const dashboardmenupluginMyMenuPlugin = extensions.dashboardMenuPlugin({
+  id: "{{GENERATE_UUID}}",
+  title: "My Menu Plugin",
+  extends: "<MENU_SLOT_ID>",
+  iconKey: "Sparkles",
+  action: {
+    navigateToPage: {
+      pageId: "<DASHBOARD_PAGE_ID>",
+    },
+  },
+});
+```
+
+**CRITICAL: UUID Generation**
+
+The `id` must be a unique, static UUID v4 string. Generate a fresh UUID for each extension — do NOT use `randomUUID()` or copy UUIDs from examples. Replace `{{GENERATE_UUID}}` with a freshly generated UUID like `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`.
+
+### Builder Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique plugin ID (GUID). Must be unique across all extensions in the project. |
+| `title` | string | Text displayed for the menu item. |
+| `extends` | string | Menu slot ID where the extension integrates. See [Slot Lookup Table](#slot-lookup-table). |
+| `iconKey` | string | Icon name from Wix Design System appearing next to the title. |
+| `action` | object | Navigation configuration determining behavior when clicked. |
+
+### The `extends` Field
+
+The `extends` field specifies which dashboard menu slot hosts your menu plugin. Each Wix business app exposes menu slots on its dashboard pages. You must provide the exact slot ID.
+
+**Important:** Some slots with the same ID appear on different pages within the dashboard. If you create a menu plugin for a slot that exists on multiple pages, the menu plugin is displayed on all of those pages.
+
+For the complete list of available menu slot IDs, see the [Slot Lookup Table](#slot-lookup-table) below. Read only the vertical file that matches the user's request.
+
+### The `action` Field
+
+The `action` field determines what happens when the user clicks the menu item. You must configure exactly one of the following:
+
+#### Option 1: Navigate to a Dashboard Page
+
+```typescript
+action: {
+  navigateToPage: {
+    pageId: "<DASHBOARD_PAGE_ID>",
+  },
+},
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `action.navigateToPage` | object | Page navigation configuration object. |
+| `action.navigateToPage.pageId` | string | The `id` of the target dashboard page extension. |
+
+#### Option 2: Open a Dashboard Modal
+
+```typescript
+action: {
+  openModal: {
+    componentId: "<DASHBOARD_MODAL_ID>",
+  },
+},
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `action.openModal` | object | Modal navigation configuration object. |
+| `action.openModal.componentId` | string | The `id` of the target dashboard modal extension. |
+
+### The `iconKey` Field
+
+The `iconKey` must be a valid icon name from the Wix Design System icon set (`@wix/wix-ui-icons-common`). Use the `wix-design-system` skill to look up available icon names.
+
+## Extension Registration
+
+**Extension registration is MANDATORY and has TWO required steps.**
+
+### Step 1: Create Plugin-Specific Extension File
+
+Each dashboard menu plugin requires a `<plugin-name>.extension.ts` file in its folder. See [Plugin Builder Configuration](#plugin-builder-configuration) above.
+
+### Step 2: Register in Main Extensions File
+
+**CRITICAL:** After creating the plugin-specific extension file, you MUST read [Extension Registration reference](EXTENSION_REGISTRATION.md) and follow the "App Registration" section to update `src/extensions.ts`.
+
+**Without completing Step 2, the dashboard menu plugin will not appear on the dashboard page.**
+
+## Dashboard-Menu-Plugin-specific Conventions
+
+- The `extends` field MUST contain a valid menu slot ID from a Wix business app — do NOT invent slot IDs.
+- The `action.navigateToPage.pageId` MUST reference the `id` of an existing dashboard page extension in the project.
+- The `action.openModal.componentId` MUST reference the `id` of an existing dashboard modal extension in the project.
+- A dashboard menu plugin does NOT have a React component — it is configuration-only.
+- Do NOT confuse dashboard menu plugins with dashboard plugins — they are different extension types.
+
+## Slot Lookup Table
+
+Identify which Wix app the user is targeting, then read **only** the corresponding reference file for slot IDs.
+
+| Wix App | Keywords | Slot Reference |
+|---------|----------|----------------|
+| Wix Blog | blog, posts, categories, tags, drafts, scheduled | [blog-slots.md](dashboard-menu-plugin/blog-slots.md) |
+| Wix Bookings | bookings, calendar, services, staff, booking list | [bookings-slots.md](dashboard-menu-plugin/bookings-slots.md) |
+| Wix CRM | CRM, contacts | [crm-slots.md](dashboard-menu-plugin/crm-slots.md) |
+| Wix eCommerce | ecommerce, orders, payment | [ecommerce-slots.md](dashboard-menu-plugin/ecommerce-slots.md) |
+| Wix Events | events, guests, RSVP, ticketed | [events-slots.md](dashboard-menu-plugin/events-slots.md) |
+| Wix Stores | stores, products, inventory, catalog | [stores-slots.md](dashboard-menu-plugin/stores-slots.md) |
+| Wix Restaurants | restaurants, reservations, online orders, menus | [restaurants-slots.md](dashboard-menu-plugin/restaurants-slots.md) |
+

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

@@ -0,0 +1,283 @@
+
+## Overview
+
+Dashboard modals are popup dialogs triggered from dashboard pages or plugins. They consist of three files and use the Dashboard SDK for lifecycle control via `openModal()` and `closeModal()`.
+
+## Quick Reference
+
+| Task | Method | Example |
+|------|--------|---------|
+| Create modal | Create 3 files in `src/extensions/dashboard/modals/<folder>/` | See File Structure below |
+| Open modal | `dashboard.openModal()` | `openModal({ modalId: "modal-id" })` |
+| Pass data to modal | `params` in `openModal()` | `params: { userId: "123" }` |
+| Read data in modal | `observeState()` | `dashboard.observeState((state) => { ... })` |
+| Close modal | `dashboard.closeModal()` | `closeModal()` |
+| Return data to parent | Pass data to `closeModal()` | `closeModal({ ... })` |
+| Wait for modal close | `modalClosed` Promise | `const { modalClosed } = openModal(...);` |
+
+## File Structure
+
+Create **three files** in `src/extensions/dashboard/modals/<folder-name>/`:
+
+1. **`extensions.ts`** - Builder configuration with modal ID, title, dimensions, component path
+2. **`<modal-name>.tsx`** - React component rendering modal content
+3. **`<modal-name>.config.ts`** - Configurable modal properties (title, width, height)
+
+## Implementation
+
+### Creating a Modal
+
+Create the three required files:
+
+**1. `extensions.ts`** - Modal builder configuration:
+
+```typescript
+import { extensions } from '@wix/astro/builders';
+import config from './<modal-name>.config.ts';
+
+export default extensions.dashboardModal({
+  id: "{{GENERATE_UUID}}",
+  title: config.title,
+  width: config.width,
+  height: config.height,
+  component: './extensions/dashboard/modals/<modal-name>/<modal-name>.tsx',
+});
+
+```
+
+**CRITICAL: UUID Generation**
+
+The `id` must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use `randomUUID()` or copy UUIDs from examples. Replace `{{GENERATE_UUID}}` with a freshly generated UUID like `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`.
+
+Builder fields:
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique modal ID (GUID). Used with `openModal()` |
+| title | string | Modal title shown in project dashboard |
+| width | number | Initial width while loading |
+| height | number | Initial height while loading |
+| component | string | Path to the modal content `.tsx` file |
+
+**2. `<modal-name>.tsx`** - Modal content component:
+
+```typescript
+import type { FC } from 'react';
+import { dashboard } from '@wix/dashboard';
+import {
+  WixDesignSystemProvider,
+  Text,
+  Box,
+  CustomModalLayout,
+} from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import config from './<modal-name>.config.ts';
+
+const { width, height, title } = config;
+
+// To open your modal, call `openModal` with your modal id.
+// e.g.
+// import { dashboard } from '@wix/dashboard';
+// function MyComponent() {
+//   return <button onClick={() => dashboard.openModal({ modalId: '8ef4d434-9c80-44f5-a3f5-6f15f3a34be7' })}>Open Modal</button>;
+// }
+const Modal: FC = () => {
+  return (
+    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
+      <CustomModalLayout
+        width={width}
+        maxHeight={height}
+        primaryButtonText="Save"
+        secondaryButtonText="Cancel"
+        primaryButtonOnClick={() => dashboard.closeModal()}
+        secondaryButtonOnClick={() => dashboard.closeModal()}
+        title={title}
+        subtitle="Edit this file to customize your modal"
+        content={
+          <Box direction="vertical" align="center">
+            <Text>Wix CLI Modal</Text>
+          </Box>
+        }
+      />
+    </WixDesignSystemProvider>
+  );
+};
+
+export default Modal;
+```
+
+**3. `<modal-name>.config.ts`** - Configurable properties:
+
+```typescript
+export default {
+  title: "My Modal",
+  width: 600,
+  height: 400,
+};
+```
+
+Then register in `src/extensions.ts`:
+
+```typescript
+import { dashboardmodalYourModal } from './extensions/dashboard/modals/<modal-name>/extensions.ts';
+
+export default app()
+  .use(dashboardmodalYourModal)
+  // ... other extensions
+```
+
+### Opening a Modal
+
+```typescript
+import { dashboard } from "@wix/dashboard";
+
+// Simple open
+const result = await dashboard.openModal({
+  modalId: "your-modal-id", // From .extension.ts id field
+});
+
+// Pass data to modal via params
+const result = await dashboard.openModal({
+  modalId: "your-modal-id",
+  params: {
+    userId: user.id,
+    itemData: complexObject, // Objects are passed directly, no encoding needed
+  },
+});
+
+// Get notified when the modal is closed
+const { modalClosed } = dashboard.openModal({
+  modalId: "your-modal-id",
+});
+const result = await modalClosed; // Resolves with data from closeModal()
+```
+
+### Receiving Data in Modal
+
+Use `observeState()` to access data passed via `params` in `openModal()`:
+
+```typescript
+import { dashboard } from "@wix/dashboard";
+import { useEffect, useState } from "react";
+
+function MyModal() {
+  const [modalData, setModalData] = useState<{ userId?: string; itemData?: any }>({});
+
+  useEffect(() => {
+    dashboard.observeState((state) => {
+      // Access custom data passed through openModal params
+      if (state.userId) {
+        setModalData({
+          userId: state.userId,
+          itemData: state.itemData,
+        });
+      }
+    });
+  }, []);
+
+  return <div>User ID: {modalData.userId}</div>;
+}
+```
+
+### Closing Modal
+
+Call `closeModal()` from within the modal extension to close it. Optionally pass data back to the opener.
+
+```typescript
+import { dashboard } from "@wix/dashboard";
+
+// Close without returning data
+dashboard.closeModal();
+
+// Close with custom return data
+dashboard.closeModal({ saved: true, itemId: "123" });
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| closeData | Serializable (optional) | Data to pass back to the modal opener. Must be cloneable via [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). |
+
+**Supported types:** strings, numbers, booleans, plain objects, arrays, Dates, Maps, Sets, ArrayBuffers.
+**Not supported:** functions, DOM nodes, class instances with methods, Symbols, Promises.
+
+**Returns:** `void`
+
+### Customizing Modal
+
+Edit `.config.ts` for organized settings:
+
+```typescript
+export default {
+  title: 'User Settings',
+  width: 600,
+  height: 500,
+}
+```
+
+Import in `.tsx`:
+
+```typescript
+import config from './modal.config.ts';
+
+export default function MyModal() {
+  return (
+    <CustomModalLayout
+      title={config.title}
+      // ... rest of component
+    />
+  );
+}
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Can't find modal ID | Check `.extension.ts` file's `id` field |
+| Forgetting to register in `extensions.ts` | Import and `.use()` the modal |
+| Using `extensionId` instead of `modalId` | Use `modalId` in `openModal()` |
+| Can't access params in modal | Use `dashboard.observeState()` to read passed data |
+| Modal won't close | Use `dashboard.closeModal()` from `@wix/dashboard` |
+
+## Real-World Example
+
+```typescript
+// Dashboard Page: Opening edit modal
+const handleEdit = async (item: Item) => {
+  dashboard.openModal({
+    modalId: "edit-item-modal-guid",
+    params: {
+      itemId: item._id,
+      item: item, // Objects passed directly via params
+    },
+  });
+};
+
+// Modal: Receiving and saving data
+export default function ItemEditModal() {
+  const [formData, setFormData] = useState<Item | null>(null);
+
+  useEffect(() => {
+    dashboard.observeState((state) => {
+      if (state.item) {
+        setFormData(state.item);
+      }
+    });
+  }, []);
+
+  const handleSave = async () => {
+    // Save logic
+    dashboard.showToast({ message: "Saved!", type: "success" });
+    dashboard.closeModal();
+  };
+
+  return (
+    <CustomModalLayout
+      title="Edit Item"
+      primaryButtonText="Save"
+      onCloseButtonClick={() => dashboard.closeModal()}
+      primaryButtonOnClick={handleSave}
+      content={/* form fields */}
+    />
+  );
+}
+```