@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-headless-fast/references/cms/app/hooks/cms/useItem.ts

@@ -0,0 +1,57 @@
+// One item — by `_id` or by a field match (slug routing). SSR-friendly: pass the
+// server-fetched item as `initialItem` and no client fetch happens; a SPA passes nothing.
+import { useEffect, useState } from "react";
+import { getItemBy, getItemById } from "../../wix/cms/items";
+import type { CmsItem } from "../../wix/cms/types";
+
+/** Exactly one of `id` / `by`. */
+export interface UseItemRef {
+  id?: string;
+  by?: { field: string; value: string | number };
+}
+
+export interface UseItemOptions {
+  initialItem?: CmsItem;
+  /** Reference field keys to inline as full items. */
+  include?: string[];
+}
+
+export interface UseItem {
+  /** null while loading OR when not found — branch on notFound for the miss state. */
+  item: CmsItem | null;
+  notFound: boolean;
+  error: string | null;
+}
+
+export function useItem(collectionId: string, ref: UseItemRef, options: UseItemOptions = {}): UseItem {
+  const { initialItem, include } = options;
+  const [item, setItem] = useState<CmsItem | null>(initialItem ?? null);
+  const [notFound, setNotFound] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (initialItem) return;
+    let alive = true;
+    const fetching = ref.id
+      ? getItemById(collectionId, ref.id, { include })
+      : ref.by
+        ? getItemBy(collectionId, ref.by.field, ref.by.value, { include })
+        : Promise.reject(new Error("useItem: pass ref.id or ref.by"));
+    fetching
+      .then((found) => {
+        if (!alive) return;
+        setItem(found);
+        setNotFound(found === null);
+      })
+      .catch((e) => {
+        if (!alive) return;
+        setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collectionId, ref.id, ref.by?.field, ref.by?.value]);
+
+  return { item, notFound, error };
+}

package/skills/wix-headless-fast/references/cms/app/wix/cms/items.ts

