@wix/agent-skills 1.19.0 → 1.19.2

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js

@@ -40,17 +40,24 @@ const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
  * Throws on out-of-stock so the buyer can't reach checkout with an unbuyable line.
  * Full catalogReference reference: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md
  *
+ * A pre-order variant (inventoryStatus.preorderEnabled, out of stock) is added with `preorder: true`;
+ * a recurring subscription plan with its `subscriptionOptionId` (omit it for a one-time purchase).
+ * The two may coexist.
+ *
  * @param {string} catalogItemId    Product GUID (product.id).
  * @param {string} [variantId]      variantsInfo.variants[].id — required for products with variants.
  * @param {number} [quantity]
- * @param {{ modifierChoices?: Record<string,string>, customTextFields?: Record<string,string> }} [extras]
+ * @param {{ modifierChoices?: Record<string,string>, customTextFields?: Record<string,string>,
+ *           subscriptionOptionId?: string, preorder?: boolean }} [extras]
  * @returns {Promise<object>} Updated cart.
  */
-export async function addToCart(catalogItemId, variantId, quantity = 1, { modifierChoices, customTextFields } = {}) {
+export async function addToCart(catalogItemId, variantId, quantity = 1, { modifierChoices, customTextFields, subscriptionOptionId, preorder } = {}) {
   const catalogReferenceOptions = {};
   if (variantId) catalogReferenceOptions.variantId = variantId;
   if (modifierChoices && Object.keys(modifierChoices).length) catalogReferenceOptions.options = modifierChoices;
   if (customTextFields && Object.keys(customTextFields).length) catalogReferenceOptions.customTextFields = customTextFields;
+  if (subscriptionOptionId) catalogReferenceOptions.subscriptionOptionId = subscriptionOptionId;
+  if (preorder) catalogReferenceOptions.preOrderRequested = true;
 
   const catalogReference = { appId: STORES_APP_ID, catalogItemId };
   if (Object.keys(catalogReferenceOptions).length) catalogReference.options = catalogReferenceOptions;
@@ -92,8 +99,30 @@ export async function getCurrentCart() {
   }
 }
 
+/**
+ * Estimate the current cart's totals — the ONLY source of the after-discount subtotal and the
+ * cart-level discount. Line prices already carry item-level discounts; delivery and tax resolve at
+ * checkout unless asked for, so never invent them. Returns null when there is no cart or the
+ * estimate fails (a display nicety — the cart itself stays valid).
+ * https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/estimate-current-cart.md
+ * @returns {Promise<{ priceSummary: { subtotal: object, discount: object, total: object } }|null>}
+ *   priceSummary amounts are ConvertedMoney { amount, convertedAmount } — format like line prices.
+ */
+export async function estimateCurrentCart() {
+  try {
+    const res = await wixApiRequest("/ecom/v2/carts/current/estimate", { method: "POST", body: {} });
+    return res?.summary ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Start the hosted checkout for the current cart and return its URL.
+ * This is the shopper's CURRENT cart. A "Buy now" that skips the cart needs a standalone cart
+ * (POST /ecom/v2/carts) handed to the redirect session — it must never append to or replace the
+ * current cart. Not shipped here; verify the redirect session accepts a standalone cart id under
+ * the visitor token before adding it.
  * In Cart V2 the cart id IS the checkout id — there is no separate checkout-creation call; the
  * redirect session is created straight from the current cart's id.
  * Throws on empty cart, unavailable lines, or a missing redirect URL.

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-catalog.js

@@ -13,8 +13,13 @@ import { wixApiRequest } from "./wix-client.js";
  *   actualPriceRange.minValue.formattedAmount {string} — lowest price with currency symbol,
  *   actualPriceRange.maxValue.formattedAmount {string} — highest price with currency symbol,
  *   compareAtPriceRange.minValue.formattedAmount {string} — strikethrough price (present when on sale),
- *   actualPriceRange/compareAtPriceRange .minValue.amount {string} — the same figures unformatted
- *     ("129.00"). Use these for arithmetic: a percent-off badge can't be computed from "€129.00",
+ *   actualPriceRange/compareAtPriceRange .minValue.amount {string} — the same figures unformatted.
+ *     Never compute a percent-off or "you save" claim from them: a range's minimum says nothing about
+ *     the variant the buyer picks. The price the buyer pays comes from sellingPrice() below.
+ *   variantSummary.minPriceVariant {object} — the lowest-priced visible variant (MIN_PRICE_VARIANT):
+ *     { id, price: { actualPrice, compareAtPrice?, priceAfterDiscount? } } — a card's price, and the
+ *     variantId for a direct add on a product with no options,
+ *   discountInfo.discountRuleNames {string[]} — automatic-discount names (DISCOUNT_INFO), product level,
  *   inventory.availabilityStatus {string} — "IN_STOCK"|"OUT_OF_STOCK"|"PARTIALLY_OUT_OF_STOCK",
  *   inventory.preorderStatus {string} — "ENABLED"|"DISABLED". ENABLED + OUT_OF_STOCK is a pre-order,
  *     which is buyable — label it "Pre-order" rather than "Sold out",
@@ -23,8 +28,9 @@ import { wixApiRequest } from "./wix-client.js";
  *     getProductBySlug call per product,
  *   ribbon {object} — { id, name } merchant-set badge: "New", "Sale", "Best Seller". This is the
  *     catalogue's own label, so prefer it over anything derived — a "new" badge computed from
- *     createdDate flags every product at once right after seeding,
- *   additionalRibbons {array} — further { id, name } badges,
+ *     createdDate flags every product at once right after seeding. A ribbon is a LABEL: a "Sale"
+ *     ribbon is not proof of a lower price, and a compareAtPrice does not earn a ribbon,
+ *   additionalRibbons {array} — up to four further { id, name } badges. Render ALL of them,
  *   createdDate / updatedDate {string} — ISO timestamps,
  *   variantSummary.variantCount {number} — how many variants exist, without fetching them,
  *   options {array} — product options e.g. Size, Color:
@@ -45,9 +51,11 @@ import { wixApiRequest } from "./wix-client.js";
  *     dangerouslySetInnerHTML; strip tags only for plain-text contexts (meta description, teaser),
  *   variantsInfo.variants {array} — returned only by getProductBySlug:
  *     [{ id, visible, choices [{ optionChoiceIds: { optionId, choiceId } }],
- *        price: { actualPrice, compareAtPrice }, media, inventoryStatus: { inStock } }]
+ *        price: { actualPrice, compareAtPrice?, priceAfterDiscount? }, media,
+ *        inventoryStatus: { inStock, preorderEnabled } }]
  *     To resolve a buyer's option selections to a variantId: find the variant whose choices
  *     match all selected { optionId, choiceId } pairs, then pass variant.id to addToCart.
+ *     A variant is buyable when inStock OR preorderEnabled (a preorder add carries preOrderRequested).
  *
  * Category: { id, name, slug, visible, description, image, itemCounter, parentCategory.id }
  *   NB: queryCategories includes the auto-created system category { slug: "all-products" } —
@@ -55,6 +63,20 @@ import { wixApiRequest } from "./wix-client.js";
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories
  */
 
+/**
+ * The price the buyer pays, and the price to strike — exact precedence, shared by cards and the PDP.
+ * An automatic discount (priceAfterDiscount, present only when DISCOUNT_INFO is requested) wins and
+ * strikes the regular actualPrice; otherwise actualPrice with the merchant's compareAtPrice as the
+ * "was". `!== undefined` on purpose: a discounted price of 0 is a real price.
+ * @param {{ actualPrice?: object, compareAtPrice?: object, priceAfterDiscount?: object }} [price]
+ *   variant.price, or variantSummary.minPriceVariant.price. Each is { amount, formattedAmount }.
+ * @returns {{ current: object|undefined, original: object|undefined }} render .formattedAmount
+ */
+export function sellingPrice(price) {
+  if (price?.priceAfterDiscount !== undefined) return { current: price.priceAfterDiscount, original: price.actualPrice };
+  return { current: price?.actualPrice, original: price?.compareAtPrice };
+}
+
 // Search Products supports server-side sort/filter before cursor paging:
 // https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
 export const CATALOG_SORTS = {
@@ -108,7 +130,9 @@ export async function searchProducts({ limit = 100, cursor, categoryId, sort = "
   }
   const res = await wixApiRequest("/stores/v3/products/search", {
     method: "POST",
-    body: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"], search: query },
+    // MIN_PRICE_VARIANT + DISCOUNT_INFO → variantSummary.minPriceVariant with its discounted price:
+    // the card's price and the direct-add variantId, without a per-product fetch.
+    body: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"], search: query },
   });
   return { products: res?.products ?? [], nextCursor: res?.pagingMetadata?.cursors?.next ?? null };
 }
@@ -137,6 +161,7 @@ export async function getProductBySlug(slug) {
         "MEDIA_ITEMS_INFO",
         "PRODUCT_CHOICES_MEDIA_REFERENCES",
         "VARIANT_OPTION_CHOICE_NAMES",
+        "DISCOUNT_INFO", // variant price.priceAfterDiscount + discountInfo.discountRuleNames
       ],
     },
   });

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

