@jsenv/navi 0.0.1 → 0.1.0

package/src/components/use_auto_focus.js

@@ -3,6 +3,27 @@
 
 import { useEffect, useLayoutEffect } from "preact/hooks";
 
+let blurEvent = null;
+let timeout;
+document.body.addEventListener(
+  "blur",
+  (e) => {
+    blurEvent = e;
+    setTimeout(() => {
+      blurEvent = null;
+    });
+  },
+  { capture: true },
+);
+document.body.addEventListener(
+  "focus",
+  () => {
+    clearTimeout(timeout);
+    blurEvent = null;
+  },
+  { capture: true },
+);
+
 export const useAutoFocus = (
   focusableElementRef,
   autoFocus,
@@ -21,19 +42,49 @@ export const useAutoFocus = (
       focusableElement.scrollLeft = 0;
     }
     return () => {
-      if (
+      const focusIsOnSelfOrInsideSelf =
         document.activeElement === focusableElement ||
-        document.activeElement === document.body
+        focusableElement.contains(document.activeElement);
+      if (
+        !focusIsOnSelfOrInsideSelf &&
+        document.activeElement !== document.body
       ) {
-        // if the input is focused when the component is unmounted,
-        // we restore focus to the element that was focused before
-        // the input was focused
-        if (document.body.contains(activeElement)) {
-          activeElement.focus();
+        // focus is not on our element (or body) anymore
+        // keep it where it is
+        return;
+      }
+
+      // We have focus but we are unmounted
+      // -> try to move focus back to something more meaningful that what browser would do
+      // (browser would put it to document.body)
+      // -> We'll try to move focus back to the element that had focus before we moved it to this element
+
+      if (!document.body.contains(activeElement)) {
+        // previously active element is no longer in the document
+        return;
+      }
+
+      if (blurEvent) {
+        // But if this element is unmounted during a blur, the element that is about to receive focus should prevail
+        const elementAboutToReceiveFocus = blurEvent.relatedTarget;
+        const isSelfOrInsideSelf =
+          elementAboutToReceiveFocus === focusableElement ||
+          focusableElement.contains(elementAboutToReceiveFocus);
+        const isPreviouslyActiveElementOrInsideIt =
+          elementAboutToReceiveFocus === activeElement ||
+          (activeElement && activeElement.contains(elementAboutToReceiveFocus));
+        if (!isSelfOrInsideSelf && !isPreviouslyActiveElementOrInsideIt) {
+          // the element about to receive focus is not the input itself or inside it
+          // and is not the previously active element or inside it
+          // -> the element about to receive focus should prevail
+          return;
         }
       }
+
+      activeElement.focus();
     };
   }, []);
+
   useEffect(() => {
     if (autoFocus) {
       const focusableElement = focusableElementRef.current;

package/src/components/use_batch_during_render.js

@@ -0,0 +1,33 @@
+import { useLayoutEffect, useMemo, useRef } from "preact/hooks";
+
+import { useStableCallback } from "./use_stable_callback.js";
+
+export const useBatchDuringRender = (callback) => {
+  const pendingCallArrayRef = useRef([]);
+  const pendingCallArray = pendingCallArrayRef.current;
+
+  callback = useStableCallback(callback);
+  const callbackWithBatching = useMemo(() => {
+    return (...args) => {
+      if (isRenderingRef.current) {
+        pendingCallArray.push(args);
+        return;
+      }
+      callback(...args);
+    };
+  }, []);
+
+  const isRenderingRef = useRef();
+  isRenderingRef.current = true;
+  useLayoutEffect(() => {
+    isRenderingRef.current = false;
+    if (pendingCallArray.length === 0) {
+      return;
+    }
+    const copy = [...pendingCallArray];
+    pendingCallArray.length = 0;
+    callback(copy);
+  });
+
+  return callbackWithBatching;
+};

package/src/components/use_debounce_true.js

@@ -1,14 +1,14 @@
-import { useEffect, useRef, useState } from "preact/hooks";
+import { useLayoutEffect, useRef, useState } from "preact/hooks";
 
 export const useDebounceTrue = (value, delay = 300) => {
-  const [debouncedValue, setDebouncedValue] = useState(false);
+  const [debouncedTrue, setDebouncedTrue] = useState(false);
   const timerRef = useRef(null);
 
-  useEffect(() => {
-    // If value becomes true, start a timer
+  useLayoutEffect(() => {
+    // If value is true or becomes true, start a timer
     if (value) {
       timerRef.current = setTimeout(() => {
-        setDebouncedValue(true);
+        setDebouncedTrue(true);
       }, delay);
     } else {
       // If value becomes false, clear any pending timer and immediately set to false
@@ -16,7 +16,7 @@ export const useDebounceTrue = (value, delay = 300) => {
         clearTimeout(timerRef.current);
         timerRef.current = null;
       }
-      setDebouncedValue(false);
+      setDebouncedTrue(false);
     }
 
     // Cleanup function
@@ -27,5 +27,5 @@ export const useDebounceTrue = (value, delay = 300) => {
     };
   }, [value, delay]);
 
-  return debouncedValue;
+  return debouncedTrue;
 };

package/src/components/use_dependencies_diff.js

@@ -0,0 +1,35 @@
+/*
+ * - Usage
+ * useEffect(() => {
+ *   // here you want to know what has changed, causing useEffect to be called
+ * }, [name, value])
+ *
+ * const diff = useDependenciesDiff({ name, value })
+ * useEffect(() => {
+ *   console.log('useEffect called because', diff)
+ * }, [name, value])
+ */
+
+import { useMemo, useRef } from "preact/hooks";
+
+export const useDependenciesDiff = (inputs) => {
+  const oldInputsRef = useRef(inputs);
+  const inputValuesArray = Object.values(inputs);
+  const inputKeysArray = Object.keys(inputs);
+  const diffRef = useRef();
+  useMemo(() => {
+    const oldInputs = oldInputsRef.current;
+    const diff = {};
+    for (const key of inputKeysArray) {
+      const previous = oldInputs[key];
+      const current = inputs[key];
+      if (previous !== current) {
+        diff[key] = { previous, current };
+      }
+    }
+    diffRef.current = diff;
+    oldInputsRef.current = inputs;
+  }, inputValuesArray);
+
+  return diffRef.current;
+};

package/src/components/use_focus_group.js

@@ -1,9 +1,10 @@
 import { initFocusGroup } from "@jsenv/dom";
 import { useLayoutEffect } from "preact/hooks";
 
-export const useFocusGroup = (elementRef, options) => {
-  const { direction, skipTab, loop, name, enabled } = options;
-
+export const useFocusGroup = (
+  elementRef,
+  { enabled = true, direction, skipTab, loop, name } = {},
+) => {
   useLayoutEffect(() => {
     if (!enabled) {
       return null;

package/src/components/use_initial_value.js

@@ -64,41 +64,15 @@ export const useExternalValueSync = (
   }
 };
 
-/**
- * Hook that handles initial value setup and external value synchronization.
- *
- * @param {string} name - Parameter name for debugging
- * @param {any} externalValue - Value from props or parent component
- * @param {any} fallbackValue - Backup value if external value isn't useful
- * @param {any} defaultValue - Final fallback value
- * @param {Function} setValue - Function to call when value needs to be set
- *
- * @returns {any} The resolved initial value
- */
-export const useInitialValue = (
-  name,
-  externalValue,
-  fallbackValue,
-  defaultValue,
-  setValue,
-) => {
-  const initialValue = resolveInitialValue(
-    externalValue,
-    fallbackValue,
-    defaultValue,
-  );
-
-  // Set initial value on mount
-  const mountedRef = useRef(false);
-  if (!mountedRef.current) {
-    mountedRef.current = true;
-    if (name) {
-      setValue(initialValue);
-    }
+const UNSET = {};
+export const useInitialValue = (compute) => {
+  const initialValueRef = useRef(UNSET);
+  let initialValue = initialValueRef.current;
+  if (initialValue !== UNSET) {
+    return initialValue;
   }
 
-  // Use the new sync hook
-  useExternalValueSync(externalValue, defaultValue, setValue, name);
-
+  initialValue = compute();
+  initialValueRef.current = initialValue;
   return initialValue;
 };

package/src/components/use_signal_sync.js

@@ -20,7 +20,7 @@ import { useRef } from "preact/hooks";
  *   const nameSignal = useSignalSync(file.name);
  *
  *   return (
- *     <EditableText
+ *     <Editable
  *       valueSignal={nameSignal}  // User can edit this
  *       action={renameFileAction} // Saves changes
  *     />

package/src/components/use_stable_callback.js

@@ -0,0 +1,68 @@
+/**
+ * Custom hook creating a stable callback that doesn't trigger re-renders.
+ *
+ * PROBLEM: Parent components often forget to use useCallback, causing library
+ * components to re-render unnecessarily when receiving callback props.
+ *
+ * SOLUTION: Library components can use this hook to create stable callback
+ * references internally, making them defensive against parents who don't
+ * optimize their callbacks. This ensures library components don't force
+ * consumers to think about useCallback.
+ *
+ * USAGE:
+ * ```js
+ * // Parent component (consumer) - no useCallback needed
+ * const Parent = () => {
+ *   const [count, setCount] = useState(0);
+ *
+ *   // Parent naturally creates new function reference each render
+ *   // (forgetting useCallback is common and shouldn't break performance)
+ *   return <LibraryButton onClick={(e) => setCount(count + 1)} />;
+ * };
+ *
+ * // Library component - defensive against changing callbacks
+ * const LibraryButton = ({ onClick }) => {
+ *   // ✅ Create stable reference from parent's potentially changing callback
+ *   const stableClick = useStableCallback(onClick);
+ *
+ *   // Internal expensive components won't re-render when parent updates
+ *   return <ExpensiveInternalButton onClick={stableClick} />;
+ * };
+ *
+ * // Deep internal component gets stable reference
+ * const ExpensiveInternalButton = memo(({ onClick }) => {
+ *   // This won't re-render when Parent's count changes
+ *   // But onClick will always call the latest Parent callback
+ *   return <button onClick={onClick}>Click me</button>;
+ * });
+ * ```
+ *
+ * Perfect for library components that need performance without burdening consumers.
+ */
+
+import { useRef } from "preact/hooks";
+
+export const useStableCallback = (callback, mapper) => {
+  const callbackRef = useRef();
+  callbackRef.current = callback;
+  const stableCallbackRef = useRef();
+
+  // Return original falsy value directly when callback is not a function
+  if (!callback) {
+    return callback;
+  }
+
+  const existingStableCallback = stableCallbackRef.current;
+  if (existingStableCallback) {
+    return existingStableCallback;
+  }
+  const stableCallback = (...args) => {
+    const currentCallback = callbackRef.current;
+    if (mapper) {
+      args = mapper(...args);
+    }
+    return currentCallback(...args);
+  };
+  stableCallbackRef.current = stableCallback;
+  return stableCallback;
+};

package/src/components/use_state_array.js

@@ -1,28 +1,35 @@
-import { useCallback, useState } from "preact/hooks";
+import { useCallback, useRef, useState } from "preact/hooks";
 import { addIntoArray, removeFromArray } from "../utils/array_add_remove.js";
 import {
   resolveInitialValue,
   useExternalValueSync,
 } from "./use_initial_value.js";
 
+const FIRST_MOUNT = {};
 export const useStateArray = (
-  externalValue = [],
+  externalValue,
   fallbackValue,
   defaultValue = [],
 ) => {
-  const initialValue = resolveInitialValue(
-    externalValue,
-    fallbackValue,
-    defaultValue,
-  );
+  const initialValueRef = useRef(FIRST_MOUNT);
+  if (initialValueRef.current === FIRST_MOUNT) {
+    const initialValue = resolveInitialValue(
+      externalValue,
+      fallbackValue,
+      defaultValue,
+    );
+    initialValueRef.current = initialValue;
+  }
+  const initialValue = initialValueRef.current;
   const [array, setArray] = useState(initialValue);
 
-  // Sync external value changes
+  // Only sync external value changes if externalValue was explicitly provided
   useExternalValueSync(externalValue, defaultValue, setArray, "state_array");
 
   const add = useCallback((valueToAdd) => {
     setArray((array) => {
-      return addIntoArray(array, valueToAdd);
+      const newArray = addIntoArray(array, valueToAdd);
+      return newArray;
     });
   }, []);
 

package/src/docs/actions.md

@@ -13,6 +13,7 @@
 - ```js
 
   ```
+
 - const getUserTemplate = createActionTemplate(async ({ userId }) => {
 - const response = await fetch(`/api/users/${userId}`);
 - return response.json();
@@ -20,6 +21,7 @@
 - ```
 
   ```
+
 -
 - ### 🎯 **Action Instances**
 - Stateful objects created from templates with specific parameters. Each unique parameter set
@@ -27,17 +29,20 @@
 - ```js
 
   ```
+
 - const userAction = getUserTemplate.instantiate({ userId: 123 });
 - const status = useActionStatus(userAction); // { pending, data, error, ... }
 - ```
 
   ```
+
 -
 - ### 🔄 **Action Proxies**
 - Dynamic actions that react to signal changes, automatically reloading when parameters change.
 - ```js
 
   ```
+
 - const userProxy = createActionProxy(getUserTemplate, {
 - userId: userIdSignal, // Signal - reactive
 - includeProfile: true // Static - not reactive
@@ -46,6 +51,7 @@
 - ```
 
   ```
+
 -
 - ## Loading States & Lifecycle
 -
@@ -77,6 +83,7 @@
 - ```js
 
   ```
+
 - const baseAction = getUserTemplate.instantiate({ userId: 123 });
 - const enrichedAction = baseAction.bindParams({ includeProfile: true });
 - // Result: { userId: 123, includeProfile: true }
@@ -86,6 +93,7 @@
 - ```
 
   ```
+
 -
 - ### 🎮 **Concurrent Loading Control**
 - - Prevents duplicate requests for same resource
@@ -96,6 +104,7 @@
 - ```js
 
   ```
+
 - const actionTemplate = createActionTemplate(callback, {
 - sideEffect: (params, loadParams) => {
 -     // Setup logic (analytics, subscriptions, etc.)
@@ -107,6 +116,7 @@
 - ```
 
   ```
+
 -
 - ## Usage Patterns
 -
@@ -114,6 +124,7 @@
 - ```js
 
   ```
+
 - const getUserAction = createActionTemplate(async ({ userId }) => {
 - return await api.getUser(userId);
 - });
@@ -128,11 +139,13 @@
 - ```
 
   ```
+
 -
 - ### 🔄 **Reactive Data Loading**
 - ```js
 
   ```
+
 - const searchProxy = createActionProxy(searchTemplate, {
 - query: searchSignal,
 - filters: filtersSignal
@@ -141,11 +154,13 @@
 - ```
 
   ```
+
 -
 - ### 📋 **Master-Detail Pattern**
 - ```js
 
   ```
+
 - const usersAction = getUsersTemplate.instantiate();
 - const selectedUser = signal(null);
 -
@@ -155,11 +170,13 @@
 - ```
 
   ```
+
 -
 - ### 🏃 **Progressive Loading**
 - ```js
 
   ```
+
 - // Preload on hover, load on click
 - <button
 - onMouseEnter={() => action.preload()}
@@ -170,6 +187,7 @@
 - ```
 
   ```
+
 -
 - ## Advanced Features
 -
@@ -177,6 +195,7 @@
 - ```js
 
   ```
+
 - const actionTemplate = createActionTemplate(fetchUser, {
 - computedDataSignal: computed(() => {
 -     const rawData = dataSignal.value;
@@ -186,11 +205,13 @@
 - ```
 
   ```
+
 -
 - ### 🎨 **Async Rendering Support**
 - ```js
 
   ```
+
 - const actionTemplate = createActionTemplate(fetchData, {
 - renderLoadedAsync: async () => {
 -     const { UserComponent } = await import('./UserComponent.js');
@@ -200,6 +221,7 @@
 - ```
 
   ```
+
 -
 - ### 🛠️ **Debugging & Observability**
 - Built-in debug mode with detailed logging of state transitions, loading coordination,

package/src/notes.md

@@ -1,13 +1,34 @@
-- import.meta.css during build should use stylesheet to inject so that it puts an url instead of constructed stylesheet?
+- Drag to move row and column
+
+  (ideally we keep an empty "clone" in the table and we create a visually identic clone to drag)
+
+  sitcky prevents drag to re-order
+  I think we are starting to reach the limits of a table element
+
+  donc on va refaire mais avec des div comme ca on controle bien tout
+  de toute facon les dimensions des lignes et colonnes seront fixes
+  et je gagne pas grand chose a passer par la balise table
+
+- Ideally the drag gesture should autoscroll once dragged element boundaries reach the scrollable parent (not the mouse)
+
+- Can use shortcuts on table selection
+  - cmd + delete would delete rows/columns
+    on cells it does nothing but we'll be able to copy via keyboard to start
+
+- Fixed first column and first row (overflow on the rest + it's fixed when there is a lof of content)
+
+- Can delete a table row
 
-- La table qui affiche une page, on mettra les details dans un bouton settings en haut a droite
-  Qui ouvrira les infos a propos de cette tables et on focus sur les données au lieu des settings de la table
-  (surement qu'on aura
-  - api/tables/:tablename/settings
-  - api/tables/:tablename/columns
-  - api/tables/:tablename/rows
-    (et api/tables on verra je serais pas encore)
-
-- See table columns, ability to add, update, remove table columns
-- Ability to see table rows, ability to add/update/remove rows
-- Pagination of course
+- Can update a table row cell
+
+- Can see table columns attributes
+
+- Can update table column attributes
+
+- Can remove table column
+
+- Can move table column
+
+- Pagination
+
+- import.meta.css during build should use stylesheet to inject so that it puts an url instead of constructed stylesheet?