@resistdesign/voltra 3.0.0-alpha.47 → 3.0.0-alpha.49

package/app/index.d.ts

@@ -8,14 +8,15 @@
  * ```ts
  * import {
  *   createFormRenderer,
+ *   getApplicationStateIdentifier,
  *   useApplicationStateLoader,
- *   useApplicationStateValueStructure,
+ *   useApplicationStateValue,
  *   type RemoteProcedureCall,
  * } from "@resistdesign/voltra/app";
  * ```
  *
- * @see {@link useApplicationStateValueStructure} and
- * {@link useApplicationStateLoader} for good starting points.
+ * @see {@link useApplicationStateValue} and {@link useApplicationStateLoader}
+ * for good starting points.
  *
  * Reference examples:
  * - `examples/README.md`
@@ -24,17 +25,22 @@
  * @example
  * ```tsx
  * import {
+ *   getApplicationStateIdentifier,
  *   useApplicationStateLoader,
- *   useApplicationStateValueStructure,
+ *   useApplicationStateValue,
  *   type RemoteProcedureCall,
  * } from "@resistdesign/voltra/app";
  * import { useCallback } from "react";
  *
+ * const loginUsernameId = getApplicationStateIdentifier<string>();
+ * const loginPasswordId = getApplicationStateIdentifier<string>();
+ * const loginLoggedInId = getApplicationStateIdentifier<boolean>();
+ *
  * const APP_STATE_IDENTIFIERS = {
  *   LOGIN: {
- *     USERNAME: {},
- *     PASSWORD: {},
- *     LOGGED_IN: {},
+ *     USERNAME: loginUsernameId,
+ *     PASSWORD: loginPasswordId,
+ *     LOGGED_IN: loginLoggedInId,
  *   },
  * };
  *
@@ -52,27 +58,24 @@
  *
  * export const LoginController = () => {
  *   const {
- *     valueStructure: {
- *       username: username = "",
- *       password: password = "",
- *       loggedIn: loggedIn = false,
- *     },
- *     onChangeStructure: {
- *       username: setUsername,
- *       password: setPassword,
- *       loggedIn: setLoggedIn,
- *     },
- *   } = useApplicationStateValueStructure<{
- *     username: string;
- *     password: string;
- *     loggedIn: boolean;
- *   }>({
- *     username: APP_STATE_IDENTIFIERS.LOGIN.USERNAME,
- *     password: APP_STATE_IDENTIFIERS.LOGIN.PASSWORD,
- *     loggedIn: APP_STATE_IDENTIFIERS.LOGIN.LOGGED_IN,
- *   });
+ *     value: username = "",
+ *     onChange: setUsername,
+ *   } = useApplicationStateValue(APP_STATE_IDENTIFIERS.LOGIN.USERNAME);
+ *   const {
+ *     value: password = "",
+ *     onChange: setPassword,
+ *   } = useApplicationStateValue(APP_STATE_IDENTIFIERS.LOGIN.PASSWORD);
+ *   const {
+ *     value: loggedIn = false,
+ *     onChange: setLoggedIn,
+ *   } = useApplicationStateValue(APP_STATE_IDENTIFIERS.LOGIN.LOGGED_IN);
  *
- *   const { loading: loadingLogin, makeRemoteProcedureCall } =
+ *   const {
+ *     value: latestLoginState,
+ *     modified: loginStateModified,
+ *     loading: loadingLogin,
+ *     makeRemoteProcedureCall,
+ *   } =
  *     useApplicationStateLoader({
  *       identifier: APP_STATE_IDENTIFIERS.LOGIN.LOGGED_IN,
  *       remoteProcedureCall: LOGIN_RPC,
@@ -83,7 +86,18 @@
  *     makeRemoteProcedureCall(username, password);
  *   }, [username, password, makeRemoteProcedureCall]);
  *
- *   return { username, password, loggedIn, setUsername, setPassword, onSubmit, loadingLogin };
+ *   return {
+ *     username,
+ *     password,
+ *     loggedIn,
+ *     latestLoginState,
+ *     loginStateModified,
+ *     setUsername,
+ *     setPassword,
+ *     setLoggedIn,
+ *     onSubmit,
+ *     loadingLogin,
+ *   };
  * };
  * ```
  *

package/app/index.js

@@ -1,25 +1,20 @@
-export { createEasyLayout, getEasyLayoutTemplateDetails, getPascalCaseAreaName } from '../chunk-QXYUXJKM.js';
+export { createEasyLayout, getEasyLayoutTemplateDetails, getPascalCaseAreaName } from '../chunk-BSHQIRBV.js';
 export { computeTrackPixels } from '../chunk-TJFTWPXQ.js';
