@resistdesign/voltra 3.0.0-alpha.4 → 3.0.0-alpha.41

package/iac/types/Renderers.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Render helpers that convert CloudFormation spec nodes into TypeScript types.
+ */
+import { AttributeType, IDocumentable, NamespaceStructure, PropertyDescriptor, PropertyType, ResourceType } from "./Types";
+/**
+ * Render a primitive CloudFormation type to a TypeScript type string.
+ *
+ * @param primitiveType - CloudFormation primitive type name.
+ * @returns Rendered TypeScript type string.
+ */
+export declare const renderPrimitiveType: (primitiveType: string) => string;
+/**
+ * Render a property type from an attribute descriptor.
+ *
+ * @param path - Namespace path segments.
+ * @param attribute - Attribute type descriptor.
+ * @returns Rendered TypeScript type string.
+ */
+export declare const renderPropertyType: (path: string[], { PrimitiveType, Type, PrimitiveItemType, ItemType }: AttributeType) => string;
+/**
+ * Render a property name with optionality.
+ *
+ * @param propertyName - Property name from the spec.
+ * @param descriptor - Property descriptor or attribute type.
+ * @returns Rendered property name string.
+ */
+export declare const renderPropertyName: (propertyName: string, descriptor: PropertyDescriptor | AttributeType) => string;
+/**
+ * Render a JSDoc comment block from a documentable descriptor.
+ *
+ * @param descriptor - Documentable spec node.
+ * @returns Comment block string or empty string.
+ */
+export declare const renderCommentBlock: ({ UpdateType, DuplicatesAllowed, Documentation, }: IDocumentable) => string;
+/**
+ * Render a property line for a type.
+ *
+ * @param path - Namespace path segments.
+ * @param propertyName - Property name.
+ * @param propertyDescriptor - Property descriptor or attribute type.
+ * @returns Rendered property line.
+ */
+export declare const renderProperty: (path: string[], propertyName: string, propertyDescriptor: PropertyDescriptor | AttributeType) => string;
+/**
+ * Render a type alias with a fully formed body.
+ *
+ * @param commentBlock - Optional comment block.
+ * @param typeName - Type name.
+ * @param fullBody - Type body string.
+ * @returns Rendered type alias string.
+ */
+export declare const renderTypeWithFullBody: (commentBlock: string, typeName: string, fullBody: string) => string;
+/**
+ * Render a type body with property definitions.
+ *
+ * @param path - Namespace path segments.
+ * @param properties - Properties to render.
+ * @returns Rendered type body string.
+ */
+export declare const renderTypePropertiesBody: (path: string[], properties: Record<string, PropertyDescriptor | AttributeType>) => string;
+/**
+ * Render a type alias from a property map.
+ *
+ * @param path - Namespace path segments.
+ * @param typeName - Type name.
+ * @param properties - Property definitions.
+ * @param commentBlock - Optional comment block.
+ * @returns Rendered type alias string.
+ */
+export declare const renderTypeWithProperties: (path: string[], typeName: string, properties: Record<string, AttributeType>, commentBlock?: string) => string;
+/**
+ * Render a type alias from a property type.
+ *
+ * @param path - Namespace path segments.
+ * @param typeName - Type name.
+ * @param propertyType - Property type descriptor.
+ * @returns Rendered type alias string.
+ */
+export declare const renderTypeFromPropertyType: (path: string[], typeName: string, propertyType: PropertyType) => string;
+/**
+ * Render a type alias for a resource type.
+ *
+ * @param path - Namespace path segments.
+ * @param typeName - Type name.
+ * @param resourceType - Resource type descriptor.
+ * @returns Rendered type alias string.
+ */
+export declare const renderTypeFromResourceType: (path: string[], typeName: string, resourceType: ResourceType) => string;
+/**
+ * Render a namespace structure into TypeScript type output.
+ *
+ * @param structure - Namespace structure to render.
+ * @param namespaceName - Optional namespace name.
+ * @returns Rendered namespace string.
+ */
+export declare const renderNamespaceStructure: ({ path, includes, propertyTypes, resourceTypes, namespaces, }: NamespaceStructure, namespaceName?: string) => string;

