@scaleflex/template-builder 0.1.1

package/dist/template-builder.d.ts

@@ -0,0 +1,206 @@
+import { LitElement, nothing, type PropertyValues } from 'lit';
+import { type BuilderContentData, type BuilderDirtyData, type BuilderErrorData, type BuilderSaveData, 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 declare class SfxTemplateBuilder extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** Origin + optional path prefix of the design-templates-app deployment. */
+    baseUrl: string;
+    /** Filerobot token (`ftoken`). */
+    token: string;
+    sassKey: string;
+    sessionUuid: string;
+    /**
+     * 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.
+     */
+    secTemplate: string;
+    companyUuid: string;
+    projectUuid: string;
+    /**
+     * DAM-backed mode: the Filerobot uuid to load; empty opens the new-template
+     * flow. Stateless mode: an opaque host id, echoed back on `save`.
+     */
+    templateId: string;
+    mode: 'inline' | 'modal';
+    /**
+     * Hand the template in and take it back out instead of letting the app read
+     * and write Filerobot. Requires `content`.
+     */
+    stateless: boolean;
+    /**
+     * 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.
+     */
+    content: string;
+    /** Stateless mode: display name for the editor header. */
+    templateName: string;
+    /**
+     * 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.
+     */
+    templateQuery: string;
+    /**
+     * 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.
+     */
+    brandColor: string;
+    /** Colour scheme for the editor chrome. Empty leaves the app's own default. */
+    theme: BuilderTheme | '';
+    /** Ms to wait for the app's ready signal before emitting `error`. 0 disables. */
+    readyTimeout: number;
+    private _status;
+    private _open;
+    private _src;
+    private _handshakeTimer?;
+    /**
+     * The app asked for content. Tracked because the request and the `content`
+     * assignment race: whichever lands second triggers the send.
+     */
+    private _contentRequested;
+    /**
+     * 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?;
+    /**
+     * 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?;
+    /**
+     * 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;
+    private _isDirty;
+    get status(): TemplateBuilderStatus;
+    /**
+     * 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;
+    /** Open the editor (loads the iframe). Optionally switch template first. */
+    open(templateId?: string): void;
+    /** Close the editor and unload the iframe. Does not emit `close`. */
+    close(): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
+    private _computeSrc;
+    private get _appOrigin();
+    private _onMessage;
+    /**
+     * 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;
+    /** Identity of a delivered template, as compared against `_sentKey`. */
+    private _contentKey;
+    /** Post into the iframe, targeted at the app origin. False if not mounted. */
+    private _postToApp;
+    private _startHandshakeTimer;
+    private _clearHandshakeTimer;
+    private _fail;
+    private _emit;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'sfx-template-builder': SfxTemplateBuilder;
+    }
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@scaleflex/template-builder",
+  "version": "0.1.1",
+  "description": "Embeddable web component (<sfx-template-builder>) for the Filerobot design-templates builder",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js",
+      "require": "./dist/define.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    },
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "default": "./src/protocol.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src/*.ts",
+    ".claude",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite --config vite.demo.config.ts",
+    "dev:demo": "vite --config vite.demo.config.ts",
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "build:cdn": "vite build --config vite.cdn.config.ts",
+    "build:demo": "vite build --config vite.demo.config.ts",
+    "preview:demo": "vite preview --config vite.demo.config.ts",
+    "build:all": "yarn build && yarn build:cdn",
+    "release": "node scripts/release-cdn.mjs plugin",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "lit": "^3.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "jsdom": "^29.0.1",
+    "markdown-it": "^14.0.0",
+    "typescript": "^5",
+    "vite": "^6.3.5",
+    "vitest": "^4.1.2"
+  }
+}

package/src/define.ts

@@ -0,0 +1,10 @@
+import { SfxTemplateBuilder } from './template-builder'
+
+if (
+  typeof customElements !== 'undefined' &&
+  !customElements.get('sfx-template-builder')
+) {
+  customElements.define('sfx-template-builder', SfxTemplateBuilder)
+}
+
+export { SfxTemplateBuilder }

