@jsenv/navi 0.0.1

package/src/components/use_signal_sync.js

@@ -0,0 +1,50 @@
+import { useSignal } from "@preact/signals";
+import { useRef } from "preact/hooks";
+
+/**
+ * Creates a signal that stays synchronized with an external value,
+ * only updating the signal when the value actually changes.
+ *
+ * This hook solves a common reactive UI pattern where:
+ * 1. A signal controls a UI element (like an input field)
+ * 2. The UI element can be modified by user interaction
+ * 3. When the external "source of truth" changes, it should take precedence
+ *
+ * @param {any} value - The external value to sync with (the "source of truth")
+ * @param {any} [initialValue] - Optional initial value for the signal (defaults to value)
+ * @returns {Signal} A signal that tracks the external value but allows temporary local changes
+ *
+ * @example
+ * const FileNameEditor = ({ file }) => {
+ *   // Signal stays in sync with file.name, but allows user editing
+ *   const nameSignal = useSignalSync(file.name);
+ *
+ *   return (
+ *     <EditableText
+ *       valueSignal={nameSignal}  // User can edit this
+ *       action={renameFileAction} // Saves changes
+ *     />
+ *   );
+ * };
+ *
+ * // Scenario:
+ * // 1. file.name = "doc.txt", nameSignal.value = "doc.txt"
+ * // 2. User types "report" -> nameSignal.value = "report.txt"
+ * // 3. External update: file.name = "shared-doc.txt"
+ * // 4. Next render: nameSignal.value = "shared-doc.txt" (model wins!)
+ *
+ */
+
+export const useSignalSync = (value, initialValue = value) => {
+  const signal = useSignal(initialValue);
+  const previousValueRef = useRef(value);
+
+  // Only update signal when external value actually changes
+  // This preserves user input between external changes
+  if (previousValueRef.current !== value) {
+    previousValueRef.current = value;
+    signal.value = value; // Model takes precedence
+  }
+
+  return signal;
+};

package/src/components/use_state_array.js

@@ -0,0 +1,40 @@
+import { useCallback, useState } from "preact/hooks";
+import { addIntoArray, removeFromArray } from "../utils/array_add_remove.js";
+import {
+  resolveInitialValue,
+  useExternalValueSync,
+} from "./use_initial_value.js";
+
+export const useStateArray = (
+  externalValue = [],
+  fallbackValue,
+  defaultValue = [],
+) => {
+  const initialValue = resolveInitialValue(
+    externalValue,
+    fallbackValue,
+    defaultValue,
+  );
+  const [array, setArray] = useState(initialValue);
+
+  // Sync external value changes
+  useExternalValueSync(externalValue, defaultValue, setArray, "state_array");
+
+  const add = useCallback((valueToAdd) => {
+    setArray((array) => {
+      return addIntoArray(array, valueToAdd);
+    });
+  }, []);
+
+  const remove = useCallback((valueToRemove) => {
+    setArray((array) => {
+      return removeFromArray(array, valueToRemove);
+    });
+  }, []);
+
+  const reset = useCallback(() => {
+    setArray(initialValue);
+  }, [initialValue]);
+
+  return [array, add, remove, reset];
+};

package/src/docs/actions.md