@@ -0,0 +1,151 @@
+// Wix Data reads/writes (@wix/data `items`) — the only file that touches raw data items.
+// CMS is schema-generic: every function takes the collection id from the seed plan
+// (seed/SEED.md) and returns plain CmsItem DTOs from ./types. Copy as-is; extend by adding
+// functions, not by editing these.
+// docs: https://dev.wix.com/docs/sdk/business-solutions/data/items/query.md
+// docs: https://dev.wix.com/docs/sdk/business-solutions/data/items/update.md
+import { items as itemsModule } from "@wix/data";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import type { CmsFilter, CmsItem, CmsPage, CmsQuery } from "./types";
+
+const items = wixModule(itemsModule);
+
+type Raw = Record<string, any>;
+
+// SDK → DTO: the SDK decodes date fields into Date objects (not serializable as island
+// props) and IMAGE fields arrive as wix:image:// identifiers a browser can't load
+// (ERR_UNKNOWN_URL_SCHEME). Normalize recursively — included reference items too.
+function toValue(v: unknown): unknown {
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === "string" && v.startsWith("wix:image://")) return imgSrc(v, 1200, 900);
+  if (Array.isArray(v)) return v.map(toValue);
+  if (v && typeof v === "object") {
+    const out: Raw = {};
+    for (const [k, val] of Object.entries(v as Raw)) out[k] = toValue(val);
+    return out;
+  }
+  return v;
+}
+
+const toItem = (raw: Raw): CmsItem => toValue(raw) as CmsItem;
+
+// An undefined comparand silently changes what a query matches (every row, or none) with no
+// server error — the classic "my items shows everyone's items" bug. Throw at the call site;
+// omit the filter entirely when you don't hold a value yet.
+function assertFilterValue(f: CmsFilter): void {
+  if (f.op !== "isEmpty" && f.op !== "isNotEmpty" && f.value === undefined) {
+    throw new Error(
+      `cms: filter on "${f.field}" (${f.op}) has an undefined value — pass a real value or omit the filter.`,
+    );
+  }
+}
+
+/**
+ * Query one page of a collection. An empty result on a PUBLIC collection is a seed
+ * permissions bug (read must be "ANYONE"), not a query bug — never reach for auth.elevate.
+ */
+export async function queryItems(collectionId: string, query: CmsQuery = {}): Promise<CmsPage> {
+  const { filters = [], sort = [], limit = 20, skip = 0, include = [], withTotal = false } = query;
+  let q = items.query(collectionId);
+  for (const f of filters) {
+    assertFilterValue(f);
+    const v = f.value as any;
+    switch (f.op) {
+      case "eq": q = q.eq(f.field, v); break;
+      case "ne": q = q.ne(f.field, v); break;
+      case "gt": q = q.gt(f.field, v); break;
+      case "ge": q = q.ge(f.field, v); break;
+      case "lt": q = q.lt(f.field, v); break;
+      case "le": q = q.le(f.field, v); break;
+      case "contains": q = q.contains(f.field, v); break;
+      case "startsWith": q = q.startsWith(f.field, v); break;
+      case "hasSome": q = q.hasSome(f.field, v); break;
+      case "hasAll": q = q.hasAll(f.field, v); break;
+      case "isEmpty": q = q.isEmpty(f.field); break;
+      case "isNotEmpty": q = q.isNotEmpty(f.field); break;
+    }
+  }
+  for (const s of sort) q = s.direction === "desc" ? q.descending(s.field) : q.ascending(s.field);
+  if (include.length) q = q.include(...include);
+  const res = await q.limit(limit).skip(skip).find(withTotal ? { returnTotalCount: true } : undefined);
+  return {
+    items: (res.items ?? []).map((r: Raw) => toItem(r)),
+    hasNext: res.hasNext(),
+    total: res.totalCount ?? null,
+  };
+}
+
+/** Fetch one item by `_id`. Null when not found. */
+export async function getItemById(
+  collectionId: string,
+  itemId: string,
+  { include = [] }: { include?: string[] } = {},
+): Promise<CmsItem | null> {
+  const raw = await items.get(collectionId, itemId, {
+    ...(include.length ? { includeReferences: include.map((field) => ({ field })) } : {}),
+  });
+  return raw ? toItem(raw as Raw) : null;
+}
+
+/**
+ * Fetch the first item whose `field` equals `value` — slug-style routing (Wix Data has no
+ * native get-by-slug). Null when not found → render a not-found state, never invent an item.
+ */
+export async function getItemBy(
+  collectionId: string,
+  field: string,
+  value: string | number,
+  { include = [] }: { include?: string[] } = {},
+): Promise<CmsItem | null> {
+  const page = await queryItems(collectionId, { filters: [{ field, op: "eq", value }], limit: 1, include });
+  return page.items[0] ?? null;
+}
+
+/** Count items matching the filters — empty-state logic and result counts. */
+export async function countItems(collectionId: string, filters: CmsFilter[] = []): Promise<number> {
+  const page = await queryItems(collectionId, { filters, limit: 1, withTotal: true });
+  return page.total ?? page.items.length;
+}
+
+/**
+ * Insert an item (visitor form / member submission). Succeeds only when the collection's
+ * insert permission covers the caller (403 otherwise — a seed permissions step, not a code
+ * bug). Never set `_owner` — Wix stamps it from the caller's identity.
+ * Date fields must be Date objects (an ISO string is stored as text and breaks date queries).
+ */
+export async function insertItem(collectionId: string, data: Record<string, unknown>): Promise<CmsItem> {
+  const created = await items.insert(collectionId, data as Raw);
+  return toItem(created as Raw);
+}
+
+/**
+ * REPLACE an item — fields omitted from `item` are WIPED (update does not patch). Spread the
+ * full item you hold and override; for an id + a few changed fields use patchItemFields.
+ * A round-tripped DTO carries dates as ISO strings — wrap each date field back
+ * (`new Date(iso)`) before updating, or the DATE field is silently rewritten as text.
+ */
+export async function updateItem(collectionId: string, item: CmsItem): Promise<CmsItem> {
+  const updated = await items.update(collectionId, item as Raw & { _id: string });
+  return toItem(updated as Raw);
+}
+
+/** Patch only the named fields — the safe partial change (no replace-wipes-fields footgun). */
+export async function patchItemFields(
+  collectionId: string,
+  itemId: string,
+  fields: Record<string, unknown>,
+): Promise<CmsItem> {
+  const entries = Object.entries(fields);
+  if (!entries.length) throw new Error("cms: patchItemFields called with no fields.");
+  let p = items.patch(collectionId, itemId);
+  for (const [k, v] of entries) p = p.setField(k, v);
+  const patched = await p.run();
+  return toItem(patched as Raw);
+}
+
+/** Remove an item by `_id`. Irreversible. Returns the removed item (null if it didn't exist). */
+export async function removeItem(collectionId: string, itemId: string): Promise<CmsItem | null> {
+  const removed = await items.remove(collectionId, itemId);
+  return removed ? toItem(removed as Raw) : null;
+}

