iwgt 2.4.10 → 2.4.12

package/dist/data/widget-wrapper-and-context.md

@@ -0,0 +1,647 @@
+# Системная обёртка виджетов и контекст выполнения
+
+## Системная обёртка (layout wrapper)
+
+**ВАЖНО:** Весь код из `snippet.liquid` автоматически оборачивается системой InSales в `div` с классом `layout` и уникальным классом виджета.
+
+### Структура обёртки
+
+```html
+<div
+  class="layout widget-type_#{widget_handle}"
+  style="--heading-hide:false; --delete-borders:false; --align-title:left; ..."
+  data-widget-drop-item-id="209226033"
+>
+  <!-- ВАШ КОД ИЗ snippet.liquid -->
+</div>
+```
+
+### Шаблон класса виджета
+
+```
+widget-type_#{widget_handle}
+```
+
+Пример: для виджета с `handle: "system-widget-story"` класс будет `widget-type_system-widget-story`
+
+### CSS переменные из настроек
+
+Система автоматически преобразует настройки виджета из `settings_form.json` в CSS-переменные в атрибуте `style`.
+
+**Правило преобразования:**
+- Название настройки становится CSS-переменной: `layout-wide-bg` → `--layout-wide-bg`
+- Значение настройки становится значением CSS-переменной
+
+**Пример:**
+
+```json
+// settings_form.json
+{
+  "handle": "layout-wide-bg",
+  "type": "checkbox",
+  "value": true
+}
+```
+
+Преобразуется в:
+```html
+style="--layout-wide-bg:true"
+```
+
+### Полный пример
+
+```html
+<div
+   class="layout widget-type_system-widget-story"
+   style="--heading-hide:false; --delete-borders:false; --align-title:left; --stories-rounding:false; --slide-width:200px; --slide-gap:30rem; --open-link:normal; --img-ratio:1; --banner-border-radius:0px; --slide-width-mobile:150px; --img-ratio-mobile:1; --layout-wide-bg:true; --layout-pt:2vw; --layout-pb:2vw; --layout-wide-content:false; --layout-edge:false; --hide-desktop:false; --hide-mobile:false;"
+   data-widget-drop-item-id="209226033"
+>
+   <!-- html из snippet.liquid -->
+</div>
+```
+
+## Контекст выполнения виджета
+
+### Основные переменные контекста
+
+#### 1. `widget_settings` - настройки виджета
+
+Доступ к значениям из `settings_form.json`:
+
+```liquid
+{{ widget_settings.layout-wide-content }}
+{{ widget_settings.title_text-default }}
+{{ widget_settings.menu-handle }}
+```
+
+#### 2. `data.blocks` - блоки виджета (только для BlockListWidgetType)
+
+**ВАЖНО:** Для виджетов типа `BlockListWidgetType` блоки доступны через переменную `data.blocks`.
+
+**Перебор блоков:**
+
+```liquid
+{% for block in data.blocks %}
+  {{ block.name }}
+  {{ block.image }}
+  {{ block.link }}
+{% endfor %}
+```
+
+**Доступные поля блока** зависят от `block_template_handle`, указанного в `info.json`.
+
+Например, для `system-banner-video`:
+- `block.link` - ссылка
+- `block.image` - заставка
+
+#### 3. `widget_messages` - переводы текстов
+
+Содержит переводы из файла `messages.json`:
+
+```liquid
+{{ widget_messages.button_text }}
+{{ widget_messages.empty_state }}
+```
+
+#### 4. Доступ к сущностям магазина через настройки
+
+Через настройки виджета можно получить доступ к различным сущностям магазина.
+
+**Пример: вывод меню**
+
+```liquid
+{%  comment %}
+  В settings_form.json есть настройка:
+  {
+    "handle": "menu-handle",
+    "type": "menu",
+    "value": "main-menu"
+  }
+{% endcomment %}
+
+{% for link in linklists[widget_settings.menu-handle].links %}
+  <li class="header__menu-item" data-navigation-item data-menu-item-id="{{ link.id}}">
+    <div class="header__menu-controls">
+      <a href="{{ link.url }}" class="header__menu-link" data-navigation-link="{{ link.url }}">
+        {{ link.title }}
+      </a>
+    </div>
+  </li>
+{% endfor %}
+```
+
+**Пример: вывод категории**
+
+```liquid
+{%  comment %}
+  В settings_form.json есть настройка:
+  {
+    "handle": "collection-handle",
+    "type": "collection",
+    "value": null
+  }
+{% endcomment %}
+
+{% assign collection = collections[widget_settings.collection-handle] %}
+{% if collection %}
+  <h2>{{ collection.title }}</h2>
+  {% for product in collection.products %}
+    {{ product.title }}
+  {% endfor %}
+{% endif %}
+```
+
+### Глобальные переменные Liquid
+
+В контексте виджета доступны все глобальные переменные InSales Liquid:
+
+- `account` - данные магазина
+- `template` - текущий шаблон страницы
+- `language` / `languages` - локализация
+- `product` - товар (на странице товара)
+- `collection` - категория (на странице категории)
+- `cart` - корзина
+- `linklists` - все меню магазина
+- `collections` - все категории магазина
+- `settings` - глобальные настройки темы
+
+Полный список в справочнике: `get_liquid_variables`
+
+## JavaScript виджета (snippet.js)
+
+### Системная обёртка snippet.js
+
+**ВАЖНО:** Весь код из `snippet.js` автоматически оборачивается системой в `try/catch` блок с предопределёнными переменными.
+
+**Система оборачивает ваш код так:**
+
+```js
+try {
+  let widget = '.widget-type_your-widget-handle';
+  let $widget = $('.widget-type_your-widget-handle');
+  
+  // ВАШ КОД ИЗ snippet.js
+  
+} catch(error) {
+  console.error('Widget "widget-type_your-widget-handle"', error)
+}
+```
+
+**Доступные переменные:**
+- `widget` - строка с селектором виджета (`.widget-type_#{handle}`)
+- `$widget` - jQuery объект виджета (если подключен jQuery)
+
+**Ваш код в snippet.js:**
+
+```js
+// НЕ нужно оборачивать в try/catch - это делается автоматически!
+// НЕ нужно объявлять widget и $widget - они уже доступны!
+
+// Можно сразу использовать переменные:
+console.log('Виджет инициализирован:', widget);
+
+if ($widget.length) {
+  // Работа с jQuery
+  $widget.find('.block').each(function() {
+    // ...
+  });
+}
+
+// Или с vanilla JS:
+const widgetEl = document.querySelector(widget);
+if (widgetEl) {
+  // ...
+}
+```
+
+### EventBus - события визуального редактора
+
+**EventBus** - это сервисный объект с событиями визуального редактора виджетов InSales.
+
+**События изменения настроек виджета:**
+
+```js
+EventBus.subscribe([
+  'widget:input-setting:insales:system:editor',
+  'widget:change-setting:insales:system:editor', 
+  'widget:input-color:insales:system:editor'
+], (data) => {
+  console.log('Настройка изменена:', data);
+});
+```
+
+**Структура объекта data:**
+
+```js
+{
+  widget_id: 87289537,           // ID виджета
+  widget_item_id: 209226033,     // ID экземпляра виджета
+  setting_name: "align-title",   // Название настройки
+  value: "center",               // Новое значение
+  unit: "px",                    // Единица измерения (для числовых)
+  type: "icon_group"             // Тип настройки
+}
+```
+
+**Примеры событий:**
+
+```js
+// Изменение выравнивания
+{
+  setting_name: "align-title",
+  type: "icon_group",
+  unit: undefined,
+  value: "center",
+  widget_id: 87289537,
+  widget_item_id: 209226033
+}
+
+// Изменение цвета с оттенками
+{
+  widget_id: 87289537,
+  widget_item_id: 209226033,
+  setting_name: "bg-details-stories-color",
+  value: "#338072",
+  type: "color",
+  shades: [
+    {name: "minor", light: -3, dark: 10},
+    {name: "major", light: -7, dark: 20},
+    {name: "half", light: -50, dark: 50}
+  ]
+}
+```
+
+**Типы настроек (type):**
+- `color` - цветовая настройка
+- `text` - текстовое поле
+- `number` - числовое поле
+- `select` - выпадающий список
+- `fonts_select` - выбор шрифта
+- `icon_group` - группа иконок
+- и другие...
+
+**Пример использования EventBus:**
+
+```js
+// Обновление стилей при изменении настроек в редакторе
+EventBus.subscribe([
+  'widget:input-setting:insales:system:editor',
+  'widget:change-setting:insales:system:editor'
+], (data) => {
+  if (data.setting_name === 'slide-gap') {
+    // Обновляем слайдер с новым значением gap
+    const widgetEl = document.querySelector(widget);
+    if (widgetEl && window.Splide) {
+      const splide = widgetEl.querySelector('.splide');
+      // Переинициализация слайдера
+    }
+  }
+});
+```
+
+## Архитектура виджетов InSales (важно!)
+
+### НЕ ИСПОЛЬЗУЮТСЯ:
+
+❌ **Кастомные теги** - нестандартные HTML-теги являются ОШИБКОЙ  
+❌ **React, Angular** и другие фреймворки
+
+### ИСПОЛЬЗУЮТСЯ:
+
+✅ **Liquid** - шаблонизатор для разметки (snippet.liquid)  
+✅ **Vanilla JavaScript** - для логики виджета (snippet.js)  
+✅ **CommonJS API** - для работы с магазином (Cart, Products, EventBus и т.д.)  
+✅ **Библиотеки** - указанные в `info.json` в поле `libraries` (jquery, splide, swiper и т.д.)
+
+### Правильная структура HTML
+
+```liquid
+<div class="widget-container">
+  {% if widget_settings.show-heading %}
+    <h2 class="widget-heading">{{ widget_settings.heading-text }}</h2>
+  {% endif %}
+  
+  {% if data.blocks %}
+    <div class="widget-blocks">
+      {% for block in data.blocks %}
+        <div class="widget-block">
+          {% if block.image %}
+            <img src="{{ block.image | img_url: '800x' }}" alt="{{ block.name }}">
+          {% endif %}
+          {% if block.name %}
+            <h3>{{ block.name }}</h3>
+          {% endif %}
+          {% if block.link %}
+            <a href="{{ block.link }}" class="widget-link">Подробнее</a>
+          {% endif %}
+        </div>
+      {% endfor %}
+    </div>
+  {% endif %}
+</div>
+```
+
+## Debugging
+
+### Вывод доступных переменных
+
+```liquid
+{% help %}
+```
+
+### Вывод свойств объекта
+
+```liquid
+{% help account %}
+{% help product %}
+{% help widget_settings %}
+```
+
+### Проверка значения переменной
+
+```liquid
+{{ widget_settings | json }}
+{{ data.blocks | json }}
+```
+
+## Стили виджета (snippet.scss)
+
+### Структура SCSS файла
+
+**ВАЖНО:** Весь код в `snippet.scss` автоматически оборачивается в класс виджета.
+
+Система компилирует ваш SCSS так:
+```scss
+// Ваш код в snippet.scss:
+& {
+  padding: 2rem;
+}
+
+// Компилируется в:
+.layout.widget-type_your-widget {
+  padding: 2rem;
+}
+```
+
+### Использование & (амперсанд)
+
+Символ `&` обращается к родительскому классу (`.layout.widget-type_#{handle}`):
+
+```scss
+& {
+  // Стили для родительского элемента
+  border-bottom: 1px solid var(--bg-minor-shade);
+  box-shadow: 0px 10px 20px -10px rgba(0,0,0,0.1);
+  position: relative;
+}
+
+// Состояния на основе CSS-переменных из настроек
+&[style*="--article-hide-photo:true"] {
+  .article-photo {
+    display: none!important;
+  }
+}
+
+&[style*="--hide-favorites:true"][style*="--hide-personal:false"] {
+  .navigation-bar {
+    grid-template-columns: repeat(4, 1fr);
+  }
+}
+```
+
+### Работа с CSS-переменными
+
+Настройки виджета автоматически становятся CSS-переменными:
+
+```scss
+& {
+  // Используем переменные из настроек
+  padding-top: var(--layout-pt, 2rem);
+  padding-bottom: var(--layout-pb, 2rem);
+  
+  // Переопределяем переменные
+  --grid-list-min-width: 190px;
+  --grid-list-row-gap: 1rem;
+  --grid-list-column-gap: 2rem;
+  
+  @media screen and (max-width: 767px) {
+    --grid-list-min-width: 50%;
+  }
+}
+```
+
+### Глобальный миксин background-color
+
+**ВАЖНО:** В системе InSales глобально доступен миксин для работы с цветами фона, который автоматически управляет цветом текста в зависимости от яркости фона.
+
+```scss
+@mixin background-color($color) {
+    $dark_selector: '[style*="#{$color}-is-dark:true"]';
+    $light_selector: '[style*="#{$color}-is-light:true"]';
+    background-color: var(#{$color});
+    @at-root #{selector-append($dark_selector, &)} {
+        color: var(--color-text-light);
+        --color-text: var(--color-text-light);
+        --color-text-minor-shade: var(--color-text-light-minor-shade);
+        --color-text-major-shade: var(--color-text-light-major-shade);
+        --color-text-half-shade: var(--color-text-light-half-shade);
+    }
+    @at-root #{selector-append($light_selector, &)} {
+        color: var(--color-text-dark);
+        --color-text: var(--color-text-dark);
+        --color-text-minor-shade: var(--color-text-dark-minor-shade);
+        --color-text-major-shade: var(--color-text-dark-major-shade);
+        --color-text-half-shade: var(--color-text-dark-half-shade);
+    }
+}
+```
+
+**Использование миксина:**
+
+```scss
+.widget-block {
+  // Применяем фоновый цвет с автоматической адаптацией текста
+  @include background-color(--bg-color);
+  
+  // Система автоматически добавит переменные:
+  // --bg-color-is-dark:true или --bg-color-is-light:true
+  // в атрибут style родительского элемента
+}
+```
+
+**Как это работает:**
+1. Настройка цвета в `settings_form.json` типа `color` создаёт CSS-переменную
+2. Система анализирует яркость цвета и добавляет `--название-цвета-is-dark:true` или `--название-цвета-is-light:true`
+3. Миксин автоматически применяет правильный цвет текста (светлый для тёмного фона, тёмный для светлого)
+
+**Доступные оттенки текста:**
+- `--color-text` - основной цвет текста
+- `--color-text-minor-shade` - лёгкий оттенок
+- `--color-text-major-shade` - сильный оттенок  
+- `--color-text-half-shade` - средний оттенок
+
+### Полный пример SCSS
+
+```scss
+& {
+  // Основные стили
+  padding-top: var(--layout-pt, 2rem);
+  padding-bottom: var(--layout-pb, 2rem);
+  position: relative;
+  
+  // Используем миксин для фонового цвета
+  @include background-color(--bg-widget-color);
+}
+
+// Широкий фон
+&[style*="--layout-wide-bg:true"] {
+  width: 100vw;
+  margin-left: calc(50% - 50vw);
+}
+
+// Скрытие на устройствах
+&[style*="--hide-mobile:true"] {
+  @media (max-width: 767px) {
+    display: none;
+  }
+}
+
+// Вложенные элементы
+.widget-container {
+  max-width: var(--layout-content-max-width, 1200px);
+  margin: 0 auto;
+}
+
+.widget-block {
+  @include background-color(--bg-block-color);
+  
+  img {
+    width: 100%;
+    height: auto;
+  }
+  
+  &:hover {
+    transform: scale(1.02);
+  }
+}
+```
+
+## Типичные ошибки
+
+### ❌ НЕПРАВИЛЬНО (Liquid):
+
+```liquid
+<!-- НЕ ИСПОЛЬЗУЙТЕ кастомные теги -->
+<custom-tag>
+  <another-custom-tag>
+    Контент
+  </another-custom-tag>
+</custom-tag>
+
+<!-- НЕ добавляйте обёртку layout вручную -->
+<div class="layout">
+  <!-- код виджета -->
+</div>
+```
+
+### ❌ НЕПРАВИЛЬНО (SCSS):
+
+```scss
+// НЕ добавляйте класс виджета вручную
+.layout.widget-type_my-widget {
+  padding: 2rem;
+}
+
+// НЕ используйте :root или html для переменных виджета
+:root {
+  --my-variable: 10px;
+}
+```
+
+### ✅ ПРАВИЛЬНО (Liquid):
+
+```liquid
+<!-- Используйте обычные HTML-теги -->
+<div class="grid">
+  <div class="grid-cell">
+    Контент
+  </div>
+</div>
+
+<!-- Обёртка layout добавится автоматически -->
+<div class="widget-content">
+  <!-- ваш код -->
+</div>
+```
+
+### ✅ ПРАВИЛЬНО (SCSS):
+
+```scss
+// Используйте & для родительского элемента
+& {
+  padding: 2rem;
+  
+  // Определяйте переменные здесь
+  --my-variable: 10px;
+}
+
+// Селекторы элементов без &
+.widget-content {
+  margin: 1rem 0;
+}
+
+// Состояния с &
+&[style*="--some-setting:true"] {
+  .element {
+    display: none;
+  }
+}
+```
+
+## Работа с блоками
+
+### Проверка наличия блоков
+
+```liquid
+{% if data.blocks and data.blocks.size > 0 %}
+  <!-- вывод блоков -->
+{% else %}
+  <!-- заглушка или пустое состояние -->
+  <div class="widget-empty">
+    {{ widget_messages.no_blocks_message }}
+  </div>
+{% endif %}
+```
+
+### Перебор блоков с индексом
+
+```liquid
+{% assign slide_index = 0 %}
+{% for block in data.blocks %}
+  <div class="slide" data-slide-index="{{ slide_index }}">
+    {{ block.name }}
+  </div>
+  {% assign slide_index = slide_index | plus: 1 %}
+{% endfor %}
+```
+
+### Доступ к полям блока
+
+Поля блока зависят от `block_template_handle`. Например:
+
+**system-banner-2:**
+- `block.name` - название (текст)
+- `block.image` - изображение (файл)
+- `block.link` - ссылка (текст)
+
+**system-banner-video:**
+- `block.link` - ссылка на видео (текст)
+- `block.image` - заставка видео (файл)
+
+**system-benefit-2:**
+- `block.name` - заголовок (текст)
+- `block.description` - описание (HTML)
+- `block.image` - изображение (файл)
+
+Полный список шаблонов блоков и их полей: `get_block_templates`
+

package/dist/generators/index.js

@@ -259,6 +259,11 @@ export function generateSettingsForm(commonSettings) {
                 if (setting.clearable)
                     item.clearable = setting.clearable;
             }
+            else if (setting.type === 'file') {
+                item.value = setting.value || null;
+                if (setting['with-generate-logo'])
+                    item['with-generate-logo'] = setting['with-generate-logo'];
+            }
             // Общие свойства
             if (setting.help)
                 item.help = setting.help;

package/dist/server-http.js

@@ -57,7 +57,7 @@ const httpServer = createServer(async (req, res) => {
         res.end(JSON.stringify({
             status: 'ok',
             service: 'InSales Widgets MCP Server',
-            version: '2.4.10',
+            version: '2.4.12',
             transport: 'SSE',
             endpoints: {
                 sse: '/sse',