@jsenv/navi 0.0.1

package/src/browser_integration/via_navigation.js

@@ -0,0 +1,168 @@
+import { updateDocumentUrl } from "./document_url_signal.js";
+
+let DEBUG = false;
+
+export const setupRoutingViaNavigation = (handler) => {
+  updateDocumentUrl(navigation.currentEntry.url);
+  navigation.addEventListener("currententrychange", () => {
+    updateDocumentUrl(navigation.currentEntry.url);
+  });
+
+  let isReloadFromNavigationAPI = false;
+  const navigationReload = navigation.reload;
+  navigation.reload = (...args) => {
+    isReloadFromNavigationAPI = true;
+    navigationReload.call(navigation, ...args);
+    isReloadFromNavigationAPI = false;
+  };
+
+  navigation.addEventListener("navigate", (event) => {
+    if (!event.canIntercept) {
+      return;
+    }
+    if (event.hashChange || event.downloadRequest !== null) {
+      return;
+    }
+    if (
+      !event.userInitiated &&
+      event.navigationType === "reload" &&
+      event.isTrusted &&
+      !isReloadFromNavigationAPI
+    ) {
+      // let window.location.reload() reload the whole document
+      // (used by jsenv hot reload)
+      return;
+    }
+    const { signal } = event;
+    const formAction = event.info?.formAction;
+    const isReload = event.navigationType === "reload";
+    const isReplace = event.navigationType === "replace";
+    const currentUrl = navigation.currentEntry.url;
+    const destinationUrl = event.destination.url;
+    const currentState = navigation.currentEntry.getState();
+    const destinationState = event.destination.getState();
+    const formData = event.formData || event.info?.formData;
+    const formUrl = event.info?.formUrl;
+    const stopAbortController = new AbortController();
+    const stopSignal = stopAbortController.signal;
+    const removeStopButtonClickDetector = detectBrowserStopButtonClick(
+      signal,
+      () => {
+        stopAbortController.abort("stop button clicked");
+      },
+    );
+
+    if (DEBUG) {
+      console.log("receive navigate event", {
+        destinationUrl,
+        destinationState,
+      });
+    }
+
+    event.intercept({
+      handler: async () => {
+        if (event.info?.onStart) {
+          event.info.onStart();
+        }
+        try {
+          await handler(event, {
+            abortSignal: signal,
+            stopSignal,
+            formAction,
+            formData,
+            formUrl,
+            isReload,
+            isReplace,
+            currentUrl,
+            destinationUrl,
+            currentState,
+            destinationState,
+          });
+        } catch (e) {
+          console.error(e); // browser remains silent in case of error during handler so we explicitely log the error to the console
+          throw e;
+        } finally {
+          removeStopButtonClickDetector();
+        }
+      },
+      // https://github.com/WICG/navigation-api?tab=readme-ov-file#focus-management
+      // without this, after clicking <a href="...">, the focus does to document.body
+      // which is problematic for shortcuts for instance
+      focusReset: "manual",
+    });
+  });
+};
+
+// setupNavigateHandler(async (event, { stopSignal, formAction, formData }) => {
+//   if (formAction) {
+//     const result = await applyAction(formAction, {
+//       signal: stopSignal,
+//       formData,
+//     });
+//     event.info.formActionCallback(result);
+//   }
+
+//   await navMethods.applyRouting({
+//     sourceUrl: currentUrl,
+//     targetUrl: formUrl || destinationUrl,
+//     sourceState: currentState,
+//     targetState: destinationState || currentState,
+//     abortSignal,
+//     stopSignal,
+//     isReload,
+//     isReplace,
+//     info: event.info,
+//   });
+//   if (formUrl) {
+//     const finishedPromise = event.target.transition.finished;
+//     (async () => {
+//       try {
+//         await finishedPromise;
+//       } finally {
+//         navigation.navigate(window.location.href, {
+//           state: navigation.currentEntry.getState(),
+//           history: "replace",
+//         });
+//       }
+//     })();
+//   }
+// });
+
+/**
+ * There is 2 distinct reason to abort a navigation:
+ * - the user clicked the browser stop button
+ * - the user navigate to an other page
+ *
+ * When navigating to an other page we don't want to abort anything, the routing does that
+ * When clicking the stop button we want to cancel everything
+ *
+ * To detect that when aborted, we wait a setTimeout to see if we receive a new navigation
+ * If yes it means this is an abort due to a new navigation
+ * Otherwise it's an abort due to the stop button
+ *
+ * On top of that stop button must cancel X navigation so the last navigation detecting the stop click
+ * is notifying any current navigation that stop button was clicked
+ */
+let callEffect = () => {};
+const browserStopButtonClickCallbackSet = new Set();
+const detectBrowserStopButtonClick = (navigateEventSignal, callback) => {
+  callEffect();
+  browserStopButtonClickCallbackSet.add(callback);
+  navigateEventSignal.addEventListener("abort", async () => {
+    const timeout = setTimeout(() => {
+      callEffect = () => {};
+
+      for (const browserStopButtonClickCallback of browserStopButtonClickCallbackSet) {
+        browserStopButtonClickCallback();
+      }
+      browserStopButtonClickCallbackSet.clear();
+    });
+    callEffect = () => {
+      clearTimeout(timeout);
+    };
+  });
+
+  return () => {
+    browserStopButtonClickCallbackSet.delete(callback);
+  };
+};

