@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-headless-fast/references/portfolio/app/hooks/portfolio/useCollections.ts

@@ -0,0 +1,39 @@
+// Collections gallery. SSR-friendly: pass server-fetched data as `initialCollections`
+// (Astro frontmatter / server component) and no client fetch happens; a SPA passes nothing.
+import { useEffect, useState } from "react";
+import { fetchCollections } from "../../wix/portfolio/portfolio";
+import type { CollectionSummary } from "../../wix/portfolio/types";
+
+export interface UseCollectionsOptions {
+  initialCollections?: CollectionSummary[];
+}
+
+export interface UseCollections {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  collections: CollectionSummary[] | null;
+  error: string | null;
+}
+
+export function useCollections({ initialCollections }: UseCollectionsOptions = {}): UseCollections {
+  const [collections, setCollections] = useState<CollectionSummary[] | null>(initialCollections ?? null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (!initialCollections) {
+      fetchCollections()
+        .then((c) => alive && setCollections(c))
+        .catch((e) => {
+          if (!alive) return;
+          setCollections([]);
+          setError(e instanceof Error ? e.message : String(e));
+        });
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return { collections, error };
+}

package/skills/wix-headless-fast/references/portfolio/app/hooks/portfolio/useProjectDetail.ts

@@ -0,0 +1,58 @@
+// Project detail + media gallery, by slug. SSR-friendly: pass both `initial*` and no client
+// fetch happens. `notFound` is the real not-found signal (project stays null while loading).
+import { useEffect, useState } from "react";
+import { fetchProjectBySlug, fetchProjectGallery } from "../../wix/portfolio/portfolio";
+import type { GalleryItem, ProjectDetail } from "../../wix/portfolio/types";
+
+export interface UseProjectDetailOptions {
+  initialProject?: ProjectDetail;
+  initialItems?: GalleryItem[];
+}
+
+export interface UseProjectDetail {
+  /** null while loading AND when not found — check `notFound` to tell them apart. */
+  project: ProjectDetail | null;
+  notFound: boolean;
+  /** null while the gallery load is in flight — render skeletons, not an empty state. */
+  items: GalleryItem[] | null;
+  error: string | null;
+}
+
+export function useProjectDetail(
+  slug: string,
+  { initialProject, initialItems }: UseProjectDetailOptions = {},
+): UseProjectDetail {
+  const [project, setProject] = useState<ProjectDetail | null>(initialProject ?? null);
+  const [notFound, setNotFound] = useState(false);
+  const [items, setItems] = useState<GalleryItem[] | null>(initialItems ?? null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (initialProject && initialItems) return;
+    let alive = true;
+    (async () => {
+      try {
+        const proj = initialProject ?? (await fetchProjectBySlug(slug));
+        if (!alive) return;
+        if (!proj) {
+          setNotFound(true);
+          setItems([]);
+          return;
+        }
+        setProject(proj);
+        const gallery = await fetchProjectGallery(proj.id);
+        if (alive) setItems(gallery);
+      } catch (e) {
+        if (!alive) return;
+        setItems([]);
+        setError(e instanceof Error ? e.message : String(e));
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [slug]);
+
+  return { project, notFound, items, error };
+}

package/skills/wix-headless-fast/references/portfolio/app/wix/portfolio/portfolio.ts

@@ -0,0 +1,165 @@
+// Portfolio reads (Wix Portfolio v1) — the only file that touches raw portfolio entities.
+// Read-only vertical: no cart, no checkout, no @wix/ecom. Everything it returns is a plain
+// DTO from ./types. Copy as-is; extend by adding functions, not by editing these.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/list-collections.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/list-projects.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/list-project-items.md
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import {
+  collections as collectionsModule,
+  projects as projectsModule,
+  projectItems as projectItemsModule,
+} from "@wix/portfolio";
+import { media, VideoResolution } from "@wix/sdk";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import type {
+  CollectionSummary,
+  GalleryItem,
+  ProjectDetail,
+  ProjectDetailRow,
+  ProjectSummary,
+} from "./types";
+
+const collections = wixModule(collectionsModule);
+const projects = wixModule(projectsModule);
+const projectItems = wixModule(projectItemsModule);
+
+type Raw = Record<string, any>;
+
+// The SDK types coverImage.imageInfo / item.image.imageInfo as a bare wix:image:// STRING
+// (the REST docs show an object with .url — the package wins); imgSrc resolves either shape.
+
+// videoInfo is likewise a bare wix:video:// string; getVideoUrl derives the mp4 rendition +
+// poster (a wix:image:// string → imgSrc again). 720p is the standard transcode. Tolerates
+// the REST-shaped object ({ resolutions, posters }) in case a surface returns it at runtime.
+function toVideo(value: unknown): { videoUrl: string | null; posterUrl: string } {
+  if (typeof value === "string" && value.startsWith("wix:video://")) {
+    try {
+      const v = media.getVideoUrl(value, VideoResolution.MID);
+      return { videoUrl: v.url, posterUrl: imgSrc(v.thumbnail, 1200, 675) };
+    } catch {
+      return { videoUrl: null, posterUrl: "" };
+    }
+  }
+  const raw = value as Raw | null | undefined;
+  const url = raw?.resolutions?.[0]?.url;
+  return {
+    videoUrl: typeof url === "string" ? url : null,
+    posterUrl: imgSrc(raw?.posters?.[0], 1200, 675),
+  };
+}
+
+function toCollection(raw: Raw): CollectionSummary {
+  return {
+    id: raw._id ?? "",
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    description: raw.description ?? "",
+    imageUrl: imgSrc(raw.coverImage?.imageInfo, 1200, 900),
+  };
+}
+
+// coverImage is ONE-OF with coverVideo — a video-covered project falls back to its poster.
+function projectCover(raw: Raw): string {
+  return imgSrc(raw.coverImage?.imageInfo, 1200, 900) || toVideo(raw.coverVideo?.videoInfo).posterUrl;
+}
+
+function toProject(raw: Raw): ProjectSummary {
+  return {
+    id: raw._id ?? "",
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    description: raw.description ?? "",
+    imageUrl: projectCover(raw),
+    collectionIds: raw.collectionIds ?? [],
+  };
+}
+
+// A details row is a one-of: { label, text } or { label, link: { text, url, target } }.
+function toDetailRow(raw: Raw): ProjectDetailRow {
+  return {
+    label: raw.label ?? "",
+    text: raw.link?.text ?? raw.text ?? "",
+    url: raw.link?.url ?? null,
+    target: raw.link?.target ?? null,
+  };
+}
+
+function toDetail(raw: Raw): ProjectDetail {
+  return { ...toProject(raw), details: (raw.details ?? []).map((d: Raw) => toDetailRow(d)) };
+}
+
+function toGalleryItem(raw: Raw): GalleryItem | null {
+  const base = {
+    id: raw._id ?? "",
+    title: raw.title ?? "",
+    description: raw.description ?? "",
+    linkUrl: raw.link?.url ?? null,
+    linkTarget: raw.link?.target ?? null,
+  };
+  if (raw.type === "IMAGE") {
+    const imageUrl = imgSrc(raw.image?.imageInfo, 1600, 1200);
+    return imageUrl ? { ...base, kind: "image", imageUrl, videoUrl: null } : null;
+  }
+  if (raw.type === "VIDEO") {
+    const { videoUrl, posterUrl } = toVideo(raw.video?.videoInfo);
+    return videoUrl ? { ...base, kind: "video", imageUrl: posterUrl, videoUrl } : null;
+  }
+  return null; // UNDEFINED — nothing renderable
+}
+
+/**
+ * List visible collections in the owner's dashboard order (sortOrder — collections have one,
+ * projects don't). An omitted `hidden` comes back ABSENT (proto3): test falsy, never === false.
+ */
+export async function fetchCollections({ limit = 100 } = {}): Promise<CollectionSummary[]> {
+  const res = await collections.listCollections({ paging: { limit } });
+  return (res.collections ?? [])
+    .filter((c: Raw) => !c.hidden)
+    .sort((a: Raw, b: Raw) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
+    .map((c: Raw) => toCollection(c));
+}
+
+/** Fetch one visible collection by its URL slug. Null when not found or hidden. */
+export async function fetchCollectionBySlug(slug: string): Promise<CollectionSummary | null> {
+  const res = await collections.queryCollections().eq("slug", slug).limit(1).find();
+  const raw = res.items?.[0] as Raw | undefined;
+  return raw && !raw.hidden ? toCollection(raw) : null;
+}
+
+/**
+ * List visible projects (list order — Project exposes no sortOrder), optionally only one
+ * collection's. The collection filter is client-side over the one list call (portfolios are
+ * small; a project links to collections via collectionIds).
+ */
+export async function fetchProjects({
+  collectionId,
+  limit = 100,
+}: { collectionId?: string; limit?: number } = {}): Promise<ProjectSummary[]> {
+  const res = await projects.listProjects({ paging: { limit } });
+  return (res.projects ?? [])
+    .filter((p: Raw) => !p.hidden)
+    .filter((p: Raw) => !collectionId || (p.collectionIds ?? []).includes(collectionId))
+    .map((p: Raw) => toProject(p));
+}
+
+/** Fetch one visible project by its URL slug. Null when not found or hidden. */
+export async function fetchProjectBySlug(slug: string): Promise<ProjectDetail | null> {
+  const res = await projects.queryProjects().eq("slug", slug).limit(1).find();
+  const raw = res.items?.[0] as Raw | undefined;
+  return raw && !raw.hidden ? toDetail(raw) : null;
+}
+
+/**
+ * A project's media gallery in dashboard order (item sortOrder). IMAGE and VIDEO items only —
+ * UNDEFINED and unresolvable media are dropped. First arg is the project _id (positional).
+ */
+export async function fetchProjectGallery(projectId: string): Promise<GalleryItem[]> {
+  const res = await projectItems.listProjectItems(projectId, { paging: { limit: 100 } });
+  return (res.items ?? [])
+    .slice()
+    .sort((a: Raw, b: Raw) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
+    .map((it: Raw) => toGalleryItem(it))
+    .filter((g: GalleryItem | null): g is GalleryItem => g !== null);
+}

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

@@ -0,0 +1,55 @@
+// Portfolio DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. Images are
+// resolved https URLs; videos are playable mp4 URLs with a poster frame.
+
+/** A collection as the gallery grid needs it. */
+export interface CollectionSummary {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  /** Resolved https URL ("" when the collection has no cover). */
+  imageUrl: string;
+}
+
+/** A project as a grid tile needs it. */
+export interface ProjectSummary {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  /** Cover image; a video-covered project falls back to its poster frame ("" when neither). */
+  imageUrl: string;
+  /** The collections this project belongs to (a project can be in several). */
+  collectionIds: string[];
+}
+
+/** One row of a project's metadata (Role, Year, Client…): plain text or an outbound link. */
+export interface ProjectDetailRow {
+  label: string;
+  text: string;
+  /** Non-null → render the row's text as a link. */
+  url: string | null;
+  /** Link rows only: "_blank" | "_self". */
+  target: string | null;
+}
+
+/** A project as the detail page needs it. */
+export interface ProjectDetail extends ProjectSummary {
+  details: ProjectDetailRow[];
+}
+
+/** One media item of a project's gallery (dashboard order). */
+export interface GalleryItem {
+  id: string;
+  kind: "image" | "video";
+  title: string;
+  description: string;
+  /** image: the resolved image. video: the poster frame ("" when the video has none). */
+  imageUrl: string;
+  /** video only: playable mp4 URL. */
+  videoUrl: string | null;
+  /** Optional owner-attached outbound link for this item. */
+  linkUrl: string | null;
+  linkTarget: string | null;
+}

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

@@ -0,0 +1,40 @@
+---
+// The site chrome for every portfolio 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. (Deploy is fill-only: if another vertical is already
+// deployed, its SiteLayout won — merge a Portfolio nav link 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">
+          <a href="/portfolio" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Portfolio</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>

package/skills/wix-headless-fast/references/portfolio/app-astro/pages/portfolio/[slug].astro

@@ -0,0 +1,30 @@
+---
+// Collection page — header + its projects, resolved by slug SERVER-SIDE.
+// Portfolio has no documented Wix SEO item type, so this page carries plain
+// <title>/<meta description> from the DTO (no wixMetadata / <SEO.Tags> — unlike
+// storefront/bookings item pages). Keep the frontmatter; swap the island import to YOUR
+// collection-page component.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import CollectionProjectsView from "../../components/portfolio/CollectionProjectsView";
+import { fetchCollectionBySlug, fetchProjects } from "../../wix/portfolio/portfolio";
+import type { CollectionSummary, ProjectSummary } from "../../wix/portfolio/types";
+
+const slug = Astro.params.slug!;
+
+let collection: CollectionSummary | null = null;
+let projects: ProjectSummary[] = [];
+try {
+  collection = await fetchCollectionBySlug(slug);
+  if (collection) projects = await fetchProjects({ collectionId: collection.id });
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!collection) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={collection.title} description={collection.description}>
+  <CollectionProjectsView client:load slug={slug} initialCollection={collection} initialProjects={projects} />
+</SiteLayout>

package/skills/wix-headless-fast/references/portfolio/app-astro/pages/portfolio.astro

@@ -0,0 +1,21 @@
+---
+// Collections gallery — data fetched SERVER-SIDE (SEO) and handed to the island as DTO props.
+// Keep this frontmatter; swap the island import to YOUR gallery component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import CollectionsView from "../components/portfolio/CollectionsView";
+import { fetchCollections } from "../wix/portfolio/portfolio";
+import type { CollectionSummary } from "../wix/portfolio/types";
+
+let collections: CollectionSummary[] = [];
+try {
+  collections = await fetchCollections();
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Portfolio">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Portfolio</h1>
+  <CollectionsView client:load initialCollections={collections} />
+</SiteLayout>

package/skills/wix-headless-fast/references/portfolio/app-astro/pages/projects/[slug].astro

@@ -0,0 +1,29 @@
+---
+// Project detail page — project + media gallery, resolved by slug SERVER-SIDE.
+// Portfolio has no documented Wix SEO item type, so this page carries plain
+// <title>/<meta description> from the DTO (no wixMetadata / <SEO.Tags>). Keep the
+// frontmatter; swap the island import to YOUR detail component.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import ProjectDetailView from "../../components/portfolio/ProjectDetailView";
+import { fetchProjectBySlug, fetchProjectGallery } from "../../wix/portfolio/portfolio";
+import type { GalleryItem, ProjectDetail } from "../../wix/portfolio/types";
+
+const slug = Astro.params.slug!;
+
+let project: ProjectDetail | null = null;
+let items: GalleryItem[] = [];
+try {
+  project = await fetchProjectBySlug(slug);
+  if (project) items = await fetchProjectGallery(project.id);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!project) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={project.title} description={project.description}>
+  <ProjectDetailView client:load slug={slug} initialProject={project} initialItems={items} />
+</SiteLayout>