@alfalab/bridge-to-native 1.3.2-beta.531b429 → 1.3.2-beta.9b534a8

package/client/bridge-to-native.d.ts

@@ -147,15 +147,8 @@ export declare class BridgeToNative {
      * экзепляру B2N следующей страницы текущего WA (в случае multi-page application).
      *
      * ВАЖНО!
-     *
-     * Не поддерживаются такие сценарии:
-     *
-     * 1. Микс client-side навигации и server-side навигации в рамках одного WA.
-     *  т.е. одно WA должно использовать либо только `navigateClientSide`, либо только `navigateServerSide`.
-     * 2. Старт в WA 1 → переход к WA 2 → переход к WA 1,
-     *  т.е. при использовании server-side навигации, история переходов разных WA не должна смешиваться.
-     *
-     * Снять эти ограничения возможно, но нужны доработки.
+     * `goBackAFewStepsClientSide` можно использовать только в рамках истории по SPA WA! Движение назад
+     * server-side переходом на несколько шагов не поддерживается.
      *
      * @param url URL для перехода внутри WA server-side навигацией.
      * @param nativeTitle Текст заголовка, для «нативной» части WV, пустая строка — отсутствие заголовка.
@@ -206,8 +199,9 @@ export declare class BridgeToNative {
     /**
      * Для перезагрузки страницы необходимо использовать этот метод.
      * Иначе синхронизация состояния с NA будет потеряна.
-     * По умолчанию метод сам делает location.reload,
-     * но с помощью аргумента можно отключить этот вызов
+     *
+     * @param skipReload По умолчанию метод сам делает `location.reload`,
+     *  но с помощью аргумента можно отключить этот вызов, если нужно.
      */
     reload(skipReload?: boolean): void;
     /**

package/client/bridge-to-native.js

@@ -181,15 +181,8 @@ class BridgeToNative {
      * экзепляру B2N следующей страницы текущего WA (в случае multi-page application).
      *
      * ВАЖНО!
-     *
-     * Не поддерживаются такие сценарии:
-     *
-     * 1. Микс client-side навигации и server-side навигации в рамках одного WA.
-     *  т.е. одно WA должно использовать либо только `navigateClientSide`, либо только `navigateServerSide`.
-     * 2. Старт в WA 1 → переход к WA 2 → переход к WA 1,
-     *  т.е. при использовании server-side навигации, история переходов разных WA не должна смешиваться.
-     *
-     * Снять эти ограничения возможно, но нужны доработки.
+     * `goBackAFewStepsClientSide` можно использовать только в рамках истории по SPA WA! Движение назад
+     * server-side переходом на несколько шагов не поддерживается.
      *
      * @param url URL для перехода внутри WA server-side навигацией.
      * @param nativeTitle Текст заголовка, для «нативной» части WV, пустая строка — отсутствие заголовка.
@@ -248,8 +241,9 @@ class BridgeToNative {
     /**
      * Для перезагрузки страницы необходимо использовать этот метод.
      * Иначе синхронизация состояния с NA будет потеряна.
-     * По умолчанию метод сам делает location.reload,
-     * но с помощью аргумента можно отключить этот вызов
+     *
+     * @param skipReload По умолчанию метод сам делает `location.reload`,
+     *  но с помощью аргумента можно отключить этот вызов, если нужно.
      */
     reload(skipReload) {
         this.nativeNavigationAndTitleService.reload(skipReload);

package/client/services-and-utils/native-navigation-and-title-service.d.ts

@@ -1,9 +1,11 @@
- 
 import { type BrowserHistoryApiWrappers, type HistoryPushStateParams, type LocationAssignParam, type LogError } from '../types';
 import { type NativeParamsService } from './native-params-service';
 /**
  * Сервис, отвечающий за взаимодействие WA с WV компонентами NA —
  * «заголовком» и кнопкой «назад».
+ *
+ * Подробное описание сценариев навигации и логики восстановления состояния при hard навигации
+ * см. в документе {@link ./NAVIGATION_SCENARIOS.md}.
  */
 export declare class NativeNavigationAndTitleService {
     private nativeParamsService;
@@ -34,14 +36,23 @@ export declare class NativeNavigationAndTitleService {
      * после нажатия на кнопку «Назад» в NA, вызова `history.back()` и `history.go(-x)`.
      */
     private handleClientSideNavigationBack;
-    private static hasSavedHistoryStack;
+    private hasSavedHistoryStack;
     /**
-     * Инициализирует `nativeHistoryStack`, учитывая варианты:
-     * - Инициализация при открытии WV (Сценарий 1);
-     * - Инициализация при server-side навигации в рамках одной WV-сессии (Сценарий 2);
-     * - Инициализация при server-side переходе «назад» по истории (Сценарий 3).
+     * Инициализирует `nativeHistoryStack`.
+     *
+     * Подробное описание каждого сценария см. в {@link ./NAVIGATION_SCENARIOS.md}.
      */
     private initializeNativeHistoryStack;
+    private initializeForNewOrigin;
+    private initializeForForward;
+    private initializeFromBackwardOrReload;
+    private stackContainsCrossOriginMarker;
+    private truncateToLastCrossOriginMarker;
+    /**
+     * Читает и парсит `nativeHistoryStack` из SessionStorage.
+     * При ошибке чтения или парсинга логирует через `logError` и пробрасывает исключение.
+     */
+    private readSavedHistoryStack;
     /**
      * Подготавливает ссылку для корректного перехода server-side навигацией.
      *
@@ -50,17 +61,8 @@ export declare class NativeNavigationAndTitleService {
      * экзепляра B2N следующей страницы текущего WA
      */
     private prepareExternalLinkBeforeOpen;
-    private static shouldInitializeFromNextPageId;
-    /**
-     * Читает сохраннённый в sessionStorage `nativeHistoryStack`,
-     * снова сохраняет его в sessionStorage, уменьшая список на одну запись,
-     * на случай, если будет дальнейший переход назад server-side навигацией.
-     *
-     * @returns Актуальное состояние `nativeHistoryStack` из sessionStorage.
-     */
-    private readAndUpdateNativeHistoryStackSessionStorage;
     /**
-     * Сохранение состояния связи текущего WA с NA при server-side навигации в sessionStorage.
+     * Сохраняет `nativeHistoryStack` в SessionStorage.
      */
     private saveNativeHistoryStack;
     /**

package/client/services-and-utils/native-navigation-and-title-service.js

@@ -1,5 +1,5 @@
 "use strict";
-/* eslint max-lines: ["error", {"skipComments": true}] */ // Много комментариев.
+/* eslint max-lines: ["error", {"max": 400, "skipComments": true}] */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NativeNavigationAndTitleService = void 0;
 const query_and_headers_keys_1 = require("../../query-and-headers-keys");
@@ -7,6 +7,9 @@ const close_webview_util_1 = require("./close-webview-util");
 /**
  * Сервис, отвечающий за взаимодействие WA с WV компонентами NA —
  * «заголовком» и кнопкой «назад».
+ *
+ * Подробное описание сценариев навигации и логики восстановления состояния при hard навигации
+ * см. в документе {@link ./NAVIGATION_SCENARIOS.md}.
  */
 class NativeNavigationAndTitleService {
     constructor(nativeParamsService, browserHistoryApiWrappers, logError) {
@@ -64,20 +67,26 @@ class NativeNavigationAndTitleService {
             window.history.pushState(state, '', url);
         }
         this.nativeHistoryStack.push(nativeTitle);
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
     navigateServerSide(link, nativeTitle = '') {
         const url = link instanceof URL ? link : new URL(link);
+        const isCrossOrigin = url.origin !== window.location.origin;
+        if (isCrossOrigin) {
+            this.nativeHistoryStack.push(2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */);
+        }
+        else {
+            this.nativeHistoryStack.push(nativeTitle);
+        }
         if (nativeTitle) {
             url.searchParams.set(query_and_headers_keys_1.QUERY_B2N_TITLE, nativeTitle);
         }
-        // TODO: Предыдущая реализация на iOS открывала новое WV. Возможно, что-то плохо работало,
-        // обязательно протестировать.
         this.saveNativeHistoryStack();
         window.location.assign(this.prepareExternalLinkBeforeOpen(url));
     }
     reload(skipReload = false) {
-        this.nativeHistoryStack.push(1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */); // небольшой костыль, чтобы переиспользовать server-side сценарий
+        this.nativeHistoryStack.push(1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */);
         this.saveNativeHistoryStack();
         // информация для серверной стороны B2N, что происходит `reload` и парсить запрос на предмет NA параметров не нужно (в нем их скорее всего не будет)
         document.cookie = `${query_and_headers_keys_1.COOKIE_KEY_BRIDGE_TO_NATIVE_RELOAD}=true; Path=/`;
@@ -87,10 +96,12 @@ class NativeNavigationAndTitleService {
     }
     setInitialView(nativeTitle = '') {
         this.nativeHistoryStack = [nativeTitle];
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
     setTitle(nativeTitle) {
         this.nativeHistoryStack[this.nativeHistoryStack.length - 1] = nativeTitle;
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
     /**
@@ -122,46 +133,144 @@ class NativeNavigationAndTitleService {
             (0, close_webview_util_1.closeWebviewUtil)();
             return;
         }
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
-    static hasSavedHistoryStack() {
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    hasSavedHistoryStack() {
         return sessionStorage.getItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK) !== null;
     }
     /**
-     * Инициализирует `nativeHistoryStack`, учитывая варианты:
-     * - Инициализация при открытии WV (Сценарий 1);
-     * - Инициализация при server-side навигации в рамках одной WV-сессии (Сценарий 2);
-     * - Инициализация при server-side переходе «назад» по истории (Сценарий 3).
+     * Инициализирует `nativeHistoryStack`.
+     *
+     * Подробное описание каждого сценария см. в {@link ./NAVIGATION_SCENARIOS.md}.
      */
     initializeNativeHistoryStack() {
         const { nextPageId, title } = this.nativeParamsService;
-        if (nextPageId &&
-            NativeNavigationAndTitleService.shouldInitializeFromNextPageId(nextPageId)) {
-            // Сценарий 2 – `nextPageId` ставит метод `this.navigateServerSide`,
-            // т.е. это инициализация сразу после перехода server-side навигацией.
-            // Если в sessionStorage уже есть стек, используем `nextPageId` только для прямого
-            // перехода "вперёд", когда он на 1 больше сохранённой глубины истории.
-            this.nativeHistoryStack = new Array(nextPageId).fill(0 /* NativeHistoryStackSpecialValues.ServerSideNavigationStub */);
-            this.nativeHistoryStack[this.nativeHistoryStack.length - 1] = title;
+        const hasSS = this.hasSavedHistoryStack();
+        console.log('-------');
+        console.log('Инициализируюсь');
+        if (nextPageId && !hasSS) {
+            // есть nextPageId + нет SS → на этом origin ранее не были.
+            console.log('есть nextPageId + нет SS → на этом origin ранее не были.');
+            this.nativeHistoryStack = this.initializeForNewOrigin(nextPageId, title);
         }
-        else if (NativeNavigationAndTitleService.hasSavedHistoryStack()) {
-            // Сценарий 3 - в sessionStorage есть сохранённый nativeHistoryStack,
-            // значит это инициализация сразу после перехода назад server-side навигацией,
-            // или инициализация после использования метода `reload`.
-            try {
-                this.nativeHistoryStack = this.readAndUpdateNativeHistoryStackSessionStorage();
-            }
-            catch (_a) {
-                this.nativeHistoryStack = [''];
-            }
+        else if (nextPageId && hasSS) {
+            // есть nextPageId + есть SS → forward навигация.
+            console.log('есть nextPageId + есть SS → forward навигация.');
+            this.nativeHistoryStack = this.initializeForForward(nextPageId, title);
+        }
+        else if (!nextPageId && hasSS) {
+            // нет nextPageId + есть SS → back-навигация или reload.
+            console.log('нет nextPageId + есть SS → back-навигация или reload.');
+            this.nativeHistoryStack = this.initializeFromBackwardOrReload(title);
         }
         else {
-            // Сценарий 1 - запись в sessionStorage ставит метод `this.navigateServerSide`,
-            // её нет, значит это инициализация сразу после открытия нового WV.
+            // нет nextPageId + нет SS → старт нового WV, назад идти некуда.
+            console.log('нет nextPageId + нет SS → старт нового WV, назад идти некуда.');
             this.nativeHistoryStack = [title];
         }
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    initializeForNewOrigin(nextPageId, title) {
+        const stack = new Array(nextPageId).fill(0 /* NativeHistoryStackSpecialValues.ServerSideNavigationStub */);
+        stack[stack.length - 1] = title;
+        console.log('nextPageId', nextPageId);
+        console.log('newStack', stack);
+        return stack;
+    }
+    initializeForForward(nextPageId, title) {
+        try {
+            const savedStack = this.readSavedHistoryStack();
+            const lastSaved = savedStack[savedStack.length - 1];
+            if (lastSaved === 2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */ &&
+                savedStack.length < nextPageId) {
+                const stack = new Array(nextPageId).fill(0 /* NativeHistoryStackSpecialValues.ServerSideNavigationStub */);
+                for (let i = 0; i < savedStack.length; i++) {
+                    stack[i] = savedStack[i];
+                }
+                stack[stack.length - 1] = title;
+                console.log('nextPageId', nextPageId);
+                console.log('newStack', stack);
+                return stack;
+            }
+            if (savedStack.length === nextPageId) {
+                savedStack[savedStack.length - 1] = title;
+                console.log('nextPageId', nextPageId);
+                console.log('newStack', savedStack);
+                return savedStack;
+            }
+            return this.initializeForNewOrigin(nextPageId, title);
+        }
+        catch (_a) {
+            return this.initializeForNewOrigin(nextPageId, title);
+        }
+    }
+    initializeFromBackwardOrReload(title) {
+        try {
+            const savedStack = this.readSavedHistoryStack();
+            const lastEntry = savedStack[savedStack.length - 1];
+            if (lastEntry === 1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */) {
+                savedStack.pop();
+                if (savedStack.length === 0) {
+                    console.log('newStack', [title]);
+                    return [title];
+                }
+                console.log('newStack', savedStack);
+                return savedStack;
+            }
+            if (this.stackContainsCrossOriginMarker(savedStack)) {
+                console.log('newStack', this.truncateToLastCrossOriginMarker(savedStack));
+                return this.truncateToLastCrossOriginMarker(savedStack);
+            }
+            savedStack.pop();
+            if (savedStack.length === 0) {
+                console.log('newStack', [title]);
+                return [title];
+            }
+            console.log('newStack', savedStack);
+            return savedStack;
+        }
+        catch (_a) {
+            return [title];
+        }
+    }
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    stackContainsCrossOriginMarker(stack) {
+        return stack.find((el) => el === 2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */);
+    }
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    truncateToLastCrossOriginMarker(stack) {
+        for (let i = stack.length - 1; i >= 0; i--) {
+            if (stack[i] === 2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */) {
+                return stack.slice(0, i);
+            }
+        }
+        return stack;
+    }
+    /**
+     * Читает и парсит `nativeHistoryStack` из SessionStorage.
+     * При ошибке чтения или парсинга логирует через `logError` и пробрасывает исключение.
+     */
+    readSavedHistoryStack() {
+        const serialized = sessionStorage.getItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK);
+        try {
+            if (!serialized) {
+                throw new Error(`${query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK} sessionStorage expected not to be null`);
+            }
+            console.log('serializedStack', serialized);
+            return JSON.parse(serialized);
+        }
+        catch (e) {
+            if (this.logError) {
+                this.logError(`Клиентский код B2N не смог получить ${query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK} из sessionStorage
+                    Могут возникнуть проблемы с кнопкой «Назад» в NA.`, e);
+            }
+            throw e;
+        }
+    }
     /**
      * Подготавливает ссылку для корректного перехода server-side навигацией.
      *
@@ -183,61 +292,18 @@ class NativeNavigationAndTitleService {
         // Таким образом гарантируется, что версию приложения будет видеть следующее WA
         // (заголовок `app-version` может отсутствовать при server-side переходах).
         modifiedUrl.searchParams.set(query_and_headers_keys_1.QUERY_NATIVE_IOS_APPVERSION, appVersion);
-        modifiedUrl.searchParams.set(query_and_headers_keys_1.QUERY_B2N_NEXT_PAGEID, (currentPageId + 1).toString());
+        modifiedUrl.searchParams.set(query_and_headers_keys_1.QUERY_B2N_NEXT_PAGEID, currentPageId.toString());
         return modifiedUrl;
     }
-    static shouldInitializeFromNextPageId(nextPageId) {
-        if (!NativeNavigationAndTitleService.hasSavedHistoryStack()) {
-            return true;
-        }
-        try {
-            const serializedNativeHistoryStack = sessionStorage.getItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK);
-            if (!serializedNativeHistoryStack) {
-                return true;
-            }
-            return (nextPageId ===
-                JSON.parse(serializedNativeHistoryStack).length +
-                    1);
-        }
-        catch (_a) {
-            return true;
-        }
-    }
-    /**
-     * Читает сохраннённый в sessionStorage `nativeHistoryStack`,
-     * снова сохраняет его в sessionStorage, уменьшая список на одну запись,
-     * на случай, если будет дальнейший переход назад server-side навигацией.
-     *
-     * @returns Актуальное состояние `nativeHistoryStack` из sessionStorage.
-     */
-    readAndUpdateNativeHistoryStackSessionStorage() {
-        try {
-            const serializedNativeHistoryStack = sessionStorage.getItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK);
-            if (!serializedNativeHistoryStack) {
-                throw new Error();
-            }
-            const nativeHistoryStack = JSON.parse(serializedNativeHistoryStack); // происходит внутри оператора `catch`, поэтому кастинг типа приемлем
-            const nativeHistoryStackToSerialize = nativeHistoryStack.slice(0, -1);
-            sessionStorage.setItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK, JSON.stringify(nativeHistoryStackToSerialize));
-            if (nativeHistoryStack[nativeHistoryStack.length - 1] ===
-                1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */) {
-                return nativeHistoryStack.slice(0, -1);
-            }
-            return nativeHistoryStack;
-        }
-        catch (e) {
-            if (this.logError) {
-                this.logError('Клиентский код B2N не смог восстановить `nativeHistoryStack` из sessionStorage. ' +
-                    'Могут возникнуть проблемы с кнопкой «Назад» в NA.', e);
-            }
-            throw new Error();
-        }
-    }
     /**
-     * Сохранение состояния связи текущего WA с NA при server-side навигации в sessionStorage.
+     * Сохраняет `nativeHistoryStack` в SessionStorage.
      */
     saveNativeHistoryStack() {
         const serializedNativeHistoryStack = JSON.stringify(this.nativeHistoryStack);
+        console.log('-------');
+        console.log('сохраняю стек');
+        console.log('стек', this.nativeHistoryStack);
+        console.log('сериализованный стек', serializedNativeHistoryStack);
         sessionStorage.setItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK, serializedNativeHistoryStack);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfalab/bridge-to-native",
-  "version": "1.3.2-beta.531b429",
+  "version": "1.3.2-beta.9b534a8",
   "license": "MIT",
   "description": "Утилита для удобной работы веб приложения внутри нативного приложения и коммуникации с ним.",
   "engines": {