Merge pull request #875 from modx-pro/docs/ms3productsets-ms3favorites-update

docs: обновление ms3ProductSets и ms3Favorites (RU/EN)

Author: Ibochkarev

docs/components/ms3favorites/frontend.md

@@ -9,9 +9,14 @@ title: Подключение на сайте
 
 Для гостей при пустой БД данные берутся из `localStorage/cookie`. Для авторизованных и гостей (при `guest_db_enabled`) — из БД по `user_id` или `session_id`.
 
-**Чек-лист:** лексикон и `favorites.js` подключены на каждой странице товара; кнопка имеет `data-favorites-toggle` и `data-id`; `ms3favorites.guest_db_enabled` = Да; для авторизованных — пользователь авторизован в контексте **web**.
+**Чек-лист перед проверкой**
 
-## Коннектор (AJAX)
+- На каждой странице карточки товара подключены лексикон и скрипт `favorites.js`.
+- У кнопки избранного заданы атрибуты `data-favorites-toggle` и `data-id`.
+- При работе гостей с БД в системных настройках включено `ms3favorites.guest_db_enabled` (**Да**).
+- Авторизованный пользователь открывает сайт в контексте **web** (сессия совпадает с фронтом каталога).
+
+## Коннектор (AJAX) {#connector-ajax}
 
 **URL:** `assets/components/ms3favorites/connector.php`
 
@@ -23,7 +28,7 @@ title: Подключение на сайте
 - **sync** — синхронизация списков в БД (JSON). POST `lists` (JSON) или `ids`
 - **create_share** — создание публичной ссылки (JSON). POST `list`. Только авторизованные
 - **get_share** — получение данных по токену (JSON). POST `token`
-- **copy_share** — копирование чужого списка в свой (JSON). POST `token`, `target_list`
+- **`copy_share`** — копирование чужого списка в свой (JSON). POST **`token=xxx`**, **`target_list=default`** → **`{ success, ids }`**. **Гости** получают **`ids`** для **localStorage**.
 - **update_comment** — обновление заметки к элементу (JSON). POST `product_id`, `list`, `comment`. При `comments_enabled`
 - **add_to_cart** — добавление товаров в корзину (JSON). POST `ids` или `product_id`
 - **get_popularity** — маппинг id→count (JSON). POST `ids`, `resource_type`
@@ -37,7 +42,7 @@ title: Подключение на сайте
 |------|------------|
 | `tplFavoritesItem` | Карточка товара в списке «Избранное» |
 | `tplFavoritesEmpty` | Пустое состояние (при отсутствии товаров) |
-| `tplFavoritesPage` | Страница `/wishlist/` (табы, тулбар; карточки заполняет `favorites.js`, встроенной пагинации нет) |
+| `tplFavoritesPage` | Страница `/wishlist/` (табы, тулбар; при `resource_type=products` и `serverList=1` — SSR **pdoPage** + **msProducts** в чанке; при `serverList=0` или другом типе — карточки через `favorites.js`) |
 | `tplFavoritesPageItem` | Элемент для страницы `/wishlist/` (checkbox, заметка, кнопка удаления) |
 | `tplFavoritesPageDemo` | Тот же файл, что и `tplFavoritesPage`: при `&tpl=tplFavoritesPageDemo` или `&extendedToolbar=1` включается панель «Каталог / Очистить / Поделиться» |
 | `tplFavoritesListSelector` | Dropdown выбора списка (`default`, `gifts`, `plans`) |
@@ -65,6 +70,8 @@ title: Подключение на сайте
 | `data-favorites-count` | span | Счётчик количества элементов |
 | `data-favorites-share` | button | Кнопка «Поделиться списком» (атрибут `data-list`) |
 | `data-favorites-page-container` | div | Контейнер страницы wishlist |
+| `data-server-empty` | div | `1` — список на сервере пуст (cookie/sync); выставляет **ms3FavoritesPage** |
+| `data-ms3f-ssr-products` | div | `1` — SSR-список товаров в **tplFavoritesPage**; при «Очистить» и при удалении последней карточки возможна перезагрузка страницы |
 | `data-favorites-mode="list"` | div | Режим удаления карточки при клике «Удалить» |
 
 Чанки можно переопределять своими (Fenom или MODX); параметры `tpl` и `emptyTpl` задаются в сниппете и при вызове `render()` в JS.