package/skills/wix-headless-fast/references/cms/app/wix/cms/types.ts

@@ -0,0 +1,75 @@
+// CMS DTOs — the serializable shapes every hook, component, and page consumes. CMS is
+// schema-generic: field keys come from the seed plan (seed/SEED.md), so an item is a flat
+// field map rather than a fixed interface. Plain JSON: safe as Astro island props or across
+// server/client boundaries. By the time an item leaves the data layer, Date fields are ISO
+// strings and IMAGE fields are resolved https URLs.
+
+/**
+ * One collection item: `_id` plus the collection's fields, flat on the item (there is no
+ * `item.data.*` — that is the REST shape and reads undefined here).
+ * Field values by type: TEXT/URL/EMAIL → string, NUMBER → number, BOOLEAN → boolean,
+ * DATE/DATETIME → ISO string, IMAGE → https URL ("" never happens — absent fields are
+ * undefined), RICH_TEXT → the stored HTML string, REFERENCE/MULTI_REFERENCE → id(s), or
+ * full CmsItem(s) when the query included the field.
+ */
+export interface CmsItem {
+  _id: string;
+  /** ISO string (the SDK's Date objects are serialized by the data layer). */
+  _createdDate?: string;
+  _updatedDate?: string;
+  /** Id of the member who created the row (member-scoped collections). */
+  _owner?: string;
+  [key: string]: unknown;
+}
+
+export type CmsFilterOp =
+  | "eq"
+  | "ne"
+  | "gt"
+  | "ge"
+  | "lt"
+  | "le"
+  | "contains"
+  | "startsWith"
+  | "hasSome"
+  | "hasAll"
+  | "isEmpty"
+  | "isNotEmpty";
+
+/**
+ * One query predicate. Comparands must match the field's stored type — a DATE/DATETIME
+ * field only matches a Date object (an ISO string compares as text and matches nothing).
+ */
+export interface CmsFilter {
+  field: string;
+  op: CmsFilterOp;
+  /** Required except for isEmpty/isNotEmpty; hasSome/hasAll take an array. */
+  value?: string | number | boolean | Date | (string | number | Date)[];
+}
+
+export interface CmsSort {
+  field: string;
+  /** Default "asc". */
+  direction?: "asc" | "desc";
+}
+
+export interface CmsQuery {
+  filters?: CmsFilter[];
+  sort?: CmsSort[];
+  /** Page size (default 20). */
+  limit?: number;
+  /** Items to skip — page N is skip = N * limit. */
+  skip?: number;
+  /** Reference field keys to inline as full items (otherwise the field holds ids). */
+  include?: string[];
+  /** true → the page carries `total` (slower query; for counts/empty-state logic). */
+  withTotal?: boolean;
+}
+
+/** One page of items. Load the next page with skip = items shown so far. */
+export interface CmsPage {
+  items: CmsItem[];
+  hasNext: boolean;
+  /** Total matching items — only when the query asked `withTotal`, else null. */
+  total: number | null;
+}

package/skills/wix-headless-fast/references/cms/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,41 @@
+---
+// The site chrome for every CMS page — THIS file (header/footer/nav) plus the @theme token
+// block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" /> in
+// <head> and the global.css import. Add one nav link per content surface you build (the
+// routes are yours — CMS ships no fixed pages). (If another vertical is also deployed, its
+// SiteLayout won; merge nav links there instead.)
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <!-- one link per content surface you build, e.g. <a href="/recipes">Recipes</a> -->
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+  </body>
+</html>