create-visualbuild-app 0.1.0 → 1.0.1

package/visual-app-builder/shared/visualbuildConfig.d.mts

@@ -0,0 +1,144 @@
+export type VisualBuildTheme =
+  | 'default'
+  | 'codex-dark'
+  | 'vs-light'
+  | 'vs-dark'
+  | 'system'
+  | 'dark'
+  | 'light'
+export type VisualBuildViewport = 'mobile' | 'tablet' | 'desktop'
+export type VisualBuildCodeView = 'page' | 'app' | 'layout' | 'schema' | 'file'
+
+export interface VisualBuildPaths {
+  sourceDir?: string
+  pagesDir?: string
+  layoutsDir?: string
+  appFile?: string
+  schemaFile?: string
+  componentRegistryFile?: string
+  generatedManifestFile?: string
+}
+
+export interface VisualBuildEditorOptions {
+  theme?: VisualBuildTheme
+  defaultViewport?: VisualBuildViewport
+  responsiveWidths?: {
+    mobile?: number
+    tablet?: number
+    desktop?: number | 'fluid'
+  }
+  panels?: {
+    leftOpen?: boolean
+    leftTab?: 'files' | 'elements'
+    rightOpen?: boolean
+    rightTab?: 'code' | 'properties'
+    codeView?: VisualBuildCodeView
+  }
+}
+
+export interface VisualBuildGeneratorOptions {
+  emitApp?: boolean
+  emitLayout?: boolean
+  cleanStaleFiles?: boolean
+}
+
+export interface VisualBuildDeploymentOptions {
+  provider?: 'vercel'
+  outputDirectory?: string
+  projectName?: string
+  teamId?: string
+}
+
+export type VisualBuildPropType =
+  | 'string'
+  | 'text'
+  | 'number'
+  | 'boolean'
+  | 'color'
+  | 'select'
+  | 'array'
+  | 'attributes'
+
+export interface VisualBuildPropDefinition {
+  type: VisualBuildPropType
+  label?: string
+  default?: unknown
+  options?: string[]
+}
+
+export interface VisualBuildCustomComponent {
+  name: string
+  importPath: string
+  exportName?: 'default' | string
+  label?: string
+  category?: string
+  icon?: string
+  description?: string
+  acceptsChildren?: boolean
+  props?: Record<string, VisualBuildPropDefinition>
+}
+
+export interface VisualBuildConfig {
+  paths?: VisualBuildPaths
+  editor?: VisualBuildEditorOptions
+  generator?: VisualBuildGeneratorOptions
+  deployment?: VisualBuildDeploymentOptions
+  components?: VisualBuildCustomComponent[]
+}
+
+export interface ResolvedVisualBuildCustomComponent {
+  name: string
+  importPath: string
+  exportName: string
+  label: string
+  category: string
+  icon: string
+  description: string
+  acceptsChildren: boolean
+  defaultProps: Record<string, unknown>
+  propSchema: Record<
+    string,
+    {
+      type: VisualBuildPropType
+      label: string
+      default: unknown
+      options?: string[]
+    }
+  >
+}
+
+export interface ResolvedVisualBuildConfig {
+  paths: Required<VisualBuildPaths>
+  editor: {
+    theme: VisualBuildTheme
+    defaultViewport: VisualBuildViewport
+    responsiveWidths: {
+      mobile: number
+      tablet: number
+      desktop: number | 'fluid'
+    }
+    panels: {
+      leftOpen: boolean
+      leftTab: 'files' | 'elements'
+      rightOpen: boolean
+      rightTab: 'code' | 'properties'
+      codeView: VisualBuildCodeView
+    }
+  }
+  generator: Required<VisualBuildGeneratorOptions>
+  deployment: {
+    provider: 'vercel'
+    outputDirectory: string
+    projectName?: string
+    teamId?: string
+  }
+  components: ResolvedVisualBuildCustomComponent[]
+}
+
+export const defaultVisualBuildConfig: ResolvedVisualBuildConfig
+export function loadVisualBuildConfig(
+  projectRoot: string
+): Promise<ResolvedVisualBuildConfig>
+export function validateVisualBuildConfig(
+  value: unknown
+): ResolvedVisualBuildConfig

