@adobe/uix-guest 0.6.3

package/dist/guest.d.ts

@@ -0,0 +1,160 @@
+import { Connection } from "penpal";
+import type { RemoteHostApis, NamedEvent, VirtualApi } from "@adobe/uix-core";
+import { Emitter } from "@adobe/uix-core";
+/**
+ * @public
+ */
+export declare type GuestEvent<Type extends string = string, Detail = Record<string, unknown>> = NamedEvent<Type, Detail & Record<string, unknown> & {
+    guest: Guest;
+}>;
+/**
+ * @public
+ */
+export declare type GuestEventContextChange = GuestEvent<"contextchange", {
+    context: Record<string, unknown>;
+}>;
+/** @public */
+export declare type GuestEventBeforeConnect = GuestEvent<"beforeconnect">;
+/** @public */
+export declare type GuestEventConnected = GuestEvent<"connected", {
+    connection: Connection;
+}>;
+/** @public */
+export declare type GuestEventError = GuestEvent<"error", {
+    error: Error;
+}>;
+/**
+ * @public
+ */
+export declare 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 declare class SharedContext {
+    private _map;
+    constructor(values: Record<string, unknown>);
+    private reset;
+    /**
+     * @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): unknown;
+}
+/**
+ * Generic Guest object, with methods shared by all types of Guest.
+ * @internal
+ */
+export declare class Guest<Incoming extends object = VirtualApi> extends Emitter<GuestEvents> {
+    /**
+     * Shared context has been set or updated.
+     * @eventProperty
+     */
+    contextchange: GuestEventContextChange;
+    /**
+     * About to attempt connection to the host.
+     * @eventProperty
+     */
+    beforeconnect: GuestEventBeforeConnect;
+    /**
+     * Host connection has been established.
+     * @eventProperty
+     */
+    connected: GuestEventConnected;
+    /**
+     * Host connection has failed.
+     * @eventProperty
+     */
+    error: GuestEventError;
+    /**
+     * {@inheritdoc SharedContext}
+     */
+    sharedContext: SharedContext;
+    private debugLogger;
+    /**
+     * @param config - Initializer for guest object, including ID.
+     */
+    constructor(config: GuestConfig);
+    /**
+     * 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>;
+    private timeout;
+    private hostConnectionPromise;
+    private hostConnection;
+    /** @internal */
+    protected getLocalMethods(): {
+        emit: (type: "contextchange" | "beforeconnect" | "connected" | "error", detail: ({
+            context: Record<string, unknown>;
+        } & Record<string, unknown> & {
+            guest: Guest<VirtualApi>;
+        }) | (Record<string, unknown> & {
+            guest: Guest<VirtualApi>;
+        }) | ({
+            connection: Connection<import("penpal").CallSender>;
+        } & Record<string, unknown> & {
+            guest: Guest<VirtualApi>;
+        }) | ({
+            error: Error;
+        } & Record<string, unknown> & {
+            guest: Guest<VirtualApi>;
+        })) => void;
+    };
+    /**
+     * 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
+     */
+    connect(): Promise<void>;
+    /**
+     * @internal
+     */
+    _connect(): Promise<void>;
+}
+//# sourceMappingURL=guest.d.ts.map

package/dist/guest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,UAAU,EAAmB,MAAM,QAAQ,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EAEd,UAAU,EACV,UAAU,EACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,OAAO,EAIR,MAAM,iBAAiB,CAAC;AAGzB;;GAEG;AACH,oBAAY,UAAU,CACpB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC9B,UAAU,CACZ,IAAI,EACJ,MAAM,GACJ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACxB,KAAK,EAAE,KAAK,CAAC;CACd,CACJ,CAAC;AAEF;;GAEG;AACH,oBAAY,uBAAuB,GAAG,UAAU,CAC9C,eAAe,EACf;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CACrC,CAAC;AAEF,cAAc;AACd,oBAAY,uBAAuB,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;AAClE,cAAc;AACd,oBAAY,mBAAmB,GAAG,UAAU,CAC1C,WAAW,EACX;IAAE,UAAU,EAAE,UAAU,CAAA;CAAE,CAC3B,CAAC;AACF,cAAc;AACd,oBAAY,eAAe,GAAG,UAAU,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAEpE;;GAEG;AACH,oBAAY,WAAW,GACnB,uBAAuB,GACvB,uBAAuB,GACvB,mBAAmB,GACnB,eAAe,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAuB;gBACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAG3C,OAAO,CAAC,KAAK;IAGb;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM;CAGhB;AAED;;;GAGG;AACH,qBAAa,KAAK,CAChB,QAAQ,SAAS,MAAM,GAAG,UAAU,CACpC,SAAQ,OAAO,CAAC,WAAW,CAAC;IAC5B;;;OAGG;IACI,aAAa,EAAE,uBAAuB,CAAC;IAC9C;;;OAGG;IACI,aAAa,EAAE,uBAAuB,CAAC;IAC9C;;;OAGG;IACI,SAAS,EAAE,mBAAmB,CAAC;IACtC;;;OAGG;IACI,KAAK,EAAE,eAAe,CAAC;IAC9B;;OAEG;IACH,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,CAAC,WAAW,CAAyB;IAE5C;;OAEG;gBACS,MAAM,EAAE,WAAW;IAY/B;;;;;;;;OAQG;IACH,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,CAqB5B;IACF,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,qBAAqB,CAA0C;IACvE,OAAO,CAAC,cAAc,CAAkC;IACxD,gBAAgB;IAChB,SAAS,CAAC,eAAe;;;;;;;;;;;;;;;;;IAQzB;;;;;;;;;OASG;IACG,OAAO;IAIb;;OAEG;IACG,QAAQ;CAoBf"}