lucid-extension-sdk 0.0.41 → 0.0.44

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lucid-extension-sdk",
-    "version": "0.0.41",
+    "version": "0.0.44",
     "description": "Utility classes for writing Lucid Software editor extensions",
     "main": "sdk/index.js",
     "types": "sdk/index.d.ts",

package/sdk/commandtypes.d.ts

@@ -85,6 +85,7 @@ export declare const enum CommandName {
     SetProperty = "sp",
     SetReferenceKey = "srk",
     SetShapeData = "ssd",
+    SetText = "st",
     ShowModal = "sm",
     ShowPanel = "spn",
     SleepForTestCase = "sleep",
@@ -374,6 +375,10 @@ export declare type CommandArgs = {
         query: SetShapeDataQuery;
         result: SetShapeDataResult;
     };
+    [CommandName.SetText]: {
+        query: SetTextQuery;
+        result: SetTextResult;
+    };
     [CommandName.ShowModal]: {
         query: ShowModalQuery;
         result: ShowModalResult;
@@ -927,6 +932,17 @@ export declare type SetShapeDataQuery = {
     'v'?: SerializedFieldType;
 };
 export declare type SetShapeDataResult = undefined;
+export declare type SetTextQuery = {
+    /** ID of the element to change text on */
+    'id': string;
+    /** Name of the text area to update */
+    'n': string;
+    /** Plain text to put in the text area*/
+    't': string;
+    /** Optional force boolean for extension to update uneditable items*/
+    'f'?: boolean | undefined;
+};
+export declare type SetTextResult = undefined;
 export declare type ShowModalQuery = {
     /** Name of the modal's action for receiving events; generated automatically by Modal base class */
     'n': string;

package/sdk/core/iframe/iframeutils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Aspect ratio 16:9, wider rectangle
+ * This will be the default setting if not provided
+ *
+ * The values are small since we only use width and height value to calculate aspect ratio
+ * So in this case, it will be width/height, which will be 16:9
+ * It's the same result as 1600 and 900 as default width and height
+ */
+export declare const DEFAULT_IFRAME_WIDTH: number;
+export declare const DEFAULT_IFRAME_HEIGHT: number;
+/** @ignore */
+export interface IframeAttributes {
+    /**
+     * The source url
+     */
+    src: string;
+    /**
+     * The list of feature policies allowed
+     * for example, "autoplay; fullscreen;"
+     */
+    allow?: string;
+    /**
+     * The iFrame height
+     */
+    height?: number;
+    /**
+     * The iFrame width
+     */
+    width?: number;
+    /**
+     * The iFrame title for accessibility
+     */
+    title?: string;
+}
+/**
+ * Generate iframe HTML from the IFrameAttributes object
+ * @returns the generated iframe HTML
+ * @ignore
+ * */
+export declare function generateIFrameHTML(iframeAttributes: IframeAttributes): string;
+/**
+ * Parse the iframe HTML, i.e. <iframe>...</iframe> into the IFrameAttributes object
+ * @returns the required attributes to render the target iframe
+ * @ignore
+ */
+export declare function parseIFrameAttributesFromHTML(iframeHTML: string): IframeAttributes;

package/sdk/core/iframe/iframeutils.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseIFrameAttributesFromHTML = exports.generateIFrameHTML = exports.DEFAULT_IFRAME_HEIGHT = exports.DEFAULT_IFRAME_WIDTH = void 0;
+const checks_1 = require("../checks");
+/**
+ * Aspect ratio 16:9, wider rectangle
+ * This will be the default setting if not provided
+ *
+ * The values are small since we only use width and height value to calculate aspect ratio
+ * So in this case, it will be width/height, which will be 16:9
+ * It's the same result as 1600 and 900 as default width and height
+ */
+exports.DEFAULT_IFRAME_WIDTH = 16;
+exports.DEFAULT_IFRAME_HEIGHT = 9;
+/**
+ * Iframes from external sources are not trustworthy to be embedded directly. They could cause security vulnerability,
+ * including XSS attacks. Even if the iframes come from sources with good reputation, it is still a good practice to
+ * sanitize their source HTML and restrict their functionality in the sandbox before embedding them to our apps.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe for a list of iframe attributes.
+ */
+const iframeRegExps = {
+    allow: /allow="(.*?)"/i,
+    src: /src="((https:\/\/|\/\/).*?)"/i,
+    height: /height="(\d*?)"/i,
+    width: /width="(\d*?)"/i,
+    title: /title="(.*?)"/i,
+};
+/**
+ * Generate iframe HTML from the IFrameAttributes object
+ * @returns the generated iframe HTML
+ * @ignore
+ * */
+function generateIFrameHTML(iframeAttributes) {
+    let iframeHTML = `<iframe src="${iframeAttributes.src}"`;
+    if (iframeAttributes.width) {
+        iframeHTML += ` width="${iframeAttributes.width.toString()}"`;
+    }
+    if (iframeAttributes.height) {
+        iframeHTML += ` height="${iframeAttributes.height.toString()}"`;
+    }
+    if (iframeAttributes.title) {
+        // Escape all the double quotation marks
+        const title = iframeAttributes.title.replace(/"/g, '&quot;');
+        iframeHTML += ` title="${title}"`;
+    }
+    if (iframeAttributes.allow) {
+        iframeHTML += ` allow="${iframeAttributes.allow}"`;
+    }
+    iframeHTML += '></iframe>';
+    return iframeHTML;
+}
+exports.generateIFrameHTML = generateIFrameHTML;
+/**
+ * Parse the iframe HTML, i.e. <iframe>...</iframe> into the IFrameAttributes object
+ * @returns the required attributes to render the target iframe
+ * @ignore
+ */
+function parseIFrameAttributesFromHTML(iframeHTML) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const allow = (_b = (_a = iframeHTML.match(iframeRegExps.allow)) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : '';
+    const src = (_d = (_c = iframeHTML.match(iframeRegExps.src)) === null || _c === void 0 ? void 0 : _c[1]) !== null && _d !== void 0 ? _d : '';
+    const height = (_e = iframeHTML.match(iframeRegExps.height)) === null || _e === void 0 ? void 0 : _e[1];
+    const width = (_f = iframeHTML.match(iframeRegExps.width)) === null || _f === void 0 ? void 0 : _f[1];
+    const title = (_h = (_g = iframeHTML.match(iframeRegExps.title)) === null || _g === void 0 ? void 0 : _g[1]) !== null && _h !== void 0 ? _h : '';
+    return {
+        allow: allow,
+        src: src,
+        height: !(0, checks_1.isUndefined)(height) ? Number.parseInt(height) : exports.DEFAULT_IFRAME_HEIGHT,
+        width: !(0, checks_1.isUndefined)(width) ? Number.parseInt(width) : exports.DEFAULT_IFRAME_WIDTH,
+        title: title,
+    };
+}
+exports.parseIFrameAttributesFromHTML = parseIFrameAttributesFromHTML;

package/sdk/core/unfurl/unfurlcallbacks.d.ts

@@ -35,5 +35,5 @@ export interface UnfurlCallbacks {
      * @param blockProxy The block proxy of the unfurl block
      * @ignore
      */
-    afterUnfurlCallback?: (blockProxy: ExperimentalLinkUnfurlBlockProxy) => Promise<void>;
+    afterUnfurlCallback?: (blockProxy: ExperimentalLinkUnfurlBlockProxy, url: string) => Promise<void>;
 }

package/sdk/core/unfurl/unfurldetails.d.ts

@@ -49,7 +49,8 @@ export declare const isValidUnfurlDetails: (subject: unknown) => subject is impo
     UnfurlTitle: (x: unknown) => x is string | undefined;
     Iframe: (x: unknown) => x is import("../guards").DestructureGuardedTypeObj<{
         IframeUrl: typeof isString;
-        Size: (x: unknown) => x is import("./unfurliframe").UnfurlIframeSize.Standard | undefined;
+        AspectRatio: (x: unknown) => x is import("./unfurliframe").UnfurlIframeAspectRatio | undefined;
+        IframeTitle: (x: unknown) => x is string | undefined;
     }> | undefined;
     Thumbnails: (x: unknown) => x is import("../guards").DestructureGuardedTypeObj<{
         url: typeof isString;

package/sdk/core/unfurl/unfurliframe.d.ts

@@ -1,12 +1,30 @@
 import { isString } from '../checks';
 /**
- * An enumeration of of the supported unfurl Iframe sizes.
+ * An enumeration of of the supported unfurl Iframe aspect ratio.
+ * The iframe will be maximized to fit the screen responsively
  */
-export declare enum UnfurlIframeSize {
+export declare enum UnfurlIframeAspectRatio {
     /**
-     * The standard iframe size.
+     * Aspect ratio 1:1, square
      */
-    Standard = "standard"
+    Square = "1:1",
+    /**
+     * Aspect ratio 16:9, wider rectangle
+     * This will be the default setting if not provided
+     */
+    SixteenToNine = "16:9",
+    /**
+     * Aspect ratio 9:16, taller rectangle
+     */
+    NineToSixteen = "9:16",
+    /**
+     * Aspect ratio 4:3, wider rectangle
+     */
+    FourToThree = "4:3",
+    /**
+     * Aspect ratio 3:4, taller rectangle
+     */
+    ThreeToFour = "3:4"
 }
 /**
  * A definition of the properties needed to expand an iframe for an unfurl
@@ -18,20 +36,31 @@ export interface UnfurlIframe {
     iframeUrl: string;
     /**
      * The size of the iframe requested
+     * If not provided, 16:9
+     */
+    aspectRatio?: UnfurlIframeAspectRatio;
+    /**
+     * The iframe title for accessibility
      */
-    size?: UnfurlIframeSize;
+    iframeTitle?: string;
 }
 /** @ignore */
 export interface SerializedUnfurlIframe {
     'IframeUrl': string;
-    'Size'?: UnfurlIframeSize;
+    'AspectRatio'?: UnfurlIframeAspectRatio;
+    'IframeTitle'?: string;
 }
 /** @ignore */
 export declare const isValidUnfurlIframe: (subject: unknown) => subject is import("../guards").DestructureGuardedTypeObj<{
     IframeUrl: typeof isString;
-    Size: (x: unknown) => x is UnfurlIframeSize.Standard | undefined;
+    AspectRatio: (x: unknown) => x is UnfurlIframeAspectRatio | undefined;
+    IframeTitle: (x: unknown) => x is string | undefined;
 }>;
 /** @ignore */
 export declare function deserializeUnfurlIframe(raw: SerializedUnfurlIframe): UnfurlIframe;
 /** @ignore */
 export declare function serializeUnfurlIframe(concrete: UnfurlIframe): SerializedUnfurlIframe;
+/** @ignore */
+export declare function getIFrameHeight(unfurlIframeAspectRatio: UnfurlIframeAspectRatio): number;
+/** @ignore */
+export declare function getIFrameWidth(unfurlIframeAspectRatio: UnfurlIframeAspectRatio): number;

package/sdk/core/unfurl/unfurliframe.js

@@ -1,28 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serializeUnfurlIframe = exports.deserializeUnfurlIframe = exports.isValidUnfurlIframe = exports.UnfurlIframeSize = void 0;
+exports.getIFrameWidth = exports.getIFrameHeight = exports.serializeUnfurlIframe = exports.deserializeUnfurlIframe = exports.isValidUnfurlIframe = exports.UnfurlIframeAspectRatio = void 0;
 const checks_1 = require("../checks");
 const validators_1 = require("../validators/validators");
 /**
- * An enumeration of of the supported unfurl Iframe sizes.
+ * An enumeration of of the supported unfurl Iframe aspect ratio.
+ * The iframe will be maximized to fit the screen responsively
  */
-var UnfurlIframeSize;
-(function (UnfurlIframeSize) {
+var UnfurlIframeAspectRatio;
+(function (UnfurlIframeAspectRatio) {
     /**
-     * The standard iframe size.
+     * Aspect ratio 1:1, square
      */
-    UnfurlIframeSize["Standard"] = "standard";
-})(UnfurlIframeSize = exports.UnfurlIframeSize || (exports.UnfurlIframeSize = {}));
+    UnfurlIframeAspectRatio["Square"] = "1:1";
+    /**
+     * Aspect ratio 16:9, wider rectangle
+     * This will be the default setting if not provided
+     */
+    UnfurlIframeAspectRatio["SixteenToNine"] = "16:9";
+    /**
+     * Aspect ratio 9:16, taller rectangle
+     */
+    UnfurlIframeAspectRatio["NineToSixteen"] = "9:16";
+    /**
+     * Aspect ratio 4:3, wider rectangle
+     */
+    UnfurlIframeAspectRatio["FourToThree"] = "4:3";
+    /**
+     * Aspect ratio 3:4, taller rectangle
+     */
+    UnfurlIframeAspectRatio["ThreeToFour"] = "3:4";
+})(UnfurlIframeAspectRatio = exports.UnfurlIframeAspectRatio || (exports.UnfurlIframeAspectRatio = {}));
 /** @ignore */
 exports.isValidUnfurlIframe = (0, validators_1.objectValidator)({
     'IframeUrl': checks_1.isString,
-    'Size': (0, validators_1.option)((0, validators_1.stringEnumValidator)(UnfurlIframeSize)),
+    'AspectRatio': (0, validators_1.option)((0, validators_1.stringEnumValidator)(UnfurlIframeAspectRatio)),
+    'IframeTitle': (0, validators_1.option)(checks_1.isString),
 });
 /** @ignore */
 function deserializeUnfurlIframe(raw) {
     return {
         iframeUrl: raw['IframeUrl'],
-        size: raw['Size'],
+        aspectRatio: raw['AspectRatio'],
+        iframeTitle: raw['IframeTitle'],
     };
 }
 exports.deserializeUnfurlIframe = deserializeUnfurlIframe;
@@ -30,7 +50,44 @@ exports.deserializeUnfurlIframe = deserializeUnfurlIframe;
 function serializeUnfurlIframe(concrete) {
     return {
         'IframeUrl': concrete.iframeUrl,
-        'Size': concrete.size,
+        'AspectRatio': concrete.aspectRatio,
+        'IframeTitle': concrete.iframeTitle,
     };
 }
 exports.serializeUnfurlIframe = serializeUnfurlIframe;
+/** @ignore */
+function getIFrameHeight(unfurlIframeAspectRatio) {
+    switch (unfurlIframeAspectRatio) {
+        case UnfurlIframeAspectRatio.Square:
+            return 1;
+        case UnfurlIframeAspectRatio.SixteenToNine:
+            return 9;
+        case UnfurlIframeAspectRatio.NineToSixteen:
+            return 16;
+        case UnfurlIframeAspectRatio.FourToThree:
+            return 3;
+        case UnfurlIframeAspectRatio.ThreeToFour:
+            return 4;
+        default:
+            return 9;
+    }
+}
+exports.getIFrameHeight = getIFrameHeight;
+/** @ignore */
+function getIFrameWidth(unfurlIframeAspectRatio) {
+    switch (unfurlIframeAspectRatio) {
+        case UnfurlIframeAspectRatio.Square:
+            return 1;
+        case UnfurlIframeAspectRatio.SixteenToNine:
+            return 16;
+        case UnfurlIframeAspectRatio.NineToSixteen:
+            return 9;
+        case UnfurlIframeAspectRatio.FourToThree:
+            return 4;
+        case UnfurlIframeAspectRatio.ThreeToFour:
+            return 3;
+        default:
+            return 16;
+    }
+}
+exports.getIFrameWidth = getIFrameWidth;

package/sdk/document/blockclasses/linkunfurlblockproxy.d.ts

@@ -1,3 +1,4 @@
+import { UnfurlIframe } from '../../core/unfurl/unfurliframe';
 import { BlockProxy } from '../blockproxy';
 /**
  * @ignore
@@ -12,6 +13,12 @@ export declare class ExperimentalLinkUnfurlBlockProxy extends BlockProxy {
      * @ignore
      */
     getTitle(): string;
+    /**
+     * Sets the title on the block, which is the main text shown on the block.
+     *
+     * @ignore
+     */
+    setTitle(title: string): void;
     /**
      * Returns the name of the service the link belongs to, such as "Lucid" or "Google", as displayed below the title on
      * the block.
@@ -24,7 +31,7 @@ export declare class ExperimentalLinkUnfurlBlockProxy extends BlockProxy {
      *
      * @ignore
      */
-    setIframeUrl(iframeUrl: string): void;
+    setIframe(unfurlIframe: UnfurlIframe): void;
     /**
      * Sets the main thumbnail on the block
      *

package/sdk/document/blockclasses/linkunfurlblockproxy.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExperimentalLinkUnfurlBlockProxy = void 0;
+const iframeutils_1 = require("../../core/iframe/iframeutils");
+const unfurliframe_1 = require("../../core/unfurl/unfurliframe");
 const blockproxy_1 = require("../blockproxy");
 /**
  * @ignore
@@ -16,6 +18,14 @@ class ExperimentalLinkUnfurlBlockProxy extends blockproxy_1.BlockProxy {
     getTitle() {
         return this.textAreas.get('t_LinkUnfurlTitle');
     }
+    /**
+     * Sets the title on the block, which is the main text shown on the block.
+     *
+     * @ignore
+     */
+    setTitle(title) {
+        this.textAreas.set('t_LinkUnfurlTitle', title, { force: true });
+    }
     /**
      * Returns the name of the service the link belongs to, such as "Lucid" or "Google", as displayed below the title on
      * the block.
@@ -30,8 +40,16 @@ class ExperimentalLinkUnfurlBlockProxy extends blockproxy_1.BlockProxy {
      *
      * @ignore
      */
-    setIframeUrl(iframeUrl) {
-        throw new Error('Not yet implemented');
+    setIframe(unfurlIframe) {
+        const iframeAttributes = {
+            src: unfurlIframe.iframeUrl,
+            height: unfurlIframe.aspectRatio ? (0, unfurliframe_1.getIFrameHeight)(unfurlIframe.aspectRatio) : iframeutils_1.DEFAULT_IFRAME_HEIGHT,
+            width: unfurlIframe.aspectRatio ? (0, unfurliframe_1.getIFrameWidth)(unfurlIframe.aspectRatio) : iframeutils_1.DEFAULT_IFRAME_WIDTH,
+            title: unfurlIframe.iframeTitle,
+        };
+        this.properties.set('LinkUnfurlIframeHtml', (0, iframeutils_1.generateIFrameHTML)(iframeAttributes));
+        this.properties.set('LinkUnfurlIframeHeight', iframeAttributes.height);
+        this.properties.set('LinkUnfurlIframeWidth', iframeAttributes.width);
     }
     /**
      * Sets the main thumbnail on the block

package/sdk/document/itemproxy.js

@@ -21,10 +21,11 @@ class ItemProxy extends elementproxy_1.ElementProxy {
         this.textAreas = new mapproxy_1.WriteableMapProxy(() => this.client.sendCommand("lta" /* ListTextAreas */, this.id), (name) => this.client.sendCommand("gp" /* GetProperty */, {
             'id': this.id,
             'p': name,
-        }), (name, plainText) => this.client.sendCommand("sp" /* SetProperty */, {
+        }), (name, plainText, options) => this.client.sendCommand("st" /* SetText */, {
             'id': this.id,
-            'p': name,
-            'v': plainText,
+            'n': name,
+            't': plainText,
+            'f': options === null || options === void 0 ? void 0 : options.force,
         }));
     }
     /**

package/sdk/document/mapproxy.d.ts

@@ -17,6 +17,9 @@ export declare class MapProxy<KEY, VALUE> {
 }
 export declare class WriteableMapProxy<KEY, VALUE> extends MapProxy<KEY, VALUE> {
     private readonly setter;
-    constructor(getKeys: () => KEY[], getItem: (key: KEY) => VALUE, setter: (key: KEY, val: VALUE) => void);
-    set(key: KEY, value: VALUE): void;
+    constructor(getKeys: () => KEY[], getItem: (key: KEY) => VALUE, setter: (key: KEY, val: VALUE, options?: SetterOptions) => void);
+    set(key: KEY, value: VALUE, options?: SetterOptions): void;
+}
+export interface SetterOptions {
+    force?: boolean;
 }

package/sdk/document/mapproxy.js

@@ -58,8 +58,8 @@ class WriteableMapProxy extends MapProxy {
         super(getKeys, getItem);
         this.setter = setter;
     }
-    set(key, value) {
-        this.setter(key, value);
+    set(key, value, options = {}) {
+        this.setter(key, value, options);
     }
 }
 exports.WriteableMapProxy = WriteableMapProxy;

package/sdk/editorclient.js

@@ -220,7 +220,7 @@ class EditorClient {
                     if (msg.blockId) {
                         const proxy = this.getBlockProxy(msg.blockId);
                         if (proxy instanceof linkunfurlblockproxy_1.ExperimentalLinkUnfurlBlockProxy) {
-                            await ((_a = callbacks.afterUnfurlCallback) === null || _a === void 0 ? void 0 : _a.call(callbacks, proxy));
+                            await ((_a = callbacks.afterUnfurlCallback) === null || _a === void 0 ? void 0 : _a.call(callbacks, proxy, msg.url));
                         }
                     }
                 }