@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/faq/app/components/faq/FaqAccordion.tsx

@@ -0,0 +1,159 @@
+// REFERENCE accordion: the visible questions grouped by category, one expandable answer per question,
+// on the @theme tokens. Correct and complete; per the skill's model you design and build your own on
+// useFaq. Accessible by construction — the question is a <button aria-expanded aria-controls> inside a
+// heading, the answer a role="region" panel labelled by it, collapsed with `hidden` (so a no-JS visitor
+// and a search engine still get every answer in the HTML). No fetching, no routing; the ONLY HTML render
+// is `answerHtml`, which the core sanitized.
+import { useState, type ComponentType, type ReactNode } from "react";
+import { useFaq, type UseFaqOptions } from "../../hooks/faq/useFaq";
+import { anchorId, faqDeepLink } from "../../wix/faq/faq-core";
+import type { FaqQuestion, FaqSection } from "../../wix/faq/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+// The answer's HTML is plain tags (p, h4, ul/ol/li, blockquote, pre/code, a, img, hr, strong/em/u/s):
+// styled here through Tailwind's arbitrary-descendant variants, on the tokens.
+const ANSWER_CLASS =
+  "text-[15px] leading-relaxed text-foreground [&_p]:my-2 [&_h4]:mt-4 [&_h4]:mb-1 [&_h4]:font-semibold " +
+  "[&_ul]:my-2 [&_ul]:list-disc [&_ul]:pl-5 [&_ol]:my-2 [&_ol]:list-decimal [&_ol]:pl-5 [&_li]:my-1 " +
+  "[&_blockquote]:my-3 [&_blockquote]:border-l-2 [&_blockquote]:border-border [&_blockquote]:pl-4 [&_blockquote]:text-muted-foreground " +
+  "[&_pre]:my-3 [&_pre]:overflow-x-auto [&_pre]:rounded-md [&_pre]:bg-secondary [&_pre]:p-3 [&_pre]:text-sm " +
+  "[&_a]:underline [&_a]:underline-offset-2 [&_img]:my-3 [&_img]:max-w-full [&_img]:rounded-lg [&_hr]:my-4 [&_hr]:border-border";
+
+export interface FaqAccordionProps extends UseFaqOptions {
+  /** The FAQ page's path — the base of every copied deep link (default "/faq"). */
+  base?: string;
+  emptyMessage?: string;
+  /** Category headings above each group. Default: only while every category shows (no active filter). */
+  showCategoryHeadings?: boolean;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+function Skeleton() {
+  return (
+    <div aria-busy="true" className="divide-y divide-border">
+      {Array.from({ length: 5 }, (_, i) => (
+        <div key={i} className="py-5">
+          <div className="h-4 w-3/4 animate-pulse rounded bg-secondary" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default function FaqAccordion({
+  base = "/faq",
+  emptyMessage = "No questions yet.",
+  showCategoryHeadings,
+  LinkComponent = PlainLink,
+  ...options
+}: FaqAccordionProps) {
+  const { data, sections, visible, query, activeCategoryId, error, loading, isExpanded, toggleQuestion, setQuery, retry } = useFaq(options);
+  const [copiedId, setCopiedId] = useState<string | null>(null);
+  const headings = showCategoryHeadings ?? activeCategoryId === null;
+
+  // The deep link to one question, absolute when a browser is present. Clipboard access is browser-only
+  // and may be refused (insecure context); the link is also rendered as an <a>, so nothing is lost.
+  const copyLink = (q: FaqQuestion) => {
+    const href = faqDeepLink(q, base, activeCategoryId);
+    if (typeof navigator === "undefined" || !navigator.clipboard) return;
+    const abs = typeof location !== "undefined" ? new URL(href, location.href).toString() : href;
+    navigator.clipboard.writeText(abs).then(
+      () => {
+        setCopiedId(q.id);
+        setTimeout(() => setCopiedId((c) => (c === q.id ? null : c)), 2000);
+      },
+      () => {},
+    );
+  };
+
+  if (data === null) return <Skeleton />;
+
+  return (
+    <div>
+      {error && (
+        <p className="mb-4 flex items-center gap-3 text-sm text-destructive">
+          <span>{error}</span>
+          <button type="button" onClick={retry} disabled={loading} className="rounded-md border border-border px-3 py-1 text-foreground hover:bg-secondary disabled:opacity-50">
+            Try again
+          </button>
+        </p>
+      )}
+      {data.questions.length === 0 ? (
+        !error && <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : visible.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">
+          {query.trim() ? (
+            <>
+              No results for &ldquo;{query.trim()}&rdquo;.{" "}
+              <button type="button" onClick={() => setQuery("")} className="underline underline-offset-2 text-foreground">
+                Clear search
+              </button>
+            </>
+          ) : (
+            emptyMessage
+          )}
+        </p>
+      ) : (
+        sections.map((section: FaqSection) => (
+          <section key={section.category.id} aria-labelledby={headings ? `faq-cat-${section.category.id}` : undefined} className="mb-10">
+            {headings && (
+              <h2 id={`faq-cat-${section.category.id}`} className="mb-2 text-xl font-semibold tracking-tight">
+                {section.category.title}
+              </h2>
+            )}
+            <div className="divide-y divide-border border-y border-border">
+              {section.questions.map((q) => {
+                const expanded = isExpanded(q.id);
+                const id = anchorId(q);
+                return (
+                  <div key={q.id} id={id} className="scroll-mt-24">
+                    <h3 className="m-0">
+                      <button
+                        type="button"
+                        id={`${id}-button`}
+                        aria-expanded={expanded}
+                        aria-controls={`${id}-panel`}
+                        onClick={() => toggleQuestion(q.id)}
+                        className="flex w-full items-start justify-between gap-4 py-4 text-left text-base font-medium text-foreground hover:text-muted-foreground"
+                      >
+                        <span>{q.question}</span>
+                        <span aria-hidden="true" className={`mt-1 shrink-0 text-muted-foreground transition-transform ${expanded ? "rotate-45" : ""}`}>
+                          +
+                        </span>
+                      </button>
+                    </h3>
+                    <div id={`${id}-panel`} role="region" aria-labelledby={`${id}-button`} hidden={!expanded} className="pb-5">
+                      <div className={ANSWER_CLASS} dangerouslySetInnerHTML={{ __html: q.answerHtml }} />
+                      <p className="mt-3 flex items-center gap-3 text-xs text-muted-foreground">
+                        <LinkComponent href={faqDeepLink(q, base, activeCategoryId)} className="underline underline-offset-2">
+                          Link to this question
+                        </LinkComponent>
+                        <button type="button" onClick={() => copyLink(q)} className="underline underline-offset-2">
+                          {copiedId === q.id ? "Copied" : "Copy link"}
+                        </button>
+                      </p>
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          </section>
+        ))
+      )}
+      {data.truncated && (
+        <p className="mt-6 text-sm text-muted-foreground">Showing the first {data.questions.length} questions.</p>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-templates/faq/app/components/faq/FaqCategoryNav.tsx

@@ -0,0 +1,46 @@
+// REFERENCE category filter: "All" plus one pill per category that has questions, on the @theme
+// tokens. Correct and complete; per the skill's model you design and build your own on useFaq.
+// Renders nothing while fewer than two categories have questions. `asLinks` renders plain anchors to
+// `?category=<id>` instead of buttons — a no-JS fallback (the page pre-selects the category server-side).
+import { useFaq, type UseFaqOptions } from "../../hooks/faq/useFaq";
+
+export interface FaqCategoryNavProps extends UseFaqOptions {
+  /** The FAQ page's path (default "/faq") — the href base in asLinks mode. */
+  base?: string;
+  asLinks?: boolean;
+  allLabel?: string;
+}
+
+const pill = (active: boolean) =>
+  `rounded-control border px-4 py-1.5 text-sm font-medium transition-colors ${
+    active ? "border-primary bg-primary text-primary-foreground" : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function FaqCategoryNav({ base = "/faq", asLinks = false, allLabel = "All", ...options }: FaqCategoryNavProps) {
+  const { data, activeCategoryId, selectCategory } = useFaq(options);
+  const categories = (data?.categories ?? []).filter((c) => c.questionCount > 0);
+  if (categories.length < 2) return null;
+
+  const items = [{ id: null as string | null, title: allLabel }, ...categories.map((c) => ({ id: c.id as string | null, title: c.title }))];
+
+  return (
+    <nav aria-label="Categories" className="mb-8 flex flex-wrap gap-2">
+      {items.map((item) =>
+        asLinks ? (
+          <a
+            key={item.id ?? "all"}
+            href={item.id ? `${base}?category=${encodeURIComponent(item.id)}` : base}
+            aria-current={activeCategoryId === item.id ? "page" : undefined}
+            className={`${pill(activeCategoryId === item.id)} no-underline`}
+          >
+            {item.title}
+          </a>
+        ) : (
+          <button key={item.id ?? "all"} type="button" aria-pressed={activeCategoryId === item.id} onClick={() => selectCategory(item.id)} className={pill(activeCategoryId === item.id)}>
+            {item.title}
+          </button>
+        ),
+      )}
+    </nav>
+  );
+}

package/skills/wix-headless-templates/faq/app/components/faq/FaqSearch.tsx

@@ -0,0 +1,56 @@
+// REFERENCE search box: a labelled <input type="search"> debounced 250 ms into the store's query (Enter
+// and clearing flush at once), with the results count announced to assistive tech. Correct and
+// complete; per the skill's model you design and build your own on useFaq. Search runs client-side over
+// the loaded questions and answers (the API has no substring search) — nothing here fetches.
+import { useEffect, useRef, useState } from "react";
+import { useFaq, type UseFaqOptions } from "../../hooks/faq/useFaq";
+
+export interface FaqSearchProps extends UseFaqOptions {
+  label?: string;
+  placeholder?: string;
+  /** Debounce in ms (default 250). */
+  delay?: number;
+}
+
+export default function FaqSearch({ label = "Search questions", placeholder = "Search…", delay = 250, ...options }: FaqSearchProps) {
+  const { query, setQuery, resultsCount, data } = useFaq(options);
+  const [draft, setDraft] = useState(query);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // The store's query can change from elsewhere (the accordion's "Clear search") — mirror it.
+  useEffect(() => setDraft(query), [query]);
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+
+  const flush = (value: string) => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+    setQuery(value);
+  };
+  const onChange = (value: string) => {
+    setDraft(value);
+    if (timer.current) clearTimeout(timer.current);
+    if (!value.trim()) return flush("");
+    timer.current = setTimeout(() => flush(value), delay);
+  };
+
+  const active = query.trim().length > 0 && data !== null;
+  return (
+    <form role="search" onSubmit={(e) => { e.preventDefault(); flush(draft); }} className="mb-6">
+      <label htmlFor="faq-search" className="eyebrow mb-2 block">
+        {label}
+      </label>
+      <input
+        id="faq-search"
+        type="search"
+        value={draft}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        autoComplete="off"
+        className="w-full rounded-lg border border-border bg-background px-4 py-2.5 text-base text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-primary"
+      />
+      <p aria-live="polite" className="mt-2 min-h-5 text-sm text-muted-foreground">
+        {active ? `${resultsCount} ${resultsCount === 1 ? "result" : "results"}` : ""}
+      </p>
+    </form>
+  );
+}

package/skills/wix-headless-templates/faq/app/hooks/faq/useFaq.ts

@@ -0,0 +1,53 @@
+// React binding of the FAQ store (wix/faq/faq-store.ts) — the state machine (category filter, search,
+// accordion, URL state, the load) lives there, framework-free and module-scoped; this hook seeds it
+// with the island's SSR props during render and subscribes with useSyncExternalStore. Every island on
+// the page calls it and they all see one state. Astro islands and React SPAs use this; a static page,
+// Vue, or Svelte uses the store directly.
+import { useMemo, useSyncExternalStore } from "react";
+import {
+  collapseAll,
+  expandQuestion,
+  getFaqState,
+  retry,
+  seedFaq,
+  selectCategory,
+  setQuery,
+  subscribeFaq,
+  toggleQuestion,
+  type FaqState,
+  type FaqStoreOptions,
+} from "../../wix/faq/faq-store";
+import { groupByCategory } from "../../wix/faq/faq-core";
+import type { FaqSection } from "../../wix/faq/types";
+
+export type UseFaqOptions = FaqStoreOptions;
+
+export interface UseFaq extends FaqState {
+  /** The visible questions grouped by category in owner order (one section when a category is active). */
+  sections: FaqSection[];
+  isExpanded(id: string): boolean;
+  selectCategory: typeof selectCategory;
+  setQuery: typeof setQuery;
+  toggleQuestion: typeof toggleQuestion;
+  expandQuestion: typeof expandQuestion;
+  collapseAll: typeof collapseAll;
+  retry: typeof retry;
+}
+
+export function useFaq(options: UseFaqOptions = {}): UseFaq {
+  // Idempotent in the browser (the first island seeds); on the server it makes this request's data current.
+  seedFaq(options);
+  const state = useSyncExternalStore(subscribeFaq, getFaqState, getFaqState);
+  const sections = useMemo(() => groupByCategory(state.data?.categories ?? [], state.visible), [state.data, state.visible]);
+  return {
+    ...state,
+    sections,
+    isExpanded: (id) => state.expandedIds.includes(id),
+    selectCategory,
+    setQuery,
+    toggleQuestion,
+    expandQuestion,
+    collapseAll,
+    retry,
+  };
+}