Added full documentation

2022-10-19 20:33:37 +03:00
parent 99785cc76b
commit b01b65586a
37 changed files with 14590 additions and 32 deletions
--- a/src/cg-dropdown.js
+++ b/src/cg-dropdown.js
@ -1,48 +1,61 @@
 import {
-  customStyles,
  createSelected,
+  customStyles,
  getFormatItem,
  customStylesFormat,
 } from './components/utils';
 import { createBreadcrumb } from './components/create-element';

+/**
+ * @class Описание класса DropDown
+ * @description Этот класс реализовывает функционал кастомного селекта, с возможностями кастомизации.
+ *@author Овсяников Максим
+ */
 export class DropDown {
  /**
   * Созданный HTML елемент
+   * @type {HTMLElement}
   */
  #element;
  /**
   * Созданный список(ul), с классом list
+   * @type {HTMLElement}
   */
  #list;
  /**
   * Настройки селекта передаваемые при создании экземпляра класса
+   * @type {object}
   */
  #options;
  /**
   * Переменная для управления каретки
+   * @type {HTMLElement}
   */
  #caret;
  /**
   * Массив переданных элементов
+   * @type {object[]}
   */
  #items;
  /**
   * Переданные категории
+   * @type {string}
   */
  #category;
  /**
   * Выбранный или массив выбранных элементов из списка
+   * @type {object[] | object}
   */
  #selectedItems;
  /**
   * Массив индексов выбранных элементов
+   * @type {number[]}
   */
  #indexes = [];

  /**
   * Метод экземпляра класса DropDown
-   * @returns Возвращает выбранные элемент(ы) в виде массива/элемента/null
+   * @returns {string[] | string | null} Возвращает выбранные элемент(ы) в виде массива/элемента/null
   * @description Геттер возвращающий выбранные элемент(ы) селекта
   */
  get value() {
@ -51,7 +64,7 @@ export class DropDown {

  /**
   * Метод экземпляра класса DropDown
-   * @returns Возвращает индексы выбранных элемента(ов) в виде массива/пустой массив
+   * @returns {number | number[]}Возвращает индексы выбранных элемента(ов) в виде массива/пустой массив
   * @description Геттер возвращающий индексы выбранных элемента(ов) селекта
   */
  get indexes() {
@ -59,10 +72,31 @@ export class DropDown {
  }

  /**
-   * Конструктор DropDown
-   * @param {object} options - Объект принимающий настройки селекта
-   * @constructor  Жизненный цикл элемента
+   *
+   * @param {object} options Объект принимающий настройки селекта
+   * @constructor Конструктор класса DropDown
   * @description  Конструктор принимает объект и рендерит селект.
+   * @example
+   * options = {
+   *  selector: 'Уникальный селектор',
+      selected: 'Выбранный элемент',
+      placeholder: '...',
+      items: [string|number|object],
+      styles: {
+        head: {
+          background: '...',
+        },
+        list: {...},
+        chips: {...},
+        caret: {...},
+        placeholder: {...},
+      },
+      event: '...',
+      url: 'http/...',
+      multiselect: true/false,
+      multiselectTag: true/false,
+   * }
+     
   */
  constructor(options = {}) {
    this.#init(options);
@ -72,9 +106,9 @@ export class DropDown {

  /**
   * Метод экземпляра класса DropDown
-   * @param {string} item может быть как строкой так и объектом
-   * @description добавляет переданный элемент в конец списка и перерисовывает список.
-   * Не может использоваться при передачи элементов с категорями
+   * @param {string | object} item добавляемый елемент
+   * @description добавляет переданный элемент в конец списка и перерисовывает список. Не может использоваться при передачи элементов с категорями
+   * @method addItem
   */
  addItem(item) {
    if (this.#category) {
@ -95,8 +129,8 @@ export class DropDown {
  /**
   * Метод экземпляра класса DropDown
   * @param {number} index индекс удаляемого элемента
-   * @description удаляет елемент по индексу из списка и перерисовывает его.
-   * Не может использоваться при передачи элементов с категорями
+   * @description удаляет елемент по индексу из списка и перерисовывает его. Не может использоваться при передачи элементов с категорями.
+   * @method deleteItem
   */
  deleteItem(index) {
    if (this.#category) {
@ -113,6 +147,7 @@ export class DropDown {
  /**
   * Метод экземпляра класса DropDown
   * @description удаляет все елементы из списка и перерисовывает его.
+   * @method deleteItemAll
   */
  deleteItemAll() {
    this.#items.splice(0, this.#items.length);
@ -123,6 +158,7 @@ export class DropDown {
   * Метод экземпляра класса DropDown
   * @param {number} index индекс выбранного элемента
   * @description  выбирает элемент который будет изначально отрисовываться в селекте
+   * @method selectIndex
   */
  selectIndex(index) {
    if (this.#category) {
@ -143,7 +179,8 @@ export class DropDown {
  /**
   * Метод экземпляра класса DropDown
   * @param {number} numberItem номер возвращаемого элемента
-   * @returns возвращает ссылку на выбранный HTML элемент
+   * @returns {HTMLElement} возвращает ссылку на выбранный HTML элемент
+   * @method getElement
   */
  getElement(numberItem) {
    if (numberItem > this.#items.length) {
@ -156,6 +193,7 @@ export class DropDown {
   * Метод экземпляра класса DropDown
   * @param {boolean} value - Передаваемый параметр для добавления атрибута disabled;
   * @description Метод позволяющий переключать состояние селекта disabled,
+   * @method disabled
   */
  disabled(value) {
    if (typeof value !== 'boolean') {
@ -177,6 +215,7 @@ export class DropDown {
   * @param {HTMLInputElement} button - HTML кнопка
   * @param {string} method - метод открытия open/close
   * @description Метод позволяющий открывать/закрывать селект с помощью кнопок
+   * @method buttonControl
   */
  buttonControl(button, method) {
    button.addEventListener('click', () => {
@ -191,9 +230,30 @@ export class DropDown {
  }

  /**
-   * Метод инициализации экземпляра класса DropDown
+   * Приватный метод инициализации экземпляра класса DropDown
+   * @method #init
+   * @member
+   * @protected
   * @param {object} options передаваемые настройки селекта
-   * @description общая инициализация селекта. Получение настоек и преобразвание элементов селекта.
+   * @description Приватный метод. Общая инициализация селекта. Получение настоек и преобразвание элементов селекта.
+   * @example
+   *  {
+        selector: '.cg-dropdown_one',
+        placeholder: 'Выберите авто',
+        items: [
+          'BMW',
+          {
+            id: '213sade',
+            title: 'Opel',
+            value: 1,
+          },
+          'Mersedes',
+          'MAN',
+          'max',
+        ],
+        multiselect: true,
+        multiselectTag: true,
+      }
   */
  #init(options) {
    this.#options = options;
@ -237,9 +297,12 @@ export class DropDown {
  }

  /**
-   * Метод экземпляра класса DropDown
+   * Привaтный метод экземпляра класса DropDown
+   *
+   * @method #initSelected
   * @param {string} select необязательный елемент. Используется в методе selectIndex
-   * @description отрисовывает и стилизует селект
+   * @description Отрисовывает и стилизует селект
+   * @protected
   */
  #initSelected(select) {
    const { styles, selected, placeholder } = this.#options;
@ -262,9 +325,11 @@ export class DropDown {
  }

  /**
-   * Метод рендера экземпляра класса DropDown
+   * Приватный метод рендера экземпляра класса DropDown
+   *@protected
+   * @method #render
   * @param {string} select  необязательный елемент. Передаеться в метод initSelected
-   * @description рендер елементов в селекте.
+   * @description Рендер елементов в селекте.
   */
  #render(select) {
    const { styles, multiselect } = this.#options;
@ -326,8 +391,10 @@ export class DropDown {
  }

  /**
-   * Метод рендера экземпляра класса DropDown
-   * @description рендер елементов в селекте переданных с URL и их настойка
+   * Приватный метод рендера экземпляра класса DropDown
+   *@protected
+   * @method #renderUrl
+   * @description Рендер елементов в селекте переданных с URL и их настойка
   */
  async #renderUrl() {
    const { url, items, multiselect } = this.#options;
@ -380,9 +447,11 @@ export class DropDown {
  }

  /**
-   * Метод экземпляра класса DropDown
+   * Приватный метод экземпляра класса DropDown
+   * @protected
   * @param {boolean} oneClick необязательный параметр передаваемый из функции buttonControl
-   * @description открывает список для выбора элемента
+   * @description Открывает список для выбора элемента
+   * @method #open
   */
  #open(oneClick) {
    this.#list = this.#element.querySelector('.list');
@ -398,8 +467,10 @@ export class DropDown {
  }

  /**
-   * Метод экземпляра класса DropDown
-   * @description закрывающий список
+   * Приватный метод экземпляра класса DropDown
+   * @protected
+   * @description Закрывает список
+   * @method #close
   */
  #close() {
    this.#list.classList.remove('open');
@ -407,8 +478,10 @@ export class DropDown {
  }

  /**
-   * Метод экземпляра класса DropDown
-   * @description метод реализовывающий выбор элементов в разных режимах. Обычный/Мультиселект/Мультиселект + Мультиселект Таг.
+   * Приватный метод экземпляра класса DropDown
+   * @protected
+   * @description Метод реализовывающий выбор элементов в разных режимах. Обычный/Мультиселект/Мультиселект + Мультиселект Таг.
+   * @method #addOptionsBehaviour
   */
  #addOptionsBehaviour() {
    const { multiselect, placeholder, selected, multiselectTag } = this.#options;
@ -500,8 +573,10 @@ export class DropDown {
  }

  /**
-   * Метод экземпляра класса DropDown
-   * @description открывает и закрывает список по переданному эвенту
+   * Приватный метод экземпляра класса DropDown
+   * @protected
+   * @description Открывает и закрывает список по переданному эвенту
+   * @method #initEvent
   */
  #initEvent() {
    const { event } = this.#options;
--- a/src/components/create-element.js
+++ b/src/components/create-element.js
@ -1,4 +1,7 @@
 import { customStylesFormat } from './utils';
+/**
+ * @module createBreadcrumb
+ */

 /**
 * Метод который создает и отвечает за поведение chips
@ -6,7 +9,7 @@ import { customStylesFormat } from './utils';
 * @param {string} title имя выбранного элемента для отрисовки chips
 * @param {number} index индекс выбранного элемента для отрисовки chips
 * @param {string} id уникальное id выбранного элемента
- * @returns возвращает сформированный HTMLElement chips item
+ * @returns {HTMLElement} возвращает сформированный HTMLElement chips item
 */
 export function createBreadcrumb(data, title, index, id) {
  const { element, option, indexes, selectedItems } = data;
--- a/src/components/utils.js
+++ b/src/components/utils.js
@ -1,3 +1,8 @@
+/**
+ * Utils module
+ * @module Utils
+ */
+
 /**
 * Создание кнопки выбора элементов
 * @param {HTMLElement} element созданный экземпляр класса DropDown
@ -67,7 +72,7 @@ export function customStylesFormat(elemOption, selector) {
 /**
 * Проверка содержит ли item  указанные свойства,
 * @param {object} item проверяемый на определенную структуру элемент
- * @returns возвращает true/false если item содержит указанные свойства
+ * @returns {boolean} возвращает true/false если item содержит указанные свойства
 */
 export function checkItemStruct(item) {
  if (item && typeof item !== 'object') {
@ -79,9 +84,9 @@ export function checkItemStruct(item) {

 /**
 * Преобразование каждого елемента полученного из поля Items;
- * @param {object} dataItem полученный елемент переданный при создании селекта может быть как object/string
+ * @param {object | string} dataItem полученный елемент переданный при создании селекта может быть как object/string
 * @param {number} index индекс этого элемента
- * @returns возвращает сформированный объект
+ * @returns {object} возвращает сформированный объект
 */
 export function getFormatItem(dataItem, index) {
  const random = Math.random().toString(36).substring(2, 10);