@jsenv/navi 0.16.26 → 0.16.28

package/dist/jsenv_navi.js

@@ -2401,15 +2401,18 @@ const generateSignalId = () => {
  * 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
+ * 5. If dynamic default is undefined and options.default is provided, uses the static fallback
  *
  * 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
+ * - Having a static fallback when dynamic defaults might be undefined
  *
  * @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 {any} [options.default] - Static fallback value used when defaultValue is a signal and that signal's value is undefined
  * @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
@@ -2450,6 +2453,21 @@ const generateSignalId = () => {
  * // Reset: userTheme.value = undefined; // Now follows dynamic default again
  *
  * @example
+ * // Dynamic default with static fallback
+ * const backendValue = signal(undefined); // might be undefined initially
+ * const userValue = stateSignal(backendValue, {
+ *   default: "fallback",
+ *   persists: true
+ * });
+ *
+ * // Initially: userValue.value = "fallback" (static fallback since dynamic is undefined)
+ * // Backend loads: backendValue.value = "loaded"; userValue.value = "loaded" (follows dynamic)
+ * // User sets: userValue.value = "custom" (explicit choice, persisted)
+ * // Backend changes: backendValue.value = "updated"
+ * // Result: userValue.value = "custom" (user choice preserved)
+ * // Reset: userValue.value = undefined; userValue.value = "updated" (follows dynamic again)
+ *
+ * @example
  * // Route parameter with dynamic default from parent route
  * const parentTab = signal("overview");
  * const childTab = stateSignal(parentTab);
@@ -2464,6 +2482,7 @@ const stateSignal = (defaultValue, options = {}) => {
     autoFix,
     persists = false,
     debug,
+    default: staticFallback,
   } = options;
 
   // Check if defaultValue is a signal (dynamic default) or static value
@@ -2473,7 +2492,7 @@ const stateSignal = (defaultValue, options = {}) => {
     "value" in defaultValue &&
     "peek" in defaultValue;
   const dynamicDefaultSignal = isDynamicDefault ? defaultValue : null;
-  const staticDefaultValue = isDynamicDefault ? undefined : defaultValue;
+  const staticDefaultValue = isDynamicDefault ? staticFallback : defaultValue;
   const signalId = id || generateSignalId();
   // Convert numeric IDs to strings for consistency
   const signalIdString = String(signalId);
@@ -2505,7 +2524,15 @@ const stateSignal = (defaultValue, options = {}) => {
     if (dynamicDefaultSignal) {
       const dynamicValue = dynamicDefaultSignal.peek();
       if (dynamicValue === undefined) {
-        return undefined;
+        if (staticDefaultValue === undefined) {
+          return undefined;
+        }
+        if (debug) {
+          console.debug(
+            `[stateSignal:${signalIdString}] dynamic default is undefined, using static default=${staticDefaultValue}`,
+          );
+        }
+        return staticDefaultValue;
       }
       if (debug) {
         console.debug(
@@ -2526,7 +2553,11 @@ const stateSignal = (defaultValue, options = {}) => {
       return false;
     }
     if (dynamicDefaultSignal) {
-      return value !== dynamicDefaultSignal.peek();
+      const dynamicValue = dynamicDefaultSignal.peek();
+      if (dynamicValue === undefined) {
+        return value !== staticDefaultValue;
+      }
+      return value !== dynamicValue;
     }
     return value !== staticDefaultValue;
   };
@@ -2577,21 +2608,40 @@ const stateSignal = (defaultValue, options = {}) => {
         dynamicDefaultPreviousValue = dynamicDefaultValue;
         return;
       }
-      if (value !== dynamicDefaultPreviousValue) {
+      // Check if current signal value matches the PREVIOUS dynamic default
+      // If so, it was following the dynamic default and should update
+      // Special case: if previous was undefined and we were using static fallback
+      let wasFollowingDefault = false;
+      if (
+        dynamicDefaultPreviousValue === undefined &&
+        staticDefaultValue !== undefined
+      ) {
+        // Signal might have been using static fallback
+        wasFollowingDefault = value === staticDefaultValue;
+      } else {
+        // Signal was following the previous dynamic default
+        wasFollowingDefault = value === dynamicDefaultPreviousValue;
+      }
+
+      if (!wasFollowingDefault) {
+        // Signal has a custom value, don't update even if dynamic default changes
         dynamicDefaultPreviousValue = dynamicDefaultValue;
         return;
       }
-      dynamicDefaultPreviousValue = dynamicDefaultValue;
-      const defaultValue = getDefaultValue();
-      if (defaultValue === value) {
+
+      // Signal was using default value, update to new default
+      const newDefaultValue = getDefaultValue();
+      if (newDefaultValue === value) {
+        dynamicDefaultPreviousValue = dynamicDefaultValue;
         return;
       }
       if (debug) {
         console.debug(
-          `[stateSignal:${signalIdString}] dynamic default updated, update to ${defaultValue}`,
+          `[stateSignal:${signalIdString}] dynamic default updated, update to ${newDefaultValue}`,
         );
       }
-      advancedSignal.value = defaultValue;
+      dynamicDefaultPreviousValue = dynamicDefaultValue;
+      advancedSignal.value = newDefaultValue;
     });
   }
   persist_in_local_storage: {
@@ -2664,6 +2714,7 @@ const stateSignal = (defaultValue, options = {}) => {
       getDefaultValue,
       defaultValue: staticDefaultValue,
       dynamicDefaultSignal,
+      isCustomValue,
       type,
       persists,
       localStorageKey,
@@ -7847,21 +7898,26 @@ const createRoutePattern = (pattern) => {
 
   /**
    * Helper: Filter out default values from parameters for cleaner URLs
+   *
+   * This function removes parameters that match their default values (static or dynamic)
+   * while preserving custom values and inherited parameters from ancestor routes.
+   * Parameter inheritance from parent routes is intentional - only default values
+   * for the current route's own parameters are filtered out.
    */
   const removeDefaultValues = (params) => {
     const filtered = { ...params };
 
     for (const connection of connections) {
-      const { paramName, signal } = connection;
-      const defaultValue = parameterDefaults.get(paramName);
+      const { paramName, signal, options } = connection;
 
-      if (paramName in filtered && filtered[paramName] === defaultValue) {
-        delete filtered[paramName];
-      } else if (
-        !(paramName in filtered) &&
-        signal?.value !== undefined &&
-        signal.value !== defaultValue
-      ) {
+      if (paramName in filtered) {
+        // Parameter is explicitly provided - check if we should remove it
+        if (!options.isCustomValue?.(filtered[paramName])) {
+          // Parameter value is not custom (matches default) - remove it
+          delete filtered[paramName];
+        }
+      } else if (options.isCustomValue?.(signal.value)) {
+        // Parameter not provided but signal has custom value - add it
         filtered[paramName] = signal.value;
       }
     }
@@ -7880,7 +7936,7 @@ const createRoutePattern = (pattern) => {
       const effectiveValue = userValue !== undefined ? userValue : signalValue;
       return (
         effectiveValue === literalValue &&
-        effectiveValue !== conn.options.defaultValue
+        conn.options.isCustomValue?.(effectiveValue)
       );
     });
 
@@ -7918,7 +7974,7 @@ const createRoutePattern = (pattern) => {
       const signalValue = conn.signal?.value;
       return (
         signalValue === literalValue &&
-        signalValue !== conn.options.defaultValue
+        conn.options.isCustomValue?.(signalValue)
       );
     });
 
@@ -8061,10 +8117,10 @@ const createRoutePattern = (pattern) => {
     } else {
       const { paramName: name, signal, options } = item;
       paramName = name;
-      // Only include non-default parent signal values
+      // Only include custom parent signal values (not using defaults)
       if (
         signal?.value === undefined ||
-        signal.value === options.defaultValue
+        !options.isCustomValue?.(signal.value)
       ) {
         return { isCompatible: true, shouldInclude: false };
       }
@@ -8214,7 +8270,6 @@ const createRoutePattern = (pattern) => {
 
     for (const connection of childPatternObj.connections) {
       const { paramName, signal, options } = connection;
-      const defaultValue = options.defaultValue;
 
       // Check if parameter was explicitly provided by user
       const hasExplicitParam = paramName in params;
@@ -8223,13 +8278,16 @@ const createRoutePattern = (pattern) => {
       if (hasExplicitParam) {
         // User explicitly provided this parameter - use their value
         childParams[paramName] = explicitValue;
-        if (explicitValue !== undefined && explicitValue !== defaultValue) {
+        if (
+          explicitValue !== undefined &&
+          options.isCustomValue?.(explicitValue)
+        ) {
           hasActiveParams = true;
         }
       } else if (signal?.value !== undefined) {
         // No explicit override - use signal value
         childParams[paramName] = signal.value;
-        if (signal.value !== defaultValue) {
+        if (options.isCustomValue?.(signal.value)) {
           hasActiveParams = true;
         }
       }
@@ -8309,7 +8367,7 @@ const createRoutePattern = (pattern) => {
         // Check if parameters that determine child selection are non-default
         // OR if any descendant parameters indicate explicit navigation
         for (const connection of connections) {
-          const { paramName } = connection;
+          const { paramName, options } = connection;
           const defaultValue = parameterDefaults.get(paramName);
           const resolvedValue = resolvedParams[paramName];
           const userProvidedParam = paramName in params;
@@ -8318,9 +8376,10 @@ const createRoutePattern = (pattern) => {
             // This literal corresponds to a parameter in the parent
             if (
               userProvidedParam ||
-              (resolvedValue !== undefined && resolvedValue !== defaultValue)
+              (resolvedValue !== undefined &&
+                options.isCustomValue?.(resolvedValue))
             ) {
-              // Parameter was explicitly provided or has non-default value - child is needed
+              // Parameter was explicitly provided or has custom value - child is needed
               childSpecificParamsAreDefaults = false;
               break;
             }
@@ -8421,7 +8480,7 @@ const createRoutePattern = (pattern) => {
         // If explicitly undefined, don't include it (which means don't use child route)
       } else if (
         signal?.value !== undefined &&
-        signal.value !== options.defaultValue
+        options.isCustomValue?.(signal.value)
       ) {
         // No explicit override - use signal value if non-default
         baseParams[paramName] = signal.value;
@@ -8439,7 +8498,6 @@ const createRoutePattern = (pattern) => {
       // Add parent's signal parameters
       for (const connection of parentPatternObj.connections) {
         const { paramName, signal, options } = connection;
-        const defaultValue = options.defaultValue;
 
         // Skip if child route already handles this parameter
         const childConnection = childPatternObj.connections.find(
@@ -8454,8 +8512,11 @@ const createRoutePattern = (pattern) => {
           continue; // Already have this parameter
         }
 
-        // Only include non-default signal values
-        if (signal?.value !== undefined && signal.value !== defaultValue) {
+        // Only include custom signal values (not using defaults)
+        if (
+          signal?.value !== undefined &&
+          options.isCustomValue?.(signal.value)
+        ) {
           // Skip if parameter is consumed by child's literal path segments
           const isConsumedByChildPath = childPatternObj.pattern.segments.some(
             (segment) =>
@@ -8521,10 +8582,9 @@ const createRoutePattern = (pattern) => {
 
       if (childConnection) {
         const { options } = childConnection;
-        const defaultValue = options.defaultValue;
 
-        // Only include if it's NOT the signal's default value
-        if (userValue !== defaultValue) {
+        // Only include if it's a custom value (not default)
+        if (options.isCustomValue?.(userValue)) {
           baseParams[paramName] = userValue;
         } else {
           // User provided the default value - complete omission
@@ -8584,7 +8644,7 @@ const createRoutePattern = (pattern) => {
       const hasNonDefaultChildParams = (childPatternObj.connections || []).some(
         (childConnection) => {
           const { signal, options } = childConnection;
-          return signal?.value !== options.defaultValue;
+          return options.isCustomValue?.(signal?.value);
         },
       );
 
@@ -8794,13 +8854,15 @@ const createRoutePattern = (pattern) => {
       // 2. The source route has only query parameters that are non-default
       const hasNonDefaultPathParams = connections.some((connection) => {
         const resolvedValue = resolvedParams[connection.paramName];
-        const defaultValue = connection.options.defaultValue;
+
         // Check if this is a query parameter (not in the pattern path)
         const isQueryParam = parsedPattern.queryParams.some(
           (qp) => qp.name === connection.paramName,
         );
         // Allow non-default query parameters, but not path parameters
-        return !isQueryParam && resolvedValue !== defaultValue;
+        return (
+          !isQueryParam && connection.options.isCustomValue?.(resolvedValue)
+        );
       });
 
       if (hasNonDefaultPathParams) {
@@ -8830,8 +8892,7 @@ const createRoutePattern = (pattern) => {
     // For non-immediate parents, only allow optimization if all resolved parameters have default values
     const hasNonDefaultParameters = connections.some((connection) => {
       const resolvedValue = resolvedParams[connection.paramName];
-      const defaultValue = connection.options.defaultValue;
-      return resolvedValue !== defaultValue;
+      return connection.options.isCustomValue?.(resolvedValue);
     });
 
     if (hasNonDefaultParameters) {
@@ -9100,13 +9161,12 @@ const createRoutePattern = (pattern) => {
     // Also check target ancestor's own signal values for parameters not in resolvedParams
     for (const connection of targetAncestor.connections) {
       const { paramName, signal, options } = connection;
-      const defaultValue = options.defaultValue;
 
-      // Only include if not already processed and has non-default value
+      // Only include if not already processed and has custom value (not default)
       if (
         !(paramName in ancestorParams) &&
         signal?.value !== undefined &&
-        signal.value !== defaultValue
+        options.isCustomValue?.(signal.value)
       ) {
         // Don't include path parameters that correspond to literal segments we're optimizing away
         const targetParam = targetParams.find((p) => p.name === paramName);
@@ -9136,13 +9196,12 @@ const createRoutePattern = (pattern) => {
     while (currentParent) {
       for (const connection of currentParent.connections) {
         const { paramName, signal, options } = connection;
-        const defaultValue = options.defaultValue;
 
-        // Only inherit non-default values that we don't already have
+        // Only inherit custom values (not defaults) that we don't already have
         if (
           !(paramName in ancestorParams) &&
           signal?.value !== undefined &&
-          signal.value !== defaultValue
+          options.isCustomValue?.(signal.value)
         ) {
           // Check if this parameter would be redundant with target ancestor's literal segments
           const isRedundant = isParameterRedundantWithLiteralSegments(
@@ -9217,13 +9276,12 @@ const createRoutePattern = (pattern) => {
       // Check parent's signal connections for non-default values to inherit
       for (const parentConnection of currentParent.connections) {
         const { paramName, signal, options } = parentConnection;
-        const defaultValue = options.defaultValue;
 
-        // Only inherit if we don't have this param and parent has non-default value
+        // Only inherit if we don't have this param and parent has custom value (not default)
         if (
           !(paramName in finalParams) &&
           signal?.value !== undefined &&
-          signal.value !== defaultValue
+          options.isCustomValue?.(signal.value)
         ) {
           // Don't inherit if parameter corresponds to a literal in our path
           const shouldInherit = !isParameterRedundantWithLiteralSegments(
@@ -9707,6 +9765,21 @@ const extractSearchParams = (urlObj, connections = []) => {
 /**
  * Build query parameters respecting hierarchical order from ancestor patterns
  */
+/**
+ * Build hierarchical query parameters from pattern hierarchy
+ *
+ * IMPORTANT: This function implements parameter inheritance - child routes inherit
+ * query parameters from their ancestor routes. This is intentional behavior that
+ * allows child routes to preserve context from parent routes.
+ *
+ * For example:
+ * - Parent route: /map/?lon=123
+ * - Child route: /map/isochrone?iso_lon=456
+ * - Final URL: /map/isochrone?lon=123&iso_lon=456
+ *
+ * The child route inherits 'lon' from its parent, maintaining navigation context.
+ * Only parameters that match their defaults (static or dynamic) are omitted.
+ */
 const buildHierarchicalQueryParams = (
   parsedPattern,
   params,