@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -0,0 +1,97 @@
+# Draft Template — the starting point for every dashboard page
+
+**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** Pick the case below, copy its files, rename, and adapt fields/API calls/data source. Only leave this file for [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md), the package's own `Collection Toolkit.md` guide, [TABLE_STATE.md](TABLE_STATE.md), a component doc, or an MCP lookup when the request needs something no case shows.
+
+Every snippet below was copied from the installed `dist/docs/*.md` and `dist/dts-bundle/*.d.ts`, not from memory — confirm props against your own installed version before deviating.
+
+## Which case matches the request?
+
+| The request needs… | Case | Router? |
+| --- | --- | --- |
+| A list/report whose rows are read-only — no create/edit form | **A — Collection + read-only detail** | Yes |
+| A list **and** create/edit for each record (no separate app-settings area) | **B — Collection + Entity** | Yes |
+| Only app-wide settings/config — no list at all | **C — Settings only** | No |
+| A list, create/edit, **and** an app-settings area, all in one extension | **D — Collection + Entity + Settings** | Yes |
+
+Don't default to D because it's the most complete — [Step 4c's checklist](../../SKILL.md#step-4c-ux-completeness-self-audit) doesn't ask for a settings or entity page unless the request needs one. If unsure between B and D, re-read the prompt for "settings," "configure," "preferences" — their absence means B.
+
+## Then: what `fetchData` calls
+
+Case tells you how many pages. This tells you only what `fetchData` calls — the page itself is
+[DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md) either way:
+
+| The rows come from | `fetchData` calls |
+| --- | --- |
+| A vertical SDK (`@wix/bookings`, `@wix/ecom`, …) or any API you call yourself | that SDK's own query method — [DATA_SOURCES.md](DATA_SOURCES.md) |
+| A **CMS collection** — one your Data Collection extension ships, or an existing site collection | `@wix/data` `items.query()` — [WIX_DATA.md](../data-collection/WIX_DATA.md) |
+
+A CMS collection is not a different template, just a different call inside the same one: you write
+`fetchData`, the filters and the columns for both.
+
+**Cases B and D both need a router** — their entry file, app shell, and entity page are in [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md). The collection and settings files are shared by every case that uses them, B and D included; the router file links back rather than repeating them.
+
+## File layout
+
+```
+src/extensions/dashboard/pages/{feature}/
+  {feature}.extension.ts        # single wix generate scaffold — always exactly one route registered here
+  {feature}.tsx                 # entry — Case C: Section 1 below. Cases A/B/D: DRAFT_TEMPLATE_ROUTER.md
+  {Feature}App.tsx              # Case A/B/D only — see DRAFT_TEMPLATE_ROUTER.md
+  {Feature}CollectionPage.tsx   # Case A, B, D — see DRAFT_TEMPLATE_COLLECTION.md
+  {Feature}DetailPage.tsx       # Case A only — read-only detail route, DRAFT_TEMPLATE_ROUTER.md §4
+  {Feature}EntityPage.tsx       # Case B, D only — see DRAFT_TEMPLATE_ROUTER.md
+  {Feature}SettingsPage.tsx     # Case C, D only — see DRAFT_TEMPLATE_SETTINGS.md
+  {feature}-api.ts              # fetch/save calls — keep these out of the components
+```
+
+Scaffold with a single call regardless of case — this is always one extension:
+
+```bash
+wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","route":"<route>"}'
+```
+
+## 1. Entry — Case C only (router-free, no location plumbing)
+
+Case C has one page and no rows to open, so it needs no router and no manual `location` wiring. **Cases A, B and D all route** — a row opens a page of its own in every one of them — so their entry file is [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) §1:
+
+```tsx
+// {feature}.tsx — Case C
+import type { FC } from 'react';
+import { withDashboard } from '@wix/patterns';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { {Feature}SettingsPage } from './{Feature}SettingsPage'; // DRAFT_TEMPLATE_SETTINGS.md
+
+const Page: FC = () => (
+  <WixDesignSystemProvider>
+    <WixPatternsProvider>
+      <{Feature}SettingsPage />
+    </WixPatternsProvider>
+  </WixDesignSystemProvider>
+);
+
+export default withDashboard(Page);
+```
+
+Cases A, B and D differ — they need `location` supplied manually for `PatternsReactRouter`. See [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) rather than adding that plumbing here; it's dead code without a router underneath it.
+
+## 2. Collection page — Case A, B, D
+
+In [DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md) — `useTableCollection`, a working
+filter, the four placeholder states, and a row that opens. Shared by Cases A, B and D. No
+`SummaryBar` unless the request asked for one, and the drill-in is always a route — never a side
+panel.
+
+## 3. Settings page — Case C, D
+
+In [DRAFT_TEMPLATE_SETTINGS.md](DRAFT_TEMPLATE_SETTINGS.md) — `useSettingsPage` + `useForm`,
+with the same field-controller patterns as the entity page.
+
+## What to change vs. keep, per case
+
+| Change per request | Keep as shown |
+| --- | --- |
+| Feature/entity names, fields, columns, API calls in `{feature}-api.ts` | Which case (A/B/C/D) — don't over-build D for a request that only named a list |
+| Detail fields, form field types, columns | The drill-in being a route, and the absence of a `SummaryBar` the request never asked for |
+| Real data source (SDK-first per [SDK-First Rule](../../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms)) vs CMS | B/D wiring (provider/router nesting, `parentPath`, `location`): [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) |

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

@@ -0,0 +1,184 @@
+# Draft Template — Collection page (Cases A, B and D)
+
+> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first. This page is shared by A, B
+> and D.
+
+> **You write `fetchData`, the filters and the columns.** This holds whatever the rows are: for a
+> CMS collection `fetchData` calls `@wix/data` `items.query()`
+> ([WIX_DATA.md](../data-collection/WIX_DATA.md)) and nothing else on this page changes.
+
+## Two rules this skeleton encodes, so read them before editing it
+
+**Every row opens a page of its own, never a panel.** `onRowClick` navigates —
+`navigateToEntityPage` to an `EntityPage` route when the record is editable, or to a read-only
+detail route when the page is display-only ([DRAFT_TEMPLATE_ROUTER.md § 4](DRAFT_TEMPLATE_ROUTER.md#4-read-only-detail-route--case-a)).
+A WDS `SidePanel` is not the drill-in: in Cairo it is the host for a page's own side panels — the
+fields card's "Manage fields", a table's column panel — and `example-bm` uses it as a row drill-in
+in exactly nothing. Every collection example there navigates.
+
+**No `SummaryBar` unless the request asked for one.** Not "unless the page seems to want one" —
+unless the prompt named a total, a count, or a "how many / how much" figure. It is absent from this
+skeleton on purpose; adding one uninvited pushes the rows down the page and puts a number on screen
+nobody has to be right about. When you do add one, wire it from
+[SKILL.md § Step 2](../../SKILL.md) — no `SummaryBar` unless the request asked for one.
+
+## The collection page
+
+This is the file [Step 4c's UX Completeness Self-Audit](../../SKILL.md#step-4c-ux-completeness-self-audit)
+is about: a working filter, named filters, and a row that opens.
+
+```tsx
+// {Feature}CollectionPage.tsx — Case A, B, D
+import type { FC } from 'react';
+import {
+  CollectionEmptyState, CollectionErrorState, CollectionNoResultsState, CollectionSearch, CollectionToolbarFilters,
+  MultiSelectCheckboxFilter, Table, stringsArrayFilter,
+  useStaticListFilterCollection, useTableCollection,
+} from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { usePatternsNavigate } from '@wix/patterns/router';
+import { fetch{Feature}Page, type {Entity}Row } from './{feature}-api';
+
+const STATUS_LABELS: Record<string, string> = { ACTIVE: 'Active', ARCHIVED: 'Archived' };
+// Filter factories are module-level: one instance per page, not per render.
+const statusFilter = stringsArrayFilter<'ACTIVE' | 'ARCHIVED'>({
+  // `name` is NOT the visible title — it feeds a11y legends, BI grouping and dataHooks.
+  // The title comes from the label props in the JSX below; the package's own
+  // `Collection Toolkit.md` guide has the prop model.
+  name: 'Status',
+  itemKey: (item) => item,
+  itemName: (item) => STATUS_LABELS[item] ?? item,
+});
+
+export const {Feature}CollectionPage: FC = () => {
+  const { navigateToEntityPage } = usePatternsNavigate<{Entity}Row>();
+
+  const state = useTableCollection<{Entity}Row, { status: typeof statusFilter }>({
+    queryName: '{feature}',
+    paginationMode: 'cursor', // 'offset' if your API pages by offset
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+    filters: { status: statusFilter },
+    // Every declared filter AND the search box are read here — one that never
+    // reaches the query renders fine and narrows nothing.
+    fetchData: async (query) =>
+      fetch{Feature}Page({
+        limit: query.limit,
+        cursor: query.cursor ?? undefined, // return `cursor: next || undefined` — key always
+        //                                    present, '' walks pages forever
+        search: query.search,
+        filters: { status: query.filters.status },
+      }),
+    // fetchTotal is for a requested aggregate, so it is commented out here. Uncommented, it
+    // must RESOLVE A NUMBER from an endpoint that counts, and it OVERRIDES the fallback to the
+    // loaded-rows count — so a wrong one reports 0 beside a full table while tsc stays green.
+    // Read QUERY_AND_PAGING.md, "What fetchTotal is allowed to call", before uncommenting.
+    // fetchTotal: async (query) => count{Feature}({ search: query.search, filters: query.filters }),
+    fetchErrorMessage: ({ err }) => (err instanceof Error ? err.message : 'Failed to load {feature}'),
+  });
+
+  const statusOptions = useStaticListFilterCollection(statusFilter, ['ACTIVE', 'ARCHIVED']);
+
+  // Nothing here reads `state` directly: the Table observes it internally. The moment you
+  // DO derive a number from it in this component — a header figure, a badge, a requested
+  // SummaryBar — it is MobX, and a plain read is computed once while the collection is still
+  // empty and never recomputed. Wrap it in `useSelector` and select a primitive: TABLE_STATE.md.
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: '{Page Title}' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          // `search` defaults to ON, so omitting it ships a box that reaches no
+          // query. Wire it AND read query.search above. If the API has no
+          // free-text filter, resolve the term to one it does support.
+          search={<CollectionSearch placeholder="Search {feature}" />}
+          filters={
+            <CollectionToolbarFilters>
+              {/* BOTH label props, same string, and never accordionItemProps.title.
+                  The resolution model is the package's own `Collection Toolkit.md` guide. */}
+              <MultiSelectCheckboxFilter
+                filter={statusFilter} collection={statusOptions}
+                toolbarItemProps={{ label: 'Status' }}
+                accordionItemProps={{ label: 'Status' }}
+              />
+            </CollectionToolbarFilters>
+          }
+          // Three distinct messages. Without errorState a failed query looks
+          // exactly like a slow one: skeletons, forever.
+          emptyState={<CollectionEmptyState title="No {feature} yet" />}
+          // Name what excluded the rows — a seeded default or a missing scope
+          // looks exactly like "nothing matched", and only one is actionable.
+          noResultsState={<CollectionNoResultsState title="No {feature} match" subtitle="…" />}
+          // errorState is a RENDER FUNCTION: (err, { retry }) => ReactElement.
+          errorState={(err, { retry }) => (
+            <CollectionErrorState
+              title="Couldn't load {feature}"
+              subtitle={String(err)}
+              action={{ text: 'Retry', onClick: retry }}
+            />
+          )}
+          // The drill-in. Editable record → the EntityPage route (`/${item.id}`).
+          // Display-only → the read-only route, DRAFT_TEMPLATE_ROUTER.md §4. Either way a
+          // route, and passing `entity` lets the target title itself before its fetch lands.
+          onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
+          columns={[
+            // One column per field the prompt names; verify each source field —
+            // DATA_SOURCES.md, "A column must show what its header promises."
+            { id: 'name', title: 'Name', render: (item) => item.name },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+};
+```
+
+## Turning `query.search` into a query
+
+`{feature}-api.ts` turns one term into a filter over *several* fields — an OR. **This is where
+search ships broken**: it renders, it reaches the query, and still returns every row, so nothing
+looks wrong until someone counts results.
+
+### A CMS collection — `@wix/data`
+
+`or()` combines two filters; it is **not** a condition. Called on a query or filter holding no
+condition yet it contributes an empty `{}` branch, and `{} OR x` matches the whole collection. Seed
+the filter with the first field, `or()` the rest onto it, then `and()` it onto the query — which is
+also what keeps the facet filters applying to *every* branch:
+
+```ts
+// SHORT_TEXT / LONG_TEXT fields only: `contains` on a number, date or
+// reference field is not a narrower match, it is no match.
+const searchFilter = (term: string, fields: string[]) =>
+  fields.map((f) => items.filter().contains(f, term)).reduce((acc, f) => acc.or(f));
+
+let query = items.query(COLLECTION_ID).eq('status', status).limit(limit);
+const term = search?.trim();
+if (term) query = query.and(searchFilter(term, ['companyName', 'contactEmail']));
+
+// ❌ or() onto a query holding no condition — empty $or branch, every row matches
+items.query(ID).or(items.filter().contains('a', t)).or(items.filter().contains('b', t));
+// ❌ or() onto the query itself — `status` survives only on the first branch
+items.query(ID).eq('status', s).contains('a', t).or(items.filter().contains('b', t));
+```
+
+### A vertical SDK — `@wix/bookings`, `@wix/ecom`, …
+
+No shared free-text operator; the shape differs per endpoint. Read its *Supported Filters* page
+([QUERY_AND_PAGING.md](QUERY_AND_PAGING.md#the-filterable-fields-are-a-closed-list-published-per-endpoint)),
+then `$or` one clause per identity field it lists. Never route the term to a single field by its
+shape — a measured run shipped this, and one branch is always dead:
+
+```ts
+query = term.includes('@')
+  ? query.startsWith('loginEmail', term)
+  : query.startsWith('contact.firstName', term);  // a surname matches nothing, ever
+```
+
+`startsWith` is prefix-only too — "Smith" never finds "John Smith" — so prefer the containment
+operator when the endpoint declares one, and say which you used in `noResultsState`.
+
+**Whatever the shape, prove it narrows.** Run one term you expect to hit a known row and one you
+expect to hit nothing, and check the row count changes for both.

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

@@ -0,0 +1,203 @@
+# Draft Template — Cases A, B and D (router-wired)
+
+**Applies to [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md)'s Cases A, B and D.** All three need `PatternsReactRouter`, because in all three a row opens a page of its own — a panel is not the drill-in ([UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md)). Case A's detail route is read-only (§4); B and D route to a full `EntityPage`. The collection and settings components live in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md); this file covers only what a router adds — the entry file, the app shell, and the detail/entity page.
+
+Every snippet below is copied from the installed `dist/docs/*.md` this session read, not from memory.
+
+## 1. Entry — `location` is manual in a Wix CLI app, and only because the router needs it
+
+`PatternsReactRouter` reads the page location through `container.usePageLocation()`, which only `withDashboard`'s `location` prop feeds — nothing supplies it automatically in a Wix CLI app the way Yoshi BM flow does:
+
+```tsx
+// {feature}.tsx — Case A, B or D
+import { useEffect, useState, type FC } from 'react';
+import { dashboard } from '@wix/dashboard';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { {Feature}App } from './{Feature}App';
+
+type PageLocation = Parameters<Parameters<typeof dashboard.observeState>[0]>[1]['pageLocation'];
+
+const Page: FC = () => {
+  const [location, setLocation] = useState<PageLocation | undefined>();
+
+  useEffect(() => {
+    const subscription = dashboard.observeState((_pageParams, environment) => {
+      setLocation(environment.pageLocation);
+    });
+    return () => subscription.disconnect();
+  }, []);
+
+  return (
+    <WixDesignSystemProvider>
+      {location ? <{Feature}App location={location} /> : null}
+    </WixDesignSystemProvider>
+  );
+};
+
+export default Page;
+```
+
+**Skipping this is a runtime-only failure.** Per `PatternsReactRouter`'s own docs: "Nothing catches this before runtime — type checking and bundling both pass, because neither renders the page." `tsc` and `wix build` will not catch a missing `location` — only opening the page in a browser will. This is exactly why [Step 5's Preview](../../SKILL.md#validation) is not optional for Case B/D.
+
+## 2. App shell — provider, router, routes
+
+```tsx
+// {Feature}App.tsx — Case A, B or D
+import { withDashboard } from '@wix/patterns';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsReactRouter, PatternsReactRoute } from '@wix/patterns/router';
+import { {Feature}CollectionPage } from './{Feature}CollectionPage';
+import { {Feature}EntityPage } from './{Feature}EntityPage';
+// Case D only:
+import { {Feature}SettingsPage } from './{Feature}SettingsPage';
+
+export const {Feature}App = withDashboard(() => (
+  <WixPatternsProvider>
+    <PatternsReactRouter>
+      <PatternsReactRoute type="collection" path="/" element={<{Feature}CollectionPage />} />
+      {/* Case B/D — editable record. Case A registers this ONE route instead, with
+          {Feature}DetailPage as the element and no /new route (§4). Either way the
+          type is `editEntity`: it wires back-navigation to the collection. */}
+      <PatternsReactRoute type="editEntity" path="/:id" element={<{Feature}EntityPage />} />
+      {/* Case B/D only — Case A has nothing to create: */}
+      <PatternsReactRoute type="createEntity" path="/new" element={<{Feature}EntityPage />} />
+      {/* Case D only: */}
+      <PatternsReactRoute type="other" path="/settings" element={<{Feature}SettingsPage />} />
+    </PatternsReactRouter>
+  </WixPatternsProvider>
+));
+```
+
+`PatternsReactRoute`'s `type` is one of exactly `"collection" | "createEntity" | "editEntity" | "other"` — no dedicated settings value, so a settings route is `"other"`. Case B: delete the `/settings` route and the import above it — nothing else changes.
+
+`{Feature}CollectionPage` is [DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md)'s component, unchanged; `{Feature}SettingsPage` (Case D) is [DRAFT_TEMPLATE_SETTINGS.md](DRAFT_TEMPLATE_SETTINGS.md).
+
+## 2b. The collection side of the handoff
+
+The router file above registers `/new`; something has to navigate there. All three of these live on
+the collection page, and `usePatternsNavigate` comes from **`@wix/patterns/router`** — not the root
+export, which is where it is easy to reach for it:
+
+```tsx
+import { PrimaryPageButton } from '@wix/patterns';
+import { usePatternsNavigate } from '@wix/patterns/router';
+
+const { navigateToEntityPage } = usePatternsNavigate<{Entity}>();
+const openNew = () => navigateToEntityPage({ path: '/new' }); // no record yet — omit `entity`
+
+// CollectionPage.Header — primaryAction takes an ELEMENT, not a { text, onClick } config:
+<CollectionPage.Header
+  title={{ text: '{Page Title}' }}
+  primaryAction={<PrimaryPageButton text="Add {entity}" onClick={openNew} />}
+/>
+
+// the empty state should offer the same action, and this one IS a config object:
+<CollectionEmptyState title="No {feature} yet" addNewCta={{ text: 'Add {entity}', onClick: openNew }} />
+
+// and a row opens the edit route:
+onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
+```
+
+The two shapes differ on purpose — `primaryAction` is an element, `addNewCta` is `{ text, onClick }`.
+Guessing either costs a compile round.
+
+## 3. Entity page — one component for both `/new` and `/:id`
+
+Full call details (both generics, what `onSave` receives, the `UseEntityPageParams` pick list) are in `<pkgRoot>/dist/docs/useEntityPage.md` — read it before filling in fields. The part specific to this router-based shape:
+
+```tsx
+// {Feature}EntityPage.tsx — Case B or D (sketch — see dist/docs/useEntityPage.md for the full call)
+import { useParams } from 'react-router-dom'; // NOT @wix/patterns/router — PatternsReactRoute wraps react-router-dom's Route, but only exports PatternsReactRoute/PatternsReactRouter/usePatternsNavigate itself
+import { useEntityPage, EntityPage } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { fetch{Entity}, save{Entity}, type {Entity} } from './{feature}-api';
+
+// The form's shape is yours to declare, and need not match the saved entity type.
+type {Entity}FormFields = { name: string };
+
+export const {Feature}EntityPage = () => {
+  const { id } = useParams<{ id?: string }>();
+  const form = useForm<{Entity}FormFields>();
+
+  const state = useEntityPage<{Entity}, {Entity}FormFields>({
+    parentPath: '/', // NOT parentPageId — this shape always uses Patterns Router
+    isNewEntity: () => !id, // a getter: the route can change (/new -> /:id after save) while this stays mounted
+    form,
+    fetch: () => (id ? fetch{Entity}(id).then((entity) => ({ entity })) : Promise.resolve({ entity: undefined })),
+    onSave: ({ widgetsFormData }) =>
+      save{Entity}({ id, ...form.getValues(), ...widgetsFormData }).then((updatedEntity) => ({ updatedEntity })),
+  });
+
+  return (
+    <EntityPage state={state}>
+      <EntityPage.Header title={{ text: id ? 'Edit {Entity}' : 'New {Entity}' }} />
+      <EntityPage.Content>
+        <EntityPage.MainContent>{/* form cards — see dist/docs/EntityPage.md */}</EntityPage.MainContent>
+      </EntityPage.Content>
+    </EntityPage>
+  );
+};
+```
+
+`useEntityPage`'s own docs are explicit about both details above: `parentPath` "Must be passed if using Patterns Router" (`parentPageId` is the non-router alternative — irrelevant here, since Case B/D always uses the router), and `isNewEntity` should be "a getter when the route can change while the page stays mounted" — exactly this component's case, since a successful create typically navigates `/new` → `/:newId`.
+
+**`UseEntityPageParams` is a `Pick<>`, so a param missing from it is a compile error, not an ignored prop.** `isNewEntity` is in that list at 1.470.0 and absent before ~1.46x. If it doesn't compile, read the pick list in your installed `dist/types/hooks/useEntityPage.d.ts` and upgrade — deleting the line makes a create route behave as an edit.
+
+## 4. Read-only detail route — Case A
+
+A display-only collection still routes its rows to a page — but not an `EntityPage`, which has no
+read-only mode and still has none at **1.471.0**: `fetch` and `onSave` are both required, and
+`actionsBarConfig` (`saveCta.text`, `cancelCta`) can retext Save but not remove it. It would ship
+two buttons that either do nothing or save a form nobody was offered.
+
+Use a WDS `Page` — what Cairo does itself: `example-bm`'s `DataExtensionEntityViewPage` and
+auto-patterns' `ViewModeEntityPage` are both plain WDS `Page`s, the latter unexported.
+
+```tsx
+// {Feature}DetailPage.tsx — Case A
+import { useEffect, useState } from 'react';
+import { useParams } from 'react-router-dom';
+import { Card, Loader, Page, Text } from '@wix/design-system';
+import { usePatternsNavigate } from '@wix/patterns/router';
+import { fetch{Entity}, type {Entity} } from './{feature}-api';
+
+export const {Feature}DetailPage = () => {
+  const { id } = useParams<{ id: string }>();
+  const { navigateToCollectionPage } = usePatternsNavigate();
+  const [entity, setEntity] = useState<{Entity} | undefined>();
+
+  useEffect(() => {
+    if (id) {
+      fetch{Entity}(id).then(setEntity);
+    }
+  }, [id]);
+
+  return (
+    <Page>
+      {/* The way back is the header's back button — a read-only page has no Cancel. */}
+      <Page.Header
+        title={entity?.name ?? '{Entity}'}
+        showBackButton
+        onBackClicked={() => navigateToCollectionPage({ path: '/' })}
+      />
+      <Page.Content>
+        {entity ? (
+          <Card>
+            <Card.Header title="Details" />
+            <Card.Divider />
+            <Card.Content>
+              <Text>{entity.name}</Text>
+            </Card.Content>
+          </Card>
+        ) : (
+          <Loader />
+        )}
+      </Page.Content>
+    </Page>
+  );
+};
+```
+
+If the request later grows an edit form this becomes §3's `EntityPage`, route type and `onRowClick`
+unchanged — which is why Case A registers `editEntity`, not `other`.

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

@@ -0,0 +1,44 @@
+# Draft Template — Settings page (Cases C and D)
+
+> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first; this page covers Case C or D.
+
+## The settings page
+
+No dedicated toolkit file exists for this yet (unlike Entity/Collection) — the shape, verified against `useSettingsPage.md`:
+
+```tsx
+// {Feature}SettingsPage.tsx — Case C or D
+import { SettingsPage, useSettingsPage, useSettings } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { fetch{Feature}Settings, save{Feature}Settings, type {Feature}Settings } from './{feature}-api';
+
+// The form's shape is yours to declare, and need not match the saved settings type —
+// one field per control on the page.
+type {Feature}SettingsFormFields = { reminderHours: number; notifyStaff: boolean };
+
+export const {Feature}SettingsPage = () => {
+  const form = useForm<{Feature}SettingsFormFields>();
+
+  const state = useSettingsPage<{Feature}Settings, {Feature}SettingsFormFields>({
+    form,
+    fetch: () => fetch{Feature}Settings().then((settings) => ({ settings })),
+    onSave: () => save{Feature}Settings(form.getValues()),
+    onCancel: async () => form.reset(),
+    saveSuccessToast: 'Settings saved',
+    saveErrorToast: (err, { retry }) => ({ message: 'Failed to save settings', action: { text: 'Retry', onClick: retry } }),
+  });
+
+  const settings = useSettings<{Feature}Settings, {Feature}SettingsFormFields>(state);
+
+  return (
+    <SettingsPage state={state}>
+      <SettingsPage.Header title={{ text: '{Settings Page Title}' }} />
+      <SettingsPage.Content>
+        <SettingsPage.MainContent>{/* form cards — same field-controller patterns as EntityPage */}</SettingsPage.MainContent>
+      </SettingsPage.Content>
+    </SettingsPage>
+  );
+};
+```
+
+`useSettingsPage`'s params are all required except `saveSuccessToast`/`saveErrorToast`: `form`, `fetch`, `onSave`, `onCancel`. There is no `parentPath`/`parentPageId` — a settings page isn't reached by drilling into a row, so it carries no back-navigation contract, and Case C needs no router at all to reach it (Section 1's entry renders it directly).

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

@@ -141,6 +141,23 @@ dashboard.navigate(
 );
 ```
 
+## taxSettings()
+
+Ecom Extensions Dashboard Pages 'taxSettings()' destination builder for navigating to the Tax Settings dashboard page.
+
+**Request:**
+This method does not take any parameters.
+
+**Example:**
+```typescript
+import { dashboard } from "@wix/dashboard";
+import { pages } from "@wix/ecom/dashboard";
+
+dashboard.navigate(
+  pages.taxSettings(),
+);
+```
+
 ## orderRefund()
 
 Ecom Extensions Dashboard Pages 'orderRefund()' destination builder for navigating to the Order Refund dashboard page.