@hybridly/core 0.0.1-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,642 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const axios = require('axios');
+const qs = require('qs');
+const utils = require('@hybridly/utils');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e["default"] : e; }
+
+const axios__default = /*#__PURE__*/_interopDefaultLegacy(axios);
+const qs__default = /*#__PURE__*/_interopDefaultLegacy(qs);
+
+const STORAGE_EXTERNAL_KEY = "hybridly:external";
+const HYBRIDLY_HEADER = "x-hybridly";
+const EXTERNAL_VISIT_HEADER = `${HYBRIDLY_HEADER}-external`;
+const PARTIAL_COMPONENT_HEADER = `${HYBRIDLY_HEADER}-partial-component`;
+const ONLY_DATA_HEADER = `${HYBRIDLY_HEADER}-only-data`;
+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,
+	STORAGE_EXTERNAL_KEY: STORAGE_EXTERNAL_KEY,
+	HYBRIDLY_HEADER: HYBRIDLY_HEADER,
+	EXTERNAL_VISIT_HEADER: EXTERNAL_VISIT_HEADER,
+	PARTIAL_COMPONENT_HEADER: PARTIAL_COMPONENT_HEADER,
+	ONLY_DATA_HEADER: ONLY_DATA_HEADER,
+	EXCEPT_DATA_HEADER: EXCEPT_DATA_HEADER,
+	CONTEXT_HEADER: CONTEXT_HEADER,
+	VERSION_HEADER: VERSION_HEADER,
+	ERROR_BAG_HEADER: ERROR_BAG_HEADER,
+	SCROLL_REGION_ATTRIBUTE: SCROLL_REGION_ATTRIBUTE
+};
+
+class NotAHybridlyResponseError extends Error {
+  constructor(response) {
+    super();
+    this.response = response;
+  }
+}
+class VisitCancelledError extends Error {
+}
+
+function saveScrollPositions() {
+  const regions = getScrollRegions();
+  utils.debug.scroll("Saving scroll positions of:", regions);
+  setContext({
+    scrollRegions: regions.map(({ scrollTop, scrollLeft }) => ({
+      top: scrollTop,
+      left: scrollLeft
+    }))
+  });
+  setHistoryState({ replace: true });
+}
+function getScrollRegions() {
+  return Array.from(document?.querySelectorAll(`[${SCROLL_REGION_ATTRIBUTE}]`) ?? []);
+}
+function resetScrollPositions() {
+  utils.debug.scroll("Resetting scroll positions.");
+  getScrollRegions().concat(document.documentElement, document.body).forEach((element) => {
+    element.scrollTop = 0;
+    element.scrollLeft = 0;
+  });
+  saveScrollPositions();
+  if (window.location.hash) {
+    utils.debug.scroll(`Hash is present, scrolling to the element of ID ${window.location.hash}.`);
+    document.getElementById(window.location.hash.slice(1))?.scrollIntoView();
+  }
+}
+async function restoreScrollPositions() {
+  utils.debug.scroll("Restoring scroll positions stored in the context.");
+  const context = getRouterContext();
+  const regions = getScrollRegions();
+  if (!context.scrollRegions) {
+    return;
+  }
+  let tries = 0;
+  const timer = setInterval(() => {
+    if (context.scrollRegions.length !== regions.length) {
+      if (++tries > 20) {
+        utils.debug.scroll("The limit of tries has been reached. Cancelling scroll restoration.");
+        clearInterval(timer);
+        return;
+      }
+      utils.debug.scroll(`The scroll regions count do not match. Waiting for page to fully load (try #${tries}).`);
+      return;
+    }
+    clearInterval(timer);
+    regions.forEach((el, i) => el.scrollTo({
+      top: context.scrollRegions.at(i)?.top ?? el.scrollTop,
+      left: context.scrollRegions.at(i)?.top ?? el.scrollLeft
+    }));
+  }, 50);
+}
+
+function normalizeUrl(href) {
+  return makeUrl(href).toString();
+}
+function makeUrl(href, transformations = {}) {
+  try {
+    const base = document?.location?.href === "//" ? void 0 : document.location.href;
+    const url = new URL(String(href), base);
+    Object.entries(transformations ?? {}).forEach(([key, value]) => Reflect.set(url, key, value));
+    return url;
+  } catch (error) {
+    throw new TypeError(`${href} is not resolvable to a valid URL.`);
+  }
+}
+function sameUrls(...hrefs) {
+  if (hrefs.length < 2) {
+    return true;
+  }
+  try {
+    return hrefs.every((href) => {
+      return makeUrl(href, { hash: "" }).toJSON() === makeUrl(hrefs.at(0), { hash: "" }).toJSON();
+    });
+  } catch {
+  }
+  return false;
+}
+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();
+}
+
+function setHistoryState(options = {}) {
+  if (!window?.history) {
+    throw new Error("The history API is not available, so Hybridly cannot operate.");
+  }
+  const context = getRouterContext();
+  const method = options.replace ? "replaceState" : "pushState";
+  const serialized = serializeContext(context);
+  utils.debug.history("Setting history state:", {
+    method,
+    context,
+    serialized
+  });
+  try {
+    window.history[method](serialized, "", context.url);
+  } catch (error) {
+    console.error("Hybridly could not save its current state in the history. This is most likely due to a property being non-serializable, such as a proxy or a reference.");
+    throw error;
+  }
+}
+function getHistoryState(key) {
+  const state = key ? window.history.state?.state?.[key] : window.history.state?.state;
+  return getRouterContext().serializer.unserialize(state);
+}
+async function registerEventListeners() {
+  const context = getRouterContext();
+  utils.debug.history("Registering [popstate] and [scroll] event listeners.");
+  window?.addEventListener("popstate", async (event) => {
+    utils.debug.history("Navigation detected (popstate event). State:", { state: event.state });
+    if (!event.state) {
+      utils.debug.history("There is no state. Adding hash if any and restoring scroll positions.");
+      return await navigate({
+        payload: {
+          ...context,
+          url: makeUrl(context.url, { hash: window.location.hash }).toString()
+        },
+        preserveScroll: true,
+        preserveState: true,
+        replace: true
+      });
+    }
+    await navigate({
+      payload: event.state,
+      preserveScroll: true,
+      preserveState: false,
+      updateHistoryState: false,
+      isBackForward: true
+    });
+  });
+  window?.addEventListener("scroll", (event) => utils.debounce(() => {
+    if (event?.target?.hasAttribute?.(SCROLL_REGION_ATTRIBUTE)) {
+      saveScrollPositions();
+    }
+  }, 100), true);
+}
+function isBackForwardVisit() {
+  if (!window.history.state) {
+    return false;
+  }
+  return window.performance?.getEntriesByType("navigation").at(0)?.type === "back_forward";
+}
+async function handleBackForwardVisit() {
+  utils.debug.router("Handling a back/forward visit.");
+  window.history.state.version = getRouterContext().version;
+  await navigate({
+    preserveScroll: true,
+    preserveState: true
+  });
+}
+function remember(key, value) {
+  utils.debug.history(`Remembering key "${key}" with value`, value);
+  setContext({
+    state: {
+      ...getRouterContext().state,
+      [key]: value
+    }
+  }, { propagate: false });
+  setHistoryState({ replace: true });
+}
+function getKeyFromHistory(key) {
+  return getHistoryState(key);
+}
+function serializeContext(context) {
+  return {
+    url: context.url,
+    version: context.version,
+    view: context.serializer.serialize(context.view),
+    dialog: context.dialog,
+    scrollRegions: context.scrollRegions,
+    state: context.serializer.serialize(context.state)
+  };
+}
+function createSerializer(options) {
+  if (options.serializer) {
+    return options.serializer;
+  }
+  return {
+    serialize: (view) => JSON.parse(JSON.stringify(view)),
+    unserialize: (state) => state
+  };
+}
+
+const state = {
+  initialized: false,
+  context: {}
+};
+function getRouterContext() {
+  return getInternalRouterContext();
+}
+function getInternalRouterContext() {
+  if (!state.initialized) {
+    throw new Error("Hybridly is not initialized.");
+  }
+  return state.context;
+}
+async function initializeContext(options) {
+  state.initialized = true;
+  state.context = {
+    ...options.payload,
+    serializer: createSerializer(options),
+    url: makeUrl(options.payload.url).toString(),
+    adapter: options.adapter,
+    scrollRegions: [],
+    plugins: options.plugins ?? [],
+    hooks: {},
+    state: {}
+  };
+  for (const plugin of state.context.plugins) {
+    utils.debug.plugin(plugin.name, 'Calling "initialized" hook.');
+    await plugin.initialized?.(state.context);
+  }
+  return getInternalRouterContext();
+}
+function setContext(merge = {}, options = {}) {
+  Object.keys(merge).forEach((key) => {
+    Reflect.set(state.context, key, merge[key]);
+  });
+  if (options.propagate !== false) {
+    state.context.adapter.update?.(state.context);
+  }
+  utils.debug.context("Updated context:", { context: state.context, added: merge });
+}
+function payloadFromContext() {
+  return {
+    url: getRouterContext().url,
+    version: getRouterContext().version,
+    view: getRouterContext().view,
+    dialog: getRouterContext().dialog
+  };
+}
+
+async function performExternalVisit(options) {
+  utils.debug.external("Making a hard navigation for an external visit:", options);
+  window.sessionStorage.setItem(STORAGE_EXTERNAL_KEY, JSON.stringify(options));
+  window.location.href = options.url;
+  if (sameUrls(window.location, options.url)) {
+    utils.debug.external("Manually reloading due to the external URL being the same.");
+    window.location.reload();
+  }
+}
+function isExternalResponse(response) {
+  return response?.status === 409 && !!response?.headers?.[EXTERNAL_VISIT_HEADER];
+}
+async function handleExternalVisit() {
+  utils.debug.external("Handling an external visit.");
+  const options = JSON.parse(window.sessionStorage.getItem(STORAGE_EXTERNAL_KEY) || "{}");
+  window.sessionStorage.removeItem(STORAGE_EXTERNAL_KEY);
+  utils.debug.external("Options from the session storage:", options);
+  setContext({
+    url: makeUrl(getRouterContext().url, { hash: window.location.hash }).toString()
+  });
+  await navigate({
+    preserveScroll: options.preserveScroll,
+    preserveState: true
+  });
+}
+function isExternalVisit() {
+  try {
+    return window.sessionStorage.getItem(STORAGE_EXTERNAL_KEY) !== null;
+  } catch {
+  }
+  return false;
+}
+
+function definePlugin(plugin) {
+  return plugin;
+}
+async function runPluginHooks(hook, ...args) {
+  const { plugins } = getRouterContext();
+  let result = true;
+  for (const plugin of plugins) {
+    if (plugin.hooks[hook]) {
+      utils.debug.plugin(plugin.name, `Calling "${hook}" hooks.`);
+      result = await plugin.hooks[hook]?.(...args) ?? result;
+    }
+  }
+  return result;
+}
+async function runGlobalHooks(hook, ...args) {
+  const { hooks } = getRouterContext();
+  if (!hooks[hook]) {
+    return true;
+  }
+  let result = true;
+  for (const fn of hooks[hook]) {
+    utils.debug.hook(`Calling global "${hook}" hooks.`);
+    result = await fn(...args) ?? result;
+  }
+  return result;
+}
+async function runHooks(hook, requestHooks, ...args) {
+  const result = await Promise.all([
+    requestHooks?.[hook]?.(...args),
+    runGlobalHooks(hook, ...args),
+    runPluginHooks(hook, ...args)
+  ]);
+  return !result.includes(false);
+}
+
+function registerHook(hook, fn) {
+  const hooks = getRouterContext().hooks;
+  hooks[hook] = [...hooks[hook] ?? [], fn];
+  return () => hooks[hook]?.splice(hooks[hook].indexOf(fn), 1);
+}
+function registerHookOnce(hook, fn) {
+  const unregister = registerHook(hook, async (...args) => {
+    await fn(...args);
+    unregister();
+  });
+}
+
+const router = {
+  abort: async () => getRouterContext().activeVisit?.controller.abort(),
+  active: () => !!getRouterContext().activeVisit,
+  visit: async (options) => await visit(options),
+  reload: async (options) => await visit({ preserveScroll: true, preserveState: true, ...options }),
+  get: async (url, options = {}) => await visit({ ...options, url, method: "GET" }),
+  post: async (url, options = {}) => await visit({ preserveState: true, ...options, url, method: "POST" }),
+  put: async (url, options = {}) => await visit({ preserveState: true, ...options, url, method: "PUT" }),
+  patch: async (url, options = {}) => await visit({ preserveState: true, ...options, url, method: "PATCH" }),
+  delete: async (url, options = {}) => await visit({ preserveState: true, ...options, url, method: "DELETE" }),
+  local: async (url, options) => await performLocalComponentVisit(url, options),
+  external: (url, data = {}) => performLocalExternalVisit(url, data),
+  history: {
+    get: (key) => getKeyFromHistory(key),
+    remember: (key, value) => remember(key, value)
+  }
+};
+async function createRouter(options) {
+  await initializeContext(options);
+  return await initializeRouter();
+}
+async function visit(options) {
+  const visitId = utils.random();
+  const context = getRouterContext();
+  utils.debug.router("Making a visit:", { context, options, visitId });
+  try {
+    if ((utils.hasFiles(options.data) || options.useFormData) && !(options.data instanceof FormData)) {
+      options.data = utils.objectToFormData(options.data);
+      utils.debug.router("Converted data to FormData.", options.data);
+    }
+    if (!await runHooks("before", options.hooks, options)) {
+      utils.debug.router('"before" event returned false, aborting the visit.');
+      throw new VisitCancelledError('The visit was cancelled by the "before" event.');
+    }
+    if (context.activeVisit) {
+      utils.debug.router("Aborting current visit.", context.activeVisit);
+      context.activeVisit?.controller.abort();
+    }
+    saveScrollPositions();
+    if (options.url && options.transformUrl) {
+      options.url = makeUrl(options.url, options.transformUrl);
+    }
+    setContext({
+      activeVisit: {
+        id: visitId,
+        url: makeUrl(options.url ?? context.url),
+        controller: new AbortController(),
+        options
+      }
+    });
+    await runHooks("start", options.hooks, context);
+    utils.debug.router("Making request with axios.");
+    const response = await axios__default.request({
+      url: context.activeVisit.url.toString(),
+      method: options.method ?? "GET",
+      data: options.method === "GET" ? {} : options.data,
+      params: options.method === "GET" ? options.data : {},
+      signal: context.activeVisit.controller.signal,
+      headers: {
+        ...options.headers,
+        ...utils.when(options.only !== void 0 || options.except !== void 0, {
+          [PARTIAL_COMPONENT_HEADER]: context.view.name,
+          ...utils.when(options.only, { [ONLY_DATA_HEADER]: JSON.stringify(options.only) }, {}),
+          ...utils.when(options.except, { [EXCEPT_DATA_HEADER]: JSON.stringify(options.except) }, {})
+        }, {}),
+        ...utils.when(options.errorBag, { [ERROR_BAG_HEADER]: options.errorBag }, {}),
+        ...utils.when(context.version, { [VERSION_HEADER]: context.version }, {}),
+        [HYBRIDLY_HEADER]: true,
+        "X-Requested-With": "XMLHttpRequest",
+        "Accept": "text/html, application/xhtml+xml"
+      },
+      validateStatus: () => true,
+      onUploadProgress: async (event) => {
+        await runHooks("progress", options.hooks, {
+          event,
+          percentage: Math.round(event.loaded / (event.total ?? 0) * 100)
+        });
+      }
+    });
+    await runHooks("data", options.hooks, response);
+    if (isExternalResponse(response)) {
+      utils.debug.router("The response is explicitely external.");
+      await performExternalVisit({
+        url: fillHash(context.activeVisit.url, response.headers[EXTERNAL_VISIT_HEADER]),
+        preserveScroll: options.preserveScroll === true
+      });
+      return { response };
+    }
+    if (!isHybridlyResponse(response)) {
+      throw new NotAHybridlyResponseError(response);
+    }
+    utils.debug.router("The response respects the hybridly protocol.");
+    const payload = response.data;
+    if ((options.only?.length ?? options.except?.length) && payload.view.name === context.view.name) {
+      utils.debug.router(`Merging ${options.only ? '"only"' : '"except"'} properties.`, payload.view.properties);
+      payload.view.properties = utils.merge(context.view.properties, payload.view.properties);
+      utils.debug.router("Merged properties:", payload.view.properties);
+    }
+    await navigate({
+      payload: {
+        ...payload,
+        url: fillHash(context.activeVisit.url, payload.url)
+      },
+      preserveScroll: options.preserveScroll === true,
+      preserveState: options.preserveState,
+      preserveUrl: options.preserveUrl,
+      replace: options.replace === true || sameUrls(payload.url, window.location.href) || options.preserveUrl
+    });
+    if (Object.keys(context.view.properties.errors ?? {}).length > 0) {
+      const errors = (() => {
+        if (options.errorBag && typeof context.view.properties.errors === "object") {
+          return context.view.properties.errors[options.errorBag] ?? {};
+        }
+        return context.view.properties.errors;
+      })();
+      utils.debug.router("The request returned validation errors.", errors);
+      await runHooks("error", options.hooks, errors);
+      setContext({
+        activeVisit: {
+          ...context.activeVisit,
+          status: "error"
+        }
+      });
+    } else {
+      await runHooks("success", options.hooks, payload);
+      setContext({
+        activeVisit: {
+          ...context.activeVisit,
+          status: "success"
+        }
+      });
+    }
+    return { response };
+  } catch (error) {
+    await utils.match(error.constructor.name, {
+      VisitCancelledError: async () => {
+        utils.debug.router('The request was cancelled through the "before" hook.', error);
+        console.warn(error);
+        await runHooks("abort", options.hooks, context);
+      },
+      AbortError: async () => {
+        utils.debug.router("The request was cancelled.", error);
+        console.warn(error);
+        await runHooks("abort", options.hooks, context);
+      },
+      NotAHybridlyResponseError: async () => {
+        utils.debug.router("The request was not hybridly.");
+        console.error(error);
+        await runHooks("invalid", options.hooks, error);
+        utils.showResponseErrorModal(error.response.data);
+      },
+      default: async () => {
+        utils.debug.router("An unknown error occured.", error);
+        console.error(error);
+        await runHooks("exception", options.hooks, error);
+      }
+    });
+    await runHooks("fail", options.hooks, context);
+    return {
+      error: {
+        type: error.constructor.name,
+        actual: error
+      }
+    };
+  } finally {
+    utils.debug.router("Ending visit.");
+    await runHooks("after", options.hooks, context);
+    if (context.activeVisit?.id === visitId) {
+      setContext({ activeVisit: void 0 });
+    }
+  }
+}
+function isHybridlyResponse(response) {
+  return !!response?.headers[HYBRIDLY_HEADER];
+}
+async function navigate(options) {
+  const context = getRouterContext();
+  utils.debug.router("Making an internal navigation:", { context, options });
+  options.payload ?? (options.payload = payloadFromContext());
+  const evaluateConditionalOption = (option) => typeof option === "function" ? option(options.payload) : option;
+  const shouldPreserveState = evaluateConditionalOption(options.preserveState);
+  const shouldPreserveScroll = evaluateConditionalOption(options.preserveScroll);
+  const shouldReplaceHistory = evaluateConditionalOption(options.replace);
+  const shouldReplaceUrl = evaluateConditionalOption(options.preserveUrl);
+  if (shouldPreserveState && getHistoryState() && options.payload.view.name === context.view.name) {
+    setContext({ state: getHistoryState() });
+  }
+  if (shouldReplaceUrl) {
+    utils.debug.router(`Preserving the current URL (${context.url}) instead of navigating to ${options.payload.url}`);
+    options.payload.url = context.url;
+  }
+  setContext({
+    ...options.payload,
+    state: {}
+  }, { propagate: false });
+  if (options.updateHistoryState !== false) {
+    utils.debug.router(`Target URL is ${context.url}, current window URL is ${window.location.href}.`, { shouldReplaceHistory });
+    setHistoryState({ replace: shouldReplaceHistory });
+  }
+  const viewComponent = await context.adapter.resolveComponent(context.view.name);
+  utils.debug.router(`Component [${context.view.name}] resolved to:`, viewComponent);
+  await context.adapter.swapView({
+    component: viewComponent,
+    preserveState: shouldPreserveState
+  });
+  if (context.dialog) {
+    const dialogComponent = await context.adapter.resolveComponent(context.dialog.name);
+    utils.debug.router(`Dialog [${context.view.name}] resolved to:`, dialogComponent);
+    await context.adapter.swapDialog({
+      component: dialogComponent,
+      preserveState: shouldPreserveState
+    });
+  }
+  setContext();
+  if (!shouldPreserveScroll) {
+    resetScrollPositions();
+  } else {
+    restoreScrollPositions();
+  }
+  await runHooks("navigate", {}, options);
+}
+async function initializeRouter() {
+  const context = getRouterContext();
+  if (isBackForwardVisit()) {
+    handleBackForwardVisit();
+  } else if (isExternalVisit()) {
+    handleExternalVisit();
+  } else {
+    utils.debug.router("Handling the initial page visit.");
+    setContext({
+      url: makeUrl(context.url, { hash: window.location.hash }).toString()
+    });
+    await navigate({
+      preserveState: true,
+      replace: sameUrls(context.url, window.location.href)
+    });
+  }
+  registerEventListeners();
+  return context;
+}
+async function performLocalComponentVisit(targetUrl, options) {
+  const context = getRouterContext();
+  const url = normalizeUrl(targetUrl);
+  return await navigate({
+    ...options,
+    payload: {
+      version: context.version,
+      dialog: context.dialog,
+      url,
+      view: {
+        name: options.component ?? context.view.name,
+        properties: options.properties
+      }
+    }
+  });
+}
+function performLocalExternalVisit(url, data) {
+  document.location.href = makeUrl(url, {
+    search: qs__default.stringify(data, {
+      encodeValuesOnly: true,
+      arrayFormat: "brackets"
+    })
+  }).toString();
+}
+
+function can(resource, action) {
+  return resource.authorization?.[action] ?? false;
+}
+
+exports.can = can;
+exports.constants = constants;
+exports.createRouter = createRouter;
+exports.definePlugin = definePlugin;
+exports.getRouterContext = getRouterContext;
+exports.makeUrl = makeUrl;
+exports.registerHook = registerHook;
+exports.registerHookOnce = registerHookOnce;
+exports.router = router;
+exports.sameUrls = sameUrls;