-export { AutoForm, AutoFormView, Route, RouteContext, RouteContextConsumer, RouteContextProvider, RouteProvider, buildHistoryPath, buildQueryString, buildRoutePath, canUseBrowserHistory, computeAreaBounds, createAutoField, createBrowserRouteAdapter, createFormRenderer, createHistoryBackHandler, createManualRouteAdapter, createMemoryHistory, createNativeRouteAdapter, createRouteAdapterFromHistory, createUniversalAdapter, defaultTranslateValidationErrorCode, getFieldKind, parseHistoryPath, parseTemplate, resolveSuite, useFormEngine, useRouteContext, validateAreas, wrapRouteAdapterWithPathResolver } from '../chunk-UD2ALOCE.js';
+export { AutoForm, AutoFormView, Route, RouteContext, RouteContextConsumer, RouteContextProvider, RouteProvider, buildHistoryPath, buildQueryString, buildRoutePath, canUseBrowserHistory, computeAreaBounds, createAutoField, createBrowserRouteAdapter, createFormRenderer, createHistoryBackHandler, createManualRouteAdapter, createMemoryHistory, createNativeRouteAdapter, createRouteAdapterFromHistory, createUniversalAdapter, defaultTranslateValidationErrorCode, getFieldKind, parseHistoryPath, parseTemplate, resolveSuite, useFormEngine, useRouteContext, validateAreas, wrapRouteAdapterWithPathResolver } from '../chunk-K4R2PFNG.js';
 import '../chunk-RUNXRISF.js';
 import '../chunk-3HVYVX3S.js';
 import { mergeStringPaths, PATH_DELIMITER } from '../chunk-2JDOM6PB.js';
 import '../chunk-I2KLQ2HA.js';
-import { createContext, useContext, useRef, useMemo, useCallback, useState, useEffect } from 'react';
+import { createContext, useContext, useMemo, useCallback, useState, useRef, useEffect } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
-var getApplicationStateIdentifier = (subStateIdMap) => subStateIdMap ? subStateIdMap : {};
+function getApplicationStateIdentifier(subStateIdMap) {
+  return subStateIdMap ? subStateIdMap : {};
+}
 var getApplicationStateModified = (identifier, modificationState) => !!modificationState.get(identifier);
 var getApplicationStateValue = (identifier, applicationState) => applicationState.get(identifier);
 var setApplicationStateModified = (identifier, value, modificationState) => new Map(modificationState).set(identifier, value);
 var setApplicationStateValue = (identifier, value, applicationState) => new Map(applicationState).set(identifier, value);
