@wix/agent-skills 1.0.0

package/skills/wix-headless/shared-utilities/ricos.ts

@@ -0,0 +1,179 @@
+/**
+ * SSR-friendly Ricos JSON to HTML renderer.
+ *
+ * Ricos is Wix's structured rich-text format. CMS rich-text fields (about-content
+ * body, FAQ answer, etc.) are stored as a node tree, not HTML strings. The Wix
+ * dashboard's rich-text editor reads and writes this format.
+ *
+ * Use this util on Astro SSR pages that need to render Ricos content as HTML
+ * without pulling the full @wix/ricos React package (~80kb) into a static page.
+ * The blog vertical uses @wix/ricos's RicosViewer React component because blog
+ * posts can carry the full Ricos feature set (galleries, polls, embedded media).
+ * CMS pages render a much narrower subset, so this walker covers about 80% of
+ * what the dashboard editor produces:
+ *
+ *   - PARAGRAPH, HEADING (levels 1–6), BULLETED_LIST, ORDERED_LIST, LIST_ITEM
+ *   - BLOCKQUOTE, DIVIDER
+ *   - TEXT decorations: BOLD, ITALIC, UNDERLINE, LINK
+ *
+ * Anything outside this set is rendered as a defensive `<p>` with the raw
+ * `textData.text` (or empty string), so unknown nodes never throw — they
+ * just render plainly. Add cases as the CMS surface grows.
+ *
+ * Usage:
+ *   import { renderRicos } from "../utils/ricos";
+ *   ---
+ *   const html = renderRicos(item.body);
+ *   ---
+ *   <div class="prose" set:html={html} />
+ */
+
+type RicosTextDecoration =
+  | { type: "BOLD" }
+  | { type: "ITALIC" }
+  | { type: "UNDERLINE" }
+  | { type: "LINK"; linkData?: { link?: { url?: string; target?: string; rel?: string } } }
+  | { type: string; [key: string]: unknown };
+
+interface RicosTextData {
+  text?: string;
+  decorations?: RicosTextDecoration[];
+}
+
+interface RicosNode {
+  type?: string;
+  nodes?: RicosNode[];
+  textData?: RicosTextData;
+  headingData?: { level?: number };
+  [key: string]: unknown;
+}
+
+interface RicosDocument {
+  nodes?: RicosNode[];
+  [key: string]: unknown;
+}
+
+/**
+ * Render a Ricos document (or a JSON-encoded Ricos string) as HTML.
+ * Returns an empty string on null/undefined input — pages can `set:html=""`
+ * without throwing.
+ */
+export function renderRicos(
+  content: RicosDocument | string | null | undefined,
+): string {
+  if (!content) return "";
+
+  const doc = typeof content === "string" ? safeParse(content) : content;
+  if (!doc || !Array.isArray(doc.nodes)) return "";
+
+  return doc.nodes.map(renderBlockNode).join("");
+}
+
+function safeParse(raw: string): RicosDocument | null {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as RicosDocument;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function renderBlockNode(node: RicosNode): string {
+  switch (node.type) {
+    case "PARAGRAPH":
+      return `<p>${renderInlineChildren(node)}</p>`;
+
+    case "HEADING": {
+      const level = clampHeadingLevel(node.headingData?.level);
+      return `<h${level}>${renderInlineChildren(node)}</h${level}>`;
+    }
+
+    case "BULLETED_LIST":
+      return `<ul>${(node.nodes ?? []).map(renderBlockNode).join("")}</ul>`;
+
+    case "ORDERED_LIST":
+      return `<ol>${(node.nodes ?? []).map(renderBlockNode).join("")}</ol>`;
+
+    case "LIST_ITEM":
+      return `<li>${(node.nodes ?? []).map(renderBlockNode).join("")}</li>`;
+
+    case "BLOCKQUOTE":
+      return `<blockquote>${(node.nodes ?? []).map(renderBlockNode).join("")}</blockquote>`;
+
+    case "DIVIDER":
+      return "<hr />";
+
+    default:
+      return `<p>${renderInlineChildren(node)}</p>`;
+  }
+}
+
+function renderInlineChildren(node: RicosNode): string {
+  if (!Array.isArray(node.nodes)) return "";
+  return node.nodes.map(renderInlineNode).join("");
+}
+
+function renderInlineNode(node: RicosNode): string {
+  if (node.type !== "TEXT") {
+    if (Array.isArray(node.nodes)) return renderInlineChildren(node);
+    return "";
+  }
+
+  const text = escapeHtml(node.textData?.text ?? "");
+  const decorations = node.textData?.decorations ?? [];
+
+  let html = text;
+  let linkOpen = "";
+  let linkClose = "";
+
+  for (const decoration of decorations) {
+    switch (decoration.type) {
+      case "BOLD":
+        html = `<strong>${html}</strong>`;
+        break;
+      case "ITALIC":
+        html = `<em>${html}</em>`;
+        break;
+      case "UNDERLINE":
+        html = `<u>${html}</u>`;
+        break;
+      case "LINK": {
+        const url = decoration.linkData?.link?.url;
+        if (url) {
+          const target = decoration.linkData?.link?.target;
+          const rel = decoration.linkData?.link?.rel ?? (target === "_blank" ? "noopener noreferrer" : undefined);
+          linkOpen = `<a href="${escapeAttr(url)}"${target ? ` target="${escapeAttr(target)}"` : ""}${rel ? ` rel="${escapeAttr(rel)}"` : ""}>`;
+          linkClose = "</a>";
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  return `${linkOpen}${html}${linkClose}`;
+}
+
+function clampHeadingLevel(raw: number | undefined): 1 | 2 | 3 | 4 | 5 | 6 {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return 2;
+  const n = Math.floor(raw);
+  if (n < 1) return 1;
+  if (n > 6) return 6;
+  return n as 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;");
+}

package/skills/wix-headless/shared-utilities/wix-image.ts

@@ -0,0 +1,72 @@
+import { media } from "@wix/sdk";
+
+export type WixImage = {
+  url: string;
+  altText?: string;
+  width?: number;
+  height?: number;
+};
+
+export function resolveWixImage(
+  image: string | { id?: string; url?: string } | undefined
+): WixImage | null {
+  if (!image) return null;
+
+  if (typeof image === "string") {
+    if (image.startsWith("wix:image://")) {
+      const resolved = media.getImageUrl(image);
+      return { url: resolved.url, width: resolved.width, height: resolved.height };
+    }
+    return { url: image };
+  }
+
+  if (image.url) {
+    return { url: image.url };
+  }
+
+  if (image.id) {
+    const resolved = media.getImageUrl(image.id);
+    return { url: resolved.url, width: resolved.width, height: resolved.height };
+  }
+
+  return null;
+}
+
+export function scaledSrc(img: WixImage, width: number): string {
+  const url = new URL(img.url);
+  url.searchParams.set("w", String(width));
+  return url.toString();
+}
+
+export function srcSet(img: WixImage, widths: number[]): string {
+  return widths.map((w) => `${scaledSrc(img, w)} ${w}w`).join(", ");
+}
+
+// Consumed by every vertical that renders a Wix image at a specific size
+// (stores ProductCard + detail page, blog post hero, cms list thumbnails).
+// Kept alongside resolveWixImage so verticals do not ship their own copy.
+export function resolveWixImageUrl(
+  image: string | { id?: string; url?: string } | undefined,
+  width?: number,
+  height?: number,
+): string | null {
+  if (!image) return null;
+
+  if (
+    typeof image === "string" &&
+    image.startsWith("wix:image://") &&
+    width != null &&
+    height != null
+  ) {
+    return media.getScaledToFillImageUrl(image, width, height, {});
+  }
+
+  const resolved = resolveWixImage(image);
+  if (!resolved) return null;
+  if (width == null && height == null) return resolved.url;
+
+  const url = new URL(resolved.url);
+  if (width != null) url.searchParams.set("w", String(width));
+  if (height != null) url.searchParams.set("h", String(height));
+  return url.toString();
+}

package/skills/wix-headless/templates/ecom/CartBadge.tsx

@@ -0,0 +1,84 @@
+import { useState, useEffect } from "react";
+import { currentCart } from "@wix/ecom";
+
+// CartView writes { lineItems, summary } to sessionStorage on every successful
+// fetch/update. Read the snapshot here so the badge count renders instantly
+// on every navigation instead of flashing empty while the fresh fetch runs.
+// Same key as CartView; CartBadge is a read-only consumer.
+const CART_CACHE_KEY = "cart:last-snapshot";
+
+function readCachedCount(): number {
+  if (typeof window === "undefined") return 0;
+  try {
+    const raw = window.sessionStorage.getItem(CART_CACHE_KEY);
+    if (!raw) return 0;
+    const parsed = JSON.parse(raw);
+    const items = Array.isArray(parsed?.lineItems) ? parsed.lineItems : [];
+    return items.reduce(
+      (sum: number, item: any) => sum + (item?.quantity ?? 0),
+      0,
+    );
+  } catch {
+    return 0;
+  }
+}
+
+export default function CartBadge() {
+  const [count, setCount] = useState(() => readCachedCount());
+
+  const fetchCount = async () => {
+    try {
+      const cart = await currentCart.getCurrentCart();
+      const total = (cart.lineItems ?? []).reduce(
+        (sum, item) => sum + (item.quantity ?? 0),
+        0
+      );
+      setCount(total);
+    } catch {
+      setCount(0);
+    }
+  };
+
+  useEffect(() => {
+    // Always fetch client-side — cart count is per-visitor and must not
+    // be server-rendered (would break SSR caching)
+    fetchCount();
+
+    const handleCartUpdate = (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.cart?.lineItems) {
+        const total = (detail.cart.lineItems as any[]).reduce(
+          (sum: number, item: any) => sum + (item.quantity ?? 0),
+          0
+        );
+        setCount(total);
+      } else if (detail?.delta) {
+        setCount((prev) => prev + detail.delta);
+      } else {
+        fetchCount();
+      }
+    };
+    window.addEventListener("cart-updated", handleCartUpdate);
+    return () => window.removeEventListener("cart-updated", handleCartUpdate);
+  }, []);
+
+  return (
+    <a href="/cart" className="cart-badge" aria-label={count > 0 ? `Cart, ${count} items` : "Cart"}>
+      <svg
+        className="cart-badge-icon"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+        focusable="false"
+      >
+        <path d="M5 8h14l-1.2 10.2a2 2 0 0 1-2 1.8H8.2a2 2 0 0 1-2-1.8L5 8Z" />
+        <path d="M9 8V6a3 3 0 0 1 6 0v2" />
+      </svg>
+      {count > 0 && <span className="cart-badge-count">{count}</span>}
+    </a>
+  );
+}