# wt.core assets source

Источник: https://bitbucket.org/bellord13/kit/

## is a dependency wt.core

Репозиторий wt.core: https://bitbucket.org/andreyleoua/wt.core/


Предназначен для асинхронной работы с ресурсами на веб-проектах.

## Установка

В директории [php:wt.core] `app()->config()->get('templater.path') . '/kit'` (по умолчанию `/local/templater.dev/kit`) выполнить клонирование проекта 

```bash
git clone https://bellord@bitbucket.org/bellord13/kit.git ./
```


## Термины и определения в контексте фреймворка
`Плагин` - сущность включающая в себя модуль, js-, css-файлы, шрифты.

`Модуль` - составляющая плагина, определяемая как основной файл плагина (его наличие не обязательно в плагине)

`PluginManager` - класс для работы с плагинами

`window.kit` - объект, который изолирует все плагины

## Базовые принципы

✨ Инициализация 

Выдержка из плагина `core`:

```js
manager = new PluginManager(global);
manager.register('PluginManager', {
   alias: 'pm',
   type: MD_TYPE.HMD,
   handler: function(require, exports, module, global) {
      return module.exports = manager;
   }
});
manager.register('config', {
   type: MD_TYPE.HMD,
   handler: function(require, exports, module, global) {
      global.config = Object.assign({}, defaultConfig, config);
    }
});
manager.install('PluginManager');
```
Создается экземпляр класса `PluginManager` и регистрирует сам себя.
Переменная `global` выполняем роль фасада для всех установленных плагинов. В качестве глобальной переменной используется `window.kit`. В паре с менеджером сразу инициализируется `config` доступный из `window.kit.config`.


✨ Основные этапы работы с плагином:

| этап        | метод                                                        |
|-------------|--------------------------------------------------------------|
| Регистрация | register(`pluginId`, `config`) или registerPlugins(`object`) |
| Загрузка    | load(`pluginId`, `callback`)                                 |
| Установка   | install(`pluginId`, `callback`)                              |
| Запрос      | require(`pluginId`, `callback`)                              |


## Примеры регистрации

### Пример регистрации Стандартного плагина (Тип default)

```js
__PluginManager__.register('menu', {
   path: kit.config.assetsPath + '/menu',
   module: '/menu.js',
   type: 'loader',
   css: [
      '/menu.css'
   ],
   deps: ['lib', 'align', 'utils']
});

kit.pm.register('UserCart', {
   path: '/assets/plugins/cart/',
   module: 'main.js',
   js: ['jquery.min.js', ['utils.js', 'api.js']], // jquery -> (utils + api вместе)
   css: ['style.css'],
   autoRequire: true
});
```

### Пример регистрации HMD-плагина

```js
kit.pm.register('Logger', {
   type: 'HMD',
   alias: ['AltLogger'],
   handler: function(require, module, exports, global) {
       var object = {
          log: function(msg) { console.log('[Logger]: ' + msg); }
       };
      // kit.require('Logger') вернет module
      module.exports = object;
      // return задает, что определить в global.Logger и global.AltLogger
      return object.log;
   },
   onInstall: function(p) {
      console.log('Logger готов!');
   }
});
```

### Пример регистрации UMD-плагина

```js
kit.pm.register('MyUmdModule', {
   type: 'UMD',
   path: '/js/plugins/',
   module: 'my-plugin.umd.js', // Файл с UMD-оберткой
   deps: ['jquery'],           // Если плагину нужен jQuery
   autoRequire: true,
   onInstall: function(plugin) {
      console.log('UMD модуль успешно инициализирован');
   }
});
```

### Пример регистрации ES-плагина

```js
kit.pm.register('UserDashboard', {
   type: 'ES',                 // Указываем тип ES (ECMAScript)
   path: '/assets/modules/',   // Базовый путь
   module: 'dashboard.js',     // Файл, содержащий "export default"
   autoRequire: true,          // Начать загрузку сразу
   onInstall: function(plugin) {
      // В plugin.module.exports попадет то, что экспортировано из файла
      console.log('ES-модуль загружен:', plugin.module.exports);
   }
});
```

> Особенности работы с типом ES в твоем скрипте:

- Нативная загрузка: Вместо создания обычного тега `<script>`, менеджер использует динамический импорт `import(url)`.
- Строгий режим: Все ES-модули по умолчанию работают в use strict.
- CORS: Если модули загружаются с другого домена, сервер обязательно должен отдавать заголовок `Access-Control-Allow-Origin`, иначе браузер заблокирует загрузку.



## Описание параметров конфига для плагина

| Параметр              | Тип             | По умолчанию | Описание                                                                                      |
|:----------------------|:----------------|:------------:|:----------------------------------------------------------------------------------------------|
| **type**              | `string`        |  `default`   | Тип плагина.                                                                                  |
| **handler**           | `callback`      |      —       | Используется в связке с типом `HMD`. Имеет вид `function(r, m, e, g){m.e = {}; return {};}`.  |
| **path**              | `string`        |     `""`     | Базовый префикс пути для модуля, скриптов и стилей.                                           |
| **alias**             | `Array string`  |     `[]`     | Псевдонимы для `pluginId`, доступные в `require()` и `global`.                                |
| **module**            | `string`        |      —       | Прямая ссылка на файл с основным модулем.                                                     |
| **deps**              | `Array string`  |     `[]`     | Список ID плагинов-зависимостей, которые должны быть загружены ранее.                         |
| **css**               | `Array string`  |     `[]`     | Массив путей к стилям. Загружаются параллельно.                                               |
| **js**                | `Array string`  |     `[]`     | Цепочка скриптов. Массив в массиве (напр. `[1.js, [2.1, 2.2]]`) задает параллельную загрузку. |
| **loadJsAfterModule** | `bool`          |   `false`    | Если `true`, то внешние JS-скрипты загрузятся строго после основного модуля.                  |
| **isSetTimestamp**    | `bool`          |    `true`    | Добавит к загружаемым файлам параметр __pm который позволит установить кеш на 1 час.          |
| **onRegister**        | `callback`      |      —       | Функция, выполняемая однократно сразу после регистрации плагина.                              |
| **onLoad**            | `callback`      |      —       | Функция, выполняемая однократно после завершения загрузки всех ресурсов.                      |
| **onInstall**         | `callback`      |      —       | Функция, выполняемая однократно после финальной установки (выполнения handler).               |


