- const pseudoClassesFromStyleSet = new Set();
- boxPseudoNamedStyles = {};
- const visitProp = (value, name, styleContext, boxStylesTarget, styleOrigin) => {
- const isPseudoElement = name.startsWith("::");
- const isPseudoClass = name.startsWith(":");
- if (isPseudoElement || isPseudoClass) {
- styleDeps.push(name);
- pseudoClassesFromStyleSet.add(name);
- const pseudoStyleContext = {
- ...styleContext,
- styleCSSVars: {
- ...styleCSSVars,
- ...styleCSSVars[name]
- },
- pseudoName: name
- };
- const pseudoStyleKeys = Object.keys(value);
- if (isPseudoElement) {
- const pseudoElementStyles = {};
- for (const key of pseudoStyleKeys) {
- visitProp(value[key], key, pseudoStyleContext, pseudoElementStyles, "pseudo_style");
+ // Only include if not already processed and has custom value (not default)
+ const signalValue = connection.signal.value;
+ if (signalValue !== undefined) {
+ // Don't include path parameters that correspond to literal segments we're optimizing away
+ const targetParam = targetParams.find((p) => p.name === paramName);
+ const isPathParam = targetParam !== undefined; // Any param in segments is a path param
+ if (isPathParam) {
+ // Skip path parameters - we want them to use default values for optimization
+ if (DEBUG$3) {
+ console.debug(
+ `[${pattern}] tryDirectOptimization: Skipping path param ${paramName}=${signalValue} (will use default)`,
+ );
}
- boxPseudoNamedStyles[name] = pseudoElementStyles;
- return;
+ continue;
}
- const pseudoClassStyles = {};
- for (const key of pseudoStyleKeys) {
- visitProp(value[key], key, pseudoStyleContext, pseudoClassStyles, "pseudo_style");
- boxPseudoNamedStyles[name] = pseudoClassStyles;
+
+ // For query parameters, only include custom values (not defaults)
+ if (connection.isCustomValue(signalValue)) {
+ ancestorParams[paramName] = signalValue;
+ if (DEBUG$3) {
+ console.debug(
+ `[${pattern}] tryDirectOptimization: Added target signal param ${paramName}=${signalValue}`,
+ );
+ }
+ } else if (DEBUG$3) {
+ console.debug(
+ `[${pattern}] tryDirectOptimization: Skipping default value ${paramName}=${signalValue}`,
+ );
}
- return;
- }
- const context = styleOrigin === "base_style" ? "js" : "css";
- const isCss = styleOrigin === "base_style" || styleOrigin === "style";
- if (isCss) {
- addStyle(value, name, styleContext, boxStylesTarget, context);
- return;
- }
- if (name.startsWith("--")) {
- addStyle(value, name, styleContext, boxStylesTarget, context);
- return;
+ } else if (DEBUG$3) {
+ console.debug(
+ `[${pattern}] tryDirectOptimization: Skipping ${paramName}=${signalValue} - undefined value`,
+ );
}
- const isPseudoStyle = styleOrigin === "pseudo_style";
- if (isStyleProp(name)) {
- // it's a style prop, we need first to check if we have css var to handle them
- // otherwise we decide to put it either on self or child
- const visualChildPropStrategy = visualSelector && getVisualChildStylePropStrategy(name);
- const getStyle = getHowToHandleStyleProp(name);
+ }
+
+ // Then, get all ancestors starting from the target ancestor's parent (skip the target itself)
+ let currentParent = targetAncestor.parent;
+
+ while (currentParent) {
+ for (const connection of currentParent.connections) {
+ const { paramName } = connection;
+ if (paramName in ancestorParams) {
+ continue;
+ }
+
+ // Only inherit custom values (not defaults) that we don't already have
+ const signalValue = connection.signal.value;
if (
- // prop name === css style name
- !getStyle) {
- const needForwarding = addStyleMaybeForwarding(value, name, styleContext, boxStylesTarget, context, visualChildPropStrategy);
- if (needForwarding) {
- if (isPseudoStyle) ; else {
- childForwardedProps[name] = value;
- }
+ signalValue !== undefined &&
+ connection.isCustomValue(signalValue)
+ ) {
+ // Check if this parameter would be redundant with target ancestor's literal segments
+ const isRedundant = isParameterRedundantWithLiteralSegments(
+ targetAncestor.pattern,
+ currentParent.pattern,
+ paramName);
+
+ if (!isRedundant) {
+ ancestorParams[paramName] = signalValue;
}
- return;
}
- const cssValues = getStyle(value, styleContext);
- if (!cssValues) {
- return;
+ }
+
+ // Move up the parent chain
+ currentParent = currentParent.parent;
+ }
+
+ return buildUrlFromPattern(
+ targetAncestor.pattern,
+ ancestorParams,
+ targetAncestor.originalPattern,
+ targetAncestor,
+ );
+ };
+
+ /**
+ * Helper: Try to use a descendant route (simple compatibility check)
+ */
+ const tryUseDescendant = (
+ descendantPatternObj,
+ params,
+ parentResolvedParams,
+ ) => {
+ // Check basic compatibility
+ const compatibility = checkChildRouteCompatibility(
+ descendantPatternObj,
+ params,
+ );
+ if (!compatibility.isCompatible) {
+ return null;
+ }
+
+ // Check if we should use this descendant
+ const shouldUse = shouldUseChildRoute(
+ descendantPatternObj,
+ params,
+ compatibility,
+ parentResolvedParams,
+ );
+ if (!shouldUse) {
+ return null;
+ }
+
+ // Build descendant URL using buildUrl (not buildMostPreciseUrl) to prevent recursion
+ return buildChildRouteUrl(
+ descendantPatternObj,
+ params,
+ parentResolvedParams,
+ );
+ };
+
+ /**
+ * Helper: Inherit query parameters from parent patterns
+ */
+ const inheritParentParameters = (finalParams) => {
+ let currentParent = patternObject.parent;
+
+ // Traverse up the parent chain to inherit parameters
+ while (currentParent) {
+ // Check parent's signal connections for non-default values to inherit
+ // Only inherit query (search) parameters, not path parameters
+ // Path parameters are structural and correspond to specific path segments
+ for (const parentConnection of currentParent.connections) {
+ if (parentConnection.paramType === "path") {
+ continue;
}
- let needForwarding = false;
- for (const styleName of Object.keys(cssValues)) {
- const cssValue = cssValues[styleName];
- needForwarding = addStyleMaybeForwarding(cssValue, styleName, styleContext, boxStylesTarget, context, visualChildPropStrategy);
+ const { paramName } = parentConnection;
+ if (paramName in finalParams) {
+ continue; // Already have this parameter
}
- if (needForwarding) {
- if (isPseudoStyle) ; else {
- childForwardedProps[name] = value;
+
+ // Only inherit if we don't have this param and parent has custom value (not default)
+ const parentSignalValue = parentConnection.signal.value;
+ if (
+ parentSignalValue !== undefined &&
+ parentConnection.isCustomValue(parentSignalValue)
+ ) {
+ // Don't inherit if parameter corresponds to a literal in our path
+ const shouldInherit = !isParameterRedundantWithLiteralSegments(
+ parsedPattern,
+ currentParent.pattern,
+ paramName);
+
+ if (shouldInherit) {
+ finalParams[paramName] = parentSignalValue;
}
}
- return;
- }
- const cssVarName = styleCSSVars[name];
- if (cssVarName) {
- if (value !== undefined) {
- addCSSVar(value, cssVarName, boxStylesTarget);
- }
- return;
}
- // not a style prop what do we do with it?
- // When pseudoStateSelector is set, the child element is the semantic/interactive one
- // When both selectors are set the child IS the component (e.g. Button with scale
- // transform) — forward everything so it behaves like a normal element.
- // When only pseudoStateSelector is set, the box keeps its own visual identity
- // (border, background, overflow…) and the child is just the interactive/semantic
- // element inside it. Only event handlers (onXxx) belong on that child; everything
- // else stays on the box.
- if (isPseudoStyle) {
- if (shouldForwardAllToChild) ; else {
- console.warn(`unsupported pseudo style key "${name}"`);
- selfForwardedProps[name] = value;
+ // Move to the next parent up the chain
+ currentParent = currentParent.parent;
+ }
+ };
+
+ /**
+ * Helper: Build URL for current route with filtered pattern
+ */
+ const buildCurrentRouteUrl = (finalParams) => {
+ if (!parsedPattern.segments) {
+ return "/";
+ }
+
+ // Filter out parameter segments that don't have values
+ const filteredPattern = {
+ ...parsedPattern,
+ segments: parsedPattern.segments.filter((segment) => {
+ if (segment.type === "param") {
+ return segment.name in finalParams;
}
- } else if (shouldForwardAllToChild) {
- childForwardedProps[name] = value;
- } else {
- selfForwardedProps[name] = value;
- }
- return;
+ return true; // Keep literal segments
+ }),
};
- if (baseStyle) {
- for (const key of baseStyle) {
- const value = baseStyle[key];
- visitProp(value, key, styleContext, boxStyles, "baseStyle");
- }
+
+ // Remove trailing slash if we filtered out segments
+ if (
+ filteredPattern.segments.length < parsedPattern.segments.length &&
+ parsedPattern.trailingSlash
+ ) {
+ filteredPattern.trailingSlash = false;
}
- for (const propName of remainingPropKeySet) {
- const propValue = rest[propName];
- if (baseChildPropSet?.has(propName) || childPropSet?.has(propName)) {
- if (canForwardToChild) {
- childForwardedProps[propName] = propValue;
- } else {
- selfForwardedProps[propName] = propValue;
- }
- continue;
- }
- if (canForwardToChild && toCopySet.has(propName)) {
- childForwardedProps[propName] = propValue;
- }
- const isDataAttribute = propName.startsWith("data-");
- if (isDataAttribute) {
- selfForwardedProps[propName] = propValue;
- continue;
- }
- // At some point I'd like to transform all data-* attribute in the DOM
- // into navi-* attribute so that when you look at the DOM you can easily understand which attributes
- // where added by navi or your code.
- // This help human to better scan the DOM
- const isNaviAttribute = propName.startsWith("navi-");
- if (isNaviAttribute) {
- selfForwardedProps[propName] = propValue;
- continue;
- }
- const isEventHandler = propName.startsWith("on");
- if (isEventHandler) {
- if (shouldForwardAllToChild) {
- childForwardedProps[propName] = propValue;
- continue;
- }
- selfForwardedProps[propName] = propValue;
- continue;
- }
- if (canForwardToChild && pseudoStateSelector && PSEUDO_STATE_CHILD_PROP_SET.has(propName)) {
- childForwardedProps[propName] = propValue;
- continue;
- }
- visitProp(propValue, propName, styleContext, boxStyles, "prop");
+
+ return buildUrlFromPattern(
+ filteredPattern,
+ finalParams,
+ pattern,
+ patternObject,
+ );
+ };
+
+ // Returns the pathname that this route's own literal prefix resolves to.
+ // For route "/": "/"
+ // For route "/profile/": "/profile/"
+ // For route "/map/isochrone/compare": "/map/isochrone/compare"
+ // For route "/map/isochrone/:tab=/": "/map/isochrone/" (literal prefix before first param)
+ const getOwnBasePathname = () => {
+ const segments = parsedPattern.segments;
+ if (segments.length === 0) {
+ return new URL(resolveRouteUrl("/")).pathname;
}
- if (typeof style === "string") {
- const styleObject = normalizeStyles(style, "css");
- for (const styleName of Object.keys(styleObject)) {
- const styleValue = styleObject[styleName];
- visitProp(styleValue, styleName, styleContext, boxStyles, "style");
- }
- } else if (style && typeof style === "object") {
- for (const styleName of Object.keys(style)) {
- const styleValue = style[styleName];
- visitProp(styleValue, styleName, styleContext, boxStyles, "style");
+ const literalSegments = [];
+ for (const seg of segments) {
+ if (seg.type !== "literal") {
+ break;
}
+ literalSegments.push(seg.value);
}
- styleDeps.push(pseudoStateSelector, innerPseudoState);
- let innerPseudoClasses;
- if (pseudoClassesFromStyleSet.size) {
- innerPseudoClasses = [...pseudoClasses];
- if (pseudoClasses !== PSEUDO_CLASSES_DEFAULT) {
- styleDeps.push(...pseudoClasses);
- }
- for (const key of pseudoClassesFromStyleSet) {
- innerPseudoClasses.push(key);
- styleDeps.push(key);
- }
- } else {
- innerPseudoClasses = pseudoClasses;
- if (pseudoClasses !== PSEUDO_CLASSES_DEFAULT) {
- styleDeps.push(...pseudoClasses);
- }
+ if (literalSegments.length === 0) {
+ return new URL(resolveRouteUrl("/")).pathname;
}
- const syncBox = useCallback(boxEl => {
- const pseudoStateEl = pseudoStateSelector ? boxEl.querySelector(pseudoStateSelector) : boxEl;
- if (!pseudoStateEl) {
- console.error(`pseudoStateSelector "${pseudoStateSelector}" did not match any element inside the box`, boxEl);
- }
- const visualEl = visualSelector ? boxEl.querySelector(visualSelector) : null;
- return initPseudoStyles(pseudoStateEl, {
- pseudoClasses: innerPseudoClasses,
- pseudoState: innerPseudoState,
- effect: state => {
- applyStyle(boxEl, boxStyles, state, boxPseudoNamedStyles, preventInitialTransition);
- },
- elementToImpact: boxEl,
- elementListeningPseudoState: visualEl === pseudoStateEl ? null : visualEl
+ const prefix = `/${literalSegments.join("/")}/`;
+ return new URL(resolveRouteUrl(prefix)).pathname;
+ };
+
+ // Like buildMostPreciseUrl but takes the actual current browser URL into account.
+ // When buildMostPreciseUrl returns the route's own base URL (catch-all matching an
+ // unrepresentable path like "/404") the current pathname is preserved and only
+ // search params are updated. When buildMostPreciseUrl performs an ancestor
+ // optimisation (e.g. "/map/isochrone/compare" → "/map/isochrone") it is trusted
+ // as-is because the built pathname will differ from the route's own base pathname.
+ const buildUrlPreservingPath = (currentUrl, params = {}) => {
+ const relativeBuiltUrl = buildMostPreciseUrl(params);
+ if (!currentUrl) {
+ return resolveRouteUrl(relativeBuiltUrl);
+ }
+ const absoluteBuiltUrl = resolveRouteUrl(relativeBuiltUrl);
+ const builtPathname = new URL(absoluteBuiltUrl).pathname;
+ const currentPathname = new URL(currentUrl).pathname;
+ if (builtPathname === currentPathname) {
+ return absoluteBuiltUrl;
+ }
+ const ownBasePathname = getOwnBasePathname();
+ if (builtPathname === ownBasePathname) {
+ // Catch-all: the route resolved to its own base pathname but the current URL
+ // sits on a different path that this trailing-slash route caught. Keep the
+ // current pathname and only update the search string.
+ const correctedUrl = new URL(currentUrl);
+ correctedUrl.search = new URL(absoluteBuiltUrl).search;
+ return correctedUrl.href;
+ }
+ // Ancestor optimisation or descendant selection — trust buildMostPreciseUrl.
+ return absoluteBuiltUrl;
+ };
+
+ // Pattern object with unified data and methods
+ const patternObject = {
+ // Pattern data properties (formerly patternData)
+ urlPatternRaw: pattern,
+ cleanPattern,
+ connections,
+ pathConnectionMap, // Separate map for path parameters
+ queryConnectionMap, // Separate map for query parameters
+ parsedPattern,
+ signalSet,
+ children: [],
+ parent: null,
+ depth: 0, // Will be calculated after relationships are built
+ descendantPathSignals: new Map(), // Precomputed during setupPatterns (Map
)
+
+ // Pattern methods (formerly patternObj methods)
+ originalPattern: pattern,
+ pattern: parsedPattern,
+ applyOn,
+ buildMostPreciseUrl,
+ buildUrlPreservingPath,
+ resolveParams,
+ };
+
+ return patternObject;
+};
+
+// Raw URL part functionality for bypassing encoding
+const rawUrlPartSymbol = Symbol("raw_url_part");
+const rawUrlPart = (value) => {
+ return {
+ [rawUrlPartSymbol]: true,
+ value,
+ };
+};
+
+/**
+ * Encode parameter values for URL usage, with special handling for raw URL parts.
+ * When a parameter is wrapped with rawUrlPart(), it bypasses encoding and is
+ * inserted as-is into the URL.
+ */
+const encodeParamValue = (value, isWildcard = false) => {
+ if (value && value[rawUrlPartSymbol]) {
+ return value.value;
+ }
+
+ if (isWildcard) {
+ // For wildcards, only encode characters that are invalid in URL paths,
+ // but preserve slashes as they are path separators
+ return value
+ ? value.replace(/[^a-zA-Z0-9\-._~!$&'()*+,;=:@/]/g, (char) => {
+ return encodeURIComponent(char);
+ })
+ : value;
+ }
+
+ // For named parameters and search params, encode everything including slashes
+ return encodeURIComponent(value);
+};
+
+// Function to detect signals in route patterns and connect them
+const detectSignals = (routePattern) => {
+ const signalConnections = [];
+ let updatedPattern = routePattern;
+
+ // Look for path signals: :paramName={navi_state_signal:id}
+ const signalParamRegex = /(:)(\w+)(=)?(\{navi_state_signal:[^}]+\})/g;
+ let match;
+
+ while ((match = signalParamRegex.exec(routePattern)) !== null) {
+ const [fullMatch, prefix, paramName, equalSign, signalString] = match;
+
+ // Emit warning if equal sign is missing
+ if (!equalSign) {
+ console.warn(
+ `[detectSignals] Missing '=' sign in route pattern: "${prefix}${paramName}${signalString}". ` +
+ `Consider using "${prefix}${paramName}=${signalString}" for better clarity.`,
+ );
+ }
+
+ // Extract the signal ID from the format: {navi_state_signal:id}
+ const signalIdMatch = signalString.match(/\{navi_state_signal:([^}]+)\}/);
+ if (!signalIdMatch) {
+ console.warn(
+ `[detectSignals] Failed to extract signal ID from: ${signalString}`,
+ );
+ continue;
+ }
+
+ const signalId = signalIdMatch[1];
+ const signalData = globalSignalRegistry.get(signalId);
+
+ if (signalData) {
+ const { signal, options } = signalData;
+ updatedPattern = updatedPattern.replace(fullMatch, `:${paramName}`);
+ signalConnections.push({
+ paramName,
+ signal,
+ paramType: "path",
+ ...options,
});
- }, styleDeps);
- finalRef = useComposeElementRef(syncBox, ref);
- usePartiallyHidden(finalRef, Boolean(rest.viewTransitionName));
+ } else {
+ console.warn(
+ `[detectSignals] Signal not found in registry for ID: "${signalId}"`,
+ );
+ console.warn(
+ `[detectSignals] Available signal IDs in registry:`,
+ Array.from(globalSignalRegistry.keys()),
+ );
+ console.warn(`[detectSignals] Full pattern: "${routePattern}"`);
+ }
}
- let innerChildren = children;
- if (separator) {
- // Flatten nested arrays (e.g., from .map()) to treat each element as individual child
- innerChildren = applySeparatorOnChildren(innerChildren, separator);
+
+ return [updatedPattern, signalConnections];
+};
+
+/**
+ * Helper: Check if parameter matches any literal in child pattern
+ */
+const paramMatchesChildLiteral = (paramValue, childParsedPattern) => {
+ return childParsedPattern.segments.some(
+ (segment) => segment.type === "literal" && segment.value === paramValue,
+ );
+};
+
+/**
+ * Helper: Check if a parent parameter can semantically reach a child route
+ * This replaces the fragile position-based matching with semantic verification
+ */
+const canParameterReachChildRoute = (
+ paramName,
+ paramValue,
+ parentPattern,
+ childPattern,
+) => {
+ // Find the parent parameter segment
+ const parentParamSegment = parentPattern.segments.find(
+ (segment) => segment.type === "param" && segment.name === paramName,
+ );
+
+ if (!parentParamSegment) {
+ return true; // Not a path parameter, no conflict
}
- // When hasChildUsingForwardedProps is used it means
- // Some/all the children needs to access remainingProps
- // to render and will provide a function to do so.
- if (hasChildUsingForwardedProps) {
- innerChildren = jsx(BoxForwardedPropsContext.Provider, {
- value: childForwardedProps,
- children: innerChildren
+ // Get parameter's logical path position (not array index)
+ const paramPathPosition = parentParamSegment.index;
+
+ // Find corresponding child segment at the same logical path position
+ const childSegmentAtSamePosition = childPattern.segments.find(
+ (segment) => segment.index === paramPathPosition,
+ );
+
+ if (!childSegmentAtSamePosition) {
+ return true; // Child doesn't extend to this position, no conflict
+ }
+
+ if (childSegmentAtSamePosition.type === "literal") {
+ // Child has a literal at this position - parent parameter must match exactly
+ return childSegmentAtSamePosition.value === paramValue;
+ }
+
+ // Child has parameter at same position - compatible
+ return true;
+};
+
+/**
+ * Parse a route pattern string into structured segments
+ */
+const parsePattern = (pattern, { pathConnectionMap, queryConnectionMap }) => {
+ // Build queryParams from queryConnectionMap
+ const queryParams = [];
+ for (const [paramName, connection] of queryConnectionMap) {
+ queryParams.push({
+ type: "query_param",
+ name: paramName,
+ hasDefaultValue: connection.getDefaultValue() !== undefined,
});
}
- const aspectRatio = rest.square || rest.circle ? "1/1" : rest.aspectRatio;
- return jsx(TagName, {
- ref: finalRef,
- className: innerClassName,
- "navi-box-flow": boxFlowIsDefault ? undefined : boxFlow,
- "navi-box-flow-row": row ? "" : undefined,
- "navi-box-flow-column": column ? "" : undefined,
- "navi-aspect-ratio": aspectRatio ? aspectRatio : undefined,
- "data-visual-selector": visualSelector,
- ...selfForwardedProps,
- children: jsx(BoxFlowContext.Provider, {
- value: boxFlow,
- children: innerChildren
- })
+
+ // Handle root route
+ if (pattern === "/") {
+ return {
+ original: pattern,
+ segments: [],
+ trailingSlash: true,
+ wildcard: false,
+ queryParams,
+ };
+ }
+
+ // Remove leading slash for processing the path portion
+ let cleanPattern = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+
+ // Check for wildcard first
+ const wildcard = cleanPattern.endsWith("*");
+ if (wildcard) {
+ cleanPattern = cleanPattern.slice(0, -1); // Remove *
+ // Also remove the slash before * if present
+ if (cleanPattern.endsWith("/")) {
+ cleanPattern = cleanPattern.slice(0, -1);
+ }
+ }
+
+ // Check for trailing slash (after wildcard check)
+ const trailingSlash = !wildcard && pattern.endsWith("/");
+ if (trailingSlash) {
+ cleanPattern = cleanPattern.slice(0, -1); // Remove trailing /
+ }
+
+ // Split into segments (filter out empty segments)
+ const segmentStrings = cleanPattern
+ ? cleanPattern.split("/").filter((s) => s !== "")
+ : [];
+ const segments = segmentStrings.map((seg, index) => {
+ if (seg.startsWith(":")) {
+ // Parameter segment
+ const paramName = seg.slice(1).replace("?", ""); // Remove : and optional ?
+
+ // 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)
+ const connection =
+ pathConnectionMap.get(paramName) || queryConnectionMap.get(paramName);
+ const hasDefault =
+ connection && connection.getDefaultValue() !== undefined;
+ let isOptional = seg.endsWith("?") || hasDefault;
+
+ if (!isOptional) {
+ // Check if connected signal has undefined value (making parameter optional for index routes)
+ if (
+ connection &&
+ connection.signal &&
+ connection.signal.value === undefined &&
+ !hasDefault
+ ) {
+ isOptional = true;
+ }
+ }
+
+ return {
+ type: "param",
+ name: paramName,
+ optional: isOptional,
+ index,
+ };
+ }
+ // Literal segment
+ return {
+ type: "literal",
+ value: seg,
+ index,
+ };
});
+
+ return {
+ original: pattern,
+ segments,
+ queryParams, // Add query parameters to the parsed pattern
+ trailingSlash,
+ wildcard,
+ };
};
-const toCopySet = new Set([]);
-const applySeparatorOnChildren = (children, separator) => {
- const flattenedChildren = toChildArray(children);
- if (flattenedChildren.length <= 1) {
- return children;
+
+/**
+ * Check if a literal segment can be treated as optional based on pattern hierarchy
+ */
+const checkIfLiteralCanBeOptionalWithPatternObj = (
+ literalValue,
+ patternObj,
+) => {
+ if (!patternObj) {
+ return false; // No pattern object available, cannot determine optionality
}
- const childrenWithSeparators = [];
- let i = 0;
- while (true) {
- const child = flattenedChildren[i];
- childrenWithSeparators.push(child);
- i++;
- const isLast = i === flattenedChildren.length;
- if (isLast) {
- break;
- }
- const nextChild = flattenedChildren[i];
- if (!shouldInjectSeparatorBetween(child, nextChild)) {
- continue;
+
+ // Check current pattern's connections
+ for (const connection of patternObj.connections) {
+ if (connection.isDefaultValue(literalValue)) {
+ return true;
}
- // Support function separators that receive separator index
- const separatorElement = typeof separator === "function" ? separator(i - 1) // i-1 because i was incremented after pushing child
- : separator;
- childrenWithSeparators.push(separatorElement);
}
- return childrenWithSeparators;
-};
-const shouldInjectSeparatorBetween = (left, right) => {
- if (isValidElement(left) && left.props?.hidden) {
- return false;
+
+ // Check parent pattern's connections
+ let currentParent = patternObj.parent;
+ while (currentParent) {
+ for (const connection of currentParent.connections) {
+ if (connection.isDefaultValue(literalValue)) {
+ return true;
+ }
+ }
+ currentParent = currentParent.parent;
}
- if (isValidElement(right) && right.props?.hidden) {
+
+ // Check children pattern's connections
+ const checkChildrenRecursively = (pattern) => {
+ for (const child of pattern.children || []) {
+ for (const connection of child.connections) {
+ if (connection.isDefaultValue(literalValue)) {
+ return true;
+ }
+ }
+ if (checkChildrenRecursively(child)) {
+ return true;
+ }
+ }
return false;
- }
- return true;
+ };
+
+ return checkChildrenRecursively(patternObj);
};
/**
- * View transitions, made safe to call.
- *
- * Calling this installs `document.startViewTransition` when the browser has
- * none — so code that runs after it can take the API for granted — and returns
- * the function to actually call, which does two things the raw API leaves to
- * every caller:
- *
- * - It runs the update no matter what. A transition is about the animation,
- * never about the change.
- * - It swallows the rejection a SKIPPED transition produces. Starting a
- * transition while another is running skips that other one, and a skipped
- * transition rejects its promises; nothing is waiting on them, so the
- * rejection surfaces as an unhandled error (a full error overlay in dev) for
- * something that is not an error at all — two updates close together is
- * normal in a list that is being edited.
- *
- * navi calls it from wherever it animates a DOM change itself (see list.jsx),
- * which is why an application using navi finds the API already there.
- *
- * const startViewTransition = ensureDocumentStartViewTransition();
- * startViewTransition(() => setItems(next));
+ * Helper function to try extracting parameters from child routes for remaining URL segments
*/
-const ensureDocumentStartViewTransition = () => {
- if (!document.startViewTransition) {
- document.startViewTransition = (updateCallback) => {
- updateCallback();
- return {
- updateCallbackDone: Promise.resolve(),
- ready: Promise.resolve(),
- finished: Promise.resolve(),
- skipTransition: () => {},
- };
- };
- }
- return startViewTransition;
-};
+const tryExtractChildParameters = (
+ childPattern,
+ remainingSegments,
+ existingParams,
+) => {
+ const childParsedPattern = childPattern.pattern;
-const startViewTransition = (updateCallback) => {
- const viewTransition = document.startViewTransition(updateCallback);
- viewTransition.updateCallbackDone.catch(ignoreSkip);
- viewTransition.ready.catch(ignoreSkip);
- viewTransition.finished.catch(ignoreSkip);
- return viewTransition;
-};
+ // For child patterns, we need to check if they can provide additional parameters
+ // by matching segments that come after what the parent matched
-// "Skipped" is an outcome, not a failure — anything else is still a real error
-// and must keep travelling.
-const ignoreSkip = (e) => {
- if (e && e.name === "AbortError") {
- return;
- }
- if (e && typeof e.message === "string" && e.message.includes("skipped")) {
- return;
+ // The child pattern might have literals that were already matched by the parent
+ // We need to find where in the child pattern we should start matching the remaining segments
+ let remainingIndex = 0;
+ const childParams = {};
+
+ // Simple approach: look for parameter segments in the child pattern that could
+ // match our remaining segments, but skip literals that were likely matched by parent
+ for (let i = 0; i < childParsedPattern.segments.length; i++) {
+ const segment = childParsedPattern.segments[i];
+
+ if (segment.type === "param" && remainingIndex < remainingSegments.length) {
+ // Check if this parameter segment could match a remaining URL segment
+ // We need to verify that this parameter isn't already captured by parent
+ if (!(segment.name in existingParams)) {
+ const urlSegment = remainingSegments[remainingIndex];
+ childParams[segment.name] = decodeURIComponent(urlSegment);
+ remainingIndex++;
+ }
+ } else if (
+ segment.type === "literal" &&
+ remainingIndex < remainingSegments.length
+ ) {
+ // Check if this literal matches remaining segments
+ const urlSegment = remainingSegments[remainingIndex];
+ if (urlSegment === segment.value) {
+ remainingIndex++;
+ }
+ // Note: we don't return null if literal doesn't match, because it might be
+ // a literal that was already consumed by the parent pattern
+ }
}
- throw e;
+
+ // Return extracted parameters if we found any
+ return Object.keys(childParams).length > 0 ? childParams : null;
};
/**
- * Fix alignment behavior for flex/grid containers that use `height: 100%`.
- *
- * Context:
- * - When a flex/grid container has `height: 100%`, it is "height-locked".
- * - If its content becomes taller than the container, alignment rules like
- * `align-items: center` will cause content to be partially clipped.
- *
- * Goal:
- * - Center content only when it fits.
- * - Align content at start when it overflows.
- *
- * How:
- * - Temporarily remove height-constraint (`height:auto`) to measure natural height.
- * - Compare natural height to container height.
- * - Add/remove an attribute so CSS can adapt alignment.
- *
- * Usage:
- * monitorItemsOverflow(containerElement);
- *
- * CSS example:
- * .container { align-items: center; }
- * .container[data-items-height-overflow] { align-items: flex-start; }
+ * Match a URL against a parsed pattern
*/
+const matchUrl = (
+ parsedPattern,
+ url,
+ { baseUrl, baseFileUrl, queryConnectionMap, patternObj = null },
+) => {
+ // Parse the URL
+ const urlObj = new URL(url, baseUrl);
+ let pathname = urlObj.pathname;
+ const originalPathname = pathname; // Store original pathname before baseUrl processing
-
-const WIDTH_ATTRIBUTE_NAME = "data-items-width-overflow";
-const HEIGHT_ATTRIBUTE_NAME = "data-items-height-overflow";
-const monitorItemsOverflow = (container) => {
- let widthIsOverflowing;
- let heightIsOverflowing;
- const onItemsWidthOverflowChange = () => {
- if (widthIsOverflowing) {
- container.setAttribute(WIDTH_ATTRIBUTE_NAME, "");
- } else {
- container.removeAttribute(WIDTH_ATTRIBUTE_NAME);
- }
- };
- const onItemsHeightOverflowChange = () => {
- if (heightIsOverflowing) {
- container.setAttribute(HEIGHT_ATTRIBUTE_NAME, "");
- } else {
- container.removeAttribute(HEIGHT_ATTRIBUTE_NAME);
+ // If baseUrl is provided, calculate the pathname relative to the baseUrl's directory
+ if (baseUrl) {
+ const baseUrlObj = new URL(baseUrl);
+ // if the base url is a file, we want to be relative to the directory containing that file
+ const baseDir = baseUrlObj.pathname.endsWith("/")
+ ? baseUrlObj.pathname
+ : baseUrlObj.pathname.substring(0, baseUrlObj.pathname.lastIndexOf("/"));
+ if (pathname.startsWith(baseDir)) {
+ pathname = pathname.slice(baseDir.length);
}
- };
+ }
- const update = () => {
- // Save current manual height constraint
- const prevWidth = container.style.width;
- const prevHeight = container.style.height;
- // Remove constraint → get true content dimension
- container.style.width = "auto";
- container.style.height = "auto";
- const naturalWidth = container.scrollWidth;
- const naturalHeight = container.scrollHeight;
- if (prevWidth) {
- container.style.width = prevWidth;
- } else {
- container.style.removeProperty("width");
- }
- if (prevHeight) {
- container.style.height = prevHeight;
- } else {
- container.style.removeProperty("height");
+ // Handle root route - only matches empty path or just "/"
+ // OR when URL exactly matches baseUrl (treating baseUrl as root)
+ // OR any sub-path when the route has a trailing slash (prefix matching)
+ if (parsedPattern.segments.length === 0) {
+ if (pathname === "/" || pathname === "") {
+ return extractSearchParams(urlObj, queryConnectionMap);
}
- const lockedWidth = container.clientWidth;
- const lockedHeight = container.clientHeight;
- const currentWidthIsOverflowing = naturalWidth > lockedWidth;
- const currentHeightIsOverflowing = naturalHeight > lockedHeight;
- if (currentWidthIsOverflowing !== widthIsOverflowing) {
- widthIsOverflowing = currentWidthIsOverflowing;
- onItemsWidthOverflowChange();
+ // Special case: if URL exactly matches baseUrl or baseFileUrl (the HTML root file), treat as root route
+ if (baseUrl) {
+ const baseUrlObj = new URL(baseUrl);
+ if (originalPathname === baseUrlObj.pathname) {
+ return extractSearchParams(urlObj, queryConnectionMap);
+ }
}
- if (currentHeightIsOverflowing !== heightIsOverflowing) {
- heightIsOverflowing = currentHeightIsOverflowing;
- onItemsHeightOverflowChange();
+ if (baseFileUrl) {
+ const baseFileUrlObj = new URL(baseFileUrl);
+ if (originalPathname === baseFileUrlObj.pathname) {
+ return extractSearchParams(urlObj, queryConnectionMap);
+ }
}
- };
-
- const [teardown, addTeardown] = createPubSub();
-
- update();
-
- // mutation observer
- const mutationObserver = new MutationObserver(() => {
- update();
- });
- mutationObserver.observe(container, {
- childList: true,
- characterData: true,
- });
- addTeardown(() => {
- mutationObserver.disconnect();
- });
-
- // resize observer
- const resizeObserver = new ResizeObserver(update);
- resizeObserver.observe(container);
- addTeardown(() => {
- resizeObserver.disconnect();
- });
- const destroy = () => {
- teardown();
- container.removeAttribute(WIDTH_ATTRIBUTE_NAME);
- container.removeAttribute(HEIGHT_ATTRIBUTE_NAME);
- };
- return destroy;
-};
+ // Root route with trailing slash matches all sub-paths (prefix matching, like other trailing-slash routes)
+ if (parsedPattern.trailingSlash) {
+ return extractSearchParams(urlObj, queryConnectionMap);
+ }
-installImportMetaCssBuild(import.meta);/**
- * UI Transition - Core Implementation
- * Provides smooth resize transitions with cross-fade effects between content states
- *
- * Content Types and Terminology:
- *
- * - ui: What the user currently sees rendered in the UI
- * - dom_nodes: The actual DOM elements that make up the visual representation
- * - content_id: Unique identifier for a content and its content_phase(s)
- * - content_phase: Intermediate states (loading spinners, error messages, empty states)
- * - content: The primary/final content we want to display (e.g., car details, user profile)
- *
- * Required HTML structure:
- *
- *
- *
- * Architecture Overview:
- *
- * .ui_transition
- * The main container that handles dimensional transitions. Its width and height animate
- * smoothly from current to target dimensions. Has overflow:hidden to clip ui during transitions.
- *
- * .active_group
- * Contains the ui that should be active after the transition completes. Groups both the target
- * ui (.target_slot) and transitional ui (.outgoing_slot) as a single unit that can
- * be manipulated together (e.g., applying transforms or slides).
- *
- * .target_slot
- * Always contains the target ui - what should be displayed at the end of the transition.
- * Whether transitioning to content or content_phase, this slot receives the new dom_nodes.
- * Receives fade-in transitions (opacity 0 → 1) during all transition types.
- *
- * .outgoing_slot
- * Holds content_phase that's being replaced during content_phase transitions. When transitioning
- * from one content_phase to another, or from content_phase to content, the old content_phase moves
- * here for fade-out. Receives fade-out transitions (opacity 1 → 0).
- *
- * .previous_group
- * Used for content-to-content transitions. When switching between content (not phases),
- * the entire .active_group dom_nodes are cloned here to fade out while the new content fades in.
- * Can slide out when sliding transitions are enabled, otherwise fades out.
- *
- * Transition Scenarios:
- * - content → content: Car A details → Car B details (clone to previous_group)
- * - content_phase → content_phase: Loading state → Error state (move to outgoing_slot, same content_id)
- * - content → content_phase: Car A details → Loading Car B (use outgoing_slot for cross-fade)
- * - content_phase → content: Loading Car B → Car B details (use outgoing_slot for cross-fade)
- *
- * Size Transition Handling:
- * During dimensional transitions, both .target_slot and .outgoing_slot have their dimensions
- * explicitly set to prevent dom_nodes reflow and maintain visual consistency.
- */
-import.meta.css = [/* css */`
- * {
- box-sizing: border-box;
+ return null;
}
- .ui_transition {
- --transition-duration: 300ms;
- --justify-content: center;
- --align-items: center;
+ // Remove leading slash and split into segments
+ let urlSegments = pathname.startsWith("/")
+ ? pathname
+ .slice(1)
+ .split("/")
+ .filter((s) => s !== "")
+ : pathname.split("/").filter((s) => s !== "");
- --x-transition-duration: var(--transition-duration);
- --x-justify-content: var(--justify-content);
- --x-align-items: var(--align-items);
+ // Handle trailing slash flexibility: if pattern has trailing slash but URL doesn't (or vice versa)
+ // and we're at the end of segments, allow the match
+ const urlHasTrailingSlash = pathname.endsWith("/") && pathname !== "/";
+ const patternHasTrailingSlash = parsedPattern.trailingSlash;
- position: relative;
- }
- /* Alignment controls */
- .ui_transition[data-align-x="start"] {
- --x-justify-content: flex-start;
- }
- .ui_transition[data-align-x="center"] {
- --x-justify-content: center;
- }
- .ui_transition[data-align-x="end"] {
- --x-justify-content: flex-end;
- }
- .ui_transition[data-align-y="start"] {
- --x-align-items: flex-start;
- }
- .ui_transition[data-align-y="center"] {
- --x-align-items: center;
- }
- .ui_transition[data-align-y="end"] {
- --x-align-items: flex-end;
- }
+ const params = {};
+ let urlSegmentIndex = 0;
- .ui_transition,
- .ui_transition_active_group,
- .ui_transition_previous_group,
- .ui_transition_target_slot,
- .ui_transition_previous_target_slot,
- .ui_transition_outgoing_slot,
- .ui_transition_previous_outgoing_slot {
- width: 100%;
- height: 100%;
- }
+ // Process each pattern segment
+ for (let i = 0; i < parsedPattern.segments.length; i++) {
+ const patternSeg = parsedPattern.segments[i];
- .ui_transition_target_slot,
- .ui_transition_outgoing_slot,
- .ui_transition_previous_target_slot,
- .ui_transition_previous_outgoing_slot {
- display: flex;
- align-items: var(--x-align-items);
- justify-content: var(--x-justify-content);
- }
- .ui_transition_target_slot[data-items-width-overflow],
- .ui_transition_previous_target_slot[data-items-width-overflow],
- .ui_transition_previous_target_slot[data-items-width-overflow],
- .ui_transition_previous_outgoing_slot[data-items-width-overflow] {
- --x-justify-content: flex-start;
- }
- .ui_transition_target_slot[data-items-height-overflow],
- .ui_transition_previous_slot[data-items-height-overflow],
- .ui_transition_previous_target_slot[data-items-height-overflow],
- .ui_transition_previous_outgoing_slot[data-items-height-overflow] {
- --x-align-items: flex-start;
- }
+ if (patternSeg.type === "literal") {
+ // Check if URL has this segment
+ if (urlSegmentIndex >= urlSegments.length) {
+ // URL is too short for this literal segment
+ // Check if this literal segment can be treated as optional based on pattern hierarchy
+ const canBeOptional = checkIfLiteralCanBeOptionalWithPatternObj(
+ patternSeg.value,
+ patternObj,
+ );
+ if (canBeOptional) {
+ // Skip this literal segment, don't increment urlSegmentIndex
+ continue;
+ }
+ return null; // URL too short and literal is not optional
+ }
- .ui_transition_active_group {
- position: relative;
- }
- .ui_transition_target_slot {
- position: relative;
- }
- .ui_transition_outgoing_slot,
- .ui_transition_previous_outgoing_slot {
- position: absolute;
- top: 0;
- left: 0;
- }
- .ui_transition_previous_group {
- position: absolute;
- inset: 0;
- }
- .ui_transition[data-only-previous-group] .ui_transition_previous_group {
- position: relative;
+ const urlSeg = urlSegments[urlSegmentIndex];
+ if (urlSeg !== patternSeg.value) {
+ // Literal mismatch - this route doesn't match this URL
+ return null;
+ }
+ urlSegmentIndex++;
+ } else if (patternSeg.type === "param") {
+ // Parameter segment
+ if (urlSegmentIndex >= urlSegments.length) {
+ // No URL segment for this parameter
+ if (patternSeg.optional) {
+ // Optional parameter - don't add default here, let resolveParams handle it
+ continue;
+ }
+ // Required parameter missing - but check if we can use trailing slash logic
+ // If this is the last segment and we have a trailing slash difference, it might still match
+ const isLastSegment = i === parsedPattern.segments.length - 1;
+ if (isLastSegment && patternHasTrailingSlash && !urlHasTrailingSlash) {
+ // Pattern expects trailing slash segment, URL doesn't have it - allow missing optional param
+ continue;
+ }
+ return null; // Required parameter missing
+ }
+
+ // Capture URL segment as parameter value
+ const urlSeg = urlSegments[urlSegmentIndex];
+ params[patternSeg.name] = decodeURIComponent(urlSeg);
+ urlSegmentIndex++;
+ }
}
- .ui_transition_target_slot_background {
- position: absolute;
- top: 0;
- left: 0;
- z-index: -1;
- display: none;
- width: var(--target-slot-width, 100%);
- height: var(--target-slot-height, 100%);
- background: var(--target-slot-background, transparent);
- pointer-events: none;
+ // 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)
+ if (
+ !parsedPattern.wildcard &&
+ !parsedPattern.trailingSlash &&
+ urlSegmentIndex < urlSegments.length
+ ) {
+ return null; // Pattern without trailing slash/wildcard should not match extra segments
}
- .ui_transition[data-transitioning] .ui_transition_target_slot_background {
- display: block;
+
+ // If there are remaining URL segments and we have descendant routes,
+ // try to capture parameters from descendant routes
+ if (
+ urlSegmentIndex < urlSegments.length &&
+ patternObj &&
+ patternObj.children
+ ) {
+ const remainingSegments = urlSegments.slice(urlSegmentIndex);
+
+ // Try to match remaining segments against child routes to extract their parameters
+ for (const childPattern of patternObj.children) {
+ const childParams = tryExtractChildParameters(
+ childPattern,
+ remainingSegments,
+ params,
+ );
+ if (childParams) {
+ Object.assign(params, childParams);
+ break; // Found a matching child pattern
+ }
+ }
}
-`, "@jsenv/navi/src/transition/ui_transition.js"];
-const CONTENT_ID_ATTRIBUTE = "data-content-id";
-const CONTENT_PHASE_ATTRIBUTE = "data-content-phase";
-const UNSET = {
- domNodes: [],
- domNodesClone: [],
- isEmpty: true,
- type: "unset",
- contentId: "unset",
- contentPhase: undefined,
- isContentPhase: false,
- isContent: false,
- toString: () => "unset"
-};
-const isSameConfiguration = (configA, configB) => {
- return configA.toString() === configB.toString();
+
+ // Add search parameters
+ const searchParams = extractSearchParams(urlObj, queryConnectionMap);
+ Object.assign(params, searchParams);
+
+ // Don't add defaults here - rawParams should only contain what's in the URL
+ // Defaults are handled by resolveParams() to create the final merged parameters
+
+ return params;
};
-const createUITransitionController = (root, {
- duration = 300,
- alignX = "center",
- alignY = "center",
- onStateChange = () => {},
- pauseBreakpoints = []
-} = {}) => {
- const debugConfig = {
- detection: root.hasAttribute("data-debug-detection"),
- size: root.hasAttribute("data-debug-size")
- };
- const hasDebugLogs = debugConfig.size;
- const debugDetection = message => {
- if (!debugConfig.detection) return;
- console.debug(`[detection]`, message);
- };
- const debugSize = message => {
- if (!debugConfig.size) return;
- console.debug(`[size]`, message);
- };
- const activeGroup = root.querySelector(".ui_transition_active_group");
- const targetSlot = root.querySelector(".ui_transition_target_slot");
- const outgoingSlot = root.querySelector(".ui_transition_outgoing_slot");
- const previousGroup = root.querySelector(".ui_transition_previous_group");
- const previousTargetSlot = previousGroup?.querySelector(".ui_transition_previous_target_slot");
- const previousOutgoingSlot = previousGroup?.querySelector(".ui_transition_previous_outgoing_slot");
- if (!root || !activeGroup || !targetSlot || !outgoingSlot || !previousGroup || !previousTargetSlot || !previousOutgoingSlot) {
- throw new Error("createUITransitionController requires element with .active_group, .target_slot, .outgoing_slot, .previous_group, .previous_target_slot, and .previous_outgoing_slot elements");
- }
- // we maintain a background copy behind target slot to avoid showing
- // the body flashing during the fade-in
- const targetSlotBackground = document.createElement("div");
- targetSlotBackground.className = "ui_transition_target_slot_background";
- activeGroup.insertBefore(targetSlotBackground, targetSlot);
- root.style.setProperty("--x-transition-duration", `${duration}ms`);
- outgoingSlot.setAttribute("inert", "");
- previousGroup.setAttribute("inert", "");
- const detectConfiguration = (slot, {
- contentId,
- contentPhase
- } = {}) => {
- const domNodes = Array.from(slot.childNodes);
- if (!domNodes) {
- return UNSET;
- }
- const isEmpty = domNodes.length === 0;
- let textNodeCount = 0;
- let elementNodeCount = 0;
- let firstElementNode;
- const domNodesClone = [];
- if (isEmpty) {
- if (contentPhase === undefined) {
- contentPhase = "empty";
- }
- } else {
- const contentIdSlotAttr = slot.getAttribute(CONTENT_ID_ATTRIBUTE);
- let contentIdChildAttr;
- for (const domNode of domNodes) {
- if (domNode.nodeType === Node.TEXT_NODE) {
- textNodeCount++;
- } else {
- if (!firstElementNode) {
- firstElementNode = domNode;
- }
- elementNodeCount++;
- if (domNode.hasAttribute("data-content-phase")) {
- const contentPhaseAttr = domNode.getAttribute("data-content-phase");
- contentPhase = contentPhaseAttr || "attr";
- }
- if (domNode.hasAttribute("data-content-key")) {
- contentIdChildAttr = domNode.getAttribute("data-content-key");
- }
+/**
+ * Build query string from parameters, respecting rawUrlPart values
+ */
+const buildQueryString = (params) => {
+ const searchParamPairs = [];
+
+ for (const [key, value] of Object.entries(params)) {
+ if (value !== undefined && value !== null) {
+ const encodedKey = encodeURIComponent(key);
+
+ // Handle array values - join with commas
+ if (Array.isArray(value)) {
+ if (value.length === 0) ; else {
+ const encodedValue = value
+ .map((item) => encodeURIComponent(String(item)))
+ .join(",");
+ searchParamPairs.push(`${encodedKey}=${encodedValue}`);
}
- const domNodeClone = domNode.cloneNode(true);
- domNodesClone.push(domNodeClone);
}
- if (contentIdSlotAttr && contentIdChildAttr) {
- console.warn(`Slot and slot child both have a [${CONTENT_ID_ATTRIBUTE}]. Slot is ${contentIdSlotAttr} and child is ${contentIdChildAttr}, using the child.`);
+ // Handle boolean values - if true, just add the key without value
+ else if (value === true || value === "") {
+ searchParamPairs.push(encodedKey);
}
- if (contentId === undefined) {
- contentId = contentIdChildAttr || contentIdSlotAttr || undefined;
+ // Handle Date objects - format as YYYY-MM-DD using UTC to match new Date('YYYY-MM-DD') semantics
+ else if (value instanceof Date) {
+ const yyyy = value.getUTCFullYear();
+ const mm = String(value.getUTCMonth() + 1).padStart(2, "0");
+ const dd = String(value.getUTCDate()).padStart(2, "0");
+ searchParamPairs.push(`${encodedKey}=${yyyy}-${mm}-${dd}`);
+ } else {
+ const encodedValue = encodeParamValue(value, false); // Search params encode slashes
+ searchParamPairs.push(`${encodedKey}=${encodedValue}`);
}
}
- const isOnlyTextNodes = elementNodeCount === 0 && textNodeCount > 1;
- const singleElementNode = elementNodeCount === 1 ? firstElementNode : null;
- contentId = contentId || getElementSignature(domNodes[0]);
- if (!contentPhase && isEmpty) {
- // Imagine code rendering null while switching to a new content
- // or even while staying on the same content.
- // In the UI we want to consider this as an "empty" phase.
- // meaning the ui will keep the same size until something else happens
- // This prevent layout shifts of code not properly handling
- // intermediate states.
- contentPhase = "empty";
- }
- let width;
- let height;
- let borderRadius;
- let border;
- let background;
- if (isEmpty) {
- debugSize(`measureSlot(".${slot.className}") -> it is empty`);
- } else if (singleElementNode) {
- const visualSelector = singleElementNode.getAttribute("data-visual-selector");
- const visualElement = visualSelector ? singleElementNode.querySelector(visualSelector) || singleElementNode : singleElementNode;
- const rect = visualElement.getBoundingClientRect();
- width = rect.width;
- height = rect.height;
- debugSize(`measureSlot(".${slot.className}") -> [${width}x${height}]`);
- borderRadius = getBorderRadius(visualElement);
- border = getComputedStyle(visualElement).border;
- background = getComputedStyle(visualElement).background;
- } else {
- // text, multiple elements
- const rect = slot.getBoundingClientRect();
- width = rect.width;
- height = rect.height;
- debugSize(`measureSlot(".${slot.className}") -> [${width}x${height}]`);
- }
- const commonProperties = {
- domNodes,
- domNodesClone,
- isEmpty,
- isOnlyTextNodes,
- singleElementNode,
- width,
- height,
- borderRadius,
- border,
- background,
- contentId
- };
- if (contentPhase) {
- return {
- ...commonProperties,
- type: "content_phase",
- contentPhase,
- isContentPhase: true,
- isContent: false,
- toString: () => `content(${contentId}).phase(${contentPhase})`
- };
- }
- return {
- ...commonProperties,
- type: "content",
- contentPhase: undefined,
- isContentPhase: false,
- isContent: true,
- toString: () => `content(${contentId})`
- };
- };
- const targetSlotInitialConfiguration = detectConfiguration(targetSlot);
- const outgoingSlotInitialConfiguration = detectConfiguration(outgoingSlot, {
- contentPhase: "true"
- });
- let targetSlotConfiguration = targetSlotInitialConfiguration;
- let outgoingSlotConfiguration = outgoingSlotInitialConfiguration;
- let previousTargetSlotConfiguration = UNSET;
- const updateSlotAttributes = () => {
- if (targetSlotConfiguration.isEmpty && outgoingSlotConfiguration.isEmpty) {
- root.setAttribute("data-only-previous-group", "");
+ }
+
+ return searchParamPairs.join("&");
+};
+
+/**
+ * Extract search parameters from URL
+ */
+const extractSearchParams = (urlObj, queryConnectionMap) => {
+ const params = {};
+
+ // Parse the raw query string manually instead of using urlObj.searchParams
+ // This is necessary for array parameters to handle encoded commas correctly.
+ // urlObj.searchParams automatically decodes %2C to , which breaks our comma-based array splitting.
+ //
+ // Design choice: We use comma-separated values (colors=red,blue,green) instead of
+ // the standard repeated parameters (colors=red&colors=blue&colors=green) because:
+ // 1. More human-readable URLs
+ // 2. Shorter URL length
+ // 3. Easier to copy/paste and manually edit
+ if (!urlObj.search) {
+ return params;
+ }
+
+ const rawQuery = urlObj.search.slice(1); // Remove leading ?
+ const pairs = rawQuery.split("&");
+
+ for (const pair of pairs) {
+ const eqIndex = pair.indexOf("=");
+ let key;
+ let rawValue;
+
+ if (eqIndex > -1) {
+ key = decodeURIComponent(pair.slice(0, eqIndex));
+ rawValue = pair.slice(eqIndex + 1); // Keep raw for array processing
} else {
- root.removeAttribute("data-only-previous-group");
- }
- };
- const updateAlignment = () => {
- // Set data attributes for CSS-based alignment
- root.setAttribute("data-align-x", alignX);
- root.setAttribute("data-align-y", alignY);
- };
- const moveConfigurationIntoSlot = (configuration, slot) => {
- slot.innerHTML = "";
- for (const domNode of configuration.domNodesClone) {
- slot.appendChild(domNode);
- }
- // in case border or stuff like that have changed we re-detect the config
- const updatedConfig = detectConfiguration(slot);
- if (slot === targetSlot) {
- targetSlotConfiguration = updatedConfig;
- } else if (slot === outgoingSlot) {
- outgoingSlotConfiguration = updatedConfig;
- } else if (slot === previousTargetSlot) {
- previousTargetSlotConfiguration = updatedConfig;
- } else if (slot === previousOutgoingSlot) ; else {
- throw new Error("Unknown slot for applyConfiguration");
+ key = decodeURIComponent(pair);
+ rawValue = "";
}
- };
- updateAlignment();
- let transitionType = "none";
- const groupTransitionOptions = {
- // debugBreakpoints: [0.25],
- pauseBreakpoints,
- lifecycle: {
- setup: () => {
- updateSlotAttributes();
- root.setAttribute("data-transitioning", "");
- onStateChange({
- isTransitioning: true
- });
- return {
- teardown: () => {
- root.removeAttribute("data-transitioning");
- updateSlotAttributes(); // Update positioning after transition
- onStateChange({
- isTransitioning: false
- });
- }
- };
+
+ const connection = queryConnectionMap.get(key);
+ const signalType = connection ? connection.type : null;
+
+ // Cast value based on signal type
+ if (signalType === "array") {
+ // Handle array query parameters with proper comma encoding:
+ // ?colors=red,blue,green → ["red", "blue", "green"]
+ // ?colors=red,blue%2Cgreen → ["red", "blue,green"] (comma in value)
+ // ?colors= → []
+ // ?colors → []
+ if (rawValue === "") {
+ params[key] = [];
+ } else {
+ params[key] = rawValue
+ .split(",")
+ .map((item) => decodeURIComponent(item))
+ .filter((item) => item.trim() !== "");
}
+ } else if (signalType === "number" || signalType === "float") {
+ const decodedValue = decodeURIComponent(rawValue);
+ const numberValue = Number(decodedValue);
+ params[key] = isNaN(numberValue) ? decodedValue : numberValue;
+ } else if (signalType === "boolean") {
+ const decodedValue = decodeURIComponent(rawValue);
+ // Handle boolean query parameters:
+ // ?walk=true → true
+ // ?walk=1 → true
+ // ?walk → true (parameter present without value)
+ // ?walk=false → false
+ // ?walk=0 → false
+ params[key] =
+ decodedValue === "true" || decodedValue === "1" || decodedValue === "";
+ } else if (signalType === "date") {
+ const decodedValue = decodeURIComponent(rawValue);
+ // Keep as "YYYY-MM-DD" string — canonical date form, no timezone conversion
+ params[key] = decodedValue.slice(0, 10);
+ } else if (signalType === "datetime") {
+ const decodedValue = decodeURIComponent(rawValue);
+ // Normalize to ISO string — canonical datetime form
+ const d = new Date(decodedValue);
+ params[key] = isNaN(d.getTime()) ? decodedValue : d.toISOString();
+ } else {
+ params[key] = decodeURIComponent(rawValue);
}
- };
- const transitionController = createGroupTransitionController(groupTransitionOptions);
- const elementToClip = root;
- const morphContainerIntoTarget = () => {
- const morphTransitions = [];
- {
- // TODO: ideally when scrollContainer is document AND we transition
- // from a layout with scrollbar to a layout without
- // we have clip path detecting we go from a given width/height to a new width/height
- // that might just be the result of scrollbar appearing/disappearing
- // we should detect when this happens to avoid clipping what correspond to the scrollbar presence toggling
- const fromWidth = previousTargetSlotConfiguration.width || 0;
- const fromHeight = previousTargetSlotConfiguration.height || 0;
- const toWidth = targetSlotConfiguration.width || 0;
- const toHeight = targetSlotConfiguration.height || 0;
- debugSize(`transition from [${fromWidth}x${fromHeight}] to [${toWidth}x${toHeight}]`);
- const restoreOverflow = preventIntermediateScrollbar(root, {
- fromWidth,
- fromHeight,
- toWidth,
- toHeight,
- onPrevent: ({
- x,
- y,
- scrollContainer
- }) => {
- if (x) {
- debugSize(`Temporarily hiding horizontal overflow during transition on ${getElementSignature(scrollContainer)}`);
- }
- if (y) {
- debugSize(`Temporarily hiding vertical overflow during transition on ${getElementSignature(scrollContainer)}`);
- }
- },
- onRestore: () => {
- debugSize(`Restored overflow after transition`);
- }
- });
- const onSizeTransitionFinished = () => {
- // Restore overflow when transition is complete
- restoreOverflow();
- };
+ }
- // https://emilkowal.ski/ui/the-magic-of-clip-path
- const elementToClipRect = elementToClip.getBoundingClientRect();
- const elementToClipWidth = elementToClipRect.width;
- const elementToClipHeight = elementToClipRect.height;
- // Calculate where content is positioned within the large container
- const getAlignedPosition = (containerSize, contentSize, align) => {
- switch (align) {
- case "start":
- return 0;
- case "end":
- return containerSize - contentSize;
- case "center":
- default:
- return (containerSize - contentSize) / 2;
- }
- };
- // Position of "from" content within large container
- const fromLeft = getAlignedPosition(elementToClipWidth, fromWidth, alignX);
- const fromTop = getAlignedPosition(elementToClipHeight, fromHeight, alignY);
- // Position of target content within large container
- const targetLeft = getAlignedPosition(elementToClipWidth, toWidth, alignX);
- const targetTop = getAlignedPosition(elementToClipHeight, toHeight, alignY);
- debugSize(`Positions in container: from [${fromLeft},${fromTop}] ${fromWidth}x${fromHeight} to [${targetLeft},${targetTop}] ${toWidth}x${toHeight}`);
- // Get border-radius values
- const fromBorderRadius = previousTargetSlotConfiguration.borderRadius || 0;
- const toBorderRadius = targetSlotConfiguration.borderRadius || 0;
- const startInsetTop = fromTop;
- const startInsetRight = elementToClipWidth - (fromLeft + fromWidth);
- const startInsetBottom = elementToClipHeight - (fromTop + fromHeight);
- const startInsetLeft = fromLeft;
- const endInsetTop = targetTop;
- const endInsetRight = elementToClipWidth - (targetLeft + toWidth);
- const endInsetBottom = elementToClipHeight - (targetTop + toHeight);
- const endInsetLeft = targetLeft;
- const startClipPath = `inset(${startInsetTop}px ${startInsetRight}px ${startInsetBottom}px ${startInsetLeft}px round ${fromBorderRadius}px)`;
- const endClipPath = `inset(${endInsetTop}px ${endInsetRight}px ${endInsetBottom}px ${endInsetLeft}px round ${toBorderRadius}px)`;
- // Create clip-path animation using Web Animations API
- const clipAnimation = elementToClip.animate([{
- clipPath: startClipPath
- }, {
- clipPath: endClipPath
- }], {
- duration,
- easing: "ease",
- fill: "forwards"
- });
+ return params;
+};
- // Handle finish
- clipAnimation.finished.then(() => {
- // Clear clip-path to restore normal behavior
- elementToClip.style.clipPath = "";
- clipAnimation.cancel();
- onSizeTransitionFinished();
- }).catch(() => {
- // Animation was cancelled
- });
- clipAnimation.play();
+/**
+ * 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,
+ originalPattern,
+ patternObj,
+) => {
+ const queryParams = {};
+ const processedParams = new Set();
+
+ // Get pattern data for this pattern - use direct pattern object or null
+ const patternData = patternObj;
+
+ // Collect all ancestors by traversing parent chain - only if we have pattern data
+ const ancestorPatterns = [];
+ if (patternData) {
+ let currentParent = patternData.parent;
+ while (currentParent) {
+ ancestorPatterns.unshift(currentParent); // Add to front for correct order
+ // Move to next parent in the chain
+ currentParent = currentParent.parent;
}
- return morphTransitions;
- };
- const fadeInTargetSlot = () => {
- targetSlotBackground.style.setProperty("--target-slot-background", targetSlotConfiguration.background);
- targetSlotBackground.style.setProperty("--target-slot-width", `${targetSlotConfiguration.width || 0}px`);
- targetSlotBackground.style.setProperty("--target-slot-height", `${targetSlotConfiguration.height || 0}px`);
- return createOpacityTransition(targetSlot, 1, {
- from: 0,
- duration,
- styleSynchronizer: "inline_style",
- onFinish: targetSlotOpacityTransition => {
- targetSlotBackground.style.removeProperty("--target-slot-background");
- targetSlotBackground.style.removeProperty("--target-slot-width");
- targetSlotBackground.style.removeProperty("--target-slot-height");
- targetSlotOpacityTransition.cancel();
- }
- });
- };
- const fadeOutPreviousGroup = () => {
- return createOpacityTransition(previousGroup, 0, {
- from: 1,
- duration,
- styleSynchronizer: "inline_style",
- onFinish: previousGroupOpacityTransition => {
- previousGroupOpacityTransition.cancel();
- previousGroup.style.opacity = "0"; // keep previous group visually hidden
- }
- });
- };
- const fadeOutOutgoingSlot = () => {
- return createOpacityTransition(outgoingSlot, 0, {
- duration,
- from: 1,
- styleSynchronizer: "inline_style",
- onFinish: outgoingSlotOpacityTransition => {
- outgoingSlotOpacityTransition.cancel();
- outgoingSlot.style.opacity = "0"; // keep outgoing slot visually hidden
- }
- });
- };
+ }
- // content_to_content transition (uses previous_group)
- const applyContentToContentTransition = toConfiguration => {
- // 1. move target slot to previous
- moveConfigurationIntoSlot(targetSlotConfiguration, previousTargetSlot);
- targetSlotConfiguration = toConfiguration;
- // 2. move outgoing slot to previous
- moveConfigurationIntoSlot(outgoingSlotConfiguration, previousOutgoingSlot);
- moveConfigurationIntoSlot(UNSET, outgoingSlot);
- const transitions = [...morphContainerIntoTarget(), fadeInTargetSlot(), fadeOutPreviousGroup()];
- const transition = transitionController.update(transitions, {
- onFinish: () => {
- moveConfigurationIntoSlot(UNSET, previousTargetSlot);
- moveConfigurationIntoSlot(UNSET, previousOutgoingSlot);
- if (hasDebugLogs) {
- console.groupEnd();
+ // DEBUG: Log what we found
+ if (DEBUG$3) {
+ // Force debug for now
+ console.debug(`Building params for ${originalPattern}`);
+ console.debug(`parsedPattern:`, parsedPattern.original);
+ console.debug(`params:`, params);
+ console.debug(
+ `ancestorPatterns:`,
+ ancestorPatterns.map((p) => p.urlPatternRaw),
+ );
+ }
+
+ // Step 1: Add query parameters from ancestor patterns (oldest to newest)
+ // This ensures ancestor parameters come first in their declaration order
+ // ancestorPatterns is in correct order: root ancestor first, then immediate parent
+
+ for (const ancestorPatternObj of ancestorPatterns) {
+ for (const queryParam of ancestorPatternObj.parsedPattern.queryParams) {
+ const paramName = queryParam.name;
+ if (params[paramName] !== undefined && !processedParams.has(paramName)) {
+ queryParams[paramName] = params[paramName];
+ processedParams.add(paramName);
+
+ if (DEBUG$3) {
+ console.debug(
+ `Added ancestor param: ${paramName}=${params[paramName]}`,
+ );
}
}
- });
- transition.play();
- };
- // content_phase_to_content_phase transition (uses outgoing_slot)
- const applyContentPhaseToContentPhaseTransition = toConfiguration => {
- // 1. Move target slot to outgoing
- moveConfigurationIntoSlot(targetSlotConfiguration, outgoingSlot);
- targetSlotConfiguration = toConfiguration;
- const transitions = [...morphContainerIntoTarget(), fadeInTargetSlot(), fadeOutOutgoingSlot()];
- const transition = transitionController.update(transitions, {
- onFinish: () => {
- moveConfigurationIntoSlot(UNSET, outgoingSlot);
- if (hasDebugLogs) {
- console.groupEnd();
+ }
+ }
+
+ // Step 2: Add query parameters from current pattern
+ if (parsedPattern.queryParams) {
+ if (DEBUG$3) {
+ console.debug(
+ `Processing current pattern query params:`,
+ parsedPattern.queryParams.map((q) => q.name),
+ );
+ }
+
+ for (const queryParam of parsedPattern.queryParams) {
+ const paramName = queryParam.name;
+ if (params[paramName] !== undefined && !processedParams.has(paramName)) {
+ queryParams[paramName] = params[paramName];
+ processedParams.add(paramName);
+
+ if (DEBUG$3) {
+ console.debug(
+ `Added current param: ${paramName}=${params[paramName]}`,
+ );
}
}
- });
- transition.play();
- };
- // any_to_empty transition
- const applyToEmptyTransition = () => {
- // 1. move target slot to previous
- moveConfigurationIntoSlot(targetSlotConfiguration, previousTargetSlot);
- targetSlotConfiguration = UNSET;
- // 2. move outgoing slot to previous
- moveConfigurationIntoSlot(outgoingSlotConfiguration, previousOutgoingSlot);
- outgoingSlotConfiguration = UNSET;
- const transitions = [...morphContainerIntoTarget(), fadeOutPreviousGroup()];
- const transition = transitionController.update(transitions, {
- onFinish: () => {
- moveConfigurationIntoSlot(UNSET, previousTargetSlot);
- moveConfigurationIntoSlot(UNSET, previousOutgoingSlot);
- if (hasDebugLogs) {
- console.groupEnd();
- }
+ }
+ }
+
+ // Step 3: Add remaining parameters (extra params) alphabetically
+ const extraParams = [];
+
+ // Get all path parameter names to exclude them
+ const pathParamNames = new Set(
+ parsedPattern.segments.filter((s) => s.type === "param").map((s) => s.name),
+ );
+
+ for (const [key, value] of Object.entries(params)) {
+ if (
+ !pathParamNames.has(key) &&
+ !processedParams.has(key) &&
+ value !== undefined
+ ) {
+ extraParams.push([key, value]);
+ }
+ }
+
+ // Sort extra params alphabetically for consistent order
+ extraParams.sort(([a], [b]) => a.localeCompare(b));
+
+ // Add sorted extra params
+ for (const [key, value] of extraParams) {
+ queryParams[key] = value;
+ }
+
+ return queryParams;
+};
+
+/**
+ * Build a URL from a pattern and parameters
+ */
+const buildUrlFromPattern = (
+ parsedPattern,
+ params = {},
+ originalPattern = null,
+ patternObj = null,
+) => {
+ if (parsedPattern.segments.length === 0) {
+ // Root route
+ const queryParams = {};
+ for (const [key, value] of Object.entries(params)) {
+ if (value !== undefined) {
+ queryParams[key] = value;
+ }
+ }
+ const search = buildQueryString(queryParams);
+ return `/${search ? `?${search}` : ""}`;
+ }
+
+ const segments = [];
+
+ for (const patternSeg of parsedPattern.segments) {
+ if (patternSeg.type === "literal") {
+ segments.push(patternSeg.value);
+ } else if (patternSeg.type === "param") {
+ const value = params[patternSeg.name];
+
+ // If value is provided, include it
+ if (value !== undefined) {
+ segments.push(encodeParamValue(value, false)); // Named parameters encode slashes
+ } else if (!patternSeg.optional) {
+ // For required parameters without values, keep the placeholder
+ segments.push(`:${patternSeg.name}`);
}
+ // Optional parameters with undefined values are omitted
+ }
+ }
+
+ let path = `/${segments.join("/")}`;
+
+ // Handle trailing slash - only add if it serves a purpose
+ if (parsedPattern.trailingSlash && !path.endsWith("/") && path !== "/") {
+ // Only add trailing slash if the original pattern suggests there could be more content
+ // For patterns like "/admin/:section/" where the slash is at the very end,
+ // it's not needed in the generated URL if there are no more segments
+ const lastSegment =
+ parsedPattern.segments[parsedPattern.segments.length - 1];
+ const hasMorePotentialContent =
+ parsedPattern.wildcard || (lastSegment && lastSegment.type === "literal"); // Only add slash after literals, not parameters
+
+ if (hasMorePotentialContent) {
+ path += "/";
+ }
+ } else if (
+ !parsedPattern.trailingSlash &&
+ path.endsWith("/") &&
+ path !== "/"
+ ) {
+ // Remove trailing slash for patterns without trailing slash
+ path = path.slice(0, -1);
+ }
+
+ // Check if we'll have query parameters to decide on trailing slash removal
+ const willHaveQueryParams =
+ parsedPattern.queryParams.some((qp) => {
+ const value = params[qp.name];
+ return value !== undefined;
+ }) ||
+ Object.entries(params).some(([key, value]) => {
+ const isPathParam = parsedPattern.segments.some(
+ (s) => s.type === "param" && s.name === key,
+ );
+ const isQueryParam = parsedPattern.queryParams?.some(
+ (qp) => qp.name === key,
+ );
+ return value !== undefined && !isPathParam && !isQueryParam;
});
- transition.play();
- };
- // Main transition method
- const transitionTo = (newContentElement, {
- contentPhase,
- contentId
- } = {}) => {
- if (contentId) {
- targetSlot.setAttribute(CONTENT_ID_ATTRIBUTE, contentId);
- } else {
- targetSlot.removeAttribute(CONTENT_ID_ATTRIBUTE);
+
+ // Remove trailing slash when we have query params for prettier URLs
+ if (willHaveQueryParams && path.endsWith("/") && path !== "/") {
+ path = path.slice(0, -1);
+ }
+
+ // Always remove trailing slash from simple paths (unless root) for cleaner URLs
+ if (path.endsWith("/") && path !== "/" && !willHaveQueryParams) {
+ path = path.slice(0, -1);
+ }
+
+ // Build query parameters respecting hierarchical order
+ const queryParams = buildHierarchicalQueryParams(
+ parsedPattern,
+ params,
+ originalPattern,
+ patternObj,
+ );
+
+ const search = buildQueryString(queryParams);
+
+ // No longer handle trailing slash inheritance here
+
+ return path + (search ? `?${search}` : "");
+};
+
+/**
+ * Check if childPattern is a child route of parentPattern
+ * This determines parent-child relationships for signal clearing behavior.
+ *
+ * Route families vs parent-child relationships:
+ * - Different families: preserve signals (e.g., "/" and "/settings")
+ * - Parent-child: clear signals when navigating to parent (e.g., "/settings" and "/settings/:tab")
+ *
+ * E.g., "/admin/settings/:tab" is a child of "/admin/:section/"
+ * Also, "/admin/?tab=something" is a child of "/admin/"
+ */
+const isChildPattern = (childPattern, parentPattern) => {
+ if (!childPattern || !parentPattern) {
+ return false;
+ }
+
+ // Split path and query parts
+ const [childPath, childQuery] = childPattern.split("?");
+ const [parentPath, parentQuery] = parentPattern.split("?");
+
+ // Remove trailing slashes for path comparison
+ const cleanChild = childPath.replace(/\/$/, "");
+ const cleanParent = parentPath.replace(/\/$/, "");
+
+ // CASE 1: Same path, child has query params, parent doesn't
+ // E.g., "/admin/?tab=something" is child of "/admin/"
+ if (cleanChild === cleanParent && childQuery && !parentQuery) {
+ return true;
+ }
+
+ // CASE 2: Traditional path-based child relationship
+ const childSegments = cleanChild.split("/").filter((s) => s);
+ const parentSegments = cleanParent.split("/").filter((s) => s);
+
+ // Child must have at least as many segments as parent (or more for specificity)
+ if (childSegments.length < parentSegments.length) {
+ return false;
+ }
+
+ let hasMoreSpecificSegment = false;
+
+ // Check if all parent segments match child segments (allowing for parameters)
+ for (let i = 0; i < parentSegments.length; i++) {
+ const parentSeg = parentSegments[i];
+ const childSeg = childSegments[i];
+
+ if (parentSeg.startsWith(":")) {
+ // Parent has parameter - child can have any value in that position
+ // Child is more specific if it has a literal value for a parent parameter
+ if (!childSeg.startsWith(":")) {
+ hasMoreSpecificSegment = true;
+ }
+ continue;
}
- if (contentPhase) {
- targetSlot.setAttribute(CONTENT_PHASE_ATTRIBUTE, contentPhase);
- } else {
- targetSlot.removeAttribute(CONTENT_PHASE_ATTRIBUTE);
+
+ // Parent has literal - child must match exactly
+ if (parentSeg !== childSeg) {
+ return false;
}
- if (newContentElement) {
- targetSlot.innerHTML = "";
- targetSlot.appendChild(newContentElement);
- } else {
- targetSlot.innerHTML = "";
+ }
+
+ // Child must be more specific (more segments OR more specific segments)
+ return childSegments.length > parentSegments.length || hasMoreSpecificSegment;
+};
+
+/**
+ * Check if a parameter is redundant because the child pattern already has it as a literal segment
+ * E.g., parameter "section" is redundant for pattern "/admin/settings/:tab" because "settings" is literal
+ */
+const isParameterRedundantWithLiteralSegments = (
+ childPattern,
+ parentPattern,
+ paramName,
+) => {
+ // Find which segment position corresponds to this parameter in the parent
+ let paramSegmentIndex = -1;
+ for (let i = 0; i < parentPattern.segments.length; i++) {
+ const segment = parentPattern.segments[i];
+ if (segment.type === "param" && segment.name === paramName) {
+ paramSegmentIndex = i;
+ break;
}
- };
- // Reset to initial content
- const resetContent = () => {
- transitionController.cancel();
- moveConfigurationIntoSlot(targetSlotInitialConfiguration, targetSlot);
- moveConfigurationIntoSlot(outgoingSlotInitialConfiguration, outgoingSlot);
- moveConfigurationIntoSlot(UNSET, previousTargetSlot);
- moveConfigurationIntoSlot(UNSET, previousOutgoingSlot);
- };
- const targetSlotEffect = reasons => {
- if (root.hasAttribute("data-disabled")) {
- return;
+ }
+
+ // If parameter not found in parent segments, it's not redundant with path
+ if (paramSegmentIndex === -1) {
+ return false;
+ }
+
+ // Check if child has a literal segment at the same position
+ if (childPattern.segments.length > paramSegmentIndex) {
+ const childSegment = childPattern.segments[paramSegmentIndex];
+ if (childSegment.type === "literal") {
+ // Child has a literal segment where parent has parameter
+ // This means the child is more specific and shouldn't inherit this parameter
+ return true; // Redundant - child already specifies this position with a literal
}
- const fromConfiguration = targetSlotConfiguration;
- const toConfiguration = detectConfiguration(targetSlot);
- if (hasDebugLogs) {
- console.group(`targetSlotEffect()`);
- console.debug(`reasons:`);
- console.debug(`- ${reasons.join("\n- ")}`);
+ }
+
+ return false;
+};
+
+/**
+ * Register all patterns at once and build their relationships
+ */
+const setupRoutePatterns = (routePatterns) => {
+ const routePatternSet = new Set(); // Set of pattern objects
+ // Phase 1: Fill pattern set
+ for (const routePattern of routePatterns) {
+ routePatternSet.add(routePattern);
+ }
+ // Phase 2: Determine parent-child relationships based on pattern analysis
+ for (const routePattern of routePatternSet) {
+ for (const otherRoutePattern of routePatternSet) {
+ if (otherRoutePattern === routePattern) {
+ continue;
+ }
+ if (
+ !isChildPattern(
+ routePattern.cleanPattern,
+ otherRoutePattern.cleanPattern,
+ )
+ ) {
+ continue;
+ }
+ const currentSegmentCount = routePattern.parent
+ ? getPathSegmentCount(routePattern.parent.originalPattern)
+ : 0;
+ const otherSegmentCount = getPathSegmentCount(
+ otherRoutePattern.originalPattern,
+ );
+ if (!routePattern.parent || otherSegmentCount > currentSegmentCount) {
+ routePattern.parent = otherRoutePattern;
+ }
+ otherRoutePattern.children.push(routePattern);
}
- if (isSameConfiguration(fromConfiguration, toConfiguration)) {
- debugDetection(`already in desired state (${toConfiguration}) -> early return`);
- if (hasDebugLogs) {
- console.groupEnd();
+ }
+ // Phase 3: Inherit search parameter connections from ancestors
+ // Search params are global and should be inherited by descendants regardless of path segments
+ for (const routePattern of routePatternSet) {
+ let ancestorRoutePattern = routePattern.parent;
+ while (ancestorRoutePattern) {
+ // For each ancestor's query connection, check if it should be inherited
+ for (const [
+ paramName,
+ ancestorConnection,
+ ] of ancestorRoutePattern.queryConnectionMap) {
+ // Skip if descendant already has this parameter
+ if (routePattern.queryConnectionMap.has(paramName)) {
+ continue;
+ }
+
+ // Check if child route is truly more specific than parent, or just using default values
+ // If child has literal segments that match parent's parameter defaults, skip inheritance
+ let shouldInherit = true;
+
+ // Compare path segments to see if child is just parent with default values
+ const childSegments = routePattern.pattern.segments;
+ const parentSegments = ancestorRoutePattern.pattern.segments;
+
+ for (
+ let i = 0;
+ i < Math.min(childSegments.length, parentSegments.length);
+ i++
+ ) {
+ const childSeg = childSegments[i];
+ const parentSeg = parentSegments[i];
+
+ if (parentSeg.type === "param" && childSeg.type === "literal") {
+ // Check if this literal value matches the parent parameter's default
+ const parentConnection = ancestorRoutePattern.pathConnectionMap.get(
+ parentSeg.name,
+ );
+ if (
+ parentConnection &&
+ parentConnection.getDefaultValue() === childSeg.value
+ ) {
+ // Child uses literal that matches parent's parameter default
+ // This means they're essentially the same route, not parent-child
+ shouldInherit = false;
+ break;
+ }
+ }
+ }
+
+ if (shouldInherit) {
+ // Create inherited connection
+ const inheritedConnection = {
+ ...ancestorConnection,
+ inherited: true, // Mark as inherited for proper handling
+ };
+ routePattern.queryConnectionMap.set(paramName, inheritedConnection);
+ routePattern.connections.push(inheritedConnection);
+
+ if (DEBUG$3) {
+ console.debug(
+ `[${routePattern.originalPattern}] Inherited search param "${paramName}" from ancestor [${ancestorRoutePattern.originalPattern}]`,
+ );
+ }
+ } else if (DEBUG$3) {
+ console.debug(
+ `[${routePattern.originalPattern}] Skipped inheriting "${paramName}" - child uses default values, not truly more specific`,
+ );
+ }
}
- return;
- }
- const fromConfigType = fromConfiguration.type;
- const toConfigType = toConfiguration.type;
- transitionType = `${fromConfigType}_to_${toConfigType}`;
- debugDetection(`Prepare "${transitionType}" transition (${fromConfiguration} -> ${toConfiguration})`);
- // content_to_empty / content_phase_to_empty
- if (toConfiguration.isEmpty) {
- applyToEmptyTransition();
- return;
- }
- // content_phase_to_content_phase
- if (fromConfiguration.isContentPhase && toConfiguration.isContentPhase) {
- applyContentPhaseToContentPhaseTransition(toConfiguration);
- return;
+ ancestorRoutePattern = ancestorRoutePattern.parent;
}
- // content_phase_to_content
- if (fromConfiguration.isContentPhase && toConfiguration.isContent) {
- applyContentPhaseToContentPhaseTransition(toConfiguration);
- return;
+ }
+ // Phase 4: Collect all relevant signals for each pattern based on relationships
+ for (const routePattern of routePatternSet) {
+ const allRelevantSignals = new Set();
+
+ // Add own signals
+ for (const signal of routePattern.signalSet) {
+ allRelevantSignals.add(signal);
}
- // content_to_content_phase
- if (fromConfiguration.isContent && toConfiguration.isContentPhase) {
- applyContentPhaseToContentPhaseTransition(toConfiguration);
- return;
+
+ // Add signals from ancestors (they might be inherited)
+ let parentRoutePattern = routePattern.parent;
+ while (parentRoutePattern) {
+ for (const connection of parentRoutePattern.connections) {
+ allRelevantSignals.add(connection.signal);
+ }
+ // Move up the parent chain
+ parentRoutePattern = parentRoutePattern.parent;
}
- // content_to_content (default case)
- applyContentToContentTransition(toConfiguration);
- };
- const [teardown, addTeardown] = createPubSub();
- {
- const mutationObserver = new MutationObserver(mutations => {
- const reasonParts = [];
- for (const mutation of mutations) {
- if (mutation.type === "childList") {
- const added = mutation.addedNodes.length;
- const removed = mutation.removedNodes.length;
- if (added && removed) {
- reasonParts.push(`addedNodes(${added}) removedNodes(${removed})`);
- } else if (added) {
- reasonParts.push(`addedNodes(${added})`);
- } else {
- reasonParts.push(`removedNodes(${removed})`);
- }
- continue;
+
+ // Add signals from descendants (they might be used for optimization)
+ const addDescendantSignals = (patternObj) => {
+ for (const childPattern of patternObj.children) {
+ // Add child's own signals
+ for (const connection of childPattern.connections) {
+ allRelevantSignals.add(connection.signal);
}
- if (mutation.type === "attributes") {
- const {
- attributeName
- } = mutation;
- if (attributeName === CONTENT_ID_ATTRIBUTE || attributeName === CONTENT_PHASE_ATTRIBUTE) {
- const {
- oldValue
- } = mutation;
- if (oldValue === null) {
- const value = targetSlot.getAttribute(attributeName);
- reasonParts.push(value ? `added [${attributeName}=${value}]` : `added [${attributeName}]`);
- } else if (targetSlot.hasAttribute(attributeName)) {
- const value = targetSlot.getAttribute(attributeName);
- reasonParts.push(`[${attributeName}] ${oldValue} -> ${value}`);
- } else {
- reasonParts.push(oldValue ? `removed [${attributeName}=${oldValue}]` : `removed [${attributeName}]`);
+ // Recursively add grandchildren signals
+ addDescendantSignals(childPattern);
+ }
+ };
+ addDescendantSignals(routePattern);
+
+ // Update the pattern's signalSet with all relevant signals
+ routePattern.signalSet = allRelevantSignals;
+
+ if (DEBUG$3 && allRelevantSignals.size > 0) {
+ console.debug(
+ `[${routePattern.urlPatternRaw}] Collected ${allRelevantSignals.size} relevant signals`,
+ );
+ }
+ }
+ // Phase 5: Precompute descendant path signals for each pattern (used by canReachLiteralValue)
+ // Stored as a Map for O(1) lookup by position.
+ for (const routePattern of routePatternSet) {
+ const descendantPathSignalsByIndex = new Map();
+ const collectDescendantPathSignals = (patternObj) => {
+ for (const conn of patternObj.connections) {
+ if (conn.paramType === "path") {
+ const paramSegment = patternObj.pattern.segments.find(
+ (seg) => seg.type === "param" && seg.name === conn.paramName,
+ );
+ if (paramSegment) {
+ const { index } = paramSegment;
+ let conns = descendantPathSignalsByIndex.get(index);
+ if (!conns) {
+ conns = [];
+ descendantPathSignalsByIndex.set(index, conns);
}
+ conns.push(conn);
}
}
}
- if (reasonParts.length === 0) {
- return;
+ for (const child of patternObj.children) {
+ collectDescendantPathSignals(child);
}
- targetSlotEffect(reasonParts);
- });
- mutationObserver.observe(targetSlot, {
- childList: true,
- attributes: true,
- attributeFilter: [CONTENT_ID_ATTRIBUTE, CONTENT_PHASE_ATTRIBUTE],
- characterData: false
- });
- addTeardown(() => {
- mutationObserver.disconnect();
- });
+ };
+ collectDescendantPathSignals(routePattern);
+ routePattern.descendantPathSignals = descendantPathSignalsByIndex;
}
- {
- const slots = [targetSlot, outgoingSlot, previousTargetSlot, previousOutgoingSlot];
- for (const slot of slots) {
- addTeardown(monitorItemsOverflow(slot));
- }
+ // Phase 6: Calculate depths for all patterns
+ for (const routePattern of routePatternSet) {
+ calculatePatternDepth(routePattern);
}
- const setDuration = newDuration => {
- duration = newDuration;
- // Update CSS variable immediately
- root.style.setProperty("--x-transition-duration", `${duration}ms`);
- };
- const setAlignment = (newAlignX, newAlignY) => {
- alignX = newAlignX;
- alignY = newAlignY;
- updateAlignment();
- };
- return {
- updateContentId: value => {
- if (value) {
- targetSlot.setAttribute(CONTENT_ID_ATTRIBUTE, value);
- } else {
- targetSlot.removeAttribute(CONTENT_ID_ATTRIBUTE);
- }
- },
- transitionTo,
- resetContent,
- setDuration,
- setAlignment,
- updateAlignment,
- setPauseBreakpoints: value => {
- groupTransitionOptions.pauseBreakpoints = value;
- },
- cleanup: () => {
- teardown();
- }
- };
+ if (DEBUG$3) {
+ console.debug("Pattern registry updated");
+ }
+};
+// Store the most specific parent (closest parent in hierarchy)
+const getPathSegmentCount = (pattern) => {
+ // Only count path segments, not query parameters
+ const pathPart = pattern.split("?")[0];
+ return pathPart.split("/").filter(Boolean).length;
+};
+const calculatePatternDepth = (patternObj) => {
+ if (patternObj.depth !== 0) {
+ return patternObj.depth; // Already calculated
+ }
+
+ if (!patternObj.parent) {
+ patternObj.depth = 0;
+ return 0;
+ }
+
+ const parentDepth = calculatePatternDepth(patternObj.parent);
+ patternObj.depth = parentDepth + 1;
+ return patternObj.depth;
+};
+
+const resolveRouteUrl = (relativeUrl) => {
+ if (relativeUrl[0] === "/") {
+ // we remove the leading slash because we want to resolve against baseUrl which may
+ // not be the root url
+ relativeUrl = relativeUrl.slice(1);
+ }
+
+ // we don't use URL constructor on PURPOSE (in case the relativeUrl contains invalid url chars)
+ // and we want to support use cases where people WANT to produce invalid urls (for example rawUrlPart with spaces)
+ // because these urls will be handled by non standard clients (like a backend service allowing url like stuff)
+ if (baseUrl.endsWith("/")) {
+ return `${baseUrl}${relativeUrl}`;
+ }
+ return `${baseUrl}/${relativeUrl}`;
};
/**
- * UITransition
- *
- * A Preact component that enables smooth animated transitions between its children when the content changes.
- * It observes content keys and phases to create different types of transitions.
- *
- * Features:
- * - Content transitions: Between different content keys (e.g., user profiles, search results)
- * - Phase transitions: Between loading/content/error states for the same content key
- * - Automatic size animation to accommodate content changes
- * - Configurable transition types: "slide-left", "cross-fade"
- * - Independent duration control for content and phase transitions
- *
- * Usage:
- * - Wrap dynamic content in to animate between states
- * - Set a unique `data-content-id` on your rendered content to identify each content variant
- * - Use `data-content-phase` to mark loading/error states for phase transitions
- * - Configure transition types and durations for both content and phase changes
- *
- * Example:
- *
- *
- * {isLoading
- * ?
- *
- * When `data-content-id` changes, UITransition animates content transitions.
- * When `data-content-phase` changes for the same key, it animates phase transitions.
+ * Route management with pattern-first architecture
+ * Routes work with relative URLs, patterns handle base URL resolution
*/
-const UITransitionContentIdContext = createContext();
-const UITransition = ({
- children,
- contentId,
- type,
- duration,
- debugDetection,
- debugContent,
- debugSize,
- disabled,
- uiTransitionRef,
- alignX,
- alignY,
- ...props
-}) => {
- const contentIdRef = useRef(contentId);
- const updateContentId = () => {
- const uiTransition = uiTransitionRef.current;
- if (!uiTransition) {
- return;
- }
- const value = contentIdRef.current;
- uiTransition.updateContentId(value);
+
+const routePrivatePropertiesMap = new WeakMap();
+const getRoutePrivateProperties = (route) => {
+ return routePrivatePropertiesMap.get(route);
+};
+const ROUTE_NOT_MATCHING_PARAMS = {};
+// Flag to prevent signal-to-URL synchronization during URL-to-signal synchronization
+let isUpdatingRoutesFromUrl = false;
+const route = (pattern, { searchParams } = {}) => {
+ const routePattern = createRoutePattern(pattern, { searchParams });
+ const { cleanPattern } = routePattern;
+ const [publishStatus, subscribeStatus] = createPubSub();
+
+ // prepare route object
+ const route = {
+ urlPattern: cleanPattern,
+ pattern: cleanPattern,
+ isRoute: true,
+ setupCalled: false,
+ matching: false,
+ params: ROUTE_NOT_MATCHING_PARAMS,
+ buildUrl: null,
+ relativeUrl: null,
+ url: null,
+ matchingSignal: signal(false),
+ rawParamsSignal: signal(ROUTE_NOT_MATCHING_PARAMS),
+ visited: false,
+ visitedSignal: signal(false),
+ paramsSignal: null,
+ urlSignal: null,
+ replaceParams: undefined,
+ buildRelativeUrl: undefined,
+ relativeUrlSignal: null,
+ matchesParams: undefined,
+ navTo: undefined,
+ redirectTo: undefined,
+ subscribeStatus,
+ toString: () => {
+ return `route "${cleanPattern}"`;
+ },
};
- const uiTransitionContentIdContextValue = useMemo(() => {
- const set = new Set();
- const onSetChange = () => {
- const value = Array.from(set).join("|");
- contentIdRef.current = value;
- updateContentId();
+ Object.preventExtensions(route);
+
+ // route private props
+ const cleanupCallbackSet = new Set();
+ const setupCallbackSet = new Set();
+ const registerSetup = (callback) => {
+ setupCallbackSet.add(callback);
+ };
+ {
+ const routePrivateProperties = {
+ routePattern,
+ setup: null,
+ updateStatus: null,
+ cleanup: null,
};
- const update = (part, newPart) => {
- if (!set.has(part)) {
- if (set.size === 0) {
- console.warn(`UITransition: content id update "${part}" -> "${newPart}" ignored because content id set is empty`);
- return;
+ routePrivatePropertiesMap.set(route, routePrivateProperties);
+ routePrivateProperties.cleanup = () => {
+ for (const cleanupCallback of cleanupCallbackSet) {
+ cleanupCallback();
+ }
+ cleanupCallbackSet.clear();
+ };
+ routePrivateProperties.updateStatus = ({ matching, params, visited }) => {
+ let someChange = false;
+ route.matchingSignal.value = matching;
+
+ if (route.matching !== matching) {
+ route.matching = matching;
+ someChange = true;
+ }
+ route.visitedSignal.value = visited;
+ if (route.visited !== visited) {
+ route.visited = visited;
+ someChange = true;
+ }
+ // Store raw params (from URL) - paramsSignal will reactively compute merged params
+ route.rawParamsSignal.value = params;
+ // Get merged params for comparison (computed signal will handle the merging)
+ const mergedParams = route.paramsSignal.value;
+ if (route.params !== mergedParams) {
+ route.params = mergedParams;
+ someChange = true;
+ }
+ if (!someChange) {
+ return false;
+ }
+ publishStatus({
+ matching,
+ params: mergedParams,
+ visited,
+ });
+ return true;
+ };
+ // (for now data contains only { routeSet })
+ routePrivateProperties.setup = (data) => {
+ for (const setupCallback of setupCallbackSet) {
+ const returnValue = setupCallback(data);
+ if (typeof returnValue === "function") {
+ cleanupCallbackSet.add(returnValue);
}
- console.warn(`UITransition: content id update "${part}" -> "${newPart}" ignored because content id not found in set, only got [${Array.from(set).join(", ")}]`);
- return;
}
- set.delete(part);
- set.add(newPart);
- onSetChange();
+ setupCallbackSet.clear();
+ };
+ }
+
+ registerSetup(() => {
+ route.setupCalled = true;
+ });
+ // methods
+ registerSetup(({ routeSet, getUrl }) => {
+ route.buildRelativeUrl = (params) => {
+ // buildMostPreciseUrl now handles parameter resolution internally
+ return routePattern.buildMostPreciseUrl(params);
+ };
+ route.buildUrl = (params) => {
+ const routeRelativeUrl = route.buildRelativeUrl(params);
+ const routeUrl = resolveRouteUrl(routeRelativeUrl);
+ return routeUrl;
+ };
+ route.navTo = (params) => {
+ if (!integration) {
+ return Promise.resolve();
+ }
+ const routeUrl = route.buildUrl(params);
+ return integration.navTo(routeUrl);
+ };
+ route.redirectTo = (params, { callReason } = {}) => {
+ if (!integration) {
+ return Promise.resolve();
+ }
+ const routeUrl = route.buildUrl(params);
+ return integration.navTo(routeUrl, {
+ replace: true,
+ callReason,
+ });
+ };
+ route.replaceParams = (newParams, { callReason, isSignalChange } = {}) => {
+ const matching = route.matchingSignal.peek();
+ if (!matching) {
+ console.warn(
+ `Cannot replace params on route ${route} because it is not matching the current URL.`,
+ );
+ return null;
+ }
+
+ // Find all matching routes and update their actions, then delegate to most specific (deeper = more specific)
+ let mostSpecificRoute = route;
+ const routePrivateProperties = getRoutePrivateProperties(route);
+ let maxDepth = routePrivateProperties.routePattern.depth;
+ for (const routeCandidate of routeSet) {
+ if (routeCandidate === route) {
+ continue;
+ }
+ if (!routeCandidate.matching) {
+ continue;
+ }
+ const matchingRoute = routeCandidate;
+ const matchingRoutePrivateProperties =
+ getRoutePrivateProperties(matchingRoute);
+ const depth = matchingRoutePrivateProperties.routePattern.depth;
+ if (depth > maxDepth) {
+ maxDepth = depth;
+ mostSpecificRoute = matchingRoute;
+ }
+ }
+ const isMostSpecificRoute = mostSpecificRoute === route;
+
+ // If we found a more specific route, delegate to it; otherwise handle it ourselves
+ if (!isMostSpecificRoute) {
+ // For signal-originated calls, only skip delegation if the more specific route
+ // has its own signal connection for the same params — meaning its own effect will
+ // fire and handle the redirect. If it doesn't have the connection, the signal
+ // change would be silently dropped, so we must delegate anyway.
+ if (isSignalChange) {
+ const mostSpecificRoutePrivateProperties =
+ getRoutePrivateProperties(mostSpecificRoute);
+ const { pathConnectionMap, queryConnectionMap } =
+ mostSpecificRoutePrivateProperties.routePattern;
+ const willHandleItself = Object.keys(newParams).every(
+ (paramName) =>
+ pathConnectionMap.has(paramName) ||
+ queryConnectionMap.has(paramName),
+ );
+ if (willHandleItself) {
+ return null;
+ }
+ }
+ return mostSpecificRoute.redirectTo(newParams, {
+ callReason: `replaceParams delegation from ${route} to ${mostSpecificRoute} (original reason: ${callReason})`,
+ });
+ }
+
+ // This route is the most specific — compute the target URL.
+ // buildUrlPreservingPath handles the catch-all case where this trailing-slash
+ // route matched a path it cannot represent (e.g. "/" on "/404") without
+ // corrupting the current URL. Ancestor optimisation is trusted as-is.
+ if (!integration) {
+ return Promise.resolve();
+ }
+ const targetUrl = routePattern.buildUrlPreservingPath(
+ getUrl(),
+ newParams,
+ );
+ return integration.navTo(targetUrl, {
+ replace: true,
+ callReason,
+ });
+ };
+ route.matchesParams = (providedParams) => {
+ const currentParams = route.params;
+ const resolvedParams = routePattern.resolveParams({
+ ...currentParams,
+ ...providedParams,
+ });
+ const same = compareTwoJsValues(currentParams, resolvedParams);
+ return same;
+ };
+ });
+ // relativeUrl/url
+ registerSetup(() => {
+ route.relativeUrlSignal = computed(() => {
+ const rawParams = route.rawParamsSignal.value;
+ const relativeUrl = route.buildRelativeUrl(rawParams);
+ return relativeUrl;
+ });
+ route.urlSignal = computed(() => {
+ const routeUrl = route.buildUrl();
+ return routeUrl;
+ });
+ const cleanupRelativeUrlSignalEffect = effect(() => {
+ const routeRelativeUrl = route.relativeUrlSignal.value;
+ route.relativeUrl = routeRelativeUrl;
+ });
+ const cleanupUrlSignalEffect = effect(() => {
+ const routeUrl = route.urlSignal.value;
+ route.url = routeUrl;
+ });
+ return () => {
+ cleanupRelativeUrlSignalEffect();
+ cleanupUrlSignalEffect();
};
- const add = part => {
- if (!part) {
- return;
- }
- if (set.has(part)) {
- return;
+ });
+ // params
+ registerSetup(() => {
+ route.paramsSignal = computed(() => {
+ const rawParams = route.rawParamsSignal.value;
+ const resolvedParams = routePattern.resolveParams(rawParams);
+ return resolvedParams;
+ });
+
+ // Keep route.params synchronized with paramsSignal
+ // Doing this with the signal instead of in the updateStatus function ensures route.params includes parameters from child routes
+ const cleanupParamsSignalEffect = effect(() => {
+ const params = route.paramsSignal.value;
+ if (route.params !== params) {
+ route.params = params;
}
- set.add(part);
- onSetChange();
+ });
+
+ return () => {
+ cleanupParamsSignalEffect();
};
- const remove = part => {
- if (!part) {
- return;
- }
- if (!set.has(part)) {
- return;
+ });
+ // Signal -> URL sync: When signal changes, update URL to reflect meaningful state
+ // Only sync non-default values to keep URLs clean (static fallbacks stay invisible)
+ registerSetup(() => {
+ const cleanupSignalUrlEffectSet = new Set();
+ const { pathConnectionMap, queryConnectionMap } = routePattern;
+ // important: keep this connectionMap after setup so that connectionMap correctly inherits parent pattern signals
+ const connectionMap = new Map([
+ ...pathConnectionMap,
+ ...queryConnectionMap,
+ ]);
+ for (const [paramName, connection] of connectionMap) {
+ const { signal: paramSignal, debug } = connection;
+ if (debug) {
+ console.debug(
+ `[route] connecting url param "${paramName}" to signal`,
+ paramSignal,
+ );
}
- set.delete(part);
- onSetChange();
- };
- return {
- add,
- update,
- remove
- };
- }, []);
- const ref = useRef();
- const uiTransitionRefDefault = useRef();
- uiTransitionRef = uiTransitionRef || uiTransitionRefDefault;
- useLayoutEffect(() => {
- const uiTransition = createUITransitionController(ref.current, {
- alignX,
- alignY
- });
- uiTransitionRef.current = uiTransition;
+ // eslint-disable-next-line no-loop-func
+ const cleanupSignalUrlEffect = effect(() => {
+ const value = paramSignal.value;
+ // Use peek() to avoid subscribing to URL-derived signals.
+ // This effect should only re-run when the param signal changes,
+ // not when the URL changes (which would create a cycle: signal→URL→signal).
+ const rawParams = route.rawParamsSignal.peek();
+ const urlParamValue = rawParams[paramName];
+ const matching = route.matchingSignal.peek();
+
+ // Signal returned to default - clean up URL by removing the parameter
+ // Skip cleanup during URL-to-signal synchronization to prevent recursion
+ if (isUpdatingRoutesFromUrl) {
+ return;
+ }
+
+ if (!matching) {
+ // Route not matching, no URL sync needed
+ return;
+ }
+ if (urlParamValue === undefined) {
+ // No URL parameter exists - check if signal has meaningful value to add
+ if (connection.isDefaultValue(value)) {
+ // Signal using default value, keep URL clean (no parameter needed)
+ return;
+ }
+ if (debug) {
+ console.debug(
+ `[route] Signal->URL: ${paramName} adding custom value ${value} to URL (default: ${connection.getDefaultValue()})`,
+ );
+ }
+ route.replaceParams(
+ { [paramName]: value },
+ {
+ callReason: `${paramName} signal change on ${route}`,
+ isSignalChange: true,
+ },
+ );
+ return;
+ }
+
+ // URL parameter exists - check if we need to update or clean it up
+ if (connection.isDefaultValue(value)) {
+ if (debug) {
+ console.debug(
+ `[route] Signal->URL: ${paramName} cleaning URL (removing default value ${value})`,
+ );
+ }
+ route.replaceParams(
+ { [paramName]: undefined },
+ {
+ callReason: `${paramName} signal reset to default on ${route}`,
+ isSignalChange: true,
+ },
+ );
+ return;
+ }
+
+ if (compareTwoJsValues(value, urlParamValue)) {
+ // Values already match, no sync needed
+ return;
+ }
+ if (debug) {
+ console.debug(
+ `[route] Signal->URL: ${paramName} updating URL ${urlParamValue} -> ${value}`,
+ );
+ }
+ route.replaceParams(
+ { [paramName]: value },
+ {
+ callReason: `${paramName} signal change on ${route}`,
+ isSignalChange: true,
+ },
+ );
+ });
+ cleanupSignalUrlEffectSet.add(cleanupSignalUrlEffect);
+ }
return () => {
- uiTransition.cleanup();
+ for (const cleanupSignalUrlEffect of cleanupSignalUrlEffectSet) {
+ cleanupSignalUrlEffect();
+ }
};
- }, [disabled, alignX, alignY]);
- return jsxs("div", {
- ref: ref,
- ...props,
- className: "ui_transition",
- "data-disabled": disabled ? "" : undefined,
- "data-transition-type": type,
- "data-transition-duration": duration,
- "data-debug-detection": debugDetection ? "" : undefined,
- "data-debug-size": debugSize ? "" : undefined,
- "data-debug-content": debugContent ? "" : undefined,
- children: [jsxs("div", {
- className: "ui_transition_active_group",
- children: [jsx("div", {
- className: "ui_transition_target_slot",
- "data-content-id": contentIdRef.current ? contentIdRef.current : undefined,
- children: jsx(UITransitionContentIdContext.Provider, {
- value: uiTransitionContentIdContextValue,
- children: children
- })
- }), jsx("div", {
- className: "ui_transition_outgoing_slot",
- inert: true
- })]
- }), jsxs("div", {
- className: "ui_transition_previous_group",
- inert: true,
- children: [jsx("div", {
- className: "ui_transition_previous_target_slot"
- }), jsx("div", {
- className: "ui_transition_previous_outgoing_slot"
- })]
- })]
});
+
+ return route;
};
-/**
- * The goal of this hook is to allow a component to set a "content key"
- * Meaning all content within the component is identified by that key
- *
- * When the key changes, UITransition will be able to detect that and consider the content
- * as changed even if the component is still the same
- *
- * This is used by to set the content key to the route path
- * When the route becomes inactive it will call useUITransitionContentId(undefined)
- * And if a sibling route becones active it will call useUITransitionContentId with its own path
- *
- */
-const useUITransitionContentId = value => {
- const contentId = useContext(UITransitionContentIdContext);
- const valueRef = useRef();
- if (contentId !== undefined && valueRef.current !== value) {
- const previousValue = valueRef.current;
- valueRef.current = value;
- if (previousValue === undefined) {
- contentId.add(value);
- } else {
- contentId.update(previousValue, value);
- }
+const [publishRouteMutations, observeRouteMutations] = createPubSub();
+
+let setupRoutesCalled = false;
+const setupRoutes = (routes) => {
+ if (setupRoutesCalled) {
+ throw new Error(
+ `There is an active set of routes already.
+Some code called setupRoutes before and did not properly cleanup routes with clearRoutes().
+This prevents cross-test pollution and ensures clean state.`,
+ );
}
- useLayoutEffect(() => {
- if (contentId === undefined) {
- return null;
+ setupRoutesCalled = true;
+
+ const routeSet = new Set();
+ let currentUrl = null;
+ const getUrl = () => currentUrl;
+ // PHASE 1: Setup patterns with unified objects (includes all relationships and signal connections)
+ const routePatterns = [];
+ for (const route of routes) {
+ const { routePattern } = getRoutePrivateProperties(route);
+ routePatterns.push(routePattern);
+ routeSet.add(route);
+ }
+ setupRoutePatterns(routePatterns);
+
+ // Setup routes now that patterns are correctly initialized
+ for (const route of routeSet) {
+ const { setup } = getRoutePrivateProperties(route);
+ setup({ routeSet, getUrl });
+ }
+
+ // Store previous route states to detect changes
+ const routePreviousStateMap = new WeakMap();
+ const updateRoutes = (
+ url,
+ {
+ isVisited = () => false,
+ // state
+ } = {},
+ ) => {
+ currentUrl = url;
+ const returnValue = {};
+ const routeMatchInfoSet = new Set();
+ for (const route of routeSet) {
+ const routePrivateProperties = getRoutePrivateProperties(route);
+ const { routePattern } = routePrivateProperties;
+
+ const previousState = routePreviousStateMap.get(route) || {
+ matching: false,
+ params: ROUTE_NOT_MATCHING_PARAMS,
+ actionParams: ROUTE_NOT_MATCHING_PARAMS,
+ };
+ const oldMatching = previousState.matching;
+ const oldParams = previousState.params;
+ const oldActionParams = previousState.actionParams;
+
+ let extractedParams = routePattern.applyOn(url);
+ let newMatching = Boolean(extractedParams);
+ let newParams;
+ if (extractedParams) {
+ if (compareTwoJsValues(oldParams, extractedParams)) {
+ // No change in parameters, keep the old params
+ newParams = oldParams;
+ } else {
+ newParams = extractedParams;
+ }
+ } else {
+ newParams = ROUTE_NOT_MATCHING_PARAMS;
+ }
+
+ const routeMatchInfo = {
+ route,
+ routePrivateProperties,
+ oldMatching,
+ newMatching,
+ oldParams,
+ newParams,
+ oldActionParams,
+ };
+ routeMatchInfoSet.add(routeMatchInfo);
+ // Store current state for next comparison
+ routePreviousStateMap.set(route, {
+ matching: newMatching,
+ params: newParams,
+ actionParams: oldActionParams, // updated to newActionParams in update_route_actions
+ });
+ }
+
+ {
+ // URL -> Signal synchronization (moved from individual route effects to eliminate circular dependency)
+ // Prevent signal-to-URL synchronization during URL-to-signal synchronization
+ isUpdatingRoutesFromUrl = true;
+ // Apply all signal updates in a batch
+ const matchingRouteSet = new Set();
+ const routeUpdateSet = new Set();
+ batch(() => {
+ for (const {
+ route,
+ routePrivateProperties,
+ newMatching,
+ newParams,
+ } of routeMatchInfoSet) {
+ const { updateStatus } = routePrivateProperties;
+ const visited = isVisited(route.url);
+ const updated = updateStatus({
+ matching: newMatching,
+ params: newParams,
+ visited,
+ });
+ if (updated) {
+ routeUpdateSet.add(route);
+ }
+ if (newMatching) {
+ matchingRouteSet.add(route);
+ }
+ }
+
+ for (const {
+ route,
+ routePrivateProperties,
+ newMatching,
+ } of routeMatchInfoSet) {
+ const { routePattern } = routePrivateProperties;
+ const { pathConnectionMap, queryConnectionMap } = routePattern;
+ const connectionMap = new Map([
+ ...pathConnectionMap,
+ ...queryConnectionMap,
+ ]);
+
+ for (const [paramName, connection] of connectionMap) {
+ const { signal: paramSignal, debug } = connection;
+ const rawParams = route.rawParamsSignal.value;
+ const urlParamValue = rawParams[paramName];
+
+ if (!newMatching) {
+ // 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 otherRawParams = otherRoute.rawParamsSignal.value;
+ const otherRoutePrivateProperties =
+ getRoutePrivateProperties(otherRoute);
+
+ // Check if this matching route extracts the parameter
+ if (paramName in otherRawParams) {
+ parameterExtractedByMatchingRoute = true;
+ }
+
+ // Check if this matching route is in the same family using parent-child relationships
+ const thisPatternObj = routePattern;
+ const otherPatternObj =
+ otherRoutePrivateProperties.routePattern;
+
+ // 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) {
+ inSameFamily = true;
+ break;
+ }
+ currentParent = currentParent.parent;
+ }
+
+ // 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;
+ }
+ }
+
+ // 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;
+ }
+
+ currentParent = otherPatternObj.parent;
+ while (currentParent) {
+ if (thisAncestors.has(currentParent)) {
+ inSameFamily = true;
+ break;
+ }
+ currentParent = currentParent.parent;
+ }
+ }
+
+ if (inSameFamily) {
+ matchingRouteInSameFamily = true;
+ }
+ }
+
+ // 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)
+ // 4. AND parameter is a path segment (not a search param)
+ // Search params represent user preferences/choices and must survive
+ // navigation away — only path segments are explicitly removed from
+ // the URL when the route stops matching.
+ if (
+ matchingRouteInSameFamily &&
+ !parameterExtractedByMatchingRoute &&
+ pathConnectionMap.has(paramName)
+ ) {
+ const defaultValue = connection.getDefaultValue();
+ 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`,
+ );
+ }
+ paramSignal.value = undefined;
+ } else if (debug) {
+ // Parameter has a default value - preserve current signal value
+ console.debug(
+ `[route] Parameter ${paramName} has default value ${defaultValue}: preserving signal value: ${paramSignal.value}`,
+ );
+ }
+ } else if (debug) {
+ if (!matchingRouteInSameFamily) {
+ console.debug(
+ `[route] Different route family: preserving ${paramName} signal value: ${paramSignal.value}`,
+ );
+ } else if (queryConnectionMap.has(paramName)) {
+ console.debug(
+ `[route] Search param ${paramName}: preserving signal value (user choice): ${paramSignal.value}`,
+ );
+ } else {
+ console.debug(
+ `[route] Parameter ${paramName} extracted by matching route: preserving signal value: ${paramSignal.value}`,
+ );
+ }
+ }
+ continue;
+ }
+
+ // URL -> Signal sync: When route matches, ensure signal matches URL state
+ // URL is the source of truth for explicit parameters
+ const value = paramSignal.peek();
+ if (urlParamValue === undefined) {
+ // No URL parameter - reset signal to its current default value
+ // (handles both static fallback and dynamic default cases)
+ const defaultValue = connection.getDefaultValue();
+ if (connection.isDefaultValue(value)) {
+ // Signal already has correct default value, no sync needed
+ continue;
+ }
+ if (debug) {
+ console.debug(
+ `[route] URL->Signal: ${paramName} not in URL, reset signal to default (${defaultValue})`,
+ );
+ }
+ paramSignal.value = defaultValue;
+ continue;
+ }
+ if (compareTwoJsValues(urlParamValue, value)) {
+ // Values already match, no sync needed
+ continue;
+ }
+ if (debug) {
+ console.debug(
+ `[route] URL->Signal: ${paramName}=${urlParamValue} in url, sync signal with url`,
+ );
+ }
+ paramSignal.value = urlParamValue;
+ continue;
+ }
+ }
+ });
+ if (routeUpdateSet.size > 0) {
+ publishRouteMutations(routeUpdateSet);
+ }
+ // Reset flag after URL -> Signal synchronization is complete
+ isUpdatingRoutesFromUrl = false;
+ Object.assign(returnValue, { matchingRouteSet });
}
- return () => {
- contentId.remove(valueRef.current);
- };
- }, []);
+
+ return returnValue;
+ };
+
+ // notify all routes are now ready (signals are initialized and patterns are set up) so integrations can safely read route state
+ // and call updateRoutes
+ onAllRouteReady(updateRoutes);
+
+ // for unit test purposes code can call updateRoutes and clearRoutes
+ const clearRoutes = () => {
+ for (const route of routeSet) {
+ const routePrivateProperties = getRoutePrivateProperties(route);
+ routePrivateProperties.cleanup();
+ routePrivatePropertiesMap.delete(route);
+ }
+ routeSet.clear();
+ setupRoutesCalled = false;
+ };
+ return {
+ updateRoutes,
+ clearRoutes,
+ };
};
-/**
- * Custom route pattern matching system
- * Replaces URLPattern with a simpler, more predictable approach
- */
+const useRouteStatus = (route) => {
+ const { urlSignal, matchingSignal, paramsSignal, visitedSignal } = route;
+ const url = urlSignal.value;
+ const matching = matchingSignal.value;
+ const params = paramsSignal.value;
+ const visited = visitedSignal.value;
+ return {
+ url,
+ matching,
+ params,
+ visited,
+ };
+};
-const DEBUG$2 =
- typeof process === "object" ? process.env.DEBUG === "true" : false;
+let integration;
+const setRouteIntegration = (integrationInterface) => {
+ integration = integrationInterface;
+};
+let onAllRouteReady = () => {};
+const setOnAllRouteReady = (callback) => {
+ onAllRouteReady = callback;
+};
-// Base URL management
-let baseFileUrl;
-let baseUrl;
-const setBaseUrl = (value) => {
- baseFileUrl = new URL(
- value,
- typeof window === "undefined" ? "http://localhost/" : window.location,
- ).href;
- baseUrl = new URL(".", baseFileUrl).href;
+const ButtonRouteResolver = props => {
+ const Next = useNextResolver();
+ if (props.route) {
+ return jsx(ButtonWithRoute, {
+ ...props
+ });
+ }
+ return jsx(Next, {
+ ...props
+ });
+};
+const ButtonWithRoute = props => {
+ const Next = useNextResolver();
+ const {
+ route,
+ routeParams,
+ children,
+ pseudoState,
+ ...rest
+ } = props;
+ const url = route.buildUrl(routeParams);
+ const {
+ matching
+ } = useRouteStatus(route);
+ const paramsAreMatching = route.matchesParams(routeParams);
+ const linkMatching = matching && paramsAreMatching;
+
+ // Merged into whatever the caller already holds: a button can be forced into
+ // a state for a demo and still learn its own current-ness from its route.
+ return jsx(Next, {
+ href: url,
+ pseudoState: {
+ ...pseudoState,
+ ":-navi-href-current": linkMatching
+ },
+ ...rest,
+ children: children || route.buildRelativeUrl(routeParams)
+ });
};
-setBaseUrl(
- typeof window === "undefined"
- ? "/"
- : window.location.origin,
-);
/**
- * Creates a custom route pattern matcher
+ * Merges a component's base className with className received from props.
+ *
+ * ```jsx
+ * const MyButton = ({ className, children }) => (
+ *
+ * {children}
+ *
+ * );
+ *
+ * // Usage:
+ * precomputed during setupPatterns.
- const connsAtPosition =
- patternObject.descendantPathSignals.get(literalPosition);
- if (!connsAtPosition) {
- return false;
+ return { flexShrink: 1, minWidth: 0 };
+ },
+ shrinkY: (value) => {
+ if (!value || value === "0") {
+ return { flexShrink: 0 };
}
- return connsAtPosition.some((conn) => {
- const signalValue = conn.signal.value;
- return signalValue === literalValue && conn.isCustomValue(signalValue);
- });
- };
- const checkChildRouteCompatibility = (childPatternObj, params) => {
- const childParams = {};
- let isCompatible = true;
-
- // CRITICAL: Check if parent route can reach all child route's literal segments
- // A route can only optimize to a descendant if there's a viable path through parameters
- // to reach all the descendant's literal segments (e.g., "/" cannot reach "/admin"
- // without a parameter that produces "admin")
- const childLiterals = childPatternObj.pattern.segments.filter(
- (segment) => segment.type === "literal",
- );
- // Check each child literal segment
- for (let i = 0; i < childLiterals.length; i++) {
- const childLiteral = childLiterals[i];
- const childPosition = childLiteral.index;
- const literalValue = childLiteral.value;
-
- // Check what the parent has at this position
- const parentSegmentAtPosition = parsedPattern.segments.find(
- (segment) => segment.index === childPosition,
- );
-
- if (parentSegmentAtPosition) {
- if (parentSegmentAtPosition.type === "literal") {
- // Parent has a literal at this position
- if (parentSegmentAtPosition.value === literalValue) {
- // Same literal - no problem
- continue;
- }
- // Different literal - incompatible
- if (DEBUG$2) {
- console.debug(
- `[${pattern}] INCOMPATIBLE with ${childPatternObj.originalPattern}: conflicting literal "${parentSegmentAtPosition.value}" vs "${literalValue}" at position ${childPosition}`,
- );
- }
- return { isCompatible: false, childParams: {} };
- }
- if (parentSegmentAtPosition.type === "param") {
- // Parent has a parameter at this position - child literal can satisfy this parameter
- // BUT we need to check if the parent's parameter value matches the child's literal
-
- // Find the parent's parameter value from signals or params
- const paramName = parentSegmentAtPosition.name;
- let parentParamValue = params[paramName];
-
- // If not in params, check signals
- if (parentParamValue === undefined) {
- const parentConnection =
- pathConnectionMap.get(paramName) ||
- queryConnectionMap.get(paramName);
- if (parentConnection) {
- parentParamValue = parentConnection.signal.value;
- }
- }
+ return { flexShrink: 1, minHeight: 0 };
+ },
- // If parent has a specific value for this parameter, it must match the child literal
- if (
- parentParamValue !== undefined &&
- parentParamValue !== literalValue
- ) {
- return { isCompatible: false, childParams: {} };
- }
+ scaleX: (value) => {
+ return { transform: `scaleX(${stringifyStyle(value, "scaleX")})` };
+ },
+ scaleY: (value) => {
+ return { transform: `scaleY(${stringifyStyle(value, "scaleY")})` };
+ },
+ scale: (value) => {
+ if (Array.isArray(value)) {
+ const [x, y] = value;
+ return { transform: `scale(${x}, ${y})` };
+ }
+ return { transform: `scale(${value})` };
+ },
+ scaleZ: (value) => {
+ return { transform: `scaleZ(${value})` };
+ },
+};
+const POSITION_PROPS = {
+ // For row, selfAlignX uses auto margins for positioning
+ // NOTE: Auto margins only work effectively for positioning individual items.
+ // When multiple adjacent items have the same auto margin alignment (e.g., selfAlignX="end"),
+ // only the first item will be positioned as expected because subsequent items
+ // will be positioned relative to the previous item's margins, not the container edge.
+ selfAlignX: (value, { parentBoxFlow }) => {
+ const inGridFlow =
+ parentBoxFlow === "grid" || parentBoxFlow === "inline-grid";
+ if (inGridFlow) {
+ return { justifySelf: value };
+ }
- continue;
- }
+ const inVerticalFlexFlow =
+ parentBoxFlow === "flex-y" || parentBoxFlow === "inline-flex-y";
+ if (value === "start") {
+ if (inVerticalFlexFlow) {
+ return { alignSelf: "start" };
}
- // Parent doesn't have a segment at this position - child extends beyond parent
- // Check if any available parameter can produce this literal value
- else if (!canReachLiteralValue(literalValue, params, childPosition)) {
- if (DEBUG$2) {
- console.debug(
- `[${pattern}] INCOMPATIBLE with ${childPatternObj.originalPattern}: cannot reach literal segment "${literalValue}" at position ${childPosition} - no viable parameter path`,
- );
- }
- return { isCompatible: false, childParams: {} };
+ return { marginRight: "auto" };
+ }
+ if (value === "end") {
+ if (inVerticalFlexFlow) {
+ return { alignSelf: "end" };
}
+ return { marginLeft: "auto" };
}
-
- // Check both parent signals AND user-provided params for child route matching
- const paramsToCheck = [
- ...connections,
- ...Object.entries(params).map(([key, value]) => ({
- paramName: key,
- userValue: value,
- isUserProvided: true,
- })),
- ];
-
- for (const item of paramsToCheck) {
- const result = processParameterForChildRoute(
- item,
- childPatternObj.pattern,
- );
-
- if (DEBUG$2) {
- console.debug(
- `[${pattern}] Processing param '${item.paramName}' (userProvided: ${item.isUserProvided}, value: ${item.isUserProvided ? item.userValue : item.signal?.value}) for child ${childPatternObj.originalPattern}: compatible=${result.isCompatible}, shouldInclude=${result.shouldInclude}`,
- );
+ if (value === "center") {
+ if (inVerticalFlexFlow) {
+ return { alignSelf: "center" };
}
+ return { marginLeft: "auto", marginRight: "auto" };
+ }
+ if (inVerticalFlexFlow && value !== "stretch") {
+ return { alignSelf: value };
+ }
+ return undefined;
+ },
+ selfAlignY: (value, { parentBoxFlow }) => {
+ const inGridFlow =
+ parentBoxFlow === "grid" || parentBoxFlow === "inline-grid";
+ if (inGridFlow) {
+ return { alignSelf: value };
+ }
- if (!result.isCompatible) {
- isCompatible = false;
- if (DEBUG$2) {
- console.debug(
- `[${pattern}] Child ${childPatternObj.originalPattern} INCOMPATIBLE due to param '${item.paramName}'`,
- );
- }
- break;
+ const inHorizontalFlexFlow =
+ parentBoxFlow === "flex-x" || parentBoxFlow === "inline-flex-x";
+ if (value === "start") {
+ if (inHorizontalFlexFlow) {
+ return { alignSelf: "start" };
}
-
- if (result.shouldInclude) {
- childParams[result.paramName] = result.paramValue;
+ return { marginBottom: "auto" };
+ }
+ if (value === "center") {
+ if (inHorizontalFlexFlow) {
+ return { alignSelf: "center" };
}
+ return { marginTop: "auto", marginBottom: "auto" };
}
-
- if (DEBUG$2) {
- console.debug(
- `[${pattern}] Final compatibility result for ${childPatternObj.originalPattern}: ${isCompatible}`,
- );
+ if (value === "end") {
+ if (inHorizontalFlexFlow) {
+ return { alignSelf: "end" };
+ }
+ return { marginTop: "auto" };
}
+ return undefined;
+ },
+ position: PASS_THROUGH,
+ absolute: applyToCssPropWhenTruthy("position", "absolute", "static"),
+ relative: applyToCssPropWhenTruthy("position", "relative", "static"),
+ fixed: applyToCssPropWhenTruthy("position", "fixed", "static"),
+ sticky: applyToCssPropWhenTruthy("position", "sticky", "static"),
+ zIndex: PASS_THROUGH,
+ order: PASS_THROUGH,
+ left: (value) => {
+ return { left: value === true ? 0 : value };
+ },
+ // Allow to write Click me
+ * ```
+ *
+ * Layered — a visual wrapper surrounds a native input that is the real host:
+ * ```html
+ * ← wrapper: root of the control's DOM subtree
+ *
+ * ```
+ *
+ * Attribute roles:
+ * - `navi-control` boolean, on the wrapper/root; marks the control boundary
+ * - `navi-control-host` boolean, on the host; set automatically by `useInteractiveProps`
+ *
+ * See control_proxy.js for the `navi-control-proxy-for` pattern.
+ */
- // Check if parent parameter is at default value
- const parentConnection =
- pathConnectionMap.get(paramName) || queryConnectionMap.get(paramName);
- const parentDefault = parentConnection
- ? parentConnection.getDefaultValue()
- : undefined;
- if (parentValue === parentDefault) {
- continue; // Don't inherit default values
- }
+/**
+ * Returns the host element inside `el` — the element that holds the control's
+ * value, UI state, and constraints (i.e. the element onto which
+ * `useInteractiveProps` spreads `controlProps` and its event handlers).
+ *
+ * Returns `null` when `el` is itself the host (no separate wrapper).
+ */
+const findControlHost = (el) => {
+ if (el.hasAttribute("navi-control-host")) {
+ return el;
+ }
+ return el.querySelector("[navi-control-host]");
+};
+const isControlRoot = (el) => {
+ return el.hasAttribute("navi-control");
+};
+const isControlHost = (el) => {
+ return el.hasAttribute("navi-control-host");
+};
- // Inherit this parameter as it's not handled by child and not at default
- baseParams[paramName] = parentValue;
+/**
+ * Returns the nearest ancestor of `el` (exclusive of `el`'s own control) that
+ * has a `[data-action]` attribute.
+ *
+ * The search walks up `parentElement` manually (rather than using `.closest()`)
+ * so it can stop at hard boundaries.
+ *
+ * **`[navi-control="picker"]` boundary**: a picker is a hard stop. Elements inside a picker
+ * (including inside its popover content) can reach the picker itself, but nothing above it.
+ * This prevents an input inside a picker from accidentally submitting a parent form.
+ *
+ * ```html
+ *
+ * ```
+ */
+const findClosestControlWithAction = (el) => {
+ let current = el;
+ while (current) {
+ if (current.hasAttribute("data-action")) {
+ return current;
}
-
- // Apply user params with filtering logic
- for (const [paramName, userValue] of Object.entries(params)) {
- const childConnection =
- childPatternObj.pathConnectionMap.get(paramName) ||
- childPatternObj.queryConnectionMap.get(paramName);
-
- if (childConnection) {
- // Only include if it's a custom value (not default)
- if (childConnection.isCustomValue(userValue)) {
- baseParams[paramName] = userValue;
- } else {
- // User provided the default value - complete omission
- delete baseParams[paramName];
- }
- } else {
- // Check if param corresponds to a literal segment in child pattern
- const isConsumedByChildPath = childPatternObj.pattern.segments.some(
- (segment) =>
- segment.type === "literal" && segment.value === userValue,
- );
-
- if (!isConsumedByChildPath) {
- // Not consumed by child path, keep it as query param
- baseParams[paramName] = userValue;
- }
- }
+ // Stop at a picker boundary — nothing above the picker is reachable from within.
+ if (current.getAttribute("navi-control") === "picker") {
+ return undefined;
}
+ current = current.parentElement;
+ }
+ return undefined;
+};
- // Build child URL using buildUrl (not buildMostPreciseUrl) to prevent recursion
- const childUrl = buildUrlFromPattern(
- childPatternObj.pattern,
- baseParams,
- childPatternObj.originalPattern,
- childPatternObj,
- );
-
- if (childUrl && !childUrl.includes(":")) {
- // Check for parent optimization before returning
- const optimizedUrl = checkChildParentOptimization(
- childPatternObj,
- childUrl,
- baseParams,
- );
- return optimizedUrl || childUrl;
- }
+/**
+ * Returns the closest ancestor control element of `el` — i.e. the nearest
+ * `[navi-control]` element that is not the control `el` belongs to.
+ *
+ * `navi-control` is only on wrapper elements, never on hosts. So
+ * `el.closest("[navi-control]")` from a host returns that host's own wrapper,
+ * and one more `.parentNode.closest("[navi-control]")` reaches a true ancestor:
+ *
+ * ```html
+ * ← outer control (returned)
+ * ← inner wrapper (skipped via parentNode)
+ *
+ *
+ * ```
+ */
+const getParentControl = (el) => {
+ const ownControlRoot = el.closest("[navi-control]");
+ const parentControlRoot = ownControlRoot.parentNode.closest("[navi-control]");
+ return parentControlRoot;
+};
- return null;
- };
+/**
+ * Returns the root element of the control that `el` belongs to, or `null` if
+ * `el` is not part of a control.
+ *
+ * Use this when you have an element that may be a host (inner input) and need
+ * the visual boundary of its control — e.g. to anchor a callout, track
+ * mousedown interactions, or measure the control's bounding box.
+ */
+const findControlRoot = (el) => {
+ if (el.hasAttribute("navi-control")) {
+ return el;
+ }
+ if (el.hasAttribute("navi-control-host")) {
+ return el.closest("[navi-control]");
+ }
+ return null;
+};
- /**
- * Helper: Check if parent route optimization applies to child route
- */
- const checkChildParentOptimization = (
- childPatternObj,
- childUrl,
- baseParams,
- ) => {
- const childParent = childPatternObj.parent;
+/**
+ * DOM utilities for the proxy control pattern.
+ *
+ * Some components need a native `
+ *
+ * ```
+ *
+ * When the proxy is interacted with, navi events are forwarded to the real
+ * control so validation, state management, and form submission all work
+ * through the real input.
+ *
+ * Note: an alternative design would be to require users to always instantiate
+ * the input explicitly — e.g. ` that reacts to mousedown + click, or a third-party
+ // library that attaches its own listeners, would break because an ancestor
+ // grabbed the pointer out from under them.
+ // To avoid forcing every such element to declare an opt-out attribute
+ // (e.g. navi-own-pointer-capture) we simply listen on document instead,
+ // which is safe and does not interfere with anyone else's event flow.
+ const onPointerDown = (e) => {
+ if (e.button !== 0) {
+ // only left pointer (mouse left click, touch, pen)
+ return;
}
-
- // Only inherit custom values (not defaults) that we don't already have
- const signalValue = connection.signal.value;
- if (
- signalValue !== undefined &&
- connection.isCustomValue(signalValue)
- ) {
- // Check if this parameter would be redundant with target ancestor's literal segments
- const isRedundant = isParameterRedundantWithLiteralSegments(
- targetAncestor.pattern,
- currentParent.pattern,
- paramName);
-
- if (!isRedundant) {
- ancestorParams[paramName] = signalValue;
+ pressedElements.add(el);
+ const onRelease = () => {
+ pressedElements.delete(el);
+ document.removeEventListener("pointercancel", onRelease, true);
+ document.removeEventListener("pointerup", onRelease, true);
+ document.removeEventListener("contextmenu", onContextMenu, true);
+ callback();
+ };
+ const onContextMenu = (e) => {
+ // On touch devices, a long-press triggers the context menu.
+ // If the context menu is not prevented, it means it will open and the
+ // pointer events (pointerup, lostpointercapture) won't fire normally,
+ // leaving the element stuck in pressed state. We clear it manually.
+ // e.button === -1 means the event was synthesized from a long-press (not a real mouse click).
+ if (e.button === -1 && !e.defaultPrevented) {
+ pressedElements.delete(el);
+ document.removeEventListener("pointercancel", onRelease, true);
+ document.removeEventListener("pointerup", onRelease, true);
+ document.removeEventListener("contextmenu", onContextMenu, true);
+ callback();
}
- }
- }
+ };
+ document.addEventListener("pointercancel", onRelease, true);
+ document.addEventListener("pointerup", onRelease, true);
+ document.addEventListener("contextmenu", onContextMenu, true);
+ callback();
+ };
+ el.addEventListener("pointerdown", onPointerDown);
+ return () => {
+ el.removeEventListener("pointerdown", onPointerDown);
+ pressedElements.delete(el);
+ };
+ },
+ test: (el) => pressedElements.has(el),
+ });
+}
- // Move up the parent chain
- currentParent = currentParent.parent;
- }
+{
+ definePseudoClass(":-navi-drag-grabbed", {
+ attribute: "navi-drag-grabbed",
+ setup: (el, callback) => {
+ const onGrab = () => {
+ callback();
+ const onRelease = () => {
+ el.removeEventListener("navi_drag_release", onRelease);
+ callback();
+ };
+ el.addEventListener("navi_drag_release", onRelease);
+ };
+ el.addEventListener("navi_drag_grab", onGrab);
+ return () => {
+ el.removeEventListener("navi_drag_grab", onGrab);
+ };
+ },
+ test: (el) => el.hasAttribute("data-drag-grabbed"),
+ });
+ definePseudoClass(":-navi-dragging", {
+ attribute: "navi-dragging",
+ setup: (el, callback) => {
+ const onStart = () => {
+ callback();
+ const onRelease = () => {
+ el.removeEventListener("navi_drag_release", onRelease);
+ callback();
+ };
+ el.addEventListener("navi_drag_release", onRelease);
+ };
+ el.addEventListener("navi_drag_start", onStart);
+ return () => {
+ el.removeEventListener("navi_drag_start", onStart);
+ };
+ },
+ test: (el) => el.hasAttribute("data-dragging"),
+ });
+}
- return buildUrlFromPattern(
- targetAncestor.pattern,
- ancestorParams,
- targetAncestor.originalPattern,
- targetAncestor,
+const EMPTY_STATE = {};
+const elementToImpactWeakMap = new WeakMap();
+const initPseudoStyles = (
+ element,
+ {
+ pseudoClasses,
+ pseudoState, // ":disabled", ":read-only", ":-navi-loading", etc...
+ effect,
+ elementToImpact = element,
+ elementListeningPseudoState,
+ },
+) => {
+ elementToImpactWeakMap.set(element, elementToImpact);
+ if (elementListeningPseudoState === element) {
+ console.warn(
+ `elementListeningPseudoState should not be the same as element to avoid infinite loop`,
);
- };
+ elementListeningPseudoState = null;
+ }
- /**
- * Helper: Try to use a descendant route (simple compatibility check)
- */
- const tryUseDescendant = (
- descendantPatternObj,
- params,
- parentResolvedParams,
- ) => {
- // Check basic compatibility
- const compatibility = checkChildRouteCompatibility(
- descendantPatternObj,
- params,
- );
- if (!compatibility.isCompatible) {
- return null;
- }
+ const proxyTarget = findControlProxyTarget(element);
- // Check if we should use this descendant
- const shouldUse = shouldUseChildRoute(
- descendantPatternObj,
- params,
- compatibility,
- parentResolvedParams,
- );
- if (!shouldUse) {
- return null;
+ const onStateChange = (value, oldValue) => {
+ effect?.(value, oldValue);
+ if (elementListeningPseudoState) {
+ dispatchPseudoStateCustomEvent(
+ elementListeningPseudoState,
+ value,
+ oldValue,
+ );
+ }
+ // When this element's state changes, notify any proxy element that mirrors it
+ // so it can re-check and visually reflect the new state.
+ const proxy = findControlProxy(element);
+ if (proxy) {
+ requestPseudoStateCheck(proxy, {});
}
-
- // Build descendant URL using buildUrl (not buildMostPreciseUrl) to prevent recursion
- return buildChildRouteUrl(
- descendantPatternObj,
- params,
- parentResolvedParams,
- );
};
- /**
- * Helper: Inherit query parameters from parent patterns
- */
- const inheritParentParameters = (finalParams) => {
- let currentParent = patternObject.parent;
-
- // Traverse up the parent chain to inherit parameters
- while (currentParent) {
- // Check parent's signal connections for non-default values to inherit
- // Only inherit query (search) parameters, not path parameters
- // Path parameters are structural and correspond to specific path segments
- for (const parentConnection of currentParent.connections) {
- if (parentConnection.paramType === "path") {
- continue;
- }
- const { paramName } = parentConnection;
- if (paramName in finalParams) {
- continue; // Already have this parameter
- }
+ if (!pseudoClasses || pseudoClasses.length === 0) {
+ onStateChange(EMPTY_STATE);
+ return () => {};
+ }
- // Only inherit if we don't have this param and parent has custom value (not default)
- const parentSignalValue = parentConnection.signal.value;
- if (
- parentSignalValue !== undefined &&
- parentConnection.isCustomValue(parentSignalValue)
- ) {
- // Don't inherit if parameter corresponds to a literal in our path
- const shouldInherit = !isParameterRedundantWithLiteralSegments(
- parsedPattern,
- currentParent.pattern,
- paramName);
+ const [teardown, addTeardown] = createPubSub();
- if (shouldInherit) {
- finalParams[paramName] = parentSignalValue;
- }
+ let state;
+ const checkPseudoClasses = () => {
+ let someChange = false;
+ const currentState = {};
+ for (const pseudoClass of pseudoClasses) {
+ const pseudoClassDefinition = PSEUDO_CLASSES[pseudoClass];
+ if (!pseudoClassDefinition) {
+ console.warn(`Unknown pseudo class: ${pseudoClass}`);
+ continue;
+ }
+ let currentValue;
+ if (
+ pseudoState &&
+ Object.hasOwn(pseudoState, pseudoClass) &&
+ pseudoState[pseudoClass] !== undefined
+ ) {
+ currentValue = pseudoState[pseudoClass];
+ } else {
+ const { test } = pseudoClassDefinition;
+ if (test) {
+ currentValue = test(element, pseudoState);
}
}
- // Move to the next parent up the chain
- currentParent = currentParent.parent;
- }
- };
-
- /**
- * Helper: Build URL for current route with filtered pattern
- */
- const buildCurrentRouteUrl = (finalParams) => {
- if (!parsedPattern.segments) {
- return "/";
- }
-
- // Filter out parameter segments that don't have values
- const filteredPattern = {
- ...parsedPattern,
- segments: parsedPattern.segments.filter((segment) => {
- if (segment.type === "param") {
- return segment.name in finalParams;
+ // If this element is a proxy for another (navi-control-proxy-for="targetId"),
+ // inherit the target's active pseudo-state when the element itself isn't in that state.
+ // We check the target's elementToImpact (not the target itself) because the
+ // data-* attribute may be set on a different element (e.g. pseudoStateSelector).
+ if (!currentValue && proxyTarget) {
+ const { attribute } = pseudoClassDefinition;
+ if (attribute) {
+ const targetElementToImpact =
+ elementToImpactWeakMap.get(proxyTarget) || proxyTarget;
+ if (targetElementToImpact.hasAttribute(attribute)) {
+ currentValue = true;
+ }
+ }
+ }
+ currentState[pseudoClass] = currentValue;
+ const oldValue = state ? state[pseudoClass] : undefined;
+ if (oldValue !== currentValue || !state) {
+ someChange = true;
+ const { attribute, add, remove } = pseudoClassDefinition;
+ if (currentValue) {
+ if (attribute) {
+ elementToImpact.setAttribute(attribute, "");
+ }
+ add?.(element);
+ } else {
+ if (attribute) {
+ elementToImpact.removeAttribute(attribute);
+ }
+ remove?.(element);
}
- return true; // Keep literal segments
- }),
- };
-
- // Remove trailing slash if we filtered out segments
- if (
- filteredPattern.segments.length < parsedPattern.segments.length &&
- parsedPattern.trailingSlash
- ) {
- filteredPattern.trailingSlash = false;
- }
-
- return buildUrlFromPattern(
- filteredPattern,
- finalParams,
- pattern,
- patternObject,
- );
- };
-
- // Returns the pathname that this route's own literal prefix resolves to.
- // For route "/": "/"
- // For route "/profile/": "/profile/"
- // For route "/map/isochrone/compare": "/map/isochrone/compare"
- // For route "/map/isochrone/:tab=/": "/map/isochrone/" (literal prefix before first param)
- const getOwnBasePathname = () => {
- const segments = parsedPattern.segments;
- if (segments.length === 0) {
- return new URL(resolveRouteUrl("/")).pathname;
- }
- const literalSegments = [];
- for (const seg of segments) {
- if (seg.type !== "literal") {
- break;
}
- literalSegments.push(seg.value);
- }
- if (literalSegments.length === 0) {
- return new URL(resolveRouteUrl("/")).pathname;
- }
- const prefix = `/${literalSegments.join("/")}/`;
- return new URL(resolveRouteUrl(prefix)).pathname;
- };
-
- // Like buildMostPreciseUrl but takes the actual current browser URL into account.
- // When buildMostPreciseUrl returns the route's own base URL (catch-all matching an
- // unrepresentable path like "/404") the current pathname is preserved and only
- // search params are updated. When buildMostPreciseUrl performs an ancestor
- // optimisation (e.g. "/map/isochrone/compare" → "/map/isochrone") it is trusted
- // as-is because the built pathname will differ from the route's own base pathname.
- const buildUrlPreservingPath = (currentUrl, params = {}) => {
- const relativeBuiltUrl = buildMostPreciseUrl(params);
- if (!currentUrl) {
- return resolveRouteUrl(relativeBuiltUrl);
- }
- const absoluteBuiltUrl = resolveRouteUrl(relativeBuiltUrl);
- const builtPathname = new URL(absoluteBuiltUrl).pathname;
- const currentPathname = new URL(currentUrl).pathname;
- if (builtPathname === currentPathname) {
- return absoluteBuiltUrl;
}
- const ownBasePathname = getOwnBasePathname();
- if (builtPathname === ownBasePathname) {
- // Catch-all: the route resolved to its own base pathname but the current URL
- // sits on a different path that this trailing-slash route caught. Keep the
- // current pathname and only update the search string.
- const correctedUrl = new URL(currentUrl);
- correctedUrl.search = new URL(absoluteBuiltUrl).search;
- return correctedUrl.href;
+ if (!someChange) {
+ return;
}
- // Ancestor optimisation or descendant selection — trust buildMostPreciseUrl.
- return absoluteBuiltUrl;
+ const oldState = state;
+ state = currentState;
+ onStateChange(state, oldState);
};
- // Pattern object with unified data and methods
- const patternObject = {
- // Pattern data properties (formerly patternData)
- urlPatternRaw: pattern,
- cleanPattern,
- connections,
- pathConnectionMap, // Separate map for path parameters
- queryConnectionMap, // Separate map for query parameters
- parsedPattern,
- signalSet,
- children: [],
- parent: null,
- depth: 0, // Will be calculated after relationships are built
- descendantPathSignals: new Map(), // Precomputed during setupPatterns (Map)
+ element.addEventListener(NAVI_PSEUDO_STATE_CUSTOM_EVENT, (event) => {
+ const oldState = event.detail.oldPseudoState;
+ state = event.detail.pseudoState;
+ onStateChange(state, oldState);
+ });
+ element.addEventListener("navi_pseudo_state_request_check", () => {
+ checkPseudoClasses();
+ });
- // Pattern methods (formerly patternObj methods)
- originalPattern: pattern,
- pattern: parsedPattern,
- applyOn,
- buildMostPreciseUrl,
- buildUrlPreservingPath,
- resolveParams,
- };
+ for (const pseudoClass of pseudoClasses) {
+ const pseudoClassDefinition = PSEUDO_CLASSES[pseudoClass];
+ if (!pseudoClassDefinition) {
+ console.warn(`Unknown pseudo class: ${pseudoClass}`);
+ continue;
+ }
+ const { setup } = pseudoClassDefinition;
+ if (setup) {
+ const cleanup = setup(element, () => {
+ checkPseudoClasses();
+ });
+ addTeardown(cleanup);
+ }
+ }
+ checkPseudoClasses();
- return patternObject;
+ return teardown;
};
-// Raw URL part functionality for bypassing encoding
-const rawUrlPartSymbol = Symbol("raw_url_part");
-const rawUrlPart = (value) => {
- return {
- [rawUrlPartSymbol]: true,
- value,
- };
+const applyStyle = (
+ element,
+ style,
+ pseudoState,
+ pseudoNamedStyles,
+ preventInitialTransition,
+) => {
+ if (!element) {
+ return;
+ }
+ const styleToApply = getStyleToApply(style, pseudoState, pseudoNamedStyles);
+ updateStyle(element, styleToApply, preventInitialTransition);
};
-/**
- * Encode parameter values for URL usage, with special handling for raw URL parts.
- * When a parameter is wrapped with rawUrlPart(), it bypasses encoding and is
- * inserted as-is into the URL.
- */
-const encodeParamValue = (value, isWildcard = false) => {
- if (value && value[rawUrlPartSymbol]) {
- return value.value;
+const PSEUDO_STATE_DEFAULT = {};
+const PSEUDO_NAMED_STYLES_DEFAULT = {};
+const getStyleToApply = (styles, pseudoState, pseudoNamedStyles) => {
+ if (
+ !pseudoState ||
+ pseudoState === PSEUDO_STATE_DEFAULT ||
+ !pseudoNamedStyles ||
+ pseudoNamedStyles === PSEUDO_NAMED_STYLES_DEFAULT
+ ) {
+ return styles;
}
- if (isWildcard) {
- // For wildcards, only encode characters that are invalid in URL paths,
- // but preserve slashes as they are path separators
- return value
- ? value.replace(/[^a-zA-Z0-9\-._~!$&'()*+,;=:@/]/g, (char) => {
- return encodeURIComponent(char);
- })
- : value;
- }
+ const isMatching = (pseudoKey) => {
+ if (pseudoKey.startsWith("::")) {
+ const nextColonIndex = pseudoKey.indexOf(":", 2);
+ if (nextColonIndex === -1) {
+ return true;
+ }
+ // Handle pseudo-elements with states like "::-navi-loader:checked:disabled"
+ const pseudoStatesString = pseudoKey.slice(nextColonIndex);
+ return isMatching(pseudoStatesString);
+ }
+ const nextColonIndex = pseudoKey.indexOf(":", 1);
+ if (nextColonIndex === -1) {
+ return pseudoState[pseudoKey];
+ }
+ // Handle compound pseudo-states like ":checked:disabled"
+ return pseudoKey
+ .slice(1)
+ .split(":")
+ .every((state) => pseudoState[state]);
+ };
- // For named parameters and search params, encode everything including slashes
- return encodeURIComponent(value);
+ const styleToAddSet = new Set();
+ for (const pseudoKey of Object.keys(pseudoNamedStyles)) {
+ if (isMatching(pseudoKey)) {
+ const stylesToApply = pseudoNamedStyles[pseudoKey];
+ styleToAddSet.add(stylesToApply);
+ }
+ }
+ if (styleToAddSet.size === 0) {
+ return styles;
+ }
+ let style = styles || {};
+ for (const styleToAdd of styleToAddSet) {
+ style = mergeTwoStyles(style, styleToAdd, "css");
+ }
+ return style;
};
-// Function to detect signals in route patterns and connect them
-const detectSignals = (routePattern) => {
- const signalConnections = [];
- let updatedPattern = routePattern;
-
- // Look for path signals: :paramName={navi_state_signal:id}
- const signalParamRegex = /(:)(\w+)(=)?(\{navi_state_signal:[^}]+\})/g;
- let match;
-
- while ((match = signalParamRegex.exec(routePattern)) !== null) {
- const [fullMatch, prefix, paramName, equalSign, signalString] = match;
-
- // Emit warning if equal sign is missing
- if (!equalSign) {
- console.warn(
- `[detectSignals] Missing '=' sign in route pattern: "${prefix}${paramName}${signalString}". ` +
- `Consider using "${prefix}${paramName}=${signalString}" for better clarity.`,
- );
+const styleKeySetWeakMap = new WeakMap();
+const elementTransitionWeakMap = new WeakMap();
+const elementRenderedWeakSet = new WeakSet();
+const NO_STYLE_KEY_SET = new Set();
+const updateStyle = (element, style, preventInitialTransition) => {
+ const styleKeySet = style ? new Set(Object.keys(style)) : NO_STYLE_KEY_SET;
+ const oldStyleKeySet = styleKeySetWeakMap.get(element) || NO_STYLE_KEY_SET;
+ // TRANSITION ANTI-FLICKER STRATEGY:
+ // Problem: When setting both transition and styled properties simultaneously
+ // (e.g., el.style.transition = "border-radius 0.3s ease"; el.style.borderRadius = "20px"),
+ // the browser will immediately perform a transition even if no transition existed before.
+ //
+ // Solution: Temporarily disable transitions during initial style application by setting
+ // transition to "none", then restore the intended transition after the frame completes.
+ // We handle multiple updateStyle calls in the same frame gracefully - only one
+ // requestAnimationFrame is scheduled per element, and the final transition value wins.
+ let styleKeySetToApply = styleKeySet;
+ if (!elementRenderedWeakSet.has(element)) {
+ const hasTransition = styleKeySet.has("transition");
+ if (hasTransition || preventInitialTransition) {
+ if (elementTransitionWeakMap.has(element)) {
+ elementTransitionWeakMap.set(element, style?.transition);
+ } else {
+ element.style.transition = "none";
+ elementTransitionWeakMap.set(element, style?.transition);
+ }
+ // Don't apply the transition property now - we've set it to "none" temporarily
+ styleKeySetToApply = new Set(styleKeySet);
+ styleKeySetToApply.delete("transition");
}
+ requestAnimationFrame(() => {
+ if (elementTransitionWeakMap.has(element)) {
+ const transitionToRestore = elementTransitionWeakMap.get(element);
+ if (transitionToRestore === undefined) {
+ element.style.transition = "";
+ } else {
+ element.style.transition = transitionToRestore;
+ }
+ elementTransitionWeakMap.delete(element);
+ }
+ elementRenderedWeakSet.add(element);
+ });
+ }
- // Extract the signal ID from the format: {navi_state_signal:id}
- const signalIdMatch = signalString.match(/\{navi_state_signal:([^}]+)\}/);
- if (!signalIdMatch) {
- console.warn(
- `[detectSignals] Failed to extract signal ID from: ${signalString}`,
- );
+ // Apply all styles normally (excluding transition during anti-flicker)
+ const keysToDelete = new Set(oldStyleKeySet);
+ for (const key of styleKeySetToApply) {
+ const value = style[key];
+ if (value === undefined || value === null) {
+ // Treat undefined/null as "remove" — leave key in keysToDelete
continue;
}
-
- const signalId = signalIdMatch[1];
- const signalData = globalSignalRegistry.get(signalId);
-
- if (signalData) {
- const { signal, options } = signalData;
- updatedPattern = updatedPattern.replace(fullMatch, `:${paramName}`);
- signalConnections.push({
- paramName,
- signal,
- paramType: "path",
- ...options,
- });
+ keysToDelete.delete(key);
+ if (key.startsWith("--")) {
+ element.style.setProperty(key, value);
} else {
- console.warn(
- `[detectSignals] Signal not found in registry for ID: "${signalId}"`,
- );
- console.warn(
- `[detectSignals] Available signal IDs in registry:`,
- Array.from(globalSignalRegistry.keys()),
- );
- console.warn(`[detectSignals] Full pattern: "${routePattern}"`);
+ element.style[key] = value;
}
}
- return [updatedPattern, signalConnections];
-};
+ // Remove obsolete styles
+ for (const key of keysToDelete) {
+ if (key.startsWith("--")) {
+ element.style.removeProperty(key);
+ } else {
+ element.style[key] = "";
+ }
+ }
-/**
- * Helper: Check if parameter matches any literal in child pattern
- */
-const paramMatchesChildLiteral = (paramValue, childParsedPattern) => {
- return childParsedPattern.segments.some(
- (segment) => segment.type === "literal" && segment.value === paramValue,
- );
+ styleKeySetWeakMap.set(element, styleKeySet);
};
/**
- * Helper: Check if a parent parameter can semantically reach a child route
- * This replaces the fragile position-based matching with semantic verification
+ * Keeps a DOM element in sync with `syncElement(el)` whenever syncElement changes.
+ * - If element is already mounted: runs syncElement immediately during render.
+ * - If not yet mounted: runs syncElement in the ref callback when element arrives.
+ * - Calls cleanup (if returned by syncElement) before each re-run and on unmount.
+ *
+ * Wrap `syncElement` in `useCallback(fn, deps)` at the call site to control
+ * when re-sync happens.
+ *
+ * @param {function} syncElement - Called with the DOM element when its reference changes
+ * @param {function|object|null} externalRef - Optional ref to forward to
*/
-const canParameterReachChildRoute = (
- paramName,
- paramValue,
- parentPattern,
- childPattern,
-) => {
- // Find the parent parameter segment
- const parentParamSegment = parentPattern.segments.find(
- (segment) => segment.type === "param" && segment.name === paramName,
- );
-
- if (!parentParamSegment) {
- return true; // Not a path parameter, no conflict
+const useComposeElementRef = (syncElement, externalRef) => {
+ const cleanupRef = useRef(null);
+ const elRef = useRef(null);
+ const prevSyncElementRef = useRef(undefined);
+ const refCallbackRef = useRef(null);
+ const externalRefRef = useRef(externalRef);
+ // Detect external ref identity change between renders. The refCallback is
+ // stable across renders, so when the parent passes a new ref object (or
+ // switches from null to a ref), Preact does NOT re-fire the callback while
+ // the DOM element is unchanged. We must manually clear the old ref and
+ // populate the new one with the current element to avoid leaving the new
+ // ref's `.current` stuck at `null`.
+ const prevExternalRefRef = useRef(externalRef);
+ if (prevExternalRefRef.current !== externalRef) {
+ const previous = prevExternalRefRef.current;
+ if (previous && typeof previous !== "function") {
+ previous.current = null;
+ }
+ if (externalRef && elRef.current) {
+ if (typeof externalRef === "function") {
+ externalRef(elRef.current);
+ } else {
+ externalRef.current = elRef.current;
+ }
+ }
+ prevExternalRefRef.current = externalRef;
}
+ externalRefRef.current = externalRef;
- // Get parameter's logical path position (not array index)
- const paramPathPosition = parentParamSegment.index;
-
- // Find corresponding child segment at the same logical path position
- const childSegmentAtSamePosition = childPattern.segments.find(
- (segment) => segment.index === paramPathPosition,
- );
+ const runSync = (el) => {
+ if (cleanupRef.current) {
+ cleanupRef.current();
+ cleanupRef.current = null;
+ }
+ prevSyncElementRef.current = syncElement;
+ const cleanup = syncElement(el);
+ if (typeof cleanup === "function") {
+ cleanupRef.current = cleanup;
+ }
+ };
- if (!childSegmentAtSamePosition) {
- return true; // Child doesn't extend to this position, no conflict
+ // If element already mounted, re-sync when syncElement reference changed.
+ if (elRef.current && syncElement !== prevSyncElementRef.current) {
+ runSync(elRef.current);
}
- if (childSegmentAtSamePosition.type === "literal") {
- // Child has a literal at this position - parent parameter must match exactly
- return childSegmentAtSamePosition.value === paramValue;
+ if (!refCallbackRef.current) {
+ const refCallback = (el) => {
+ elRef.current = el;
+ // Keep .current in sync immediately so useEffect callbacks that read
+ // ref.current (e.g. usePartiallyHidden) see the element, not null.
+ refCallback.current = el;
+ const currentExternalRef = externalRefRef.current;
+ if (currentExternalRef) {
+ if (typeof currentExternalRef === "function") {
+ currentExternalRef(el);
+ } else {
+ currentExternalRef.current = el;
+ }
+ }
+ if (el) {
+ runSync(el);
+ } else {
+ if (cleanupRef.current) {
+ cleanupRef.current();
+ cleanupRef.current = null;
+ }
+ prevSyncElementRef.current = undefined;
+ }
+ };
+ refCallbackRef.current = refCallback;
}
- // Child has parameter at same position - compatible
- return true;
+ const refCallback = refCallbackRef.current;
+ refCallback.current = elRef.current;
+ return refCallback;
};
/**
- * Parse a route pattern string into structured segments
+ * Tracks whether an element is fully visible in its scroll container and sets
+ * the `navi-partially-hidden` attribute when any part of it is clipped.
+ *
+ * This is used to suppress `view-transition-name` on elements that are partially
+ * outside the viewport or a scrollable container. Without this, a partially clipped
+ * element would still participate in view transitions, producing ghost animations or
+ * incorrect cross-fade effects.
+ *
+ * CSS usage:
+ * ```css
+ * [navi-partially-hidden] {
+ * view-transition-name: none !important;
+ * }
+ * ```
+ *
+ * `Box` enables this hook automatically when a `viewTransitionName` prop is provided.
+ *
+ * @param {import("preact").RefObject} ref - Ref to the element to observe.
+ * @param {boolean} enabled - Only observe when true (typically when view-transition-name is set).
*/
-const parsePattern = (pattern, { pathConnectionMap, queryConnectionMap }) => {
- // Build queryParams from queryConnectionMap
- const queryParams = [];
- for (const [paramName, connection] of queryConnectionMap) {
- queryParams.push({
- type: "query_param",
- name: paramName,
- hasDefaultValue: connection.getDefaultValue() !== undefined,
- });
- }
+const usePartiallyHidden = (ref, enabled) => {
+ useEffect(() => {
+ const el = ref.current;
+ if (!el || !enabled) {
+ return undefined;
+ }
+ return setupPartiallyHidden(el);
+ }, [enabled]);
+};
- // Handle root route
- if (pattern === "/") {
- return {
- original: pattern,
- segments: [],
- trailingSlash: true,
- wildcard: false,
- queryParams,
- };
- }
+const setupPartiallyHidden = (el) => {
+ const observer = new IntersectionObserver(
+ ([entry]) => {
+ if (entry.intersectionRatio >= 0.99) {
+ el.removeAttribute("navi-partially-hidden");
+ } else {
+ el.setAttribute("navi-partially-hidden", "");
+ }
+ },
+ { threshold: 0.99 },
+ );
+ observer.observe(el);
+ return () => {
+ observer.disconnect();
+ };
+};
+
+installImportMetaCssBuild(import.meta);/**
+ * Box - A Swiss Army Knife for Layout
+ *
+ * A regular div by default, enhanced with styling props for spacing, sizing,
+ * and layout. The main value is a friendlier API over raw CSS Flexbox.
+ *
+ * ## Display & Layout
+ *
+ * - `flex` — horizontal flex container (items side by side)
+ * - `flex="y"` — vertical flex container (items stacked). The prop name makes
+ * the axis explicit, avoiding the classic CSS trap where `flex-direction: column`
+ * actually stacks items vertically despite "column" feeling horizontal.
+ * - `grid` — grid container
+ * - `inline` — switches to inline display (works with flex and grid too)
+ *
+ * ## Alignment
+ *
+ * Instead of CSS's justify-content/align-items which swap meaning based on flex-direction:
+ * - `alignX` — horizontal alignment, always
+ * - `alignY` — vertical alignment, always
+ *
+ * ## Spacing & Sizing
+ *
+ * Props for margin, padding, gap, width, height, expand, shrink, and more.
+ *
+ * ## Pseudo-class Styles
+ *
+ * The `style` prop supports pseudo-class keys alongside regular CSS properties.
+ * This lets you express hover, focus, and custom interaction states in one object,
+ * without writing CSS or adding class names:
+ *
+ * ```jsx
+ * ,
+ * preventInitialTransition?: boolean,
+ * separator?: import("ignore:preact").ComponentChildren | ((index: number) => import("ignore:preact").ComponentChildren),
+ * children?: import("ignore:preact").ComponentChildren,
+ * [key: string]: any,
+ * }>}
*/
-const matchUrl = (
- parsedPattern,
- url,
- { baseUrl, baseFileUrl, queryConnectionMap, patternObj = null },
-) => {
- // Parse the URL
- const urlObj = new URL(url, baseUrl);
- let pathname = urlObj.pathname;
- const originalPathname = pathname; // Store original pathname before baseUrl processing
+const Box = props => {
+ const {
+ ref,
+ as: asProp = "div",
+ baseClassName,
+ className,
+ baseStyle,
+ // style management
+ style,
+ styleCSSVars = STYLE_CSS_VARS_DEFAULT,
+ basePseudoState,
+ pseudoState,
+ // for demo purposes it's possible to control pseudo state from props
+ pseudoClasses = PSEUDO_CLASSES_DEFAULT,
+ pseudoElements = PSEUDO_ELEMENTS_DEFAULT,
+ // visualSelector convey the following:
+ // The box itself is visually "invisible", one of its descendant is responsible for visual representation
+ // - Some styles will be used on the box itself (for instance margins)
+ // - Some styles will be used on the visual element (for instance paddings, backgroundColor)
+ // -> introduced for / rather than a div: the role is exactly what those tags
+ // mean, and a screen reader gets it for free. The body stays a div —
+ // means "the main content of the document", which a popup's body is not.
+ if (header && as === "div") {
+ as = "header";
+ }
+ if (footer && as === "div") {
+ as = "footer";
+ }
+ const TagName = as;
+ if (scrolls) {
+ rest["data-scrollable"] = "";
+ if (rest.overflow === "auto" || rest.overflow === "scroll") {
+ // Handed over to CSS rather than kept as an inline style: a body inside
+ // makes the body the only thing that scrolls, and an inline overflow
+ // would win over that rule — see [data-scrollable] in this file's CSS.
+ rest["data-scrollable-overflow"] = rest.overflow;
+ rest.overflow = undefined;
}
}
+ if (header) {
+ rest["data-header"] = "";
+ }
+ if (footer) {
+ rest["data-footer"] = "";
+ }
+ if (body) {
+ rest["data-body"] = "";
+ }
+ const defaultDisplay = getDefaultDisplay(TagName);
+ // Read the parent flow early so we can use it when display="inherit" is requested.
+ const parentBoxFlow = useContext(BoxFlowContext);
+ let {
+ inline,
+ block,
+ flex,
+ grid,
+ row,
+ column
+ } = rest;
+ // To obtain flex direction we have the following deprecated props:
+ // - [deprecated] -> or
+ // - [deprecated] ->
+ // - [deprecated] ->
+ // - [deprecated] ->
- // Handle root route - only matches empty path or just "/"
- // OR when URL exactly matches baseUrl (treating baseUrl as root)
- // OR any sub-path when the route has a trailing slash (prefix matching)
- if (parsedPattern.segments.length === 0) {
- if (pathname === "/" || pathname === "") {
- return extractSearchParams(urlObj, queryConnectionMap);
+ if (flex === true) {
+ flex = row ? "y" : "x";
+ }
+ if (flex === undefined && grid === undefined) {
+ if (column) {
+ flex = "x";
+ } else if (row) {
+ flex = "y";
}
-
- // Special case: if URL exactly matches baseUrl or baseFileUrl (the HTML root file), treat as root route
- if (baseUrl) {
- const baseUrlObj = new URL(baseUrl);
- if (originalPathname === baseUrlObj.pathname) {
- return extractSearchParams(urlObj, queryConnectionMap);
+ }
+ if (defaultDisplay === "inline") {
+ if (inline === undefined && !block) {
+ inline = true;
+ }
+ } else if (defaultDisplay === "block") {
+ if (block === undefined && !flex && !grid) {
+ block = true;
+ }
+ } else if (defaultDisplay === "inline-block") {
+ if (inline === undefined && !block) {
+ inline = true;
+ }
+ if (block === undefined && !flex && !grid) {
+ block = true;
+ }
+ }
+ if (inline && (rest.width !== undefined || rest.height !== undefined) && flex === undefined) {
+ flex = "x";
+ }
+ let boxFlow;
+ if (inline) {
+ if (flex === "x") {
+ boxFlow = "inline-flex-x";
+ } else if (flex === "y") {
+ boxFlow = "inline-flex-y";
+ } else if (grid) {
+ boxFlow = "inline-grid";
+ } else if (block) {
+ boxFlow = "inline-block";
+ } else {
+ boxFlow = "inline";
+ }
+ } else if (flex === "x") {
+ boxFlow = "flex-x";
+ } else if (flex === "y") {
+ boxFlow = "flex-y";
+ } else if (grid) {
+ boxFlow = "grid";
+ } else if (block) {
+ boxFlow = "block";
+ } else {
+ boxFlow = defaultDisplay;
+ }
+ // When display="inherit" is passed, adopt the parent's flow instead of computing one.
+ // This lets a child Box mirror its parent's flex/grid/block layout without repeating
+ // the same layout props, and is used e.g. by Button's inner content element.
+ if (rest.display === "inherit") {
+ boxFlow = parentBoxFlow;
+ }
+ const boxFlowIsDefault = boxFlow === defaultDisplay;
+ const remainingPropKeySet = new Set(Object.keys(rest));
+ const innerClassName = withPropsClassName(baseClassName, className);
+ const selfForwardedProps = {};
+ const childForwardedProps = {};
+ let finalRef;
+ {
+ const styleDeps = [
+ // Layout and alignment props
+ parentBoxFlow, boxFlow,
+ // Style context dependencies
+ styleCSSVars, pseudoClasses, pseudoElements,
+ // Selectors
+ visualSelector, pseudoStateSelector, preventInitialTransition];
+ let innerPseudoState;
+ if (basePseudoState && pseudoState) {
+ innerPseudoState = {};
+ const baseStateKeys = Object.keys(basePseudoState);
+ const pseudoStateKeySet = new Set(Object.keys(pseudoState));
+ for (const key of baseStateKeys) {
+ if (pseudoStateKeySet.has(key)) {
+ pseudoStateKeySet.delete(key);
+ const value = pseudoState[key];
+ styleDeps.push(value);
+ innerPseudoState[key] = value;
+ } else {
+ const value = basePseudoState[key];
+ styleDeps.push(value);
+ innerPseudoState[key] = value;
+ }
}
- }
- if (baseFileUrl) {
- const baseFileUrlObj = new URL(baseFileUrl);
- if (originalPathname === baseFileUrlObj.pathname) {
- return extractSearchParams(urlObj, queryConnectionMap);
+ for (const key of pseudoStateKeySet) {
+ const value = pseudoState[key];
+ styleDeps.push(value);
+ innerPseudoState[key] = value;
}
+ } else if (basePseudoState) {
+ innerPseudoState = basePseudoState;
+ for (const key of Object.keys(basePseudoState)) {
+ const value = basePseudoState[key];
+ styleDeps.push(value);
+ }
+ } else if (pseudoState) {
+ innerPseudoState = pseudoState;
+ for (const key of Object.keys(pseudoState)) {
+ const value = pseudoState[key];
+ styleDeps.push(value);
+ }
+ } else {
+ innerPseudoState = PSEUDO_STATE_DEFAULT;
}
-
- // Root route with trailing slash matches all sub-paths (prefix matching, like other trailing-slash routes)
- if (parsedPattern.trailingSlash) {
- return extractSearchParams(urlObj, queryConnectionMap);
- }
-
- return null;
- }
-
- // Remove leading slash and split into segments
- let urlSegments = pathname.startsWith("/")
- ? pathname
- .slice(1)
- .split("/")
- .filter((s) => s !== "")
- : pathname.split("/").filter((s) => s !== "");
-
- // Handle trailing slash flexibility: if pattern has trailing slash but URL doesn't (or vice versa)
- // and we're at the end of segments, allow the match
- const urlHasTrailingSlash = pathname.endsWith("/") && pathname !== "/";
- const patternHasTrailingSlash = parsedPattern.trailingSlash;
-
- const params = {};
- let urlSegmentIndex = 0;
-
- // Process each pattern segment
- for (let i = 0; i < parsedPattern.segments.length; i++) {
- const patternSeg = parsedPattern.segments[i];
-
- if (patternSeg.type === "literal") {
- // Check if URL has this segment
- if (urlSegmentIndex >= urlSegments.length) {
- // URL is too short for this literal segment
- // Check if this literal segment can be treated as optional based on pattern hierarchy
- const canBeOptional = checkIfLiteralCanBeOptionalWithPatternObj(
- patternSeg.value,
- patternObj,
- );
- if (canBeOptional) {
- // Skip this literal segment, don't increment urlSegmentIndex
- continue;
+ const boxStyles = {};
+ const styleContext = {
+ parentBoxFlow,
+ boxFlow,
+ styleCSSVars,
+ pseudoState: innerPseudoState,
+ pseudoClasses,
+ pseudoElements,
+ remainingProps: rest,
+ styles: boxStyles
+ };
+ let boxPseudoNamedStyles = PSEUDO_NAMED_STYLES_DEFAULT;
+ const canForwardToChild = hasChildUsingForwardedProps;
+ const shouldForwardAllToChild = canForwardToChild && visualSelector && pseudoStateSelector;
+ const addStyle = (value, name, styleContext, stylesTarget, context) => {
+ const mergedValue = prepareStyleValue(stylesTarget[name], value, name, styleContext, context);
+ const cssVar = styleContext.styleCSSVars[name];
+ if (cssVar) {
+ addCSSVar(mergedValue, cssVar, stylesTarget);
+ if (name === "borderRadius" && value === "inherit") {
+ // "inherit" cannot be expressed via a CSS variable — a var() reference
+ // never propagates the inherit keyword itself. So when borderRadius="inherit"
+ // we must also set the inline style directly so the element actually
+ // inherits the radius from its parent.
+ styleDeps.push(name, value);
+ stylesTarget[name] = mergedValue;
}
- return null; // URL too short and literal is not optional
+ return true;
}
-
- const urlSeg = urlSegments[urlSegmentIndex];
- if (urlSeg !== patternSeg.value) {
- // Literal mismatch - this route doesn't match this URL
- return null;
+ styleDeps.push(name, value); // impact box style -> add to deps
+ stylesTarget[name] = mergedValue;
+ return false;
+ };
+ const addCSSVar = (value, name, stylesTarget) => {
+ styleDeps.push(name, value); // impact box style -> add to deps
+ stylesTarget[name] = value;
+ };
+ const addStyleMaybeForwarding = (value, name, styleContext, stylesTarget, context, visualChildPropStrategy) => {
+ if (!visualChildPropStrategy) {
+ addStyle(value, name, styleContext, stylesTarget, context);
+ return false;
}
- urlSegmentIndex++;
- } else if (patternSeg.type === "param") {
- // Parameter segment
- if (urlSegmentIndex >= urlSegments.length) {
- // No URL segment for this parameter
- if (patternSeg.optional) {
- // Optional parameter - don't add default here, let resolveParams handle it
- continue;
+ const cssVar = styleCSSVars[name];
+ if (cssVar) {
+ // css var wins over visual child handling
+ addStyle(value, name, styleContext, stylesTarget, context);
+ return false;
+ }
+ if (visualChildPropStrategy === "copy") {
+ // we stylyze ourself + forward prop to the child
+ addStyle(value, name, styleContext, stylesTarget, context);
+ }
+ if (!canForwardToChild) {
+ return false;
+ }
+ return true;
+ };
+
+ // By default ":hover", ":active" are not tracked.
+ // But if code explicitely do something like:
+ // style={{ ":hover": { backgroundColor: "red" } }}
+ // then we'll track ":hover" state changes even for basic elements like
+ const pseudoClassesFromStyleSet = new Set();
+ boxPseudoNamedStyles = {};
+ const visitProp = (value, name, styleContext, boxStylesTarget, styleOrigin) => {
+ const isPseudoElement = name.startsWith("::");
+ const isPseudoClass = name.startsWith(":");
+ if (isPseudoElement || isPseudoClass) {
+ styleDeps.push(name);
+ pseudoClassesFromStyleSet.add(name);
+ const pseudoStyleContext = {
+ ...styleContext,
+ styleCSSVars: {
+ ...styleCSSVars,
+ ...styleCSSVars[name]
+ },
+ pseudoName: name
+ };
+ const pseudoStyleKeys = Object.keys(value);
+ if (isPseudoElement) {
+ const pseudoElementStyles = {};
+ for (const key of pseudoStyleKeys) {
+ visitProp(value[key], key, pseudoStyleContext, pseudoElementStyles, "pseudo_style");
+ }
+ boxPseudoNamedStyles[name] = pseudoElementStyles;
+ return;
}
- // Required parameter missing - but check if we can use trailing slash logic
- // If this is the last segment and we have a trailing slash difference, it might still match
- const isLastSegment = i === parsedPattern.segments.length - 1;
- if (isLastSegment && patternHasTrailingSlash && !urlHasTrailingSlash) {
- // Pattern expects trailing slash segment, URL doesn't have it - allow missing optional param
- continue;
+ const pseudoClassStyles = {};
+ for (const key of pseudoStyleKeys) {
+ visitProp(value[key], key, pseudoStyleContext, pseudoClassStyles, "pseudo_style");
+ boxPseudoNamedStyles[name] = pseudoClassStyles;
}
- return null; // Required parameter missing
+ return;
}
-
- // Capture URL segment as parameter value
- const urlSeg = urlSegments[urlSegmentIndex];
- params[patternSeg.name] = decodeURIComponent(urlSeg);
- urlSegmentIndex++;
- }
- }
-
- // 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)
- if (
- !parsedPattern.wildcard &&
- !parsedPattern.trailingSlash &&
- urlSegmentIndex < urlSegments.length
- ) {
- return null; // Pattern without trailing slash/wildcard should not match extra segments
- }
-
- // If there are remaining URL segments and we have descendant routes,
- // try to capture parameters from descendant routes
- if (
- urlSegmentIndex < urlSegments.length &&
- patternObj &&
- patternObj.children
- ) {
- const remainingSegments = urlSegments.slice(urlSegmentIndex);
-
- // Try to match remaining segments against child routes to extract their parameters
- for (const childPattern of patternObj.children) {
- const childParams = tryExtractChildParameters(
- childPattern,
- remainingSegments,
- params,
- );
- if (childParams) {
- Object.assign(params, childParams);
- break; // Found a matching child pattern
+ const context = styleOrigin === "base_style" ? "js" : "css";
+ const isCss = styleOrigin === "base_style" || styleOrigin === "style";
+ if (isCss) {
+ addStyle(value, name, styleContext, boxStylesTarget, context);
+ return;
}
- }
- }
-
- // Add search parameters
- const searchParams = extractSearchParams(urlObj, queryConnectionMap);
- Object.assign(params, searchParams);
-
- // Don't add defaults here - rawParams should only contain what's in the URL
- // Defaults are handled by resolveParams() to create the final merged parameters
-
- return params;
-};
-
-/**
- * Build query string from parameters, respecting rawUrlPart values
- */
-const buildQueryString = (params) => {
- const searchParamPairs = [];
-
- for (const [key, value] of Object.entries(params)) {
- if (value !== undefined && value !== null) {
- const encodedKey = encodeURIComponent(key);
-
- // Handle array values - join with commas
- if (Array.isArray(value)) {
- if (value.length === 0) ; else {
- const encodedValue = value
- .map((item) => encodeURIComponent(String(item)))
- .join(",");
- searchParamPairs.push(`${encodedKey}=${encodedValue}`);
+ if (name.startsWith("--")) {
+ addStyle(value, name, styleContext, boxStylesTarget, context);
+ return;
+ }
+ const isPseudoStyle = styleOrigin === "pseudo_style";
+ if (isStyleProp(name)) {
+ // it's a style prop, we need first to check if we have css var to handle them
+ // otherwise we decide to put it either on self or child
+ const visualChildPropStrategy = visualSelector && getVisualChildStylePropStrategy(name);
+ const getStyle = getHowToHandleStyleProp(name);
+ if (
+ // prop name === css style name
+ !getStyle) {
+ const needForwarding = addStyleMaybeForwarding(value, name, styleContext, boxStylesTarget, context, visualChildPropStrategy);
+ if (needForwarding) {
+ if (isPseudoStyle) ; else {
+ childForwardedProps[name] = value;
+ }
+ }
+ return;
+ }
+ const cssValues = getStyle(value, styleContext);
+ if (!cssValues) {
+ return;
+ }
+ let needForwarding = false;
+ for (const styleName of Object.keys(cssValues)) {
+ const cssValue = cssValues[styleName];
+ needForwarding = addStyleMaybeForwarding(cssValue, styleName, styleContext, boxStylesTarget, context, visualChildPropStrategy);
+ }
+ if (needForwarding) {
+ if (isPseudoStyle) ; else {
+ childForwardedProps[name] = value;
+ }
}
+ return;
}
- // Handle boolean values - if true, just add the key without value
- else if (value === true || value === "") {
- searchParamPairs.push(encodedKey);
+ const cssVarName = styleCSSVars[name];
+ if (cssVarName) {
+ if (value !== undefined) {
+ addCSSVar(value, cssVarName, boxStylesTarget);
+ }
+ return;
}
- // Handle Date objects - format as YYYY-MM-DD using UTC to match new Date('YYYY-MM-DD') semantics
- else if (value instanceof Date) {
- const yyyy = value.getUTCFullYear();
- const mm = String(value.getUTCMonth() + 1).padStart(2, "0");
- const dd = String(value.getUTCDate()).padStart(2, "0");
- searchParamPairs.push(`${encodedKey}=${yyyy}-${mm}-${dd}`);
+ // not a style prop what do we do with it?
+ // When pseudoStateSelector is set, the child element is the semantic/interactive one
+ // When both selectors are set the child IS the component (e.g. Button with scale
+ // transform) — forward everything so it behaves like a normal element.
+ // When only pseudoStateSelector is set, the box keeps its own visual identity
+ // (border, background, overflow…) and the child is just the interactive/semantic
+ // element inside it. Only event handlers (onXxx) belong on that child; everything
+ // else stays on the box.
+ if (isPseudoStyle) {
+ if (shouldForwardAllToChild) ; else {
+ console.warn(`unsupported pseudo style key "${name}"`);
+ selfForwardedProps[name] = value;
+ }
+ } else if (shouldForwardAllToChild) {
+ childForwardedProps[name] = value;
} else {
- const encodedValue = encodeParamValue(value, false); // Search params encode slashes
- searchParamPairs.push(`${encodedKey}=${encodedValue}`);
+ selfForwardedProps[name] = value;
}
- }
- }
-
- return searchParamPairs.join("&");
-};
-
-/**
- * Extract search parameters from URL
- */
-const extractSearchParams = (urlObj, queryConnectionMap) => {
- const params = {};
-
- // Parse the raw query string manually instead of using urlObj.searchParams
- // This is necessary for array parameters to handle encoded commas correctly.
- // urlObj.searchParams automatically decodes %2C to , which breaks our comma-based array splitting.
- //
- // Design choice: We use comma-separated values (colors=red,blue,green) instead of
- // the standard repeated parameters (colors=red&colors=blue&colors=green) because:
- // 1. More human-readable URLs
- // 2. Shorter URL length
- // 3. Easier to copy/paste and manually edit
- if (!urlObj.search) {
- return params;
- }
-
- const rawQuery = urlObj.search.slice(1); // Remove leading ?
- const pairs = rawQuery.split("&");
-
- for (const pair of pairs) {
- const eqIndex = pair.indexOf("=");
- let key;
- let rawValue;
-
- if (eqIndex > -1) {
- key = decodeURIComponent(pair.slice(0, eqIndex));
- rawValue = pair.slice(eqIndex + 1); // Keep raw for array processing
- } else {
- key = decodeURIComponent(pair);
- rawValue = "";
- }
-
- const connection = queryConnectionMap.get(key);
- const signalType = connection ? connection.type : null;
-
- // Cast value based on signal type
- if (signalType === "array") {
- // Handle array query parameters with proper comma encoding:
- // ?colors=red,blue,green → ["red", "blue", "green"]
- // ?colors=red,blue%2Cgreen → ["red", "blue,green"] (comma in value)
- // ?colors= → []
- // ?colors → []
- if (rawValue === "") {
- params[key] = [];
- } else {
- params[key] = rawValue
- .split(",")
- .map((item) => decodeURIComponent(item))
- .filter((item) => item.trim() !== "");
+ return;
+ };
+ if (baseStyle) {
+ for (const key of baseStyle) {
+ const value = baseStyle[key];
+ visitProp(value, key, styleContext, boxStyles, "baseStyle");
}
- } else if (signalType === "number" || signalType === "float") {
- const decodedValue = decodeURIComponent(rawValue);
- const numberValue = Number(decodedValue);
- params[key] = isNaN(numberValue) ? decodedValue : numberValue;
- } else if (signalType === "boolean") {
- const decodedValue = decodeURIComponent(rawValue);
- // Handle boolean query parameters:
- // ?walk=true → true
- // ?walk=1 → true
- // ?walk → true (parameter present without value)
- // ?walk=false → false
- // ?walk=0 → false
- params[key] =
- decodedValue === "true" || decodedValue === "1" || decodedValue === "";
- } else if (signalType === "date") {
- const decodedValue = decodeURIComponent(rawValue);
- // Keep as "YYYY-MM-DD" string — canonical date form, no timezone conversion
- params[key] = decodedValue.slice(0, 10);
- } else if (signalType === "datetime") {
- const decodedValue = decodeURIComponent(rawValue);
- // Normalize to ISO string — canonical datetime form
- const d = new Date(decodedValue);
- params[key] = isNaN(d.getTime()) ? decodedValue : d.toISOString();
- } else {
- params[key] = decodeURIComponent(rawValue);
- }
- }
-
- return params;
-};
-
-/**
- * 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,
- originalPattern,
- patternObj,
-) => {
- const queryParams = {};
- const processedParams = new Set();
-
- // Get pattern data for this pattern - use direct pattern object or null
- const patternData = patternObj;
-
- // Collect all ancestors by traversing parent chain - only if we have pattern data
- const ancestorPatterns = [];
- if (patternData) {
- let currentParent = patternData.parent;
- while (currentParent) {
- ancestorPatterns.unshift(currentParent); // Add to front for correct order
- // Move to next parent in the chain
- currentParent = currentParent.parent;
}
- }
-
- // DEBUG: Log what we found
- if (DEBUG$2) {
- // Force debug for now
- console.debug(`Building params for ${originalPattern}`);
- console.debug(`parsedPattern:`, parsedPattern.original);
- console.debug(`params:`, params);
- console.debug(
- `ancestorPatterns:`,
- ancestorPatterns.map((p) => p.urlPatternRaw),
- );
- }
-
- // Step 1: Add query parameters from ancestor patterns (oldest to newest)
- // This ensures ancestor parameters come first in their declaration order
- // ancestorPatterns is in correct order: root ancestor first, then immediate parent
-
- for (const ancestorPatternObj of ancestorPatterns) {
- for (const queryParam of ancestorPatternObj.parsedPattern.queryParams) {
- const paramName = queryParam.name;
- if (params[paramName] !== undefined && !processedParams.has(paramName)) {
- queryParams[paramName] = params[paramName];
- processedParams.add(paramName);
-
- if (DEBUG$2) {
- console.debug(
- `Added ancestor param: ${paramName}=${params[paramName]}`,
- );
+ for (const propName of remainingPropKeySet) {
+ const propValue = rest[propName];
+ if (baseChildPropSet?.has(propName) || childPropSet?.has(propName)) {
+ if (canForwardToChild) {
+ childForwardedProps[propName] = propValue;
+ } else {
+ selfForwardedProps[propName] = propValue;
+ }
+ continue;
+ }
+ if (canForwardToChild && toCopySet.has(propName)) {
+ childForwardedProps[propName] = propValue;
+ }
+ const isDataAttribute = propName.startsWith("data-");
+ if (isDataAttribute) {
+ selfForwardedProps[propName] = propValue;
+ continue;
+ }
+ // At some point I'd like to transform all data-* attribute in the DOM
+ // into navi-* attribute so that when you look at the DOM you can easily understand which attributes
+ // where added by navi or your code.
+ // This help human to better scan the DOM
+ const isNaviAttribute = propName.startsWith("navi-");
+ if (isNaviAttribute) {
+ selfForwardedProps[propName] = propValue;
+ continue;
+ }
+ const isEventHandler = propName.startsWith("on");
+ if (isEventHandler) {
+ if (shouldForwardAllToChild) {
+ childForwardedProps[propName] = propValue;
+ continue;
}
+ selfForwardedProps[propName] = propValue;
+ continue;
+ }
+ if (canForwardToChild && pseudoStateSelector && PSEUDO_STATE_CHILD_PROP_SET.has(propName)) {
+ childForwardedProps[propName] = propValue;
+ continue;
}
+ visitProp(propValue, propName, styleContext, boxStyles, "prop");
}
- }
-
- // Step 2: Add query parameters from current pattern
- if (parsedPattern.queryParams) {
- if (DEBUG$2) {
- console.debug(
- `Processing current pattern query params:`,
- parsedPattern.queryParams.map((q) => q.name),
- );
+ if (typeof style === "string") {
+ const styleObject = normalizeStyles(style, "css");
+ for (const styleName of Object.keys(styleObject)) {
+ const styleValue = styleObject[styleName];
+ visitProp(styleValue, styleName, styleContext, boxStyles, "style");
+ }
+ } else if (style && typeof style === "object") {
+ for (const styleName of Object.keys(style)) {
+ const styleValue = style[styleName];
+ visitProp(styleValue, styleName, styleContext, boxStyles, "style");
+ }
}
-
- for (const queryParam of parsedPattern.queryParams) {
- const paramName = queryParam.name;
- if (params[paramName] !== undefined && !processedParams.has(paramName)) {
- queryParams[paramName] = params[paramName];
- processedParams.add(paramName);
-
- if (DEBUG$2) {
- console.debug(
- `Added current param: ${paramName}=${params[paramName]}`,
- );
- }
+ styleDeps.push(pseudoStateSelector, innerPseudoState);
+ let innerPseudoClasses;
+ if (pseudoClassesFromStyleSet.size) {
+ innerPseudoClasses = [...pseudoClasses];
+ if (pseudoClasses !== PSEUDO_CLASSES_DEFAULT) {
+ styleDeps.push(...pseudoClasses);
+ }
+ for (const key of pseudoClassesFromStyleSet) {
+ innerPseudoClasses.push(key);
+ styleDeps.push(key);
+ }
+ } else {
+ innerPseudoClasses = pseudoClasses;
+ if (pseudoClasses !== PSEUDO_CLASSES_DEFAULT) {
+ styleDeps.push(...pseudoClasses);
}
}
+ const syncBox = useCallback(boxEl => {
+ const pseudoStateEl = pseudoStateSelector ? boxEl.querySelector(pseudoStateSelector) : boxEl;
+ if (!pseudoStateEl) {
+ console.error(`pseudoStateSelector "${pseudoStateSelector}" did not match any element inside the box`, boxEl);
+ }
+ const visualEl = visualSelector ? boxEl.querySelector(visualSelector) : null;
+ return initPseudoStyles(pseudoStateEl, {
+ pseudoClasses: innerPseudoClasses,
+ pseudoState: innerPseudoState,
+ effect: state => {
+ applyStyle(boxEl, boxStyles, state, boxPseudoNamedStyles, preventInitialTransition);
+ },
+ elementToImpact: boxEl,
+ elementListeningPseudoState: visualEl === pseudoStateEl ? null : visualEl
+ });
+ }, styleDeps);
+ finalRef = useComposeElementRef(syncBox, ref);
+ usePartiallyHidden(finalRef, Boolean(rest.viewTransitionName));
}
-
- // Step 3: Add remaining parameters (extra params) alphabetically
- const extraParams = [];
-
- // Get all path parameter names to exclude them
- const pathParamNames = new Set(
- parsedPattern.segments.filter((s) => s.type === "param").map((s) => s.name),
- );
-
- for (const [key, value] of Object.entries(params)) {
- if (
- !pathParamNames.has(key) &&
- !processedParams.has(key) &&
- value !== undefined
- ) {
- extraParams.push([key, value]);
- }
+ let innerChildren = children;
+ if (separator) {
+ // Flatten nested arrays (e.g., from .map()) to treat each element as individual child
+ innerChildren = applySeparatorOnChildren(innerChildren, separator);
}
- // Sort extra params alphabetically for consistent order
- extraParams.sort(([a], [b]) => a.localeCompare(b));
-
- // Add sorted extra params
- for (const [key, value] of extraParams) {
- queryParams[key] = value;
+ // When hasChildUsingForwardedProps is used it means
+ // Some/all the children needs to access remainingProps
+ // to render and will provide a function to do so.
+ if (hasChildUsingForwardedProps) {
+ innerChildren = jsx(BoxForwardedPropsContext.Provider, {
+ value: childForwardedProps,
+ children: innerChildren
+ });
}
-
- return queryParams;
+ const aspectRatio = rest.square || rest.circle ? "1/1" : rest.aspectRatio;
+ return jsx(TagName, {
+ ref: finalRef,
+ className: innerClassName,
+ "navi-box-flow": boxFlowIsDefault ? undefined : boxFlow,
+ "navi-box-flow-row": row ? "" : undefined,
+ "navi-box-flow-column": column ? "" : undefined,
+ "navi-aspect-ratio": aspectRatio ? aspectRatio : undefined,
+ "data-visual-selector": visualSelector,
+ ...selfForwardedProps,
+ children: jsx(BoxFlowContext.Provider, {
+ value: boxFlow,
+ children: innerChildren
+ })
+ });
};
-
-/**
- * Build a URL from a pattern and parameters
- */
-const buildUrlFromPattern = (
- parsedPattern,
- params = {},
- originalPattern = null,
- patternObj = null,
-) => {
- if (parsedPattern.segments.length === 0) {
- // Root route
- const queryParams = {};
- for (const [key, value] of Object.entries(params)) {
- if (value !== undefined) {
- queryParams[key] = value;
- }
- }
- const search = buildQueryString(queryParams);
- return `/${search ? `?${search}` : ""}`;
+const toCopySet = new Set([]);
+const applySeparatorOnChildren = (children, separator) => {
+ const flattenedChildren = toChildArray(children);
+ if (flattenedChildren.length <= 1) {
+ return children;
}
-
- const segments = [];
-
- for (const patternSeg of parsedPattern.segments) {
- if (patternSeg.type === "literal") {
- segments.push(patternSeg.value);
- } else if (patternSeg.type === "param") {
- const value = params[patternSeg.name];
-
- // If value is provided, include it
- if (value !== undefined) {
- segments.push(encodeParamValue(value, false)); // Named parameters encode slashes
- } else if (!patternSeg.optional) {
- // For required parameters without values, keep the placeholder
- segments.push(`:${patternSeg.name}`);
- }
- // Optional parameters with undefined values are omitted
+ const childrenWithSeparators = [];
+ let i = 0;
+ while (true) {
+ const child = flattenedChildren[i];
+ childrenWithSeparators.push(child);
+ i++;
+ const isLast = i === flattenedChildren.length;
+ if (isLast) {
+ break;
}
- }
-
- let path = `/${segments.join("/")}`;
-
- // Handle trailing slash - only add if it serves a purpose
- if (parsedPattern.trailingSlash && !path.endsWith("/") && path !== "/") {
- // Only add trailing slash if the original pattern suggests there could be more content
- // For patterns like "/admin/:section/" where the slash is at the very end,
- // it's not needed in the generated URL if there are no more segments
- const lastSegment =
- parsedPattern.segments[parsedPattern.segments.length - 1];
- const hasMorePotentialContent =
- parsedPattern.wildcard || (lastSegment && lastSegment.type === "literal"); // Only add slash after literals, not parameters
-
- if (hasMorePotentialContent) {
- path += "/";
+ const nextChild = flattenedChildren[i];
+ if (!shouldInjectSeparatorBetween(child, nextChild)) {
+ continue;
}
- } else if (
- !parsedPattern.trailingSlash &&
- path.endsWith("/") &&
- path !== "/"
- ) {
- // Remove trailing slash for patterns without trailing slash
- path = path.slice(0, -1);
- }
-
- // Check if we'll have query parameters to decide on trailing slash removal
- const willHaveQueryParams =
- parsedPattern.queryParams.some((qp) => {
- const value = params[qp.name];
- return value !== undefined;
- }) ||
- Object.entries(params).some(([key, value]) => {
- const isPathParam = parsedPattern.segments.some(
- (s) => s.type === "param" && s.name === key,
- );
- const isQueryParam = parsedPattern.queryParams?.some(
- (qp) => qp.name === key,
- );
- return value !== undefined && !isPathParam && !isQueryParam;
- });
-
- // Remove trailing slash when we have query params for prettier URLs
- if (willHaveQueryParams && path.endsWith("/") && path !== "/") {
- path = path.slice(0, -1);
- }
-
- // Always remove trailing slash from simple paths (unless root) for cleaner URLs
- if (path.endsWith("/") && path !== "/" && !willHaveQueryParams) {
- path = path.slice(0, -1);
+ // Support function separators that receive separator index
+ const separatorElement = typeof separator === "function" ? separator(i - 1) // i-1 because i was incremented after pushing child
+ : separator;
+ childrenWithSeparators.push(separatorElement);
}
-
- // Build query parameters respecting hierarchical order
- const queryParams = buildHierarchicalQueryParams(
- parsedPattern,
- params,
- originalPattern,
- patternObj,
- );
-
- const search = buildQueryString(queryParams);
-
- // No longer handle trailing slash inheritance here
-
- return path + (search ? `?${search}` : "");
+ return childrenWithSeparators;
};
-
-/**
- * Check if childPattern is a child route of parentPattern
- * This determines parent-child relationships for signal clearing behavior.
- *
- * Route families vs parent-child relationships:
- * - Different families: preserve signals (e.g., "/" and "/settings")
- * - Parent-child: clear signals when navigating to parent (e.g., "/settings" and "/settings/:tab")
- *
- * E.g., "/admin/settings/:tab" is a child of "/admin/:section/"
- * Also, "/admin/?tab=something" is a child of "/admin/"
- */
-const isChildPattern = (childPattern, parentPattern) => {
- if (!childPattern || !parentPattern) {
+const shouldInjectSeparatorBetween = (left, right) => {
+ if (isValidElement(left) && left.props?.hidden) {
return false;
}
-
- // Split path and query parts
- const [childPath, childQuery] = childPattern.split("?");
- const [parentPath, parentQuery] = parentPattern.split("?");
-
- // Remove trailing slashes for path comparison
- const cleanChild = childPath.replace(/\/$/, "");
- const cleanParent = parentPath.replace(/\/$/, "");
-
- // CASE 1: Same path, child has query params, parent doesn't
- // E.g., "/admin/?tab=something" is child of "/admin/"
- if (cleanChild === cleanParent && childQuery && !parentQuery) {
- return true;
- }
-
- // CASE 2: Traditional path-based child relationship
- const childSegments = cleanChild.split("/").filter((s) => s);
- const parentSegments = cleanParent.split("/").filter((s) => s);
-
- // Child must have at least as many segments as parent (or more for specificity)
- if (childSegments.length < parentSegments.length) {
+ if (isValidElement(right) && right.props?.hidden) {
return false;
}
+ return true;
+};
- let hasMoreSpecificSegment = false;
-
- // Check if all parent segments match child segments (allowing for parameters)
- for (let i = 0; i < parentSegments.length; i++) {
- const parentSeg = parentSegments[i];
- const childSeg = childSegments[i];
+const useDebounceTrue = (value, delay = 300) => {
+ const [debouncedTrue, setDebouncedTrue] = useState(false);
+ const timerRef = useRef(null);
- if (parentSeg.startsWith(":")) {
- // Parent has parameter - child can have any value in that position
- // Child is more specific if it has a literal value for a parent parameter
- if (!childSeg.startsWith(":")) {
- hasMoreSpecificSegment = true;
+ useLayoutEffect(() => {
+ // If value is true or becomes true, start a timer
+ if (value) {
+ timerRef.current = setTimeout(() => {
+ setDebouncedTrue(true);
+ }, delay);
+ } else {
+ // If value becomes false, clear any pending timer and immediately set to false
+ if (timerRef.current) {
+ clearTimeout(timerRef.current);
+ timerRef.current = null;
}
- continue;
+ setDebouncedTrue(false);
}
- // Parent has literal - child must match exactly
- if (parentSeg !== childSeg) {
- return false;
- }
- }
+ // Cleanup function
+ return () => {
+ if (timerRef.current) {
+ clearTimeout(timerRef.current);
+ }
+ };
+ }, [value, delay]);
- // Child must be more specific (more segments OR more specific segments)
- return childSegments.length > parentSegments.length || hasMoreSpecificSegment;
+ return debouncedTrue;
};
-/**
- * Check if a parameter is redundant because the child pattern already has it as a literal segment
- * E.g., parameter "section" is redundant for pattern "/admin/settings/:tab" because "settings" is literal
- */
-const isParameterRedundantWithLiteralSegments = (
- childPattern,
- parentPattern,
- paramName,
-) => {
- // Find which segment position corresponds to this parameter in the parent
- let paramSegmentIndex = -1;
- for (let i = 0; i < parentPattern.segments.length; i++) {
- const segment = parentPattern.segments[i];
- if (segment.type === "param" && segment.name === paramName) {
- paramSegmentIndex = i;
- break;
- }
- }
-
- // If parameter not found in parent segments, it's not redundant with path
- if (paramSegmentIndex === -1) {
- return false;
- }
-
- // Check if child has a literal segment at the same position
- if (childPattern.segments.length > paramSegmentIndex) {
- const childSegment = childPattern.segments[paramSegmentIndex];
- if (childSegment.type === "literal") {
- // Child has a literal segment where parent has parameter
- // This means the child is more specific and shouldn't inherit this parameter
- return true; // Redundant - child already specifies this position with a literal
- }
- }
-
- return false;
+const useNetworkSpeed = () => {
+ return networkSpeedSignal.value;
};
-/**
- * Register all patterns at once and build their relationships
- */
-const setupRoutePatterns = (routePatterns) => {
- const routePatternSet = new Set(); // Set of pattern objects
- // Phase 1: Fill pattern set
- for (const routePattern of routePatterns) {
- routePatternSet.add(routePattern);
+const connection =
+ window.navigator.connection ||
+ window.navigator.mozConnection ||
+ window.navigator.webkitConnection;
+
+const getNetworkSpeed = () => {
+ // ✅ Network Information API (support moderne)
+ if (!connection) {
+ return "3g";
}
- // Phase 2: Determine parent-child relationships based on pattern analysis
- for (const routePattern of routePatternSet) {
- for (const otherRoutePattern of routePatternSet) {
- if (otherRoutePattern === routePattern) {
- continue;
- }
- if (
- !isChildPattern(
- routePattern.cleanPattern,
- otherRoutePattern.cleanPattern,
- )
- ) {
- continue;
- }
- const currentSegmentCount = routePattern.parent
- ? getPathSegmentCount(routePattern.parent.originalPattern)
- : 0;
- const otherSegmentCount = getPathSegmentCount(
- otherRoutePattern.originalPattern,
- );
- if (!routePattern.parent || otherSegmentCount > currentSegmentCount) {
- routePattern.parent = otherRoutePattern;
- }
- otherRoutePattern.children.push(routePattern);
+ if (connection) {
+ const effectiveType = connection.effectiveType;
+ if (effectiveType) {
+ return effectiveType; // "slow-2g", "2g", "3g", "4g", "5g"
+ }
+ const downlink = connection.downlink;
+ if (downlink) {
+ // downlink is in Mbps
+ if (downlink < 1) return "slow-2g"; // < 1 Mbps
+ if (downlink < 2.5) return "2g"; // 1-2.5 Mbps
+ if (downlink < 10) return "3g"; // 2.5-10 Mbps
+ return "4g"; // > 10 Mbps
}
}
- // Phase 3: Inherit search parameter connections from ancestors
- // Search params are global and should be inherited by descendants regardless of path segments
- for (const routePattern of routePatternSet) {
- let ancestorRoutePattern = routePattern.parent;
- while (ancestorRoutePattern) {
- // For each ancestor's query connection, check if it should be inherited
- for (const [
- paramName,
- ancestorConnection,
- ] of ancestorRoutePattern.queryConnectionMap) {
- // Skip if descendant already has this parameter
- if (routePattern.queryConnectionMap.has(paramName)) {
- continue;
- }
-
- // Check if child route is truly more specific than parent, or just using default values
- // If child has literal segments that match parent's parameter defaults, skip inheritance
- let shouldInherit = true;
+ return "3g";
+};
- // Compare path segments to see if child is just parent with default values
- const childSegments = routePattern.pattern.segments;
- const parentSegments = ancestorRoutePattern.pattern.segments;
+const updateNetworkSpeed = () => {
+ networkSpeedSignal.value = getNetworkSpeed();
+};
- for (
- let i = 0;
- i < Math.min(childSegments.length, parentSegments.length);
- i++
- ) {
- const childSeg = childSegments[i];
- const parentSeg = parentSegments[i];
+const networkSpeedSignal = signal(getNetworkSpeed());
- if (parentSeg.type === "param" && childSeg.type === "literal") {
- // Check if this literal value matches the parent parameter's default
- const parentConnection = ancestorRoutePattern.pathConnectionMap.get(
- parentSeg.name,
- );
- if (
- parentConnection &&
- parentConnection.getDefaultValue() === childSeg.value
- ) {
- // Child uses literal that matches parent's parameter default
- // This means they're essentially the same route, not parent-child
- shouldInherit = false;
- break;
- }
- }
- }
+const setupNetworkMonitoring = () => {
+ const cleanupFunctions = [];
- if (shouldInherit) {
- // Create inherited connection
- const inheritedConnection = {
- ...ancestorConnection,
- inherited: true, // Mark as inherited for proper handling
- };
- routePattern.queryConnectionMap.set(paramName, inheritedConnection);
- routePattern.connections.push(inheritedConnection);
+ // ✅ 1. Écouter les changements natifs
- if (DEBUG$2) {
- console.debug(
- `[${routePattern.originalPattern}] Inherited search param "${paramName}" from ancestor [${ancestorRoutePattern.originalPattern}]`,
- );
- }
- } else if (DEBUG$2) {
- console.debug(
- `[${routePattern.originalPattern}] Skipped inheriting "${paramName}" - child uses default values, not truly more specific`,
- );
- }
- }
- ancestorRoutePattern = ancestorRoutePattern.parent;
- }
+ if (connection) {
+ connection.addEventListener("change", updateNetworkSpeed);
+ cleanupFunctions.push(() => {
+ connection.removeEventListener("change", updateNetworkSpeed);
+ });
}
- // Phase 4: Collect all relevant signals for each pattern based on relationships
- for (const routePattern of routePatternSet) {
- const allRelevantSignals = new Set();
- // Add own signals
- for (const signal of routePattern.signalSet) {
- allRelevantSignals.add(signal);
+ // ✅ 2. Polling de backup (toutes les 60 secondes)
+ const pollInterval = setInterval(updateNetworkSpeed, 60000);
+ cleanupFunctions.push(() => clearInterval(pollInterval));
+
+ // ✅ 3. Vérifier lors de la reprise d'activité
+ const handleVisibilityChange = () => {
+ if (!document.hidden) {
+ updateNetworkSpeed();
}
+ };
- // Add signals from ancestors (they might be inherited)
- let parentRoutePattern = routePattern.parent;
- while (parentRoutePattern) {
- for (const connection of parentRoutePattern.connections) {
- allRelevantSignals.add(connection.signal);
- }
- // Move up the parent chain
- parentRoutePattern = parentRoutePattern.parent;
- }
+ document.addEventListener("visibilitychange", handleVisibilityChange);
+ cleanupFunctions.push(() => {
+ document.removeEventListener("visibilitychange", handleVisibilityChange);
+ });
- // Add signals from descendants (they might be used for optimization)
- const addDescendantSignals = (patternObj) => {
- for (const childPattern of patternObj.children) {
- // Add child's own signals
- for (const connection of childPattern.connections) {
- allRelevantSignals.add(connection.signal);
- }
- // Recursively add grandchildren signals
- addDescendantSignals(childPattern);
- }
- };
- addDescendantSignals(routePattern);
+ // ✅ 4. Vérifier lors de la reprise de connexion
+ const handleOnline = () => {
+ updateNetworkSpeed();
+ };
- // Update the pattern's signalSet with all relevant signals
- routePattern.signalSet = allRelevantSignals;
+ window.addEventListener("online", handleOnline);
+ cleanupFunctions.push(() => {
+ window.removeEventListener("online", handleOnline);
+ });
- if (DEBUG$2 && allRelevantSignals.size > 0) {
- console.debug(
- `[${routePattern.urlPatternRaw}] Collected ${allRelevantSignals.size} relevant signals`,
- );
+ // Cleanup global
+ return () => {
+ cleanupFunctions.forEach((cleanup) => cleanup());
+ };
+};
+setupNetworkMonitoring();
+
+installImportMetaCssBuild(import.meta);const css$X = /* css */`
+ .navi_loading_indicator_fluid_container {
+ position: relative;
+ display: flex;
+ width: 100%;
+ height: 100%;
+ border-radius: inherit;
+ opacity: 1;
+
+ &[data-visually-hidden] {
+ opacity: 0;
}
}
- // Phase 5: Precompute descendant path signals for each pattern (used by canReachLiteralValue)
- // Stored as a Map
for O(1) lookup by position.
- for (const routePattern of routePatternSet) {
- const descendantPathSignalsByIndex = new Map();
- const collectDescendantPathSignals = (patternObj) => {
- for (const conn of patternObj.connections) {
- if (conn.paramType === "path") {
- const paramSegment = patternObj.pattern.segments.find(
- (seg) => seg.type === "param" && seg.name === conn.paramName,
- );
- if (paramSegment) {
- const { index } = paramSegment;
- let conns = descendantPathSignalsByIndex.get(index);
- if (!conns) {
- conns = [];
- descendantPathSignalsByIndex.set(index, conns);
- }
- conns.push(conn);
- }
- }
+`;
+
+/**
+ * A loading indicator that fills its container, adapting to its shape like water.
+ * Reads border-radius from the container (or accepts an explicit `radius` prop).
+ *
+ * @param {string} [props.color="currentColor"] - Stroke color
+ * @param {number|"inherit"} [props.radius] - Corner radius in px. When omitted, reads border-radius from the container.
+ * @param {number} [props.size=2] - Stroke width in px
+ * @param {string} [props.networkSpeed] - Force the connection speed the animation is paced by ("slow-2g" | "2g" | "3g" | "4g"). Omitted, it follows the real connection.
+ */
+const LoadingIndicatorFluid = ({
+ color = "currentColor",
+ size = 2,
+ radius,
+ networkSpeed,
+ visuallyHidden,
+ ...rest
+}) => {
+ import.meta.css = [css$X, "@jsenv/navi/src/graphic/loading/loading_indicator_fluid.jsx"];
+ const ref = useRef(null);
+ // The container dimensions can be deduced from the ref itself as the indicator is absolute inset 0
+ const [containerWidth, setContainerWidth] = useState(0);
+ const [containerHeight, setContainerHeight] = useState(0);
+ const [containerRadius, setContainerRadius] = useState(0);
+ useLayoutEffect(() => {
+ const indicatorEl = ref.current;
+ if (!indicatorEl) {
+ return null;
+ }
+ const {
+ width,
+ height
+ } = indicatorEl.getBoundingClientRect();
+ setContainerWidth(width);
+ setContainerHeight(height);
+ if (radius === undefined || radius === "inherit") {
+ const parentEl = indicatorEl.parentElement;
+ // Prefer the inline style (always available, even before layout is computed).
+ // Fall back to computed longhands — getComputedStyle shorthand may return ""
+ // if the browser hasn't resolved the layout yet.
+ const radius = parentEl.style.borderRadius || parentEl.style.borderTopLeftRadius || getComputedStyle(parentEl).borderTopLeftRadius || "0px";
+ setContainerRadius(radius);
+ }
+ let animationFrameId = null;
+ // Create a resize observer to detect changes in the container's dimensions
+ const resizeObserver = new ResizeObserver(entries => {
+ // Use requestAnimationFrame to debounce updates
+ if (animationFrameId) {
+ cancelAnimationFrame(animationFrameId);
}
- for (const child of patternObj.children) {
- collectDescendantPathSignals(child);
+ animationFrameId = requestAnimationFrame(() => {
+ const [containerEntry] = entries;
+ const {
+ width,
+ height
+ } = containerEntry.contentRect;
+ setContainerWidth(width);
+ setContainerHeight(height);
+ });
+ });
+ resizeObserver.observe(indicatorEl);
+ return () => {
+ if (animationFrameId) {
+ cancelAnimationFrame(animationFrameId);
}
+ resizeObserver.disconnect();
};
- collectDescendantPathSignals(routePattern);
- routePattern.descendantPathSignals = descendantPathSignalsByIndex;
+ }, []);
+ return jsx("span", {
+ ...rest,
+ ref: ref,
+ className: "navi_loading_indicator_fluid_container",
+ "data-visually-hidden": visuallyHidden ? "" : undefined,
+ children: containerWidth > 0 && containerHeight > 0 && jsx(LoadingRectangleSvg, {
+ color: color,
+ radius: containerRadius,
+ width: containerWidth,
+ height: containerHeight,
+ strokeWidth: size,
+ networkSpeed: networkSpeed
+ })
+ });
+};
+const LoadingRectangleSvg = ({
+ width,
+ height,
+ color,
+ radius,
+ trailColor = "transparent",
+ strokeWidth,
+ networkSpeed: networkSpeedForced
+}) => {
+ const margin = Math.max(2, Math.min(width, height) * 0.03);
+
+ // Calculate the drawable area
+ const drawableWidth = width - margin * 2;
+ const drawableHeight = height - margin * 2;
+
+ // ✅ Check if this should be a circle - only if width and height are nearly equal
+ const maxPossibleRadius = Math.min(drawableWidth, drawableHeight) / 2;
+ radius = resolveCSSSize(radius, {
+ availableSize: Math.min(width, height)
+ });
+ const actualRadius = Math.min(radius || Math.min(drawableWidth, drawableHeight) * 0.05, maxPossibleRadius // ✅ Limité au radius maximum possible
+ );
+ const aspectRatio = Math.max(drawableWidth, drawableHeight) / Math.min(drawableWidth, drawableHeight);
+ const isNearlySquare = aspectRatio <= 1.2; // Allow some tolerance for nearly square shapes
+ const isCircle = isNearlySquare && actualRadius >= maxPossibleRadius * 0.95;
+ let pathLength;
+ let rectPath;
+ if (isCircle) {
+ // ✅ Circle: perimeter = 2πr
+ pathLength = 2 * Math.PI * actualRadius;
+
+ // ✅ Circle path centered in the drawable area
+ const centerX = margin + drawableWidth / 2;
+ const centerY = margin + drawableHeight / 2;
+ rectPath = `
+ M ${centerX + actualRadius},${centerY}
+ A ${actualRadius},${actualRadius} 0 1 1 ${centerX - actualRadius},${centerY}
+ A ${actualRadius},${actualRadius} 0 1 1 ${centerX + actualRadius},${centerY}
+ `;
+ } else {
+ // ✅ Rectangle: calculate perimeter properly
+ const straightEdges = 2 * (drawableWidth - 2 * actualRadius) + 2 * (drawableHeight - 2 * actualRadius);
+ const cornerArcs = actualRadius > 0 ? 2 * Math.PI * actualRadius : 0;
+ pathLength = straightEdges + cornerArcs;
+ rectPath = `
+ M ${margin + actualRadius},${margin}
+ L ${margin + drawableWidth - actualRadius},${margin}
+ A ${actualRadius},${actualRadius} 0 0 1 ${margin + drawableWidth},${margin + actualRadius}
+ L ${margin + drawableWidth},${margin + drawableHeight - actualRadius}
+ A ${actualRadius},${actualRadius} 0 0 1 ${margin + drawableWidth - actualRadius},${margin + drawableHeight}
+ L ${margin + actualRadius},${margin + drawableHeight}
+ A ${actualRadius},${actualRadius} 0 0 1 ${margin},${margin + drawableHeight - actualRadius}
+ L ${margin},${margin + actualRadius}
+ A ${actualRadius},${actualRadius} 0 0 1 ${margin + actualRadius},${margin}
+ `;
}
- // Phase 6: Calculate depths for all patterns
- for (const routePattern of routePatternSet) {
- calculatePatternDepth(routePattern);
+
+ // Fixed segment size in pixels
+ const maxSegmentSize = 40;
+ const segmentLength = Math.min(maxSegmentSize, pathLength * 0.25);
+ const gapLength = pathLength - segmentLength;
+
+ // Vitesse constante en pixels par seconde
+ // The connection this one is paced by: whatever it was told, otherwise the
+ // real one. A caller forcing it is showing what a speed looks like (see the
+ // loading indicator demo), not reacting to the network.
+ const networkSpeedCurrent = useNetworkSpeed();
+ const networkSpeed = networkSpeedForced ?? networkSpeedCurrent;
+ const pixelsPerSecond = {
+ "slow-2g": 40,
+ "2g": 60,
+ "3g": 80,
+ "4g": 120
+ }[networkSpeed] || 80;
+ const animationDuration = Math.max(1.5, pathLength / pixelsPerSecond);
+
+ // ✅ Calculate correct offset based on actual segment size
+ const segmentRatio = segmentLength / pathLength;
+ const circleOffset = -animationDuration * segmentRatio;
+ // The dash and the dot are two animations that must stay in phase — the dot
+ // is the head of the dash. SMIL keeps running when its dur is edited, so
+ // changing the speed (or the path) re-times one and leaves the other where it
+ // was, and the dot detaches from the segment. Keyed on what defines their
+ // timing, both are recreated together and start on the same beat.
+ const animationKey = `${animationDuration}-${Math.round(pathLength)}`;
+ return jsxs("svg", {
+ width: "100%",
+ height: "100%",
+ viewBox: `0 0 ${width} ${height}`,
+ preserveAspectRatio: "none",
+ style: "overflow: visible",
+ xmlns: "http://www.w3.org/2000/svg",
+ "shape-rendering": "geometricPrecision",
+ "data-radius": radius,
+ children: [isCircle ? jsx("circle", {
+ cx: margin + drawableWidth / 2,
+ cy: margin + drawableHeight / 2,
+ r: actualRadius,
+ fill: "none",
+ stroke: trailColor,
+ strokeWidth: strokeWidth
+ }) : jsx("rect", {
+ x: margin,
+ y: margin,
+ width: drawableWidth,
+ height: drawableHeight,
+ fill: "none",
+ stroke: trailColor,
+ strokeWidth: strokeWidth,
+ rx: actualRadius
+ }), jsx("path", {
+ d: rectPath,
+ fill: "none",
+ stroke: color,
+ strokeWidth: strokeWidth,
+ strokeLinecap: "round",
+ strokeDasharray: `${segmentLength} ${gapLength}`,
+ pathLength: pathLength,
+ children: jsx("animate", {
+ attributeName: "stroke-dashoffset",
+ from: pathLength,
+ to: "0",
+ dur: `${animationDuration}s`,
+ repeatCount: "indefinite",
+ begin: "0s"
+ }, animationKey)
+ }), jsx("circle", {
+ r: strokeWidth,
+ fill: color,
+ children: jsx("animateMotion", {
+ path: rectPath,
+ dur: `${animationDuration}s`,
+ repeatCount: "indefinite",
+ rotate: "auto",
+ begin: `${circleOffset}s`
+ }, animationKey)
+ })]
+ });
+};
+
+installImportMetaCssBuild(import.meta);const css$W = /* css */`
+ .navi_loading_outline_wrapper {
+ position: absolute;
+ /* Controls place the outline slightly outside their box, right on top of
+ their border. Inside something that scrolls that bleed is enough to make
+ the area scrollable, so such a container sets --loading-outline-min-inset
+ to 0px to keep the outline within the control: a scrollbar appearing
+ just because something started loading is worse than an outline drawn a
+ couple pixels inward. The var is only ever read here (never set on this
+ element) so it keeps inheriting from whichever container declared it. */
+ top: max(
+ var(--loading-outline-min-inset, -100vh),
+ var(--loading-rectangle-top, 0px)
+ );
+ right: max(
+ var(--loading-outline-min-inset, -100vh),
+ var(--loading-rectangle-right, 0px)
+ );
+ bottom: max(
+ var(--loading-outline-min-inset, -100vh),
+ var(--loading-rectangle-bottom, 0px)
+ );
+ left: max(
+ var(--loading-outline-min-inset, -100vh),
+ var(--loading-rectangle-left, 0px)
+ );
+ z-index: 1;
+ border-radius: inherit;
+ pointer-events: none;
+
+ &[hidden] {
+ display: block;
+ opacity: 0;
+ }
}
- if (DEBUG$2) {
- console.debug("Pattern registry updated");
+`;
+const LoadingOutline = props => {
+ import.meta.css = [css$W, "@jsenv/navi/src/graphic/loading/loading_outline.jsx"];
+ if (props.containerRef) {
+ const container = props.containerRef.current;
+ if (!container) {
+ return props.children;
+ }
+ return createPortal(jsx(LoadingOutlineWithPortal, {
+ container: container,
+ ...props,
+ containerRef: undefined
+ }), container);
}
+ return jsx(LoadingOutlineUI, {
+ ...props
+ });
};
-// Store the most specific parent (closest parent in hierarchy)
-const getPathSegmentCount = (pattern) => {
- // Only count path segments, not query parameters
- const pathPart = pattern.split("?")[0];
- return pathPart.split("/").filter(Boolean).length;
-};
-const calculatePatternDepth = (patternObj) => {
- if (patternObj.depth !== 0) {
- return patternObj.depth; // Already calculated
+const LoadingOutlineUI = props => {
+ const {
+ loading,
+ debounce = 300,
+ targetSelector,
+ color,
+ borderWidth = 0,
+ radius,
+ spacingTop = 0,
+ spacingRight = 0,
+ spacingBottom = 0,
+ spacingLeft = 0,
+ marginTop = 0,
+ marginRight = 0,
+ marginBottom = 0,
+ marginLeft = 0,
+ paddingTop = 0,
+ paddingRight = 0,
+ paddingBottom = 0,
+ paddingLeft = 0,
+ inset = 0,
+ children
+ } = props;
+ const shouldShowSpinner = useDebounceTrue(loading, debounce);
+ const rectangleRef = useRef(null);
+ let insetTop = inset + spacingTop + marginTop;
+ let insetRight = inset + spacingRight + marginRight;
+ let insetBottom = inset + spacingBottom + marginBottom;
+ let insetLeft = inset + spacingLeft + marginLeft;
+ if (targetSelector) {
+ // oversimplification that actually works
+ // (simplified because it assumes the targeted element is a direct child of the contained element which may have padding)
+ insetTop += paddingTop;
+ insetRight += paddingBottom;
+ insetBottom += paddingRight;
+ insetLeft += paddingLeft;
}
+ const maxBorderWidth = Math.max(borderWidth);
+ const halfMaxBorderSize = maxBorderWidth / 2;
+ const size = halfMaxBorderSize < 2 ? 2 : halfMaxBorderSize;
+ const lineHalfSize = size / 2;
+ insetTop -= lineHalfSize;
+ insetRight -= lineHalfSize;
+ insetBottom -= lineHalfSize;
+ insetLeft -= lineHalfSize;
+ return jsxs(Fragment$1, {
+ children: [jsx("span", {
+ ref: rectangleRef,
+ className: "navi_loading_outline_wrapper",
+ style: {
+ "--loading-rectangle-top": `${insetTop}px`,
+ "--loading-rectangle-right": `${insetRight}px`,
+ "--loading-rectangle-bottom": `${insetBottom}px`,
+ "--loading-rectangle-left": `${insetLeft}px`
+ },
+ children: loading && jsx(LoadingIndicatorFluid, {
+ visuallyHidden: !shouldShowSpinner,
+ radius: radius,
+ color: color,
+ size: size
+ })
+ }), children]
+ });
+};
- if (!patternObj.parent) {
- patternObj.depth = 0;
- return 0;
+// Not actually used anymore.
+// Now all UI have a common wrapper that can be used to display the loading indicator without needing a container portal.
+const LoadingOutlineWithPortal = props => {
+ const {
+ container,
+ loading,
+ color,
+ inset = 0,
+ radius,
+ spacingTop = 0,
+ spacingRight = 0,
+ spacingBottom = 0,
+ spacingLeft = 0,
+ children
+ } = props;
+ const shouldShowSpinner = useDebounceTrue(loading, 300);
+ if (!shouldShowSpinner) {
+ return children;
+ }
+ container.style.position = "relative";
+ let insetTop = inset + spacingTop;
+ let insetRight = inset + spacingRight;
+ let insetBottom = inset + spacingBottom;
+ let insetLeft = inset + spacingLeft;
+ if (container.nodeName === "DETAILS") {
+ insetTop += container.querySelector("summary").offsetHeight;
}
+ return jsxs(Fragment$1, {
+ children: [jsx("div", {
+ className: "navi_loading_outline_wrapper",
+ style: {
+ "--loading-rectangle-top": `${insetTop}px`,
+ "--loading-rectangle-right": `${insetRight}px`,
+ "--loading-rectangle-bottom": `${insetBottom}px`,
+ "--loading-rectangle-left": `${insetLeft}px`
+ },
+ children: shouldShowSpinner && jsx(LoadingIndicatorFluid, {
+ color: color,
+ radius: radius
+ })
+ }), children]
+ });
+};
- const parentDepth = calculatePatternDepth(patternObj.parent);
- patternObj.depth = parentDepth + 1;
- return patternObj.depth;
+const documentUrlSignal = signal(
+ typeof window === "undefined" ? "http://localhost" : window.location.href,
+);
+const useDocumentUrl = () => {
+ return documentUrlSignal.value;
+};
+const updateDocumentUrl = (value) => {
+ documentUrlSignal.value = value;
};
-const resolveRouteUrl = (relativeUrl) => {
- if (relativeUrl[0] === "/") {
- // we remove the leading slash because we want to resolve against baseUrl which may
- // not be the root url
- relativeUrl = relativeUrl.slice(1);
+const documentResourceSignal = computed(() => {
+ const documentUrl = documentUrlSignal.value;
+ const documentResource = urlToResource(documentUrl);
+ return documentResource;
+});
+const useDocumentResource = () => {
+ return documentResourceSignal.value;
+};
+const urlToResource = (url) => {
+ const scheme = urlToScheme(url);
+ if (scheme === "file") {
+ const urlAsStringWithoutFileProtocol = String(url).slice("file://".length);
+ return urlAsStringWithoutFileProtocol;
+ }
+ if (scheme === "https" || scheme === "http") {
+ // remove origin
+ const afterProtocol = String(url).slice(scheme.length + "://".length);
+ const pathnameSlashIndex = afterProtocol.indexOf("/", "://".length);
+ const urlAsStringWithoutOrigin = afterProtocol.slice(pathnameSlashIndex);
+ return urlAsStringWithoutOrigin;
}
-
- // we don't use URL constructor on PURPOSE (in case the relativeUrl contains invalid url chars)
- // and we want to support use cases where people WANT to produce invalid urls (for example rawUrlPart with spaces)
- // because these urls will be handled by non standard clients (like a backend service allowing url like stuff)
- if (baseUrl.endsWith("/")) {
- return `${baseUrl}${relativeUrl}`;
+ const urlAsStringWithoutProtocol = String(url).slice(scheme.length + 1);
+ return urlAsStringWithoutProtocol;
+};
+const urlToScheme = (url) => {
+ const urlString = String(url);
+ const colonIndex = urlString.indexOf(":");
+ if (colonIndex === -1) {
+ return "";
}
- return `${baseUrl}/${relativeUrl}`;
+ const scheme = urlString.slice(0, colonIndex);
+ return scheme;
};
-/**
- * Route management with pattern-first architecture
- * Routes work with relative URLs, patterns handle base URL resolution
- */
-
+const getHrefTargetInfo = (href) => {
+ href = String(href);
-const routePrivatePropertiesMap = new WeakMap();
-const getRoutePrivateProperties = (route) => {
- return routePrivatePropertiesMap.get(route);
-};
-const ROUTE_NOT_MATCHING_PARAMS = {};
-// Flag to prevent signal-to-URL synchronization during URL-to-signal synchronization
-let isUpdatingRoutesFromUrl = false;
-const route = (pattern, { searchParams } = {}) => {
- const routePattern = createRoutePattern(pattern, { searchParams });
- const { cleanPattern } = routePattern;
- const [publishStatus, subscribeStatus] = createPubSub();
+ if (!href || href.trim() === "") {
+ return {
+ isEmpty: true,
+ isCurrent: false,
+ isAnchor: false,
+ isSameOrigin: true,
+ isSameSite: true,
+ };
+ }
- // prepare route object
- const route = {
- urlPattern: cleanPattern,
- pattern: cleanPattern,
- isRoute: true,
- setupCalled: false,
- matching: false,
- params: ROUTE_NOT_MATCHING_PARAMS,
- buildUrl: null,
- relativeUrl: null,
- url: null,
- matchingSignal: signal(false),
- rawParamsSignal: signal(ROUTE_NOT_MATCHING_PARAMS),
- visited: false,
- visitedSignal: signal(false),
- paramsSignal: null,
- urlSignal: null,
- replaceParams: undefined,
- buildRelativeUrl: undefined,
- relativeUrlSignal: null,
- matchesParams: undefined,
- navTo: undefined,
- redirectTo: undefined,
- subscribeStatus,
- toString: () => {
- return `route "${cleanPattern}"`;
- },
- };
- Object.preventExtensions(route);
+ const currentUrl = new URL(window.location.href);
+ const targetUrl = new URL(href, window.location.href);
- // route private props
- const cleanupCallbackSet = new Set();
- const setupCallbackSet = new Set();
- const registerSetup = (callback) => {
- setupCallbackSet.add(callback);
- };
+ let isCurrent = false;
{
- const routePrivateProperties = {
- routePattern,
- setup: null,
- updateStatus: null,
- cleanup: null,
- };
- routePrivatePropertiesMap.set(route, routePrivateProperties);
- routePrivateProperties.cleanup = () => {
- for (const cleanupCallback of cleanupCallbackSet) {
- cleanupCallback();
- }
- cleanupCallbackSet.clear();
- };
- routePrivateProperties.updateStatus = ({ matching, params, visited }) => {
- let someChange = false;
- route.matchingSignal.value = matching;
-
- if (route.matching !== matching) {
- route.matching = matching;
- someChange = true;
- }
- route.visitedSignal.value = visited;
- if (route.visited !== visited) {
- route.visited = visited;
- someChange = true;
- }
- // Store raw params (from URL) - paramsSignal will reactively compute merged params
- route.rawParamsSignal.value = params;
- // Get merged params for comparison (computed signal will handle the merging)
- const mergedParams = route.paramsSignal.value;
- if (route.params !== mergedParams) {
- route.params = mergedParams;
- someChange = true;
- }
- if (!someChange) {
- return false;
- }
- publishStatus({
- matching,
- params: mergedParams,
- visited,
- });
- return true;
- };
- // (for now data contains only { routeSet })
- routePrivateProperties.setup = (data) => {
- for (const setupCallback of setupCallbackSet) {
- const returnValue = setupCallback(data);
- if (typeof returnValue === "function") {
- cleanupCallbackSet.add(returnValue);
- }
- }
- setupCallbackSet.clear();
- };
+ isCurrent = currentUrl.href === targetUrl.href;
}
-
- registerSetup(() => {
- route.setupCalled = true;
- });
- // methods
- registerSetup(({ routeSet, getUrl }) => {
- route.buildRelativeUrl = (params) => {
- // buildMostPreciseUrl now handles parameter resolution internally
- return routePattern.buildMostPreciseUrl(params);
- };
- route.buildUrl = (params) => {
- const routeRelativeUrl = route.buildRelativeUrl(params);
- const routeUrl = resolveRouteUrl(routeRelativeUrl);
- return routeUrl;
- };
- route.navTo = (params) => {
- if (!integration) {
- return Promise.resolve();
- }
- const routeUrl = route.buildUrl(params);
- return integration.navTo(routeUrl);
- };
- route.redirectTo = (params, { callReason } = {}) => {
- if (!integration) {
- return Promise.resolve();
- }
- const routeUrl = route.buildUrl(params);
- return integration.navTo(routeUrl, {
- replace: true,
- callReason,
- });
+ let isAnchor = false;
+ {
+ if (
+ currentUrl.pathname === targetUrl.pathname &&
+ currentUrl.search === targetUrl.search &&
+ targetUrl.hash !== ""
+ ) {
+ isAnchor = true;
+ }
+ }
+ let isSameOrigin = false;
+ {
+ const currentOrigin = currentUrl.origin;
+ const targetOrigin = targetUrl.origin;
+ isSameOrigin = currentOrigin === targetOrigin;
+ }
+ let isSameSite = false;
+ {
+ const baseDomain = (hostname) => {
+ const parts = hostname.split(".").slice(-2);
+ return parts.join(".");
};
- route.replaceParams = (newParams, { callReason, isSignalChange } = {}) => {
- const matching = route.matchingSignal.peek();
- if (!matching) {
- console.warn(
- `Cannot replace params on route ${route} because it is not matching the current URL.`,
- );
- return null;
- }
+ const currentDomain = baseDomain(currentUrl.hostname);
+ const targetDomain = baseDomain(targetUrl.hostname);
+ isSameSite = currentDomain === targetDomain;
+ }
- // Find all matching routes and update their actions, then delegate to most specific (deeper = more specific)
- let mostSpecificRoute = route;
- const routePrivateProperties = getRoutePrivateProperties(route);
- let maxDepth = routePrivateProperties.routePattern.depth;
- for (const routeCandidate of routeSet) {
- if (routeCandidate === route) {
- continue;
- }
- if (!routeCandidate.matching) {
- continue;
- }
- const matchingRoute = routeCandidate;
- const matchingRoutePrivateProperties =
- getRoutePrivateProperties(matchingRoute);
- const depth = matchingRoutePrivateProperties.routePattern.depth;
- if (depth > maxDepth) {
- maxDepth = depth;
- mostSpecificRoute = matchingRoute;
- }
- }
- const isMostSpecificRoute = mostSpecificRoute === route;
+ return {
+ isEmpty: false,
+ isCurrent,
+ isAnchor,
+ isSameOrigin,
+ isSameSite,
+ };
+};
- // If we found a more specific route, delegate to it; otherwise handle it ourselves
- if (!isMostSpecificRoute) {
- // For signal-originated calls, only skip delegation if the more specific route
- // has its own signal connection for the same params — meaning its own effect will
- // fire and handle the redirect. If it doesn't have the connection, the signal
- // change would be silently dropped, so we must delegate anyway.
- if (isSignalChange) {
- const mostSpecificRoutePrivateProperties =
- getRoutePrivateProperties(mostSpecificRoute);
- const { pathConnectionMap, queryConnectionMap } =
- mostSpecificRoutePrivateProperties.routePattern;
- const willHandleItself = Object.keys(newParams).every(
- (paramName) =>
- pathConnectionMap.has(paramName) ||
- queryConnectionMap.has(paramName),
- );
- if (willHandleItself) {
- return null;
- }
+const useInitialTextSelection = (ref, textSelection) => {
+ const deps = [];
+ if (Array.isArray(textSelection)) {
+ deps.push(...textSelection);
+ } else {
+ deps.push(textSelection);
+ }
+ useLayoutEffect(() => {
+ const el = ref.current;
+ if (!el || !textSelection) {
+ return;
+ }
+ const range = document.createRange();
+ const selection = window.getSelection();
+ if (Array.isArray(textSelection)) {
+ if (textSelection.length === 2) {
+ const [start, end] = textSelection;
+ if (typeof start === "number" && typeof end === "number") {
+ // Format: [0, 10] - character indices
+ selectByCharacterIndices(el, range, start, end);
+ } else if (typeof start === "string" && typeof end === "string") {
+ // Format: ["Click on the", "button to return"] - text strings
+ selectByTextStrings(el, range, start, end);
}
- return mostSpecificRoute.redirectTo(newParams, {
- callReason: `replaceParams delegation from ${route} to ${mostSpecificRoute} (original reason: ${callReason})`,
- });
- }
-
- // This route is the most specific — compute the target URL.
- // buildUrlPreservingPath handles the catch-all case where this trailing-slash
- // route matched a path it cannot represent (e.g. "/" on "/404") without
- // corrupting the current URL. Ancestor optimisation is trusted as-is.
- if (!integration) {
- return Promise.resolve();
- }
- const targetUrl = routePattern.buildUrlPreservingPath(
- getUrl(),
- newParams,
- );
- return integration.navTo(targetUrl, {
- replace: true,
- callReason,
- });
- };
- route.matchesParams = (providedParams) => {
- const currentParams = route.params;
- const resolvedParams = routePattern.resolveParams({
- ...currentParams,
- ...providedParams,
- });
- const same = compareTwoJsValues(currentParams, resolvedParams);
- return same;
- };
- });
- // relativeUrl/url
- registerSetup(() => {
- route.relativeUrlSignal = computed(() => {
- const rawParams = route.rawParamsSignal.value;
- const relativeUrl = route.buildRelativeUrl(rawParams);
- return relativeUrl;
- });
- route.urlSignal = computed(() => {
- const routeUrl = route.buildUrl();
- return routeUrl;
- });
- const cleanupRelativeUrlSignalEffect = effect(() => {
- const routeRelativeUrl = route.relativeUrlSignal.value;
- route.relativeUrl = routeRelativeUrl;
- });
- const cleanupUrlSignalEffect = effect(() => {
- const routeUrl = route.urlSignal.value;
- route.url = routeUrl;
- });
- return () => {
- cleanupRelativeUrlSignalEffect();
- cleanupUrlSignalEffect();
- };
- });
- // params
- registerSetup(() => {
- route.paramsSignal = computed(() => {
- const rawParams = route.rawParamsSignal.value;
- const resolvedParams = routePattern.resolveParams(rawParams);
- return resolvedParams;
- });
-
- // Keep route.params synchronized with paramsSignal
- // Doing this with the signal instead of in the updateStatus function ensures route.params includes parameters from child routes
- const cleanupParamsSignalEffect = effect(() => {
- const params = route.paramsSignal.value;
- if (route.params !== params) {
- route.params = params;
- }
- });
-
- return () => {
- cleanupParamsSignalEffect();
- };
- });
- // Signal -> URL sync: When signal changes, update URL to reflect meaningful state
- // Only sync non-default values to keep URLs clean (static fallbacks stay invisible)
- registerSetup(() => {
- const cleanupSignalUrlEffectSet = new Set();
- const { pathConnectionMap, queryConnectionMap } = routePattern;
- // important: keep this connectionMap after setup so that connectionMap correctly inherits parent pattern signals
- const connectionMap = new Map([
- ...pathConnectionMap,
- ...queryConnectionMap,
- ]);
- for (const [paramName, connection] of connectionMap) {
- const { signal: paramSignal, debug } = connection;
- if (debug) {
- console.debug(
- `[route] connecting url param "${paramName}" to signal`,
- paramSignal,
- );
}
- // eslint-disable-next-line no-loop-func
- const cleanupSignalUrlEffect = effect(() => {
- const value = paramSignal.value;
- // Use peek() to avoid subscribing to URL-derived signals.
- // This effect should only re-run when the param signal changes,
- // not when the URL changes (which would create a cycle: signal→URL→signal).
- const rawParams = route.rawParamsSignal.peek();
- const urlParamValue = rawParams[paramName];
- const matching = route.matchingSignal.peek();
-
- // Signal returned to default - clean up URL by removing the parameter
- // Skip cleanup during URL-to-signal synchronization to prevent recursion
- if (isUpdatingRoutesFromUrl) {
- return;
- }
-
- if (!matching) {
- // Route not matching, no URL sync needed
- return;
- }
- if (urlParamValue === undefined) {
- // No URL parameter exists - check if signal has meaningful value to add
- if (connection.isDefaultValue(value)) {
- // Signal using default value, keep URL clean (no parameter needed)
- return;
- }
- if (debug) {
- console.debug(
- `[route] Signal->URL: ${paramName} adding custom value ${value} to URL (default: ${connection.getDefaultValue()})`,
- );
- }
- route.replaceParams(
- { [paramName]: value },
- {
- callReason: `${paramName} signal change on ${route}`,
- isSignalChange: true,
- },
- );
- return;
- }
-
- // URL parameter exists - check if we need to update or clean it up
- if (connection.isDefaultValue(value)) {
- if (debug) {
- console.debug(
- `[route] Signal->URL: ${paramName} cleaning URL (removing default value ${value})`,
- );
- }
- route.replaceParams(
- { [paramName]: undefined },
- {
- callReason: `${paramName} signal reset to default on ${route}`,
- isSignalChange: true,
- },
- );
- return;
- }
+ } else if (typeof textSelection === "string") {
+ // Format: "some text" - select the entire string occurrence
+ selectSingleTextString(el, range, textSelection);
+ }
+ selection.removeAllRanges();
+ selection.addRange(range);
+ }, deps);
+};
+const selectByCharacterIndices = (element, range, startIndex, endIndex) => {
+ const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, null, false);
+ let currentIndex = 0;
+ let startNode = null;
+ let startOffset = 0;
+ let endNode = null;
+ let endOffset = 0;
+ while (walker.nextNode()) {
+ const textContent = walker.currentNode.textContent;
+ const nodeLength = textContent.length;
- if (compareTwoJsValues(value, urlParamValue)) {
- // Values already match, no sync needed
- return;
- }
- if (debug) {
- console.debug(
- `[route] Signal->URL: ${paramName} updating URL ${urlParamValue} -> ${value}`,
- );
- }
- route.replaceParams(
- { [paramName]: value },
- {
- callReason: `${paramName} signal change on ${route}`,
- isSignalChange: true,
- },
- );
- });
- cleanupSignalUrlEffectSet.add(cleanupSignalUrlEffect);
+ // Check if start position is in this text node
+ if (!startNode && currentIndex + nodeLength > startIndex) {
+ startNode = walker.currentNode;
+ startOffset = startIndex - currentIndex;
}
- return () => {
- for (const cleanupSignalUrlEffect of cleanupSignalUrlEffectSet) {
- cleanupSignalUrlEffect();
- }
- };
- });
- return route;
+ // Check if end position is in this text node
+ if (currentIndex + nodeLength >= endIndex) {
+ endNode = walker.currentNode;
+ endOffset = endIndex - currentIndex;
+ break;
+ }
+ currentIndex += nodeLength;
+ }
+ if (startNode && endNode) {
+ range.setStart(startNode, startOffset);
+ range.setEnd(endNode, endOffset);
+ }
+};
+const selectSingleTextString = (element, range, text) => {
+ const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, null, false);
+ while (walker.nextNode()) {
+ const textContent = walker.currentNode.textContent;
+ const index = textContent.indexOf(text);
+ if (index !== -1) {
+ range.setStart(walker.currentNode, index);
+ range.setEnd(walker.currentNode, index + text.length);
+ return;
+ }
+ }
+};
+const selectByTextStrings = (element, range, startText, endText) => {
+ const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, null, false);
+ let startNode = null;
+ let endNode = null;
+ let foundStart = false;
+ while (walker.nextNode()) {
+ const textContent = walker.currentNode.textContent;
+ if (!foundStart && textContent.includes(startText)) {
+ startNode = walker.currentNode;
+ foundStart = true;
+ }
+ if (foundStart && textContent.includes(endText)) {
+ endNode = walker.currentNode;
+ break;
+ }
+ }
+ if (startNode && endNode) {
+ const startOffset = startNode.textContent.indexOf(startText);
+ const endOffset = endNode.textContent.indexOf(endText) + endText.length;
+ range.setStart(startNode, startOffset);
+ range.setEnd(endNode, endOffset);
+ }
};
-const [publishRouteMutations, observeRouteMutations] = createPubSub();
+installImportMetaCssBuild(import.meta);// https://jsfiddle.net/v5xzJ/4/
+const css$V = /* css */`
+ @layer navi {
+ .navi_text {
+ &[data-skeleton] {
+ border-radius: 0.2em;
+ }
-let setupRoutesCalled = false;
-const setupRoutes = (routes) => {
- if (setupRoutesCalled) {
- throw new Error(
- `There is an active set of routes already.
-Some code called setupRoutes before and did not properly cleanup routes with clearRoutes().
-This prevents cross-test pollution and ensures clean state.`,
- );
- }
- setupRoutesCalled = true;
+ &[data-capitalize] {
+ text-transform: capitalize;
- const routeSet = new Set();
- let currentUrl = null;
- const getUrl = () => currentUrl;
- // PHASE 1: Setup patterns with unified objects (includes all relationships and signal connections)
- const routePatterns = [];
- for (const route of routes) {
- const { routePattern } = getRoutePrivateProperties(route);
- routePatterns.push(routePattern);
- routeSet.add(route);
+ .navi_text_sizer {
+ .navi_text {
+ display: inline-block; /* We need inline-block to match the pseudo element */
+ }
+ }
+ }
+ &[data-shrinkwrap] {
+ display: inline-block;
+ }
+ }
}
- setupRoutePatterns(routePatterns);
- // Setup routes now that patterns are correctly initialized
- for (const route of routeSet) {
- const { setup } = getRoutePrivateProperties(route);
- setup({ routeSet, getUrl });
+ time.navi_text {
+ font-variant-numeric: tabular-nums;
}
- // Store previous route states to detect changes
- const routePreviousStateMap = new WeakMap();
- const updateRoutes = (
- url,
- {
- isVisited = () => false,
- // state
- } = {},
- ) => {
- currentUrl = url;
- const returnValue = {};
- const routeMatchInfoSet = new Set();
- for (const route of routeSet) {
- const routePrivateProperties = getRoutePrivateProperties(route);
- const { routePattern } = routePrivateProperties;
+ *[data-navi-space] {
+ }
- const previousState = routePreviousStateMap.get(route) || {
- matching: false,
- params: ROUTE_NOT_MATCHING_PARAMS,
- actionParams: ROUTE_NOT_MATCHING_PARAMS,
- };
- const oldMatching = previousState.matching;
- const oldParams = previousState.params;
- const oldActionParams = previousState.actionParams;
+ .navi_text {
+ position: relative;
- let extractedParams = routePattern.applyOn(url);
- let newMatching = Boolean(extractedParams);
- let newParams;
- if (extractedParams) {
- if (compareTwoJsValues(oldParams, extractedParams)) {
- // No change in parameters, keep the old params
- newParams = oldParams;
- } else {
- newParams = extractedParams;
- }
- } else {
- newParams = ROUTE_NOT_MATCHING_PARAMS;
+ /* There is a chrome specific bug that prevents text-transform: capitalize to be applied in nested DOM structure */
+ /* The CSS below ensure capitalize is propagated to the bold clones */
+ &[data-capitalize] {
+ &::first-letter {
+ text-transform: uppercase;
+ }
+ .navi_text_sizer_placeholder::first-letter {
+ text-transform: uppercase;
+ }
+ .navi_text_sizer_overlay::first-letter {
+ text-transform: uppercase;
}
+ }
- const routeMatchInfo = {
- route,
- routePrivateProperties,
- oldMatching,
- newMatching,
- oldParams,
- newParams,
- oldActionParams,
- };
- routeMatchInfoSet.add(routeMatchInfo);
- // Store current state for next comparison
- routePreviousStateMap.set(route, {
- matching: newMatching,
- params: newParams,
- actionParams: oldActionParams, // updated to newActionParams in update_route_actions
- });
+ .navi_text_sizer,
+ .navi_text_sizer_placeholder,
+ .navi_text_sizer_overlay {
+ display: inherit;
+ width: inherit;
+ min-width: inherit;
+ height: inherit;
+ min-height: inherit;
+ flex-grow: inherit;
+ align-items: inherit;
+ align-self: inherit;
+ justify-content: inherit;
+ gap: inherit;
+ text-align: inherit;
+ border-radius: inherit;
}
- {
- // URL -> Signal synchronization (moved from individual route effects to eliminate circular dependency)
- // Prevent signal-to-URL synchronization during URL-to-signal synchronization
- isUpdatingRoutesFromUrl = true;
- // Apply all signal updates in a batch
- const matchingRouteSet = new Set();
- const routeUpdateSet = new Set();
- batch(() => {
- for (const {
- route,
- routePrivateProperties,
- newMatching,
- newParams,
- } of routeMatchInfoSet) {
- const { updateStatus } = routePrivateProperties;
- const visited = isVisited(route.url);
- const updated = updateStatus({
- matching: newMatching,
- params: newParams,
- visited,
- });
- if (updated) {
- routeUpdateSet.add(route);
- }
- if (newMatching) {
- matchingRouteSet.add(route);
- }
- }
+ &[data-text-overflow] {
+ display: block;
+ min-width: 0;
+ text-overflow: ellipsis;
+ overflow: hidden;
+ overflow-wrap: normal;
+ }
- for (const {
- route,
- routePrivateProperties,
- newMatching,
- } of routeMatchInfoSet) {
- const { routePattern } = routePrivateProperties;
- const { pathConnectionMap, queryConnectionMap } = routePattern;
- const connectionMap = new Map([
- ...pathConnectionMap,
- ...queryConnectionMap,
- ]);
+ &[data-skeleton] {
+ max-width: 100%;
+ /* Children stay in the DOM to preserve natural layout dimensions,
+ but are hidden so only the skeleton is visible. */
+ visibility: hidden;
- for (const [paramName, connection] of connectionMap) {
- const { signal: paramSignal, debug } = connection;
- const rawParams = route.rawParamsSignal.value;
- const urlParamValue = rawParams[paramName];
+ /* When there are no children a placeholder "W" is injected (see JSX).
+ It must stretch to the full available width so the skeleton
+ fills the container rather than collapsing to a single character. */
+ .navi_text_skeleton_children_placeholder {
+ display: inline-flex;
+ width: 100%;
+ }
- if (!newMatching) {
- // Route doesn't match - check if any matching route extracts this parameter
- let parameterExtractedByMatchingRoute = false;
- let matchingRouteInSameFamily = false;
+ /* Three-level structure to respect padding AND border-radius:
- for (const otherRoute of routeSet) {
- if (otherRoute === route || !otherRoute.matching) {
- continue;
- }
- const otherRawParams = otherRoute.rawParamsSignal.value;
- const otherRoutePrivateProperties =
- getRoutePrivateProperties(otherRoute);
+ 1. navi_text_skeleton_container — absolutely fills the border box
+ (inset:0), then applies padding:inherit so its content box equals
+ the parent's content box. line-height:normal prevents the container
+ from inheriting a large line-height that would make it taller than
+ the border box. border-radius:inherit passes the radius down.
+ visibility:visible overrides the parent's visibility:hidden.
- // Check if this matching route extracts the parameter
- if (paramName in otherRawParams) {
- parameterExtractedByMatchingRoute = true;
- }
+ 2. navi_text_skeleton_inset — a relative block that fills 100% of the
+ container's content box (= parent's content box). It is the
+ positioned ancestor for the absolutely placed skeleton bar.
+ border-radius:inherit chains the radius further down.
- // Check if this matching route is in the same family using parent-child relationships
- const thisPatternObj = routePattern;
- const otherPatternObj =
- otherRoutePrivateProperties.routePattern;
+ 3. navi_text_skeleton — the visible gradient bar. position:absolute
+ inset:0 fills the inset box precisely. border-radius:inherit
+ finally applies the radius at this level, which is now correctly
+ sized to the content area. */
+ .navi_text_skeleton_container {
+ position: absolute;
+ inset: 0;
+ padding: inherit;
+ line-height: normal;
+ border-radius: inherit;
+ visibility: visible;
+ }
- // 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;
+ .navi_text_skeleton_inset {
+ position: relative;
+ display: inline-flex;
+ width: 100%;
+ height: 100%;
+ border-radius: inherit;
+ }
- // Check if other route is ancestor of this route
- let currentParent = thisPatternObj.parent;
- while (currentParent) {
- if (currentParent === otherPatternObj) {
- inSameFamily = true;
- break;
- }
- currentParent = currentParent.parent;
- }
+ .navi_text_skeleton {
+ position: absolute;
+ inset: 0;
+ background: linear-gradient(
+ 90deg,
+ #e0e0e0 25%,
+ #f0f0f0 50%,
+ #e0e0e0 75%
+ );
+ background-size: 200% 100%;
+ border-radius: inherit;
+ }
- // 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;
- }
- }
+ &[data-loading] {
+ .navi_text_skeleton {
+ animation: navi_text_skeleton_shimmer 1.5s infinite;
+ }
+ }
+ }
+ }
- // 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;
- }
+ @keyframes navi_text_skeleton_shimmer {
+ 0% {
+ background-position: 200% 0;
+ }
+ 100% {
+ background-position: -200% 0;
+ }
+ }
- currentParent = otherPatternObj.parent;
- while (currentParent) {
- if (thisAncestors.has(currentParent)) {
- inSameFamily = true;
- break;
- }
- currentParent = currentParent.parent;
- }
- }
+ .navi_text_sizer {
+ position: relative;
+ display: inline-block;
- if (inSameFamily) {
- matchingRouteInSameFamily = true;
- }
- }
+ .navi_text_sizer_placeholder {
+ opacity: 0;
+ }
+ .navi_text_sizer_overlay {
+ position: absolute;
+ inset: 0;
+ }
+ }
- // 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)
- // 4. AND parameter is a path segment (not a search param)
- // Search params represent user preferences/choices and must survive
- // navigation away — only path segments are explicitly removed from
- // the URL when the route stops matching.
- if (
- matchingRouteInSameFamily &&
- !parameterExtractedByMatchingRoute &&
- pathConnectionMap.has(paramName)
- ) {
- const defaultValue = connection.getDefaultValue();
- 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`,
- );
- }
- paramSignal.value = undefined;
- } else if (debug) {
- // Parameter has a default value - preserve current signal value
- console.debug(
- `[route] Parameter ${paramName} has default value ${defaultValue}: preserving signal value: ${paramSignal.value}`,
- );
- }
- } else if (debug) {
- if (!matchingRouteInSameFamily) {
- console.debug(
- `[route] Different route family: preserving ${paramName} signal value: ${paramSignal.value}`,
- );
- } else if (queryConnectionMap.has(paramName)) {
- console.debug(
- `[route] Search param ${paramName}: preserving signal value (user choice): ${paramSignal.value}`,
- );
- } else {
- console.debug(
- `[route] Parameter ${paramName} extracted by matching route: preserving signal value: ${paramSignal.value}`,
- );
- }
- }
- continue;
- }
+ .navi_text_bold_background {
+ position: absolute;
+ top: 0;
+ left: 0;
+ color: currentColor;
+ font-weight: normal;
+ background: currentColor;
+ background-clip: text;
+ -webkit-background-clip: text;
+ transform-origin: center;
+ -webkit-text-fill-color: transparent;
+ opacity: 0;
+ }
+ .navi_text[data-contains-absolute-child] {
+ display: inline-block;
+ }
+ .navi_text[data-bold] {
+ .navi_text_bold_background {
+ opacity: 1;
+ }
+ }
+`;
+const REGULAR_SPACE = jsx("span", {
+ "data-navi-space": "",
+ children: " "
+});
+// A space that uses padding-left instead of a real space character.
+// This avoids the underline that browsers draw under spaces inside links.
+const FAKE_SPACE = jsx("span", {
+ "data-navi-space": "",
+ style: "padding-left: 0.25em",
+ children: "\u200B"
+});
+const CustomWidthSpace = ({
+ value,
+ useRealSpaceChar
+}) => {
+ if (useRealSpaceChar) {
+ // Two-span trick: we want a real space character in the DOM so that
+ // copy-pasting the text produces an actual space, but we also want
+ // full control over the visual width of that gap.
+ // - First span: contains the real space but rendered at font-size:0 so it
+ // takes up zero visual space.
+ // - Second span: a zero-width joiner () with padding-left set to
+ // the desired gap size. This is the only visible part.
+ return jsxs("span", {
+ children: [jsx("span", {
+ style: "font-size: 0",
+ children: " "
+ }), jsx("span", {
+ style: `padding-left: ${value}`,
+ children: "\u200B"
+ })]
+ });
+ }
+ return jsx("span", {
+ style: `padding-left: ${value}`,
+ children: "\u200B"
+ });
+};
- // URL -> Signal sync: When route matches, ensure signal matches URL state
- // URL is the source of truth for explicit parameters
- const value = paramSignal.peek();
- if (urlParamValue === undefined) {
- // No URL parameter - reset signal to its current default value
- // (handles both static fallback and dynamic default cases)
- const defaultValue = connection.getDefaultValue();
- if (connection.isDefaultValue(value)) {
- // Signal already has correct default value, no sync needed
- continue;
- }
- if (debug) {
- console.debug(
- `[route] URL->Signal: ${paramName} not in URL, reset signal to default (${defaultValue})`,
- );
- }
- paramSignal.value = defaultValue;
- continue;
- }
- if (compareTwoJsValues(urlParamValue, value)) {
- // Values already match, no sync needed
- continue;
- }
- if (debug) {
- console.debug(
- `[route] URL->Signal: ${paramName}=${urlParamValue} in url, sync signal with url`,
- );
- }
- paramSignal.value = urlParamValue;
- continue;
- }
- }
+// Keeps the last child from being left alone on a line of its own — an icon
+// after a label, a unit after a number. It is an atomic inline, so the browser
+// is free to break the line right before it, and no character can stop that (a
+// word joiner does not suppress a break before an atomic inline). So the last
+// word of what precedes it and the child itself go in one nowrap box instead:
+// the classic widow fix, applied to the one place it is always wrong to break.
+//
+// Only the last word travels with it — wrapping the whole preceding child would
+// stop a long label from wrapping at all.
+const attachLastTextChild = (children, separator) => {
+ const childArray = toChildArray(children);
+ if (childArray.length < 2) {
+ // Nothing to attach it to: on its own it cannot be orphaned.
+ return children;
+ }
+ const lastChild = childArray[childArray.length - 1];
+ const previousChild = childArray[childArray.length - 2];
+ const before = childArray.slice(0, -2);
+ const attach = attached => jsxs("span", {
+ style: "white-space: nowrap",
+ children: [attached, separator, lastChild]
+ }, "attached");
+ if (typeof previousChild !== "string") {
+ return [...before, attach(previousChild)];
+ }
+ const lastWordMatch = /\s+(\S+)$/.exec(previousChild);
+ if (!lastWordMatch) {
+ return [...before, attach(previousChild)];
+ }
+ return [...before, previousChild.slice(0, lastWordMatch.index), attach(lastWordMatch[1])];
+};
+const applySpacingOnTextChildren = (children, spacing, defaultSpace) => {
+ if (spacing === "pre" || spacing === "0" || spacing === 0) {
+ return children;
+ }
+ if (!children) {
+ return children;
+ }
+ const childArray = toChildArray(children);
+ const childCount = childArray.length;
+ if (childCount <= 1) {
+ return children;
+ }
+ const useRealSpaceChar = defaultSpace !== FAKE_SPACE;
+ let separator;
+ if (spacing === REGULAR_SPACE || spacing === FAKE_SPACE) {
+ separator = defaultSpace;
+ } else if (typeof spacing === "string") {
+ if (isSizeSpacingKey(spacing)) {
+ const value = stringifySpacingStyle(spacing);
+ separator = jsx(CustomWidthSpace, {
+ value: value,
+ useRealSpaceChar: useRealSpaceChar
});
- if (routeUpdateSet.size > 0) {
- publishRouteMutations(routeUpdateSet);
- }
- // Reset flag after URL -> Signal synchronization is complete
- isUpdatingRoutesFromUrl = false;
- Object.assign(returnValue, { matchingRouteSet });
+ } else if (hasCSSSizeUnit(spacing) || spacing.startsWith("var(")) {
+ separator = jsx(CustomWidthSpace, {
+ value: spacing,
+ useRealSpaceChar: useRealSpaceChar
+ });
+ } else {
+ separator = spacing;
}
+ } else if (typeof spacing === "number") {
+ separator = jsx(CustomWidthSpace, {
+ value: `${spacing}px`,
+ useRealSpaceChar: useRealSpaceChar
+ });
+ } else {
+ separator = spacing;
+ }
+ const childrenWithGap = [];
+ let i = 0;
+ while (true) {
+ const child = childArray[i];
+ childrenWithGap.push(child);
+ i++;
+ if (i === childCount) {
+ break;
+ }
+ const currentChild = childArray[i - 1];
+ const nextChild = childArray[i];
+ if (!shouldInjectSpacingBetween(currentChild, nextChild)) {
+ continue;
+ }
+ childrenWithGap.push(separator);
+ }
+ return childrenWithGap;
+};
+const outsideTextFlowSet = new Set();
+const markAsOutsideTextFlow = jsxElement => {
+ outsideTextFlowSet.add(jsxElement);
+};
+const isMarkedAsOutsideTextFlow = jsxElement => {
+ return outsideTextFlowSet.has(jsxElement.type);
+};
+const shouldInjectSpacingBetween = (left, right) => {
+ const leftIsNode = isValidElement(left);
+ const rightIsNode = isValidElement(right);
+ // only inject spacing when at least one side is a preact node
+ if (!leftIsNode && !rightIsNode) {
+ return false;
+ }
+ if (leftIsNode && isMarkedAsOutsideTextFlow(left)) {
+ return false;
+ }
+ if (rightIsNode && isMarkedAsOutsideTextFlow(right)) {
+ return false;
+ }
+ // A reveal-on-interaction Link (e.g. the "#" anchor before a title) is
+ // absolutely positioned and takes no room in the flow, so a separator after
+ // it would leave a stray gap at the start of the line.
+ if (leftIsNode && left.props?.revealOnInteraction) {
+ return false;
+ }
+ if (typeof left === "string" && /\s$/.test(left)) {
+ return false;
+ }
+ if (typeof right === "string" && /^\s/.test(right)) {
+ return false;
+ }
+ return true;
+};
- return returnValue;
- };
-
- // notify all routes are now ready (signals are initialized and patterns are set up) so integrations can safely read route state
- // and call updateRoutes
- onAllRouteReady(updateRoutes);
-
- // for unit test purposes code can call updateRoutes and clearRoutes
- const clearRoutes = () => {
- for (const route of routeSet) {
- const routePrivateProperties = getRoutePrivateProperties(route);
- routePrivateProperties.cleanup();
- routePrivatePropertiesMap.delete(route);
+/**
+ * @type {import("ignore:preact").FunctionComponent<{
+ * children?: import("ignore:preact").ComponentChildren,
+ * as?: string,
+ * className?: string,
+ * style?: import("ignore:preact").JSX.CSSProperties,
+ * bold?: boolean,
+ * noWrap?: boolean,
+ * maxLines?: number,
+ * spacing?: string | number | import("ignore:preact").ComponentChildren,
+ * loading?: boolean,
+ * skeleton?: boolean,
+ * preventSpaceUnderlines?: boolean,
+ * holdSpaceForStyle?: import("ignore:preact").JSX.CSSProperties,
+ * boldStable?: boolean,
+ * shrinkWrap?: boolean,
+ * capitalize?: boolean,
+ * selectRange?: string | [number, number],
+ * childrenOutsideFlow?: import("ignore:preact").ComponentChildren,
+ * [key: string]: any,
+ * }>}
+ *
+ * @param {number} [maxLines]
+ * Truncates overflowing text with an ellipsis. `maxLines={1}` produces a
+ * single-line truncation; `maxLines={n}` (n > 1) uses `-webkit-line-clamp`
+ * to allow up to n lines before clipping.
+ *
+ * @param {string|number} [spacing]
+ * Separator injected between child nodes. Accepts a size token (`"s"`, `"m"`, …),
+ * a CSS length string, a number (interpreted as px), or `"pre"` / `0` to
+ * disable spacing entirely. Defaults to a regular space character.
+ *
+ * @param {boolean} [loading]
+ * Renders a shimmer skeleton animation in place of the text content.
+ *
+ * @param {boolean} [skeleton]
+ * Same as `loading` but without the shimmer animation — a static grey bar.
+ *
+ * @param {boolean} [attachLastChild]
+ * Keeps the last child on the same line as the word before it — a trailing
+ * icon, a unit, an arrow. Without it the browser may break the line right
+ * before that child and leave it alone underneath.
+ *
+ * @param {boolean} [preventSpaceUnderlines]
+ * Replaces real space characters between children with padding-based spaces.
+ * Useful inside `` elements where browsers draw an underline under spaces.
+ *
+ * @param {import("ignore:preact").JSX.CSSProperties} [holdSpaceForStyle]
+ * Prevents layout shifts when text styles change (e.g. font-weight, font-size).
+ * Pass the CSS properties representing the "largest" visual state of the text.
+ * An invisible placeholder rendered with those styles reserves the space; the
+ * real visible text is layered on top via `position: absolute`.
+ * Best combined with `noWrap` — does not work reliably on multi-line text.
+ *
+ * @param {boolean} [boldStable]
+ * Alternative to `holdSpaceForStyle` for multi-line text. Keeps a consistent
+ * visual width across bold/normal transitions by painting normal-weight text
+ * over a bold background using `background-clip: text`. Does not handle
+ * font-size changes.
+ *
+ * @param {boolean} [shrinkWrap]
+ * Forces the element width to match its longest visual line, preventing the
+ * text block from being wider than its content when inside a flex/grid container.
+ *
+ * @param {boolean} [capitalize]
+ * Uppercases the first letter of the text content via CSS.
+ *
+ * @param {string|[number,number]} [selectRange]
+ * Selects a portion of the text on mount. Pass a substring to search for, or
+ * a `[start, end]` character-offset tuple.
+ *
+ * @param {import("ignore:preact").ComponentChildren} [childrenOutsideFlow]
+ * Rendered after children but outside the text spacing/flow logic. Used
+ * internally for overlays such as the skeleton container.
+ */
+const Text = props => {
+ const defaultRef = useRef();
+ const ref = props.ref || defaultRef;
+ return jsx(TextDispatcher, {
+ ...props,
+ ref: ref
+ });
+};
+const TextDispatcher = props => {
+ if (props.loading || props.skeleton) {
+ return jsx(TextSkeleton, {
+ ...props
+ });
+ }
+ if (props.shrinkWrap) {
+ return jsx(TextShrinkWrap, {
+ ...props
+ });
+ }
+ if (props.maxLines === 1 || props.maxLines === "1") {
+ return jsx(TextOverflow, {
+ ...props
+ });
+ }
+ if (props.selectRange) {
+ return jsx(TextWithSelectRange, {
+ ...props
+ });
+ }
+ return jsx(TextUI, {
+ ...props
+ });
+};
+const TextShrinkWrap = props => {
+ const {
+ ref
+ } = props;
+ const applyWidth = () => {
+ const text = ref.current;
+ // Reset any previously forced width so we measure the natural size
+ text.style.width = "";
+ const optimalWidth = measureLongestVisualLineWidth(text);
+ if (optimalWidth === null) {
+ return;
}
- routeSet.clear();
- setupRoutesCalled = false;
- };
- return {
- updateRoutes,
- clearRoutes,
+ text.style.width = `${Math.ceil(optimalWidth)}px`;
};
+ useLayoutEffect(() => {
+ const text = ref.current;
+ if (!text) {
+ return;
+ }
+ applyWidth();
+ });
+ useLayoutEffect(() => {
+ // Re-compute whenever the parent resizes (covers cases where the parent
+ // has an independent size constraint, e.g. max-width, flex layout).
+ // We also listen to window resize because when the parent's width is
+ // driven solely by the text itself (no external constraint), the parent
+ // won't change size when the viewport changes — so the ResizeObserver
+ // alone would never fire.
+ const text = ref.current;
+ if (!text) {
+ return undefined;
+ }
+ const parent = text.parentElement;
+ let observer;
+ if (parent) {
+ observer = new ResizeObserver(applyWidth);
+ observer.observe(parent);
+ }
+ window.addEventListener("resize", applyWidth);
+ return () => {
+ observer?.disconnect();
+ window.removeEventListener("resize", applyWidth);
+ };
+ }, []);
+ return jsx(TextDispatcher, {
+ ...props,
+ "data-shrinkwrap": "",
+ shrinkWrap: undefined
+ });
};
-
-const useRouteStatus = (route) => {
- const { urlSignal, matchingSignal, paramsSignal, visitedSignal } = route;
- const url = urlSignal.value;
- const matching = matchingSignal.value;
- const params = paramsSignal.value;
- const visited = visitedSignal.value;
-
- return {
- url,
- matching,
- params,
- visited,
+const TextUI = props => {
+ import.meta.css = [css$V, "@jsenv/navi/src/text/text.jsx"];
+ let {
+ ref,
+ spacing,
+ preventSpaceUnderlines = false,
+ attachLastChild = false,
+ boldStable,
+ holdSpaceForStyle,
+ capitalize,
+ children,
+ childrenOutsideFlow,
+ shrinkWrap,
+ ...rest
+ } = props;
+ const defaultSpace = preventSpaceUnderlines ? FAKE_SPACE : REGULAR_SPACE;
+ const resolvedSpacing = spacing ?? defaultSpace;
+ const boxProps = {
+ "as": "span",
+ "data-capitalize": capitalize ? "" : undefined,
+ "data-shrinkwrap": shrinkWrap ? "" : undefined,
+ ...rest,
+ ref,
+ "baseClassName": withPropsClassName("navi_text", rest.baseClassName)
};
+ if (attachLastChild) {
+ // Before the spacing pass, so the box it makes is one child of it: the gap
+ // between the text and the box is Text's own, the one inside it is written
+ // here (it has to live inside the nowrap box to be unbreakable).
+ children = attachLastTextChild(children, resolvedSpacing === "pre" || resolvedSpacing === 0 || resolvedSpacing === "0" ? null : defaultSpace);
+ }
+ const shouldPreserveSpacing = rest.as === "pre" || rest.flex || rest.grid;
+ if (shouldPreserveSpacing) {
+ boxProps.spacing = resolvedSpacing;
+ } else {
+ children = applySpacingOnTextChildren(children, resolvedSpacing, defaultSpace);
+ }
+ if (boldStable) {
+ const {
+ bold
+ } = boxProps;
+ return jsxs(Box, {
+ ...boxProps,
+ bold: undefined,
+ "data-bold": bold ? "" : undefined,
+ "data-contains-absolute-child": "",
+ children: [jsx("span", {
+ className: "navi_text_bold_background",
+ "aria-hidden": "true",
+ children: children
+ }), children, childrenOutsideFlow]
+ });
+ }
+ if (holdSpaceForStyle) {
+ // The sizer technique prevents layout shifts when styles that affect text dimensions change.
+ // - navi_text_sizer_placeholder: invisible, rendered with holdSpaceForStyle applied so it
+ // always occupies the "maximum" dimensions (e.g. bold + larger font-size).
+ // - navi_text_sizer_overlay: absolutely positioned on top, renders the actual visible text
+ // with its current style. Transitions can be applied on this element from the outside.
+ return jsxs(Box, {
+ ...boxProps,
+ children: [jsxs("span", {
+ className: "navi_text_sizer",
+ children: [jsx("span", {
+ className: "navi_text_sizer_placeholder",
+ "aria-hidden": "true",
+ style: holdSpaceForStyle,
+ children: children
+ }), jsx("span", {
+ className: "navi_text_sizer_overlay",
+ children: children
+ })]
+ }), childrenOutsideFlow]
+ });
+ }
+ return jsxs(Box, {
+ ...boxProps,
+ children: [children, childrenOutsideFlow]
+ });
+};
+const TextSkeleton = ({
+ loading,
+ children,
+ ...props
+}) => {
+ // Three-level structure — see CSS comment on [data-skeleton] for details.
+ const skeletonOverlay = jsx("span", {
+ className: "navi_text_skeleton_container",
+ "aria-hidden": "true",
+ children: jsx("span", {
+ className: "navi_text_skeleton_inset",
+ children: jsx("span", {
+ className: "navi_text_skeleton"
+ })
+ })
+ });
+ // When there are no children, inject a full-width placeholder so the element
+ // has measurable height driven by the current font-size/line-height, and the
+ // skeleton fills the available width instead of shrinking to a single char.
+ const hasChildren = children !== null && children !== undefined && children !== false;
+ const innerChildren = hasChildren ? children : jsx("span", {
+ className: "navi_text_skeleton_children_placeholder",
+ "aria-hidden": "true",
+ children: "W"
+ });
+ return jsx(TextDispatcher, {
+ "data-skeleton": "",
+ "data-loading": loading ? "" : undefined,
+ ...props,
+ skeleton: undefined,
+ childrenOutsideFlow: skeletonOverlay,
+ children: innerChildren
+ });
};
+const TextOverflow = ({
+ noWrap,
+ spacing,
+ capitalize,
+ children,
+ ...rest
+}) => {
+ return jsx(TextDispatcher, {
+ block: true,
+ as: "div",
+ pre: noWrap === undefined ? true : undefined
+ // For paragraph we prefer to keep lines and only hide unbreakable long sections
+ ,
-let integration;
-const setRouteIntegration = (integrationInterface) => {
- integration = integrationInterface;
+ preLine: rest.as === "p" ? true : undefined,
+ noWrap: noWrap,
+ ...rest,
+ maxLines: undefined,
+ "data-text-overflow": "",
+ spacing: spacing,
+ capitalize: capitalize,
+ children: children
+ });
};
-let onAllRouteReady = () => {};
-const setOnAllRouteReady = (callback) => {
- onAllRouteReady = callback;
+const TextWithSelectRange = ({
+ ref,
+ selectRange,
+ ...props
+}) => {
+ useInitialTextSelection(ref, selectRange);
+ return jsx(TextDispatcher, {
+ ...props,
+ ref: ref,
+ selectRange: undefined
+ });
};
-const arraySignal = (initialValue = []) => {
- const theSignal = signal(initialValue);
-
- const add = (...args) => {
- theSignal.value = addIntoArray(theSignal.peek(), ...args);
- };
- const remove = (...args) => {
- theSignal.value = removeFromArray(theSignal.peek(), ...args);
- };
+const LIGHT_ACCENT_ATTRIBUTE = "data-accent-light";
+const VERY_LIGHT_ACCENT_ATTRIBUTE = "data-accent-very-light";
+const DARK_CONTRAST_ATTRIBUTE = "data-accent-needs-dark-fg";
+const LIGHT_LUMINANCE_THRESHOLD = 0.5;
+const VERY_LIGHT_LUMINANCE_THRESHOLD = 0.92;
+const DARK_CONTRAST_LIGHTNESS_THRESHOLD = 0.65;
- return [theSignal, add, remove];
+/**
+ * Sets data attributes on an element based on the OKLCH lightness and contrast
+ * of a CSS color (typically an accent/brand color). All thresholds use OKLCH L
+ * (0–1, perceptually uniform scale).
+ *
+ * Three boolean attributes are managed independently:
+ *
+ * ## `data-accent-light` (set when OKLCH L > 0.5)
+ * The accent color is perceptually light (orange, green, pink, yellow…).
+ * Use to adjust color-mix direction so hover/active effects darken toward
+ * black instead of lightening toward white.
+ *
+ * ## `data-accent-very-light` (set when OKLCH L > 0.92)
+ * The accent color is near-white or white. Use to show a grey background on
+ * unchecked state so the component boundary remains visible against white
+ * page backgrounds.
+ *
+ * ## `data-accent-needs-dark-fg` (set when OKLCH L > 0.65)
+ * The best contrasting foreground color against the accent is dark (black).
+ * Use to render checkmarks, icons, or text in a dark color instead of white.
+ *
+ * @param {import("preact").RefObject} ref - Ref to the root element that receives the attributes.
+ * @param {string} accentColor - The accent color value. When it changes, attributes are recomputed.
+ * @param {object} [options]
+ * @param {string} [options.elementSelector] - CSS selector to find the element whose computed color is read.
+ * Defaults to the root element itself. Useful when the color is applied to a probe/child element.
+ * @param {string} [options.colorProperty="backgroundColor"] - Computed style property to read (e.g. "color", "borderColor").
+ */
+const useAccentColorAttributes = (
+ ref,
+ accentColor,
+ { elementSelector, colorProperty = "backgroundColor" } = {},
+) => {
+ useLayoutEffect(() => {
+ const el = ref.current;
+ if (!el) {
+ return undefined;
+ }
+ let elementToCheck = el;
+ elementSelector =
+ elementSelector || el.getAttribute("data-visual-selector");
+ if (elementSelector) {
+ elementToCheck = el.querySelector(elementSelector);
+ if (!elementToCheck) {
+ return undefined;
+ }
+ }
+ const updateAttributes = () => {
+ const computedStyle = getComputedStyle(elementToCheck);
+ const color = computedStyle[colorProperty];
+ if (!color) {
+ el.removeAttribute(LIGHT_ACCENT_ATTRIBUTE);
+ el.removeAttribute(VERY_LIGHT_ACCENT_ATTRIBUTE);
+ el.removeAttribute(DARK_CONTRAST_ATTRIBUTE);
+ return;
+ }
+ const luminance = resolveOklchLightness(color, el);
+ if (luminance !== null && luminance > LIGHT_LUMINANCE_THRESHOLD) {
+ el.setAttribute(LIGHT_ACCENT_ATTRIBUTE, "");
+ } else {
+ el.removeAttribute(LIGHT_ACCENT_ATTRIBUTE);
+ }
+ if (luminance !== null && luminance > VERY_LIGHT_LUMINANCE_THRESHOLD) {
+ el.setAttribute(VERY_LIGHT_ACCENT_ATTRIBUTE, "");
+ } else {
+ el.removeAttribute(VERY_LIGHT_ACCENT_ATTRIBUTE);
+ }
+ const bestContrast = contrastColor(
+ color,
+ el,
+ DARK_CONTRAST_LIGHTNESS_THRESHOLD,
+ );
+ if (bestContrast === "black") {
+ el.setAttribute(DARK_CONTRAST_ATTRIBUTE, "");
+ } else {
+ el.removeAttribute(DARK_CONTRAST_ATTRIBUTE);
+ }
+ };
+ updateAttributes();
+ el.addEventListener(NAVI_PSEUDO_STATE_CUSTOM_EVENT, updateAttributes);
+ return () => {
+ el.removeEventListener(NAVI_PSEUDO_STATE_CUSTOM_EVENT, updateAttributes);
+ el.removeAttribute(LIGHT_ACCENT_ATTRIBUTE);
+ el.removeAttribute(VERY_LIGHT_ACCENT_ATTRIBUTE);
+ el.removeAttribute(DARK_CONTRAST_ATTRIBUTE);
+ };
+ }, [ref, accentColor, elementSelector, colorProperty]);
};
-const executeWithCleanup = (fn, cleanup) => {
- let isThenable;
- try {
- const result = fn();
- isThenable = result && typeof result.then === "function";
- if (isThenable) {
- return (async () => {
- try {
- return await result;
- } finally {
- cleanup();
- }
- })();
- }
- return result;
- } finally {
- if (!isThenable) {
- cleanup();
+const addIntoArray = (array, ...valuesToAdd) => {
+ if (valuesToAdd.length === 1) {
+ const [valueToAdd] = valuesToAdd;
+ const arrayWithThisValue = [];
+ for (const value of array) {
+ if (value === valueToAdd) {
+ return array;
+ }
+ arrayWithThisValue.push(value);
}
+ arrayWithThisValue.push(valueToAdd);
+ return arrayWithThisValue;
}
-};
-
-let DEBUG$1 = false;
-const enableDebugOnDocumentLoading = () => {
- DEBUG$1 = true;
-};
-
-const windowIsLoadingSignal = signal(true);
-if (document.readyState === "complete") {
- windowIsLoadingSignal.value = false;
-} else {
- document.addEventListener("readystatechange", () => {
- if (document.readyState === "complete") {
- windowIsLoadingSignal.value = false;
- }
- });
-}
-const [
- documentLoadingRouteArraySignal,
- addToDocumentLoadingRouteArraySignal,
- removeFromDocumentLoadingRouteArraySignal,
-] = arraySignal([]);
-const routingWhile = (fn, routeNames = []) => {
- if (DEBUG$1 && routeNames.length > 0) {
- console.debug(`routingWhile: Adding routes to loading state:`, routeNames);
+ const existingValueSet = new Set();
+ const arrayWithTheseValues = [];
+ for (const existingValue of array) {
+ arrayWithTheseValues.push(existingValue);
+ existingValueSet.add(existingValue);
}
- addToDocumentLoadingRouteArraySignal(...routeNames);
- return executeWithCleanup(fn, () => {
- removeFromDocumentLoadingRouteArraySignal(...routeNames);
- if (DEBUG$1 && routeNames.length > 0) {
- console.debug(
- `routingWhile: Removed routes from loading state:`,
- routeNames,
- "state after removing:",
- documentLoadingRouteArraySignal.peek(),
- );
+ let hasNewValues = false;
+ for (const valueToAdd of valuesToAdd) {
+ if (existingValueSet.has(valueToAdd)) {
+ continue;
}
- });
-};
-
-const [
- documentLoadingActionArraySignal,
- addToDocumentLoadingActionArraySignal,
- removeFromDocumentLoadingActionArraySignal,
-] = arraySignal([]);
-const workingWhile = (fn, actionNames = []) => {
- if (DEBUG$1 && actionNames.length > 0) {
- console.debug(
- `workingWhile: Adding actions to loading state:`,
- actionNames,
- );
+ arrayWithTheseValues.push(valueToAdd);
+ hasNewValues = true;
}
- addToDocumentLoadingActionArraySignal(...actionNames);
- return executeWithCleanup(fn, () => {
- removeFromDocumentLoadingActionArraySignal(...actionNames);
- if (DEBUG$1 && actionNames.length > 0) {
- console.debug(
- `routingWhile: Removed action from loading state:`,
- actionNames,
- "start after removing:",
- documentLoadingActionArraySignal.peek(),
- );
- }
- });
+ return hasNewValues ? arrayWithTheseValues : array;
};
-const documentIsBusySignal = computed(() => {
- return (
- documentLoadingRouteArraySignal.value.length > 0 ||
- documentLoadingActionArraySignal.value.length > 0
- );
-});
-
-computed(() => {
- const windowIsLoading = windowIsLoadingSignal.value;
- const routesLoading = documentLoadingRouteArraySignal.value;
- const actionsLoading = documentLoadingActionArraySignal.value;
- const reasonArray = [];
- if (windowIsLoading) {
- reasonArray.push("window_loading");
- }
- if (routesLoading.length > 0) {
- reasonArray.push("document_routing");
- }
- if (actionsLoading.length > 0) {
- reasonArray.push("document_working");
+const removeFromArray = (array, ...valuesToRemove) => {
+ if (valuesToRemove.length === 1) {
+ const [valueToRemove] = valuesToRemove;
+ const arrayWithoutThisValue = [];
+ let found = false;
+ for (const value of array) {
+ if (value === valueToRemove) {
+ found = true;
+ continue;
+ }
+ arrayWithoutThisValue.push(value);
+ }
+ if (!found) {
+ return array;
+ }
+ return arrayWithoutThisValue;
}
- return reasonArray;
-});
-const documentStateSignal = signal(null);
-const useDocumentState = () => {
- return documentStateSignal.value;
-};
-const updateDocumentState = (value) => {
- documentStateSignal.value = value;
+ const valuesToRemoveSet = new Set(valuesToRemove);
+ const arrayWithoutTheseValues = [];
+ let hasRemovedValues = false;
+ for (const value of array) {
+ if (valuesToRemoveSet.has(value)) {
+ hasRemovedValues = true;
+ continue;
+ }
+ arrayWithoutTheseValues.push(value);
+ }
+ return hasRemovedValues ? arrayWithoutTheseValues : array;
};
-const documentUrlSignal = signal(
- typeof window === "undefined" ? "http://localhost" : window.location.href,
-);
-const useDocumentUrl = () => {
- return documentUrlSignal.value;
-};
-const updateDocumentUrl = (value) => {
- documentUrlSignal.value = value;
+const isSignal = (value) => {
+ return getSignalType(value) !== null;
};
-const documentResourceSignal = computed(() => {
- const documentUrl = documentUrlSignal.value;
- const documentResource = urlToResource(documentUrl);
- return documentResource;
-});
-const useDocumentResource = () => {
- return documentResourceSignal.value;
-};
-const urlToResource = (url) => {
- const scheme = urlToScheme(url);
- if (scheme === "file") {
- const urlAsStringWithoutFileProtocol = String(url).slice("file://".length);
- return urlAsStringWithoutFileProtocol;
- }
- if (scheme === "https" || scheme === "http") {
- // remove origin
- const afterProtocol = String(url).slice(scheme.length + "://".length);
- const pathnameSlashIndex = afterProtocol.indexOf("/", "://".length);
- const urlAsStringWithoutOrigin = afterProtocol.slice(pathnameSlashIndex);
- return urlAsStringWithoutOrigin;
- }
- const urlAsStringWithoutProtocol = String(url).slice(scheme.length + 1);
- return urlAsStringWithoutProtocol;
-};
-const urlToScheme = (url) => {
- const urlString = String(url);
- const colonIndex = urlString.indexOf(":");
- if (colonIndex === -1) {
- return "";
+const BRAND_SYMBOL = Symbol.for("preact-signals");
+const getSignalType = (value) => {
+ if (!value || typeof value !== "object") {
+ return null;
}
- const scheme = urlString.slice(0, colonIndex);
- return scheme;
-};
-const getHrefTargetInfo = (href) => {
- href = String(href);
-
- if (!href || href.trim() === "") {
- return {
- isEmpty: true,
- isCurrent: false,
- isAnchor: false,
- isSameOrigin: true,
- isSameSite: true,
- };
+ if (value.brand !== BRAND_SYMBOL) {
+ return null;
}
- const currentUrl = new URL(window.location.href);
- const targetUrl = new URL(href, window.location.href);
-
- let isCurrent = false;
- {
- isCurrent = currentUrl.href === targetUrl.href;
- }
- let isAnchor = false;
- {
- if (
- currentUrl.pathname === targetUrl.pathname &&
- currentUrl.search === targetUrl.search &&
- targetUrl.hash !== ""
- ) {
- isAnchor = true;
- }
- }
- let isSameOrigin = false;
- {
- const currentOrigin = currentUrl.origin;
- const targetOrigin = targetUrl.origin;
- isSameOrigin = currentOrigin === targetOrigin;
- }
- let isSameSite = false;
- {
- const baseDomain = (hostname) => {
- const parts = hostname.split(".").slice(-2);
- return parts.join(".");
- };
- const currentDomain = baseDomain(currentUrl.hostname);
- const targetDomain = baseDomain(targetUrl.hostname);
- isSameSite = currentDomain === targetDomain;
+ if (typeof value._fn === "function") {
+ return "computed";
}
- return {
- isEmpty: false,
- isCurrent,
- isAnchor,
- isSameOrigin,
- isSameSite,
- };
+ return "signal";
};
-const setupBrowserIntegrationViaHistory = ({
- applyActions,
- applyRouting,
- isRouting,
-}) => {
- const { history } = window;
-
- let globalAbortController = new AbortController();
- const triggerGlobalAbort = (reason) => {
- globalAbortController.abort(reason);
- globalAbortController = new AbortController();
- };
+/**
+ * jsenv/navi - createJsValueWeakMap
+ *
+ * Key/value cache with true ephemeron behavior and deep equality support.
+ *
+ * Features:
+ * - Mutual retention: key keeps value alive, value keeps key alive
+ * - Deep equality: different objects with same content are treated as identical keys
+ * - Automatic GC: entries are eligible for collection when unreferenced
+ * - Iteration support: can iterate over live entries for deep equality lookup
+ *
+ * Implementation:
+ * - Dual WeakMap (key->value, value->key) provides ephemeron behavior
+ * - WeakRef registry enables iteration without preventing GC
+ * - Primitives stored in Map (permanent retention - avoid for keys)
+ *
+ * Use case: Action caching where params (key) and action (value) should have
+ * synchronized lifetimes while allowing natural garbage collection.
+ */
- const dispatchActions = (params) => {
- const { requestedResult } = applyActions({
- globalAbortSignal: globalAbortController.signal,
- abortSignal: new AbortController().signal,
- ...params,
- });
- return requestedResult;
- };
- setActionDispatcher(dispatchActions);
- const getDocumentState = () => {
- return window.history.state ? { ...window.history.state } : null;
- };
+const createJsValueWeakMap = () => {
+ // Core ephemeron maps for mutual retention
+ const keyToValue = new WeakMap(); // key -> value
+ const valueToKey = new WeakMap(); // value -> key
- const historyStartAtStart = getDocumentState();
- const visitedUrlSet = historyStartAtStart
- ? new Set(historyStartAtStart.jsenv_visited_urls || [])
- : new Set();
+ // Registry for iteration/deep equality (holds WeakRefs)
+ const keyRegistry = new Set(); // Set of WeakRef(key)
- // Create a signal that tracks visited URLs for reactive updates
- // Using a counter instead of the Set directly for better performance
- // Links will check isVisited() when this signal changes
- const visitedUrlsSignal = signal(0);
+ // Primitive cache
+ const primitiveCache = new Map();
- const isVisited = (url) => {
- url = new URL(url, window.location.href).href;
- return visitedUrlSet.has(url);
- };
- const markUrlAsVisited = (url) => {
- if (visitedUrlSet.has(url)) {
- return;
+ function cleanupKeyRegistry() {
+ for (const keyRef of keyRegistry) {
+ if (keyRef.deref() === undefined) {
+ keyRegistry.delete(keyRef);
+ }
}
- visitedUrlSet.add(url);
- visitedUrlsSignal.value++;
- };
-
- let abortController = null;
- const handleRoutingTask = (url, options) => {
- const isSameUrl = url === window.location.href;
- const {
- reason,
- navigationType, // "load", "reload", "replace", "push", "traverse"
- state,
- } = options;
+ }
- if (navigationType === "push" || navigationType === "replace") {
- markUrlAsVisited(url);
- // undefined → inherit current state (link click, neutral navigation)
- // null → explicit reset (no nav-state keys carried over)
- // {...} → explicit state from enter()/leave(), already built from currentState
- // When state is given it's responsability of the caller to ensure it inherits document state (or not, you want it 99% of the time)
- let effectiveState;
- const sharedState = {
- jsenv_visited_urls: Array.from(visitedUrlSet),
- };
- if (state === undefined) {
- effectiveState = {
- ...(getDocumentState() || {}),
- ...sharedState,
- };
- } else if (state === null) {
- effectiveState = sharedState;
- } else if (state) {
- effectiveState = {
- ...state,
- ...sharedState,
- };
+ return {
+ *[Symbol.iterator]() {
+ cleanupKeyRegistry();
+ for (const keyRef of keyRegistry) {
+ const key = keyRef.deref();
+ if (key && keyToValue.has(key)) {
+ yield [key, keyToValue.get(key)];
+ }
}
- if (navigationType === "push") {
- window.history.pushState(effectiveState, null, url);
- } else {
- window.history.replaceState(effectiveState, null, url);
+ for (const [k, v] of primitiveCache) {
+ yield [k, v];
}
- updateDocumentUrl(url);
- updateDocumentState(effectiveState);
- } else {
- // traverse / reload: state comes from the history entry, no push/replace needed.
- markUrlAsVisited(url);
- updateDocumentUrl(url);
- updateDocumentState(state);
- }
-
- // Skip route matching for state-only changes: push/replace to the same URL
- // (e.g. useNavState updating document state without changing the route).
- // Do NOT apply for "traverse" — window.location.href is already updated by
- // the browser before the popstate handler runs, so isSameUrl is always true
- // for back/forward navigation regardless of whether the URL actually changed.
- if (
- isSameUrl &&
- (navigationType === "push" || navigationType === "replace")
- ) {
- return undefined;
- }
+ },
- if (abortController) {
- abortController.abort(`navigating to ${url}`);
- }
- abortController = new AbortController();
- const abortSignal = abortController.signal;
- const { allResult, requestedResult } = applyRouting(url, {
- globalAbortSignal: globalAbortController.signal,
- abortSignal,
- reason,
- navigationType,
- isVisited,
- state,
- });
- executeWithCleanup(
- () => allResult,
- () => {
- abortController = undefined;
- },
- );
- return requestedResult;
- };
+ get(key) {
+ const isObject =
+ key && (typeof key === "object" || typeof key === "function");
+ if (isObject) {
+ // Fast path: exact key match
+ if (keyToValue.has(key)) {
+ return keyToValue.get(key);
+ }
- // Browser event handlers
- window.addEventListener(
- "click",
- (e) => {
- if (e.button !== 0) {
- // Ignore non-left clicks
- return;
- }
- if (e.metaKey) {
- // Ignore clicks with meta key (e.g. open in new tab)
- return;
- }
- if (e.defaultPrevented) {
- return;
- }
- // Nothing here declared a route, so there is nothing to route to: the
- // page is a plain document and a link in it is a plain link. Taking it
- // over anyway would push the url and then have nothing to show for it —
- // the address bar moves and the page does not (see applyRouting's own
- // "not called yet" branch, which is where that used to end up).
- if (!isRouting()) {
- return;
- }
- const linkElement = e.target.closest("a");
- if (!linkElement) {
- return;
- }
- if (linkElement.hasAttribute("data-readonly")) {
- return;
- }
- const href = linkElement.href;
- const { isEmpty, isSameOrigin, isAnchor } = getHrefTargetInfo(href);
- if (
- isEmpty ||
- // Let link to other origins be handled by the browser
- !isSameOrigin ||
- // Ignore anchor navigation (same page, different hash)
- isAnchor
- ) {
- return;
+ // Slow path: deep equality search
+ cleanupKeyRegistry();
+ for (const keyRef of keyRegistry) {
+ const existingKey = keyRef.deref();
+ if (existingKey && compareTwoJsValues(existingKey, key)) {
+ return keyToValue.get(existingKey);
+ }
+ }
+ return undefined;
}
- e.preventDefault();
- handleRoutingTask(href, {
- reason: `"click" on a[href="${href}"]`,
- navigationType: "push",
- });
+ return primitiveCache.get(key);
},
- { capture: true },
- );
- window.addEventListener(
- "submit",
- () => {
- // Handle form submissions?
- // Not needed yet
+ set(key, value) {
+ const isObject =
+ key && (typeof key === "object" || typeof key === "function");
+ if (isObject) {
+ cleanupKeyRegistry();
+
+ // Remove existing deep-equal key
+ for (const keyRef of keyRegistry) {
+ const existingKey = keyRef.deref();
+ if (existingKey && compareTwoJsValues(existingKey, key)) {
+ const existingValue = keyToValue.get(existingKey);
+ keyToValue.delete(existingKey);
+ valueToKey.delete(existingValue);
+ keyRegistry.delete(keyRef);
+ break;
+ }
+ }
+
+ // Set ephemeron pair
+ keyToValue.set(key, value);
+ valueToKey.set(value, key);
+ keyRegistry.add(new WeakRef(key));
+ } else {
+ primitiveCache.set(key, value);
+ }
},
- { capture: true },
- );
-
- window.addEventListener("popstate", (popstateEvent) => {
- const url = window.location.href;
- const state = popstateEvent.state;
- handleRoutingTask(url, {
- reason: `"popstate" event for ${url}`,
- navigationType: "traverse",
- state,
- });
- });
-
- const navTo = async (url, { replace, state } = {}) => {
- handleRoutingTask(url, {
- reason: `navTo called with "${url}"`,
- navigationType: replace ? "replace" : "push",
- state,
- });
- };
- const stop = (reason = "stop called") => {
- triggerGlobalAbort(reason);
- };
+ delete(key) {
+ const isObject =
+ key && (typeof key === "object" || typeof key === "function");
+ if (isObject) {
+ cleanupKeyRegistry();
- const reload = () => {
- const url = window.location.href;
- const state = history.state;
- handleRoutingTask(url, {
- reason: "reload called",
- navigationType: "reload",
- state,
- });
- };
+ // Try exact match first
+ if (keyToValue.has(key)) {
+ const value = keyToValue.get(key);
+ keyToValue.delete(key);
+ valueToKey.delete(value);
- const navBack = () => {
- window.history.back();
- };
+ // Remove from registry
+ for (const keyRef of keyRegistry) {
+ if (keyRef.deref() === key) {
+ keyRegistry.delete(keyRef);
+ break;
+ }
+ }
+ return true;
+ }
- const navForward = () => {
- window.history.forward();
- };
+ // Try deep equality
+ for (const keyRef of keyRegistry) {
+ const existingKey = keyRef.deref();
+ if (existingKey && compareTwoJsValues(existingKey, key)) {
+ const value = keyToValue.get(existingKey);
+ keyToValue.delete(existingKey);
+ valueToKey.delete(value);
+ keyRegistry.delete(keyRef);
+ return true;
+ }
+ }
+ return false;
+ }
+ return primitiveCache.delete(key);
+ },
- const init = () => {
- const url = window.location.href;
- const state = history.state;
- handleRoutingTask(url, {
- reason: "routing initialization",
- navigationType: "load",
- state,
- });
- };
+ getStats: () => {
+ cleanupKeyRegistry();
+ const aliveKeys = Array.from(keyRegistry).filter((ref) =>
+ ref.deref(),
+ ).length;
- return {
- integration: "browser_history_api",
- init,
- navTo,
- stop,
- reload,
- navBack,
- navForward,
- getDocumentState,
- isVisited,
- visitedUrlsSignal,
+ return {
+ ephemeronPairs: {
+ total: keyRegistry.size,
+ alive: aliveKeys,
+ note: "True ephemeron: key ↔ value mutual retention via dual WeakMap",
+ },
+ primitive: {
+ total: primitiveCache.size,
+ note: "Primitive keys never GC'd",
+ },
+ };
+ },
};
};
-let updateRoutes;
+const MERGE_AS_PRIMITIVE_SYMBOL = Symbol("navi_merge_as_primitive");
-const applyActions = (params) => {
- const updateActionsResult = updateActions(params);
- const { allResult, runningActionSet } = updateActionsResult;
- const pendingTaskNameArray = [];
- for (const runningAction of runningActionSet) {
- pendingTaskNameArray.push(runningAction.name);
- }
- workingWhile(() => allResult, pendingTaskNameArray);
- return updateActionsResult;
-};
-const applyRouting = (
- url,
- {
- globalAbortSignal,
- abortSignal,
- // state
- navigationType,
- isVisited,
- reason,
- },
-) => {
- if (!updateRoutes) {
- // .init() not called yet
- // likely because code does not uses routing at all
- return {};
- }
- const {
- loadSet,
- reloadSet,
- abortSignalMap,
- routeLoadRequestedMap,
- activeRouteSet,
- } = updateRoutes(url, {
- navigationType,
- isVisited,
- // state,
- });
- if (
- (!loadSet || loadSet.size === 0) &&
- (!reloadSet || reloadSet.size === 0)
- ) {
- return {
- allResult: undefined,
- requestedResult: undefined,
- activeRouteSet: new Set(),
- };
+const mergeTwoJsValues = (firstValue, secondValue) => {
+ const firstIsPrimitive =
+ firstValue === null ||
+ typeof firstValue !== "object" ||
+ MERGE_AS_PRIMITIVE_SYMBOL in firstValue;
+
+ if (firstIsPrimitive) {
+ return secondValue;
}
- const updateActionsResult = updateActions({
- globalAbortSignal,
- abortSignal,
- runSet: loadSet,
- rerunSet: reloadSet,
- abortSignalMap,
- reason,
- isReplace: navigationType === "replace",
- });
- const { allResult, runningActionSet } = updateActionsResult;
- const pendingTaskNameArray = [];
- for (const [route, routeAction] of routeLoadRequestedMap) {
- if (runningActionSet.has(routeAction)) {
- pendingTaskNameArray.push(`${route.relativeUrl} -> ${routeAction.name}`);
- }
+ const secondIsPrimitive =
+ secondValue === null ||
+ typeof secondValue !== "object" ||
+ MERGE_AS_PRIMITIVE_SYMBOL in secondValue;
+ if (secondIsPrimitive) {
+ return secondValue;
}
- routingWhile(() => allResult, pendingTaskNameArray);
- return { ...updateActionsResult, activeRouteSet };
-};
-
-const browserIntegration = setupBrowserIntegrationViaHistory({
- applyActions,
- applyRouting,
- // Routes are declared by the consumer and registered through
- // setOnAllRouteReady below, so "does this document route at all?" is only
- // answerable once that has run — hence a function, read at click time rather
- // than a value read at setup time.
- isRouting: () => Boolean(updateRoutes),
-});
+ const objectMerge = {};
+ const firstKeys = Object.keys(firstValue);
+ const secondKeys = Object.keys(secondValue);
+ let hasChanged = false;
-setOnAllRouteReady((v) => {
- updateRoutes = v;
- browserIntegration.init();
-});
-setRouteIntegration(browserIntegration);
+ // First loop: check for keys in first object and recursively merge with second
+ for (const key of firstKeys) {
+ const firstValueForKey = firstValue[key];
+ const secondHasKey = secondKeys.includes(key);
-const navIntegratedVia = browserIntegration.integration;
-const navTo = (target, options) => {
- const url = new URL(target, window.location.href).href;
- const currentUrl = documentUrlSignal.peek();
- if (url === currentUrl) {
- if (options?.state === undefined) {
- return null;
- }
- // State-only update on same URL: skip if state is identical to current.
- const currentState = browserIntegration.getDocumentState();
- if (compareTwoJsValues(options.state, currentState)) {
- return null;
+ if (secondHasKey) {
+ const secondValueForKey = secondValue[key];
+ const mergedValue = mergeTwoJsValues(firstValueForKey, secondValueForKey);
+ objectMerge[key] = mergedValue;
+ if (mergedValue !== firstValueForKey) {
+ hasChanged = true;
+ }
+ } else {
+ objectMerge[key] = firstValueForKey;
}
}
- return browserIntegration.navTo(url, options);
-};
-const stopLoad = (reason = "stopLoad() called") => {
- const windowIsLoading = windowIsLoadingSignal.value;
- if (windowIsLoading) {
- window.stop();
+
+ for (const key of secondKeys) {
+ if (firstKeys.includes(key)) {
+ continue;
+ }
+ objectMerge[key] = secondValue[key];
+ hasChanged = true;
}
- const documentIsBusy = documentIsBusySignal.value;
- if (documentIsBusy) {
- browserIntegration.stop(reason);
+
+ if (!hasChanged) {
+ return firstValue;
}
+ return objectMerge;
};
-const reload = browserIntegration.reload;
-const navBack = browserIntegration.navBack;
-const navForward = browserIntegration.navForward;
-const isVisited = browserIntegration.isVisited;
-const visitedUrlsSignal = browserIntegration.visitedUrlsSignal;
-browserIntegration.handleActionTask;
-// Preact's own useId() (see preact/hooks) returns "P-", where
-// the mask is derived from render order within the nearest root/async
-// boundary — stable across re-renders of the *same* mount, but not across a
-// reload (render order can differ) or even across two mounts on the same
-// page (two components hitting useId() in the same relative order get the
-// same string). Storing one of these under type: "push" bakes it into a
-// history entry: reload the page and the entry's key may now belong to a
-// completely different component (or none), silently auto-opening whatever
-// happens to render at that same position instead.
-const PREACT_GENERATED_ID_REGEX = /^P\d+-\d+/;
-const isLikelyPreactGeneratedId = (id) => PREACT_GENERATED_ID_REGEX.test(id);
+const MAX_ENTRIES = 5;
-const NO_OP = () => {};
-const NO_ID_GIVEN = [undefined, NO_OP, NO_OP];
-const useNavStateBasic = (
- id,
- { debug, type = "replace", onLeave, defaultValue } = {},
+const stringifyForDisplay = (
+ value,
+ maxDepth = 2,
+ currentDepth = 0,
+ options = {},
) => {
- // Hooks must be called unconditionally — before the !id early return.
- const state = documentStateSignal.value;
- // Key presence is the flag — the value may be anything, including undefined.
- const keyInState = Boolean(id && state && Object.hasOwn(state, id));
- const onLeaveRef = useRef(onLeave);
- onLeaveRef.current = onLeave;
- const prevKeyInStateRef = useRef(keyInState);
- // enteredRef tracks whether enter() was called without a matching leave() yet.
- // It lets the effect distinguish an external disappearance (back button → fire onLeave)
- // from a programmatic one (leave() already set it to false before the state updates).
- const enteredRef = useRef(false);
- useEffect(() => {
- const prevKeyInState = prevKeyInStateRef.current;
- prevKeyInStateRef.current = keyInState;
- if (prevKeyInState && !keyInState && enteredRef.current) {
- enteredRef.current = false;
- onLeaveRef.current?.();
- }
- }, [keyInState]);
+ const { asFunctionArgs = false } = options;
+ const indent = " ".repeat(currentDepth);
+ const nextIndent = " ".repeat(currentDepth + 1);
- if (!id) {
- return NO_ID_GIVEN;
+ if (currentDepth >= maxDepth) {
+ return typeof value === "object" && value !== null
+ ? "[Object]"
+ : String(value);
}
- let effectiveType = type;
- if (type === "push" && isLikelyPreactGeneratedId(id)) {
- effectiveType = "replace";
+ if (value === null) {
+ return "null";
+ }
+ if (value === undefined) {
+ return "undefined";
+ }
+ if (typeof value === "string") {
+ return `"${value}"`;
+ }
+ if (typeof value === "number" || typeof value === "boolean") {
+ return String(value);
+ }
+ if (typeof value === "function") {
+ return `[Function ${value.name || "anonymous"}]`;
+ }
+ if (value instanceof Date) {
+ return `Date(${value.toISOString()})`;
+ }
+ if (value instanceof RegExp) {
+ return value.toString();
}
- const currentValue = keyInState ? state[id] : defaultValue;
+ if (Array.isArray(value)) {
+ const openBracket = asFunctionArgs ? "(" : "[";
+ const closeBracket = asFunctionArgs ? ")" : "]";
- if (debug) {
- console.debug(`useNavState(${id}) current value is ${currentValue}`);
- }
+ if (value.length === 0) return `${openBracket}${closeBracket}`;
- // enter(value): navigate TO this state (push or replace depending on type).
- // Calling enter() without a value stores "on" — the mere presence of the key
- // in the document state is enough to match; the value just allows associating
- // extra data with the entry when needed.
- const enter = (value = "on") => {
- enteredRef.current = true;
- const currentStateCopy = browserIntegration.getDocumentState() || {};
- if (Object.hasOwn(currentStateCopy, id) && currentStateCopy[id] === value) {
- return;
+ // Display arrays with only one element on a single line
+ if (value.length === 1) {
+ const item = stringifyForDisplay(
+ value[0],
+ maxDepth,
+ currentDepth + 1,
+ // Remove asFunctionArgs for nested calls
+ { ...options, asFunctionArgs: false },
+ );
+ return `${openBracket}${item}${closeBracket}`;
}
- currentStateCopy[id] = value;
- navTo(window.location.href, {
- replace: effectiveType !== "push",
- state: currentStateCopy,
- });
- };
- // leave(): navigate AWAY FROM this state (navBack in push mode, replace in replace mode).
- // isBack: when true (cancel close in push mode), call history.back() to restore the
- // pre-open state — discards any in-progress edits.
- // When false (confirmed close), replace the pushed entry instead: preserves the
- // current URL state (e.g. a new picker value) while removing the popup key.
- const leave = ({ isBack } = {}) => {
- enteredRef.current = false;
- const currentStateCopy = browserIntegration.getDocumentState() || {};
- if (!Object.hasOwn(currentStateCopy, id)) {
- return;
- }
- if (effectiveType === "push" && isBack) {
- browserIntegration.navBack();
- } else {
- delete currentStateCopy[id];
- navTo(window.location.href, {
- replace: true,
- state: currentStateCopy,
- });
+ if (value.length > MAX_ENTRIES) {
+ const preview = value
+ .slice(0, MAX_ENTRIES)
+ .map(
+ (v) =>
+ `${nextIndent}${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+ );
+ return `${openBracket}\n${preview.join(",\n")},\n${nextIndent}...${value.length - MAX_ENTRIES} more\n${indent}${closeBracket}`;
}
- };
-
- return [currentValue, enter, leave];
-};
-
-/**
- * Stores a named value in the browser's document state and returns it reactively.
- * The component re-renders whenever the value changes (navigation, back/forward button).
- *
- * @param {string} id
- * Unique key used to store the value in document state. Must be stable across renders.
- *
- * @param {object} [options]
- * @param {"push"|"replace"} [options.type="replace"]
- * Controls how enter() adds the state to browser history.
- * - "push": creates a new history entry — pressing the back button removes it and calls onLeave.
- * - "replace": updates the current history entry — no extra history entry is created.
- * Silently downgraded to "replace" (with a dev-only console.warn) when `id`
- * looks auto-generated (e.g. preact's own useId()) — an unstable id baked
- * into a pushed history entry won't survive a reload correctly, and could
- * even collide with a different component's own auto-generated id. Pass a
- * stable, explicit id to actually get "push" behavior.
- * @param {() => void} [options.onLeave]
- * Called when the state key disappears **externally** — e.g. the user presses the browser
- * back button. Not called when leave() is invoked programmatically.
- * @param {*} [options.defaultValue]
- * Value returned when `id` is absent from document state. Defaults to `undefined`.
- *
- * @returns {[value, enter, leave]}
- * - `value`: current value from document state, or `defaultValue` when the key is absent.
- * - `enter(value = "on")`: navigate TO this state (stores `value` under `id`).
- * Calling without an argument stores `"on"` — the presence of the key is enough to match;
- * the value allows associating extra data when needed.
- * - `leave()`: navigate AWAY FROM this state (removes `id` from document state,
- * or goes back in history when `type` is "push").
- */
-const useNavState = useNavStateBasic;
-const NEVER_SET = {};
-const useUrlSearchParam = (paramName, defaultValue) => {
- const documentUrl = documentUrlSignal.value;
- const searchParam = new URL(documentUrl).searchParams.get(paramName);
- const valueRef = useRef(NEVER_SET);
- const [value, setValue] = useState(defaultValue);
- if (valueRef.current !== searchParam) {
- valueRef.current = searchParam;
- setValue(searchParam);
+ const items = value.map(
+ (v) =>
+ `${nextIndent}${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+ );
+ return `${openBracket}\n${items.join(",\n")}\n${indent}${closeBracket}`;
}
- const setSearchParamValue = (newValue, { replace = false } = {}) => {
- const newUrlObject = new URL(window.location.href);
- newUrlObject.searchParams.set(paramName, newValue);
- const newUrl = newUrlObject.href;
- navTo(newUrl, { replace });
- };
+ if (typeof value === "object") {
+ const signalType = getSignalType(value);
+ if (signalType) {
+ const signalValue = value.peek();
+ const prefix = signalType === "computed" ? "computed" : "signal";
+ return `${prefix}(${stringifyForDisplay(signalValue, maxDepth, currentDepth, { ...options, asFunctionArgs: false })})`;
+ }
- return [value, setSearchParamValue];
-};
+ const entries = Object.entries(value);
+ if (entries.length === 0) return "{}";
-const Head = ({
- children
-}) => {
- useLayoutEffect(() => {
- if (!children) {
- return undefined;
- }
- const childArray = Array.isArray(children) ? children : [children];
- const previousTitle = document.title;
- const appendedElements = [];
- for (const child of childArray) {
- if (!child) {
- continue;
- }
- if (child.type === "title") {
- const titleChildren = child.props.children;
- document.title = Array.isArray(titleChildren) ? titleChildren.join("") : titleChildren ?? "";
- continue;
- }
- const el = document.createElement(child.type);
- const props = child.props || {};
- for (const [key, value] of Object.entries(props)) {
- el.setAttribute(key, value);
- }
- document.head.appendChild(el);
- appendedElements.push(el);
+ // ✅ Inclure les clés avec valeurs undefined/null
+ const allEntries = [];
+ for (const [key, val] of entries) {
+ allEntries.push([key, val]);
}
- return () => {
- document.title = previousTitle;
- for (const el of appendedElements) {
- el.remove();
+
+ // Ajouter les clés avec undefined (que Object.entries omet)
+ const descriptor = Object.getOwnPropertyDescriptors(value);
+ for (const [key, desc] of Object.entries(descriptor)) {
+ if (desc.value === undefined && !entries.some(([k]) => k === key)) {
+ allEntries.push([key, undefined]);
}
- };
- }, [children]);
- return null;
+ }
+
+ // Display objects with only one key on a single line
+ if (allEntries.length === 1) {
+ const [key, val] = allEntries[0];
+ const valueStr = stringifyForDisplay(val, maxDepth, currentDepth + 1, {
+ ...options,
+ asFunctionArgs: false,
+ });
+ return `{ ${key}: ${valueStr} }`;
+ }
+
+ if (allEntries.length > MAX_ENTRIES) {
+ const preview = allEntries
+ .slice(0, MAX_ENTRIES)
+ .map(
+ ([k, v]) =>
+ `${nextIndent}${k}: ${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+ );
+ return `{\n${preview.join(",\n")},\n${nextIndent}...${allEntries.length - MAX_ENTRIES} more\n${indent}}`;
+ }
+
+ const pairs = allEntries.map(
+ ([k, v]) =>
+ `${nextIndent}${k}: ${stringifyForDisplay(v, maxDepth, currentDepth + 1, { ...options, asFunctionArgs: false })}`,
+ );
+ return `{\n${pairs.join(",\n")}\n${indent}}`;
+ }
+
+ return String(value);
};
/**
- * Route is the single primitive for URL-based rendering.
- *
- * ## Layout pattern
- * Use this when multiple routes share a common layout but have no shared URL prefix,
- * making it impossible to set a guard route on the parent container.
- * For example, `/profile` and `/settings` both live inside `AuthLayout` but there
- * is no `/auth/` prefix to match on. A container Route wraps them: the active
- * child's element is injected as `children` into the layout element.
- * If a page needs state owned by the layout, the layout must expose it via context.
- *
- * ```jsx
- * const PROFILE_ROUTE = route("/profile");
- * const SETTINGS_ROUTE = route("/settings");
- *
- *
- *
- * ```
- *
- * ## Self-contained section pattern
- * Use this when routes share a common URL prefix (e.g. `/dashboard/`).
- * A single leaf Route in the top-level router matches the prefix; the component
- * it renders owns its sub-router and all related routes internally.
- * Everything about the section — routes, structure, sub-pages — is co-located.
- * The component is not a reusable layout; it is the section.
- *
- * Compared to the layout pattern, a dedicated section component is more powerful:
- * - Wrapper elements (chrome, nav, containers) are part of the component's render,
- * not injected via `children`, so a layout is not needed.
- * - Local state can be passed directly via `elementProps` to sub-pages. With the
- * layout pattern, sub-pages receive state only through `children` or context.
+ * Creates an effect that uses WeakRef to prevent garbage collection of referenced values.
*
- * The layout pattern remains necessary when a shared prefix does not exist
- * (see "Layout pattern" above).
+ * This utility is useful when you want to create reactive effects that watch objects
+ * without preventing those objects from being garbage collected. If any of the referenced
+ * values is collected, the effect automatically disposes itself.
*
- * ```jsx
- * const DASHBOARD_SECTION_ROUTE = route("/dashboard/");
- * const DASHBOARD_HOME_ROUTE = route("/dashboard");
- * const DASHBOARD_POSTS_ROUTE = route("/dashboard/posts");
+ * @param {Array} values - Array of values to create weak references for
+ * @param {Function} callback - Function to call when the effect runs, receives dereferenced values as arguments
+ * @returns {Function} dispose - Function to manually dispose the effect
*
- * // top-level router — only knows about the prefix
- * setSidebarOpen(o => !o)}
- * >
- *
- *
- *
;
- * }
+ * // Effect will auto-dispose if objectA or objectB where garbage collected
+ * // or can be manually disposed:
+ * dispose();
* ```
*/
-
-const debug$1 = (...args) => {
- {
- return;
+const weakEffect = (values, callback) => {
+ const weakRefSet = new Set();
+ for (const value of values) {
+ weakRefSet.add(new WeakRef(value));
}
+ const dispose = effect(() => {
+ const values = [];
+ for (const weakRef of weakRefSet) {
+ const value = weakRef.deref();
+ if (value === undefined) {
+ dispose();
+ return;
+ }
+ values.push(value);
+ }
+ callback(...values);
+ });
+ return dispose;
};
-// dispatches based on props:
-// - children → RouteContainer (traverses children statically, renders active branch)
-// - route → RouteLeafRoute (rendered by parent container when URL matches)
-// - fallback → RouteActive (rendered by parent container when no sibling matches)
-const Route = props => {
- if (props.children) {
- return jsx(RouteContainer, {
- ...props
- });
+const actionPrivatePropertiesWeakMap = new WeakMap();
+const getActionPrivateProperties = (action) => {
+ const actionPrivateProperties = actionPrivatePropertiesWeakMap.get(action);
+ if (!actionPrivateProperties) {
+ throw new Error(`Cannot find action private properties for "${action}"`);
}
- return jsx(RouteLeaf, {
- ...props
- });
+ return actionPrivateProperties;
};
-// RouteContainer: traverses children statically per render, finds the active branch,
-// and renders only that branch — or the fallback if nothing matches.
-// No effects, no signals, no contexts needed: reads route signals directly.
-const RouteContainer = ({
- id,
- element,
- elementProps,
- children
-}) => {
- const {
- activeBranch
- } = collectBranches(children);
- debug$1(`[container "${id}"] RENDER, active=${activeBranch ? activeBranch.type : "none"}`);
- const content = activeBranch ? activeBranch.node : null;
- if (!content) {
- return null;
- }
- if (element) {
- return h(element, elementProps, content);
- }
- return content;
+const setActionPrivateProperties = (action, properties) => {
+ actionPrivatePropertiesWeakMap.set(action, properties);
};
-// Walk JSX children vnodes (without rendering) to build a branch list and
-// find the active one in the same pass.
-// All children must be — throws in dev otherwise.
-// Returns { matchingBranch, fallbackBranch, activeBranch }.
-const collectBranches = children => {
- let matchingBranch = null;
- let fallbackBranch = null;
- const visit = child => {
- if (!child || child === true || child === false) {
- return;
- }
- if (Array.isArray(child)) {
- for (const item of child) {
- visit(item);
- }
- return;
- }
- if (child.type !== Route) {
- throw new Error(`All children must be nodes, got: ${String(child.type?.name ?? child.type)}`);
- }
- const {
- children: nodeChildren,
- fallback,
- route,
- routeParams
- } = child.props;
- if (nodeChildren) {
- const {
- matchingBranch: matchingChild
- } = collectBranches(nodeChildren);
- const branch = {
- type: "container",
- node: child
- };
- if (!matchingBranch) {
- if (matchingChild) {
- // Real leaf match inside — always select this container
- matchingBranch = branch;
- } else if (route && route.matchingSignal.value) {
- // No leaf match but an explicit route guard matches — select this
- // container so it can render its own fallback inside its layout
- matchingBranch = branch;
- }
- }
- } else if (fallback) {
- if (!fallbackBranch) {
- fallbackBranch = {
- type: "fallback",
- node: child
- };
- }
- } else {
- const branch = {
- type: "leaf",
- node: child
- };
- if (!matchingBranch && route.matchingSignal.value && (!routeParams || route.matchesParams(routeParams))) {
- matchingBranch = branch;
- }
- }
- };
- visit(children);
- const activeBranch = matchingBranch || fallbackBranch || null;
- return {
- matchingBranch,
- fallbackBranch,
- activeBranch
- };
+
+const IDLE = { id: "idle" };
+const RUNNING = { id: "running" };
+const ABORTED = { id: "aborted" };
+const FAILED = { id: "failed" };
+const COMPLETED = { id: "completed" };
+
+const SYMBOL_OBJECT_SIGNAL = Symbol.for("navi_object_signal");
+
+let DEBUG$2 = false;
+const enableDebugActions = () => {
+ DEBUG$2 = true;
};
-const RouteLeaf = props => {
- if (props.route) {
- return jsx(RouteLeafRoute, {
- ...props
- });
- }
- if (props.fallback) {
- return jsx(RouteLeafFallback, {
- ...props
- });
- }
- // not supposed to happen?
- return jsx(RouteUI, {
- ...props
+
+let dispatchActions = (params) => {
+ const { requestedResult } = updateActions({
+ globalAbortSignal: new AbortController().signal,
+ abortSignal: new AbortController().signal,
+ ...params,
});
+ return requestedResult;
};
-const RouteLeafRoute = props => {
- useUITransitionContentId(props.route?.urlPattern);
- return jsx(RouteUI, {
- ...props
+
+const dispatchSingleAction = (action, method, options) => {
+ const requestedResult = dispatchActions({
+ prerunSet: method === "prerun" ? new Set([action]) : undefined,
+ runSet: method === "run" ? new Set([action]) : undefined,
+ rerunSet: method === "rerun" ? new Set([action]) : undefined,
+ resetSet: method === "reset" ? new Set([action]) : undefined,
+ ...options,
});
+ if (requestedResult && typeof requestedResult.then === "function") {
+ return requestedResult.then((resolvedResult) =>
+ resolvedResult ? resolvedResult[0] : undefined,
+ );
+ }
+ return requestedResult ? requestedResult[0] : undefined;
};
-const RouteLeafFallback = props => {
- return jsx(RouteUI, {
- ...props
- });
+const setActionDispatcher = (value) => {
+ dispatchActions = value;
};
-const RouteUI = ({
- element,
- elementProps
-}) => {
- if (typeof element === "function") {
- return h(element, elementProps);
- }
- return element;
+
+const getActionDispatcher = () => dispatchActions;
+
+const rerunActions = async (actionSet, options) => {
+ return dispatchActions({
+ rerunSet: actionSet,
+ reason: "rerunActions was calle",
+ ...options,
+ });
};
-const routeAction = (
- routeOrRoutes,
- action,
- paramsEffect = () => true,
- options = {},
-) => {
- const routeMatchingSignal = Array.isArray(routeOrRoutes)
- ? anyMatchingRouteSignal(routeOrRoutes)
- : routeOrRoutes.matchingSignal;
- const actionBoundToRoute = actionRunEffect(
- action,
- () => {
- const matching = routeMatchingSignal.value;
- const params = paramsEffect();
- if (!matching) {
- return null;
+/**
+ * Registry that prevents prerun actions from being garbage collected.
+ *
+ * When an action is prerun, it might not have any active references yet
+ * (e.g., the component that will use it hasn't loaded yet due to dynamic imports).
+ * This registry keeps a reference to prerun actions for a configurable duration
+ * to ensure they remain available when needed.
+ *
+ * Actions are automatically unprotected when:
+ * - The protection duration expires (default: 5 minutes)
+ * - The action is explicitly stopped via .reset()
+ */
+const prerunProtectionRegistry = (() => {
+ const protectedActionMap = new Map(); // action -> { timeoutId, timestamp }
+ const PROTECTION_DURATION = 5 * 60 * 1000; // 5 minutes en millisecondes
+
+ const unprotect = (action) => {
+ const protection = protectedActionMap.get(action);
+ if (protection) {
+ clearTimeout(protection.timeoutId);
+ protectedActionMap.delete(action);
+ const elapsed = Date.now() - protection.timestamp;
+ action.debug(`"${action}": GC protection removed after ${elapsed}ms`);
+ }
+ };
+
+ return {
+ protect(action) {
+ // Si déjà protégée, étendre la protection
+ if (protectedActionMap.has(action)) {
+ const existing = protectedActionMap.get(action);
+ clearTimeout(existing.timeoutId);
}
- return params;
+
+ const timestamp = Date.now();
+ const timeoutId = setTimeout(() => {
+ unprotect(action);
+ action.debug(
+ `"${action}": prerun protection expired after ${PROTECTION_DURATION}ms`,
+ );
+ }, PROTECTION_DURATION);
+ protectedActionMap.set(action, { timeoutId, timestamp });
+ action.debug(
+ `"${action}": protected from GC for ${PROTECTION_DURATION}ms`,
+ );
},
- options,
- );
- return actionBoundToRoute;
-};
+ unprotect,
-// I delibrately prefer the term "any" and avoid "some" so dev are not tempted to think
-// "well I could just use array.some" and bypass this helper entirely, which would be incorrect:
-// This helper does return if some/any route is matching but ensure all route matching signals are read (subscribed to)
-// array.some would return as soon as it finds a match and would not subscribe to the rest of the signals.
-const anyMatchingRouteSignal = (routes) => {
- if (routes.length === 0) {
- return signal(false);
- }
- if (routes.length === 1) {
- const [route] = routes;
- return route.matchingSignal;
- }
- const anyMatchingSignal = computed(() => {
- let someMatching;
- for (const route of routes) {
- const matching = route.matchingSignal.value;
- if (matching) {
- someMatching = true;
+ isProtected(action) {
+ return protectedActionMap.has(action);
+ },
+
+ // Pour debugging
+ getProtectedActions() {
+ return Array.from(protectedActionMap.keys());
+ },
+
+ // Nettoyage manuel si nécessaire
+ clear() {
+ for (const [, protection] of protectedActionMap) {
+ clearTimeout(protection.timeoutId);
}
- }
- return someMatching;
- });
- return anyMatchingSignal;
-};
+ protectedActionMap.clear();
+ },
+ };
+})();
-// used by form elements such as ,