@nextsparkjs/core 0.1.0-beta.19 → 0.1.0-beta.191

package/scripts/build/registry/generators/block-registry.mjs

@@ -1,14 +1,61 @@
 /**
  * Block Registry Generator
  *
- * Generates block-registry.ts
+ * Generates block-registry.ts, block-registry.client.ts and block-registry.lazy.ts
+ *
+ * The split is what keeps block components out of the browser bundle. A block
+ * component is a server component and may import server-only code; the editor,
+ * the picker and the devtools viewers are client components that only ever read
+ * the configs. Importing both from one module drags every component — and
+ * whatever it imports — into the client build, which fails outright when one of
+ * them is server-only.
  *
  * @module core/scripts/build/registry/generators/block-registry
  */
 
 import { join } from 'path'
+import { toSafeIdentifier } from './identifier.mjs'
 import { convertCorePath } from '../config.mjs'
 
+/**
+ * The registry entries both halves emit, so the configs cannot drift apart.
+ *
+ * @param {Array} blocks - Discovered blocks
+ * @returns {string} The entries, ready to sit inside the object literal
+ */
+function buildRegistryEntries(blocks) {
+  return blocks.map(block => {
+
+    const slugVar = toSafeIdentifier(block.slug)
+    const scopeValue = block.scope
+      ? `[${block.scope.map(s => `'${s}'`).join(', ')}]`
+      : 'undefined'
+    const examplesValue = block.hasExamples ? `${slugVar}_examples` : '[]'
+    const allowInPatternsValue = block.allowInPatterns !== undefined
+      ? block.allowInPatterns.toString()
+      : 'undefined'
+
+    return `  '${block.slug}': {
+    slug: '${block.slug}',
+    name: '${block.name}',
+    description: '${block.description}',
+    category: '${block.category}' as BlockCategory,
+    icon: '${block.icon}',
+    componentPath: '${block.paths.component}',
+    schemaPath: '${block.paths.schema}',
+    fieldsPath: '${block.paths.fields}',
+    thumbnail: ${block.paths.thumbnail ? `'${block.paths.thumbnail}'` : 'undefined'},
+    fieldDefinitions: ${slugVar}_fields,
+    examples: ${examplesValue},
+    scope: ${scopeValue},
+    allowInPatterns: ${allowInPatternsValue},
+    isCore: false,
+    source: 'theme' as const,
+    sourceId: '${block.themeName}'
+  }`
+  }).join(',\n')
+}
+
 /**
  * Generate the block registry file
  * @param {Array} blocks - Discovered blocks
@@ -18,6 +65,8 @@ import { convertCorePath } from '../config.mjs'
 export function generateBlockRegistry(blocks, config) {
   const outputFilePath = join(config.outputDir, 'block-registry.ts')
   if (blocks.length === 0) {
+    // When no blocks, use inline type definition to avoid import issues in npm mode
+    // (DTS generation is disabled in core package for performance reasons)
     return `/**
  * Auto-generated Block Registry
  *
@@ -28,13 +77,37 @@ export function generateBlockRegistry(blocks, config) {
  */
 
 import React from 'react'
-import type { BlockConfig } from '${convertCorePath('@/core/types/blocks', outputFilePath, config)}'
 
-export const BLOCK_REGISTRY: Record<string, BlockConfig> = {}
+// Inline type definition for empty registry (avoids import issues in npm mode)
+type BlockConfig = {
+  slug: string
+  name: string
+  description?: string
+  category: string
+  icon?: string
+  componentPath?: string
+  schemaPath?: string
+  fieldsPath?: string
+  thumbnail?: string
+  fieldDefinitions: unknown[]
+  examples: unknown[]
+  scope?: string[]
+  allowInPatterns?: boolean
+  schemaType?: string
+  tags?: string[]
+  isCore?: boolean
+  source?: string
+  sourceId?: string
+  version?: string
+  deprecated?: boolean
+  replacedBy?: string
+}
 
