@orion-studios/payload-studio 0.6.0-beta.185 → 0.6.0-beta.186

package/README.md

@@ -22,8 +22,10 @@ Prefer explicit subpath imports.
 import { configureAdmin, type StudioSection } from '@orion-studios/payload-studio/admin'
 import { createPayloadClient, createPageQueries, createSiteQueries } from '@orion-studios/payload-studio/nextjs'
 import { defaultPageLayoutBlocks } from '@orion-studios/payload-studio/blocks'
-import { pageStudioModuleManifest } from '@orion-studios/payload-studio/studio-pages'
+import { createStudioPagesCollection, pageStudioModuleManifest } from '@orion-studios/payload-studio/studio-pages'
 import { withImageUploadOptimization } from '@orion-studios/payload-studio/studio'
+import { validateEmail, formatPhoneUS } from '@orion-studios/payload-studio/forms'
+import { createFormSubmissionHandler } from '@orion-studios/payload-studio/forms/server'
 ```
 
 The root `@orion-studios/payload-studio` namespace export remains available for backward compatibility, but new integrations should treat subpath imports as the public contract.
@@ -32,6 +34,7 @@ The root `@orion-studios/payload-studio` namespace export remains available for
 
 ```bash
 npm install @orion-studios/payload-studio
+npx payload-studio-init   # scaffolds app scripts, lib wrappers, and the form submission route
 ```
 
 ```ts
