documentation

Author: lenadax

js/src/bootstrap5/buttons.js

@@ -3,6 +3,16 @@ import bootstrap from 'bootstrap';
 
 export class Action {
 
+    /**
+     * @param {Object} editor - The editor instance to which this action belongs.
+     * @param {Object} [opts={}] - Options for configuring the action.
+     * @param {HTMLElement} opts.container_elem - The container element for the action.
+     * @param {string} opts.tooltip - The tooltip text to display on hover.
+     * @param {string} opts.icon - The icon class to use (from Bootstrap Icons).
+     * @param {string} opts.text - The text label for the action.
+     * @param {Object} opts.css - CSS properties to apply to the action.
+     * @param {boolean} opts.toggle - If true, the action can be toggled active/inactive.
+     */
     constructor(editor, opts = {}) {
         this.editor = editor;
         this.editor_elem = $(editor.options.element);
@@ -13,6 +23,11 @@ export class Action {
         this.elem.on('click', this.on_click);
     }
 
+    /**
+     * Compiles the action's UI elements based on the provided options.
+     *
+     * @param {Object} opts - The options used to configure the action.
+     */
     compile(opts) {
         this.container = $('<div />')
             .addClass('action')
@@ -41,22 +56,44 @@ export class Action {
         this.content = $('> *', this.elem);
     }
 
+    /**
+     * Gets the active state of the action.
+     *
+     * @returns {boolean} True if the action is active, false otherwise.
+     */
     get active() {
         return this._active;
     }
+
+    /**
+     * Sets the active state of the action.
+     *
+     * @param {boolean} active - The new active state.
+     */
     set active(active) {
         if (this.opts.toggle) {
             active ? this.elem.addClass('active') : this.elem.removeClass('active');
         }
         this._active = active;
     }
+
+    /**
+     * Handles click events on the action element.
+     *
+     * @param {Event} e - The click event.
+     */
     on_click(e) {
         e.preventDefault();
     }
 }
 
 export class Button extends Action {
 
+    /**
+     * Compiles the button's UI elements, adding button-specific classes.
+     *
+     * @param {Object} opts - The options used to configure the button.
+     */
     compile(opts) {
         super.compile(opts);
         this.container.addClass('btn-group');
@@ -67,6 +104,13 @@ export class Button extends Action {
 
 export class DropdownButton extends Button {
 
+    /**
+     * Creates an instance of the DropdownButton class.
+     *
+     * @param {Object} editor - The editor instance to which this dropdown button belongs.
+     * @param {Object} [opts={}] - Options for configuring the dropdown button.
+     * @param {boolean} opts.submit - If true, includes a submit button in the dropdown.
+     */
     constructor(editor, opts = {}) {
         super(editor, opts);
         this.elem.addClass('drop_btn dropdown-toggle')
@@ -90,10 +134,20 @@ export class DropdownButton extends Button {
         $(window).on('resize', this.on_resize);
     }
 
+    /**
+     * Gets the currently active item in the dropdown.
+     *
+     * @returns {Object} The currently active item.
+     */
     get active_item() {
         return this._active_item;
     }
 
+    /**
+     * Sets the currently active item in the dropdown.
+     *
+     * @param {Object} item - The item to set as active.
+     */
     set active_item(item) {
         let clone = item.elem.children().clone();
         this.elem.empty().append(clone);
@@ -103,14 +157,25 @@ export class DropdownButton extends Button {
         this._active_item = item;
     }
 
+    /**
+     * Cleans up the dropdown button by removing event listeners.
+     */
     unload() {
         $(window).off('resize', this.on_resize);
     }
 
+    /**
+     * Handles the window resize event, resetting the active state.
+     *
+     * @param {Event} e - The resize event.
+     */
     on_resize(e) {
         this.active = false;
     }
 
+    /**
+     * Sets the items in the dropdown menu.
+     */
     set_items() {
         for (let child of this.children) {
             child.container.addClass('dropdown-item');
@@ -122,11 +187,19 @@ export class DropdownButton extends Button {
         this.active_item = this.children[0];
     }
 
+    /**
+     * Updates the dropdown button based on the current state.
+     */
     on_update() {
         // ...
     }
 
     /* istanbul ignore next */
+    /**
+     * Handles the submit action for the dropdown.
+     *
+     * @param {Event} e - The submit event.
+     */
     submit(e) {
         e.preventDefault();
     }

js/src/bootstrap5/widget.js

@@ -3,6 +3,9 @@ import {actions} from './actions';
 
 export class TiptapWidget {
 
+    /**
+     * @param {HTMLElement} context - DOM context for initialization.
+     */
     static initialize(context) {
         $('div.tiptap-editor', context).each(function() {
             let elem = $(this);
@@ -18,6 +21,13 @@ export class TiptapWidget {
         });
     }
 
+    /**
+     * @param {jQuery} elem - The jQuery element representing the Tiptap widget.
+     * @param {Object} [opts={}] - Configuration options for the Tiptap widget.
+     * @param {Array} opts.actions - An array of actions to be used in the editor.
+     * @param {Array} opts.colors - An array of colors to be used in the editor.
+     * @param {string} opts.helpLink - A link to help resources related to the editor.
+     */
     constructor(elem, opts={}) {
         elem.data('yafowil-tiptap', this);
         elem.attr('spellcheck', false);
@@ -60,7 +70,7 @@ export class TiptapWidget {
                 let container = $('<div />')
                     .addClass('btn-group me-2')
                     .appendTo(this.controls);
-                    act.forEach(name => this.add_button(name, container));
+                act.forEach(name => this.add_button(name, container));
             } else {
                 this.add_button(act, this.controls);
             }
@@ -72,13 +82,19 @@ export class TiptapWidget {
         this.editor.on('selectionUpdate', this.on_selection_update);
     }
 
+    /**
+     * Cleans up the widget and removes event listeners.
+     */
     destroy() {
         this.unload_all();
         this.editor.destroy();
         this.elem.empty();
         this.buttons = null;
     }
 
+    /**
+     * Unloads all action buttons in the widget.
+     */
     unload_all() {
         for (let btn in this.buttons) {
             if (this.buttons[btn].unload) {
@@ -87,14 +103,26 @@ export class TiptapWidget {
         }
     }
 
+    /**
+     * Adds a button to the control panel.
+     *
+     * @param {string} name - The name of the action to create a button for.
+     * @param {jQuery} container - The jQuery container to append the button to.
+     */
     add_button(name, container) {
-        let factory = actions[name],
-            btn = new factory(this, this.editor, {
-                container_elem: container
-            });
+        let factory = actions[name];
+        let btn = new factory(this, this.editor, {
+            container_elem: container
+        });
         this.buttons[name] = btn;
     }
 
+    /**
+     * Parses the provided actions and returns a structured array.
+     *
+     * @param {Array} acs - An array of action names.
+     * @returns {Array} A structured array of parsed actions.
+     */
     parse_actions(acs) {
         let ret = [];
         function parse(ret_arr, acts) {
@@ -107,12 +135,18 @@ export class TiptapWidget {
                 } else {
                     ret_arr.push(action);
                 }
-            })
+            });
         }
         parse(ret, acs);
         return ret;
     }
 
+    /**
+     * Parses the provided actions and returns a set of corresponding extensions.
+     *
+     * @param {Array} acs - An array of action names.
+     * @returns {Set} A set of extensions associated with the actions.
+     */
     parse_extensions(acs) {
         let extensions = new Set([
             tiptap.Document,
@@ -129,6 +163,9 @@ export class TiptapWidget {
         return extensions;
     }
 
+    /**
+     * Updates the state of all buttons and the textarea value.
+     */
     on_update() {
         for (let btn in this.buttons) {
             if (this.buttons[btn].on_update) {
@@ -138,6 +175,9 @@ export class TiptapWidget {
         this.textarea.val(this.editor.getHTML());
     }
 
+    /**
+     * Updates the state of all buttons based on the current selection.
+     */
     on_selection_update() {
         for (let btn in this.buttons) {
             if (this.buttons[btn].on_selection_update) {
@@ -147,18 +187,23 @@ export class TiptapWidget {
     }
 }
 
-
 //////////////////////////////////////////////////////////////////////////////
 // yafowil.widget.array integration
 //////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Re-initializes widget on array add event.
+ */
 function tiptap_on_array_add(inst, context) {
     TiptapWidget.initialize(context);
 }
 
+/**
+ * Registers subscribers to yafowil array events.
+ */
 export function register_array_subscribers() {
     if (window.yafowil_array === undefined) {
         return;
     }
     window.yafowil_array.on_array_event('on_add', tiptap_on_array_add);
-}
+}