@holo-js/forms 0.2.5 → 0.3.0

package/dist/internal/client.d.ts

@@ -27,6 +27,7 @@ interface UseFormOptions<TData, TSuccess = unknown> {
     readonly initialState?: SerializedFormSubmission<TData> | FormFailurePayload<TData> | null;
     readonly submitter?: (context: ClientSubmitContext<TData>) => Promise<ClientSubmitResult<TData, TSuccess> | void> | ClientSubmitResult<TData, TSuccess> | void;
 }
+declare function markClientSubmitControlFlowError(error: unknown): unknown;
 interface FormFieldState<TValue> {
     value: TValue;
     readonly errors: readonly string[];
@@ -65,4 +66,4 @@ declare function runWithBrowserFormElement<TData, TSuccess>(formClient: Pick<Use
  */
 declare function createFormClient<TSchema extends FormSchema, TSuccess = unknown>(schemaDefinition: TSchema, options?: UseFormOptions<InferFormData<TSchema>, TSuccess>): UseFormResult<InferFormData<TSchema>, TSuccess, InferFormFieldTree<TSchema>>;
 
-export { type ClientSubmitContext, type ClientSubmitResult, type FormFieldState, type FormFieldTree, type InferFormFieldTree, type UseFormOptions, type UseFormResult, type ValidateOnMode, createFormClient, runWithBrowserFormElement };
+export { type ClientSubmitContext, type ClientSubmitResult, type FormFieldState, type FormFieldTree, type InferFormFieldTree, type UseFormOptions, type UseFormResult, type ValidateOnMode, createFormClient, markClientSubmitControlFlowError, runWithBrowserFormElement };

package/dist/internal/client.mjs

@@ -133,11 +133,139 @@ function validationExceptionToFailure(error, fallbackValues = {}) {
   return void 0;
 }
 
+// src/internal/formValues.ts
+function isPlainFormObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof Blob);
+}
+function isSchemaFieldLike(value) {
+  return !!value && typeof value === "object" && value.kind === "field" && !!value.definition && typeof value.definition === "object";
+}
+function areFormValuesEqual(left, right) {
+  if (Object.is(left, right)) return true;
+  if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  if (left instanceof Blob || right instanceof Blob) return false;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => areFormValuesEqual(value, right[index]));
+  }
+  if (isPlainFormObject(left) && isPlainFormObject(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    return leftKeys.length === rightKeys.length && leftKeys.every((key) => key in right && areFormValuesEqual(left[key], right[key]));
+  }
+  return false;
+}
+function cloneFormValue(value) {
+  if (Array.isArray(value)) return value.map((item) => cloneFormValue(item));
+  if (value instanceof Date) return new Date(value.getTime());
+  if (isPlainFormObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, cloneFormValue(entry)])
+    );
+  }
+  return value;
+}
+function isFormLeafValue(value) {
+  return Array.isArray(value) || value instanceof Date || value instanceof Blob || isSchemaFieldLike(value) || !isPlainFormObject(value);
+}
+function normalizeFormObject(value) {
+  return isPlainFormObject(value) ? cloneFormValue(value) : {};
+}
+function mergeFormValues(base, override) {
+  if (!override || !isPlainFormObject(override)) return cloneFormValue(base);
+  const output = cloneFormValue(base);
+  for (const [key, value] of Object.entries(override)) {
+    if (typeof value === "undefined" && key in output) continue;
+    if (isPlainFormObject(value) && isPlainFormObject(output[key])) {
+      output[key] = mergeFormValues(output[key], value);
+      continue;
+    }
+    output[key] = cloneFormValue(value);
+  }
+  return output;
+}
+function splitFormPath(path) {
+  return path.split(".").map((part) => part.trim()).filter(Boolean);
+}
+function getFormValueAtPath(root, path) {
+  let cursor = root;
+  for (const part of splitFormPath(path)) {
+    if (!isPlainFormObject(cursor) && !Array.isArray(cursor)) return void 0;
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+function setFormValueAtPath(root, path, value) {
+  const parts = splitFormPath(path);
+  let cursor = root;
+  for (const [index, part] of parts.entries()) {
+    const last = index === parts.length - 1;
+    const nextPart = parts[index + 1];
+    if (!nextPart && !last) return;
+    if (Array.isArray(cursor)) {
+      const offset = Number(part);
+      if (!Number.isInteger(offset) || offset < 0) return;
+      if (last) {
+        cursor[offset] = value;
+        return;
+      }
+      const existing2 = cursor[offset];
+      if (!isPlainFormObject(existing2) && !Array.isArray(existing2)) cursor[offset] = /^\d+$/.test(nextPart) ? [] : {};
+      cursor = cursor[offset];
+      continue;
+    }
+    if (last) {
+      cursor[part] = value;
+      return;
+    }
+    const existing = cursor[part];
+    if (!isPlainFormObject(existing) && !Array.isArray(existing)) cursor[part] = /^\d+$/.test(nextPart) ? [] : {};
+    cursor = cursor[part];
+  }
+}
+function flattenFormLeafPaths(value, prefix = "") {
+  if (isFormLeafValue(value)) return [prefix].filter(Boolean);
+  return Object.entries(value).flatMap(([key, nested]) => {
+    return flattenFormLeafPaths(nested, prefix ? `${prefix}.${key}` : key);
+  });
+}
+function buildFormData(value, path = "", formData = new FormData()) {
+  if (typeof value === "undefined") return formData;
+  if (value instanceof Date) {
+    formData.append(path, value.toISOString());
+    return formData;
+  }
+  if (value instanceof Blob) {
+    formData.append(path, value);
+    return formData;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) buildFormData(item, `${path}[]`, formData);
+    return formData;
+  }
+  if (isPlainFormObject(value)) {
+    for (const [key, nested] of Object.entries(value)) buildFormData(nested, path ? `${path}.${key}` : key, formData);
+    return formData;
+  }
+  formData.append(path, String(value));
+  return formData;
+}
+
 // src/internal/client.ts
 var browserFormSubmitSymbol = /* @__PURE__ */ Symbol("browserFormSubmit");
+var clientSubmitControlFlowErrors = /* @__PURE__ */ new WeakSet();
 function isBrowserFormSubmitter(value) {
   return browserFormSubmitSymbol in value;
 }
+function markClientSubmitControlFlowError(error) {
+  if (!error || typeof error !== "object" && typeof error !== "function") {
+    return error;
+  }
+  clientSubmitControlFlowErrors.add(error);
+  return error;
+}
+function isClientSubmitControlFlowError(error) {
+  return !!error && (typeof error === "object" || typeof error === "function") && clientSubmitControlFlowErrors.has(error);
+}
 var transportFailureMessage = "Unable to submit the form right now. Please try again.";
 function serializeSubmissionState(valid, values, errors, schemaDefinition) {
   return Object.freeze({
@@ -232,152 +360,6 @@ async function validateClientValues(values, schemaDefinition) {
     result.errors.flatten()
   );
 }
-function isPlainObject2(value) {
-  return !!value && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof Blob);
-}
-function isSchemaFieldLike(value) {
-  return !!value && typeof value === "object" && value.kind === "field" && !!value.definition && typeof value.definition === "object";
-}
-function areEqual(left, right) {
-  if (Object.is(left, right)) {
-    return true;
-  }
-  if (left instanceof Date && right instanceof Date) {
-    return left.getTime() === right.getTime();
-  }
-  if (left instanceof Blob || right instanceof Blob) {
-    return false;
-  }
-  if (Array.isArray(left) && Array.isArray(right)) {
-    return left.length === right.length && left.every((value, index) => areEqual(value, right[index]));
-  }
-  if (isPlainObject2(left) && isPlainObject2(right)) {
-    const leftKeys = Object.keys(left);
-    const rightKeys = Object.keys(right);
-    return leftKeys.length === rightKeys.length && leftKeys.every((key) => key in right && areEqual(left[key], right[key]));
-  }
-  return false;
-}
-function cloneValue(value) {
-  if (Array.isArray(value)) {
-    return value.map((item) => cloneValue(item));
-  }
-  if (value instanceof Date) {
-    return new Date(value.getTime());
-  }
-  if (isPlainObject2(value)) {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, entry]) => [key, cloneValue(entry)])
-    );
-  }
-  return value;
-}
-function isLeafValue(value) {
-  return Array.isArray(value) || value instanceof Date || value instanceof Blob || isSchemaFieldLike(value) || !isPlainObject2(value);
-}
-function normalizeObject(value) {
-  return isPlainObject2(value) ? cloneValue(value) : {};
-}
-function mergeValues(base, override) {
-  if (!override || !isPlainObject2(override)) {
-    return cloneValue(base);
-  }
-  const output = cloneValue(base);
-  for (const [key, value] of Object.entries(override)) {
-    if (typeof value === "undefined" && key in output) {
-      continue;
-    }
-    if (isPlainObject2(value) && isPlainObject2(output[key])) {
-      output[key] = mergeValues(output[key], value);
-      continue;
-    }
-    output[key] = cloneValue(value);
-  }
-  return output;
-}
-function splitPath(path) {
-  return path.split(".").map((part) => part.trim()).filter(Boolean);
-}
-function getValueAtPath(root, path) {
-  let cursor = root;
-  for (const part of splitPath(path)) {
-    if (!isPlainObject2(cursor) && !Array.isArray(cursor)) {
-      return void 0;
-    }
-    cursor = cursor[part];
-  }
-  return cursor;
-}
-function setValueAtPath(root, path, value) {
-  const parts = splitPath(path);
-  let cursor = root;
-  for (const [index, part] of parts.entries()) {
-    const last = index === parts.length - 1;
-    const nextPart = parts[index + 1];
-    if (Array.isArray(cursor)) {
-      const offset = Number(part);
-      if (!Number.isInteger(offset) || offset < 0) {
-        return;
-      }
-      if (last) {
-        cursor[offset] = value;
-        return;
-      }
-      const existing2 = cursor[offset];
-      if (!isPlainObject2(existing2) && !Array.isArray(existing2)) {
-        cursor[offset] = /^\d+$/.test(nextPart) ? [] : {};
-      }
-      cursor = cursor[offset];
-      continue;
-    }
-    if (last) {
-      cursor[part] = value;
-      return;
-    }
-    const existing = cursor[part];
-    if (!isPlainObject2(existing) && !Array.isArray(existing)) {
-      cursor[part] = /^\d+$/.test(nextPart) ? [] : {};
-    }
-    cursor = cursor[part];
-  }
-}
-function flattenLeafPaths(value, prefix = "") {
-  if (isLeafValue(value)) {
-    return [prefix].filter(Boolean);
-  }
-  return Object.entries(value).flatMap(([key, nested]) => {
-    const next = prefix ? `${prefix}.${key}` : key;
-    return flattenLeafPaths(nested, next);
-  });
-}
-function buildFormData(value, path = "", formData = new FormData()) {
-  if (typeof value === "undefined") {
-    return formData;
-  }
-  if (value instanceof Date) {
-    formData.append(path, value.toISOString());
-    return formData;
-  }
-  if (value instanceof Blob) {
-    formData.append(path, value);
-    return formData;
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      buildFormData(item, `${path}[]`, formData);
-    }
-    return formData;
-  }
-  if (isPlainObject2(value)) {
-    for (const [key, nested] of Object.entries(value)) {
-      const next = path ? `${path}.${key}` : key;
-      buildFormData(nested, next, formData);
-    }
-    return formData;
-  }
-  formData.append(path, String(value));
-  return formData;
-}
 function getActiveElementBrowserForm() {
   const activeElement = globalThis.document?.activeElement;
   return activeElement?.form ?? void 0;
@@ -432,11 +414,11 @@ function replaceErrorsForPath(flattenedErrors, path, nextErrors) {
   return merged;
 }
 function buildFieldsTree(state, schemaDefinition, source, validateOn, prefix = "") {
-  if (isLeafValue(source)) {
+  if (isFormLeafValue(source)) {
     const path = prefix;
     return Object.freeze({
       get value() {
-        return getValueAtPath(state.values, path);
+        return getFormValueAtPath(state.values, path);
       },
       set value(next) {
         void this.set(next);
@@ -451,9 +433,9 @@ function buildFieldsTree(state, schemaDefinition, source, validateOn, prefix = "
         return state.dirty.has(path);
       },
       async set(value) {
-        setValueAtPath(state.values, path, value);
+        setFormValueAtPath(state.values, path, value);
         state.touched.add(path);
-        if (!areEqual(getValueAtPath(state.initialValues, path), value)) {
+        if (!areFormValuesEqual(getFormValueAtPath(state.initialValues, path), value)) {
           state.dirty.add(path);
         } else {
           state.dirty.delete(path);
@@ -461,7 +443,7 @@ function buildFieldsTree(state, schemaDefinition, source, validateOn, prefix = "
         if (validateOn === "change") {
           const sequence = nextValidationSequence(state);
           const submission = await validateClientValues(
-            cloneValue(state.values),
+            cloneFormValue(state.values),
             schemaDefinition
           );
           if (isLatestValidation(state, sequence)) {
@@ -478,7 +460,7 @@ function buildFieldsTree(state, schemaDefinition, source, validateOn, prefix = "
         if (validateOn === "blur") {
           const sequence = nextValidationSequence(state);
           const submission = await validateClientValues(
-            cloneValue(state.values),
+            cloneFormValue(state.values),
             schemaDefinition
           );
           if (isLatestValidation(state, sequence)) {
@@ -493,7 +475,7 @@ function buildFieldsTree(state, schemaDefinition, source, validateOn, prefix = "
       },
       async validate() {
         const sequence = nextValidationSequence(state);
-        const submission = await validateClientValues(cloneValue(state.values), schemaDefinition);
+        const submission = await validateClientValues(cloneFormValue(state.values), schemaDefinition);
         if (isLatestValidation(state, sequence)) {
           state.flattenedErrors = submission.errors.flatten();
           notifyListeners(state);
@@ -515,13 +497,13 @@ function isSerializedSubmission(value) {
   return "submitted" in value && "errors" in value && "values" in value && !("ok" in value);
 }
 function isFormFailurePayload2(value) {
-  return isPlainObject2(value) && value.ok === false && typeof value.status === "number" && value.valid === false && isPlainObject2(value.values) && isPlainObject2(value.errors);
+  return isPlainFormObject(value) && value.ok === false && typeof value.status === "number" && value.valid === false && isPlainFormObject(value.values) && isPlainFormObject(value.errors);
 }
 function isSvelteKitActionFailureResult(value) {
-  return isPlainObject2(value) && value.type === "failure" && typeof value.status === "number" && typeof value.data === "string";
+  return isPlainFormObject(value) && value.type === "failure" && typeof value.status === "number" && typeof value.data === "string";
 }
 function isSvelteKitActionErrorResult(value) {
-  return isPlainObject2(value) && value.type === "error" && isPlainObject2(value.error);
+  return isPlainFormObject(value) && value.type === "error" && isPlainFormObject(value.error);
 }
 function parseJsonObject(value) {
   try {
@@ -648,13 +630,13 @@ function isSafeMethod(method) {
 }
 function createFormClient(schemaDefinition, options = {}) {
   const initialState = options.initialState ?? void 0;
-  const initialValues = mergeValues(
-    normalizeObject(options.initialValues),
-    normalizeObject(initialState?.values)
+  const initialValues = mergeFormValues(
+    normalizeFormObject(options.initialValues),
+    normalizeFormObject(initialState?.values)
   );
   const state = {
-    values: cloneValue(initialValues),
-    initialValues: cloneValue(initialValues),
+    values: cloneFormValue(initialValues),
+    initialValues: cloneFormValue(initialValues),
     flattenedErrors: { ...initialState?.errors ?? {} },
     touched: /* @__PURE__ */ new Set(),
     dirty: /* @__PURE__ */ new Set(),
@@ -664,7 +646,7 @@ function createFormClient(schemaDefinition, options = {}) {
     validationSequence: 0
   };
   const validateOn = options.validateOn ?? "submit";
-  const fieldPaths = flattenLeafPaths(schemaDefinition.fields);
+  const fieldPaths = flattenFormLeafPaths(schemaDefinition.fields);
   const fields = buildFieldsTree(
     state,
     schemaDefinition,
@@ -672,13 +654,13 @@ function createFormClient(schemaDefinition, options = {}) {
     validateOn
   );
   async function runValidation() {
-    return await runValidationForInput(cloneValue(state.values));
+    return await runValidationForInput(cloneFormValue(state.values));
   }
   async function runValidationForInput(input) {
     const sequence = nextValidationSequence(state);
     const submission = await validateClientValues(input, schemaDefinition);
     if (isLatestValidation(state, sequence)) {
-      state.values = mergeValues(
+      state.values = mergeFormValues(
         state.values,
         submission.valid ? submission.data : submission.values
       );
@@ -704,7 +686,7 @@ function createFormClient(schemaDefinition, options = {}) {
         ...normalized,
         values: sanitizeFlashedInput(normalized.values, schemaDefinition)
       };
-      state.values = mergeValues(state.values, sanitized.values);
+      state.values = mergeFormValues(state.values, sanitized.values);
       clearSensitiveInputValues(state.values, schemaDefinition);
       state.flattenedErrors = sanitized.errors;
       state.lastSubmission = sanitized;
@@ -712,7 +694,7 @@ function createFormClient(schemaDefinition, options = {}) {
       return sanitized;
     }
     const normalizedSubmission = normalized;
-    state.values = mergeValues(state.values, normalizedSubmission.values);
+    state.values = mergeFormValues(state.values, normalizedSubmission.values);
     clearSensitiveInputValues(state.values, schemaDefinition);
     state.flattenedErrors = normalizedSubmission.errors.flatten();
     state.lastSubmission = normalizedSubmission.valid ? void 0 : normalizedSubmission.fail();
@@ -748,6 +730,9 @@ function createFormClient(schemaDefinition, options = {}) {
           formData
         });
       } catch (error) {
+        if (isClientSubmitControlFlowError(error)) {
+          throw error;
+        }
         return applyServerState(
           validationExceptionToFailure(error, state.values) ?? createTransportFailure(state.values)
         );
@@ -799,9 +784,9 @@ function createFormClient(schemaDefinition, options = {}) {
       return submit(form);
     },
     reset(values) {
-      const next = mergeValues(state.initialValues, values);
-      state.values = cloneValue(next);
-      state.initialValues = cloneValue(next);
+      const next = mergeFormValues(state.initialValues, values);
+      state.values = cloneFormValue(next);
+      state.initialValues = cloneFormValue(next);
       state.flattenedErrors = {};
       state.touched.clear();
       state.dirty.clear();
@@ -809,9 +794,9 @@ function createFormClient(schemaDefinition, options = {}) {
       notifyListeners(state);
     },
     async setValue(path, value) {
-      setValueAtPath(state.values, path, value);
+      setFormValueAtPath(state.values, path, value);
       state.touched.add(path);
-      if (!areEqual(getValueAtPath(state.initialValues, path), value)) {
+      if (!areFormValuesEqual(getFormValueAtPath(state.initialValues, path), value)) {
         state.dirty.add(path);
       } else {
         state.dirty.delete(path);
@@ -829,5 +814,6 @@ function createFormClient(schemaDefinition, options = {}) {
 }
 export {
   createFormClient,
+  markClientSubmitControlFlowError,
   runWithBrowserFormElement
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/forms",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Holo-JS Framework - forms-first validation and submission contracts",
   "type": "module",
   "license": "MIT",
@@ -33,10 +33,10 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@holo-js/validation": "^0.2.5"
+    "@holo-js/validation": "^0.3.0"
   },
   "peerDependencies": {
-    "@holo-js/security": "^0.2.5"
+    "@holo-js/security": "^0.3.0"
   },
   "peerDependenciesMeta": {
     "@holo-js/security": {