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

package/native/testing/react-native.d.ts

@@ -0,0 +1,46 @@
+import React from "react";
+type Listener = () => boolean;
+export declare const Platform: {
+    OS: string;
+};
+export declare const BackHandler: {
+    addEventListener: (_eventName: "hardwareBackPress", listener: Listener) => {
+        remove: () => void;
+    };
+    removeEventListener: (_eventName: "hardwareBackPress", listener: Listener) => void;
+    __triggerHardwareBackPress: () => boolean;
+};
+type PrimitiveProps = Record<string, any> & {
+    children?: React.ReactNode;
+};
+export declare const View: {
+    ({ children, ...props }: PrimitiveProps): React.ReactElement<{
+        "data-rn": string;
+    }, string | React.JSXElementConstructor<any>>;
+    displayName: string;
+};
+export declare const Text: {
+    ({ children, ...props }: PrimitiveProps): React.ReactElement<{
+        "data-rn": string;
+    }, string | React.JSXElementConstructor<any>>;
+    displayName: string;
+};
+export declare const Pressable: {
+    ({ children, ...props }: PrimitiveProps): React.ReactElement<{
+        "data-rn": string;
+    }, string | React.JSXElementConstructor<any>>;
+    displayName: string;
+};
+export declare const Switch: {
+    ({ children, ...props }: PrimitiveProps): React.ReactElement<{
+        "data-rn": string;
+    }, string | React.JSXElementConstructor<any>>;
+    displayName: string;
+};
+export declare const TextInput: {
+    ({ children, ...props }: PrimitiveProps): React.ReactElement<{
+        "data-rn": string;
+    }, string | React.JSXElementConstructor<any>>;
+    displayName: string;
+};
+export {};

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,124 @@
+/**
+ * @packageDocumentation
+ *
+ * Native history helpers that provide the mobile equivalent of browser
+ * location/history behavior for shared app Route matching.
+ */
+import type { HistoryController } from "../../app/utils/History";
+/**
+ * Adapter contract for React Native deep-link APIs.
+ *
+ * Intended for RN `Linking` wrappers so native URL opens behave like browser
+ * navigations entering the shared Voltra history model.
+ */
+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";
+/**
+ * BackHandler-like contract for native platform back actions.
+ */
+export type NativeBackHandlerLike = {
+    addEventListener: (eventName: "hardwareBackPress", listener: () => boolean) => {
+        remove?: () => void;
+    } | void;
+    removeEventListener?: (eventName: "hardwareBackPress", listener: () => boolean) => void;
+};
+/**
+ * Native history controller with explicit lifecycle hooks.
+ *
+ * This is the native/mobile analogue to browser-backed history in web apps.
+ */
+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;
+    /**
+     * Optional native platform back handler wired into this history runtime.
+     */
+    backHandler?: NativeBackHandlerLike;
+};
+/**
+ * Default native URL -> path mapping.
+ *
+ * Strips scheme and host, preserves path + query + hash so incoming native URLs
+ * become the same route paths used on web.
+ */
+export declare const mapNativeURLToPath: (url: string) => string;
+/**
+ * Create a native history controller backed by in-memory history.
+ *
+ * This is the primary native routing primitive when the environment does not
+ * provide browser history. It gives shared Route matching a stable path/history
+ * source and applies incoming deep links as navigations in that same model.
+ *
+ * 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;
+/**
+ * @deprecated Use {@link createHistoryBackHandler} from `app/utils/History`.
+ */
+export declare const createNativeBackHandler: (history: HistoryController) => {
+    handle: () => boolean;
+};

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/Route.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ *
+ * Native routing helpers that keep shared app Route semantics intact on mobile.
+ *
+ * The primary native model is still Voltra path/history routing. These helpers
+ * supply the runtime selection needed by the `native` barrel:
+ * - React Native mobile uses native history + deep-link + platform back
+ * - React Native web uses the browser adapter
+ *
+ * This separation keeps `app` free of native-platform code.
+ */
+import { type PropsWithChildren } from "react";
+import type { RouteProps, RouteRuntimeIntegration } from "../../app/utils/Route";
+import type { RouteAdapter } from "../../app/utils/Route";
+import { type NativeBackHandlerLike } from "./History";
+/**
+ * Create a hardware-back listener from a route adapter.
+ */
+export declare const createNativeHardwareBackHandler: (adapter: RouteAdapter) => () => boolean;
+/**
+ * Register hardware-back handling against a BackHandler-like runtime.
+ */
+export declare const registerNativeHardwareBackHandler: (adapter: RouteAdapter, backHandler: NativeBackHandlerLike) => () => void;
+/**
+ * Low-level helper to build a Route runtime integration from a BackHandler.
+ *
+ * Native Route no longer uses this for the default path because platform back
+ * ownership now lives with the native adapter/history layer. This remains
+ * available for manual integrations.
+ */
+export declare const createNativeRouteBackIntegration: (backHandler: NativeBackHandlerLike) => RouteRuntimeIntegration;
+/**
+ * Native Route wrapper for root/provider mode.
+ *
+ * Behavior:
+ * - On React Native mobile runtimes, auto-injects a native-history-backed
+ *   adapter so native history owns platform back actions.
+ * - On React Native web runtimes, auto-injects the browser adapter.
+ */
+export declare const Route: <ParamsType extends Record<string, any>>(props: PropsWithChildren<RouteProps<ParamsType>>) => import("react/jsx-runtime").JSX.Element;

