@wix/agent-skills 1.21.0 → 1.23.0

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/shop-store.ts

@@ -1,289 +0,0 @@
-// The shop listing as a framework-free store — the logic behind useShop, usable from React
-// (useShop wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
-// render), or as the specification for a port. Same shape as cart-store.ts: state, actions,
-// subscribe/getState, emit after every change.
-//
-// Category, sort, price/stock/search filters, option facets, and cursor paging are all applied
-// by Wix across the whole catalog (searchCatalog), never to a page already in hand. A changed
-// selection starts a fresh cursor chain; a late response from a superseded query is dropped.
-//
-// SSR-friendly: seed with `initialProducts`/`initialCategories` and they render at once; `start()`
-// then revalidates the first page to open the cursor chain, replacing the seed without a
-// skeleton flash. `initialCategoryId` scopes the first query (a /category/[slug] page).
-//
-// URL state: sort, filters, facet choices (and a live category switch on /shop) are read from the
-// query string by `start()` and written back with replaceState after every change — a filtered
-// gallery is a link a shopper can share, reload, and step back to. Paging stays out of the URL.
-//
-// One store per mounted listing (a page can hold a shop and a featured rail): createShopStore(),
-// not a singleton. The cart store is a singleton because the cart is one per visitor.
-import { CATALOG_SORTS, fetchCategories, fetchFacetData, searchCatalog, type CatalogSort } from "./catalog";
-import type { Category, Facet, PriceRange, ProductSummary } from "./types";
-
-export const SORTS = CATALOG_SORTS;
-
-export interface ShopFilters {
-  minPrice?: number | string;
-  maxPrice?: number | string;
-  inStockOnly?: boolean;
-  /** Name search, max 100 chars. */
-  search?: string;
-}
-
-export interface ShopStoreOptions {
-  initialProducts?: ProductSummary[];
-  initialCategories?: Category[];
-  /** Scope the listing to one category from the first render (a /category/[slug] page). */
-  initialCategoryId?: string | null;
-  pageSize?: number;
-  /** Mirror the selection into the query string (default true; off for a rail that isn't the page's subject). */
-  syncUrl?: boolean;
-}
-
-/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
-export interface ShopState {
-  /** null while the first load is in flight — render skeletons, not an empty state. */
-  products: ProductSummary[] | null;
-  /** Matching products across the whole catalog for the current selection; null until known. */
-  total: number | null;
-  categories: Category[];
-  /** null = "all products". */
-  activeCategoryId: string | null;
-  sort: CatalogSort;
-  filters: ShopFilters;
-  /** The filterable options of the current scope (Color, Size…), from the catalog itself. */
-  facets: Facet[];
-  /** Lowest and highest product price in the scope — the price slider's bounds; null until known or when equal. */
-  priceRange: PriceRange | null;
-  /** Selected facet choice ids — products carrying ANY of them match. */
-  selectedChoiceIds: string[];
-  /** True when any filter or facet is active. */
-  hasActiveFilters: boolean;
-  loading: boolean;
-  error: string | null;
-  hasMore: boolean;
-  loadingMore: boolean;
-}
-
-export interface ShopStore {
-  getState(): ShopState;
-  subscribe(listener: () => void): () => void;
-  /** Adopt the URL, fetch categories/facets, open the cursor chain. Call once when mounted (a browser). */
-  start(): void;
-  /** Stop reacting; drop late responses. */
-  stop(): void;
-  setActiveCategoryId(id: string | null): void;
-  setSort(sort: CatalogSort): void;
-  setFilters(filters: ShopFilters): void;
-  toggleChoice(choiceId: string): void;
-  /** Clears price/stock/search filters and facet selections (keeps category and sort). */
-  clearFilters(): void;
-  retry(): void;
-  loadMore(): Promise<void>;
-}
-
-const URL_KEYS = { sort: "sort", min: "min", max: "max", stock: "stock", q: "q", choice: "choice", category: "category" } as const;
-
-function readUrlState(): { sort?: CatalogSort; filters: ShopFilters; choiceIds: string[]; categoryId?: string | null } | null {
-  if (typeof window === "undefined") return null;
-  const p = new URLSearchParams(window.location.search);
-  const sort = p.get(URL_KEYS.sort);
-  const filters: ShopFilters = {};
-  if (p.get(URL_KEYS.min)) filters.minPrice = p.get(URL_KEYS.min)!;
-  if (p.get(URL_KEYS.max)) filters.maxPrice = p.get(URL_KEYS.max)!;
-  if (p.get(URL_KEYS.stock) === "1") filters.inStockOnly = true;
-  if (p.get(URL_KEYS.q)) filters.search = p.get(URL_KEYS.q)!;
-  return {
-    sort: sort && sort in CATALOG_SORTS ? (sort as CatalogSort) : undefined,
-    filters,
-    choiceIds: p.getAll(URL_KEYS.choice),
-    categoryId: p.has(URL_KEYS.category) ? p.get(URL_KEYS.category) : undefined,
-  };
-}
-
-function writeUrlState(s: { sort: CatalogSort; filters: ShopFilters; selectedChoiceIds: string[]; activeCategoryId: string | null }, initialCategoryId: string | null): void {
-  if (typeof window === "undefined") return;
-  const p = new URLSearchParams(window.location.search);
-  for (const k of Object.values(URL_KEYS)) p.delete(k);
-  if (s.sort !== "featured") p.set(URL_KEYS.sort, s.sort);
-  if (s.filters.minPrice != null && s.filters.minPrice !== "") p.set(URL_KEYS.min, String(s.filters.minPrice));
-  if (s.filters.maxPrice != null && s.filters.maxPrice !== "") p.set(URL_KEYS.max, String(s.filters.maxPrice));
-  if (s.filters.inStockOnly) p.set(URL_KEYS.stock, "1");
-  if (s.filters.search?.trim()) p.set(URL_KEYS.q, s.filters.search.trim());
-  for (const id of s.selectedChoiceIds) p.append(URL_KEYS.choice, id);
-  if (s.activeCategoryId !== initialCategoryId) p.set(URL_KEYS.category, s.activeCategoryId ?? "");
-  const qs = p.toString();
-  const next = `${window.location.pathname}${qs ? `?${qs}` : ""}${window.location.hash}`;
-  if (next !== `${window.location.pathname}${window.location.search}${window.location.hash}`) window.history.replaceState(window.history.state, "", next);
-}
-
-export function createShopStore({ initialProducts, initialCategories, initialCategoryId = null, pageSize = 24, syncUrl = true }: ShopStoreOptions = {}): ShopStore {
-  // selection
-  let activeCategoryId: string | null = initialCategoryId;
-  let sort: CatalogSort = "featured";
-  let filters: ShopFilters = {};
-  let selectedChoiceIds: string[] = [];
-  let attempt = 0;
-  // data
-  let categories: Category[] = initialCategories ?? [];
-  let facets: Facet[] = [];
-  let priceRange: PriceRange | null = null;
-  // the current page; `key` is the selection it answers to (null = the SSR seed, no query yet)
-  let pageKey: string | null = null;
-  let products: ProductSummary[] | null = initialProducts ?? null;
-  let total: number | null = null;
-  let cursor: string | null = null;
-  let error: string | null = null;
-  let loadingMore = false;
-  // control
-  let started = false;
-  let generation = 0;
-  let pendingMore: object | null = null;
-  const listeners = new Set<() => void>();
-
-  const selectionKey = () =>
-    JSON.stringify([pageSize, activeCategoryId, sort, filters.minPrice ?? null, filters.maxPrice ?? null, !!filters.inStockOnly, filters.search ?? "", [...selectedChoiceIds].sort(), attempt]);
-
-  let snapshot: ShopState | null = null;
-  const emit = () => {
-    snapshot = null;
-    for (const fn of listeners) fn();
-  };
-
-  function getState(): ShopState {
-    if (snapshot) return snapshot;
-    const key = selectionKey();
-    const current = pageKey === key;
-    const seeded = pageKey === null && products !== null; // SSR seed, first query in flight
-    const hasActiveFilters =
-      selectedChoiceIds.length > 0 ||
-      !!filters.inStockOnly ||
-      (filters.minPrice != null && filters.minPrice !== "") ||
-      (filters.maxPrice != null && filters.maxPrice !== "") ||
-      !!(filters.search && filters.search.trim());
-    snapshot = {
-      products: current || seeded ? products : null,
-      total: current ? total : null,
-      categories,
-      activeCategoryId,
-      sort,
-      filters,
-      facets,
-      priceRange,
-      selectedChoiceIds,
-      hasActiveFilters,
-      // Seeded content on screen is not "loading" — skeletons are only for a genuinely empty wait.
-      loading: (!current && !seeded) || (current && products === null),
-      error: current ? error : null,
-      hasMore: current && !!cursor,
-      loadingMore: current && loadingMore,
-    };
-    return snapshot;
-  }
-
-  // Facets follow the category scope (a Size facet in "Donuts" is meaningless).
-  let facetScope: string | null | undefined;
-  function loadFacets(): void {
-    if (facetScope === activeCategoryId) return;
-    facetScope = activeCategoryId;
-    const scope = activeCategoryId;
-    fetchFacetData({ categoryId: scope }).then((d) => {
-      if (!started || scope !== activeCategoryId) return;
-      facets = d.facets;
-      priceRange = d.priceRange;
-      emit();
-    });
-  }
-
-  // Run the query for the current selection. Keeps the seed (or the previous page) on screen while
-  // it runs; only a selection change with no seed shows skeletons.
-  function query(): void {
-    if (!started) return;
-    const key = selectionKey();
-    const id = ++generation;
-    pendingMore = null;
-    if (pageKey !== null) products = null;
-    pageKey = key; total = null; cursor = null; error = null; loadingMore = false;
-    emit();
-    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds] = JSON.parse(key);
-    searchCatalog({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds })
-      .then((res) => {
-        if (generation !== id || selectionKey() !== key) return; // superseded — drop it
-        products = res.products; total = res.total; cursor = res.nextCursor; error = null;
-        emit();
-      })
-      .catch((e) => {
-        if (generation !== id || selectionKey() !== key) return;
-        products = []; total = null; cursor = null;
-        error = e instanceof Error ? e.message : "Couldn't load products.";
-        emit();
-      });
-  }
-
-  function changed(): void {
-    if (syncUrl) writeUrlState({ sort, filters, selectedChoiceIds, activeCategoryId }, initialCategoryId);
-    loadFacets();
-    // A new filters object with the same values keeps the page (same selection, same query).
-    if (selectionKey() === pageKey) emit();
-    else query();
-  }
-
-  return {
-    getState,
-    subscribe(fn) {
-      listeners.add(fn);
-      return () => listeners.delete(fn);
-    },
-    start() {
-      if (started) return;
-      started = true;
-      // Adopt the URL's selection once (the server rendered the defaults).
-      const u = syncUrl ? readUrlState() : null;
-      if (u) {
-        if (u.sort) sort = u.sort;
-        if (Object.keys(u.filters).length) filters = u.filters;
-        if (u.choiceIds.length) selectedChoiceIds = u.choiceIds;
-        if (u.categoryId !== undefined && u.categoryId !== initialCategoryId) activeCategoryId = u.categoryId || null;
-      }
-      if (!initialCategories) {
-        fetchCategories().then((list) => { if (started) { categories = list; emit(); } }).catch(() => { if (started) { categories = []; emit(); } });
-      }
-      loadFacets();
-      query();
-    },
-    stop() {
-      started = false;
-      generation++;
-    },
-    setActiveCategoryId(id) { if (id === activeCategoryId) return; activeCategoryId = id; changed(); },
-    setSort(next) { if (next === sort) return; sort = next; changed(); },
-    setFilters(next) { filters = next; changed(); },
-    toggleChoice(choiceId) {
-      selectedChoiceIds = selectedChoiceIds.includes(choiceId) ? selectedChoiceIds.filter((x) => x !== choiceId) : [...selectedChoiceIds, choiceId];
-      changed();
-    },
-    clearFilters() { filters = {}; selectedChoiceIds = []; changed(); },
-    retry() { attempt++; changed(); },
-    async loadMore() {
-      const key = selectionKey();
-      if (pageKey !== key || !cursor || pendingMore) return;
-      const request = { generation, key };
-      pendingMore = request; // blocks repeated clicks before a re-render
-      const isCurrent = () => generation === request.generation && selectionKey() === key;
-      loadingMore = true; error = null; emit();
-      try {
-        const res = await searchCatalog({ limit: pageSize, cursor });
-        if (isCurrent()) {
-          const seen = new Set((products ?? []).map((p) => p.id));
-          products = [...(products ?? []), ...res.products.filter((p) => (seen.has(p.id) ? false : (seen.add(p.id), true)))];
-          cursor = res.nextCursor;
-        }
-      } catch (e) {
-        if (isCurrent()) error = e instanceof Error ? e.message : "Couldn't load more products.";
-      } finally {
-        if (pendingMore === request) pendingMore = null;
-        if (isCurrent()) { loadingMore = false; emit(); }
-      }
-    },
-  };
-}

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

