@smartex.com/modules-utils 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,302 @@
+# @smartex/modules-utils
+
+Утилиты для создания, монтирования и управления жизненным циклом ES-модулей в рамках основного SPA-приложения.
+
+Библиотека предоставляет два независимых набора инструментов:
+
+- **base** — для виджет-модулей общего назначения (карточки, формы, информационные блоки).
+- **survey** — для модулей опросов с полным управлением контекстом, историей навигации и ответами.
+
+## Установка
+
+```bash
+npm install @smartex/modules-utils
+```
+
+### Peer-зависимости
+
+Библиотека ожидает, что в проекте установлены:
+
+```bash
+npm install react react-dom dayjs @smartex.com/ctx
+```
+
+## Виджет-модули (`base`)
+
+### Использование
+
+Виджет-модуль — это React-компонент, который принимает `ModuleProps<E>`, где `E` — тип внешних данных, специфичных для конкретного модуля.
+
+Определите компонент:
+
+```tsx
+// participant-info.tsx
+import type { ModuleProps } from '@smartex/modules-utils/base';
+
+interface ExternalData {
+  participantId: string;
+  callHash: string;
+}
+
+export const ParticipantInfo = ({ token, externalData }: ModuleProps<ExternalData>) => {
+  return <div>{externalData?.participantId}</div>;
+};
+```
+
+Экспортируйте модуль через контроллер:
+
+```tsx
+// index.tsx
+import { createModuleController } from '@smartex/modules-utils/base';
+import { ParticipantInfo } from './participant-info';
+
+const moduleController = createModuleController(ParticipantInfo);
+
+export default moduleController;
+```
+
+Основное приложение монтирует модуль в DOM:
+
+```ts
+const mod = await loadModule('participant-info');
+mod.mount('target-element-id', {
+  token: '...',
+  apiConfig: { services: '...', externalApi: '...' },
+  externalData: { participantId: '123', callHash: 'abc' },
+});
+
+// При необходимости:
+mod.unmount();
+```
+
+### API
+
+#### `createModuleController<E>(Module)`
+
+Создаёт контроллер с методами `mount` и `unmount`. Тип `E` (внешние данные) выводится автоматически из типа пропсов компонента.
+
+#### `ModuleProps<T>`
+
+| Поле           | Тип                                        | Обязательное | Описание                         |
+| -------------- | ------------------------------------------- | ------------ | -------------------------------- |
+| `token`        | `string`                                    | да           | Токен авторизации                |
+| `lang`         | `'ru' \| 'kz' \| 'en'`                     | нет          | Язык интерфейса                  |
+| `theme`        | `string`                                    | нет          | Тема оформления                  |
+| `externalData` | `T`                                         | нет          | Внешние данные для модуля        |
+| `apiConfig`    | `{ services: string; externalApi: string }` | да           | Конфигурация API                 |
+| `onSuccess`    | `() => void`                                | нет          | Callback при успешном завершении |
+| `onError`      | `(errors: string[]) => void`                | нет          | Callback при ошибке              |
+
+## Модули опросов (`survey`)
+
+Модули опросов используют фабричный паттерн. Библиотека предоставляет headless-обёртку (логика без UI), а проект определяет компонент-layout (отображение).
+
+### Настройка в проекте
+
+#### 1. Определите схему контекста
+
+```ts
+// schema.ts
+export const surveyCtxSchema = {
+  token: '',
+  user: { code: 0, name: '', role: { code: 0, name: '' }, companyCode: 0 },
+  session: { code: 0, id: '' },
+  lang: '',
+  theme: '',
+};
+```
+
+#### 2. Объявите глобальный тип `ctx`
+
+```ts
+// ctx.d.ts
+import type { SurveyCtxStore } from '@smartex/modules-utils/survey';
+import type { surveyCtxSchema } from './schema';
+
+declare global {
+  interface Window {
+    ctx: SurveyCtxStore<typeof surveyCtxSchema>;
+  }
+  var ctx: SurveyCtxStore<typeof surveyCtxSchema>;
+}
+```
+
+#### 3. Определите тип внешних данных
+
+```ts
+// types.ts
+export interface SurveyExternalData {
+  user: {
+    code: number;
+    name: string;
+    role: { code: number; name: string };
+    companyCode: number;
+  };
+  session: { code: number; id: string };
+}
+```
+
+#### 4. Создайте layout-компонент
+
+Layout получает `mountProps` (данные вопроса, язык), `surveyProps` (обработчики: `onSetAnswer`, `goPrev` и т.д.) и `children` (сам модуль):
+
+```tsx
+// survey-layout.tsx
+import type { ReactNode } from 'react';
+import type { SurveyMountProps, SurveyComponentProps } from '@smartex/modules-utils/survey';
+
+interface SurveyLayoutProps {
+  mountProps: SurveyMountProps;
+  surveyProps: SurveyComponentProps;
+  children: ReactNode;
+}
+
+export const SurveyLayout = ({ mountProps, surveyProps, children }: SurveyLayoutProps) => {
+  const lang = mountProps.lang ?? 'ru';
+
+  return (
+    <div>
+      <h1>{mountProps.question.text[lang]}</h1>
+      <div>{children}</div>
+      {!mountProps.question.isPrevStepDisabled && (
+        <button onClick={surveyProps.goPrev}>Назад</button>
+      )}
+    </div>
+  );
+};
+```
+
+#### 5. Сконфигурируйте фабрику контроллера
+
+Выполняется один раз. Все модули опросов импортируют результат:
+
+```ts
+// survey-module-controller.ts
+import { createSurveyModuleControllerFactory } from '@smartex/modules-utils/survey';
+import { SurveyLayout } from './survey-layout';
+import { surveyCtxSchema } from './schema';
+import type { SurveyExternalData } from './types';
+
+export const createSurveyModuleController =
+  createSurveyModuleControllerFactory<SurveyExternalData>(SurveyLayout, {
+    schema: surveyCtxSchema,
+    defaultLang: 'ru',
+    logicScreenTypes: ['DYNAMIC_ROUTING'],
+  });
+```
+
+### Создание модуля опроса
+
+Модуль получает `SurveyComponentProps` — набор пропсов, подготовленных headless-обёрткой:
+
+```tsx
+// list-selection.tsx
+import type { SurveyComponentProps } from '@smartex/modules-utils/survey';
+
+export const ListSelection = ({ question, onSetAnswer, goNext }: SurveyComponentProps) => {
+  const handleSelect = (answerCode: number, nextQuestion: number) => {
+    onSetAnswer(answerCode, null);
+    goNext(nextQuestion);
+  };
+
+  return (
+    <ul>
+      {question.answers.map((answer) => (
+        <li key={answer.code} onClick={() => handleSelect(answer.code, answer.nextQuestion!)}>
+          {answer.text.ru}
+        </li>
+      ))}
+    </ul>
+  );
+};
+```
+
+Экспорт через контроллер:
+
+```tsx
+// index.tsx
+import { createSurveyModuleController } from '@/modules/_lib/survey/survey-module-controller';
+import { ListSelection } from './list-selection';
+
+const moduleController = createSurveyModuleController(ListSelection);
+
+export default moduleController;
+```
+
+### API
+
+#### `createSurveyModuleControllerFactory<E>(Layout, config)`
+
+Фабрика, возвращающая функцию `createSurveyModuleController`.
+
+| Параметр | Тип                        | Описание                                         |
+| -------- | -------------------------- | ------------------------------------------------ |
+| `Layout` | `SurveyLayoutComponent`    | React-компонент для отображения обёртки модуля    |
+| `config` | `SurveyModuleWrapperConfig`| Конфигурация (см. ниже)                          |
+
+#### `SurveyModuleWrapperConfig`
+
+| Поле               | Тип                      | Описание                                                     |
+| ------------------ | ------------------------ | ------------------------------------------------------------ |
+| `schema`           | `Record<string, unknown>` | Схема контекста для `@smartex.com/ctx`                       |
+| `defaultLang`      | `'ru' \| 'kz' \| 'en'`   | Язык по умолчанию                                            |
+| `logicScreenTypes` | `string[]`               | Типы вопросов-экранов, пропускаемых при навигации назад      |
+
+#### `SurveyComponentProps`
+
+Пропсы, которые получает каждый модуль опроса:
+
+| Поле             | Тип                                                  | Описание                                    |
+| ---------------- | ---------------------------------------------------- | ------------------------------------------- |
+| `question`       | `SurveyQuestion`                                     | Данные текущего вопроса                     |
+| `getSettings`    | `<T>(key?: string) => [T \| null, string \| null]`   | Получение настроек вопроса                  |
+| `onSetAnswer`    | `(answer: number \| number[], value: unknown) => void`| Сохранение ответа                          |
+| `goNext`         | `(questionCode: number) => void`                     | Переход к следующему вопросу                |
+| `goPrev`         | `() => void`                                         | Переход к предыдущему вопросу               |
+| `onSuccess`      | `() => void`                                         | Сигнал успешного завершения                 |
+| `onError`        | `(errors: string[]) => void`                         | Сигнал ошибки                               |
+| `onSurveyFinish` | `() => void`                                         | Завершение опроса                           |
+
+#### `SurveyLayoutComponent`
+
+Тип layout-компонента, ожидаемый фабрикой:
+
+```ts
+type SurveyLayoutComponent = ComponentType<{
+  mountProps: SurveyMountProps;
+  surveyProps: SurveyComponentProps;
+  children: ReactNode;
+}>;
+```
+
+## Инициализация контекста
+
+Headless-обёртка автоматически управляет жизненным циклом `ctx`:
+
+- Создаёт контекст на первом вопросе опроса.
+- Записывает `token`, `lang`, `theme` из пропсов монтирования.
+- Итерирует `externalData` и записывает каждый ключ через `ctx.set()`. Ключи `externalData` должны совпадать с ключами схемы — `ctx` валидирует их в рантайме.
+- Уничтожает контекст при навигации назад с первого вопроса.
+
+Проект не вызывает методы `ctx` напрямую при настройке — только модули используют глобальный `ctx` в своей логике.
+
+## Архитектура
+
+```
+Основное приложение
+  └── module.mount(id, props)         // знает только пропсы монтирования
+        │
+        ▼
+Контроллер модуля                     // mount / unmount
+  └── createRoot + render
+        │
+        ├── SurveyModuleWrapper       // библиотека: ctx, история, ответы (без UI)
+        │     └── children(injectedProps)
+        │           │
+        │           ▼
+        ├── SurveyLayout              // проект: заголовок, кнопки, стили
+        │     └── children
+        │           │
+        │           ▼
+        └── Module                    // компонент модуля (SurveyComponentProps)
+```

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@smartex.com/modules-utils",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "exports": {
     "./base": {
       "types": "./dist/base/index.d.ts",