@hybridly/core 0.10.0-beta.11 → 0.10.0-beta.13

package/dist/_chunks/chunk.mjs

@@ -1,4 +1,4 @@
-import "node:module";
+//#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -9,4 +9,5 @@ var __exportAll = (all, no_symbols) => {
 	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
+//#endregion
 export { __exportAll as t };

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { debounce, debug, hasFiles, match, merge, objectToFormData, random, remo
 import axios from "axios";
 import { parse, stringify } from "superjson";
 import qs from "qs";
+//#region src/constants.ts
 var constants_exports = /* @__PURE__ */ __exportAll({
 	DIALOG_KEY_HEADER: () => DIALOG_KEY_HEADER,
 	DIALOG_REDIRECT_HEADER: () => DIALOG_REDIRECT_HEADER,
@@ -29,6 +30,8 @@ const EXCEPT_DATA_HEADER = `${HYBRIDLY_HEADER}-except-data`;
 const VERSION_HEADER = `${HYBRIDLY_HEADER}-version`;
 const ERROR_BAG_HEADER = `${HYBRIDLY_HEADER}-error-bag`;
 const SCROLL_REGION_ATTRIBUTE = "scroll-region";
+//#endregion
+//#region src/errors.ts
 var NotAHybridResponseError = class extends Error {
 	constructor(response) {
 		super();
@@ -51,6 +54,8 @@ var MissingRouteParameter = class extends Error {
 		super(`Parameter [${parameter}] is required for route [${routeName}].`);
 	}
 };
+//#endregion
+//#region src/plugins/plugin.ts
 function definePlugin(plugin) {
 	return plugin;
 }
@@ -87,6 +92,11 @@ async function runHooks(hook, requestHooks, ...args) {
 	debug.hook(`Called all hooks for [${hook}],`, result);
 	return !result.includes(false);
 }
+//#endregion
+//#region src/plugins/hooks.ts
+/**
+* Registers a global hook.
+*/
 function appendCallbackToHooks(hook, fn) {
 	const hooks = getRouterContext().hooks;
 	hooks[hook] = [...hooks[hook] ?? [], fn];
@@ -95,6 +105,9 @@ function appendCallbackToHooks(hook, fn) {
 		if (index !== -1) hooks[hook]?.splice(index, 1);
 	};
 }
+/**
+* Registers a global hook.
+*/
 function registerHook(hook, fn, options) {
 	if (options?.once) {
 		const unregister = appendCallbackToHooks(hook, async (...args) => {
@@ -105,6 +118,9 @@ function registerHook(hook, fn, options) {
 	}
 	return appendCallbackToHooks(hook, fn);
 }
+//#endregion
+//#region src/scroll.ts
+/** Saves the current view's scrollbar positions into the history state. */
 function saveScrollPositions() {
 	const regions = getScrollRegions();
 	debug.scroll("Saving scroll positions of:", regions.map((el) => ({
@@ -120,9 +136,14 @@ function saveScrollPositions() {
 	})) });
 	setHistoryState({ replace: true });
 }
+/** Gets DOM elements which scroll positions should be saved. */
 function getScrollRegions() {
-	return Array.from(document?.querySelectorAll(`[${SCROLL_REGION_ATTRIBUTE}]`) ?? []).concat(document.documentElement, document.body);
+	return Array.from(document?.querySelectorAll(`[scroll-region]`) ?? []).concat(document.documentElement, document.body);
 }
+/**
+* Resets the current view's scrollbars positions to the top, and save them
+* in the history state.
+*/
 function resetScrollPositions() {
 	debug.scroll("Resetting scroll positions.");
 	getScrollRegions().forEach((element) => element.scrollTo({
@@ -135,6 +156,7 @@ function resetScrollPositions() {
 		document.getElementById(window.location.hash.slice(1))?.scrollIntoView();
 	}
 }
+/** Restores the scroll positions stored in the context. */
 async function restoreScrollPositions() {
 	const context = getRouterContext();
 	const regions = getScrollRegions();
@@ -150,9 +172,15 @@ async function restoreScrollPositions() {
 		}));
 	});
 }
+//#endregion
+//#region src/url.ts
+/** Normalizes the given input to an URL. */
 function normalizeUrl(href, trailingSlash) {
 	return makeUrl(href, { trailingSlash }).toString();
 }
+/**
+* Converts an input to an URL, optionally changing its properties after initialization.
+*/
 function makeUrl(href, transformations = {}) {
 	try {
 		const base = document?.location?.href === "//" ? void 0 : document.location.href;
@@ -179,6 +207,9 @@ function makeUrl(href, transformations = {}) {
 		throw new TypeError(`${href} is not resolvable to a valid URL.`);
 	}
 }
+/**
+* Checks if the given URLs have the same origin and path.
+*/
 function sameUrls(...hrefs) {
 	if (hrefs.length < 2) return true;
 	try {
@@ -188,6 +219,9 @@ function sameUrls(...hrefs) {
 	} catch {}
 	return false;
 }
+/**
+* Checks if the given URLs have the same origin, path, and hash.
+*/
 function sameHashes(...hrefs) {
 	if (hrefs.length < 2) return true;
 	try {
@@ -197,12 +231,20 @@ function sameHashes(...hrefs) {
 	} catch {}
 	return false;
 }
+/**
+* If the back-end did not specify a hash, if the navigation specified one,
+* and both URLs lead to the same endpoint, we update the target URL
+* to use the hash of the initially-requested URL.
+*/
 function fillHash(currentUrl, targetUrl) {
 	currentUrl = makeUrl(currentUrl);
 	targetUrl = makeUrl(targetUrl);
 	if (currentUrl.hash && !targetUrl.hash && sameUrls(targetUrl, currentUrl)) targetUrl.hash = currentUrl.hash;
 	return targetUrl.toString();
 }
+//#endregion
+//#region src/router/history.ts
+/** Puts the given context into the history state. */
 function setHistoryState(options = {}) {
 	if (!window?.history) throw new Error("The history API is not available, so Hybridly cannot operate.");
 	const context = getRouterContext();
@@ -219,13 +261,16 @@ function setHistoryState(options = {}) {
 		throw error;
 	}
 }
+/** Gets the current history data if it exists. */
 function getHistoryState() {
 	return getRouterContext().serializer.unserialize(window.history.state);
 }
+/** Gets the current history state if it exists. */
 function getHistoryMemo(key) {
 	const state = getHistoryState();
 	return key ? state?.memo?.[key] : state?.memo;
 }
+/** Register history-related event listeneners. */
 async function registerEventListeners() {
 	const context = getRouterContext();
 	debug.history("Registering [popstate] and [scroll] event listeners.");
@@ -259,13 +304,15 @@ async function registerEventListeners() {
 		});
 	});
 	window?.addEventListener("scroll", (event) => debounce(100, () => {
-		if ((event?.target)?.hasAttribute?.(SCROLL_REGION_ATTRIBUTE)) saveScrollPositions();
+		if ((event?.target)?.hasAttribute?.("scroll-region")) saveScrollPositions();
 	}), true);
 }
+/** Checks if the current navigation was made by going back or forward. */
 function isBackForwardNavigation() {
 	if (!window.history.state) return false;
 	return (window.performance?.getEntriesByType("navigation").at(0))?.type === "back_forward";
 }
+/** Handles a navigation which was going back or forward. */
 async function handleBackForwardNavigation() {
 	debug.router("Handling a back/forward navigation from an external URL.");
 	const context = getRouterContext();
@@ -282,6 +329,7 @@ async function handleBackForwardNavigation() {
 		updateHistoryState: false
 	});
 }
+/** Saves a value into the current history state. */
 function remember(key, value) {
 	debug.history(`Remembering key "${key}" with value`, value);
 	setContext({ memo: {
@@ -290,6 +338,7 @@ function remember(key, value) {
 	} }, { propagate: false });
 	setHistoryState({ replace: true });
 }
+/** Serializes the context so it can be written to the history state. */
 function serializeContext(context) {
 	return context.serializer.serialize({
 		url: context.url,
@@ -316,6 +365,8 @@ function createSerializer(options) {
 		}
 	};
 }
+//#endregion
+//#region src/routing/route.ts
 function getUrlRegexForRoute(name) {
 	const routing = getRouting();
 	const definition = getRouteDefinition(name);
@@ -333,6 +384,12 @@ function getUrlRegexForRoute(name) {
 	});
 	return RegExp(urlRegexPattern);
 }
+/**
+* Check if a given URL matches a route based on its name.
+* Additionally you can pass an object of parameters to check if the URL matches the route with the given parameters.
+* Otherwise it will accept and thus return true for any values for the parameters defined by the route.
+* Note: passing additional parameters that are not defined by the route or included in the current URL will cause this to return false.
+*/
 function urlMatchesRoute(fullUrl, name, routeParameters) {
 	const url = makeUrl(fullUrl, { hash: "" }).toString();
 	const parameters = routeParameters || {};
@@ -369,6 +426,9 @@ function getUrlFromName(name, parameters, shouldThrow) {
 		...transforms
 	}));
 }
+/**
+* Resolved the value of a route parameter from either the passed parameters or the default parameters.
+*/
 function getRouteParameterValue(routeName, parameterName, routeParameters) {
 	const routing = getRouting();
 	const definition = getRouteDefinition(routeName);
@@ -386,6 +446,9 @@ function getRouteParameterValue(routeName, parameterName, routeParameters) {
 	}
 	if (routing.defaults?.[parameterName]) return routing.defaults?.[parameterName];
 }
+/**
+* Gets the `UrlTransformable` object for the given route and parameters.
+*/
 function getRouteTransformable(routeName, routeParameters, shouldThrow) {
 	const definition = getRouteDefinition(routeName);
 	const parameters = routeParameters || {};
@@ -415,23 +478,44 @@ function getRouteTransformable(routeName, routeParameters, shouldThrow) {
 		})
 	};
 }
+/**
+* Gets the route definition.
+*/
 function getRouteDefinition(name) {
 	const definition = getRouting().routes[name];
 	if (!definition) throw new RouteNotFound(name);
 	return definition;
 }
+/**
+* Gets the routing configuration from the current context.
+*/
 function getRouting() {
 	const { routing } = getInternalRouterContext();
 	if (!routing) throw new RoutingNotInitialized();
 	return routing;
 }
+/**
+* Generates a route from the given route name.
+*/
 function route(name, parameters, absolute) {
 	return generateRouteFromName(name, parameters, absolute ?? getRouting().absolute ?? true);
 }
+//#endregion
+//#region src/routing/current.ts
 function getCurrentUrl() {
 	if (typeof window === "undefined") return getInternalRouterContext().url;
 	return window.location.toString();
 }
+/**
+* Determines whether the current route matches the given name and parameters.
+* If multiple routes match, the first one will be returned.
+*
+* @example
+* ```ts
+* currentRouteMatches('tenant.*') // matches all routes starting with 'tenant.'
+* currentRouteMatches('tenant.*.admin') // matches all routes starting with 'tenant.' and ending with '.admin'
+* ```
+*/
 function currentRouteMatches(name, parameters) {
 	const namePattern = `^${name.replaceAll(".", "\\.").replaceAll("*", ".*")}$`;
 	const possibleRoutes = Object.values(getRouting().routes).filter((x) => x.method.includes("GET") && RegExp(namePattern).test(x.name)).map((x) => x.name);
@@ -443,13 +527,19 @@ function currentRouteMatches(name, parameters) {
 function getCurrentRouteName() {
 	return getNameFromUrl(getCurrentUrl());
 }
+//#endregion
+//#region src/routing/index.ts
 function updateRoutingConfiguration(routing) {
 	if (!routing) return;
 	setContext({ routing });
 }
+//#endregion
+//#region src/download.ts
+/** Checks if the response wants to redirect to an external URL. */
 function isDownloadResponse(response) {
 	return response.status === 200 && !!response.headers["content-disposition"];
 }
+/** Handles a download. */
 async function handleDownloadResponse(response) {
 	const blob = new Blob([response.data], { type: response.headers["content-type"] });
 	const urlObject = window.webkitURL || window.URL;
@@ -466,17 +556,22 @@ async function handleDownloadResponse(response) {
 function getFileNameFromContentDispositionHeader(header) {
 	return (header.split(";")[1]?.trim().split("=")[1])?.replace(/^"(.*)"$/, "$1") ?? "";
 }
+//#endregion
+//#region src/context/context.ts
 const state = {
 	initialized: false,
 	context: {}
 };
+/** Gets the current context. */
 function getRouterContext() {
 	return getInternalRouterContext();
 }
+/** Gets the current context, but not in read-only. */
 function getInternalRouterContext() {
 	if (!state.initialized) throw new Error("Hybridly is not initialized.");
 	return state.context;
 }
+/** Initializes the context. */
 async function initializeContext(options) {
 	state.initialized = true;
 	state.context = {
@@ -499,6 +594,10 @@ async function initializeContext(options) {
 	await runHooks("initialized", {}, state.context);
 	return getInternalRouterContext();
 }
+/**
+* Registers an interceptor that assumes `arraybuffer`
+* responses and converts responses to JSON or text.
+*/
 function registerAxios(axios) {
 	axios.interceptors.response.use((response) => {
 		if (!isDownloadResponse(response)) {
@@ -513,6 +612,9 @@ function registerAxios(axios) {
 	}, (error) => Promise.reject(error));
 	return axios;
 }
+/**
+* Mutates properties at the top-level of the context.
+*/
 function setContext(merge = {}, options = {}) {
 	Object.keys(merge).forEach((key) => {
 		Reflect.set(state.context, key, merge[key]);
@@ -523,6 +625,7 @@ function setContext(merge = {}, options = {}) {
 		added: merge
 	});
 }
+/** Gets a payload from the current context. */
 function payloadFromContext() {
 	return {
 		url: getRouterContext().url,
@@ -531,6 +634,13 @@ function payloadFromContext() {
 		dialog: getRouterContext().dialog
 	};
 }
+//#endregion
+//#region src/external.ts
+/**
+* Performs an external navigation by saving options to the storage and
+* making a full page reload. Upon loading, the navigation options
+* will be pulled and a hybrid navigation will be made.
+*/
 async function performExternalNavigation(options) {
 	debug.external("Navigating to an external URL:", options);
 	if (options.target === "new-tab") {
@@ -549,18 +659,24 @@ async function performExternalNavigation(options) {
 		window.location.reload();
 	}
 }
+/** Navigates to the given URL without the hybrid protocol. */
 function navigateToExternalUrl(url, data) {
 	document.location.href = makeUrl(url, { search: qs.stringify(data, {
 		encodeValuesOnly: true,
 		arrayFormat: "brackets"
 	}) }).toString();
 }
+/** Checks if the response wants to redirect to an external URL. */
 function isExternalResponse(response) {
 	return response?.status === 409 && !!response?.headers?.[EXTERNAL_NAVIGATION_HEADER];
 }
+/**
+* Performs the internal navigation when an external navigation to a hybrid view has been made.
+* This method is meant to be called on router creation.
+*/
 async function handleExternalNavigation() {
 	debug.external("Handling an external navigation.");
-	const options = JSON.parse(window.sessionStorage.getItem(STORAGE_EXTERNAL_KEY) || "{}");
+	const options = JSON.parse(window.sessionStorage.getItem("hybridly:external") || "{}");
 	window.sessionStorage.removeItem(STORAGE_EXTERNAL_KEY);
 	debug.external("Options from the session storage:", options);
 	setContext({ url: makeUrl(getRouterContext().url, { hash: window.location.hash }).toString() });
@@ -570,12 +686,18 @@ async function handleExternalNavigation() {
 		preserveScroll: options.preserveScroll
 	});
 }
+/** Checks if the navigation being initialized points to an external location. */
 function isExternalNavigation() {
 	try {
 		return window.sessionStorage.getItem(STORAGE_EXTERNAL_KEY) !== null;
 	} catch {}
 	return false;
 }
+//#endregion
+//#region src/dialog/index.ts
+/**
+* Closes the dialog.
+*/
 async function closeDialog(options) {
 	const context = getInternalRouterContext();
 	const url = context.dialog?.redirectUrl ?? context.dialog?.baseUrl;
@@ -596,18 +718,33 @@ async function closeDialog(options) {
 		...options
 	});
 }
+//#endregion
+//#region src/router/preload.ts
+/**
+* Checks if there is a preloaded request for the given URL.
+*/
 function isPreloaded(targetUrl) {
 	return getInternalRouterContext().preloadCache.has(targetUrl.toString()) ?? false;
 }
+/**
+* Gets the response of a preloaded request.
+*/
 function getPreloadedRequest(targetUrl) {
 	return getInternalRouterContext().preloadCache.get(targetUrl.toString());
 }
+/**
+* Stores the response of a preloaded request.
+*/
 function storePreloadRequest(targetUrl, response) {
 	getInternalRouterContext().preloadCache.set(targetUrl.toString(), response);
 }
+/**
+* Discards a preloaded request.
+*/
 function discardPreloadedRequest(targetUrl) {
 	return getInternalRouterContext().preloadCache.delete(targetUrl.toString());
 }
+/** Preloads a hybrid request. */
 async function performPreloadRequest(options) {
 	const context = getRouterContext();
 	const url = makeUrl(options.url ?? context.url);
@@ -637,6 +774,17 @@ async function performPreloadRequest(options) {
 		return false;
 	}
 }
+//#endregion
+//#region src/router/router.ts
+/**
+* The hybridly router.
+* This is the core function that you can use to navigate in
+* your application. Make sure the routes you call return a
+* hybrid response, otherwise you need to call `external`.
+*
+* @example
+* router.get('/posts/edit', { post })
+*/
 const router = {
 	abort: async () => getRouterContext().pendingNavigation?.controller.abort(),
 	active: () => !!getRouterContext().pendingNavigation,
@@ -700,10 +848,12 @@ const router = {
 		remember: (key, value) => remember(key, value)
 	}
 };
+/** Creates the hybridly router. */
 async function createRouter(options) {
 	await initializeContext(options);
 	return await initializeRouter();
 }
+/** Performs every action necessary to make a hybrid navigation. */
 async function performHybridNavigation(options) {
 	const navigationId = random();
 	const context = getRouterContext();
@@ -854,9 +1004,14 @@ async function performHybridNavigation(options) {
 		if (context.pendingNavigation?.id === navigationId) setContext({ pendingNavigation: void 0 });
 	}
 }
+/** Checks if the response contains a hybrid header. */
 function isHybridResponse(response) {
 	return !!response?.headers[HYBRIDLY_HEADER];
 }
+/**
+* Makes an internal navigation that swaps the view and updates the context.
+* @internal
+*/
 async function navigate(options) {
 	const context = getRouterContext();
 	options.hasDialog ??= !!options.payload?.dialog;
@@ -966,6 +1121,7 @@ async function performHybridRequest(targetUrl, options, abortController) {
 		}
 	});
 }
+/** Initializes the router by reading the context and registering events if necessary. */
 async function initializeRouter() {
 	const context = getRouterContext();
 	if (isBackForwardNavigation()) handleBackForwardNavigation();
@@ -983,6 +1139,7 @@ async function initializeRouter() {
 	await runHooks("ready", {}, context);
 	return context;
 }
+/** Performs a local navigation to the given component without a round-trip. */
 async function performLocalNavigation(targetUrl, options) {
 	const context = getRouterContext();
 	const url = normalizeUrl(targetUrl);
@@ -1001,7 +1158,14 @@ async function performLocalNavigation(targetUrl, options) {
 		}
 	});
 }
+//#endregion
+//#region src/authorization.ts
+/**
+* Checks whether the given data has the authorization for the given action.
+* If the data object has no authorization definition corresponding to the given action, this method will return `false`.
+*/
 function can(resource, action) {
 	return resource.authorization?.[action] ?? false;
 }
+//#endregion
 export { can, constants_exports as constants, createRouter, definePlugin, getRouterContext, makeUrl, registerHook, route, router, sameUrls };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hybridly/core",
   "type": "module",
-  "version": "0.10.0-beta.11",
+  "version": "0.10.0-beta.13",
   "description": "Core functionality of Hybridly",
   "author": "Enzo Innocenzi <enzo@innocenzi.dev>",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "axios": "^1.7.2"
   },
   "dependencies": {
-    "@hybridly/utils": "0.10.0-beta.11",
+    "@hybridly/utils": "0.10.0-beta.13",
     "qs": "^6.14.0",
     "superjson": "^2.2.2"
   },