blocks-dusted 0.1.6 → 0.1.9

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.9",
   "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,106 @@
+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_DIRECTORY = 'src/Header'
+
+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 activeHeaderExists = await fileExists(`${targetDirectory}/${ACTIVE_HEADER_DIRECTORY}`)
+  const activeHeaderBackupPath = activeHeaderExists
+    ? await plannedBackupPath({ destinationPath: ACTIVE_HEADER_DIRECTORY, targetDirectory })
+    : null
+
+  heading('Header workflow')
+  info(`Name: ${manifest.name}`)
+  info(`Target directory: ${targetDirectory}`)
+  info(`Payload config: ${project.payloadConfigPath}`)
+  info(`Source template path: ${templateDirectory}`)
+  info(`Active Header path: ${ACTIVE_HEADER_DIRECTORY}`)
+
+  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 backup')
+  if (activeHeaderBackupPath) item(dryRun ? `Would back up ${ACTIVE_HEADER_DIRECTORY} to ${activeHeaderBackupPath}` : `Will back up ${ACTIVE_HEADER_DIRECTORY} to ${activeHeaderBackupPath}`)
+  else item('No existing src/Header directory found; a new active Header will be installed.')
+
+  heading('Activation')
+  item('Install a complete active src/Header replacement wired to HeaderDD02.')
+  item('The previous Header folder is preserved as src/Header.bak, src/Header.bak.1, or the next available backup path.')
+
+  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 (activeHeaderExists) await backupExistingDestination({ destinationPath: ACTIVE_HEADER_DIRECTORY, targetDirectory })
+  const copiedFiles = await copyTemplateFiles({ manifest, templateDirectory, targetDirectory })
+
+  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 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/Component.client.tsx

@@ -0,0 +1,9 @@
+'use client'
+
+import type { Header as HeaderType } from '@/payload-types'
+
+import { HeaderNav } from './Nav'
+
+export const HeaderClient: React.FC<{ data: HeaderType }> = ({ data }) => {
+  return <HeaderNav data={data} />
+}

package/templates/components/HeaderDD02/Component.tsx

@@ -0,0 +1,10 @@
+import type { Header as HeaderType } from '@/payload-types'
+import { getCachedGlobal } from '@/utilities/getGlobals'
+
+import { HeaderClient } from './Component.client'
+
+export async function Header() {
+  const headerData = (await getCachedGlobal('header', 1)()) as HeaderType | null
+
+  return <HeaderClient data={headerData ?? ({} as HeaderType)} />
+}

package/templates/components/HeaderDD02/Header.config.ts

@@ -0,0 +1,33 @@
+import type { GlobalConfig } from 'payload'
+
+import { HeaderDD02 } from '@/Header/variants/HeaderDD02/config'
+
+import { revalidateHeader } from './hooks/revalidateHeader'
+
+export const Header: GlobalConfig = {
+  slug: 'header',
+  access: {
+    read: () => true,
+    update: () => true,
+  },
+  fields: [
+    {
+      name: 'variant',
+      label: 'Variant',
+      type: 'select',
+      defaultValue: 'header02',
+      options: [{ label: 'Header DD 02', value: 'header02' }],
+      admin: {
+        position: 'sidebar',
+      },
+    },
+    {
+      name: 'header02',
+      type: 'group',
+      fields: HeaderDD02,
+    },
+  ],
+  hooks: {
+    afterChange: [revalidateHeader],
+  },
+}

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/Nav/index.tsx

@@ -0,0 +1,9 @@
+'use client'
+
+import type { Header as HeaderType } from '@/payload-types'
+
+import HeaderDD02 from '@/Header/variants/HeaderDD02'
+
+export const HeaderNav: React.FC<{ data: HeaderType }> = ({ data }) => {
+  return <HeaderDD02 data={data} />
+}

package/templates/components/HeaderDD02/README.md

@@ -4,48 +4,55 @@ HeaderDD02 is the exported Header02 implementation from DesignsDustedv3.
 
 This header uses the shared `defaultLexical` editor standard from `@/fields/defaultLexical`. Project-specific Lexical blocks are intentionally not bundled. The nested `BlocksFeature` uses an empty `blocks` array so each target project can register only the blocks it requires.
 
+The header workflow backs up the active `src/Header` folder before installing a complete replacement Header shell wired directly to `HeaderDD02`.
+
 Included files:
 
-- `index.tsx` for the HeaderDD02 desktop runtime.
-- `MobileBottomNav/index.tsx` because Header02 imports it directly.
-- `config.ts` for the Header02 field structure adapted to `HeaderDD02` and `defaultLexical`.
-- `RowLabel.tsx` because the Header02 config references `/Header/RowLabel.tsx#RowLabel` for Payload admin array labels.
+- `Component.tsx` for the active server Header component.
+- `Component.client.tsx` for the active client Header wrapper.
+- `Nav/index.tsx` to render `HeaderDD02` directly.
+- `config.ts` for the active Payload Header global.
+- `hooks/revalidateHeader.ts` for Header global revalidation.
+- `RowLabel.tsx` for Payload admin array labels.
+- `variants/HeaderDD02/index.tsx` for the HeaderDD02 desktop runtime.
+- `variants/HeaderDD02/MobileBottomNav/index.tsx` because Header02 imports it directly.
+- `variants/HeaderDD02/config.ts` for the Header02 field structure adapted to `HeaderDD02` and `defaultLexical`.
 
 Not included:
 
 - Header01 and Header03 implementations.
