chayns-api 3.0.1 → 3.1.0-beta.1

package/dist/types/utils/history/NavigationQueue.d.ts

@@ -0,0 +1,118 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import type { ChaynsHistoryActionResult, ChaynsHistoryNavigateOptions, ChaynsHistoryNavigationCommitOptions } from '../../types/history';
+export type NavOp = {
+    kind: 'setRoute';
+    layerId: string;
+    segments: string[];
+    opts: ChaynsHistoryNavigateOptions;
+    /** @internal Force a change notification even when segments appear unchanged (bootstrap via setSegmentCount). */
+    _notifyEvenIfUnchanged?: true;
+    /** @internal Notify subscribers without mutating the browser history (used for segment ownership/bootstrap updates). */
+    _skipCommit?: true;
+} | {
+    kind: 'setState';
+    layerId: string;
+    state: Record<string, unknown>;
+    opts: ChaynsHistoryNavigateOptions;
+} | {
+    kind: 'setParams';
+    layerId: string;
+    params: Record<string, string>;
+    opts: ChaynsHistoryNavigationCommitOptions;
+} | {
+    kind: 'setHash';
+    layerId: string;
+    hash: string;
+    opts: ChaynsHistoryNavigationCommitOptions;
+} | {
+    kind: 'setActiveChild';
+    layerId: string;
+    childId: string | null;
+    init?: {
+        route?: string[];
+        state?: Record<string, unknown>;
+    };
+} | {
+    kind: 'navigate';
+    layerId: string;
+    route?: string[];
+    state?: Record<string, unknown>;
+    params?: Record<string, string>;
+    hash?: string;
+    activeChild?: string | null;
+    activeChildInit?: {
+        route?: string[];
+        state?: Record<string, unknown>;
+    };
+    opts: ChaynsHistoryNavigationCommitOptions;
+} | {
+    kind: 'popstate';
+    rawState: unknown;
+    /**
+     * @internal Skips the block check pipeline for this popstate. Used when
+     * the popstate was triggered by us right after a native-back callback
+     * that already ran `checkActiveBlocks` — re-running it would prompt the
+     * user twice.
+     */
+    skipBlockCheck?: boolean;
+};
+export type NavResult = ChaynsHistoryActionResult;
+export interface NavigationQueueDeps {
+    /** Returns root layer (top window only). */
+    getRoot: () => ChaynsHistoryLayer;
+    /** Find a layer by id starting at root. */
+    findLayer: (id: string) => ChaynsHistoryLayer | undefined;
+    /** Run the block check pipeline for a target layer. Returns true if free to proceed. */
+    checkBlocks: (target: ChaynsHistoryLayer) => Promise<boolean>;
+    /** Project the current memory tree into the URL string. */
+    projectUrl: () => string;
+    /** Project the current memory tree into the history state object (merged with existing foreign keys). */
+    projectState: () => Record<string, unknown>;
+    /**
+     * Compute which layer ids WOULD change without mutating the tree.
+     * Used to identify the block target before applying incoming state.
+     */
+    diffIncomingState: (raw: unknown) => {
+        changedLayerIds: Set<string>;
+    };
+    /** Apply an incoming raw `__chaynsHistory` state onto the memory tree. Returns affected layer ids. */
+    applyIncomingState: (raw: unknown) => {
+        changedLayerIds: Set<string>;
+    };
+    /** Move history without triggering our normal popstate handling (used to undo blocked navigations). */
+    silentGo: (delta: number) => Promise<void>;
+    /** Returns the current navigation index (incremented on every push). */
+    getCurrentIdx: () => number;
+    /** Increments the navigation index and returns the new value. */
+    incrementIdx: () => number;
+    /** Called after a browser history commit finished. */
+    onCommit?: () => void;
+    /**
+     * Re-parse segments from `window.location.pathname` and apply them to each
+     * layer in the active chain based on its `segmentCount`. Called after
+     * `applyIncomingState` so the active chain reflects the new `activeChild`.
+     * Returns the ids of layers whose segments actually changed.
+     */
+    applyUrlSegments: () => {
+        changedLayerIds: Set<string>;
+    };
+}
+export declare class NavigationQueue {
+    private readonly queue;
+    private isRunning;
+    private readonly deps;
+    constructor(deps: NavigationQueueDeps);
+    enqueue(op: NavOp): Promise<NavResult>;
+    private tick;
+    private process;
+    private processSetRoute;
+    private processSetParams;
+    private processSetHash;
+    private processSetState;
+    private processSetActiveChild;
+    private processNavigate;
+    private processPopstate;
+    private resolveActiveLayer;
+    private resolveLowestCommonLayer;
+    private commit;
+}

package/dist/types/utils/history/layerTree.d.ts

