@resistdesign/voltra 3.0.0-alpha.5 → 3.0.0-alpha.51

package/app/utils/Route.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @packageDocumentation
+ *
+ * Render-agnostic routing helpers with nested Route contexts.
+ * Supply a RouteAdapter via RouteProvider or use root Route provider mode.
+ */
+import { PropsWithChildren } from "react";
+import { type UniversalRouteIngress } from "./UniversalRouteAdapter";
+/**
+ * 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`/`replace` paths are normalized through shared routing utils:
+     * absolute (`/x`), relative (`x`, `./x`, `../x`), and empty (`""` => `/`).
+     */
+    push?: (path: string, title?: string) => void;
+    /** Optional navigation helper for adapters that can replace state. */
+    replace?: (path: string, title?: string) => void;
+    /** Optional navigation helper for adapters that can go backward. */
+    back?: () => void;
+    /** Optional capability check for backward navigation. */
+    canGoBack?: () => boolean;
+};
+/**
+ * Optional runtime integration for root Route provider mode.
+ *
+ * Use this to layer platform-specific side effects (for example, native
+ * hardware back wiring) without coupling core app routing to a platform API.
+ */
+export type RouteRuntimeIntegration = {
+    /**
+     * Start integration against the active adapter.
+     *
+     * Return a cleanup function when teardown is required.
+     */
+    setup: (adapter: RouteAdapter) => void | (() => 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>;
+/**
+ * Route path matcher config.
+ */
+export type RoutePathConfig = {
+    /** Path pattern, using `:` for params. */
+    path: string;
+    /** Optional exact-match override for this path entry. */
+    exact?: boolean;
+};
+/**
+ * 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`.
+ *
+ * `parentPath` is the consumer-facing route pattern for the currently matched
+ * parent route chain, expressed as plain slash-delimited segments such as
+ * `app/books/:id`.
+ *
+ * `parentPathInternal` carries the same logical route pattern in the
+ * JSON-serialized segment format used by the shared routing internals. Most
+ * consumers should prefer `parentPath`.
+ */
+export type RouteContextType = {
+    /**
+     * Current window pathname (top-level) or inherited path (nested).
+     */
+    currentWindowPath: string;
+    /**
+     * Consumer-facing parent route pattern for this route level.
+     *
+     * Example: `app/books/:id`
+     */
+    parentPath: string;
+    /**
+     * Internal parent route pattern used by routing utilities and matcher logic.
+     *
+     * Example: `"app"/"books"/":id"`
+     */
+    parentPathInternal: string;
+    /**
+     * Aggregated route params from parent and current routes.
+     */
+    params: Record<string, any>;
+    /**
+     * 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.
+     */
+    adapter?: RouteAdapter;
+};
+/**
+ * React context for route state and parameters.
+ */
+export declare const RouteContext: import("react").Context<RouteContextType>;
+export declare const RouteContextProvider: import("react").Provider<RouteContextType>, RouteContextConsumer: import("react").Consumer<RouteContextType>;
+/**
+ * Access Route path and parameter information.
+ *
+ * Use `parentPath` for app-facing route logic. `parentPathInternal` is exposed
+ * so advanced integrations can align with the internal routing helpers when
+ * needed.
+ *
+ * @returns The current route context.
+ */
+export declare const useRouteContext: () => RouteContextType;
+/**
+ * Wrap a RouteAdapter so `push` and `replace` resolve relative paths.
+ *
+ * This preserves existing adapter behavior for subscriptions/back navigation,
+ * while normalizing path syntax consistently across web/native/app wrappers.
+ *
+ * @param adapter - RouteAdapter to normalize.
+ * @returns Adapter with relative-aware `push` and `replace`.
+ */
+export declare const wrapRouteAdapterWithPathResolver: (adapter: RouteAdapter, getBasePath?: () => string) => RouteAdapter;
+/**
+ * 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(s), using `:` for params.
+     */
+    path?: string | (string | RoutePathConfig)[];
+    /**
+     * 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;
+    /**
+     * Optional initial path override for root provider mode only.
+     */
+    initialPath?: string;
+    /**
+     * Optional adapter override for root provider mode only.
+     */
+    adapter?: RouteAdapter;
+    /**
+     * Optional external URL ingress for root provider mode only.
+     */
+    ingress?: UniversalRouteIngress;
+    /**
+     * Optional runtime integration hook for root provider mode only.
+     */
+    runtimeIntegration?: RouteRuntimeIntegration;
+};
+export declare const Route: <ParamsType extends Record<string, any>>(props: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element | null;

package/app/utils/RouteHistory.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ * Relative navigation input is resolved against the current history path.
+ *
+ * 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;

package/app/utils/Service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The HTTP service configuration, including authorization, to be used for a service call.
+ * */
+export type ServiceConfig = {
+    /**
+     * URL protocol (http or https).
+     * */
+    protocol: string;
+    /**
+     * Service domain or host.
+     * */
+    domain: string;
+    /**
+     * Optional port override.
+     * */
+    port?: number;
+    /**
+     * Base path to prefix all request paths.
+     * */
+    basePath?: string;
+    /**
+     * Bearer token for authorization.
+     * */
+    authorization?: string;
+};
+/**
+ * Build the full URL for a service call from config pieces.
+ *
+ * @param protocol - URL protocol (http or https).
+ * @param domain - Service domain or host.
+ * @param basePath - Base path to prefix all requests.
+ * @param path - Endpoint path to append.
+ * @param port - Optional port override.
+ * @returns Fully qualified URL string.
+ */
+export declare const getFullUrl: (protocol: string, domain: string, basePath?: string, path?: string, port?: number) => string;
+/**
+ * Send a POST request to a service endpoint with JSON arguments.
+ *
+ * @param config - Service configuration for the request.
+ * @param path - Endpoint path to call.
+ * @param args - JSON-serializable arguments to send.
+ * @returns Parsed JSON response.
+ */
+export declare const sendServiceRequest: (config: ServiceConfig, path?: string, args?: any[]) => Promise<any>;

package/app/utils/TypeInfoORMAPIUtils.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @packageDocumentation
+ *
+ * Hook utilities that wrap a {@link TypeInfoORMClientAPI} with request state
+ * tracking.
+ * Each method returns a request id and updates loading/data/error state per method.
+ */
+import { TypeInfoORMClientAPI, TypeInfoORMServiceError } from "../../common/TypeInfoORM";
+import type { ExpandComplexType } from "../../common/HelperTypes";
+/**
+ * Sync request handler that returns a request id.
+ *
+ * @param args - Arguments for the API method.
+ * @returns Request id for tracking.
+ * */
+export type SyncRequestHandler<ArgsType extends any[]> = (...args: ArgsType) => string;
+/**
+ * Synchronous wrapper API that returns a request id for each method.
+ * */
+export type TypeInfoORMServiceAPI = ExpandComplexType<{
+    [K in keyof TypeInfoORMClientAPI]: TypeInfoORMClientAPI[K] extends (...args: infer A) => Promise<any> ? SyncRequestHandler<A> : TypeInfoORMClientAPI[K];
+}>;
+/**
+ * Request state for a single TypeInfoORM API method.
+ * */
+export type BaseTypeInfoORMAPIRequestState = {
+    /**
+     * Whether the request is currently loading.
+     * */
+    loading?: boolean;
+    /**
+     * Latest successful response data.
+     * */
+    data?: any;
+    /**
+     * Latest request error.
+     * */
+    error?: TypeInfoORMServiceError;
+};
+/**
+ * Request state plus tracking of active request ids.
+ * */
+export type TypeInfoORMAPIRequestState = ExpandComplexType<BaseTypeInfoORMAPIRequestState & {
+    /**
+     * Active request ids for this method.
+     * */
+    activeRequests?: string[];
+}>;
+type RequestStateChangeHandler = (methodName: keyof TypeInfoORMClientAPI, requestId: string, requestState: BaseTypeInfoORMAPIRequestState) => void;
+/**
+ * Request state keyed by TypeInfoORM API method.
+ */
+export type TypeInfoORMAPIState = Partial<Record<keyof TypeInfoORMClientAPI, TypeInfoORMAPIRequestState>>;
+/**
+ * Hook return shape for request state and wrapped API.
+ * */
+export type TypeInfoORMAPIController = {
+    /**
+     * Request state keyed by method name.
+     * */
+    state: TypeInfoORMAPIState;
+    /**
+     * Wrapped API that returns request ids.
+     * */
+    api: TypeInfoORMServiceAPI;
+};
+/**
+ * Execute a request and emit request state changes.
+ *
+ * @param requestId - Unique id for this request.
+ * @param args - Arguments to pass to the API method.
+ * @param typeInfoORMAPI - API instance to call.
+ * @param methodName - Method name to invoke.
+ * @param onRequestStateChange - Handler for request state updates.
+ * @returns Promise resolved when request state is updated.
+ * */
+export declare const handleRequest: (requestId: string, args: any[], typeInfoORMAPI: TypeInfoORMClientAPI, methodName: keyof TypeInfoORMClientAPI, onRequestStateChange: RequestStateChangeHandler) => Promise<void>;
+/**
+ * Create a sync handler that dispatches async requests.
+ *
+ * @param typeInfoORMAPI - API instance to call.
+ * @param methodName - Method name to invoke.
+ * @param onRequestStateChange - Handler for request state updates.
+ * @returns Sync handler that returns a request id.
+ * */
+export declare const requestHandlerFactory: (typeInfoORMAPI: TypeInfoORMClientAPI, methodName: keyof TypeInfoORMClientAPI, onRequestStateChange: RequestStateChangeHandler) => SyncRequestHandler<any>;
+/**
+ * Wrap a TypeInfoORM API instance with request tracking state.
+ *
+ * @param typeInfoORMAPI - API instance to wrap.
+ * @returns Controller with request state and wrapped API methods.
+ * */
+export declare const useTypeInfoORMAPI: (typeInfoORMAPI: TypeInfoORMClientAPI) => TypeInfoORMAPIController;
+export {};

package/app/utils/TypeInfoORMClient.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @packageDocumentation
+ *
+ * Client wrapper around the TypeInfoORM API RouteMap. Uses ServiceConfig to
+ * route requests to the server-side TypeInfoORM routes.
+ */
+import { DeleteRelationshipResults, TypeInfoORMClientAPI, TypeInfoORMAPIRoutePaths, TypeInfoORMUpdateConfig } from "../../common/TypeInfoORM";
+import { ServiceConfig } from "./Service";
+import { TypeInfoDataItem } from "../../common/TypeParsing/TypeInfo";
+import { ListItemsConfig, ListItemsResults, ListRelationshipsConfig } from "../../common/SearchTypes";
+import { BaseItemRelationshipInfo, ItemRelationshipInfo } from "../../common/ItemRelationshipInfoTypes";
+/**
+ * Client implementation of the client-safe TypeInfoORMClientAPI contract.
+ *
+ * @param config - The configuration pointing to the Type Info ORM `RouteMap`.
+ * */
+export declare class TypeInfoORMClient implements TypeInfoORMClientAPI {
+    private config;
+    /**
+     * Create a client for TypeInfoORM routes.
+     *
+     * @param config - Service configuration for the API routes.
+     */
+    constructor(config: ServiceConfig);
+    /**
+     * Dispatch a request to the configured service.
+     *
+     * @param path - Route path for the ORM method.
+     * @param args - Arguments to send in the request body.
+     * @returns Parsed response payload.
+     */
+    protected makeRequest: (path: TypeInfoORMAPIRoutePaths, args: any[]) => Promise<any>;
+    /**
+     * Create an item of the provided type.
+     *
+     * @param typeName - TypeInfo type name.
+     * @param item - Item payload to persist.
+     * @returns The created item result.
+     */
+    create: (typeName: string, item: TypeInfoDataItem) => Promise<any>;
+    /**
+     * Read an item by its primary field value.
+     *
+     * @param typeName - TypeInfo type name.
+     * @param primaryFieldValue - Primary field value to lookup.
+     * @returns The retrieved item, if found.
+     */
+    read: (typeName: string, primaryFieldValue: any, selectedFields?: (keyof TypeInfoDataItem)[]) => Promise<TypeInfoDataItem>;
+    /**
+     * Update an item by replacing it with the provided payload.
+     *
+     * @param typeName - TypeInfo type name.
+     * @param item - Updated item payload.
+     * @param updateConfig - Optional per-field operator config.
+     * @returns Whether the update succeeded.
+     */
+    update: (typeName: string, item: TypeInfoDataItem, updateConfig?: TypeInfoORMUpdateConfig) => Promise<boolean>;
+    /**
+     * Delete an item by its primary field value.
+     *
+     * @param typeName - TypeInfo type name.
+     * @param primaryFieldValue - Primary field value to delete.
+     * @returns Whether the delete succeeded.
+     */
+    delete: (typeName: string, primaryFieldValue: any) => Promise<boolean>;
+    /**
+     * List items for a given type.
+     *
+     * @param typeName - TypeInfo type name.
+     * @param config - List configuration including filters and paging.
+     * @param selectedFields - Optional fields to project.
+     * @returns List results for the query.
+     */
+    list: (typeName: string, config: ListItemsConfig, selectedFields?: (keyof TypeInfoDataItem)[]) => Promise<ListItemsResults<TypeInfoDataItem>>;
+    /**
+     * Create a relationship between items.
+     *
+     * @param relationshipItem - Relationship payload.
+     * @returns Whether the relationship was created.
+     */
+    createRelationship: (relationshipItem: BaseItemRelationshipInfo) => Promise<boolean>;
+    /**
+     * Delete a relationship between items.
+     *
+     * @param relationshipItem - Relationship payload.
+     * @returns Results describing the deletion.
+     */
+    deleteRelationship: (relationshipItem: BaseItemRelationshipInfo) => Promise<DeleteRelationshipResults>;
+    /**
+     * List relationship records matching the query.
+     *
+     * @param config - Relationship list query configuration.
+     * @returns Relationship list results.
+     */
+    listRelationships: (config: ListRelationshipsConfig) => Promise<ListItemsResults<ItemRelationshipInfo>>;
+    /**
+     * List related items for a relationship query.
+     *
+     * @param config - Relationship list query configuration.
+     * @param selectedFields - Optional fields to project on related items.
+     * @returns Related item list results.
+     */
+    listRelatedItems: (config: ListRelationshipsConfig, selectedFields?: (keyof TypeInfoDataItem)[]) => Promise<ListItemsResults<Partial<TypeInfoDataItem>>>;
+}

package/app/utils/UniversalRouteAdapter.d.ts

@@ -0,0 +1,73 @@
+import type { RouteAdapter } from "./Route";
+/**
+ * Runtime strategy for universal route adapters.
+ */
+export type UniversalRouteStrategy = "auto" | "web" | "native";
+/**
+ * Options for {@link createUniversalAdapter}.
+ */
+export type CreateUniversalAdapterOptions = {
+    /**
+     * Runtime strategy selection.
+     *
+     * - `"auto"`: use web when DOM + History API exist, else native.
+     * - `"web"`: force browser history.
+     * - `"native"`: force in-memory history.
+     *
+     * Default: `"auto"`.
+     */
+    strategy?: UniversalRouteStrategy;
+    /**
+     * Initial path used by native strategy memory history.
+     *
+     * Default: `"/"`.
+     */
+    initialPath?: string;
+    /**
+     * Optional ingress hook for native strategy.
+     *
+     * Use this to bridge deep-link systems into the adapter.
+     */
+    ingress?: UniversalRouteIngress;
+};
+/**
+ * Ingress hook for applying external URLs/paths to native strategy.
+ */
+export type UniversalRouteIngress = {
+    /**
+     * Optional initial URL/path provider.
+     */
+    getInitialURL?: () => Promise<string | null | undefined> | string | null | undefined;
+    /**
+     * Optional URL/path event subscription.
+     */
+    subscribe?: (listener: (url: string) => void) => () => void;
+    /**
+     * Incoming event application mode.
+     *
+     * Default: `"replace"`.
+     */
+    onIncomingURL?: "push" | "replace";
+    /**
+     * Optional mapper converting URL -> route path.
+     *
+     * Default maps using shared history path parsing.
+     */
+    mapURLToPath?: (url: string) => string;
+};
+/**
+ * Detect whether browser history is available at runtime.
+ */
+export declare const canUseBrowserHistory: () => boolean;
+/**
+ * Create a browser RouteAdapter backed by the History API.
+ */
+export declare const createBrowserRouteAdapter: () => RouteAdapter;
+/**
+ * Create an in-memory RouteAdapter for non-DOM runtimes.
+ */
+export declare const createNativeRouteAdapter: (initialPath?: string, ingress?: UniversalRouteIngress) => RouteAdapter;
+/**
+ * Create a runtime-selected RouteAdapter for web/native environments.
+ */
+export declare const createUniversalAdapter: (options?: CreateUniversalAdapterOptions) => RouteAdapter;

package/app/utils/easy-layout/computeAreaBounds.d.ts

@@ -0,0 +1,5 @@
+import type { AreaBounds, EasyLayoutParsed } from "./types";
+/**
+ * Compute 1-based row/column bounds for each area name.
+ */
+export declare const computeAreaBounds: (parsed: EasyLayoutParsed) => Record<string, AreaBounds>;

package/app/utils/easy-layout/computeTracks.d.ts

@@ -0,0 +1,16 @@
+import type { TrackSpec } from "./types";
+/**
+ * Input for converting track specifications into pixels.
+ */
+export type ComputeTrackPixelsInput = {
+    tracks: TrackSpec[];
+    totalPx: number;
+    gapPx?: number;
+    paddingPx?: number;
+};
+/**
+ * Compute pixel sizes for track specs.
+ *
+ * @category EasyLayout
+ */
+export declare const computeTrackPixels: ({ tracks, totalPx, gapPx, paddingPx, }: ComputeTrackPixelsInput) => number[];

package/app/utils/easy-layout/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./computeAreaBounds";
+export * from "./computeTracks";
+export * from "./parseTemplate";
+export * from "./types";
+export * from "./validateAreas";

package/app/utils/easy-layout/parseTemplate.d.ts

@@ -0,0 +1,12 @@
+import type { EasyLayoutParsed, EasyLayoutTemplate } from "./types";
+/**
+ * Parse an EasyLayout template into rows, tracks, and area names.
+ *
+ * @category EasyLayout
+ *
+ * Supported syntax:
+ * - row lines: `<area area ...>, <row-track>`
+ * - column line: `\\ <col-track> <col-track> ...`
+ * - row track is optional for parity with current behavior.
+ */
+export declare const parseTemplate: (template?: EasyLayoutTemplate) => EasyLayoutParsed;

package/app/utils/easy-layout/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @packageDocumentation
+ *
+ * Shared EasyLayout core types.
+ */
+/**
+ * Raw layout template input.
+ */
+export type EasyLayoutTemplate = string;
+/**
+ * Supported track units.
+ */
+export type TrackUnit = {
+    kind: "fr";
+    value: number;
+} | {
+    kind: "px";
+    value: number;
+} | {
+    kind: "pct";
+    value: number;
+};
+/**
+ * Track specification for rows/columns.
+ */
+export type TrackSpec = TrackUnit;
+/**
+ * Parsed layout representation shared by web/native implementations.
+ */
+export type EasyLayoutParsed = {
+    areaGrid: string[][];
+    rowTracks: TrackSpec[];
+    colTracks: TrackSpec[];
+    areaNames: string[];
+};
+/**
+ * 1-based area bounds in row/column space.
+ */
+export type AreaBounds = {
+    name: string;
+    rowStart: number;
+    rowEnd: number;
+    colStart: number;
+    colEnd: number;
+};
+/**
+ * Shared core payload for parsed template + computed bounds.
+ */
+export type EasyLayoutCore = {
+    parsed: EasyLayoutParsed;
+    bounds: Record<string, AreaBounds>;
+};

package/app/utils/easy-layout/validateAreas.d.ts

@@ -0,0 +1,5 @@
+import type { EasyLayoutParsed } from "./types";
+/**
+ * Validate that each named area in the parsed grid is a rectangle.
+ */
+export declare const validateAreas: (parsed: EasyLayoutParsed) => void;

package/app/utils/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @packageDocumentation
+ *
+ * Utility exports for app helpers. Import directly or via `app/Utils`:
+ * ```ts
+ * import { useRouteContext } from "./utils";
+ * // or
+ * import { Utils } from "../app";
+ * const { useRouteContext } = Utils;
+ * ```
+ */
+export * from "./ApplicationState";
+export * from "./ApplicationStateLoader";
+export * from "./Controller";
+export * from "./Debug";
+export * from "./EasyLayout";
+export * from "./easy-layout";
+export * from "./History";
+export * from "./Route";
+export * from "./RouteHistory";
+export * from "./UniversalRouteAdapter";
+export * from "./Service";
+export * from "./TypeInfoORMAPIUtils";
+export * from "./TypeInfoORMClient";