-- The parent multi-variant Header shell.
 - Source project Lexical blocks: `AnimatedText`, `ButtonWithIcon`, `CounterBlock`, and `MediaBlock`.
 
-Before activating this header in an existing project, inspect the current Header global schema and stored Header data. The template installer copies files and backs up the `HeaderDD02` destination folder when it already exists, but it does not automatically replace the active Header global or inspect database content.
+Removed source Lexical block imports: `@/blocks/AnimatedText/config`, `@/blocks/ButtonWithIcon/config`, `@/blocks/CounterBlock/config`, `@/blocks/MediaBlock/config`.
+
+Before activating this header in an existing project, inspect the current Header global schema and stored Header data. The header workflow preserves the old active Header folder as `src/Header.bak`, `src/Header.bak.1`, or the next available backup path. It does not rewrite stored rich text data or run destructive migrations.
 
 ## AI handover prompt
 
 ```prompt
-Review the newly installed HeaderDD02 files and integrate them into this project
+Review the newly installed HeaderDD02 files in this project
 
 Do not assume the source project architecture matches this repository.
 
 Tasks:
 
-1. Inspect the current Header component, Payload Header global, frontend layout, fields, utilities, generated types and styling conventions.
-2. Resolve HeaderDD02 imports against the current project.
+1. Inspect the active Header component, Payload Header global, frontend layout, fields, utilities, generated types and styling conventions.
+2. Confirm `src/Header/Component.tsx`, `src/Header/Component.client.tsx`, `src/Header/Nav/index.tsx`, and `src/Header/config.ts` now point to HeaderDD02.
 3. Reuse existing project utilities and fields where appropriate.
-4. Adapt HeaderDD02 config to the current Header global without deleting or destructively renaming existing database-backed fields.
+4. Confirm the active Header global has not created a duplicate Header registration.
 5. Keep the shared defaultLexical standard.
 6. Keep BlocksFeature({ blocks: [] }).
-7. Integrate the component into the existing header render flow.
-8. Preserve the existing layout, providers, transitions and mobile behaviour.
-9. Add any required CSS variables or utility classes using the current project's styling system.
-10. Report every file modified and any manual content migration required.
+7. Preserve layout, providers, transitions and mobile behaviour that are intentionally kept by the target project.
+8. Add any required CSS variables or utility classes using the current project's styling system.
+9. Report every file modified and any manual content migration required.
 
 Do not modify database records automatically.
 Do not run destructive migrations.
-Do not remove the existing header until the replacement is verified.
+Do not delete the backup folder until the replacement is verified.
 ```
 
 ## Bundled shared UI primitives
 
 HeaderDD02 includes shared templates for `src/components/ui/navigation-menu.tsx`, `src/components/animate-ui/components/animate/tooltip.tsx`, `src/components/animate-ui/primitives/animate/tooltip.tsx`, `src/components/animate-ui/primitives/animate/slot.tsx`, and `src/lib/get-strict-context.tsx`. The installer copies them only when missing and preserves existing target files.
 
-If package dependencies are missing, run the install command printed by the CLI, for example `pnpm add @radix-ui/react-navigation-menu class-variance-authority motion @floating-ui/react`.
+If package dependencies are missing, run the install command printed by the CLI, for example `pnpm add @radix-ui/react-navigation-menu class-variance-authority motion @floating-ui/react`.

package/templates/components/HeaderDD02/hooks/revalidateHeader.ts

@@ -0,0 +1,11 @@
+import type { GlobalAfterChangeHook } from 'payload'
+import { revalidateTag } from 'next/cache'
+
+export const revalidateHeader: GlobalAfterChangeHook = ({ doc, req: { payload, context } }) => {
+  if (!context.disableRevalidate) {
+    payload.logger.info('Revalidating header')
+    revalidateTag('global_header')
+  }
+
+  return doc
+}

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 (
     <>

package/templates/components/HeaderDD02/manifest.json

@@ -17,15 +17,33 @@
       "@/blocks/CounterBlock/config",
       "@/blocks/MediaBlock/config"
     ],
