@edgedev/create-edge-app 1.1.29 → 1.2.30

package/edge/components/cms/blockEditor.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { Maximize2, Monitor, Smartphone, Tablet } from 'lucide-vue-next'
+import { HelpCircle, Maximize2, Monitor, Smartphone, Tablet } from 'lucide-vue-next'
 import { toTypedSchema } from '@vee-validate/zod'
 import * as z from 'zod'
 const props = defineProps({
@@ -33,6 +33,7 @@ const state = reactive({
   jsonEditorOpen: false,
   jsonEditorContent: '',
   jsonEditorError: '',
+  helpOpen: false,
   editingContext: null,
   renderSite: '',
   initialBlocksSeeded: false,
@@ -523,14 +524,20 @@ watch(() => state.jsonEditorOpen, (open) => {
     resetJsonEditorState()
 })
 const sites = computed(() => {
-  return Object.values(edgeFirebase.data?.[`${edgeGlobal.edgeState.organizationDocPath}/sites`] || {})
+  const sitesMap = edgeFirebase.data?.[`${edgeGlobal.edgeState.organizationDocPath}/sites`] || {}
+  return Object.entries(sitesMap)
+    .map(([docId, data]) => ({ docId, ...(data || {}) }))
+    .filter(site => site.docId && site.docId !== 'templates')
 })
 
 watch (sites, async (newSites) => {
   state.loading = true
-  if (!edgeGlobal.edgeState.blockEditorSite && newSites.length > 0) {
+  const selectedSite = String(edgeGlobal.edgeState.blockEditorSite || '').trim()
+  const hasSelectedSite = newSites.some(site => site.docId === selectedSite)
+  if ((!selectedSite || !hasSelectedSite) && newSites.length > 0)
     edgeGlobal.edgeState.blockEditorSite = newSites[0].docId
-  }
+  else if (!newSites.length)
+    edgeGlobal.edgeState.blockEditorSite = ''
   await nextTick()
   state.loading = false
 }, { immediate: true, deep: true })
@@ -607,7 +614,6 @@ const getTagsFromBlocks = computed(() => {
           </div>
         </div>
       </template>
-
       <template #main="slotProps">
         <div class="pt-4">
           <div class="flex w-full gap-2">
@@ -655,8 +661,20 @@ const getTagsFromBlocks = computed(() => {
             <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="text-xs font-semibold uppercase tracking-wide text-slate-600 dark:text-slate-300">
-                    Dynamic Content
+                  <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
@@ -729,6 +747,729 @@ const getTagsFromBlocks = computed(() => {
         </div>
       </template>
     </edge-editor>
+    <Sheet v-model:open="state.helpOpen">
+      <SheetContent side="right" class="w-full md:w-1/2 max-w-none sm:max-w-none max-w-2xl">
+        <SheetHeader>
+          <SheetTitle class="text-left">
+            Block Editor Guide
+          </SheetTitle>
+          <SheetDescription class="text-left text-sm text-muted-foreground">
+            Everything about blocks: how fields are built, how data loads, which options exist, and how the editor renders.
+          </SheetDescription>
+        </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">
+              <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="scroll-reveals" class="w-full text-black data-[state=active]:bg-black data-[state=active]:text-white">
+                Scroll Reveals
+              </TabsTrigger>
+            </TabsList>
+
+            <TabsContent value="guide">
+              <div class="h-[calc(100vh-190px)] overflow-y-auto pr-1 pb-6">
+                <div class="space-y-8">
+                  <div class="rounded-md border border-border/60 bg-muted/30 p-3">
+                    <div class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                      Quick Menu
+                    </div>
+                    <div class="mt-2 flex flex-wrap gap-2 text-xs">
+                      <a href="#block-overview" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Overview</a>
+                      <a href="#fields-built" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Fields</a>
+                      <a href="#basic-tags" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Basic Tags</a>
+                      <a href="#tag-format" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Tag Format</a>
+                      <a href="#block-settings" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Settings</a>
+                      <a href="#input-types" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Inputs</a>
+                      <a href="#image-fields" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Images</a>
+                      <a href="#select-options" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Selects</a>
+                      <a href="#arrays-manual" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Arrays</a>
+                      <a href="#arrays-firestore" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Firestore</a>
+                      <a href="#arrays-api" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">API</a>
+                      <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="#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>
+                      <a href="#stored-data" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Stored Data</a>
+                      <a href="#preview-placeholders" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Preview</a>
+                      <a href="#json-editor" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">JSON Editor</a>
+                      <a href="#common-mistakes" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Mistakes</a>
+                      <a href="#indexes-kv" class="px-2 py-1 rounded border border-border bg-background hover:bg-muted transition">Indexes + KV</a>
+                    </div>
+                  </div>
+                  <section id="block-overview" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      What A Block Is
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      A block is HTML plus special tags. The editor scans those tags and builds the form for CMS users.
+                      Any tag with a <code>field</code> becomes an editable input.
+                    </p>
+                    <p class="text-sm text-foreground">
+                      Your HTML is the template. The CMS form is the data. The preview renders the data inside the template.
+                    </p>
+                  </section>
+
+                  <section id="fields-built" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      How The CMS Builds Fields
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>The editor scans the HTML for triple‑brace tags like <code v-pre>{{{#text ...}}}</code>.</div>
+                      <div>The <code>field</code> key becomes the saved data key.</div>
+                      <div>Fields appear in the order they are first found in the HTML.</div>
+                      <div>Only triple‑brace tags create inputs. Plain <code v-pre>{{...}}</code> does not.</div>
+                      <div>When you edit a block, template meta + stored meta are merged. Filters and limits persist.</div>
+                    </div>
+                  </section>
+
+                  <section id="basic-tags" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Basic Field Tags
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#text {"field":"headline","value":"Hello","title":"Headline"}}}}
+{{{#textarea {"field":"intro","value":""}}}}
+{{{#richtext {"field":"body","value":""}}}}
+{{{#image {"field":"heroImage","value":"https://example.com/hero.jpg"}}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>field</code> is the key stored in the block.</div>
+                      <div><code>value</code> is the default value when nothing is saved yet.</div>
+                      <div><code>title</code> sets the label shown to CMS users. If missing, the field name is used.</div>
+                    </div>
+                  </section>
+
+                  <section id="tag-format" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Tag Format (Be Exact)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#text {"field":"title","value":"My Title","title":"Title"}}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>Tags start with <code v-pre>{{{#</code> and end with <code v-pre>}}}</code>.</div>
+                      <div>Config inside the tag is JSON. Use double quotes around keys and strings.</div>
+                      <div>Commas are required between fields in the config object.</div>
+                    </div>
+                  </section>
+
+                  <section id="block-settings" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Block Settings (Top Row)
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><strong>Name</strong> is the library name of the block.</div>
+                      <div><strong>Tags</strong> are for filtering blocks in the picker.</div>
+                      <div><strong>Allowed Themes</strong> limits where this block can be used.</div>
+                      <div><strong>Synced Block</strong> means edits are shared across all instances.</div>
+                    </div>
+                  </section>
+
+                  <section id="input-types" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Input Types (What CMS Users See)
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>text</code> → single‑line input (HTML is escaped on render).</div>
+                      <div><code>textarea</code> → multi‑line input (HTML is escaped on render).</div>
+                      <div><code>richtext</code> → WYSIWYG editor (HTML is rendered as‑is).</div>
+                      <div><code>number</code> → number input.</div>
+                      <div><code>image</code> → image picker + preview.</div>
+                      <div><code>array</code> → list editor (manual items) or data loader (API/collection).</div>
+                    </div>
+                    <p class="text-sm text-foreground">
+                      Rich text image controls include size buttons, float left/none/right, and a width slider (10–100%).
+                    </p>
+                  </section>
+
+                  <section id="image-fields" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Image Fields (Media Picker)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#image {"field":"heroImage","value":"","tags":["Backgrounds"]}}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>tags</code> filters the media manager to specific tag groups.</div>
+                      <div>The stored value is the image URL.</div>
+                    </div>
+                  </section>
+
+                  <section id="select-options" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Select / Options Fields
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      Add an <code>option</code> object to a field to show a select. Options can be static or pulled from a collection.
+                    </p>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#text {
+  "field":"layout",
+  "title":"Layout",
+  "option":{
+    "field":"layout",
+    "options":[{"title":"Left","name":"left"},{"title":"Right","name":"right"}],
+    "optionsKey":"title",
+    "optionsValue":"name"
+  }
+}}}</code></pre>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#text {
+  "field":"agentId",
+  "title":"Agent",
+  "option":{
+    "field":"agentId",
+    "options":"users",
+    "optionsKey":"name",
+    "optionsValue":"userId",
+    "multiple":true
+  }
+}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>options</code> can be a static array or a collection name.</div>
+                      <div><code>optionsKey</code> is the label shown in the dropdown.</div>
+                      <div><code>optionsValue</code> is the stored value.</div>
+                      <div><code>multiple: true</code> saves an array of values.</div>
+                    </div>
+                  </section>
+
+                  <section id="arrays-manual" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Arrays (Manual Lists)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#array {"field":"list","value":[]}}}}
+  {{item}}
+{{{/array}}}</code></pre>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#array {
+  "field":"cards",
+  "schema":[
+    {"field":"title","type":"text"},
+    {"field":"body","type":"richtext"},
+    {"field":"image","type":"image"}
+  ],
+  "value":[]
+}}}}
+  <h3>{{item.title}}</h3>
+  <div>{{item.body}}</div>
+  <img :src="item.image">
+{{{/array}}}</code></pre>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#array {
+  "field":"statics",
+  "value":[
+    "First item",
+    "Second item",
+    "Third item"
+  ]
+}}}}
+  <li>{{item}}</li>
+{{{/array}}}</code></pre>
+                    <p class="text-sm text-foreground">
+                      Use <code>schema</code> to define fields on each array item.
+                      Supported item UI types: <code>text</code>, <code>textarea</code>, <code>richtext</code>, <code>image</code>, <code>number</code>, <code>option</code>.
+                    </p>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>Manual arrays show an “Add Entry” form, drag handles to reorder, and delete buttons.</div>
+                      <div>Use <code>number</code> for numeric input. <code>integer</code>/<code>money</code> only affect display formatting.</div>
+                      <div><code>limit</code> trims output to the first N items when rendering.</div>
+                    </div>
+                    <p class="text-sm text-foreground">
+                      Inside an array block you render <code v-pre>{{item}}</code> or <code v-pre>{{item.fieldName}}</code>.
+                    </p>
+                    <p class="text-sm text-foreground">
+                      For schema formatting only, you can also use <code>integer</code> or <code>money</code> types.
+                    </p>
+                  </section>
+
+                  <section id="arrays-firestore" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Arrays from Firestore
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#array {
+  "field":"list",
+  "schema":[{"field":"name","type":"text"},{"field":"role","type":"text"}],
+  "collection":{
+    "path":"team",
+    "uniqueKey":"{orgId}",
+    "query":[{"field":"active","operator":"==","value":true}],
+    "order":[{"field":"name","direction":"asc"}]
+  },
+  "limit":6,
+  "value":[]
+}}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>path</code> is under <code>organizations/{orgId}</code>.</div>
+                      <div><code>uniqueKey</code> supports <code>{orgId}</code> and <code>{siteId}</code>.</div>
+                      <div><code>query</code> and <code>order</code> map to Firestore filters and sort.</div>
+                      <div><code>limit</code> caps the results.</div>
+                    </div>
+                  </section>
+
+                  <section id="arrays-api" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Arrays from an API
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#array {
+  "field":"list",
+  "api":"https://api.example.com/items",
+  "apiField":"data",
+  "apiQuery":"?limit=4",
+  "limit":4,
+  "value":[]
+}}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>api</code> is the base URL without query string.</div>
+                      <div><code>apiQuery</code> is appended to the URL.</div>
+                      <div><code>apiField</code> is the array field in the response.</div>
+                    </div>
+                    <p class="text-sm text-foreground">
+                      Filters from <code>queryOptions</code> become query string parameters at runtime.
+                    </p>
+                  </section>
+
+                  <section id="arrays-filters" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Filters for Arrays (queryOptions)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>"queryOptions":[
+  {
+    "field":"users",
+    "operator":"array-contains-any",
+    "options":"users",
+    "optionsKey":"name",
+    "optionsValue":"userId",
+    "multiple":true
+  }
+]</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>queryOptions</code> creates filter inputs for CMS users.</div>
+                      <div>Selections are stored in <code>meta.queryItems</code> and used in the API/collection query.</div>
+                      <div><code>options</code> can be a collection name or static array.</div>
+                      <div><code>multiple: true</code> saves an array.</div>
+                    </div>
+                  </section>
+
+                  <section id="conditionals" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Conditionals (Inside Arrays)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#if {"cond":"item.price > 0"} }}}
+  <div>Price: {{item.price}}</div>
+{{{#else}}}
+  <div>Contact for pricing</div>
+{{{/if}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>cond</code> works on <code>item.*</code> inside array/subarray templates.</div>
+                      <div>Supported operators: <code>==</code>, <code>!=</code>, <code>&gt;</code>, <code>&lt;</code>, <code>&gt;=</code>, <code>&lt;=</code>.</div>
+                    </div>
+                  </section>
+
+                  <section id="subarrays" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Subarrays (Nested Lists)
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#array {"field":"items","value":[],"as":"card"}}}}
+  <h3>{{card.title}}</h3>
+  {{{#subarray:child {"field":"item.children","limit":0 }}}}
+    <div>{{child}}</div>
+  {{{/subarray}}}
+{{{/array}}}</code></pre>
+                    <p class="text-sm text-foreground">
+                      Use <code>as</code> to set an alias (like <code v-pre>{{card.title}}</code>). Use <code>subarray</code> to loop nested lists.
+                    </p>
+                  </section>
+
+                  <section id="rendering-rules" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Rendering Rules
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>text</code> and <code>textarea</code> output is HTML‑escaped.</div>
+                      <div><code>richtext</code> output is inserted as HTML.</div>
+                      <div>Array schema types format output (e.g. <code>money</code> formats USD, <code>integer</code> truncates).</div>
+                    </div>
+                  </section>
+
+                  <section id="loading-tokens" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Loading Tokens
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code v-pre>{{loading}}</code> is empty while loading and <code>hidden</code> when loaded.</div>
+                      <div><code v-pre>{{loaded}}</code> is <code>hidden</code> while loading and empty when loaded.</div>
+                      <div>These tokens only change when the block is waiting on API or collection data.</div>
+                    </div>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#array {"field":"list","api":"https://api.example.com/items","apiField":"data","value":[]}}}}
+  &lt;div class="skeleton {{loading}}"&gt;Loading items...&lt;/div&gt;
+  &lt;div class="{{loaded}}"&gt;
+    &lt;div&gt;{{item.title}}&lt;/div&gt;
+  &lt;/div&gt;
+{{{/array}}}</code></pre>
+                  </section>
+
+                  <section id="validation" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Validation Rules
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{{{#text {"field":"title","validation":{"required":true,"min":5,"max":80}}}}}
+{{{#array {"field":"items","schema":[{"field":"name","type":"text","validation":{"required":true}}]}}}}</code></pre>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>required</code>, <code>min</code>, <code>max</code> are supported.</div>
+                      <div>For numbers, <code>min</code>/<code>max</code> are numeric. For text/arrays they are length or item count.</div>
+                    </div>
+                  </section>
+
+                  <section id="stored-data" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Editor vs Stored Data
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      The editor only shows fields in the current template. If a field is removed, it disappears,
+                      but stored data stays. Add the field back later and the old data returns.
+                    </p>
+                  </section>
+
+                  <section id="preview-placeholders" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Preview + Placeholders
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>Empty fields show placeholder text or images in the preview.</div>
+                      <div>Array previews show sample items if the list is empty.</div>
+                      <div>Use the viewport buttons to test different screen sizes.</div>
+                    </div>
+                  </section>
+
+                  <section id="json-editor" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      JSON Field Editor
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      Click a line inside the code editor to open the JSON Field Editor for that tag.
+                      Fix JSON errors there and save to update the tag.
+                    </p>
+                  </section>
+
+                  <section id="common-mistakes" class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Common Mistakes
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>Missing a <code>field</code> key in a tag.</div>
+                      <div>Invalid JSON (missing commas or quotes).</div>
+                      <div>Using a schema object instead of a schema array (the editor expects an array).</div>
+                      <div>Using <code>order</code> without the right Firestore index.</div>
+                    </div>
+                  </section>
+
+                  <section id="indexes-kv" class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Firestore Indexes + KV Sync (Required)
+                    </h3>
+                    <p class="text-sm text-foreground">
+                      If you add a Firestore query (like <code>array-contains</code> + <code>order</code>), you must add the
+                      matching composite index in <code>firestore.indexes.json</code>.
+                    </p>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>{
+  "collectionGroup": "listings",
+  "queryScope": "COLLECTION",
+  "fields": [
+    {
+      "fieldPath": "status",
+      "arrayConfig": "CONTAINS"
+    },
+    {
+      "fieldPath": "doc_created_at",
+      "order": "DESCENDING"
+    }
+  ]
+},</code></pre>
+                    <p class="text-sm text-foreground">
+                      If you want fast search/filtering in the CMS, you also need a KV mirror in Firebase Functions.
+                      Example (use your collection + fields):
+                    </p>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>exports.onListingWritten = createKvMirrorHandlerFromFields({
+  documentPath: 'organizations/{orgId}/listings',
+  uniqueKey: '{orgId}',
+  indexKeys: ['name', 'city', 'state', 'status'],
+  metadataKeys: ['name', 'city', 'state', 'status', 'price', 'doc_created_at'],
+})</code></pre>
+                  </section>
+                </div>
+              </div>
+            </TabsContent>
+
+            <TabsContent value="carousel">
+              <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 <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>
+
+                  <section class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Quick Start
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>&lt;div
+  data-carousel
+  class="relative overflow-hidden"
+  data-carousel-autoplay
+  data-carousel-interval="4000"
+  data-carousel-loop
+  data-carousel-slides-to-scroll="1"
+  data-carousel-slides-to-scroll-lg="3"
+&gt;
+  &lt;div data-carousel-track class="flex"&gt;
+    {{{#array {"field":"List","schema":[{"field":"header","type":"text"}],"value":[{"header":"One"},{"header":"Two"},{"header":"Three"},{"header":"Four"}]}}}}
+      &lt;div class="shrink-0 min-w-0 flex-[0_0_100%] lg:flex-[0_0_33.333%] p-4"&gt;
+        &lt;div class="bg-white shadow rounded p-6 h-40 flex items-center justify-center"&gt;
+          {{item.header}}
+        &lt;/div&gt;
+      &lt;/div&gt;
+    {{{/array}}}
+  &lt;/div&gt;
+
+  &lt;button type="button" data-carousel-prev class="absolute left-2 top-1/2 -translate-y-1/2 p-2 bg-black/60 text-white rounded-full"&gt;‹&lt;/button&gt;
+  &lt;button type="button" data-carousel-next class="absolute right-2 top-1/2 -translate-y-1/2 p-2 bg-black/60 text-white rounded-full"&gt;›&lt;/button&gt;
+  &lt;div data-carousel-dots class="mt-3 flex justify-center gap-2"&gt;&lt;/div&gt;
+&lt;/div&gt;</code></pre>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Required Markup
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>[data-carousel]</code> is the root element.</div>
+                      <div><code>[data-carousel-track]</code> is the Embla container and should be <code>display:flex</code>.</div>
+                      <div>Each slide should be <code>shrink-0</code> with an explicit basis (for example <code>flex-[0_0_100%]</code>).</div>
+                      <div>Keep <code>overflow-hidden</code> on the root, not the track.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Supported Data Attributes
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>data-carousel-autoplay</code> enables autoplay (off by default).</div>
+                      <div><code>data-carousel-interval="MS"</code> autoplay delay in ms (default <code>5000</code>).</div>
+                      <div><code>data-carousel-loop</code> enables looping.</div>
+                      <div><code>data-carousel-transition="fade"</code> uses Embla Fade plugin.</div>
+                      <div><code>data-carousel-fade-duration="MS"</code> fade duration in ms (default <code>200</code>).</div>
+                      <div><code>data-carousel-no-pause</code> keeps autoplay running through hover/interaction.</div>
+                      <div><code>data-carousel-slides-to-scroll="N"</code> base slidesToScroll (default <code>1</code>).</div>
+                      <div><code>data-carousel-slides-to-scroll-md="N"</code> at <code>min-width: 768px</code>.</div>
+                      <div><code>data-carousel-slides-to-scroll-lg="N"</code> at <code>min-width: 1024px</code>.</div>
+                      <div><code>data-carousel-slides-to-scroll-xl="N"</code> at <code>min-width: 1280px</code>.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Behavior Notes
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>When <code>loop</code> is off, runtime uses <code>containScroll: "trimSnaps"</code>.</div>
+                      <div>Prev/next controls are optional; in loop mode edge clicks wrap manually.</div>
+                      <div>Dots are generated from Embla snap points, not raw slide count.</div>
+                      <div>Breakpoints can change snap count, so dots/buttons are rebuilt on <code>reInit</code>.</div>
+                      <div>Carousels are initialized once per root and tagged with <code>data-embla="true"</code>.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Common Patterns
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>&lt;!-- Single-slide fade --&gt;
+&lt;div data-carousel data-carousel-transition="fade" data-carousel-fade-duration="800"&gt;...&lt;/div&gt;
+
+&lt;!-- Multi-up desktop paging by 3 --&gt;
+&lt;div data-carousel data-carousel-slides-to-scroll="1" data-carousel-slides-to-scroll-lg="3"&gt;...&lt;/div&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">
+                  <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 classes to HTML elements in CMS blocks to trigger scroll reveal animations automatically.
+                    </p>
+                  </section>
+
+                  <section class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Quick Start
+                    </h3>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>&lt;div class="sr sr-up sr-delay-150 sr-dur-800 sr-dist-30"&gt;
+  I animate on scroll
+&lt;/div&gt;</code></pre>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>&lt;div class="sr-group sr-up sr-interval-120 sr-dur-700"&gt;
+  &lt;div class="sr-item"&gt;Item 1&lt;/div&gt;
+  &lt;div class="sr-item"&gt;Item 2&lt;/div&gt;
+  &lt;div class="sr-item"&gt;Item 3&lt;/div&gt;
+&lt;/div&gt;</code></pre>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Required Base Classes
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr</code>: reveal this element.</div>
+                      <div><code>sr-group</code>: reveal/stagger a group of children with shared options.</div>
+                      <div><code>sr-item</code>: child element inside <code>sr-group</code>.</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Direction / Origin
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-up</code>, <code>sr-down</code>, <code>sr-left</code>, <code>sr-right</code></div>
+                      <div><code>sr-origin-top</code>, <code>sr-origin-right</code>, <code>sr-origin-bottom</code>, <code>sr-origin-left</code></div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Timing
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-delay-200</code> (ms)</div>
+                      <div><code>sr-dur-700</code> or <code>sr-duration-700</code> (ms)</div>
+                      <div><code>sr-interval-120</code> or <code>sr-stagger-120</code> (ms between items)</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Movement / Transform
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-dist-24</code> or <code>sr-distance-24</code> (px when numeric)</div>
+                      <div><code>sr-opacity-0.2</code></div>
+                      <div><code>sr-scale-0.9</code></div>
+                      <div><code>sr-rotate-10</code>, <code>sr-rotate-x-15</code>, <code>sr-rotate-y-15</code>, <code>sr-rotate-z-15</code></div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      View Trigger
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-view-factor-0.2</code> or <code>sr-viewfactor-0.2</code></div>
+                      <div><code>sr-view-offset-top-80</code>, <code>sr-view-offset-right-40</code>, <code>sr-view-offset-bottom-80</code>, <code>sr-view-offset-left-40</code></div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Behavior
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-reset</code>, <code>sr-no-reset</code></div>
+                      <div><code>sr-cleanup</code>, <code>sr-no-cleanup</code></div>
+                      <div><code>sr-use-delay-always</code>, <code>sr-use-delay-once</code>, <code>sr-use-delay-onload</code></div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Device Targeting
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-no-mobile</code>, <code>sr-no-desktop</code></div>
+                      <div><code>sr-mobile-true</code>, <code>sr-mobile-false</code></div>
+                      <div><code>sr-desktop-true</code>, <code>sr-desktop-false</code></div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Easing
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-ease-linear</code>, <code>sr-ease-in</code>, <code>sr-ease-out</code>, <code>sr-ease-in-out</code></div>
+                      <div><code>sr-easing-...</code> for advanced raw tokens</div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Container Targeting (Advanced)
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-container-id-main</code></div>
+                      <div><code>sr-container-class-scroll-area</code></div>
+                      <div><code>sr-container-tag-main</code></div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Defaults
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>origin: bottom</code></div>
+                      <div><code>distance: 24px</code></div>
+                      <div><code>duration: 700</code></div>
+                      <div><code>easing: cubic-bezier(0.5, 0, 0, 1)</code></div>
+                      <div><code>viewFactor: 0.15</code></div>
+                      <div><code>reset: false</code></div>
+                      <div><code>cleanup: false</code></div>
+                      <div><code>mobile: true</code></div>
+                      <div><code>desktop: true</code></div>
+                    </div>
+                  </section>
+
+                  <section class="space-y-3">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Callback Hooks (Advanced)
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div><code>sr-before-reveal-{key}</code></div>
+                      <div><code>sr-after-reveal-{key}</code></div>
+                      <div><code>sr-before-reset-{key}</code></div>
+                      <div><code>sr-after-reset-{key}</code></div>
+                    </div>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>window.__srCallbacks = {
+  myHook: (el) => { console.log('revealed', el) },
+}</code></pre>
+                    <pre v-pre class="rounded-md bg-muted p-3 text-xs overflow-auto"><code>&lt;div class="sr sr-up sr-after-reveal-myHook"&gt;...&lt;/div&gt;</code></pre>
+                  </section>
+
+                  <section class="space-y-2">
+                    <h3 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                      Best Practices
+                    </h3>
+                    <div class="text-sm text-foreground space-y-1">
+                      <div>Always include <code>sr</code> for single elements.</div>
+                      <div>For staggered lists, use <code>sr-group</code> on parent and <code>sr-item</code> on children.</div>
+                      <div>Keep class names lowercase.</div>
+                      <div>Prefer <code>sr-ease-*</code> presets unless you need advanced easing.</div>
+                    </div>
+                  </section>
+                </div>
+              </div>
+            </TabsContent>
+          </Tabs>
+        </div>
+      </SheetContent>
+    </Sheet>
     <Sheet
       v-model:open="state.jsonEditorOpen"
     >