package/src/components/action_execution/form_context.js

@@ -0,0 +1,8 @@
+import { createContext } from "preact";
+import { useContext } from "preact/hooks";
+
+export const FormContext = createContext();
+
+export const useFormContext = () => {
+  return useContext(FormContext);
+};

package/src/components/action_execution/render_actionable_component.jsx

@@ -0,0 +1,27 @@
+import { useFormContext } from "./form_context.js";
+
+export const renderActionableComponent = (
+  props,
+  ref,
+  { Basic, WithAction, InsideForm, WithActionInsideForm },
+) => {
+  const { action, shortcuts, ignoreForm } = props;
+  const formContext = useFormContext();
+  const hasActionProps = Boolean(action || (shortcuts && shortcuts.length > 0));
+  const considerInsideForm = ignoreForm ? false : Boolean(formContext);
+
+  if (hasActionProps && WithAction) {
+    if (considerInsideForm && WithActionInsideForm) {
+      return (
+        <WithActionInsideForm formContext={formContext} ref={ref} {...props} />
+      );
+    }
+    return <WithAction ref={ref} {...props} />;
+  }
+
+  if (considerInsideForm && InsideForm) {
+    return <InsideForm formContext={formContext} ref={ref} {...props} />;
+  }
+
+  return <Basic ref={ref} {...props} />;
+};

package/src/components/action_execution/use_action.js