package/iac/types/Types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @packageDocumentation
+ *
+ * Core types used by the IaC type generator. The generated outputs live in
+ * `src/iac/types/IaCTypes.ts` and `src/iac/types/CloudFormationResourceSpecification.ts`
+ * and should not be edited by hand. Regenerate them via `yarn iac:types:gen`.
+ */
+export interface IDocumentable {
+    /**
+     * Update type description from the spec.
+     */
+    UpdateType?: string;
+    /**
+     * Whether duplicates are allowed.
+     */
+    DuplicatesAllowed?: boolean;
+    /**
+     * Documentation URL for the spec entry.
+     */
+    Documentation?: string;
+}
+/**
+ * Attribute type descriptor from the CloudFormation spec.
+ */
+export type AttributeType = {
+    /**
+     * Primitive type name, when applicable.
+     */
+    PrimitiveType?: string;
+    /**
+     * Container or complex type name.
+     */
+    Type?: string;
+    /**
+     * Item type for container types.
+     */
+    ItemType?: string;
+    /**
+     * Primitive item type for container types.
+     */
+    PrimitiveItemType?: string;
+    /**
+     * Whether duplicate items are allowed.
+     */
+    DuplicatesAllowed?: boolean;
+};
+/**
+ * Property descriptor including documentation and attribute details.
+ */
+export type PropertyDescriptor = IDocumentable & AttributeType & {
+    /**
+     * Whether the property is required.
+     */
+    Required?: boolean;
+};
+/**
+ * Property type with nested properties.
+ */
+export type PropertyType = PropertyDescriptor & {
+    /**
+     * Child properties for object types.
+     */
+    Properties?: Record<string, PropertyDescriptor>;
+};
+/**
+ * Resource type descriptor from the CloudFormation spec.
+ */
+export type ResourceType = {
+    /**
+     * CloudFormation resource type name.
+     */
+    Type?: string;
+    /**
+     * Documentation URL for the resource type.
+     */
+    Documentation?: string;
+    /**
+     * Whether additional properties are allowed.
+     */
+    AdditionalProperties?: boolean;
+    /**
+     * Resource properties map.
+     */
+    Properties?: Record<string, PropertyDescriptor>;
+    /**
+     * Resource attributes map.
+     */
+    Attributes?: Record<string, AttributeType>;
+};
+/**
+ * Full CloudFormation resource specification payload.
+ */
+export type CloudFormationResourceSpecification = {
+    /**
+     * Map of property types keyed by name.
+     */
+    PropertyTypes: Record<string, PropertyType>;
+    /**
+     * Map of resource types keyed by name.
+     */
+    ResourceTypes: Record<string, ResourceType>;
+    /**
+     * Specification version string.
+     */
+    ResourceSpecificationVersion: `${number}.${number}.${number}`;
+};
+/**
+ * Namespace structure produced by the type generator.
+ */
+export type NamespaceStructure = {
+    /**
+     * Namespace path segments.
+     */
+    path: string[];
+    /**
+     * TypeScript include strings for the namespace.
+     */
+    includes?: string[];
+    /**
+     * Property types contained in the namespace.
+     */
+    propertyTypes?: Record<string, PropertyType>;
+    /**
+     * Resource types contained in the namespace.
+     */
+    resourceTypes?: Record<string, ResourceType>;
+    /**
+     * Nested namespaces.
+     */
+    namespaces?: Record<string, NamespaceStructure>;
+};

package/iac/types/Utils.d.ts

@@ -0,0 +1,9 @@
+import { CloudFormationResourceSpecification, NamespaceStructure } from "./Types";
+/**
+ * Build a namespace structure from the CloudFormation specification.
+ *
+ * @param specification - CloudFormation resource specification.
+ * @param baseStructure - Base namespace structure to extend.
+ * @returns Fully built namespace structure.
+ */
+export declare const getNamespaceStructure: (specification: CloudFormationResourceSpecification, baseStructure: NamespaceStructure) => NamespaceStructure;

package/iac/types/generate.d.ts

@@ -0,0 +1 @@
+export {};

