@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/shared/capabilities/site-search/INSTRUCTIONS.md

@@ -0,0 +1,194 @@
+# Site search — capability playbook
+
+One search box, one results page, across everything the deployed verticals hold: products,
+booking services, blog posts, events. Wix indexes the site's content (the Wix Site Search app), the
+shipped code queries the index and links every hit to **this site's routes** — never to a Wix page.
+A capability, not a vertical: it has no content and no seed of its own, it rides along with the
+verticals whose entities it finds, and it is switched on from the plan.
+
+## Switching it on
+
+```json
+{
+  "capabilities": {
+    "siteSearch": {
+      "install": true,
+      "types": ["products", "services", "posts", "events"],
+      "routes": { "products": "/products/[slug]", "services": "/services/[slug]", "posts": "/blog/[slug]", "events": "/events/[slug]" },
+      "labels": { "posts": "Journal" }
+    }
+  }
+}
+```
+
+`{}` (or `true`) is enough — every field has a default. `types` is the order of the groups on the
+results page, restricted to the verticals the site deploys (a type the site has no app for answers
+an empty group and is dropped). `routes` are this site's item-page routes, `[slug]` replaced by the
+URL-encoded slug — change one when a route is named differently (`posts: "/journal/[slug]"`).
+`labels` are the group headings. `pages` (Wix-page content) exists as a type but stays off: a
+headless site has no Wix pages. **`install: true` records that the seed step installs the Wix Site
+Search app (below); the deploy never mutates the site.**
+
+The deploy (`deploy.mjs <vertical…> --stack <stack> --plan plan.json`) copies the files below, adds
+`@wix/search` to `package.json`, and writes `src/wix/site-search/config.generated.ts` from the plan
+(`site/js/wix/site-search-config.generated.ts` on the static stack). Do not hand-edit the generated
+file — edit the plan and redeploy.
+
+## The site must be indexed — the one site mutation
+
+Nothing is searchable until the **Wix Site Search app** (`1484cb44-49cd-5b39-9681-75188ab429de`)
+is installed on the site. Before that, every search answers 200 with zero documents — silently, no
+error. Install it **after the content seed**, from the project root:
+
+```bash
+node <SKILL_ROOT>/templates/shared/capabilities/site-search/seed/install.mjs
+```
+
+It mints the CLI token in-process, installs the app once (idempotent — an installed app is
+reported, not re-installed), and prints `{ installed: "now" | "already" }`. The install back-fills
+the site's existing content: products were searchable about 26 s later and services about 14 s
+later on the probe sites — **allow half a minute**, then smoke-test before wiring any UI:
+`searchAll("<a word from a seeded title>")` from the deployed data layer (or the page
+`/search?q=<word>`) must return a non-empty group. Zero documents after a minute means the app is
+not installed or the content is not visible to the index (hidden products, draft posts) — never that
+the query is wrong. The helper behind the script is `templates/shared/seed/site.mjs`
+`installSiteSearch(ctx)`, for a seed that wants to call it itself. How fast a later edit reaches the
+index was not measured.
+
+## The file map (deployed into `src/`)
+
+| file | what it is |
+|---|---|
+| `wix/site-search/types.ts` | the DTOs (`SearchHit` per type, `SearchGroup`, `SearchPage`, `SearchFacets`, `SuggestGroup`, `SearchAllResult`, `SiteSearchConfig`) — contracts inlined below |
+| `wix/site-search/search.ts` | `searchAll(q)`, `searchType({ q, type, … })`, `suggest(q)`, `config` — the transport (SDK `siteSearch` from `@wix/search`); every body, field name and href rule is in `search-core.ts` beside it (shared with the REST twin `rest/search.ts`) |
+| `wix/site-search/search-store.ts` · `suggest-store.ts` | the results page and the header box as framework-free state machines (`createSearchStore()`, `createSuggestStore()` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly. The suggestion debounce lives in `suggest-store.ts` — the capability's only timer |
+| `wix/site-search/config.generated.ts` | written by deploy from the plan — data only |
+| `hooks/site-search/useSearch.ts` · `useSuggest.ts` | React bindings of the two stores — contracts below |
+| `components/site-search/SearchBox.tsx` | the header search box with suggestions — **wire as-is** in your `SiteLayout` header, `client:only="react"` |
+| `components/site-search/SearchResults.tsx` (+ `SearchHit.tsx`) | the results surface — **wire as-is** on the search page, or the reference for your own on `useSearch` |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `pages/search.astro` | `/search?q=&type=` — SSR of the first result set, then the `SearchResults` island. **Keep the frontmatter** (the query clamp, the type check, the `X-Robots-Tag: noindex` header); restyle the template |
+
+Static stack (`--stack static`): `rest/search.ts` lands flat as `js/wix/search.js` beside
+`search-core.js`, `search-store.js`, `suggest-store.js`, `site-search-types.js` and the generated
+config; the stores import the REST twin under the same names. No components — the page renders from
+the stores (subscribe, render `getState()`, call actions), like every other vertical there.
+
+## Wiring
+
+1. **The header box.** In the deployed vertical's `SiteLayout.astro` (the one that won, if several
+   are deployed), next to the nav or the cart button:
+   `<SearchBox client:only="react" placeholder="Search" />`. It is a `<form role="search">` with a
+   suggestions listbox; Enter with no active row opens `/search?q=…`. Pass `searchPath` if the page
+   lives elsewhere, `onNavigate` to route client-side.
+2. **The results page** ships (`pages/search.astro`) and mounts `SearchResults`. Brand it through
+   the layout and the `@theme` tokens; the component's own classes read the same tokens.
+3. **The routes** must exist: a hit links to `routes[type]` — the storefront's `/products/[slug]`,
+   bookings' `/services/[slug]`, blog's `/blog/[...slug]`, events' `/events/[slug]`. A site that
+   names one differently says so in the plan.
+4. **Smoke-test** per the section above before calling the surface done.
+
+## Contracts
+
+```ts
+// wix/site-search/search.ts
+searchAll(q, { limit = 4 }): Promise<{ groups: SearchGroup[]; indexed: boolean | null }>
+searchType({ q, type, limit = 12, offset = 0, sort?, filter?, fuzzy? }): Promise<SearchPage>
+suggest(q, { limit = 4 }): Promise<SuggestGroup[]>     // [] under 3 chars, no request
+
+// every hit: { id, type, title, titleHtml, excerptHtml, imageUrl, href }
+//   title       plain text — aria-labels, fallbacks
+//   titleHtml   the title with matched words in <mark>; TEXT AND <mark> ONLY (sanitised in core) — the
+//   excerptHtml one thing you may hand to dangerouslySetInnerHTML / set:html
+//   imageUrl    resolved https URL, "" when none — through imgAttrs() like every image
+//   href        THIS site's route, "" when no slug could be derived → render the row unlinked
+// per type: products { slug, price (formatted, as indexed), inStock, collections[] }
+//           services { slug, category, tagLine }   posts { slug, publishDate (ISO), author, tags[] }
+//           events { slug, startDate (ISO), location, price ("From €20" | "Free" | "") }
+// SearchGroup { type, label, total, hits }    — total is the whole index's count for the type
+// SearchPage  { type, hits, total, offset, limit, hasNext, facets: { terms, ranges } }
+//   facets: products only — terms.collections / terms.inStock [{ value, count }],
+//   ranges.discountedPriceNumeric { min, max }
+// sort: "relevance" | "price-asc" | "price-desc" (products) | "date-desc" (posts, events) — sortsFor(type)
+// filter (products): { collections?: string[], inStockOnly?, minPrice?, maxPrice? }
+
+// hooks/site-search/useSearch.ts
+const s = useSearch({ q, type, initialGroups, initialIndexed, initialPage });
+// s.groups   SearchGroup[] | null   grouped view; null = first load in flight (skeletons), [] = nothing
+// s.indexed  boolean | null         see below
+// s.page     SearchPage | null      single-type view
+// s.sorts, s.sort, s.filter, s.loading, s.loadingMore, s.hasMore, s.error
+// s.setQuery(q) · s.setType(type | null) · s.setSort(sort) · s.setFilter(f) · s.loadMore() · s.retry()
+
+// hooks/site-search/useSuggest.ts
+const b = useSuggest({ minChars = 3, debounceMs = 300, limit = 4 });
+// b.input, b.groups, b.rows (flattened), b.open, b.activeIndex, b.loading, b.error
+// b.setInput(v) · b.show() · b.hide() · b.moveActive(±1) · b.setActive(i)
+// b.submit() → { kind: "hit", href } | { kind: "query", q, type } | null — you route
+```
+
+**`indexed`** answers "does this site have an index at all": `true` when documents came back;
+`false` when the response listed no document type — nothing is indexed, the app is not installed;
+`null` when it is **unknown** — zero documents across listed types is ambiguous (no match, an empty
+catalog, an index still back-filling) and must not be read as "not installed". The shipped empty
+state says "still being set up" only on `false`.
+
+## Hard rules
+
+- **Never render the index's `url`.** On a headless site it is `""` (products) or an absolute URL
+  on the Wix fallback host pointing at a page this site does not serve (services). Hrefs come from
+  `hrefFor(type, slug, config)` in core; a hit without a slug renders unlinked.
+- **Highlights are HTML fragments.** Only `titleHtml`/`excerptHtml` go into `set:html` or
+  `dangerouslySetInnerHTML`, and only after `safeHighlight()` in core (everything but `<mark>` is
+  dropped). Never interpolate a raw `_highlights` string.
+- **Limits are the service's.** 100 chars for search, 50 for suggest, 3-char minimum for suggest;
+  the core clamps (the service 400s otherwise). `federatedSearch` has no paging — page 2 is a
+  single-type `searchType` with `offset`.
+- **Products take two requests** — the default format carries `title` and `_highlights`, the
+  `result-format: store-front` format carries the slug (`urlPart`) and neither carries both. The
+  transports run the pair and join on id; when the second fails the products render unlinked. A
+  suggestion row for a product therefore has no href — `submit()` turns it into a search for its
+  title.
+- **The search page is `noindex`** (the `X-Robots-Tag` header in the frontmatter).
+- **Fail loudly.** A non-2xx from the search service surfaces as the store's `error` with a retry;
+  the only swallowed failure is the store-front pass (it degrades to unlinked products).
+- **CMS collections are not indexed** — Wix Search has no document type for them. A CMS site
+  searches its collections with `queryItems(collectionId, { filters: [{ field, op: "contains", value }] })`
+  (`templates/cms`); merging that into these groups is the agent's call, marked as a separate list.
+
+## Not verified live — guarded
+
+Two probe sites (a store with bookings, a spa) answered the observations above; the rest of the
+surface is from the SDK typings and the schema page, and the code degrades where a guess would
+otherwise show:
+
+- **Blog post and event hrefs.** No probe site had posts or events. The mappers assume `url` has the
+  services' shape (`…/<page>/<slug>`) and take the last path segment; an empty `url` → `href: ""`,
+  an unlinked row — never a Wix URL. Verify on a site with posts/events; if `url` is empty there,
+  the fallback is one read per hit (`GET /blog/v3/posts/{id}` for the slug) or dropping the type
+  from `types`.
+- **Visitor access.** Both search surfaces accepted an anonymous visitor token on the probe sites,
+  while the platformized typings say `@applicableIdentity APP` and the docs show an admin client. If
+  that door closes, the fallback is an Astro API route with `auth.elevate(wixSiteSearch.search)` per
+  `CUSTOM_OPERATIONS.md`; the failure shows as the store's `error`.
+- **Preview API.** The federated module (`suggest`, facets, highlights, `result-format`) is
+  `@documentationMaturity preview`; `_highlights`, `documentImage`, `urlPart` are wire names. Each
+  is spelled once in `search-core.ts`.
+- **Filter operators.** `inStock $eq` was observed; `collections $hasSome` and
+  `discountedPriceNumeric $gte/$lte` follow the schema page. A rejected filter surfaces as `error`.
+- **Sorts on posts/events** (`publishDate`, `startDate`) follow the schema page's sortable fields.
+- **Store-front document id.** The join reads `id` (else `_id`); a store-front document without a
+  matching id leaves that product unlinked.
+- **Event prices** (`minPrice` + `currency`) follow the schema page; absent → `""`.
+- **Propagation of later edits** to the index was not measured (the install back-fill was: ≤ 26 s).
+
+## Extensions (same module, not shipped)
+
+`siteSearch.related({ documentId, documentType })` — "you may also like" on a product page;
+`trending` — empty on a new site (no view data), so the empty-input state must not depend on it;
+`federatedAutocomplete` — phrase completion. Add each as a function in `search.ts` and
+`rest/search.ts` over a body spelled in `search-core.ts`.

