@viveksinghind/narrative-form-core 1.0.0

package/dist/index.js

@@ -0,0 +1,641 @@
+'use strict';
+
+// src/state/formState.ts
+var FormStateEngine = class {
+  /**
+   * Create a new FormStateEngine.
+   *
+   * @param fields - Ordered array of field configurations
+   * @param onChange - Optional callback invoked on every state mutation
+   */
+  constructor(fields, onChange) {
+    this.fields = fields;
+    this.activeIndex = -1;
+    this.values = {};
+    this.statuses = {};
+    this.fieldTimings = {};
+    this.fieldStartTimes = {};
+    this.formStartTime = Date.now();
+    this.onChange = onChange;
+    for (const field of fields) {
+      this.statuses[field.key] = "idle";
+      this.fieldTimings[field.key] = 0;
+    }
+  }
+  /** Returns a readonly snapshot of the current form state. */
+  getSnapshot() {
+    return {
+      fields: this.fields,
+      activeIndex: this.activeIndex,
+      values: { ...this.values },
+      statuses: { ...this.statuses },
+      isComplete: this.fields.every((f) => this.statuses[f.key] === "confirmed")
+    };
+  }
+  /** Returns a copy of all confirmed field values. */
+  getValues() {
+    return { ...this.values };
+  }
+  /**
+   * Returns analytics metadata about the form session.
+   *
+   * @param formId - Optional form identifier
+   * @param formVersion - Optional form version number
+   */
+  getMeta(formId, formVersion) {
+    return {
+      formId,
+      formVersion,
+      totalTimeMs: Date.now() - this.formStartTime,
+      fieldTimings: { ...this.fieldTimings }
+    };
+  }
+  /**
+   * Start typing animation for a specific field.
+   * Transitions the field from `idle` to `typing`.
+   *
+   * @param key - The field key to begin typing
+   */
+  startTyping(key) {
+    const index = this.findFieldIndex(key);
+    if (index === -1) return;
+    this.statuses[key] = "typing";
+    this.notify();
+  }
+  /**
+   * Mark a field as active (typewriter finished, input is now visible).
+   * Starts the timing clock for this field.
+   *
+   * @param key - The field key to activate
+   */
+  activateField(key) {
+    const index = this.findFieldIndex(key);
+    if (index === -1) return;
+    this.activeIndex = index;
+    this.statuses[key] = "active";
+    this.fieldStartTimes[key] = Date.now();
+    this.notify();
+  }
+  /**
+   * Confirm a field with a value.
+   * Records the time spent on the field and advances to the next one.
+   *
+   * @param key - The field key to confirm
+   * @param value - The confirmed value
+   */
+  confirmField(key, value) {
+    const index = this.findFieldIndex(key);
+    if (index === -1) return;
+    this.values[key] = value;
+    this.statuses[key] = "confirmed";
+    const startTime = this.fieldStartTimes[key];
+    if (startTime !== void 0) {
+      this.fieldTimings[key] = Date.now() - startTime;
+    }
+    const nextIndex = this.findNextUnconfirmedIndex(index);
+    if (nextIndex !== -1) {
+      this.activeIndex = nextIndex;
+    }
+    this.notify();
+  }
+  /**
+   * Reopen a confirmed field for editing.
+   * The field transitions to `editing` status with its current value preserved.
+   *
+   * @param key - The field key to edit
+   */
+  editField(key) {
+    const index = this.findFieldIndex(key);
+    if (index === -1) return;
+    if (this.statuses[key] !== "confirmed") return;
+    this.statuses[key] = "editing";
+    this.activeIndex = index;
+    this.fieldStartTimes[key] = Date.now();
+    this.notify();
+  }
+  /**
+   * Re-confirm a field after editing.
+   *
+   * @param key - The field key to re-confirm
+   * @param value - The new confirmed value
+   */
+  reconfirmField(key, value) {
+    var _a;
+    const index = this.findFieldIndex(key);
+    if (index === -1) return;
+    this.values[key] = value;
+    this.statuses[key] = "confirmed";
+    const startTime = this.fieldStartTimes[key];
+    if (startTime !== void 0) {
+      this.fieldTimings[key] = ((_a = this.fieldTimings[key]) != null ? _a : 0) + (Date.now() - startTime);
+    }
+    const nextIndex = this.findNextUnconfirmedIndex(-1);
+    if (nextIndex !== -1) {
+      this.activeIndex = nextIndex;
+    }
+    this.notify();
+  }
+  /**
+   * Move to the next field without confirming the current one.
+   * Useful for programmatic navigation via ref API.
+   */
+  next() {
+    const nextIndex = this.findNextUnconfirmedIndex(this.activeIndex);
+    if (nextIndex !== -1) {
+      this.activeIndex = nextIndex;
+      this.notify();
+    }
+  }
+  /**
+   * Focus a specific field by key.
+   * Only works for confirmed fields (triggers edit) or the current active field.
+   *
+   * @param key - The field key to focus
+   */
+  focusField(key) {
+    const index = this.findFieldIndex(key);
+    if (index === -1) return;
+    const status = this.statuses[key];
+    if (status === "confirmed") {
+      this.editField(key);
+    } else if (status === "active" || status === "editing") {
+      this.activeIndex = index;
+      this.notify();
+    }
+  }
+  /**
+   * Reset all form state to initial values.
+   * Clears all values, statuses, and timings.
+   */
+  reset() {
+    this.activeIndex = -1;
+    this.values = {};
+    this.fieldTimings = {};
+    this.fieldStartTimes = {};
+    this.formStartTime = Date.now();
+    for (const field of this.fields) {
+      this.statuses[field.key] = "idle";
+      this.fieldTimings[field.key] = 0;
+    }
+    this.notify();
+  }
+  /**
+   * Update the onChange listener.
+   * Used by framework wrappers to trigger re-renders.
+   *
+   * @param fn - Callback to invoke on state changes
+   */
+  setOnChange(fn) {
+    this.onChange = fn;
+  }
+  // ── Private helpers ──────────────────────────────────────────────
+  findFieldIndex(key) {
+    return this.fields.findIndex((f) => f.key === key);
+  }
+  findNextUnconfirmedIndex(afterIndex) {
+    for (let i = afterIndex + 1; i < this.fields.length; i++) {
+      const field = this.fields[i];
+      if (field && this.statuses[field.key] !== "confirmed") {
+        return i;
+      }
+    }
+    return -1;
+  }
+  notify() {
+    var _a;
+    (_a = this.onChange) == null ? void 0 : _a.call(this);
+  }
+};
+
+// src/validators/registry.ts
+var registry = /* @__PURE__ */ new Map();
+function registerValidator(name, fn) {
+  registry.set(name, fn);
+}
+function getValidator(name) {
+  return registry.get(name);
+}
+function hasValidator(name) {
+  return registry.has(name);
+}
+function unregisterValidator(name) {
+  registry.delete(name);
+}
+function clearValidators() {
+  registry.clear();
+}
+function getRegisteredValidatorNames() {
+  return Array.from(registry.keys());
+}
+
+// src/validation/engine.ts
+function validateField(value, validation, allValues = {}) {
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+  if (!validation) {
+    return { valid: true, errors: [] };
+  }
+  const errors = [];
+  const mode = (_a = validation.mode) != null ? _a : "bail";
+  const addError = (message) => {
+    errors.push(message);
+    return mode === "bail";
+  };
+  if (validation.required) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      if (addError((_b = validation.requiredMessage) != null ? _b : "This field is required")) {
+        return { valid: false, errors };
+      }
+    }
+  }
+  if (value.trim().length === 0) {
+    return { valid: errors.length === 0, errors };
+  }
+  if (validation.minLength !== void 0 && value.length < validation.minLength) {
+    if (addError(
+      (_c = validation.minLengthMessage) != null ? _c : `Must be at least ${String(validation.minLength)} characters`
+    )) {
+      return { valid: false, errors };
+    }
+  }
+  if (validation.maxLength !== void 0 && value.length > validation.maxLength) {
+    if (addError(
+      (_d = validation.maxLengthMessage) != null ? _d : `Must be at most ${String(validation.maxLength)} characters`
+    )) {
+      return { valid: false, errors };
+    }
+  }
+  if (validation.exactLength !== void 0 && value.length !== validation.exactLength) {
+    if (addError(
+      (_e = validation.exactLengthMessage) != null ? _e : `Must be exactly ${String(validation.exactLength)} characters`
+    )) {
+      return { valid: false, errors };
+    }
+  }
+  if (validation.min !== void 0 || validation.max !== void 0) {
+    const num = Number(value);
+    if (!isNaN(num)) {
+      if (validation.min !== void 0 && num < validation.min) {
+        if (addError(
+          (_f = validation.minMessage) != null ? _f : `Must be at least ${String(validation.min)}`
+        )) {
+          return { valid: false, errors };
+        }
+      }
+      if (validation.max !== void 0 && num > validation.max) {
+        if (addError(
+          (_g = validation.maxMessage) != null ? _g : `Must be at most ${String(validation.max)}`
+        )) {
+          return { valid: false, errors };
+        }
+      }
+    }
+  }
+  if (validation.pattern !== void 0 && !validation.pattern.test(value)) {
+    if (addError((_h = validation.patternMessage) != null ? _h : "Invalid format")) {
+      return { valid: false, errors };
+    }
+  }
+  if (validation.isEmail) {
+    const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailPattern.test(value.trim())) {
+      if (addError((_i = validation.isEmailMessage) != null ? _i : "Enter a valid email address")) {
+        return { valid: false, errors };
+      }
+    }
+  }
+  if (validation.use !== void 0) {
+    const names = Array.isArray(validation.use) ? validation.use : [validation.use];
+    for (const name of names) {
+      const validatorFn = getValidator(name);
+      if (validatorFn) {
+        const result = validatorFn(value, allValues);
+        if (typeof result === "string") {
+          if (addError(result)) {
+            return { valid: false, errors };
+          }
+        } else if (result === false) {
+          if (addError(`Validation "${name}" failed`)) {
+            return { valid: false, errors };
+          }
+        }
+      }
+    }
+  }
+  if (validation.custom !== void 0) {
+    const result = validation.custom(value, allValues);
+    if (typeof result === "string") {
+      if (addError(result)) {
+        return { valid: false, errors };
+      }
+    } else if (result === false) {
+      if (addError("Validation failed")) {
+        return { valid: false, errors };
+      }
+    }
+  }
+  if (validation.rules !== void 0) {
+    for (const rule of validation.rules) {
+      if (rule.async) continue;
+      const result = rule.validate(value, allValues);
+      if (typeof result === "string") {
+        if (addError(result)) {
+          return { valid: false, errors };
+        }
+      } else if (result === false) {
+        if (addError((_j = rule.message) != null ? _j : `Validation "${rule.name}" failed`)) {
+          return { valid: false, errors };
+        }
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+function hasAsyncValidation(validation) {
+  var _a;
+  if (!validation) return false;
+  if ((_a = validation.rules) == null ? void 0 : _a.some((r) => r.async)) return true;
+  if (validation.serverValidate) return true;
+  return false;
+}
+function validateFieldAsync(value, validation, allValues = {}) {
+  const controller = new AbortController();
+  const promise = (async () => {
+    var _a, _b;
+    const syncResult = validateField(value, validation, allValues);
+    if (!syncResult.valid) {
+      return syncResult;
+    }
+    if (!validation) {
+      return { valid: true, errors: [] };
+    }
+    const errors = [];
+    const mode = (_a = validation.mode) != null ? _a : "bail";
+    const addError = (message) => {
+      errors.push(message);
+      return mode === "bail";
+    };
+    if (validation.custom !== void 0) {
+      const result = validation.custom(value, allValues);
+      if (result instanceof Promise) {
+        if (controller.signal.aborted) return { valid: true, errors: [] };
+        const resolved = await result;
+        if (controller.signal.aborted) return { valid: true, errors: [] };
+        if (typeof resolved === "string") {
+          if (addError(resolved)) return { valid: false, errors };
+        } else if (resolved === false) {
+          if (addError("Validation failed")) return { valid: false, errors };
+        }
+      }
+    }
+    if (validation.use !== void 0) {
+      const names = Array.isArray(validation.use) ? validation.use : [validation.use];
+      for (const name of names) {
+        const validatorFn = getValidator(name);
+        if (validatorFn) {
+          const result = validatorFn(value, allValues);
+          if (result instanceof Promise) {
+            if (controller.signal.aborted) return { valid: true, errors: [] };
+            const resolved = await result;
+            if (controller.signal.aborted) return { valid: true, errors: [] };
+            if (typeof resolved === "string") {
+              if (addError(resolved)) return { valid: false, errors };
+            } else if (resolved === false) {
+              if (addError(`Validation "${name}" failed`))
+                return { valid: false, errors };
+            }
+          }
+        }
+      }
+    }
+    if (validation.rules !== void 0) {
+      for (const rule of validation.rules) {
+        if (!rule.async) continue;
+        if (controller.signal.aborted) return { valid: true, errors: [] };
+        const result = await rule.validate(value, allValues);
+        if (controller.signal.aborted) return { valid: true, errors: [] };
+        if (typeof result === "string") {
+          if (addError(result)) return { valid: false, errors };
+        } else if (result === false) {
+          if (addError((_b = rule.message) != null ? _b : `Validation "${rule.name}" failed`))
+            return { valid: false, errors };
+        }
+      }
+    }
+    if (validation.serverValidate) {
+      if (controller.signal.aborted) return { valid: true, errors: [] };
+      const serverResult = await runServerValidation(
+        value,
+        validation.serverValidate,
+        allValues,
+        controller.signal
+      );
+      if (controller.signal.aborted) return { valid: true, errors: [] };
+      if (!serverResult.valid) {
+        for (const err of serverResult.errors) {
+          if (addError(err)) return { valid: false, errors };
+        }
+      }
+    }
+    return { valid: errors.length === 0, errors };
+  })();
+  return {
+    promise,
+    abort: () => controller.abort()
+  };
+}
+async function runServerValidation(value, config, allValues, signal) {
+  var _a, _b;
+  const { url, method = "POST", headers = {}, timeout = 5e3 } = config;
+  try {
+    const timeoutId = setTimeout(() => {
+    }, timeout);
+    const fetchOptions = {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      signal
+    };
+    if (method === "POST") {
+      fetchOptions.body = JSON.stringify({ value, allValues });
+    }
+    const response = await fetch(url, fetchOptions);
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      return {
+        valid: false,
+        errors: [(_a = config.timeoutMessage) != null ? _a : "Server validation failed"]
+      };
+    }
+    const data = await response.json();
+    const isValid = getNestedValue(data, config.responsePath);
+    if (isValid === true || isValid === "true") {
+      return { valid: true, errors: [] };
+    }
+    const errorMsg = getNestedValue(data, config.errorPath);
+    const message = typeof errorMsg === "string" && errorMsg.length > 0 ? errorMsg : "Server validation failed";
+    return { valid: false, errors: [message] };
+  } catch (err) {
+    if (signal.aborted) {
+      return { valid: true, errors: [] };
+    }
+    const message = err instanceof Error && err.name === "AbortError" ? "Validation cancelled" : (_b = config.timeoutMessage) != null ? _b : "Server validation failed";
+    return { valid: false, errors: [message] };
+  }
+}
+function getNestedValue(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === void 0) return void 0;
+    if (typeof current !== "object") return void 0;
+    current = current[part];
+  }
+  return current;
+}
+
+// src/validators/builtins.ts
+var registered = false;
+function registerBuiltinValidators() {
+  if (registered) return;
+  registered = true;
+  registerValidator("indianPhone", (value) => {
+    const cleaned = value.replace(/\s+/g, "");
+    return /^[6-9]\d{9}$/.test(cleaned) || "Enter a valid 10-digit Indian phone number";
+  });
+  registerValidator("indianPincode", (value) => {
+    return /^\d{6}$/.test(value.trim()) || "Enter a valid 6-digit pincode";
+  });
+  registerValidator("aadhaar", (value) => {
+    const cleaned = value.replace(/\s+/g, "");
+    return /^\d{12}$/.test(cleaned) || "Enter a valid 12-digit Aadhaar number";
+  });
+  registerValidator("pan", (value) => {
+    return /^[A-Z]{5}\d{4}[A-Z]$/.test(value.trim().toUpperCase()) || "Enter a valid PAN (e.g., ABCDE1234F)";
+  });
+  registerValidator("gst", (value) => {
+    return /^\d{2}[A-Z]{5}\d{4}[A-Z]\d[A-Z\d][A-Z]$/.test(value.trim().toUpperCase()) || "Enter a valid 15-character GST number";
+  });
+  registerValidator("ifsc", (value) => {
+    return /^[A-Z]{4}0[A-Z0-9]{6}$/.test(value.trim().toUpperCase()) || "Enter a valid IFSC code (e.g., SBIN0001234)";
+  });
+  registerValidator("email", (value) => {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim()) || "Enter a valid email address";
+  });
+  registerValidator("url", (value) => {
+    try {
+      new URL(value.trim());
+      return true;
+    } catch {
+      return "Enter a valid URL";
+    }
+  });
+  registerValidator("strongPassword", (value) => {
+    if (value.length < 8) return "Password must be at least 8 characters";
+    if (!/[A-Z]/.test(value)) return "Password must contain an uppercase letter";
+    if (!/[a-z]/.test(value)) return "Password must contain a lowercase letter";
+    if (!/\d/.test(value)) return "Password must contain a number";
+    if (!/[^A-Za-z0-9]/.test(value)) return "Password must contain a special character";
+    return true;
+  });
+  registerValidator("alphanumeric", (value) => {
+    return /^[A-Za-z0-9]+$/.test(value) || "Only letters and numbers are allowed";
+  });
+  registerValidator("noSpaces", (value) => {
+    return !/\s/.test(value) || "Spaces are not allowed";
+  });
+  registerValidator("futureDate", (value) => {
+    const date = new Date(value);
+    if (isNaN(date.getTime())) return "Enter a valid date";
+    return date > /* @__PURE__ */ new Date() || "Date must be in the future";
+  });
+  registerValidator("pastDate", (value) => {
+    const date = new Date(value);
+    if (isNaN(date.getTime())) return "Enter a valid date";
+    return date < /* @__PURE__ */ new Date() || "Date must be in the past";
+  });
+  registerValidator("minAge", (value) => {
+    const date = new Date(value);
+    if (isNaN(date.getTime())) return "Enter a valid date";
+    const today = /* @__PURE__ */ new Date();
+    const age = today.getFullYear() - date.getFullYear();
+    const monthDiff = today.getMonth() - date.getMonth();
+    const dayDiff = today.getDate() - date.getDate();
+    const actualAge = monthDiff < 0 || monthDiff === 0 && dayDiff < 0 ? age - 1 : age;
+    return actualAge >= 18 || "You must be at least 18 years old";
+  });
+}
+
+// src/i18n/strings.ts
+var defaultStrings = {
+  editLabel: "Edit",
+  requiredMessage: "This field is required",
+  otpResend: "Resend code",
+  otpTimer: "Resend in {seconds}s",
+  submitLabel: "Submit",
+  loadingLabel: "Checking\u2026",
+  successLabel: "Looks good!",
+  retryLabel: "Try again",
+  fetchErrorMessage: "Something went wrong. Please try again."
+};
+function mergeStrings(custom) {
+  if (!custom) return { ...defaultStrings };
+  return { ...defaultStrings, ...custom };
+}
+
+// src/dynamic/fetchConfig.ts
+var ConfigFetchError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigFetchError";
+  }
+};
+async function fetchFormConfig(url, options) {
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        "Accept": "application/json",
+        ...options == null ? void 0 : options.headers
+      }
+    });
+    if (!response.ok) {
+      throw new ConfigFetchError(`HTTP error! status: ${response.status}`);
+    }
+    const data = await response.json();
+    if (!data || typeof data !== "object") {
+      throw new ConfigFetchError("Invalid response: expected a JSON object.");
+    }
+    if (!Array.isArray(data.fields)) {
+      throw new ConfigFetchError("Invalid schema: 'fields' must be an array.");
+    }
+    return data;
+  } catch (error) {
+    if (error instanceof ConfigFetchError) {
+      throw error;
+    }
+    throw new ConfigFetchError(
+      error instanceof Error ? error.message : "Failed to fetch form configuration"
+    );
+  }
+}
+
+exports.ConfigFetchError = ConfigFetchError;
+exports.FormStateEngine = FormStateEngine;
+exports.clearValidators = clearValidators;
+exports.defaultStrings = defaultStrings;
+exports.fetchFormConfig = fetchFormConfig;
+exports.getRegisteredValidatorNames = getRegisteredValidatorNames;
+exports.getValidator = getValidator;
+exports.hasAsyncValidation = hasAsyncValidation;
+exports.hasValidator = hasValidator;
+exports.mergeStrings = mergeStrings;
+exports.registerBuiltinValidators = registerBuiltinValidators;
+exports.registerValidator = registerValidator;
+exports.unregisterValidator = unregisterValidator;
+exports.validateField = validateField;
+exports.validateFieldAsync = validateFieldAsync;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map