-    "excludedHeaderFiles": [
-      "src/Header/Component.tsx",
-      "src/Header/Component.client.tsx",
-      "src/Header/config.ts",
-      "src/Header/Nav/index.tsx",
-      "src/Header/hooks/revalidateHeader.ts"
-    ]
+    "excludedHeaderFiles": []
   },
   "files": [
+    {
+      "from": "Component.tsx",
+      "to": "src/Header/Component.tsx"
+    },
+    {
+      "from": "Component.client.tsx",
+      "to": "src/Header/Component.client.tsx"
+    },
+    {
+      "from": "Header.config.ts",
+      "to": "src/Header/config.ts"
+    },
+    {
+      "from": "Nav/index.tsx",
+      "to": "src/Header/Nav/index.tsx"
+    },
+    {
+      "from": "hooks/revalidateHeader.ts",
+      "to": "src/Header/hooks/revalidateHeader.ts"
+    },
+    {
+      "from": "RowLabel.tsx",
+      "to": "src/Header/RowLabel.tsx"
+    },
     {
       "from": "index.tsx",
       "to": "src/Header/variants/HeaderDD02/index.tsx"
@@ -38,10 +56,6 @@
       "from": "config.ts",
       "to": "src/Header/variants/HeaderDD02/config.ts"
     },
-    {
-      "from": "RowLabel.tsx",
-      "to": "src/Header/RowLabel.tsx"
-    },
     {
       "from": "README.md",
       "to": "src/Header/variants/HeaderDD02/README.md"
@@ -90,6 +104,10 @@
     {
       "path": "src/utilities/ui.ts",
       "reason": "HeaderDD02 uses cn from @/utilities/ui."
+    },
+    {
+      "path": "src/utilities/getGlobals.ts",
+      "reason": "The active Header server component fetches the Payload header global through getCachedGlobal."
     }
   ],
   "collectionRegistration": {
@@ -101,8 +119,7 @@
   "manual": [
     "This header uses the shared `defaultLexical` editor standard from `@/fields/defaultLexical`. Project-specific Lexical blocks are intentionally not bundled. The nested `BlocksFeature` uses an empty `blocks` array so each target project can register only the blocks it requires.",
     "Removed source Lexical block imports: `@/blocks/AnimatedText/config`, `@/blocks/ButtonWithIcon/config`, `@/blocks/CounterBlock/config`, `@/blocks/MediaBlock/config`.",
-    "HeaderDD02 installs the Header02 runtime component, MobileBottomNav, Header02 field config, and the RowLabel admin helper only. Header01 and Header03 are not bundled.",
-    "This component template does not yet patch an existing active Header global, replace Header/Component.tsx, or inspect database-stored Header content automatically. Review the existing Header global before activation and back up active files before wiring the variant into the target project.",
+    "HeaderDD02 header workflow backs up the existing active src/Header folder, then installs a complete replacement Header shell wired directly to HeaderDD02. Header01 and Header03 are not bundled.",
     "Inspect any existing target Header richText data before replacing an active Header schema. Do not apply the empty nested blocks extension point to stored content that already depends on registered block node types.",
     "Verify the target `src/fields/defaultLexical.ts` exports a compatible `defaultLexical` helper that accepts `defaultLexical({ features: [] })` and does not inject unrelated project-specific blocks.",
     "Wire `HeaderDD02` into the target Header global or render it directly after confirming the target project will not render two headers.",
@@ -111,8 +128,7 @@
   "manualSteps": [
     "This header uses the shared `defaultLexical` editor standard from `@/fields/defaultLexical`. Project-specific Lexical blocks are intentionally not bundled. The nested `BlocksFeature` uses an empty `blocks` array so each target project can register only the blocks it requires.",
     "Removed source Lexical block imports: `@/blocks/AnimatedText/config`, `@/blocks/ButtonWithIcon/config`, `@/blocks/CounterBlock/config`, `@/blocks/MediaBlock/config`.",
-    "HeaderDD02 installs the Header02 runtime component, MobileBottomNav, Header02 field config, and the RowLabel admin helper only. Header01 and Header03 are not bundled.",
-    "This component template does not yet patch an existing active Header global, replace Header/Component.tsx, or inspect database-stored Header content automatically. Review the existing Header global before activation and back up active files before wiring the variant into the target project.",
+    "HeaderDD02 header workflow backs up the existing active src/Header folder, then installs a complete replacement Header shell wired directly to HeaderDD02. Header01 and Header03 are not bundled.",
     "Inspect any existing target Header richText data before replacing an active Header schema. Do not apply the empty nested blocks extension point to stored content that already depends on registered block node types.",
     "Verify the target `src/fields/defaultLexical.ts` exports a compatible `defaultLexical` helper that accepts `defaultLexical({ features: [] })` and does not inject unrelated project-specific blocks.",
     "Wire `HeaderDD02` into the target Header global or render it directly after confirming the target project will not render two headers.",
@@ -121,7 +137,7 @@
   "notes": [
     "Converted from DesignsDustedv3 Header02 after tracing Header/variants/Header02/index.tsx and its direct imports.",
     "Header02 styling is inline Tailwind class usage plus style jsx global blocks in index.tsx and MobileBottomNav/index.tsx; no separate Header02 stylesheet was imported.",
-    "Parent Header files were audited but excluded because the reusable export targets Header02 only, not the multi-variant app header shell.",
+    "The header workflow now installs active Component.tsx, Component.client.tsx, config.ts, Nav, RowLabel, and revalidateHeader files so the installed header is wired into the project immediately.",
     "NavigationMenu and animate-ui tooltip primitives are bundled as shared files because HeaderDD02 imports them directly."
   ],
   "backupExistingDestination": true,