package/skills/wix-headless-templates/shared/capabilities/site-search/app/components/site-search/SearchBox.tsx

@@ -0,0 +1,136 @@
+// The header search box — wire as-is in your SiteLayout header, client:only (browser state):
+//   <SearchBox client:only="react" placeholder="Search products, posts…" />
+// A search form with a suggestions listbox: grouped rows with the matched words in <mark>, arrows
+// move, Enter follows the active row or opens the results page for the phrase, Escape closes. The
+// debounce and the request live in the suggest store; this component renders and routes. Routing-
+// free: default navigation is `location.assign`; pass `onNavigate` to route client-side. Styled from
+// the @theme tokens.
+import { useId, useRef } from "react";
+import { useSuggest } from "../../hooks/site-search/useSuggest";
+import { searchHref } from "../../wix/site-search/search-core";
+import { imgAttrs } from "../../wix/media";
+
+interface Props {
+  placeholder?: string;
+  /** The results page (default "/search"); its `q` and `type` query params are the store's. */
+  searchPath?: string;
+  onNavigate?: (href: string) => void;
+  minChars?: number;
+  debounceMs?: number;
+  /** Suggestions per type (default 4). */
+  limit?: number;
+  className?: string;
+}
+
+const MARK = "[&_mark]:rounded-sm [&_mark]:bg-secondary [&_mark]:px-0.5 [&_mark]:text-foreground";
+
+export default function SearchBox({ placeholder = "Search", searchPath = "/search", onNavigate, minChars, debounceMs, limit, className = "" }: Props) {
+  const s = useSuggest({ minChars, debounceMs, limit });
+  const listId = useId();
+  const inputRef = useRef<HTMLInputElement>(null);
+  const navigate = (href: string) => (onNavigate ? onNavigate(href) : window.location.assign(href));
+
+  const go = () => {
+    const action = s.submit();
+    if (!action) return;
+    s.hide();
+    navigate(action.kind === "hit" ? action.href : searchHref(action.q, action.type, searchPath));
+  };
+
+  let rowIndex = -1;
+  return (
+    <form
+      role="search"
+      className={`relative ${className}`}
+      onSubmit={(e) => {
+        e.preventDefault();
+        go();
+      }}
+    >
+      <input
+        ref={inputRef}
+        type="search"
+        name="q"
+        value={s.input}
+        placeholder={placeholder}
+        autoComplete="off"
+        aria-label={placeholder}
+        aria-autocomplete="list"
+        aria-controls={listId}
+        aria-expanded={s.open}
+        aria-activedescendant={s.open && s.activeIndex >= 0 ? `${listId}-${s.activeIndex}` : undefined}
+        onChange={(e) => s.setInput(e.target.value)}
+        onFocus={s.show}
+        onBlur={s.hide}
+        onKeyDown={(e) => {
+          if (e.key === "ArrowDown") {
+            e.preventDefault();
+            s.moveActive(1);
+          } else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            s.moveActive(-1);
+          } else if (e.key === "Escape") {
+            s.hide();
+          }
+        }}
+        className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-primary"
+      />
+      {s.loading && <span aria-hidden="true" className="absolute right-3 top-1/2 h-3 w-3 -translate-y-1/2 animate-pulse rounded-full bg-muted-foreground/40" />}
+      <ul
+        id={listId}
+        role="listbox"
+        aria-label="Suggestions"
+        hidden={!s.open}
+        className="absolute left-0 right-0 top-full z-50 mt-1 max-h-96 overflow-y-auto rounded-lg border border-border bg-background p-1 shadow-lg"
+      >
+        {s.groups.map((group) => (
+          <li key={group.type} role="presentation">
+            <ul role="group" aria-label={group.label}>
+              <li role="presentation" className="px-2 pb-1 pt-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                {group.label}
+              </li>
+              {group.hits.map((hit) => {
+                const index = ++rowIndex;
+                const active = index === s.activeIndex;
+                const img = imgAttrs(hit.imageUrl, "32px");
+                return (
+                  <li
+                    key={hit.id}
+                    id={`${listId}-${index}`}
+                    role="option"
+                    aria-selected={active}
+                    onMouseEnter={() => s.setActive(index)}
+                    // mousedown, not click: the input blurs (and the list closes) before a click lands.
+                    onMouseDown={(e) => {
+                      e.preventDefault();
+                      s.setActive(index);
+                      go();
+                    }}
+                    className={`flex cursor-pointer items-center gap-3 rounded-md px-2 py-1.5 text-sm text-foreground ${active ? "bg-secondary" : ""}`}
+                  >
+                    {"src" in img ? <img {...img} alt="" width={32} height={32} className="h-8 w-8 shrink-0 rounded object-cover" /> : <span aria-hidden="true" className="h-8 w-8 shrink-0 rounded bg-secondary" />}
+                    <span className={`truncate ${MARK}`} dangerouslySetInnerHTML={{ __html: hit.titleHtml }} />
+                  </li>
+                );
+              })}
+            </ul>
+          </li>
+        ))}
+        {s.input.trim() && (
+          <li
+            role="option"
+            aria-selected={false}
+            onMouseDown={(e) => {
+              e.preventDefault();
+              s.setActive(-1);
+              go();
+            }}
+            className="mt-1 cursor-pointer rounded-md border-t border-border px-2 py-2 text-sm text-muted-foreground"
+          >
+            See all results for “{s.input.trim()}”
+          </li>
+        )}
+      </ul>
+    </form>
+  );
+}