package/native/utils/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @packageDocumentation
+ *
+ * Native layout/navigation utilities.
+ */
+/**
+ * @category native
+ * @group Layout and Navigation
+ */
+export * from "./EasyLayout";
+/**
+ * @category native
+ * @group Layout and Navigation
+ */
+export * from "./History";
+/**
+ * @category native
+ * @group Layout and Navigation
+ */
+export * from "./NavButton";
+/**
+ * @category native
+ * @group Layout and Navigation
+ */
+export * from "./Route";

package/package.json

@@ -1,22 +1,16 @@
 {
   "name": "@resistdesign/voltra",
-  "version": "3.0.0-alpha.5",
+  "version": "3.0.0-alpha.51",
   "description": "With our powers combined!",
   "homepage": "https://voltra.app",
   "repository": "git@github.com:resistdesign/voltra.git",
   "author": "Resist Design",
   "license": "MIT",
   "type": "module",
-  "main": "./index.js",
-  "types": "./index.d.ts",
   "bin": {
     "vest": "common/Testing/CLI.js"
   },
   "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js"
-    },
     "./api": {
       "types": "./api/index.d.ts",
       "import": "./api/index.js"
@@ -25,6 +19,18 @@
       "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"
@@ -38,34 +44,61 @@
       "import": "./iac/packs/index.js"
     }
   },
-  "files": [
-    "*.d.ts",
-    "*.d.ts.map",
-    "index.js",
-    "api/**",
-    "app/**",
-    "common/**",
-    "iac/**",
-    "README.md",
-    "package.json"
-  ],
+  "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"
+      ]
+    }
+  },
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.490.0",
     "@aws-sdk/client-s3": "^3.490.0",
     "@aws-sdk/s3-request-presigner": "^3.490.0",
     "@aws-sdk/util-dynamodb": "^3.490.0",
     "@fontsource/montserrat-subrayada": "^5.2.5",
-    "@noble/hashes": "^2.0.1",
     "@picocss/pico": "^2.1.1",
     "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",
     "typescript": "^5.3.3",
     "uuid": "^11.0.3",
     "yaml": "^2.3.4"
+  },
+  "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,74 @@
+/**
+ * @packageDocumentation
+ *
+ * Web AutoForm wrappers backed by the default web renderer.
+ */
+import { type FC } from "react";
+import type { AutoFieldProps, CustomValidatorMap, CustomTypeActionPayload, FormValues, RelationActionPayload, TranslateValidationErrorCode } from "../../app/forms/types";
+import type { TypeInfo, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import type { FormController } 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;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
+}
+/**
+ * Render a web 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;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
+    /** Optional custom validators keyed by field name. */
+    customValidatorMap?: CustomValidatorMap;
+}
+/**
+ * Build a controller from type metadata and render a web auto form.
+ *
+ * @param props - Auto form props including type info and callbacks.
+ * @returns Rendered web form.
+ */
+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: import("react").FC<import("../../app").AutoFieldInput>;
+    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: import("react").FC<import("../../app").AutoFieldInput>;

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";