@viveksinghind/narrative-form-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,484 @@
+interface NarrativeErrorDisplay {
+    mode?: "inline" | "toast" | "shake" | "inline+shake" | "tooltip";
+    position?: "below" | "above";
+    icon?: boolean;
+    iconChar?: string;
+    animateIn?: "fadeUp" | "slideDown" | "none";
+    clearOn?: "onChange" | "onFocus";
+}
+interface NarrativeField {
+    key: string;
+    type: NarrativeFieldType;
+    prefix: string;
+    suffix?: string;
+    placeholder?: string;
+    order?: number;
+    options?: string[];
+    animate?: boolean;
+    autoAdvance?: boolean;
+    lockPrevious?: boolean;
+    showIf?: (values: NarrativeFieldValues) => boolean;
+    className?: string;
+    inputClassName?: string;
+    editable?: boolean;
+    defaultValue?: string;
+    validation?: NarrativeValidation;
+    sanitise?: (value: string) => string;
+    format?: (value: string) => string;
+    otpLength?: number;
+    onRequest?: () => void | Promise<void>;
+    onVerify?: (otp: string) => void | Promise<void>;
+    resendLabel?: string;
+    resendDelay?: number;
+}
+type NarrativeFieldType = "text" | "tel" | "email" | "password" | "number" | "select" | "chips" | "multi-chips" | "date" | "otp";
+interface NarrativeValidation {
+    required?: boolean;
+    requiredMessage?: string;
+    minLength?: number;
+    minLengthMessage?: string;
+    maxLength?: number;
+    maxLengthMessage?: string;
+    exactLength?: number;
+    exactLengthMessage?: string;
+    pattern?: RegExp;
+    patternMessage?: string;
+    isEmail?: boolean;
+    isEmailMessage?: string;
+    min?: number;
+    minMessage?: string;
+    max?: number;
+    maxMessage?: string;
+    custom?: (value: string, allValues: NarrativeFieldValues) => boolean | string | Promise<boolean | string>;
+    rules?: NarrativeValidationRule[];
+    mode?: "bail" | "all";
+    trigger?: "onChange" | "onBlur" | "onSubmit" | "onConfirm" | "debounced";
+    debounceMs?: number;
+    errorDisplay?: NarrativeErrorDisplay;
+    use?: string | string[];
+    serverValidate?: NarrativeServerValidation;
+    loadingText?: string;
+    successIndicator?: boolean;
+}
+interface NarrativeValidationRule {
+    name: string;
+    validate: (value: string, allValues: NarrativeFieldValues) => boolean | string | Promise<boolean | string>;
+    message?: string;
+    async?: boolean;
+    debounce?: number;
+}
+interface NarrativeServerValidation {
+    url: string;
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    debounceMs?: number;
+    timeout?: number;
+    timeoutMessage?: string;
+    responsePath: string;
+    errorPath: string;
+}
+interface NarrativeTheme {
+    background?: string;
+    textColor?: string;
+    inputBorderColor?: string;
+    placeholderColor?: string;
+    errorColor?: string;
+    filledColor?: string;
+    cursorColor?: string;
+    successColor?: string;
+    loadingColor?: string;
+    fontFamily?: string;
+    uiFontFamily?: string;
+    fontSize?: string;
+    mobileFontSize?: string;
+    inputFontStyle?: string;
+    lineGap?: string;
+    pagePadding?: string;
+    buttonRadius?: string;
+    buttonBackground?: string;
+    buttonColor?: string;
+    enterBtnSize?: string;
+    chipBorderRadius?: string;
+    chipBorderColor?: string;
+    chipActiveBackground?: string;
+    chipActiveColor?: string;
+    chipFontStyle?: string;
+    mode?: "light" | "dark" | "auto";
+    dark?: Partial<NarrativeTheme>;
+}
+interface NarrativeTypewriter {
+    enabled?: boolean;
+    speed?: number;
+    cursor?: boolean;
+    cursorChar?: string;
+    pauseAfter?: number;
+}
+interface NarrativeWelcome {
+    show?: boolean;
+    heading?: string;
+    subtext?: string;
+    ctaLabel?: string;
+}
+interface NarrativeDone {
+    show?: boolean;
+    message?: string | ((values: NarrativeFieldValues) => string);
+    ctaLabel?: string;
+    onSubmit?: (values: NarrativeFieldValues, meta: NarrativeMeta) => void | Promise<void>;
+}
+interface NarrativeFormConfig {
+    form: {
+        id: string;
+        name: string;
+        version: number;
+    };
+    welcome?: NarrativeWelcome;
+    fields: NarrativeField[];
+    theme?: NarrativeTheme;
+    done?: NarrativeDone;
+}
+interface NarrativeMeta {
+    formId?: string;
+    formVersion?: number;
+    totalTimeMs: number;
+    fieldTimings: Record<string, number>;
+}
+interface NarrativeFieldValues {
+    [key: string]: string | string[];
+}
+interface NarrativeI18n {
+    editLabel?: string;
+    requiredMessage?: string;
+    otpResend?: string;
+    otpTimer?: string;
+    submitLabel?: string;
+    loadingLabel?: string;
+    successLabel?: string;
+    retryLabel?: string;
+    fetchErrorMessage?: string;
+}
+interface NarrativeRefHandle {
+    next: () => void;
+    getValues: () => NarrativeFieldValues;
+    reset: () => void;
+    focusField: (key: string) => void;
+}
+/** Cross-field validation rule that validates across multiple fields. */
+interface NarrativeCrossFieldValidator {
+    /** Fields this validator watches. */
+    fields: string[];
+    /** Field key where the error should be displayed. */
+    errorField: string;
+    /** Validation function receiving all values. */
+    validate: (values: NarrativeFieldValues) => boolean | string | Promise<boolean | string>;
+    /** Fallback error message. */
+    message?: string;
+}
+interface NarrativeCallbacks {
+    onChange?: (key: string, value: string) => void;
+    onFieldFocus?: (key: string) => void;
+    onFieldBlur?: (key: string, value: string) => void;
+    onFieldComplete?: (key: string, value: string, timeSpentMs: number) => void;
+    onEdit?: (key: string) => void;
+    onError?: (key: string, message: string) => void;
+    onDropOff?: (lastFieldKey: string) => void;
+    onComplete?: (values: NarrativeFieldValues, meta: NarrativeMeta) => void;
+}
+
+/**
+ * Framework-agnostic form state manager for narrative-form.
+ * Manages field lifecycle, values, and timing metadata.
+ *
+ * @remarks
+ * This module has zero framework dependencies — it is pure TypeScript logic
+ * consumed by React/Vue/Angular wrappers.
+ */
+
+/** Possible statuses for a single field in the form flow. */
+type FieldStatus = "idle" | "typing" | "active" | "confirmed" | "editing";
+/** Snapshot of the entire form's state at a point in time. */
+interface FormStateSnapshot {
+    /** Ordered list of field configurations. */
+    readonly fields: readonly NarrativeField[];
+    /** Index of the currently active field (-1 if none are active yet). */
+    readonly activeIndex: number;
+    /** Map of field key → current value. */
+    readonly values: Readonly<NarrativeFieldValues>;
+    /** Map of field key → current lifecycle status. */
+    readonly statuses: Readonly<Record<string, FieldStatus>>;
+    /** Whether every field has been confirmed. */
+    readonly isComplete: boolean;
+}
+/**
+ * Pure form state engine for narrative-form.
+ *
+ * Tracks which field is active, all confirmed values, per-field statuses,
+ * and timing metadata for analytics. Framework wrappers subscribe to
+ * state changes via the `onChange` callback.
+ */
+declare class FormStateEngine {
+    private fields;
+    private activeIndex;
+    private values;
+    private statuses;
+    private fieldTimings;
+    private fieldStartTimes;
+    private formStartTime;
+    private onChange;
+    /**
+     * Create a new FormStateEngine.
+     *
+     * @param fields - Ordered array of field configurations
+     * @param onChange - Optional callback invoked on every state mutation
+     */
+    constructor(fields: readonly NarrativeField[], onChange?: () => void);
+    /** Returns a readonly snapshot of the current form state. */
+    getSnapshot(): FormStateSnapshot;
+    /** Returns a copy of all confirmed field values. */
+    getValues(): NarrativeFieldValues;
+    /**
+     * Returns analytics metadata about the form session.
+     *
+     * @param formId - Optional form identifier
+     * @param formVersion - Optional form version number
+     */
+    getMeta(formId?: string, formVersion?: number): NarrativeMeta;
+    /**
+     * Start typing animation for a specific field.
+     * Transitions the field from `idle` to `typing`.
+     *
+     * @param key - The field key to begin typing
+     */
+    startTyping(key: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string, value: string | string[]): void;
+    /**
+     * 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: string): void;
+    /**
+     * Re-confirm a field after editing.
+     *
+     * @param key - The field key to re-confirm
+     * @param value - The new confirmed value
+     */
+    reconfirmField(key: string, value: string | string[]): void;
+    /**
+     * Move to the next field without confirming the current one.
+     * Useful for programmatic navigation via ref API.
+     */
+    next(): void;
+    /**
+     * 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: string): void;
+    /**
+     * Reset all form state to initial values.
+     * Clears all values, statuses, and timings.
+     */
+    reset(): void;
+    /**
+     * Update the onChange listener.
+     * Used by framework wrappers to trigger re-renders.
+     *
+     * @param fn - Callback to invoke on state changes
+     */
+    setOnChange(fn: () => void): void;
+    private findFieldIndex;
+    private findNextUnconfirmedIndex;
+    private notify;
+}
+
+/**
+ * Validation engine for narrative-form.
+ *
+ * @remarks
+ * Runs validation rules in a strict priority order defined in SPEC.md.
+ * Supports both `bail` (stop at first failure) and `all` (collect all errors) modes.
+ *
+ * **Priority order:**
+ * 1. required
+ * 2. minLength / maxLength
+ * 3. exactLength
+ * 4. min / max
+ * 5. pattern / isEmail
+ * 6. use (registered plugin validators) — in array order
+ * 7. Sync custom rules — in array order
+ * 8. Async custom rules — in array order
+ * 9. serverValidate URL call
+ * 10. Global cross-field validators (handled externally)
+ *
+ * Async rules only run if all sync rules pass first.
+ */
+
+/** Result of running the validation engine on a single field. */
+interface ValidationResult {
+    /** Whether the field value is valid. */
+    valid: boolean;
+    /** Array of error messages (empty if valid). */
+    errors: string[];
+}
+/** Result of async validation — extends sync with an abort handle. */
+interface AsyncValidationHandle {
+    /** Promise that resolves with the validation result. */
+    promise: Promise<ValidationResult>;
+    /** Abort the in-flight async validation. */
+    abort: () => void;
+}
+/**
+ * Validate a single field value synchronously.
+ *
+ * Runs rules in strict priority order. In `bail` mode (default),
+ * stops at the first failure. In `all` mode, collects every error.
+ *
+ * @param value - The field value to validate
+ * @param validation - The validation configuration for this field
+ * @param allValues - All confirmed field values (for cross-field checks)
+ * @returns Validation result with valid flag and error messages
+ */
+declare function validateField(value: string, validation: NarrativeValidation | undefined, allValues?: NarrativeFieldValues): ValidationResult;
+/**
+ * Check if a field has any async validation rules that need to run.
+ *
+ * @param validation - The validation configuration to check
+ * @returns Whether async validation is needed
+ */
+declare function hasAsyncValidation(validation: NarrativeValidation | undefined): boolean;
+/**
+ * Run async validation rules on a field value.
+ *
+ * Only runs if all sync rules pass first. Returns an abort handle
+ * so callers can cancel in-flight requests on new input.
+ *
+ * @param value - The field value to validate
+ * @param validation - The validation configuration
+ * @param allValues - All confirmed field values
+ * @returns An abort handle with a promise and abort method
+ */
+declare function validateFieldAsync(value: string, validation: NarrativeValidation | undefined, allValues?: NarrativeFieldValues): AsyncValidationHandle;
+
+/**
+ * Validator plugin registry for narrative-form.
+ *
+ * @remarks
+ * Allows developers to register reusable named validators globally at app level.
+ * Fields can then reference them by name via the `use` property.
+ *
+ * @example
+ * ```ts
+ * registerValidator("indianPhone", (value) => {
+ *   return /^[6-9]\d{9}$/.test(value) || "Enter a valid Indian phone number";
+ * });
+ *
+ * // In field config:
+ * { key: "phone", type: "tel", prefix: "My phone is", validation: { use: "indianPhone" } }
+ * ```
+ */
+
+/** A validator function that returns true on pass or an error string on fail. */
+type ValidatorFn = (value: string, allValues: NarrativeFieldValues) => boolean | string | Promise<boolean | string>;
+/**
+ * Register a reusable named validator.
+ *
+ * @param name - Unique validator name (e.g., "indianPhone", "pan")
+ * @param fn - Validator function returning true on pass or error string on fail
+ */
+declare function registerValidator(name: string, fn: ValidatorFn): void;
+/**
+ * Retrieve a registered validator by name.
+ *
+ * @param name - The validator name to look up
+ * @returns The validator function, or undefined if not found
+ */
+declare function getValidator(name: string): ValidatorFn | undefined;
+/**
+ * Check if a validator is registered.
+ *
+ * @param name - The validator name to check
+ */
+declare function hasValidator(name: string): boolean;
+/**
+ * Remove a registered validator.
+ *
+ * @param name - The validator name to remove
+ */
+declare function unregisterValidator(name: string): void;
+/**
+ * Clear all registered validators.
+ * Useful for testing or hot-reload scenarios.
+ */
+declare function clearValidators(): void;
+/**
+ * Get all registered validator names.
+ * Useful for debugging.
+ */
+declare function getRegisteredValidatorNames(): string[];
+
+/**
+ * Built-in validators shipped with narrative-form.
+ *
+ * @remarks
+ * These cover common Indian regulatory formats and universal patterns.
+ * Call `registerBuiltinValidators()` once at app startup to register them all.
+ *
+ * **India-specific:** indianPhone, indianPincode, aadhaar, pan, gst, ifsc
+ * **Universal:** email, url, strongPassword, alphanumeric, noSpaces,
+ *                futureDate, pastDate, minAge
+ *
+ * @example
+ * ```ts
+ * import { registerBuiltinValidators } from "@viveksinghind/narrative-form-core";
+ * registerBuiltinValidators(); // Call once at app startup
+ * ```
+ */
+/**
+ * Register all built-in validators.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ */
+declare function registerBuiltinValidators(): void;
+
+/**
+ * Default internationalisation strings for narrative-form.
+ *
+ * @remarks
+ * All user-facing copy lives here. Consumers override via the `i18n` prop,
+ * which is deep-merged with these defaults using {@link mergeStrings}.
+ */
+
+/** Default English strings shipped with the package. */
+declare const defaultStrings: Readonly<Required<NarrativeI18n>>;
+/**
+ * Deep-merge user-provided i18n overrides with the default strings.
+ *
+ * @param custom - Partial i18n overrides from the consumer
+ * @returns A complete i18n object with all keys guaranteed to be present
+ */
+declare function mergeStrings(custom?: Partial<NarrativeI18n>): Required<NarrativeI18n>;
+
+interface FetchConfigOptions {
+    headers?: Record<string, string>;
+}
+declare class ConfigFetchError extends Error {
+    constructor(message: string);
+}
+declare function fetchFormConfig(url: string, options?: FetchConfigOptions): Promise<NarrativeFormConfig>;
+
+export { type AsyncValidationHandle, ConfigFetchError, type FetchConfigOptions, type FieldStatus, FormStateEngine, type FormStateSnapshot, type NarrativeCallbacks, type NarrativeCrossFieldValidator, type NarrativeDone, type NarrativeErrorDisplay, type NarrativeField, type NarrativeFieldType, type NarrativeFieldValues, type NarrativeFormConfig, type NarrativeI18n, type NarrativeMeta, type NarrativeRefHandle, type NarrativeServerValidation, type NarrativeTheme, type NarrativeTypewriter, type NarrativeValidation, type NarrativeValidationRule, type NarrativeWelcome, type ValidationResult, type ValidatorFn, clearValidators, defaultStrings, fetchFormConfig, getRegisteredValidatorNames, getValidator, hasAsyncValidation, hasValidator, mergeStrings, registerBuiltinValidators, registerValidator, unregisterValidator, validateField, validateFieldAsync };