arui-scripts 15.8.2 → 15.10.0

package/docs/modules.md

@@ -337,8 +337,11 @@ export const MyAwesomeComponent = () => {
 Для решения конфликтов стилей вы можете попробовать перевести проект на css-modules, но это может быть довольно
 трудоемкой задачей, особенно если у вас уже есть большая кодовая база.
 
-Простое решение, которое предлагает arui-scripts - это использование другого типа модулей, основанного не
-на module-federation. Эти модули мы называем _compat_ модулями.
+arui-scripts предоставляет два решения для этой проблемы:
+- _compat_ модули
+- использование shadow dom
+
+## compat модули
 
 Суть метода заключается в том, что ко всем стилям модуля будет добавляться префикс, который позволит изолировать
 стили модуля от стилей приложения-потребителя.
@@ -431,7 +434,7 @@ Webpack module federation делает абсолютно то же самое,
 - **---** Нет встроенной изоляции стилей. Стили модуля будут применены к хост-приложению.
 - **---** Нет возможности использовать модуль в приложении, которое не использует webpack.
 
-Проблема изоляции стилей может быть решена с помощью [shadow dom](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM),
+Проблема изоляции стилей может быть решена с помощью [shadow dom](#shadow-dom),
 или с помощью css modules. Но это накладывает некоторые ограничения либо на поддерживаемые браузеры (shadow dom), либо на
 существующую кодовую базу (css modules должны использоваться везде, если у вас будет две версии arui-feather на странице - будет не очень приятно).
 
@@ -444,6 +447,50 @@ Webpack module federation делает абсолютно то же самое,
 вам в таком случае не грозят. Если же вы используете обычный css, или ваши библиотеки используют обычный css, то лучше
 использовать `compat` режим.
 
+## Shadow dom
+[Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) - это спецификация, которая позволяет
+создавать изолированные DOM-деревья, которые не будут влиять на DOM-дерево родительского элемента.
+
+arui-scripts предоставляет возможность использовать shadow dom для модулей. Для этого вам нужно:
+
+- На стороне модуля - использовать `arui-scripts` старше `15.9.2`.
+- На стороне потребителя - указать параметр `useShadowDom` в `useModuleMounter`:
+
+```tsx
+import {
+    createModuleLoader,
+    createModuleFetcher,
+    useModuleMounter,
+    MountableModule,
+} from '@alfalab/scripts-modules';
+
+const loader = createModuleLoader<MountableModule>({
+    hostAppId: 'bar-app',
+    moduleId: 'test',
+    getModuleResources: createModuleFetcher({
+        baseUrl: 'https://examle.com/foo-app',
+    }),
+});
+
+export const MyAwesomeComponent = () => {
+    const { loadingState, targetElementRef } = useModuleMounter({
+        loader,
+        useShadowDom: true, // !!!
+    });
+
+    return (
+        <div>
+            {loadingState === 'pending' && <div>pending...</div>}
+            {loadingState === 'rejected' && <div>Error</div>}
+            <div ref={targetElementRef} /> {/* сюда будет монтироваться модуль */}
+        </div>
+    );
+}
+```
+
+Этот режим работает как для _default_, так и для _compat_ модулей.
+Внутри targetElementRef будет создаваться shadowRoot, и модуль и его стили будут монтироваться в него.
+
 # Другие типы модулей
 
 Помимо создания монтируемых модулей, есть возможность создавать и другие типы модулей, более подходящие для некоторых вариантов использования.

package/docs/overrides.md

@@ -120,3 +120,62 @@ export default overrides;
 не боясь что это повлияет на другие конфигурации.
 
 Созданная таким образом конфигурация будет шарить с оригинальной конфигурацией только плагин для формирования assets-manifest'а.
+
+### Переопределение плагинов или загрузчиков для конфигураций webpack
+Иногда может понадобиться возможность поменять конфигурацию конкретного загрузчика или плагина, для этого в `webpackClient`, `webpackClientDev`, `webpackServer` и `webpackServerDev` третьим параметром можно получить хелпер-функции `findLoader` и `findPlugin`:
+```ts
+import type { OverrideFile } from 'arui-scripts';
+
+const overrides: OverrideFile = {
+    webpackClient: (config, appConfig, { findLoader, findPlugin }) => {
+      // ...        
+    }
+};
+
+export default overrides;
+```
+- `findLoader` - помогает найти загрузчик для переопределения. Функция возвращает ссылку, поэтому вы можете спокойно мутировать этот результат и обходиться без создания нового объекта через spread-оператор. В качестве аргументов принимает `config` и `testRule`, по которому будет искаться загрузчик. Пример:
+```ts
+import type { OverrideFile } from 'arui-scripts';
+
+const overrides: OverrideFile = {
+    webpackClient: (config, appConfig, { findLoader }) => {
+      const cssModulesLoader = findLoader(config, '/\\.module\\.css$/')
+      const currentCssLoader = cssModulesLoader.use.find((cssLoader) => {
+        return cssLoader.loader.includes('css-loader') && !cssLoader.loader.includes('postcss-loader')
+      })
+
+      currentCssLoader.options.modules = {
+        localIdentName: '[name]-[local]-[hash:base64:5]'
+      }
+
+      return config
+    }
+};
+
+export default overrides
+```
+- `findPlugin` - помогает найти плагин для переопределения. Функция так же возвращает ссылку. В качестве аргументов принимает `config` и название плагина. Все типизировано, поэтому название можете достать из автокомплита. для `webpackClient` и `webpackClientDev` из автокомплита будут приходить клиентские плагины, а для `webpackServer` и `webpackServerDev` серверные. Примеры:
+```ts
+import type { OverrideFile } from 'arui-scripts';
+
+const overrides: OverrideFile = {
+    webpackClient: (config, appConfig, { findPlugin }) => {
+      const [MiniCssExtractPlugin] = findPlugin(config, 'MiniCssExtractPlugin')
+
+      // возвращаемые плагины так же типизированы
+      MiniCssExtractPlugin.options.ignoreOrder = false
+
+      return config
+    },
+    webpackServerDev: (config, appConfig, { findPlugin }) => {
+      const [BannerPlugin] = findPlugin(config, 'BannerPlugin');
+
+      BannerPlugin.options.banner = 'unexpected error';
+
+      return config
+    }
+};
+
+export default overrides
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "arui-scripts",
-    "version": "15.8.2",
+    "version": "15.10.0",
     "main": "./build/index.js",
     "typings": "./build/index.d.ts",
     "license": "MPL-2.0",