@wix/agent-skills 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +111 -0
  3. package/package.json +29 -0
  4. package/skills/wix-app/SKILL.md +344 -0
  5. package/skills/wix-app/references/APP_IDENTIFIERS.md +35 -0
  6. package/skills/wix-app/references/APP_MARKET_REVIEW.md +311 -0
  7. package/skills/wix-app/references/APP_VALIDATION.md +171 -0
  8. package/skills/wix-app/references/BACKEND_API.md +233 -0
  9. package/skills/wix-app/references/BACKEND_EVENT.md +116 -0
  10. package/skills/wix-app/references/CODE_QUALITY.md +33 -0
  11. package/skills/wix-app/references/CUSTOM_ELEMENT_WIDGET.md +587 -0
  12. package/skills/wix-app/references/DASHBOARD_MENU_PLUGIN.md +157 -0
  13. package/skills/wix-app/references/DASHBOARD_MODAL.md +283 -0
  14. package/skills/wix-app/references/DASHBOARD_PAGE.md +403 -0
  15. package/skills/wix-app/references/DASHBOARD_PLUGIN.md +205 -0
  16. package/skills/wix-app/references/DATA_COLLECTION.md +451 -0
  17. package/skills/wix-app/references/DOCUMENTATION.md +42 -0
  18. package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md +65 -0
  19. package/skills/wix-app/references/EMBEDDED_SCRIPT.md +468 -0
  20. package/skills/wix-app/references/EXTENSION_REGISTRATION.md +96 -0
  21. package/skills/wix-app/references/SERVICE_PLUGIN.md +235 -0
  22. package/skills/wix-app/references/SITE_PLUGIN.md +436 -0
  23. package/skills/wix-app/references/STORES_VERSIONING.md +334 -0
  24. package/skills/wix-app/references/backend-event/COMMON-EVENTS.md +84 -0
  25. package/skills/wix-app/references/custom-element-widget/SETTINGS_PANEL.md +345 -0
  26. package/skills/wix-app/references/dashboard-menu-plugin/blog-slots.md +71 -0
  27. package/skills/wix-app/references/dashboard-menu-plugin/bookings-slots.md +58 -0
  28. package/skills/wix-app/references/dashboard-menu-plugin/crm-slots.md +8 -0
  29. package/skills/wix-app/references/dashboard-menu-plugin/ecommerce-slots.md +17 -0
  30. package/skills/wix-app/references/dashboard-menu-plugin/events-slots.md +29 -0
  31. package/skills/wix-app/references/dashboard-menu-plugin/restaurants-slots.md +27 -0
  32. package/skills/wix-app/references/dashboard-menu-plugin/stores-slots.md +35 -0
  33. package/skills/wix-app/references/dashboard-page/API_SPEC.md +138 -0
  34. package/skills/wix-app/references/dashboard-page/DASHBOARD_API.md +573 -0
  35. package/skills/wix-app/references/dashboard-page/DYNAMIC_PARAMETERS.md +269 -0
  36. package/skills/wix-app/references/dashboard-page/ECOM_NAVIGATION.md +164 -0
  37. package/skills/wix-app/references/dashboard-plugin/SLOTS.md +294 -0
  38. package/skills/wix-app/references/data-collection/WIX_DATA.md +270 -0
  39. package/skills/wix-app/references/data-collection/extension-template.ts +107 -0
  40. package/skills/wix-app/references/editor-react-component/ACCESSIBILITY.md +138 -0
  41. package/skills/wix-app/references/editor-react-component/COMPONENT-API.md +454 -0
  42. package/skills/wix-app/references/editor-react-component/COMPONENT-CONFIGURATION.md +165 -0
  43. package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md +576 -0
  44. package/skills/wix-app/references/editor-react-component/DIRECTIONALITY.md +170 -0
  45. package/skills/wix-app/references/editor-react-component/EDIT-FLOW.md +6 -0
  46. package/skills/wix-app/references/editor-react-component/PARTS.md +25 -0
  47. package/skills/wix-app/references/editor-react-component/PROPS-VS-CSS.md +203 -0
  48. package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md +167 -0
  49. package/skills/wix-app/references/editor-react-component/REACT-PATTERNS.md +137 -0
  50. package/skills/wix-app/references/service-plugin/ADDITIONAL-FEES.md +112 -0
  51. package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md +118 -0
  52. package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md +87 -0
  53. package/skills/wix-app/references/service-plugin/GIFT-CARDS.md +86 -0
  54. package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md +135 -0
  55. package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md +79 -0
  56. package/skills/wix-app/references/service-plugin/VALIDATIONS.md +68 -0
  57. package/skills/wix-app/references/site-plugin/EXAMPLES.md +311 -0
  58. package/skills/wix-app/references/site-plugin/SLOTS.md +263 -0
  59. package/skills/wix-design-system/SKILL.md +129 -0
  60. package/skills/wix-design-system/references/file-structure.md +56 -0
  61. package/skills/wix-design-system/scripts/wds.cjs +531 -0
  62. package/skills/wix-headless/SKILL.md +418 -0
  63. package/skills/wix-headless/references/DISCOVERY.md +332 -0
  64. package/skills/wix-headless/references/ORCHESTRATION.md +269 -0
  65. package/skills/wix-headless/references/SETUP.md +154 -0
  66. package/skills/wix-headless/references/blog/BLOG_CONTENT.md +152 -0
  67. package/skills/wix-headless/references/blog/BLOG_PAGES.md +299 -0
  68. package/skills/wix-headless/references/blog/BLOG_SETUP.md +218 -0
  69. package/skills/wix-headless/references/blog/INSTRUCTIONS.md +32 -0
  70. package/skills/wix-headless/references/cms/CMS_FOUNDATIONS.md +373 -0
  71. package/skills/wix-headless/references/cms/FAQ_KNOWLEDGE_BASE.md +229 -0
  72. package/skills/wix-headless/references/cms/INSTRUCTIONS.md +40 -0
  73. package/skills/wix-headless/references/cms/PORTFOLIO.md +454 -0
  74. package/skills/wix-headless/references/cms/RESOURCE_LIBRARY.md +356 -0
  75. package/skills/wix-headless/references/cms/TEAM_DIRECTORY.md +299 -0
  76. package/skills/wix-headless/references/commands/install-app.md +42 -0
  77. package/skills/wix-headless/references/commands/known-apps.json +5 -0
  78. package/skills/wix-headless/references/commands/mcp-bootstrap.md +28 -0
  79. package/skills/wix-headless/references/designer/INSTRUCTIONS.md +828 -0
  80. package/skills/wix-headless/references/ecom/CART_PAGES.md +120 -0
  81. package/skills/wix-headless/references/ecom/CART_WIRING.md +103 -0
  82. package/skills/wix-headless/references/ecom/COMPONENTS_CSS.md +132 -0
  83. package/skills/wix-headless/references/ecom/INSTRUCTIONS.md +59 -0
  84. package/skills/wix-headless/references/forms/CONTACT_FORM.md +477 -0
  85. package/skills/wix-headless/references/forms/INSTRUCTIONS.md +43 -0
  86. package/skills/wix-headless/references/gift-cards/COMPONENTS.md +119 -0
  87. package/skills/wix-headless/references/gift-cards/INSTRUCTIONS.md +51 -0
  88. package/skills/wix-headless/references/gift-cards/PAGES.md +129 -0
  89. package/skills/wix-headless/references/images/INSTRUCTIONS.md +359 -0
  90. package/skills/wix-headless/references/shared/BUILD_NOISE.md +8 -0
  91. package/skills/wix-headless/references/shared/IMAGE_GENERATION.md +185 -0
  92. package/skills/wix-headless/references/shared/IMPLEMENTER.md +155 -0
  93. package/skills/wix-headless/references/shared/MCP_PREFIX.md +105 -0
  94. package/skills/wix-headless/references/shared/PRODUCTION_SHARP_EDGES.md +97 -0
  95. package/skills/wix-headless/references/shared/RETURN_CONTRACT.md +423 -0
  96. package/skills/wix-headless/references/shared/STYLING.md +117 -0
  97. package/skills/wix-headless/references/stores/BACK_IN_STOCK.md +178 -0
  98. package/skills/wix-headless/references/stores/CATEGORY_PAGES.md +86 -0
  99. package/skills/wix-headless/references/stores/COMPONENTS_CSS.md +129 -0
  100. package/skills/wix-headless/references/stores/HOME_AND_NAV.md +227 -0
  101. package/skills/wix-headless/references/stores/INSTRUCTIONS.md +96 -0
  102. package/skills/wix-headless/references/stores/PRODUCT_CATALOG_DATA.md +249 -0
  103. package/skills/wix-headless/references/stores/PRODUCT_PAGES.md +213 -0
  104. package/skills/wix-headless/references/stores/SHARED_WIRING.md +164 -0
  105. package/skills/wix-headless/references/verticals/_schema.json +160 -0
  106. package/skills/wix-headless/references/verticals/_schema.md +185 -0
  107. package/skills/wix-headless/references/verticals/blog.md +125 -0
  108. package/skills/wix-headless/references/verticals/cms.md +121 -0
  109. package/skills/wix-headless/references/verticals/ecom.md +96 -0
  110. package/skills/wix-headless/references/verticals/forms.md +106 -0
  111. package/skills/wix-headless/references/verticals/gift-cards.md +121 -0
  112. package/skills/wix-headless/references/verticals/stores.md +167 -0
  113. package/skills/wix-headless/scripts/check-manifest.mjs +198 -0
  114. package/skills/wix-headless/scripts/copy-utility-templates.mjs +153 -0
  115. package/skills/wix-headless/scripts/emit-design-tokens.mjs +77 -0
  116. package/skills/wix-headless/scripts/finalize-run-json.mjs +141 -0
  117. package/skills/wix-headless/scripts/init-site-json.mjs +63 -0
  118. package/skills/wix-headless/scripts/patch-decorative-slots.mjs +124 -0
  119. package/skills/wix-headless/scripts/plan-entity-image-waves.mjs +190 -0
  120. package/skills/wix-headless/scripts/preview.sh +45 -0
  121. package/skills/wix-headless/scripts/release.sh +73 -0
  122. package/skills/wix-headless/scripts/scaffold.sh +53 -0
  123. package/skills/wix-headless/scripts/seed-utilities.sh +55 -0
  124. package/skills/wix-headless/shared-utilities/analytics.ts +40 -0
  125. package/skills/wix-headless/shared-utilities/ricos.ts +179 -0
  126. package/skills/wix-headless/shared-utilities/wix-image.ts +72 -0
  127. package/skills/wix-headless/templates/ecom/CartBadge.tsx +84 -0
  128. package/skills/wix-headless/templates/ecom/CartView.tsx +543 -0
  129. package/skills/wix-headless/templates/ecom/cart.astro +13 -0
  130. package/skills/wix-headless/templates/ecom/components-ecom.css +215 -0
  131. package/skills/wix-headless/templates/ecom/discounts.ts +71 -0
  132. package/skills/wix-headless/templates/ecom/thank-you.astro +24 -0
  133. package/skills/wix-headless/templates/gift-cards/GiftCardPurchase.tsx +172 -0
  134. package/skills/wix-headless/templates/gift-cards/_home-teaser-snippet.astro +42 -0
  135. package/skills/wix-headless/templates/gift-cards/_nav-snippet.astro +11 -0
  136. package/skills/wix-headless/templates/gift-cards/components-gift-cards.css +219 -0
  137. package/skills/wix-headless/templates/gift-cards/gift-cards.astro +51 -0
  138. package/skills/wix-headless/templates/gift-cards/gift-cards.ts +75 -0
  139. package/skills/wix-headless/templates/stores/AddToCartButton.tsx +77 -0
  140. package/skills/wix-headless/templates/stores/BackInStockForm.tsx +176 -0
  141. package/skills/wix-headless/templates/stores/CategoryRail.astro +69 -0
  142. package/skills/wix-headless/templates/stores/ProductCard.astro +79 -0
  143. package/skills/wix-headless/templates/stores/ProductPurchase.tsx +397 -0
  144. package/skills/wix-headless/templates/stores/SeoTags.astro +21 -0
  145. package/skills/wix-headless/templates/stores/back-in-stock.ts +67 -0
  146. package/skills/wix-headless/templates/stores/categories.ts +155 -0
  147. package/skills/wix-headless/templates/stores/category/[slug].astro +130 -0
  148. package/skills/wix-headless/templates/stores/components-stores.css +295 -0
  149. package/skills/wix-headless/templates/stores/products/[slug].astro +128 -0
  150. package/skills/wix-headless/templates/stores/products/index.astro +101 -0
  151. package/skills/wix-manage/SKILL.md +280 -0
  152. package/skills/wix-manage/references/app-installation/install-wix-apps.md +155 -0
  153. package/skills/wix-manage/references/app-installation/list-installed-apps.md +124 -0
  154. package/skills/wix-manage/references/blog/how-to-create-blog-posts.md +226 -0
  155. package/skills/wix-manage/references/bookings/booking-service-policy-setup.md +95 -0
  156. package/skills/wix-manage/references/bookings/booking-system-integration-gaps.md +416 -0
  157. package/skills/wix-manage/references/bookings/bookings-staff-setup.md +255 -0
  158. package/skills/wix-manage/references/bookings/create-and-update-booking-services.md +462 -0
  159. package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md +278 -0
  160. package/skills/wix-manage/references/bookings/external-calendar-integration.md +258 -0
  161. package/skills/wix-manage/references/bookings/multi-resource-service-creation.md +231 -0
  162. package/skills/wix-manage/references/calendar/configure-default-business-hours.md +226 -0
  163. package/skills/wix-manage/references/cms/cms-data-items-crud.md +422 -0
  164. package/skills/wix-manage/references/cms/cms-data-operations-extended.md +263 -0
  165. package/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md +136 -0
  166. package/skills/wix-manage/references/cms/cms-references-and-relationships.md +160 -0
  167. package/skills/wix-manage/references/cms/cms-schema-management.md +143 -0
  168. package/skills/wix-manage/references/contacts/bulk-delete-contacts.md +73 -0
  169. package/skills/wix-manage/references/contacts/bulk-label-and-unlabel-contacts.md +67 -0
  170. package/skills/wix-manage/references/domains/domain-search-and-purchase.md +434 -0
  171. package/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md +420 -0
  172. package/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md +267 -0
  173. package/skills/wix-manage/references/ecommerce/flow-bundle-and-save.md +290 -0
  174. package/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md +300 -0
  175. package/skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md +364 -0
  176. package/skills/wix-manage/references/ecommerce/flow-seasonal-promotion.md +315 -0
  177. package/skills/wix-manage/references/ecommerce/flow-stock-mover.md +308 -0
  178. package/skills/wix-manage/references/ecommerce/flow-upsell-boost.md +271 -0
  179. package/skills/wix-manage/references/ecommerce/goal-clear-inventory.md +118 -0
  180. package/skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md +122 -0
  181. package/skills/wix-manage/references/ecommerce/goal-increase-aov.md +132 -0
  182. package/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md +148 -0
  183. package/skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md +146 -0
  184. package/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md +118 -0
  185. package/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md +88 -0
  186. package/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md +108 -0
  187. package/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md +124 -0
  188. package/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md +299 -0
  189. package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md +582 -0
  190. package/skills/wix-manage/references/ecommerce/setup-coupons.md +338 -0
  191. package/skills/wix-manage/references/ecommerce/setup-discount-rules.md +444 -0
  192. package/skills/wix-manage/references/ecommerce/setup-shipping-rates.md +86 -0
  193. package/skills/wix-manage/references/ecommerce/setup-shipping-regions.md +56 -0
  194. package/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md +209 -0
  195. package/skills/wix-manage/references/ecommerce/skill-graph.md +139 -0
  196. package/skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md +124 -0
  197. package/skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md +95 -0
  198. package/skills/wix-manage/references/events/list-events.md +203 -0
  199. package/skills/wix-manage/references/forms/create-form.md +260 -0
  200. package/skills/wix-manage/references/get-paid/create-payment-links.md +212 -0
  201. package/skills/wix-manage/references/get-paid/how-to-setup-wix-payments.md +57 -0
  202. package/skills/wix-manage/references/get-paid/payment-links-for-bookings.md +101 -0
  203. package/skills/wix-manage/references/media/upload-media-to-wix.md +216 -0
  204. package/skills/wix-manage/references/pricing-plans/create-and-update-pricing-plans.md +77 -0
  205. package/skills/wix-manage/references/pricing-plans/pricing-plans-bookings-integration.md +166 -0
  206. package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md +336 -0
  207. package/skills/wix-manage/references/rich-content/ricos-converter-service.md +295 -0
  208. package/skills/wix-manage/references/site-properties/change-payment-currency-site-properties.md +59 -0
  209. package/skills/wix-manage/references/sites/create-site-from-template.md +183 -0
  210. package/skills/wix-manage/references/sites/query-sites.md +125 -0
  211. package/skills/wix-manage/references/stores/add-store-pages-to-site.md +57 -0
  212. package/skills/wix-manage/references/stores/bulk-create-products-with-options.md +1041 -0
  213. package/skills/wix-manage/references/stores/create-product-catalog-v1.md +125 -0
  214. package/skills/wix-manage/references/stores/create-product-from-image.md +824 -0
  215. package/skills/wix-manage/references/stores/create-product-with-options-catalog-v3.md +566 -0
  216. package/skills/wix-manage/references/stores/find-products-query-and-search-catalog-v3.md +194 -0
  217. package/skills/wix-manage/references/stores/query-products-catalog-v1.md +80 -0
  218. package/skills/wix-manage/references/stores/setup-online-store-catalog-v3.md +99 -0
  219. package/skills/wix-manage/references/stores/update-product-pre-order.md +213 -0
  220. package/skills/wix-manage/references/stores/update-product-with-options.md +318 -0
