@hybridly/core 0.4.4 → 0.5.0

package/dist/index.cjs

@@ -18,14 +18,12 @@ const ONLY_DATA_HEADER = `${HYBRIDLY_HEADER}-only-data`;
 const DIALOG_KEY_HEADER = `${HYBRIDLY_HEADER}-dialog-key`;
 const DIALOG_REDIRECT_HEADER = `${HYBRIDLY_HEADER}-dialog-redirect`;
 const EXCEPT_DATA_HEADER = `${HYBRIDLY_HEADER}-except-data`;
-const CONTEXT_HEADER = `${HYBRIDLY_HEADER}-context`;
 const VERSION_HEADER = `${HYBRIDLY_HEADER}-version`;
 const ERROR_BAG_HEADER = `${HYBRIDLY_HEADER}-error-bag`;
 const SCROLL_REGION_ATTRIBUTE = "scroll-region";
 
 const constants = {
 	__proto__: null,
-	CONTEXT_HEADER: CONTEXT_HEADER,
 	DIALOG_KEY_HEADER: DIALOG_KEY_HEADER,
 	DIALOG_REDIRECT_HEADER: DIALOG_REDIRECT_HEADER,
 	ERROR_BAG_HEADER: ERROR_BAG_HEADER,
@@ -273,6 +271,7 @@ async function registerEventListeners() {
     if (!state) {
       utils.debug.history("There is no state. Adding hash if any and restoring scroll positions.");
       return await navigate({
+        type: "initial",
         payload: {
           ...context,
           url: makeUrl(context.url, { hash: window.location.hash }).toString()
@@ -283,11 +282,11 @@ async function registerEventListeners() {
       });
     }
     await navigate({
+      type: "back-forward",
       payload: state,
       preserveScroll: true,
       preserveState: !!getInternalRouterContext().dialog || !!state.dialog,
-      updateHistoryState: false,
-      isBackForward: true
+      updateHistoryState: false
     });
   });
   window?.addEventListener("scroll", (event) => utils.debounce(() => {
@@ -310,14 +309,14 @@ async function handleBackForwardNavigation() {
     throw new Error("Tried to handling a back/forward navigation, but there was no state in the history. This should not happen.");
   }
   await navigate({
+    type: "back-forward",
     payload: {
       ...state,
       version: context.version
     },
     preserveScroll: true,
     preserveState: false,
-    updateHistoryState: false,
-    isBackForward: true
+    updateHistoryState: false
   });
 }
 function remember(key, value) {
@@ -607,8 +606,9 @@ async function handleExternalNavigation() {
     url: makeUrl(getRouterContext().url, { hash: window.location.hash }).toString()
   });
   await navigate({
-    preserveScroll: options.preserveScroll,
-    preserveState: true
+    type: "initial",
+    preserveState: true,
+    preserveScroll: options.preserveScroll
   });
 }
 function isExternalNavigation() {
@@ -644,6 +644,27 @@ async function closeDialog(options) {
   });
 }
 
+function isDownloadResponse(response) {
+  return response.status === 200 && !!response.headers["content-disposition"];
+}
+async function handleDownloadResponse(response) {
+  const blob = new Blob([response.data], { type: "application/octet-stream" });
+  const urlObject = window.webkitURL || window.URL;
+  const link = document.createElement("a");
+  link.style.display = "none";
+  link.href = urlObject.createObjectURL(blob);
+  link.download = getFileNameFromContentDispositionHeader(response.headers["content-disposition"]);
+  link.click();
+  setTimeout(() => {
+    urlObject.revokeObjectURL(link.href);
+    link.remove();
+  }, 0);
+}
+function getFileNameFromContentDispositionHeader(header) {
+  const result = header.split(";")[1]?.trim().split("=")[1];
+  return result?.replace(/^"(.*)"$/, "$1") ?? "";
+}
+
 function isPreloaded(targetUrl) {
   const context = getInternalRouterContext();
   return context.preloadCache.has(targetUrl.toString()) ?? false;
@@ -765,10 +786,7 @@ async function performHybridNavigation(options) {
       context.pendingNavigation?.controller?.abort();
     }
     saveScrollPositions();
-    if (options.url && options.transformUrl) {
-      options.url = makeUrl(options.url, options.transformUrl);
-    }
-    const targetUrl = makeUrl(options.url ?? context.url);
+    const targetUrl = makeUrl(options.url ?? context.url, options.transformUrl);
     const abortController = new AbortController();
     setContext({
       pendingNavigation: {
@@ -782,7 +800,10 @@ async function performHybridNavigation(options) {
     await runHooks("start", options.hooks, context);
     utils.debug.router("Making request with axios.");
     const response = await performHybridRequest(targetUrl, options, abortController);
-    await runHooks("data", options.hooks, response, context);
+    const result = await runHooks("data", options.hooks, response, context);
+    if (result === false) {
+      return { response };
+    }
     if (isExternalResponse(response)) {
       utils.debug.router("The response is explicitely external.");
       await performExternalNavigation({
@@ -791,6 +812,11 @@ async function performHybridNavigation(options) {
       });
       return { response };
     }
+    if (isDownloadResponse(response)) {
+      utils.debug.router("The response returns a file to download.");
+      await handleDownloadResponse(response);
+      return { response };
+    }
     if (!isHybridResponse(response)) {
       throw new NotAHybridResponseError(response);
     }
@@ -802,6 +828,7 @@ async function performHybridNavigation(options) {
       utils.debug.router("Merged properties:", payload.view.properties);
     }
     await navigate({
+      type: "server",
       payload: {
         ...payload,
         url: fillHash(targetUrl, payload.url)
@@ -885,6 +912,7 @@ function isHybridResponse(response) {
 }
 async function navigate(options) {
   const context = getRouterContext();
+  options.hasDialog ?? (options.hasDialog = !!options.payload?.dialog);
   utils.debug.router("Making an internal navigation:", { context, options });
   await runHooks("navigating", {}, options, context);
   options.payload ?? (options.payload = payloadFromContext());
@@ -895,6 +923,7 @@ async function navigate(options) {
   const shouldPreserveScroll = evaluateConditionalOption(options.preserveScroll);
   const shouldReplaceHistory = evaluateConditionalOption(options.replace);
   const shouldReplaceUrl = evaluateConditionalOption(options.preserveUrl);
+  const shouldPreserveView = !options.payload.view.component;
   if (shouldPreserveState && getHistoryMemo() && options.payload.view.component === context.view.component) {
     utils.debug.history("Setting the memo from this history entry into the current context.");
     setContext({ memo: getHistoryMemo() });
@@ -903,26 +932,44 @@ async function navigate(options) {
     utils.debug.router(`Preserving the current URL (${context.url}) instead of navigating to ${options.payload.url}`);
     options.payload.url = context.url;
   }
-  setContext({
-    ...options.payload,
-    memo: {}
-  });
+  const payload = shouldPreserveView ? {
+    view: {
+      component: context.view.component,
+      properties: utils.merge(context.view.properties, options.payload.view.properties),
+      deferred: context.view.deferred
+    },
+    url: context.url,
+    version: options.payload.version,
+    dialog: context.dialog
+  } : options.payload;
+  setContext({ ...payload, memo: {} });
   if (options.updateHistoryState !== false) {
     utils.debug.router(`Target URL is ${context.url}, current window URL is ${window.location.href}.`, { shouldReplaceHistory });
     setHistoryState({ replace: shouldReplaceHistory });
   }
-  context.adapter.executeOnMounted(() => {
-    runHooks("mounted", {}, context);
-  });
-  const viewComponent = await context.adapter.resolveComponent(context.view.component);
-  utils.debug.router(`Component [${context.view.component}] resolved to:`, viewComponent);
+  if (context.view.deferred?.length) {
+    utils.debug.router("Request has deferred properties, queueing a partial reload:", context.view.deferred);
+    context.adapter.executeOnMounted(async () => {
+      await performHybridNavigation({
+        preserveScroll: true,
+        preserveState: true,
+        replace: true,
+        only: context.view.deferred
+      });
+    });
+  }
+  const viewComponent = !shouldPreserveView ? await context.adapter.resolveComponent(context.view.component) : void 0;
+  if (viewComponent) {
+    utils.debug.router(`Component [${context.view.component}] resolved to:`, viewComponent);
+  }
   await context.adapter.onViewSwap({
     component: viewComponent,
     dialog: context.dialog,
     properties: options.payload?.view?.properties,
-    preserveState: shouldPreserveState
+    preserveState: shouldPreserveState,
+    onMounted: (hookOptions) => runHooks("mounted", {}, { ...options, ...hookOptions }, context)
   });
-  if (options.isBackForward) {
+  if (options.type === "back-forward") {
     restoreScrollPositions();
   } else if (!shouldPreserveScroll) {
     resetScrollPositions();
@@ -974,12 +1021,12 @@ async function initializeRouter() {
   } else if (isExternalNavigation()) {
     handleExternalNavigation();
   } else {
-    utils.debug.router("Handling the initial page navigation.");
+    utils.debug.router("Handling the initial navigation.");
     setContext({
       url: makeUrl(context.url, { hash: window.location.hash }).toString()
     });
     await navigate({
-      isInitial: true,
+      type: "initial",
       preserveState: true,
       replace: sameUrls(context.url, window.location.href)
     });
@@ -993,13 +1040,15 @@ async function performLocalNavigation(targetUrl, options) {
   const url = normalizeUrl(targetUrl);
   return await navigate({
     ...options,
+    type: "local",
     payload: {
       version: context.version,
       dialog: options?.dialog === false ? void 0 : options?.dialog ?? context.dialog,
       url,
       view: {
         component: options?.component ?? context.view.component,
-        properties: options?.properties ?? {}
+        properties: options?.properties ?? {},
+        deferred: []
       }
     }
   });

package/dist/index.d.cts

@@ -55,7 +55,7 @@ interface Hooks extends RequestHooks {
          */
     initialized: (context: InternalRouterContext) => MaybePromise<any>;
     /**
-     * Called after Hybridly's initial page load.
+     * Called after Hybridly's initial load.
      */
     ready: (context: InternalRouterContext) => MaybePromise<any>;
     /**
@@ -65,15 +65,21 @@ interface Hooks extends RequestHooks {
     /**
      * Called when a component navigation is being made.
      */
-    navigating: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigating: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to.
      */
-    navigated: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigated: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to and was mounted by the adapter.
      */
-    mounted: (context: InternalRouterContext) => MaybePromise<any>;
+    mounted: (options: InternalNavigationOptions & MountedHookOptions, context: InternalRouterContext) => MaybePromise<any>;
+}
+interface MountedHookOptions {
+    /**
+     * Whether the component being mounted is a dialog.
+     */
+    isDialog: boolean;
 }
 interface HookOptions {
     /** Executes the hook only once. */
@@ -128,7 +134,7 @@ interface ComponentNavigationOptions {
     replace?: ConditionalNavigationOption<boolean>;
     /** Whether to preserve the current scrollbar position. */
     preserveScroll?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the current page component state. */
+    /** Whether to preserve the current view component state. */
     preserveState?: ConditionalNavigationOption<boolean>;
 }
 interface NavigationOptions {
@@ -139,9 +145,9 @@ interface NavigationOptions {
      * one. This affects the browser's "back" and "forward" features.
      */
     replace?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the scrollbars positions on the page. */
+    /** Whether to preserve the scrollbars positions on the view. */
     preserveScroll?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the current page component's state. */
+    /** Whether to preserve the current view component's state. */
     preserveState?: ConditionalNavigationOption<boolean>;
     /** Whether to preserve the current URL. */
     preserveUrl?: ConditionalNavigationOption<boolean>;
@@ -160,16 +166,22 @@ interface NavigationOptions {
      * @internal This is an advanced property meant to be used internally.
      */
     updateHistoryState?: boolean;
+}
+interface InternalNavigationOptions extends NavigationOptions {
     /**
-     * Defines whether this navigation is a back/forward navigation from the popstate event.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines the kind of navigation being performed.
+     * - initial: the initial load's navigation
+     * - server: a navigation initiated by a server round-trip
+     * - local: a navigation initiated by `router.local`
+     * - back-forward: a navigation initiated by the browser's `popstate` event
+     * @internal
      */
-    isBackForward?: boolean;
+    type: 'initial' | 'local' | 'back-forward' | 'server';
     /**
-     * Defines whether this navigation is the first to happen after a direct page load.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines whether this navigation opens a dialog.
+     * @internal
      */
-    isInitial?: boolean;
+    hasDialog?: boolean;
 }
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 interface HybridRequestOptions extends Omit<NavigationOptions, 'payload'> {
@@ -266,15 +278,17 @@ interface PendingNavigation {
     /** Current status. */
     status: 'pending' | 'success' | 'error';
 }
-/** A page or dialog component. */
+/** A view or dialog component. */
 interface View {
     /** Name of the component to use. */
-    component: string;
+    component?: string;
     /** Properties to apply to the component. */
     properties: Properties;
+    /** Deferred properties for this view. */
+    deferred: string[];
 }
-interface Dialog extends View {
-    /** URL that is the base background page when navigating to the dialog directly. */
+interface Dialog extends Required<View> {
+    /** URL that is the base background view when navigating to the dialog directly. */
     baseUrl: string;
     /** URL to which the dialog should redirect when closed. */
     redirectUrl: string;
@@ -294,6 +308,8 @@ interface SwapOptions<T> {
     preserveState?: boolean;
     /** Current dialog. */
     dialog?: Dialog;
+    /** On mounted callback. */
+    onMounted?: (options: MountedHookOptions) => void;
 }
 type ViewComponent = any;
 type ResolveComponent = (name: string) => Promise<ViewComponent>;
@@ -471,12 +487,10 @@ declare const ONLY_DATA_HEADER = "x-hybrid-only-data";
 declare const DIALOG_KEY_HEADER = "x-hybrid-dialog-key";
 declare const DIALOG_REDIRECT_HEADER = "x-hybrid-dialog-redirect";
 declare const EXCEPT_DATA_HEADER = "x-hybrid-except-data";
-declare const CONTEXT_HEADER = "x-hybrid-context";
 declare const VERSION_HEADER = "x-hybrid-version";
 declare const ERROR_BAG_HEADER = "x-hybrid-error-bag";
 declare const SCROLL_REGION_ATTRIBUTE = "scroll-region";
 
-declare const constants_CONTEXT_HEADER: typeof CONTEXT_HEADER;
 declare const constants_DIALOG_KEY_HEADER: typeof DIALOG_KEY_HEADER;
 declare const constants_DIALOG_REDIRECT_HEADER: typeof DIALOG_REDIRECT_HEADER;
 declare const constants_ERROR_BAG_HEADER: typeof ERROR_BAG_HEADER;
@@ -489,7 +503,7 @@ declare const constants_SCROLL_REGION_ATTRIBUTE: typeof SCROLL_REGION_ATTRIBUTE;
 declare const constants_STORAGE_EXTERNAL_KEY: typeof STORAGE_EXTERNAL_KEY;
 declare const constants_VERSION_HEADER: typeof VERSION_HEADER;
 declare namespace constants {
-  export { constants_CONTEXT_HEADER as CONTEXT_HEADER, constants_DIALOG_KEY_HEADER as DIALOG_KEY_HEADER, constants_DIALOG_REDIRECT_HEADER as DIALOG_REDIRECT_HEADER, constants_ERROR_BAG_HEADER as ERROR_BAG_HEADER, constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER, constants_EXTERNAL_NAVIGATION_HEADER as EXTERNAL_NAVIGATION_HEADER, constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER, constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER, constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER, constants_SCROLL_REGION_ATTRIBUTE as SCROLL_REGION_ATTRIBUTE, constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY, constants_VERSION_HEADER as VERSION_HEADER };
+  export { constants_DIALOG_KEY_HEADER as DIALOG_KEY_HEADER, constants_DIALOG_REDIRECT_HEADER as DIALOG_REDIRECT_HEADER, constants_ERROR_BAG_HEADER as ERROR_BAG_HEADER, constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER, constants_EXTERNAL_NAVIGATION_HEADER as EXTERNAL_NAVIGATION_HEADER, constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER, constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER, constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER, constants_SCROLL_REGION_ATTRIBUTE as SCROLL_REGION_ATTRIBUTE, constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY, constants_VERSION_HEADER as VERSION_HEADER };
 }
 
 export { type Authorizable, type DynamicConfiguration, type GlobalRouteCollection, type HybridPayload, type HybridRequestOptions, type MaybePromise, type Method, type NavigationResponse, type Plugin, type Progress, type ResolveComponent, type RouteDefinition, type RouteName, type RouteParameters, type Router, type RouterContext, type RouterContextOptions, type RoutingConfiguration, type UrlResolvable, can, constants, createRouter, definePlugin, getRouterContext, makeUrl, registerHook, route, router, sameUrls };

package/dist/index.d.mts

@@ -55,7 +55,7 @@ interface Hooks extends RequestHooks {
          */
     initialized: (context: InternalRouterContext) => MaybePromise<any>;
     /**
-     * Called after Hybridly's initial page load.
+     * Called after Hybridly's initial load.
      */
     ready: (context: InternalRouterContext) => MaybePromise<any>;
     /**
@@ -65,15 +65,21 @@ interface Hooks extends RequestHooks {
     /**
      * Called when a component navigation is being made.
      */
-    navigating: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigating: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to.
      */
-    navigated: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigated: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to and was mounted by the adapter.
      */
-    mounted: (context: InternalRouterContext) => MaybePromise<any>;
+    mounted: (options: InternalNavigationOptions & MountedHookOptions, context: InternalRouterContext) => MaybePromise<any>;
+}
+interface MountedHookOptions {
+    /**
+     * Whether the component being mounted is a dialog.
+     */
+    isDialog: boolean;
 }
 interface HookOptions {
     /** Executes the hook only once. */
@@ -128,7 +134,7 @@ interface ComponentNavigationOptions {
     replace?: ConditionalNavigationOption<boolean>;
     /** Whether to preserve the current scrollbar position. */
     preserveScroll?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the current page component state. */
+    /** Whether to preserve the current view component state. */
     preserveState?: ConditionalNavigationOption<boolean>;
 }
 interface NavigationOptions {
@@ -139,9 +145,9 @@ interface NavigationOptions {
      * one. This affects the browser's "back" and "forward" features.
      */
     replace?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the scrollbars positions on the page. */
+    /** Whether to preserve the scrollbars positions on the view. */
     preserveScroll?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the current page component's state. */
+    /** Whether to preserve the current view component's state. */
     preserveState?: ConditionalNavigationOption<boolean>;
     /** Whether to preserve the current URL. */
     preserveUrl?: ConditionalNavigationOption<boolean>;
@@ -160,16 +166,22 @@ interface NavigationOptions {
      * @internal This is an advanced property meant to be used internally.
      */
     updateHistoryState?: boolean;
+}
+interface InternalNavigationOptions extends NavigationOptions {
     /**
-     * Defines whether this navigation is a back/forward navigation from the popstate event.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines the kind of navigation being performed.
+     * - initial: the initial load's navigation
+     * - server: a navigation initiated by a server round-trip
+     * - local: a navigation initiated by `router.local`
+     * - back-forward: a navigation initiated by the browser's `popstate` event
+     * @internal
      */
-    isBackForward?: boolean;
+    type: 'initial' | 'local' | 'back-forward' | 'server';
     /**
-     * Defines whether this navigation is the first to happen after a direct page load.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines whether this navigation opens a dialog.
+     * @internal
      */
-    isInitial?: boolean;
+    hasDialog?: boolean;
 }
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 interface HybridRequestOptions extends Omit<NavigationOptions, 'payload'> {
@@ -266,15 +278,17 @@ interface PendingNavigation {
     /** Current status. */
     status: 'pending' | 'success' | 'error';
 }
-/** A page or dialog component. */
+/** A view or dialog component. */
 interface View {
     /** Name of the component to use. */
-    component: string;
+    component?: string;
     /** Properties to apply to the component. */
     properties: Properties;
+    /** Deferred properties for this view. */
+    deferred: string[];
 }
-interface Dialog extends View {
-    /** URL that is the base background page when navigating to the dialog directly. */
+interface Dialog extends Required<View> {
+    /** URL that is the base background view when navigating to the dialog directly. */
     baseUrl: string;
     /** URL to which the dialog should redirect when closed. */
     redirectUrl: string;
@@ -294,6 +308,8 @@ interface SwapOptions<T> {
     preserveState?: boolean;
     /** Current dialog. */
     dialog?: Dialog;
+    /** On mounted callback. */
+    onMounted?: (options: MountedHookOptions) => void;
 }
 type ViewComponent = any;
 type ResolveComponent = (name: string) => Promise<ViewComponent>;
@@ -471,12 +487,10 @@ declare const ONLY_DATA_HEADER = "x-hybrid-only-data";
 declare const DIALOG_KEY_HEADER = "x-hybrid-dialog-key";
 declare const DIALOG_REDIRECT_HEADER = "x-hybrid-dialog-redirect";
 declare const EXCEPT_DATA_HEADER = "x-hybrid-except-data";
-declare const CONTEXT_HEADER = "x-hybrid-context";
 declare const VERSION_HEADER = "x-hybrid-version";
 declare const ERROR_BAG_HEADER = "x-hybrid-error-bag";
 declare const SCROLL_REGION_ATTRIBUTE = "scroll-region";
 
-declare const constants_CONTEXT_HEADER: typeof CONTEXT_HEADER;
 declare const constants_DIALOG_KEY_HEADER: typeof DIALOG_KEY_HEADER;
 declare const constants_DIALOG_REDIRECT_HEADER: typeof DIALOG_REDIRECT_HEADER;
 declare const constants_ERROR_BAG_HEADER: typeof ERROR_BAG_HEADER;
@@ -489,7 +503,7 @@ declare const constants_SCROLL_REGION_ATTRIBUTE: typeof SCROLL_REGION_ATTRIBUTE;
 declare const constants_STORAGE_EXTERNAL_KEY: typeof STORAGE_EXTERNAL_KEY;
 declare const constants_VERSION_HEADER: typeof VERSION_HEADER;
 declare namespace constants {
-  export { constants_CONTEXT_HEADER as CONTEXT_HEADER, constants_DIALOG_KEY_HEADER as DIALOG_KEY_HEADER, constants_DIALOG_REDIRECT_HEADER as DIALOG_REDIRECT_HEADER, constants_ERROR_BAG_HEADER as ERROR_BAG_HEADER, constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER, constants_EXTERNAL_NAVIGATION_HEADER as EXTERNAL_NAVIGATION_HEADER, constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER, constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER, constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER, constants_SCROLL_REGION_ATTRIBUTE as SCROLL_REGION_ATTRIBUTE, constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY, constants_VERSION_HEADER as VERSION_HEADER };
+  export { constants_DIALOG_KEY_HEADER as DIALOG_KEY_HEADER, constants_DIALOG_REDIRECT_HEADER as DIALOG_REDIRECT_HEADER, constants_ERROR_BAG_HEADER as ERROR_BAG_HEADER, constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER, constants_EXTERNAL_NAVIGATION_HEADER as EXTERNAL_NAVIGATION_HEADER, constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER, constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER, constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER, constants_SCROLL_REGION_ATTRIBUTE as SCROLL_REGION_ATTRIBUTE, constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY, constants_VERSION_HEADER as VERSION_HEADER };
 }
 
 export { type Authorizable, type DynamicConfiguration, type GlobalRouteCollection, type HybridPayload, type HybridRequestOptions, type MaybePromise, type Method, type NavigationResponse, type Plugin, type Progress, type ResolveComponent, type RouteDefinition, type RouteName, type RouteParameters, type Router, type RouterContext, type RouterContextOptions, type RoutingConfiguration, type UrlResolvable, can, constants, createRouter, definePlugin, getRouterContext, makeUrl, registerHook, route, router, sameUrls };

package/dist/index.d.ts

@@ -55,7 +55,7 @@ interface Hooks extends RequestHooks {
          */
     initialized: (context: InternalRouterContext) => MaybePromise<any>;
     /**
-     * Called after Hybridly's initial page load.
+     * Called after Hybridly's initial load.
      */
     ready: (context: InternalRouterContext) => MaybePromise<any>;
     /**
@@ -65,15 +65,21 @@ interface Hooks extends RequestHooks {
     /**
      * Called when a component navigation is being made.
      */
-    navigating: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigating: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to.
      */
-    navigated: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigated: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to and was mounted by the adapter.
      */
-    mounted: (context: InternalRouterContext) => MaybePromise<any>;
+    mounted: (options: InternalNavigationOptions & MountedHookOptions, context: InternalRouterContext) => MaybePromise<any>;
+}
+interface MountedHookOptions {
+    /**
+     * Whether the component being mounted is a dialog.
+     */
+    isDialog: boolean;
 }
 interface HookOptions {
     /** Executes the hook only once. */
@@ -128,7 +134,7 @@ interface ComponentNavigationOptions {
     replace?: ConditionalNavigationOption<boolean>;
     /** Whether to preserve the current scrollbar position. */
     preserveScroll?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the current page component state. */
+    /** Whether to preserve the current view component state. */
     preserveState?: ConditionalNavigationOption<boolean>;
 }
 interface NavigationOptions {
@@ -139,9 +145,9 @@ interface NavigationOptions {
      * one. This affects the browser's "back" and "forward" features.
      */
     replace?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the scrollbars positions on the page. */
+    /** Whether to preserve the scrollbars positions on the view. */
     preserveScroll?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the current page component's state. */
+    /** Whether to preserve the current view component's state. */
     preserveState?: ConditionalNavigationOption<boolean>;
     /** Whether to preserve the current URL. */
     preserveUrl?: ConditionalNavigationOption<boolean>;
@@ -160,16 +166,22 @@ interface NavigationOptions {
      * @internal This is an advanced property meant to be used internally.
      */
     updateHistoryState?: boolean;
+}
+interface InternalNavigationOptions extends NavigationOptions {
     /**
-     * Defines whether this navigation is a back/forward navigation from the popstate event.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines the kind of navigation being performed.
+     * - initial: the initial load's navigation
+     * - server: a navigation initiated by a server round-trip
+     * - local: a navigation initiated by `router.local`
+     * - back-forward: a navigation initiated by the browser's `popstate` event
+     * @internal
      */
-    isBackForward?: boolean;
+    type: 'initial' | 'local' | 'back-forward' | 'server';
     /**
-     * Defines whether this navigation is the first to happen after a direct page load.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines whether this navigation opens a dialog.
+     * @internal
      */
-    isInitial?: boolean;
+    hasDialog?: boolean;
 }
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 interface HybridRequestOptions extends Omit<NavigationOptions, 'payload'> {
@@ -266,15 +278,17 @@ interface PendingNavigation {
     /** Current status. */
     status: 'pending' | 'success' | 'error';
 }
-/** A page or dialog component. */
+/** A view or dialog component. */
 interface View {
     /** Name of the component to use. */
-    component: string;
+    component?: string;
     /** Properties to apply to the component. */
     properties: Properties;
+    /** Deferred properties for this view. */
+    deferred: string[];
 }
-interface Dialog extends View {
-    /** URL that is the base background page when navigating to the dialog directly. */
+interface Dialog extends Required<View> {
+    /** URL that is the base background view when navigating to the dialog directly. */
     baseUrl: string;
     /** URL to which the dialog should redirect when closed. */
     redirectUrl: string;
@@ -294,6 +308,8 @@ interface SwapOptions<T> {
     preserveState?: boolean;
     /** Current dialog. */
     dialog?: Dialog;
+    /** On mounted callback. */
+    onMounted?: (options: MountedHookOptions) => void;
 }
 type ViewComponent = any;
 type ResolveComponent = (name: string) => Promise<ViewComponent>;
@@ -471,12 +487,10 @@ declare const ONLY_DATA_HEADER = "x-hybrid-only-data";
 declare const DIALOG_KEY_HEADER = "x-hybrid-dialog-key";
 declare const DIALOG_REDIRECT_HEADER = "x-hybrid-dialog-redirect";
 declare const EXCEPT_DATA_HEADER = "x-hybrid-except-data";
-declare const CONTEXT_HEADER = "x-hybrid-context";
 declare const VERSION_HEADER = "x-hybrid-version";
 declare const ERROR_BAG_HEADER = "x-hybrid-error-bag";
 declare const SCROLL_REGION_ATTRIBUTE = "scroll-region";
 
-declare const constants_CONTEXT_HEADER: typeof CONTEXT_HEADER;
 declare const constants_DIALOG_KEY_HEADER: typeof DIALOG_KEY_HEADER;
 declare const constants_DIALOG_REDIRECT_HEADER: typeof DIALOG_REDIRECT_HEADER;
 declare const constants_ERROR_BAG_HEADER: typeof ERROR_BAG_HEADER;
@@ -489,7 +503,7 @@ declare const constants_SCROLL_REGION_ATTRIBUTE: typeof SCROLL_REGION_ATTRIBUTE;
 declare const constants_STORAGE_EXTERNAL_KEY: typeof STORAGE_EXTERNAL_KEY;
 declare const constants_VERSION_HEADER: typeof VERSION_HEADER;
 declare namespace constants {
-  export { constants_CONTEXT_HEADER as CONTEXT_HEADER, constants_DIALOG_KEY_HEADER as DIALOG_KEY_HEADER, constants_DIALOG_REDIRECT_HEADER as DIALOG_REDIRECT_HEADER, constants_ERROR_BAG_HEADER as ERROR_BAG_HEADER, constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER, constants_EXTERNAL_NAVIGATION_HEADER as EXTERNAL_NAVIGATION_HEADER, constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER, constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER, constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER, constants_SCROLL_REGION_ATTRIBUTE as SCROLL_REGION_ATTRIBUTE, constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY, constants_VERSION_HEADER as VERSION_HEADER };
+  export { constants_DIALOG_KEY_HEADER as DIALOG_KEY_HEADER, constants_DIALOG_REDIRECT_HEADER as DIALOG_REDIRECT_HEADER, constants_ERROR_BAG_HEADER as ERROR_BAG_HEADER, constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER, constants_EXTERNAL_NAVIGATION_HEADER as EXTERNAL_NAVIGATION_HEADER, constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER, constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER, constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER, constants_SCROLL_REGION_ATTRIBUTE as SCROLL_REGION_ATTRIBUTE, constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY, constants_VERSION_HEADER as VERSION_HEADER };
 }
 
 export { type Authorizable, type DynamicConfiguration, type GlobalRouteCollection, type HybridPayload, type HybridRequestOptions, type MaybePromise, type Method, type NavigationResponse, type Plugin, type Progress, type ResolveComponent, type RouteDefinition, type RouteName, type RouteParameters, type Router, type RouterContext, type RouterContextOptions, type RoutingConfiguration, type UrlResolvable, can, constants, createRouter, definePlugin, getRouterContext, makeUrl, registerHook, route, router, sameUrls };

package/dist/index.mjs

@@ -11,14 +11,12 @@ const ONLY_DATA_HEADER = `${HYBRIDLY_HEADER}-only-data`;
 const DIALOG_KEY_HEADER = `${HYBRIDLY_HEADER}-dialog-key`;
 const DIALOG_REDIRECT_HEADER = `${HYBRIDLY_HEADER}-dialog-redirect`;
 const EXCEPT_DATA_HEADER = `${HYBRIDLY_HEADER}-except-data`;
-const CONTEXT_HEADER = `${HYBRIDLY_HEADER}-context`;
 const VERSION_HEADER = `${HYBRIDLY_HEADER}-version`;
 const ERROR_BAG_HEADER = `${HYBRIDLY_HEADER}-error-bag`;
 const SCROLL_REGION_ATTRIBUTE = "scroll-region";
 
 const constants = {
 	__proto__: null,
-	CONTEXT_HEADER: CONTEXT_HEADER,
 	DIALOG_KEY_HEADER: DIALOG_KEY_HEADER,
 	DIALOG_REDIRECT_HEADER: DIALOG_REDIRECT_HEADER,
 	ERROR_BAG_HEADER: ERROR_BAG_HEADER,
@@ -266,6 +264,7 @@ async function registerEventListeners() {
     if (!state) {
       debug.history("There is no state. Adding hash if any and restoring scroll positions.");
       return await navigate({
+        type: "initial",
         payload: {
           ...context,
           url: makeUrl(context.url, { hash: window.location.hash }).toString()
@@ -276,11 +275,11 @@ async function registerEventListeners() {
       });
     }
     await navigate({
+      type: "back-forward",
       payload: state,
       preserveScroll: true,
       preserveState: !!getInternalRouterContext().dialog || !!state.dialog,
-      updateHistoryState: false,
-      isBackForward: true
+      updateHistoryState: false
     });
   });
   window?.addEventListener("scroll", (event) => debounce(() => {
@@ -303,14 +302,14 @@ async function handleBackForwardNavigation() {
     throw new Error("Tried to handling a back/forward navigation, but there was no state in the history. This should not happen.");
   }
   await navigate({
+    type: "back-forward",
     payload: {
       ...state,
       version: context.version
     },
     preserveScroll: true,
     preserveState: false,
-    updateHistoryState: false,
-    isBackForward: true
+    updateHistoryState: false
   });
 }
 function remember(key, value) {
@@ -600,8 +599,9 @@ async function handleExternalNavigation() {
     url: makeUrl(getRouterContext().url, { hash: window.location.hash }).toString()
   });
   await navigate({
-    preserveScroll: options.preserveScroll,
-    preserveState: true
+    type: "initial",
+    preserveState: true,
+    preserveScroll: options.preserveScroll
   });
 }
 function isExternalNavigation() {
@@ -637,6 +637,27 @@ async function closeDialog(options) {
   });
 }
 
+function isDownloadResponse(response) {
+  return response.status === 200 && !!response.headers["content-disposition"];
+}
+async function handleDownloadResponse(response) {
+  const blob = new Blob([response.data], { type: "application/octet-stream" });
+  const urlObject = window.webkitURL || window.URL;
+  const link = document.createElement("a");
+  link.style.display = "none";
+  link.href = urlObject.createObjectURL(blob);
+  link.download = getFileNameFromContentDispositionHeader(response.headers["content-disposition"]);
+  link.click();
+  setTimeout(() => {
+    urlObject.revokeObjectURL(link.href);
+    link.remove();
+  }, 0);
+}
+function getFileNameFromContentDispositionHeader(header) {
+  const result = header.split(";")[1]?.trim().split("=")[1];
+  return result?.replace(/^"(.*)"$/, "$1") ?? "";
+}
+
 function isPreloaded(targetUrl) {
   const context = getInternalRouterContext();
   return context.preloadCache.has(targetUrl.toString()) ?? false;
@@ -758,10 +779,7 @@ async function performHybridNavigation(options) {
       context.pendingNavigation?.controller?.abort();
     }
     saveScrollPositions();
-    if (options.url && options.transformUrl) {
-      options.url = makeUrl(options.url, options.transformUrl);
-    }
-    const targetUrl = makeUrl(options.url ?? context.url);
+    const targetUrl = makeUrl(options.url ?? context.url, options.transformUrl);
     const abortController = new AbortController();
     setContext({
       pendingNavigation: {
@@ -775,7 +793,10 @@ async function performHybridNavigation(options) {
     await runHooks("start", options.hooks, context);
     debug.router("Making request with axios.");
     const response = await performHybridRequest(targetUrl, options, abortController);
-    await runHooks("data", options.hooks, response, context);
+    const result = await runHooks("data", options.hooks, response, context);
+    if (result === false) {
+      return { response };
+    }
     if (isExternalResponse(response)) {
       debug.router("The response is explicitely external.");
       await performExternalNavigation({
@@ -784,6 +805,11 @@ async function performHybridNavigation(options) {
       });
       return { response };
     }
+    if (isDownloadResponse(response)) {
+      debug.router("The response returns a file to download.");
+      await handleDownloadResponse(response);
+      return { response };
+    }
     if (!isHybridResponse(response)) {
       throw new NotAHybridResponseError(response);
     }
@@ -795,6 +821,7 @@ async function performHybridNavigation(options) {
       debug.router("Merged properties:", payload.view.properties);
     }
     await navigate({
+      type: "server",
       payload: {
         ...payload,
         url: fillHash(targetUrl, payload.url)
@@ -878,6 +905,7 @@ function isHybridResponse(response) {
 }
 async function navigate(options) {
   const context = getRouterContext();
+  options.hasDialog ?? (options.hasDialog = !!options.payload?.dialog);
   debug.router("Making an internal navigation:", { context, options });
   await runHooks("navigating", {}, options, context);
   options.payload ?? (options.payload = payloadFromContext());
@@ -888,6 +916,7 @@ async function navigate(options) {
   const shouldPreserveScroll = evaluateConditionalOption(options.preserveScroll);
   const shouldReplaceHistory = evaluateConditionalOption(options.replace);
   const shouldReplaceUrl = evaluateConditionalOption(options.preserveUrl);
+  const shouldPreserveView = !options.payload.view.component;
   if (shouldPreserveState && getHistoryMemo() && options.payload.view.component === context.view.component) {
     debug.history("Setting the memo from this history entry into the current context.");
     setContext({ memo: getHistoryMemo() });
@@ -896,26 +925,44 @@ async function navigate(options) {
     debug.router(`Preserving the current URL (${context.url}) instead of navigating to ${options.payload.url}`);
     options.payload.url = context.url;
   }
-  setContext({
-    ...options.payload,
-    memo: {}
-  });
+  const payload = shouldPreserveView ? {
+    view: {
+      component: context.view.component,
+      properties: merge(context.view.properties, options.payload.view.properties),
+      deferred: context.view.deferred
+    },
+    url: context.url,
+    version: options.payload.version,
+    dialog: context.dialog
+  } : options.payload;
+  setContext({ ...payload, memo: {} });
   if (options.updateHistoryState !== false) {
     debug.router(`Target URL is ${context.url}, current window URL is ${window.location.href}.`, { shouldReplaceHistory });
     setHistoryState({ replace: shouldReplaceHistory });
   }
-  context.adapter.executeOnMounted(() => {
-    runHooks("mounted", {}, context);
-  });
-  const viewComponent = await context.adapter.resolveComponent(context.view.component);
-  debug.router(`Component [${context.view.component}] resolved to:`, viewComponent);
+  if (context.view.deferred?.length) {
+    debug.router("Request has deferred properties, queueing a partial reload:", context.view.deferred);
+    context.adapter.executeOnMounted(async () => {
+      await performHybridNavigation({
+        preserveScroll: true,
+        preserveState: true,
+        replace: true,
+        only: context.view.deferred
+      });
+    });
+  }
+  const viewComponent = !shouldPreserveView ? await context.adapter.resolveComponent(context.view.component) : void 0;
+  if (viewComponent) {
+    debug.router(`Component [${context.view.component}] resolved to:`, viewComponent);
+  }
   await context.adapter.onViewSwap({
     component: viewComponent,
     dialog: context.dialog,
     properties: options.payload?.view?.properties,
-    preserveState: shouldPreserveState
+    preserveState: shouldPreserveState,
+    onMounted: (hookOptions) => runHooks("mounted", {}, { ...options, ...hookOptions }, context)
   });
-  if (options.isBackForward) {
+  if (options.type === "back-forward") {
     restoreScrollPositions();
   } else if (!shouldPreserveScroll) {
     resetScrollPositions();
@@ -967,12 +1014,12 @@ async function initializeRouter() {
   } else if (isExternalNavigation()) {
     handleExternalNavigation();
   } else {
-    debug.router("Handling the initial page navigation.");
+    debug.router("Handling the initial navigation.");
     setContext({
       url: makeUrl(context.url, { hash: window.location.hash }).toString()
     });
     await navigate({
-      isInitial: true,
+      type: "initial",
       preserveState: true,
       replace: sameUrls(context.url, window.location.href)
     });
@@ -986,13 +1033,15 @@ async function performLocalNavigation(targetUrl, options) {
   const url = normalizeUrl(targetUrl);
   return await navigate({
     ...options,
+    type: "local",
     payload: {
       version: context.version,
       dialog: options?.dialog === false ? void 0 : options?.dialog ?? context.dialog,
       url,
       view: {
         component: options?.component ?? context.view.component,
-        properties: options?.properties ?? {}
+        properties: options?.properties ?? {},
+        deferred: []
       }
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridly/core",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Core functionality of Hybridly",
   "keywords": [
     "hybridly",
@@ -38,7 +38,7 @@
   "dependencies": {
     "qs": "^6.11.2",
     "superjson": "^1.13.1",
-    "@hybridly/utils": "0.4.4"
+    "@hybridly/utils": "0.5.0"
   },
   "devDependencies": {
     "defu": "^6.1.2"