@@ -0,0 +1,228 @@
+/\*\*
+
+- # Actions System - Declarative Resource Management for Frontend Applications
+-
+- This module provides a comprehensive system for managing asynchronous resources (API calls, data fetching)
+- in a declarative, signal-based architecture. It's designed for complex frontend applications that need
+- fine-grained control over loading states, caching, and resource lifecycle management.
+-
+- ## Core Concepts
+-
+- ### 🔧 **Action Templates**
+- Factory functions that define how to load resources. Templates are pure and reusable.
+- ```js
+
+  ```
+- const getUserTemplate = createActionTemplate(async ({ userId }) => {
+- const response = await fetch(`/api/users/${userId}`);
+- return response.json();
+- });
+- ```
+
+  ```
+-
+- ### 🎯 **Action Instances**
+- Stateful objects created from templates with specific parameters. Each unique parameter set
+- gets its own cached instance (automatic memoization).
+- ```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
+- });
+- // Automatically reloads when userIdSignal changes
+- ```
+
+  ```
+-
+- ## Loading States & Lifecycle
+-
+- ### 📊 **State Management**
+- Each action has a well-defined state machine:
+- - `IDLE` → `LOADING` → `LOADED` (success)
+- - `IDLE` → `LOADING` → `FAILED` (error)
+- - `IDLE` → `LOADING` → `ABORTED` (cancelled)
+-
+- ### ⚡ **Load Types**
+- - **`.load()`** - Load with user intent (sets `loadRequested: true`)
+- - **`.preload()`** - Background loading (sets `loadRequested: false`)
+- - **`.reload()`** - Force reload even if already loaded
+- - **`.unload()`** - Cancel loading and reset state
+-
+- ### 🛡️ **Preload Protection**
+- Preloaded actions are protected from garbage collection for 5 minutes to ensure
+- they remain available for components that may load later (e.g., via dynamic imports).
+-
+- ## Key Features
+-
+- ### 🧠 **Intelligent Memoization**
+- - Actions with identical parameters share the same instance
+- - Uses deep equality comparison with `compareTwoJsValues`
+- - Supports `SYMBOL_IDENTITY` for fast recognition of "conceptually same" objects
+- - Memory-efficient with automatic garbage collection
+-
+- ### 🔗 **Parameter Binding & Composition**
+- ```js
+
+  ```
+- const baseAction = getUserTemplate.instantiate({ userId: 123 });
+- const enrichedAction = baseAction.bindParams({ includeProfile: true });
+- // Result: { userId: 123, includeProfile: true }
+-
+- // Supports objects, primitives, and signals
+- const dynamicAction = baseAction.bindParams(filtersSignal);
+- ```
+
+  ```
+-
+- ### 🎮 **Concurrent Loading Control**
+- - Prevents duplicate requests for same resource
+- - Smart request deduplication and racing condition handling
+- - Coordinated loading/unloading of multiple actions via `updateActions()`
+-
+- ### 🔧 **Side Effects & Cleanup**
+- ```js
+
+  ```
+- const actionTemplate = createActionTemplate(callback, {
+- sideEffect: (params, loadParams) => {
+-     // Setup logic (analytics, subscriptions, etc.)
+-     return () => {
+-       // Cleanup logic - called on unload/abort
+-     };
+- }
+- });
+- ```
+
+  ```
+-
+- ## Usage Patterns
+-
+- ### 🏗️ **Basic Resource Loading**
+- ```js
+
+  ```
+- const getUserAction = createActionTemplate(async ({ userId }) => {
+- return await api.getUser(userId);
+- });
+-
+- // In component
+- const userAction = getUserAction.instantiate({ userId: 123 });
+- const { pending, data, error } = useActionStatus(userAction);
+-
+- useEffect(() => {
+- userAction.load();
+- }, []);
+- ```
+
+  ```
+-
+- ### 🔄 **Reactive Data Loading**
+- ```js
+
+  ```
+- const searchProxy = createActionProxy(searchTemplate, {
+- query: searchSignal,
+- filters: filtersSignal
+- });
+- // Automatically reloads when signals change
+- ```
+
+  ```
+-
+- ### 📋 **Master-Detail Pattern**
+- ```js
+
+  ```
+- const usersAction = getUsersTemplate.instantiate();
+- const selectedUser = signal(null);
+-
+- const userDetailsProxy = createActionProxy(getUserTemplate, {
+- userId: computed(() => selectedUser.value?.id)
+- });
+- ```
+
+  ```
+-
+- ### 🏃 **Progressive Loading**
+- ```js
+
+  ```
+- // Preload on hover, load on click
+- <button
+- onMouseEnter={() => action.preload()}
+- onClick={() => action.load()}
+- >
+- Load User
+- </button>
+- ```
+
+  ```
+-
+- ## Advanced Features
+-
+- ### 🎭 **Custom Data Transformation**
+- ```js
+
+  ```
+- const actionTemplate = createActionTemplate(fetchUser, {
+- computedDataSignal: computed(() => {
+-     const rawData = dataSignal.value;
+-     return rawData ? transformUser(rawData) : null;
+- })
+- });
+- ```
+
+  ```
+-
+- ### 🎨 **Async Rendering Support**
+- ```js
+
+  ```
+- const actionTemplate = createActionTemplate(fetchData, {
+- renderLoadedAsync: async () => {
+-     const { UserComponent } = await import('./UserComponent.js');
+-     return (user) => <UserComponent user={user} />;
+- }
+- });
+- ```
+
+  ```
+-
+- ### 🛠️ **Debugging & Observability**
+- Built-in debug mode with detailed logging of state transitions, loading coordination,
+- and memory management. Enable with `debug = true`.
+-
+- ## Integration Points
+-
+- - **Signals**: Built on @preact/signals for reactive state management
+- - **Navigation**: Integrates with navigation systems for route-based loading
+- - **Components**: Use `useActionStatus()` hook for component integration
+- - **Memory Management**: Automatic cleanup with WeakMap-based private properties
+-
+- ## Performance Characteristics
+-
+- - **Memory Efficient**: Weak references prevent memory leaks
+- - **Request Deduplication**: Identical requests are automatically merged
+- - **Minimal Re-renders**: Signal-based updates only trigger when data actually changes
+- - **Lazy Loading**: Actions only created when needed, with intelligent memoization
+-
+- This system is particularly well-suited for:
+- - SPAs with complex data fetching requirements
+- - Applications needing fine-grained loading state control
+- - Systems requiring request coordination and deduplication
+- - Progressive loading and preloading scenarios
+- - Master-detail interfaces with dynamic parameter binding
+    \*/

package/src/docs/demos/resource/action_status.jsx

@@ -0,0 +1,42 @@
+import { useActionStatus } from "@jsenv/navi";
+import { stringifyForDisplay } from "../../../utils/stringify_for_display.js";
+
+export const ActionStatus = ({ action, name = action.name }) => {
+  const { idle, preloaded, pending, params, error, aborted, data } =
+    useActionStatus(action);
+
+  return (
+    <fieldset>
+      <legend>{name}</legend>
+
+      <div style="display: flex; flex-direction: column; gap: 5px;">
+        <div>
+          <span>
+            <span>loading state:</span>{" "}
+            <strong>
+              {idle
+                ? "idle"
+                : aborted
+                  ? "aborted"
+                  : error
+                    ? "error"
+                    : pending
+                      ? "pending"
+                      : preloaded
+                        ? "preloaded"
+                        : "loaded"}
+            </strong>
+          </span>
+        </div>
+        <div style="display: flex; gap: 5px;">
+          <span>params: </span>
+          <pre style="margin: 0">{stringifyForDisplay(params)}</pre>
+        </div>
+        <div style="display: flex; gap: 5px;">
+          <span>data: </span>
+          <pre style="margin: 0">{stringifyForDisplay(data)}</pre>
+        </div>
+      </div>
+    </fieldset>
+  );
+};

package/src/docs/demos/resource/demo.md

@@ -0,0 +1 @@
+## Prochain truc a faire:

package/src/docs/demos/resource/resource_demo_0.html

@@ -0,0 +1,84 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="data:," />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Action demo 0</title>
+  </head>
+  <body>
+    <div id="root" style="position: relative; width: 200px"></div>
+
+    <script type="module" jsenv-type="module/jsx">
+      /**
+       * Ici on teste juste que d'ouvrir le details
+       * charge l'action et que la donée est affichée
+       * Si on reload la page, le details est open et l'action est lancée
+       */
+
+      import { render } from "preact";
+      import { signal, effect } from "@preact/signals";
+      import { useActionStatus, resource } from "@jsenv/navi";
+
+      const USER = resource("user", {
+        idKey: "name",
+        GET_MANY: () => {
+          return [
+            {
+              name: "Alice",
+            },
+            {
+              name: "bob",
+            },
+            {
+              name: "Charlie",
+            },
+          ];
+        },
+      });
+      const openedSignal = signal(
+        localStorage.getItem("user_opened") === "true",
+      );
+      effect(() => {
+        const opened = openedSignal.value;
+        if (opened) {
+          localStorage.setItem("user_opened", "true");
+        } else {
+          localStorage.removeItem("user_opened");
+        }
+      });
+      if (openedSignal.peek()) {
+        USER.GET_MANY.preload();
+      }
+
+      // eslint-disable-next-line no-unused-vars
+      const App = () => {
+        const { data } = useActionStatus(USER.GET_MANY);
+
+        return (
+          <div>
+            <details
+              open={openedSignal.value}
+              onToggle={(e) => {
+                if (e.target.open) {
+                  openedSignal.value = true;
+                  USER.GET_MANY.load();
+                } else {
+                  openedSignal.value = false;
+                  USER.GET_MANY.abort();
+                }
+              }}
+            >
+              <summary>Users</summary>
+              {data.map(({ name }) => {
+                return <span>{name}</span>;
+              })}
+            </details>
+          </div>
+        );
+      };
+
+      render(<App />, document.querySelector("#root"));
+    </script>
+  </body>
+</html>