@scaleflex/template-builder 0.1.1

package/src/template-builder.ts

@@ -0,0 +1,599 @@
+import { LitElement, html, css, nothing, type PropertyValues } from 'lit'
+import { property, state } from 'lit/decorators.js'
+import {
+  BUILDER_CLOSE,
+  BUILDER_CONTENT,
+  BUILDER_CONTENT_REQUEST,
+  BUILDER_DIRTY,
+  BUILDER_ERROR,
+  BUILDER_OPEN,
+  BUILDER_READY,
+  BUILDER_SAVE,
+  EMBED_PARAMS,
+  EMBED_ROUTE,
+  HOST_LOAD,
+  HOST_SAVED,
+  builderRoute,
+  type BuilderContentData,
+  type BuilderContentMessage,
+  type BuilderDirtyData,
+  type BuilderDirtyMessage,
+  type BuilderErrorData,
+  type BuilderErrorMessage,
+  type BuilderSaveData,
+  type BuilderSaveMessage,
+  type BuilderTheme,
+} from './protocol'
+
+export type TemplateBuilderStatus = 'idle' | 'loading' | 'ready' | 'error'
+
+/**
+ * `save` payload. Which variant arrives follows the mode the element was
+ * configured in:
+ * - DAM-backed (default) — `BuilderSaveData`; the app uploaded the template and
+ *   reports the resulting `uuid`.
+ * - `stateless` — `BuilderContentData`; nothing was stored, and `content` is
+ *   the edited template for the host to persist.
+ */
+export type TemplateBuilderSaveDetail =
+  | BuilderSaveData
+  | BuilderContentData
+  | undefined
+
+export interface TemplateBuilderEventMap {
+  ready: CustomEvent<void>
+  open: CustomEvent<void>
+  close: CustomEvent<void>
+  save: CustomEvent<TemplateBuilderSaveDetail>
+  error: CustomEvent<BuilderErrorData>
+  dirtychange: CustomEvent<BuilderDirtyData>
+}
+
+/**
+ * `<sfx-template-builder>` — embeds the Filerobot design-templates builder.
+ *
+ * The element owns an iframe pointed at a design-templates-app deployment,
+ * passes auth via URL params (converted to cookies by the app's proxy), and
+ * translates the app's postMessage protocol into DOM CustomEvents:
+ * `ready`, `open`, `close`, `save`, `error`.
+ *
+ * Required: `base-url`, `token`, and one of two credentials:
+ * - `sass-key` + `session-uuid` — a Hub session. Full features.
+ * - `sec-template` — a Filerobot security-template key. No Hub session needed,
+ *   but it only works with `stateless`, and Hub-project features (metadata
+ *   fields, regional variants, project branding) come back empty.
+ *
+ * In `inline` mode the editor loads as soon as config is complete and fills
+ * the host element (size it explicitly). In `modal` mode nothing renders
+ * until `open()` is called; the editor then covers the viewport.
+ *
+ * Two ways to supply the template:
+ * - **DAM-backed** (default) — set `template-id` to a Filerobot file uuid. The
+ *   app loads and saves it itself, and `save` reports the new uuid.
+ * - **Stateless** — set `stateless` and assign `content`. The element sends the
+ *   template into the editor over postMessage and `save` returns the edited
+ *   document; nothing is stored on the Scaleflex side, and `template-id` is
+ *   just an opaque string echoed back. Rendering, fonts and asset browsing
+ *   still use the session's Filerobot tenant.
+ *
+ * `brand-color` and `theme` restyle the editor chrome to match the host page.
+ * They do not touch the rendered template — its colours live in the document.
+ */
+export class SfxTemplateBuilder extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      position: relative;
+    }
+    :host([mode='modal']) {
+      display: contents;
+    }
+    .overlay {
+      position: fixed;
+      inset: 0;
+      z-index: 2147483000;
+      background: rgba(0, 0, 0, 0.55);
+      display: flex;
+    }
+    .stage {
+      position: relative;
+      flex: 1;
+      display: flex;
+    }
+    iframe {
+      border: 0;
+      flex: 1;
+      width: 100%;
+      height: 100%;
+    }
+    .spinner {
+      position: absolute;
+      inset: 0;
+      margin: auto;
+      width: 32px;
+      height: 32px;
+      border: 3px solid rgba(128, 128, 128, 0.3);
+      border-top-color: currentColor;
+      border-radius: 50%;
+      animation: sfx-tb-spin 0.8s linear infinite;
+      pointer-events: none;
+    }
+    @keyframes sfx-tb-spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+  `
+
+  /** Origin + optional path prefix of the design-templates-app deployment. */
+  @property({ attribute: 'base-url' }) baseUrl = ''
+  /** Filerobot token (`ftoken`). */
+  @property() token = ''
+  @property({ attribute: 'sass-key' }) sassKey = ''
+  @property({ attribute: 'session-uuid' }) sessionUuid = ''
+  /**
+   * Filerobot security-template key — the alternative to `sass-key` +
+   * `session-uuid` for hosts with no Hub session to hand over. Requires
+   * `stateless`, and degrades the features that come from the Hub project
+   * model (metadata fields, regional variants, project branding). When set it
+   * wins: neither `sass-key` nor `session-uuid` is passed to the app.
+   */
+  @property({ attribute: 'sec-template' }) secTemplate = ''
+  @property({ attribute: 'company-uuid' }) companyUuid = ''
+  @property({ attribute: 'project-uuid' }) projectUuid = ''
+  /**
+   * DAM-backed mode: the Filerobot uuid to load; empty opens the new-template
+   * flow. Stateless mode: an opaque host id, echoed back on `save`.
+   */
+  @property({ attribute: 'template-id' }) templateId = ''
+  @property({ reflect: true }) mode: 'inline' | 'modal' = 'inline'
+  /**
+   * Hand the template in and take it back out instead of letting the app read
+   * and write Filerobot. Requires `content`.
+   */
+  @property({ type: Boolean, reflect: true }) stateless = false
+  /**
+   * Stateless mode: the template to edit, as `.fdt` XML. Property only — templates
+   * routinely exceed practical attribute/URL sizes, so it is never reflected.
+   * Assigning a different value while open loads it into the running editor.
+   */
+  @property({ attribute: false }) content = ''
+  /** Stateless mode: display name for the editor header. */
+  @property({ attribute: 'template-name' }) templateName = ''
+  /**
+   * Stateless mode: the `template_query` to open on — the value handed back in
+   * the `save` payload. Pass back what you stored and the editor reopens on the
+   * same layout and variable values; leave it empty and the render falls back
+   * to the XML's own `default=` attributes.
+   */
+  @property({ attribute: 'template-query' }) templateQuery = ''
+  /**
+   * Accent colour for the editor chrome, as `#rgb` / `#rrggbb`. The app derives
+   * buttons, focus rings and highlights from it. Empty keeps the Scaleflex
+   * default. Themes the editor UI only — never the rendered template, whose
+   * colours live in the document.
+   */
+  @property({ attribute: 'brand-color' }) brandColor = ''
+  /** Colour scheme for the editor chrome. Empty leaves the app's own default. */
+  @property() theme: BuilderTheme | '' = ''
+  /** Ms to wait for the app's ready signal before emitting `error`. 0 disables. */
+  @property({ type: Number, attribute: 'ready-timeout' }) readyTimeout = 20000
+
+  @state() private _status: TemplateBuilderStatus = 'idle'
+  @state() private _open = false
+  @state() private _src = ''
+
+  private _handshakeTimer?: number
+  /**
+   * The app asked for content. Tracked because the request and the `content`
+   * assignment race: whichever lands second triggers the send.
+   */
+  private _contentRequested = false
+  /**
+   * Identity of the template already delivered, so an unrelated re-render does
+   * not resend it and discard the user's edits. Covers the id and name too, not
+   * just the content: two host records can hold byte-identical templates, and
+   * resending only on content change would leave the app echoing a stale id
+   * back on save.
+   */
+  private _sentKey?: string
+  /**
+   * The `baseUrl` value already reported as unparseable. `_computeSrc()` runs
+   * on every update cycle, so without this a bad URL re-emits `error` forever —
+   * once per render, since the error status it sets is already in place after
+   * the first.
+   */
+  private _reportedBadBaseUrl?: string
+  /**
+   * Whether the sec-template-without-stateless mistake has been reported. Same
+   * reason as `_reportedBadBaseUrl`: `_computeSrc()` runs every update cycle
+   * and the error status it sets is already in place after the first pass.
+   */
+  private _reportedStatelessRequired = false
+
+  @state() private _isDirty = false
+
+  get status(): TemplateBuilderStatus {
+    return this._status
+  }
+
+  /**
+   * Stateless mode: whether the editor holds edits that have not been handed
+   * back yet. Check this before calling `load()` — a swap discards them.
+   * Always false in DAM-backed mode, where the app owns saving.
+   */
+  get isDirty(): boolean {
+    return this._isDirty
+  }
+
+  /** Open the editor (loads the iframe). Optionally switch template first. */
+  open(templateId?: string): void {
+    if (templateId !== undefined) this.templateId = templateId
+    this._open = true
+  }
+
+  /** Close the editor and unload the iframe. Does not emit `close`. */
+  close(): void {
+    this._open = false
+  }
+
+  /**
+   * Stateless mode: load a template, opening the editor if needed. Equivalent
+   * to assigning `templateId` / `content` / `templateName` and calling `open()`.
+   */
+  load({
+    content,
+    templateId,
+    name,
+    templateQuery,
+  }: {
+    content: string
+    templateId?: string
+    name?: string
+    templateQuery?: string
+  }): void {
+    if (templateId !== undefined) this.templateId = templateId
+    if (name !== undefined) this.templateName = name
+    // Assigned before `content`: all four ship as one HOST_LOAD, and leaving a
+    // previous template's query in place while the new content goes out would
+    // open the new document on the old layout and values.
+    if (templateQuery !== undefined) this.templateQuery = templateQuery
+    this.content = content
+    this._open = true
+  }
+
+  /**
+   * Stateless mode: report back whether a `save` was persisted on your side.
+   *
+   * Optional. The editor clears its unsaved-changes flag as soon as it hands
+   * the content over, so not calling this leaves the previous behaviour intact.
+   * Calling it with `false` is what earns something: the editor restores the
+   * dirty flag and tells the user, rather than showing a failed write as saved.
+   *
+   * No-op outside stateless mode, where the app did the saving and has nothing
+   * to hear back about.
+   */
+  confirmSave(ok: boolean, message?: string): void {
+    if (!this.stateless) return
+    this._postToApp({ type: HOST_SAVED, data: { ok, message } })
+  }
+
+  /**
+   * Whether the inline-implies-open decision has been made. It cannot be made
+   * in `connectedCallback`: frameworks insert the element first and assign
+   * properties afterwards in the same task (the React wrapper does), so at
+   * connect time `mode` may still hold its `'inline'` default — deciding there
+   * flashes a modal's full-viewport overlay open on mount. By the first update
+   * cycle the real value has settled.
+   */
+  private _autoOpenDecided = false
+
+  connectedCallback(): void {
+    super.connectedCallback()
+    window.addEventListener('message', this._onMessage)
+  }
+
+  disconnectedCallback(): void {
+    super.disconnectedCallback()
+    window.removeEventListener('message', this._onMessage)
+    this._clearHandshakeTimer()
+  }
+
+  protected willUpdate(changed: PropertyValues): void {
+    super.willUpdate(changed)
+    if (!this._autoOpenDecided) {
+      this._autoOpenDecided = true
+      if (this.mode === 'inline') this._open = true
+    }
+    const src = this._computeSrc()
+    if (src !== this._src) {
+      this._src = src
+      this._status = src ? 'loading' : 'idle'
+    }
+  }
+
+  protected updated(changed: PropertyValues): void {
+    if (changed.has('_src')) {
+      this._clearHandshakeTimer()
+      // A new document means a new app instance: it has not asked for content
+      // yet, and nothing has been delivered to it.
+      this._contentRequested = false
+      this._sentKey = undefined
+      if (this._isDirty) {
+        this._isDirty = false
+        this._emit('dirtychange', { isDirty: false })
+      }
+      if (this._src) this._startHandshakeTimer()
+    }
+    // Swapping any part of the template on a running editor reloads it. The id
+    // matters as much as the content: a host moving between two identical
+    // templates must not leave the app saving under the previous id.
+    if (
+      changed.has('content') ||
+      changed.has('templateId') ||
+      changed.has('templateName') ||
+      changed.has('templateQuery')
+    ) {
+      this._maybeSendContent()
+    }
+  }
+
+  render() {
+    const frame = this._src
+      ? html`<iframe
+          part="iframe"
+          title="Template builder"
+          src=${this._src}
+          allow="clipboard-read; clipboard-write"
+        ></iframe>`
+      : nothing
+    const spinner =
+      this._status === 'loading'
+        ? html`<div class="spinner" part="spinner"></div>`
+        : nothing
+
+    if (this.mode === 'modal') {
+      return this._open
+        ? html`<div class="overlay" part="overlay">
+            <div class="stage">${frame}${spinner}</div>
+          </div>`
+        : nothing
+    }
+    return html`${frame}${spinner}`
+  }
+
+  private _computeSrc(): string {
+    if (!this._open) return ''
+    if (!this.baseUrl || !this.token) return ''
+    if (this.secTemplate) {
+      // A security template is a guest credential with no user identity behind
+      // it, so the app takes it on the stateless route only. Saying so here
+      // turns a config mistake into a message instead of a login redirect the
+      // host sees as `handshake-timeout`.
+      if (!this.stateless) {
+        if (!this._reportedStatelessRequired) {
+          this._reportedStatelessRequired = true
+          queueMicrotask(() =>
+            this._fail({
+              code: 'invalid-config',
+              message:
+                'sec-template requires stateless mode — the app accepts a ' +
+                'security template on the stateless embed route only.',
+            }),
+          )
+        }
+        return ''
+      }
+      // Cleared on a valid pass so a host that fixes the combination and later
+      // breaks it again is told again, matching `_reportedBadBaseUrl`.
+      this._reportedStatelessRequired = false
+    } else if (!this.sassKey || !this.sessionUuid) {
+      return ''
+    }
+    let url: URL
+    try {
+      // Stateless mode keeps the id out of the URL — it is a host-side value
+      // the app never resolves, and the content arrives by postMessage.
+      const route = this.stateless
+        ? EMBED_ROUTE
+        : builderRoute(this.templateId || undefined)
+      // Resolve relative to the base, not the origin: routes are absolute
+      // paths, and `new URL('/x', 'https://host/app')` would silently drop
+      // the documented path prefix, 404 on subpath deployments, and surface
+      // only as a handshake-timeout.
+      const base = this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`
+      url = new URL(route.replace(/^\//, ''), base)
+    } catch {
+      // Report each bad value once. This runs on every update cycle, and
+      // `_fail` sets a status that is already 'error' by the second pass, so
+      // there is no state change to fall out of the loop on.
+      if (this._reportedBadBaseUrl !== this.baseUrl) {
+        this._reportedBadBaseUrl = this.baseUrl
+        // Emitted from a state-compute path; defer so consumers attached after
+        // this update cycle still receive it.
+        queueMicrotask(() =>
+          this._fail({
+            code: 'invalid-base-url',
+            message: `base-url is not a valid URL: ${this.baseUrl}`,
+          }),
+        )
+      }
+      return ''
+    }
+    this._reportedBadBaseUrl = undefined
+    url.searchParams.set(EMBED_PARAMS.FILEROBOT_TOKEN, this.token)
+    if (this.secTemplate) {
+      // Exclusive with the session credentials: the app reads the mode off
+      // which of the two arrived, and the Hub uuids below name a project it
+      // cannot look up without a session anyway.
+      url.searchParams.set(EMBED_PARAMS.SEC_TEMPLATE, this.secTemplate)
+    } else {
+      url.searchParams.set(EMBED_PARAMS.SASS_KEY, this.sassKey)
+      url.searchParams.set(EMBED_PARAMS.SESSION_UUID, this.sessionUuid)
+      if (this.companyUuid) {
+        url.searchParams.set(EMBED_PARAMS.COMPANY_UUID, this.companyUuid)
+      }
+      if (this.projectUuid) {
+        url.searchParams.set(EMBED_PARAMS.PROJECT_UUID, this.projectUuid)
+      }
+    }
+    if (this.brandColor) {
+      url.searchParams.set(EMBED_PARAMS.BRAND_COLOR, this.brandColor)
+    }
+    if (this.theme) {
+      url.searchParams.set(EMBED_PARAMS.THEME, this.theme)
+    }
+    url.searchParams.set(EMBED_PARAMS.IFRAME, '1')
+    url.searchParams.set(EMBED_PARAMS.EMBED_ORIGIN, window.location.origin)
+    return url.toString()
+  }
+
+  private get _appOrigin(): string | null {
+    try {
+      return new URL(this.baseUrl).origin
+    } catch {
+      return null
+    }
+  }
+
+  private _onMessage = (event: MessageEvent): void => {
+    if (!this._open) return
+    if (!event.origin || event.origin !== this._appOrigin) return
+    const iframe = this.shadowRoot?.querySelector('iframe')
+    if (!iframe) return
+    // Ignore messages from other frames of the same app origin. Strict: a
+    // missing source is not given the benefit of the doubt — the app side
+    // (`readHostLoadMessage`) applies the same rule.
+    if (event.source !== iframe.contentWindow) return
+
+    const msg = event.data as { type?: unknown } | null
+    if (!msg || typeof msg.type !== 'string') return
+
+    switch (msg.type) {
+      case BUILDER_READY:
+      case BUILDER_OPEN:
+        this._clearHandshakeTimer()
+        if (this._status !== 'ready') {
+          this._status = 'ready'
+          this._emit('ready')
+        }
+        if (msg.type === BUILDER_OPEN) this._emit('open')
+        break
+      case BUILDER_SAVE:
+        this._emit('save', (msg as BuilderSaveMessage).data)
+        break
+      case BUILDER_CONTENT_REQUEST:
+        this._contentRequested = true
+        // A fresh request is authoritative: the app is saying it holds no
+        // template. It may have remounted or reloaded inside an unchanged
+        // iframe, so resend even if this content went out already — otherwise
+        // the editor waits on a skeleton forever.
+        this._sentKey = undefined
+        this._maybeSendContent()
+        break
+      case BUILDER_CONTENT: {
+        // Stateless save. Surfaced as `save` so hosts have one event to bind
+        // regardless of mode; the detail shape follows the mode they chose.
+        const data = (msg as BuilderContentMessage).data
+        // The saved document is what the editor now holds. A host that stores
+        // it and echoes it back into `content` — the natural controlled
+        // pattern — must not trigger a HOST_LOAD reload that wipes the
+        // editor's undo history behind a skeleton flash.
+        this._sentKey = this._contentKey(data.content)
+        this._emit('save', data)
+        break
+      }
+      case BUILDER_DIRTY: {
+        const data = (msg as BuilderDirtyMessage).data
+        this._isDirty = !!data?.isDirty
+        this._emit('dirtychange', { isDirty: this._isDirty })
+        break
+      }
+      case BUILDER_CLOSE:
+        this._emit('close')
+        if (this.mode === 'modal') this._open = false
+        break
+      case BUILDER_ERROR:
+        this._fail((msg as BuilderErrorMessage).data ?? { code: 'unknown' })
+        break
+    }
+  }
+
+  /**
+   * Deliver `content` to the app once both sides are ready: it has asked, and
+   * we have something new to give it. Skips a re-send of identical content so
+   * an unrelated re-render can't discard the user's in-progress edits.
+   */
+  private _maybeSendContent(): void {
+    if (!this.stateless || !this._contentRequested || !this.content) return
+
+    const data = {
+      templateId: this.templateId || undefined,
+      content: this.content,
+      name: this.templateName || undefined,
+      templateQuery: this.templateQuery || undefined,
+    }
+    const key = this._contentKey(this.content)
+    if (key === this._sentKey) return
+
+    if (!this._postToApp({ type: HOST_LOAD, data })) return
+    this._sentKey = key
+  }
+
+  /** Identity of a delivered template, as compared against `_sentKey`. */
+  private _contentKey(content: string): string {
+    return JSON.stringify({
+      templateId: this.templateId || undefined,
+      content,
+      name: this.templateName || undefined,
+      templateQuery: this.templateQuery || undefined,
+    })
+  }
+
+  /** Post into the iframe, targeted at the app origin. False if not mounted. */
+  private _postToApp(message: unknown): boolean {
+    const target = this.shadowRoot?.querySelector('iframe')?.contentWindow
+    const appOrigin = this._appOrigin
+    if (!target || !appOrigin) return false
+    target.postMessage(message, appOrigin)
+    return true
+  }
+
+  private _startHandshakeTimer(): void {
+    if (this.readyTimeout <= 0) return
+    this._handshakeTimer = window.setTimeout(() => {
+      this._fail({
+        code: 'handshake-timeout',
+        message:
+          `No ready signal from ${this.baseUrl} within ${this.readyTimeout}ms. ` +
+          'Check that this origin is in the app\'s frame-ancestors allowlist ' +
+          'and that third-party cookies are not blocked.',
+      })
+    }, this.readyTimeout)
+  }
+
+  private _clearHandshakeTimer(): void {
+    if (this._handshakeTimer !== undefined) {
+      window.clearTimeout(this._handshakeTimer)
+      this._handshakeTimer = undefined
+    }
+  }
+
+  private _fail(data: BuilderErrorData): void {
+    this._clearHandshakeTimer()
+    this._status = 'error'
+    this._emit('error', data)
+  }
+
+  private _emit<T>(name: string, detail?: T): void {
+    this.dispatchEvent(
+      new CustomEvent(name, { detail, bubbles: true, composed: true }),
+    )
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'sfx-template-builder': SfxTemplateBuilder
+  }
+}