@contello/extension 8.21.0 → 8.21.3

package/README.md

@@ -0,0 +1,123 @@
+# @contello/extension
+
+Client SDK for building Contello CMS extensions and custom properties. Communicates with the Contello host application via postMessage channels.
+
+## Installation
+
+```bash
+npm install @contello/extension
+```
+
+## Usage
+
+### Extension
+
+Extensions are full-page iframe apps embedded in the Contello UI.
+
+```ts
+import { ContelloExtension } from '@contello/extension';
+
+const extension = await ContelloExtension.connect({
+  trustedOrigins: ['https://your-contello-instance.com'],
+});
+
+await extension.ready();
+
+// get URL path and query data
+const { path, query } = await extension.getUrlData();
+
+// set breadcrumbs
+await extension.setBreadcrumbs([
+  { label: 'Home', url: '/' },
+  { label: 'Current Page' },
+]);
+
+// navigate
+await extension.navigate(extension.createEntityDetailUrl('articles', { mode: 'edit', id: '123' }));
+
+// show notifications
+await extension.displayNotification('success', 'Saved successfully');
+```
+
+### Custom property
+
+Custom properties are smaller iframe widgets used inside entity forms.
+
+```ts
+import { ContelloCustomProperty } from '@contello/extension';
+
+const property = await ContelloCustomProperty.connect({
+  trustedOrigins: ['https://your-contello-instance.com'],
+  validator: () => true,
+  newValue: (value) => console.log('new value:', value),
+});
+
+await property.ready();
+
+// get / set the property value
+const value = await property.getValue();
+await property.setValue('new value');
+
+// get / set values by path (for complex entities)
+const nested = await property.getValueByPath('some.path');
+await property.setValueByPath('some.path', 'new value');
+```
+
+### Dialogs
+
+Open modal dialogs from extensions or custom properties.
+
+```ts
+const dialog = extension.openDialog<InputData, ResultData>({
+  url: 'https://my-dialog.example.com',
+  width: 800,
+  data: { someInput: 'value' },
+});
+
+await dialog.open;
+await dialog.ready;
+
+const result = await dialog.complete;
+```
+
+Inside the dialog iframe:
+
+```ts
+import { ContelloDialog } from '@contello/extension';
+
+const dialog = await ContelloDialog.connect<InputData, ResultData>({
+  trustedOrigins: ['https://your-contello-instance.com'],
+});
+
+await dialog.ready();
+
+// access data passed from the opener
+console.log(dialog.data);
+
+// close with a result
+await dialog.close({ selectedId: '456' });
+```
+
+### Auth token
+
+Retrieve the current authentication token from the host:
+
+```ts
+const token = await extension.getAuthToken();
+```
+
+## API
+
+### Classes
+
+| Class | Description |
+|-------|-------------|
+| `ContelloExtension` | Full-page extension client |
+| `ContelloCustomProperty` | Custom property widget client |
+| `ContelloDialog` | Dialog iframe client |
+| `ContelloDialogRef` | Handle returned by `openDialog()` |
+| `ExtensionChannel` | Low-level postMessage channel (advanced use) |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,357 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ContelloCustomProperty: () => ContelloCustomProperty,
+  ContelloDialog: () => ContelloDialog,
+  ContelloDialogRef: () => ContelloDialogRef,
+  ContelloExtension: () => ContelloExtension,
+  ExtensionChannel: () => ExtensionChannel
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/channel.ts
+var channelIdIterator = 0;
+var requestIdIterator = 0;
+var ExtensionChannel = class {
+  constructor(params) {
+    this.params = params;
+  }
+  handlers = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Map();
+  targetWindow;
+  channelId;
+  targetOrigin;
+  isParent;
+  populateChannelId() {
+    if (!this.channelId) {
+      this.channelId = this.createChannelId();
+    }
+    return this.channelId;
+  }
+  connectParent(targetOrigin, channelId) {
+    this.channelId = channelId;
+    this.targetOrigin = targetOrigin;
+    this.targetWindow = window.parent;
+    this.isParent = false;
+    this.connect();
+  }
+  connectChild(targetWindow) {
+    this.populateChannelId();
+    this.targetWindow = targetWindow;
+    this.targetOrigin = "*";
+    this.isParent = true;
+    this.connect();
+  }
+  getChannelId() {
+    return this.channelId;
+  }
+  getIsDebug() {
+    return this.params.debug;
+  }
+  getTargetOrigin() {
+    return this.targetOrigin;
+  }
+  getTargetWindow() {
+    return this.targetWindow;
+  }
+  connect() {
+    window.addEventListener("message", this.handler);
+  }
+  disconnect() {
+    window.removeEventListener("message", this.handler);
+  }
+  handler = (event) => {
+    if (event.data.channelId !== this.channelId) {
+      return;
+    }
+    if (this.targetOrigin === "*" || event.origin === this.targetOrigin) {
+      const { channelId: requestChannelId, requestId, method } = event.data;
+      if (requestChannelId === this.channelId) {
+        if (this.params.debug) {
+          console.log(this.isParent ? "Parent received" : "Child received", event.data);
+        }
+        if (this.handlers.has(requestId)) {
+          this.handlers.get(requestId)(event.data);
+        } else if (this.listeners.has(method)) {
+          Promise.resolve(this.listeners.get(method)?.(event.data.payload)).then((responsePayload) => this.respond(event.data, responsePayload)).catch((err) => this.respondError(event.data, err));
+        }
+      }
+    }
+  };
+  respond(request, payload) {
+    this.send({ channelId: request.channelId, requestId: request.requestId, method: request.method, payload });
+  }
+  respondError(request, error) {
+    this.send({ channelId: request.channelId, requestId: request.requestId, method: request.method, error });
+  }
+  on(method, handler) {
+    this.listeners.set(method, handler);
+  }
+  call(method, message) {
+    return new Promise((resolve, reject) => {
+      const requestId = this.createRequestId();
+      this.send({ channelId: this.channelId, requestId, method, payload: message });
+      this.handlers.set(requestId, (data) => {
+        this.handlers.delete(requestId);
+        if (data.error) {
+          return reject(data.error);
+        }
+        resolve(data.payload);
+      });
+    });
+  }
+  send(data) {
+    this.targetWindow?.postMessage(data, this.targetOrigin);
+  }
+  createChannelId() {
+    return `contello-channel-${++channelIdIterator}-${Math.random().toString(36).substring(2)}`;
+  }
+  createRequestId() {
+    return `${this.isParent ? "parent" : "child"}-request-${++requestIdIterator}-${Math.random().toString(36).substring(2)}`;
+  }
+};
+
+// src/dialog-ref.ts
+var ContelloDialogRef = class {
+  _id;
+  open;
+  connected;
+  ready;
+  complete;
+  close;
+  constructor({ channel, options, controller }) {
+    this.open = channel.call("openDialog", options).then(({ id }) => this._id = id);
+    this.connected = controller.connected.promise;
+    this.ready = controller.ready.promise;
+    this.complete = controller.complete.promise;
+    this.close = controller.close;
+  }
+  get id() {
+    return this._id;
+  }
+};
+
+// src/utils.ts
+var Deferred = class {
+  resolve;
+  reject;
+  promise = new Promise((resolve, reject) => {
+    this.resolve = resolve;
+    this.reject = reject;
+  });
+};
+
+// src/client.ts
+var ContelloClient = class {
+  channel;
+  projectId;
+  resizeObserver;
+  targetOrigin;
+  data;
+  dialogs = /* @__PURE__ */ new Map();
+  constructor(targetOrigin, channelId, projectId, debug) {
+    this.channel = new ExtensionChannel({ debug });
+    this.channel.connectParent(targetOrigin, channelId);
+    this.projectId = projectId;
+    this.targetOrigin = targetOrigin;
+  }
+  connect() {
+    return this.channel.call("connect").then(({ data }) => {
+      this.channel.on("dialogConnect", ({ id }) => this.getDialogController(id)?.connected.resolve());
+      this.channel.on("dialogReady", ({ id }) => this.getDialogController(id)?.ready.resolve());
+      this.channel.on("dialogComplete", ({ id, value }) => this.getDialogController(id)?.complete.resolve(value));
+      this.data = data;
+    });
+  }
+  ready() {
+    this.listenForResize();
+    return this.channel.call("ready", { height: this.getWindowHeight() });
+  }
+  getAuthToken() {
+    return this.channel.call("getAuthToken").then(({ token }) => token);
+  }
+  createProjectUrl() {
+    return `${this.targetOrigin}/ui/projects/${this.projectId}`;
+  }
+  createEntityEntryUrl(referenceName) {
+    return `${this.createProjectUrl()}/entities/${referenceName}`;
+  }
+  createSingletonEntityUrl(referenceName) {
+    return this.createEntityEntryUrl(referenceName);
+  }
+  createEntityDetailUrl(referenceName, params) {
+    const base = this.createEntityEntryUrl(referenceName);
+    if (params.mode === "create") {
+      return `${base}/create`;
+    }
+    return `${base}/${params.mode}/${params.id}`;
+  }
+  /**
+   * @deprecated Use createEntityDetailUrl instead
+   */
+  createEntityUrl(referenceName, entityId) {
+    return this.createEntityDetailUrl(referenceName, { mode: "edit", id: entityId });
+  }
+  createExtensionUrl(referenceName, params) {
+    const path = params?.path?.join("/") || "";
+    const query = new URLSearchParams(params?.query || {}).toString();
+    return `${this.createProjectUrl()}/extensions/${referenceName}${path ? `/${path}` : ""}${query ? `?${query}` : ""}`;
+  }
+  navigate(url) {
+    return this.channel.call("navigate", { url });
+  }
+  displayNotification(type, message) {
+    return this.channel.call("displayNotification", { type, message });
+  }
+  openDialog(options) {
+    const controller = {
+      connected: new Deferred(),
+      ready: new Deferred(),
+      complete: new Deferred(),
+      close: () => {
+        if (!this.channel) {
+          throw new Error("The channel is not yet initialized");
+        }
+        this.channel.call("closeDialog", { id: dialog.id });
+        this.dialogs.delete(dialog);
+      }
+    };
+    const dialog = new ContelloDialogRef({ channel: this.channel, options, controller });
+    this.dialogs.set(dialog, controller);
+    dialog.complete.then(() => this.dialogs.delete(dialog));
+    return dialog;
+  }
+  listenForResize() {
+    this.resizeObserver = new ResizeObserver(() => {
+      this.channel.call("resize", { height: this.getWindowHeight() });
+    });
+    this.resizeObserver.observe(document.documentElement);
+  }
+  getWindowHeight() {
+    return Math.max(document.body.scrollHeight, document.body.offsetHeight, document.body.clientHeight);
+  }
+  getDialogController(id) {
+    const key = Array.from(this.dialogs.keys()).find((dialog) => dialog.id === id);
+    if (!key) {
+      return;
+    }
+    return this.dialogs.get(key);
+  }
+};
+
+// src/url-parser.ts
+function parseUrl(trustedOrigins) {
+  const url = new URL(location.href);
+  const channelId = url.searchParams.get("channelId");
+  const targetOrigin = url.searchParams.get("origin");
+  const applicationId = url.searchParams.get("applicationId");
+  const debug = url.searchParams.get("debug") === "true";
+  if (!channelId || !targetOrigin || !applicationId) {
+    throw new Error("Missing required URL parameters");
+  }
+  if (!trustedOrigins?.length) {
+    throw new Error("No trusted origins provided");
+  }
+  if (!trustedOrigins.includes(targetOrigin)) {
+    throw new Error(`Origin ${targetOrigin} is not trusted`);
+  }
+  return { channelId, targetOrigin, applicationId, debug };
+}
+
+// src/custom-property.ts
+var ContelloCustomProperty = class _ContelloCustomProperty extends ContelloClient {
+  static connect(options) {
+    const { targetOrigin, channelId, applicationId, debug } = parseUrl(options.trustedOrigins);
+    const customProperty = new _ContelloCustomProperty(targetOrigin, channelId, applicationId, debug);
+    customProperty.validate = options.validator || (() => true);
+    customProperty.newValue = options.newValue || (() => null);
+    return customProperty.connect().then(() => customProperty);
+  }
+  validate = () => true;
+  newValue = () => null;
+  constructor(targetOrigin, channelId, applicationId, debug) {
+    super(targetOrigin, channelId, applicationId, debug);
+    this.channel.on("validate", async () => {
+      const valid = await Promise.resolve(this.validate());
+      return { valid };
+    });
+    this.channel.on("newValue", async (msg) => {
+      await Promise.resolve(this.newValue(msg.value));
+    });
+  }
+  async getValue() {
+    const r = await this.channel.call("getValue");
+    return r.value;
+  }
+  async setValue(value) {
+    const valid = await Promise.resolve(this.validate());
+    return await this.channel.call("setValue", { value, valid });
+  }
+  async getValueByPath(path) {
+    const r = await this.channel.call("getValueByPath", { path });
+    return r.value;
+  }
+  async setValueByPath(path, value) {
+    return this.channel.call("setValueByPath", { value, path });
+  }
+};
+
+// src/dialog.ts
+var ContelloDialog = class _ContelloDialog extends ContelloClient {
+  static connect({ trustedOrigins }) {
+    const { targetOrigin, channelId, applicationId, debug } = parseUrl(trustedOrigins);
+    const dialog = new _ContelloDialog(targetOrigin, channelId, applicationId, debug);
+    return dialog.connect().then(() => dialog);
+  }
+  constructor(targetOrigin, channelId, applicationId, debug) {
+    super(targetOrigin, channelId, applicationId, debug);
+  }
+  close(value) {
+    return this.channel.call("complete", { value });
+  }
+};
+
+// src/extension.ts
+var ContelloExtension = class _ContelloExtension extends ContelloClient {
+  static connect({ trustedOrigins }) {
+    const { targetOrigin, channelId, applicationId, debug } = parseUrl(trustedOrigins);
+    const extension = new _ContelloExtension(targetOrigin, channelId, applicationId, debug);
+    return extension.connect().then(() => extension);
+  }
+  constructor(targetOrigin, channelId, applicationId, debug) {
+    super(targetOrigin, channelId, applicationId, debug);
+  }
+  getUrlData() {
+    return this.channel.call("getUrlData");
+  }
+  setBreadcrumbs(breadcrumbs) {
+    return this.channel.call("setBreadcrumbs", { breadcrumbs });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ContelloCustomProperty,
+  ContelloDialog,
+  ContelloDialogRef,
+  ContelloExtension,
+  ExtensionChannel
+});