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

package/native/utils/EasyLayout.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @packageDocumentation
+ *
+ * Native EasyLayout computes absolute coordinates from a template + container size.
+ *
+ * Differences from web:
+ * - Native does not use CSS Grid.
+ * - Coordinates are computed from explicit container width/height.
+ * - Recompute whenever container size changes.
+ * - `auto` track sizing is not supported.
+ */
+import type { ComponentType, ReactNode } from "react";
+import type { AreaBounds, EasyLayoutParsed, EasyLayoutTemplate } from "../../app/utils/easy-layout/types";
+/**
+ * Native EasyLayout options.
+ */
+export type NativeEasyLayoutOptions = {
+    /**
+     * Uniform container padding in pixels.
+     */
+    padding?: number;
+    /**
+     * Uniform gap between row/column tracks in pixels.
+     */
+    gap?: number;
+    /**
+     * Coordinate rounding precision. Defaults to 3 decimals.
+     */
+    roundToDecimals?: number;
+};
+/**
+ * Absolute coordinates for each named area.
+ */
+export type NativeEasyLayoutCoords = Record<string, {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}>;
+/**
+ * Input for native coordinate computation.
+ */
+export type NativeEasyLayoutComputeInput = NativeEasyLayoutOptions & {
+    width: number;
+    height: number;
+};
+/**
+ * Native EasyLayout instance created from a template.
+ */
+export type NativeEasyLayout = {
+    template: EasyLayoutTemplate;
+    parsed: EasyLayoutParsed;
+    bounds: Record<string, AreaBounds>;
+    areaNames: string[];
+    /**
+     * Compute area coordinates for a measured container.
+     */
+    computeNativeCoords: (input: NativeEasyLayoutComputeInput) => NativeEasyLayoutCoords;
+};
+/**
+ * Optional rendering helper props for coordinate-based layout.
+ *
+ * Pass a native `View` component via `ViewComponent` in React Native apps.
+ */
+export type NativeEasyLayoutViewProps = NativeEasyLayoutComputeInput & {
+    layout: NativeEasyLayout;
+    areaChildren?: Record<string, ReactNode>;
+    ViewComponent?: ComponentType<any>;
+    containerStyle?: Record<string, any>;
+    areaStyle?: Record<string, any>;
+    onLayout?: (...args: any[]) => void;
+};
+/**
+ * Create a native EasyLayout instance from a template.
+ *
+ * @category EasyLayout
+ */
+export declare const makeNativeEasyLayout: (template: EasyLayoutTemplate) => NativeEasyLayout;
+/**
+ * Hook wrapper for native coordinate computation.
+ *
+ * Recomputes when size/options change.
+ */
+export declare const useNativeEasyLayout: (layout: NativeEasyLayout, input: NativeEasyLayoutComputeInput) => NativeEasyLayoutCoords;
+/**
+ * Optional render helper that maps named areas to absolutely positioned children.
+ */
+export declare const NativeEasyLayoutView: ({ layout, areaChildren, ViewComponent, containerStyle, areaStyle, onLayout, ...input }: NativeEasyLayoutViewProps) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;