@@ -0,0 +1,330 @@
+import { signal } from "@preact/signals";
+import { useCallback, useRef } from "preact/hooks";
+import { createAction } from "../../actions.js";
+import { addIntoArray, removeFromArray } from "../../utils/array_add_remove.js";
+import { isSignal } from "../../utils/stringify_for_display.js";
+import { useInitialValue } from "../use_initial_value.js";
+import { useFormContext } from "./form_context.js";
+
+let debug = false;
+let componentActionIdCounter = 0;
+const useComponentActionCacheKey = () => {
+  const componentActionCacheKeyRef = useRef(null);
+  // It's very important to use an object here as componentId and not just in integer
+  // because this key will be used as a key in a WeakMap
+  // and if we pass an integer the browser allows itself to garbage collect it
+  // but not if it's an object as the useRef above keeps referencing it
+  // this is a subtle different and might be the reason why WeakMap does not accept primitive as keys
+  if (!componentActionCacheKeyRef.current) {
+    const id = ++componentActionIdCounter;
+    componentActionCacheKeyRef.current = {
+      id,
+      toString: () => `component_action_id_${id}`,
+    };
+  }
+  return componentActionCacheKeyRef.current;
+};
+
+// used by <form> to have their own action bound to many parameters
+// any form element within the <form> will update these params
+// these params are also assigned just before executing the action to ensure they are in sync
+// (could also be used by <fieldset> but I think fieldset are not going to be used this way and
+// we will reserve this behavior to <form>)
+export const useFormActionBoundToFormParams = (action) => {
+  const actionCacheKey = useComponentActionCacheKey();
+  const cacheKey = typeof action === "function" ? actionCacheKey : action;
+  const [formParamsSignal, updateFormParams] = useActionParamsSignal(cacheKey);
+  const formActionBoundActionToFormParams = useBoundAction(
+    action,
+    formParamsSignal,
+  );
+  return [
+    formActionBoundActionToFormParams,
+    formParamsSignal,
+    updateFormParams,
+  ];
+};
+export const useOneFormParam = (
+  name,
+  externalValue,
+  fallbackValue,
+  defaultValue,
+) => {
+  const { formParamsSignal } = useFormContext();
+  const previousFormParamsSignalRef = useRef(null);
+  const formActionChanged =
+    previousFormParamsSignalRef.current !== null &&
+    previousFormParamsSignalRef.current !== formParamsSignal;
+  previousFormParamsSignalRef.current = formParamsSignal;
+
+  const getValue = useCallback(
+    () => formParamsSignal.value[name],
+    [formParamsSignal],
+  );
+  const setValue = useCallback(
+    (value) => updateParamsSignal(formParamsSignal, { [name]: value }),
+    [formParamsSignal],
+  );
+
+  const initialValue = useInitialValue(
+    name,
+    externalValue,
+    fallbackValue,
+    defaultValue,
+    setValue,
+  );
+  if (formActionChanged) {
+    if (debug) {
+      console.debug(
+        `useOneFormParam(${name}) form action changed, re-initializing with: ${initialValue}`,
+      );
+    }
+    setValue(initialValue);
+  }
+
+  const resetValue = useCallback(() => {
+    setValue(initialValue);
+  }, [initialValue, formParamsSignal]);
+
+  return [getValue(), setValue, resetValue];
+};
+
+// used by form elements such as <input>, <select>, <textarea> to have their own action bound to a single parameter
+// when inside a <form> the form params are updated when the form element single param is updated
+export const useActionBoundToOneParam = (
+  action,
+  name,
+  externalValue,
+  fallbackValue,
+  defaultValue,
+) => {
+  const externalValueIsSignal = isSignal(externalValue);
+  let externalValueSignal;
+  if (externalValueIsSignal) {
+    externalValueSignal = externalValue;
+    externalValue = externalValueSignal.peek();
+  }
+
+  if (action.isProxy && !externalValueSignal) {
+    throw new Error(
+      `useActionBoundToOneParam(${name}) action is a proxy but no valueSignal provided`,
+    );
+  }
+
+  const actionCacheKey = useComponentActionCacheKey();
+  const cacheKey = typeof action === "function" ? actionCacheKey : action;
+  const [paramsSignal, updateParams] = useActionParamsSignal(
+    cacheKey,
+    externalValueSignal,
+  );
+  const previousParamsSignalRef = useRef(null);
+  const actionChanged =
+    previousParamsSignalRef.current !== null &&
+    previousParamsSignalRef.current !== paramsSignal;
+  previousParamsSignalRef.current = paramsSignal;
+
+  const boundAction = useBoundAction(
+    action,
+    externalValueSignal ? null : paramsSignal,
+  );
+  const getValue = externalValueSignal
+    ? useCallback(() => paramsSignal.value, [paramsSignal])
+    : useCallback(() => paramsSignal.value[name], [paramsSignal]);
+  const setValue = externalValueSignal
+    ? useCallback(
+        (value) => {
+          paramsSignal.value = value;
+        },
+        [paramsSignal],
+      )
+    : useCallback(
+        (value) => {
+          if (debug) {
+            console.debug(
+              `useActionBoundToOneParam(${name}) set value to ${value} (old value is ${getValue()} )`,
+            );
+          }
+          return updateParams({ [name]: value });
+        },
+        [updateParams],
+      );
+
+  const initialValue = useInitialValue(
+    name,
+    externalValue,
+    fallbackValue,
+    defaultValue,
+    setValue,
+  );
+  if (actionChanged) {
+    if (debug) {
+      console.debug(
+        `useActionBoundToOneParam(${name}) action changed, re-initializing with: ${initialValue}`,
+      );
+    }
+    setValue(initialValue);
+  }
+
+  const reset = useCallback(() => {
+    setValue(initialValue);
+  }, [initialValue, paramsSignal]);
+
+  return [boundAction, getValue(), setValue, reset];
+};
+
+// export const useActionBoundToOneBooleanParam = (action, name, value) => {
+//   const [boundAction, getValue, setValue, resetValue] =
+//     useActionBoundToOneParam(action, name, Boolean(value));
+
+//   return [
+//     boundAction,
+//     () => Boolean(getValue()),
+//     (value) => setValue(Boolean(value)),
+//     resetValue,
+//   ];
+// };
+
+export const useActionBoundToOneArrayParam = (
+  action,
+  name,
+  initialValue,
+  fallbackValue,
+  defaultValue = [],
+) => {
+  const [boundAction, value, setValue, resetValue] = useActionBoundToOneParam(
+    action,
+    name,
+    initialValue,
+    fallbackValue,
+    defaultValue,
+  );
+
+  const add = (valueToAdd, valueArray = value) => {
+    setValue(addIntoArray(valueArray, valueToAdd));
+  };
+
+  const remove = (valueToRemove, valueArray = value) => {
+    setValue(removeFromArray(valueArray, valueToRemove));
+  };
+
+  return [boundAction, value, add, remove, resetValue];
+};
+export const useOneFormArrayParam = (
+  name,
+  initialValue,
+  fallbackValue,
+  defaultValue = [],
+) => {
+  const [getValue, setValue, resetValue] = useOneFormParam(
+    name,
+    initialValue,
+    fallbackValue,
+    defaultValue,
+  );
+  const add = (valueToAdd, valueArray = getValue()) => {
+    setValue(addIntoArray(valueArray, valueToAdd));
+  };
+  const remove = (valueToRemove, valueArray = getValue()) => {
+    setValue(removeFromArray(valueArray, valueToRemove));
+  };
+  return [getValue, add, remove, resetValue];
+};
+
+// used by <details> to just call their action
+export const useAction = (action, paramsSignal) => {
+  return useBoundAction(action, paramsSignal);
+};
+
+const sharedSignalCache = new WeakMap();
+const useActionParamsSignal = (cacheKey, valueSignal) => {
+  if (valueSignal) {
+    return [
+      valueSignal,
+      (value) => {
+        valueSignal.value = value;
+      },
+    ];
+  }
+
+  // ✅ cacheKey peut être componentId (Symbol) ou action (objet)
+  const fromCache = sharedSignalCache.get(cacheKey);
+  if (fromCache) {
+    return fromCache;
+  }
+
+  const paramsSignal = signal({});
+  const result = [
+    paramsSignal,
+    (value) => updateParamsSignal(paramsSignal, value, cacheKey),
+  ];
+  sharedSignalCache.set(cacheKey, result);
+  if (debug) {
+    console.debug(`Created params signal for ${cacheKey} with params:`, {});
+  }
+  return result;
+};
+
+export const updateParamsSignal = (paramsSignal, object, cacheKey) => {
+  const currentParams = paramsSignal.peek();
+  const paramsCopy = { ...currentParams };
+  let modified = false;
+  for (const key of Object.keys(object)) {
+    const value = object[key];
+    const currentValue = currentParams[key];
+    if (Object.hasOwn(currentParams, key)) {
+      if (value !== currentValue) {
+        modified = true;
+        paramsCopy[key] = value;
+      }
+    } else {
+      modified = true;
+      paramsCopy[key] = value;
+    }
+  }
+  if (modified) {
+    if (debug) {
+      console.debug(
+        `Updating params for ${cacheKey} with new params:`,
+        object,
+        `result:`,
+        paramsCopy,
+      );
+    }
+    paramsSignal.value = paramsCopy;
+  } else if (debug) {
+    console.debug(
+      `No change in params for ${cacheKey}, not updating.`,
+      `current params:`,
+      currentParams,
+      `new params:`,
+      object,
+    );
+  }
+};
+
+const useBoundAction = (action, actionParamsSignal) => {
+  const actionRef = useRef();
+  const actionCallbackRef = useRef();
+
+  if (!action) {
+    return null;
+  }
+  if (typeof action === "function" && !action.isAction) {
+    let actionInstance = actionRef.current;
+    if (!actionInstance) {
+      actionInstance = createAction((...args) => {
+        return actionCallbackRef.current(...args);
+      });
+      if (actionParamsSignal) {
+        actionInstance = actionInstance.bindParams(actionParamsSignal);
+      }
+      actionRef.current = actionInstance;
+    }
+    actionCallbackRef.current = action;
+    return actionInstance;
+  }
+  if (actionParamsSignal) {
+    return action.bindParams(actionParamsSignal);
+  }
+  return action;
+};

