Updated to v21

Author: djthorpe

js/button.js

@@ -5,12 +5,32 @@ import View from './view';
 // ////////////////////////////////////////////////////////////////////////////
 // CONSTANTS
 
-const EVENT_ROOT = 'mvc.button';
-const EVENT_CLICK = `${EVENT_ROOT}.click`;
+const EVENT_ROOT = 'button';
+
+/**
+ * Button click event
+ *
+ * @event Button#button:click
+ * @arg {Button} sender - The view that emitted the event.
+ * @arg {Node} target - The node for the button.
+ */
+const EVENT_CLICK = `${EVENT_ROOT}:click`;
 
 // ////////////////////////////////////////////////////////////////////////////
 // BUTTON
 
+/**
+ * @class Button
+ * @implements {View}
+ * @classdesc This class is constructed with a DOM element and
+ * controls an existing
+ * [Bootstrap Button]{@link https://getbootstrap.com/docs/5.0/components/buttons/}.
+ *
+ * @arg {Node} node - The node to attach the view to. Throws an error if the node
+ *   is not provided.
+ *
+ * @throws Error
+ */
 export default class Button extends View {
   constructor(node) {
     super(node);

js/error.js

@@ -1,5 +1,15 @@
-// Error class
-
+/**
+ * Error represents an error message.
+ * @class
+ * @classdesc Errors are emitted by several components. The Error class is used
+ * to encapsulate an error and numerical code for the error.
+ *
+ * @arg {string} reason - The error description
+ * @arg {number} code - The numerical code for the error
+ *
+ * @property {string} $reason - Returns the error reason
+ * @property {number} $code - Return the error code
+ */
 export default class Error {
   constructor(reason, code) {
     this.$reason = reason;

js/form.js

@@ -7,13 +7,52 @@ import Error from './error';
 // ////////////////////////////////////////////////////////////////////////////
 // CONSTANTS
 
-const EVENT_ROOT = 'mvc.form';
-const EVENT_SUBMIT = `${EVENT_ROOT}.submit`;
-const EVENT_CHANGE = `${EVENT_ROOT}.change`;
+const EVENT_ROOT = 'form';
+
+/**
+ * Form submit event, which is emitted whenever submission occurs on the
+ * form (with a button or other method). The event is only fired if the
+ * form validation checks passed.
+ *
+ * @event Form#form:submit
+ * @arg {Form} sender - The form that emitted the event.
+ * @arg {Node} target - The input control or button that submitted the form.
+ */
+const EVENT_SUBMIT = `${EVENT_ROOT}:submit`;
+
+/**
+ * Form change event, which is emitted whenever an input control on the
+ * form is changed.
+ *
+ * @event Form#form:change
+ * @arg {Form} sender - The form that emitted the event.
+ * @arg {Node} target - The input control that changed.
+ */
+const EVENT_CHANGE = `${EVENT_ROOT}:change`;
 
 // ////////////////////////////////////////////////////////////////////////////
-// FORM
 
+/**
+ * Form represents a HTML form, which can contain values entered by the user.
+ * @class
+ * @implements {View}
+ * @classdesc A list is a view which uses a 'row' template to added and remove
+ *  rows from a view.
+ * @classdesc This class is constructed with a DOM element and
+ * controls an existing
+ * [Bootstrap Form]{@link https://getbootstrap.com/docs/5.0/forms/overview/}
+ * and is generally used for validating, submitting and tracking form input. The form
+ * can be wrapped in a [Bootstrap Modal]{@link https://getbootstrap.com/docs/5.0/components/modal/}
+ * so that the show and hide methods can be used to set visibility.
+ *
+ * @arg {Node} node - The node to attach the view to. Throws an error if the node
+ *   is not provided.
+ *
+ * @property {FormData} formdata - Returns a form data object representing the form values
+ * @property {Object<string,string>} values - Get and set the form values
+ *
+ * @throws Error
+ */
 export default class Form extends View {
   constructor(node) {
     super(node);
@@ -44,6 +83,13 @@ export default class Form extends View {
     this.dispatchEvent(EVENT_CHANGE, this, evt.target);
   }
 
+  /**
+  * Sets the default values for the form and if the form is modal, the modal
+  * is show.
+  * @param {Object<string,string>} defaults - The values for the form controls.
+  * @fires Form#form:submit
+  * @fires Form#form:change
+  */
   show(defaults) {
     this.$form.classList.remove('was-validated');
     if (defaults) {
@@ -52,6 +98,9 @@ export default class Form extends View {
     this.$modal.show();
   }
 
+  /**
+  * If the form is modal, the modal is hidden.
+  */
   hide() {
     this.$modal.hide();
   }

js/index.js

@@ -26,6 +26,6 @@ import 'bootstrap-icons/font/fonts/bootstrap-icons.woff2';
 import '../css/style.css';
 
 // Exports
-export {
+export default {
   Model, View, Controller, Provider, Error, Emitter, List, Nav, Toast, Button, Form,
 };

js/list.js

@@ -6,12 +6,33 @@ import Error from './error';
 // ////////////////////////////////////////////////////////////////////////////
 // CONSTANTS
 
-const EVENT_ROOT = 'mvc.list';
-const EVENT_CLICK = `${EVENT_ROOT}.click`;
+const EVENT_ROOT = 'list';
+
+/**
+ * List row click event
+ *
+ * @event List#list:click
+ * @arg {Nav} sender - The provider that emitted the event.
+ * @arg {Node} target - The target element clicked.
+ */
+const EVENT_CLICK = `${EVENT_ROOT}:click`;
 
 // ////////////////////////////////////////////////////////////////////////////
-// LISTVIEW
 
+/**
+ * List provides a way to dynamically create an ordered list of elements in a
+ * view.
+ * @class
+ * @implements {View}
+ * @classdesc A list is a view which uses a 'row' template to added and remove
+ *  rows from a view.
+ *
+ * @arg {Node} node - The node to attach the view to. Throws an error if the node
+ *   is not provided.
+ * @arg {string} classTemplate - class name of the template within the view which is
+ *   cloned for each row.
+ * @throws Error
+ */
 export default class List extends View {
   constructor(node, classTemplate) {
     super(node);
@@ -29,6 +50,14 @@ export default class List extends View {
     this.$prototype.classList.remove(this.$className);
   }
 
+  /**
+  * Add or update an existing row. When adding a row, it is cloned from the template
+  * and added to the end of the view element.
+  * @param {Model} obj - The object which should be represented in the view.
+  * @param {string} key - A unique identifier for the row.
+  * @returns View - The view added or to be updated in the list
+  * @fires List#list:click
+  */
   set(obj, key) {
     let row = this.getForKey(key);
 
@@ -53,17 +82,33 @@ export default class List extends View {
     return new View(row);
   }
 
+  /**
+   * Return a Node representing a row.
+   * @param {string} key - A unique identifier for the row.
+   * @returns Node - The view representing the row
+   */
   getForKey(key) {
+    // TODO return a view object?
     return key ? this.query(`#${key}`) : undefined;
   }
 
+  /**
+   * Remove a row from the view.
+   * @param {string} key - A unique identifier for the row.
+   */
   deleteForKey(key) {
     const row = this.getForKey(key);
     if (row) {
       row.remove();
     }
   }
 
+  /**
+   * Update the list by adding a class name to a row identified by key,
+   * and remove the class name from all other rows.
+   * @param {string} key - A unique identifier for the row.
+   * @param {string} className - The class name to use.
+   */
   setClassForKey(key, className) {
     super.queryAll(`.${className}`).forEach((node) => {
       node.classList.remove(className);
@@ -75,6 +120,10 @@ export default class List extends View {
     return selectedNode;
   }
 
+  /**
+   * Sort rows in order according the the keys provided.
+   * @param {string[]} keys - The ordered array of keys.
+   */
   sortForKeys(keys) {
     for (let i = keys.length - 1; i >= 0; i -= 1) {
       const row = this.getForKey(keys[i]);

js/model.js

@@ -1,4 +1,4 @@
-// Model class to be subclassed by an actual model
+/* eslint-disable func-names */
 
 import Error from './error';
 
@@ -14,8 +14,21 @@ const REGEXP_ALIASED = /^([A-Za-z0-9-_]*)\s+(\{\}|\[\])?(\w+)$/i;
 const REGEXP_NOTALIASED = /^()(\{\}|\[\])?(\w+)$/i;
 
 // ////////////////////////////////////////////////////////////////////////////
-// MODEL CLASS
 
+/**
+ * Model manages data transfer between provider, form and internal representation.
+ * @class
+ * @classdesc This class is used as a base class to a model. You should extend
+ * this class and call the define method to describe the data model properties. When constructing
+ * a model, you can then access your properties as you would any other object.
+ *
+ * @arg {Object} data - The data which is parsed and used to construct the model instance.
+ *
+ * @property {string} $json - Returns JSON representation of the model values.
+ * @property {string} $className - Returns the class name of the model.
+ *
+ * @throws Error
+ */
 export default class Model {
   constructor(data) {
     // Get prototype
@@ -32,6 +45,22 @@ export default class Model {
     this.$setall(data);
   }
 
+  /**
+   * Define the object model. The model supports string, number, boolean and date
+   * as native values, and map, object and array as collections. You can define
+   * the model as an array of properties, each property is a string with an optional
+   * alias (the data key of the external representation) and the internal representation.
+   * For example, to define a string use "string" as the property, or for example "id string"
+   * if the external representation uses 'id' as the key. To define an object as a
+   * model member, use the name of the model (ie, 'User'). For a map, use '{}' before the
+   * type and for an array use '[]' before the type.
+   *
+   * @arg {function} classConstructor - The constructor for the model
+   * @arg {Object.<string,string>} classProps - The definition of the model properties
+   * @arg {string=} className - The name of the class referred to in class properties.
+   *   Uses constructor name if not given.
+   * @throws Error
+   */
   static define(classConstructor, classProps, className) {
     if (typeof classConstructor !== 'function') {
       throw new Error('Called define without a class constructor');
@@ -48,6 +77,42 @@ export default class Model {
     Model.models[classKey] = proto;
   }
 
+  /**
+   * @method Model#$get
+   * @arg {string} key - The key of the property
+   * @returns {string|number|boolean|Date|Map|Array|Model|undefined}
+   * @desc Return a property value or undefined
+   */
+  /**
+   * @method Model#$set
+   * @arg {string} key - The key of the property
+   * @arg {string|number|boolean|Date|Map|Array|Model|undefined} value - The value
+   *  for the property
+   * @returns {string|number|boolean|Date|Map|Array|Model|undefined}
+   * @desc Set a property value for a key
+   */
+  /**
+   * @method Model#$getall
+   * @returns {Object}
+   * @desc Get all property values that can be transmitted stored in external representation.
+   *  Does not include values which are undefined.
+   */
+  /**
+   * @method Model#$setall
+   * @desc Set all property values from external representation. Replaces all existing
+   * property values.
+   * @returns {Object}
+   */
+  /**
+   * @method Model#toString
+   * @desc Return object in string form, for debugging.
+   * @returns {string}
+   */
+  /**
+   * @method Model#$equals
+   * @desc Checks for equality between this object and another model.
+   * @returns {boolean}
+   */
   static $newproto(classKey, classProps, className) {
     const proto = {};
 
@@ -99,21 +164,16 @@ export default class Model {
       });
     });
 
-    // $get function
-    // eslint-disable-next-line func-names
     proto.$get = function (key) {
       return this.$data[key];
     };
 
-    // $set function
-    // eslint-disable-next-line func-names
     proto.$set = function (key, value) {
       const v = this.$type.get(key);
       this.$data[key] = Model.$cast(value, v.collection, v.primitive, v.model);
+      return this.$data[key];
     };
 
-    // $getall function
-    // eslint-disable-next-line func-names
     proto.$getall = function () {
       const obj = {};
       this.$type.forEach((v, k) => {
@@ -125,8 +185,6 @@ export default class Model {
       return obj;
     };
 
-    // $setall function
-    // eslint-disable-next-line func-names
     proto.$setall = function (data) {
       if (typeof data !== 'object') {
         throw new Error(`Constructor requires object for ${this.constructor.name}`);
@@ -137,8 +195,6 @@ export default class Model {
       });
     };
 
-    // toString function
-    // eslint-disable-next-line func-names
     proto.toString = function () {
       let str = `<${this.$className}`;
       this.$type.forEach((_, k) => {
@@ -148,8 +204,6 @@ export default class Model {
       return `${str}>`;
     };
 
-    // $equals function
-    // eslint-disable-next-line func-names
     proto.$equals = function (other) {
       if (!other) {
         return false;