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

package/README.md

@@ -14,6 +14,80 @@
 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 { SimpleCFT } from "@resistdesign/voltra/iac";
+import { addDNS } from "@resistdesign/voltra/iac/packs";
+```
+
+Not supported:
+
+```ts
+import addDNS from "@resistdesign/voltra/iac/packs/dns";
+```
+
+Public entrypoints:
+
+- `@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";
+```
+
+------------
+
+## 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!
 
 <table style="border: 0 solid black;">
@@ -33,13 +107,240 @@ 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`.
+
+### Examples
+
+- `examples/api.ts`
+- `examples/common.ts`
+- `examples/web.ts`
+- `examples/native.ts`
+- `examples/build.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 ships a render-agnostic Route core in `@resistdesign/voltra/app` plus platform adapters.
+
+Web usage (auto-wires `window.history`):
+
+```tsx
+import { Route } from "@resistdesign/voltra/web";
+```
+
+Native usage (adapter-driven):
+
+```tsx
+import { Route, RouteProvider, createManualRouteAdapter } from "@resistdesign/voltra/native";
+const { adapter, updatePath } = createManualRouteAdapter("/home");
+```
+
+For React Native navigation libraries, Voltra is optimized for react-navigation as the primary native default. Provide a RouteAdapter that maps navigation state to a path and call `RouteProvider`.
+
+Native navigation mapping example:
+
+```tsx
+import { buildPathFromRouteChain, createNavigationStateRouteAdapter } from "@resistdesign/voltra/native";
+
+const adapter = createNavigationStateRouteAdapter({
+  getState: () => navigationRef.getRootState(),
+  subscribe: (listener) => navigationRef.addListener("state", listener),
+  toPath: (state) =>
+    buildPathFromRouteChain(
+      state.routes.map((route) => ({
+        name: route.name,
+        params: route.params as Record<string, any>,
+      })),
+      {
+        Home: "home",
+        Book: "books/:id",
+      },
+    ),
+  navigate: (path) => {
+    const routeName = path === "/home" ? "Home" : "Book";
+    navigationRef.navigate(routeName);
+  },
+});
+```
+
+For RN web builds, keep your navigation library linking config in sync with the same route patterns used in `buildPathFromRouteChain`.
+
+## 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.
+
+## Docs Site
+
+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 docs flow:
+
+1) `yarn doc` generates TypeDoc output into `docs/`.
+2) `yarn doc-to-site` copies `docs/` into `site-dist/app/`.
+3) `yarn site:build:app` runs Astro and then `yarn finalize-site` to refresh the docs site with API docs.
+
+## IaC Type Generation
+
+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).
+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.
+- The generator entrypoint is `src/iac/types/generate.ts` and uses `src/iac/types/Renderers.ts` for output.
 
 ## Releasing
 
@@ -70,3 +371,22 @@ When the GitHub Release is marked as a prerelease, the npm publish step uses the
 ```bash
 yarn add @resistdesign/voltra@next
 ```
+
+## Project
+
+### Build and test commands
+
+```bash
+yarn build
+yarn test
+yarn test:gen
+yarn doc
+yarn start
+yarn site:build:app
+```
+
+### Contribution guidelines
+
+- Use Conventional Commits (`feat:`, `fix:`, `doc:`, `chore:`) with optional scopes.
+- Keep subjects imperative and concise.
+- Include test commands run (or reasons for skipping) in PR descriptions.

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[];