Docs update

src/lib/components/Keyboard.css

@@ -92,4 +92,12 @@ body, html {
 .simple-keyboard.hg-theme-default .hg-button.hg-selectedButton {
   background: rgba(5, 25, 70, 0.53);
   color: white;
+}
+
+.simple-keyboard.hg-theme-default .hg-button.hg-standardBtn[data-skbtn=".com"] {
+  max-width: 82px;
+}
+
+.simple-keyboard.hg-theme-default .hg-button.hg-standardBtn[data-skbtn="@"] {
+  max-width: 60px;
 }

src/lib/components/Keyboard.js

@@ -5,7 +5,18 @@ import PhysicalKeyboard from '../services/PhysicalKeyboard';
 import KeyboardLayout from '../services/KeyboardLayout';
 import Utilities from '../services/Utilities';
 
+/**
+ * Root class for simple-keyboard
+ * This class:
+ * - Parses the options
+ * - Renders the rows and buttons
+ * - Handles button functionality
+ */
 class SimpleKeyboard {
+  /**
+   * Creates an instance of SimpleKeyboard
+   * @param {Array} params If first parameter is a string, it is considered the container class. The second parameter is then considered the options object. If first parameter is an object, it is considered the options object.
+   */
   constructor(...params){
     let keyboardDOMQuery = typeof params[0] === "string" ? params[0] : '.simple-keyboard';
     let options = typeof params[0] === "object" ? params[0] : params[1];
@@ -22,14 +33,61 @@ class SimpleKeyboard {
      * Processing options
      */
     this.keyboardDOM = document.querySelector(keyboardDOMQuery);
+
+    /**
+     * @type {object}
+     * @property {object} layout Modify the keyboard layout.
+     * @property {string} layoutName Specifies which layout should be used.
+     * @property {object} display Replaces variable buttons (such as {bksp}) with a human-friendly name (e.g.: “backspace”).
+     * @property {boolean} mergeDisplay By default, when you set the display property, you replace the default one. This setting merges them instead.
+     * @property {string} theme A prop to add your own css classes to the keyboard wrapper. You can add multiple classes separated by a space.
+     * @property {Array} buttonTheme A prop to add your own css classes to one or several buttons.
+     * @property {boolean} debug Runs a console.log every time a key is pressed. Displays the buttons pressed and the current input.
+     * @property {boolean} newLineOnEnter Specifies whether clicking the “ENTER” button will input a newline (\n) or not.
+     * @property {boolean} tabCharOnTab Specifies whether clicking the “TAB” button will input a tab character (\t) or not.
+     * @property {string} inputName Allows you to use a single simple-keyboard instance for several inputs.
+     * @property {number} maxLength Restrains all of simple-keyboard inputs to a certain length. This should be used in addition to the input element’s maxlengthattribute.
+     * @property {object} maxLength Restrains simple-keyboard’s individual inputs to a certain length. This should be used in addition to the input element’s maxlengthattribute.
+     * @property {boolean} syncInstanceInputs When set to true, this option synchronizes the internal input of every simple-keyboard instance.
+     * @property {boolean} physicalKeyboardHighlight Enable highlighting of keys pressed on physical keyboard.
+     * @property {string} physicalKeyboardHighlightTextColor Define the text color that the physical keyboard highlighted key should have.
+     * @property {string} physicalKeyboardHighlightBgColor Define the background color that the physical keyboard highlighted key should have. 
+     * @property {function(button: string):string} onKeyPress Executes the callback function on key press. Returns button layout name (i.e.: “{shift}”).
+     * @property {function(input: string):string} onChange Executes the callback function on input change. Returns the current input’s string.
+     * @property {function} onRender Executes the callback function every time simple-keyboard is rendered (e.g: when you change layouts).
+     * @property {function} onInit Executes the callback function once simple-keyboard is rendered for the first time (on initialization).
+     * @property {function(inputs: object):object} onChangeAll Executes the callback function on input change. Returns the input object with all defined inputs.
+     */
     this.options = options;
     this.options.layoutName = this.options.layoutName || "default";
     this.options.theme = this.options.theme || "hg-theme-default";
     this.options.inputName = this.options.inputName || "default";
+
+    /**
+     * simple-keyboard uses a non-persistent internal input to keep track of the entered string (the variable `keyboard.input`).
+     * This removes any dependency to input DOM elements. You can type and directly display the value in a div element, for example.
+     * @example
+     * // To get entered input
+     * let input = keyboard.getInput();
+     * 
+     * // To clear entered input.
+     * keyboard.clearInput();
+     * 
+     * @type {object}
+     * @property {object} default Default SimpleKeyboard internal input.
+     * @property {object} myInputName Example input that can be set through `options.inputName:"myInputName"`.
+     */
     this.input = {};
     this.input[this.options.inputName] = '';
+
+    /**
+     * @type {string} DOM class of the keyboard wrapper, normally "simple-keyboard" by default.
+     */
     this.keyboardDOMClass = keyboardDOMQuery.split('.').join("");
-    this.timers = {};
+
+    /**
+     * @type {object} Contains the DOM elements of every rendered button, the key being the button's layout name (e.g.: "{enter}").
+     */
     this.buttonElements = {};
 
     /**
@@ -56,7 +114,10 @@ class SimpleKeyboard {
      */
     this.physicalKeyboardInterface = new PhysicalKeyboard(this);
   }
-
+  /**
+   * Handles clicks made to keyboard buttons
+   * @param  {string} button The button's layout name.
+   */
   handleButtonClicked = (button) => {
     let debug = this.options.debug;
 
@@ -92,7 +153,7 @@ class SimpleKeyboard {
         console.log('Input changed:', this.input);
 
       /**
-       * syncInstanceInputs
+       * Enforce syncInstanceInputs, if set
        */
       if(this.options.syncInstanceInputs)
         this.syncInstanceInputs(this.input);
@@ -109,28 +170,39 @@ class SimpleKeyboard {
     }
   }
 
+  /**
+   * Send a command to all simple-keyboard instances (if you have several instances).
+   */
   syncInstanceInputs = () => {
-    this.dispatch((section) => {
-      section.replaceInput(this.input);
+    this.dispatch((instance) => {
+      instance.replaceInput(this.input);
     });
   }
-
+  
+  /**
+   * Clear the keyboard’s input.
+   * @param  {string} [inputName] optional - the internal input to select
+   */
   clearInput = (inputName) => {
     inputName = inputName || this.options.inputName;
     this.input[this.options.inputName] = '';
 
     /**
-     * syncInstanceInputs
+     * Enforce syncInstanceInputs, if set
      */
     if(this.options.syncInstanceInputs)
       this.syncInstanceInputs(this.input);
   }
 
+  /**
+   * Get the keyboard’s input (You can also get it from the onChange prop).
+   * @param  {string} [inputName] optional - the internal input to select
+   */
   getInput = (inputName) => {
     inputName = inputName || this.options.inputName;
 
     /**
-     * syncInstanceInputs
+     * Enforce syncInstanceInputs, if set
      */
     if(this.options.syncInstanceInputs)
       this.syncInstanceInputs(this.input);
@@ -138,33 +210,54 @@ class SimpleKeyboard {
     return this.input[this.options.inputName];
   }
 
+  /**
+   * Set the keyboard’s input.
+   * @param  {string} input the input value
+   * @param  {string} inputName optional - the internal input to select
+   */
   setInput = (input, inputName) => {
     inputName = inputName || this.options.inputName;
     this.input[inputName] = input;
 
     /**
-     * syncInstanceInputs
+     * Enforce syncInstanceInputs, if set
      */
     if(this.options.syncInstanceInputs)
       this.syncInstanceInputs(this.input);
   }
-
+  
+  /**
+   * Replace the input object (`keyboard.input`)
+   * @param  {object} inputObj The input object
+   */
   replaceInput = (inputObj) => {
     this.input = inputObj;
   }
 
+  /**
+   * Set new option or modify existing ones after initialization. 
+   * @param  {object} option The option to set
+   */
   setOptions = option => {
     option = option || {};
     this.options = Object.assign(this.options, option);
     this.render();
   }
 
+  /**
+   * Remove all keyboard rows and reset keyboard values.
+   * Used interally between re-renders.
+   */
   clear = () => {
     this.keyboardDOM.innerHTML = '';
     this.keyboardDOM.className = this.keyboardDOMClass;
     this.buttonElements = {};
   }
 
+  /**
+   * Send a command to all simple-keyboard instances at once (if you have multiple instances).
+   * @param  {function(instance: object, key: string)} callback Function to run on every instance
+   */
   dispatch = (callback) => {
     if(!window['SimpleKeyboardInstances']){
       console.warn(`SimpleKeyboardInstances is not defined. Dispatch cannot be called.`);
@@ -176,6 +269,11 @@ class SimpleKeyboard {
     })
   }
 
+  /**
+   * Adds/Modifies an entry to the `buttonTheme`. Basically a way to add a class to a button.
+   * @param  {string} buttons List of buttons to select (separated by a space).
+   * @param  {string} className Classes to give to the selected buttons (separated by space).
+   */
   addButtonTheme = (buttons, className) => {
     if(!className || !buttons)
       return false;
@@ -221,6 +319,11 @@ class SimpleKeyboard {
     this.render();
   }
 
+  /**
+   * Removes/Amends an entry to the `buttonTheme`. Basically a way to remove a class previously added to a button through buttonTheme or addButtonTheme.
+   * @param  {string} buttons List of buttons to select (separated by a space).
+   * @param  {string} className Classes to give to the selected buttons (separated by space).
+   */
   removeButtonTheme = (buttons, className) => {
     /**
      * When called with empty parameters, remove all button themes
@@ -269,6 +372,10 @@ class SimpleKeyboard {
     }
   }
 
+  /**
+   * Get the DOM Element of a button. If there are several buttons with the same name, an array of the DOM Elements is returned.
+   * @param  {string} button The button layout name to select
+   */
   getButtonElement = (button) => {
     let output;
 
@@ -284,6 +391,9 @@ class SimpleKeyboard {
     return output;
   }
 
+  /**
+   * Retrieves the current cursor position within a input or textarea (if any)
+   */
   handleCaret = () => {
     if(this.options.debug){
       console.log("Caret handling started");
@@ -294,6 +404,9 @@ class SimpleKeyboard {
     document.addEventListener("touchend", this.caretEventHandler);
   }
 
+  /**
+   * Called by {@link handleCaret} when an event that warrants a cursor position update is triggered
+   */
   caretEventHandler = (event) => {
     let targetTagName = event.target.tagName.toLowerCase();
 
@@ -301,6 +414,10 @@ class SimpleKeyboard {
       targetTagName === "textarea" ||
       targetTagName === "input"
     ){
+      /**
+       * Tracks current cursor position
+       * As keys are pressed, text will be added/removed at that position within the input.
+       */
       this.caretPosition = event.target.selectionStart;
 
       if(this.options.debug){
@@ -309,6 +426,9 @@ class SimpleKeyboard {
     }
   }
 
+  /**
+   * Executes the callback function once simple-keyboard is rendered for the first time (on initialization).
+   */
   onInit = () => {
     if(this.options.debug){
       console.log("Initialized");
@@ -323,11 +443,17 @@ class SimpleKeyboard {
       this.options.onInit();
   }
 
+  /**
+   * Executes the callback function every time simple-keyboard is rendered (e.g: when you change layouts).
+   */
   onRender = () => {
     if(typeof this.options.onRender === "function")
       this.options.onRender();
   }
 
+  /**
+   * Renders rows and buttons as per options
+   */
   render = () => {
     /**
      * Clear keyboard
@@ -454,6 +580,9 @@ class SimpleKeyboard {
     this.onRender();
 
     if(!this.initialized){
+      /**
+       * Ensures that onInit is only called once per instantiation
+       */
       this.initialized = true;
 
       /**