create-appsemble 0.20.15 → 0.20.17

package/README.md

@@ -1,10 +1,10 @@
-# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.20.15/config/assets/logo.svg) Appsemble Create
+# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.20.17/config/assets/logo.svg) Appsemble Create
 
 > Bootstrap an Appsemble block
 
 [![npm](https://img.shields.io/npm/v/create-appsemble)](https://www.npmjs.com/package/create-appsemble)
-[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.20.15/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.20.15)
-[![Code coverage](https://codecov.io/gl/appsemble/appsemble/branch/0.20.15/graph/badge.svg)](https://codecov.io/gl/appsemble/appsemble)
+[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.20.17/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.20.17)
+[![Code coverage](https://codecov.io/gl/appsemble/appsemble/branch/0.20.17/graph/badge.svg)](https://codecov.io/gl/appsemble/appsemble)
 [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)
 
 ## Usage
@@ -31,5 +31,5 @@ npm init appsemble block
 
 ## License
 
-[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.20.15/LICENSE.md) ©
+[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.20.17/LICENSE.md) ©
 [Appsemble](https://appsemble.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-appsemble",
-  "version": "0.20.15",
+  "version": "0.20.17",
   "description": "Bootstrap an Appsemble project",
   "keywords": [
     "app",
@@ -33,7 +33,7 @@
     "test": "NODE_OPTIONS=--experimental-vm-modules jest"
   },
   "dependencies": {
-    "@appsemble/node-utils": "0.20.15",
+    "@appsemble/node-utils": "0.20.17",
     "inquirer": "^9.0.0",
     "type-fest": "^2.0.0",
     "yargs": "^17.0.0"

package/templates/mini-jsx/README.md

@@ -0,0 +1,11 @@
+This block was bootstrapped using the following command:
+
+```sh
+npm init appsemble block
+```
+
+This block renders a single data entity that is emitted through an Appsemble block event. It uses
+[`mini-jsx`](https://gitlab.com/appsemble/mini-jsx) to define raw DOM nodes using JSX syntax.
+
+This readme will be rendered on <https://appsemble.app> when the block is published. Replace the
+contents of this document with a useful block description.

package/templates/mini-jsx/block.ts

@@ -1,5 +1,12 @@
+// Blocks can actions, parameters, messages, and event listeners and emitters. These can be defined
+// by augmenting the @appsemble/sdk module. Typically this happens in a file named block.ts. When a
+// block is published, the CLI will process the augmented interfaces and validate the app definition
+// complies with them. The JSDoc will be used to render documentation.
 import { IconName, Remapper } from '@appsemble/sdk';
 
+/**
+ * A field to display.
+ */
 export interface Field {
   /**
    * The value of the property to render.
@@ -19,10 +26,23 @@ export interface Field {
 
 declare module '@appsemble/sdk' {
   interface EventListeners {
-    data: {};
+    /**
+     * The event to listen on for data to display.
+     */
+    data: never;
+  }
+
+  interface Messages {
+    /**
+     * This message is displayed when there was an error loading data.
+     */
+    error: never;
   }
 
   interface Parameters {
+    /**
+     * The fields to display.
+     */
     fields: Field[];
   }
 }

package/templates/mini-jsx/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "error": "There was a problem loading the data."
+}

package/templates/mini-jsx/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@appsemble/sdk": "0.20.15",
+    "@appsemble/sdk": "0.20.17",
     "mini-jsx": "^3.0.0"
   }
 }

package/templates/mini-jsx/src/index.tsx

@@ -1,29 +1,50 @@
+// `src/index.tsx` is the initial entry poinf of the block source code run. For small blocks this
+// often contains the entire logic of the block. Bigger blocks are often split into smaller modules.
 import { bootstrap } from '@appsemble/sdk';
 
 import styles from './index.module.css';
 
-bootstrap(({ events, parameters: { fields }, utils: { fa, remap } }) => {
+// The bootstrap function injects various properties that can be destructured. You can use your
+// editor’s autocomplete to see which variables are available.
+bootstrap(({ events, parameters: { fields }, utils: { fa, formatMessage, remap } }) => {
+  /**
+   * The wrapper element is used to assign data to when it has loaded asyncronously.
+   */
   const wrapper = (
+    // In this template the JSX is handled by mini-jsx (https://gitlab.com/appsemble/mini-jsx).
+    // This is a small library that turns JSX into plain DOM nodes. Unlike React or Preact, no
+    // virtual DOM or state management is involved.
     <div className={styles.wrapper}>
       <div className={styles.loader} />
     </div>
   );
 
+  // The preferred way to listen for handling data is using event listeners. At first it may seem
+  // simpler to use actions, but event handlers give users the ability to do additional processing
+  // in another block, or to render the same data in different blocks. Typically user data is loaded
+  // using the data-loader block.
   events.on.data((data, error) => {
-    while (wrapper.lastElementChild) {
-      wrapper.lastElementChild.remove();
+    while (wrapper.lastChild) {
+      wrapper.lastChild.remove();
     }
 
     if (error) {
-      wrapper.append('error');
+      // It’s always important to handle errors. Events may emit errors for various reasons that are
+      // out of control for this block.
+      wrapper.append(formatMessage('error'));
     } else {
       wrapper.append(
         ...fields.map(({ icon, label, value }) => {
+          // The remap utility is a powerful tool to transform user data. A full reference is found
+          // on https://appsemble.app/docs/reference/remapper. However, for the block all that
+          // matters is we can pass in a user defined remapper and a value, and get the value the
+          // user wants to use.
           const remappedLabel = remap(label, data) as string;
 
           return (
             <div className={styles.field}>
               <i className={`${fa(icon)} ${styles.icon}`} />
+              {/* Bulma classes are supported. See https://bulma.io/documentation */}
               <div className={`has-text-weight-bold ${styles.value}`}>
                 {remap(value, data) as string}
               </div>
@@ -35,5 +56,6 @@ bootstrap(({ events, parameters: { fields }, utils: { fa, remap } }) => {
     }
   });
 
+  // If a DOM node is returned by the bootstrap function, it will be rendered in the shadow root.
   return <div>{wrapper}</div>;
 });

package/templates/preact/README.md

@@ -0,0 +1,11 @@
+This block was bootstrapped using the following command:
+
+```sh
+npm init appsemble block
+```
+
+This block renders a list of data entities that is emitted through an Appsemble block event. It uses
+[`preact`](https://preactjs.com) to define a block.
+
+This readme will be rendered on <https://appsemble.app> when the block is published. Replace the
+contents of this document with a useful block description.

package/templates/preact/block.ts

@@ -1,3 +1,8 @@
+// Blocks can actions, parameters, messages, and event listeners and emitters. These can be defined
+// by augmenting the @appsemble/sdk module. Typically this happens in a file named block.ts. When a
+// block is published, the CLI will process the augmented interfaces and validate the app definition
+// complies with them. The JSDoc will be used to render documentation.
+
 declare module '@appsemble/sdk' {
   interface EventListeners {
     /**
@@ -6,6 +11,23 @@ declare module '@appsemble/sdk' {
     data: never;
   }
 
+  interface Messages {
+    /**
+     * This message is displayed if the data is empty.
+     */
+    empty: never;
+
+    /**
+     * This message is displayed if there was a problem loading the data.
+     */
+    error: never;
+
+    /**
+     * This message is displayed if no data has been loaded yet.
+     */
+    loading: never;
+  }
+
   interface Parameters {
     /**
      * A list of fields to render out in a table.
@@ -13,5 +35,3 @@ declare module '@appsemble/sdk' {
     fields: string[];
   }
 }
-
-export {};

package/templates/preact/i18n/en.json

@@ -0,0 +1,5 @@
+{
+  "empty": "There is no data to display",
+  "error": "There was a problem loading the data.",
+  "loading": "Loading…"
+}

package/templates/preact/package.json

@@ -2,8 +2,8 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@appsemble/preact": "0.20.15",
-    "@appsemble/sdk": "0.20.15",
+    "@appsemble/preact": "0.20.17",
+    "@appsemble/sdk": "0.20.17",
     "preact": "^10.0.0"
   }
 }

package/templates/preact/src/index.tsx

@@ -1,18 +1,39 @@
-import { bootstrap } from '@appsemble/preact';
+// `src/index.tsx` is the initial entry poinf of the block source code run. For small blocks this
+// often contains the entire logic of the block. Bigger blocks are often split into smaller modules.
+
+// Normally bootstrap is imported from @appsemble/sdk. When using preact, it must be imported from
+// @appsemble/preact instead.
+import { bootstrap, FormattedMessage } from '@appsemble/preact';
 import { useEffect, useState } from 'preact/hooks';
 
-bootstrap(({ events, parameters: { fields } }) => {
-  const [data, setData] = useState<any[]>(null);
+// The bootstrap function injects various properties that can be destructured. You can use your
+// editor’s autocomplete to see which variables are available. These properties can also be accessed
+// from anywhere in a preact component using the useBlock() hook.
+bootstrap(({ events, parameters: { fields }, ready }) => {
+  // The @appsemble/preact bootstrap function renders a component. This means preact hooks such as
+  // useState and useEffect can be used.
+  const [data, setData] = useState<any[]>();
   const [error, setError] = useState(false);
 
+  // The block needs to call ready() once when it’s ready. Appsemble waits for all blocks to be
+  // ready before it dispatches any actions or events.
+  useEffect(() => {
+    ready();
+  }, [ready]);
+
+  // The preferred way to listen for handling data is using event listeners. At first it may seem
+  // simpler to use actions, but event handlers give users the ability to do additional processing
+  // in another block, or to render the same data in different blocks. Typically user data is loaded
+  // using the data-loader block.
   useEffect(() => {
     const onData = (newData: unknown[], newError: unknown): void => {
       if (newError) {
         setError(true);
-        setData(null);
+        // @ts-expect-error this is valid.
+        setData();
       } else {
-        setError(false);
         setData(newData);
+        setError(false);
       }
     };
 
@@ -23,19 +44,36 @@ bootstrap(({ events, parameters: { fields } }) => {
     };
   }, [events]);
 
+  // It’s always important to handle errors. Events may emit errors for various reasons that are
+  // out of control for this block.
   if (error) {
-    return <p>Error loading data.</p>;
+    return (
+      <p>
+        <FormattedMessage id="error" />
+      </p>
+    );
   }
 
+  // It’s always important to handle the loading state.
   if (!data) {
-    return <p>Loading…</p>;
+    return (
+      <p>
+        <FormattedMessage id="loading" />
+      </p>
+    );
   }
 
+  // It’s always important to handle an empty state
   if (!data.length) {
-    return <p>No data to display.</p>;
+    return (
+      <p>
+        <FormattedMessage id="empty" />
+      </p>
+    );
   }
 
   return (
+    // Bulma classes are supported in Appsemble blocks. See https://bulma.io/documentation
     <table className="table">
       <thead>
         <tr>
@@ -46,6 +84,9 @@ bootstrap(({ events, parameters: { fields } }) => {
       </thead>
       <tbody>
         {data.map((item, dataIndex) => (
+          // Because any data may be emitted, it’s often hard to determine the correct key to use.
+          // Often an id property is known, at least this handles the use case of Appsemble
+          // resources.
           <tr key={item.id || dataIndex}>
             {fields.map((field) => (
               <td key={field}>{item[field]}</td>

package/templates/preact/tsconfig.json

@@ -2,8 +2,8 @@
   "extends": "../../tsconfig",
   "compilerOptions": {
     "jsx": "react-jsx",
-    "jsxImportSource": "preact"
-  },
-  "lib": ["dom", "dom.iterable", "esnext"],
-  "types": ["@appsemble/webpack-config/types"]
+    "jsxImportSource": "preact",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "types": ["@appsemble/webpack-config/types"]
+  }
 }

package/templates/vanilla/README.md

@@ -0,0 +1,10 @@
+This block was bootstrapped using the following command:
+
+```sh
+npm init appsemble block
+```
+
+This block displays a button that dispatches an action when clicked.
+
+This readme will be rendered on <https://appsemble.app> when the block is published. Replace the
+contents of this document with a useful block description.

package/templates/vanilla/block.ts

@@ -1,3 +1,8 @@
+// Blocks can actions, parameters, messages, and event listeners and emitters. These can be defined
+// by augmenting the @appsemble/sdk module. Typically this happens in a file named block.ts. When a
+// block is published, the CLI will process the augmented interfaces and validate the app definition
+// complies with them. The JSDoc will be used to render documentation.
+
 declare module '@appsemble/sdk' {
   interface Actions {
     /**
@@ -5,6 +10,11 @@ declare module '@appsemble/sdk' {
      */
     onClick: never;
   }
-}
 
-export {};
+  interface Messages {
+    /**
+     * The button label.
+     */
+    label: never;
+  }
+}

package/templates/vanilla/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "label": "Click me"
+}

package/templates/vanilla/package.json

@@ -2,6 +2,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@appsemble/sdk": "0.20.15"
+    "@appsemble/sdk": "0.20.17"
   }
 }

package/templates/vanilla/src/index.ts

@@ -1,25 +1,25 @@
+// `src/index.ts` is the initial entry poinf of the block source code run. For small blocks this
+// often contains the entire logic of the block. Bigger blocks are often split into smaller modules.
 import { bootstrap } from '@appsemble/sdk';
 
-/**
- * @param {Object} actions Prepared actions the block can dispatch.
- * @param {Object} data The data that was somehow passed into the block. I.e. data passed in from
- * another block.
- * @param {Object} events Event related functions and constants.
- * @param {Object} pageParameters Parameters that the app creator defined in the app definition.
- * @param {Object} utils Some utility functions provided by the Appsemble framework.
- */
-bootstrap(({ actions, data, events, pageParameters, shadowRoot, utils }) => {
+// The bootstrap function injects various properties that can be destructured. You can use your
+// editor’s autocomplete to see which variables are available.
+bootstrap(({ actions, utils }) => {
   const button = document.createElement('button');
   button.type = 'button';
-  button.textContent = 'Click me!';
+
+  // Using utils.formatMessage we can provide internationalized messages.
+  button.textContent = utils.formatMessage('label');
+
+  // Bulma classes are supported. See https://bulma.io/documentation
   button.classList.add('button');
-  button.addEventListener(
-    'click',
-    (event) => {
-      event.preventDefault();
-      actions.onClick();
-    },
-    true,
-  );
+
+  button.addEventListener('click', (event) => {
+    event.preventDefault();
+    // This dispatches a user defined action.
+    actions.onClick();
+  });
+
+  // If a DOM node is returned by the bootstrap function, it will be rendered in the shadow root.
   return button;
 });