package/iac/utils/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @packageDocumentation
+ *
+ * IaC utility helpers for patching templates, creating resource packs, and
+ * defining parameter groups.
+ */
+import { CloudFormationParameter, CloudFormationTemplate } from "../types/IaCTypes";
+export * from "./patch-utils";
+/**
+ * Stack parameter definition with display metadata.
+ */
+export type ParameterInfo = {
+    /**
+     * Parameter id used in the template.
+     */
+    ParameterId: string;
+    /**
+     * CloudFormation parameter definition.
+     */
+    Parameter: CloudFormationParameter;
+    /**
+     * Display label for the parameter.
+     */
+    Label: string;
+    /**
+     * Optional parameter group label.
+     */
+    Group?: string;
+};
+/**
+ * Add a stack parameter including its descriptive info and an optional parameter group.
+ *
+ * @param parameterInfo - Parameter metadata and definition.
+ * @param template - Template to update.
+ * @returns Updated CloudFormation template.
+ */
+export declare const addParameter: (parameterInfo: ParameterInfo, template: CloudFormationTemplate) => CloudFormationTemplate;
+/**
+ * Add multiple stack parameters with info and groups.
+ *
+ * @param parameters - Parameter definitions to add.
+ * @param template - Template to update.
+ * @returns Updated CloudFormation template.
+ */
+export declare const addParameters: (parameters: ParameterInfo[], template: CloudFormationTemplate) => CloudFormationTemplate;
+/**
+ * A function used to apply a pack to a stack template.
+ *
+ * @typeParam ParamsType - Pack parameter type.
+ * @param params - Pack configuration.
+ * @param template - Template to update.
+ * @returns Updated CloudFormation template.
+ */
+export type ResourcePackApplier<ParamsType> = (params: ParamsType, template: CloudFormationTemplate) => CloudFormationTemplate;
+/**
+ * Apply a patch to a stack template.
+ *
+ * @param patch - Partial template patch.
+ * @param template - Template to update.
+ * @returns Updated CloudFormation template.
+ */
+export declare const patchTemplate: (patch: Partial<CloudFormationTemplate>, template: CloudFormationTemplate) => CloudFormationTemplate;
+/**
+ * Create a custom resource pack that can use configuration input to patch a stack with convenient resources, parameters, etc.
+ *
+ * @typeParam ParamsType - Pack parameter type.
+ * @param creator - Pack creator that returns a template patch.
+ * @returns Resource pack applier.
+ */
+export declare const createResourcePack: <ParamsType>(creator: (params: ParamsType) => Partial<CloudFormationTemplate>) => ResourcePackApplier<ParamsType>;
+/**
+ * Grouped parameter definitions for CloudFormation interfaces.
+ */
+export type ParameterGroup = {
+    /**
+     * Group label.
+     */
+    Label: string;
+    /**
+     * Map of parameter ids to parameter definitions.
+     */
+    Parameters: {
+        [parameterId: string]: {
+            Label: string;
+        } & CloudFormationParameter;
+    };
+};

package/iac/utils/patch-utils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @packageDocumentation
+ *
+ * Deep merge helpers used by IaC packs to patch CloudFormation templates.
+ */
+/**
+ * Merge strategy for patching values.
+ */
+export type MergeStrategy = "transpose" | "accumulate" | "accumulate-unique" | "accumulate-unique-by" | "replace";
+/**
+ * Descriptor defining how a value path should be merged.
+ */
+export type MergeStrategyDescriptor = {
+    strategy: MergeStrategy;
+} | {
+    strategy: "accumulate-unique-by";
+    data: string | ((value: any) => string);
+};
+/**
+ * Encoded value path string.
+ */
+export type ValuePathString = string;
+/**
+ * Value path segments.
+ */
+export type ValuePathArray = (string | number)[];
+/**
+ * Map of value path strings to merge strategy descriptors.
+ */
+export type MergeStrategyMap = Record<ValuePathString, MergeStrategyDescriptor>;
+/**
+ * Default merge strategy for patching.
+ */
+export declare const DEFAULT_MERGE_STRATEGY: MergeStrategy;
+/**
+ * Convert a value path array into a path string.
+ *
+ * @param valuePathArray - Value path segments.
+ * @returns Encoded value path string.
+ */
+export declare const getValuePathString: (valuePathArray?: ValuePathArray) => string;
+/**
+ * Convert a value path string into path segments.
+ *
+ * @param valuePathString - Encoded value path string.
+ * @returns Decoded value path segments.
+ */
+export declare const getValuePathArray: (valuePathString?: ValuePathString) => string[];
+/**
+ * Check whether a value is constructed by a specific constructor.
+ *
+ * @param value - Value to inspect.
+ * @param constructorReference - Constructor to compare against.
+ * @returns Whether the value matches the constructor.
+ */
+export declare const isConstructedFrom: (value: any, constructorReference: Function) => boolean;
+/**
+ * Merge two values using path-based merge strategies.
+ *
+ * @param valuePathArray - Path to the value being merged.
+ * @param existingValue - Existing value in the template.
+ * @param newValue - New value to merge in.
+ * @param mergeStrategyMap - Merge strategy overrides.
+ * @returns Merged value.
+ */
+export declare const mergeValues: (valuePathArray: ValuePathArray | undefined, existingValue: any, newValue: any, mergeStrategyMap?: MergeStrategyMap) => any;

