@staffbase/widget-sdk 3.3.3 → 3.4.0-alpha.14

package/dist/base-block.d.ts

@@ -0,0 +1,98 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Base class for custom widgets.
+ *
+ * Should be used to extend other custom elements to render their content.
+ * Provides common editing and render capabilities for Staffbase widgets.
+ */
+export interface BaseBlock extends HTMLElement {
+    /**
+     * Called when the widget is rendered in a page.
+     * Override this method in order to display your widget contents.
+     *
+     * Default implementation is a noop.
+     *
+     * @param container an `HTMLElement` into which the contents of the widget should be rendered.
+     * Note that this does not necessarily have to be `this` since the base class might
+     * render a title, a div with a border, or other decorations.
+     */
+    renderBlock(container: HTMLElement): void;
+    /**
+     * Called when the widget is rendered in the WYSIWYG editor.
+     * override this method in order to display your widget preview.
+     *
+     * By default, the editor will display a generic placeholder
+     * with the widget name and icon.
+     *
+     * @param container an `HTMLElement` into which the contents of the widget should be rendered
+     * Note that this does not necessarily have to be `this` since the base class might
+     * render a title, a div with a border, or other decorations.
+     */
+    renderBlockInEditor(container: HTMLElement): void;
+    /**
+     * Called when the widget is unmounted from the DOM.
+     *
+     * Override this in order to implement your unmount logic.
+     *
+     * @param container an `HTMLElement` which was used previously to render the widget.
+     */
+    unmountBlock(container: HTMLElement): void;
+    /**
+     * Called when an attribute is changed.
+     *
+     * Override this in order to get notified about new attribute values.
+     *
+     * NOTE: There are attributes that are common to all widgets. They are handled
+     * inside the base block. Therefore, if you override this method, be sure to
+     * call `super.attributeChangedCallback()` inside your implementation, in
+     * order to let the base class know about the arguments that it might be interested in.
+     */
+    attributeChangedCallback(attrName: string, oldValue: string | undefined, newValue: string | undefined): void;
+    /**
+     * Called after the dialog is closed and the attributes are set on the web component.
+     *
+     * Override this if the attributes are handled with a different logic then the default one.
+     *
+     * @param attributes A map of attributes, as defined in the block definition, which have the
+     * types from the form data
+     *
+     * NOTE: The default implementation turns every value in a string, except arrays and object, which
+     * are converted to base64 encoded data uris in the format `data:text/plain;base64,...`
+     */
+    parseConfig<T extends Record<string, any>>(attributes: T): Record<string, string>;
+    /**
+     * Called when the config dialog is opened. The dialog uses the parsed attributes, to fill
+     * the fields with the existing values.
+     *
+     * Uses the property blockDefinition.attributes to parse each indidividual attribute and
+     * returns it in the format, the configuration form needs. The common attributes are handled
+     * externally
+     *
+     * This method is the counter part of parseConfig, the this must be implemented, if parseConfig
+     * is overriden.
+     *
+     * NOTE: The default implementation converts every string to string, boolean or number and decodes
+     * and parses the data uris to the arrays and objects. Dates are remaining a string!
+     */
+    parseAttributes<T extends Record<string, any>>(): T;
+    /**
+     * The content language as defined in the hosting system. Should be used to provide
+     * the correct localization in the widget.
+     *
+     * NOTE: This is not necessarily the same as the UI language, which is defined by the browser.
+     * When a widget is added to a specific content, the content-language attribute gets automatically set
+     * to that language.
+     */
+    contentLanguage: string;
+}

package/{index.d.ts → dist/base-block.js}

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
@@ -10,13 +10,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
-export * from "./lib/block-attributes";
-export * from "./lib/block-definition";
-export * from "./lib/block-element";
-export * from "./lib/block-factory";
-export * from "./lib/global";
-export * from "./lib/external-block-definition";
-export * from "./lib/base-block";
-export * from './lib/widget-api';
-export * from './lib/widget-api-types';
+export {};

package/{lib/block-attributes.ts → dist/block-attributes.d.ts}

@@ -10,8 +10,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 export interface BlockAttributes {
-  contentLanguage: string;
-  [key: string]: number | boolean | string;
+    contentLanguage: string;
+    [key: string]: number | boolean | string;
 }

package/dist/block-attributes.js

@@ -0,0 +1,13 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/dist/block-definition.d.ts

@@ -0,0 +1,91 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { BlockFactory } from "./block-factory";
+import { JSONSchema7 } from "json-schema";
+import { UiSchema } from '@rjsf/core';
+export interface BlockDefinition<Factory = BlockFactory> {
+    /**
+     * The tag name of the widget. It must be compatible with
+     * webcomponent naming conventions.
+     *
+     * @see https://www.webcomponents.org/community/articles/how-should-i-name-my-element
+     */
+    name: string;
+    /**
+     * The implementation of the web component.
+     */
+    factory: Factory;
+    /**
+     * Can be used for extending from a built-in element.
+     */
+    options?: ElementDefinitionOptions;
+    /**
+     * DOM attributes of the element, must be in kebab-case.
+     */
+    attributes: string[];
+    /**
+     * Set to `inline` if you want the element to behave like a span element
+     * rather than a div element if not specified, it defaults to `block`.
+     */
+    blockLevel?: "block" | "inline";
+    /**
+     * Schema used for defining the configuration form.
+     *
+     * @example
+     * ```json
+     * {
+     *  "type": "object",
+     *  "required": [
+     *    "firstName",
+     *    "lastName"
+     *    ],
+     *  "properties": {
+     *    "firstName": {
+     *      "type": "string",
+     *      "title": "First name"
+     *      },
+     *  "lastName": {
+     *    "type": "string",
+     *    "title": "Last name"
+     *    }
+     *  }
+     * }
+     * ```
+     * @see https://react-jsonschema-form.readthedocs.io/en/latest/
+     */
+    configurationSchema: JSONSchema7;
+    /**
+     *
+     * Schema to add more customization to the look and feel of the configuration form.
+     *
+     * ```json
+     * {
+     *   "firstName": {
+     *      "ui:help": "Your first name."
+     *   }
+     * }
+     * ```
+     *
+     * @see https://react-jsonschema-form.readthedocs.io/en/latest/api-reference/uiSchema/
+     */
+    uiSchema?: UiSchema;
+    /**
+     * Label displayed in the settings dialog and in the default widget preview.
+     */
+    label?: string;
+    /**
+     * Icon displayed on the widget installation page.
+     * We recommend an icon with the dimensions 32x32 px.
+     */
+    iconUrl?: string;
+}

