@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/{src/app → app}/utils/ApplicationState.d.ts

@@ -1,52 +1,167 @@
+/**
+ * @packageDocumentation
+ *
+ * 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}.
+ */
 import { FC, PropsWithChildren } from "react";
 /**
  * An object, nested or not, used as the identifier or identifier path for a state value.
  * */
 export interface ApplicationStateIdentifier extends Record<string, ApplicationStateIdentifier | {}> {
 }
+/**
+ * The stored value type for application state entries.
+ * */
 export type ApplicationStateValue = any;
+/**
+ * Map of state identifiers to a "modified" boolean.
+ * */
 export type ApplicationStateModificationState = Map<ApplicationStateIdentifier, boolean>;
+/**
+ * Map of state identifiers to stored values.
+ * */
 export type ApplicationState = Map<ApplicationStateIdentifier, ApplicationStateValue>;
+/**
+ * Determines the identifier shape for a specific sub-state.
+ *
+ * @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.
+ *
+ * @param subStateIdMap - Optional sub-state identifier map.
+ * @returns The identifier map or an empty identifier object.
+ * */
 export declare const getApplicationStateIdentifier: <SubStateIdStructure extends ApplicationStateIdentifier>(subStateIdMap?: SubStateIdStructure) => ApplicationStateIdentifierSubStateType<SubStateIdStructure>;
+/**
+ * Read the modification status for a specific identifier.
+ *
+ * @param identifier - The identifier to look up.
+ * @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;
+/**
+ * Read the stored value for an identifier.
+ *
+ * @param identifier - The identifier to look up.
+ * @param applicationState - The application state map.
+ * @returns The stored value, if any.
+ * */
 export declare const getApplicationStateValue: (identifier: ApplicationStateIdentifier, applicationState: ApplicationState) => ApplicationStateValue;
+/**
+ * Set the modification status for an identifier.
+ *
+ * @param identifier - The identifier to update.
+ * @param value - The new modified flag.
+ * @param modificationState - The current modification map.
+ * @returns A new modification map with the updated flag.
+ * */
 export declare const setApplicationStateModified: (identifier: ApplicationStateIdentifier, value: boolean, modificationState: ApplicationState) => ApplicationStateModificationState;
+/**
+ * Set the stored value for an identifier.
+ *
+ * @param identifier - The identifier to update.
+ * @param value - The new value to store.
+ * @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;
+/**
+ * Context state and updater hooks for application state.
+ * */
 export type ApplicationStateContextType = {
+    /**
+     * Map of identifiers to modified flags.
+     * */
     modified: ApplicationStateModificationState;
+    /**
+     * Map of identifiers to stored values.
+     * */
     value: ApplicationState;
+    /**
+     * Replace the current application state map.
+     * */
     onChange: (newValue: ApplicationState) => void;
+    /**
+     * Replace the current modification state map.
+     * */
     setModified: (newValue: ApplicationStateModificationState) => void;
 };
+/**
+ * React context for application state and modification tracking.
+ * */
 export declare const ApplicationStateContext: import("react").Context<ApplicationStateContextType>;
 /**
  * Used to access and update application state values.
  * */
 export type ApplicationStateValueController = {
+    /**
+     * Whether the value is marked as modified.
+     * */
     modified: boolean;
+    /**
+     * The current value for the identifier.
+     * */
     value: ApplicationStateValue;
+    /**
+     * Update the current value.
+     *
+     * @param value - The new value to store.
+     * */
     onChange: (value: ApplicationStateValue) => void;
+    /**
+     * Update the modified flag.
+     *
+     * @param value - The new modified flag.
+     * */
     setModified: (value: boolean) => void;
 };
 /**
  * Get and set an application state value by identifier.
+ *
+ * @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>;
+/**
+ * Props for ApplicationStateProvider.
+ * */
 export type ApplicationStateProviderProps = PropsWithChildren<{}>;
 /**
  * Provide a context container for application state.
+ *
+ * @param children - React children to render in the provider.
  * */
 export declare const ApplicationStateProvider: FC<ApplicationStateProviderProps>;

