@resistdesign/voltra 3.0.0-alpha.3 → 3.0.0-alpha.30

package/chunk-WELZGQDJ.js

@@ -0,0 +1,456 @@
+import { useState, useCallback, useMemo, useEffect } from 'react';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+
+// src/app/utils/easy-layout/parseTemplate.ts
+var parseTrackSpec = (token) => {
+  const trimmed = token.trim();
+  const numericMatch = trimmed.match(/^([0-9]*\.?[0-9]+)(fr|px|%)$/);
+  if (!numericMatch) {
+    throw new Error(
+      `Invalid track token "${trimmed}". Supported units are fr, px, and %.`
+    );
+  }
+  const value = Number(numericMatch[1]);
+  const suffix = numericMatch[2];
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`Track value must be a non-negative number. Received "${trimmed}".`);
+  }
+  if (suffix === "fr") {
+    return { kind: "fr", value };
+  }
+  if (suffix === "px") {
+    return { kind: "px", value };
+  }
+  return { kind: "pct", value };
+};
+var normalizeAreas = (areaPart) => {
+  return areaPart.trim().split(/\s+/g).map((token) => token.trim()).filter(Boolean);
+};
+var parseTemplate = (template = "") => {
+  const lines = template.split("\n").map((line) => line.trim()).filter(Boolean);
+  const areaGrid = [];
+  const rowTracks = [];
+  let colTracks = null;
+  for (const line of lines) {
+    if (line.startsWith("\\")) {
+      if (colTracks) {
+        throw new Error("Template can include only one column-track line.");
+      }
+      const colTokens = line.replace(/\\/g, " ").trim().split(/\s+/g).filter(Boolean);
+      colTracks = colTokens.map(parseTrackSpec);
+      continue;
+    }
+    const parts = line.split(",").map((part) => part.trim());
+    const areaPart = parts[0] || "";
+    if (!areaPart) {
+      continue;
+    }
+    if (parts.length > 2) {
+      throw new Error(
+        `Invalid row definition "${line}". Expected "<areas>, <row-track>".`
+      );
+    }
+    const areas = normalizeAreas(areaPart);
+    if (!areas.length) {
+      continue;
+    }
+    areaGrid.push(areas);
+    const rowTrack = parts[1];
+    if (rowTrack) {
+      rowTracks.push(parseTrackSpec(rowTrack));
+    }
+  }
+  if (!areaGrid.length) {
+    throw new Error("Template must include at least one area row.");
+  }
+  const expectedWidth = areaGrid[0].length;
+  for (let rowIndex = 0; rowIndex < areaGrid.length; rowIndex++) {
+    const width = areaGrid[rowIndex].length;
+    if (width !== expectedWidth) {
+      throw new Error(
+        `All area rows must have the same width. Expected ${expectedWidth}, received ${width} at row ${rowIndex + 1}.`
+      );
+    }
+  }
+  if (colTracks && colTracks.length !== expectedWidth) {
+    throw new Error(
+      `Column track count must match area width. Expected ${expectedWidth}, received ${colTracks.length}.`
+    );
+  }
+  const areaNames = Array.from(
+    new Set(
+      areaGrid.flat().map((name) => name.trim()).filter((name) => !!name && name !== ".")
+    )
+  );
+  return {
+    areaGrid,
+    rowTracks,
+    colTracks: colTracks || [],
+    areaNames
+  };
+};
+
+// src/app/utils/easy-layout/computeAreaBounds.ts
+var computeAreaBounds = (parsed) => {
+  const result = {};
+  for (let rowIndex = 0; rowIndex < parsed.areaGrid.length; rowIndex++) {
+    const row = parsed.areaGrid[rowIndex];
+    for (let colIndex = 0; colIndex < row.length; colIndex++) {
+      const name = row[colIndex];
+      if (!name || name === ".") {
+        continue;
+      }
+      const row1 = rowIndex + 1;
+      const col1 = colIndex + 1;
+      const existing = result[name];
+      if (!existing) {
+        result[name] = {
+          name,
+          rowStart: row1,
+          rowEnd: row1,
+          colStart: col1,
+          colEnd: col1
+        };
+        continue;
+      }
+      existing.rowStart = Math.min(existing.rowStart, row1);
+      existing.rowEnd = Math.max(existing.rowEnd, row1);
+      existing.colStart = Math.min(existing.colStart, col1);
+      existing.colEnd = Math.max(existing.colEnd, col1);
+    }
+  }
+  return result;
+};
+
+// src/app/utils/easy-layout/validateAreas.ts
+var validateAreas = (parsed) => {
+  const bounds = computeAreaBounds(parsed);
+  for (const areaName of parsed.areaNames) {
+    const bound = bounds[areaName];
+    if (!bound) {
+      continue;
+    }
+    for (let row = bound.rowStart; row <= bound.rowEnd; row++) {
+      for (let col = bound.colStart; col <= bound.colEnd; col++) {
+        const token = parsed.areaGrid[row - 1]?.[col - 1];
+        if (token !== areaName) {
+          throw new Error(
+            `Area "${areaName}" must be a rectangle. Missing "${areaName}" at row ${row}, col ${col}.`
+          );
+        }
+      }
+    }
+  }
+};
+
+// src/app/forms/core/getFieldKind.ts
+var hasSelectableValues = (field) => {
+  const possibleValues = field.possibleValues ?? [];
+  return possibleValues.some(
+    (value) => typeof value === "string" || typeof value === "number"
+  );
+};
+var getFieldKind = (field) => {
+  if (field.typeReference) {
+    return field.array ? "relation_array" : "relation_single";
+  }
+  if (field.tags?.customType) {
+    return field.array ? "custom_array" : "custom_single";
+  }
+  if (field.array) {
+    return "array";
+  }
+  if (hasSelectableValues(field)) {
+    return "enum_select";
+  }
+  if (field.type === "boolean") {
+    return "boolean";
+  }
+  if (field.type === "number") {
+    return "number";
+  }
+  return "string";
+};
+
+// src/app/forms/core/resolveSuite.ts
+var fieldKinds = [
+  "string",
+  "number",
+  "boolean",
+  "enum_select",
+  "array",
+  "relation_single",
+  "relation_array",
+  "custom_single",
+  "custom_array"
+];
+var getMissingKinds = (renderers) => {
+  return fieldKinds.filter((kind) => !renderers[kind]);
+};
+var resolveSuite = (overrides, fallback) => {
+  const mergedRenderers = {
+    ...fallback.renderers ?? {},
+    ...overrides?.renderers ?? {}
+  };
+  const missingKinds = getMissingKinds(mergedRenderers);
+  if (missingKinds.length) {
+    throw new Error(
+      `Missing renderers for field kinds: ${missingKinds.join(", ")}`
+    );
+  }
+  const mergedPrimitives = {
+    ...fallback.primitives ?? {},
+    ...overrides?.primitives ?? {}
+  };
+  return {
+    renderers: mergedRenderers,
+    primitives: Object.keys(mergedPrimitives).length ? mergedPrimitives : void 0
+  };
+};
+
+// src/app/forms/core/createAutoField.ts
+var createAutoField = (suite) => {
+  const renderField = (props) => {
+    const { field, fieldKey, value, onChange, error, disabled } = props;
+    const { tags } = field;
+    const context = {
+      field,
+      fieldKey,
+      label: tags?.label ?? fieldKey,
+      required: !field.optional,
+      disabled: !!disabled,
+      error,
+      value,
+      onChange,
+      constraints: tags?.constraints,
+      format: tags?.format,
+      possibleValues: field.possibleValues,
+      allowCustomSelection: tags?.allowCustomSelection,
+      customType: tags?.customType,
+      onRelationAction: props.onRelationAction,
+      onCustomTypeAction: props.onCustomTypeAction,
+      renderField
+    };
+    const kind = getFieldKind(field);
+    return suite.renderers[kind](context);
+  };
+  return renderField;
+};
+
+// src/app/forms/core/createFormRenderer.ts
+var createFormRenderer = (options) => {
+  const resolvedSuite = resolveSuite(
+    options.suite,
+    options.fallbackSuite
+  );
+  const AutoField = createAutoField(resolvedSuite);
+  return {
+    AutoField,
+    suite: resolvedSuite
+  };
+};
+var getDeniedOperation = (deniedOperations, operation) => {
+  if (!deniedOperations) {
+    return false;
+  }
+  const denied = deniedOperations[operation];
+  if (typeof denied === "boolean") {
+    return denied;
+  }
+  return deniedOperations[operation.toLowerCase()] ?? false;
+};
+var buildInitialValues = (initialValues, typeInfo) => {
+  const values = { ...initialValues };
+  for (const [key, field] of Object.entries(typeInfo.fields ?? {})) {
+    if (values[key] !== void 0) {
+      continue;
+    }
+    const defaultValue = field.tags?.constraints?.defaultValue;
+    if (defaultValue !== void 0) {
+      let parsedDefaultValue = defaultValue;
+      try {
+        parsedDefaultValue = JSON.parse(defaultValue);
+      } catch (error) {
+      }
+      values[key] = parsedDefaultValue;
+      continue;
+    }
+    if (field.array && !field.typeReference && !field.optional) {
+      values[key] = [];
+      continue;
+    }
+    if (field.type === "boolean" && !field.optional) {
+      values[key] = false;
+    }
+  }
+  return values;
+};
+var useFormEngine = (initialValues = {}, typeInfo, options) => {
+  const operation = options?.operation ?? "CREATE" /* CREATE */;
+  const [values, setValues] = useState(
+    buildInitialValues(initialValues, typeInfo)
+  );
+  const [errors, setErrors] = useState({});
+  const setFieldValue = useCallback((path, value) => {
+    setValues((prev) => {
+      return {
+        ...prev,
+        [path]: value
+      };
+    });
+  }, []);
+  const validate = useCallback(() => {
+    const newErrors = {};
+    for (const [key, field] of Object.entries(typeInfo.fields ?? {})) {
+      if (field.tags?.hidden) {
+        continue;
+      }
+      const val = values[key];
+      if (field.readonly && (val === void 0 || val === null || val === "")) {
+        continue;
+      }
+      const isMissing = val === void 0 || val === null || val === "" || field.array && (!Array.isArray(val) || val.length === 0);
+      if (!field.optional && isMissing) {
+        newErrors[key] = "This field is required";
+        continue;
+      }
+      if (isMissing) {
+        continue;
+      }
+      const constraints = field.tags?.constraints;
+      if (constraints?.pattern && typeof val === "string") {
+        const pattern = new RegExp(constraints.pattern);
+        if (!pattern.test(val)) {
+          newErrors[key] = "Value does not match required pattern";
+          continue;
+        }
+      }
+      if (field.type === "number" && typeof val === "number") {
+        if (constraints?.min !== void 0 && val < constraints.min) {
+          newErrors[key] = `Value must be at least ${constraints.min}`;
+          continue;
+        }
+        if (constraints?.max !== void 0 && val > constraints.max) {
+          newErrors[key] = `Value must be at most ${constraints.max}`;
+          continue;
+        }
+      }
+    }
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [typeInfo, values]);
+  const fields = useMemo(() => {
+    return Object.entries(typeInfo.fields ?? {}).map(([key, field]) => {
+      const { tags } = field;
+      const isPrimary = tags?.primaryField || typeInfo.primaryField === key;
+      return {
+        key,
+        field,
+        label: tags?.label ?? key,
+        required: !field.optional,
+        disabled: field.readonly || getDeniedOperation(typeInfo.tags?.deniedOperations, operation) || getDeniedOperation(tags?.deniedOperations, operation) || operation === "UPDATE" /* UPDATE */ && isPrimary,
+        hidden: !!tags?.hidden,
+        primary: isPrimary,
+        format: tags?.format,
+        constraints: tags?.constraints,
+        value: values[key],
+        onChange: (value) => setFieldValue(key, value),
+        error: errors[key]
+      };
+    });
+  }, [typeInfo, values, errors, setFieldValue, operation]);
+  return {
+    typeInfo,
+    typeTags: typeInfo.tags,
+    operation,
+    values,
+    errors,
+    fields,
+    setFieldValue,
+    validate,
+    setErrors
+  };
+};
+var fallbackFormRoot = ({
+  children,
+  onSubmit
+}) => {
+  const handleSubmit = (event) => {
+    event.preventDefault();
+    onSubmit?.();
+  };
+  return /* @__PURE__ */ jsx("form", { onSubmit: handleSubmit, children });
+};
+var fallbackButton = ({
+  children,
+  disabled,
+  type,
+  onClick
+}) => {
+  return /* @__PURE__ */ jsx("button", { type: type ?? "button", disabled, onClick, children });
+};
+var AutoFormView = ({
+  controller,
+  onSubmit,
+  renderer,
+  submitDisabled,
+  onRelationAction,
+  onCustomTypeAction
+}) => {
+  const FormRoot = renderer.suite.primitives?.FormRoot ?? fallbackFormRoot;
+  const Button = renderer.suite.primitives?.Button ?? fallbackButton;
+  const AutoField = renderer.AutoField;
+  const submit = () => {
+    if (controller.validate()) {
+      onSubmit(controller.values);
+    }
+  };
+  return /* @__PURE__ */ jsx(FormRoot, { onSubmit: submit, children: /* @__PURE__ */ jsxs(Fragment, { children: [
+    controller.fields.filter((fieldController) => !fieldController.hidden).map((fieldController) => /* @__PURE__ */ jsx(
+      AutoField,
+      {
+        field: fieldController.field,
+        fieldKey: fieldController.key,
+        value: fieldController.value,
+        onChange: fieldController.onChange,
+        error: fieldController.error,
+        onRelationAction,
+        disabled: fieldController.disabled,
+        onCustomTypeAction
+      },
+      fieldController.key
+    )),
+    /* @__PURE__ */ jsx(Button, { type: "submit", onClick: submit, disabled: submitDisabled, children: /* @__PURE__ */ jsx(Fragment, { children: "Submit" }) })
+  ] }) });
+};
+var AutoForm = ({
+  typeInfo,
+  onSubmit,
+  renderer,
+  initialValues,
+  onValuesChange,
+  onRelationAction,
+  onCustomTypeAction,
+  operation,
+  submitDisabled
+}) => {
+  const controller = useFormEngine(initialValues, typeInfo, { operation });
+  useEffect(() => {
+    if (onValuesChange) {
+      onValuesChange(controller.values);
+    }
+  }, [controller.values, onValuesChange]);
+  return /* @__PURE__ */ jsx(
+    AutoFormView,
+    {
+      controller,
+      onSubmit,
+      renderer,
+      onRelationAction,
+      onCustomTypeAction,
+      submitDisabled
+    }
+  );
+};
+
+export { AutoForm, AutoFormView, computeAreaBounds, createAutoField, createFormRenderer, getFieldKind, parseTemplate, resolveSuite, useFormEngine, validateAreas };

package/common/CommandLine/collectRequiredEnvironmentVariables.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Collect required environment variables or throw with a missing-name error.
+ *
+ * @typeParam VarName - Allowed environment variable names.
+ * @param varNames - List of required environment variable names.
+ * @returns Map of environment variable names to values.
+ * @throws Error when a required variable is missing or empty.
+ */
+export declare const collectRequiredEnvironmentVariables: <VarName extends string>(varNames: VarName[]) => Record<VarName, string>;

package/common/CommandLine/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @packageDocumentation
+ *
+ * Command-line utilities.
+ */
+export * from "./collectRequiredEnvironmentVariables";

package/common/HelperTypes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Expand inferred types for clearer IntelliSense/display.
+ *
+ * @typeParam T - Type to expand.
+ */
+export type ExpandComplexType<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export declare const HelperTypes: {};

package/common/IdGeneration/getSimpleId.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Get a simple id, unique to the current run session.
+ *
+ * Includes a counter and timestamp so it stays unique within the same process.
+ *
+ * @returns A process-unique string id.
+ */
+export declare const getSimpleId: () => string;

package/{src/common → common}/ItemRelationshipInfoTypes.d.ts

@@ -1,17 +1,35 @@
-import { ExpandComplexType } from "./HelperTypes";
+/**
+ * Relationship info types used by ORM and relationship utilities.
+ */
+import type { ExpandComplexType } from "./HelperTypes";
 /**
  * The keys for item relationship info.
  * */
 export declare enum ItemRelationshipInfoKeys {
+    /**
+     * Relationship origin type name.
+     * */
     fromTypeName = "fromTypeName",
+    /**
+     * Relationship origin field name.
+     * */
     fromTypeFieldName = "fromTypeFieldName",
+    /**
+     * Relationship origin primary field value.
+     * */
     fromTypePrimaryFieldValue = "fromTypePrimaryFieldValue",
+    /**
+     * Relationship destination primary field value.
+     * */
     toTypePrimaryFieldValue = "toTypePrimaryFieldValue"
 }
 /**
  * The identifying keys for item relationship info.
  * */
 export declare enum ItemRelationshipInfoIdentifyingKeys {
+    /**
+     * Identifier value for a relationship item.
+     * */
     id = "id"
 }
 /**

package/common/ItemRelationships/ItemRelationshipValidation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validation helpers for relationship items.
+ */
+import { TypeInfoValidationResults } from "../TypeParsing/Validation";
+import { ItemRelationshipInfoKeys, ItemRelationshipInfoType } from "../ItemRelationshipInfoTypes";
+/**
+ * Error codes for relationship validation.
+ * */
+export declare const TYPE_INFO_ORM_RELATIONSHIP_ERRORS: {
+    INVALID_RELATIONSHIP_ITEM: string;
+    INVALID_RELATIONSHIP_ITEM_FIELD: string;
+    MISSING_RELATIONSHIP_ITEM_FIELD: string;
+};
+/**
+ * Validates a relationship item.
+ *
+ * @param relationshipItem - Relationship item to validate.
+ * @param omitFields - Relationship keys to ignore during validation.
+ * @returns Validation results with errors and errorMap when invalid.
+ * */
+export declare const validateRelationshipItem: (relationshipItem: ItemRelationshipInfoType, omitFields: ItemRelationshipInfoKeys[]) => TypeInfoValidationResults;

package/common/ItemRelationships/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./ItemRelationshipValidation";
+/**
+ * @category common
+ * @group Type Dependencies
+ */
+export type { TypeInfoValidationResults, } from "../TypeParsing/Validation";

package/common/Logging/Utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Logging tags used by {@link logFunctionCall}.
+ */
+export declare enum LOGGING_MESSAGES {
+    LOGGING_FUNCTION_CALL = "LOGGING_FUNCTION_CALL",
+    INPUT = "INPUT",
+    OUTPUT = "OUTPUT",
+    ERROR = "ERROR"
+}
+/**
+ * Make a function call and log input/output/errors when enabled.
+ *
+ * @param label - Label to include in logs.
+ * @param args - Arguments passed to the function.
+ * @param functionRef - Function to execute.
+ * @param enabled - Whether to emit logs.
+ * @returns The function result.
+ */
+export declare const logFunctionCall: (label: string, args: any[], functionRef: (...args: any[]) => Promise<any> | any, enabled: boolean) => Promise<any>;

package/common/Routing.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Helpers for parsing and composing path strings used by the Router utilities.
+ */
+/**
+ * The delimiter used to separate paths.
+ */
+export declare const PATH_DELIMITER = "/";
+/**
+ * Parse a string into JSON if possible, otherwise return the raw value.
+ *
+ * @param value - Input string to parse.
+ * @returns Parsed JSON or the original string.
+ */
+export declare const getPotentialJSONValue: (value: string) => any;
+/**
+ * Get the path segments from a path string.
+ *
+ * @param path - Path string to split.
+ * @param delimiter - Delimiter used to split the path.
+ * @param filterEmptyOutput - Whether to remove empty output segments.
+ * @param filterEmptyInput - Whether to remove empty input segments.
+ * @param useJson - Whether to parse each segment as JSON.
+ * @param uriDecodeParts - Whether to URI-decode each segment.
+ * @returns Array of path segments.
+ * */
+export declare const getPathArray: (path: string, delimiter?: string, filterEmptyOutput?: boolean, filterEmptyInput?: boolean, useJson?: boolean, uriDecodeParts?: boolean) => any[];
+/**
+ * Get the path string from path segments.
+ *
+ * @param parts - Path segments to join.
+ * @param delimiter - Delimiter used to join the path.
+ * @param filterEmptyInput - Whether to remove empty input segments.
+ * @param useJson - Whether to JSON-stringify each segment.
+ * @param uriEncodeParts - Whether to URI-encode each segment.
+ * @returns Joined path string.
+ * */
+export declare const getPathString: (parts?: any[], delimiter?: string, filterEmptyInput?: boolean, useJson?: boolean, uriEncodeParts?: boolean) => string;
+/**
+ * Merge two path strings.
+ *
+ * @param path1 - First path string.
+ * @param path2 - Second path string.
+ * @param delimiter - Delimiter used to split and join paths.
+ * @param filterEmptyOutput - Whether to remove empty output segments.
+ * @param filterEmptyInput - Whether to remove empty input segments.
+ * @param useJson - Whether to parse/serialize segments as JSON.
+ * @param uriEncodeParts - Whether to URI-encode each segment.
+ * @returns Merged path string.
+ * */
+export declare const mergeStringPaths: (path1: string, path2: string, delimiter?: string, filterEmptyOutput?: boolean, filterEmptyInput?: boolean, useJson?: boolean, uriEncodeParts?: boolean) => string;
+/**
+ * Resolve a path string against another path string.
+ *
+ * @param currentPath - Base path to resolve against.
+ * @param newPath - New path to resolve, absolute or relative.
+ * @returns Resolved path string.
+ * */
+export declare const resolvePath: (currentPath: string, newPath: string) => string;
+/**
+ * Get the parameter values from a path string and test the `path` against a `testPath`.
+ *
+ * @param path - Actual path to test.
+ * @param testPath - Route pattern to match against.
+ * @param exact - Whether to require an exact match.
+ * @returns Params object when matched, otherwise false.
+ * */
+export declare const getParamsAndTestPath: (path: string, testPath: string, exact?: boolean) => Record<string, any> | false;