@@ -1,169 +0,0 @@
-// Storefront DTOs — the serializable shapes every hook, component, and page consumes.
-// These are plain JSON: safe to pass as Astro island props or across a server/client
-// boundary. Image values are already-resolved https URLs (never wix:image://), and every
-// displayable price is a ready formatted string.
-
-export type Availability = "IN_STOCK" | "OUT_OF_STOCK" | "PARTIALLY_OUT_OF_STOCK";
-
-/** A product as a listing/grid tile needs it. */
-export interface ProductSummary {
-  id: string;
-  slug: string;
-  name: string;
-  /**
-   * The price the buyer pays for the cheapest variant, formatted (an automatic discount already
-   * applied). When `price !== maxPrice` the product is a RANGE — render "price – maxPrice".
-   */
-  price: string;
-  /** Highest variant price, formatted — differs from `price` when variants are priced differently. */
-  maxPrice: string;
-  /**
-   * Struck "was" price, formatted; null when not on sale — and ALWAYS null for a range (a lone
-   * struck minimum beside a range claims a saving that may not apply to the variant picked).
-   */
-  compareAtPrice: string | null;
-  /** The primary merchant ribbon ("New", "Best Seller"); null when none. Same as ribbons[0]. */
-  ribbon: string | null;
-  /** EVERY merchant ribbon, primary first ("New", "Sale") — render all of them, one shared style. */
-  ribbons: string[];
-  /** The cheapest variant's id — what a direct add sends for a product with no options; null when unknown. */
-  minPriceVariantId: string | null;
-  availability: Availability;
-  /** OUT_OF_STOCK but pre-orderable — label "Pre-order", not "Sold out". */
-  preorder: boolean;
-  /** Resolved https URL of the main image ("" when the product has none). */
-  imageUrl: string;
-  /** Resolved https URL of the second gallery image ("" when there is only one). */
-  hoverImageUrl: string;
-  /** e.g. "2 colors · 3 sizes"; "" for a single-variant product. */
-  optionsSummary: string;
-  /**
-   * Hex colors of a color option's visible choices, catalog order — render as small dots on the
-   * tile (a preview, not a picker: selection happens in QuickAdd or on the PDP). [] when none.
-   */
-  swatches: string[];
-  /** True when the product can be added to the cart with no choices (single variant, in stock). */
-  quickAddable: boolean;
-}
-
-export interface OptionChoice {
-  choiceId: string;
-  name: string;
-  /** Hex color for swatch rendering; null for text choices. */
-  colorCode: string | null;
-  inStock: boolean;
-}
-
-export interface ProductOption {
-  id: string;
-  name: string;
-  /** Render choices as color swatches (true) or text pills (false). */
-  isColor: boolean;
-  choices: OptionChoice[];
-}
-
-export interface ProductModifier {
-  key: string;
-  name: string;
-  mandatory: boolean;
-  /** "choices" renders pills; "text" renders a free-text input. */
-  type: "choices" | "text";
-  choices: { key: string; name: string }[];
-}
-
-export interface ProductVariant {
-  variantId: string;
-  /** The option selections this variant answers to: optionName -> choiceName. */
-  choices: Record<string, string>;
-  /** The price the buyer pays, formatted — an automatic discount beats the regular price. */
-  price: string;
-  /** Struck "was" price, formatted; null unless it is real and higher than `price`. */
-  compareAtPrice: string | null;
-  inStock: boolean;
-  /** Out of stock but pre-orderable — still buyable (the add carries preOrderRequested). */
-  preorderEnabled: boolean;
-  /** This variant's own image (from its choice's linked media), resolved to an https URL; null when it has none. */
-  imageUrl: string | null;
-}
-
-/** A product as the detail page needs it. */
-export interface ProductDetail extends ProductSummary {
-  /** Product description as an HTML string — render with innerHTML, not as text. */
-  descriptionHtml: string;
-  /** Merchant info sections (materials, shipping, care…) — title + HTML; render as sections or accordions. */
-  infoSections: { title: string; html: string }[];
-  /** Every gallery image as a resolved https URL, main image first, de-duplicated. */
-  gallery: string[];
-  options: ProductOption[];
-  modifiers: ProductModifier[];
-  variants: ProductVariant[];
-}
-
-export interface Category {
-  id: string;
-  slug: string;
-  name: string;
-  /** Plain-text description when the merchant wrote one; "" otherwise. */
-  description: string;
-}
-
-export interface FacetChoice {
-  /** The option choice id — what searchCatalog({ choiceIds }) filters on. */
-  id: string;
-  name: string;
-  /** Hex color for a swatch facet; null for a text facet. */
-  colorCode: string | null;
-}
-
-/** One filterable option across the catalog (or a category): "Color" with its choices. */
-export interface Facet {
-  name: string;
-  isColor: boolean;
-  choices: FacetChoice[];
-}
-
-/** The catalog's (or category's) lowest and highest product price, as numbers in site currency — the slider's bounds. */
-export interface PriceRange {
-  min: number;
-  max: number;
-  currency: string;
-}
-
-/** What the filter panel needs beyond the product page: the facets and the price bounds of the scope. */
-export interface FacetData {
-  facets: Facet[];
-  priceRange: PriceRange | null;
-}
-
-export interface CartLine {
-  /** The cart line id — what update/remove take (NOT the product id). */
-  lineItemId: string;
-  productName: string;
-  quantity: number;
-  /** Per-unit price, formatted. */
-  unitPrice: string;
-  /** Line total, formatted. */
-  linePrice: string;
-  /** Resolved https URL ("" when none). */
-  imageUrl: string;
-  /** Human-readable option/modifier labels, e.g. ["Color: Ink", "Size: M"]. */
-  descriptionLines: string[];
-  /** Not IN_STOCK → the line can't be checked out as-is. */
-  status: string;
-  /**
-   * The recurring plan's terms for a subscription line — "Monthly plan · every month · 12 payments";
-   * "" for a one-time purchase. A subscription line must read as one in the cart.
-   */
-  subscription: string;
-}
-
-export interface Cart {
-  lines: CartLine[];
-  /** Sum of line quantities. */
-  itemCount: number;
-  /** Formatted subtotal (after discounts) — from the cart estimate, not hand-summed. */
-  subtotal: string;
-  /** Formatted CART-level discount (a coupon or cart rule) — "" when none; item discounts are already in subtotal. */
-  discount: string;
-  currency: string;
-}

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