## Использование

### Методы управления модулями

| Метод       | Аргументы                       | Вернет  | Описание                                                                                                                              |
|:------------|:--------------------------------|:-------:|:--------------------------------------------------------------------------------------------------------------------------------------|
| **require** | `pluginId, callback`            |   *     | Вызывает метод `callback` после установки `pluginId`. Возвращает модуль, если плагин установлен.                                      |
| **get**     | `pluginId, callback`            |   *     | Вызывает метод `callback` после установки `pluginId`. Возвращает модуль, если плагин установлен.                                      |
| **define**  | `deps, callback`                | Promise | Организаует вызов метода в стиле https://requirejs.org/. В качестве аргументов в метод `callback` будут проброшены экспорты плагинов. |
| **require** | `deps, callback`                | Promise | Организаует вызов метода в стиле https://requirejs.org/. В качестве аргументов в метод `callback` будут проброшены экспорты плагинов. |
| **ready**   | `deps, callback`                | Promise | Вызывает метод `callback` после установки зависимостей `deps` и отработки события `document.DOMContentLoaded`.                        |
| **exec**    | `deps, callback, args, context` | Promise | Вызывает метод `callback` после установки зависимостей `deps`.                                                                        |
| **loaded**  | `deps, callback`                | Promise | Вызывает метод `callback` после установки зависимостей `deps` и отработки события `window.load`.                                      |

---


Запуск исполняемого кода после установки зависимостей:

```js
kit.exec(deps, callback, argArr, context)
```
```js
kit.define(['UserAPI', 'Logger'], function(api, log) {
   log.info('Start');
});
```

```js
kit.ready(['UserAPI', 'Logger'], function() {
   kit.logger.info('Start');
   kit.require('UserAPI').do();
});
```

```js
kit.exec(['UserAPI', 'Logger'], function() {
   kit.logger.info('Start');
});
```

```js
kit.require('Product').then(function(){
   kit.Product.make(productId).then(function(product){
      product.setXData('.catalog-page');
      kit.require('alpine');
   })
})
```

# State list

| Значение | Состояние      | Описание                                                                 |
|:---------|:---------------|:-------------------------------------------------------------------------|
| `0`      | `undefined`    | Начальное состояние, плагин только что создан.                           |
| `1`      | `registered`   | Плагин зарегистрирован в системе, конфиг проверен.                       |
| `3`      | `loading`      | Идет активная загрузка файлов (JS, CSS, зависимости).                    |
| `4`      | `loaded`       | Все внешние ресурсы успешно загружены.                                   |
| `5`      | `installing`   | Выполняется основной код плагина (`handler`).                            |
| `6`      | `installed`    | Плагин полностью готов к работе, экспорт завершен.                       |



## Глобальный конфиг 

Параметры определяются в плагине `config`

> Параметры допустимо определять до загрузки `PluginManager`

| name                 | default                         | description                                                                                                                                                                 |
|----------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| assetsPath           | /local/templater.dev/kit/assets | Если не указывать, то определится автоматически при инициализации PluginManager                                                                                             |
| requiredDependencies | ['bsCore', 'toolkit']           | дополнительно определяет список зависимостей для любого колбека вызванного функциями `exec` и `ready`                                                                       |
| autoloadPluginList   | ['tooltip']                     | Автоматически загрузит ресурсы указанных плагинов. В случае модуля с типом `HMD` код не будет исполнен сразу после загрузки. Исполнение бдует определятся функций `install` |
| debug                | false                           | Расширит список выводимой в консоль информации                                                                                                                              |



## Глобальные переменные (window)

переменная kit может быть задана любой, поэтому в некоторых местах корректно будет использовать универсальные глобальные переменные

| name                | link                            | description   |
|---------------------|---------------------------------|---------------|
| `__pmGlobal__`      | аналог window.kit               |               |
| `__PluginManager__` | аналог window.kit.PluginManager |               | 
| `__pmConfig__`      | аналог window.kit.config        |               |


## z-index map

| z-index   | plugin   | selector                             |
|-----------|----------|--------------------------------------|
| 100       | flex-kit | .flex-card:hover .flex-card__content |
| 1000      | bs       | dropdown                             |
| 1020      | bs       | sticky                               |
| 1030      | bs       | fixed                                |
| 1040      | bs       | modal-backdrop                       |
| 1050      | bs       | offcanvas                            |
| 1060      | bs       | modal                                |
| 1070      | bs       | popover                              |
| 1080      | bs       | tooltip                              |




[//]: # (These are reference links used in the body of this note and get stripped out when the markdown processor does its job. There is no need to format nicely because it shouldn't be seen. Thanks SO - http://stackoverflow.com/questions/4823468/store-comments-in-markdown-syntax)

   [dill]: <https://github.com/joemccann/dillinger>