package/src/index.ts

@@ -0,0 +1,9 @@
+// Core entry — exports the element class without registering the tag.
+// Import '@scaleflex/template-builder/define' to register <sfx-template-builder>.
+export {
+  SfxTemplateBuilder,
+  type TemplateBuilderStatus,
+  type TemplateBuilderEventMap,
+  type TemplateBuilderSaveDetail,
+} from './template-builder'
+export * from './protocol'

package/src/protocol.ts

@@ -0,0 +1,298 @@
+// ---------------------------------------------------------------------------
+// postMessage protocol between the design-templates app (inside the iframe)
+// and its embedder (the <sfx-template-builder> widget or the Hub).
+//
+// This module is the single source of truth for both sides: the app imports
+// it via `@scaleflex/template-builder/protocol` (workspace TS-source export),
+// the widget bundles it. Message *values* are wire format — never change an
+// existing string; add new messages instead. All changes must stay additive
+// so older widgets keep working against newer app deployments and vice versa.
+// ---------------------------------------------------------------------------
+
+export const PROTOCOL_VERSION = 2
+
+// App → embedder ------------------------------------------------------------
+
+/** Editor mounted with valid auth — the embed handshake succeeded. */
+export const BUILDER_READY = 'design-templates:builder:ready'
+/** Editor UI opened (kept for Hub backwards compatibility; implies ready). */
+export const BUILDER_OPEN = 'design-templates:builder:open'
+/** Editor UI closed / unmounted. */
+export const BUILDER_CLOSE = 'design-templates:builder:close'
+/** Template saved. `data` is absent on app deployments older than protocol v1. */
+export const BUILDER_SAVE = 'design-templates:builder:save'
+/** The app cannot start (e.g. auth cookies missing/blocked). */
+export const BUILDER_ERROR = 'design-templates:builder:error'
+/**
+ * Stateless mode only (protocol v2). The editor mounted without a template and
+ * is waiting for the host to send `HOST_LOAD`. Re-sent on nothing — the host
+ * may answer late; the app keeps waiting until content arrives.
+ */
+export const BUILDER_CONTENT_REQUEST = 'design-templates:builder:content-request'
+/**
+ * Stateless mode only (protocol v2). The user saved and the app is handing the
+ * edited template back instead of uploading it. This is the stateless
+ * counterpart to `BUILDER_SAVE` — a separate message so that embedders written
+ * against v1 (which read `data.uuid` from a save they assume was persisted)
+ * never receive a payload that was not, in fact, stored anywhere.
+ */
+export const BUILDER_CONTENT = 'design-templates:builder:content'
+/**
+ * Stateless mode only (protocol v2). The unsaved-changes flag flipped. Sent so
+ * a host can ask the user before swapping the template out from under them —
+ * `HOST_LOAD` is honoured unconditionally and discards whatever was in
+ * progress, and without this the host has no way to know there was anything to
+ * lose.
+ */
+export const BUILDER_DIRTY = 'design-templates:builder:dirty'
+
+export interface BuilderReadyMessage {
+  type: typeof BUILDER_READY
+}
+
+export interface BuilderOpenMessage {
+  type: typeof BUILDER_OPEN
+}
+
+export interface BuilderCloseMessage {
+  type: typeof BUILDER_CLOSE
+}
+
+export interface BuilderSaveData {
+  uuid: string
+  name?: string
+}
+
+export interface BuilderSaveMessage {
+  type: typeof BUILDER_SAVE
+  data?: BuilderSaveData
+}
+
+/**
+ * `auth` and `invalid-content` are the codes the app itself sends. The widget
+ * adds `handshake-timeout` (no ready signal — typically blocked third-party
+ * cookies or a missing frame-ancestors entry), `invalid-base-url` and
+ * `invalid-config`.
+ */
+export type BuilderErrorCode =
+  /**
+   * The app could not authenticate. In `secTemplate` mode this also covers a
+   * security-template key the Filerobot API refused to exchange for a sass key.
+   */
+  | 'auth'
+  /** Stateless mode: the `HOST_LOAD` content could not be parsed as a template. */
+  | 'invalid-content'
+  | 'handshake-timeout'
+  | 'invalid-base-url'
+  /** Attributes that contradict each other, e.g. `sec-template` without `stateless`. */
+  | 'invalid-config'
+  | 'unknown'
+
+export interface BuilderErrorData {
+  code: BuilderErrorCode
+  message?: string
+}
+
+export interface BuilderErrorMessage {
+  type: typeof BUILDER_ERROR
+  data: BuilderErrorData
+}
+
+export interface BuilderContentRequestMessage {
+  type: typeof BUILDER_CONTENT_REQUEST
+}
+
+export interface BuilderContentData {
+  /**
+   * The id the host supplied in `HOST_LOAD`, echoed back verbatim. Absent when
+   * the host sent content without one.
+   */
+  templateId?: string
+  /** The edited template, serialized as `.fdt` XML. */
+  content: string
+  /** Display name the host supplied, echoed back. */
+  name?: string
+  /**
+   * `template_query` for the default render — layout, variable values and
+   * locale. In DAM-backed mode this is stored as file metadata; a stateless
+   * host must persist it alongside `content` or renders will fall back to
+   * whatever defaults the XML alone implies.
+   */
+  templateQuery?: string
+}
+
+export interface BuilderContentMessage {
+  type: typeof BUILDER_CONTENT
+  data: BuilderContentData
+}
+
+export interface BuilderDirtyData {
+  /** True when the editor holds edits that have not been handed back. */
+  isDirty: boolean
+}
+
+export interface BuilderDirtyMessage {
+  type: typeof BUILDER_DIRTY
+  data: BuilderDirtyData
+}
+
+export type BuilderMessage =
+  | BuilderReadyMessage
+  | BuilderOpenMessage
+  | BuilderCloseMessage
+  | BuilderSaveMessage
+  | BuilderErrorMessage
+  | BuilderContentRequestMessage
+  | BuilderContentMessage
+  | BuilderDirtyMessage
+
+// Embedder → app --------------------------------------------------------------
+
+/**
+ * Stateless mode only (protocol v2). Hands the app a template to edit. Sent in
+ * answer to `BUILDER_CONTENT_REQUEST`, and again whenever the host swaps the
+ * template without remounting the iframe.
+ *
+ * Content travels by postMessage rather than a URL param because template XML
+ * routinely exceeds practical URL length limits.
+ *
+ * The app accepts this message only from the origin pinned as `embedOrigin`
+ * when the session credentials were handed over, so an unrelated framing page
+ * cannot inject a template into someone else's session.
+ */
+export const HOST_LOAD = 'design-templates:host:load'
+
+export interface HostLoadData {
+  /**
+   * Opaque host-side identifier, echoed back on save. It is never used to
+   * fetch anything, so it need not be a Filerobot uuid — any string the host
+   * can map back to its own record works.
+   */
+  templateId?: string
+  /** Template to edit, as `.fdt` XML. */
+  content: string
+  /** Display name for the editor header. */
+  name?: string
+  /**
+   * `template_query` describing the render to open on — layout and variable
+   * values, in the same `$key=value&$key2=value2` form the editor hands back
+   * in `BuilderContentData.templateQuery`.
+   *
+   * Round-trips that value: a host that stored it on save and passes it back
+   * here reopens the template exactly as it was left. Omitting it falls back
+   * to the `default=` attributes in the XML, which is a different render
+   * whenever the query overrode any of them.
+   *
+   * Applied as display state, not as an edit — it selects the layout and fills
+   * variable values without marking the document dirty, so opening a template
+   * and closing it again does not look like an unsaved change.
+   */
+  templateQuery?: string
+}
+
+export interface HostLoadMessage {
+  type: typeof HOST_LOAD
+  data: HostLoadData
+}
+
+/**
+ * Stateless mode only (protocol v2). Reports whether the host managed to
+ * persist the content it received in `BUILDER_CONTENT`.
+ *
+ * Optional by design. The editor clears its unsaved-changes flag optimistically
+ * when it posts `BUILDER_CONTENT`, so a host that never acks behaves exactly as
+ * before. Sending `ok: false` is what buys something: the editor restores the
+ * dirty flag and tells the user, instead of leaving a failed write looking
+ * saved.
+ */
+export const HOST_SAVED = 'design-templates:host:saved'
+
+export interface HostSavedData {
+  /** False when the host could not persist the content. */
+  ok: boolean
+  /** Shown to the user when `ok` is false. */
+  message?: string
+}
+
+export interface HostSavedMessage {
+  type: typeof HOST_SAVED
+  data: HostSavedData
+}
+
+export type HostMessage = HostLoadMessage | HostSavedMessage
+
+// Embed URL contract ----------------------------------------------------------
+
+/**
+ * Query params the app's proxy middleware (`src/proxy.ts`) converts into auth
+ * cookies on first navigation. Names are wire format.
+ */
+export const EMBED_PARAMS = {
+  SESSION_UUID: 'suuid',
+  COMPANY_UUID: 'cuuid',
+  PROJECT_UUID: 'puuid',
+  SASS_KEY: 'sassKey',
+  FILEROBOT_TOKEN: 'ftoken',
+  /**
+   * Filerobot security-template key, the alternative to a Hub session. The app
+   * exchanges it for a sass key itself and runs in a reduced mode — see
+   * `AUTH_MODES`. Sent *instead of* `sassKey` + `suuid`, never alongside them.
+   */
+  SEC_TEMPLATE: 'secTemplate',
+  IFRAME: 'iframe',
+  /** Origin of the embedding page; the app uses it as postMessage targetOrigin. */
+  EMBED_ORIGIN: 'embedOrigin',
+  /**
+   * Accent colour for the editor chrome, as `#rgb` / `#rrggbb`. The app derives
+   * its whole accent ramp from it. Rejected server-side if it doesn't match
+   * that shape — it ends up inside a stylesheet.
+   */
+  BRAND_COLOR: 'brandColor',
+  /** Colour scheme for the editor chrome: `light` | `dark` | `auto`. */
+  THEME: 'theme',
+} as const
+
+/** Values the `theme` param accepts. */
+export type BuilderTheme = 'light' | 'dark' | 'auto'
+
+/**
+ * How the embedder authenticated.
+ *
+ * - `session` — a Hub session (`suuid` + `sassKey` + `ftoken`). Full features.
+ * - `secTemplate` — a Filerobot security-template key (`secTemplate` +
+ *   `ftoken`). A guest credential: no user identity and no Hub project, so the
+ *   app accepts it on {@link EMBED_ROUTE} only, and everything that reads the
+ *   Hub project model (metadata fields, regional variants, project branding)
+ *   comes back empty. Rendering, fonts and asset browsing work, scoped by
+ *   whatever the security template grants.
+ *
+ * Derived by the app from the params it received; named here so both sides use
+ * the same vocabulary.
+ */
+export const AUTH_MODES = {
+  SESSION: 'session',
+  SEC_TEMPLATE: 'secTemplate',
+} as const
+
+export type AuthMode = (typeof AUTH_MODES)[keyof typeof AUTH_MODES]
+
+/**
+ * Shape the app requires of `brandColor`. Hex only: the value is interpolated
+ * into a `:root { … }` rule, so anything that could carry CSS syntax is
+ * refused rather than escaped. Mirrored in the app's proxy — keep in sync.
+ */
+export const BRAND_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/
+
+/** Editor route for an existing template, or the new-template route. */
+export function builderRoute(templateId?: string): string {
+  return templateId
+    ? `/templates/${encodeURIComponent(templateId)}/edit`
+    : '/templates/new'
+}
+
+/**
+ * Stateless editor route. Takes no template id — the id is an opaque host
+ * value that arrives with the content over `HOST_LOAD`, not something the app
+ * resolves against Filerobot, so it has no place in the URL.
+ */
+export const EMBED_ROUTE = '/templates/embed'