package/iac-packs/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @packageDocumentation
+ *
+ * Import from `@resistdesign/voltra/iac/packs`.
+ */
+export * from '../iac/packs';

package/native/forms/UI.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @packageDocumentation
+ *
+ * Native AutoForm wrappers backed by the default native renderer.
+ */
+import { type FC } from "react";
+import type { AutoFieldProps, CustomValidatorMap, CustomTypeActionPayload, FormController, FormValues, RelationActionPayload, TranslateValidationErrorCode } from "../../app/forms/types";
+import type { TypeInfo, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+/**
+ * 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 native 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 native auto form.
+ *
+ * @param props - Auto form props including type info and callbacks.
+ * @returns Rendered native form.
+ */
+export declare const AutoForm: FC<AutoFormProps>;

package/native/forms/createNativeFormRenderer.d.ts

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

package/native/forms/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @packageDocumentation
+ *
+ * Native form rendering exports.
+ */
+/**
+ * @category native
+ * @group Forms
+ */
+export * from "./suite";
+/**
+ * @category native
+ * @group Forms
+ */
+export * from "./UI";
+/**
+ * @category native
+ * @group Forms
+ */
+export * from "./primitives";
+/**
+ * @category native
+ * @group Forms
+ */
+export * from "./createNativeFormRenderer";

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

@@ -0,0 +1,38 @@
+/**
+ * @packageDocumentation
+ *
+ * React Native primitives for the form generation system.
+ */
+import { Text, View } from "react-native";
+/**
+ * Wrapper for grouped field content.
+ */
+export declare const FieldWrapper: (props: {
+    children?: React.ReactNode;
+}) => import("react").CElement<import("react-native").ViewProps, View>;
+/**
+ * Inline error message renderer.
+ */
+export declare const ErrorMessage: ({ children }: {
+    children: React.ReactNode;
+}) => import("react").CElement<import("react-native").TextProps, Text>;
+/**
+ * Container for array field items.
+ */
+export declare const ArrayContainer: (props: {
+    children?: React.ReactNode;
+}) => import("react").CElement<import("react-native").ViewProps, View>;
+/**
+ * Wrapper for an individual array item row.
+ */
+export declare const ArrayItemWrapper: (props: {
+    children?: React.ReactNode;
+}) => import("react").CElement<import("react-native").ViewProps, View>;
+/**
+ * Minimal button primitive.
+ */
+export declare const Button: ({ children, disabled, onPress, }: {
+    children?: React.ReactNode;
+    disabled?: boolean;
+    onPress?: () => void;
+}) => import("react").FunctionComponentElement<import("react-native").PressableProps & import("react").RefAttributes<View>>;

package/native/forms/suite.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * Default native component suite for form rendering.
+ */
+import type { ReactElement } from "react";
+import type { ComponentSuite } from "../../app/forms/core";
+/**
+ * Default native suite for form rendering.
+ */
+export declare const nativeSuite: ComponentSuite<ReactElement>;
+/**
+ * AutoField renderer backed by the default native suite.
+ */
+export declare const nativeAutoField: import("react").FC<import("../../app").AutoFieldInput>;

package/native/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @packageDocumentation
+ *
+ * Native entrypoint exports.
+ *
+ * AGENT NOTE:
+ * In this native barrel, direct imports from `react-native` are expected and
+ * correct. Do not replace them with runtime import/require indirection hacks.
+ */
+/**
+ * @category native
+ * @group Forms
+ */
+export * from "./forms";
+/**
+ * @category native
+ * @group Layout and Navigation
+ */
+export * from "./utils";