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

package/README.md

@@ -14,15 +14,23 @@
 yarn add @resistdesign/voltra
 ```
 
+Runtime peer dependencies:
+
+- Consumers must provide `react` (required).
+- Web consumers must provide `react-dom`.
+- Native consumers must provide `react-native`.
+
 ### Imports
 
 Prefer the public entrypoints below to keep imports stable and IDE auto-imports clean.
 
+The root import `@resistdesign/voltra` is intentionally unsupported to avoid
+cross-runtime bundling issues.
+
 Preferred:
 
 ```ts
-import { IaC } from "@resistdesign/voltra";
-import { Packs } from "@resistdesign/voltra/iac";
+import { SimpleCFT } from "@resistdesign/voltra/iac";
 import { addDNS } from "@resistdesign/voltra/iac/packs";
 ```
 
@@ -34,12 +42,98 @@ import addDNS from "@resistdesign/voltra/iac/packs/dns";
 
 Public entrypoints:
 
-- `@resistdesign/voltra`
 - `@resistdesign/voltra/api`
 - `@resistdesign/voltra/app`
 - `@resistdesign/voltra/common`
+- `@resistdesign/voltra/web`
+- `@resistdesign/voltra/native`
 - `@resistdesign/voltra/iac`
 - `@resistdesign/voltra/iac/packs`
+- `@resistdesign/voltra/build`
+
+Common imports by domain:
+
+```ts
+import { addRoutesToRouteMap, handleCloudFunctionEvent } from "@resistdesign/voltra/api";
+import { TypeInfo, TypeInfoORMServiceError } from "@resistdesign/voltra/common";
+import { parseTemplate, computeTrackPixels } from "@resistdesign/voltra/app";
+import { AutoField, AutoForm, createWebFormRenderer, getEasyLayout } from "@resistdesign/voltra/web";
+import { createNativeFormRenderer, makeNativeEasyLayout } from "@resistdesign/voltra/native";
+import { SimpleCFT } from "@resistdesign/voltra/iac";
+import { addDNS } from "@resistdesign/voltra/iac/packs";
+import { getTypeInfoMapFromTypeScript } from "@resistdesign/voltra/build";
+```
+
+### IaC Auth/Gateway Example
+
+`addGateway` authorizer provider ARNs can use CloudFormation intrinsics:
+
+```ts
+import { addGateway } from "@resistdesign/voltra/iac/packs";
+import { SimpleCFT } from "@resistdesign/voltra/iac";
+
+new SimpleCFT().applyPack(addGateway, {
+  id: "ApiGateway",
+  hostedZoneId: { Ref: "HostedZoneId" },
+  domainName: { Ref: "ApiDomainName" },
+  certificateArn: { Ref: "ApiCertificateArn" },
+  cloudFunction: { id: "ApiFunction" },
+  authorizer: {
+    providerARNs: [{ "Fn::GetAtt": ["MyUserPool", "Arn"] }],
+  },
+});
+```
+
+`addAuth` can pass partial user-management id overrides without changing all defaults:
+
+```ts
+import { addAuth } from "@resistdesign/voltra/iac/packs";
+import { SimpleCFT } from "@resistdesign/voltra/iac";
+
+new SimpleCFT().applyPack(addAuth, {
+  userManagementId: "UserPool",
+  userManagementIds: {
+    userPool: "MyUserPool",
+    userPoolClient: "MyUserPoolClient",
+  },
+  authRoleName: "AuthRole",
+  unauthRoleName: "UnauthRole",
+  apiCloudFunctionGatewayId: "ApiGateway",
+  apiStageName: "prod",
+  adminGroupId: "AdminGroup",
+  userManagementAdminGroupName: "admins",
+  hostedZoneIdParameterName: "HostedZoneId",
+  domainNameParameterName: "DomainName",
+  sslCertificateId: "CertificateArn",
+  mainCDNCloudFrontId: "MainCDN",
+  callbackUrls: ["https://example.com/callback"],
+  logoutUrls: ["https://example.com/logout"],
+});
+```
+
+------------
+
+## Build-time Type Parsing (Advanced)
+
+Voltra exposes TypeScript compiler–powered parsing utilities intended **only for build-time tooling** (scripts,
+generators, CI).
+
+These APIs depend on the TypeScript compiler and **must not be imported into runtime code** (e.g. Lambdas, servers,
+browsers).
+
+Build entrypoint:
+
+```ts
+import {getTypeInfoMapFromTypeScript} from "@resistdesign/voltra/build";
+```
+
+Use this entrypoint for:
+
+- Code generation
+- Pre-build analysis
+- Producing static artifacts (JSON / TS)
+
+Do **not** import `@resistdesign/voltra/build` from runtime code.
 
 ## With our powers combined!
 
@@ -60,13 +154,292 @@ front-end apps.</td>
 
 ## Features
 
-| API                                                                         | App                                           | IaC                                                           |
-|-----------------------------------------------------------------------------|-----------------------------------------------|---------------------------------------------------------------|
-| RPC                                                                         | Easy Layout                                   | Full Parameter Support: Groups/Labels/Types/etc...            |
-| Auth: Public/Secured/Role Based                                             | State Management                              | Packs: Easy to add Database/Storage/Auth/Functions/etc...     |
-| Routing: Nesting/Handlers/Injected Handlers                                 | Routing: Param Handlers/Parallel Routes/Hooks | Utilities: Patching Stacks/Constants/Standard Includes/etc... |
-| ORM: TypeScript Type Driven Auto-generated Data Contexts with Relationships |                                               | Typed Build Spec Creation                                     |
-|                                                                             |                                               | Typed Resource Parameters                                     |
+App features include form generation via TypeInfo-driven AutoForm/AutoField with validation, constraints, and relation/custom handlers.
+
+| API                                                                         | App                                                             | IaC                                                           |
+|-----------------------------------------------------------------------------|-----------------------------------------------------------------|---------------------------------------------------------------|
+| RPC                                                                         | Easy Layout                                                     | Full Parameter Support: Groups/Labels/Types/etc...            |
+| Auth: Public/Secured/Role Based                                             | State Management                                                | Packs: Easy to add Database/Storage/Auth/Functions/etc...     |
+| Routing: Nesting/Handlers/Injected Handlers                                 | Routing: Param Handlers/Parallel Routes/Hooks                   | Utilities: Patching Stacks/Constants/Standard Includes/etc... |
+| ORM: TypeScript Type Driven Auto-generated Data Contexts with Relationships | Form Generation: AutoForm/AutoField + constraints/relations     | Typed Build Spec Creation                                     |
+|                                                                             | Form Engine: validation, defaults, denied ops, custom type flow | Typed Resource Parameters                                     |
+
+## EasyLayout (Web + Native + Core)
+
+EasyLayout now has:
+
+- Shared core parsing/math in `@resistdesign/voltra/app` (`parseTemplate`, `computeTrackPixels`, etc.).
+- Web rendering via CSS Grid in `@resistdesign/voltra/web`.
+- Native coordinate computation in `@resistdesign/voltra/native`.
+
+### Reference Examples
+
+- Index: `examples/README.md`
+- Client routing: `examples/routing/app-routing.ts`
+- Backend API routing: `examples/api/backend-routing.ts`
+- Forms: `examples/forms/`
+  - `examples/forms/auto-form-validation-customization.tsx`
+- Layout: `examples/layout/`
+- Common types: `examples/common/types.ts`
+  - `examples/common/typeinfo-validation.ts`
+- Build-time parsing: `examples/build/type-parsing.ts`
+
+### Template syntax
+
+```text
+header header, 1fr
+side main, 2fr
+\ 100px 1fr
+```
+
+- Row lines: `<areas>, <row-track>` (row track optional)
+- Column line: `\ <col-track> <col-track> ...`
+- Supported units: `fr`, `px`, `%`
+- Named areas must form rectangles
+
+### Web usage
+
+```tsx
+import { getEasyLayout } from "@resistdesign/voltra/web";
+
+const { layout: Layout, areas } = getEasyLayout(undefined, undefined, {
+  gap: 12,
+  padding: 16,
+})`
+  header header, 1fr
+  side main, 2fr
+  \ 1fr 2fr
+`;
+```
+
+### Native usage
+
+```tsx
+import { makeNativeEasyLayout } from "@resistdesign/voltra/native";
+
+const layout = makeNativeEasyLayout(`
+  header header, 100px
+  side main, 1fr
+  \\ 1fr 2fr
+`);
+
+const coords = layout.computeNativeCoords({
+  width: 320,
+  height: 240,
+  padding: 12,
+  gap: 8,
+});
+```
+
+### Web vs Native
+
+| Runtime | Rendering model | Output |
+|---------|------------------|--------|
+| Web | CSS Grid (browser layout engine) | CSS template strings |
+| Native | Computed absolute layout | `{ left, top, width, height }` per area |
+
+## Routing (Web + Native)
+
+Voltra routing uses the same `Route` API across app/web/native.
+Use the platform barrel for root `Route` so runtime mechanics are auto-wired.
+The routing model is path/history based on every platform.
+
+Reference example: `examples/routing/app-routing.ts`
+
+```tsx
+import { Route } from "@resistdesign/voltra/web";
+
+<Route>
+  <Route path="/" exact>
+    <HomeScreen />
+  </Route>
+  <Route path="/login" exact>
+    <LoginScreen />
+  </Route>
+  <Route path="/signup" exact>
+    <SignUpScreen />
+  </Route>
+</Route>;
+```
+
+```tsx
+import { Route } from "@resistdesign/voltra/native";
+
+<Route>
+  <Route path="/" exact>
+    <HomeScreen />
+  </Route>
+</Route>;
+```
+
+On native, Voltra provides the missing browser-like pieces:
+
+- history-style path state for environments without the browser History API
+- deep-link URL ingress so app opens behave like web navigations
+- hardware back wiring into that same history model
+- the `native` barrel auto-selects browser behavior on React Native web targets
+  and native-history behavior on mobile targets
+
+How it works:
+
+- Root `<Route>` (no `path`) is provider mode.
+- Nested `<Route path="...">` entries are matcher mode.
+- Shared app routing matches normalized path strings on every platform.
+- Web already receives a browser pathname.
+- Native provides the browser-like history/path source that mobile lacks.
+- Native deep-link ingress is mapped into that same path/history model.
+- Strategy is auto-selected:
+  - DOM + History API => browser history strategy.
+  - Otherwise => in-memory native strategy.
+- Native strategy automatically wires Android hardware back to route history.
+  - If Voltra can go back (`history.index > 0`), it consumes the event and navigates back.
+  - If Voltra cannot go back, the event is not consumed so OS/native container behavior continues.
+
+Optional back affordances:
+
+- `adapter.back?.()` navigates backward when supported.
+- `adapter.canGoBack?.()` reports whether back navigation is currently possible.
+
+Escape hatches (root-only):
+
+- `initialPath` sets fallback startup path when no ingress URL exists.
+- `adapter` allows full custom adapter control.
+- `ingress` supports deep-link ingress wiring (`getInitialURL`, `subscribe`, URL mapping, push/replace mode).
+
+If you are looking for backend request routing (Cloud Function/API event routing), see:
+
+- `examples/api/backend-routing.ts`
+
+## Form Suites (Web + Native + BYOCS)
+
+Voltra's form system is split into a platform-agnostic core and platform suites:
+
+- Core contracts live under `src/app/forms/core` (field kinds, suite resolution, renderer factories).
+- Web DOM suite lives under `src/web/forms`.
+- React Native suite lives under `src/native/forms`.
+
+### Web Usage
+
+```tsx
+import { createWebFormRenderer } from "@resistdesign/voltra/web";
+
+const { AutoField } = createWebFormRenderer();
+```
+
+Override a single renderer:
+
+```tsx
+import { withRendererOverride } from "@resistdesign/voltra/app";
+import { createWebFormRenderer } from "@resistdesign/voltra/web";
+
+const { AutoField } = createWebFormRenderer({
+  suite: withRendererOverride("string", (ctx) => {
+    return <input value={(ctx.value as string) || ""} onChange={(e) => ctx.onChange(e.target.value)} />;
+  }),
+});
+```
+
+### Native Usage
+
+```tsx
+import { createNativeFormRenderer } from "@resistdesign/voltra/native";
+
+const { AutoField } = createNativeFormRenderer();
+```
+
+### BYOCS (Bring Your Own Component Suite)
+
+Provide partial overrides (renderers and/or primitives). Missing renderers are filled from the default suite and validated.
+
+```tsx
+import { createWebFormRenderer } from "@resistdesign/voltra/web";
+
+const { AutoField } = createWebFormRenderer({
+  suite: {
+    primitives: {
+      Button: ({ children }) => <button className="my-button">{children}</button>,
+    },
+    renderers: {
+      boolean: (ctx) => (
+        <label>
+          <input
+            type="checkbox"
+            checked={!!ctx.value}
+            onChange={(e) => ctx.onChange(e.target.checked)}
+          />
+          {ctx.label}
+        </label>
+      ),
+    },
+  },
+});
+```
+
+### Relation + Custom Type Hooks
+
+Renderers emit actions via:
+
+- `onRelationAction(payload)` for relation fields
+- `onCustomTypeAction(payload)` for custom types
+
+Use these to wire modals, selectors, or editors without baking UI into the core engine.
+
+### Centralized Validation
+
+All TypeInfo data-item validation can be run directly from `@resistdesign/voltra/common`:
+
+```ts
+import { validateTypeInfoDataItem } from "@resistdesign/voltra/common";
+```
+
+`validateTypeInfoDataItem` supports:
+
+- field-level `customValidatorMap` callbacks that return `ErrorDescriptor`
+- `tags.validation` field options:
+  - `validateHidden`
+  - `validateReadonly`
+  - `emptyArrayIsValid`
+
+AutoForm passes validation through the same centralized logic and supports:
+
+- `customValidatorMap` for app-specific rules
+- `translateValidationErrorCode` for UI-facing messages
+- multiple value-level errors per field
+- per-index array item errors for array fields
+
+Validation error maps can include both value-level errors and array item errors:
+
+```ts
+{
+  errorMap: {
+    title: [
+      { code: "MISSING_FIELD_VALUE" },
+      { code: "VALUE_DOES_NOT_MATCH_PATTERN" }
+    ],
+    tags: [
+      { code: "INVALID_TYPE" },
+      {
+        itemErrorMap: {
+          0: [{ code: "NOT_A_STRING" }],
+          2: [
+            { code: "NOT_A_STRING" },
+            { code: "INVALID_CUSTOM_TYPE" }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+- Field-level multiple errors are represented by multiple `ErrorDescriptor` entries in the field array.
+- Array item errors are represented by `itemErrorMap[index] = ErrorDescriptor[]`.
+
+Error-code constants are split by purpose:
+
+- `PRIMITIVE_ERROR_MESSAGE_CONSTANTS` keys follow `typeof` (`string`, `number`, `boolean`)
+- `DENIED_TYPE_OPERATIONS` keys follow `TypeOperation` (`CREATE`, `READ`, `UPDATE`, `DELETE`)
+- `ERROR_MESSAGE_CONSTANTS` exposes canonical code-keyed entries (for example `NOT_A_STRING`, `DENIED_TYPE_OPERATION_CREATE`)
 
 ## Docs Site
 
@@ -74,8 +447,10 @@ The docs site is both reference documentation and a canonical usage example.
 Key pieces:
 
 - Astro app in `site/app` builds the UI into `site-dist/app` via `yarn site:build:app`.
-- API bundle for the docs site is built by `yarn site:build:api` (see `site/build-api.mjs`) and written to `site-dist/api`.
-- The IaC demo template is generated by `yarn site:build:iac` from `site/iac/index.ts` and written to `site-dist/iac/index.yml`.
+- API bundle for the docs site is built by `yarn site:build:api` (see `site/build-api.mjs`) and written to
+  `site-dist/api`.
+- The IaC demo template is generated by `yarn site:build:iac` from `site/iac/index.ts` and written to
+  `site-dist/iac/index.yml`.
 
 API docs flow:
 
@@ -89,12 +464,15 @@ IaC types are generated from the AWS CloudFormation resource specification.
 When updating, follow this flow:
 
 1) Download the latest CloudFormation resource specification JSON from AWS (region: `us-east-1`).
-2) Replace the contents of `src/iac/types/CloudFormationResourceSpecification.ts` with the JSON payload (as the exported data).
+2) Replace the contents of `src/iac/types/CloudFormationResourceSpecification.ts` with the JSON payload (as the exported
+   data).
 3) Run `yarn iac:types:gen` to regenerate `dist/IaCTypes.ts`.
 4) Verify `dist/IaCTypes.ts` looks correct, then commit both files.
 
 Notes:
-- `src/iac/types/IaCTypes.ts` and `src/iac/types/CloudFormationResourceSpecification.ts` are generated artifacts; do not edit by hand.
+
+- `src/iac/types/IaCTypes.ts` and `src/iac/types/CloudFormationResourceSpecification.ts` are generated artifacts; do not
+  edit by hand.
 - The generator entrypoint is `src/iac/types/generate.ts` and uses `src/iac/types/Renderers.ts` for output.
 
 ## Releasing

package/api/DBX/DBXAsserts.d.ts

@@ -0,0 +1,95 @@
+import type { ListItemsResults } from "../../common/SearchTypes";
+/**
+ * Summary of IDs and cursors observed across pages.
+ */
+export type DBXPagingTranscript = {
+    /**
+     * Number of pages inspected.
+     */
+    pageCount: number;
+    /**
+     * Cursors observed per page.
+     */
+    cursors: Array<string | undefined>;
+    /**
+     * IDs grouped by page.
+     */
+    idsByPage: string[][];
+    /**
+     * Flattened IDs across all pages (page order preserved).
+     */
+    flattenedIds: string[];
+};
+/**
+ * Results from paging invariant checks.
+ */
+export type DBXPagingAssertionResult = {
+    /**
+     * True when no invariant violations were detected.
+     */
+    ok: boolean;
+    /**
+     * Total items observed across all pages.
+     */
+    totalItems: number;
+    /**
+     * Number of unique IDs observed across all pages.
+     */
+    uniqueItems: number;
+    /**
+     * IDs that appeared more than once.
+     */
+    duplicateIds: string[];
+    /**
+     * Pages with zero items.
+     */
+    emptyPageIndexes: number[];
+    /**
+     * Pages that violated the expected page size.
+     */
+    pageSizeViolations: Array<{
+        index: number;
+        size: number;
+    }>;
+    /**
+     * Raw paging transcript for debugging.
+     */
+    transcript: DBXPagingTranscript;
+};
+/**
+ * Results from ordering checks against an expected sequence.
+ */
+export type DBXOrderingAssertionResult = {
+    /**
+     * True when actual ordering matches expected ordering.
+     */
+    ok: boolean;
+    /**
+     * Actual IDs in observed order.
+     */
+    actualIds: string[];
+    /**
+     * Expected IDs for comparison.
+     */
+    expectedIds: string[];
+    /**
+     * First mismatched index, if any.
+     */
+    mismatchIndex?: number;
+};
+/**
+ * Build a paging transcript for a set of list results.
+ */
+export declare const getDbxPagingTranscript: <ItemType extends Record<string, any>>(pages: Array<ListItemsResults<ItemType>>, idField?: string) => DBXPagingTranscript;
+/**
+ * Assert paging invariants such as stable pagination and no duplicates.
+ */
+export declare const assertDbxPagingInvariants: <ItemType extends Record<string, any>>(pages: Array<ListItemsResults<ItemType>>, options?: {
+    idField?: string;
+    itemsPerPage?: number;
+    allowEmptyPages?: boolean;
+}) => DBXPagingAssertionResult;
+/**
+ * Assert that the observed ordering exactly matches an expected ordering.
+ */
+export declare const assertDbxStableOrdering: <ItemType extends Record<string, any>>(pages: Array<ListItemsResults<ItemType>>, expectedIds: string[], idField?: string) => DBXOrderingAssertionResult;

package/api/DBX/DBXRequest.d.ts

@@ -0,0 +1,5 @@
+import type { DBXRequestInput, DBXResponse, DBXRuntime } from "./DBXTypes";
+/**
+ * Run a DBX request through the router.
+ */
+export declare const runDbxRequest: <T = unknown>(runtime: DBXRuntime, request: DBXRequestInput) => Promise<DBXResponse<T>>;

package/api/DBX/DBXRuntime.d.ts

@@ -0,0 +1,5 @@
+import type { DBXRuntime, DBXRuntimeConfig } from "./DBXTypes";
+/**
+ * Build an in-memory runtime for DBX scenarios.
+ */
+export declare const createDbxRuntime: (config: DBXRuntimeConfig) => DBXRuntime;

package/api/DBX/DBXScenarioConfig.d.ts

@@ -0,0 +1,9 @@
+import type { TypeInfoMap } from "../../common/TypeParsing/TypeInfo";
+/**
+ * Canonical TypeInfo map used by DBX E2E scenario tests.
+ */
+export declare const DBX_TYPE_INFO_MAP: TypeInfoMap;
+/**
+ * Ordered list of DBX scenario type names.
+ */
+export declare const DBX_TYPE_NAMES: string[];

package/api/DBX/DBXSeed.d.ts

@@ -0,0 +1,124 @@
+import type { TypeInfoDataItem, TypeInfoMap } from "../../common/TypeParsing/TypeInfo";
+/**
+ * Dataset size presets for DBX scenarios.
+ */
+export declare const DBX_DATASET_SIZES: {
+    readonly SMALL: 50;
+    readonly MED: 200;
+    readonly LARGE: 1000;
+};
+/**
+ * Relationship edge shape used by DBX seeds.
+ */
+export type DBXSeedRelationship = {
+    /**
+     * Type name of the relationship origin.
+     */
+    fromTypeName: string;
+    /**
+     * Field name on the origin type that defines the relationship.
+     */
+    fromTypeFieldName: string;
+    /**
+     * Primary field value for the origin item.
+     */
+    fromTypePrimaryFieldValue: string;
+    /**
+     * Primary field value for the target item.
+     */
+    toTypePrimaryFieldValue: string;
+};
+/**
+ * Configuration for generating a DBX dataset.
+ */
+export type DBXSeedConfig = {
+    /**
+     * Seed used for deterministic generation.
+     */
+    seed: number | string;
+    /**
+     * Type info map used to shape items.
+     */
+    typeInfoMap: TypeInfoMap;
+    /**
+     * Optional list of type names to seed.
+     */
+    itemTypeNames?: string[];
+    /**
+     * Default item count per type when sizeByType is not provided.
+     */
+    size?: number;
+    /**
+     * Optional per-type overrides for item counts.
+     */
+    sizeByType?: Record<string, number>;
+    /**
+     * Optional base date for date-like string fields.
+     */
+    baseDate?: string;
+    /**
+     * Whether to include optional fields (default true).
+     */
+    includeOptionalFields?: boolean;
+    /**
+     * Whether to include array fields (default true).
+     */
+    includeArrayFields?: boolean;
+    /**
+     * Max array length when generating array fields.
+     */
+    maxArrayLength?: number;
+    /**
+     * Custom token pool for text generation.
+     */
+    textTokenPool?: string[];
+    /**
+     * Whether to include relationship edges (default true).
+     */
+    includeRelationships?: boolean;
+    /**
+     * Ratio of relationship edges that should point at missing targets.
+     */
+    relationshipDanglingRate?: number;
+    /**
+     * Number of relationships to generate per item when possible.
+     */
+    relationshipsPerItem?: number;
+};
+/**
+ * Seeded dataset payload returned by {@link makeDbxDataset}.
+ */
+export type DBXSeedDataset = {
+    /**
+     * Seed used for deterministic generation.
+     */
+    seed: number | string;
+    /**
+     * Items keyed by type name.
+     */
+    itemsByType: Record<string, TypeInfoDataItem[]>;
+    /**
+     * Generated ids per type name.
+     */
+    idsByType: Record<string, string[]>;
+    /**
+     * Relationship edges seeded for scenarios.
+     */
+    relationships: DBXSeedRelationship[];
+    /**
+     * Token pool used for text values.
+     */
+    tokenPool: string[];
+};
+/**
+ * Generate a deterministic dataset for DBX scenarios.
+ */
+export declare const makeDbxDataset: (config: DBXSeedConfig) => DBXSeedDataset;
+/**
+ * Build relationship seeds from existing items.
+ */
+export declare const makeDbxRelationshipSeeds: (typeInfoMap: TypeInfoMap, itemsByType: Record<string, TypeInfoDataItem[]>, idsByType: Record<string, string[]>, options: {
+    seed: number | string;
+    relationshipDanglingRate?: number;
+    relationshipsPerItem?: number;
+}) => DBXSeedRelationship[];