@@ -75,7 +82,7 @@ title: Подключение на сайте
 
 На мобильных устройствах — горизонтальный скролл списка (`.ms3f__list`).
 
-## CSS-переменные
+## CSS-переменные {#css-variables}
 
 Переопределяйте в своей теме (`:root` или контейнер блока):
 
@@ -86,7 +93,9 @@ title: Подключение на сайте
 | `--ms3f-radius` | Скругление |
 | `--ms3f-color` | Цвет текста |
 | `--ms3f-price-color` | Цвет цены |
-| `--ms3f-button-active` | Цвет активной кнопки (товар в списке) |
+| `--ms3f-button-active` | Акцентный цвет: активная кнопка избранного, основные кнопки на `/wishlist/`, outline фокуса, `accent-color` у чекбокса |
+
+Переменные заданы в начале `favorites.css` в блоке `:root` и влияют на карточки списка, страницу `/wishlist/` (вкладки, тулбар, поля) и кнопку избранного. В отдельных правилах для `--ms3f-button-active` указан запасной цвет `#e74c3c`, если переменная не переопределена.
 
 Пример:
 
@@ -115,22 +124,42 @@ title: Подключение на сайте
 
 ## JavaScript API
 
+Актуально для объекта, который экспортирует `assets/components/ms3favorites/js/favorites.js` (`window.ms3Favorites`).
+
 ```javascript
 window.ms3Favorites = {
-  getList(name),        // Получить ID списка
-  getAllLists(resourceType?), // Все списки {default:[], gifts:[]}; без аргумента — текущий resource_type
-  add(id, list),        // Добавить товар в список
-  remove(id, list),     // Удалить из списка
-  switchList(name),     // Переключить активный список
-  render(selector, options),  // options: list, tpl, emptyTpl, limit
-  updateCounter(), updateButtonStates(),
-  sync(),               // Синхронизация (POST lists)
-  createShare(list),    // Создать share-ссылку → token (только авторизованные)
-  copyFromShare(token), // Скопировать чужой список (target_list опционально)
-  addToCart(ids),       // Добавить товары в корзину MiniShop3
-  addSelectedToCart(),  // Добавить выбранные (checkbox)
-  updateComment(productId, list, comment),  // Сохранить заметку (до 500 символов)
-  clear(list)           // Очистить список (action=clear)
+  // Списки и тип ресурса (второй/третий аргументы опциональны — берутся из контекста страницы / storage)
+  getList(name?, resourceType?),
+  getAllLists(resourceType?), // без аргумента — слияние списков по всем типам из byType (для /wishlist/ обычно передают тип страницы)
+  add(id, list?, resourceType?),
+  remove(id, list?, resourceType?),
+  clearList(list?, resourceType?), // локально очистить список и комментарии к позициям; кнопка «Очистить» дополнительно шлёт POST action=clear
+  switchList(name),
+
+  render(selector, options), // selector: строка (querySelector) или DOM-элемент с id → регистрируется как #id; options: list, tpl, emptyTpl, limit, resource_type или resourceType
+  updateCounter(),
+  updateButtonStates(),
+
+  sync(options?), // для каждого типа: POST action=sync с локальными списками, ответ сервера записывается в storage; authoritative: true — флаг «локальное состояние — источник правды» (см. flushToServer)
+  flushToServer(), // обёртка: sync({ authoritative: true }) и событие ms3f:synced
+
+  createShare(list?, resourceType?), // Promise → token | null (только авторизованные)
+  copyFromShare(token), // Promise → массив ID; список назначения — текущий активный (перед вызовом при необходимости switchList)
+
+  addToCart(ids), // Promise → число добавленных в корзину MiniShop3
+  addSelectedToCart(), // Promise — по отмеченным [data-favorites-cart-checkbox]
+  updateComment(productId, list?, comment, resourceType?), // заметка до лимита COMMENT_MAX_LENGTH в коде (500)
+
+  // Дополнительно
+  getData(), // объект из localStorage/cookie (byType, _defaultType, …)
+  save(data), // записать после правок и обновить счётчики, кнопки и зарегистрированные render-цели
+  getTotalCount(resourceType?), // без аргумента — сумма по всем типам и спискам
+  getComment(productId, listName?, resourceType?),
+  getResourceTypeFromElement(el), // data-resource-type
+  getAll(), // устаревшее имя: getList('default') с типом ресурса из _defaultType в данных
+  toast(text, variant?),
+  getConnectorUrl(),
+  ensureCookie(), // используется при data-server-empty на странице списка
 };
 ```
 

