@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,79 @@
+# 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` |
+
+**Ask for several names at once.** `docs`, `types` and `exports` all take a list — `types ComputedQuery OffsetQuery RangeItem`, `exports page form router` — and each call is a full model turn, so five one-name calls cost five turns for one call's worth of answer. `exports` with no argument lists the 31 entry points; that is a one-off orientation, not something to re-run.
+
+**A factory or hook's doc is often empty where its signature should be** — `docs idNameArrayFilter` prints an `## API` heading with nothing under it, because the props table only exists for components. Ask `types idNameArrayFilter` instead and you get the signature: `<T extends { id: string; name: string }>(params?) => ArrayFilterState<T>`. That applies to every `use…` hook and every `…Filter` factory in the table above, and it is the difference between knowing the name and being able to call it.
+
+**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). 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 |
+| --- | --- |
+| Row actions | `PrimaryActions`, `SecondaryActions`, `More Actions`, `deleteSecondaryAction` |
+| Page-level button | `PrimaryPageButton`, `PrimaryActionButton` |
+| Acting on a multi-row selection | `MultiBulkActionToolbar`, `bulkActionModal` |
+| Immediate feedback, then reconcile | `useOptimisticActions`, `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

@@ -0,0 +1,73 @@
+# 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: '/shifts',
+});
+```
+
+`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`, `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 has an empty API section, 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.
+
+## 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` |
+| Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
+| The fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
+
+`@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.
+
+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

@@ -0,0 +1,52 @@
+# Reading `@wix/patterns` Bundles and Docs
+
+> **Scope.** You are here because a lookup in `dist/dts-bundle/index.json` or
+> `dist/docs/index.json` gave you an entry and you are about to open the file it names. Getting to that index in the first
+> place — 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.
+
+## Types the docs don't cover
+
+The docs cover components and props, not 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 and the stub names where to find it.
+
+A handful of names carry `"status": "unreachable"` 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.
+
+## 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.

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

@@ -0,0 +1,184 @@
+# Dashboard UX Success Model
+
+What makes a generated dashboard page actually *succeed* for the person using it. Use this to turn a vague prompt ("help me manage order exceptions") into concrete requirements, and as the checklist before calling a dashboard done.
+
+Ported from the FeatureVibe dashboard product doc.
+
+> **North Star.** A successful dashboard helps a site owner or collaborator **understand what matters, complete the intended task, and trust the result**. It fulfills the user's prompt through a clear workflow, the right presentation, and trustworthy business data.
+
+This file is about *what to build*. For *how* to build it, see [WDS_LAYOUT.md](WDS_LAYOUT.md) for content layout and [DASHBOARD_PAGE.md](../DASHBOARD_PAGE.md) for the `@wix/patterns` → `@wix/design-system` component order — the workflow stages below are user needs, not an excuse to hand-roll shells, tables, or filter bars.
+
+
+## The Success Model
+
+A generated dashboard succeeds across three connected dimensions.
+
+| Success dimension | What must be true |
+|---|---|
+| Workflow success | The dashboard supports a complete journey from understanding to a confirmed outcome. |
+| Presentation success | Information is shown clearly and in the format that best supports the task. |
+| Data success | Information is accurate and consistent, including when it comes from multiple sources. |
+
+
+## The Workflow Journey
+
+The prompt defines the outcome. The stages define the journey from understanding the situation to confirming the result. They are **user needs**, not necessarily separate screens or a rigid sequence.
+
+| Stage | User outcome |
+|---|---|
+| **Understand** | Know the current situation. |
+| **Focus** | Recognize what matters or requires attention. |
+| **Investigate** | Access the details needed to decide. |
+| **Act** | Complete the intended business task. |
+| **Feedback** | See that the action succeeded and the state changed correctly. |
+
+### 1. Understand
+
+**Intent:** Help the user understand the business area this dashboard supports, what the data represents, and how to interpret it.
+
+- Present the most important totals, trends, and status indicators.
+- Make scope, time range, and freshness clear.
+- Distinguish no data, loading, access, connection, and system problems.
+- Connect summaries to underlying items.
+
+**Success:** The user can explain what is happening now.
+
+### 2. Focus
+
+**Intent:** Help the user recognize what matters or requires attention.
+
+- Choose the view that best supports the task.
+- Reduce noise through hierarchy, search, filters, sorting, saved views, and alerts.
+- Explain empty results and offer a useful next step.
+- Make the most important next action clear.
+
+**Success:** The user knows where to direct attention and what to do next.
+
+### 3. Investigate
+
+**Intent:** Give the user enough context to make a confident decision.
+
+- Reveal detail progressively without making users lose their place.
+- Show related information, history, and meaningful connections.
+- Make missing, unmatched, or uncertain information visible.
+
+**Success:** The user can understand why something happened and decide how to respond.
+
+### 4. Act
+
+**Intent:** Let the user complete the intended business task.
+
+- Provide the actions required by the prompt and allowed by permissions.
+- Support individual and bulk actions when both are useful.
+- Make consequences clear and protect against destructive mistakes.
+
+**Success:** The user can complete the task without leaving the workflow or guessing what to do.
+
+### 5. Feedback
+
+**Intent:** Confirm that the action succeeded and the business state changed correctly.
+
+- Provide immediate feedback after an action.
+- Refresh relevant items, summaries, counts, filters, and views.
+- Keep status and history visible when users may need to return later.
+
+**Success:** The user can see the confirmed result everywhere it matters.
+
+
+## The 5 WHATs
+
+How to gain enough context to ensure a complete workflow. Translate each prompt into concrete journey requirements:
+
+- What outcome is the user trying to achieve?
+- What must they understand before acting?
+- What requires deeper investigation?
+- Which actions must be available?
+- What visible result will confirm success?
+
+> **Example:** "Help me manage order exceptions" requires an overview of open issues, ways to focus on urgent cases, enough order context to decide, actions to resolve each issue, and confirmation that resolved items leave the active list.
+
+
+## Presentation Success
+
+Presentation success applies across all five stages. Choose both the right **representation** and the right **interaction surface**, while keeping hierarchy, meaning, and state consistent.
+
+### Choosing the Right View
+
+| View | Use when… | Success looks like… |
+|---|---|---|
+| **Table** | Users compare many records across several attributes. | Records are easy to scan, compare, filter, select, and act on. |
+| **Gallery** | Visual recognition is central. | Images identify items while key status and actions remain visible. |
+| **List** | Items have one dominant identity and limited supporting detail. | Users scan quickly without unnecessary density. |
+| **Kanban** | Work moves through meaningful stages. | Stage, workload, and valid movement are understandable. |
+| **Timeline or calendar** | Time, sequence, or scheduling matters. | Upcoming activity, conflicts, and timing are clear. |
+| **Chart** | The user needs to understand a trend or relationship. | The visualization answers a specific business question. |
+| **Summary metrics** | The user needs a quick health signal. | Metrics clarify current conditions and where to focus. |
+
+- Choose the default view that best supports the primary task.
+- Offer another view only when it provides distinct value.
+- Keep filters, state, and meaning consistent when users change views.
+- Connect summaries and visualizations back to the relevant records.
+
+### Choosing the Right Drill-In
+
+Choose the smallest interface that gives users enough context and room to complete the task. These are defaults, not rigid rules.
+
+| Interface | Use when… | Success looks like… |
+|---|---|---|
+| **Side panel** | The user should review or update one item while keeping the dashboard visible. | Context is preserved while deeper work remains focused. |
+| **Modal** | The user needs to complete a focused, bounded task or decision. | Attention stays on one task and the user can return cleanly. |
+| **Entity page** | The task involves complex details, multi-section editing, history, or related information. | The user has enough space and structure to complete deeper work. |
+| **Inline or expanded row** | The user needs a quick inspection or simple action. | Detail appears without creating a separate workspace. |
+
+Which Wix primitive builds each of these — and which components serve the summaries, filters and empty states named above — is in [Collection Toolkit](COLLECTION_TOOLKIT.md). Patterns has no side panel; that one is WDS.
+
+
+## Data Success
+
+Data success means giving users a complete and trustworthy view of the business. A dashboard may rely on one source or connect related customer, transaction, payment, and operational data.
+
+### Major Data Sources
+
+| Data source | What it provides |
+|---|---|
+| **CMS** | Custom collections, items, references, and custom business records. |
+| **Stores** | Products, variants, categories, inventory, and locations. |
+| **eCommerce** | Carts, checkouts, orders, line items, and fulfillment. |
+| **Bookings** | Services, appointments, classes, courses, staff, availability, and attendance. |
+| **Contacts and Members** | Customer identity, profiles, labels, roles, and audience context. |
+| **Payments and Pricing Plans** | Transactions, refunds, payouts, plans, subscriptions, and renewals. |
+| **Events** | Events, tickets, registrations, guests, and check-ins. |
+| **Other connected sources** | Restaurants, Forms, Invoices, Programs, and external systems. |
+
+### What Must Succeed Across Sources
+
+| Requirement | User outcome |
+|---|---|
+| **Meaningful relationship** | Sources combine around the business item or decision the user cares about. |
+| **Consistent meaning** | Shared concepts use understandable and consistent language. |
+| **Clear gaps** | Missing or unmatched information is visible rather than silently ignored. |
+| **Trusted actions** | Actions update the correct source and the result appears everywhere relevant. |
+| **Right level of combination** | Related items may be combined; useful but distinct sources remain separate. |
+
+> The goal is not to merge everything. Combine sources when the relationship helps users understand or act; otherwise keep them separate but connected.
+
+### Multi-Source Examples
+
+| Single view | Primary record | Connected sources | User outcome |
+|---|---|---|---|
+| **Order exceptions** | eCommerce order | Payments, Contacts, Stores | Resolve unpaid, delayed, or incorrect orders from one queue. |
+| **Booking follow-up** | Booking or appointment | Bookings, Contacts, Payments | Find missed or unpaid appointments and contact the client. |
+
+
+## Evaluation
+
+Rendering is not enough. A successful dashboard passes every check below.
+
+- [ ] **Prompt fulfilled:** The main result requested by the user is delivered.
+- [ ] **Task completion:** The intended task works from entry to confirmed result.
+- [ ] **Presentation fit:** Layout, actions, and empty states make the task easy to understand and complete.
+- [ ] **Trusted data:** All sources and views form one accurate picture of the business.
+- [ ] **Consistent results:** Actions, filters, views, summaries, and details agree.
+- [ ] **Business fit:** The experience matches the user's context, role, and permissions.
+
+> **Final evaluation question.** Does this dashboard give the user a **clear, trustworthy, and effective** way to accomplish what they asked for?