@pantheon-systems/create-p1-starter-kit 0.8.0 → 0.11.0

package/template/__tests__/page-seo.test.ts

@@ -6,8 +6,11 @@ vi.mock("../lib/remote-datasource-fetchers", () => ({
   REMOTE_DATASOURCE_FETCHERS: {},
 }));
 
+vi.mock("@pantheon-systems/p1-next-sdk/server", () => ({
+  loadRouteTemplateKeys: vi.fn().mockResolvedValue([]),
+}));
+
 vi.mock("@pantheon-systems/puck-css/server", () => ({
-  listRouteTemplateKeysFromDatabase: vi.fn().mockResolvedValue([]),
   extractReferencedDatasourceIds: vi.fn().mockReturnValue([]),
   loadRemoteDatasourceContext: vi.fn().mockResolvedValue({}),
   resolveStringTemplates: vi.fn(async (input: string) =>
@@ -36,7 +39,6 @@ describe("resolvePageMetadata", () => {
         _seo: { siteName: "Acme Docs" },
       }),
       path: "/about/team",
-      searchParams: {},
     });
 
     expect(meta.title).toBe("About Our Team");
@@ -62,7 +64,6 @@ describe("resolvePageMetadata", () => {
         _seo: { siteName: "Acme Docs" },
       }),
       path: "/untitled",
-      searchParams: {},
     });
 
     expect(meta.title).toBeUndefined();
@@ -81,7 +82,6 @@ describe("resolvePageMetadata", () => {
         description: "Welcome, {{name}}!",
       }),
       path: "/greet",
-      searchParams: {},
     });
 
     expect(meta.title).toBe("Hello World");
@@ -103,7 +103,6 @@ describe("resolvePageMetadata", () => {
         },
       }),
       path: "/untitled",
-      searchParams: {},
     });
 
     expect(meta.title).toBe("Root Title");
