@pantheon-systems/create-p1-starter-kit 0.1.0 → 0.4.2

package/lib/messages.js

@@ -13,8 +13,9 @@ export function showSuccess(projectName, projectPath, packageManager) {
   console.log(`  ${pc.dim('# Copy .env.example to .env and fill in your credentials:')}`);
   console.log(`  ${pc.cyan('cp')} .env.example .env`);
   console.log(`  ${pc.dim('# Edit .env with your PCC_SITE_ID and PCC_TOKEN')}\n`);
+  const devCmd = packageManager === 'npm' ? 'npm run dev' : `${packageManager} dev`;
   console.log(`  ${pc.dim('# Start the dev server:')}`);
-  console.log(`  ${pc.cyan(`${packageManager} dev`)}\n`);
+  console.log(`  ${pc.cyan(devCmd)}\n`);
   console.log(pc.bold('Happy building! 🚀\n'));
 }
 

package/lib/messages.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { showSuccess } from './messages.js';
+
+describe('showSuccess', () => {
+  let output;
+
+  beforeEach(() => {
+    output = [];
+    vi.spyOn(console, 'log').mockImplementation((...args) => output.push(args.join(' ')));
+  });
+
+  it('shows "npm run dev" for npm users', () => {
+    showSuccess('my-app', '/tmp/my-app', 'npm');
+    const allOutput = output.join('\n');
+    expect(allOutput).toContain('npm run dev');
+  });
+
+  it('shows "pnpm dev" for pnpm users', () => {
+    showSuccess('my-app', '/tmp/my-app', 'pnpm');
+    const allOutput = output.join('\n');
+    expect(allOutput).toContain('pnpm dev');
+  });
+
+  it('shows "yarn dev" for yarn users', () => {
+    showSuccess('my-app', '/tmp/my-app', 'yarn');
+    const allOutput = output.join('\n');
+    expect(allOutput).toContain('yarn dev');
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/create-p1-starter-kit",
-  "version": "0.1.0",
+  "version": "0.4.2",
   "description": "Scaffold a new P1 starter project",
   "type": "module",
   "bin": {
@@ -11,6 +11,11 @@
     "lib/",
     "template/"
   ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": false
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/pantheon-systems/puck-css-integration.git",
@@ -27,12 +32,16 @@
   "engines": {
     "node": ">=20.12.0"
   },
+  "devDependencies": {
+    "vitest": "^4.1.5"
+  },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
     "picocolors": "^1.1.1"
   },
   "license": "MIT",
   "scripts": {
-    "build": "node scripts/build-template.js"
+    "build": "node scripts/build-template.js",
+    "test": "vitest run"
   }
 }

package/template/.env.example

@@ -6,5 +6,9 @@ NEXT_PUBLIC_CSS_BASE_URL=https://css.example.com
 NEXT_PUBLIC_CSS_SITE_ID=site-123
 P1_CSS_API_KEY=your-api-key
 
+# --- P1 Admin Dashboard (optional) ---
+# Override the default dashboard URL (https://content.pantheon.io)
+# NEXT_PUBLIC_P1_ADMIN_DASHBOARD_URL=https://staging.content.pantheon.io
+
 # Branch is auto-detected (defaults to main) unless specified:
 # NEXT_PUBLIC_CSS_BRANCH_ID=branch-456

package/template/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @pantheon-systems/p1-starter
+
+## 1.0.1
+
+### Patch Changes
+
+- Updated dependencies [6650602]
+- Updated dependencies [dc7cfd7]
+  - @pantheon-systems/puck-css@0.4.2
+  - @pantheon-systems/css-client@0.4.2
+  - @pantheon-systems/p1-next-sdk@0.4.2

package/template/app/[...puckPath]/client.tsx

@@ -4,6 +4,37 @@ import type { Data } from "@puckeditor/core";
 import { RenderClient } from "@pantheon-systems/puck-css";
 import config from "../../puck.config";
 
-export function Client({ data }: { data: Data }) {
-  return <RenderClient config={config} data={data} />;
+export function Client({
+  data,
+  pageMetadata,
+}: {
+  data: Data;
+  pageMetadata?: {
+    route: string;
+    documentName?: string;
+    pageType?: "page" | "template" | "override";
+  };
+}) {
+  return (
+    <>
+      <RenderClient config={config} data={data} />
+      {pageMetadata && (
+        <footer className="mt-16 border-t border-gray-200 py-4 text-center text-sm text-gray-500">
+          Rendered with{" "}
+          <span className="font-medium">
+            {pageMetadata.documentName || pageMetadata.route}
+          </span>{" "}
+          from{" "}
+          <span className="font-medium">
+            {pageMetadata.pageType === "page" && "page"}
+            {pageMetadata.pageType === "template" && "page template"}
+            {pageMetadata.pageType === "override" && "page template override"}
+            {!pageMetadata.pageType && "page"}
+          </span>{" "}
+          at route{" "}
+          <span className="font-mono text-xs">{pageMetadata.route}</span>
+        </footer>
+      )}
+    </>
+  );
 }

package/template/app/[...puckPath]/page.tsx

@@ -125,7 +125,16 @@ export default async function Page({
   });
   const resolvedData = await resolveDataTemplates(data, context);
 
-  return <Client data={resolvedData} />;
+  return (
+    <Client
+      data={resolvedData}
+      pageMetadata={{
+        route: path,
+        documentName: data.root.props?.title as string | undefined,
+        pageType: "page",
+      }}
+    />
+  );
 }
 
 export const dynamic = "force-dynamic";

package/template/app/layout.tsx

@@ -7,7 +7,7 @@ export default function RootLayout({
 }) {
   return (
     <html lang="en">
-      <body>{children}</body>
+      <body data-rm-theme="light">{children}</body>
     </html>
   );
 }

package/template/app/p1/[[...p1]]/editor-client.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback } from "react";
+import React, { useCallback } from "react";
 import { useRouter } from "next/navigation";
 import { Puck } from "@puckeditor/core";
 import {
@@ -31,6 +31,9 @@ try {
 const editorConfig = wrapConfigForEditorPreview(config);
 
 export function EditorClientWrapper({ path }: { path: string }) {
+  // Keep ref at this level - EditorClientWrapper doesn't unmount on branch switch
+  const lastGoodStateRef = React.useRef<{ puckKey: string; puckProps: any } | null>(null);
+
   if (!p1Config) {
     return (
       <div style={{ textAlign: "center", padding: "4rem", fontFamily: "system-ui" }}>
@@ -53,14 +56,20 @@ export function EditorClientWrapper({ path }: { path: string }) {
           config={p1Config}
           loginPageProps={{ title: "P1 Starter", subtitle: "Sign in to edit" }}
         >
-          <EditorContent path={path} />
+          <EditorContent path={path} lastGoodStateRef={lastGoodStateRef} />
         </P1App>
       </P1NextRouterProvider>
     </P1QueryProvider>
   );
 }
 
-function EditorContent({ path }: { path: string }) {
+function EditorContent({
+  path,
+  lastGoodStateRef,
+}: {
+  path: string;
+  lastGoodStateRef: React.MutableRefObject<{ puckKey: string; puckProps: any } | null>;
+}) {
   const router = useRouter();
   const p1Plugins = useP1Plugins(path, config);
 
@@ -78,6 +87,8 @@ function EditorContent({ path }: { path: string }) {
     pluginOptions: {
       onDocumentSelect: handleDocumentSelect,
       selectedDocumentPath: path,
+      siteId: process.env.NEXT_PUBLIC_CSS_SITE_ID,
+      dashboardUrl: process.env.NEXT_PUBLIC_P1_ADMIN_DASHBOARD_URL,
     },
     overrideOptions: {
       showDefaultPublish: false,
@@ -90,7 +101,15 @@ function EditorContent({ path }: { path: string }) {
     },
   });
 
-  if (loading) {
+  // Update last good state when loading completes successfully (ref passed from parent)
+  React.useEffect(() => {
+    if (!loading && !error) {
+      lastGoodStateRef.current = { puckKey, puckProps };
+    }
+  }, [loading, error, puckKey, puckProps]);
+
+  // Show full loading screen only on first load (no previous state)
+  if (loading && !lastGoodStateRef.current) {
     return (
       <div style={{ textAlign: "center", padding: "4rem", fontFamily: "system-ui" }}>
         Loading editor...
@@ -98,7 +117,8 @@ function EditorContent({ path }: { path: string }) {
     );
   }
 
-  if (error) {
+  // Show error only if we have no previous state to fall back to
+  if (error && !lastGoodStateRef.current) {
     return (
       <div style={{ textAlign: "center", padding: "4rem", fontFamily: "system-ui" }}>
         <h3>Error loading document</h3>
@@ -107,10 +127,55 @@ function EditorContent({ path }: { path: string }) {
     );
   }
 
+  // Use current state if loaded, otherwise keep showing last good state
+  const displayState = (!loading && !error)
+    ? { puckKey, puckProps }
+    : lastGoodStateRef.current ?? { puckKey, puckProps };
+
   return (
-    <div className="puck-editor-theme">
+    <div className="puck-editor-theme" style={{ position: "relative" }}>
+      {/* Loading overlay - shown during branch switch */}
+      {loading && lastGoodStateRef.current && (
+        <div
+          style={{
+            position: "fixed",
+            top: "50%",
+            left: "50%",
+            transform: "translate(-50%, -50%)",
+            zIndex: 9999,
+            background: "rgba(255, 255, 255, 0.95)",
+            padding: "1rem 2rem",
+            borderRadius: "8px",
+            boxShadow: "0 4px 12px rgba(0, 0, 0, 0.15)",
+            fontFamily: "system-ui",
+            fontSize: "14px",
+            color: "#333",
+            fontWeight: 500,
+            display: "flex",
+            alignItems: "center",
+            gap: "0.75rem",
+          }}
+        >
+          <div
+            style={{
+              width: "16px",
+              height: "16px",
+              border: "2px solid #e0e0e0",
+              borderTopColor: "#2563eb",
+              borderRadius: "50%",
+              animation: "spin 0.6s linear infinite",
+            }}
+          />
+          Switching workstream...
+          <style>{`
+            @keyframes spin {
+              to { transform: rotate(360deg); }
+            }
+          `}</style>
+        </div>
+      )}
       {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
-      <Puck key={puckKey} {...puckProps as any} _experimentalFullScreenCanvas={true} />
+      <Puck key={displayState.puckKey} {...displayState.puckProps as any} _experimentalFullScreenCanvas={true} />
     </div>
   );
 }

package/template/app/page.tsx

@@ -64,7 +64,16 @@ export default async function HomePage() {
       referencedDatasourceIds,
     });
     const resolvedData = await resolveDataTemplates(data, context);
-    return <Client data={resolvedData} />;
+    return (
+      <Client
+        data={resolvedData}
+        pageMetadata={{
+          route: "/",
+          documentName: data.root.props?.title as string | undefined,
+          pageType: "page",
+        }}
+      />
+    );
   }
 
   const routes = await listRoutes();

package/template/components/puck/paragraph-block.tsx

@@ -1,3 +1,4 @@
+import { isValidElement, type ReactNode } from "react";
 import { blockPaddingClass } from "./block-padding";
 import ReactMarkdown from "react-markdown";
 
@@ -19,7 +20,10 @@ export const paragraphBlock = {
   defaultProps: {
     text: "Add your copy here. You can use multiple lines.",
   },
-  render: ({ text }: { text?: string }) => {
+  render: ({ text }: { text?: string | ReactNode }) => {
+    if (isValidElement(text)) {
+      return <div className={blockPaddingClass}>{text}</div>;
+    }
     const markdown = asMarkdownText(text);
     return (
       <div className={blockPaddingClass}>

package/template/components/puck/root.tsx

@@ -9,10 +9,9 @@ export const puckRoot = {
     title: "My Puck Editor",
   },
   render: (props: { children?: ReactNode; title?: string }) => {
-    const { children, title } = props;
+    const { children } = props;
     return (
       <div className="font-sans antialiased">
-        <h1>{title}</h1>
         {children}
       </div>
     );

package/template/package.json

@@ -11,9 +11,9 @@
   },
   "dependencies": {
     "@pantheon-systems/cpub-react-sdk": "^5.2.1",
-    "@pantheon-systems/css-client": "^0.4.0",
-    "@pantheon-systems/p1-next-sdk": "^0.1.0",
-    "@pantheon-systems/puck-css": "^0.4.0",
+    "@pantheon-systems/css-client": "^0.4.2",
+    "@pantheon-systems/p1-next-sdk": "^0.4.2",
+    "@pantheon-systems/puck-css": "^0.4.2",
     "@puckeditor/core": "^0.21.1",
     "@tailwindcss/postcss": "^4.2.2",
     "classnames": "^2.5.1",

package/template/README.md

@@ -1,53 +0,0 @@
-# Content Publisher Site Sample
-
-A sample Next.js site demonstrating the Content Publisher CMS — Pantheon's visual page-building and content management system. Content Publisher combines a Puck-based drag-and-drop editor with server-side datasource resolution, enabling authors to build dynamic, data-driven pages without writing code.
-
-## What's included
-
-- **Visual page editor** — Puck-powered drag-and-drop editing at `/p1/<path>` with built-in blocks for typography, media, layout, and actions
-- **Site structure management** — Dashboard at `/p1` for creating and organizing pages and templates
-- **Datasource bindings** — Connect page blocks to live data from Content Publisher articles, external APIs (SWAPI, Pokemon GraphQL), and URL route parameters
-- **Next.js App Router** — Server components, catch-all routing, and API route handlers via `@pantheon-systems/p1-client-sdk`
-
-## Getting started
-
-1. Copy the environment file and fill in your credentials:
-
-   ```
-   cp .env.example .env
-   ```
-
-   | Variable      | Description                |
-   | ------------- | -------------------------- |
-   | `PCC_SITE_ID` | Your Content Cloud site ID |
-   | `PCC_TOKEN`   | API token for your site    |
-
-2. Install dependencies and start the dev server:
-
-   ```
-   npm install
-   npm run dev
-   ```
-
-3. Open http://localhost:3000 to view the site, or http://localhost:3000/p1 for the page management dashboard.
-
-## Project structure
-
-```
-app/
-  page.tsx                    # Site root (renders via Puck)
-  [...puckPath]/              # Catch-all route for published pages
-  p1/
-    page.tsx                  # P1 dashboard — lists pages, links to editor
-    [...p1]/                  # Editor & renderer for any page path
-    api/[...p1]/route.ts      # API handler (GET/POST/DELETE) for page data
-components/puck/              # Block definitions (Heading, Paragraph, Image, etc.)
-lib/builtin-datasources.ts    # Datasource registry (SWAPI, Pokemon, articles, URL params)
-puck.config.tsx               # Puck editor configuration — block registry & categories
-```
-
-## Customization
-
-- **Add blocks** — Create a new component in `components/puck/`, then register it in `puck.config.tsx`
-- **Add datasources** — Define a new `DatasourceDefinition` in `lib/builtin-datasources.ts` to make external data available to block fields via `{{ datasource.field }}` expressions
-- **Change styling** — The project uses Tailwind CSS v4; edit `app/styles.css` or individual block components