@coherent.js/forms 1.0.0 → 1.1.0

package/dist/index.js

@@ -1,4 +1,40 @@
 // src/form-builder.js
+import { render as renderToHTML } from "@coherent.js/core";
+var DEFAULT_CLASS_NAMES = {
+  /** Wrapper around label, control and error */
+  field: "form-field",
+  label: "",
+  /** Base class on the control, before any per-field className */
+  control: "",
+  /** Added to the control while it has a visible error */
+  invalid: "error",
+  /** The error message element */
+  error: "error-message",
+  submit: "submit-button"
+};
+var VALID_ATTRIBUTE_NAME = /^[A-Za-z_:][-A-Za-z0-9_:.]*$/;
+var EVENT_HANDLER_NAME = /^on/i;
+function safeAttributes(attributes) {
+  if (!attributes || typeof attributes !== "object") return {};
+  const safe = {};
+  for (const [name, value] of Object.entries(attributes)) {
+    if (!VALID_ATTRIBUTE_NAME.test(name)) {
+      console.warn(`[coherent.js/forms] Ignoring invalid attribute name: ${JSON.stringify(name)}`);
+      continue;
+    }
+    if (EVENT_HANDLER_NAME.test(name)) {
+      console.warn(
+        `[coherent.js/forms] Ignoring inline event handler "${name}". Attach handlers with hydrateForm instead.`
+      );
+      continue;
+    }
+    safe[name] = value;
+  }
+  return safe;
+}
+function joinClasses(...names) {
+  return names.filter(Boolean).join(" ");
+}
 var FormBuilder = class {
   constructor(options = {}) {
     this.options = {
@@ -226,11 +262,8 @@ var FormBuilder = class {
    */
   validate() {
     const errors = {};
-    for (const [name, field] of this.fields) {
-      const showCondition = field.showWhen || field.showIf;
-      if (showCondition && !showCondition(this.values)) {
-        continue;
-      }
+    for (const [name] of this.fields) {
+      if (!this.isFieldVisible(name)) continue;
       const error = this.validateField(name);
       if (error) {
         errors[name] = error;
@@ -286,17 +319,8 @@ var FormBuilder = class {
   /**
    * Convert form to HTML string
    */
-  toHTML() {
-    const fields = this.getFields();
-    let html = `<form name="${this.options.name}">`;
-    fields.forEach((field) => {
-      html += `<div class="form-field">`;
-      html += `<label for="${field.name}">${field.label}</label>`;
-      html += `<input type="${field.type}" name="${field.name}" id="${field.name}">`;
-      html += `</div>`;
-    });
-    html += `</form>`;
-    return html;
+  toHTML(options = {}) {
+    return renderToHTML(this.buildForm(options));
   }
   /**
    * Mark field as touched
@@ -307,7 +331,7 @@ var FormBuilder = class {
   /**
    * Build input component with validation metadata for hydration
    */
-  buildInput(name) {
+  buildInput(name, classNames = this.resolveClassNames()) {
     const field = this.fields.get(name);
     if (!field) return null;
     const value = this.values[name] || "";
@@ -318,16 +342,26 @@ var FormBuilder = class {
       if (typeof v === "string") return v;
       return null;
     }).filter(Boolean).join(",");
+    const controlClass = joinClasses(
+      classNames.control,
+      field.className,
+      error && isTouched ? classNames.invalid : null
+    );
     const inputProps = {
+      // Spread first: name, id, type and the aria-* pair below are the
+      // builder's own invariants, and hydration keys off them.
+      ...safeAttributes(field.attributes),
       type: field.type,
       name: field.name,
       id: field.name,
       value,
-      placeholder: field.placeholder,
       "aria-invalid": error ? "true" : "false",
-      "aria-describedby": error ? `${name}-error` : void 0,
-      className: error && isTouched ? "error" : ""
+      "aria-describedby": error ? `${name}-error` : void 0
     };
+    if (field.placeholder) inputProps.placeholder = field.placeholder;
+    if (controlClass) inputProps.className = controlClass;
+    if (field.disabled) inputProps.disabled = true;
+    if (field.readonly) inputProps.readonly = true;
     if (field.required) {
       inputProps.required = true;
       inputProps["data-required"] = "true";
@@ -335,6 +369,29 @@ var FormBuilder = class {
     if (validatorNames) {
       inputProps["data-validators"] = validatorNames;
     }
+    if (field.type === "textarea" || field.type === "select") {
+      const { type: _type, value: _value, ...rest } = inputProps;
+      const props = { ...rest };
+      if (field.type === "textarea") {
+        return { textarea: { ...props, text: String(value) } };
+      }
+      const { placeholder: _placeholder, ...selectProps } = props;
+      return {
+        select: {
+          ...selectProps,
+          children: (field.options ?? []).map((option) => {
+            const { value: optionValue, label = optionValue } = typeof option === "object" && option !== null ? option : { value: option };
+            return {
+              option: {
+                value: optionValue,
+                selected: String(optionValue) === String(value) || void 0,
+                text: String(label)
+              }
+            };
+          })
+        }
+      };
+    }
     return {
       input: inputProps
     };
@@ -342,78 +399,103 @@ var FormBuilder = class {
   /**
    * Build label component
    */
-  buildLabel(name) {
+  buildLabel(name, classNames = this.resolveClassNames()) {
     const field = this.fields.get(name);
     if (!field) return null;
-    return {
-      label: {
-        for: field.name,
-        text: field.label
-      }
-    };
+    const props = { for: field.name, text: field.label };
+    if (classNames.label) props.className = classNames.label;
+    return { label: props };
   }
   /**
    * Build error component
    */
-  buildError(name) {
+  buildError(name, classNames = this.resolveClassNames()) {
     const error = this.errors[name];
     const isTouched = this.touched[name];
     if (!error || !isTouched) return null;
-    return {
-      div: {
-        id: `${name}-error`,
-        className: "error-message",
-        role: "alert",
-        text: error
-      }
-    };
+    const props = { id: `${name}-error`, role: "alert", text: error };
+    if (classNames.error) props.className = classNames.error;
+    return { div: props };
+  }
+  /**
+   * Merge configured class names over the defaults
+   */
+  resolveClassNames(overrides = {}) {
+    return { ...DEFAULT_CLASS_NAMES, ...this.options.classNames, ...overrides };
   }
   /**
    * Build complete field component
    */
-  buildField(name) {
+  buildField(name, classNames = this.resolveClassNames()) {
     const field = this.fields.get(name);
     if (!field) return null;
     const children = [
-      this.buildLabel(name),
-      this.buildInput(name)
+      this.buildLabel(name, classNames),
+      this.buildInput(name, classNames)
     ];
-    const error = this.buildError(name);
+    const error = this.buildError(name, classNames);
     if (error) {
       children.push(error);
     }
-    return {
-      div: {
-        className: "form-field",
-        "data-field": name,
-        children
-      }
-    };
+    const props = { "data-field": name, children };
+    if (classNames.field) props.className = classNames.field;
+    return { div: props };
   }
   /**
    * Build entire form
    */
   buildForm(options = {}) {
+    const settings = { ...this.options, ...options };
+    const classNames = this.resolveClassNames(options.classNames);
     const fields = [];
     for (const [name] of this.fields) {
-      fields.push(this.buildField(name));
-    }
-    if (options.submitButton !== false) {
-      fields.push({
-        button: {
-          type: "submit",
-          text: options.submitText || "Submit",
-          className: "submit-button"
-        }
-      });
-    }
-    return {
-      form: {
-        onsubmit: "handleSubmit(event)",
-        novalidate: true,
-        children: fields
-      }
-    };
+      if (!this.isFieldVisible(name)) continue;
+      fields.push(this.buildField(name, classNames));
+    }
+    if (settings.submitButton !== false) {
+      const button = { type: "submit", text: settings.submitText || "Submit" };
+      if (classNames.submit) button.className = classNames.submit;
+      fields.push({ button });
+    }
+    const form = {};
+    if (settings.action) form.action = settings.action;
+    if (settings.method) form.method = settings.method;
+    if (settings.name) form.name = settings.name;
+    if (settings.id) form.id = settings.id;
+    if (settings.className) form.className = settings.className;
+    if (settings.enctype) form.enctype = settings.enctype;
+    if (settings.enhance) {
+      form.onsubmit = typeof settings.enhance === "string" ? settings.enhance : "handleSubmit(event)";
+    }
+    if (settings.novalidate === true) form.novalidate = true;
+    form.children = fields;
+    return { form };
+  }
+  /**
+   * Set the form action URL
+   */
+  setAction(action) {
+    this.options.action = action;
+    return this;
+  }
+  /**
+   * Set the form submission method
+   */
+  setMethod(method) {
+    this.options.method = method;
+    return this;
+  }
+  /**
+   * Build the form component (alias for buildForm)
+   */
+  build(options = {}) {
+    return this.buildForm(options);
+  }
+  /**
+   * Render the form to a component (alias for buildForm)
+   */
+  render(options = {}) {
+    return this.buildForm(options);
   }
   /**
    * Check if form is currently submitting
@@ -433,11 +515,12 @@ var FormBuilder = class {
   isFieldVisible(name) {
     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 field.visible !== false;
+    return true;
   }
   /**
    * Reset form
@@ -466,19 +549,199 @@ function createFormBuilder(options = {}) {
   }
   return form;
 }
-function buildForm(fields, options = {}) {
+function buildForm(config = {}) {
+  const { fields = [], ...options } = Array.isArray(config) ? { fields: config } : config;
   const builder = new FormBuilder(options);
-  for (const [name, config] of Object.entries(fields)) {
-    builder.field(name, config);
+  if (Array.isArray(fields)) {
+    for (const field of fields) {
+      if (field && field.name) builder.field(field.name, field);
+    }
+  } else {
+    for (const [name, field] of Object.entries(fields)) {
+      builder.field(name, field);
+    }
   }
-  return builder;
+  return builder.buildForm(options);
 }
 
-// src/validators.js
+// src/validation.js
 var validators = {
+  required: (message = "This field is required") => (value) => {
+    if (value === null || value === void 0 || value === "") {
+      return message;
+    }
+    return null;
+  },
+  minLength: (min, message = `Minimum length is ${min}`) => (value) => {
+    if (value && value.length < min) {
+      return message;
+    }
+    return null;
+  },
+  maxLength: (max, message = `Maximum length is ${max}`) => (value) => {
+    if (value && value.length > max) {
+      return message;
+    }
+    return null;
+  },
+  min: (min, message = `Minimum value is ${min}`) => (value) => {
+    if (value !== null && value !== void 0 && Number(value) < min) {
+      return message;
+    }
+    return null;
+  },
+  max: (max, message = `Maximum value is ${max}`) => (value) => {
+    if (value !== null && value !== void 0 && Number(value) > max) {
+      return message;
+    }
+    return null;
+  },
+  email: (message = "Invalid email address") => (value) => {
+    if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+      return message;
+    }
+    return null;
+  },
+  url: (message = "Invalid URL") => (value) => {
+    if (value) {
+      try {
+        new URL(value);
+      } catch {
+        return message;
+      }
+    }
+    return null;
+  },
+  pattern: (regex, message = "Invalid format") => (value) => {
+    if (value && !regex.test(value)) {
+      return message;
+    }
+    return null;
+  },
+  matches: (fieldName, message = "Fields do not match") => (value, formData) => {
+    if (value !== formData[fieldName]) {
+      return message;
+    }
+    return null;
+  },
+  oneOf: (options, message = "Invalid option") => (value) => {
+    if (value && !options.includes(value)) {
+      return message;
+    }
+    return null;
+  },
+  custom: (fn, message = "Validation failed") => (value, formData) => {
+    if (!fn(value, formData)) {
+      return message;
+    }
+    return null;
+  }
+};
+var FormValidator = class {
+  constructor(schema = {}) {
+    this.schema = schema;
+    this.errors = {};
+    this.touched = {};
+  }
+  /**
+   * Validate a single field
+   */
+  validateField(name, value, formData = {}) {
+    const fieldValidators = this.schema[name];
+    if (!fieldValidators) {
+      return null;
+    }
+    const validatorArray = Array.isArray(fieldValidators) ? fieldValidators : [fieldValidators];
+    for (const validator of validatorArray) {
+      const error = validator(value, formData);
+      if (error) {
+        return error;
+      }
+    }
+    return null;
+  }
+  /**
+   * Validate entire form
+   */
+  validate(formData) {
+    const errors = {};
+    let isValid = true;
+    for (const [name, value] of Object.entries(formData)) {
+      const error = this.validateField(name, value, formData);
+      if (error) {
+        errors[name] = error;
+        isValid = false;
+      }
+    }
+    for (const name of Object.keys(this.schema)) {
+      if (!(name in formData)) {
+        const error = this.validateField(name, void 0, formData);
+        if (error) {
+          errors[name] = error;
+          isValid = false;
+        }
+      }
+    }
+    this.errors = errors;
+    return { isValid, errors };
+  }
+  /**
+   * Mark field as touched
+   */
+  touch(name) {
+    this.touched[name] = true;
+  }
+  /**
+   * Check if field is touched
+   */
+  isTouched(name) {
+    return this.touched[name] || false;
+  }
+  /**
+   * Get error for field
+   */
+  getError(name) {
+    return this.errors[name] || null;
+  }
+  /**
+   * Check if field has error
+   */
+  hasError(name) {
+    return !!this.errors[name];
+  }
+  /**
+   * Clear errors
+   */
+  clearErrors() {
+    this.errors = {};
+  }
+  /**
+   * Clear touched state
+   */
+  clearTouched() {
+    this.touched = {};
+  }
+  /**
+   * Reset validator
+   */
+  reset() {
+    this.clearErrors();
+    this.clearTouched();
+  }
+};
+function createValidator(schema) {
+  return new FormValidator(schema);
+}
+function validate(formData, schema) {
+  const validator = new FormValidator(schema);
+  return validator.validate(formData);
+}
+
+// src/validators.js
+var validators2 = {
   required: (value, options = {}) => {
     if (value === null || value === void 0 || value === "") {
-      return options.message || validators.required.message || "This field is required";
+      return options.message || validators2.required.message || "This field is required";
     }
     return null;
   },
@@ -661,7 +924,7 @@ var validators = {
   },
   // Get a registered validator
   get: (name) => {
-    return validators[name];
+    return validators2[name];
   },
   // Compose multiple validators
   compose: (validatorList) => {
@@ -729,19 +992,19 @@ var validators = {
     const stopOnFirstError = options.stopOnFirstError !== false;
     const chain = {
       required: (opts) => {
-        validatorList.push((v, o, t, a) => validators.required(v, opts || o, t, a));
+        validatorList.push((v, o, t, a) => validators2.required(v, opts || o, t, a));
         return chain;
       },
       email: (opts) => {
-        validatorList.push((v, o, t, a) => validators.email(v, opts || o, t, a));
+        validatorList.push((v, o, t, a) => validators2.email(v, opts || o, t, a));
         return chain;
       },
       minLength: (opts) => {
-        validatorList.push((v, o, t, a) => validators.minLength(v, opts || o, t, a));
+        validatorList.push((v, o, t, a) => validators2.minLength(v, opts || o, t, a));
         return chain;
       },
       maxLength: (opts) => {
-        validatorList.push((v, o, t, a) => validators.maxLength(v, opts || o, t, a));
+        validatorList.push((v, o, t, a) => validators2.maxLength(v, opts || o, t, a));
         return chain;
       },
       custom: (fn, message) => {
@@ -796,6 +1059,7 @@ function validateForm(formData, fieldValidators) {
   return Object.keys(errors).length > 0 ? errors : null;
 }
 function registerValidator(name, validatorFn) {
+  validators2[name] = validatorFn;
   validators[name] = validatorFn;
 }
 function composeValidators(...validatorFns) {
@@ -827,7 +1091,14 @@ function hydrateForm(formSelector, options = {}) {
     validateOnSubmit: true,
     showErrorsOnTouch: true,
     debounce: 300,
-    ...options
+    ...options,
+    // Must match whatever the server rendered, so pass the same names given to
+    // buildForm's `classNames` when they were customised.
+    classNames: {
+      invalid: DEFAULT_CLASS_NAMES.invalid,
+      error: DEFAULT_CLASS_NAMES.error,
+      ...options.classNames
+    }
   };
   const state = {
     values: {},
@@ -842,8 +1113,8 @@ function hydrateForm(formSelector, options = {}) {
     return validatorString.split(",").map((v) => {
       const trimmed = v.trim();
       const [name, ...params] = trimmed.split(":");
-      if (validators[name]) {
-        return params.length > 0 ? validators[name](...params.map((p) => isNaN(p) ? p : Number(p))) : validators[name];
+      if (validators2[name]) {
+        return params.length > 0 ? validators2[name](...params.map((p) => isNaN(p) ? p : Number(p))) : validators2[name];
       }
       return null;
     }).filter(Boolean);
@@ -871,10 +1142,10 @@ function hydrateForm(formSelector, options = {}) {
   function createErrorElement(name, inputElement) {
     const errorDiv = document.createElement("div");
     errorDiv.id = `${name}-error`;
-    errorDiv.className = "error-message";
+    if (opts.classNames.error) errorDiv.className = opts.classNames.error;
     errorDiv.setAttribute("role", "alert");
     errorDiv.style.display = "none";
-    const fieldWrapper = inputElement.closest(".form-field") || inputElement.parentElement;
+    const fieldWrapper = inputElement.closest("[data-field]") || inputElement.parentElement;
     fieldWrapper.appendChild(errorDiv);
     return errorDiv;
   }
@@ -923,6 +1194,9 @@ function hydrateForm(formSelector, options = {}) {
     displayError(name, error);
     return !error;
   }
+  function invalidClasses() {
+    return opts.classNames.invalid ? opts.classNames.invalid.trim().split(/\s+/) : [];
+  }
   function displayError(name, error) {
     const field = state.fields.get(name);
     if (!field) return;
@@ -931,12 +1205,12 @@ function hydrateForm(formSelector, options = {}) {
       errorElement.textContent = error;
       errorElement.style.display = "block";
       element.setAttribute("aria-invalid", "true");
-      element.classList.add("error");
+      invalidClasses().forEach((name2) => element.classList.add(name2));
     } else {
       errorElement.textContent = "";
       errorElement.style.display = "none";
       element.setAttribute("aria-invalid", "false");
-      element.classList.remove("error");
+      invalidClasses().forEach((name2) => element.classList.remove(name2));
     }
   }
   function validateForm2() {
@@ -1067,180 +1341,8 @@ function hydrateForm(formSelector, options = {}) {
     })
   };
 }
-
-// src/validation.js
-var validators2 = {
-  required: (message = "This field is required") => (value) => {
-    if (value === null || value === void 0 || value === "") {
-      return message;
-    }
-    return null;
-  },
-  minLength: (min, message = `Minimum length is ${min}`) => (value) => {
-    if (value && value.length < min) {
-      return message;
-    }
-    return null;
-  },
-  maxLength: (max, message = `Maximum length is ${max}`) => (value) => {
-    if (value && value.length > max) {
-      return message;
-    }
-    return null;
-  },
-  min: (min, message = `Minimum value is ${min}`) => (value) => {
-    if (value !== null && value !== void 0 && Number(value) < min) {
-      return message;
-    }
-    return null;
-  },
-  max: (max, message = `Maximum value is ${max}`) => (value) => {
-    if (value !== null && value !== void 0 && Number(value) > max) {
-      return message;
-    }
-    return null;
-  },
-  email: (message = "Invalid email address") => (value) => {
-    if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
-      return message;
-    }
-    return null;
-  },
-  url: (message = "Invalid URL") => (value) => {
-    if (value) {
-      try {
-        new URL(value);
-      } catch {
-        return message;
-      }
-    }
-    return null;
-  },
-  pattern: (regex, message = "Invalid format") => (value) => {
-    if (value && !regex.test(value)) {
-      return message;
-    }
-    return null;
-  },
-  matches: (fieldName, message = "Fields do not match") => (value, formData) => {
-    if (value !== formData[fieldName]) {
-      return message;
-    }
-    return null;
-  },
-  oneOf: (options, message = "Invalid option") => (value) => {
-    if (value && !options.includes(value)) {
-      return message;
-    }
-    return null;
-  },
-  custom: (fn, message = "Validation failed") => (value, formData) => {
-    if (!fn(value, formData)) {
-      return message;
-    }
-    return null;
-  }
-};
-var FormValidator = class {
-  constructor(schema = {}) {
-    this.schema = schema;
-    this.errors = {};
-    this.touched = {};
-  }
-  /**
-   * Validate a single field
-   */
-  validateField(name, value, formData = {}) {
-    const fieldValidators = this.schema[name];
-    if (!fieldValidators) {
-      return null;
-    }
-    const validatorArray = Array.isArray(fieldValidators) ? fieldValidators : [fieldValidators];
-    for (const validator of validatorArray) {
-      const error = validator(value, formData);
-      if (error) {
-        return error;
-      }
-    }
-    return null;
-  }
-  /**
-   * Validate entire form
-   */
-  validate(formData) {
-    const errors = {};
-    let isValid = true;
-    for (const [name, value] of Object.entries(formData)) {
-      const error = this.validateField(name, value, formData);
-      if (error) {
-        errors[name] = error;
-        isValid = false;
-      }
-    }
-    for (const name of Object.keys(this.schema)) {
-      if (!(name in formData)) {
-        const error = this.validateField(name, void 0, formData);
-        if (error) {
-          errors[name] = error;
-          isValid = false;
-        }
-      }
-    }
-    this.errors = errors;
-    return { isValid, errors };
-  }
-  /**
-   * Mark field as touched
-   */
-  touch(name) {
-    this.touched[name] = true;
-  }
-  /**
-   * Check if field is touched
-   */
-  isTouched(name) {
-    return this.touched[name] || false;
-  }
-  /**
-   * Get error for field
-   */
-  getError(name) {
-    return this.errors[name] || null;
-  }
-  /**
-   * Check if field has error
-   */
-  hasError(name) {
-    return !!this.errors[name];
-  }
-  /**
-   * Clear errors
-   */
-  clearErrors() {
-    this.errors = {};
-  }
-  /**
-   * Clear touched state
-   */
-  clearTouched() {
-    this.touched = {};
-  }
-  /**
-   * Reset validator
-   */
-  reset() {
-    this.clearErrors();
-    this.clearTouched();
-  }
-};
-function createValidator(schema) {
-  return new FormValidator(schema);
-}
-function validate(formData, schema) {
-  const validator = new FormValidator(schema);
-  return validator.validate(formData);
-}
 export {
+  DEFAULT_CLASS_NAMES,
   FormBuilder,
   FormValidator,
   buildForm,
@@ -1252,6 +1354,6 @@ export {
   validate,
   validateField,
   validateForm,
-  validators2 as validators
+  validators
 };
 //# sourceMappingURL=index.js.map