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

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,103 @@
+/**
+ * @packageDocumentation
+ *
+ * Client wrapper around the TypeInfoORM API RouteMap. Uses ServiceConfig to
+ * route requests to the server-side TypeInfoORM routes.
+ */
+import { DeleteRelationshipResults, TypeInfoORMClientAPI, TypeInfoORMAPIRoutePaths } 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.
+     * @returns Whether the update succeeded.
+     */
+    update: (typeName: string, item: TypeInfoDataItem) => 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/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,23 @@
+/**
+ * @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 "./Service";
+export * from "./TypeInfoORMAPIUtils";
+export * from "./TypeInfoORMClient";

package/{src/common/TypeParsing → build}/TypeMapping.d.ts

@@ -1,3 +1,6 @@
+/**
+ * AST mapping helpers for extracting type aliases from TypeScript sources.
+ */
 import { Node, TypeAliasDeclaration } from "typescript";
 /**
  * A map of type aliases in the TypeScript AST.
@@ -5,5 +8,10 @@ import { Node, TypeAliasDeclaration } from "typescript";
 export type TypeMap = Record<string, TypeAliasDeclaration>;
 /**
  * Converts a TypeScript AST to a map of type aliases.
+ *
+ * @param node - AST node to traverse.
+ * @param map - Accumulator map of type aliases.
+ * @param parentName - Parent module name for nested namespaces.
+ * @returns Map of type alias declarations keyed by name.
  */
 export declare const convertASTToMap: (node: Node, map?: Record<string, TypeAliasDeclaration>, parentName?: string) => TypeMap;

package/build/TypeParsing.d.ts

@@ -0,0 +1,10 @@
+import { TypeInfoMap } from "../common/TypeParsing/TypeInfo";
+/**
+ * Extracts type information from TypeScript content.
+ *
+ * @category TypeInfo
+ *
+ * @param source - TypeScript source text to parse.
+ * @returns Map of exported type info definitions.
+ */
+export declare const getTypeInfoMapFromTypeScript: (source: string) => TypeInfoMap;

package/build/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * Various build tools like a dynamic TypeScript-to-TypeInfo parser.
+ */
+/**
+ * @category build
+ * @group Type Mapping
+ */
+export * from "./TypeMapping";
+/**
+ * @category build
+ * @group Type Parsing
+ */
+export * from "./TypeParsing";