@neutro/form 0.0.4 → 0.1.0

package/dist/devtools.cjs

@@ -0,0 +1,244 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/devtools.ts
+var devtools_exports = {};
+__export(devtools_exports, {
+  devtools: () => devtools
+});
+module.exports = __toCommonJS(devtools_exports);
+
+// ../core/src/index.ts
+function isDeepEqual(a, b, hash = /* @__PURE__ */ new WeakMap()) {
+  if (a === b) return true;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (a instanceof RegExp && b instanceof RegExp) return a.toString() === b.toString();
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (hash.has(a) && hash.get(a) === b) return true;
+  hash.set(a, b);
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false;
+    for (const item of a) if (!b.has(item)) return false;
+    return true;
+  }
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false;
+    for (const [key, val] of a) {
+      if (!b.has(key) || !isDeepEqual(val, b.get(key), hash)) return false;
+    }
+    return true;
+  }
+  const keysA = Reflect.ownKeys(a);
+  const keysB = new Set(Reflect.ownKeys(b));
+  if (keysA.length !== keysB.size) return false;
+  for (const key of keysA) {
+    if (!keysB.has(key) || !isDeepEqual(a[key], b[key], hash)) return false;
+  }
+  return true;
+}
+
+// ../core/src/devtools.ts
+var BADGE_STYLE = "background:#6366f1;color:#fff;padding:2px 6px;border-radius:3px;font-weight:bold;font-size:11px;";
+var DIM_STYLE = "color:#888;font-weight:normal;";
+var ACTION_STYLE = "color:#f59e0b;font-weight:bold;";
+var RESET_STYLE = "color:inherit;font-weight:normal;";
+function formatElapsed(ms) {
+  return ms < 1e3 ? `+${ms}ms` : `+${(ms / 1e3).toFixed(1)}s`;
+}
+function describeAction(action) {
+  switch (action.type) {
+    case "SET":
+      return `SET ${action.path}`;
+    case "VALIDATE":
+      return action.paths ? `VALIDATE [${action.paths.join(", ")}]` : "VALIDATE";
+    case "SUBMIT":
+      return "SUBMIT";
+    case "RESET":
+      return "RESET";
+    case "SET_ERRORS":
+      return `SET_ERRORS [${Object.keys(action.errors).join(", ")}]`;
+    case "CLEAR_ERRORS":
+      return "CLEAR_ERRORS";
+    case "CONNECT":
+      return `CONNECT ${action.path}`;
+    case "DISCONNECT":
+      return `DISCONNECT ${action.path}`;
+    case "BLUR":
+      return `BLUR ${action.path}`;
+    case "BATCH_START":
+      return "BATCH_START";
+    case "BATCH_END":
+      return "BATCH_END";
+    case "ARRAY_APPEND":
+      return `ARRAY_APPEND ${action.path}`;
+    case "ARRAY_INSERT":
+      return `ARRAY_INSERT ${action.path}[${action.index}]`;
+    case "ARRAY_REMOVE":
+      return `ARRAY_REMOVE ${action.path}[${action.index}]`;
+    case "ARRAY_MOVE":
+      return `ARRAY_MOVE ${action.path} ${action.from}\u2192${action.to}`;
+    case "ARRAY_SWAP":
+      return `ARRAY_SWAP ${action.path} [${action.i}\u2194${action.j}]`;
+    default:
+      return action.type;
+  }
+}
+function computeDiff(prev, next) {
+  const rows = [];
+  const slices = ["values", "errors", "touched", "dirty"];
+  for (const slice of slices) {
+    const prevSlice = prev[slice];
+    const nextSlice = next[slice];
+    const allKeys = /* @__PURE__ */ new Set([...Object.keys(prevSlice), ...Object.keys(nextSlice)]);
+    for (const key of allKeys) {
+      const p = prevSlice[key];
+      const n = nextSlice[key];
+      const equal = slice === "values" ? isDeepEqual(p, n) : p === n;
+      if (!equal) rows.push({ slice, key, prev: p, next: n });
+    }
+  }
+  if (prev.isSubmitting !== next.isSubmitting) {
+    rows.push({
+      slice: "meta",
+      key: "isSubmitting",
+      prev: prev.isSubmitting,
+      next: next.isSubmitting
+    });
+  }
+  if (prev.isValidating !== next.isValidating) {
+    rows.push({
+      slice: "meta",
+      key: "isValidating",
+      prev: prev.isValidating,
+      next: next.isValidating
+    });
+  }
+  return rows;
+}
+function logAction(action, state, prev, name, groupFn, lastTimeRef) {
+  const now = Date.now();
+  const elapsed = now - lastTimeRef.value;
+  lastTimeRef.value = now;
+  const label = describeAction(action);
+  const timestamp = new Date(now).toLocaleTimeString("en", {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+  groupFn(
+    "%c NeutroForm: %s %c %s %c %s  %s",
+    BADGE_STYLE,
+    name,
+    RESET_STYLE,
+    label,
+    DIM_STYLE,
+    timestamp,
+    formatElapsed(elapsed)
+  );
+  console.log("%c action", ACTION_STYLE, action);
+  const diff = computeDiff(prev, state);
+  if (diff.length > 0) {
+    console.table(diff);
+  } else {
+    console.log("%c no state change", DIM_STYLE);
+  }
+  console.groupCollapsed("%c full state", DIM_STYLE);
+  console.log("%o", state);
+  console.groupEnd();
+  console.groupEnd();
+}
+var registeredForms = /* @__PURE__ */ new WeakSet();
+function devtools(form, options = {}) {
+  if (registeredForms.has(form)) {
+    console.warn(
+      "[NeutroForm devtools] devtools() was called twice on the same form instance. Ignoring duplicate registration."
+    );
+    return () => {
+    };
+  }
+  registeredForms.add(form);
+  const name = options.name ?? "Form";
+  const collapsed = options.collapsed ?? true;
+  const groupFn = collapsed ? console.groupCollapsed.bind(console) : console.group.bind(console);
+  let prevState = form.getState();
+  const lastTimeRef = { value: Date.now() };
+  let inBatch = false;
+  let batchActions = [];
+  groupFn("%c NeutroForm: %s %c init", BADGE_STYLE, name, RESET_STYLE);
+  console.log("%c initial state", DIM_STYLE, form.getState());
+  console.groupEnd();
+  const unsubscribe = form._subscribeToActions((action, state) => {
+    if (action.type === "BATCH_START") {
+      inBatch = true;
+      batchActions = [];
+      return;
+    }
+    if (action.type === "BATCH_END") {
+      inBatch = false;
+      const count = batchActions.length;
+      if (count === 0) {
+        batchActions = [];
+        return;
+      }
+      const now = Date.now();
+      const elapsed = now - lastTimeRef.value;
+      lastTimeRef.value = now;
+      const timestamp = new Date(now).toLocaleTimeString("en", {
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit"
+      });
+      groupFn(
+        "%c NeutroForm: %s %c BATCH (%d mutations) %c %s  %s",
+        BADGE_STYLE,
+        name,
+        RESET_STYLE,
+        count,
+        DIM_STYLE,
+        timestamp,
+        formatElapsed(elapsed)
+      );
+      const frozenTimeRef = { value: lastTimeRef.value };
+      for (const { action: a, state: s, prev: prev2 } of batchActions) {
+        logAction(a, s, prev2, name, groupFn, frozenTimeRef);
+      }
+      console.groupEnd();
+      batchActions = [];
+      return;
+    }
+    if (inBatch) {
+      batchActions.push({ action, state, prev: prevState });
+      prevState = state;
+      return;
+    }
+    const prev = prevState;
+    prevState = state;
+    logAction(action, state, prev, name, groupFn, lastTimeRef);
+  });
+  return () => {
+    registeredForms.delete(form);
+    unsubscribe();
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  devtools
+});

package/dist/devtools.d.cts

@@ -0,0 +1,141 @@
+/**
+ * @neutro/form-core
+ * High-Performance, Zero-Dependency, Framework-Agnostic Reactive Form Engine.
+ */
+type Primitive = string | number | boolean | null | undefined | Date | File;
+type Prev = [never, 0, 1, 2, 3, 4, 5, ...any[]];
+type PathImpl<T, K extends keyof T, Depth extends number = 5> = [Depth] extends [never] ? never : K extends string ? T[K] extends Primitive ? K : T[K] extends Array<infer U> ? K | `${K}.${number}` | (U extends object ? `${K}.${number}.${PathImpl<U, keyof U, Prev[Depth]>}` : never) : NonNullable<T[K]> extends object ? K | `${K}.${PathImpl<NonNullable<T[K]>, keyof NonNullable<T[K]>, Prev[Depth]>}` : K : never;
+type Path<T> = PathImpl<T, keyof T> & string;
+type _GetPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? _GetPathValue<NonNullable<T[K]>, Rest> : T extends readonly any[] ? _GetPathValue<NonNullable<T[number]>, Rest> : unknown : P extends keyof T ? T[P] : T extends readonly any[] ? T[number] : unknown;
+type GetPathValue<T, P extends string> = _GetPathValue<T, P>;
+interface FormState<T> {
+    values: T;
+    errors: Record<string, string>;
+    touched: Record<string, boolean>;
+    dirty: Record<string, boolean>;
+    isSubmitting: boolean;
+    isValidating: boolean;
+}
+type FormSubscriber<T> = (state: FormState<T>) => void;
+type PathSubscriber<V = any> = (value: V, fieldState: {
+    error?: string;
+    touched?: boolean;
+    dirty?: boolean;
+}) => void;
+type ValidationMode = 'onChange' | 'onBlur' | 'onTouched' | 'onSubmitOnly';
+type FormAction = {
+    type: 'SET';
+    path: string;
+    value: unknown;
+    options?: {
+        touch?: boolean;
+        validate?: boolean;
+    };
+} | {
+    type: 'VALIDATE';
+    paths?: string[];
+} | {
+    type: 'SUBMIT';
+} | {
+    type: 'RESET';
+    newValues?: unknown;
+} | {
+    type: 'SET_ERRORS';
+    errors: Record<string, string>;
+} | {
+    type: 'CONNECT';
+    path: string;
+} | {
+    type: 'DISCONNECT';
+    path: string;
+} | {
+    type: 'BLUR';
+    path: string;
+} | {
+    type: 'BATCH_START';
+} | {
+    type: 'BATCH_END';
+} | {
+    type: 'ARRAY_APPEND';
+    path: string;
+    item: unknown;
+} | {
+    type: 'ARRAY_INSERT';
+    path: string;
+    index: number;
+    item: unknown;
+} | {
+    type: 'ARRAY_REMOVE';
+    path: string;
+    index: number;
+} | {
+    type: 'ARRAY_MOVE';
+    path: string;
+    from: number;
+    to: number;
+} | {
+    type: 'ARRAY_SWAP';
+    path: string;
+    i: number;
+    j: number;
+} | {
+    type: 'CLEAR_ERRORS';
+};
+interface AriaPropsOptions {
+    required?: boolean;
+    errorId?: string;
+}
+interface AriaProps {
+    'aria-invalid': 'true' | 'false';
+    'aria-describedby': string | undefined;
+    'aria-required': true | undefined;
+}
+interface ConnectOptions {
+    persist?: boolean;
+    format?: (val: string) => string;
+    validateOn?: ValidationMode;
+}
+interface FormInstance<T extends object> {
+    subscribe: (fn: FormSubscriber<T>) => () => void;
+    subscribeToPath<P extends Path<T>>(path: P, fn: PathSubscriber<GetPathValue<T, P>>): () => void;
+    subscribeToPath(path: string, fn: PathSubscriber): () => void;
+    get<P extends Path<T>>(path: P): GetPathValue<T, P>;
+    get(path: string | string[]): any;
+    set: (path: Path<T> | string | string[], val: any, options?: {
+        touch?: boolean;
+        validate?: boolean;
+    }) => void;
+    validate: (scopePaths?: Path<T>[] | string[] | string[][]) => Promise<boolean>;
+    connect: (path: Path<T> | string, el: HTMLElement, options?: ConnectOptions) => () => void;
+    submit: (onValid: (payload: Partial<T>) => void | Promise<void>) => Promise<boolean>;
+    handleSubmit: (onValid: (payload: Partial<T>) => void | Promise<void>, onInvalid?: (errors: Record<string, string>) => void) => (e?: Event) => void;
+    getState: () => FormState<T>;
+    getPayload: () => Partial<T>;
+    getAriaProps: (path: Path<T> | string, options?: AriaPropsOptions) => AriaProps;
+    batch: (fn: () => void) => void;
+    arrayAppend: (path: Path<T> | string | string[], item: any) => void;
+    arrayInsert: (path: Path<T> | string | string[], index: number, item: any) => void;
+    arrayRemove: (path: Path<T> | string | string[], index: number) => void;
+    arrayMove: (path: Path<T> | string | string[], fromIndex: number, toIndex: number) => void;
+    arraySwap: (path: Path<T> | string | string[], indexA: number, indexB: number) => void;
+    reset: (newValues?: T) => void;
+    getConnectedCount: () => number;
+    destroy: () => void;
+    setErrors: (errors: Record<Path<T> | (string & {}), string>) => void;
+    clearErrors: () => void;
+    /**
+     * Returns the effective ValidationMode for a field. Useful for debugging
+     * validation timing; framework adapters should rely on this only in custom
+     * event handlers, not in render logic.
+     */
+    getFieldMode: (path: string) => ValidationMode;
+    _subscribeToActions: (fn: (action: FormAction, state: FormState<T>) => void) => () => void;
+}
+
+interface DevtoolsOptions {
+    name?: string;
+    collapsed?: boolean;
+}
+declare function devtools<T extends object>(form: FormInstance<T>, options?: DevtoolsOptions): () => void;
+
+export { type DevtoolsOptions, devtools };

package/dist/devtools.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @neutro/form-core
+ * High-Performance, Zero-Dependency, Framework-Agnostic Reactive Form Engine.
+ */
+type Primitive = string | number | boolean | null | undefined | Date | File;
+type Prev = [never, 0, 1, 2, 3, 4, 5, ...any[]];
+type PathImpl<T, K extends keyof T, Depth extends number = 5> = [Depth] extends [never] ? never : K extends string ? T[K] extends Primitive ? K : T[K] extends Array<infer U> ? K | `${K}.${number}` | (U extends object ? `${K}.${number}.${PathImpl<U, keyof U, Prev[Depth]>}` : never) : NonNullable<T[K]> extends object ? K | `${K}.${PathImpl<NonNullable<T[K]>, keyof NonNullable<T[K]>, Prev[Depth]>}` : K : never;
+type Path<T> = PathImpl<T, keyof T> & string;
+type _GetPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? _GetPathValue<NonNullable<T[K]>, Rest> : T extends readonly any[] ? _GetPathValue<NonNullable<T[number]>, Rest> : unknown : P extends keyof T ? T[P] : T extends readonly any[] ? T[number] : unknown;
+type GetPathValue<T, P extends string> = _GetPathValue<T, P>;
+interface FormState<T> {
+    values: T;
+    errors: Record<string, string>;
+    touched: Record<string, boolean>;
+    dirty: Record<string, boolean>;
+    isSubmitting: boolean;
+    isValidating: boolean;
+}
+type FormSubscriber<T> = (state: FormState<T>) => void;
+type PathSubscriber<V = any> = (value: V, fieldState: {
+    error?: string;
+    touched?: boolean;
+    dirty?: boolean;
+}) => void;
+type ValidationMode = 'onChange' | 'onBlur' | 'onTouched' | 'onSubmitOnly';
+type FormAction = {
+    type: 'SET';
+    path: string;
+    value: unknown;
+    options?: {
+        touch?: boolean;
+        validate?: boolean;
+    };
+} | {
+    type: 'VALIDATE';
+    paths?: string[];
+} | {
+    type: 'SUBMIT';
+} | {
+    type: 'RESET';
+    newValues?: unknown;
+} | {
+    type: 'SET_ERRORS';
+    errors: Record<string, string>;
+} | {
+    type: 'CONNECT';
+    path: string;
+} | {
+    type: 'DISCONNECT';
+    path: string;
+} | {
+    type: 'BLUR';
+    path: string;
+} | {
+    type: 'BATCH_START';
+} | {
+    type: 'BATCH_END';
+} | {
+    type: 'ARRAY_APPEND';
+    path: string;
+    item: unknown;
+} | {
+    type: 'ARRAY_INSERT';
+    path: string;
+    index: number;
+    item: unknown;
+} | {
+    type: 'ARRAY_REMOVE';
+    path: string;
+    index: number;
+} | {
+    type: 'ARRAY_MOVE';
+    path: string;
+    from: number;
+    to: number;
+} | {
+    type: 'ARRAY_SWAP';
+    path: string;
+    i: number;
+    j: number;
+} | {
+    type: 'CLEAR_ERRORS';
+};
+interface AriaPropsOptions {
+    required?: boolean;
+    errorId?: string;
+}
+interface AriaProps {
+    'aria-invalid': 'true' | 'false';
+    'aria-describedby': string | undefined;
+    'aria-required': true | undefined;
+}
+interface ConnectOptions {
+    persist?: boolean;
+    format?: (val: string) => string;
+    validateOn?: ValidationMode;
+}
+interface FormInstance<T extends object> {
+    subscribe: (fn: FormSubscriber<T>) => () => void;
+    subscribeToPath<P extends Path<T>>(path: P, fn: PathSubscriber<GetPathValue<T, P>>): () => void;
+    subscribeToPath(path: string, fn: PathSubscriber): () => void;
+    get<P extends Path<T>>(path: P): GetPathValue<T, P>;
+    get(path: string | string[]): any;
+    set: (path: Path<T> | string | string[], val: any, options?: {
+        touch?: boolean;
+        validate?: boolean;
+    }) => void;
+    validate: (scopePaths?: Path<T>[] | string[] | string[][]) => Promise<boolean>;
+    connect: (path: Path<T> | string, el: HTMLElement, options?: ConnectOptions) => () => void;
+    submit: (onValid: (payload: Partial<T>) => void | Promise<void>) => Promise<boolean>;
+    handleSubmit: (onValid: (payload: Partial<T>) => void | Promise<void>, onInvalid?: (errors: Record<string, string>) => void) => (e?: Event) => void;
+    getState: () => FormState<T>;
+    getPayload: () => Partial<T>;
+    getAriaProps: (path: Path<T> | string, options?: AriaPropsOptions) => AriaProps;
+    batch: (fn: () => void) => void;
+    arrayAppend: (path: Path<T> | string | string[], item: any) => void;
+    arrayInsert: (path: Path<T> | string | string[], index: number, item: any) => void;
+    arrayRemove: (path: Path<T> | string | string[], index: number) => void;
+    arrayMove: (path: Path<T> | string | string[], fromIndex: number, toIndex: number) => void;
+    arraySwap: (path: Path<T> | string | string[], indexA: number, indexB: number) => void;
+    reset: (newValues?: T) => void;
+    getConnectedCount: () => number;
+    destroy: () => void;
+    setErrors: (errors: Record<Path<T> | (string & {}), string>) => void;
+    clearErrors: () => void;
+    /**
+     * Returns the effective ValidationMode for a field. Useful for debugging
+     * validation timing; framework adapters should rely on this only in custom
+     * event handlers, not in render logic.
+     */
+    getFieldMode: (path: string) => ValidationMode;
+    _subscribeToActions: (fn: (action: FormAction, state: FormState<T>) => void) => () => void;
+}
+
+interface DevtoolsOptions {
+    name?: string;
+    collapsed?: boolean;
+}
+declare function devtools<T extends object>(form: FormInstance<T>, options?: DevtoolsOptions): () => void;
+
+export { type DevtoolsOptions, devtools };