@scaleflex/template-builder 0.1.1 → 0.4.0

package/src/index.ts

@@ -5,5 +5,7 @@ export {
   type TemplateBuilderStatus,
   type TemplateBuilderEventMap,
   type TemplateBuilderSaveDetail,
+  type StoredTemplate,
+  type DamStoreAuth,
 } from './template-builder'
 export * from './protocol'

package/src/protocol.ts

@@ -9,7 +9,7 @@
 // so older widgets keep working against newer app deployments and vice versa.
 // ---------------------------------------------------------------------------
 
-export const PROTOCOL_VERSION = 2
+export const PROTOCOL_VERSION = 3
 
 // App → embedder ------------------------------------------------------------
 
@@ -195,6 +195,96 @@ export interface HostLoadMessage {
   data: HostLoadData
 }
 
+/**
+ * An empty `.fdt` document: no layouts, no layers, no variables. What the
+ * widget sends as `HOST_LOAD` content when the host asked for a new template
+ * (`new-template`) instead of supplying one, so starting from scratch costs a
+ * host no knowledge of the template format.
+ *
+ * The editor opens on its empty state — "No layouts yet. Click + Add to create
+ * one." — and the user picks the canvas size there. Save is refused until a
+ * layout exists, and hands back a fully-formed document serialized by the app,
+ * not this skeleton.
+ *
+ * Sent as ordinary `HOST_LOAD` content rather than a new message so it works
+ * against app deployments that predate this widget version: the document is
+ * the whole signal, and every app that can parse a template can parse this.
+ *
+ * `version` tracks the app's `TEMPLATE_VERSION` for the benefit of whoever
+ * reads this next: nothing consumes it. The parser never looks at it, and the
+ * backend never sees this document — the app refuses to save a template with
+ * no layouts, so what reaches the render pipeline was re-serialized by the app
+ * with a layout present. A widget lagging the app by a version still loads.
+ * `design-templates` pins the pair in
+ * `src/lib/xml/__tests__/blank-template.test.ts`.
+ */
+export const BLANK_TEMPLATE_XML =
+  '<?xml version="1.0" encoding="UTF-8"?>\n' +
+  '<template><templateInfo><version>0.3</version></templateInfo>' +
+  '<rootStack/><layouts/><variables/></template>'
+
+/**
+ * Host-supplied editor configuration (protocol v3). Sent once the app reports
+ * `BUILDER_READY`, and again whenever the host changes it.
+ *
+ * Separate from `HOST_LOAD` because it is not per-template and because it must
+ * also reach DAM-backed embeds, which never receive a `HOST_LOAD` at all — the
+ * app loads those templates itself.
+ *
+ * Purely additive: an app deployment that predates this message ignores it and
+ * behaves exactly as before, so a newer widget stays compatible with an older
+ * app. Held to the same origin bar as `HOST_LOAD`.
+ */
+export const HOST_CONFIG = 'design-templates:host:config'
+
+/**
+ * One field of a host-supplied metadata model, offered in the editor as the
+ * "Custom metadata" value source.
+ *
+ * The model is a vocabulary, not data: it names the fields the host can fill at
+ * render time, so an author can bind a variable to `sku` rather than having to
+ * remember that the variable's slug happens to mean the SKU. No value travels
+ * with it — the host substitutes one by putting `$slug=value` in the render
+ * query, exactly as it would for a free-text variable.
+ *
+ * This is what makes named fields workable in `secTemplate` / stateless embeds,
+ * where the Hub project model (and with it the "File metadata" source) is
+ * unavailable.
+ */
+export interface CustomMetadataField {
+  /**
+   * Stable identifier stored in the template as `custom_ckey`. The host's own
+   * key for the field — the app never resolves it against anything.
+   */
+  key: string
+  /** Label shown in the editor's field picker. Falls back to `key` when empty. */
+  title?: string
+  /** Optional section header, used to group fields in the picker. */
+  group?: string
+}
+
+export interface HostConfigData {
+  /**
+   * Metadata model offered as the "Custom metadata" value source. Omitted or
+   * empty hides that source in the editor, so a host that sends nothing sees
+   * the two sources it always had.
+   */
+  customMetadata?: CustomMetadataField[]
+  /**
+   * Display name for the custom-metadata value source in the editor's UI
+   * (source dropdowns, properties-panel section). Defaults to "Custom
+   * metadata"; a host can rename it after its own domain — e.g. "External
+   * metadata" or "Product attributes". Pure wording: the stored template is
+   * unaffected.
+   */
+  customMetadataLabel?: string
+}
+
+export interface HostConfigMessage {
+  type: typeof HOST_CONFIG
+  data: HostConfigData
+}
+
 /**
  * Stateless mode only (protocol v2). Reports whether the host managed to
  * persist the content it received in `BUILDER_CONTENT`.
@@ -219,7 +309,7 @@ export interface HostSavedMessage {
   data: HostSavedData
 }
 
-export type HostMessage = HostLoadMessage | HostSavedMessage
+export type HostMessage = HostLoadMessage | HostSavedMessage | HostConfigMessage
 
 // Embed URL contract ----------------------------------------------------------
 

package/src/react.ts

@@ -10,7 +10,12 @@ import {
 import './define'
 import type { SfxTemplateBuilder } from './template-builder'
 import type { TemplateBuilderSaveDetail } from './template-builder'
-import type { BuilderDirtyData, BuilderErrorData, BuilderTheme } from './protocol'
+import type {
+  BuilderDirtyData,
+  BuilderErrorData,
+  BuilderTheme,
+  CustomMetadataField,
+} from './protocol'
 
 /**
  * Hub session — the full-featured credential.
@@ -50,6 +55,13 @@ export interface TemplateBuilderBaseProps {
   stateless?: boolean
   /** Stateless mode: the template to edit, as `.fdt` XML. */
   content?: string