package/native/utils/History.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @packageDocumentation
+ *
+ * Native history helpers that adapt deep links into the shared history state machine.
+ */
+import type { HistoryController } from "../../app/utils/History";
+/**
+ * Adapter contract for React Native deep-link APIs.
+ *
+ * Intended for RN `Linking` wrappers.
+ */
+export type NativeLinkAdapter = {
+    /**
+     * Get the initial URL that opened the app.
+     */
+    getInitialURL: () => Promise<string | null>;
+    /**
+     * Subscribe to incoming URL events.
+     */
+    subscribe: (listener: (url: string) => void) => () => void;
+};
+/**
+ * Mode for incoming URL handling.
+ */
+export type NativeIncomingURLMode = "push" | "replace";
+/**
+ * Native history controller with explicit lifecycle hooks.
+ */
+export type NativeHistoryController = HistoryController & {
+    /**
+     * Start listening for incoming deep links.
+     */
+    start: () => Promise<void>;
+    /**
+     * Stop listening for incoming deep links.
+     */
+    stop: () => void;
+};
+/**
+ * Create-native-history options.
+ */
+export type CreateNativeHistoryOptions = {
+    /**
+     * Deep-link adapter implementation.
+     */
+    adapter?: NativeLinkAdapter;
+    /**
+     * Initial fallback path when there is no incoming URL.
+     *
+     * Default: `"/"`.
+     */
+    initialPath?: string;
+    /**
+     * How to apply incoming URL events to history.
+     *
+     * Default: `"replace"`.
+     */
+    onIncomingURL?: NativeIncomingURLMode;
+    /**
+     * Mapper for converting a URL into a path string.
+     *
+     * Default: {@link mapNativeURLToPath}.
+     */
+    mapURLToPath?: (url: string) => string;
+};
+/**
+ * Default native URL -> path mapping.
+ *
+ * Strips scheme and host, preserves path + query + hash.
+ */
+export declare const mapNativeURLToPath: (url: string) => string;
+/**
+ * Create a native history controller backed by in-memory history.
+ *
+ * Lifecycle behavior:
+ * - `start()` is idempotent.
+ * - `stop()` is idempotent.
+ * - `start()` applies `getInitialURL()` once per start cycle only if
+ *   navigation state has not changed since startup began.
+ * - This prevents late `getInitialURL()` resolution from overriding
+ *   user navigation that happened during startup.
+ *
+ * Incoming URL behavior:
+ * - `"replace"` updates current entry (default).
+ * - `"push"` appends a new entry.
+ *
+ * Example:
+ * ```ts
+ * const history = createNativeHistory({
+ *   adapter: linkingAdapter,
+ *   onIncomingURL: "replace",
+ * });
+ * await history.start();
+ * ```
+ */
+export declare const createNativeHistory: (options?: CreateNativeHistoryOptions) => NativeHistoryController;
+/**
+ * Create an Android back-handler helper for native history.
+ *
+ * Returns `true` only when history consumed the back action.
+ *
+ * Example:
+ * ```ts
+ * const handler = createNativeBackHandler(history);
+ * const consumed = handler.handle();
+ * ```
+ */
+export declare const createNativeBackHandler: (history: HistoryController) => {
+    /**
+     * @returns True when back navigation was handled by history.
+     */
+    handle: () => boolean;
+};

