@edgedev/create-edge-app 1.2.33 → 1.2.35

package/edge/components/cms/blockEditor.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { HelpCircle, Maximize2, Monitor, Smartphone, Tablet } from 'lucide-vue-next'
+import { Download, HelpCircle, Maximize2, Monitor, Smartphone, Tablet } from 'lucide-vue-next'
 import { toTypedSchema } from '@vee-validate/zod'
 import * as z from 'zod'
 const props = defineProps({
@@ -12,20 +12,12 @@ const props = defineProps({
 const emit = defineEmits(['head'])
 
 const edgeFirebase = inject('edgeFirebase')
-
-const route = useRoute()
+const { blocks: blockNewDocSchema } = useCmsNewDocs()
 
 const state = reactive({
   filter: '',
   newDocs: {
-    blocks: {
-      name: { value: '' },
-      content: { value: '' },
-      tags: { value: [] },
-      themes: { value: [] },
-      synced: { value: false },
-      version: 1,
-    },
+    blocks: blockNewDocSchema.value,
   },
   mounted: false,
   workingDoc: {},
@@ -40,6 +32,8 @@ const state = reactive({
   seedingInitialBlocks: false,
   previewViewport: 'full',
   previewBlock: null,
+  editorWorkingDoc: null,
+  themeDefaultAppliedForBlockId: '',
 })
 
 const blockSchema = toTypedSchema(z.object({
@@ -54,6 +48,14 @@ const previewViewportOptions = [
   { id: 'medium', label: 'Medium', width: '992px', icon: Tablet },
   { id: 'mobile', label: 'Mobile', width: '420px', icon: Smartphone },
 ]
+const previewTypeOptions = [
+  { name: 'light', title: 'Light Preview' },
+  { name: 'dark', title: 'Dark Preview' },
+]
+
+const normalizePreviewType = (value) => {
+  return value === 'dark' ? 'dark' : 'light'
+}
 
 const selectedPreviewViewport = computed(() => previewViewportOptions.find(option => option.id === state.previewViewport) || previewViewportOptions[0])
 
@@ -79,6 +81,19 @@ const previewViewportMode = computed(() => {
   return state.previewViewport
 })
 
+const previewSurfaceClass = computed(() => {
+  const previewType = normalizePreviewType(state.previewBlock?.previewType)
+  return previewType === 'light'
+    ? 'bg-white text-black'
+    : 'bg-neutral-950 text-neutral-50'
+})
+
+const previewCanvasClass = computed(() => {
+  const content = String(state.previewBlock?.content || '')
+  const hasFixedContent = /\bfixed\b/.test(content)
+  return hasFixedContent ? 'min-h-[calc(100vh-360px)]' : 'min-h-[88px]'
+})
+
 onMounted(() => {
   // state.mounted = true
 })
@@ -92,7 +107,7 @@ const PLACEHOLDERS = {
     'Consectetur adipiscing elit.',
     'Sed do eiusmod tempor incididunt.',
   ],
-  image: '/images/filler.png',
+  image: 'https://imagedelivery.net/h7EjKG0X9kOxmLp41mxOng/f1f7f610-dfa9-4011-08a3-7a98d95e7500/thumbnail',
 }
 
 const contentEditorRef = ref(null)
@@ -105,6 +120,11 @@ const BLOCK_CONTENT_SNIPPETS = [
     snippet: '{{{#text {"field": "fieldName", "value": "" }}}}',
     description: 'Simple text field placeholder',
   },
+  {
+    label: 'Text with Options',
+    snippet: '{{{#text {"field":"fieldName","title":"Field Label","option":{"field":"fieldName","options":[{"title":"Option 1","name":"option1"},{"title":"Option 2","name":"option2"}],"optionsKey":"title","optionsValue":"name"},"value":"option1"}}}}',
+    description: 'Text field with selectable options',
+  },
   {
     label: 'Text Area',
     snippet: '{{{#textarea {"field": "fieldName", "value": "" }}}}',
@@ -172,6 +192,14 @@ function insertBlockContentSnippet(snippet) {
   editor.insertSnippet(snippet)
 }
 
+const updateWorkingPreviewType = (nextValue) => {
+  const normalized = normalizePreviewType(nextValue)
+  if (state.editorWorkingDoc)
+    state.editorWorkingDoc.previewType = normalized
+  if (state.previewBlock)
+    state.previewBlock.previewType = normalized
+}
+
 function normalizeConfigLiteral(str) {
   // ensure keys are quoted: { title: "x", field: "y" } -> { "title": "x", "field": "y" }
   return str
@@ -451,6 +479,7 @@ const buildPreviewBlock = (workingDoc, parsed) => {
     id: state.previewBlock?.id || 'preview',
     blockId: props.blockId,
     name: workingDoc?.name || state.previewBlock?.name || '',
+    previewType: normalizePreviewType(workingDoc?.previewType),
     content,
     values: nextValues,
     meta: nextMeta,
@@ -459,15 +488,32 @@ const buildPreviewBlock = (workingDoc, parsed) => {
 }
 
 const theme = computed(() => {
-  const theme = edgeGlobal.edgeState.blockEditorTheme || ''
-  let themeContents = null
-  if (theme) {
-    themeContents = edgeFirebase.data?.[`${edgeGlobal.edgeState.organizationDocPath}/themes`]?.[theme]?.theme || null
+  const selectedThemeId = String(edgeGlobal.edgeState.blockEditorTheme || '').trim()
+  if (!selectedThemeId)
+    return null
+  const themeDoc = edgeFirebase.data?.[`${edgeGlobal.edgeState.organizationDocPath}/themes`]?.[selectedThemeId] || null
+  const themeContents = themeDoc?.theme || null
+  if (!themeContents)
+    return null
+  const extraCSS = typeof themeDoc?.extraCSS === 'string' ? themeDoc.extraCSS : ''
+  if (typeof themeContents === 'object' && !Array.isArray(themeContents))
+    return { ...themeContents, extraCSS }
+  try {
+    const parsedTheme = JSON.parse(themeContents)
+    if (!parsedTheme || typeof parsedTheme !== 'object' || Array.isArray(parsedTheme))
+      return null
+    return { ...parsedTheme, extraCSS }
   }
-  if (themeContents) {
-    return JSON.parse(themeContents)
+  catch {
+    return null
   }
-  return null
+})
+
+const previewThemeRenderKey = computed(() => {
+  const themeId = String(edgeGlobal.edgeState.blockEditorTheme || 'no-theme')
+  const siteId = String(edgeGlobal.edgeState.blockEditorSite || 'no-site')
+  const previewType = normalizePreviewType(state.previewBlock?.previewType)
+  return `${themeId}:${siteId}:${state.previewViewport}:${previewType}`
 })
 
 const headObject = computed(() => {
@@ -485,6 +531,7 @@ watch(headObject, (newHeadElements) => {
 }, { immediate: true, deep: true })
 
 const editorDocUpdates = (workingDoc) => {
+  state.editorWorkingDoc = workingDoc || null
   const parsed = blockModel(workingDoc.content)
   state.workingDoc = parsed
   state.previewBlock = buildPreviewBlock(workingDoc, parsed)
@@ -510,11 +557,51 @@ const themes = computed(() => {
   return Object.values(edgeFirebase.data?.[`${edgeGlobal.edgeState.organizationDocPath}/themes`] || {})
 })
 
-watch (themes, async (newThemes) => {
-  state.loading = true
-  if (!edgeGlobal.edgeState.blockEditorTheme && newThemes.length > 0) {
-    edgeGlobal.edgeState.blockEditorTheme = newThemes[0].docId
+const availableThemeIds = computed(() => {
+  return themes.value
+    .map(themeDoc => String(themeDoc?.docId || '').trim())
+    .filter(Boolean)
+})
+
+const currentBlockAllowedThemeIds = computed(() => {
+  const currentBlockDoc = edgeFirebase.data?.[`${edgeGlobal.edgeState.organizationDocPath}/blocks`]?.[props.blockId]
+  if (!Array.isArray(currentBlockDoc?.themes))
+    return []
+  return currentBlockDoc.themes.map(themeId => String(themeId || '').trim()).filter(Boolean)
+})
+
+const preferredThemeDefaultForBlock = computed(() => {
+  const firstAllowedAvailable = currentBlockAllowedThemeIds.value.find(themeId => availableThemeIds.value.includes(themeId))
+  if (firstAllowedAvailable)
+    return firstAllowedAvailable
+  return availableThemeIds.value[0] || ''
+})
+
+const applyThemeDefaultForBlock = () => {
+  const blockId = String(props.blockId || '').trim()
+  if (!blockId)
+    return
+  if (state.themeDefaultAppliedForBlockId === blockId)
+    return
+
+  const preferredThemeId = preferredThemeDefaultForBlock.value
+  if (!preferredThemeId) {
+    if (!availableThemeIds.value.length)
+      edgeGlobal.edgeState.blockEditorTheme = ''
+    return
   }
+
+  edgeGlobal.edgeState.blockEditorTheme = preferredThemeId
+  state.themeDefaultAppliedForBlockId = blockId
+}
+
+watch(() => props.blockId, () => {
+  state.themeDefaultAppliedForBlockId = ''
+}, { immediate: true })
+
+watch([availableThemeIds, currentBlockAllowedThemeIds, () => props.blockId], async () => {
+  state.loading = true
+  applyThemeDefaultForBlock()
   await nextTick()
   state.loading = false
 }, { immediate: true, deep: true })
@@ -567,6 +654,59 @@ const getTagsFromBlocks = computed(() => {
   // Always prepend it
   return [{ name: 'Quick Picks', title: 'Quick Picks' }, ...filtered]
 })
+
+const downloadJsonFile = (payload, filename) => {
+  if (typeof window === 'undefined')
+    return
+  const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' })
+  const objectUrl = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = objectUrl
+  anchor.download = filename
+  document.body.appendChild(anchor)
+  anchor.click()
+  anchor.remove()
+  URL.revokeObjectURL(objectUrl)
+}
+
+const isPlainObject = value => !!value && typeof value === 'object' && !Array.isArray(value)
+
+const cloneSchemaValue = (value) => {
+  if (isPlainObject(value) || Array.isArray(value))
+    return edgeGlobal.dupObject(value)
+  return value
+}
+
+const getDocDefaultsFromSchema = (schema = {}) => {
+  const defaults = {}
+  for (const [key, schemaEntry] of Object.entries(schema || {})) {
+    const hasValueProp = isPlainObject(schemaEntry) && Object.prototype.hasOwnProperty.call(schemaEntry, 'value')
+    const baseValue = hasValueProp ? schemaEntry.value : schemaEntry
+    defaults[key] = cloneSchemaValue(baseValue)
+  }
+  return defaults
+}
+
+const getBlockDocDefaults = () => getDocDefaultsFromSchema(blockNewDocSchema.value || {})
+
+const notifySuccess = (message) => {
+  edgeFirebase?.toast?.success?.(message)
+}
+
+const notifyError = (message) => {
+  edgeFirebase?.toast?.error?.(message)
+}
+
+const exportCurrentBlock = () => {
+  const doc = blocks.value?.[props.blockId]
+  if (!doc || !doc.docId) {
+    notifyError('Save this block before exporting.')
+    return
+  }
+  const exportPayload = { ...getBlockDocDefaults(), ...doc }
+  downloadJsonFile(exportPayload, `block-${doc.docId}.json`)
+  notifySuccess(`Exported block "${doc.docId}".`)
+}
 </script>
 
 <template>
@@ -578,7 +718,9 @@ const getTagsFromBlocks = computed(() => {
       :doc-id="props.blockId"
       :schema="blockSchema"
       :new-doc-schema="state.newDocs.blocks"
-      class="w-full mx-auto flex-1 bg-transparent flex flex-col border-none shadow-none"
+      header-class="py-2 bg-secondary text-foreground rounded-none sticky top-0 border"
+      class="w-full mx-auto flex-1 bg-transparent flex flex-col border-none shadow-none pt-0 px-0"
+      card-content-class="px-0"
       :show-footer="false"
       :no-close-after-save="true"
       :working-doc-overrides="state.workingDoc"
@@ -589,29 +731,52 @@ const getTagsFromBlocks = computed(() => {
         {{ slotProps.title }}
       </template>
       <template #header-center>
-        <div class="w-full flex gap-1 px-4">
-          <div class="w-1/2">
+        <div class="w-full flex gap-2 px-4 items-center">
+          <div class="flex-1">
             <edge-shad-select
               v-if="!state.loading"
               v-model="edgeGlobal.edgeState.blockEditorTheme"
-              label="Theme Viewer Select"
               name="theme"
               :items="themes.map(t => ({ title: t.name, name: t.docId }))"
               placeholder="Theme Viewer Select"
               class="w-full"
             />
           </div>
-          <div class="w-1/2">
+          <div class="flex-1">
             <edge-shad-select
               v-if="!state.loading"
               v-model="edgeGlobal.edgeState.blockEditorSite"
-              label="Site"
               name="site"
               :items="sites.map(s => ({ title: s.name, name: s.docId }))"
               placeholder="Select Site"
               class="w-full"
             />
           </div>
+          <div class="flex-1">
+            <edge-shad-select
+              v-if="!state.loading"
+              :model-value="state.editorWorkingDoc?.previewType || 'light'"
+              name="previewType"
+              :items="previewTypeOptions"
+              placeholder="Preview Surface"
+              class="w-full"
+              @update:model-value="updateWorkingPreviewType($event)"
+            />
+          </div>
+          <div class="flex items-center gap-2">
+            <edge-shad-button
+              type="button"
+              size="icon"
+              variant="outline"
+              class="h-9 w-9"
+              :disabled="props.blockId === 'new' || !blocks?.[props.blockId]"
+              title="Export Block"
+              aria-label="Export Block"
+              @click="exportCurrentBlock"
+            >
+              <Download class="h-4 w-4" />
+            </edge-shad-button>
+          </div>
         </div>
       </template>
       <template #main="slotProps">
@@ -659,55 +824,53 @@ const getTagsFromBlocks = computed(() => {
           </div>
           <div class="flex gap-4">
             <div class="w-1/2">
-              <div class="flex gap-2">
-                <div class="w-2/12 mb-3 rounded-md border border-slate-200 bg-white/80 p-3 shadow-sm shadow-slate-200/60 dark:border-slate-800 dark:bg-slate-900/60">
-                  <div class="flex flex-col gap-2">
-                    <edge-shad-button
-                      type="button"
-                      size="sm"
-                      variant="secondary"
-                      class="w-full h-8 px-2 text-[11px] uppercase tracking-wide gap-2"
-                      @click="state.helpOpen = true"
-                    >
-                      <HelpCircle class="w-4 h-4" />
-                      Block Help
-                    </edge-shad-button>
-                    <div class="text-xs font-semibold uppercase tracking-wide text-slate-600 dark:text-slate-300 whitespace-nowrap">
-                      Dynamic Content
-                    </div>
-                  </div>
-                  <div class="mt-2 flex flex-wrap gap-2">
-                    <edge-tooltip
-                      v-for="snippet in BLOCK_CONTENT_SNIPPETS"
-                      :key="snippet.label"
-                    >
+              <edge-cms-code-editor
+                ref="contentEditorRef"
+                v-model="slotProps.workingDoc.content"
+                title="Block Content"
+                language="handlebars"
+                name="content"
+                :enable-formatting="false"
+                height="calc(100vh - 300px)"
+                class="mb-4 flex-1"
+                @line-click="payload => handleEditorLineClick(payload, slotProps.workingDoc)"
+              >
+                <template #end-actions>
+                  <DropdownMenu>
+                    <DropdownMenuTrigger as-child>
                       <edge-shad-button
+                        type="button"
                         size="sm"
                         variant="outline"
-                        class="text-xs w-full"
-                        @click="insertBlockContentSnippet(snippet.snippet)"
+                        class="h-8 px-2 text-[11px] uppercase tracking-wide"
                       >
-                        {{ snippet.label }}
+                        Dynamic Content
                       </edge-shad-button>
-                      <template #content>
-                        <pre class="max-w-[320px] whitespace-pre-wrap break-words text-left text-xs font-mono leading-tight">{{ snippet.snippet }}</pre>
-                      </template>
-                    </edge-tooltip>
-                  </div>
-                </div>
-                <div class="w-10/12">
-                  <edge-cms-code-editor
-                    ref="contentEditorRef"
-                    v-model="slotProps.workingDoc.content"
-                    title="Block Content"
-                    language="html"
-                    name="content"
-                    height="calc(100vh - 300px)"
-                    class="mb-4 flex-1"
-                    @line-click="payload => handleEditorLineClick(payload, slotProps.workingDoc)"
-                  />
-                </div>
-              </div>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent align="end" class="w-72">
+                      <DropdownMenuItem
+                        v-for="snippet in BLOCK_CONTENT_SNIPPETS"
+                        :key="snippet.label"
+                        class="cursor-pointer flex-col items-start gap-0.5"
+                        @click="insertBlockContentSnippet(snippet.snippet)"
+                      >
+                        <span class="text-sm font-medium">{{ snippet.label }}</span>
+                        <span class="text-xs text-muted-foreground whitespace-normal">{{ snippet.description }}</span>
+                      </DropdownMenuItem>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                  <edge-shad-button
+                    type="button"
+                    size="sm"
+                    variant="secondary"
+                    class="h-8 px-2 text-[11px] uppercase tracking-wide gap-2"
+                    @click="state.helpOpen = true"
+                  >
+                    <HelpCircle class="w-4 h-4" />
+                    Block Help
+                  </edge-shad-button>
+                </template>
+              </edge-cms-code-editor>
             </div>
             <div class="w-1/2 space-y-2">
               <div class="flex items-center justify-between">
@@ -728,19 +891,25 @@ const getTagsFromBlocks = computed(() => {
                 </div>
               </div>
               <div
-                class="w-full mx-auto bg-card border border-border rounded-lg shadow-sm md:shadow-md"
+                class="w-full mx-auto rounded-none overflow-visible"
                 :style="previewViewportStyle"
               >
-                <edge-cms-block
-                  v-if="state.previewBlock"
-                  v-model="state.previewBlock"
-                  :site-id="edgeGlobal.edgeState.blockEditorSite"
-                  :theme="theme"
-                  :edit-mode="true"
-                  :viewport-mode="previewViewportMode"
-                  :block-id="state.previewBlock.id"
-                  @delete="ignorePreviewDelete"
-                />
+                <div class="relative overflow-visible rounded-none" :class="[previewSurfaceClass, previewCanvasClass]" style="transform: translateZ(0);">
+                  <edge-cms-block
+                    v-if="state.previewBlock"
+                    :key="previewThemeRenderKey"
+                    v-model="state.previewBlock"
+                    :site-id="edgeGlobal.edgeState.blockEditorSite"
+                    :theme="theme"
+                    :edit-mode="true"
+                    :contain-fixed="true"
+                    :disable-interactive-preview-in-edit="false"
+                    :allow-delete="false"
+                    :viewport-mode="previewViewportMode"
+                    :block-id="state.previewBlock.id"
+                    @delete="ignorePreviewDelete"
+                  />
+                </div>
               </div>
             </div>
           </div>
@@ -759,13 +928,19 @@ const getTagsFromBlocks = computed(() => {
         </SheetHeader>
         <div class="px-6 pb-6">
           <Tabs class="w-full" default-value="guide">
-            <TabsList class="w-full mt-3 bg-secondary rounded-sm grid grid-cols-3">
+            <TabsList class="w-full mt-3 bg-secondary rounded-sm grid grid-cols-5">
               <TabsTrigger value="guide" class="w-full text-black data-[state=active]:bg-black data-[state=active]:text-white">
                 Block Guide
               </TabsTrigger>
               <TabsTrigger value="carousel" class="w-full text-black data-[state=active]:bg-black data-[state=active]:text-white">
                 Carousel Usage
               </TabsTrigger>
+              <TabsTrigger value="form-helpers" class="w-full text-black data-[state=active]:bg-black data-[state=active]:text-white">
+                Form Helpers
+              </TabsTrigger>
+              <TabsTrigger value="nav-bar" class="w-full text-black data-[state=active]:bg-black data-[state=active]:text-white">
+                Nav Bar
+              </TabsTrigger>
               <TabsTrigger value="scroll-reveals" class="w-full text-black data-[state=active]:bg-black data-[state=active]:text-white">
                 Scroll Reveals
               </TabsTrigger>
@@ -793,6 +968,7 @@ const getTagsFromBlocks = computed(() => {
                       <a href="#arrays-filters" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Filters</a>
                       <a href="#conditionals" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Conditionals</a>
                       <a href="#subarrays" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Subarrays</a>
+                      <a href="#entries" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Entries</a>
                       <a href="#rendering-rules" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Rendering</a>
                       <a href="#loading-tokens" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Loading</a>
                       <a href="#validation" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Validation</a>
@@ -1077,6 +1253,29 @@ const getTagsFromBlocks = computed(() => {
                     </p>
                   </section>
 
+                  <section id="entries" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Entries (Object Key/Value Loops)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#entries:pair {"field":"settings","value":{"theme":"dark","ctaText":"Contact Us"}}}}}
+  <div><strong>{{pair.key}}</strong>: {{pair.value}}</div>
+{{{/entries}}}
+
+{{{#entries:group {"field":"groupedItems","value":{"featured":["One","Two"],"archive":["Three"]}}}}}
+  <h4>{{group.key}}</h4>
+  {{{#subarray:child {"field":"item.value","value":[]}}}}
+    <div>{{child}}</div>
+  {{{/subarray}}}
+{{{/entries}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>entries</code> loops object fields instead of arrays.</div>
+                      <div>Use it at the root or inside other loops; it does not need to be inside <code>subarray</code>.</div>
+                      <div>Each iteration exposes <code>item.key</code> and <code>item.value</code>, plus alias access like <code v-pre>{{pair.key}}</code>.</div>
+                      <div>If a value is an array, use nested <code>subarray</code> on <code>item.value</code>.</div>
+                      <div>If <code>field</code> is not an object, it renders nothing.</div>
+                    </div>
+                  </section>
+
                   <section id="rendering-rules" class="space-y-2">
                     <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
                       Rendering Rules
@@ -1206,7 +1405,6 @@ const getTagsFromBlocks = computed(() => {
                     </h3>
                     <p class="text-sm text-foreground">
                       Add <code>data-carousel</code> markup to any CMS block and the runtime auto-initializes Embla on the client.
-                      This is initialized in <code>htmlContent.vue</code> and works inside raw block HTML.
                     </p>
                   </section>
 
@@ -1296,6 +1494,410 @@ const getTagsFromBlocks = computed(() => {
               </div>
             </TabsContent>
 
+            <TabsContent value="nav-bar">
+              <div class="h-[calc(100vh-190px)] overflow-y-auto pr-1 pb-6">
+                <div class="space-y-6">
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      What This Does
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      Use helper classes to make a CMS nav block interactive: hamburger toggle, right slide-out menu, close actions, and contained preview behavior.
+                    </p>
+                    <p class="text-sm text-foreground">
+                      The runtime in <code>htmlContent.vue</code> auto-wires these helpers and marks them as interactive so they do not open the block editor when clicked.
+                    </p>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Helper Class Contract
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>cms-nav-root</code>: nav behavior root (required).</div>
+                      <div><code>cms-nav-toggle</code>: button that toggles open/closed (required).</div>
+                      <div><code>cms-nav-panel</code>: right slide-out panel (required).</div>
+                      <div><code>cms-nav-overlay</code>: backdrop click-to-close (optional but recommended).</div>
+                      <div><code>cms-nav-close</code>: explicit close button in panel (optional).</div>
+                      <div><code>cms-nav-link</code>: links that should close panel on click (optional).</div>
+                      <div><code>cms-nav-folder</code>: desktop folder wrapper for dropdown behavior (recommended).</div>
+                      <div><code>cms-nav-folder-toggle</code>: desktop folder trigger link/button (recommended).</div>
+                      <div><code>cms-nav-folder-menu</code>: desktop dropdown menu panel for folder items (recommended).</div>
+                      <div><code>cms-nav-main</code>: optional hook for scroll/sticky/hide classes (defaults to first <code>&lt;nav&gt;</code>).</div>
+                      <div><code>cms-nav-pos-right</code>, <code>cms-nav-pos-left</code>, <code>cms-nav-pos-center</code>: helper classes for menu position behavior.</div>
+                      <div><code>cms-nav-layout</code>, <code>cms-nav-logo</code>, <code>cms-nav-desktop</code>: optional structure hooks for precise layout mapping.</div>
+                      <div><code>cms-nav-sticky</code>: force sticky top behavior even if your nav did not include fixed classes.</div>
+                      <div><code>cms-nav-hide-on-down</code>: hide nav on scroll down, show on scroll up.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Optional Root Attributes
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>data-cms-nav-open="true"</code> to start open.</div>
+                      <div><code>data-cms-nav-open-class="your-class"</code> to change the root open class (default <code>is-open</code>).</div>
+                      <div><code>data-cms-nav-close-on-link="false"</code> to keep panel open after link clicks.</div>
+                      <div><code>data-cms-nav-position="right|left|center"</code> as an alternative to helper classes.</div>
+                      <div><code>data-cms-nav-scrolled-class</code> / <code>data-cms-nav-top-class</code>: classes toggled on nav main target.</div>
+                      <div><code>data-cms-nav-scrolled-row-class</code> / <code>data-cms-nav-top-row-class</code>: classes toggled on <code>cms-nav-layout</code> for shrink/expand.</div>
+                      <div><code>data-cms-nav-scroll-threshold</code>: px before “scrolled” classes apply (default 10).</div>
+                      <div><code>data-cms-nav-hide-on-down="true"</code>, <code>data-cms-nav-hide-threshold</code> (default 80), <code>data-cms-nav-hide-delta</code> (default 6).</div>
+                      <div><code>data-cms-nav-hidden-class</code> / <code>data-cms-nav-visible-class</code> / <code>data-cms-nav-transition-class</code> for hide/show animation control.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Nav Block Template (Copy / Paste)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>&lt;div class="cms-nav-root cms-nav-sticky" data-cms-nav-root data-cms-nav-position="{{{#text {"field":"navPosition","title":"Menu Position","option":{"field":"navPosition","options":[{"title":"Right","name":"right"},{"title":"Left","name":"left"},{"title":"Center","name":"center"}],"optionsKey":"title","optionsValue":"name"},"value":"right"}}}}" data-cms-nav-close-on-link="true" data-cms-nav-top-class="bg-transparent border-transparent" data-cms-nav-scrolled-class="bg-navBg/80 backdrop-blur-lg shadow-lg" data-cms-nav-top-row-class="h-[64px] md:h-[88px] py-6 md:py-8" data-cms-nav-scrolled-row-class="h-[56px] md:h-[68px] py-5 md:py-4"&gt;
+  {{{#array {"field":"siteDoc","collection":{"path":"sites","uniqueKey":"{orgId}","query":[{"field":"docId","operator":"==","value":"{siteId}"}],"order":[]},"limit":1,"value":[]}}}}
+  &lt;nav class="cms-nav-main fixed inset-x-0 top-0 z-30 w-full bg-transparent text-navText"&gt;
+    &lt;div class="relative w-full px-6 md:px-12"&gt;
+      &lt;div class="cms-nav-layout flex h-[64px] md:h-[88px] items-center justify-between gap-6 py-6 md:py-8"&gt;
+        &lt;a href="/" class="cms-nav-logo cursor-pointer text-xl text-navText"&gt;
+          {{{#if {"cond":"item.logoLight"}}}}
+          &lt;img src="{{item.logoLight}}" class="h-[56px] md:h-[72px] py-3" /&gt;
+          {{{#else}}}
+          &lt;img src="{{item.logo}}" class="h-[56px] md:h-[72px] py-3" /&gt;
+          {{{/if}}}
+        &lt;/a&gt;
+
+        &lt;div class="cms-nav-desktop ml-auto flex items-center gap-2"&gt;
+          &lt;ul class="hidden lg:flex items-center gap-x-[20px] pt-1 text-sm uppercase tracking-widest list-none m-0 p-0 [&amp;&gt;li]:m-0 [&amp;&gt;li&gt;a]:m-0"&gt;
+            {{{#subarray:menuItem {"field":"item.menus.Site Root","limit":5,"value":[]}}}}
+            &lt;li class="relative group cms-nav-folder" data-cms-nav-folder&gt;
+              {{{#if {"cond":"menuItem.item.type == 'external'"}}}}
+              &lt;a href="{{menuItem.item.url}}" class="cursor-pointer"&gt;{{menuItem.name}}&lt;/a&gt;
+              {{{#else}}}
+              {{{#if {"cond":"menuItem.item == '[object Object]'"}}}}
+              {{{#entries:folderEntry {"field":"menuItem.item","value":{}}}}}
+              {{{#if {"cond":"folderEntry.key == 'home'"}}}}
+              &lt;a href="/" class="cms-nav-folder-toggle cursor-pointer text-sideNavText" data-cms-nav-folder-toggle&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+              {{{#else}}}
+              &lt;a href="/{{folderEntry.key}}" class="cms-nav-folder-toggle cursor-pointer text-sideNavText" data-cms-nav-folder-toggle&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+              {{{/if}}}
+              &lt;div class="cms-nav-folder-menu absolute left-0 top-full z-40 hidden min-w-max whitespace-nowrap bg-sideNavBg text-sideNavText py-2 text-left px-12 normal-case tracking-normal shadow-xl" data-cms-nav-folder-menu&gt;
+              &lt;ul&gt;
+                {{{#subarray:folderChild {"field":"item.value","value":[]}}}}
+                &lt;li class="py-1"&gt;
+                  {{{#if {"cond":"folderChild.item.type == 'external'"}}}}
+                  &lt;a href="{{folderChild.item.url}}" class="block cursor-pointer whitespace-nowrap text-sideNavText"&gt;{{folderChild.name}}&lt;/a&gt;
+                  {{{#else}}}
+                  {{{#if {"cond":"folderChild.menuTitle"}}}}
+                  &lt;a href="/{{folderEntry.key}}/{{folderChild.name}}" class="block cursor-pointer whitespace-nowrap text-sideNavText"&gt;{{folderChild.menuTitle}}&lt;/a&gt;
+                  {{{#else}}}
+                  &lt;a href="/{{folderEntry.key}}/{{folderChild.name}}" class="block cursor-pointer whitespace-nowrap text-sideNavText"&gt;{{folderChild.name}}&lt;/a&gt;
+                  {{{/if}}}
+                  {{{/if}}}
+                &lt;/li&gt;
+                {{{/subarray}}}
+              &lt;/ul&gt;
+              &lt;/div&gt;
+              {{{/entries}}}
+              {{{#else}}}
+              {{{#if {"cond":"menuItem.name == 'home'"}}}}
+              {{{#if {"cond":"menuItem.menuTitle"}}}}
+              &lt;a href="/" class="cursor-pointer"&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+              {{{#else}}}
+              &lt;a href="/" class="cursor-pointer"&gt;{{menuItem.name}}&lt;/a&gt;
+              {{{/if}}}
+              {{{#else}}}
+              {{{#if {"cond":"menuItem.menuTitle"}}}}
+              &lt;a href="/{{menuItem.name}}" class="cursor-pointer"&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+              {{{#else}}}
+              &lt;a href="/{{menuItem.name}}" class="cursor-pointer"&gt;{{menuItem.name}}&lt;/a&gt;
+              {{{/if}}}
+              {{{/if}}}
+              {{{/if}}}
+              {{{/if}}}
+            &lt;/li&gt;
+            {{{/subarray}}}
+          &lt;/ul&gt;
+
+          &lt;button class="cms-nav-toggle flex h-12 w-12 items-center justify-center rounded-full text-navText" type="button" aria-label="Open Menu"&gt;
+            &lt;svg class="h-6 w-6" viewBox="0 0 24 24" fill="none" stroke="currentColor" xmlns="http://www.w3.org/2000/svg"&gt;
+              &lt;path d="M4 6h16M4 12h16M4 18h16" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" /&gt;
+            &lt;/svg&gt;
+          &lt;/button&gt;
+        &lt;/div&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;
+  &lt;/nav&gt;
+
+  &lt;div class="cms-nav-overlay fixed inset-0 z-[110] bg-black/50 transition-opacity duration-300 opacity-0 pointer-events-none"&gt;&lt;/div&gt;
+
+  &lt;aside class="cms-nav-panel fixed inset-y-0 right-0 z-[120] w-full max-w-md bg-sideNavBg text-sideNavText transition-all duration-300 translate-x-full opacity-0 pointer-events-none"&gt;
+    &lt;div class="relative flex h-full flex-col overflow-y-auto px-8 py-10 text-center"&gt;
+      &lt;button type="button" class="cms-nav-close absolute right-6 top-6 text-4xl text-sideNavText"&gt;&amp;times;&lt;/button&gt;
+
+      &lt;div class="mb-8 mt-2 flex items-center justify-center gap-4"&gt;
+        &lt;a href="/" class="flex items-center gap-4 text-navText"&gt;
+          &lt;img src="{{item.logo}}" class="h-[30px] w-auto max-w-full object-contain" /&gt;
+          {{{#if {"cond":"item.brandLogoDark"}}}}
+          &lt;span class="h-10 w-px bg-black" aria-hidden="true"&gt;&lt;/span&gt;
+          &lt;img src="{{item.brandLogoDark}}" class="h-[30px] w-auto max-w-full object-contain" /&gt;
+          {{{/if}}}
+        &lt;/a&gt;
+      &lt;/div&gt;
+
+      &lt;ul class="w-full space-y-4 border-b border-black pb-4 uppercase"&gt;
+        {{{#subarray:menuItem {"field":"item.menus.Site Root","value":[]}}}}
+        &lt;li class="border-t border-black pt-4"&gt;
+          {{{#if {"cond":"menuItem.item.type == 'external'"}}}}
+          &lt;a href="{{menuItem.item.url}}" class="cms-nav-link block text-sideNavText tracking-widest text-sm"&gt;{{menuItem.name}}&lt;/a&gt;
+          {{{#else}}}
+          {{{#if {"cond":"menuItem.item == '[object Object]'"}}}}
+          {{{#entries:folderEntry {"field":"menuItem.item","value":{}}}}}
+          {{{#if {"cond":"folderEntry.key == 'home'"}}}}
+          &lt;a href="/" class="cms-nav-link block text-sideNavText tracking-widest text-sm"&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+          {{{#else}}}
+          &lt;a href="/{{folderEntry.key}}" class="cms-nav-link block text-sideNavText tracking-widest text-sm"&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+          {{{/if}}}
+          &lt;ul class="mt-2 space-y-2 border-l border-black/40 pl-4"&gt;
+            {{{#subarray:folderChild {"field":"item.value","value":[]}}}}
+            &lt;li&gt;
+              {{{#if {"cond":"folderChild.item.type == 'external'"}}}}
+              &lt;a href="{{folderChild.item.url}}" class="cms-nav-link block text-sideNavText tracking-widest text-xs"&gt;{{folderChild.name}}&lt;/a&gt;
+              {{{#else}}}
+              {{{#if {"cond":"folderChild.menuTitle"}}}}
+              &lt;a href="/{{folderEntry.key}}/{{folderChild.name}}" class="cms-nav-link block text-sideNavText tracking-widest text-xs"&gt;{{folderChild.menuTitle}}&lt;/a&gt;
+              {{{#else}}}
+              &lt;a href="/{{folderEntry.key}}/{{folderChild.name}}" class="cms-nav-link block text-sideNavText tracking-widest text-xs"&gt;{{folderChild.name}}&lt;/a&gt;
+              {{{/if}}}
+              {{{/if}}}
+            &lt;/li&gt;
+            {{{/subarray}}}
+          &lt;/ul&gt;
+          {{{/entries}}}
+          {{{#else}}}
+          {{{#if {"cond":"menuItem.name == 'home'"}}}}
+          {{{#if {"cond":"menuItem.menuTitle"}}}}
+          &lt;a href="/" class="cms-nav-link block text-sideNavText tracking-widest text-sm"&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+          {{{#else}}}
+          &lt;a href="/" class="cms-nav-link block text-sideNavText tracking-widest text-sm"&gt;{{menuItem.name}}&lt;/a&gt;
+          {{{/if}}}
+          {{{#else}}}
+          {{{#if {"cond":"menuItem.menuTitle"}}}}
+          &lt;a href="/{{menuItem.name}}" class="cms-nav-link block text-sideNavText tracking-widest text-sm"&gt;{{menuItem.menuTitle}}&lt;/a&gt;
+          {{{#else}}}
+          &lt;a href="/{{menuItem.name}}" class="cms-nav-link block text-sideNavText tracking-widest text-sm"&gt;{{menuItem.name}}&lt;/a&gt;
+          {{{/if}}}
+          {{{/if}}}
+          {{{/if}}}
+          {{{/if}}}
+        &lt;/li&gt;
+        {{{/subarray}}}
+      &lt;/ul&gt;
+
+      &lt;div class="mt-10 flex w-full items-center justify-center gap-4"&gt;
+        {{{#if {"cond":"item.socialFacebook"}}}}
+        &lt;a href="{{item.socialFacebook}}" target="_blank" rel="noopener" class="flex h-10 w-10 items-center justify-center rounded-full border border-sideNavText text-sideNavText transition-colors duration-200 hover:bg-sideNavText hover:text-sideNavBg"&gt;
+          &lt;span class="sr-only"&gt;Facebook&lt;/span&gt;
+          &lt;span class="h-5 w-5 [&amp;&gt;svg]:h-5 [&amp;&gt;svg]:w-5 [&amp;&gt;svg]:fill-current" aria-hidden="true"&gt;
+            &lt;svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"&gt;
+              &lt;path d="M80 299.3V512H196V299.3h86.5l18-97.8H196V166.9c0-51.7 20.3-71.5 72.7-71.5c16.3 0 29.4 .4 37 1.2V7.9C291.4 4 256.4 0 236.2 0C129.3 0 80 50.5 80 159.4v42.1H14v97.8H80z"&gt;&lt;/path&gt;
+            &lt;/svg&gt;
+          &lt;/span&gt;
+        &lt;/a&gt;
+        {{{/if}}}
+        {{{#if {"cond":"item.socialInstagram"}}}}
+        &lt;a href="{{item.socialInstagram}}" target="_blank" rel="noopener" class="flex h-10 w-10 items-center justify-center rounded-full border border-sideNavText text-sideNavText transition-colors duration-200 hover:bg-sideNavText hover:text-sideNavBg"&gt;
+          &lt;span class="sr-only"&gt;Instagram&lt;/span&gt;
+          &lt;span class="h-5 w-5 [&amp;&gt;svg]:h-5 [&amp;&gt;svg]:w-5 [&amp;&gt;svg]:fill-current" aria-hidden="true"&gt;
+            &lt;svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"&gt;
+              &lt;path d="M224.1 141c-63.6 0-114.9 51.3-114.9 114.9s51.3 114.9 114.9 114.9S339 319.5 339 255.9 287.7 141 224.1 141zm0 189.6c-41.1 0-74.7-33.5-74.7-74.7s33.5-74.7 74.7-74.7 74.7 33.5 74.7 74.7-33.6 74.7-74.7 74.7zm146.4-194.3c0 14.9-12 26.8-26.8 26.8-14.9 0-26.8-12-26.8-26.8s12-26.8 26.8-26.8 26.8 12 26.8 26.8zm76.1 27.2c-1.7-35.9-9.9-67.7-36.2-93.9-26.2-26.2-58-34.4-93.9-36.2-37-2.1-147.9-2.1-184.9 0-35.8 1.7-67.6 9.9-93.9 36.1s-34.4 58-36.2 93.9c-2.1 37-2.1 147.9 0 184.9 1.7 35.9 9.9 67.7 36.2 93.9s58 34.4 93.9 36.2c37 2.1 147.9 2.1 184.9 0 35.9-1.7 67.7-9.9 93.9-36.2 26.2-26.2 34.4-58 36.2-93.9 2.1-37 2.1-147.8 0-184.8zM398.8 388c-7.8 19.6-22.9 34.7-42.6 42.6-29.5 11.7-99.5 9-132.1 9s-102.7 2.6-132.1-9c-19.6-7.8-34.7-22.9-42.6-42.6-11.7-29.5-9-99.5-9-132.1s-2.6-102.7 9-132.1c7.8-19.6 22.9-34.7 42.6-42.6 29.5-11.7 99.5-9 132.1-9s102.7-2.6 132.1 9c19.6 7.8 34.7 22.9 42.6 42.6 11.7 29.5 9 99.5 9 132.1s2.7 102.7-9 132.1z"&gt;&lt;/path&gt;
+            &lt;/svg&gt;
+          &lt;/span&gt;
+        &lt;/a&gt;
+        {{{/if}}}
+        {{{#if {"cond":"item.socialLinkedIn"}}}}
+        &lt;a href="{{item.socialLinkedIn}}" target="_blank" rel="noopener" class="flex h-10 w-10 items-center justify-center rounded-full border border-sideNavText text-sideNavText transition-colors duration-200 hover:bg-sideNavText hover:text-sideNavBg"&gt;
+          &lt;span class="sr-only"&gt;LinkedIn&lt;/span&gt;
+          &lt;span class="h-5 w-5 [&amp;&gt;svg]:h-5 [&amp;&gt;svg]:w-5 [&amp;&gt;svg]:fill-current" aria-hidden="true"&gt;
+            &lt;svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"&gt;
+              &lt;path d="M100.28 448H7.4V148.9h92.88zM53.79 108.1C24.09 108.1 0 83.5 0 53.8a53.79 53.79 0 0 1 107.58 0c0 29.7-24.1 54.3-53.79 54.3zM447.9 448h-92.68V302.4c0-34.7-.7-79.2-48.29-79.2-48.29 0-55.69 37.7-55.69 76.7V448h-92.78V148.9h89.08v40.8h1.3c12.4-23.5 42.69-48.3 87.88-48.3 94 0 111.28 61.9 111.28 142.3V448z"&gt;&lt;/path&gt;
+            &lt;/svg&gt;
+          &lt;/span&gt;
+        &lt;/a&gt;
+        {{{/if}}}
+        {{{#if {"cond":"item.socialYouTube"}}}}
+        &lt;a href="{{item.socialYouTube}}" target="_blank" rel="noopener" class="flex h-10 w-10 items-center justify-center rounded-full border border-sideNavText text-sideNavText transition-colors duration-200 hover:bg-sideNavText hover:text-sideNavBg"&gt;
+          &lt;span class="sr-only"&gt;YouTube&lt;/span&gt;
+          &lt;span class="h-5 w-5 [&amp;&gt;svg]:h-5 [&amp;&gt;svg]:w-5 [&amp;&gt;svg]:fill-current" aria-hidden="true"&gt;
+            &lt;svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"&gt;
+              &lt;path d="M549.655 124.083c-6.281-23.65-24.787-42.276-48.284-48.597C458.781 64 288 64 288 64S117.22 64 74.629 75.486c-23.497 6.322-42.003 24.947-48.284 48.597-11.412 42.867-11.412 132.305-11.412 132.305s0 89.438 11.412 132.305c6.281 23.65 24.787 41.5 48.284 47.821C117.22 448 288 448 288 448s170.78 0 213.371-11.486c23.497-6.321 42.003-24.171 48.284-47.821 11.412-42.867 11.412-132.305 11.412-132.305s0-89.438-11.412-132.305zm-317.51 213.508V175.185l142.739 81.205-142.739 81.201z"&gt;&lt;/path&gt;
+            &lt;/svg&gt;
+          &lt;/span&gt;
+        &lt;/a&gt;
+        {{{/if}}}
+      &lt;/div&gt;
+    &lt;/div&gt;
+  &lt;/aside&gt;
+  {{{/array}}}
+&lt;/div&gt;</code></pre>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Preview + Edit Behavior
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>Clicking the nav button opens the slide-out in Block Editor preview and Page Preview mode.</div>
+                      <div>Interactive nav elements do not trigger “Edit Block”. Clicking outside them still opens the editor in edit mode.</div>
+                      <div>In CMS preview, fixed nav and panel are contained to the preview surface by the block wrapper.</div>
+                      <div><code>cms-nav-pos-left</code> also switches the slide-out panel to the left side.</div>
+                    </div>
+                  </section>
+                </div>
+              </div>
+            </TabsContent>
+
+            <TabsContent value="form-helpers">
+              <div class="h-[calc(100vh-190px)] overflow-y-auto pr-1 pb-6">
+                <div class="space-y-6">
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      What This Does
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      Add helper classes or data attributes to a CMS block form, and the client runtime will submit to
+                      <code>/api/contact</code> with anti-bot checks and submit history tracking.
+                    </p>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      CMS Preview Scope
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      In Block Editor, this is for structure and messaging preview only. Use it to verify markup and required-state UX,
+                      not to validate end-to-end delivery.
+                    </p>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Helper Contract
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>form.cms-form</code> or <code>form[data-cms-form]</code>: form root.</div>
+                      <div><code>.cms-form-required</code> or <code>[data-cms-required=&quot;true&quot;]</code>: required field markers.</div>
+                      <div><code>.cms-form-submit</code> or <code>[data-cms-form-submit]</code>: submit button.</div>
+                      <div><code>.cms-form-message</code> or <code>[data-cms-form-message]</code>: status/error message container.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Defaults + Messages
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>Default endpoint: <code>/api/contact</code>.</div>
+                      <div><code>data-cms-success-message</code>: override success copy.</div>
+                      <div><code>data-cms-error-message</code>: override error copy.</div>
+                      <div><code>data-cms-required-message</code>: override required-field copy.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Context IDs
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      Block/Page/Site/Org IDs are inherited from the CMS HTML wrapper automatically, so forms in blocks
+                      do not need manual context wiring.
+                    </p>
+                  </section>
+
+                  <section class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Contact Form Example (Block HTML)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>&lt;section
+  class="relative cms-block cms-block-contact-form-placeholder rounded-2xl border border-dashed border-slate-300 bg-slate-50/70 px-4 py-6 sm:px-6 sm:py-8"
+  data-block-type="contact-form-placeholder"
+&gt;
+  &lt;div class="mx-auto max-w-3xl pt-6"&gt;
+    &lt;div class="mb-6 space-y-2 text-center sm:text-left"&gt;
+      &lt;h2 class="text-xl font-semibold text-slate-900"&gt;
+        {{{#text {"field":"formHeader","title":"Form Header","value":"Contact Us"}}}}
+      &lt;/h2&gt;
+      &lt;p class="text-sm text-slate-600"&gt;
+        {{{#text {"field":"formSubheader","title":"Form Subheader","value":"Subheader content"}}}}
+      &lt;/p&gt;
+    &lt;/div&gt;
+
+    &lt;form
+      class="cms-form space-y-4"
+      data-cms-form
+      data-cms-required-message="Please complete all required fields."
+      data-cms-success-message="Thanks! Your message has been sent."
+      data-cms-error-message="Sorry, we could not send your message. Please try again."
+      data-cms-success-class="cms-form-message cms-form-message-success"
+      data-cms-error-class="cms-form-message cms-form-message-error"
+      data-cms-invalid-class="cms-form-field-invalid"
+      data-cms-working-class="cms-form-submitting"
+    &gt;
+      &lt;!-- Honeypot (optional, used by helper if present) --&gt;
+      &lt;div class="pointer-events-none absolute -left-[9999px] top-auto h-px w-px overflow-hidden opacity-0" aria-hidden="true"&gt;
+        &lt;label for="cms-company"&gt;Company&lt;/label&gt;
+        &lt;input id="cms-company" name="company" type="text" tabindex="-1" autocomplete="off" /&gt;
+      &lt;/div&gt;
+
+      &lt;div class="space-y-4"&gt;
+        {{{#array {"field":"formFields","schema":[{"field":"fieldName","type":"text","title":"Field Label"},{"field":"fieldType","type":"option","title":"Field Type","option":{"optionsKey":"title","optionsValue":"value","options":[{"title":"Text","value":"text"},{"title":"Email","value":"email"},{"title":"Phone","value":"tel"},{"title":"Textarea","value":"textarea"}]},"value":"text"},{"field":"fieldRequired","type":"option","title":"Required","option":{"optionsKey":"title","optionsValue":"value","options":[{"title":"Yes","value":"true"},{"title":"No","value":"false"}]},"value":"true"}],"value":[{"fieldName":"Name","fieldType":"text","fieldRequired":"true"},{"fieldName":"Email","fieldType":"email","fieldRequired":"true"},{"fieldName":"Message","fieldType":"textarea","fieldRequired":"true"}]}}}}
+          &lt;div class="space-y-1"&gt;
+            &lt;label class="text-xs font-medium uppercase tracking-wide text-slate-600"&gt;
+              {{item.fieldName}}
+            &lt;/label&gt;
+
+            {{{#if {"cond":"item.fieldType == 'textarea'"}}}}
+              &lt;textarea
+                class="w-full rounded-lg border border-slate-300 bg-white px-3 py-2 text-sm text-slate-900"
+                data-cms-required="{{item.fieldRequired}}"
+                name="{{item.fieldName}}"
+                placeholder="{{item.fieldName}}"
+                rows="6"
+              &gt;&lt;/textarea&gt;
+            {{{#else}}}
+              &lt;input
+                class="w-full rounded-lg border border-slate-300 bg-white px-3 py-2 text-sm text-slate-900"
+                data-cms-required="{{item.fieldRequired}}"
+                type="{{item.fieldType}}"
+                name="{{item.fieldName}}"
+                placeholder="{{item.fieldName}}"
+              /&gt;
+            {{{/if}}}
+          &lt;/div&gt;
+        {{{/array}}}
+      &lt;/div&gt;
+
+      &lt;div class="mt-6"&gt;
+        &lt;button
+          type="submit"
+          class="cms-form-submit inline-flex w-full items-center justify-center rounded-lg bg-slate-900 px-4 py-2.5 text-sm font-semibold text-white shadow-sm disabled:cursor-not-allowed disabled:opacity-60 sm:w-auto"
+          data-cms-form-submit
+        &gt;
+          {{{#text {"field":"buttonText","title":"Button Text","value":"Send Message"}}}}
+        &lt;/button&gt;
+      &lt;/div&gt;
+
+      &lt;p class="cms-form-message hidden text-sm" data-cms-form-message&gt;&lt;/p&gt;
+    &lt;/form&gt;
+
+    &lt;div class="hidden"&gt;
+      {{{#text {"field":"emailTo","title":"Email To","value":"test@testing.com"}}}}
+    &lt;/div&gt;
+  &lt;/div&gt;
+&lt;/section&gt;</code></pre>
+                  </section>
+                </div>
+              </div>
+            </TabsContent>
+
             <TabsContent value="scroll-reveals">
               <div class="h-[calc(100vh-190px)] overflow-y-auto pr-1 pb-6">
                 <div class="space-y-6">