@jsenv/navi 0.16.24 → 0.16.26

package/dist/jsenv_navi.js

@@ -2390,22 +2390,26 @@ const generateSignalId = () => {
 };
 
 /**
- * Creates an advanced signal with optional source signal synchronization, local storage persistence, and validation.
+ * Creates an advanced signal with dynamic default value, local storage persistence, and validation.
  *
- * The sourceSignal option creates a fallback mechanism where:
- * 1. The signal initially takes the value from sourceSignal (if defined) or falls back to defaultValue
- * 2. The signal can be manually overridden with any value
- * 3. When sourceSignal changes, it will override the current value again
+ * The first parameter can be either a static value or a signal acting as a "dynamic default":
+ * - If a static value: traditional default behavior
+ * - If a signal: acts as a dynamic default that updates the signal ONLY when no explicit value has been set
  *
- * This is useful for scenarios like UI state management where you want to:
- * - Start with a value from an external source (e.g., backend data)
- * - Allow temporary local overrides (e.g., user interactions)
- * - Reset to the external source when context changes (e.g., navigation, data refresh)
+ * Dynamic default behavior (when first param is a signal):
+ * 1. Initially takes value from the default signal
+ * 2. When explicitly set (programmatically or via localStorage), the explicit value takes precedence
+ * 3. When default signal changes, it only updates if no explicit value was ever set
+ * 4. Calling reset() or setting to undefined makes the signal use the dynamic default again
  *
- * @param {any} defaultValue - The default value to use when no other value is available
+ * This is useful for:
+ * - Backend data that can change but shouldn't override user preferences
+ * - Route parameters with dynamic defaults based on other state
+ * - Cascading configuration where defaults can be updated without losing user customizations
+ *
+ * @param {any|import("@preact/signals").Signal} defaultValue - Static default value OR signal for dynamic default behavior
  * @param {Object} [options={}] - Configuration options
  * @param {string|number} [options.id] - Custom ID for the signal. If not provided, an auto-generated ID will be used. Used for localStorage key and route pattern detection.
- * @param {import("@preact/signals").Signal} [options.sourceSignal] - Source signal to synchronize with. When the source signal changes, this signal will be updated
  * @param {boolean} [options.persists=false] - Whether to persist the signal value in localStorage using the signal ID as key
  * @param {"string" | "number" | "boolean" | "object"} [options.type="string"] - Type for localStorage serialization/deserialization
  * @param {Array} [options.oneOf] - Array of valid values for validation. Signal will be marked invalid if value is not in this array
@@ -2435,14 +2439,21 @@ const generateSignalId = () => {
  * });
  *
  * @example
- * // Position that follows backend data but allows temporary overrides
- * const backendPosition = signal({ x: 100, y: 50 });
- * const currentPosition = stateSignal({ x: 0, y: 0 }, { sourceSignal: backendPosition });
+ * // Dynamic default that doesn't override user choices
+ * const backendTheme = signal("light");
+ * const userTheme = stateSignal(backendTheme, { persists: true });
+ *
+ * // Initially: userTheme.value = "light" (from dynamic default)
+ * // User sets: userTheme.value = "dark" (explicit choice, persisted)
+ * // Backend changes: backendTheme.value = "blue"
+ * // Result: userTheme.value = "dark" (user choice preserved)
+ * // Reset: userTheme.value = undefined; // Now follows dynamic default again
  *
- * // Initially: currentPosition.value = { x: 100, y: 50 } (from backend)
- * // User drags: currentPosition.value = { x: 150, y: 80 } (manual override)
- * // Backend updates: backendPosition.value = { x: 200, y: 60 }
- * // Result: currentPosition.value = { x: 200, y: 60 } (reset to new backend value)
+ * @example
+ * // Route parameter with dynamic default from parent route
+ * const parentTab = signal("overview");
+ * const childTab = stateSignal(parentTab);
+ * // childTab follows parentTab changes unless explicitly set
  */
 const NO_LOCAL_STORAGE = [() => undefined, () => {}, () => {}];
 const stateSignal = (defaultValue, options = {}) => {
@@ -2451,10 +2462,18 @@ const stateSignal = (defaultValue, options = {}) => {
     type = "string",
     oneOf,
     autoFix,
-    sourceSignal,
     persists = false,
     debug,
   } = options;
+
+  // Check if defaultValue is a signal (dynamic default) or static value
+  const isDynamicDefault =
+    defaultValue &&
+    typeof defaultValue === "object" &&
+    "value" in defaultValue &&
+    "peek" in defaultValue;
+  const dynamicDefaultSignal = isDynamicDefault ? defaultValue : null;
+  const staticDefaultValue = isDynamicDefault ? undefined : defaultValue;
   const signalId = id || generateSignalId();
   // Convert numeric IDs to strings for consistency
   const signalIdString = String(signalId);
@@ -2471,202 +2490,199 @@ const stateSignal = (defaultValue, options = {}) => {
     persists
       ? valueInLocalStorage(localStorageKey, { type })
       : NO_LOCAL_STORAGE;
-  const getFallbackValue = () => {
-    const valueFromLocalStorage = readFromLocalStorage();
-    if (valueFromLocalStorage !== undefined) {
-      if (debug) {
-        console.debug(
-          `[stateSignal:${signalIdString}] using value from localStorage "${localStorageKey}"=${valueFromLocalStorage}`,
-        );
-      }
-      return valueFromLocalStorage;
-    }
-    if (sourceSignal) {
-      const sourceValue = sourceSignal.peek();
-      if (sourceValue !== undefined) {
+  const getDefaultValue = () => {
+    if (persists) {
+      const valueFromLocalStorage = readFromLocalStorage();
+      if (valueFromLocalStorage !== undefined) {
         if (debug) {
           console.debug(
-            `[stateSignal:${signalIdString}] using value from source signal=${sourceValue}`,
+            `[stateSignal:${signalIdString}] using value from localStorage "${localStorageKey}"=${valueFromLocalStorage}`,
           );
         }
-        return sourceValue;
+        return valueFromLocalStorage;
       }
     }
+    if (dynamicDefaultSignal) {
+      const dynamicValue = dynamicDefaultSignal.peek();
+      if (dynamicValue === undefined) {
+        return undefined;
+      }
+      if (debug) {
+        console.debug(
+          `[stateSignal:${signalIdString}] using value from dynamic default signal=${dynamicValue}`,
+        );
+      }
+      return dynamicValue;
+    }
     if (debug) {
       console.debug(
-        `[stateSignal:${signalIdString}] using default value=${defaultValue}`,
+        `[stateSignal:${signalIdString}] using static default value=${staticDefaultValue}`,
       );
     }
-    return defaultValue;
+    return staticDefaultValue;
+  };
+  const isCustomValue = (value) => {
+    if (value === undefined) {
+      return false;
+    }
+    if (dynamicDefaultSignal) {
+      return value !== dynamicDefaultSignal.peek();
+    }
+    return value !== staticDefaultValue;
   };
 
-  const advancedSignal = signal(getFallbackValue());
-
-  if (debug) {
-    console.debug(
-      `[stateSignal:${signalIdString}] created with initial value=${advancedSignal.peek()}`,
-      {
-        defaultValue,
-        hasSourceSignal: Boolean(sourceSignal),
-        persists,
-        localStorageKey: persists ? localStorageKey : undefined,
-      },
-    );
-  }
-
-  // Set signal ID and create meaningful string representation
-  advancedSignal.__signalId = signalIdString;
-  advancedSignal.toString = () => `{navi_state_signal:${signalIdString}}`;
-
-  // Store signal with its options for later route connection
-  globalSignalRegistry.set(signalIdString, {
-    signal: advancedSignal,
-    options: {
-      getFallbackValue,
-      defaultValue,
-      type,
-      persists,
-      localStorageKey,
-      debug,
-      ...options,
-    },
-  });
-
+  // Create signal with initial value: use stored value, or undefined to indicate no explicit value
+  const advancedSignal = signal(getDefaultValue());
   const validity = { valid: true };
   advancedSignal.validity = validity;
-
-  // ensure current value always fallback to
-  // 1. source signal
-  // 2. local storage
-  // 3. default value
+  advancedSignal.__signalId = signalIdString;
+  advancedSignal.toString = () => `{navi_state_signal:${signalIdString}}`;
+  // 1. when signal value changes to undefined, it needs to fallback to default value
+  // 2. when dynamic default changes and signal value is not custom, it needs to update
   {
-    let firstRun = true;
+    let isFirstRun = true;
     effect(() => {
       const value = advancedSignal.value;
-      if (sourceSignal) {
-        // eslint-disable-next-line no-unused-expressions
-        sourceSignal.value;
-      }
-      if (firstRun) {
-        firstRun = true;
+      if (isFirstRun) {
+        isFirstRun = false;
         return;
       }
       if (value !== undefined) {
         return;
       }
-      advancedSignal.value = getFallbackValue();
+      const defaultValue = getDefaultValue();
+      if (defaultValue === value) {
+        return;
+      }
+      if (debug) {
+        console.debug(
+          `[stateSignal:${signalIdString}] becomes undefined, reset to ${defaultValue}`,
+        );
+      }
+      advancedSignal.value = defaultValue;
     });
   }
-  // When source signal value is updated, it overrides current signal value
-  source_signal_override: {
-    if (!sourceSignal) {
-      break source_signal_override;
+  dynamic_signal_effect: {
+    if (!dynamicDefaultSignal) {
+      break dynamic_signal_effect;
     }
-
+    // here we listen only on the dynamic default signal
     let isFirstRun = true;
-    let sourcePreviousValue;
+    let dynamicDefaultPreviousValue;
     effect(() => {
-      const sourceValue = sourceSignal.value;
+      const value = advancedSignal.peek();
+      const dynamicDefaultValue = dynamicDefaultSignal.value;
       if (isFirstRun) {
-        // first run
         isFirstRun = false;
-        sourcePreviousValue = sourceValue;
+        dynamicDefaultPreviousValue = dynamicDefaultValue;
         return;
       }
-      if (sourceValue === undefined) {
-        // we don't have anything in the source signal, keep current value
-        if (debug) {
-          console.debug(
-            `[stateSignal:${signalIdString}] source signal is undefined, keeping current value=${advancedSignal.peek()}`,
-            {
-              sourcePreviousValue,
-              sourceValue,
-              currentValue: advancedSignal.peek(),
-            },
-          );
-        }
-        sourcePreviousValue = undefined;
+      if (value !== dynamicDefaultPreviousValue) {
+        dynamicDefaultPreviousValue = dynamicDefaultValue;
+        return;
+      }
+      dynamicDefaultPreviousValue = dynamicDefaultValue;
+      const defaultValue = getDefaultValue();
+      if (defaultValue === value) {
         return;
       }
-      // the case we want to support: source signal value changes -> override current value
       if (debug) {
         console.debug(
-          `[stateSignal:${signalIdString}] source signal updated, overriding current value`,
-          {
-            sourcePreviousValue,
-            sourceValue,
-            previousValue: advancedSignal.peek(),
-          },
+          `[stateSignal:${signalIdString}] dynamic default updated, update to ${defaultValue}`,
         );
       }
-      advancedSignal.value = sourceValue;
-      sourcePreviousValue = sourceValue;
+      advancedSignal.value = defaultValue;
     });
   }
-  // Read/write into local storage when enabled
   persist_in_local_storage: {
     if (!localStorageKey) {
       break persist_in_local_storage;
     }
     effect(() => {
       const value = advancedSignal.value;
-      if (value === undefined || value === null || value === defaultValue) {
+      if (isCustomValue(value)) {
         if (debug) {
           console.debug(
-            `[stateSignal:${signalIdString}] removing "${localStorageKey}" from localStorage (value=${value}, default=${defaultValue})`,
+            `[stateSignal:${signalIdString}] writing into localStorage "${localStorageKey}"=${value}`,
           );
         }
-        removeFromLocalStorage();
+        writeIntoLocalStorage(value);
       } else {
         if (debug) {
           console.debug(
-            `[stateSignal:${signalIdString}] writing into localStorage "${localStorageKey}"=${value}`,
+            `[stateSignal:${signalIdString}] removing "${localStorageKey}" from localStorage (value=${value})`,
           );
         }
-        writeIntoLocalStorage(value);
+        removeFromLocalStorage();
       }
     });
   }
-  // update validity object according to the advanced signal value
+  // update validity object according to the signal value
   {
     effect(() => {
-      const value = advancedSignal.value;
       const wasValid = validity.valid;
+      const value = advancedSignal.value;
       updateValidity({ oneOf }, validity, value);
-      if (!validity.valid) {
-        if (debug) {
-          console.debug(`[stateSignal:${signalIdString}] validation failed`, {
-            value,
-            oneOf,
-            hasAutoFix: Boolean(autoFix),
-          });
-        }
-        if (autoFix) {
-          const fixedValue = autoFix();
+      if (validity.valid) {
+        if (!wasValid) {
           if (debug) {
             console.debug(
-              `[stateSignal:${signalIdString}] auto-fixing invalid value`,
-              {
-                invalidValue: value,
-                fixedValue,
-              },
+              `[stateSignal:${signalIdString}] validation now passes`,
+              { value },
             );
           }
-          advancedSignal.value = fixedValue;
-          return;
         }
-      } else if (!wasValid && validity.valid) {
+        return;
+      }
+      if (debug) {
+        console.debug(`[stateSignal:${signalIdString}] validation failed`, {
+          value,
+          oneOf,
+          hasAutoFix: Boolean(autoFix),
+        });
+      }
+      if (autoFix) {
+        const fixedValue = autoFix(value);
         if (debug) {
           console.debug(
-            `[stateSignal:${signalIdString}] validation now passes`,
+            `[stateSignal:${signalIdString}] autoFix applied: ${value} → ${fixedValue}`,
             {
               value,
+              fixedValue,
             },
           );
         }
+        advancedSignal.value = fixedValue;
+        return;
       }
     });
   }
+  // Store signal with its options (used by route_pattern.js)
+  globalSignalRegistry.set(signalIdString, {
+    signal: advancedSignal,
+    options: {
+      getDefaultValue,
+      defaultValue: staticDefaultValue,
+      dynamicDefaultSignal,
+      type,
+      persists,
+      localStorageKey,
+      debug,
+      ...options,
+    },
+  });
+  if (debug) {
+    console.debug(
+      `[stateSignal:${signalIdString}] created with initial value=${advancedSignal.value}`,
+      {
+        staticDefaultValue,
+        hasDynamicDefault: Boolean(dynamicDefaultSignal),
+        hasStoredValue: persists && readFromLocalStorage() !== undefined,
+        persists,
+        localStorageKey: persists ? localStorageKey : undefined,
+      },
+    );
+  }
 
   return advancedSignal;
 };
@@ -7723,7 +7739,11 @@ const createRoutePattern = (pattern) => {
     }
   }
 
-  const parsedPattern = parsePattern(cleanPattern, parameterDefaults);
+  const parsedPattern = parsePattern(
+    cleanPattern,
+    parameterDefaults,
+    connections,
+  );
 
   // Create signalSet to track all signals this pattern depends on
   const signalSet = new Set();
@@ -9334,7 +9354,11 @@ const canParameterReachChildRoute = (
 /**
  * Parse a route pattern string into structured segments
  */
-const parsePattern = (pattern, parameterDefaults = new Map()) => {
+const parsePattern = (
+  pattern,
+  parameterDefaults = new Map(),
+  connections = [],
+) => {
   // Handle root route
   if (pattern === "/") {
     return {
@@ -9403,7 +9427,27 @@ const parsePattern = (pattern, parameterDefaults = new Map()) => {
     if (seg.startsWith(":")) {
       // Parameter segment
       const paramName = seg.slice(1).replace("?", ""); // Remove : and optional ?
-      const isOptional = seg.endsWith("?") || parameterDefaults.has(paramName);
+
+      // Check if parameter should be optional:
+      // 1. Explicitly marked with ?
+      // 2. Has a default value
+      // 3. Connected signal has undefined value and no explicit default (allows /map to match /map/:panel)
+      let isOptional = seg.endsWith("?") || parameterDefaults.has(paramName);
+
+      if (!isOptional) {
+        // Check if connected signal has undefined value (making parameter optional for index routes)
+        const connection = connections.find(
+          (conn) => conn.paramName === paramName,
+        );
+        if (
+          connection &&
+          connection.signal &&
+          connection.signal.value === undefined &&
+          !parameterDefaults.has(paramName)
+        ) {
+          isOptional = true;
+        }
+      }
 
       return {
         type: "param",
@@ -9597,14 +9641,18 @@ const matchUrl = (
   // Check for remaining URL segments
   // Patterns with trailing slashes can match additional URL segments (like wildcards)
   // Patterns without trailing slashes should match exactly (unless they're wildcards)
+  // BUT: if pattern has children, it can also match additional segments (hierarchical matching)
+  const hasChildren =
+    patternObj && patternObj.children && patternObj.children.length > 0;
   if (
     !parsedPattern.wildcard &&
     !parsedPattern.trailingSlash &&
+    !hasChildren &&
     urlSegmentIndex < urlSegments.length
   ) {
-    return null; // Pattern without trailing slash should not match extra segments
+    return null; // Pattern without trailing slash/wildcard/children should not match extra segments
   }
-  // If pattern has trailing slash or wildcard, allow extra segments (no additional check needed)
+  // If pattern has trailing slash, wildcard, or children, allow extra segments
 
   // Add search parameters
   const searchParams = extractSearchParams(urlObj, connections);
@@ -10255,84 +10303,117 @@ const updateRoutes = (
         if (newMatching) {
           // When route matches, sync signal with URL parameter value
           // This ensures URL is the source of truth
-          if (debug) {
-            console.debug(
-              `[route] Route matching: setting ${paramName} signal to URL value: ${urlParamValue}`,
-            );
+          const currentValue = stateSignal.peek();
+          if (currentValue !== urlParamValue) {
+            if (debug) {
+              console.debug(
+                `[route] Route matching: setting ${paramName} signal to URL value: ${urlParamValue}`,
+              );
+            }
+            stateSignal.value = urlParamValue;
           }
-          stateSignal.value = urlParamValue;
         } else {
-          // When route doesn't match, check if we're navigating to a parent route
-          let parentRouteMatching = false;
+          // Route doesn't match - check if any matching route extracts this parameter
+          let parameterExtractedByMatchingRoute = false;
+          let matchingRouteInSameFamily = false;
+
           for (const otherRoute of routeSet) {
             if (otherRoute === route || !otherRoute.matching) {
               continue;
             }
             const otherRouteProperties = getRoutePrivateProperties(otherRoute);
+            const otherParams = otherRouteProperties.rawParamsSignal.value;
+
+            // Check if this matching route extracts the parameter
+            if (paramName in otherParams) {
+              parameterExtractedByMatchingRoute = true;
+            }
+
+            // Check if this matching route is in the same family using parent-child relationships
+            const thisPatternObj = routePattern;
             const otherPatternObj = otherRouteProperties.routePattern;
 
-            // Check if the other route pattern is a parent of this route pattern
-            // Using the built relationships in the pattern objects
-            let currentParent = routePattern.parent;
-            let foundParent = false;
+            // Routes are in same family if they share a hierarchical relationship:
+            // 1. One is parent/ancestor of the other
+            // 2. They share a common parent/ancestor
+            let inSameFamily = false;
+
+            // Check if other route is ancestor of this route
+            let currentParent = thisPatternObj.parent;
             while (currentParent) {
               if (currentParent === otherPatternObj) {
-                foundParent = true;
+                inSameFamily = true;
                 break;
               }
               currentParent = currentParent.parent;
             }
 
-            if (!foundParent) {
-              continue;
+            // Check if this route is ancestor of other route
+            if (!inSameFamily) {
+              currentParent = otherPatternObj.parent;
+              while (currentParent) {
+                if (currentParent === thisPatternObj) {
+                  inSameFamily = true;
+                  break;
+                }
+                currentParent = currentParent.parent;
+              }
             }
 
-            // Found a parent route that's matching, but check if there's a more specific
-            // sibling route also matching (indicating sibling navigation, not parent navigation)
-            let hasMatchingSibling = false;
-            for (const siblingCandidateRoute of routeSet) {
-              if (
-                siblingCandidateRoute === route ||
-                siblingCandidateRoute === otherRoute ||
-                !siblingCandidateRoute.matching
-              ) {
-                continue;
+            // Check if they share a common parent (siblings or cousins)
+            if (!inSameFamily) {
+              const thisAncestors = new Set();
+              currentParent = thisPatternObj.parent;
+              while (currentParent) {
+                thisAncestors.add(currentParent);
+                currentParent = currentParent.parent;
               }
 
-              const siblingProperties = getRoutePrivateProperties(
-                siblingCandidateRoute,
-              );
-              const siblingPatternObj = siblingProperties.routePattern;
-
-              // Check if this is a sibling (shares the same parent)
-              if (siblingPatternObj.parent === currentParent) {
-                hasMatchingSibling = true;
-                break;
+              currentParent = otherPatternObj.parent;
+              while (currentParent) {
+                if (thisAncestors.has(currentParent)) {
+                  inSameFamily = true;
+                  break;
+                }
+                currentParent = currentParent.parent;
               }
             }
 
-            // Only treat as parent navigation if no sibling is matching
-            if (!hasMatchingSibling) {
-              parentRouteMatching = true;
-              break; // Found the parent route, no need to check other routes
+            if (inSameFamily) {
+              matchingRouteInSameFamily = true;
             }
           }
 
-          if (parentRouteMatching) {
-            // We're navigating to a parent route - clear this signal to reflect the hierarchy
+          // Only reset signal if:
+          // 1. We're navigating within the same route family (not to completely unrelated routes)
+          // 2. AND no matching route extracts this parameter from URL
+          // 3. AND parameter has no default value (making it truly optional)
+          if (matchingRouteInSameFamily && !parameterExtractedByMatchingRoute) {
             const defaultValue = routePattern.parameterDefaults?.get(paramName);
-            if (debug) {
+            if (defaultValue === undefined) {
+              // Parameter is not extracted within same family and has no default - reset it
+              if (debug) {
+                console.debug(
+                  `[route] Same family navigation, ${paramName} not extracted and has no default: resetting signal`,
+                );
+              }
+              stateSignal.value = undefined;
+            } else if (debug) {
+              // Parameter has a default value - preserve current signal value
               console.debug(
-                `[route] Parent route ${parentRouteMatching} matching: clearing ${paramName} signal to default: ${defaultValue}`,
+                `[route] Parameter ${paramName} has default value ${defaultValue}: preserving signal value: ${stateSignal.value}`,
               );
             }
-            stateSignal.value = defaultValue;
           } else if (debug) {
-            // We're navigating to a different route family - preserve signal for future URL building
-            // Keep current signal value unchanged
-            console.debug(
-              `[route] Different route family: preserving ${paramName} signal value: ${stateSignal.value}`,
-            );
+            if (!matchingRouteInSameFamily) {
+              console.debug(
+                `[route] Different route family: preserving ${paramName} signal value: ${stateSignal.value}`,
+              );
+            } else {
+              console.debug(
+                `[route] Parameter ${paramName} extracted by matching route: preserving signal value: ${stateSignal.value}`,
+              );
+            }
           }
         }
       }