-var getApplicationStateValueStructure = (idStructure, applicationState) => Object.keys(idStructure).reduce(
-  (acc, k) => ({
-    ...acc,
-    [k]: getApplicationStateValue(idStructure[k], applicationState)
-  }),
-  {}
-);
 var ApplicationStateContext = createContext({
   modified: /* @__PURE__ */ new Map(),
   value: /* @__PURE__ */ new Map(),
@@ -36,10 +31,6 @@ var useApplicationStateValue = (identifier) => {
     onChange: setApplicationState,
     setModified: setModificationState
   } = useContext(ApplicationStateContext);
-  const appStateRef = useRef(applicationState);
-  appStateRef.current = applicationState;
-  const modificationStateRef = useRef(modificationState);
-  modificationStateRef.current = modificationState;
   const modified = useMemo(
     () => getApplicationStateModified(identifier, modificationState),
     [identifier, modificationState]
@@ -51,23 +42,30 @@ var useApplicationStateValue = (identifier) => {
   const setModified = useCallback(
     (isModified) => {
       setModificationState(
-        setApplicationStateModified(
-          identifier,
-          isModified,
-          modificationStateRef.current
-        )
+        (previousModified) => setApplicationStateModified(identifier, isModified, previousModified)
       );
     },
     [identifier, setModificationState]
   );
   const onChange = useCallback(
     (newValue) => {
-      setApplicationState(
-        setApplicationStateValue(identifier, newValue, appStateRef.current)
+      setApplicationState((previousState) => {
+        const previousValue = getApplicationStateValue(
+          identifier,
+          previousState
+        );
+        const resolvedValue = typeof newValue === "function" ? newValue(previousValue) : newValue;
+        return setApplicationStateValue(
+          identifier,
+          resolvedValue,
+          previousState
+        );
+      });
+      setModificationState(
+        (previousModified) => setApplicationStateModified(identifier, true, previousModified)
       );
-      setModified(true);
     },
-    [identifier, setApplicationState]
+    [identifier, setApplicationState, setModificationState]
   );
   const controller = useMemo(
     () => ({
@@ -80,41 +78,6 @@ var useApplicationStateValue = (identifier) => {
   );
   return controller;
 };
-var useApplicationStateValueStructure = (idStructure) => {
-  const { value: applicationState, onChange: setApplicationState } = useContext(
-    ApplicationStateContext
-  );
-  const valueStructure = useMemo(
-    () => getApplicationStateValueStructure(idStructure, applicationState),
-    [applicationState, idStructure]
-  );
-  const onChangeStructure = useMemo(
-    () => Object.keys(idStructure).reduce(
-      (acc, k) => ({
-        ...acc,
-        [k]: (newValue) => {
-          setApplicationState(
-            setApplicationStateValue(
-              idStructure[k],
-              newValue,
-              applicationState
-            )
-          );
-        }
-      }),
-      {}
-    ),
-    [applicationState, idStructure, setApplicationState]
-  );
-  const controller = useMemo(
-    () => ({
-      valueStructure,
-      onChangeStructure
-    }),
-    [onChangeStructure, valueStructure]
-  );
-  return controller;
-};
 var ApplicationStateProvider = ({
   children
 }) => {
@@ -200,13 +163,14 @@ var useApplicationStateLoader = (config) => {
   const [cacheValidity, setCacheValidity] = useState({});
   const [loading, setLoading] = useState(false);
   const [latestError, setLatestError] = useState();
-  const { onChange, setModified } = useApplicationStateValue(identifier);
+  const valueController = useApplicationStateValue(identifier);
+  const { onChange, setModified } = valueController;
   const invalidate = useCallback(() => {
     setCacheValidity({});
   }, []);
   const makeRemoteProcedureCall = useCallback(
     async (...directArgs) => {
-      let success;
+      let success = false;
       setLoading(true);
       setLatestError(void 0);
       try {
@@ -234,12 +198,13 @@ var useApplicationStateLoader = (config) => {
   );
   const appStateLoader = useMemo(
     () => ({
+      ...valueController,
       loading,
       latestError,
       invalidate,
       makeRemoteProcedureCall
     }),
-    [loading, latestError, invalidate, makeRemoteProcedureCall]
+    [valueController, loading, latestError, invalidate, makeRemoteProcedureCall]
   );
   useEffect(() => {
     if (!manual && argsRef.current) {
@@ -580,4 +545,4 @@ var withRendererOverride = (kind, renderer) => ({
   }
 });
 
-export { ApplicationStateContext, ApplicationStateProvider, TypeInfoORMClient, getApplicationStateIdentifier, getApplicationStateModified, getApplicationStateValue, getApplicationStateValueStructure, getChangedDependencyIndexes, getFullUrl, handleRequest, mergeSuites, requestHandlerFactory, sendServiceRequest, setApplicationStateModified, setApplicationStateValue, useApplicationStateLoader, useApplicationStateValue, useApplicationStateValueStructure, useController, useDebugDependencies, useTypeInfoORMAPI, withRendererOverride };
+export { ApplicationStateContext, ApplicationStateProvider, TypeInfoORMClient, getApplicationStateIdentifier, getApplicationStateModified, getApplicationStateValue, getChangedDependencyIndexes, getFullUrl, handleRequest, mergeSuites, requestHandlerFactory, sendServiceRequest, setApplicationStateModified, setApplicationStateValue, useApplicationStateLoader, useApplicationStateValue, useController, useDebugDependencies, useTypeInfoORMAPI, withRendererOverride };

package/app/utils/ApplicationState.d.ts

@@ -3,39 +3,56 @@
  *
  * Application-level state container built on React context and maps. Use
  * {@link ApplicationStateProvider} to host state, then access values with
- * {@link useApplicationStateValue} or {@link useApplicationStateValueStructure}.
+ * {@link useApplicationStateValue}.
  */
-import { FC, PropsWithChildren } from "react";
+import { FC, PropsWithChildren, type Dispatch, type SetStateAction } from "react";
 /**
- * An object, nested or not, used as the identifier or identifier path for a state value.
+ * An object, nested or not, used as the identifier or identifier path for a
+ * state value.
+ *
+ * The generic parameter exists purely for TypeScript. It lets a consumer make
+ * the identifier itself the source of truth for what value type lives at that
+ * location in application state, without changing the runtime shape.
  * */
-export interface ApplicationStateIdentifier extends Record<string, ApplicationStateIdentifier | {}> {
+declare const applicationStateIdentifierValueTypeSymbol: unique symbol;
+export interface ApplicationStateIdentifier<ValueType = unknown> extends Record<string, ApplicationStateIdentifier<any> | {}> {
+    readonly [applicationStateIdentifierValueTypeSymbol]?: ValueType;
 }
 /**
  * The stored value type for application state entries.
  * */
-export type ApplicationStateValue = any;
+export type ApplicationStateValue = unknown;
+/**
+ * React-style state action for a specific application-state value.
+ *
+ * Passing a function follows the same contract as React `useState`: the
+ * function receives the previous value and returns the next value.
+ * */
+export type ApplicationStateSetAction<ValueType> = ValueType | ((previousValue: ValueType) => ValueType);
+/**
+ * React-style stable setter for a specific application-state value.
+ * */
+export type ApplicationStateSetter<ValueType> = (value: ApplicationStateSetAction<ValueType>) => void;
 /**
  * Map of state identifiers to a "modified" boolean.
  * */
-export type ApplicationStateModificationState = Map<ApplicationStateIdentifier, boolean>;
+export type ApplicationStateModificationState = Map<ApplicationStateIdentifier<any>, boolean>;
 /**
  * Map of state identifiers to stored values.
  * */
-export type ApplicationState = Map<ApplicationStateIdentifier, ApplicationStateValue>;
+export type ApplicationState = Map<ApplicationStateIdentifier<any>, ApplicationStateValue>;
 /**
- * Determines the identifier shape for a specific sub-state.
+ * Create or forward an application-state identifier.
  *
- * @typeParam SpecificType - The identifier shape, if provided.
- * */
-export type ApplicationStateIdentifierSubStateType<SpecificType> = SpecificType extends undefined ? ApplicationStateIdentifier : SpecificType extends ApplicationStateIdentifier ? SpecificType : never;
-/**
- * Normalize a sub-state identifier map to an ApplicationStateIdentifier.
+ * Call with no argument to create a new identifier object and attach a value
+ * type at the type level:
+ * `const profileId = getApplicationStateIdentifier<UserProfile>()`
  *
- * @param subStateIdMap - Optional sub-state identifier map.
- * @returns The identifier map or an empty identifier object.
+ * Call with an existing identifier object to preserve that exact object
+ * reference while keeping its type information intact.
  * */
-export declare const getApplicationStateIdentifier: <SubStateIdStructure extends ApplicationStateIdentifier>(subStateIdMap?: SubStateIdStructure) => ApplicationStateIdentifierSubStateType<SubStateIdStructure>;
+export declare function getApplicationStateIdentifier<ValueType = ApplicationStateValue>(): ApplicationStateIdentifier<ValueType>;
+export declare function getApplicationStateIdentifier<IdentifierType extends ApplicationStateIdentifier<any>>(subStateIdMap: IdentifierType): IdentifierType;
 /**
  * Read the modification status for a specific identifier.
  *
@@ -43,7 +60,7 @@ export declare const getApplicationStateIdentifier: <SubStateIdStructure extends
  * @param modificationState - The modification map to read from.
  * @returns Whether the identifier is marked as modified.
  * */
-export declare const getApplicationStateModified: (identifier: ApplicationStateIdentifier, modificationState: ApplicationStateModificationState) => boolean;
+export declare const getApplicationStateModified: (identifier: ApplicationStateIdentifier<any>, modificationState: ApplicationStateModificationState) => boolean;
 /**
  * Read the stored value for an identifier.
  *
@@ -51,7 +68,7 @@ export declare const getApplicationStateModified: (identifier: ApplicationStateI
  * @param applicationState - The application state map.
  * @returns The stored value, if any.
  * */
-export declare const getApplicationStateValue: (identifier: ApplicationStateIdentifier, applicationState: ApplicationState) => ApplicationStateValue;
+export declare const getApplicationStateValue: <ValueType = ApplicationStateValue>(identifier: ApplicationStateIdentifier<ValueType>, applicationState: ApplicationState) => ValueType | undefined;
 /**
  * Set the modification status for an identifier.
  *
@@ -60,7 +77,7 @@ export declare const getApplicationStateValue: (identifier: ApplicationStateIden
  * @param modificationState - The current modification map.
  * @returns A new modification map with the updated flag.
  * */
-export declare const setApplicationStateModified: (identifier: ApplicationStateIdentifier, value: boolean, modificationState: ApplicationStateModificationState) => ApplicationStateModificationState;
+export declare const setApplicationStateModified: (identifier: ApplicationStateIdentifier<any>, value: boolean, modificationState: ApplicationStateModificationState) => ApplicationStateModificationState;
 /**
  * Set the stored value for an identifier.
  *
@@ -69,15 +86,7 @@ export declare const setApplicationStateModified: (identifier: ApplicationStateI
  * @param applicationState - The current application state map.
  * @returns A new application state map with the updated value.
  * */
-export declare const setApplicationStateValue: (identifier: ApplicationStateIdentifier, value: ApplicationStateValue, applicationState: ApplicationState) => ApplicationState;
-/**
- * Resolve a structured map of identifiers into their current values.
- *
- * @param idStructure - Map of structure keys to identifiers.
- * @param applicationState - The application state map.
- * @returns An object of the same shape containing resolved values.
- * */
-export declare const getApplicationStateValueStructure: <ReturnStructureType extends Record<string, any>>(idStructure: Record<keyof ReturnStructureType, ApplicationStateIdentifier>, applicationState: ApplicationState) => ReturnStructureType;
+export declare const setApplicationStateValue: <ValueType = ApplicationStateValue>(identifier: ApplicationStateIdentifier<ValueType>, value: ValueType, applicationState: ApplicationState) => ApplicationState;
 /**
  * Context state and updater hooks for application state.
  * */
@@ -93,11 +102,11 @@ export type ApplicationStateContextType = {
     /**
      * Replace the current application state map.
      * */
-    onChange: (newValue: ApplicationState) => void;
+    onChange: Dispatch<SetStateAction<ApplicationState>>;
     /**
      * Replace the current modification state map.
      * */
-    setModified: (newValue: ApplicationStateModificationState) => void;
+    setModified: Dispatch<SetStateAction<ApplicationStateModificationState>>;
 };
 /**
  * React context for application state and modification tracking.
@@ -106,7 +115,7 @@ export declare const ApplicationStateContext: import("react").Context<Applicatio
 /**
  * Used to access and update application state values.
  * */
-export type ApplicationStateValueController = {
+export type ApplicationStateValueController<ValueType = ApplicationStateValue> = {
     /**
      * Whether the value is marked as modified.
      * */
@@ -114,13 +123,17 @@ export type ApplicationStateValueController = {
     /**
      * The current value for the identifier.
      * */
-    value: ApplicationStateValue;
+    value: ValueType | undefined;
     /**
-     * Update the current value.
+     * Update the current value with React `useState` semantics.
      *
-     * @param value - The new value to store.
+     * The setter is intentionally stable so consumers can safely depend on it
+     * like a normal React state setter.
+     *
+     * @param value - The next value, or a function that derives it from the
+     * previous value.
      * */
-    onChange: (value: ApplicationStateValue) => void;
+    onChange: ApplicationStateSetter<ValueType | undefined>;
     /**
      * Update the modified flag.
      *
@@ -134,27 +147,7 @@ export type ApplicationStateValueController = {
  * @param identifier - Identifier to read and update.
  * @returns Controller for the identifier value and modified flag.
  * */
-export declare const useApplicationStateValue: (identifier: ApplicationStateIdentifier) => ApplicationStateValueController;
-/**
- * A mapped structure of application state value controllers.
- * */
-export type ApplicationStateValueStructureController<StructureType extends Record<string, any>> = {
-    /**
-     * The resolved value structure.
-     * */
-    valueStructure: StructureType;
-    /**
-     * Per-field change handlers for the structure.
-     * */
-    onChangeStructure: Record<keyof StructureType, (newValue: any) => void>;
-};
-/**
- * Use an object that is a collection of application state value controllers.
- *
- * @param idStructure - Map of structure keys to identifiers.
- * @returns Controller with the resolved values and per-field change handlers.
- * */
-export declare const useApplicationStateValueStructure: <StructureType extends Record<string, any>>(idStructure: Record<keyof StructureType, ApplicationStateIdentifier>) => ApplicationStateValueStructureController<StructureType>;
+export declare const useApplicationStateValue: <ValueType = ApplicationStateValue>(identifier: ApplicationStateIdentifier<ValueType>) => ApplicationStateValueController<ValueType>;
 /**
  * Props for ApplicationStateProvider.
  * */
@@ -165,3 +158,4 @@ export type ApplicationStateProviderProps = PropsWithChildren<{}>;
  * @param children - React children to render in the provider.
  * */
 export declare const ApplicationStateProvider: FC<ApplicationStateProviderProps>;
+export {};

package/app/utils/ApplicationStateLoader.d.ts

@@ -4,12 +4,12 @@
  * Loader hook for remote application state values. Calls a service endpoint,
  * tracks loading/error state, and populates ApplicationState via identifiers.
  */
-import { ApplicationStateIdentifier } from "./ApplicationState";
+import { ApplicationStateIdentifier, type ApplicationStateValue, type ApplicationStateValueController } from "./ApplicationState";
 import { ServiceConfig } from "./Service";
 /**
  * Access and track the loading of an application state value.
  * */
-export type ApplicationStateLoader = {
+export type ApplicationStateLoader<ValueType = ApplicationStateValue, ArgsType extends any[] = any[]> = ApplicationStateValueController<ValueType> & {
     /**
      * Whether the current request is in flight.
      * */
@@ -27,12 +27,12 @@ export type ApplicationStateLoader = {
      *
      * @param args - Arguments to send with the request.
      * */
-    makeRemoteProcedureCall: (...args: any[]) => Promise<void>;
+    makeRemoteProcedureCall: (...args: ArgsType) => Promise<void>;
 };
 /**
  * The service, path and arguments to use for a remote procedure call.
  * */
-export type RemoteProcedureCall = {
+export type RemoteProcedureCall<ArgsType extends any[] = any[]> = {
     /**
      * Configuration for the target service endpoint.
      * */
@@ -44,20 +44,20 @@ export type RemoteProcedureCall = {
     /**
      * Default args to send when the call auto-runs.
      * */
-    args?: any[];
+    args?: ArgsType;
 };
 /**
  * The configuration for an application state loader.
  * */
-export type ApplicationStateLoaderConfig = {
+export type ApplicationStateLoaderConfig<ValueType = ApplicationStateValue, ArgsType extends any[] = any[]> = {
     /**
      * Identifier for the value to update in application state.
      * */
-    identifier: ApplicationStateIdentifier;
+    identifier: ApplicationStateIdentifier<ValueType>;
     /**
      * RPC target configuration and arguments.
      * */
-    remoteProcedureCall: RemoteProcedureCall;
+    remoteProcedureCall: RemoteProcedureCall<ArgsType>;
     /**
      * Clear the application state value on error.
      *
@@ -80,7 +80,12 @@ export type ApplicationStateLoaderConfig = {
 /**
  * Load, track and access an application state value.
  *
+ * The returned object intentionally combines the remote-loading lifecycle with
+ * the same stable local controller contract as
+ * {@link useApplicationStateValue}. That keeps a loader-backed state value
+ * usable like normal React state once it has been identified.
+ *
  * @param config - Loader configuration for state identifier and RPC details.
  * @returns Loader controls and request state.
  * */
-export declare const useApplicationStateLoader: (config: ApplicationStateLoaderConfig) => ApplicationStateLoader;
+export declare const useApplicationStateLoader: <ValueType = ApplicationStateValue, ArgsType extends any[] = any[]>(config: ApplicationStateLoaderConfig<ValueType, ArgsType>) => ApplicationStateLoader<ValueType, ArgsType>;

package/app/utils/Route.d.ts

@@ -119,6 +119,11 @@ export type RouteContextType = {
      * Whether this route is the top-level router.
      */
     isTopLevel: boolean;
+    /**
+     * Absolute matched path used as the base for relative navigation at this
+     * route level.
+     */
+    adapterBasePath: string;
     /**
      * Adapter driving route updates.
      */
@@ -148,7 +153,7 @@ export declare const useRouteContext: () => RouteContextType;
  * @param adapter - RouteAdapter to normalize.
  * @returns Adapter with relative-aware `push` and `replace`.
  */
-export declare const wrapRouteAdapterWithPathResolver: (adapter: RouteAdapter) => RouteAdapter;
+export declare const wrapRouteAdapterWithPathResolver: (adapter: RouteAdapter, getBasePath?: () => string) => RouteAdapter;
 /**
  * RouteProvider props.
  */

package/{chunk-QXYUXJKM.js → chunk-BSHQIRBV.js}

@@ -1,4 +1,4 @@
-import { parseTemplate, validateAreas } from './chunk-UD2ALOCE.js';
+import { parseTemplate, validateAreas } from './chunk-K4R2PFNG.js';
 
 // src/app/utils/EasyLayout.tsx
 var getPascalCaseAreaName = (area) => {

package/{chunk-UD2ALOCE.js → chunk-K4R2PFNG.js}

@@ -552,7 +552,8 @@ var RouteContext = createContext({
   parentPath: "",
   parentPathInternal: "",
   params: {},
-  isTopLevel: true
+  isTopLevel: true,
+  adapterBasePath: "/"
 });
 var {
   /**
@@ -565,27 +566,42 @@ var {
   Consumer: RouteContextConsumer
 } = RouteContext;
 var useRouteContext = () => useContext(RouteContext);
-var wrappedRouteAdapterCache = /* @__PURE__ */ new WeakMap();
-var wrapRouteAdapterWithPathResolver = (adapter) => {
+var wrapRouteAdapterWithPathResolver = (adapter, getBasePath = () => adapter.getPath()) => {
   if (!adapter.push && !adapter.replace) {
     return adapter;
   }
-  const cachedAdapter = wrappedRouteAdapterCache.get(adapter);
-  if (cachedAdapter) {
-    return cachedAdapter;
-  }
   const wrappedAdapter = {
     ...adapter,
     push: adapter.push ? (path, title) => {
-      adapter.push?.(resolveRouteAdapterPath(adapter.getPath(), path), title);
+      adapter.push?.(resolveRouteAdapterPath(getBasePath(), path), title);
     } : void 0,
     replace: adapter.replace ? (path, title) => {
-      adapter.replace?.(resolveRouteAdapterPath(adapter.getPath(), path), title);
+      adapter.replace?.(resolveRouteAdapterPath(getBasePath(), path), title);
     } : void 0
   };
-  wrappedRouteAdapterCache.set(adapter, wrappedAdapter);
   return wrappedAdapter;
 };
+var getAdapterBasePath = (currentPath) => {
+  const normalizedPath = String(currentPath ?? "").trim();
+  if (normalizedPath === "") {
+    return "/";
+  }
+  const [pathOnly] = normalizedPath.split(/[?#]/, 1);
+  return pathOnly || "/";
+};
+var getMatchedRouteBasePath = (currentPath, matchedRoutePath) => {
+  const currentPathSegments = getPathArray(
+    getAdapterBasePath(currentPath),
+    PATH_DELIMITER,
+    true,
+    true,
+    false,
+    false
+  );
+  const matchedRouteSegments = getPathArray(matchedRoutePath);
+  const resolvedSegments = currentPathSegments.slice(0, matchedRouteSegments.length);
+  return resolvedSegments.length > 0 ? `/${resolvedSegments.join(PATH_DELIMITER)}` : "/";
+};
 var getWindow2 = () => {
   if (typeof globalThis === "undefined") {
     return void 0;
@@ -645,6 +661,10 @@ var RouteProvider = ({
   const [currentPath, setCurrentPath] = useState(
     initialPath ?? normalizedAdapter.getPath()
   );
+  const adapterBasePath = useMemo(
+    () => getAdapterBasePath(currentPath),
+    [currentPath]
+  );
   useEffect(() => {
     return normalizedAdapter.subscribe((nextPath) => {
       setCurrentPath(nextPath);
@@ -657,9 +677,10 @@ var RouteProvider = ({
       parentPathInternal: "",
       params: {},
       isTopLevel: true,
+      adapterBasePath,
       adapter: normalizedAdapter
     }),
-    [currentPath, normalizedAdapter]
+    [currentPath, adapterBasePath, normalizedAdapter]
   );
   return /* @__PURE__ */ jsx(RouteContextProvider, { value: contextValue, children });
 };
@@ -677,6 +698,7 @@ var RouteMatcher = ({
     parentPath = "",
     parentPathInternal = "",
     params: parentParams = {},
+    adapterBasePath: inheritedAdapterBasePath = "/",
     adapter
   } = useRouteContext();
   const targetCurrentPath = useMemo(
@@ -722,6 +744,14 @@ var RouteMatcher = ({
     }),
     [parentParams, matchedRoute]
   );
+  const matchedAdapterBasePath = useMemo(
+    () => matchedRoute ? getMatchedRouteBasePath(targetCurrentPath, matchedRoute.fullPath) : inheritedAdapterBasePath,
+    [targetCurrentPath, matchedRoute, inheritedAdapterBasePath]
+  );
+  const scopedAdapter = useMemo(
+    () => adapter ? wrapRouteAdapterWithPathResolver(adapter, () => matchedAdapterBasePath) : adapter,
+    [adapter, matchedAdapterBasePath]
+  );
   const newRouteContext = useMemo(
     () => ({
       currentWindowPath: targetCurrentPath,
@@ -729,9 +759,17 @@ var RouteMatcher = ({
       parentPathInternal: matchedRoute?.fullPath ?? parentPathInternal,
       params,
       isTopLevel: false,
-      adapter
+      adapterBasePath: matchedAdapterBasePath,
+      adapter: scopedAdapter
     }),
-    [targetCurrentPath, matchedRoute, parentPathInternal, params, adapter]
+    [
+      targetCurrentPath,
+      matchedRoute,
+      parentPathInternal,
+      params,
+      matchedAdapterBasePath,
+      scopedAdapter
+    ]
   );
   useEffect(() => {
     if (onParamsChange) {

package/native/index.js

@@ -1,5 +1,5 @@
 import { computeTrackPixels } from '../chunk-TJFTWPXQ.js';
-import { createFormRenderer, createHistoryBackHandler, buildHistoryPath, AutoFormView, AutoForm, parseTemplate, validateAreas, computeAreaBounds, parseHistoryPath, createMemoryHistory, createBrowserRouteAdapter, Route, createRouteAdapterFromHistory } from '../chunk-UD2ALOCE.js';
+import { createFormRenderer, createHistoryBackHandler, buildHistoryPath, AutoFormView, AutoForm, parseTemplate, validateAreas, computeAreaBounds, parseHistoryPath, createMemoryHistory, useRouteContext, createBrowserRouteAdapter, Route, createRouteAdapterFromHistory } from '../chunk-K4R2PFNG.js';
 import { ERROR_MESSAGE_CONSTANTS } from '../chunk-3HVYVX3S.js';
 import '../chunk-2JDOM6PB.js';
 import '../chunk-I2KLQ2HA.js';
@@ -675,6 +675,33 @@ var createNativeHistory = (options = {}) => {
   };
 };
 var createNativeBackHandler = (history) => createHistoryBackHandler(history);
+var NavButton = ({
+  path,
+  replace = false,
+  onPress,
+  disabled,
+  children,
+  ...other
+}) => {
+  const { adapter } = useRouteContext();
+  const onPressInternal = (event) => {
+    onPress?.(event);
+    if (disabled || event?.defaultPrevented) {
+      return;
+    }
+    const navigate = replace ? adapter?.replace : adapter?.push;
+    navigate?.(path);
+  };
+  return createElement(
+    Pressable,
+    {
+      ...other,
+      disabled,
+      onPress: onPressInternal
+    },
+    children
+  );
+};
 var createNativeHardwareBackHandler = (adapter) => {
   return () => {
     if (adapter.canGoBack?.()) {
@@ -762,4 +789,4 @@ var Route2 = (props) => {
   ) : /* @__PURE__ */ jsx(Route, { ...routeProps });
 };
 
-export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm2 as AutoForm, AutoFormView2 as AutoFormView, Button, ErrorMessage, FieldWrapper, NativeEasyLayoutView, Route2 as Route, createNativeBackHandler, createNativeFormRenderer, createNativeHardwareBackHandler, createNativeHistory, createNativeRouteBackIntegration, makeNativeEasyLayout, mapNativeURLToPath, nativeAutoField, nativeSuite, registerNativeHardwareBackHandler, useNativeEasyLayout };
+export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm2 as AutoForm, AutoFormView2 as AutoFormView, Button, ErrorMessage, FieldWrapper, NativeEasyLayoutView, NavButton, Route2 as Route, createNativeBackHandler, createNativeFormRenderer, createNativeHardwareBackHandler, createNativeHistory, createNativeRouteBackIntegration, makeNativeEasyLayout, mapNativeURLToPath, nativeAutoField, nativeSuite, registerNativeHardwareBackHandler, useNativeEasyLayout };

package/native/utils/NavButton.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @packageDocumentation
+ *
+ * Native intra-application navigation button.
+ */
+import type { FC } from "react";
+import { type PressableProps } from "react-native";
+/**
+ * Props for {@link NavButton}.
+ */
+export type NavButtonProps = PressableProps & {
+    /** Relative or absolute Voltra route path. */
+    path: string;
+    /** Use adapter `replace` instead of `push` when true. */
+    replace?: boolean;
+};
+/**
+ * Render a pressable control that navigates within the current Voltra app.
+ *
+ * Relative paths resolve from the route context where this component renders.
+ *
+ * @param props - Pressable props plus the destination route path.
+ * @returns Pressable element wired to the current route adapter.
+ */
+export declare const NavButton: FC<NavButtonProps>;

package/native/utils/index.d.ts

@@ -13,6 +13,11 @@ export * from "./EasyLayout";
  * @group Layout and Navigation
  */
 export * from "./History";
+/**
+ * @category native
+ * @group Layout and Navigation
+ */
+export * from "./NavButton";
 /**
  * @category native
  * @group Layout and Navigation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resistdesign/voltra",
-  "version": "3.0.0-alpha.47",
+  "version": "3.0.0-alpha.49",
   "description": "With our powers combined!",
   "homepage": "https://voltra.app",
   "repository": "git@github.com:resistdesign/voltra.git",

package/web/index.js

@@ -1,7 +1,7 @@
-import { createEasyLayout } from '../chunk-QXYUXJKM.js';
-import { createFormRenderer, AutoFormView, AutoForm, createBrowserRouteAdapter, Route } from '../chunk-UD2ALOCE.js';
+import { createEasyLayout } from '../chunk-BSHQIRBV.js';
+import { createFormRenderer, AutoFormView, AutoForm, useRouteContext, createBrowserRouteAdapter, Route } from '../chunk-K4R2PFNG.js';
 import { ERROR_MESSAGE_CONSTANTS } from '../chunk-3HVYVX3S.js';
-import '../chunk-2JDOM6PB.js';
+import { resolveRouteAdapterPath } from '../chunk-2JDOM6PB.js';
 import { __export, __reExport } from '../chunk-I2KLQ2HA.js';
 import { createElement, useCallback, useRef } from 'react';
 import * as styledBase from 'styled-components';
@@ -648,6 +648,39 @@ var styledFactory = {
 var getEasyLayout = (extendFrom, areasExtendFrom, options = {}) => {
   return createEasyLayout(styledFactory, extendFrom, areasExtendFrom, options);
 };
+var NavLink = ({
+  path,
+  replace = false,
+  onClick,
+  title,
+  children,
+  ...other
+}) => {
+  const { adapter, adapterBasePath } = useRouteContext();
+  const href = resolveRouteAdapterPath(adapterBasePath, path);
+  const onClickInternal = (event) => {
+    onClick?.(event);
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.altKey || event.ctrlKey || event.shiftKey) {
+      return;
+    }
+    const navigate = replace ? adapter?.replace : adapter?.push;
+    if (!navigate) {
+      return;
+    }
+    event.preventDefault();
+    navigate(path, title);
+  };
+  return createElement(
+    "a",
+    {
+      ...other,
+      href,
+      title,
+      onClick: onClickInternal
+    },
+    children
+  );
+};
 var Route2 = (props) => {
   const hasMatcherProps = typeof props.path !== "undefined" || typeof props.exact !== "undefined" || typeof props.onParamsChange !== "undefined";
   const adapterRef = useRef(null);
@@ -665,4 +698,4 @@ var Route2 = (props) => {
   ) : /* @__PURE__ */ jsx(Route, { ...routeProps });
 };
 
-export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm2 as AutoForm, AutoFormView2 as AutoFormView, ErrorMessage, FieldWrapper, Route2 as Route, createWebFormRenderer, getEasyLayout, webAutoField, webSuite };
+export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm2 as AutoForm, AutoFormView2 as AutoFormView, ErrorMessage, FieldWrapper, NavLink, Route2 as Route, createWebFormRenderer, getEasyLayout, webAutoField, webSuite };

package/web/utils/NavLink.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @packageDocumentation
+ *
+ * Web intra-application navigation link.
+ */
+import type { AnchorHTMLAttributes, FC } from "react";
+/**
+ * Props for {@link NavLink}.
+ */
+export type NavLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & {
+    /** Relative or absolute Voltra route path. */
+    path: string;
+    /** Use adapter `replace` instead of `push` when true. */
+    replace?: boolean;
+};
+/**
+ * Render an anchor-like control that navigates within the current Voltra app.
+ *
+ * Relative paths resolve from the route context where this component renders.
+ *
+ * @param props - Anchor props plus the destination route path.
+ * @returns Anchor element wired to the current route adapter.
+ */
+export declare const NavLink: FC<NavLinkProps>;

package/web/utils/index.d.ts

@@ -4,4 +4,5 @@
  * Web-only utilities.
  */
 export * from "./EasyLayout";
+export * from "./NavLink";
 export * from "./Route";