@coherent.js/forms 1.1.2 → 2.0.0-rc.0

package/dist/form-builder.js

@@ -8,6 +8,396 @@ function isEmailShaped(value) {
   return typeof value === "string" && value.length <= EMAIL_MAX_LENGTH && EMAIL_PATTERN.test(value);
 }
 
+// src/rules.js
+var BUILTIN = /* @__PURE__ */ Symbol("coherent.forms.builtin");
+var DESCRIPTORS = /* @__PURE__ */ new WeakMap();
+var HELPER_NAMES = /* @__PURE__ */ new Set(["get", "compose", "debounce", "cancellable", "when", "chain"]);
+var isEmpty = (value) => value === null || value === void 0 || value === "";
+var isOptionsObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof RegExp);
+function argsFromString(params, kind, text) {
+  if (text === void 0 || text.trim() === "") return [];
+  if (params.length === 0) return [text.trim()];
+  if (kind === "list") {
+    return [text.split(",").map((part) => part.trim()).filter(Boolean)];
+  }
+  if (kind === "regexp") {
+    try {
+      return [new RegExp(text)];
+    } catch {
+      return null;
+    }
+  }
+  const comma = text.indexOf(",");
+  const raw = (comma === -1 ? text : text.slice(0, comma)).trim();
+  const message = comma === -1 ? "" : text.slice(comma + 1).trim();
+  let arg = raw;
+  if (kind === "number") {
+    arg = Number(raw);
+    if (raw === "" || Number.isNaN(arg)) return null;
+  }
+  return message ? [arg, message] : [arg];
+}
+function defineRule(name, { params = [], stringArg = "string", valid, message }) {
+  const fromOptions = (options = {}) => {
+    const config = { message: options.message };
+    for (const [key, ...aliases] of params) {
+      config[key] = [key, ...aliases].map((alias) => options[alias]).find((v) => v !== void 0);
+    }
+    return config;
+  };
+  const check = (value, config, formData) => {
+    if (valid(value, config, formData || {})) return null;
+    return config.message || builtin.message || message(config);
+  };
+  const factory = (...args) => {
+    const config = { message: args[params.length] };
+    params.forEach(([key], index) => {
+      config[key] = args[index];
+    });
+    const rule = (value, formData, _translator, allValues) => check(value, config, allValues ?? formData);
+    DESCRIPTORS.set(rule, { name, args });
+    return rule;
+  };
+  const isDirectCall = (args) => {
+    if (args.length >= 2) {
+      return params.length === 0 || isOptionsObject(args[1]);
+    }
+    if (args.length === 1 && params.length === 0) {
+      const [arg] = args;
+      return arg === "" || arg !== void 0 && arg !== null && typeof arg !== "string";
+    }
+    return false;
+  };
+  function builtin(...args) {
+    if (isDirectCall(args)) {
+      const [value, options, , allValues] = args;
+      return check(value, fromOptions(isOptionsObject(options) ? options : {}), allValues);
+    }
+    return factory(...args);
+  }
+  Object.defineProperty(builtin, "name", { value: name });
+  builtin[BUILTIN] = {
+    name,
+    factory,
+    argsFromString: (text) => argsFromString(params, stringArg, text)
+  };
+  return builtin;
+}
+var toNumber = (value) => typeof value === "number" ? value : Number(value);
+function testRegExp(regex, value) {
+  if (!(regex instanceof RegExp)) return true;
+  regex.lastIndex = 0;
+  return regex.test(String(value));
+}
+function fileMatchesType(file, allowedTypes) {
+  const fileType = file.type;
+  const fileExt = file.name ? file.name.split(".").pop().toLowerCase() : "";
+  return allowedTypes.some((type) => {
+    if (type.startsWith(".")) {
+      return fileExt === type.slice(1).toLowerCase();
+    }
+    if (type.includes("/")) {
+      if (type.endsWith("/*")) {
+        return fileType.startsWith(type.replace("/*", "/"));
+      }
+      return fileType === type;
+    }
+    return fileExt === type.toLowerCase();
+  });
+}
+var validators = {
+  required: defineRule("required", {
+    valid: (value) => !isEmpty(value),
+    message: () => "This field is required"
+  }),
+  email: defineRule("email", {
+    valid: (value) => isEmpty(value) || isEmailShaped(value),
+    message: () => "Invalid email address"
+  }),
+  url: defineRule("url", {
+    valid: (value) => {
+      if (isEmpty(value)) return true;
+      try {
+        new URL(value);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    message: () => "Invalid URL"
+  }),
+  minLength: defineRule("minLength", {
+    params: [["min", "minLength"]],
+    stringArg: "number",
+    valid: (value, { min }) => !value || !(value.length < (min ?? 0)),
+    message: ({ min }) => `Minimum length is ${min}`
+  }),
+  maxLength: defineRule("maxLength", {
+    params: [["max", "maxLength"]],
+    stringArg: "number",
+    valid: (value, { max }) => !value || !(value.length > (max ?? Infinity)),
+    message: ({ max }) => `Maximum length is ${max}`
+  }),
+  // Empty values pass (combine with `required`); a non-numeric value fails.
+  min: defineRule("min", {
+    params: [["min"]],
+    stringArg: "number",
+    valid: (value, { min }) => {
+      if (isEmpty(value)) return true;
+      const number = toNumber(value);
+      return !Number.isNaN(number) && !(number < (min ?? -Infinity));
+    },
+    message: ({ min }) => `Minimum value is ${min}`
+  }),
+  max: defineRule("max", {
+    params: [["max"]],
+    stringArg: "number",
+    valid: (value, { max }) => {
+      if (isEmpty(value)) return true;
+      const number = toNumber(value);
+      return !Number.isNaN(number) && !(number > (max ?? Infinity));
+    },
+    message: ({ max }) => `Maximum value is ${max}`
+  }),
+  pattern: defineRule("pattern", {
+    params: [["pattern", "regex"]],
+    stringArg: "regexp",
+    valid: (value, { pattern }) => isEmpty(value) || testRegExp(pattern, value),
+    message: () => "Invalid format"
+  }),
+  /** Equal to another field, even when empty */
+  matches: defineRule("matches", {
+    params: [["field", "fieldName"]],
+    valid: (value, { field }, formData) => value === formData[field],
+    message: () => "Fields do not match"
+  }),
+  /** Equal to another field; an empty value passes */
+  match: defineRule("match", {
+    params: [["field", "fieldName"]],
+    valid: (value, { field }, formData) => !value || value === formData[field],
+    message: ({ field }) => `Must match ${field}`
+  }),
+  oneOf: defineRule("oneOf", {
+    params: [["options", "values"]],
+    stringArg: "list",
+    valid: (value, { options }) => !value || !Array.isArray(options) || options.includes(value),
+    message: () => "Invalid option"
+  }),
+  custom: defineRule("custom", {
+    params: [["validator", "fn"]],
+    valid: (value, { validator }, formData) => typeof validator !== "function" || Boolean(validator(value, formData)),
+    message: () => "Validation failed"
+  }),
+  number: defineRule("number", {
+    valid: (value) => isEmpty(value) || !Number.isNaN(Number(value)),
+    message: () => "Must be a valid number"
+  }),
+  integer: defineRule("integer", {
+    valid: (value) => isEmpty(value) || Number.isInteger(Number(value)),
+    message: () => "Must be a whole number"
+  }),
+  phone: defineRule("phone", {
+    valid: (value) => !value || /^[\d\s\-+()]+$/.test(value) && value.replace(/\D/g, "").length >= 10,
+    message: () => "Please enter a valid phone number"
+  }),
+  date: defineRule("date", {
+    valid: (value) => !value || !Number.isNaN(new Date(value).getTime()),
+    message: () => "Please enter a valid date"
+  }),
+  alpha: defineRule("alpha", {
+    valid: (value) => !value || /^[a-zA-Z]+$/.test(value),
+    message: () => "Must contain only letters"
+  }),
+  alphanumeric: defineRule("alphanumeric", {
+    valid: (value) => !value || /^[a-zA-Z0-9]+$/.test(value),
+    message: () => "Must contain only letters and numbers"
+  }),
+  uppercase: defineRule("uppercase", {
+    valid: (value) => !value || value === String(value).toUpperCase(),
+    message: () => "Must be uppercase"
+  }),
+  fileType: defineRule("fileType", {
+    params: [["accept", "types"]],
+    stringArg: "list",
+    valid: (value, { accept }) => !value || value.type === void 0 || fileMatchesType(value, accept || []),
+    message: ({ accept }) => `File type must be one of: ${(accept || []).join(", ")}`
+  }),
+  fileSize: defineRule("fileSize", {
+    params: [["maxSize"]],
+    stringArg: "number",
+    valid: (value, { maxSize }) => !value || value.size === void 0 || !(value.size > (maxSize ?? Infinity)),
+    message: ({ maxSize }) => `File size must be less than ${((maxSize ?? Infinity) / (1024 * 1024)).toFixed(2)}MB`
+  }),
+  fileExtension: defineRule("fileExtension", {
+    params: [["extensions"]],
+    stringArg: "list",
+    valid: (value, { extensions }) => {
+      if (!value) return true;
+      const fileName = value.name || value;
+      const ext = `.${String(fileName).split(".").pop().toLowerCase()}`;
+      return (extensions || []).some((allowed) => ext === allowed.toLowerCase());
+    },
+    message: ({ extensions }) => `File extension must be one of: ${(extensions || []).join(", ")}`
+  }),
+  /** A registered validator or built-in by name */
+  get: (name) => Object.hasOwn(validators, name) ? validators[name] : void 0,
+  /** Combine validators into one returning the first error */
+  compose: (validatorList) => {
+    const rules = validatorList.map(resolveValidator);
+    return (value, options, translator, allValues) => {
+      for (const rule of rules) {
+        const error = rule ? rule(value, options, translator, allValues) : null;
+        if (error) {
+          return error;
+        }
+      }
+      return null;
+    };
+  },
+  /** Debounce an async validator */
+  debounce: (validator, delay = 300) => {
+    let timeoutId;
+    return (value) => {
+      return new Promise((resolve) => {
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(async () => {
+          const result = await validator(value);
+          resolve(result);
+        }, delay);
+      });
+    };
+  },
+  /** Cancellable async validator */
+  cancellable: (validator) => {
+    let abortController;
+    const wrapped = async (value) => {
+      if (abortController) {
+        abortController.abort();
+      }
+      abortController = typeof AbortController !== "undefined" ? new AbortController() : null;
+      try {
+        return await validator(value, abortController ? abortController.signal : null);
+      } catch (error) {
+        if (error.name === "AbortError") {
+          return null;
+        }
+        throw error;
+      }
+    };
+    wrapped.cancel = () => {
+      if (abortController) {
+        abortController.abort();
+      }
+    };
+    return wrapped;
+  },
+  /** Run `validator` only when `condition` holds */
+  when: (condition, validator) => {
+    const rule = resolveValidator(validator);
+    return (value, options = {}, translator, allValues = {}) => {
+      const context = options.min !== void 0 || options.max !== void 0 ? allValues : options;
+      const shouldValidate = typeof condition === "function" ? condition(value, context) : condition;
+      if (!shouldValidate) {
+        return null;
+      }
+      return rule ? rule(value, options, translator, allValues) : null;
+    };
+  },
+  /** Validator chain builder */
+  chain: (options = {}) => {
+    const validatorList = [];
+    const stopOnFirstError = options.stopOnFirstError !== false;
+    const direct = (name) => (opts) => {
+      validatorList.push((v, o, t, a) => validators[name](v, opts || o || {}, t, a));
+      return chain;
+    };
+    const chain = {
+      required: direct("required"),
+      email: direct("email"),
+      minLength: direct("minLength"),
+      maxLength: direct("maxLength"),
+      custom: (fn, message) => {
+        validatorList.push((v, o, t, a) => {
+          const result = fn(v, a);
+          return result === null || result === true || result === void 0 ? null : message || result;
+        });
+        return chain;
+      },
+      validate: (value, opts, translator, allValues) => {
+        if (stopOnFirstError) {
+          for (const validator of validatorList) {
+            const error = validator(value, opts, translator, allValues);
+            if (error) {
+              return error;
+            }
+          }
+          return null;
+        }
+        const errors = [];
+        for (const validator of validatorList) {
+          const error = validator(value, opts, translator, allValues);
+          if (error) {
+            errors.push(error);
+          }
+        }
+        return errors.length > 0 ? errors : null;
+      }
+    };
+    return chain;
+  }
+};
+function lookup(name) {
+  const found = Object.hasOwn(validators, name) && !HELPER_NAMES.has(name) ? validators[name] : null;
+  return typeof found === "function" ? found : null;
+}
+function resolveString(entry) {
+  const exact = lookup(entry);
+  const colon = exact ? -1 : entry.indexOf(":");
+  const name = colon === -1 ? entry : entry.slice(0, colon).trim();
+  const found = exact ?? lookup(name);
+  if (!found) return null;
+  const text = colon === -1 ? void 0 : entry.slice(colon + 1);
+  if (!found[BUILTIN]) {
+    return text === void 0 ? { name, args: [], validator: found } : null;
+  }
+  const args = found[BUILTIN].argsFromString(text);
+  if (!args) return null;
+  return { name: found[BUILTIN].name, args, validator: found[BUILTIN].factory(...args) };
+}
+function resolveValidator(entry) {
+  if (typeof entry === "string") {
+    return resolveString(entry)?.validator ?? null;
+  }
+  if (typeof entry !== "function") return null;
+  return entry[BUILTIN] ? entry[BUILTIN].factory() : entry;
+}
+function serializeArg(arg) {
+  if (arg instanceof RegExp) return { $regexp: [arg.source, arg.flags] };
+  return arg;
+}
+function isSerializable(arg) {
+  if (arg === void 0 || arg === null) return true;
+  if (arg instanceof RegExp) return true;
+  if (Array.isArray(arg)) return arg.every(isSerializable);
+  return ["string", "number", "boolean"].includes(typeof arg);
+}
+function describeValidator(entry) {
+  let descriptor;
+  if (typeof entry === "string") {
+    descriptor = resolveString(entry);
+  } else if (typeof entry === "function") {
+    descriptor = entry[BUILTIN] ? { name: entry[BUILTIN].name, args: [] } : DESCRIPTORS.get(entry);
+  }
+  if (!descriptor || !descriptor.args.every(isSerializable)) return null;
+  const args = [...descriptor.args];
+  while (args.length > 0 && args[args.length - 1] === void 0) args.pop();
+  return { name: descriptor.name, args: args.map(serializeArg) };
+}
+function serializeValidators(validatorList) {
+  const specs = (validatorList || []).map(describeValidator).filter(Boolean);
+  return specs.length > 0 ? JSON.stringify(specs) : null;
+}
+
 // src/form-builder.js
 var DEFAULT_CLASS_NAMES = {
   /** Wrapper around label, control and error */
@@ -41,10 +431,11 @@ function safeAttributes(attributes) {
   }
   return safe;
 }
+var DEFAULT_CSRF_FIELD_NAME = "_csrf";
 function joinClasses(...names) {
   return names.filter(Boolean).join(" ");
 }
-var FormBuilder = class {
+var FormBuilder = class _FormBuilder {
   constructor(options = {}) {
     this.options = {
       validateOnChange: true,
@@ -255,8 +646,9 @@ var FormBuilder = class {
         return error;
       }
     }
-    for (const validator of field.validators || []) {
-      const error = validator(value, this.values);
+    for (const entry of field.validators || []) {
+      const validator = resolveValidator(entry);
+      const error = validator ? validator(value, this.values) : null;
       if (error) {
         this.errors[name] = error;
         return error;
@@ -336,20 +728,59 @@ var FormBuilder = class {
   touch(name) {
     this.touched[name] = true;
   }
+  /**
+   * A copy of this form's definition — fields, groups, options and handlers —
+   * with fresh values, errors and touched state.
+   *
+   * A FormBuilder holds the state of one submission. On a server, keep the
+   * shared definition at module scope and fork it per request, so one user's
+   * submitted values and errors never render into another user's page.
+   */
+  fork() {
+    const copy = new _FormBuilder({ ...this.options });
+    for (const [name, config] of this.fields) {
+      copy.fields.set(name, config);
+    }
+    for (const [name, group] of this.groups) {
+      copy.groups.set(name, group);
+    }
+    copy.values = { ...this.initialValues };
+    copy.initialValues = { ...this.initialValues };
+    copy.submitHandler = this.submitHandler;
+    copy.errorHandler = this.errorHandler;
+    return copy;
+  }
+  /**
+   * The values, errors and touched state a render uses.
+   *
+   * Passing any of `values`, `errors` or `touched` to buildForm renders from
+   * those alone — the instance's own state is neither read nor changed — so a
+   * shared builder can render per-request state. Values are merged over the
+   * fields' default values, and fields with an error count as touched unless
+   * `touched` is given.
+   */
+  resolveRenderState(options = {}) {
+    const { values, errors, touched } = options;
+    if (values === void 0 && errors === void 0 && touched === void 0) {
+      return { values: this.values, errors: this.errors, touched: this.touched };
+    }
+    const renderErrors = errors || {};
+    return {
+      values: { ...this.initialValues, ...values },
+      errors: renderErrors,
+      touched: touched || Object.fromEntries(Object.keys(renderErrors).map((name) => [name, true]))
+    };
+  }
   /**
    * Build input component with validation metadata for hydration
    */
-  buildInput(name, classNames = this.resolveClassNames()) {
+  buildInput(name, classNames = this.resolveClassNames(), state = this.resolveRenderState()) {
     const field = this.fields.get(name);
     if (!field) return null;
-    const value = this.values[name] || "";
-    const error = this.errors[name];
-    const isTouched = this.touched[name];
-    const validatorNames = field.validators.map((v) => {
-      if (typeof v === "function") return v.name || "custom";
-      if (typeof v === "string") return v;
-      return null;
-    }).filter(Boolean).join(",");
+    const value = state.values[name] || "";
+    const error = state.errors[name];
+    const isTouched = state.touched[name];
+    const validatorSpec = serializeValidators(field.validators);
     const controlClass = joinClasses(
       classNames.control,
       field.className,
@@ -374,8 +805,8 @@ var FormBuilder = class {
       inputProps.required = true;
       inputProps["data-required"] = "true";
     }
-    if (validatorNames) {
-      inputProps["data-validators"] = validatorNames;
+    if (validatorSpec) {
+      inputProps["data-validators"] = validatorSpec;
     }
     if (field.type === "textarea" || field.type === "select") {
       const { type: _type, value: _value, ...rest } = inputProps;
@@ -417,9 +848,9 @@ var FormBuilder = class {
   /**
    * Build error component
    */
-  buildError(name, classNames = this.resolveClassNames()) {
-    const error = this.errors[name];
-    const isTouched = this.touched[name];
+  buildError(name, classNames = this.resolveClassNames(), state = this.resolveRenderState()) {
+    const error = state.errors[name];
+    const isTouched = state.touched[name];
     if (!error || !isTouched) return null;
     const props = { id: `${name}-error`, role: "alert", text: error };
     if (classNames.error) props.className = classNames.error;
@@ -434,14 +865,14 @@ var FormBuilder = class {
   /**
    * Build complete field component
    */
-  buildField(name, classNames = this.resolveClassNames()) {
+  buildField(name, classNames = this.resolveClassNames(), state = this.resolveRenderState()) {
     const field = this.fields.get(name);
     if (!field) return null;
     const children = [
       this.buildLabel(name, classNames),
-      this.buildInput(name, classNames)
+      this.buildInput(name, classNames, state)
     ];
-    const error = this.buildError(name, classNames);
+    const error = this.buildError(name, classNames, state);
     if (error) {
       children.push(error);
     }
@@ -451,14 +882,31 @@ var FormBuilder = class {
   }
   /**
    * Build entire form
+   *
+   * `options.values`, `options.errors` and `options.touched` render
+   * per-request state without touching the builder's own (see
+   * resolveRenderState). `options.csrfToken` adds a hidden `_csrf` input (the
+   * name is `options.csrfFieldName`); create the token with
+   * `@coherent.js/forms/csrf`.
    */
   buildForm(options = {}) {
-    const settings = { ...this.options, ...options };
+    const { values: _values, errors: _errors, touched: _touched, ...formOptions } = options;
+    const settings = { ...this.options, ...formOptions };
     const classNames = this.resolveClassNames(options.classNames);
+    const state = this.resolveRenderState(options);
     const fields = [];
+    if (settings.csrfToken !== void 0 && settings.csrfToken !== null && settings.csrfToken !== "") {
+      fields.push({
+        input: {
+          type: "hidden",
+          name: settings.csrfFieldName || DEFAULT_CSRF_FIELD_NAME,
+          value: String(settings.csrfToken)
+        }
+      });
+    }
     for (const [name] of this.fields) {
-      if (!this.isFieldVisible(name)) continue;
-      fields.push(this.buildField(name, classNames));
+      if (!this.isFieldVisible(name, state.values)) continue;
+      fields.push(this.buildField(name, classNames, state));
     }
     if (settings.submitButton !== false) {
       const button = { type: "submit", text: settings.submitText || "Submit" };
@@ -520,13 +968,13 @@ var FormBuilder = class {
   /**
    * Check if a field is visible
    */
-  isFieldVisible(name) {
+  isFieldVisible(name, values = this.values) {
     const field = this.fields.get(name);
     if (!field) return false;
     if (field.visible === false) return false;
     const showCondition = field.showWhen || field.showIf;
     if (showCondition) {
-      return showCondition(this.values);
+      return showCondition(values);
     }
     return true;
   }