Skip to content

Latest commit

 

History

History
75 lines (46 loc) · 9.21 KB

demands.md

File metadata and controls

75 lines (46 loc) · 9.21 KB

Потребитель - это приложение, в которое встраивается виджет.

Есть 4 вида требований:

  1. Принципиальные (обязательные);
  2. Непринципиальные (снимаемые);
  3. Ограничения предлагаемого схемой либо платформой при использовании рекомендованного фронтового API виджета;
  4. Дополнительные ограничения, которое разработчик виджета установил, выбрав определенный формат фронтового API.

Принципиальные

Принципиальные требования нельзя будет снять в будущем.

Обязательное требование к потребителю одно. В браузере пользователей потребителя должна быть поддержка:

  1. es6-module-dynamic-import;
  2. import.meta.

Это требует браузеров Chrome 64 или Firefox 67.

Windows XP и Internet Explorer 11 не поддерживаются.

Это ограничение принципиальное, на нем основана вся схема, и мы его не снимем. Теоретически можно полифилами версию Chrome понизить до 61, но делать мы это не планируем (слишком сложный и инвазивный полифил, требующий специального транспайлинга, а пара версий Chrome этого не стоит).

Непринципиальные требования

Непринципиальные требования являются следствиями текущего состояния кода Платформы или кода связанных библиотек и, при необходимости, могут быть ослаблены или сняты полностью, но это потребует дополнительной разработки. И хотя такая разработка не является сложной, необходимость их реализации на первый взгляд кажется скорее вредной чем полезной. При необходимости готовы рассказать как простым образом реализовать эти требования у потребителя.

Текущие непринципиальные требования обусловлены форматом npm-loader. Список требований:

  1. Транспайлер потребителя должен преобразовывать ESNext внутри npm-пакетов платформы в target браузеров потребителя (например, в ES2019). Loader-builder, operation-result, npm-loader, widget-consumer-react-utils и другие библиотеки, подключаемые потребителю, cобираются под ESNext. CRA и Vite такие трансформации делает автоматически. Если у потребителя настроен голый webpack и в нем исключен node_modules из ts-loader или babel, то перечисленные npm-пакеты нужно исключить из исключения.

Ограничение не планируем снимать без явной потребности.

  1. Возможность подключения npm-пакетов с помощью пакетного менеджера и их сборка бандлером во фронтовом проекте потребителя.

Это ограничение актуально только, если виджет переиспользует зависимости потребителя. Иначе можно раздавать нативно в браузер без бандлера.

  1. У потребителей в сборщике и TypeScript должна быть поддержка файлов, интерпретируемыхкак честные ES-модули. Это значит: а. Версия TypeScript не меньше 4.7. б. В tsconfig.json значения (module и moduleResolution) должно быть равно (Node16, Node16), (NodeNext, NodeNext), (ES2020 или выше, bundler) или (preserve, bundler); Остальные moduleResolution не поддерживаются (classic устарел, node не рекомендуются к использованию разработчиками TypeScript); Другие варанты module не поддерживаются выбранным moduleResolution. в. "type": "module" в package.json, либо динамический импорт mts(mjs)-файлов с помощью сборщика (не в рантайме). В Vite это нативно поддерживается, webpack требует версии 5.44 или выше (но это не точно).

Ограничение можно снять, если переведем генерацию npm-loader в dual-build esm и commonjs в режиме Node16. В таком режиме уже собирается operation-result, loader-builder и widget-consumer-react-utils.

Полифилы

Пользователям потребителя потребуется или актуальная версия браузера или подключенный в потребителе полифил:

  • Chrome 66 или подключенный полифил abortcontroller-polyfil.

  • Chrome 73 или Firefox 101 или подключенный полифил construct-style-sheets;. Большинство других полифилов может быть добавлено разработчиком виджета внутри виджета самостоятельно без влияния на потребилей. Перечисленные полифилы - исключение, так как:

  • Используются библиотеками загружающими виджет;

  • Вляют непросредственно на рендер, который производится в DOM потребителя.

Требования API по-умолчанию

В зависимости от API, которое выберет разработчик виджета, могут появиться дополнительные требования. Если разработчик выберет API, которое мы предлагаем использовать по-умолчанию (двух-этапная инициализация: сначала получение фронтового API модуля виджета с целью кеширования, потом рендер), то будет необходимо научиться:

  1. Дожидаться Promise (все функции в API асинхронные).
  2. Обрабатывать ошибки с помощью OperationResult (стандартное фронтовое API никогда не выкидывает исключения).
  3. Вызывать dispose по завершении работы с модулем виджета или когда необходимо скрыть результат отрисовки.
  4. Кешировать инициализированное API-виджета (хоть в window), таким образом чтобы на все рендеры использовали создаваемое один раз API (синглтон).
  5. Управлять жизненным циклом HTMLElement-контейнера, в котором виджет будет отрисовываться (например, статический тег div в html или ref в react). Для проектов с React есть компонент, решающий эту задачу полностью.

Если разработчик виджета сделает другое тривиальное API (не предлагаемое по-умолчанию), то потребителю не потребуется этому учиться. Например, если виджет сразу после загрузки сам добавляет HTMLElement на страницу и в нем же отрисовывается (как виджет поддержка), то поддержка пунктов выше у потребителя не потребуется.

Т.е. схема и Платформа не ставит такие ограничения, но дает рекомендации из которых они следуют.

Требования конкретного виджета

Также в зависимости от API, выбранного разработчиком виджета, могут появиться иные требования. Например:

  1. Обязательные аргументы для создания или использования API. Например, ClientID или OrganizationId.
  2. Требования к роутингу и управлению URL.