@@ -116,7 +115,6 @@ describe("resolvePageMetadata", () => {
     const meta = await resolvePageMetadata({
       pageData: null,
       path: "/",
-      searchParams: {},
     });
 
     expect(meta.title).toBeUndefined();

package/template/__tests__/paragraph-block.test.ts

@@ -1,37 +1,39 @@
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
 import { describe, expect, it } from "vitest";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const appDir = resolve(__dirname, "..");
+const content = readFileSync(
+  resolve(appDir, "components/puck/paragraph-block.tsx"),
+  "utf-8",
+);
+
 describe("paragraphBlock", () => {
-  it("has a richtext field for text", async () => {
-    const { paragraphBlock } = await import("../components/puck/paragraph-block");
-    expect(paragraphBlock.fields.text.type).toBe("richtext");
+  it("uses richtextField for the text field", () => {
+    expect(content).toContain("richtextField");
+    expect(content).toMatch(/text:\s*richtextField/);
   });
 
-  it("enables inline canvas editing", async () => {
-    const { paragraphBlock } = await import("../components/puck/paragraph-block");
-    expect((paragraphBlock.fields.text as any).contentEditable).toBe(true);
+  it("exports paragraphBlock with defaultProps", () => {
+    expect(content).toContain("export const paragraphBlock");
+    expect(content).toContain("defaultProps");
   });
 
-  it("includes ai instructions on the text field", async () => {
-    const { paragraphBlock } = await import("../components/puck/paragraph-block");
-    const ai = (paragraphBlock.fields.text as any).ai;
-    expect(ai).toBeDefined();
-    expect(typeof ai?.instructions).toBe("string");
-    expect(ai?.instructions.length).toBeGreaterThan(0);
+  it("provides a render function", () => {
+    expect(content).toMatch(/render:\s*\(/);
   });
 
-  it("provides a renderMenu function", async () => {
-    const { paragraphBlock } = await import("../components/puck/paragraph-block");
-    expect(typeof (paragraphBlock.fields.text as any).renderMenu).toBe("function");
+  it("wraps editor text in ParagraphEditorText for template preview", () => {
+    expect(content).toContain("ParagraphEditorText");
   });
 
-  it("has a default text prop", async () => {
-    const { paragraphBlock } = await import("../components/puck/paragraph-block");
-    expect(typeof paragraphBlock.defaultProps.text).toBe("string");
-    expect(paragraphBlock.defaultProps.text.length).toBeGreaterThan(0);
+  it("sanitizes richtext HTML for published rendering", () => {
+    expect(content).toContain("sanitizeRichtextHtml");
   });
 
-  it("provides a render function", async () => {
-    const { paragraphBlock } = await import("../components/puck/paragraph-block");
-    expect(typeof paragraphBlock.render).toBe("function");
+  it("has a default text prop", () => {
+    expect(content).toMatch(/text:\s*["']/);
   });
 });

package/template/__tests__/paragraph-editor-text.test.ts

@@ -0,0 +1,79 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const appDir = resolve(__dirname, "..");
+const componentPath = resolve(
+  appDir,
+  "components/puck/paragraph-editor-text.tsx",
+);
+const paragraphPath = resolve(appDir, "components/puck/paragraph-block.tsx");
+
+describe("ParagraphEditorText component", () => {
+  it("exists as a separate file", () => {
+    expect(existsSync(componentPath)).toBe(true);
+  });
+
+  it("is a client component", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toMatch(/^["']use client["']/);
+  });
+
+  it("imports useResolvedPreviewState from puck-css", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("useResolvedPreviewState");
+  });
+
+  it("imports getBlockPropsById from puck-css", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("getBlockPropsById");
+  });
+
+  it("extracts raw text from element props to detect template tokens", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("extractRawText");
+    expect(content).toMatch(/\{\{/);
+  });
+
+  it("tracks focus state via onFocus, onBlur, and a mousedown document listener for click-outside", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("onFocus");
+    expect(content).toContain("onBlur");
+    expect(content).toContain('addEventListener("mousedown"');
+  });
+
+  it("uses transparent text and pointer-events overlay instead of hiding the InlineTextField", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("color: \"transparent\"");
+    expect(content).toContain("pointerEvents: \"none\"");
+  });
+
+  it("renders resolved text as sanitized HTML, not Markdown", () => {
+    const content = readFileSync(componentPath, "utf-8");
+    expect(content).toContain("sanitizeRichtextHtml");
+    expect(content).toContain("dangerouslySetInnerHTML");
+    expect(content).not.toContain("ReactMarkdown");
+  });
+});
+
+describe("paragraph-block uses ParagraphEditorText", () => {
+  const content = readFileSync(paragraphPath, "utf-8");
+
+  it("imports ParagraphEditorText", () => {
+    expect(content).toContain("ParagraphEditorText");
+  });
+
+  it("destructures id from render props", () => {
+    expect(content).toMatch(/\bid\b.*:/);
+  });
+
+  it("wraps isValidElement branch with ParagraphEditorText", () => {
+    const reactElementBranch = content.slice(
+      content.indexOf("isValidElement(text)"),
+      content.indexOf("isValidElement(text)") + 200,
+    );
+    expect(reactElementBranch).toContain("ParagraphEditorText");
+  });
+});

package/template/__tests__/published-page-404.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loadPublishedPage, notFound } = vi.hoisted(() => ({
+  loadPublishedPage: vi.fn(),
+  notFound: vi.fn(() => {
+    throw new Error("NEXT_NOT_FOUND");
+  }),
+}));
+
+vi.mock("@pantheon-systems/p1-next-sdk/server", () => ({
+  loadPublishedPage,
+  loadRouteTemplateKeys: vi.fn().mockResolvedValue([]),
+  createCssQueryFetchers: vi.fn().mockReturnValue([]),
+}));
+
+vi.mock("next/navigation", () => ({ notFound }));
+
+vi.mock("@pantheon-systems/puck-css/server", () => ({
+  pagePathFromCatchAllSegments: (segments: string[]) => `/${segments.join("/")}`,
+  loadRemoteDatasourceContext: vi.fn().mockResolvedValue({}),
+  extractReferencedDatasourceIds: vi.fn().mockReturnValue([]),
+  resolveDataTemplates: vi.fn(async (d: unknown) => d),
+}));
+
+vi.mock("../lib/remote-datasource-fetchers", () => ({
+  REMOTE_DATASOURCE_FETCHERS: [],
+}));
+
+vi.mock("../app/[...puckPath]/client", () => ({ Client: () => null }));
+vi.mock("../components/content-unavailable", () => ({
+  ContentUnavailable: () => null,
+}));
+
+import Page from "../app/[...puckPath]/page";
+
+const render = (...segments: string[]) =>
+  Page({ params: Promise.resolve({ puckPath: segments }) });
+
+describe("catch-all route — missing vs unavailable", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  // The route is statically renderable, so a 200 here would write every junk URL
+  // a crawler probes into the response cache as a successful page.
+  it("404s a path with no published page", async () => {
+    loadPublishedPage.mockResolvedValue({ status: "missing" });
+    await expect(render("nope")).rejects.toThrow("NEXT_NOT_FOUND");
+    expect(notFound).toHaveBeenCalled();
+  });
+
+  // 404ing here would deindex a live page over a transient backend blip.
+  it("does not 404 when the backend is unreachable", async () => {
+    loadPublishedPage.mockResolvedValue({ status: "unavailable" });
+    await render("real-page");
+    expect(notFound).not.toHaveBeenCalled();
+  });
+
+  it("renders published content", async () => {
+    loadPublishedPage.mockResolvedValue({
+      status: "ok",
+      data: { root: { props: { title: "Hi" } }, content: [] },
+    });
+    await render("blog");
+    expect(notFound).not.toHaveBeenCalled();
+  });
+});

package/template/__tests__/puck-root-guidance.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { puckRoot } from "../components/puck/root";
+
+/**
+ * Guidance on the page-metadata fields: help text under every field, and a
+ * placeholder showing what an empty field will inherit.
+ *
+ * The placeholder comes from `resolveFields` reading the live root props — the
+ * only tiers that exist today are the page's own title and description. It is a
+ * placeholder rather than a value on purpose: autosave persists the whole
+ * snapshot, so a derived value written into the field would be saved and the
+ * field would stop inheriting for good.
+ */
+
+type Field = {
+  type: string;
+  label?: string;
+  placeholder?: string;
+  metadata?: { help?: string; helpWhenEmpty?: string };
+};
+type ObjectField = { type: string; objectFields: Record<string, Field> };
+
+const staticMeta = (puckRoot.fields as Record<string, unknown>)._meta as ObjectField;
+
+const resolve = (props: Record<string, unknown>) => {
+  const resolveFields = puckRoot.resolveFields as (
+    data: { props: Record<string, unknown> },
+  ) => Record<string, unknown>;
+  const fields = resolveFields({ props });
+  return (fields._meta as ObjectField).objectFields;
+};
+
+const INHERITS_FROM: Record<string, string> = {
+  ogTitle: "title",
+  ogDescription: "description",
+  twitterTitle: "title",
+};
+
+describe("page-metadata field guidance", () => {
+  it("gives every metadata field help text", () => {
+    for (const [name, field] of Object.entries(staticMeta.objectFields)) {
+      expect(
+        field.metadata?.help ?? field.metadata?.helpWhenEmpty,
+        `${name} has no help text`,
+      ).toBeTruthy();
+    }
+  });
+
+  it("tells an empty inheriting field where its value comes from", () => {
+    for (const name of Object.keys(INHERITS_FROM)) {
+      expect(staticMeta.objectFields[name]?.metadata?.helpWhenEmpty).toMatch(/inherit/i);
+    }
+  });
+});
+
+describe("puckRoot.resolveFields", () => {
+  it("shows the inherited value as the placeholder", () => {
+    const fields = resolve({ title: "Q3 Launch Recap", description: "How it went" });
+
+    expect(fields.ogTitle?.placeholder).toBe("Q3 Launch Recap");
+    expect(fields.twitterTitle?.placeholder).toBe("Q3 Launch Recap");
+    expect(fields.ogDescription?.placeholder).toBe("How it went");
+  });
+
+  it("follows the same fallback chains the head tags use", () => {
+    // buildPageMetadata resolves twitter:title from ogTitle before title, and
+    // twitter:image from ogImage. A placeholder that disagreed would mislead.
+    const fields = resolve({
+      title: "Q3 Launch Recap",
+      _meta: { ogTitle: "Read the Q3 recap", ogImage: "https://cdn.example/card.png" },
+    });
+
+    expect(fields.twitterTitle?.placeholder).toBe("Read the Q3 recap");
+    expect(fields.twitterImage?.placeholder).toBe("https://cdn.example/card.png");
+  });
+
+  it("omits the placeholder when there is nothing to inherit", () => {
+    const fields = resolve({});
+
+    expect(fields.ogTitle?.placeholder).toBeUndefined();
+    expect(fields.ogDescription?.placeholder).toBeUndefined();
+  });
+
+  it("does not offer the editor's boilerplate title as an inherited value", () => {
+    // Matches the head-tag side, which refuses to ship defaultProps.title.
+    const fields = resolve({ title: "My Puck Editor" });
+
+    expect(fields.ogTitle?.placeholder).toBeUndefined();
+  });
+
+  it("resolves the same field set it declares statically", () => {
+    expect(Object.keys(resolve({ title: "x" })).sort()).toEqual(
+      Object.keys(staticMeta.objectFields).sort(),
+    );
+  });
+
+  it("leaves the declared fields unmutated, so a resolve cannot leak into the next", () => {
+    resolve({ title: "Q3 Launch Recap" });
+
+    expect(staticMeta.objectFields.ogTitle?.placeholder).toBeUndefined();
+  });
+
+  it("keeps the placeholder out of the document by never touching props", () => {
+    const props = { title: "Q3 Launch Recap", _meta: { ogTitle: "" } };
+    resolve(props);
+
+    expect(props._meta).toEqual({ ogTitle: "" });
+  });
+});

package/template/__tests__/puck-root-meta.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { puckRoot } from "../components/puck/root";
+
+/**
+ * The fixed page-metadata field set on the Puck root config.
+ *
+ * Values live at `root.props._meta` in the page snapshot — branch-scoped,
+ * versioned and autosaved for free. The field set itself is fixed: no
+ * admin-defined fields, no template or site tiers. `resolveFields` varies only
+ * the placeholders (see puck-root-guidance), never which fields exist.
+ *
+ * Fields are declared flat inside one `_meta` object field. Grouping them
+ * (SEO / Open Graph / Twitter) would mean nesting object fields, which deepens
+ * the prop paths the root-prop migration applier has to handle.
+ */
+
+type ObjectField = {
+  type: string;
+  label?: string;
+  objectFields: Record<string, { type: string; label?: string }>;
+};
+
+const metaField = (puckRoot.fields as Record<string, unknown>)._meta as ObjectField;
+
+// ogType and twitterCard are selects: their vocabulary is fixed by what Next
+// accepts for the tag. See puck-root-selects.
+const EXPECTED_FIELDS: Record<string, string> = {
+  ogTitle: "text",
+  ogDescription: "textarea",
+  ogType: "select",
+  ogImage: "text",
+  ogLocale: "text",
+  twitterCard: "select",
+  twitterTitle: "text",
+  twitterImage: "text",
+};
+
+describe("puckRoot._meta field set", () => {
+  it("is a single object field", () => {
+    expect(metaField).toBeDefined();
+    expect(metaField.type).toBe("object");
+  });
+
+  it("declares exactly the eight fixed fields, flat", () => {
+    expect(Object.keys(metaField.objectFields).sort()).toEqual(
+      Object.keys(EXPECTED_FIELDS).sort(),
+    );
+  });
+
+  it("gives each field the expected type", () => {
+    for (const [name, type] of Object.entries(EXPECTED_FIELDS)) {
+      expect(metaField.objectFields[name]?.type).toBe(type);
+    }
+  });
+
+  it("labels every field with the tag it writes", () => {
+    // Not friendly rewrites: someone editing these is working from a checklist
+    // that names the tags, and "Social title" makes them guess which one it is.
+    expect(
+      Object.fromEntries(
+        Object.keys(EXPECTED_FIELDS).map((name) => [
+          name,
+          metaField.objectFields[name]?.label,
+        ]),
+      ),
+    ).toEqual({
+      ogTitle: "og:title",
+      ogDescription: "og:description",
+      ogType: "og:type",
+      ogImage: "og:image",
+      ogLocale: "og:locale",
+      twitterCard: "twitter:card",
+      twitterTitle: "twitter:title",
+      twitterImage: "twitter:image",
+    });
+  });
+
+  it("names the group for what it holds, matching the prototype", () => {
+    expect((metaField as { label?: string }).label).toBe("Social & sharing");
+  });
+
+  it("omits ogUrl — the canonical URL is derived from the request", () => {
+    expect(metaField.objectFields).not.toHaveProperty("ogUrl");
+  });
+
+  it("includes twitterCard, without which twitter:title and twitter:image are inert", () => {
+    expect(metaField.objectFields.twitterCard).toBeDefined();
+  });
+
+  it("keeps the existing title and description fields", () => {
+    const fields = puckRoot.fields as Record<string, { type: string }>;
+    expect(fields.title?.type).toBe("text");
+    expect(fields.description?.type).toBe("textarea");
+  });
+
+  it("adds no _meta default, so no page is seeded with boilerplate metadata", () => {
+    // Empty-means-inherit (Q1): an unset field falls back at render time. A
+    // default here would freeze a value into every new page's snapshot, and
+    // would need adding to the DEFAULT_EDITOR_TITLE-style boilerplate filter.
+    expect(puckRoot.defaultProps).not.toHaveProperty("_meta");
+  });
+});

package/template/__tests__/puck-root-selects.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { puckRoot } from "../components/puck/root";
+import { OG_TYPES, TWITTER_CARDS } from "../lib/seo-metadata.consts";
+
+/**
+ * The two metadata fields with a fixed vocabulary are dropdowns.
+ *
+ * Their options come from the same lists `buildPageMetadata` validates against,
+ * so an option cannot drift from what actually reaches the tag.
+ *
+ * The default option's value is empty rather than the default itself. Storing
+ * `website` on every page would freeze it there, and a page holding an explicit
+ * value can never pick up a template default later — so the label states the
+ * outcome while the data stays uncommitted.
+ */
+
+type Field = {
+  type: string;
+  options?: { label: string; value: string }[];
+};
+type ObjectField = { type: string; objectFields: Record<string, Field> };
+
+const staticMeta = (puckRoot.fields as Record<string, unknown>)._meta as ObjectField;
+
+const resolve = (props: Record<string, unknown>) => {
+  const resolveFields = puckRoot.resolveFields as (
+    data: { props: Record<string, unknown> },
+  ) => Record<string, unknown>;
+  return (resolveFields({ props })._meta as ObjectField).objectFields;
+};
+
+const values = (field?: Field) => field?.options?.map((option) => option.value) ?? [];
+
+describe("fixed-vocabulary metadata fields", () => {
+  it("renders as selects rather than free text", () => {
+    expect(staticMeta.objectFields.ogType?.type).toBe("select");
+    expect(staticMeta.objectFields.twitterCard?.type).toBe("select");
+  });
+
+  it("offers exactly the values the head tags accept", () => {
+    expect(values(staticMeta.objectFields.ogType).filter(Boolean)).toEqual([...OG_TYPES]);
+    expect(values(staticMeta.objectFields.twitterCard).filter(Boolean)).toEqual([
+      ...TWITTER_CARDS,
+    ]);
+  });
+
+  it("keeps an empty first option, so a page stays uncommitted", () => {
+    for (const name of ["ogType", "twitterCard"]) {
+      expect(values(staticMeta.objectFields[name])[0]).toBe("");
+    }
+  });
+
+  it("labels every option, since the tag values are not user-facing", () => {
+    for (const name of ["ogType", "twitterCard"]) {
+      const options = staticMeta.objectFields[name]?.options ?? [];
+      expect(options.length).toBeGreaterThan(1);
+      for (const option of options) {
+        expect(option.label).toBeTruthy();
+      }
+    }
+  });
+
+  it("names the og:type default, which is always website", () => {
+    expect(staticMeta.objectFields.ogType?.options?.[0]?.label).toMatch(/website/i);
+  });
+
+  it("names the default card style, which depends on whether there is an image", () => {
+    // buildPageMetadata picks summary_large_image when an image is present and
+    // summary when it is not, so the label has to follow the image field.
+    const withImage = resolve({ _meta: { ogImage: "https://cdn.example/card.png" } });
+    const without = resolve({});
+
+    expect(withImage.twitterCard?.options?.[0]?.label).toMatch(/large image/i);
+    expect(without.twitterCard?.options?.[0]?.label).toMatch(/summary/i);
+    expect(without.twitterCard?.options?.[0]?.label).not.toMatch(/large image/i);
+  });
+
+  it("varies only the default label, never the option values", () => {
+    const resolved = resolve({ _meta: { ogImage: "https://cdn.example/card.png" } });
+
+    expect(values(resolved.ogType)).toEqual(values(staticMeta.objectFields.ogType));
+    expect(values(resolved.twitterCard)).toEqual(
+      values(staticMeta.objectFields.twitterCard),
+    );
+  });
+});

package/template/__tests__/remote-datasource-fetchers.test.ts

@@ -13,8 +13,8 @@ vi.mock("@pantheon-systems/puck-css/server", async (importOriginal) => {
   return actual;
 });
 
-import { REMOTE_DATASOURCE_FETCHERS } from "../lib/remote-datasource-fetchers";
 import type { RemoteDatasourceFetcherParams } from "@pantheon-systems/puck-css/server";
+import { REMOTE_DATASOURCE_FETCHERS } from "../lib/remote-datasource-fetchers";
 
 const { PCCConvenienceFunctions } = await import(
   "@pantheon-systems/cpub-react-sdk/server"
@@ -177,7 +177,7 @@ describe("monster_list fetcher", () => {
     });
     const result = await fetcher.fetch(makeFetcherParams({ fetchImpl }));
     expect(result).toEqual({
-      items: [{ index: "bulbasaur", name: "Bulbasaur", url: "/pokemon/bulbasaur" }],
+      items: [{ key: "bulbasaur", species: "Bulbasaur", index: "bulbasaur", name: "Bulbasaur", url: "/pokemon/bulbasaur" }],
     });
   });
 });