package/dist/block-definition.js

@@ -0,0 +1,13 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/dist/block-element.d.ts

@@ -0,0 +1,45 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface BlockElement {
+    /**
+     * Static getter to determine which HTML attributes should trigger the function 'attributeChangedCallback';
+     */
+    /**
+     * Invoked when the custom element is first connected to the DOM.
+     */
+    connectedCallback: () => void;
+    /**
+     * Invoked when the custom element is disconnected from the DOM.
+     */
+    disconnectedCallback: () => void;
+    /**
+     * Invoked when the custom element is moved to a new document.
+     */
+    adoptedCallback: () => void;
+    /**
+     * Invoked when one of the attributes of the custom element is added, removed, or changed.
+     *
+     * Note that you have to statically register the observed values with the 'observedAttributes' static getter.
+     *
+     * @param attrName The changed attributes name
+     * @param oldValue The old value
+     * @param newValue The new value
+     */
+    attributeChangedCallback: (attrName: string, oldValue: string | undefined, newValue: string | undefined) => void;
+    /**
+     * Method to unmount / revert any effects applied by rendering.
+     * E.g. to be used in editor cases to remove any rendered content
+     * and revert the block to its initial state.
+     */
+    unmount: () => void;
+}

package/dist/block-element.js

@@ -0,0 +1,13 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/{lib/block-factory.ts → dist/block-factory.d.ts}

@@ -10,17 +10,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 import { BaseBlock } from "./base-block";
 import { WidgetApi } from "./widget-api";
-
 /**
  * Factory for the custom widgets.
  *
  * @param Base base class for the custom widgets to inherit from.
  * The class itself is a subclass of `HTMLElement` of the relevant `window` object,
  * with additional functionality.
- * 
+ *
  * @param widgetApi API providing methods for additional information by the Staffbase framework
  *
  * @example
@@ -35,6 +33,4 @@ import { WidgetApi } from "./widget-api";
  *     }
  *   };
  */
-export type BlockFactory = (
-  Base: new () => BaseBlock, widgetApi: WidgetApi
-) => CustomElementConstructor;
+export declare type BlockFactory = (Base: new () => BaseBlock, widgetApi: WidgetApi) => CustomElementConstructor;

package/dist/block-factory.js

@@ -0,0 +1,13 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/{lib/external-block-definition.ts → dist/external-block-definition.d.ts}

@@ -10,10 +10,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
-import { BlockDefinition } from "..";
+import { BlockDefinition } from ".";
 import { BlockFactory } from "./block-factory";
-
 /**
  * Defintion of the Widget.
  *
@@ -21,20 +19,18 @@ import { BlockFactory } from "./block-factory";
  * and meta information (author and version of the widget).
  */
 export interface ExternalBlockDefinition<Factory = BlockFactory> {
-  /**
-   * Definition of the block.
-   *
-   * Will be registered to the staffbase app.
-   */
-  blockDefinition: BlockDefinition<Factory>;
-
-  /**
-   * Current version of the widget.
-   */
-  version: string;
-
-  /**
-   * Name of the author.
-   */
-  author: string;
+    /**
+     * Definition of the block.
+     *
+     * Will be registered to the staffbase app.
+     */
+    blockDefinition: BlockDefinition<Factory>;
+    /**
+     * Current version of the widget.
+     */
+    version: string;
+    /**
+     * Name of the author.
+     */
+    author: string;
 }

package/dist/external-block-definition.js

@@ -0,0 +1,13 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/{lib → dist}/global.d.ts

@@ -10,20 +10,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 import { ExternalBlockDefinition } from "./external-block-definition";
-
 export {};
-
 /**
  * declaration merging
  * to add the defineBlock to the window
  */
 declare global {
-  interface Window {
-    /**
-     * global method to register the widget to the frontend
-     */
-    defineBlock: (widget: ExternalBlockDefinition) => void;
-  }
+    interface Window {
+        /**
+         * global method to register the widget to the frontend
+         */
+        defineBlock: (widget: ExternalBlockDefinition) => void;
+    }
 }

package/dist/global.js

@@ -0,0 +1,13 @@
+/*!
+ * Copyright 2021, Staffbase GmbH and contributors.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './base-block.js';
+export * from './block-attributes.js';
+export * from './block-definition.js';
+export * from './block-element.js';
+export * from './block-factory.js';
+export * from './external-block-definition.js';
+export * from './widget-api-types.js';
+export * from './widget-api.js';
+export * from './global.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './base-block.js';
+export * from './block-attributes.js';
+export * from './block-definition.js';
+export * from './block-element.js';
+export * from './block-factory.js';
+export * from './external-block-definition.js';
+export * from './widget-api-types.js';
+export * from './widget-api.js';
+export * from './global.js';