@openedx/frontend-base 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/runtime/slots/widget/iframe/hooks.js

@@ -0,0 +1,144 @@
+/**
+ * Hooks file for functions that handle the communication between a Plugin and its Host
+ */
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { IFRAME_MOUNTED, IFRAME_READY, IFRAME_UNMOUNTED } from './constants';
+/* Listening for events */
+/**
+ * Dynamically add an event listener to the provided source window.
+ * The source window can be the global parent (ie. the "window" object in the browser)
+ * or it can be the content window of an individual element (ie. iFrame plugin container)
+ */
+export function useMessageEvent(srcWindow, type, callback) {
+    // useLayoutEffect is called before the browser repaints the screen
+    useLayoutEffect(() => {
+        // Create a listener callback function
+        const listener = (event) => {
+            // Filter messages to those from our source window.
+            // NOTE: the "srcWindow" is determined by the below useHostEvent and usePluginEvent functions
+            if (event.source === srcWindow) {
+                // Fire callback if the type from the listened event matches the type from the message event
+                if (event.data.type === type) {
+                    callback({ type, payload: event.data.payload });
+                }
+            }
+        };
+        // Add the listener to the global object if the srcWindow is not null
+        if (srcWindow !== null) {
+            global.addEventListener('message', listener);
+        }
+        // useEffect cleanup
+        return () => {
+            global.removeEventListener('message', listener);
+        };
+    }, [srcWindow, type, callback]);
+}
+/**
+ * Called by the Plugin component to use events that were listened to (ie. PLUGIN_RESIZE)
+ */
+export function useHostEvent(type, callback) {
+    useMessageEvent(global.parent, type, callback);
+}
+/**
+ * Used to listen for events from a wrapped Plugin element (eg. PluginContainerIframe)
+ *
+ * @param element - Plugin element (eg. <iframe>)
+ * @param type - Event type (eg. PLUGIN_RESIZE)
+ * @param callback - Function to call when the event is triggered
+ */
+export function usePluginEvent(element, type, callback) {
+    const contentWindow = element ? element.contentWindow : null;
+    useMessageEvent(contentWindow, type, callback);
+}
+/** Dispatching events */
+/**
+ * Base dispatch function called by dispatchHostEvent and dispatchPluginEvent.
+ * Uses the `postMessage` method to enable cross-origin communication between Window objects
+ *
+ * @param targetWindow - Window that the message event is being dispatched to
+ * @param message - Data object for the message
+ * @param targetOrigin - URL for the window that the message event is being dispatched from
+ */
+export function dispatchMessageEvent(targetWindow, message, targetOrigin) {
+    /** Checking targetOrigin falsiness here since '', null or undefined would all be
+     * reasons not to try to post a message to the origin.
+     */
+    if (targetWindow && targetOrigin) {
+        targetWindow.postMessage(message, targetOrigin);
+    }
+}
+/**
+ * Used to dispatch events for a Plugin
+ *
+ * @param element - Plugin element (eg. <iframe>)
+ * @param message - Data object for the message
+ * @param targetOrigin - URL for the window that the message event is being dispatched from
+ */
+export function dispatchPluginEvent(element, message, targetOrigin) {
+    dispatchMessageEvent(element.contentWindow, message, targetOrigin);
+}
+/**
+ * Used to dispatch events for the Host
+ *
+ * @param message - Data object for the message
+ */
+export function dispatchHostEvent(message) {
+    dispatchMessageEvent(global.parent, message, global.document.referrer);
+}
+// Called inside Plugin when 'ready' prop is true
+export function dispatchReadyEvent() {
+    dispatchHostEvent({ type: IFRAME_READY });
+}
+// Below mounted events are called in a useEffect inside Plugin with [] dependencies — https://react.dev/learn/synchronizing-with-effects
+export function dispatchMountedEvent() {
+    dispatchHostEvent({ type: IFRAME_MOUNTED });
+}
+export function dispatchUnmountedEvent() {
+    dispatchHostEvent({ type: IFRAME_UNMOUNTED });
+}
+/**
+ * Used to determine the size of an element as it is being resized in the browser.
+ * ResizeObserver (https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) is used to maintain a reference to the element's content/border box.
+ *
+ * @returns Memoized value that contains a reference to the Plugin element (eg. iframe)
+ */
+export function useElementSize() {
+    // Holds a reference to the ResizeObserver
+    const observerRef = useRef(null);
+    const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+    const [offset, setOffset] = useState({ x: 0, y: 0 });
+    const [element, setElement] = useState();
+    // Sets a reference to the Plugin element when passed to the Plugin element as a "ref" attribute (eg. <iframe>)
+    const measuredRef = useCallback(_element => {
+        setElement(_element);
+    }, []);
+    useEffect(() => {
+        // Create a new ResizeObserver
+        observerRef.current = new ResizeObserver(() => {
+            if (element) {
+                // Set dimensions and any offset
+                setDimensions({
+                    width: element.clientWidth,
+                    height: element.clientHeight,
+                });
+                setOffset({
+                    x: element.offsetLeft,
+                    y: element.offsetTop,
+                });
+            }
+        });
+        if (element) {
+            // Tell the ResizeObserver to start watching the element — this enables the hook to detect resizing
+            observerRef.current.observe(element);
+        }
+    }, [element]);
+    return useMemo(() => ({
+        ref: measuredRef,
+        element: element,
+        width: dimensions.width,
+        height: dimensions.height,
+        x: offset.x,
+        y: offset.y
+    }), [measuredRef, element, dimensions, offset]);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/runtime/slots/widget/iframe/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../../../runtime/slots/widget/iframe/hooks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAEL,WAAW,EACX,SAAS,EACT,eAAe,EACf,OAAO,EACP,MAAM,EACN,QAAQ,EACT,MAAM,OAAO,CAAC;AAEf,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG7E,0BAA0B;AAE1B;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,SAAwB,EAAE,IAAY,EAAE,QAA8B;IACpG,mEAAmE;IACnE,eAAe,CAAC,GAAG,EAAE;QACnB,sCAAsC;QACtC,MAAM,QAAQ,GAAG,CAAC,KAAmD,EAAE,EAAE;YACvE,mDAAmD;YACnD,6FAA6F;YAC7F,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC/B,4FAA4F;gBAC5F,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBAC7B,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;gBAClD,CAAC;YACH,CAAC;QACH,CAAC,CAAC;QACF,qEAAqE;QACrE,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC/C,CAAC;QACD,oBAAoB;QACpB,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAClD,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,QAA8B;IACvE,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAsC,EAAE,IAAY,EAAE,QAA8B;IACjH,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7D,eAAe,CAAC,aAAa,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED,yBAAyB;AAEzB;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAA2B,EAAE,OAAY,EAAE,YAAoB;IAClG;;OAEG;IACH,IAAI,YAAY,IAAI,YAAY,EAAE,CAAC;QACjC,YAAY,CAAC,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAClD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA0B,EAAE,OAAY,EAAE,YAAoB;IAChG,oBAAoB,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAY;IAC5C,oBAAoB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACzE,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,kBAAkB;IAChC,iBAAiB,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,yIAAyI;AACzI,MAAM,UAAU,oBAAoB;IAClC,iBAAiB,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,0CAA0C;IAC1C,MAAM,WAAW,GAAG,MAAM,CAAwB,IAAI,CAAC,CAAC;IAExD,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IACtE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACrD,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,EAAiC,CAAC;IACxE,+GAA+G;IAC/G,MAAM,WAAW,GAAiC,WAAW,CAAC,QAAQ,CAAC,EAAE;QACvE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,SAAS,CAAC,GAAG,EAAE;QACb,8BAA8B;QAC9B,WAAW,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE;YAC5C,IAAI,OAAO,EAAE,CAAC;gBACZ,gCAAgC;gBAChC,aAAa,CAAC;oBACZ,KAAK,EAAE,OAAO,CAAC,WAAW;oBAC1B,MAAM,EAAE,OAAO,CAAC,YAAY;iBAC7B,CAAC,CAAC;gBACH,SAAS,CAAC;oBACR,CAAC,EAAE,OAAO,CAAC,UAAU;oBACrB,CAAC,EAAE,OAAO,CAAC,SAAS;iBACrB,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,EAAE,CAAC;YACZ,mGAAmG;YACnG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,OAAO,OAAO,CAQZ,GAAG,EAAE,CAAC,CAAC;QACL,GAAG,EAAE,WAAW;QAChB,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,CAAC,EAAE,MAAM,CAAC,CAAC;QACX,CAAC,EAAE,MAAM,CAAC,CAAC;KACZ,CAAC,EACF,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAC3C,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Hooks file for functions that handle the communication between a Plugin and its Host\n */\n\nimport {\n  LegacyRef,\n  useCallback,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState\n} from 'react';\n\nimport { IFRAME_MOUNTED, IFRAME_READY, IFRAME_UNMOUNTED } from './constants';\nimport { MessageEventCallback } from './types';\n\n/* Listening for events */\n\n/**\n * Dynamically add an event listener to the provided source window.\n * The source window can be the global parent (ie. the \"window\" object in the browser)\n * or it can be the content window of an individual element (ie. iFrame plugin container)\n */\nexport function useMessageEvent(srcWindow: Window | null, type: string, callback: MessageEventCallback) {\n  // useLayoutEffect is called before the browser repaints the screen\n  useLayoutEffect(() => {\n    // Create a listener callback function\n    const listener = (event: MessageEvent<{ type: string, payload: any }>) => {\n      // Filter messages to those from our source window.\n      // NOTE: the \"srcWindow\" is determined by the below useHostEvent and usePluginEvent functions\n      if (event.source === srcWindow) {\n        // Fire callback if the type from the listened event matches the type from the message event\n        if (event.data.type === type) {\n          callback({ type, payload: event.data.payload });\n        }\n      }\n    };\n    // Add the listener to the global object if the srcWindow is not null\n    if (srcWindow !== null) {\n      global.addEventListener('message', listener);\n    }\n    // useEffect cleanup\n    return () => {\n      global.removeEventListener('message', listener);\n    };\n  }, [srcWindow, type, callback]);\n}\n\n/**\n * Called by the Plugin component to use events that were listened to (ie. PLUGIN_RESIZE)\n */\nexport function useHostEvent(type: string, callback: MessageEventCallback) {\n  useMessageEvent(global.parent, type, callback);\n}\n\n/**\n * Used to listen for events from a wrapped Plugin element (eg. PluginContainerIframe)\n *\n * @param element - Plugin element (eg. <iframe>)\n * @param type - Event type (eg. PLUGIN_RESIZE)\n * @param callback - Function to call when the event is triggered\n */\nexport function usePluginEvent(element: HTMLIFrameElement | undefined, type: string, callback: MessageEventCallback) {\n  const contentWindow = element ? element.contentWindow : null;\n  useMessageEvent(contentWindow, type, callback);\n}\n\n/** Dispatching events */\n\n/**\n * Base dispatch function called by dispatchHostEvent and dispatchPluginEvent.\n * Uses the `postMessage` method to enable cross-origin communication between Window objects\n *\n * @param targetWindow - Window that the message event is being dispatched to\n * @param message - Data object for the message\n * @param targetOrigin - URL for the window that the message event is being dispatched from\n */\nexport function dispatchMessageEvent(targetWindow: Window | null, message: any, targetOrigin: string) {\n  /** Checking targetOrigin falsiness here since '', null or undefined would all be\n   * reasons not to try to post a message to the origin.\n   */\n  if (targetWindow && targetOrigin) {\n    targetWindow.postMessage(message, targetOrigin);\n  }\n}\n\n/**\n * Used to dispatch events for a Plugin\n *\n * @param element - Plugin element (eg. <iframe>)\n * @param message - Data object for the message\n * @param targetOrigin - URL for the window that the message event is being dispatched from\n */\nexport function dispatchPluginEvent(element: HTMLIFrameElement, message: any, targetOrigin: string) {\n  dispatchMessageEvent(element.contentWindow, message, targetOrigin);\n}\n\n/**\n * Used to dispatch events for the Host\n *\n * @param message - Data object for the message\n */\nexport function dispatchHostEvent(message: any) {\n  dispatchMessageEvent(global.parent, message, global.document.referrer);\n}\n\n// Called inside Plugin when 'ready' prop is true\nexport function dispatchReadyEvent() {\n  dispatchHostEvent({ type: IFRAME_READY });\n}\n\n// Below mounted events are called in a useEffect inside Plugin with [] dependencies — https://react.dev/learn/synchronizing-with-effects\nexport function dispatchMountedEvent() {\n  dispatchHostEvent({ type: IFRAME_MOUNTED });\n}\n\nexport function dispatchUnmountedEvent() {\n  dispatchHostEvent({ type: IFRAME_UNMOUNTED });\n}\n\n/**\n * Used to determine the size of an element as it is being resized in the browser.\n * ResizeObserver (https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) is used to maintain a reference to the element's content/border box.\n *\n * @returns Memoized value that contains a reference to the Plugin element (eg. iframe)\n */\nexport function useElementSize() {\n  // Holds a reference to the ResizeObserver\n  const observerRef = useRef<ResizeObserver | null>(null);\n\n  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });\n  const [offset, setOffset] = useState({ x: 0, y: 0 });\n  const [element, setElement] = useState<HTMLIFrameElement | undefined>();\n  // Sets a reference to the Plugin element when passed to the Plugin element as a \"ref\" attribute (eg. <iframe>)\n  const measuredRef: LegacyRef<HTMLIFrameElement> = useCallback(_element => {\n    setElement(_element);\n  }, []);\n\n  useEffect(() => {\n    // Create a new ResizeObserver\n    observerRef.current = new ResizeObserver(() => {\n      if (element) {\n        // Set dimensions and any offset\n        setDimensions({\n          width: element.clientWidth,\n          height: element.clientHeight,\n        });\n        setOffset({\n          x: element.offsetLeft,\n          y: element.offsetTop,\n        });\n      }\n    });\n    if (element) {\n      // Tell the ResizeObserver to start watching the element — this enables the hook to detect resizing\n      observerRef.current.observe(element);\n    }\n  }, [element]);\n\n  return useMemo<{\n    ref: LegacyRef<HTMLIFrameElement>,\n    element: HTMLIFrameElement | undefined,\n    width: number,\n    height: number,\n    x: number,\n    y: number,\n  }>(\n    () => ({\n      ref: measuredRef,\n      element: element,\n      width: dimensions.width,\n      height: dimensions.height,\n      x: offset.x,\n      y: offset.y\n    }),\n    [measuredRef, element, dimensions, offset],\n  );\n}\n"]}

package/{runtime/slots/widget/iframe/index.ts → dist/runtime/slots/widget/iframe/index.d.ts}

@@ -1,6 +1,3 @@
 export { default as IFrameContentWrapper } from './IFrameContentWrapper';
 export { default as IFrameWidget } from './IFrameWidget';
-export type {
-  MessageEventCallback,
-  MessageEventCallbackParams
-} from './types';
+export type { MessageEventCallback, MessageEventCallbackParams } from './types';

package/dist/runtime/slots/widget/iframe/index.js

@@ -0,0 +1,3 @@
+export { default as IFrameContentWrapper } from './IFrameContentWrapper';
+export { default as IFrameWidget } from './IFrameWidget';
+//# sourceMappingURL=index.js.map

package/dist/runtime/slots/widget/iframe/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../runtime/slots/widget/iframe/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["export { default as IFrameContentWrapper } from './IFrameContentWrapper';\nexport { default as IFrameWidget } from './IFrameWidget';\nexport type {\n  MessageEventCallback,\n  MessageEventCallbackParams\n} from './types';\n"]}

package/{runtime/slots/widget/iframe/types.ts → dist/runtime/slots/widget/iframe/types.d.ts}

@@ -1,7 +1,5 @@
 export interface MessageEventCallbackParams {
-  type: string,
-  payload: any,
+    type: string;
+    payload: any;
 }
-
 export type MessageEventCallback = ({ type, payload }: MessageEventCallbackParams) => void;
-;

package/dist/runtime/slots/widget/iframe/types.js

@@ -0,0 +1,3 @@
+;
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/slots/widget/iframe/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../runtime/slots/widget/iframe/types.ts"],"names":[],"mappings":"AAMA,CAAC","sourcesContent":["export interface MessageEventCallbackParams {\n  type: string,\n  payload: any,\n}\n\nexport type MessageEventCallback = ({ type, payload }: MessageEventCallbackParams) => void;\n;\n"]}

package/dist/runtime/slots/widget/index.js

@@ -0,0 +1,6 @@
+export * from './hooks';
+export * from './iframe';
+export { WidgetOperationTypes } from './types';
+export * from './utils';
+export { default as WidgetContext } from './WidgetContext';
+//# sourceMappingURL=index.js.map

package/dist/runtime/slots/widget/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../runtime/slots/widget/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AAEzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["export * from './hooks';\nexport * from './iframe';\nexport type * from './types';\nexport { WidgetOperationTypes } from './types';\nexport * from './utils';\nexport { default as WidgetContext } from './WidgetContext';\n"]}

