@scaleflex/template-builder 0.1.1

package/src/react.ts

@@ -0,0 +1,223 @@
+import {
+  createElement,
+  forwardRef,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  type CSSProperties,
+  type ReactElement,
+} from 'react'
+import './define'
+import type { SfxTemplateBuilder } from './template-builder'
+import type { TemplateBuilderSaveDetail } from './template-builder'
+import type { BuilderDirtyData, BuilderErrorData, BuilderTheme } from './protocol'
+
+/**
+ * Hub session — the full-featured credential.
+ */
+export interface TemplateBuilderSessionAuth {
+  sassKey: string
+  sessionUuid: string
+  companyUuid?: string
+  projectUuid?: string
+  secTemplate?: never
+}
+
+/**
+ * Filerobot security template — a guest credential for hosts that have no Hub
+ * session to hand over. `stateless` is required rather than merely implied:
+ * the app takes a security template on the stateless embed route only, so the
+ * combination is a compile-time error instead of a runtime one.
+ *
+ * `companyUuid` / `projectUuid` are absent by design — they name a Hub project
+ * that cannot be looked up without a session.
+ */
+export interface TemplateBuilderSecTemplateAuth {
+  secTemplate: string
+  stateless: true
+  sassKey?: never
+  sessionUuid?: never
+  companyUuid?: never
+  projectUuid?: never
+}
+
+export interface TemplateBuilderBaseProps {
+  baseUrl: string
+  token: string
+  templateId?: string
+  mode?: 'inline' | 'modal'
+  /** Hand the template in and take it back out instead of using the DAM. */
+  stateless?: boolean
+  /** Stateless mode: the template to edit, as `.fdt` XML. */
+  content?: string
+  /** Stateless mode: display name for the editor header. */
+  templateName?: string
+  /**
+   * Stateless mode: the `template_query` to open on — the value handed back on
+   * save. Reopens the template on the same layout and variable values; empty
+   * falls back to the XML's own `default=` attributes.
+   */
+  templateQuery?: string
+  /** Accent colour for the editor chrome, as `#rgb` / `#rrggbb`. */
+  brandColor?: string
+  /** Colour scheme for the editor chrome. */
+  theme?: BuilderTheme
+  readyTimeout?: number
+  className?: string
+  style?: CSSProperties
+  onReady?: () => void
+  onOpen?: () => void
+  onClose?: () => void
+  /**
+   * Fired on save. In stateless mode the detail carries the edited `content`
+   * for you to persist; otherwise it reports the uuid the app uploaded to.
+   *
+   * In stateless mode the outcome is reported back to the editor: return (or
+   * resolve to) `false`, or throw, and the editor restores its unsaved-changes
+   * flag and tells the user the save failed. Anything else counts as persisted.
+   */
+  onSave?: (
+    data: TemplateBuilderSaveDetail,
+  ) => void | boolean | Promise<void | boolean>
+  onError?: (data: BuilderErrorData) => void
+  /**
+   * Stateless mode: unsaved-changes flag changed. Use it to prompt before
+   * swapping `content`, which discards in-progress edits.
+   */
+  onDirtyChange?: (data: BuilderDirtyData) => void
+}
+
+export type TemplateBuilderProps = TemplateBuilderBaseProps &
+  (TemplateBuilderSessionAuth | TemplateBuilderSecTemplateAuth)
+
+/**
+ * React wrapper around `<sfx-template-builder>`. Props are assigned as
+ * element properties via ref (works on React 18 and 19 alike); callbacks
+ * subscribe to the element's CustomEvents.
+ *
+ * Forwards a ref to the underlying element, which is the only way to reach the
+ * imperative API — `open()` in particular, without which `mode="modal"` can
+ * never be shown:
+ *
+ * ```tsx
+ * const builder = useRef<SfxTemplateBuilder>(null)
+ * <TemplateBuilder ref={builder} mode="modal" … />
+ * <button onClick={() => builder.current?.open('tpl-1')}>Edit</button>
+ * ```
+ *
+ * `forwardRef` rather than a plain `ref` prop: React 19 accepts the latter for
+ * function components, React 18 does not, and both are supported peers.
+ */
+export const TemplateBuilder = forwardRef<
+  SfxTemplateBuilder,
+  TemplateBuilderProps
+>(function TemplateBuilder(props, forwardedRef): ReactElement {
+  const {
+    className,
+    style,
+    onReady,
+    onOpen,
+    onClose,
+    onSave,
+    onError,
+    onDirtyChange,
+    ...config
+  } = props
+  const ref = useRef<SfxTemplateBuilder>(null)
+
+  // Hand the same element out to the caller without giving up the internal ref
+  // the effects below rely on.
+  useImperativeHandle(forwardedRef, () => ref.current as SfxTemplateBuilder, [])
+
+  // Assign config before paint so the iframe doesn't first mount with defaults.
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (!el) return
+    el.baseUrl = config.baseUrl
+    el.token = config.token
+    el.sassKey = config.sassKey ?? ''
+    el.sessionUuid = config.sessionUuid ?? ''
+    el.secTemplate = config.secTemplate ?? ''
+    el.companyUuid = config.companyUuid ?? ''
+    el.projectUuid = config.projectUuid ?? ''
+    el.templateId = config.templateId ?? ''
+    el.mode = config.mode ?? 'inline'
+    el.stateless = config.stateless ?? false
+    el.templateName = config.templateName ?? ''
+    el.templateQuery = config.templateQuery ?? ''
+    el.brandColor = config.brandColor ?? ''
+    el.theme = config.theme ?? ''
+    // 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.
+    el.content = config.content ?? ''
+    if (config.readyTimeout !== undefined) el.readyTimeout = config.readyTimeout
+  }, [
+    config.baseUrl,
+    config.token,
+    config.sassKey,
+    config.sessionUuid,
+    config.secTemplate,
+    config.companyUuid,
+    config.projectUuid,
+    config.templateId,
+    config.mode,
+    config.stateless,
+    config.content,
+    config.templateName,
+    config.templateQuery,
+    config.brandColor,
+    config.theme,
+    config.readyTimeout,
+  ])
+
+  // 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 —
+  // making a mount-time error unobservable from React. This effect is declared
+  // after the config one, so it still runs once the config is assigned.
+  useLayoutEffect(() => {
+    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
+      el.addEventListener(name, listener)
+      subs.push([name, listener])
+    }
+    on('ready', onReady)
+    on('open', onOpen)
+    on('close', onClose)
+    on('error', onError)
+    on('dirtychange', 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])
+    }
+
+    return () => {
+      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 })
+})