@@ -1,80 +0,0 @@
-# Collection Toolkit — what to reach for, per user need
-
-[UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md) says what a dashboard must do for the person using it. This file says which component does it, so the stage list resolves to real names instead of a hand-rolled approximation.
-
-Everything below is a real name in the installed `@wix/patterns`. Confirm the props before writing JSX by reading its doc from `dist/docs/index.json` — and if a name is missing from `dist/dts-bundle/index.json`, the installed version is older than this file; work from that inventory, not from memory.
-
-> **The two requirements below are not suggestions.** A page that renders a filtered table and nothing else is the single most common failure of a generated dashboard: it answers "what are all the records" and nothing about how many, which one needs attention, or why something happened. Measured runs produce exactly that page unless the requirement is stated.
->
-> 1. **A dashboard that reports on records shows aggregate numbers**, not only rows.
-> 2. **A dashboard whose rows represent real business records lets the user open one**, unless the prompt is explicitly a report or an export.
-
-## Understand — the aggregate
-
-| Need | Component |
-| --- | --- |
-| Totals, counts, status breakdown above the table | `SummaryBar` |
-| Which subset the numbers describe | wire each metric to the collection's filter state so the count follows the filters |
-
-`SummaryBar` sits inside the page shell, above the collection. Compute the values from the same query the table uses, or a count query alongside it — a metric that disagrees with the visible rows is worse than no metric.
-
-## Focus — narrowing
-
-| Need | Component |
-| --- | --- |
-| Free-text search | `CollectionSearch` |
-| The filter bar itself | `CollectionToolbarFilters` |
-| Pick several values from a known list | `MultiSelectCheckboxFilter`, `MultiInlineCheckboxFilter`, `MultiAutoInlineCheckboxFilter` |
-| Pick one value | `SingleSelectFilter`, `RadioGroupFilter`, `TabsFilter` |
-| Values fetched from an API, not a fixed list | `MultiSelectCollectionFilter` + `useFilterCollection` |
-| Type-ahead over many values | `AutoCompleteFilter` |
-| Date or number ranges | `DateRangeFilter`, `NumberRangeFilter` |
-| Comparison operators (greater than, contains) | `OperatorFilterPicker` + `operatorFilter` |
-| The filter's state object | `idNameArrayFilter`, `stringFilter`, `stringsArrayFilter`, `arrayFilter`, `dateRangeFilter`, `customFilter` |
-| A fixed in-memory option list for a filter | `useStaticListFilterCollection` |
-| Sorting | `Sortable Columns`, `MultiLevelSorting` |
-
-**Read the index once, then go straight to files.** `dist/dts-bundle/index.json` answers every name in this table in a single read — resolve it once per session and keep it, rather than re-reading it per lookup. Each entry names the exact file to open next.
-
-**A factory or hook's doc is often empty where its signature should be** — the props table is generated for components, so `idNameArrayFilter`'s doc shows an `## API` heading with nothing under it. Its bundle has the signature: `<T extends { id: string; name: string }>(params?) => ArrayFilterState<T>`. That holds for every `use…` hook and every `…Filter` factory in the table above, and it is the difference between knowing a name and being able to call it — so for these, read the bundle the index names, not the doc.
-
-**A filter must narrow the result.** Declare it in the collection hook's `filters` map and read it inside `fetchData`, so the value reaches the query. Filter UI that renders but never changes the rows is a defect that looks like a feature — and it is the failure mode these components exist to prevent.
-
-## Investigate — opening one record
-
-| Surface | Use when | Built from |
-| --- | --- | --- |
-| **Side panel** | Inspect or lightly edit one record while keeping the filtered list on screen. The V1 default for review dashboards. | WDS `SidePanel` — patterns has no side panel |
-| **Entity page** | Multi-section detail, editing, history, or a link someone can share. | `EntityPage` + `useEntityPage`, reached with `usePatternsNavigate().navigateToEntityPage`, form state from `@wix/patterns/form`. The call itself: [ENTITY_PAGE_TOOLKIT.md](ENTITY_PAGE_TOOLKIT.md) |
-| **Expanded row** | A couple of extra fields, no separate workspace needed. | The collection's own row expansion |
-| **Picker / bulk confirm** | Choosing records, or confirming an action on many. | `PickerModal` + `usePickerModal`, `bulkActionModal` |
-
-A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md); for the create route itself — registering it, and the four params that differ from the edit call — [ENTITY_PAGE_TOOLKIT.md § Create route](ENTITY_PAGE_TOOLKIT.md#create-route). A row the user cannot open is the second most common failure after the missing aggregate.
-
-**Form state on an entity page** comes from `@wix/patterns/form` — `useForm` for the form, `useController` for a single field. That subpath re-exports `@wix/bex-core/form`, which wraps `react-hook-form`, so its API is react-hook-form's and only a handful of its names appear in the patterns docs: `FieldValues`, `ControllerProps` and most of the rest are documented by react-hook-form, not here. `Read <pkgRoot>/dist/dts-bundle/exports/form.d.ts` to see what the subpath actually gives you.
-
-## Act and confirm
-
-| Need | Component |
-| --- | --- |
-| Page header actions | `PrimaryActions`, `SecondaryActions`, `More Actions` — passed to the page header's `primaryAction`, `secondaryActions` and `moreActions` slots |
-| Table toolbar button | `PrimaryActionButton` — the table's own `primaryActionButton` prop |
-| Row actions | `deleteSecondaryAction`, in the row's `actionCell` |
-| Acting on a multi-row selection | `MultiBulkActionToolbar`, `bulkActionModal` |
-| Immediate feedback, then reconcile | `useOptimisticActions(state.collection)` ✅ — not `useOptimisticActions(state)` ❌: `useTableCollection()` returns `TableState<T, F>`, and the hook takes the `CollectionState<T, F>` that state exposes as `state.collection`. Returns `CollectionOptimisticActions` |
-| A banner above the table | `TableTopNotification` |
-
-## The states that are not the happy path
-
-| State | Component |
-| --- | --- |
-| Collection is genuinely empty | `CollectionEmptyState` |
-| Filters or search matched nothing | `CollectionNoResultsState` |
-| Feature needs a paid plan | `CollectionPremiumEmptyState` |
-| Load failed | the collection state's error handling — give the user a way to retry |
-
-Empty and no-results are different messages: one means "add your first record", the other means "loosen the filters". Shipping only the first makes a working filter look broken.
-
-## Export
-
-`ExportButton` (its doc is `ExportTo`) for CSV and similar. Reach for it when the prompt mentions exporting, downloading, or sending records elsewhere.

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

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

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

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

package/skills/wix-headless-fast/references/storefront/app/components/storefront/ProductCard.tsx

@@ -1,100 +0,0 @@
-// Grid tile — a REFERENCE implementation over the ProductSummary DTO. Complete and correct
-// (badges, sale price, hover image, quick-add); styled entirely from the @theme tokens via
-// Tailwind utilities. Designing your own card on the same DTO is encouraged.
-import type { ComponentType, ReactNode } from "react";
-import type { ProductSummary } from "../../wix/storefront/types";
-import { useCart } from "../../hooks/storefront/useCart";
-
-export interface LinkLikeProps {
-  href: string;
-  className?: string;
-  children?: ReactNode;
-}
-
-export interface ProductCardProps {
-  product: ProductSummary;
-  /** Route pattern for detail pages; default matches the shipped /products/[slug] page. */
-  productHref?: (slug: string) => string;
-  /** Router-specific link (react-router Link, next/link); defaults to a plain <a>. */
-  LinkComponent?: ComponentType<LinkLikeProps>;
-}
-
-const PlainLink = ({ href, className, children }: LinkLikeProps) => (
-  <a href={href} className={className}>
-    {children}
-  </a>
-);
-
-export default function ProductCard({
-  product,
-  productHref = (slug) => `/products/${slug}`,
-  LinkComponent = PlainLink,
-}: ProductCardProps) {
-  const { addToCart, busy } = useCart();
-  const soldOut = product.availability === "OUT_OF_STOCK" && !product.preorder;
-  const priceLabel =
-    product.maxPrice && product.maxPrice !== product.price
-      ? `${product.price} – ${product.maxPrice}`
-      : product.price;
-
-  return (
-    <div className="group">
-      <LinkComponent href={productHref(product.slug)} className="block no-underline">
-        <div className="relative aspect-square overflow-hidden rounded-lg bg-secondary">
-          {product.imageUrl && (
-            <img
-              src={product.imageUrl}
-              alt={product.name}
-              loading="lazy"
-              className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
-            />
-          )}
-          {product.hoverImageUrl && (
-            <img
-              src={product.hoverImageUrl}
-              alt=""
-              aria-hidden="true"
-              loading="lazy"
-              className="absolute inset-0 h-full w-full object-cover opacity-0 transition-opacity duration-300 group-hover:opacity-100"
-            />
-          )}
-          {product.ribbon && (
-            <span className="absolute left-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">
-              {product.ribbon}
-            </span>
-          )}
-          {soldOut && (
-            <span className="absolute right-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-muted-foreground backdrop-blur">
-              Sold out
-            </span>
-          )}
-          {product.preorder && (
-            <span className="absolute right-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">
-              Pre-order
-            </span>
-          )}
-        </div>
-        <p className="mt-3 text-sm font-medium text-foreground">{product.name}</p>
-        <p className="mt-0.5 flex items-baseline gap-2 text-sm">
-          <span className="text-foreground">{priceLabel}</span>
-          {product.compareAtPrice && (
-            <span className="text-muted-foreground line-through">{product.compareAtPrice}</span>
-          )}
-        </p>
-        {product.optionsSummary && (
-          <p className="mt-0.5 text-xs text-muted-foreground">{product.optionsSummary}</p>
-        )}
-      </LinkComponent>
-      {product.quickAddable && (
-        <button
-          type="button"
-          disabled={busy}
-          onClick={() => addToCart(product.id).catch(() => {})}
-          className="mt-2 rounded-full border border-border px-4 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-secondary disabled:opacity-50"
-        >
-          Add to cart
-        </button>
-      )}
-    </div>
-  );
-}