package/{runtime/slots/widget/types.ts → dist/runtime/slots/widget/types.d.ts}

@@ -7,128 +7,102 @@
  *
  * Relative widget operations depend on a relationship to some other list element, such as "insert before" and "insert after".  Some affect those elements, some add something to the list near them.
  */
-
 import { ReactNode } from 'react';
 import { BaseSlotOperation } from '../types';
-
-export enum WidgetOperationTypes {
-  /**
-   * Adds a widget to the end of the slot's list of widgets.
-   */
-  APPEND = 'widgetAppend',
-
-  /**
-   * Adds a widget to the beginning of the slot's list of widgets.
-   */
-  PREPEND = 'widgetPrepend',
-
-  /**
-   * Adds a widget after the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
-   */
-  INSERT_AFTER = 'widgetInsertAfter',
-
-  /**
-   * Adds a widget before the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
-   */
-  INSERT_BEFORE = 'widgetInsertBefore',
-
-  /**
-   * Removes the specified widget ID and adds a widget in its place.  Multiple "replace" operations on the same widget ID occur in the order they were declared, and only the first will succeed unless the new widget's ID is the same as the one that was removed.
-   */
-  REPLACE = 'widgetReplace',
-
-  /**
-   * Removes the specified widget ID from the slot's list of widgets.  Subsequent relative widget operations on that widget ID will not be applied.
-   */
-  REMOVE = 'widgetRemove',
-
-  /**
-   * Provides options to the specified widget ID.  Multiple "options" operations on the same widget ID will merge with and override any duplicate properties in the options object - last one in wins.
-   */
-  OPTIONS = 'widgetOptions',
+export declare enum WidgetOperationTypes {
+    /**
+     * Adds a widget to the end of the slot's list of widgets.
+     */
+    APPEND = "widgetAppend",
+    /**
+     * Adds a widget to the beginning of the slot's list of widgets.
+     */
+    PREPEND = "widgetPrepend",
+    /**
+     * Adds a widget after the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
+     */
+    INSERT_AFTER = "widgetInsertAfter",
+    /**
+     * Adds a widget before the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
+     */
+    INSERT_BEFORE = "widgetInsertBefore",
+    /**
+     * Removes the specified widget ID and adds a widget in its place.  Multiple "replace" operations on the same widget ID occur in the order they were declared, and only the first will succeed unless the new widget's ID is the same as the one that was removed.
+     */
+    REPLACE = "widgetReplace",
+    /**
+     * Removes the specified widget ID from the slot's list of widgets.  Subsequent relative widget operations on that widget ID will not be applied.
+     */
+    REMOVE = "widgetRemove",
+    /**
+     * Provides options to the specified widget ID.  Multiple "options" operations on the same widget ID will merge with and override any duplicate properties in the options object - last one in wins.
+     */
+    OPTIONS = "widgetOptions"
 }
-
 export type AbsoluteWidgetOperationTypes = WidgetOperationTypes.APPEND | WidgetOperationTypes.PREPEND;
-
 export type RelativeWidgetOperationTypes = WidgetOperationTypes.INSERT_AFTER | WidgetOperationTypes.INSERT_BEFORE | WidgetOperationTypes.REPLACE | WidgetOperationTypes.OPTIONS;
-
 export interface BaseWidgetOperation extends BaseSlotOperation {
-  op: WidgetOperationTypes,
+    op: WidgetOperationTypes;
 }
-
-// Widget renderer props
-
 export interface WidgetComponentProps {
-  component: React.ComponentType,
+    component: React.ComponentType;
 }
-
 export interface WidgetElementProps {
-  element: ReactNode,
+    element: ReactNode;
 }
-
 export interface WidgetIFrameProps {
-  url: string,
-  title: string,
+    url: string;
+    title: string;
 }
-
-export type WidgetRendererProps = (
-  WidgetComponentProps | WidgetElementProps | WidgetIFrameProps
-);
-
+export type WidgetRendererProps = (WidgetComponentProps | WidgetElementProps | WidgetIFrameProps);
 export interface WidgetIdentityProps {
-  id: string,
-  role?: string,
+    id: string;
+    role?: string;
 }
-
 export interface WidgetRelationshipProps {
-  relatedId: string,
+    relatedId: string;
 }
-
-// Concrete UI Widget Operations
-
 export type WidgetAppendOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & {
-  op: WidgetOperationTypes.APPEND,
+    op: WidgetOperationTypes.APPEND;
 };
-
 export type WidgetPrependOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & {
-  op: WidgetOperationTypes.PREPEND,
+    op: WidgetOperationTypes.PREPEND;
 };
-
 export type WidgetInsertAfterOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & {
-  op: WidgetOperationTypes.INSERT_AFTER,
+    op: WidgetOperationTypes.INSERT_AFTER;
 };
-
 export type WidgetInsertBeforeOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & {
-  op: WidgetOperationTypes.INSERT_BEFORE,
+    op: WidgetOperationTypes.INSERT_BEFORE;
 };
-
 export type WidgetRemoveOperation = BaseWidgetOperation & WidgetRelationshipProps & {
-  op: WidgetOperationTypes.REMOVE,
+    op: WidgetOperationTypes.REMOVE;
 };
-
 export type WidgetOptionsOperation = BaseWidgetOperation & WidgetRelationshipProps & {
-  op: WidgetOperationTypes.OPTIONS,
-  options: Record<string, unknown>,
+    op: WidgetOperationTypes.OPTIONS;
+    options: Record<string, unknown>;
+};
+export type WidgetReplaceOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & {
+    op: WidgetOperationTypes.REPLACE;
 };
-
-export type WidgetReplaceOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & { op: WidgetOperationTypes.REPLACE };
-
 export type WidgetAbsoluteOperation = WidgetAppendOperation | WidgetPrependOperation;
-
 export type WidgetRelativeRendererOperation = WidgetInsertAfterOperation | WidgetInsertBeforeOperation | WidgetReplaceOperation;
-
 export type WidgetRelativeOperation = WidgetRelativeRendererOperation | WidgetRemoveOperation | WidgetOptionsOperation;
-
 export type WidgetRendererOperation = WidgetAbsoluteOperation | WidgetRelativeRendererOperation;
-
 export type WidgetOperation = WidgetAbsoluteOperation | WidgetRelativeOperation;
-
 /**
  * An identified widget is a simple data structure to associate an ID with a ReactNode so we can
  * apply widget operations to our list of widgets.  It helps us find a ReactNode with a particular
  * ID for relative widget operations.
  */
 export interface IdentifiedWidget {
-  id: string,
-  node: ReactNode,
+    id: string;
+    role?: string;
+    node: ReactNode;
+}
+export interface WidgetList extends Array<ReactNode> {
+    identified: IdentifiedWidget[];
+    byId(id: string): ReactNode[];
+    withoutId(id: string): ReactNode[];
+    byRole(role: string): ReactNode[];
+    withoutRole(role: string): ReactNode[];
 }

package/dist/runtime/slots/widget/types.js

@@ -0,0 +1,41 @@
+/**
+ * Base UI Widget Operations
+ *
+ * "Widget" operations are a sub-type of UI operations which allow manipulation of the list of widgets (UI components) loaded into the slot.  Widget operations are divided further into two sub-types: absolute and relative.
+ *
+ * Absolute widget operations allow simple list operations like appending and prepending which don't depend on any other list elements.
+ *
+ * Relative widget operations depend on a relationship to some other list element, such as "insert before" and "insert after".  Some affect those elements, some add something to the list near them.
+ */
+export var WidgetOperationTypes;
+(function (WidgetOperationTypes) {
+    /**
+     * Adds a widget to the end of the slot's list of widgets.
+     */
+    WidgetOperationTypes["APPEND"] = "widgetAppend";
+    /**
+     * Adds a widget to the beginning of the slot's list of widgets.
+     */
+    WidgetOperationTypes["PREPEND"] = "widgetPrepend";
+    /**
+     * Adds a widget after the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
+     */
+    WidgetOperationTypes["INSERT_AFTER"] = "widgetInsertAfter";
+    /**
+     * Adds a widget before the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
+     */
+    WidgetOperationTypes["INSERT_BEFORE"] = "widgetInsertBefore";
+    /**
+     * Removes the specified widget ID and adds a widget in its place.  Multiple "replace" operations on the same widget ID occur in the order they were declared, and only the first will succeed unless the new widget's ID is the same as the one that was removed.
+     */
+    WidgetOperationTypes["REPLACE"] = "widgetReplace";
+    /**
+     * Removes the specified widget ID from the slot's list of widgets.  Subsequent relative widget operations on that widget ID will not be applied.
+     */
+    WidgetOperationTypes["REMOVE"] = "widgetRemove";
+    /**
+     * Provides options to the specified widget ID.  Multiple "options" operations on the same widget ID will merge with and override any duplicate properties in the options object - last one in wins.
+     */
+    WidgetOperationTypes["OPTIONS"] = "widgetOptions";
+})(WidgetOperationTypes || (WidgetOperationTypes = {}));
+//# sourceMappingURL=types.js.map

package/dist/runtime/slots/widget/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../runtime/slots/widget/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,CAAN,IAAY,oBAmCX;AAnCD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,+CAAuB,CAAA;IAEvB;;OAEG;IACH,iDAAyB,CAAA;IAEzB;;OAEG;IACH,0DAAkC,CAAA;IAElC;;OAEG;IACH,4DAAoC,CAAA;IAEpC;;OAEG;IACH,iDAAyB,CAAA;IAEzB;;OAEG;IACH,+CAAuB,CAAA;IAEvB;;OAEG;IACH,iDAAyB,CAAA;AAC3B,CAAC,EAnCW,oBAAoB,KAApB,oBAAoB,QAmC/B","sourcesContent":["/**\n * Base UI Widget Operations\n *\n * \"Widget\" operations are a sub-type of UI operations which allow manipulation of the list of widgets (UI components) loaded into the slot.  Widget operations are divided further into two sub-types: absolute and relative.\n *\n * Absolute widget operations allow simple list operations like appending and prepending which don't depend on any other list elements.\n *\n * Relative widget operations depend on a relationship to some other list element, such as \"insert before\" and \"insert after\".  Some affect those elements, some add something to the list near them.\n */\n\nimport { ReactNode } from 'react';\nimport { BaseSlotOperation } from '../types';\n\nexport enum WidgetOperationTypes {\n  /**\n   * Adds a widget to the end of the slot's list of widgets.\n   */\n  APPEND = 'widgetAppend',\n\n  /**\n   * Adds a widget to the beginning of the slot's list of widgets.\n   */\n  PREPEND = 'widgetPrepend',\n\n  /**\n   * Adds a widget after the specified widget ID.  Multiple \"insert after\" operations on the same widget ID occur in the order they were declared.\n   */\n  INSERT_AFTER = 'widgetInsertAfter',\n\n  /**\n   * Adds a widget before the specified widget ID.  Multiple \"insert after\" operations on the same widget ID occur in the order they were declared.\n   */\n  INSERT_BEFORE = 'widgetInsertBefore',\n\n  /**\n   * Removes the specified widget ID and adds a widget in its place.  Multiple \"replace\" operations on the same widget ID occur in the order they were declared, and only the first will succeed unless the new widget's ID is the same as the one that was removed.\n   */\n  REPLACE = 'widgetReplace',\n\n  /**\n   * Removes the specified widget ID from the slot's list of widgets.  Subsequent relative widget operations on that widget ID will not be applied.\n   */\n  REMOVE = 'widgetRemove',\n\n  /**\n   * Provides options to the specified widget ID.  Multiple \"options\" operations on the same widget ID will merge with and override any duplicate properties in the options object - last one in wins.\n   */\n  OPTIONS = 'widgetOptions',\n}\n\nexport type AbsoluteWidgetOperationTypes = WidgetOperationTypes.APPEND | WidgetOperationTypes.PREPEND;\n\nexport type RelativeWidgetOperationTypes = WidgetOperationTypes.INSERT_AFTER | WidgetOperationTypes.INSERT_BEFORE | WidgetOperationTypes.REPLACE | WidgetOperationTypes.OPTIONS;\n\nexport interface BaseWidgetOperation extends BaseSlotOperation {\n  op: WidgetOperationTypes,\n}\n\n// Widget renderer props\n\nexport interface WidgetComponentProps {\n  component: React.ComponentType,\n}\n\nexport interface WidgetElementProps {\n  element: ReactNode,\n}\n\nexport interface WidgetIFrameProps {\n  url: string,\n  title: string,\n}\n\nexport type WidgetRendererProps = (\n  WidgetComponentProps | WidgetElementProps | WidgetIFrameProps\n);\n\nexport interface WidgetIdentityProps {\n  id: string,\n  role?: string,\n}\n\nexport interface WidgetRelationshipProps {\n  relatedId: string,\n}\n\n// Concrete UI Widget Operations\n\nexport type WidgetAppendOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & {\n  op: WidgetOperationTypes.APPEND,\n};\n\nexport type WidgetPrependOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & {\n  op: WidgetOperationTypes.PREPEND,\n};\n\nexport type WidgetInsertAfterOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & {\n  op: WidgetOperationTypes.INSERT_AFTER,\n};\n\nexport type WidgetInsertBeforeOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & {\n  op: WidgetOperationTypes.INSERT_BEFORE,\n};\n\nexport type WidgetRemoveOperation = BaseWidgetOperation & WidgetRelationshipProps & {\n  op: WidgetOperationTypes.REMOVE,\n};\n\nexport type WidgetOptionsOperation = BaseWidgetOperation & WidgetRelationshipProps & {\n  op: WidgetOperationTypes.OPTIONS,\n  options: Record<string, unknown>,\n};\n\nexport type WidgetReplaceOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & { op: WidgetOperationTypes.REPLACE };\n\nexport type WidgetAbsoluteOperation = WidgetAppendOperation | WidgetPrependOperation;\n\nexport type WidgetRelativeRendererOperation = WidgetInsertAfterOperation | WidgetInsertBeforeOperation | WidgetReplaceOperation;\n\nexport type WidgetRelativeOperation = WidgetRelativeRendererOperation | WidgetRemoveOperation | WidgetOptionsOperation;\n\nexport type WidgetRendererOperation = WidgetAbsoluteOperation | WidgetRelativeRendererOperation;\n\nexport type WidgetOperation = WidgetAbsoluteOperation | WidgetRelativeOperation;\n\n/**\n * An identified widget is a simple data structure to associate an ID with a ReactNode so we can\n * apply widget operations to our list of widgets.  It helps us find a ReactNode with a particular\n * ID for relative widget operations.\n */\nexport interface IdentifiedWidget {\n  id: string,\n  role?: string,\n  node: ReactNode,\n}\n\nexport interface WidgetList extends Array<ReactNode> {\n  identified: IdentifiedWidget[],\n  byId(id: string): ReactNode[],\n  withoutId(id: string): ReactNode[],\n  byRole(role: string): ReactNode[],\n  withoutRole(role: string): ReactNode[],\n}\n"]}

package/dist/runtime/slots/widget/utils.d.ts

@@ -0,0 +1,22 @@
+import { ReactNode } from 'react';
+import { SlotOperation } from '../types';
+import { WidgetAbsoluteOperation, WidgetAppendOperation, WidgetElementProps, WidgetIdentityProps, WidgetInsertAfterOperation, WidgetInsertBeforeOperation, WidgetList, WidgetOperation, WidgetOperationTypes, WidgetOptionsOperation, WidgetPrependOperation, WidgetRemoveOperation, WidgetRendererOperation, WidgetReplaceOperation } from './types';
+export declare function isWidgetOperation(operation: SlotOperation): operation is WidgetOperation;
+export declare function isWidgetAbsoluteOperation(operation: WidgetOperation): operation is WidgetAbsoluteOperation;
+export declare function isWidgetRelativeOperation(operation: WidgetOperation): operation is (WidgetInsertAfterOperation | WidgetInsertBeforeOperation);
+export declare function isWidgetAppendOperation(operation: SlotOperation): operation is WidgetAppendOperation;
+export declare function isWidgetInsertAfterOperation(operation: SlotOperation): operation is WidgetInsertAfterOperation;
+export declare function isWidgetInsertBeforeOperation(operation: SlotOperation): operation is WidgetInsertBeforeOperation;
+export declare function isWidgetPrependOperation(operation: SlotOperation): operation is WidgetPrependOperation;
+export declare function isWidgetRemoveOperation(operation: SlotOperation): operation is WidgetRemoveOperation;
+export declare function isWidgetReplaceOperation(operation: SlotOperation): operation is WidgetReplaceOperation;
+export declare function isWidgetOptionsOperation(operation: SlotOperation): operation is WidgetOptionsOperation;
+export declare function isWidgetRendererOperation(operation: SlotOperation): operation is WidgetRendererOperation;
+export declare function isWidgetIdentityOperation(operation: SlotOperation): operation is (WidgetOperation & WidgetIdentityProps);
+export declare function isWidgetIdentityRoleOperation(operation: SlotOperation): operation is (WidgetOperation & WidgetIdentityProps & {
+    role: string;
+});
+export declare function createWidgetAppendOperation(id: string, slotId: string, element: ReactNode): (import("./types").BaseWidgetOperation & WidgetIdentityProps & WidgetElementProps & {
+    op: WidgetOperationTypes.APPEND;
+}) | undefined;
+export declare function createWidgets(operations: WidgetOperation[], componentProps?: Record<string, unknown>): WidgetList;