+  /**
+   * Stateless mode: open on a new, empty template instead of supplying
+   * `content`. The widget provides the blank document, the user picks the
+   * canvas size in the editor, and `onSave` receives a complete `.fdt` to
+   * store. Ignored when `content` is set.
+   */
+  newTemplate?: boolean
   /** Stateless mode: display name for the editor header. */
   templateName?: string
   /**
@@ -62,6 +74,39 @@ export interface TemplateBuilderBaseProps {
   brandColor?: string
   /** Colour scheme for the editor chrome. */
   theme?: BuilderTheme
+  /**
+   * Metadata model offered in the editor as the "Custom metadata" value source
+   * — names only, no values. Omit it and the source is not offered.
+   *
+   * Compared by identity, like every other prop here, so a freshly built array
+   * counts as a change. Nothing is re-sent to the editor over it — the element
+   * de-dupes by value — but hoisting or memoising the array avoids the churn.
+   */
+  customMetadata?: CustomMetadataField[]
+  /**
+   * Display name for the custom-metadata value source in the editor's UI —
+   * e.g. "External metadata". Wording only: the stored template is unaffected.
+   * Empty uses the editor's default, "Custom metadata".
+   */
+  customMetadataLabel?: string
+  /**
+   * Stateless only: store each save in Filerobot too, so the CDN can render
+   * it. `onSave`'s detail then carries `stored: { uuid, url }` next to the raw
+   * `content` — or `storeError` when the copy failed.
+   */
+  damStore?: boolean
+  /**
+   * Folder new templates land in under `damStore` when the template id names
+   * no existing DAM file (an existing file's own folder always wins).
+   */
+  storeFolder?: string
+  /**
+   * `damStore`: the `stored.uuid` a previous session's save reported for THIS
+   * document, so re-saves after a reload resolve to (and version) the copy
+   * that already exists instead of erroring on unchanged content or starting
+   * a fresh file. Per-document — pass it with the content it belongs to.
+   */
+  storedUuid?: string
   readyTimeout?: number
   className?: string
   style?: CSSProperties
@@ -147,6 +192,12 @@ export const TemplateBuilder = forwardRef<
     el.templateQuery = config.templateQuery ?? ''
     el.brandColor = config.brandColor ?? ''
     el.theme = config.theme ?? ''
+    el.newTemplate = config.newTemplate ?? false
+    el.customMetadata = config.customMetadata ?? []
+    el.customMetadataLabel = config.customMetadataLabel ?? ''
+    el.damStore = config.damStore ?? false
+    el.storeFolder = config.storeFolder ?? '/'
+    el.storedUuid = config.storedUuid ?? ''
     // Assigned last: the element sends content to the app as soon as it has
     // both a request and a value, so the id, name and query must already be
     // set — all four ship as one message.
@@ -164,13 +215,37 @@ export const TemplateBuilder = forwardRef<
     config.mode,
     config.stateless,
     config.content,
+    config.newTemplate,
     config.templateName,
     config.templateQuery,
     config.brandColor,
     config.theme,
+    config.customMetadata,
+    config.customMetadataLabel,
+    config.damStore,
+    config.storeFolder,
+    config.storedUuid,
     config.readyTimeout,
   ])
 
