blocks-dusted 0.1.6 → 0.1.8

package/README.md

@@ -356,6 +356,8 @@ pnpm dlx blocks-dusted doctor
 pnpm dlx blocks-dusted add DD-Hero --dry-run
 pnpm dlx blocks-dusted add DD-Hero
 pnpm dlx blocks-dusted add RichText
+pnpm dlx blocks-dusted header add HeaderDD02 --dry-run
+pnpm dlx blocks-dusted header add HeaderDD02
 ```
 
 Use `blocks-dusted list` first to see the exact available block names in the package. `DD-Hero` is an existing block in the current manifest registry.
@@ -378,6 +380,8 @@ blocks-dusted add DD-Hero --dry-run
 blocks-dusted add DD-Hero --no-register
 blocks-dusted add DD-Hero --cwd C:\Projects\my-payload-site
 blocks-dusted add RichText --cwd C:\Projects\my-payload-site
+blocks-dusted header add HeaderDD02 --dry-run
+blocks-dusted header add HeaderDD02
 ```
 
 `--cwd` targets a Payload project directory without changing your shell directory. Relative `--cwd` values resolve from the directory where you launched the command.
@@ -403,6 +407,17 @@ pnpm payload generate:importmap
 
 The CLI does not run migrations or build the target project.
 
+### Header workflows
+
+Headers are active Payload globals and layout wiring, not ordinary page blocks. Use the dedicated header workflow when you want to activate a reusable header implementation.
+
+```bash
+pnpm dlx blocks-dusted header add HeaderDD02 --dry-run
+pnpm dlx blocks-dusted header add HeaderDD02
+```
+
+The HeaderDD02 workflow backs up the active Header config, Nav renderer, and RowLabel before patching them. It installs the HeaderDD02 variant files, copies missing shared UI primitives, patches `src/Header/Nav/index.tsx` to render HeaderDD02, and patches `src/Header/config.ts` to expose HeaderDD02 fields while retaining legacy starter `navItems` as hidden data. Run Payload type and import-map generation after reviewing the changes.
+
 ## Payload Block Standard
 
 ### Purpose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blocks-dusted",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Manifest-driven CLI for installing reusable Payload CMS blocks.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { addTemplate } from './commands/add.js'
 import { doctor } from './commands/doctor.js'
+import { addHeader } from './commands/header.js'
 import { list } from './commands/list.js'
 import { error, info } from './utils/logger.js'
 import { packageRoot } from './utils/paths.js'
@@ -12,7 +13,8 @@ function printHelp() {
   info('Usage:')
   info('  blocks-dusted list')
   info('  blocks-dusted doctor [--cwd <path>]')
-  info('  blocks-dusted add <BlockName> [--dry-run] [--no-register] [--cwd <path>]')
+  info('  blocks-dusted add <TemplateName> [--dry-run] [--no-register] [--cwd <path>]')
+  info('  blocks-dusted header add <HeaderName> [--dry-run] [--cwd <path>]')
   info('  blocks-dusted --version')
 }
 