package/src/components/action_execution/use_execute_action.js

@@ -0,0 +1,161 @@
+import { addCustomMessage, removeCustomMessage } from "@jsenv/validation";
+import { useCallback, useLayoutEffect, useRef, useState } from "preact/hooks";
+import { useResetErrorBoundary } from "../error_boundary_context.js";
+
+let debug = false;
+
+export const useExecuteAction = (
+  elementRef,
+  {
+    errorEffect = "show_validation_message", // "show_validation_message" or "throw"
+  } = {},
+) => {
+  // see https://medium.com/trabe/catching-asynchronous-errors-in-react-using-error-boundaries-5e8a5fd7b971
+  // and https://codepen.io/dmail/pen/XJJqeGp?editors=0010
+  // To change if https://github.com/preactjs/preact/issues/4754 lands
+  const [error, setError] = useState(null);
+  const resetErrorBoundary = useResetErrorBoundary();
+  useLayoutEffect(() => {
+    if (error) {
+      error.__handled__ = true; // prevent jsenv from displaying it
+      throw error;
+    }
+  }, [error]);
+
+  const validationMessageTargetRef = useRef(null);
+  const addErrorMessage = (error) => {
+    const validationMessageTarget = validationMessageTargetRef.current;
+    addCustomMessage(validationMessageTarget, "action_error", error, {
+      // This error should not prevent <form> submission
+      // so whenever user tries to submit the form the error is cleared
+      // (Hitting enter key, clicking on submit button, etc. would allow to re-submit the form in error state)
+      removeOnRequestAction: true,
+    });
+  };
+  const removeErrorMessage = () => {
+    const validationMessageTarget = validationMessageTargetRef.current;
+    if (validationMessageTarget) {
+      removeCustomMessage(validationMessageTarget, "action_error");
+    }
+  };
+
+  useLayoutEffect(() => {
+    const element = elementRef.current;
+    if (!element) {
+      return null;
+    }
+    const form = element.tagName === "FORM" ? element : element.form;
+    if (!form) {
+      return null;
+    }
+    const onReset = () => {
+      removeErrorMessage();
+    };
+    form.addEventListener("reset", onReset);
+    return () => {
+      form.removeEventListener("reset", onReset);
+    };
+  });
+
+  const executeAction = useCallback((actionEvent) => {
+    const { action, requester, event, method } = actionEvent.detail;
+
+    if (debug) {
+      console.debug(
+        "executing action, requested by",
+        requester,
+        `(event: ${event?.type})`,
+      );
+    }
+
+    const dispatchCustomEvent = (type, options) => {
+      const element = elementRef.current;
+      const customEvent = new CustomEvent(type, options);
+      element.dispatchEvent(customEvent);
+    };
+    if (resetErrorBoundary) {
+      resetErrorBoundary();
+    }
+    removeErrorMessage();
+    setError(null);
+
+    const validationMessageTarget = requester || elementRef.current;
+    validationMessageTargetRef.current = validationMessageTarget;
+
+    dispatchCustomEvent("actionstart", {
+      detail: {
+        action,
+        requester,
+        event,
+        method,
+      },
+    });
+
+    return action[method]({
+      onAbort: (reason) => {
+        if (
+          // at this stage the action side effect might have removed the <element> from the DOM
+          // (in theory no because action side effect are batched to happen after)
+          // but other side effects might do this
+          elementRef.current
+        ) {
+          dispatchCustomEvent("actionabort", {
+            detail: {
+              reason,
+
+              action,
+              requester,
+              event,
+              method,
+            },
+          });
+        }
+      },
+      onError: (error) => {
+        if (
+          // at this stage the action side effect might have removed the <element> from the DOM
+          // (in theory no because action side effect are batched to happen after)
+          // but other side effects might do this
+          elementRef.current
+        ) {
+          dispatchCustomEvent("actionerror", {
+            detail: {
+              error,
+
+              action,
+              requester,
+              event,
+              method,
+            },
+          });
+        }
+        if (errorEffect === "show_validation_message") {
+          addErrorMessage(error);
+        } else if (errorEffect === "throw") {
+          setError(error);
+        }
+      },
+      onComplete: (data) => {
+        if (
+          // at this stage the action side effect might have removed the <element> from the DOM
+          // (in theory no because action side effect are batched to happen after)
+          // but other side effects might do this
+          elementRef.current
+        ) {
+          dispatchCustomEvent("actionend", {
+            detail: {
+              data,
+
+              action,
+              requester,
+              event,
+              method,
+            },
+          });
+        }
+      },
+    });
+  }, []);
+
+  return executeAction;
+};