lucid-extension-sdk 0.0.40 → 0.0.42

package/package.json

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

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/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
@@ -24,7 +25,7 @@ export declare class ExperimentalLinkUnfurlBlockProxy extends BlockProxy {
      *
      * @ignore
      */
-    setIframeUrl(iframeUrl: string): void;
+    setIframe(unfurlIframe: UnfurlIframe): void;
     /**
      * Sets the main thumbnail on the block
      *
@@ -37,4 +38,41 @@ export declare class ExperimentalLinkUnfurlBlockProxy extends BlockProxy {
      * @ignore
      */
     setThumbnailUrls(thumbnails: string[]): void;
+    /**
+     * @ignore
+     * Initiates the PDF upload for this block. The result includes an uploadUrl which you can use to upload the PDF.
+     * The PDF uploaded at that url will be assocaite with this block (and any copy of it) in the editor until it is refreshed.
+     * @param options The options for the upload
+     */
+    experimentalStartPDFUpload(options: LinkUnfurlPDFOptions): Promise<LinkUnfurlPDFResult>;
+}
+/**
+ * @ignore
+ * Options for starting the PDF upload process for a link unfurl
+ */
+export interface LinkUnfurlPDFOptions {
+    /**
+     * @ignore
+     * The anticipated number of pages. If this is defined, this is the number of pages that will show up while the PDF
+     * is being processed and converted into images. Once converted, the actual number will take precedence.
+     */
+    expectedNumberOfPages: number;
+}
+/**
+ * @ignore
+ * The result of initiating the PDF upload process.
+ */
+export interface LinkUnfurlPDFResult {
+    /**
+     * @ignore
+     * A signed URL you can upload the pdf to. You can do this manually (via the client, your own service) or via the
+     * oauth proxy.
+     */
+    uploadUrl: string;
+    /**
+     * @ignore
+     * The internal identifier to the PDF upload which is associated with the block.
+     * TODO: Determine if we show this to the extension, or keep internal
+     */
+    blobId: string;
 }

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
@@ -30,8 +32,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
@@ -49,6 +59,15 @@ class ExperimentalLinkUnfurlBlockProxy extends blockproxy_1.BlockProxy {
     setThumbnailUrls(thumbnails) {
         this.properties.set('LinkUnfurlThumbnailUrls', thumbnails);
     }
+    /**
+     * @ignore
+     * Initiates the PDF upload for this block. The result includes an uploadUrl which you can use to upload the PDF.
+     * The PDF uploaded at that url will be assocaite with this block (and any copy of it) in the editor until it is refreshed.
+     * @param options The options for the upload
+     */
+    experimentalStartPDFUpload(options) {
+        throw new Error('Not yet implemented');
+    }
 }
 exports.ExperimentalLinkUnfurlBlockProxy = ExperimentalLinkUnfurlBlockProxy;
 ExperimentalLinkUnfurlBlockProxy.classNameRegex = /^LinkUnfurlBlock$/;