@jsenv/navi 0.0.1 → 0.1.1

package/src/components/action_execution/use_action.js

@@ -1,200 +1,38 @@
-import { signal } from "@preact/signals";
+import { useSignal } 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);
+export const useActionBoundToOneParam = (action, externalValue) => {
+  const actionFirstArgSignal = useSignal(externalValue);
+  const boundAction = useBoundAction(action, actionFirstArgSignal);
+  const getValue = useCallback(() => actionFirstArgSignal.value, []);
+  const setValue = useCallback((value) => {
+    actionFirstArgSignal.value = value;
+  }, []);
+  const externalValueRef = useRef(externalValue);
+  if (externalValue !== externalValueRef.current) {
+    externalValueRef.current = externalValue;
+    setValue(externalValue);
   }
 
-  const reset = useCallback(() => {
-    setValue(initialValue);
-  }, [initialValue, paramsSignal]);
-
-  return [boundAction, getValue(), setValue, reset];
+  const value = getValue();
+  return [boundAction, value, setValue];
 };
-
-// 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,
+  externalValue,
   fallbackValue,
-  defaultValue = [],
+  defaultValue,
 ) => {
-  const [boundAction, value, setValue, resetValue] = useActionBoundToOneParam(
+  const [boundAction, value, setValue, initialValue] = useActionBoundToOneParam(
     action,
     name,
-    initialValue,
+    externalValue,
     fallbackValue,
     defaultValue,
   );
@@ -207,101 +45,16 @@ export const useActionBoundToOneArrayParam = (
     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];
+  const result = [boundAction, value, setValue, initialValue];
+  result.add = add;
+  result.remove = remove;
+  return result;
 };
-
 // 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();
@@ -309,22 +62,38 @@ const useBoundAction = (action, actionParamsSignal) => {
   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;
-    }
+  if (isFunctionButNotAnActionFunction(action)) {
     actionCallbackRef.current = action;
-    return actionInstance;
+    const existingAction = actionRef.current;
+    if (existingAction) {
+      return existingAction;
+    }
+    const actionFromFunction = createAction(
+      (...args) => {
+        return actionCallbackRef.current?.(...args);
+      },
+      {
+        name: action.name,
+        // We don't want to give empty params by default
+        // we want to give undefined for regular functions
+        params: undefined,
+      },
+    );
+    if (!actionParamsSignal) {
+      actionRef.current = actionFromFunction;
+      return actionFromFunction;
+    }
+    const actionBoundToParams =
+      actionFromFunction.bindParams(actionParamsSignal);
+    actionRef.current = actionBoundToParams;
+    return actionBoundToParams;
   }
   if (actionParamsSignal) {
     return action.bindParams(actionParamsSignal);
   }
   return action;
 };
+
+const isFunctionButNotAnActionFunction = (action) => {
+  return typeof action === "function" && !action.isAction;
+};

package/src/components/action_execution/use_execute_action.js

@@ -1,5 +1,8 @@
-import { addCustomMessage, removeCustomMessage } from "@jsenv/validation";
 import { useCallback, useLayoutEffect, useRef, useState } from "preact/hooks";
+import {
+  addCustomMessage,
+  removeCustomMessage,
+} from "../../validation/custom_message.js";
 import { useResetErrorBoundary } from "../error_boundary_context.js";
 
 let debug = false;
@@ -57,105 +60,116 @@ export const useExecuteAction = (
     };
   });
 
-  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: {
+  // const errorEffectRef = useRef();
+  // errorEffectRef.current = errorEffect;
+  const executeAction = useCallback(
+    (actionEvent) => {
+      const { action, actionOrigin, requester, event, method } =
+        actionEvent.detail;
+      const sharedActionEventDetail = {
         action,
+        actionOrigin,
         requester,
         event,
         method,
-      },
-    });
+      };
+
+      if (debug) {
+        console.debug(
+          "executing action, requested by",
+          requester,
+          `(event: ${event?.type})`,
+        );
+      }
 
-    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,
+      const dispatchCustomEvent = (type, options) => {
+        const element = elementRef.current;
+        const customEvent = new CustomEvent(type, options);
+        element.dispatchEvent(customEvent);
+      };
+      if (resetErrorBoundary) {
+        resetErrorBoundary();
+      }
+      removeErrorMessage();
+      setError(null);
 
-              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,
+      const validationMessageTarget = requester || elementRef.current;
+      validationMessageTargetRef.current = validationMessageTarget;
 
-              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,
+      dispatchCustomEvent("actionstart", {
+        detail: sharedActionEventDetail,
+      });
 
