diff --git a/config/guide-structure.json b/config/guide-structure.json index 6f21d3ee..17c4b744 100644 --- a/config/guide-structure.json +++ b/config/guide-structure.json @@ -437,6 +437,33 @@ } ] }, + { + "slug": "sets", + "title": "Наборы компонентов", + "order": 75, + "pages": [ + { + "slug": "connect", + "title": "Подключение набора", + "order": 10 + }, + { + "slug": "versions", + "title": "Версии и совместимость", + "order": 20 + }, + { + "slug": "licence", + "title": "Лицензия", + "order": 30 + }, + { + "slug": "names", + "title": "Имена компонентов", + "order": 40 + } + ] + }, { "slug": "layouts", "title": "Макеты и композиция", diff --git a/content/ru/guide/index.md b/content/ru/guide/index.md index d46e5d1b..c70bfe56 100644 --- a/content/ru/guide/index.md +++ b/content/ru/guide/index.md @@ -36,6 +36,7 @@ description: "Руководство описывает SIMAI Framework цели | Все | [Знакомство](/ru/guide/introduction/) и [Подключение и обновление](/ru/guide/connection/) | | Те, кто пишет разметку и оформление | [Токены, цвет и темы](/ru/guide/colour/), [Размер, пространство, текст и форма](/ru/guide/size-and-type/), [Утилиты и раскладка](/ru/guide/utilities/) | | Те, кто работает с компонентами и пишет их | [Компоненты](/ru/guide/components/) и [Смарт-компоненты](/ru/guide/smart-components/) | +| Те, кому нужны админка, таблицы с фильтрами, чат, графики или эффекты | [Наборы компонентов](/ru/guide/sets/) | | Те, кто собирает страницы из данных | [Макеты и композиция](/ru/guide/layouts/) | | Авторы Framework, проверяющие, пользователи ИИ-инструментов | [Стандарты, качество и ИИ](/ru/guide/standards/) | @@ -68,6 +69,7 @@ description: "Руководство описывает SIMAI Framework цели | [Утилиты и раскладка](/ru/guide/utilities/) | Синтаксис утилит, значения, условия, классы раскладки | Всем, кто пишет разметку | | [Компоненты](/ru/guide/components/) | Компоненты на классах: анатомия, имена настроек, размеры, состояния, поля форм | Разработчикам интерфейса | | [Смарт-компоненты](/ru/guide/smart-components/) | Собственные теги с поведением по стандарту смарт-компонентов: модель из настроек, значений, событий и действий, папка компонента и манифест, сборки с данными и правилами, данные с сервера, язык, вид и доступность | Разработчикам интерфейса и авторам компонентов | +| [Наборы компонентов](/ru/guide/sets/) | Готовые смарт-компоненты для отдельных задач поверх Framework: какие бывают, подключение одной строкой, версии, лицензия, имена | Тем, кому нужны админка, представления данных, чат, письма, графики или эффекты | | [Макеты и композиция](/ru/guide/layouts/) | Страница как данные: документ, сборка, блоки, источники данных, редактор | Тем, кто собирает страницы из данных и CMS | | [Стандарты, качество и ИИ](/ru/guide/standards/) | Что обязано быть правдой, проверки Framework и проекта, работа с ИИ | Авторам Framework, проверяющим, пользователям ИИ | | [Глоссарий](/ru/guide/glossary/) | Термины руководства | По необходимости | diff --git a/content/ru/guide/sets/connect.md b/content/ru/guide/sets/connect.md new file mode 100644 index 00000000..40e777d6 --- /dev/null +++ b/content/ru/guide/sets/connect.md @@ -0,0 +1,92 @@ +--- +title: "Подключение набора" +description: "Набор подключают одной строкой: атрибут data-sf-sets на скрипте ядра SIMAI Framework. Там же закрепляют версию, называют несколько наборов или задают свой адрес набора." +--- + +# Подключение набора + +Набор подключают одной строкой: на скрипт ядра SIMAI Framework добавляют +атрибут `data-sf-sets` с именем набора. Больше ничего перечислять не нужно: +Loader сам найдёт подходящий выпуск набора и загрузит только те его +компоненты, которые есть на странице. + +Атрибут `data-sf-sets` понимает Loader начиная с выпуска SIMAI Framework +`5.20261103.2154` (`core.runtime` 1.25.0). + +## Одна строка + +Пример подключает набор эффектов и ставит на страницу один эффект: + +```html + + + + +``` + +`<выпуск>` — версия пакета `@simai-studio/ui`, которую закрепил проект (см. +[Версии](/ru/guide/connection/versions/)): `5.20261103.2154` или новее. +Набор берётся из общего каталога выпусков: Loader выбирает самый новый +выпуск набора, который подходит к этому SIMAI Framework. Например, с +`5.20261103.2154` на месте `<выпуск>` Loader найдёт в каталоге набор `effects` +1.0.0 и загрузит его с jsDelivr. + +## Закрепить версию набора + +Чтобы страница всегда получала одну и ту же версию набора, её пишут после +имени через `@`: + +```html + +``` + +С закреплённой версией Loader не читает каталог выпусков и берёт набор прямо +из пакета npm `@simai-studio/effects@1.0.0`. Так подключают набор в рабочем +проекте: версия меняется только тогда, когда её меняет проект. + +## Несколько наборов + +Имена наборов перечисляют через пробел; у каждого может быть своя версия: + +```html + +``` + +Если один набор опирается на другой (админка показывает данные компонентами +набора `view`), страница называет оба. Loader сам второй набор не подключает. + +## Свой адрес набора + +Набор можно взять не с CDN, а со своего сервера или из локальной копии. Адрес +задают в `SF_BOOT_CONFIG` до скрипта ядра: + +```html + + +``` + +В `SF_BOOT_CONFIG.packages` набор можно описать любым из способов: + +| Запись | Что значит | +|:---|:---| +| `effects: true` | выпуск из каталога, как `data-sf-sets="effects"` | +| `effects: '1.0.0'` | эта версия пакета npm, каталог не читается | +| `effects: '/assets/sets/effects/dist/smart'` | набор лежит по этому адресу | + +Если набор назван и в `SF_BOOT_CONFIG`, и в `data-sf-sets`, действует +`SF_BOOT_CONFIG`. + +## Если что-то не так + +Ошибка в подключении набора не ломает страницу: остальные компоненты +работают, а Loader пишет предупреждение в консоль браузера. + +| Что случилось | Что будет | +|:---|:---| +| Набор не назван на странице | Его компоненты остаются неопределёнными тегами; `SF.package('effects')` отвечает ошибкой и называет строку, которую нужно добавить | +| Набора нет в каталоге или для этого SIMAI Framework нет подходящего выпуска | Предупреждение с причиной; компоненты набора не загружаются. Помогает закреплённая версия или свой адрес | +| В `data-sf-sets` написано не имя набора | Слово пропускается с предупреждением | +| Файлы набора не загрузились | Предупреждение с адресом; компоненты набора не загружаются | +| Набору нужен другой набор, которого нет на странице | В режиме отладки (`?sf-debug`) Loader называет недостающий набор | diff --git a/content/ru/guide/sets/connect.page.json b/content/ru/guide/sets/connect.page.json new file mode 100644 index 00000000..cc969543 --- /dev/null +++ b/content/ru/guide/sets/connect.page.json @@ -0,0 +1 @@ +{"schema": "docara.page.v1", "navigation": {"order": 10}} diff --git a/content/ru/guide/sets/index.md b/content/ru/guide/sets/index.md new file mode 100644 index 00000000..8882151b --- /dev/null +++ b/content/ru/guide/sets/index.md @@ -0,0 +1,63 @@ +--- +title: "Наборы компонентов" +description: "Набор компонентов — готовые смарт-компоненты для одной задачи: админка, представления данных, чат, письма, редактор, графики, эффекты. Набор подключают к странице одной строкой поверх SIMAI Framework." +--- + +# Наборы компонентов + +Бесплатный SIMAI Framework содержит универсальные части интерфейса: утилиты, +компоненты, смарт-компоненты, простой список и простую таблицу. Всё, что +нужно для отдельной задачи — админка, канбан, чат, конструктор писем, +графики, — поставляется **наборами компонентов** поверх него. + +Наборы подключаются начиная с выпуска SIMAI Framework `5.20261103.2154` +(`core.runtime` 1.25.0). Первый выпущенный набор — `effects`; остальные +появляются в каталоге выпусков по мере выхода, а до тех пор компоненты Pro +подключают как пакет `pro`, см. раздел [Pro](/ru/pro/). + +## Что такое набор + +Набор — это смарт-компоненты одной задачи, которые выпускаются вместе: + +- у набора одно короткое имя, например `effects` или `chat`; +- набор работает поверх SIMAI Framework и использует его компоненты, а не + повторяет их; +- набор сам описывает свои компоненты, поэтому новый компонент в наборе не + требует нового выпуска SIMAI Framework; +- у каждого набора свой сайт с документацией и демонстрациями. + +Страница подключает SIMAI Framework и называет нужные наборы. Loader загружает +только те компоненты набора, которые есть на странице. + +## Какие бывают наборы + +| Набор | Для чего | Лицензия | Сайт | +|:---|:---|:---|:---| +| `admin` | Админка: меню, рабочие экраны, настройки | Pro | [admin.simai.io](https://admin.simai.io/) | +| `view` | Представления данных: умная таблица с сортировкой, фильтрами и страницами, канбан, календарь, диаграмма Ганта | Pro | view.simai.io, появится | +| `chat` | Чат: лента сообщений, поле ввода, список диалогов | Pro | свой поддомен, появится | +| `mail` | Письма: конструктор и просмотр писем | Pro | свой поддомен, появится | +| `editor` | Редактор страниц и текста | Pro | свой поддомен, появится | +| `chart` | Графики и диаграммы | Pro | свой поддомен, появится | +| `effects` | Фоновые эффекты и анимации | Бесплатно | [effects.simai.io](https://effects.simai.io/) | + +Простой список и простая таблица остаются в бесплатном SIMAI Framework. +Набор `view` нужен, когда данным требуются сортировка, фильтры, страницы или +другой способ показа. + +## Что в Framework, а что в наборе + +- Всё универсальное — в SIMAI Framework: кнопки, поля, меню, списки, формы, + окна, токены и темы. +- В наборе — то, что нужно одной задаче. Набор собирает свои компоненты из + компонентов Framework. +- Наборы могут опираться друг на друга: например, админка показывает данные + компонентами набора `view`. Такие наборы страница называет все. + +## Что читать дальше + +- [Подключение набора](/ru/guide/sets/connect/) — одна строка на странице. +- [Версии и совместимость](/ru/guide/sets/versions/) — какой выпуск набора + подходит к вашему SIMAI Framework. +- [Лицензия](/ru/guide/sets/licence/) — какие наборы платные. +- [Имена компонентов](/ru/guide/sets/names/) — почему наборы не конфликтуют. diff --git a/content/ru/guide/sets/index.page.json b/content/ru/guide/sets/index.page.json new file mode 100644 index 00000000..104eca6c --- /dev/null +++ b/content/ru/guide/sets/index.page.json @@ -0,0 +1 @@ +{"schema": "docara.page.v1", "navigation": {"order": 75}} diff --git a/content/ru/guide/sets/licence.md b/content/ru/guide/sets/licence.md new file mode 100644 index 00000000..460111c1 --- /dev/null +++ b/content/ru/guide/sets/licence.md @@ -0,0 +1,33 @@ +--- +title: "Лицензия" +description: "Платные наборы (admin, view, chat, mail, editor, chart) идут под одной общей лицензией Pro; набор эффектов бесплатен и распространяется под лицензией SIMAI Framework." +--- + +# Лицензия + +У наборов две лицензии: одна общая лицензия Pro для всех платных наборов и +лицензия самого SIMAI Framework для бесплатных. Лицензию набора пишут на +главной странице его сайта и в описании выпуска. + +## Наборы Pro + +Наборы `admin`, `view`, `chat`, `mail`, `editor` и `chart` идут под одной +общей лицензией Pro. Отдельной лицензии на каждый набор нет. + +| Кто использует | Условия | +|:---|:---| +| Малый бизнес | бесплатно, PolyForm Small Business 1.0.0 | +| Некоммерческое использование | бесплатно, PolyForm Noncommercial 1.0.0 | +| Остальные | коммерческая лицензия SIMAI, выдаётся по запросу | + +## Бесплатные наборы + +Набор `effects` бесплатен и распространяется под лицензией SIMAI Framework — +Apache-2.0, как и сам SIMAI Framework. + +## Что бесплатно всегда + +Всё, что входит в SIMAI Framework, бесплатно и остаётся бесплатным: утилиты, +компоненты, смарт-компоненты, простой список и простая таблица. Платный набор +добавляет к ним компоненты для отдельной задачи, но не забирает из SIMAI +Framework ничего универсального. diff --git a/content/ru/guide/sets/licence.page.json b/content/ru/guide/sets/licence.page.json new file mode 100644 index 00000000..4e0ddcc5 --- /dev/null +++ b/content/ru/guide/sets/licence.page.json @@ -0,0 +1 @@ +{"schema": "docara.page.v1", "navigation": {"order": 30}} diff --git a/content/ru/guide/sets/names.md b/content/ru/guide/sets/names.md new file mode 100644 index 00000000..fa1942b0 --- /dev/null +++ b/content/ru/guide/sets/names.md @@ -0,0 +1,48 @@ +--- +title: "Имена компонентов" +description: "У всех наборов одна приставка sf-, имя компонента начинается с семейства его набора, а общий реестр имён следит, чтобы одно семейство не принадлежало двум наборам." +--- + +# Имена компонентов + +Компоненты всех наборов называются так же, как компоненты SIMAI Framework: +с приставкой `sf-`. Своей приставки у набора нет. Чтобы имена разных наборов +не совпадали, каждое имя начинается с семейства, а у каждого семейства один +владелец. + +## Как устроено имя + +Имя компонента строится как `sf-<семейство>-<часть>-<вариант>`; часть и +вариант могут отсутствовать. Семейство — первое слово после `sf-`: + +| Компонент | Семейство | Чьё | +|:---|:---|:---| +| `sf-effect` | `effect` | набор `effects` | +| `sf-chat-composer` | `chat` | набор `chat` | +| `sf-message-log` | `message` | набор `chat` | +| `sf-view-table` | `view` | набор `view` | +| `sf-button` | `button` | SIMAI Framework | + +По имени тега сразу видно, из какого набора компонент и какую строку +`data-sf-sets` нужно добавить на страницу. + +## Общий реестр имён + +- Все семейства записаны в один общий реестр имён SIMAI Framework. У каждого + семейства ровно один владелец: SIMAI Framework или один набор. +- Набор может занимать несколько семейств: например, `chat` владеет + семействами `chat` и `message`. +- Новый компонент в семействе, которое уже принадлежит набору, добавляют без + изменения реестра. Новое семейство набор сначала записывает в реестр. +- Проверка при выпуске не пропустит набор, если его семейство уже занято + другим набором или SIMAI Framework. + +Поэтому любые наборы можно подключать на одну страницу вместе: два набора +никогда не объявят компонент с одним и тем же именем. + +## Старые имена + +Когда компонент переименовывают, старое имя ещё какое-то время работает и +пишет в консоль подсказку с новым именем, как и у компонентов SIMAI Framework +(см. [Жизненный цикл изменений](/ru/guide/connection/change-lifecycle/)). Срок, +до которого действует старое имя, набор указывает сам. diff --git a/content/ru/guide/sets/names.page.json b/content/ru/guide/sets/names.page.json new file mode 100644 index 00000000..23d71cd6 --- /dev/null +++ b/content/ru/guide/sets/names.page.json @@ -0,0 +1 @@ +{"schema": "docara.page.v1", "navigation": {"order": 40}} diff --git a/content/ru/guide/sets/section.json b/content/ru/guide/sets/section.json new file mode 100644 index 00000000..41fe8cfa --- /dev/null +++ b/content/ru/guide/sets/section.json @@ -0,0 +1 @@ +{"schema": "docara.section.v1", "title": "Наборы компонентов", "navigation": {"order": 75}} diff --git a/content/ru/guide/sets/versions.md b/content/ru/guide/sets/versions.md new file mode 100644 index 00000000..ac379646 --- /dev/null +++ b/content/ru/guide/sets/versions.md @@ -0,0 +1,69 @@ +--- +title: "Версии и совместимость" +description: "Каждый выпуск набора собран поверх определённого SIMAI Framework и записан в общий каталог выпусков @simai-studio/sets; по нему Loader выбирает выпуск, подходящий к SIMAI Framework на странице." +--- + +# Версии и совместимость + +Набор выпускается отдельно от SIMAI Framework и со своей версией. Каждый +выпуск набора знает, какой SIMAI Framework ему нужен, и записан в общий +каталог выпусков. По этому каталогу Loader подбирает к странице подходящий +выпуск. + +## Где лежат выпуски + +- Каждый набор публикуется в npm как `@simai-studio/<набор>`, например + `@simai-studio/effects`. Файлы выпуска лежат на jsDelivr по адресу + `https://cdn.jsdelivr.net/npm/@simai-studio/<набор>@<версия>/dist/smart/`. +- Все выпуски всех наборов перечислены в одном каталоге — пакете npm + `@simai-studio/sets`. Его пополняет только выпуск набора, вручную каталог не + правят, а записанный выпуск не меняется. + +## Какой SIMAI Framework нужен набору + +У каждого выпуска набора в каталоге записаны: + +- версия набора; +- выпуск SIMAI Framework, на котором набор собран и проверен; +- самая младшая версия ядра (`core.runtime`), с которой набор работает, + например `>=1.25.0`; +- другие наборы, без которых он не работает; +- контрольные суммы архива выпуска, по которым его можно проверить. + +Каталог лежит по адресу +`https://cdn.jsdelivr.net/npm/@simai-studio/sets@1/index.json`. Запись о +выпуске выглядит так: + +```json +{ + "set": "effects", + "release": "effects-ad9823f83a56", + "version": "1.0.0", + "framework": { + "core_runtime": ">=1.25.0", + "pair": "ui-eea8c0a97cc7" + }, + "requires_sets": [], + "published_on": "2026-11-03" +} +``` + +В записи есть и другие поля (ревизия исходников, контрольные суммы); здесь они +опущены. + +Выпуск набора работает на своём SIMAI Framework и на всех более новых. Когда +страница называет набор без версии, Loader берёт из каталога самый новый +выпуск этого набора, которому хватает ядра на странице. Если страница +работает на более старом SIMAI Framework, чем нужен набору, такой выпуск +пропускается. + +## Как обновлять + +- Без версии в `data-sf-sets` страница получает новый выпуск набора сразу + после его публикации. Это удобно для черновиков и демонстраций. +- В рабочем проекте версию набора закрепляют (`data-sf-sets="effects@1.0.0"`) + и записывают рядом с выпуском SIMAI Framework в файл блокировки проекта, как + описано в разделе [Версии](/ru/guide/connection/versions/). +- Переходя на новый SIMAI Framework, проверяют, что закреплённые наборы ему + подходят; переходя на новый выпуск набора — что ему хватает вашего SIMAI + Framework. diff --git a/content/ru/guide/sets/versions.page.json b/content/ru/guide/sets/versions.page.json new file mode 100644 index 00000000..12cb21b4 --- /dev/null +++ b/content/ru/guide/sets/versions.page.json @@ -0,0 +1 @@ +{"schema": "docara.page.v1", "navigation": {"order": 20}}