package/native/utils/NativeRoute.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @packageDocumentation
+ *
+ * Native Route wrappers that bridge native history into app Route context.
+ */
+import { PropsWithChildren } from "react";
+import { type RouteProps } from "../../app/utils/Route";
+import { type CreateNativeHistoryOptions, type NativeHistoryController } from "./History";
+/**
+ * Native route-provider props.
+ */
+export type NativeRouteProviderProps = PropsWithChildren<CreateNativeHistoryOptions & {
+    /**
+     * Optional externally managed history instance.
+     *
+     * When provided, `CreateNativeHistoryOptions` are ignored for construction
+     * and the provider will use this instance directly.
+     */
+    history?: NativeHistoryController;
+}>;
+/**
+ * Native RouteProvider that starts/stops native history lifecycle automatically.
+ *
+ * Behavior:
+ * - If `history` is provided, it is used as-is.
+ * - Otherwise, a history instance is created once from options.
+ * - On mount: calls `history.start()`.
+ * - On unmount: calls `history.stop()`.
+ *
+ * Example:
+ * ```tsx
+ * <NativeRouteProvider adapter={linkingAdapter}>
+ *   <NativeRoute path="/app" />
+ * </NativeRouteProvider>
+ * ```
+ */
+export declare const NativeRouteProvider: ({ children, history, ...historyOptions }: NativeRouteProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Native Route component that auto-provides native history at the top level.
+ *
+ * If a route adapter already exists in context, this renders the core route
+ * directly. Otherwise it creates a top-level {@link NativeRouteProvider}.
+ */
+export declare const NativeRoute: <ParamsType extends Record<string, any>>(props: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element;

package/native/utils/Route.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @packageDocumentation
+ *
+ * Native routing helpers that adapt common navigation state to RouteAdapter.
+ */
+import type { RouteAdapter, RouteQuery } from "../../app/utils/Route";
+/**
+ * Options to adapt a navigation state container into a RouteAdapter.
+ */
+export type NavigationStateAdapterOptions<TState> = {
+    /** Return the current navigation state. */
+    getState: () => TState;
+    /** Subscribe to navigation state changes. */
+    subscribe: (listener: () => void) => () => void;
+    /** Convert navigation state into a path string. */
+    toPath: (state: TState) => string;
+    /** Optional navigation handler used for push-style transitions. */
+    navigate?: (path: string) => void;
+    /** Optional navigation handler used for replace-style transitions. */
+    replace?: (path: string) => void;
+};
+/**
+ * Route node in a navigation chain.
+ */
+export type NavigationRouteNode = {
+    /** Route name as reported by the navigation library. */
+    name: string;
+    /** Optional route params used to populate path patterns. */
+    params?: Record<string, any>;
+};
+/**
+ * Mapping of route names to path patterns (e.g. "books/:id").
+ */
+export type NavigationRouteConfig = Record<string, string>;
+/**
+ * Create a RouteAdapter from a navigation state container (e.g., react-navigation).
+ *
+ * @param options - Adapter options for accessing and observing navigation state.
+ * @returns RouteAdapter bound to the navigation state.
+ */
+export declare const createNavigationStateRouteAdapter: <TState>(options: NavigationStateAdapterOptions<TState>) => RouteAdapter;
+/**
+ * Build a path from a navigation route chain and route config mapping.
+ *
+ * @param routeChain - Ordered list of routes from root to leaf.
+ * @param config - Route name to path pattern mapping.
+ * @param query - Optional query parameters appended to the path.
+ * @returns Serialized path string.
+ */
+export declare const buildPathFromRouteChain: (routeChain: NavigationRouteNode[], config: NavigationRouteConfig, query?: RouteQuery) => string;

package/native/utils/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @packageDocumentation
+ *
+ * Native (render-agnostic) utilities.
+ */
+export * from "../../app/utils/Route";
+export * from "../../app/utils/History";
+export * from "./EasyLayout";
+export * from "./History";
+export * from "./NativeRoute";
+export * from "./Route";

package/package.json

@@ -1,35 +1,90 @@
 {
   "name": "@resistdesign/voltra",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "With our powers combined!",
   "homepage": "https://voltra.app",
   "repository": "git@github.com:resistdesign/voltra.git",
   "author": "Resist Design",
   "license": "MIT",
+  "type": "module",
   "bin": {
-    "vest": "src/common/Testing/CLI.ts"
+    "vest": "common/Testing/CLI.js"
+  },
+  "exports": {
+    "./api": {
+      "types": "./api/index.d.ts",
+      "import": "./api/index.js"
+    },
+    "./app": {
+      "types": "./app/index.d.ts",
+      "import": "./app/index.js"
+    },
+    "./web": {
+      "types": "./web/index.d.ts",
+      "import": "./web/index.js"
+    },
+    "./native": {
+      "types": "./native/index.d.ts",
+      "import": "./native/index.js"
+    },
+    "./build": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    },
+    "./common": {
+      "types": "./common/index.d.ts",
+      "import": "./common/index.js"
+    },
+    "./iac": {
+      "types": "./iac/index.d.ts",
+      "import": "./iac/index.js"
+    },
+    "./iac/packs": {
+      "types": "./iac/packs/index.d.ts",
+      "import": "./iac/packs/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "api": [
+        "api/index.d.ts"
+      ],
+      "app": [
+        "app/index.d.ts"
+      ],
+      "web": [
+        "web/index.d.ts"
+      ],
+      "native": [
+        "native/index.d.ts"
+      ],
+      "common": [
+        "common/index.d.ts"
+      ],
+      "iac": [
+        "iac/index.d.ts"
+      ],
+      "iac/packs": [
+        "iac/packs/index.d.ts"
+      ],
+      "build": [
+        "build/index.d.ts"
+      ]
+    }
   },
   "files": [
-    "src/**/*",
+    "*.d.ts",
+    "*.d.ts.map",
+    "api/**",
+    "app/**",
+    "web/**",
+    "native/**",
+    "build/**",
+    "common/**",
+    "iac/**",
     "README.md",
-    "package.json",
-    "!src/iac/types/CloudFormationResourceSpecification.js"
+    "package.json"
   ],
-  "scripts": {
-    "build": "tsc && yarn prep-dist",
-    "test": "ts-node src/common/Testing/CLI.ts ./src/**/*.spec.json",
-    "test:gen": "ts-node src/common/Testing/CLI.ts --generate ./src/**/*.spec.json",
-    "doc": "typedoc",
-    "doc:dev": "typedoc --watch",
-    "doc-to-site": "cp -r ./docs site-dist/app/",
-    "prep-dist": "cp package.json dist/ && cp README.md dist/ && cp .npmignore dist/",
-    "site:build:app": "astro build && yarn finalize-site",
-    "site:build:api": "node ./site/build-api.mjs",
-    "site:build:iac": "ts-node ./site/iac/index.ts",
-    "start": "astro dev --host docs-local.demo.voltra.app --https",
-    "finalize-site": "yarn doc && yarn doc-to-site && cp CNAME site-dist/app/",
-    "iac:types:gen": "ts-node ./src/iac/types/generate.ts"
-  },
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.490.0",
     "@aws-sdk/client-s3": "^3.490.0",
@@ -40,33 +95,23 @@
     "ace-builds": "^1.32.3",
     "fast-glob": "^3.3.3",
     "picocolors": "^1.1.1",
-    "react": "^18.2.0",
     "react-ace": "^10.1.0",
-    "react-dom": "^18.3.1",
     "styled-components": "^6.1.8",
-    "ts-node": "^10.9.2",
     "typescript": "^5.3.3",
     "uuid": "^11.0.3",
     "yaml": "^2.3.4"
   },