package/visual-app-builder/shared/visualbuildConfig.mjs

@@ -0,0 +1,578 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const propTypes = new Set([
+  'string',
+  'text',
+  'number',
+  'boolean',
+  'color',
+  'select',
+  'array',
+  'attributes',
+])
+const themes = new Set([
+  'default',
+  'codex-dark',
+  'vs-light',
+  'vs-dark',
+  'system',
+  'dark',
+  'light',
+])
+const viewports = new Set(['mobile', 'tablet', 'desktop'])
+const leftPanelTabs = new Set(['files', 'elements'])
+const rightPanelTabs = new Set(['code', 'properties'])
+const codeViews = new Set(['page', 'app', 'layout', 'schema', 'file'])
+
+export const defaultVisualBuildConfig = Object.freeze({
+  paths: Object.freeze({
+    sourceDir: 'src',
+    pagesDir: 'src/pages',
+    layoutsDir: 'src/layouts',
+    appFile: 'src/App.tsx',
+    schemaFile: 'visualbuild/pages.json',
+    componentRegistryFile: 'visualbuild/components.json',
+    generatedManifestFile: 'visualbuild/generated-files.json',
+  }),
+  editor: Object.freeze({
+    theme: 'default',
+    defaultViewport: 'desktop',
+    responsiveWidths: Object.freeze({
+      mobile: 390,
+      tablet: 768,
+      desktop: 'fluid',
+    }),
+    panels: Object.freeze({
+      leftOpen: true,
+      leftTab: 'elements',
+      rightOpen: true,
+      rightTab: 'properties',
+      codeView: 'page',
+    }),
+  }),
+  generator: Object.freeze({
+    emitApp: true,
+    emitLayout: true,
+    cleanStaleFiles: true,
+  }),
+  deployment: Object.freeze({
+    provider: 'vercel',
+    outputDirectory: 'dist',
+    projectName: undefined,
+    teamId: undefined,
+  }),
+  components: Object.freeze([]),
+})
+
+export async function loadVisualBuildConfig(projectRoot) {
+  const configPath = path.join(projectRoot, 'visualbuild.config.ts')
+  const exists = await fs
+    .access(configPath)
+    .then(() => true)
+    .catch(() => false)
+  let sourceConfig = {}
+
+  if (exists) {
+    const sourceUrl = pathToFileURL(configPath)
+    sourceUrl.searchParams.set('updated', String(Date.now()))
+    const loaded = await import(sourceUrl.href)
+    sourceConfig = loaded.default ?? loaded
+  }
+
+  const baseConfig = validateVisualBuildConfig({
+    ...sourceConfig,
+    components: [],
+  })
+  const registrationsPath = path.resolve(
+    projectRoot,
+    ...baseConfig.paths.componentRegistryFile.split('/')
+  )
+  const fileRegistrations = await fs
+    .readFile(registrationsPath, 'utf8')
+    .then((source) => JSON.parse(source))
+    .catch((error) => {
+      if (error?.code === 'ENOENT') return { components: [] }
+      throw error
+    })
+
+  return validateVisualBuildConfig({
+    ...sourceConfig,
+    components: (fileRegistrations.components ?? []).map((component) => ({
+      ...component,
+      acceptsChildren: true,
+      props: {
+        wrapperTag: {
+          type: 'select',
+          label: 'Component root tag',
+          default: 'div',
+          options: [
+            'div',
+            'main',
+            'section',
+            'article',
+            'header',
+            'footer',
+            'nav',
+            'aside',
+            'form',
+          ],
+        },
+        id: {
+          type: 'string',
+          label: 'ID',
+          default: '',
+        },
+        className: {
+          type: 'text',
+          label: 'Tailwind classes',
+          default: '',
+        },
+        attributes: {
+          type: 'attributes',
+          label: 'Additional attributes',
+          default: {},
+        },
+        ...(component.props ?? {}),
+      },
+    })),
+  })
+}
+
+export function validateVisualBuildConfig(value) {
+  const config = value && typeof value === 'object' ? value : {}
+  const paths = validatePaths(config.paths)
+  const editor = validateEditor(config.editor)
+  const generator = validateGenerator(config.generator)
+  const deployment = validateDeployment(config.deployment)
+  const components = Array.isArray(config.components) ? config.components : []
+  const seenNames = new Set()
+
+  return {
+    paths,
+    editor,
+    generator,
+    deployment,
+    components: components.map((component, index) => {
+      const location = `components[${index}]`
+      const name = requiredString(component?.name, `${location}.name`)
+
+      if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+        throw new Error(
+          `${location}.name must be a PascalCase React component name`
+        )
+      }
+
+      if (seenNames.has(name)) {
+        throw new Error(`Custom component "${name}" is registered more than once`)
+      }
+      seenNames.add(name)
+
+      const importPath = normalizeImportPath(
+        requiredString(component?.importPath, `${location}.importPath`),
+        paths.sourceDir
+      )
+      const propSchema = validatePropSchema(component?.props ?? {}, location)
+      const defaultProps = Object.fromEntries(
+        Object.entries(propSchema).map(([key, schema]) => [key, schema.default])
+      )
+
+      return {
+        name,
+        label: optionalString(component?.label, splitPascalCase(name)),
+        category: optionalString(component?.category, 'Custom'),
+        icon: optionalString(component?.icon, 'C'),
+        description: optionalString(
+          component?.description,
+          `Local ${name} component`
+        ),
+        importPath,
+        exportName: optionalString(component?.exportName, 'default'),
+        defaultProps,
+        propSchema,
+        acceptsChildren: component?.acceptsChildren === true,
+      }
+    }),
+  }
+}
+
+function validateDeployment(value) {
+  const deployment = objectValue(value, 'deployment')
+  const provider = enumValue(
+    deployment.provider,
+    new Set(['vercel']),
+    defaultVisualBuildConfig.deployment.provider,
+    'deployment.provider'
+  )
+  const outputDirectory = projectDirectory(
+    deployment.outputDirectory,
+    defaultVisualBuildConfig.deployment.outputDirectory,
+    'deployment.outputDirectory'
+  )
+
+  if (outputDirectory === '.') {
+    throw new Error('deployment.outputDirectory cannot be the project root')
+  }
+  const projectName = optionalConfiguredString(
+    deployment.projectName,
+    'deployment.projectName'
+  )
+  const teamId = optionalConfiguredString(
+    deployment.teamId,
+    'deployment.teamId'
+  )
+
+  if (
+    projectName &&
+    (projectName.length > 100 ||
+      !/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/.test(projectName) ||
+      projectName.includes('---'))
+  ) {
+    throw new Error(
+      'deployment.projectName must be a valid lowercase Vercel project name'
+    )
+  }
+
+  if (teamId && !/^team_[A-Za-z0-9]+$/.test(teamId)) {
+    throw new Error('deployment.teamId must start with "team_"')
+  }
+
+  return {
+    provider,
+    outputDirectory,
+    ...(projectName ? { projectName } : {}),
+    ...(teamId ? { teamId } : {}),
+  }
+}
+
+function validatePaths(value) {
+  const paths = objectValue(value, 'paths')
+
+  const result = {
+    sourceDir: projectDirectory(
+      paths.sourceDir,
+      defaultVisualBuildConfig.paths.sourceDir,
+      'paths.sourceDir'
+    ),
+    pagesDir: projectDirectory(
+      paths.pagesDir,
+      defaultVisualBuildConfig.paths.pagesDir,
+      'paths.pagesDir'
+    ),
+    layoutsDir: projectDirectory(
+      paths.layoutsDir,
+      defaultVisualBuildConfig.paths.layoutsDir,
+      'paths.layoutsDir'
+    ),
+    appFile: projectFile(
+      paths.appFile,
+      defaultVisualBuildConfig.paths.appFile,
+      'paths.appFile',
+      /\.(jsx|tsx)$/i
+    ),
+    schemaFile: projectFile(
+      paths.schemaFile,
+      defaultVisualBuildConfig.paths.schemaFile,
+      'paths.schemaFile',
+      /\.json$/i
+    ),
+    componentRegistryFile: projectFile(
+      paths.componentRegistryFile,
+      defaultVisualBuildConfig.paths.componentRegistryFile,
+      'paths.componentRegistryFile',
+      /\.json$/i
+    ),
+    generatedManifestFile: projectFile(
+      paths.generatedManifestFile,
+      defaultVisualBuildConfig.paths.generatedManifestFile,
+      'paths.generatedManifestFile',
+      /\.json$/i
+    ),
+  }
+
+  for (const [location, configuredPath] of [
+    ['paths.pagesDir', result.pagesDir],
+    ['paths.layoutsDir', result.layoutsDir],
+    ['paths.appFile', result.appFile],
+  ]) {
+    if (!isPathInside(configuredPath, result.sourceDir)) {
+      throw new Error(
+        `${location} must stay inside paths.sourceDir (${result.sourceDir})`
+      )
+    }
+  }
+
+  return result
+}
+
+function validateEditor(value) {
+  const editor = objectValue(value, 'editor')
+  const responsiveWidths = objectValue(
+    editor.responsiveWidths,
+    'editor.responsiveWidths'
+  )
+  const panels = objectValue(editor.panels, 'editor.panels')
+
+  return {
+    theme: enumValue(
+      editor.theme,
+      themes,
+      defaultVisualBuildConfig.editor.theme,
+      'editor.theme'
+    ),
+    defaultViewport: enumValue(
+      editor.defaultViewport,
+      viewports,
+      defaultVisualBuildConfig.editor.defaultViewport,
+      'editor.defaultViewport'
+    ),
+    responsiveWidths: {
+      mobile: positiveWidth(
+        responsiveWidths.mobile,
+        defaultVisualBuildConfig.editor.responsiveWidths.mobile,
+        'editor.responsiveWidths.mobile'
+      ),
+      tablet: positiveWidth(
+        responsiveWidths.tablet,
+        defaultVisualBuildConfig.editor.responsiveWidths.tablet,
+        'editor.responsiveWidths.tablet'
+      ),
+      desktop: positiveWidth(
+        responsiveWidths.desktop,
+        defaultVisualBuildConfig.editor.responsiveWidths.desktop,
+        'editor.responsiveWidths.desktop',
+        true
+      ),
+    },
+    panels: {
+      leftOpen: booleanValue(
+        panels.leftOpen,
+        defaultVisualBuildConfig.editor.panels.leftOpen,
+        'editor.panels.leftOpen'
+      ),
+      leftTab: enumValue(
+        panels.leftTab,
+        leftPanelTabs,
+        defaultVisualBuildConfig.editor.panels.leftTab,
+        'editor.panels.leftTab'
+      ),
+      rightOpen: booleanValue(
+        panels.rightOpen,
+        defaultVisualBuildConfig.editor.panels.rightOpen,
+        'editor.panels.rightOpen'
+      ),
+      rightTab: enumValue(
+        panels.rightTab,
+        rightPanelTabs,
+        defaultVisualBuildConfig.editor.panels.rightTab,
+        'editor.panels.rightTab'
+      ),
+      codeView: enumValue(
+        panels.codeView,
+        codeViews,
+        defaultVisualBuildConfig.editor.panels.codeView,
+        'editor.panels.codeView'
+      ),
+    },
+  }
+}
+
+function validateGenerator(value) {
+  const generator = objectValue(value, 'generator')
+
+  return {
+    emitApp: booleanValue(
+      generator.emitApp,
+      defaultVisualBuildConfig.generator.emitApp,
+      'generator.emitApp'
+    ),
+    emitLayout: booleanValue(
+      generator.emitLayout,
+      defaultVisualBuildConfig.generator.emitLayout,
+      'generator.emitLayout'
+    ),
+    cleanStaleFiles: booleanValue(
+      generator.cleanStaleFiles,
+      defaultVisualBuildConfig.generator.cleanStaleFiles,
+      'generator.cleanStaleFiles'
+    ),
+  }
+}
+
+function validatePropSchema(value, location) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${location}.props must be an object`)
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([name, schema]) => {
+      if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
+        throw new Error(`${location}.props contains invalid prop name "${name}"`)
+      }
+
+      if (
+        !schema ||
+        typeof schema !== 'object' ||
+        !propTypes.has(schema.type)
+      ) {
+        throw new Error(`${location}.props.${name}.type is not supported`)
+      }
+
+      if (
+        schema.type === 'select' &&
+        (!Array.isArray(schema.options) ||
+          schema.options.some((option) => typeof option !== 'string'))
+      ) {
+        throw new Error(
+          `${location}.props.${name}.options must be a string array`
+        )
+      }
+
+      return [
+        name,
+        {
+          type: schema.type,
+          label: optionalString(schema.label, splitPascalCase(name)),
+          default: schema.default ?? defaultValueForType(schema.type),
+          ...(schema.options ? { options: schema.options } : {}),
+        },
+      ]
+    })
+  )
+}
+
+function normalizeImportPath(value, sourceDir) {
+  const normalized = normalizeProjectRelativePath(value, 'component importPath')
+
+  if (
+    !isPathInside(normalized, sourceDir) ||
+    !/\.[cm]?[jt]sx?$/.test(normalized)
+  ) {
+    throw new Error(
+      `Custom component importPath must reference a JavaScript or TypeScript file inside ${sourceDir}`
+    )
+  }
+
+  return normalized
+}
+
+function projectDirectory(value, fallback, location) {
+  const normalized = normalizeProjectRelativePath(
+    value === undefined ? fallback : requiredString(value, location),
+    location
+  )
+
+  if (/\.[A-Za-z0-9]+$/.test(normalized)) {
+    throw new Error(`${location} must reference a directory`)
+  }
+  return normalized
+}
+
+function projectFile(value, fallback, location, extensionPattern) {
+  const normalized = normalizeProjectRelativePath(
+    value === undefined ? fallback : requiredString(value, location),
+    location
+  )
+
+  if (!extensionPattern.test(normalized)) {
+    throw new Error(`${location} has an unsupported file extension`)
+  }
+  return normalized
+}
+
+function normalizeProjectRelativePath(value, location) {
+  const normalized = String(value)
+    .replace(/\\/g, '/')
+    .replace(/^\.\/+/, '')
+    .replace(/\/+/g, '/')
+
+  if (
+    !normalized ||
+    normalized.startsWith('/') ||
+    /^[A-Za-z]:/.test(normalized) ||
+    normalized.split('/').some((segment) => segment === '..')
+  ) {
+    throw new Error(`${location} must stay inside the project root`)
+  }
+  return normalized.replace(/\/$/, '')
+}
+
+function isPathInside(candidate, directory) {
+  return candidate === directory || candidate.startsWith(`${directory}/`)
+}
+
+function objectValue(value, location) {
+  if (value === undefined) return {}
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${location} must be an object`)
+  }
+  return value
+}
+
+function enumValue(value, allowed, fallback, location) {
+  if (value === undefined) return fallback
+  if (!allowed.has(value)) {
+    throw new Error(
+      `${location} must be one of: ${[...allowed].join(', ')}`
+    )
+  }
+  return value
+}
+
+function booleanValue(value, fallback, location) {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') {
+    throw new Error(`${location} must be a boolean`)
+  }
+  return value
+}
+
+function positiveWidth(value, fallback, location, allowFluid = false) {
+  if (value === undefined) return fallback
+  if (allowFluid && value === 'fluid') return value
+  if (
+    typeof value !== 'number' ||
+    !Number.isFinite(value) ||
+    value < 240 ||
+    value > 4096
+  ) {
+    throw new Error(
+      `${location} must be a number from 240 to 4096${
+        allowFluid ? ' or "fluid"' : ''
+      }`
+    )
+  }
+  return Math.round(value)
+}
+
+function requiredString(value, location) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${location} must be a non-empty string`)
+  }
+  return value.trim()
+}
+
+function optionalString(value, fallback) {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback
+}
+
+function optionalConfiguredString(value, location) {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${location} must be a non-empty string when provided`)
+  }
+  return value.trim()
+}
+
+function splitPascalCase(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+}
+
+function defaultValueForType(type) {
+  if (type === 'boolean') return false
+  if (type === 'number') return 0
+  if (type === 'array') return []
+  if (type === 'attributes') return {}
+  return ''
+}