+  // The callbacks the listeners read at event time. A ref rather than effect
+  // dependencies: listeners are attached once per element (below), so a parent
+  // re-render swapping handler identities costs nothing — and, decisively, the
+  // listeners are still attached during the element's disconnect-time flush of
+  // pending dam-store saves, which a resubscribe-per-change cleanup would have
+  // already torn down.
+  const handlers = useRef({
+    onReady,
+    onOpen,
+    onClose,
+    onSave,
+    onError,
+    onDirtyChange,
+  })
+  useLayoutEffect(() => {
+    handlers.current = { onReady, onOpen, onClose, onSave, onError, onDirtyChange }
+  })
+
   // Layout effect, not passive: the element reports config errors (e.g.
   // `invalid-base-url`) in a microtask queued during this same commit, and a
   // passive effect would subscribe only after that microtask has fired —
@@ -180,43 +255,61 @@ export const TemplateBuilder = forwardRef<
     const el = ref.current
     if (!el) return
     const subs: Array<[string, EventListener]> = []
-    const on = (name: string, handler?: (detail: never) => void) => {
-      if (!handler) return
-      const listener = ((e: CustomEvent) => handler(e.detail as never)) as EventListener
+    const on = (
+      name: string,
+      pick: (h: typeof handlers.current) => ((detail: never) => void) | undefined,
+    ) => {
+      const listener = ((e: CustomEvent) =>
+        pick(handlers.current)?.(e.detail as never)) as EventListener
       el.addEventListener(name, listener)
       subs.push([name, listener])
     }
-    on('ready', onReady)
-    on('open', onOpen)
-    on('close', onClose)
-    on('error', onError)
-    on('dirtychange', onDirtyChange)
+    on('ready', (h) => h.onReady)
+    on('open', (h) => h.onOpen)
+    on('close', (h) => h.onClose)
+    on('error', (h) => h.onError)
+    on('dirtychange', (h) => h.onDirtyChange)
 
     // `save` is not just re-emitted: in stateless mode the handler's outcome
     // is acked back, so a failed write on the host side doesn't leave the
     // editor showing the template as saved. `confirmSave` no-ops in DAM mode.
-    if (onSave) {
-      const listener = ((e: CustomEvent<TemplateBuilderSaveDetail>) => {
-        // Wrapped in a promise so a synchronous throw is handled like a
-        // rejection, and a sync `false` like a resolved one.
-        Promise.resolve()
-          .then(() => onSave(e.detail))
-          .then((result) => el.confirmSave(result !== false))
-          .catch((err) => {
-            // No message: an internal error string is not something to put in
-            // front of the end user. The editor uses its own wording.
-            console.error('[sfx-template-builder] onSave failed:', err)
-            el.confirmSave(false)
-          })
-      }) as EventListener
-      el.addEventListener('save', listener)
-      subs.push(['save', listener])
-    }
+    const saveListener = ((e: CustomEvent<TemplateBuilderSaveDetail>) => {
+      const onSaveNow = handlers.current.onSave
+      if (!onSaveNow) return
+      // Wrapped in a promise so a synchronous throw is handled like a
+      // rejection, and a sync `false` like a resolved one.
+      Promise.resolve()
+        .then(() => onSaveNow(e.detail))
+        .then((result) => el.confirmSave(result !== false))
+        .catch((err) => {
+          // No message: an internal error string is not something to put in
+          // front of the end user. The editor uses its own wording.
+          console.error('[sfx-template-builder] onSave failed:', err)
+          el.confirmSave(false)
+        })
+    }) as EventListener
+    el.addEventListener('save', saveListener)
+    subs.push(['save', saveListener])
 
     return () => {
+      // React runs this cleanup BEFORE it detaches the node, so the element's
+      // own disconnect-time flush of in-flight dam-store saves would fire
+      // after every listener is gone — and the raw save would be silently
+      // lost. Flushing here, while the listeners are still attached, hands
+      // those saves (with `storeError` in place of the links) to `onSave`
+      // first. A no-op when nothing is pending, including StrictMode's
+      // simulated unmount at mount time.
+      //
+      // Guarded: when an older CDN bundle registered the tag first, `el` is
+      // that bundle's class and lacks the method — every other new-API use
+      // degrades silently via property assignment, and unmount must not be
+      // the one path that throws.
+      if (typeof el.flushPendingSaves === 'function') {
+        el.flushPendingSaves('widget removed before the rendering copy completed')
+      }
       for (const [name, listener] of subs) el.removeEventListener(name, listener)
     }
-  }, [onReady, onOpen, onClose, onSave, onError, onDirtyChange])
+  }, [])
 
   // eslint-disable-next-line react-hooks/refs -- ref is forwarded as a prop, not read during render
   return createElement('sfx-template-builder', { ref, class: className, style })