@@ -1,65 +0,0 @@
----
-// The site chrome for every storefront 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> (the product page's owner-editable SEO lands there,
-//     including the <title> — which is why ours is printed only when the slot is empty)
-//   - the global.css import (Tailwind + the design tokens every shipped component reads)
-//   - one <CartButton> in the header and one <CartDrawer> per page (both client:only —
-//     they read browser cart state and must not server-render)
-//   - category links in the nav (or your own menu/footer) — every category page reachable by
-//     a real link (`/category/<slug>`), from the live tree, so a category the owner adds later
-//     shows up with no code change
-import CartButton from "../components/storefront/CartButton";
-import CartDrawer from "../components/storefront/CartDrawer";
-import { fetchCategories } from "../wix/storefront/catalog";
-import type { Category } from "../wix/storefront/types";
-import "../styles/global.css";
-
-interface Props {
-  title: string;
-  description?: string;
-}
-const { title, description } = Astro.props;
-
-// Non-fatal: the chrome renders without the links if the read fails. Six in the header keeps a
-// large tree from crowding it — put the rest in a menu or the footer, but keep them linked.
-let navCategories: Category[] = [];
-try {
-  navCategories = (await fetchCategories()).slice(0, 6);
-} catch {
-  /* the shop link still reaches everything */
-}
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    {/* The product page's <SEO.Tags> renders the <title>; print ours only when no page filled the slot — two titles otherwise. */}
-    {!Astro.slots.has("seo-tags") && <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">
-          <a href="/shop" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Shop</a>
-          {navCategories.map((c) => (
-            <a href={`/category/${c.slug}`} class="hidden text-foreground no-underline transition-colors hover:text-muted-foreground md:inline">{c.name}</a>
-          ))}
-          <CartButton client:only="react" />
-        </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>
-    <CartDrawer client:only="react" />
-  </body>
-</html>