@@ -34,6 +36,17 @@ export async function runCli(args, options = {}) {
 
   if (command === 'list') return list()
   if (command === 'doctor') return doctor({ targetDirectory })
+  if (command === 'header') {
+    const [subcommand, ...headerRest] = rest
+    if (subcommand !== 'add') throw new Error('Usage: blocks-dusted header add <HeaderName> [--dry-run]')
+    const headerName = headerRest.find((argument) => !argument.startsWith('-'))
+    return addHeader({
+      headerName,
+      targetDirectory,
+      dryRun: headerRest.includes('--dry-run'),
+    })
+  }
+
   if (command === 'add') {
     const templateName = rest.find((argument) => !argument.startsWith('-'))
     return addTemplate({

package/src/commands/header.js

@@ -0,0 +1,145 @@
+import { writeFile } from 'node:fs/promises'
+import { copySharedFiles, copyTemplateFiles, backupExistingDestination, plannedBackupPath } from '../installers/copyTemplateFiles.js'
+import { checkDependencies } from '../installers/installDependencies.js'
+import { checkRequirements } from '../installers/checkRequirements.js'
+import { loadTemplateManifest } from '../registry/loadTemplateManifest.js'
+import { validateTemplateManifest } from '../registry/validateTemplateManifest.js'
+import { heading, info, item, status } from '../utils/logger.js'
+import { packageRoot } from '../utils/paths.js'
+import { fileExists, validateTargetProject } from '../utils/project.js'
+
+const SUPPORTED_HEADERS = new Set(['HeaderDD02'])
+const ACTIVE_HEADER_FILES = [
+  'src/Header/config.ts',
+  'src/Header/Nav/index.tsx',
+  'src/Header/RowLabel.tsx',
+]
+
+export async function addHeader({ headerName, targetDirectory = process.cwd(), dryRun = false }) {
+  if (!headerName) throw new Error('A header name is required. Example: blocks-dusted header add HeaderDD02 --dry-run')
+  if (!SUPPORTED_HEADERS.has(headerName)) throw new Error(`Unsupported header workflow: ${headerName}`)
+
+  const { manifest, templateDirectory } = await loadTemplateManifest(headerName)
+  validateTemplateManifest(manifest)
+  if (manifest.type !== 'component') throw new Error(`${headerName} must be a component template.`)
+
+  const checks = await checkRequirements({ manifest, targetDirectory })
+  const dependencyChecks = await checkDependencies({ manifest, targetDirectory })
+  const project = await validateTargetProject(targetDirectory)
+  const missingRequired = checks.missingRequirements ?? []
+  if (missingRequired.length > 0) {
+    throw new Error(`Required project files are missing:\n${missingRequired.map(formatMissingRequirement).join('\n')}`)
+  }
+
+  const activeFileChecks = await Promise.all(
+    ACTIVE_HEADER_FILES.map(async (path) => ({ path, exists: await fileExists(`${targetDirectory}/${path}`) })),
+  )
+  const missingActive = activeFileChecks.filter((check) => !check.exists)
+  if (missingActive.length > 0) {
+    throw new Error(`Active Header files are missing:\n${missingActive.map((check) => `- ${check.path}`).join('\n')}`)
+  }
+
+  const destinationBackupPath = checks.collisions.destinationExists
+    ? await plannedBackupPath({ destinationPath: checks.collisions.destinationPath, targetDirectory })
+    : null
+  const activeBackups = await Promise.all(
+    ACTIVE_HEADER_FILES.map(async (path) => ({
+      path,
+      backupPath: await plannedBackupPath({ destinationPath: path, targetDirectory }),
+    })),
+  )
+
+  heading('Header workflow')
+  info(`Name: ${manifest.name}`)
+  info(`Target directory: ${targetDirectory}`)
+  info(`Payload config: ${project.payloadConfigPath}`)
+  info(`Source template path: ${templateDirectory}`)
+  info(`Target install path: ${checks.collisions.destinationPath}`)
+
+  heading(dryRun ? 'Files that would be installed' : 'Files to install')
+  for (const file of manifest.files) item(`${file.from} -> ${file.to}`)
+
+  heading('Required project files')
+  for (const check of checks.requiredFiles) status(check.exists, check.path, check.reason)
+
+  heading('Shared files')
+  if ((manifest.sharedFiles ?? []).length === 0) item('None')
+  for (const file of manifest.sharedFiles ?? []) item(`${file.from} -> ${file.to}`)
+
+  heading('Package dependencies')
+  for (const dependency of dependencyChecks.declared) {
+    const isMissing = dependencyChecks.missing.some((missing) => missing.name === dependency.name)
+    status(!isMissing, formatDependency(dependency), isMissing ? 'missing' : 'already listed')
+  }
+  if (dependencyChecks.missing.length > 0) item(`Install command: ${installCommandText(dependencyChecks.packageManager, dependencyChecks.missing)}`)
+
+  heading('Active Header backups')
+  for (const backup of activeBackups) {
+    item(dryRun ? `Would back up ${backup.path} to ${backup.backupPath}` : `Will back up ${backup.path} to ${backup.backupPath}`)
+  }
+  if (destinationBackupPath) {
+    item(dryRun ? `Would back up ${checks.collisions.destinationPath} to ${destinationBackupPath}` : `Will back up ${checks.collisions.destinationPath} to ${destinationBackupPath}`)
+  }
+
+  heading('Activation patches')
+  item('Patch src/Header/Nav/index.tsx to render HeaderDD02')
+  item('Patch src/Header/config.ts to expose HeaderDD02 fields and preserve legacy navItems as hidden data')
+
+  if (dryRun) {
+    const sharedResults = await copySharedFiles({ manifest, packageRoot, targetDirectory, dryRun: true })
+    heading('Dry-run shared file results')
+    if (sharedResults.length === 0) item('None')
+    sharedResults.forEach((result) => item(`${result.status}: ${result.to}${result.reason ? ` - ${result.reason}` : ''}`))
+    info('Dry run complete: no files were changed.')
+    return
+  }
+
+  const sharedResults = await copySharedFiles({ manifest, packageRoot, targetDirectory })
+
+  if (checks.collisions.destinationExists) {
+    await backupExistingDestination({ destinationPath: checks.collisions.destinationPath, targetDirectory })
+  }
+  for (const file of ACTIVE_HEADER_FILES) {
+    await backupExistingDestination({ destinationPath: file, targetDirectory })
+  }
+
+  const copiedFiles = await copyTemplateFiles({ manifest, templateDirectory, targetDirectory })
+  await writeFile(`${targetDirectory}/src/Header/Nav/index.tsx`, renderHeaderNav())
+  await writeFile(`${targetDirectory}/src/Header/config.ts`, renderHeaderConfig())
+
+  heading('Copied files')
+  copiedFiles.forEach((file) => item(file))
+  heading('Shared file results')
+  if (sharedResults.length === 0) item('None')
+  sharedResults.forEach((result) => item(`${result.status}: ${result.to}${result.reason ? ` - ${result.reason}` : ''}`))
+  heading('Dependency install')
+  item('Skipped: dependency installation is manual')
+  if (dependencyChecks.missing.length > 0) item(`Run manually: ${installCommandText(dependencyChecks.packageManager, dependencyChecks.missing)}`)
+  heading('Payload commands to run manually')
+  const payloadCommand = dependencyChecks.packageManager === 'npm' ? 'npx payload' : `${dependencyChecks.packageManager} payload`
+  item(`${payloadCommand} generate:types`)
+  item(`${payloadCommand} generate:importmap`)
+  info('Header workflow complete.')
+}
+
+function renderHeaderNav() {
+  return `import React from 'react'\n\nimport type { Header as HeaderType } from '@/payload-types'\n\nimport HeaderDD02 from '@/Header/variants/HeaderDD02'\n\nexport const HeaderNav: React.FC<{ data: HeaderType }> = ({ data }) => {\n  return <HeaderDD02 data={data} />\n}\n`
+}
+
+function renderHeaderConfig() {
+  return `import type { GlobalConfig } from 'payload'\n\nimport { iconPicker } from '@/fields/lucide-icon-picker/field'\nimport { link } from '@/fields/link'\nimport { HeaderDD02 } from '@/Header/variants/HeaderDD02/config'\nimport { revalidateHeader } from './hooks/revalidateHeader'\n\nexport const Header: GlobalConfig = {\n  slug: 'header',\n  access: {\n    read: () => true,\n    update: () => true,\n  },\n  fields: [\n    {\n      name: 'variant',\n      label: 'Variant',\n      type: 'select',\n      defaultValue: 'header02',\n      options: [{ label: 'Header DD 02', value: 'header02' }],\n      admin: {\n        position: 'sidebar',\n      },\n    },\n    {\n      name: 'header02',\n      type: 'group',\n      fields: HeaderDD02,\n    },\n    {\n      name: 'navItems',\n      type: 'array',\n      admin: {\n        hidden: true,\n        description: 'Legacy starter Header navItems retained so existing stored header data is not discarded.',\n      },\n      fields: [\n        link({ appearances: false }),\n        iconPicker({\n          name: 'icon',\n          required: false,\n          description: 'Legacy optional icon to display with the navigation item',\n        }),\n      ],\n    },\n  ],\n  hooks: {\n    afterChange: [revalidateHeader],\n  },\n}\n`
+}
+
+function formatMissingRequirement(check) {
+  const resolution = check.resolution ? `\n  Resolve: ${check.resolution}` : ''
+  return `- ${check.path}: ${check.reason}${resolution}`
+}
+
+function formatDependency(dependency) {
+  return `${dependency.name}${dependency.version ? `@${dependency.version}` : ''}`
+}
+
+function installCommandText(packageManager, dependencies) {
+  const command = packageManager === 'yarn' ? ['yarn', 'add'] : packageManager === 'bun' ? ['bun', 'add'] : packageManager === 'npm' ? ['npm', 'install'] : ['pnpm', 'add']
+  return [...command, ...dependencies.map(formatDependency)].join(' ')
+}

package/templates/components/HeaderDD02/MobileBottomNav/index.tsx

@@ -133,7 +133,7 @@ export default function MobileBottomNav({ data }: MobileBottomNavProps) {
   const pathname = usePathname()
   const normalizedCurrentPathname = useMemo(() => normalizePath(pathname), [pathname])
 
-  const navItems = data?.header02?.navItems || []
+  const navItems = data?.header02?.navItems || (data as any)?.navItems || []
   const showLabels = data?.header02?.showMobileLabels ?? true
 
   useEffect(() => {

package/templates/components/HeaderDD02/index.tsx

@@ -251,7 +251,7 @@ export default function HeaderDD02({ data, variant = 'default', sticky = true }:
   }, [enableHideOnScroll, scrollThreshold])
 
   // Extract navItems from header02 data
-  const navItems = data?.header02?.navItems || []
+  const navItems = data?.header02?.navItems || (data as any)?.navItems || []
 
   return (
     <>