@rangojs/router 0.4.0 → 0.4.1

package/dist/types.backup/browser/scroll-restoration.d.ts

@@ -1,103 +0,0 @@
-/**
- * Scroll Restoration Module
- *
- * Provides scroll position persistence across navigations, following React Router v7 patterns:
- * - Saves scroll positions to sessionStorage keyed by unique history entry key
- * - Restores scroll on back/forward navigation
- * - Scrolls to top on new navigation (unless scroll: false)
- * - Supports hash link scrolling
- */
-/**
- * Custom getKey function for determining scroll restoration key
- */
-type GetScrollKeyFunction = (location: {
-    pathname: string;
-    search: string;
-    hash: string;
-    key: string;
-}) => string;
-/**
- * Generate a unique key for the current history entry.
- * Uses history.state.key if available, otherwise generates and stores a new one.
- */
-export declare function getHistoryStateKey(): string;
-/**
- * Get the scroll restoration key for a location.
- * Uses custom getKey function if set, otherwise uses history state key.
- */
-export declare function getScrollKey(): string;
-/**
- * Initialize scroll restoration.
- * Sets manual scroll restoration mode and loads saved positions from sessionStorage.
- */
-export declare function initScrollRestoration(options?: {
-    getKey?: GetScrollKeyFunction;
-}): () => void;
-/**
- * Save the current scroll position for the current history entry.
- * Maintains bounded size by evicting oldest entries when the limit is exceeded.
- */
-export declare function saveCurrentScrollPosition(): void;
-/**
- * Persist scroll positions to sessionStorage.
- * If the write fails (typically QuotaExceededError), evict the oldest ~1/4 of
- * entries ONCE and retry the write a single time; if that still fails, remove
- * our storage key entirely so we don't block other sessionStorage consumers.
- * This is a single evict-then-retry-then-clear ladder, not a loop.
- *
- * Exported so that single eviction/retry/clear ladder is unit-testable directly.
- * The browser drives it from the `pagehide` handler.
- */
-export declare function persistToSessionStorage(): void;
-/**
- * Get the saved scroll position for a history key
- */
-export declare function getSavedScrollPosition(key?: string): number | undefined;
-/**
- * Cancel any pending scroll restoration polling
- */
-export declare function cancelScrollRestorationPolling(): void;
-/**
- * Restore scroll position for the current history entry.
- * Returns true if position was fully restored, false otherwise.
- *
- * @param options.retryIfStreaming - If true, poll while streaming until we can scroll to target
- * @param options.isStreaming - Function to check if streaming is in progress
- */
-export declare function restoreScrollPosition(options?: {
-    retryIfStreaming?: boolean;
-    isStreaming?: () => boolean;
-}): boolean;
-/**
- * Handle hash link scrolling.
- * Scrolls to element with matching ID if hash is present.
- * Returns true if scrolled to element, false otherwise.
- */
-export declare function scrollToHash(): boolean;
-/**
- * Scroll to top of page
- */
-export declare function scrollToTop(): void;
-/**
- * Handle scroll for a new navigation.
- * - Saves current position before navigating
- * - Ensures new history entry has a key
- */
-export declare function handleNavigationStart(): void;
-/**
- * Handle scroll after navigation completes.
- * @param options.restore - If true, restore saved position (for popstate)
- * @param options.scroll - If false, don't scroll at all
- * @param options.isStreaming - Function to check if streaming is in progress (for retry logic)
- */
-export declare function handleNavigationEnd(options: {
-    restore?: boolean;
-    scroll?: boolean;
-    isStreaming?: () => boolean;
-}): void;
-/**
- * Update the history state key after pushState/replaceState.
- * Call this after changing history to ensure new entry has a key.
- */
-export declare function ensureHistoryKey(): void;
-export {};

package/dist/types.backup/browser/segment-reconciler.d.ts

