@adobe/uix-guest 0.6.3

package/src/guest-server.ts

@@ -0,0 +1,56 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import type { GuestApis } from "@adobe/uix-core";
+import type { SharedContext } from "./guest";
+import { Guest } from "./guest";
+
+/**
+ * A Guest to be used in the "main" or primary frame of an extension, the frame
+ * the Host loads first.
+ *
+ * @remarks This is the Guest object returned from {@link register}. It can
+ * expose internal methods to the Host via the {@link GuestServer.register}
+ * method.
+ *
+ *
+ * @public
+ */
+export class GuestServer<Outgoing extends GuestApis> extends Guest<Outgoing> {
+  private localMethods: Outgoing;
+  protected getLocalMethods() {
+    return {
+      ...super.getLocalMethods(),
+      apis: this.localMethods,
+    };
+  }
+  /**
+   * {@inheritDoc BaseGuest.sharedContext}
+   */
+  sharedContext: SharedContext;
+  /**
+   * {@inheritdoc BaseGuest.host}
+   */
+  host: Guest<Outgoing>["host"];
+  /**
+   * Pass an interface of methods which Host may call as callbacks.
+   *
+   * @remarks It is preferable to use {@link register} to obtain a guest object
+   * and register local methods in one step. The returned guest object will be
+   * pre-registered and connected.
+   * @public
+   */
+  async register(implementedMethods: Outgoing) {
+    this.localMethods = implementedMethods;
+    return this._connect();
+  }
+}

package/src/guest-ui.ts

@@ -0,0 +1,123 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import type { RemoteHostApis, VirtualApi } from "@adobe/uix-core";
+import {
+  Guest,
+  GuestConfig,
+  GuestEventBeforeConnect,
+  GuestEventConnected,
+  GuestEventContextChange,
+  GuestEventError,
+} from "./guest";
+
+/**
+ * A Guest to be used in an extension-controlled frame, usually to display UI.
+ *
+ * @typeParam Incoming - Optional interface of host methods. If using
+ * TypeScript, supply this type parameter and a promisified version of the
+ * interface will be available at {@link Guest.host}
+ *
+ * @remarks
+ * This is the object returned when calling {@link @adobe/uix-guest#attach}. It
+ * represents an additional frame or runtime created by the host application, on
+ * behalf of the extension's control frame which is running the {@link
+ * GuestServer}. It is a "secondary" guest object, which a host won't use before
+ * the control frame has connected. It exposes a subset of the functionality of
+ * the {@link GuestServer}.
+ *
+ * Unlike the {@link GuestServer}, it cannot register methods or update the
+ * {@link Guest.sharedContext}, but it remains in sync with the GuestServer and
+ * can access the {@link Guest.sharedContext} of the control frame, as well as
+ * any of the published methods on the host.
+ *
+ * Extensible host apps using the React bindings will likely render GuestUI
+ * frames using the {@link @adobe/uix-host-react#GuestUIFrame} component.
+ *
+ * @example
+ * When an extensible app renders this page, {@link @adobe/uix-guest#attach}
+ * creates a GuestUI. Once it attaches to the host, it
+ * ```javascript
+ * import React, { useEffect, useState } from "react";
+ * import { attach } from "@adobe/uix-guest";
+ * import { Tooltip } from "./tooltip";
+ *
+ * export default function PopupOverlay(props) {
+ *   // how large am I?
+ *   const [dimensions, setDimensions] = useState(
+ *     document.body.getBoundingClientRect()
+ *   );
+ *   // if possible, use language preloaded in query parameters
+ *   const [language, setLanguage] = useState(props.params.lang)
+ *
+ *   // attach only once, in a useEffect
+ *   useEffect(() => {
+ *     attach({
+ *       id: "my-extension-id",
+ *       debug: true,
+ *     })
+ *     .then(guestUI => {
+ *       // this event fires whenever the host, or the control frame, changes
+ *       // any sharedContext value
+ *       guestUI.addEventListener("contextchange", ({ detail: { context }}) => {
+ *         setLanguage(context.lang)
+ *       });
+ *       // how large does the host want me to be?
+ *       return guestUI.host.tooltips.getDimensions()
+ *     .then(setDimensions)
+ *     })
+ *     .catch((e) => {
+ *       console.error("ui attach failed", e);
+ *     });
+ *   }, []);
+ *   // render UI! Due to the setup and useState, this component will re-render
+ *   // once attach() is complete.
+ *   return (
+ *     <Tooltip {...props.params} lang={language} dimensions={dimensions} />
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export class GuestUI<IHost extends VirtualApi> extends Guest<IHost> {
+  /**
+   * {@inheritDoc Guest."constructor"}
+   */
+  constructor(config: GuestConfig) {
+    super(config);
+  }
+  /**
+   * {@inheritDoc Guest.contextchange}
+   * @eventProperty
+   */
+  public contextchange: GuestEventContextChange;
+  /**
+   * {@inheritDoc Guest.beforeconnect}
+   * @eventProperty
+   */
+  public beforeconnect: GuestEventBeforeConnect;
+  /**
+   * {@inheritDoc Guest.connected}
+   * @eventProperty
+   */
+  public connected: GuestEventConnected;
+  /**
+   * {@inheritDoc Guest.error}
+   * @eventProperty
+   */
+  public error: GuestEventError;
+  /**
+   * {@inheritDoc Guest.host}
+   */
+  host: RemoteHostApis<IHost>;
+}