-              action,
-              requester,
-              event,
-              method,
-            },
-          });
-        }
-      },
-    });
-  }, []);
+      return action[method]({
+        reason: `"${event.type}" event on ${(() => {
+          const target = event.target;
+          const tagName = target.tagName.toLowerCase();
+
+          if (target.id) {
+            return `${tagName}#${target.id}`;
+          }
+
+          const uiName = target.getAttribute("data-ui-name");
+          if (uiName) {
+            return `${tagName}[data-ui-name="${uiName}"]`;
+          }
+
+          return `<${tagName}>`;
+        })()}`,
+        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: {
+                ...sharedActionEventDetail,
+                reason,
+              },
+            });
+          }
+        },
+        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: {
+                ...sharedActionEventDetail,
+                error,
+              },
+            });
+          }
+          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: {
+                ...sharedActionEventDetail,
+                data,
+              },
+            });
+          }
+        },
+      });
+    },
+    [errorEffect],
+  );
 
   return executeAction;
 };

package/src/components/action_execution/use_run_on_mount.js

@@ -0,0 +1,9 @@
+import { useEffect } from "preact/hooks";
+
+export const useRunOnMount = (action, Component) => {
+  useEffect(() => {
+    action.run({
+      reason: `<${Component.name} /> mounted`,
+    });
+  }, []);
+};

package/src/components/action_renderer.jsx

@@ -1,27 +1,3 @@
-/**
- * TODO: when switching from one state to another we should preserve the dimensions to prevent layout shift
- * the exact way to do this is not yet clear but I suspect something as follow:
- *
- *
- * While content is loading we don't know (except if we are given an size)
- * When reloading the content will be gone, we should keep a placeholder taking the same space
- * When there is an error the error should take the same space as the content
- * but be displayed on top
- * (If error is bigger it can take more space? I guess so, maybe an overflow would be better to prevent layout shit again)
- *
- * And once we know the new content size ideally we could have some sort of transition
- * (like an height transition from current height to new height)
- *
- * consider https://motion.dev/docs/react-layout-animations
- *
- * but might be too complexe for what we want.
- * we want ability to transit from anything to anything, it's not a layout change
- * it's more view transition but with a very simple behavior
- *
- * And certainly this https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API#pseudo-elements
- *
- */
-
 import { useErrorBoundary, useLayoutEffect } from "preact/hooks";
 import { getActionPrivateProperties } from "../action_private_properties.js";
 import { useActionStatus } from "../use_action_status.js";
@@ -45,7 +21,7 @@ const renderErrorDefault = (error) => {
 };
 const renderCompletedDefault = () => null;
 
-export const ActionRenderer = ({ action, children }) => {
+export const ActionRenderer = ({ action, children, disabled }) => {
   const {
     idle: renderIdle = renderIdleDefault,
     loading: renderLoading = renderLoadingDefault,
@@ -54,7 +30,12 @@ export const ActionRenderer = ({ action, children }) => {
     completed: renderCompleted,
     always: renderAlways,
   } = typeof children === "function" ? { completed: children } : children || {};
-  if (!action) {
+
+  if (disabled) {
+    return null;
+  }
+
+  if (action === undefined) {
     throw new Error(
       "ActionRenderer requires an action to render, but none was provided.",
     );
@@ -67,8 +48,10 @@ export const ActionRenderer = ({ action, children }) => {
   // This tells the action system that errors should be caught and stored
   // in the action's error state rather than bubbling up
   useLayoutEffect(() => {
-    const { ui } = getActionPrivateProperties(action);
-    ui.hasRenderers = true;
+    if (action) {
+      const { ui } = getActionPrivateProperties(action);
+      ui.hasRenderers = true;
+    }
   }, [action]);
 
   useLayoutEffect(() => {
@@ -80,7 +63,7 @@ export const ActionRenderer = ({ action, children }) => {
     return () => {
       actionUIRenderedPromiseWeakMap.delete(action);
     };
-  }, []);
+  }, [action]);
 
   // If renderAlways is provided, it wins and handles all rendering
   if (renderAlways) {
@@ -120,9 +103,15 @@ export const ActionRenderer = ({ action, children }) => {
   return renderCompletedSafe(data, action);
 };
 
+const defaultPromise = Promise.resolve();
+defaultPromise.resolve = () => {};
+
 const actionUIRenderedPromiseWeakMap = new WeakMap();
-const useUIRenderedPromise = (route) => {
-  const actionUIRenderedPromise = actionUIRenderedPromiseWeakMap.get(route);
+const useUIRenderedPromise = (action) => {
+  if (!action) {
+    return defaultPromise;
+  }
+  const actionUIRenderedPromise = actionUIRenderedPromiseWeakMap.get(action);
   if (actionUIRenderedPromise) {
     return actionUIRenderedPromise;
   }
@@ -131,6 +120,6 @@ const useUIRenderedPromise = (route) => {
     resolve = res;
   });
   promise.resolve = resolve;
-  actionUIRenderedPromiseWeakMap.set(route, promise);
+  actionUIRenderedPromiseWeakMap.set(action, promise);
   return promise;
 };