@appsemble/sdk 0.20.10 → 0.20.13

package/README.md

@@ -1,10 +1,10 @@
-# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.18.23/config/assets/logo.svg) Appsemble SDK
+# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.20.13/config/assets/logo.svg) Appsemble SDK
 
 > Build your own blocks
 
 [![npm](https://img.shields.io/npm/v/@appsemble/sdk)](https://www.npmjs.com/package/@appsemble/sdk)
-[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.18.23/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.18.23)
-[![Code coverage](https://codecov.io/gl/appsemble/appsemble/branch/0.18.23/graph/badge.svg)](https://codecov.io/gl/appsemble/appsemble)
+[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.20.13/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.20.13)
+[![Code coverage](https://codecov.io/gl/appsemble/appsemble/branch/0.20.13/graph/badge.svg)](https://codecov.io/gl/appsemble/appsemble)
 [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)
 
 ## Installation
@@ -144,5 +144,5 @@ declare module '@appsemble/sdk' {
 
 ## License
 
-[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.18.23/LICENSE.md) ©
+[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.20.13/LICENSE.md) ©
 [Appsemble](https://appsemble.com)

package/{dist/index.d.ts → index.d.ts}

@@ -138,9 +138,9 @@ export interface Utils {
     /**
      * Remap data based in a user defined remapper function.
      *
-     * @param remapper - The user defined remapper function.
-     * @param data - The data to remap.
-     * @param context - The context to retrieve contextual data from.
+     * @param remapper The user defined remapper function.
+     * @param data The data to remap.
+     * @param context The context to retrieve contextual data from.
      * @returns The result of the remapped data.
      */
     remap: (remapper: Remapper, data: unknown, context?: Record<string, unknown>) => unknown;
@@ -155,20 +155,20 @@ export interface Utils {
     /**
      * Get a URL serving an asset for the given asset id.
      *
-     * @param assetId - The id of the asset whose URL to get.
+     * @param assetId The id of the asset whose URL to get.
      * @returns The URL that matches the given asset id.
      */
     asset: (assetId: string) => string;
     /**
      * Convert a FontAwesome icon name into a valid FontAwesome CSS class.
      *
-     * @param icon - The FontAwesome icon.
+     * @param icon The FontAwesome icon.
      * @returns String containing the FontAwesome classes for the icon.
      */
     fa: (icon: IconName) => string;
     /**
-     * @param items - The list of menu items to display.
-     * @param header - A header that can be used to separate from other block menus.
+     * @param items The list of menu items to display.
+     * @param header A header that can be used to separate from other block menus.
      */
     menu: (items: MenuItem[], header?: string) => void;
 }
@@ -176,8 +176,8 @@ export interface Events {
     /**
      * Emit an Appsemble event.
      *
-     * @param type - The type of event to emit.
-     * @param data - Data to emit with the event.
+     * @param type The type of event to emit.
+     * @param data Data to emit with the event.
      * @returns Boolean indicating whether an emitter is implemented or not.
      */
     emit: {
@@ -186,8 +186,8 @@ export interface Events {
     /**
      * Remove an event listener for an Appsemble event.
      *
-     * @param type - The type of event to listen remove the listener from.
-     * @param callback - The callback to remove.
+     * @param type The type of event to listen remove the listener from.
+     * @param callback The callback to remove.
      * @returns Boolean indicating whether a listener is implemented or not.
      */
     off: {
@@ -196,8 +196,8 @@ export interface Events {
     /**
      * Add an event listener for an Appsemble event.
      *
-     * @param type - The type of event to listen on.
-     * @param callback - A callback to register for the event.
+     * @param type The type of event to listen on.
+     * @param callback A callback to register for the event.
      * @returns Boolean indicating whether a listener is implemented or not.
      */
     on: {
@@ -266,7 +266,7 @@ export interface AppsembleBootstrapEvent extends CustomEvent {
 /**
  * Register a boostrap function.
  *
- * @param fn - The bootstrap function to register
+ * @param fn The bootstrap function to register
  *
  * If the function returns an element, it’s appended to the shadow root.
  */

package/{dist/index.js → index.js}

@@ -1,7 +1,7 @@
 /**
  * Register a boostrap function.
  *
- * @param fn - The bootstrap function to register
+ * @param fn The bootstrap function to register
  *
  * If the function returns an element, it’s appended to the shadow root.
  */

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAiTA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,EAAqB;IAC7C,MAAM,KAAK,GAA4B,IAAI,WAAW,CAAC,oBAAoB,EAAE;QAC3E,MAAM,EAAE;YACN,EAAE;YACF,QAAQ;SACT;KACF,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,aAAa,EAAE;QAC1B,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;KAC7C;AACH,CAAC"}

package/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/index.test.js

@@ -0,0 +1,31 @@
+import { bootstrap } from '.';
+let event;
+let originalCurrentScript;
+beforeEach(() => {
+    originalCurrentScript = document.currentScript;
+    Object.defineProperty(document, 'currentScript', {
+        value: {
+            dispatchEvent: jest.fn((e) => {
+                event = e;
+            }),
+        },
+        writable: true,
+    });
+});
+afterEach(() => {
+    Object.defineProperty(document, 'currentScript', {
+        value: originalCurrentScript,
+        writable: true,
+    });
+    originalCurrentScript = undefined;
+});
+describe('bootstrap', () => {
+    it('should dispatch the AppsembleBoostrap event', () => {
+        const fn = jest.fn();
+        bootstrap(fn);
+        expect(document.currentScript.dispatchEvent).toHaveBeenCalledWith(new CustomEvent(''));
+        expect(event.type).toBe('AppsembleBootstrap');
+        expect(event.detail).toStrictEqual({ fn, document });
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["index.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC;AAE9B,IAAI,KAAkB,CAAC;AACvB,IAAI,qBAA6C,CAAC;AAElD,UAAU,CAAC,GAAG,EAAE;IACd,qBAAqB,GAAG,QAAQ,CAAC,aAAa,CAAC;IAC/C,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE;QAC/C,KAAK,EAAE;YACL,aAAa,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC3B,KAAK,GAAG,CAAC,CAAC;YACZ,CAAC,CAAC;SACH;QACD,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,SAAS,CAAC,GAAG,EAAE;IACb,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE;QAC/C,KAAK,EAAE,qBAAqB;QAC5B,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,qBAAqB,GAAG,SAAS,CAAC;AACpC,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;QACrB,SAAS,CAAC,EAAE,CAAC,CAAC;QACd,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,oBAAoB,CAAC,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;QACvF,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAC9C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/index.test.ts

@@ -0,0 +1,34 @@
+import { bootstrap } from '.';
+
+let event: CustomEvent;
+let originalCurrentScript: HTMLOrSVGScriptElement;
+
+beforeEach(() => {
+  originalCurrentScript = document.currentScript;
+  Object.defineProperty(document, 'currentScript', {
+    value: {
+      dispatchEvent: jest.fn((e) => {
+        event = e;
+      }),
+    },
+    writable: true,
+  });
+});
+
+afterEach(() => {
+  Object.defineProperty(document, 'currentScript', {
+    value: originalCurrentScript,
+    writable: true,
+  });
+  originalCurrentScript = undefined;
+});
+
+describe('bootstrap', () => {
+  it('should dispatch the AppsembleBoostrap event', () => {
+    const fn = jest.fn();
+    bootstrap(fn);
+    expect(document.currentScript.dispatchEvent).toHaveBeenCalledWith(new CustomEvent(''));
+    expect(event.type).toBe('AppsembleBootstrap');
+    expect(event.detail).toStrictEqual({ fn, document });
+  });
+});

package/index.ts

@@ -0,0 +1,323 @@
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+import type { Action, BaseMessage, BulmaColor, BulmaSize, Theme } from '@appsemble/types';
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+import type { IconName } from '@fortawesome/fontawesome-common-types';
+import { Promisable } from 'type-fest';
+
+export { IconName };
+export { Action, BulmaColor, BulmaSize, Theme };
+
+/**
+ * A user defined remapper function.
+ */
+export type Remapper = object[] | boolean | number | object | string;
+
+/**
+ * Actions defined on a block.
+ *
+ * If a block uses actions, extend this interface using module augmentation. The keys are the names
+ * of the events the block supports.
+ *
+ * @example
+ * declare module '<at>appsemble/sdk' {
+ *   interface Actions {
+ *     onClick: {}
+ *   }
+ * }
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface Actions {}
+
+/**
+ * Messages defined on a block.
+ *
+ * If a block uses messages, extend this interface using module augmentation.
+ * The keys are the names of the messages.
+ * The types are either `never` if the message doesn’t support parameters
+ * or an object containing the keys of values and the type of the value.
+ *
+ * @example
+ * declare module '<at>appsemble/sdk' {
+ *   interface Messages {
+ *     exampleMessage: never;
+ *     hello: { person: string };
+ *   }
+ * }
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface Messages {}
+
+/**
+ * Event emitters defined on a block.
+ *
+ * If a block emits events, extend this interface using module augmentation. The keys are the names
+ * of the events the block can emit.
+ *
+ * @example
+ * declare module '<at>appsemble/sdk' {
+ *   interface EventEmitters {
+ *     data: {}
+ *   }
+ * }
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface EventEmitters {}
+
+/**
+ * Event listeners defined on a block.
+ *
+ * If a block listens on events, extend this interface using module augmentation. The keys are the
+ * names of the events the block can emit.
+ *
+ * @example
+ * declare module '<at>appsemble/sdk' {
+ *   interface EventListeners {
+ *     data: {}
+ *   }
+ * }
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface EventListeners {}
+
+/**
+ * Custom free form parameters defined on a block.
+ *
+ * If a block listens on events, extend this interface using module augmentation. The keys are the
+ * names of the events the block can emit.
+ *
+ * @example
+ * declare module '<at>appsemble/sdk' {
+ *   interface Parameters {
+ *     param1: string;
+ *     param2: number;
+ *     param3: {
+ *       nested: boolean;
+ *     }
+ *   }
+ * }
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface Parameters {}
+
+export type PageParameters = Record<string, string>;
+
+/**
+ * A menu item that can be displayed in addition to the normal app menu.
+ */
+export interface MenuItem {
+  /**
+   * The title of the menu item.
+   */
+  title: string;
+
+  /**
+   * The icon to display next to the title.
+   */
+  icon?: IconName;
+
+  /**
+   * The color to use for the icon.
+   */
+  iconColor?: BulmaColor;
+
+  /**
+   * The click handler for when the menu item is clicked.
+   */
+  onClick: () => void;
+
+  /**
+   * The submenu items associated with this menu item.
+   */
+  submenu?: Omit<MenuItem, 'submenu'>[];
+
+  /**
+   * Whether the item is considered active.
+   */
+  active?: boolean;
+}
+
+export interface Message extends BaseMessage {
+  /**
+   * The content of the message to display.
+   */
+  body: string;
+}
+
+/**
+ * A set of utility functions provided by the Appsemble SDK.
+ */
+export interface Utils {
+  /**
+   * Register a function that should be called when the block is being removed.
+   *
+   * Use this to clean up resouces that would otherwise stay in memory, e.g. object URLs.
+   */
+  addCleanup: (fn: () => void) => void;
+
+  /**
+   * Remap data based in a user defined remapper function.
+   *
+   * @param remapper The user defined remapper function.
+   * @param data The data to remap.
+   * @param context The context to retrieve contextual data from.
+   * @returns The result of the remapped data.
+   */
+  remap: (remapper: Remapper, data: unknown, context?: Record<string, unknown>) => unknown;
+
+  /**
+   * Show a bulma style message.
+   */
+  showMessage: (message: Message | string) => void;
+
+  /**
+   * Formats a message using ICU syntax.
+   */
+  formatMessage: <T extends keyof Messages>(
+    message: T,
+    ...args: Messages[T] extends never ? [] : [Messages[T]]
+  ) => string;
+
+  /**
+   * Get a URL serving an asset for the given asset id.
+   *
+   * @param assetId The id of the asset whose URL to get.
+   * @returns The URL that matches the given asset id.
+   */
+  asset: (assetId: string) => string;
+
+  /**
+   * Convert a FontAwesome icon name into a valid FontAwesome CSS class.
+   *
+   * @param icon The FontAwesome icon.
+   * @returns String containing the FontAwesome classes for the icon.
+   */
+  fa: (icon: IconName) => string;
+
+  /**
+   * @param items The list of menu items to display.
+   * @param header A header that can be used to separate from other block menus.
+   */
+  menu: (items: MenuItem[], header?: string) => void;
+}
+
+export interface Events {
+  /**
+   * Emit an Appsemble event.
+   *
+   * @param type The type of event to emit.
+   * @param data Data to emit with the event.
+   * @returns Boolean indicating whether an emitter is implemented or not.
+   */
+  emit: { [K in keyof EventEmitters]: (data: unknown, error?: string) => Promise<boolean> };
+
+  /**
+   * Remove an event listener for an Appsemble event.
+   *
+   * @param type The type of event to listen remove the listener from.
+   * @param callback The callback to remove.
+   * @returns Boolean indicating whether a listener is implemented or not.
+   */
+  off: {
+    [K in keyof EventListeners]: <T>(callback: (data: T, error?: string) => void) => boolean;
+  };
+
+  /**
+   * Add an event listener for an Appsemble event.
+   *
+   * @param type The type of event to listen on.
+   * @param callback A callback to register for the event.
+   * @returns Boolean indicating whether a listener is implemented or not.
+   */
+  on: {
+    [K in keyof EventListeners]: <T>(callback: (data: T, error?: string) => void) => boolean;
+  };
+}
+
+/**
+ * The parameters that get passed to the bootstrap function.
+ */
+export interface BootstrapParams {
+  /**
+   * The actions that may be dispatched by the block.
+   */
+  actions: { [K in keyof Actions]: Action };
+
+  /**
+   * The parameters as they are defined in the app definition.
+   */
+  parameters: Parameters;
+
+  /**
+   * Any kind of data that has been passed in by some context.
+   */
+  data: unknown;
+
+  /**
+   * Event related functions and constants.
+   */
+  events: Events;
+
+  /**
+   * URL parameters of the current route.
+   *
+   * If the page on which the block is rendered, has parameters specified on a page level, the
+   * parameter keys and values of the page will be extracted and set as this object.
+   */
+  pageParameters?: PageParameters;
+
+  /**
+   * The path of the block as it is being rendered on the page using the page’s normalized name.
+   */
+  path: string;
+
+  /**
+   * The path of the block as it is being rendered on the page using the page’s index.
+   */
+  pathIndex: string;
+
+  /**
+   * The theme of the block given the context.
+   *
+   * This is based on a combination of the base theme, app theme, page theme and block theme.
+   */
+  theme: Theme;
+
+  /**
+   * The shadow root to which DOM elements may be appended.
+   */
+  shadowRoot: ShadowRoot;
+
+  /**
+   * Some utility functions provided by the Appsemble app framework.
+   */
+  utils: Utils;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+export type BootstrapFunction = (params: BootstrapParams) => Promisable<Element | void>;
+
+export interface AppsembleBootstrapEvent extends CustomEvent {
+  detail: {
+    fn: BootstrapFunction;
+    document: Document;
+  };
+}
+
+/**
+ * Register a boostrap function.
+ *
+ * @param fn The bootstrap function to register
+ *
+ * If the function returns an element, it’s appended to the shadow root.
+ */
+export function bootstrap(fn: BootstrapFunction): void {
+  const event: AppsembleBootstrapEvent = new CustomEvent('AppsembleBootstrap', {
+    detail: {
+      fn,
+      document,
+    },
+  });
+  if (document.currentScript) {
+    document.currentScript.dispatchEvent(event);
+  }
+}

package/jest.config.js

@@ -0,0 +1 @@
+module.exports = require('../../config/jest/config')(__dirname);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/sdk",
-  "version": "0.20.10",
+  "version": "0.20.13",
   "description": "Build your own blocks",
   "keywords": [
     "app",
@@ -23,16 +23,17 @@
   "license": "LGPL-3.0-only",
   "author": "Appsemble <info@appsemble.com> (https://appsemble.com)",
   "sideEffects": false,
-  "main": "dist",
   "files": [
-    "dist"
+    "**/*.d.ts",
+    "**/*.js",
+    "!*.config.js"
   ],
   "scripts": {
-    "prepack": "tsc -p tsconfig.build.json",
+    "prepack": "tsc --noEmit false",
     "test": "jest"
   },
   "dependencies": {
-    "@appsemble/types": "0.20.10",
+    "@appsemble/types": "0.20.13",
     "@fortawesome/fontawesome-common-types": "^6.0.0",
     "type-fest": "^2.0.0"
   }

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig",
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"]
+  }
+}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiTA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,EAAqB;IAC7C,MAAM,KAAK,GAA4B,IAAI,WAAW,CAAC,oBAAoB,EAAE;QAC3E,MAAM,EAAE;YACN,EAAE;YACF,QAAQ;SACT;KACF,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,aAAa,EAAE;QAC1B,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;KAC7C;AACH,CAAC"}