@@ -0,0 +1,10 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+/**
+ * Returns the ordered chain of layers from root to the deepest active layer
+ * (inclusive of root).
+ */
+export declare function getChaynsHistoryActiveChain(root: ChaynsHistoryLayer): ChaynsHistoryLayer[];
+/** Depth-first search for a layer by id starting at `root`. */
+export declare function findChaynsHistoryLayerById(root: ChaynsHistoryLayer, id: string): ChaynsHistoryLayer | undefined;
+/** Returns true if the layer is reachable via active children from the root. */
+export declare function isInChaynsHistoryActiveChain(layer: ChaynsHistoryLayer): boolean;

package/dist/types/utils/history/nativeBackHandling.d.ts

@@ -0,0 +1,47 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import type { BlockRegistry } from './BlockRegistry';
+export interface NativeBackHandlerOptions {
+    rootLayer: ChaynsHistoryLayer;
+    blockRegistry: BlockRegistry;
+}
+/**
+ * Coordinates the native swipe-back gesture (Chayns app action 249) with the
+ * JS history queue.
+ *
+ * Why we disable the gesture as soon as the user has navigated inside the app
+ * (`getCurrentIdx() > 0`) and not only while a block is registered:
+ *   The native swipe animation runs independently of our JS handling. Without
+ *   intercepting it, a swipe-back would (a) play the native pop animation,
+ *   (b) pop the browser entry, (c) fire popstate, and only THEN would the
+ *   queue evaluate the block and silently push forward again — producing the
+ *   "navigate back, then snap forward" jitter described in the bug report.
+ *   By intercepting from the first own history entry on, every back must come
+ *   through the registered callback where we can resolve blocks before
+ *   mutating history.
+ *
+ * Instances are scoped to a single root layer; module-level state is avoided
+ * so re-inits (HMR, tests, multiple roots) cannot desynchronise.
+ */
+export declare class NativeBackHandler {
+    private readonly opts;
+    private isInterceptionEnabled;
+    /**
+     * Set to `true` right before `history.back()` is triggered from
+     * {@link handleNativeBack}. Consumed by the popstate listener so the
+     * queue can skip the duplicate block check (we already ran it).
+     */
+    private bypassNextPopstateBlockCheck;
+    constructor(opts: NativeBackHandlerOptions);
+    /** Re-evaluates the desired native gesture state and pushes it to the app. */
+    sync: () => void;
+    /**
+     * Returns `true` exactly once after a {@link handleNativeBack}-initiated
+     * `history.back()`. The popstate listener uses this so the queue can skip
+     * the (already performed) block check.
+     */
+    consumeBypassFlag(): boolean;
+    private static isSupported;
+    private shouldEnableInterception;
+    private handleNativeBack;
+    private runNativeBack;
+}

package/dist/types/utils/history/navigationIndex.d.ts

@@ -0,0 +1,17 @@
+/** Increment the current index (call on every real pushState). Returns the new value. */
+export declare function incrementIdx(): number;
+/** Get current index for stamping real entries or direction comparison. */
+export declare function getCurrentIdx(): number;
+export declare function setCurrentIdx(idx: number): void;
+export declare function extractHistoryIndex(raw: unknown): number | null;
+export declare function syncCurrentIdxFromState(raw: unknown): number | null;
+/**
+ * Performs a `history.go(delta)` that is silently ignored by our popstate handler.
+ * Returns a promise that resolves when the popstate for this go() fires.
+ */
+export declare function silentGo(delta: number): Promise<void>;
+/**
+ * Called by the popstate handler. Returns true if this popstate is the silent one
+ * and should be suppressed.
+ */
+export declare function consumeSilent(): boolean;

package/dist/types/utils/history/rootLayer.d.ts