-export const BLOCK_CATEGORIES: string[] = []
+export * from './block-registry.client'
+export { BLOCK_COMPONENTS } from './block-registry.lazy'
 
-export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<any>>> = {}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const BLOCK_COMPONENTS_SSR: Record<string, React.ComponentType<any>> = {}
 
 export const BLOCK_METADATA = {
   totalBlocks: 0,
@@ -46,48 +119,25 @@ export const BLOCK_METADATA = {
 `
   }
 
-  // Import field definitions and examples (if they exist)
+  // Import field definitions, examples, and components
   const imports = []
+  const ssrImports = []
 
   blocks.forEach(block => {
-    const slugVar = block.slug.replace(/-/g, '_')
+    const slugVar = toSafeIdentifier(block.slug)
 
-    // Always import field definitions
     imports.push(`import { fieldDefinitions as ${slugVar}_fields } from '${block.paths.fields}'`)
+    ssrImports.push(`import { default as ${slugVar}_component } from '${block.paths.component}'`)
 
-    // Conditionally import examples if they exist
     if (block.hasExamples) {
       imports.push(`import { examples as ${slugVar}_examples } from '${block.paths.examples}'`)
     }
   })
 
   const fieldImports = imports.join('\n')
+  const ssrComponentImports = ssrImports.join('\n')
 
-  const registryEntries = blocks.map(block => {
-    const slugVar = block.slug.replace(/-/g, '_')
-    const scopeValue = block.scope
-      ? `[${block.scope.map(s => `'${s}'`).join(', ')}]`
-      : 'undefined'
-    const examplesValue = block.hasExamples ? `${slugVar}_examples` : '[]'
-
-    return `  '${block.slug}': {
-    slug: '${block.slug}',
-    name: '${block.name}',
-    description: '${block.description}',
-    category: '${block.category}' as BlockCategory,
-    icon: '${block.icon}',
-    componentPath: '${block.paths.component}',
-    schemaPath: '${block.paths.schema}',
-    fieldsPath: '${block.paths.fields}',
-    thumbnail: ${block.paths.thumbnail ? `'${block.paths.thumbnail}'` : 'undefined'},
-    fieldDefinitions: ${slugVar}_fields,
-    examples: ${examplesValue},
-    scope: ${scopeValue},
-    isCore: false,
-    source: 'theme' as const,
-    sourceId: '${block.themeName}'
-  }`
-  }).join(',\n')
+  const registryEntries = buildRegistryEntries(blocks)
 
   const categories = [...new Set(blocks.map(b => b.category))]
 
@@ -105,24 +155,27 @@ export const BLOCK_METADATA = {
  */
 
 import React from 'react'
-import type { BlockConfig, BlockCategory } from '${convertCorePath('@/core/types/blocks', outputFilePath, config)}'
-
-${fieldImports}
 
-export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
-${registryEntries}
-}
+// Configs live in the client half so a client component can read them without
+// pulling in a single block component.
+export * from './block-registry.client'
+// Lazy components live in their own module, which a client component can import
+// without the static imports below.
+export { BLOCK_COMPONENTS } from './block-registry.lazy'
 
-export const BLOCK_CATEGORIES: BlockCategory[] = [${categories.map(c => `'${c}'`).join(', ')}]
+// Direct component imports for SSR — zero CLS, synchronous hydration
+${ssrComponentImports}
 
 /**
- * Lazy-loaded block components for runtime rendering
- * Each component is wrapped with React.lazy for code-splitting
- * Uses Object.values to get the first exported component (handles varying naming conventions)
+ * Direct-imported block components for SSR rendering.
+ * Static imports ensure synchronous hydration — zero CLS.
+ * HTML is fully visible without client JS (SEO-safe, no-JS compatible).
  */
-export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<any>>> = {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const BLOCK_COMPONENTS_SSR: Record<string, React.ComponentType<any>> = {
 ${blocks.map(block => {
-    return `  '${block.slug}': React.lazy(() => import('${block.paths.component}').then(mod => ({ default: Object.values(mod)[0] as React.ComponentType<any> })))`
+    const slugVar = toSafeIdentifier(block.slug)
+    return `  '${block.slug}': ${slugVar}_component`
   }).join(',\n')}
 }
 
@@ -143,3 +196,147 @@ ${categories.map(cat => {
 }
 `
 }
+
+/**
+ * Generate the client-safe half: block configs, with no component imports.
+ *
+ * This is what a client component reads. Keeping it free of component imports
+ * is the whole point — a block component is a server component, and pulling one
+ * into the client build fails the build when it imports server-only code.
+ *
+ * @param {Array} blocks - Discovered blocks
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {string} Generated TypeScript content
+ */
+export function generateBlockRegistryClient(blocks, config) {
+  const outputFilePath = join(config.outputDir, 'block-registry.client.ts')
+  const header = `/**
+ * Auto-generated Block Registry (client-safe)
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Blocks discovered: ${blocks.length}
+ *
+ * Block configs only: no component imports, so a client component can read the
+ * registry without the block components reaching the browser bundle.
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build-registry.mjs
+ */
+`
+
+  if (blocks.length === 0) {
+    return `${header}
+// Inline type definition for empty registry (avoids import issues in npm mode)
+type BlockConfig = {
+  slug: string
+  name: string
+  description?: string
+  category: string
+  icon?: string
+  componentPath?: string
+  schemaPath?: string
+  fieldsPath?: string
+  thumbnail?: string
+  fieldDefinitions: unknown[]
+  examples: unknown[]
+  scope?: string[]
+  allowInPatterns?: boolean
+  schemaType?: string
+  tags?: string[]
+  isCore?: boolean
+  source?: string
+  sourceId?: string
+  version?: string
+  deprecated?: boolean
+  replacedBy?: string
+}
+
+export const BLOCK_REGISTRY: Record<string, BlockConfig> = {}
+
+export const BLOCK_CATEGORIES: string[] = []
+
+export const BLOCK_METADATA = {
+  totalBlocks: 0,
+  categories: [],
+  blocksByCategory: {},
+  generatedAt: '${new Date().toISOString()}',
+  blocks: []
+}
+`
+  }
+
+  const imports = []
+  blocks.forEach(block => {
+    const slugVar = toSafeIdentifier(block.slug)
+    imports.push(`import { fieldDefinitions as ${slugVar}_fields } from '${block.paths.fields}'`)
+    if (block.hasExamples) {
+      imports.push(`import { examples as ${slugVar}_examples } from '${block.paths.examples}'`)
+    }
+  })
+
+  const registryEntries = buildRegistryEntries(blocks)
+  const categories = [...new Set(blocks.map(b => b.category))]
+
+  return `${header}
+import type { BlockConfig, BlockCategory } from '${convertCorePath('@/core/types', outputFilePath, config)}'
+
+${imports.join('\n')}
+
+export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
+${registryEntries}
+}
+
+export const BLOCK_CATEGORIES: BlockCategory[] = [${categories.map(c => `'${c}'`).join(', ')}]
+
+/**
+ * Block registry metadata
+ */
+export const BLOCK_METADATA = {
+  totalBlocks: ${blocks.length},
+  categories: [${categories.map(c => `'${c}'`).join(', ')}],
+  blocksByCategory: {
+${categories.map(cat => `    '${cat}': ${blocks.filter(b => b.category === cat).length}`).join(',\n')}
+  },
+  generatedAt: '${new Date().toISOString()}',
+  blocks: [${blocks.map(b => `'${b.slug}'`).join(', ')}]
+}
+`
+}
+
+/**
+ * Generate the lazy half: every block component behind React.lazy, and no
+ * static import.
+ *
+ * Client components that render blocks (the editor canvas, pattern previews,
+ * devtools) read this, so each block stays in a chunk of its own and loads
+ * when it is shown. Reaching the components through block-registry.ts instead
+ * carries its static SSR imports along, and with them every block and all a
+ * block imports, into that client component's bundle.
+ *
+ * @param {Array} blocks - Discovered blocks
+ * @returns {string} Generated TypeScript content
+ */
+export function generateBlockRegistryLazy(blocks) {
+  const entries = blocks.map(block =>
+    `  '${block.slug}': React.lazy(() => import('${block.paths.component}').then(mod => ({ default: Object.values(mod)[0] as React.ComponentType<any> })))`
+  ).join(',\n')
+
+  return `/**
+ * Auto-generated Block Registry (lazy components)
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Blocks discovered: ${blocks.length}
+ *
+ * Block components behind React.lazy and nothing imported statically, so a
+ * client component can render blocks while each one stays in its own chunk.
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build-registry.mjs
+ */
+
+import React from 'react'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<any>>> = {
+${entries}
+}
+`
+}

package/scripts/build/registry/generators/docs-registry.mjs

@@ -0,0 +1,240 @@
+/**
+ * Docs Registry Generator
+ *
+ * Generates docs-registry.ts with actual documentation content.
+ * Scans themes/{THEME}/docs/public/ and docs/superadmin/ directories.
+ *
+ * @module core/scripts/build/registry/generators/docs-registry
+ */
+
+import { existsSync, readdirSync } from 'fs'
+import path from 'path'
+import { CONFIG } from '../config.mjs'
+
+// Get config values - use themesDir which correctly handles monorepo mode
+const projectRoot = CONFIG.projectRoot
+const monorepoRoot = CONFIG.monorepoRoot
+const isNpmMode = CONFIG.isNpmMode
+const isMonorepoMode = CONFIG.isMonorepoMode
+
+// Themes directory - use CONFIG.themesDir for correct monorepo/npm mode handling
+const THEMES_DIR = CONFIG.themesDir
+
+/**
+ * Extract order number from filename (01-example -> 1)
+ */
+function extractOrder(name) {
+  const match = name.match(/^(\d+)-/)
+  return match ? parseInt(match[1], 10) : 999
+}
+
+/**
+ * Clean filename (01-example.md -> example)
+ */
+function cleanName(name) {
+  return name.replace(/^\d+-/, '').replace(/\.md$/, '')
+}
+
+/**
+ * Convert slug to title (getting-started -> Getting Started)
+ */
+function slugToTitle(slug) {
+  return slug
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+/**
+ * Scan a documentation directory and build registry metadata
+ *
+ * @param {string} docsPath - Absolute path to docs directory
+ * @param {'public' | 'superadmin'} source - Source type
+ * @returns {Array} Array of section metadata
+ */
+function scanDocsDirectory(docsPath, source) {
+  if (!existsSync(docsPath)) {
+    return []
+  }
+
+  const sections = []
+  const items = readdirSync(docsPath, { withFileTypes: true })
+
+  for (const item of items) {
+    if (!item.isDirectory()) continue
+
+    const sectionPath = path.join(docsPath, item.name)
+    const order = extractOrder(item.name)
+    const slug = cleanName(item.name)
+    const title = slugToTitle(slug)
+
+    const pages = []
+    const files = readdirSync(sectionPath)
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue
+
+      const filePath = path.join(sectionPath, file)
+      const fileOrder = extractOrder(file)
+      const pageSlug = cleanName(file)
+      const pageTitle = slugToTitle(pageSlug)
+
+      // Get relative path from consuming app directory
+      // In monorepo mode: calculate relative from projectRoot (apps/dev) to file in themes/
+      // In npm mode: calculate relative from projectRoot to file in contents/themes/
+      let relativePath
+      if (isMonorepoMode && monorepoRoot) {
+        // In monorepo, themes are at monorepoRoot/themes/
+        // projectRoot is apps/dev, so we need ../../themes/...
+        const themeRelativePath = filePath.replace(monorepoRoot, '')
+        relativePath = '../..' + themeRelativePath
+      } else {
+        // In npm mode, themes are at projectRoot/contents/themes/
+        relativePath = filePath.replace(projectRoot, '')
+      }
+
+      pages.push({
+        slug: pageSlug,
+        title: pageTitle,
+        order: fileOrder,
+        path: relativePath,
+        source
+      })
+    }
+
+    // Sort pages by order
+    pages.sort((a, b) => a.order - b.order)
+
+    sections.push({
+      title,
+      slug,
+      order,
+      pages,
+      source
+    })
+  }
+
+  // Sort sections by order
+  return sections.sort((a, b) => a.order - b.order)
+}
+
+/**
+ * Generate the docs registry file with actual content
+ *
+ * @returns {string} Generated TypeScript content
+ */
+export function generateDocsRegistry() {
+  const theme = CONFIG.activeTheme || 'default'
+  const themeDocsDir = path.join(THEMES_DIR, theme, 'docs')
+
+  // Scan public docs (user-facing → /docs)
+  const publicDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'public'),
+    'public'
+  )
+
+  // Scan superadmin docs (admin-facing → /superadmin/docs)
+  const superadminDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'superadmin'),
+    'superadmin'
+  )
+
+  // Create registry
+  const registry = {
+    public: publicDocs,
+    superadmin: superadminDocs,
+    all: [...publicDocs, ...superadminDocs].sort((a, b) => a.order - b.order)
+  }
+
+  // Total pages count
+  const publicPages = publicDocs.reduce((sum, section) => sum + section.pages.length, 0)
+  const superadminPages = superadminDocs.reduce((sum, section) => sum + section.pages.length, 0)
+  const totalPages = publicPages + superadminPages
+
+  return `/**
+ * Auto-generated Documentation Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Theme: ${theme}
+ * Public sections: ${publicDocs.length}
+ * Superadmin sections: ${superadminDocs.length}
+ * Total pages: ${totalPages}
+ *
+ * Structure:
+ * - public: User-facing documentation → /docs
+ * - superadmin: Admin documentation → /superadmin/docs
+ *
+ * DO NOT EDIT - This file is auto-generated
+ */
+
+// Inline type definitions for npm mode (avoids import issues since DTS is disabled)
+export interface DocPageMeta {
+  slug: string
+  title: string
+  order: number
+  path: string
+  source: 'public' | 'superadmin'
+}
+
+export interface DocSectionMeta {
+  slug: string
+  title: string
+  order: number
+  pages: DocPageMeta[]
+  source: 'public' | 'superadmin'
+}
+
+export interface DocsRegistryStructure {
+  public: DocSectionMeta[]
+  superadmin: DocSectionMeta[]
+  all: DocSectionMeta[]
+}
+
+export const DOCS_REGISTRY: DocsRegistryStructure = ${JSON.stringify(registry, null, 2)} as const
+
+export type DocsRegistry = typeof DOCS_REGISTRY
+
+/**
+ * Get all documentation sections (public + superadmin)
+ */
+export function getAllDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.all
+}
+
+/**
+ * Get public documentation sections only (for /docs)
+ */
+export function getPublicDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.public
+}
+
+/**
+ * Get superadmin documentation sections only (for /superadmin/docs)
+ */
+export function getSuperadminDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.superadmin
+}
+
+/**
+ * Find a section by slug
+ */
+export function findDocSection(slug: string): DocSectionMeta | undefined {
+  return DOCS_REGISTRY.all.find(section => section.slug === slug)
+}
+
+/**
+ * Find a section by slug in a specific category
+ */
+export function findDocSectionInCategory(slug: string, category: 'public' | 'superadmin'): DocSectionMeta | undefined {
+  return DOCS_REGISTRY[category].find(section => section.slug === slug)
+}
+
+/**
+ * Find a page within a section
+ */
+export function findDocPage(sectionSlug: string, pageSlug: string): DocPageMeta | undefined {
+  const section = findDocSection(sectionSlug)
+  return section?.pages.find(page => page.slug === pageSlug)
+}
+`
+}