@@ -1,74 +0,0 @@
-import type { ResolvedSegment } from "./types.js";
-/**
- * Determines the merging behavior for segment reconciliation.
- *
- * - 'action': From server-action-bridge's own merge. Always merges loaders,
- *   always preserves cached loading (even undefined), never clears cached
- *   segment loading.
- * - 'navigation': From partial-update during normal navigation. Does NOT merge
- *   loaders, preserves cached loading only when defined, clears truthy loading
- *   on cached segments not in server diff.
- * - 'stale-revalidation': From partial-update during stale revalidation or
- *   action-triggered refetch. Merges loaders, always preserves cached loading
- *   (same as action), clears truthy loading on cached segments not in server diff.
- */
-export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
-export interface ReconcileInput {
-    actor: ReconcileActor;
-    /** All segment IDs the server expects the client to have (matched array) */
-    matched: string[];
-    /** Segment IDs that changed (diff array) */
-    diff: string[];
-    /** Segments returned from server (raw array, keyed internally by ID) */
-    serverSegments: ResolvedSegment[];
-    /** Cached segments from current page (raw array, keyed internally by ID) */
-    cachedSegments: ResolvedSegment[];
-    /** When true, diff segments not in matched are inserted after their parent
-     *  layout. Used during navigation when consolidation fetch returns loader
-     *  segments that aren't in the matched array. */
-    insertMissingDiff?: boolean;
-}
-export interface ReconcileResult {
-    /** All merged segments in matched order (for caching and committing) */
-    segments: ResolvedSegment[];
-    /** Main segments excluding intercepts (for rendering) */
-    mainSegments: ResolvedSegment[];
-    /** Intercept segments only (passed via render options) */
-    interceptSegments: ResolvedSegment[];
-}
-/**
- * Single source of truth for merging server segments with cached segments.
- *
- * Replaces the duplicated merge loops in server-action-bridge.ts and
- * partial-update.ts. The actor parameter controls the subtle behavioral
- * differences between action and navigation merging:
- *
- * Loading preservation:
- * - action/stale-revalidation: Always preserves cached loading value when it
- *   differs from server (even when cached is undefined). This prevents tree
- *   structure changes that would remount components and destroy useActionState
- *   during action revalidation or action-triggered refetch.
- * - navigation: Preserves cached loading only when the cached value is defined
- *   (not undefined). When cached is undefined, lets server value through
- *   because we're building a new tree.
- *
- * Loader merging:
- * - action/stale-revalidation: Merges partial loader data when server returns
- *   fewer loaders than cached (revalidation only updated some loaders).
- * - navigation: Does not merge (full navigation fetches complete data).
- *
- * Cached segment handling (segments in matched but not in server response):
- * - action: Returns cached segment as-is (preserve tree structure).
- * - navigation/stale-revalidation: Clears truthy loading to undefined
- *   (prevents showing stale skeletons), but preserves loading=false
- *   (suppressed boundary is structural).
- */
-export declare function reconcileSegments(input: ReconcileInput): ReconcileResult;
-/**
- * Reconcile error segments with cached segments.
- *
- * For error responses, the server returns the error boundary segment.
- * This function overlays error segments onto the full cached tree,
- * preserving sibling layouts that aren't in the error parent chain.
- */
-export declare function reconcileErrorSegments(cachedSegments: ResolvedSegment[], errorSegments: ResolvedSegment[]): ReconcileResult;

package/dist/types.backup/browser/segment-structure-assert.d.ts

@@ -1,16 +0,0 @@
-import type { ResolvedSegment } from "./types.js";
-/**
- * Assert that merging a server segment with a cached segment won't change
- * the React tree structure. Logs a warning in development when a mismatch
- * is detected.
- *
- * This catches the class of bugs where `loading()` with `{ ssr: false }`
- * produces `loading=false` on SSR but `loading=<skeleton>` on actions,
- * causing React to remount LoaderBoundary/RouteContentWrapper and destroy
- * client state (useActionState, refs, etc.).
- *
- * @param cached - The currently cached segment
- * @param incoming - The new segment from server
- * @param context - Where this merge is happening (for the warning message)
- */
-export declare function assertSegmentStructure(cached: ResolvedSegment, incoming: ResolvedSegment, context: string): void;

package/dist/types.backup/browser/server-action-bridge.d.ts

@@ -1,29 +0,0 @@
-import type { ServerActionBridge, ServerActionBridgeConfig } from "./types.js";
-import type { EventController } from "./event-controller.js";
-/**
- * Extended configuration for server action bridge with event controller
- */
-export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
-    eventController: EventController;
-    /** Callback to trigger SPA navigation (for action redirects) */
-    onNavigate?: (url: string, options?: {
-        state?: unknown;
-        replace?: boolean;
-        _skipCache?: boolean;
-    }) => Promise<void>;
-}
-/**
- * Create a server action bridge for handling RSC server actions
- *
- * The bridge registers a callback with the RSC runtime that handles:
- * - Encoding action arguments
- * - Sending action requests to the server
- * - Processing responses and updating UI
- * - Managing concurrent action requests via event controller
- * - HMR resilience (refetching if segments are missing)
- *
- * @param config - Bridge configuration
- * @returns ServerActionBridge instance
- */
-export declare function createServerActionBridge(config: ServerActionBridgeConfigWithController): ServerActionBridge;
-export { createServerActionBridge as default };