package/{src/app → app}/utils/ApplicationStateLoader.d.ts

@@ -1,27 +1,62 @@
+/**
+ * @packageDocumentation
+ *
+ * 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 { ServiceConfig } from "./Service";
 /**
  * Access and track the loading of an application state value.
  * */
 export type ApplicationStateLoader = {
+    /**
+     * Whether the current request is in flight.
+     * */
     loading: boolean;
+    /**
+     * The most recent error, if any.
+     * */
     latestError: any;
+    /**
+     * Force a reload by invalidating the internal cache key.
+     * */
     invalidate: () => void;
+    /**
+     * Trigger a remote procedure call with the provided args.
+     *
+     * @param args - Arguments to send with the request.
+     * */
     makeRemoteProcedureCall: (...args: any[]) => Promise<void>;
 };
 /**
  * The service, path and arguments to use for a remote procedure call.
  * */
 export type RemoteProcedureCall = {
+    /**
+     * Configuration for the target service endpoint.
+     * */
     serviceConfig: ServiceConfig;
+    /**
+     * Path to the RPC handler.
+     * */
     path: string;
+    /**
+     * Default args to send when the call auto-runs.
+     * */
     args?: any[];
 };
 /**
  * The configuration for an application state loader.
  * */
 export type ApplicationStateLoaderConfig = {
+    /**
+     * Identifier for the value to update in application state.
+     * */
     identifier: ApplicationStateIdentifier;
+    /**
+     * RPC target configuration and arguments.
+     * */
     remoteProcedureCall: RemoteProcedureCall;
     /**
      * Clear the application state value on error.
@@ -31,6 +66,8 @@ export type ApplicationStateLoaderConfig = {
     resetOnError?: boolean;
     /**
      * Called each time the application state value has been loaded.
+     *
+     * @param success - Whether the request completed successfully.
      * */
     onLoadComplete?: (success: boolean) => void;
     /**
@@ -42,5 +79,8 @@ export type ApplicationStateLoaderConfig = {
 };
 /**
  * Load, track and access an application state value.
+ *
+ * @param config - Loader configuration for state identifier and RPC details.
+ * @returns Loader controls and request state.
  * */
 export declare const useApplicationStateLoader: (config: ApplicationStateLoaderConfig) => ApplicationStateLoader;

package/app/utils/Controller.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Safely access and update a value in a parent object by its key.
+ *
+ * @param parentValue - Parent object or array that owns the value.
+ * @param key - Object key or array index to access.
+ * @param onParentValueChange - Callback invoked with the updated parent value.
+ * @param isArrayIndex - Whether the key refers to an array index.
+ * @returns Tuple of current value and change handler.
+ * */
+export declare const useController: (parentValue: any, key: string | number, onParentValueChange: (value: any) => void, isArrayIndex?: boolean) => any[];

package/app/utils/Debug.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compute dependency indexes whose values changed between renders.
+ *
+ * @param prevDeps - Dependencies from the previous render.
+ * @param nextDeps - Dependencies from the current render.
+ * @returns Indexes that changed.
+ * */
+export declare const getChangedDependencyIndexes: (prevDeps: any[], nextDeps: any[]) => number[];
+/**
+ * Examines the changes in the dependencies of a hook.
+ *
+ * @param dependencies - Current dependency array to monitor.
+ * */
+export declare const useDebugDependencies: (dependencies: any[]) => void;

package/app/utils/EasyLayout.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @packageDocumentation
+ *
+ * Render-agnostic EasyLayout helpers (template parsing + component wiring).
+ */
+import type { ComponentType, PropsWithChildren } from "react";
+/**
+ * FC With Children
+ */
+export type FCWithChildren = ComponentType<PropsWithChildren>;
+/**
+ * Component Map
+ */
+export type ComponentMap = Record<string, FCWithChildren>;
+/**
+ * Layout Components
+ */
+export type LayoutComponents = {
+    /**
+     * The generated layout container component.
+     */
+    layout: FCWithChildren;
+    /**
+     * Map of PascalCase area components keyed by area name.
+     */
+    areas: ComponentMap;
+};
+/**
+ * Optional spacing controls for generated layout CSS.
+ */
+export type EasyLayoutSpacing = {
+    /**
+     * CSS gap value for grid tracks.
+     * If a number is provided, `px` is assumed.
+     */
+    gap?: number | string;
+    /**
+     * CSS padding value for the layout container.
+     * If a number is provided, `px` is assumed.
+     */
+    padding?: number | string;
+};
+/**
+ * Convert a kebab-cased area name into PascalCase.
+ *
+ * @param area - Area name from the layout template.
+ * @returns PascalCase version of the area name.
+ */
+export declare const getPascalCaseAreaName: (area: string) => string;
+/**
+ * Parse a layout template string into area names and CSS.
+ *
+ * @param layout - Raw layout template string.
+ * @param spacing - Optional gap/padding CSS settings.
+ * @returns Area names and CSS for the grid template.
+ */
+export declare const getEasyLayoutTemplateDetails: (layout?: string, spacing?: EasyLayoutSpacing) => {
+    areasList: string[];
+    css: string;
+};
+/**
+ * Configuration for building EasyLayout components.
+ */
+export type EasyLayoutFactoryConfig<TComponent> = {
+    /**
+     * Create a layout component with optional base component + css string.
+     */
+    createLayout: (options: {
+        base?: TComponent;
+        css: string;
+    }) => FCWithChildren;
+    /**
+     * Create an area component with optional base component + grid area name.
+     */
+    createArea: (options: {
+        base?: TComponent;
+        area: string;
+    }) => FCWithChildren;
+};
+/**
+ * Build layout and area components from a template using a provided factory.
+ *
+ * @param config - Factory implementations for layout and areas.
+ * @param extendFrom - Optional base component for the layout container.
+ * @param areasExtendFrom - Optional base component for area components.
+ * @param spacing - Optional gap/padding CSS settings for generated layout styles.
+ * @returns Tagged template helper that builds layout components.
+ */
+export declare const createEasyLayout: <TComponent>(config: EasyLayoutFactoryConfig<TComponent>, extendFrom?: TComponent, areasExtendFrom?: TComponent, spacing?: EasyLayoutSpacing) => ((layoutTemplate: TemplateStringsArray, ...expressions: any[]) => LayoutComponents);

package/app/utils/History.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @packageDocumentation
+ *
+ * Platform-agnostic history state machine and path helpers.
+ */
+/**
+ * A normalized location entry in history.
+ */
+export type HistoryLocation = {
+    /**
+     * Normalized pathname. Always starts with `/`.
+     */
+    path: string;
+    /**
+     * Optional query string (including leading `?`).
+     */
+    search?: string;
+    /**
+     * Optional hash fragment (including leading `#`).
+     */
+    hash?: string;
+    /**
+     * Optional app-defined state payload.
+     */
+    state?: unknown;
+    /**
+     * Stable entry key, unique per history entry.
+     */
+    key: string;
+};
+/**
+ * An entry inside the history stack.
+ */
+export type HistoryEntry = {
+    location: HistoryLocation;
+};
+/**
+ * History listener callback.
+ */
+export type HistoryListener = (location: HistoryLocation) => void;
+/**
+ * Path parts extracted from a route string.
+ */
+export type HistoryPathParts = Pick<HistoryLocation, "path" | "search" | "hash">;
+/**
+ * Shared history controller interface.
+ *
+ * This is intentionally platform-agnostic. Web/native adapters can translate
+ * platform events into calls on this interface.
+ */
+export type HistoryController = {
+    /**
+     * Current location.
+     */
+    location: HistoryLocation;
+    /**
+     * Number of entries in the history stack.
+     */
+    length: number;
+    /**
+     * Active entry index in the history stack.
+     */
+    index: number;
+    /**
+     * Push a new history entry.
+     *
+     * `replaceSearch` controls behavior when `path` does not include `?query`:
+     * - `false`/unset: carry forward current `search`.
+     * - `true`: clear current `search`.
+     */
+    push: (path: string, opts?: {
+        state?: unknown;
+        replaceSearch?: boolean;
+    }) => void;
+    /**
+     * Replace the current history entry.
+     *
+     * `replaceSearch` follows the same behavior as {@link push}.
+     */
+    replace: (path: string, opts?: {
+        state?: unknown;
+        replaceSearch?: boolean;
+    }) => void;
+    /**
+     * Move by delta within the history stack.
+     */
+    go: (delta: number) => void;
+    /**
+     * Move back one entry.
+     */
+    back: () => void;
+    /**
+     * Move forward one entry.
+     */
+    forward: () => void;
+    /**
+     * Subscribe to location changes.
+     */
+    listen: (listener: HistoryListener) => () => void;
+};
+/**
+ * Parse a path-like value into normalized path/search/hash parts.
+ *
+ * Supports full URLs and path-only strings.
+ *
+ * Examples:
+ * ```ts
+ * parseHistoryPath("voltra://host/books/42?tab=info#top")
+ * // { path: "/books/42", search: "?tab=info", hash: "#top" }
+ *
+ * parseHistoryPath("books/42")
+ * // { path: "/books/42" }
+ * ```
+ */
+export declare const parseHistoryPath: (inputPath: string) => HistoryPathParts;
+/**
+ * Build a path string from normalized path/search/hash parts.
+ *
+ * Missing prefixes are normalized:
+ * - `search: "q=1"` -> `?q=1`
+ * - `hash: "section"` -> `#section`
+ *
+ * Example:
+ * ```ts
+ * buildHistoryPath({ path: "books/42", search: "tab=info" })
+ * // "/books/42?tab=info"
+ * ```
+ */
+export declare const buildHistoryPath: ({ path, search, hash, }: HistoryPathParts) => string;
+/**
+ * Create an in-memory history implementation.
+ *
+ * @param initialPath - Initial path used for the first entry.
+ * @returns History controller backed by an in-memory stack.
+ *
+ * Behavior notes:
+ * - `go(delta)` clamps to valid bounds `[0, length - 1]`.
+ * - `push` after `back` drops forward entries.
+ * - listeners are called only when active location changes.
+ *
+ * Example:
+ * ```ts
+ * const history = createMemoryHistory("/home?tab=all");
+ * history.push("/details/42");
+ * history.back();
+ * ```
+ */
+export declare const createMemoryHistory: (initialPath?: string) => HistoryController;

package/app/utils/Route.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @packageDocumentation
+ *
+ * Render-agnostic routing helpers with nested Route contexts.
+ * Supply a RouteAdapter via RouteProvider or a platform-specific wrapper.
+ */
+import React, { PropsWithChildren } from "react";
+/**
+ * Platform adapter that supplies the current path and change notifications.
+ */
+export type RouteAdapter = {
+    /** Read the current path. */
+    getPath: () => string;
+    /** Subscribe to path changes. */
+    subscribe: (listener: (path: string) => void) => () => void;
+    /** Optional navigation helper for adapters that can push state. */
+    push?: (path: string, title?: string) => void;
+    /** Optional navigation helper for adapters that can replace state. */
+    replace?: (path: string, title?: string) => void;
+};
+/**
+ * Supported query value types for route serialization.
+ */
+export type RouteQueryValue = string | number | boolean | null | undefined | Array<string | number | boolean | null | undefined>;
+/**
+ * Query string map for route serialization.
+ */
+export type RouteQuery = Record<string, RouteQueryValue>;
+/**
+ * Create a manual adapter for non-DOM runtimes (e.g., React Native).
+ *
+ * Call `updatePath` when navigation changes.
+ */
+export declare const createManualRouteAdapter: (initialPath?: string) => {
+    adapter: RouteAdapter;
+    updatePath: (nextPath: string) => void;
+};
+/**
+ * Build a query string from a query object.
+ *
+ * @param query - Query string map.
+ * @returns Encoded query string without the leading `?`.
+ */
+export declare const buildQueryString: (query?: RouteQuery) => string;
+/**
+ * Build a path string from segments and optional query params.
+ *
+ * @param segments - Ordered route segments.
+ * @param query - Optional query parameters.
+ * @returns Path string with optional query string.
+ */
+export declare const buildRoutePath: (segments: Array<string | number>, query?: RouteQuery) => string;
+/**
+ * Access values for the current Route.
+ */
+export type RouteContextType = {
+    /**
+     * Current window pathname (top-level) or inherited path (nested).
+     */
+    currentWindowPath: string;
+    /**
+     * The parent path for this route level.
+     */
+    parentPath: string;
+    /**
+     * Aggregated route params from parent and current routes.
+     */
+    params: Record<string, any>;
+    /**
+     * Whether this route is the top-level router.
+     */
+    isTopLevel: boolean;
+    /**
+     * Adapter driving route updates.
+     */
+    adapter?: RouteAdapter;
+};
+/**
+ * React context for route state and parameters.
+ */
+export declare const RouteContext: React.Context<RouteContextType>;
+export declare const RouteContextProvider: React.Provider<RouteContextType>, RouteContextConsumer: React.Consumer<RouteContextType>;
+/**
+ * Access Route path and parameter information.
+ *
+ * @returns The current route context.
+ */
+export declare const useRouteContext: () => RouteContextType;
+/**
+ * RouteProvider props.
+ */
+export type RouteProviderProps = PropsWithChildren<{
+    /** Adapter that supplies path updates. */
+    adapter: RouteAdapter;
+    /** Optional initial path override. */
+    initialPath?: string;
+}>;
+/**
+ * Provide a RouteAdapter to the routing context.
+ *
+ * @param props - Provider props with adapter and children.
+ */
+export declare const RouteProvider: ({ adapter, initialPath, children, }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Configure the Route.
+ */
+export type RouteProps<ParamsType extends Record<string, any>> = {
+    /**
+     * Route path pattern, using `:` for params.
+     */
+    path?: string;
+    /**
+     * Callback when params update for this route.
+     *
+     * @param params - Resolved params for this route.
+     */
+    onParamsChange?: (params: ParamsType) => void;
+    /**
+     * Require an exact match for the route path.
+     */
+    exact?: boolean;
+};
+/**
+ * Organize nested routes with parameters.
+ *
+ * @typeParam ParamsType - Param shape for this route.
+ * @param props - Route props including path, params handler, and children.
+ */
+export declare const Route: <ParamsType extends Record<string, any>>({ path, onParamsChange, exact, children, }: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element | null;

package/app/utils/RouteHistory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @packageDocumentation
+ *
+ * Bridge helpers between HistoryController and RouteAdapter.
+ */
+import type { HistoryController } from "./History";
+import type { RouteAdapter } from "./Route";
+/**
+ * Create a RouteAdapter from a shared history controller.
+ *
+ * Route matching is path-based, so this adapter surfaces `location.path`
+ * (query/hash are intentionally omitted from Route context matching).
+ *
+ * Adapter navigation methods call history with `replaceSearch: true` so a
+ * path-only navigation does not accidentally retain a previous query string.
+ *
+ * Example:
+ * ```ts
+ * const history = createMemoryHistory("/app/books/42?tab=summary");
+ * const adapter = createRouteAdapterFromHistory(history);
+ * adapter.push?.("/app/books/99");
+ * // history.location.path === "/app/books/99"
+ * // history.location.search === undefined
+ * ```
+ */
+export declare const createRouteAdapterFromHistory: (history: HistoryController) => RouteAdapter;