@@ -70,6 +73,8 @@ const adminConfig = configureAdmin({
 - `@orion-studios/payload-studio/admin-app/client`
 - `@orion-studios/payload-studio/admin-app/styles.css`
 - `@orion-studios/payload-studio/blocks`
+- `@orion-studios/payload-studio/forms`
+- `@orion-studios/payload-studio/forms/server`
 - `@orion-studios/payload-studio/nextjs`
 - `@orion-studios/payload-studio/studio`
 - `@orion-studios/payload-studio/studio-pages`

package/bin/init.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+/**
+ * Scaffolds the app-side files required by the Studio Website Setup Guide.
+ *
+ * Usage (from the consuming app root):
+ *   npx payload-studio-init
+ *
+ * Existing files are never overwritten — safe to re-run after upgrades.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const cwd = process.cwd()
+
+const hasSrcDir = fs.existsSync(path.join(cwd, 'src'))
+const srcRoot = hasSrcDir ? 'src' : '.'
+
+const FILES = [
+  {
+    file: 'scripts/clean-next-cache.cjs',
+    contents: `#!/usr/bin/env node
+
+// Clears stale Next.js build caches before dev/build runs.
+// Pass --all to remove the entire .next directory instead of just the cache.
+
+const fs = require('fs')
+const path = require('path')
+
+const all = process.argv.includes('--all')
+const target = path.join(process.cwd(), '.next', all ? '' : 'cache')
+
+try {
+  fs.rmSync(target, { recursive: true, force: true })
+  console.log('[clean-next-cache] removed ' + path.relative(process.cwd(), target || '.next'))
+} catch (error) {
+  console.warn('[clean-next-cache] skipped: ' + error.message)
+}
+`,
+  },
+  {
+    file: 'scripts/schema-sync.ts',
+    contents: `/**
+ * Pushes the current Payload schema to the database.
+ *
+ * Run via: npm run schema:sync
+ * The PAYLOAD_SCHEMA_PUSH=true env flag is set by the npm script — schema push
+ * stays opt-in only, per the Studio contract.
+ */
+
+import config from '../${srcRoot}/payload.config'
+import { getPayload } from 'payload'
+
+async function run() {
+  if (process.env.PAYLOAD_SCHEMA_PUSH !== 'true') {
+    console.error('Refusing to run: set PAYLOAD_SCHEMA_PUSH=true (use \`npm run schema:sync\`).')
+    process.exit(1)
+  }
+
+  const payload = await getPayload({ config })
+  console.log('[schema-sync] schema synchronized')
+  if (typeof payload.db?.destroy === 'function') {
+    await payload.db.destroy()
+  }
+  process.exit(0)
+}
+
+run().catch((error) => {
+  console.error('[schema-sync] failed:', error)
+  process.exit(1)
+})
+`,
+  },
+  {
+    file: 'scripts/seed.ts',
+    contents: `/**
+ * Seeds the CMS with the canonical default pages from src/lib/site-page-layouts.
+ * Existing pages are left untouched — safe to re-run.
+ *
+ * Run via: npm run seed
+ */
+
+import config from '../${srcRoot}/payload.config'
+import { getPayload } from 'payload'
+import { sitePageLayouts } from '../${srcRoot}/lib/site-page-layouts'
+
+async function run() {
+  const payload = await getPayload({ config })
+
+  for (const page of sitePageLayouts) {
+    const existing = await payload.find({
+      collection: 'pages',
+      limit: 1,
+      where: { slug: { equals: page.slug } },
+    })
+
+    if (existing.docs.length > 0) {
+      console.log('[seed] skip existing page: ' + page.slug)
+      continue
+    }
+
+    await payload.create({
+      collection: 'pages',
+      data: {
+        _status: 'published',
+        layout: page.layout,
+        slug: page.slug,
+        title: page.title,
+      },
+    })
+    console.log('[seed] created page: ' + page.slug)
+  }
+
+  if (typeof payload.db?.destroy === 'function') {
+    await payload.db.destroy()
+  }
+  process.exit(0)
+}
+
+run().catch((error) => {
+  console.error('[seed] failed:', error)
+  process.exit(1)
+})
+`,
+  },
+  {
+    file: 'scripts/sync-page-layouts.ts',
+    contents: `/**
+ * Syncs the canonical default layouts from src/lib/site-page-layouts into the
+ * CMS for pages that have NOT been edited in the Studio builder yet
+ * (no studioDocument). Builder-authored pages are never overwritten.
+ *
+ * Run via: npm run pages:sync-layouts
+ */
+
+import config from '../${srcRoot}/payload.config'
+import { getPayload } from 'payload'
+import { sitePageLayouts } from '../${srcRoot}/lib/site-page-layouts'
+
+async function run() {
+  const payload = await getPayload({ config })
+
+  for (const page of sitePageLayouts) {
+    const existing = await payload.find({
+      collection: 'pages',
+      draft: true,
+      limit: 1,
+      where: { slug: { equals: page.slug } },
+    })
+
+    const doc = existing.docs[0] as { id: number | string; studioDocument?: unknown } | undefined
+
+    if (!doc) {
+      await payload.create({
+        collection: 'pages',
+        data: {
+          _status: 'published',
+          layout: page.layout,
+          slug: page.slug,
+          title: page.title,
+        },
+      })
+      console.log('[sync-layouts] created page: ' + page.slug)
+      continue
+    }
+
+    if (doc.studioDocument) {
+      console.log('[sync-layouts] skip builder-owned page: ' + page.slug)
+      continue
+    }
+
+    await payload.update({
+      collection: 'pages',
+      id: doc.id,
+      data: { layout: page.layout },
+    })
+    console.log('[sync-layouts] updated layout for page: ' + page.slug)
+  }
+
+  if (typeof payload.db?.destroy === 'function') {
+    await payload.db.destroy()
+  }
+  process.exit(0)
+}
+
+run().catch((error) => {
+  console.error('[sync-layouts] failed:', error)
+  process.exit(1)
+})
+`,
+  },
+  {
+    file: `${srcRoot}/lib/payload.ts`,
+    contents: `import config from '@/payload.config'
+import { createPayloadClient, WEBSITE_CONTENT_TAG } from '@orion-studios/payload-studio/nextjs'
+
+export const getPayloadClient = createPayloadClient(config)
+export { WEBSITE_CONTENT_TAG }
+`,
+  },
+  {
+    file: `${srcRoot}/lib/pages.ts`,
+    contents: `import { createPageQueries } from '@orion-studios/payload-studio/nextjs'
+import { getPayloadClient, WEBSITE_CONTENT_TAG } from '@/lib/payload'
+
+export const { getPageBySegments, listPublishedPagePaths, pathToSegments } = createPageQueries(
+  getPayloadClient,
+  { contentTag: WEBSITE_CONTENT_TAG },
+)
+`,
+  },
+  {
+    file: `${srcRoot}/lib/site.ts`,
+    contents: `import { createSiteQueries } from '@orion-studios/payload-studio/nextjs'
+import { getPayloadClient, WEBSITE_CONTENT_TAG } from '@/lib/payload'
+
+export const { getSiteSettings, getHeader, getFooter, getSocialMedia } = createSiteQueries(
+  getPayloadClient,
+  { contentTag: WEBSITE_CONTENT_TAG },
+)
+`,
+  },
+  {
+    file: `${srcRoot}/lib/site-page-layouts.ts`,
+    contents: `/**
+ * Canonical default page layouts.
+ *
+ * This module is the single layout source used by runtime fallback, the seed
+ * script, and the sync script, per the Studio Website Setup Guide.
+ */
+
+export type SitePageLayout = {
+  slug: string
+  title: string
+  layout: Array<Record<string, unknown>>
+}
+
+export const sitePageLayouts: SitePageLayout[] = [
+  {
+    slug: 'home',
+    title: 'Home',
+    layout: [],
+  },
+]
+`,
+  },
+  {
+    file: `${srcRoot}/app/api/form-submissions/[slug]/route.ts`,
+    contents: `import { createFormSubmissionHandler } from '@orion-studios/payload-studio/forms/server'
+import { getPayloadClient } from '@/lib/payload'
+
+/**
+ * Public form submission boundary. Anonymous users must never write directly
+ * to the submissions collection — this route is the only entry point.
+ * Origin check, honeypot, minimum fill time, rate limiting, and server-side
+ * re-validation are handled by the shared package handler.
+ */
+export const POST = createFormSubmissionHandler({
+  getPayloadClient,
+})
+`,
+  },
+]
+
+const REQUIRED_SCRIPTS = {
+  dev: 'node scripts/clean-next-cache.cjs && npm run generate:importmap && next dev --webpack',
+  build:
+    'node scripts/clean-next-cache.cjs --all && npm run generate:importmap && next build --webpack',
+  lint: 'eslint .',
+  typecheck: 'tsc --noEmit',
+  verify: 'npm run payload:types && npm run lint && npm run typecheck',
+  payload: "NODE_OPTIONS='--import tsx' payload",
+  'payload:types': "NODE_OPTIONS='--import tsx' payload generate:types",
+  'generate:importmap': "NODE_OPTIONS='--import tsx' payload generate:importmap",
+  'schema:sync': 'PAYLOAD_SCHEMA_PUSH=true tsx scripts/schema-sync.ts',
+  seed: 'tsx scripts/seed.ts',
+  'pages:sync-layouts': 'tsx scripts/sync-page-layouts.ts',
+}
+
+try {
+  console.log('Payload Studio app scaffolding\n')
+
+  let created = 0
+  let skipped = 0
+
+  for (const entry of FILES) {
+    const target = path.join(cwd, entry.file)
+
+    if (fs.existsSync(target)) {
+      console.log('  skip (exists)  ' + entry.file)
+      skipped += 1
+      continue
+    }
+
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    fs.writeFileSync(target, entry.contents)
+    console.log('  created        ' + entry.file)
+    created += 1
+  }
+
+  console.log('\n' + created + ' file(s) created, ' + skipped + ' skipped (already present).')
+
+  // Report which required package.json scripts are missing, without mutating.
+  const pkgPath = path.join(cwd, 'package.json')
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+    const scripts = pkg.scripts || {}
+    const missing = Object.entries(REQUIRED_SCRIPTS).filter(([name]) => !scripts[name])
+
+    if (missing.length > 0) {
+      console.log('\nAdd the following to package.json "scripts":\n')
+      for (const [name, command] of missing) {
+        console.log('  "' + name + '": "' + command.replace(/"/g, '\\"') + '",')
+      }
+    } else {
+      console.log('\nAll required package.json scripts are present.')
+    }
+  }
+
+  console.log('\nNext steps:')
+  console.log('  1. Wire payload.config.ts with configureAdmin(...) and createStudioPagesCollection(...)')
+  console.log('  2. npm run payload:types')
+  console.log('  3. npm run generate:importmap')
+  console.log('  4. See docs/studio-website-setup-guide.md for the full contract.')
+} catch (error) {
+  console.error('Scaffolding failed:', error)
+  process.exit(1)
+}

package/dist/admin/index.d.mts

@@ -1,4 +1,4 @@
-export { A as AdminConfig, a as AdminStudioConfig, b as AdminStudioFooterPreviewConfig, c as AdminStudioHeaderPreviewConfig, d as AdminStudioSitePreviewConfig, C as CreateSocialMediaConnectionsFieldOptions, e as CreateSocialMediaGlobalOptions, R as ResolvedStudioDashboardPanel, f as ResolvedStudioSection, S as StudioDashboardPanel, g as StudioDashboardPanelSpan, h as StudioGlobalLink, j as StudioSection, k as StudioSectionCard, l as StudioSectionComponent, m as StudioSectionRole, n as StudioSectionView, o as configureAdmin, p as createHeaderNavItemsField, q as createSocialMediaConnectionsField, r as createSocialMediaGlobal, s as createThemePreferenceField, t as socialMediaConnectionsField, u as themePreferenceField, w as withTooltips } from '../index-DLfPOqYA.mjs';
+export { A as AdminConfig, a as AdminStudioConfig, b as AdminStudioFooterPreviewConfig, c as AdminStudioHeaderPreviewConfig, d as AdminStudioSitePreviewConfig, C as CreateSocialMediaConnectionsFieldOptions, e as CreateSocialMediaGlobalOptions, R as ResolvedStudioDashboardPanel, f as ResolvedStudioSection, S as StudioDashboardPanel, g as StudioDashboardPanelSpan, h as StudioGlobalLink, j as StudioSection, k as StudioSectionCard, l as StudioSectionComponent, m as StudioSectionRole, n as StudioSectionView, o as configureAdmin, p as createHeaderNavItemsField, q as createSocialMediaConnectionsField, r as createSocialMediaGlobal, s as createThemePreferenceField, t as socialMediaConnectionsField, u as themePreferenceField, w as withTooltips } from '../index-BbTcimgH.mjs';
 export { b as SOCIAL_MEDIA_DEFAULT_ICON_BY_PLATFORM, c as SOCIAL_MEDIA_ICON_OPTIONS, d as SOCIAL_MEDIA_PLATFORMS, e as SOCIAL_MEDIA_PLATFORM_LABELS, S as SocialMediaGlobalData, f as SocialMediaIconLibrary, g as SocialMediaIconOption, a as SocialMediaPlatform, h as SocialMediaProfileData, i as SocialMediaProfilesData } from '../socialMedia-C05Iy-SV.mjs';
 import 'payload';
 import '../sitePreviewTypes-BrJwGzJj.mjs';

package/dist/admin/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AdminConfig, a as AdminStudioConfig, b as AdminStudioFooterPreviewConfig, c as AdminStudioHeaderPreviewConfig, d as AdminStudioSitePreviewConfig, C as CreateSocialMediaConnectionsFieldOptions, e as CreateSocialMediaGlobalOptions, R as ResolvedStudioDashboardPanel, f as ResolvedStudioSection, S as StudioDashboardPanel, g as StudioDashboardPanelSpan, h as StudioGlobalLink, j as StudioSection, k as StudioSectionCard, l as StudioSectionComponent, m as StudioSectionRole, n as StudioSectionView, o as configureAdmin, p as createHeaderNavItemsField, q as createSocialMediaConnectionsField, r as createSocialMediaGlobal, s as createThemePreferenceField, t as socialMediaConnectionsField, u as themePreferenceField, w as withTooltips } from '../index-BV0vEGl6.js';
+export { A as AdminConfig, a as AdminStudioConfig, b as AdminStudioFooterPreviewConfig, c as AdminStudioHeaderPreviewConfig, d as AdminStudioSitePreviewConfig, C as CreateSocialMediaConnectionsFieldOptions, e as CreateSocialMediaGlobalOptions, R as ResolvedStudioDashboardPanel, f as ResolvedStudioSection, S as StudioDashboardPanel, g as StudioDashboardPanelSpan, h as StudioGlobalLink, j as StudioSection, k as StudioSectionCard, l as StudioSectionComponent, m as StudioSectionRole, n as StudioSectionView, o as configureAdmin, p as createHeaderNavItemsField, q as createSocialMediaConnectionsField, r as createSocialMediaGlobal, s as createThemePreferenceField, t as socialMediaConnectionsField, u as themePreferenceField, w as withTooltips } from '../index-DV-nW43e.js';
 export { b as SOCIAL_MEDIA_DEFAULT_ICON_BY_PLATFORM, c as SOCIAL_MEDIA_ICON_OPTIONS, d as SOCIAL_MEDIA_PLATFORMS, e as SOCIAL_MEDIA_PLATFORM_LABELS, S as SocialMediaGlobalData, f as SocialMediaIconLibrary, g as SocialMediaIconOption, a as SocialMediaPlatform, h as SocialMediaProfileData, i as SocialMediaProfilesData } from '../socialMedia-C05Iy-SV.js';
 import 'payload';
 import '../sitePreviewTypes-BrJwGzJj.js';

package/dist/admin/index.js

@@ -260,23 +260,33 @@ function configureAdmin(config) {
   if (cssSources.length === 0) {
     cssPath = sourceCssPath;
   } else {
-    let css = cssSources.map((filePath) => import_fs.default.readFileSync(filePath, "utf-8")).join("\n\n");
-    css = css.replace(
-      "--orion-cms-brand-primary-fallback: #3b82f6;",
-      `--orion-cms-brand-primary-fallback: ${brandPrimary};`
-    );
-    css = css.replace(
-      "--orion-cms-brand-secondary-fallback: #8b5cf6;",
-      `--orion-cms-brand-secondary-fallback: ${brandSecondary};`
-    );
-    const outputBasePath = config.basePath || process.cwd();
-    const genDir = import_path.default.resolve(outputBasePath, ".generated");
-    if (!import_fs.default.existsSync(genDir)) {
-      import_fs.default.mkdirSync(genDir, { recursive: true });
+    try {
+      let css = cssSources.map((filePath) => import_fs.default.readFileSync(filePath, "utf-8")).join("\n\n");
+      css = css.replace(
+        "--orion-cms-brand-primary-fallback: #3b82f6;",
+        `--orion-cms-brand-primary-fallback: ${brandPrimary};`
+      );
+      css = css.replace(
+        "--orion-cms-brand-secondary-fallback: #8b5cf6;",
+        `--orion-cms-brand-secondary-fallback: ${brandSecondary};`
+      );
+      const outputBasePath = config.basePath || process.cwd();
+      const genDir = import_path.default.resolve(outputBasePath, ".generated");
+      const genPath = import_path.default.resolve(genDir, "admin.css");
+      let existing = null;
+      try {
+        existing = import_fs.default.readFileSync(genPath, "utf-8");
+      } catch {
+        existing = null;
+      }
+      if (existing !== css) {
+        import_fs.default.mkdirSync(genDir, { recursive: true });
+        import_fs.default.writeFileSync(genPath, css);
+      }
+      cssPath = genPath;
+    } catch {
+      cssPath = sourceCssPath;
     }
-    const genPath = import_path.default.resolve(genDir, "admin.css");
-    import_fs.default.writeFileSync(genPath, css);
-    cssPath = genPath;
   }
   const clientPath = "@orion-studios/payload-studio/admin/client";
   const studioNavClientProps = {
@@ -729,16 +739,47 @@ function configureAdmin(config) {
       });
     },
     wrapGlobals(globals2) {
-      const labelMap = {
+      const defaultLabelMap = {
         header: { group: "Site Design", label: "Header & Navigation" },
         footer: { group: "Site Design", label: "Footer" },
         "site-settings": { group: "Site Design", label: "Website Settings" },
         "social-media": { group: "Site Design", label: "Social Media" },
         "contact-form": { group: "Lead Forms", label: "Contact Form" }
       };
+      const configuredBySlug = new Map(
+        (config.studio?.globals || []).map((link) => [link.slug, link])
+      );
+      const attachBreadcrumbToGlobal = (global) => {
+        if (!studioEnabled) {
+          return global;
+        }
+        const existingControls = global.admin?.components?.elements?.beforeDocumentControls;
+        return {
+          ...global,
+          admin: {
+            ...global.admin,
+            components: {
+              ...global.admin?.components,
+              elements: {
+                ...global.admin?.components?.elements,
+                beforeDocumentControls: appendComponent(
+                  existingControls,
+                  studioBackBreadcrumbComponent,
+                  "StudioBackBreadcrumb"
+                )
+              }
+            }
+          }
+        };
+      };
       return globals2.map((global) => {
-        const mapping = labelMap[global.slug];
-        if (!mapping) return global;
+        const configured = configuredBySlug.get(global.slug);
+        const defaults = defaultLabelMap[global.slug];
+        const mapping = configured || defaults ? {
+          group: configured?.group || defaults?.group,
+          label: configured?.label || defaults?.label || global.slug
+        } : void 0;
+        if (!mapping) return attachBreadcrumbToGlobal(global);
         const shouldAttachSiteSettingsEditView = studioEnabled && global.slug === "site-settings";
         const shouldAttachSocialMediaEditView = studioEnabled && global.slug === "social-media";
         const shouldAttachContactFormRedirect = studioEnabled && global.slug === "contact-form";
@@ -847,7 +888,7 @@ function configureAdmin(config) {
           ...global,
           admin: {
             ...global.admin,
-            group: mapping.group,
+            ...mapping.group ? { group: mapping.group } : {},
             components: {
               ...global.admin?.components,
               elements: {

package/dist/admin/index.mjs

@@ -7,7 +7,7 @@ import {
   socialMediaConnectionsField,
   themePreferenceField,
   withTooltips
-} from "../chunk-KHK6RTGC.mjs";
+} from "../chunk-MMJNHBOF.mjs";
 import {
   SOCIAL_MEDIA_DEFAULT_ICON_BY_PLATFORM,
   SOCIAL_MEDIA_ICON_OPTIONS,

package/dist/blocks/index.mjs

@@ -17,8 +17,7 @@ import {
   defaultPageLayoutBlocks,
   sectionPresets,
   templateStarterPresets
-} from "../chunk-JQAHXYAM.mjs";
-import "../chunk-OQSEJXC4.mjs";
+} from "../chunk-KMYMSR7W.mjs";
 import "../chunk-6BWS3CLP.mjs";
 export {
   BeforeAfterBlock,