-  "devDependencies": {
-    "@astrojs/react": "^4.3.1",
-    "@types/cfn-response": "^1.0.8",
-    "@types/node": "^20.11.6",
-    "@types/react-dom": "^18.3.0",
-    "@types/styled-components": "^5.1.34",
-    "@vitejs/plugin-basic-ssl": "^2.1.0",
-    "astro": "^5.13.5",
-    "aws-lambda": "^1.0.7",
-    "aws-sdk": "^2.1545.0",
-    "buffer": "^5.5.0||^6.0.0",
-    "cfn-response": "^1.0.1",
-    "esbuild": "^0.25.9",
-    "prettier": "^3.6.2",
-    "process": "^0.11.10",
-    "svgo": "^3",
-    "ts-morph": "^24.0.0",
-    "typedoc": "^0.25.8",
-    "typedoc-material-theme": "^1.0.2"
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "react-native": ">=0.7"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
   }
 }

package/web/forms/UI.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @packageDocumentation
+ *
+ * Tier 2 UI components: AutoForm, AutoField.
+ */
+import { FC } from "react";
+import type { TypeInfo, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import type { AutoFieldProps, CustomTypeActionPayload, FormController, FormValues, RelationActionPayload } from "../../app/forms/types";
+/**
+ * Render a form field based on TypeInfo metadata.
+ *
+ * @category Forms
+ *
+ * @param props - AutoField props describing the field and handlers.
+ * @returns Rendered field UI.
+ */
+export declare const AutoField: FC<AutoFieldProps>;
+/**
+ * Props for the AutoFormView component.
+ */
+export interface AutoFormViewProps {
+    /** Prepared controller that supplies field state. */
+    controller: FormController;
+    /** Submit handler invoked with validated form values. */
+    onSubmit: (values: FormValues) => void;
+    /** Disable the submit button when true. */
+    submitDisabled?: boolean;
+    /** Optional relation action handler for reference fields. */
+    onRelationAction?: (payload: RelationActionPayload) => void;
+    /** Optional custom type action handler. */
+    onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+}
+/**
+ * Render a form UI from a prepared form controller.
+ *
+ * @param props - View props including controller and callbacks.
+ * @returns Rendered form view.
+ */
+export declare const AutoFormView: FC<AutoFormViewProps>;
+/**
+ * Props for the AutoForm component.
+ */
+export interface AutoFormProps {
+    /** Type metadata used to build the form. */
+    typeInfo: TypeInfo;
+    /** Submit handler invoked with validated form values. */
+    onSubmit: (values: FormValues) => void;
+    /** Optional initial values applied before defaults. */
+    initialValues?: FormValues;
+    /** Optional change handler invoked when values update. */
+    onValuesChange?: (values: FormValues) => void;
+    /** Optional relation action handler for reference fields. */
+    onRelationAction?: (payload: RelationActionPayload) => void;
+    /** Optional custom type action handler. */
+    onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+    /** Optional operation override for field state. */
+    operation?: TypeOperation;
+    /** Disable the submit button when true. */
+    submitDisabled?: boolean;
+}
+/**
+ * Build a controller from type metadata and render an auto form.
+ *
+ * @param props - Auto form props including type info and callbacks.
+ * @returns Rendered form bound to a new controller.
+ */
+export declare const AutoForm: FC<AutoFormProps>;

package/web/forms/createWebFormRenderer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @packageDocumentation
+ *
+ * Convenience factory for web form renderers.
+ */
+import type { ReactElement } from "react";
+import type { ComponentSuite } from "../../app/forms/core/types";
+/**
+ * Create a web form renderer using the default web suite.
+ *
+ * @category Forms
+ *
+ * @param options - Optional suite overrides.
+ * @returns Web form renderers.
+ */
+export declare const createWebFormRenderer: (options?: {
+    suite?: ComponentSuite<ReactElement>;
+}) => {
+    AutoField: (props: import("../../app/forms/core").AutoFieldInput) => ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+    suite: import("../../app").ResolvedSuite<ReactElement<any, string | import("react").JSXElementConstructor<any>>>;
+};

package/web/forms/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @packageDocumentation
+ *
+ * Web form rendering exports.
+ */
+export * from "./suite";
+export * from "./UI";
+export * from "./primitives";
+export * from "./createWebFormRenderer";

package/web/forms/primitives/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @packageDocumentation
+ *
+ * Web primitives for the form generation system.
+ */
+/**
+ * Wrapper for grouped field content.
+ */
+export declare const FieldWrapper: any;
+/**
+ * Inline error message styling.
+ */
+export declare const ErrorMessage: any;
+/**
+ * Container for array field items.
+ */
+export declare const ArrayContainer: any;
+/**
+ * Wrapper for an individual array item row.
+ */
+export declare const ArrayItemWrapper: any;

package/web/forms/suite.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * Default web component suite for form rendering.
+ */
+import type { ReactElement } from "react";
+import type { ComponentSuite } from "../../app/forms/core";
+/**
+ * Default web suite for form rendering.
+ */
+export declare const webSuite: ComponentSuite<ReactElement>;
+/**
+ * AutoField renderer backed by the default web suite.
+ */
+export declare const webAutoField: (props: import("../../app/forms/core").AutoFieldInput) => ReactElement<any, string | import("react").JSXElementConstructor<any>>;

package/web/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * Web (DOM) entrypoint exports.
+ */
+/**
+ * @category web
+ * @group Forms
+ */
+export * from "./forms";
+/**
+ * @category web
+ * @group Layout and Navigation
+ */
+export * from "./utils";