package/scripts/build/registry/generators/email-registry.mjs

@@ -0,0 +1,94 @@
+/**
+ * Email Registry Generator
+ *
+ * Generates email-registry.ts — a static, frozen map from slug to template
+ * function, where theme overrides win over core defaults.
+ *
+ * The generated file is intentionally NOT annotated with `Record<string, …>`.
+ * Instead it uses `as const` so TypeScript infers per-slug types from each
+ * imported function's signature — same trick `entity-registry.mjs` already
+ * uses. This means consumer-defined slugs (in `themes/<theme>/emails/`) get
+ * full per-slug type inference for free, with zero `declare module` boilerplate.
+ *
+ * @module core/scripts/build/registry/generators/email-registry
+ */
+
+import { join } from 'path'
+import { convertCorePath } from '../config.mjs'
+
+/**
+ * @param {Array<{slug: string, source: 'core'|'theme', importPath: string, importName: string}>} emails
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {string} Generated TypeScript content
+ */
+export function generateEmailRegistry(emails, config) {
+  const outputFilePath = join(config.outputDir, 'email-registry.ts')
+
+  // Resolve core import paths through convertCorePath so they work in both
+  // monorepo and npm modes. Theme paths are project-local so don't need it.
+  const importLines = emails
+    .map(email => {
+      const importPath =
+        email.source === 'core'
+          ? convertCorePath(email.importPath, outputFilePath, config)
+          : email.importPath
+      return `import ${email.importName} from '${importPath}'`
+    })
+    .join('\n')
+
+  // Map literal entries — quoted slug keys (some slugs are kebab-case which
+  // is not a valid identifier without quoting).
+  const registryEntries = emails
+    .map(email => `  '${email.slug}': ${email.importName},`)
+    .join('\n')
+
+  // Metadata for diagnostics / DX
+  const metadataEntries = emails
+    .map(
+      email =>
+        `  '${email.slug}': { source: '${email.source}' as const, overridden: ${email.source === 'theme'} },`,
+    )
+    .join('\n')
+
+  const generatedAt = new Date().toISOString()
+  const sourcesLine = emails.length === 0
+    ? '(no email templates discovered)'
+    : emails.map(e => `${e.slug}(${e.source})`).join(', ')
+
+  return `/**
+ * Auto-generated Email Registry
+ *
+ * Generated at: ${generatedAt}
+ * Templates discovered: ${emails.length}
+ * Sources: ${sourcesLine}
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build/registry.mjs.
+ * Override behaviour: drop a file at \`themes/<active-theme>/emails/<slug>.ts\`
+ * and rebuild — the theme version wins over the core default at the same slug,
+ * and entirely new slugs from a theme are additive.
+ *
+ * Type safety: this file emits a literal object with \`as const\` so TypeScript
+ * infers per-slug data types from each imported function's signature.
+ * Do NOT add a \`Record<string, …>\` annotation — that would erase the per-slug
+ * inference and consumer-defined slugs would lose type safety.
+ */
+
+${importLines}
+
+export const EMAIL_REGISTRY = {
+${registryEntries}
+} as const
+
+export type EmailSlug = keyof typeof EMAIL_REGISTRY
+
+export const EMAIL_REGISTRY_METADATA = {
+${metadataEntries}
+} as const
+
+export const EMAIL_REGISTRY_INFO = {
+  totalTemplates: ${emails.length},
+  generatedAt: '${generatedAt}',
+  slugs: [${emails.map(e => `'${e.slug}'`).join(', ')}] as const,
+} as const
+`
+}