package/skills/wix-headless-templates/shared/capabilities/site-search/app/components/site-search/SearchHit.tsx

@@ -0,0 +1,50 @@
+// One result row — wire as-is inside your results surface, or use it as the reference for your own:
+//   <SearchHit hit={hit} />
+// Image (or a placeholder), the highlighted title, the highlighted excerpt, one meta line per type
+// (price and stock; category; date and author; date, place and price). The row is a link to the
+// hit's route on THIS site; a hit whose slug could not be derived renders unlinked. `titleHtml` and
+// `excerptHtml` are the only strings rendered as HTML — they carry text and <mark> only (sanitised in
+// search-core). Styled from the @theme tokens.
+import { imgAttrs } from "../../wix/media";
+import { metaLine } from "../../wix/site-search/search-core";
+import type { SearchHit as Hit } from "../../wix/site-search/types";
+
+const MARK = "[&_mark]:rounded-sm [&_mark]:bg-secondary [&_mark]:px-0.5 [&_mark]:text-foreground";
+
+export default function SearchHit({ hit, onNavigate }: { hit: Hit; onNavigate?: (href: string) => void }) {
+  const img = imgAttrs(hit.imageUrl, "80px");
+  const meta = metaLine(hit);
+  const body = (
+    <>
+      {"src" in img ? (
+        <img {...img} alt="" width={80} height={80} className="h-20 w-20 shrink-0 rounded-md bg-secondary object-cover" />
+      ) : (
+        <div aria-hidden="true" className="h-20 w-20 shrink-0 rounded-md bg-secondary" />
+      )}
+      <div className="min-w-0 flex-1">
+        <h3 className={`text-base font-medium text-foreground ${MARK}`} dangerouslySetInnerHTML={{ __html: hit.titleHtml }} />
+        {hit.excerptHtml && <p className={`mt-1 line-clamp-2 text-sm text-muted-foreground ${MARK}`} dangerouslySetInnerHTML={{ __html: hit.excerptHtml }} />}
+        {meta && <p className="mt-1 text-xs text-muted-foreground">{meta}</p>}
+      </div>
+    </>
+  );
+  const className = "flex gap-4 rounded-lg p-3";
+  if (!hit.href) return <div className={className}>{body}</div>;
+  return (
+    <a
+      href={hit.href}
+      aria-label={hit.title}
+      className={`${className} no-underline transition-colors hover:bg-secondary`}
+      onClick={
+        onNavigate
+          ? (e) => {
+              e.preventDefault();
+              onNavigate(hit.href);
+            }
+          : undefined
+      }
+    >
+      {body}
+    </a>
+  );
+}