@@ -0,0 +1,403 @@
1
+
2
+ # Wix Dashboard Page Builder
3
+
4
+ Creates full-featured dashboard page extensions for Wix CLI applications. Dashboard pages appear in the Wix site owner's dashboard and enable site administrators to manage data, configure settings, and perform administrative tasks.
5
+
6
+
7
+ ## Quick Start Checklist
8
+
9
+ Follow these steps in order when creating a dashboard page:
10
+
11
+ 1. [ ] Create page folder: `src/extensions/dashboard/pages/<page-name>/`
12
+ 2. [ ] Create `page.tsx` with WDS components wrapped in `WixDesignSystemProvider`
13
+ 3. [ ] Create `extensions.ts` with `extensions.dashboardPage()` and unique UUID
14
+ 4. [ ] Update `src/extensions.ts` to import and use the new extension
15
+
16
+ ## Capabilities
17
+
18
+ ### Data Operations (Wix Data SDK)
19
+
20
+ See [Wix Data Reference](data-collection/WIX_DATA.md) in the Data Collection reference for complete documentation.
21
+
22
+ **Summary:**
23
+
24
+ - Read: `items.query('Collection').filter/sort.limit.find()` → `{ items, totalCount, hasNext }`
25
+ - Write: `items.insert | update | remove`. Ensure collection permissions allow the action
26
+
27
+ **Query methods:** `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `between`, `contains`, `startsWith`, `endsWith`, `hasSome`, `hasAll`, `isEmpty`, `isNotEmpty`, `and`, `or`, `not`, `ascending`, `descending`, `limit`, `skip`, `include`
28
+
29
+ ### Dashboard APIs
30
+
31
+ See [Dashboard API Reference](dashboard-page/DASHBOARD_API.md) for complete documentation including all methods, page IDs, and examples.
32
+
33
+ **Key methods:**
34
+
35
+ - `dashboard.navigate()` - Navigate between dashboard pages
36
+ - `dashboard.observeState()` - Receive contextual state and environmental information
37
+ - `dashboard.showToast()` - Display toast notifications
38
+ - `dashboard.openModal()` - Open dashboard modal extensions (see [Dashboard Modal reference](DASHBOARD_MODAL.md))
39
+ - `dashboard.navigateBack()` - Navigate back to previous page
40
+ - `dashboard.getPageUrl()` - Get full URL for a dashboard page
41
+ - `dashboard.openMediaManager()` - Open Wix Media Manager
42
+ - `dashboard.onBeforeUnload()` - Register beforeunload handler
43
+ - `dashboard.addSitePlugin()` - Add site plugin to slots
44
+ - `dashboard.setPageTitle()` - Set page title in browser tab
45
+ - `dashboard.onLayerStateChange()` - Handle foreground/background state changes
46
+
47
+ **CRITICAL: Using Modals in Dashboard Pages**
48
+
49
+ When you need to display popup forms, confirmations, detail views, or any dialog overlays from a dashboard page, you **MUST** use dashboard modals, not regular React modals or WDS Modal components.
50
+
51
+ - **Use dashboard modals** for: edit forms, delete confirmations, detail views, settings dialogs, any popup content
52
+ - **Do NOT use** WDS `Modal` component or custom React modal implementations
53
+ - **See [Dashboard Modal reference](DASHBOARD_MODAL.md)** for complete implementation guide
54
+
55
+ Dashboard modals are opened using `dashboard.openModal()` and provide proper integration with the dashboard lifecycle, state management, and navigation.
56
+
57
+ **Ecom Navigation:** See [Ecom Navigation Reference](dashboard-page/ECOM_NAVIGATION.md) for ecom-specific navigation helpers.
58
+
59
+ ### Embedded Script Configuration API
60
+
61
+ When building a dashboard page to configure an embedded script, see [Dynamic Parameters Reference](dashboard-page/DYNAMIC_PARAMETERS.md) for complete implementation guide.
62
+
63
+ **Key points:**
64
+
65
+ - Use `embeddedScripts` from `@wix/app-management`
66
+ - Parameters are returned as strings - handle type conversions when loading
67
+ - All parameters must be saved as strings (convert booleans/numbers to strings)
68
+ - Use `withProviders` wrapper when dynamic parameters are present
69
+
70
+ ## Files and Code Structure
71
+
72
+ Dashboard pages live under `src/extensions/dashboard/pages`. Each page has its own folder.
73
+
74
+ **File structure:**
75
+
76
+ - `src/extensions/dashboard/pages/<page>/page.tsx` — page component
77
+
78
+ **Key metadata fields:**
79
+
80
+ - `id` (string, GUID): Unique page ID used to register the page
81
+ - `title` (string): Used for browser tab and optional sidebar label
82
+ - `additionalRoutes` (string[], optional): Extra routes leading to this page
83
+ - `sidebar.disabled` (boolean, optional): Hide page from sidebar (default false)
84
+ - `sidebar.priority` (number, optional): Sidebar ordering; lower is higher priority
85
+ - `sidebar.whenActive.selectedPageId` (string, optional): Which page appears selected when this page is active
86
+ - `sidebar.whenActive.hideSidebar` (boolean, optional): Hide sidebar when this page is active
87
+
88
+ ## WDS Provider Usage
89
+
90
+ Wrap your dashboard page component with `WixDesignSystemProvider` to enable WDS components and theming. You must also import the global CSS styles for WDS components to render correctly.
91
+
92
+ ```typescript
93
+ import { WixDesignSystemProvider } from "@wix/design-system";
94
+ import '@wix/design-system/styles.global.css';
95
+
96
+ export default function () {
97
+ return (
98
+ <WixDesignSystemProvider>
99
+ <Page>
100
+ <Page.Header
101
+ title="My Page"
102
+ subtitle="This is a subtitle for your page"
103
+ />
104
+ <Page.Content>
105
+ <EmptyState title="My Page" subtitle="Hello World!" theme="page" />
106
+ </Page.Content>
107
+ </Page>
108
+ </WixDesignSystemProvider>
109
+ );
110
+ }
111
+ ```
112
+
113
+ **Note:** When using dynamic parameters, use the `withProviders` wrapper instead. See [Dynamic Parameters](dashboard-page/DYNAMIC_PARAMETERS.md) for details.
114
+
115
+ ## Examples
116
+
117
+ ### Data Management Table
118
+
119
+ **Request:** "Create a dashboard page to manage blog posts"
120
+
121
+ **Output:** Page with table displaying posts, search toolbar, add/edit/delete actions, empty state.
122
+
123
+ ### Settings Form
124
+
125
+ **Request:** "Build a settings page for notification preferences"
126
+
127
+ **Output:** Page with form fields, save button with toast confirmation, unsaved changes warning.
128
+
129
+ ### Order Management
130
+
131
+ **Request:** "Create an admin panel for customer orders"
132
+
133
+ **Output:** Page with orders table, status badges, filters, detail dashboard modal (using [Dashboard Modal reference](DASHBOARD_MODAL.md)), status update actions.
134
+
135
+ ### Embedded Script Configuration
136
+
137
+ **Request:** "Create a settings page for the coupon popup embedded script"
138
+
139
+ **Output:** Page with form fields for popup headline, coupon code, minimum cart value, and enable toggle. Uses `embeddedScripts` API to load/save parameters.
140
+
141
+ ```typescript
142
+ // Key pattern for embedded script configuration pages
143
+ import { embeddedScripts } from "@wix/app-management";
144
+
145
+ // Load on mount
146
+ useEffect(() => {
147
+ const load = async () => {
148
+ const script = await embeddedScripts.getEmbeddedScript();
149
+ const data = script.parameters || {};
150
+ setOptions({
151
+ headline: data.headline || "Default",
152
+ enabled: data.enabled === "true",
153
+ threshold: Number(data.threshold) || 0,
154
+ });
155
+ };
156
+ load();
157
+ }, []);
158
+
159
+ // Save handler
160
+ const handleSave = async () => {
161
+ await embeddedScripts.embedScript({
162
+ parameters: {
163
+ headline: options.headline,
164
+ enabled: String(options.enabled),
165
+ threshold: String(options.threshold),
166
+ },
167
+ });
168
+ dashboard.showToast({ message: "Saved!", type: "success" });
169
+ };
170
+ ```
171
+
172
+ ## Extension Registration
173
+
174
+ **Extension registration is MANDATORY and has TWO required steps.**
175
+
176
+ ### Step 1: Create Page-Specific Extension File
177
+
178
+ Each dashboard page requires an `extensions.ts` file in its folder:
179
+
180
+ **File:** `src/extensions/dashboard/pages/<page-name>/extensions.ts`
181
+
182
+ ```typescript
183
+ import { extensions } from "@wix/astro/builders";
184
+
185
+ export const dashboardpageMyPage = extensions.dashboardPage({
186
+ id: "{{GENERATE_UUID}}",
187
+ title: "My Page",
188
+ routePath: "my-page",
189
+ component: "./extensions/dashboard/pages/my-page/page.tsx",
190
+ });
191
+ ```
192
+
193
+ **CRITICAL: UUID Generation**
194
+
195
+ 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"`.
196
+
197
+ | Property | Type | Description |
198
+ | ----------- | ------ | ---------------------------------------------------------------------------------------------------- |
199
+ | `id` | string | Unique static UUID v4 (generate fresh - see note above) |
200
+ | `title` | string | Display title in dashboard sidebar |
201
+ | `routePath` | string | URL path segment. Lowercase letters, numbers, dashes, and slashes only. Must NOT start with a slash. |
202
+ | `component` | string | Relative path to the page component (.tsx) |
203
+
204
+ ### Step 2: Register in Main Extensions File
205
+
206
+ **CRITICAL:** After creating the page-specific extension file, you MUST read [Extension Registration reference](EXTENSION_REGISTRATION.md) and follow the "App Registration" section to update `src/extensions.ts`.
207
+
208
+ **Without completing Step 2, the dashboard page will not appear in the Wix dashboard.**
209
+
210
+ ## Common Mistakes - Do NOT
211
+
212
+ **API confusion with other extension types:**
213
+
214
+ | WRONG (Embedded Script API) | CORRECT (Dashboard Page API) |
215
+ | --------------------------- | ---------------------------- |
216
+ | `name: "..."` | `title: "..."` |
217
+ | `source: "..."` | `component: "..."` |
218
+ | `route: "..."` | `routePath: "..."` |
219
+
220
+ Do NOT copy field names from embedded script or other extension registrations. Dashboard pages use `title`, `routePath`, and `component`.
221
+
222
+ ## API Spec Support
223
+
224
+ When an API specification is provided, you can make API calls to those endpoints. See [API Spec Reference](dashboard-page/API_SPEC.md) for details on how to use API specs in dashboard pages.
225
+
226
+
227
+ ## Layout Guidelines
228
+
229
+ Layout determines how users interact with your dashboard content. It establishes the structure, hierarchy, and rhythm of your dashboard page, contributing to the overall coherence and user experience. By making mindful and calculated choices in how you organize your content, users can move around more smoothly, saving time and frustration when completing tasks.
230
+
231
+ ### Design Principles
232
+
233
+ To create dashboard pages optimized for user experience, follow these design principles:
234
+
235
+ 1. **Consistent:** Maintain repetitive layouts and content patterns for intuitive and easy-to-read pages.
236
+ 2. **Inclusive:** Create layouts and content that adapt well to various screen sizes.
237
+ 3. **Balanced:** Emphasize the priority of regions and content elements through deliberate management of size and white space.
238
+ 4. **Connected:** Minimize the distance between related regions or content elements to enhance cohesion and navigation.
239
+
240
+
241
+ ### Screen Size
242
+
243
+ Dashboard pages are designed to accommodate various screen sizes rather than being tailored to one specific resolution. The primary content should be at the top of the page to ensure users immediately understand the purpose of the page.
244
+
245
+ > **Note:** Content displayed in the top 600 pixels of the page will be visible for the majority of users.
246
+
247
+
248
+ ### Base Unit
249
+
250
+ The base unit establishes the increment by which all elements and measurements are multiplied. This practice ensures consistency in the spacing and sizing of design elements.
251
+
252
+ > **Note:** The design system is based on a 6px unit.
253
+
254
+ The layout grid, spacing tokens, and nearly all visual elements and sizes adhere to multiples of six (6, 12, 18, 24, etc.), with only occasional exceptions.
255
+
256
+ | TOKEN | SIZE | USE FOR |
257
+ |-------|------|---------|
258
+ | SP1 | 6px | Spacing between components |
259
+ | SP2 | 12px | Spacing between components |
260
+ | SP3 | 18px | Spacing between components |
261
+ | SP4 | 24px | Spacing between components, layout spacing |
262
+ | SP5 | 30px | Layout spacing |
263
+ | SP6 | 36px | Layout spacing |
264
+ | SP7 | 42px | Layout spacing |
265
+ | SP8 | 48px | Layout spacing |
266
+ | SP10 | 54px | Layout spacing |
267
+ | SP11 | 60px | Layout spacing |
268
+
269
+
270
+ ### Layout Structure
271
+
272
+ To best design the layout for your app, understand:
273
+
274
+ 1. The core frame of the app (Application frame)
275
+ 2. The placement and alignment of each segment within the grid layout (Grid layout)
276
+ 3. The content to appear in the grid (Common layouts)
277
+
278
+ #### Application Frame
279
+
280
+ The dashboard app frame is used by the majority of Wix applications settings. Dashboard pages consist of 4 areas:
281
+
282
+ | AREA | USAGE |
283
+ |------|-------|
284
+ | 1. Global navigation (top bar) | General navigation at the top of a page which allows users to navigate between different environments. Full width container with a fixed height of 48px. |
285
+ | 2. Sidebar navigation | Local navigation of an environment. Container with a fixed width of 228px. |
286
+ | 3. Content area | Page content area with a width that's adaptive to screen size. |
287
+ | 4. Side panel (optional) | An optional panel that shows additional actions or content associated with the content of a page. Fixed width of 420px. Can either overlay the main content area or push it from the right side. |
288
+
289
+ **Side Panel Guidelines:**
290
+ - Let the side panel overlay main content when it contains supplementary actions or settings, such as data filters
291
+ - Push main content with the side panel when users must see the full context to continue
292
+
293
+
294
+ #### Grid Layout
295
+
296
+ The system uses a fluid grid layout with a fixed maximum width. It uses columns that scale and resize the content accordingly.
297
+
298
+ The grid is constructed from 3 elements:
299
+ - **Columns** - The design system uses a 12-column grid. Column width is fluid and changes according to the page width.
300
+ - **Gutters** - The gaps between the columns. Gutter width has a fixed value of 24px.
301
+ - **Margins** - By default, a page's content area has 48px side margins and a 48px bottom margin.
302
+
303
+ **Grid Specifications:**
304
+ - Minimum content area width: 864 pixels (each grid column is 50px wide)
305
+ - Maximum content area width: 1248px (each column is 82px wide)
306
+ - Wider screens maintain 1248px content width with side margins stretching to center content
307
+ - Use 24px gap between cards both vertically and horizontally
308
+
309
+
310
+ ### Common Layouts
311
+
312
+ Page layouts can be divided by intention into the following types:
313
+
314
+ #### 1. Form Layouts
315
+
316
+ Forms are pages that allow users to fill in data or edit existing data. Two variations:
317
+
318
+ - **2/3 layout with optional sidebar (8/4 column split)** - Provides flexibility to expose primary and secondary content at the same time
319
+ - **Full width (12 columns)** - Supports advanced product needs with complex structures
320
+
321
+ Both form page layouts include mandatory **Save** and **Cancel** actions in the header and footer areas.
322
+
323
+ **2/3 Layout Best Practices:**
324
+ - Use to expose primary and secondary content at the same time
325
+ - Keep the form easy to scan and comprehend
326
+ - Display a live content preview on the side (widget can be sticky)
327
+ - Use 8 columns for forms to keep text lines and input fields narrow for quicker reading
328
+ - Bring actions closer to related titles (e.g., toggle switches near settings)
329
+
330
+ **Full Width Layout Best Practices:**
331
+ - Use when a form includes complex structures such as tables
332
+ - Use for list items that contain many data columns
333
+
334
+ **Combining Layouts:**
335
+ - Avoid coast-to-coast inputs; keep inputs to 2/3 width of a card, or lay them out in two columns
336
+ - Use white space on the right side for content preview
337
+ - Use full width for tables with many columns and dividers that separate sections
338
+
339
+ > **Note:** A column is easy to read if it is wide enough to accommodate an average of 10 words per line.
340
+
341
+ #### 2. Display Layouts
342
+
343
+ Display pages showcase data or content without accepting input from users. They can contain minor actions such as data filtering.
344
+
345
+ **List (Table):**
346
+ - Tables display large data sets and provide users with a quick overview
347
+ - Use a 12-column layout for tables
348
+ - Enables users to manipulate and act on a data set
349
+
350
+ **List (Grid) Options:**
351
+ - 2 columns (6/6 split) - For items with lengthy descriptions
352
+ - 3 columns (4/4/4 split) - For visual items with multiple data types
353
+ - 4 columns (3/3/3/3 split) - For user-generated galleries and collections, reveals up to 50% more content above the fold than 4/4/4
354
+ - Custom - For mixed content needs
355
+
356
+ **Grid Selection Considerations:**
357
+ - Total amount of items to show
358
+ - Content to display in each list item
359
+ - What objects the list items reflect (match physical shapes when applicable)
360
+
361
+ **Dashboards:**
362
+ Display different types of data on a specific topic using a combination grid.
363
+
364
+ Column span recommendations:
365
+ - **3 or 4 columns** - For list items, previews, marketing, statistics, and charts
366
+ - **12 columns (full width)** - For tables and marketing content
367
+ - **8 columns** - For lists, tables with few data columns, setup wizards, and charts
368
+ - **6 columns** - For lists, tables with few data columns, and statistics
369
+
370
+ **Empty States:**
371
+ - Use full width layout for empty state of a page
372
+ - Indicates feature/product has no data yet, all data cleared, or not set up yet
373
+ - Include clear CTA indicating what to do to fill the page
374
+ - Can combine with other layout elements such as tabs, statistics widgets, or marketing cards
375
+
376
+ #### 3. Marketing Layouts
377
+
378
+ Marketing pages promote new products that site owners are not aware of yet. Built using the `<MarketingPageLayout/>` component split into 2 columns:
379
+
380
+ 1. Promo messaging
381
+ 2. Visual representation of product and features
382
+
383
+ Optional footer area can display features or testimonials list.
384
+
385
+ #### 4. Wizard Layouts
386
+
387
+ Wizard pages guide users through setting up a product or feature. They split complex forms into steps for easier completion.
388
+
389
+ **Entry Points:**
390
+ - A marketing page
391
+ - A marketing card
392
+ - The primary action of a page
393
+ - An empty state
394
+
395
+ > **Note:** Wizards must have a final destination. After completing all steps, users should end up on a relevant page: a dashboard, a details page, or any other relevant location.
396
+
397
+
398
+ ### Related WDS Components
399
+
400
+ - `<Page />` - Main page wrapper
401
+ - `<Layout />` - Grid layout container
402
+ - `<MarketingPageLayout />` - Marketing page wrapper
403
+ - `<Card />` - Content container with 24px gaps between cards
@@ -0,0 +1,205 @@
1
+
2
+ # Wix Dashboard Plugin Builder
3
+
4
+ Creates dashboard plugin extensions for Wix CLI applications. Dashboard plugins are interactive widgets that embed into predefined **slots** on dashboard pages managed by Wix first-party business apps (Wix Stores, Wix Bookings, Wix Blog, Wix eCommerce, etc.).
5
+
6
+ Dashboard plugins occupy the full width of their slot and maintain dynamic height based on content.
7
+
8
+
9
+ ## Quick Start Checklist
10
+
11
+ Follow these steps in order when creating a dashboard plugin:
12
+
13
+ 1. [ ] Identify the target slot ID — see [Slots Reference](dashboard-plugin/SLOTS.md)
14
+ 2. [ ] Create plugin folder: `src/extensions/dashboard/plugins/<plugin-name>/`
15
+ 3. [ ] Create `<plugin-name>.extension.ts` with `extensions.dashboardPlugin()` and unique UUID
16
+ 4. [ ] Create `<plugin-name>.tsx` with React component wrapped in `WixDesignSystemProvider`
17
+ 5. [ ] Update `src/extensions.ts` to import and use the new extension
18
+
19
+ ## Architecture
20
+
21
+ Dashboard plugins operate through two mechanisms:
22
+
23
+ 1. **Visual Integration** — Embedding plugin UI inside a supported dashboard page slot
24
+ 2. **Logical Integration** — Implementing communication between the plugin and the host page's data via `observeState()`
25
+
26
+ ## Files and Code Structure
27
+
28
+ Dashboard plugins live under `src/extensions/dashboard/plugins/`. Each plugin has its own folder.
29
+
30
+ ```
31
+ src/extensions/dashboard/plugins/
32
+ └── <plugin-name>/
33
+ ├── <plugin-name>.extension.ts # Builder configuration
34
+ └── <plugin-name>.tsx # React component
35
+ ```
36
+
37
+ > **Note:** This is the default folder structure created by the CLI. You can move these files to any location within the `src/` folder and update the references in your `extension.ts` file.
38
+
39
+ ## Plugin Builder Configuration
40
+
41
+ ### File: `<plugin-name>.extension.ts`
42
+
43
+ ```typescript
44
+ import { extensions } from "@wix/astro/builders";
45
+
46
+ export const dashboardpluginMyPlugin = extensions.dashboardPlugin({
47
+ id: "{{GENERATE_UUID}}",
48
+ title: "My Dashboard Plugin",
49
+ extends: "<SLOT_ID>",
50
+ component: "./extensions/dashboard/plugins/my-plugin/my-plugin.tsx",
51
+ });
52
+ ```
53
+
54
+ **CRITICAL: UUID Generation**
55
+
56
+ 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"`.
57
+
58
+ ### Builder Fields
59
+
60
+ | Field | Type | Description |
61
+ |-------|------|-------------|
62
+ | `id` | string | Unique plugin ID (GUID). Must be unique across all extensions in the project. |
63
+ | `title` | string | Plugin title. Used to refer to the plugin in the project dashboard. |
64
+ | `extends` | string | Slot ID of the dashboard page hosting the plugin. See [Slots Reference](dashboard-plugin/SLOTS.md). |
65
+ | `component` | string | Relative path to the plugin content component (`.tsx` file). |
66
+
67
+ ### The `extends` Field
68
+
69
+ The `extends` field specifies which dashboard page slot hosts your plugin. Each Wix business app exposes slots on its dashboard pages. You must provide the exact slot ID.
70
+
71
+ **Important:** Some slots with the same ID appear on different pages within the dashboard. If you create a plugin for a slot that exists on multiple pages, the plugin is displayed on all of those pages.
72
+
73
+ For the complete list of available slot IDs, see [Slots Reference](dashboard-plugin/SLOTS.md).
74
+
75
+ ## Plugin Component
76
+
77
+ ### File: `<plugin-name>.tsx`
78
+
79
+ The plugin component is a React component that renders within the dashboard page slot.
80
+
81
+ ```typescript
82
+ import type { FC } from "react";
83
+ import { WixDesignSystemProvider, Card, Text } from "@wix/design-system";
84
+ import "@wix/design-system/styles.global.css";
85
+
86
+ const Plugin: FC = () => {
87
+ return (
88
+ <WixDesignSystemProvider features={{ newColorsBranding: true }}>
89
+ <Card>
90
+ <Card.Header title="My Plugin" />
91
+ <Card.Divider />
92
+ <Card.Content size="medium">
93
+ <Text>Plugin content goes here.</Text>
94
+ </Card.Content>
95
+ </Card>
96
+ </WixDesignSystemProvider>
97
+ );
98
+ };
99
+
100
+ export default Plugin;
101
+ ```
102
+
103
+ ### Available Resources in Plugin Components
104
+
105
+ - **React** — Component logic and state management
106
+ - **Wix SDK** — Access Wix business solutions and site data
107
+ - **Wix Dashboard SDK** (`@wix/dashboard`) — Interact with the dashboard page's data passed to the slot
108
+ - **Wix Design System** (`@wix/design-system`) — Native-looking React components matching Wix's own dashboard UI
109
+
110
+ ## Interacting with Dashboard Data
111
+
112
+ Use `observeState()` from the Dashboard SDK to receive data from the host dashboard page:
113
+
114
+ ```typescript
115
+ import { dashboard } from "@wix/dashboard";
116
+ import { useEffect, useState } from "react";
117
+
118
+ const Plugin: FC = () => {
119
+ const [params, setParams] = useState<Record<string, unknown>>({});
120
+
121
+ useEffect(() => {
122
+ dashboard.observeState((componentParams) => {
123
+ setParams(componentParams);
124
+ });
125
+ }, []);
126
+
127
+ return (
128
+ <WixDesignSystemProvider features={{ newColorsBranding: true }}>
129
+ <Card>
130
+ <Card.Content size="medium">
131
+ <Text>Received data: {JSON.stringify(params)}</Text>
132
+ </Card.Content>
133
+ </Card>
134
+ </WixDesignSystemProvider>
135
+ );
136
+ };
137
+ ```
138
+
139
+ ### Typed Props from Host Apps
140
+
141
+ Some Wix apps expose typed interfaces for their slot parameters. Import them from the app's dashboard package:
142
+
143
+ ```typescript
144
+ import type { plugins } from "@wix/blog/dashboard";
145
+
146
+ type Props = plugins.BlogPosts.PostsBannerParams;
147
+
148
+ const Plugin: FC<Props> = (props) => {
149
+ // props are typed according to the Blog Posts slot contract
150
+ };
151
+ ```
152
+
153
+ > **Note:** Typed props availability varies by Wix app. Consult the specific app's SDK documentation. Not all slots provide typed parameter interfaces.
154
+
155
+ ## Extension Registration
156
+
157
+ **Extension registration is MANDATORY and has TWO required steps.**
158
+
159
+ ### Step 1: Create Plugin-Specific Extension File
160
+
161
+ Each dashboard plugin requires an `<plugin-name>.extension.ts` file in its folder. See [Plugin Builder Configuration](#plugin-builder-configuration) above.
162
+
163
+ ### Step 2: Register in Main Extensions File
164
+
165
+ **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`.
166
+
167
+ **Without completing Step 2, the dashboard plugin will not appear on the dashboard page.**
168
+
169
+ ## Sizing Behavior
170
+
171
+ - Dashboard plugins take the **full width** of their slot
172
+ - **Height** adjusts dynamically based on content within slot boundaries
173
+ - When using Dashboard SDK or dashboard-react SDK, dimensions change dynamically based on contents
174
+
175
+ ## Troubleshooting
176
+
177
+ | Symptom | Cause | Fix |
178
+ |---------|-------|-----|
179
+ | Plugin not appearing on dashboard page | Missing registration | Import and `.use()` in `src/extensions.ts` |
180
+ | Plugin not appearing on dashboard page | Wrong slot ID | Verify `extends` field matches a valid slot ID from [Slots Reference](dashboard-plugin/SLOTS.md) |
181
+
182
+ ## Dashboard-Plugin-specific Conventions
183
+
184
+ - The `extends` field MUST contain a valid slot ID from a Wix business app — do NOT invent slot IDs.
185
+
186
+ ## Examples
187
+
188
+ ### Blog Posts Banner Plugin
189
+
190
+ **Request:** "Create a plugin for the Wix Blog posts page that shows a promotional banner"
191
+
192
+ **Output:** Plugin targeting slot `46035d51-2ea9-4128-a216-1dba68664ffe` (Blog Posts page) with a Card component displaying promotional content, using `observeState()` to access blog post data.
193
+
194
+ ### Bookings Staff Calendar Widget
195
+
196
+ **Request:** "Add a plugin to the Wix Bookings staff page that shows weekly availability"
197
+
198
+ **Output:** Plugin targeting slot `261e84a2-31d0-4258-a035-10544d251108` (Bookings Staff page) with a schedule display component, using `observeState()` to receive staff data.
199
+
200
+ ### Order Details Plugin
201
+
202
+ **Request:** "Create a plugin on the eCommerce order page showing fulfillment status"
203
+
204
+ **Output:** Plugin targeting slot `cb16162e-42aa-41bd-a644-dc570328c6cc` (eCommerce Order page) with status badges and fulfillment details, using `observeState()` to access order data.
205
+