docs/components/ms3favorites/index.md

@@ -38,14 +38,14 @@ ms3Favorites — компонент реализует функционал со
 - **Гости в БД** — при `guest_db_enabled` список гостя сохраняется по session_id
 - **Несколько списков** — `default`, `gifts`, `plans` и др. (до `max_lists`)
 - **Шаринг списка** — публичная ссылка `/wishlist/share?token=xxx`, копирование чужого списка
-- **Страница /wishlist/** — табы и контейнер от `ms3FavoritesPage`, карточки дорисовывает JS; счётчики табов и `ms3f.total` на сервере; пагинация отдельно (ms3FavoritesIds + pdoPage)
+- **Страница /wishlist/** — `ms3FavoritesPage`: табы и оболочка; для **`resource_type=products`** при **`serverList=1`** (по умолчанию) список товаров выводится **на сервере** в чанке (**pdoPage** + **msProducts**); при **`serverList=0`** карточки дорисовывает **favorites.js** (до 100 позиций на вкладку). Для других типов ресурсов список по-прежнему через `JS` после `sync`. Отдельная серверная пагинация — цепочка `ms3FavoritesIds` → `pdoPage` → `ms3Favorites` (или `msProducts`)
 - **Интеграция с корзиной** — «Добавить все в корзину», «Добавить выбранные»
 - **Популярность** — «У N пользователей в избранном»
 - **Типы ресурсов** — `products`, `resources`, `articles`, `pages`, `custom`
 - **Локализация** — MODX Lexicon (ru, en), на фронте — сниппет `ms3fLexiconScript`
 - **Кастомизация** — Fenom-чанки, BEM-классы (префикс `ms3f`), CSS-переменные
 - **Каталог** — чанк `tplCatalogRowMs3f` для строки с кнопкой избранного при **pdoPage** + **msProducts** ([интеграция](integration#catalog-pdopage-row))
-- **Уведомления** — цепочка: опционально `ms3fConfig.notify` → `window.ms3Message.show` (MiniShop3) → [iziToast](https://marcelodolza.github.io/iziToast/) (ленивая загрузка из `assets/components/ms3favorites/vendor/izitoast/`, базовый URL в `ms3fConfig.iziToastBaseUrl` из `ms3fLexiconScript`). Настройка `ms3favorites.use_minishop3_toast` удалена.
+- **Уведомления** — цепочка: опционально `ms3fConfig.notify` → `window.ms3Message.show` (MiniShop3) → [iziToast](https://marcelodolza.github.io/iziToast/) (ленивая загрузка из `assets/components/ms3favorites/vendor/izitoast/`, базовый URL в `ms3fConfig.iziToastBaseUrl` из `ms3fLexiconScript`).
 
 ## Системные требования
 
@@ -58,7 +58,7 @@ ms3Favorites — компонент реализует функционал со
 ### Зависимости
 
 - **[MiniShop3](/components/minishop3/)** — товары и категории
-- **[pdoTools](/components/pdotools/) 3.0.0+** — для сниппетов (pdoPage, Fenom)
+- **[pdoTools](/components/pdotools/) 3.0.0+**
 
 ## Установка
 
@@ -85,6 +85,6 @@ ms3Favorites — компонент реализует функционал со
 | Термин | Описание |
 |--------|----------|
 | **Wishlist** | Список избранных товаров (по умолчанию — `default`) |
-| **Синхронизация** | Перенос списка из localStorage в БД при входе пользователя |
+| **Синхронизация** | Перенос списка из `localStorage` в БД при входе пользователя |
 | **Шаринг** | Публичная ссылка на список по токену |
 | **Популярность** | Количество пользователей, добавивших ресурс в избранное |