package/src/guest.ts

@@ -0,0 +1,255 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/* eslint @typescript-eslint/no-explicit-any: "off" */
+import { Connection, connectToParent } from "penpal";
+import type {
+  RemoteHostApis,
+  HostConnection,
+  NamedEvent,
+  VirtualApi,
+} from "@adobe/uix-core";
+import {
+  Emitter,
+  makeNamespaceProxy,
+  timeoutPromise,
+  quietConsole,
+} from "@adobe/uix-core";
+import { debugGuest } from "./debug-guest.js";
+
+/**
+ * @public
+ */
+export type GuestEvent<
+  Type extends string = string,
+  Detail = Record<string, unknown>
+> = NamedEvent<
+  Type,
+  Detail &
+    Record<string, unknown> & {
+      guest: Guest;
+    }
+>;
+
+/**
+ * @public
+ */
+export type GuestEventContextChange = GuestEvent<
+  "contextchange",
+  { context: Record<string, unknown> }
+>;
+
+/** @public */
+export type GuestEventBeforeConnect = GuestEvent<"beforeconnect">;
+/** @public */
+export type GuestEventConnected = GuestEvent<
+  "connected",
+  { connection: Connection }
+>;
+/** @public */
+export type GuestEventError = GuestEvent<"error", { error: Error }>;
+
+/**
+ * @public
+ */
+export type GuestEvents =
+  | GuestEventContextChange
+  | GuestEventBeforeConnect
+  | GuestEventConnected
+  | GuestEventError;
+
+/**
+ * @public
+ */
+export interface GuestConfig {
+  /**
+   * String slug identifying extension. This may need to use IDs from an
+   * external system in the future.
+   */
+  id: string;
+  /**
+   * Set debug flags on all libraries that have them, and add loggers to SDK
+   * objects. Log a lot to the console.
+   */
+  debug?: boolean;
+  /**
+   * Time out and stop trying to reach the host after this many milliseconds
+   */
+  timeout?: number;
+}
+
+/**
+ * A `Map` representing the {@link @adobe/uix-host#HostConfig.sharedContext}
+ * object.
+ *
+ * @remarks While the Host object is a plain JavaScript object. the `sharedContext` in the Guest object implements the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map | Map} interface.
+ *
+ * @example
+ * In the host app window, the Host object shares context:
+ * ```javascript
+ *host.shareContext({
+ *  someAuthToken: 'abc'
+ *});
+ * ```
+ *
+ * After the `contentchange` event has fired in the guest window:
+ * ```javascript
+ * guest.sharedContext.get('someAuthToken') === 'abc'
+ * ```
+ * @public
+ */
+export class SharedContext {
+  private _map: Map<string, unknown>;
+  constructor(values: Record<string, unknown>) {
+    this.reset(values);
+  }
+  private reset(values: Record<string, unknown>) {
+    this._map = new Map(Object.entries(values));
+  }
+  /**
+   * @public
+   * Retrieve a copy of a value from the {@link @adobe/uix-host#HostConfig.sharedContext} object. *Note that this is not a reference to any actual objects from the parent. If the parent updates an "inner object" inside the SharedContext, that change will not be reflected in the Guest!*
+   */
+  get(key: string) {
+    return this._map.get(key);
+  }
+}
+
+/**
+ * Generic Guest object, with methods shared by all types of Guest.
+ * @internal
+ */
+export class Guest<
+  Incoming extends object = VirtualApi
+> extends Emitter<GuestEvents> {
+  /**
+   * Shared context has been set or updated.
+   * @eventProperty
+   */
+  public contextchange: GuestEventContextChange;
+  /**
+   * About to attempt connection to the host.
+   * @eventProperty
+   */
+  public beforeconnect: GuestEventBeforeConnect;
+  /**
+   * Host connection has been established.
+   * @eventProperty
+   */
+  public connected: GuestEventConnected;
+  /**
+   * Host connection has failed.
+   * @eventProperty
+   */
+  public error: GuestEventError;
+  /**
+   * {@inheritdoc SharedContext}
+   */
+  sharedContext: SharedContext;
+  private debugLogger: Console = quietConsole;
+
+  /**
+   * @param config - Initializer for guest object, including ID.
+   */
+  constructor(config: GuestConfig) {
+    super(config.id);
+    if (typeof config.timeout === "number") {
+      this.timeout = config.timeout;
+    }
+    if (config.debug) {
+      this.debugLogger = debugGuest(this);
+    }
+    this.addEventListener("contextchange", (event) => {
+      this.sharedContext = new SharedContext(event.detail.context);
+    });
+  }
+  /**
+   * Proxy object for calling methods on the host.
+   *
+   * @remarks Any APIs exposed to the extension via {@link @adobe/uix-host#Port.provide}
+   * can be called on this object. Because these methods are called with RPC,
+   * they are all asynchronous, The return types of all Host methods will be
+   * Promises which resolve to the value the Host method returns.
+   * @public
+   */
+  host: RemoteHostApis<Incoming> = makeNamespaceProxy<Incoming>(
+    async (address) => {
+      await this.hostConnectionPromise;
+      try {
+        const result = await timeoutPromise(
+          10000,
+          this.hostConnection.invokeHostMethod(address)
+        );
+        return result;
+      } catch (e) {
+        const error =
+          e instanceof Error ? e : new Error(e as unknown as string);
+        const methodError = new Error(
+          `Host method call host.${address.path.join(".")}() failed: ${
+            error.message
+          }`
+        );
+        this.debugLogger.error(methodError);
+        throw methodError;
+      }
+    }
+  );
+  private timeout = 10000;
+  private hostConnectionPromise: Promise<RemoteHostApis<HostConnection>>;
+  private hostConnection!: RemoteHostApis<HostConnection>;
+  /** @internal */
+  protected getLocalMethods() {
+    return {
+      emit: (...args: Parameters<typeof this.emit>) => {
+        this.debugLogger.log(`Event "${args[0]}" emitted from host`);
+        this.emit(...args);
+      },
+    };
+  }
+  /**
+   * Accept a connection from the Host.
+   * @returns A Promise that resolves when the Host has established a connection.
+   * @deprecated It is preferable to use {@link register} for primary frames,
+   * and {@link attach} for UI frames and other secondary frames, than to
+   * instantiate a Guest and then call `.connect()` on it. The latter style
+   * returns an object that cannot be used until it is connected, and therefore
+   * risks errors.
+   * @public
+   */
+  async connect() {
+    return this._connect();
+  }
+
+  /**
+   * @internal
+   */
+  async _connect() {
+    this.emit("beforeconnect", { guest: this });
+    try {
+      const connection = connectToParent<HostConnection<Incoming>>({
+        timeout: this.timeout,
+        methods: this.getLocalMethods(),
+      });
+
+      this.hostConnectionPromise = connection.promise;
+      this.hostConnection = await this.hostConnectionPromise;
+      this.sharedContext = new SharedContext(
+        await this.hostConnection.getSharedContext()
+      );
+      this.debugLogger.log("retrieved sharedContext", this.sharedContext);
+      this.emit("connected", { guest: this, connection });
+    } catch (e) {
+      this.emit("error", { guest: this, error: e });
+      this.debugLogger.error("Connection failed!", e);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * @packageDocumentation
+ * Tools for UI Extensions meant to run inside extensible apps. Connects
+ * Extensions running in their own window contexts with the host app, allowing
+ * the host and guest to exchange method, events, and signals.
+ *
+ * @remarks The core object of this library, which extensions use for
+ * communication, is the Guest object. There are two variants of the Guest
+ * object {@link GuestServer} for the bootstrap frame which your extension keeps
+ * running in the background, and {@link GuestUI} for frames meant to be
+ * displayed in the host application. An extension must have one GuestServer
+ * frame, and the host app may choose to use one or more GuestUI frames.
+ *
+ * @example Creating and connecting a GuestServer with {@link register}
+ * ```typescript
+ * import { register } from "@adobe/uix-guest";
+ *
+ * const server = await register({
+ *   // Must match extension ID from registry
+ *   id: "My Custom View Extension",
+ *   // enable logging in dev build
+ *   debug: process.env.NODE_ENV !== "production",
+ *   // Host can access these methods from its Port to this guest
+ *   methods: {
+ *     // Methods must be namespaced by one or more levels
+ *     myCustomView: {
+ *       async documentIsViewable(docId) {
+ *         const doc = await callMyRuntimeAction(docId);
+ *         return someValidation(doc);
+ *       },
+ *       renderView(docId, depth) {
+ *         // Use a host method
+ *         const tooltip = await server.host.editor.requestTooltip({
+ *           type: 'frame',
+ *           url: new URL(`/show/${docId}`, location).href
+ *         })
+ *       }
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * @example Connecting to an existing GuestServer with a GuestUI
+ * ```typescript
+ * import { attach } from "@adobe/uix-guest";
+ *
+ * const ui = await attach({
+ *   id: "My Custom View Extension",
+ * })
+ *
+ * // when editing is done:
+ * const saved = await ui.host.editor.saveChanges();
+ * if (!saved) {
+ *   const editorState = ui.sharedContext.get('editorState');
+ *   if (editorState.tooltips[ui.id].invalid === true) {
+ *     putGuestUIInInvalidState();
+ *   }
+ * } else {
+ *   ui.host.editor.dismissTooltip();
+ * }
+ * ```
+ *
+ */
+import type { Guest, GuestConfig } from "./guest.js";
+import { GuestUI } from "./guest-ui.js";
+import { GuestServer } from "./guest-server.js";
+import { GuestApis } from "@adobe/uix-core";
+
+/**
+ * {@inheritdoc GuestConfig}
+ * @public
+ */
+type GuestConfigWithMethods<Outgoing extends GuestApis> = GuestConfig & {
+  methods: Outgoing;
+};
+
+/**
+ * Create and immediately return a {@link GuestServer}.
+ *
+ * @deprecated Use {@link attach} or {@link register}, which return Promises
+ * that resolve once the guest is connected.
+ * @public
+ */
+export function createGuest(config: GuestConfig) {
+  const guest = new GuestServer(config);
+  return guest;
+}
+
+/**
+ * Connect to a running {@link GuestServer} to share its context and render UI.
+ *
+ * @remarks Creates a guest object that shares most of the GuestServer API,
+ * except it cannot register its own methods. Use `attach()` in an app or
+ * document that is meant to render a UI in the host application; it will have
+ * access to the sharedContext object shared by the host and GuestServer.
+ *
+ * @public
+ */
+export async function attach(config: GuestConfig) {
+  const guest = new GuestUI(config);
+  await guest._connect();
+  return guest;
+}
+
+/**
+ * Initiate a connection to the host app and its extension points.
+ *
+ * @remarks Creates the "main" {@link GuestServer}, which runs in the background
+ * without UI. Registers methods passed in the `methods` parameter, then
+ * resolves the returned Promise with the connected GuestServer object.
+ *
+ * @public
+ */
+export async function register<Outgoing extends GuestApis>(
+  config: GuestConfigWithMethods<Outgoing>
+) {
+  const guest = new GuestServer(config);
+  await guest.register(config.methods);
+  return guest;
+}
+
+// backwards compatibility
+export {
+  Guest,
+  Guest as BaseGuest,
+  GuestUI,
+  GuestUI as UIGuest,
+  GuestServer,
+  GuestServer as PrimaryGuest,
+};

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig-base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "src/**/*.test.tsx?"
+  ],
+  "references": [
+    {
+      "path": "../uix-core"
+    }
+  ]
+}
+