@wix/agent-skills 1.18.2 → 1.19.1

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>
-  );
-}

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

@@ -1,130 +0,0 @@
-// The full product detail surface: gallery, price, option/modifier picker, quantity,
-// add-to-cart — styled from the @theme tokens. Mount as-is (Astro: an island with the
-// server-fetched `initial` product; SPA: pass the `slug`). All selection→variant logic lives
-// in useProductDetail — never bypass it to add a product with options.
-import { useState } from "react";
-import { useProductDetail } from "../../hooks/storefront/useProductDetail";
-import VariantPicker from "./VariantPicker";
-
-export interface ProductDetailViewProps {
-  /** Server-fetched product (Astro/Next SSR). */
-  initial?: import("../../wix/storefront/types").ProductDetail | null;
-  /** SPA alternative: fetch by slug on mount. */
-  slug?: string;
-}
-
-export default function ProductDetailView({ initial, slug }: ProductDetailViewProps) {
-  const {
-    product,
-    notFound,
-    optionGroups,
-    selectOption,
-    modifierValues,
-    setModifier,
-    price,
-    compareAtPrice,
-    canAdd,
-    quantity,
-    setQuantity,
-    add,
-    adding,
-    error,
-  } = useProductDetail({ initial, slug });
-  const [imageIndex, setImageIndex] = useState(0);
-
-  if (notFound)
-    return <p className="py-16 text-center text-muted-foreground">This product doesn't exist (anymore).</p>;
-  if (!product) return <div className="aspect-square max-w-md animate-pulse rounded-xl bg-secondary" />;
-
-  const soldOut = product.availability === "OUT_OF_STOCK" && !product.preorder;
-  const mainImage = product.gallery[imageIndex] ?? product.imageUrl;
-
-  return (
-    <div className="grid gap-10 md:grid-cols-2">
-      <div>
-        <div className="aspect-square overflow-hidden rounded-xl bg-secondary">
-          {mainImage && <img src={mainImage} alt={product.name} className="h-full w-full object-cover" />}
-        </div>
-        {product.gallery.length > 1 && (
-          <div className="mt-3 flex flex-wrap gap-2">
-            {product.gallery.map((url, i) => (
-              <button
-                key={url}
-                type="button"
-                aria-label={`Image ${i + 1}`}
-                onClick={() => setImageIndex(i)}
-                className={`h-16 w-16 overflow-hidden rounded-md border-2 transition-colors ${
-                  i === imageIndex ? "border-primary" : "border-transparent hover:border-border"
-                }`}
-              >
-                <img src={url} alt="" className="h-full w-full object-cover" />
-              </button>
-            ))}
-          </div>
-        )}
-      </div>
-
-      <div>
-        <h1 className="text-2xl font-semibold tracking-tight">{product.name}</h1>
-        <p className="mt-2 flex items-baseline gap-3">
-          <span className="text-xl font-medium">{price}</span>
-          {compareAtPrice && <span className="text-base text-muted-foreground line-through">{compareAtPrice}</span>}
-        </p>
-        {soldOut && <p className="mt-2 text-sm font-medium text-red-600">Out of stock</p>}
-        {product.preorder && <p className="mt-2 text-sm text-muted-foreground">Available for pre-order</p>}
-
-        {product.descriptionHtml && (
-          // plainDescription is HTML (despite the name) — render it, don't print it.
-          <div
-            className="mt-4 space-y-2 text-sm leading-relaxed text-muted-foreground [&_strong]:font-semibold [&_strong]:text-foreground"
-            dangerouslySetInnerHTML={{ __html: product.descriptionHtml }}
-          />
-        )}
-
-        <div className="mt-6">
-          <VariantPicker
-            optionGroups={optionGroups}
-            selectOption={selectOption}
-            modifiers={product.modifiers}
-            modifierValues={modifierValues}
-            setModifier={setModifier}
-          />
-        </div>
-
-        {!soldOut && (
-          <div className="mt-2 flex items-center gap-3">
-            <div className="inline-flex items-center gap-3 rounded-full border border-border px-3 py-2">
-              <button
-                type="button"
-                aria-label="Decrease quantity"
-                disabled={quantity <= 1}
-                onClick={() => setQuantity(quantity - 1)}
-                className="px-1 text-base disabled:opacity-40"
-              >
-                −
-              </button>
-              <span className="text-sm tabular-nums">{quantity}</span>
-              <button
-                type="button"
-                aria-label="Increase quantity"
-                onClick={() => setQuantity(quantity + 1)}
-                className="px-1 text-base"
-              >
-                +
-              </button>
-            </div>
-            <button
-              type="button"
-              disabled={!canAdd || adding}
-              onClick={() => add().catch(() => {})}
-              className="rounded-full bg-primary px-8 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
-            >
-              {adding ? "Adding…" : canAdd ? "Add to cart" : "Select options"}
-            </button>
-          </div>
-        )}
-        {error && <p className="mt-3 text-sm text-red-600">{error}</p>}
-      </div>
-    </div>
-  );
-}

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

@@ -1,48 +0,0 @@
-// Listing grid with loading skeletons and an honest empty state — a REFERENCE layout on the
-// @theme tokens. Keep the states (they're correct); choosing a grid arrangement that fits the
-// brand is encouraged. Never mock products: empty catalog → the empty state.
-import type { ComponentType } from "react";
-import type { ProductSummary } from "../../wix/storefront/types";
-import ProductCard, { type ProductCardProps } from "./ProductCard";
-
-export interface ProductGridProps {
-  /** null → loading skeletons; [] → the empty state. */
-  products: ProductSummary[] | null;
-  emptyMessage?: string;
-  productHref?: ProductCardProps["productHref"];
-  LinkComponent?: ProductCardProps["LinkComponent"];
-  /** Swap in your own tile (built on ProductSummary) without re-doing the states. */
-  CardComponent?: ComponentType<ProductCardProps>;
-}
-
-export default function ProductGrid({
-  products,
-  emptyMessage = "No products yet — check back soon.",
-  productHref,
-  LinkComponent,
-  CardComponent = ProductCard,
-}: ProductGridProps) {
-  if (products === null) {
-    return (
-      <div className="grid grid-cols-2 gap-x-5 gap-y-8 sm:grid-cols-3 lg:grid-cols-4" aria-busy="true">
-        {Array.from({ length: 8 }, (_, i) => (
-          <div key={i}>
-            <div className="aspect-square animate-pulse rounded-lg bg-secondary" />
-            <div className="mt-3 h-3.5 w-3/4 animate-pulse rounded bg-secondary" />
-            <div className="mt-2 h-3.5 w-1/3 animate-pulse rounded bg-secondary" />
-          </div>
-        ))}
-      </div>
-    );
-  }
-  if (products.length === 0) {
-    return <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>;
-  }
-  return (
-    <div className="grid grid-cols-2 gap-x-5 gap-y-8 sm:grid-cols-3 lg:grid-cols-4">
-      {products.map((p) => (
-        <CardComponent key={p.id} product={p} productHref={productHref} LinkComponent={LinkComponent} />
-      ))}
-    </div>
-  );
-}