@@ -0,0 +1,42 @@
+import { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+/** Parses the URL into a flat segment array and returns all entries after the first `startIndex` entries. */
+export declare function resolveSegmentsFrom(overrideUrl: string | undefined, startIndex: number): string[];
+export interface InitRootChaynsHistoryLayerOptions {
+    /**
+     * The current page URL used to seed initial route segments.
+     * - **Browser**: defaults to `window.location.pathname` — no need to set this.
+     * - **SSR**: pass the request URL (e.g. `req.url` or `router.asPath`) so
+     *   child layers receive the correct initial segments on the server.
+     */
+    url?: string;
+    /**
+     * Number of URL path segments the root layer owns.
+     * When provided, segments are resolved from the URL immediately at construction
+     * so that `getRoute()` is populated on the very first render.
+     */
+    segmentCount?: number;
+}
+export interface InitRootChaynsHistoryLayerResult {
+    rootLayer: ChaynsHistoryLayer;
+}
+/**
+ * Initializes the root ChaynsHistoryLayer for the top window.
+ * - Reads `window.location.pathname` and `window.history.state`.
+ * - If `__chaynsHistory` is absent, replaces the current state with an empty tree.
+ * - Attaches the global `popstate` listener.
+ * - Returns the root ChaynsHistoryLayer instance.
+ *
+ * Call once at application startup (top window only).
+ */
+export declare function initRootChaynsHistoryLayer(opts?: InitRootChaynsHistoryLayerOptions): InitRootChaynsHistoryLayerResult;
+/**
+ * Returns the singleton root ChaynsHistoryLayer for the current window.
+ * Creates it on first call; subsequent calls return the same instance.
+ *
+ * @param url - On SSR, pass the current request URL (e.g. `req.url` or `router.asPath`)
+ *   so child layers receive the correct initial route segments. Ignored after first call.
+ * @param segmentCount - Number of URL segments the root layer owns. When provided the
+ *   segments are resolved from the URL immediately so `getRoute()` is populated on the
+ *   very first render without any subsequent `setSegmentCount` call. Ignored after first call.
+ */
+export declare function getOrInitRootChaynsHistoryLayer(url?: string, segmentCount?: number): InitRootChaynsHistoryLayerResult;

package/dist/types/utils/history/segments.d.ts

@@ -0,0 +1,2 @@
+export declare const normalizeHistorySegments: (segments: string[]) => string[];
+export declare const normalizeHistoryRouteInput: (route: string | string[]) => string[];

package/dist/types/utils/history/stateProjector.d.ts

@@ -0,0 +1,24 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import type { ChaynsHistoryLayerStateNode } from '../../types/history';
+/**
+ * Returns the value to store in `window.history.state`, merging with any
+ * pre-existing foreign keys so we never overwrite other consumers' state.
+ */
+export declare function projectToState(root: ChaynsHistoryLayer, existing?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Applies the raw `window.history.state` payload onto the layer tree.
+ * Returns the set of layer ids whose segments OR ownState changed.
+ */
+export declare function applyStateToTree(root: ChaynsHistoryLayer, raw: unknown): {
+    changedLayerIds: Set<string>;
+};
+/**
+ * Like `applyStateToTree` but does NOT mutate the tree.
+ * Returns layer ids that WOULD change if the state were applied.
+ */
+export declare function diffIncomingState(root: ChaynsHistoryLayer, raw: unknown): {
+    changedLayerIds: Set<string>;
+};
+declare function extractNode(raw: unknown): ChaynsHistoryLayerStateNode | null;
+export { extractNode as _extractNode };
+export declare function hasChaynsHistoryState(raw: unknown): boolean;

package/dist/types/utils/history/url.d.ts

@@ -0,0 +1,17 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+/**
+ * Concatenates all segments along the active chain into a URL with pathname,
+ * merged query params, and the deepest explicitly-set hash.
+ */
+export declare function projectToUrl(root: ChaynsHistoryLayer): string;
+export interface ParseResult {
+    /** Maps layer id → segments assigned to that layer. */
+    perLayerSegments: Map<string, string[]>;
+    /** Segments that could not be assigned to any layer's segmentCount. */
+    pendingSegments: string[];
+}
+/**
+ * Splits the incoming URL pathname onto layers based on each layer's `segmentCount`.
+ * Traverses the active chain; excess segments go to `pendingSegments`.
+ */
+export declare function parseFromUrl(url: string, root: ChaynsHistoryLayer): ParseResult;

package/dist/types/utils/history/window.d.ts

@@ -0,0 +1 @@
+export declare function hasWindowHistory(): boolean;

package/dist/types/wrapper/FrameWrapper.d.ts

@@ -5,6 +5,7 @@ export declare class FrameWrapper implements IChaynsReact {
     private exposedCustomFunctions;
     private exposedCustomFunctionNames;
     private resizeListener;
+    private _historyLayer;
     ready: Promise<unknown>;
     values: ChaynsReactValues;
     chaynsApiId: string;

package/dist/types/wrapper/StaticChaynsApi.d.ts

@@ -64,6 +64,7 @@ declare class StaticChaynsApi implements ChaynsReactFunctions {
     addAccessTokenChangeListener: ChaynsReactFunctions['addAccessTokenChangeListener'];
     removeAccessTokenChangeListener: ChaynsReactFunctions['removeAccessTokenChangeListener'];
     redirect: ChaynsReactFunctions['redirect'];
+    getHistoryLayer: ChaynsReactFunctions['getHistoryLayer'];
     ready: Promise<void>;
     addDataListener: (cb: DataChangeCallback) => () => void;
     private _wrapper;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "chayns-api",
-    "version": "3.0.1",
+    "version": "3.1.0-beta.1",
     "description": "new chayns api",
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",
@@ -74,6 +74,7 @@
         "chayns-toolkit": "^4.0.0-beta.0",
         "concurrently": "^9.2.1",
         "cross-env": "^10.1.0",
+        "jsdom": "^29.1.1",
         "prettier": "^3.7.4",
         "prettier-plugin-packagejson": "^2.5.20",
         "react": "^18.3.1",