Принципы

На этих принципах держится всё остальное руководство.

1. Единственный источник. Framework правится только в исходниках; поставки генерируются. Документация, справочники и машинные контракты выводятся из тех же исходников и сверяются с ними.

2. Выпуск и закрепление. Проект работает на конкретном выпуске Framework, а не на «последней версии». Обновление — осознанный переход на новый выпуск.

3. Предсказуемые изменения. Публичное имя не исчезает без предупреждения: каждое изменение, которое требует правки проекта, записывается в журнал изменений с датой удаления и проходит жизненный цикл, описанный в Жизненный цикл изменений и совместимость.

4. Одно правило на один вопрос. Одна лестница размеров, одни имена настроек, одно событие change для изменения значения у всех контролов, одни роли цвета. Исключение из правила считается дефектом, а не особенностью компонента.

5. Стандарты веба. Framework опирается на возможности браузера: CSS- переменные, каскадные слои, light-dark(), логические свойства для письма слева направо и справа налево, собственные HTML-элементы (Custom Elements), доступность по клавиатуре. Ни сборщик, ни npm проекту не нужны.

6. Машиночитаемые контракты. У Smart-компонента есть манифест, у изменений — журнал, у поставки — запись о выпуске, у макета — JSON-схема. Человек читает руководство; ИИ и проверки читают контракты. И то, и другое описывает одну и ту же правду.

7. Открытая основа. Framework — Core, Loader, утилиты, компоненты, Smart-компоненты, стандарты и порты — распространяется по лицензии Apache 2.0, в том числе для коммерческого использования. Лицензия не даёт права на имена SIMAI и SIMAI Framework. Компоненты пакета продукта распространяются по лицензии этого продукта (см. Пакеты компонентов продуктов). Сторонний код внутри поставки сохраняет свои лицензии.

8. Расширение пакетами, а не правкой ядра. Framework растёт за счёт пакетов, а не за счёт правки его ядра: одно ядро у всех проектов позволяет обновлять их централизованно. Ядро — Loader, основа Smart-компонентов, система языков — расширяется только через объявленные точки расширения:

   • регистрация пакета — SF.RuleLoader.registerPackage и объявление SF_BOOT_CONFIG.packages (см. Пакеты компонентов);
   • регистрация языка — SF.language.register и SF.language.registerAll (см. Свой язык и явный выбор языка);
   • выбор темы (см. Как выбирается тема на странице и Своя тема проекта);
   • реестр типов композиции (см. API сборки и отрисовки и Собственный тип).

   Расширяющий пакет Framework — пакет компонентов: набор Smart-компонентов владельца, который соответствует стандарту simai.component-package (см. Пакеты компонентов продуктов и Пакет компонентов (simai.component-package)). Пакет только добавляет к Framework: он не заменяет файлы Framework и не меняет его код на странице. Публичный API расширения — обещание совместимости: он меняется через журнал изменений (см. Жизненный цикл изменений и совместимость).