@axzydev/axzy_ui_system 1.2.16 → 1.3.0

package/src/components/organisms/form-builder/fieldRenderer.tsx

@@ -12,41 +12,108 @@ import { getColSpanClass, getGridColsClass } from "@/utils/styles";
 import ITText from "@/components/atoms/text/text";
 import { FaSpinner } from "react-icons/fa";
 
-function useAsyncOptions(options: FieldConfigV2["options"], depends: any[]) {
+/**
+ * Resolves `FieldConfigV2["options"]` to a stable `{ value, label }[]` array,
+ * calling the function form once per dependency change. Returns a loading flag
+ * while an async loader is in flight so the caller can render a placeholder.
+ *
+ * Sync arrays are returned synchronously; async functions are awaited and the
+ * resolved array is memoized until one of the supplied `deps` changes.
+ *
+ * The `deps` argument is intentionally a dynamic array — callers pass in the
+ * values of `dependsOn` siblings so option lists re-fetch when a parent field
+ * changes (e.g. cascading country -> city).
+ */
+function useAsyncOptions(
+  options: FieldConfigV2["options"],
+  deps: ReadonlyArray<unknown>,
+): { options: { value: string; label: string }[]; loading: boolean } {
   const [resolved, setResolved] = useState<{ value: string; label: string }[]>([]);
   const [loading, setLoading] = useState(false);
+
+  // Keep a ref so the async loader closure always reads the freshest options
+  // function without re-running the effect on identity changes.
   const optionsRef = useRef(options);
   optionsRef.current = options;
 
   useEffect(() => {
     const opts = optionsRef.current;
+    let cancelled = false;
+
     if (typeof opts === "function") {
       setLoading(true);
-      opts().then((result) => {
-        setResolved(result.map(o => ({ value: String(o.value), label: o.label })));
-        setLoading(false);
-      });
+      Promise.resolve()
+        .then(() => opts())
+        .then((result) => {
+          if (cancelled) return;
+          setResolved(result.map((o) => ({ value: String(o.value), label: o.label })));
+        })
+        .catch((err) => {
+          if (cancelled) return;
+          if (typeof console !== "undefined") {
+            console.error("[ITFormBuilder] Failed to load async options:", err);
+          }
+          setResolved([]);
+        })
+        .finally(() => {
+          if (!cancelled) setLoading(false);
+        });
     } else if (Array.isArray(opts)) {
-      setResolved(opts.map(o => ({ value: String(o.value), label: o.label })));
+      setResolved(opts.map((o) => ({ value: String(o.value), label: o.label })));
+      setLoading(false);
+    } else {
+      setResolved([]);
+      setLoading(false);
     }
-    // Dependencias dinámicas por diseño (campos dependientes) — no verificables estáticamente.
+
+    return () => {
+      cancelled = true;
+    };
+    // `deps` is intentionally a dynamic array of dependent-values; the ESLint
+    // rule cannot statically verify the dependency surface here.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, depends);
+  }, deps);
 
   return { options: resolved, loading };
 }
 
-
-
 interface ITFieldRendererProps {
+  /** The V2 field definition driving the render. */
   config: FieldConfigV2;
+  /** Grid column count used for `column` spans and nested `section` grids. */
   columns?: number;
+  /** Current value of this field (controlled). */
   value?: any;
+  /** Validation error message for this field. */
   error?: string;
+  /** Whether this field has been touched. */
   touched?: boolean;
+  /**
+   * Pre-filtered `values` slice containing only the keys listed in
+   * `config.dependsOn`. Computed by {@link ITFormBuilder}.
+   */
   dependentValues?: Record<string, any>;
 }
 
+/**
+ * Renders a single V2 {@link FieldConfigV2}. Mounts/unmounts the field in the
+ * shared registry, evaluates `renderWhen` / `dynamicProps` via
+ * {@link useFieldRules}, and dispatches to the correct input component for the
+ * field's `type`.
+ *
+ * Field kinds supported by `type`:
+ * - `"text" | "password" | "number" | "email"` -> `<ITInput>`
+ * - `"select"` (sync options) -> `<ITSelect>`
+ * - `"select"` (async options) -> `<ITSearchSelect>` with a spinner fallback
+ * - `"date"` -> `<ITDatePicker>`
+ * - `"time"` -> `<ITTimePicker>`
+ * - `"custom"` -> the `config.component` renderer
+ * - `"section"` -> nested grid of `config.fields`
+ * - `"array"` -> placeholder (reserved for future dynamic lists)
+ *
+ * Memoised with `React.memo`; equality is shallow on props so passing fresh
+ * `value`/`error`/`touched` per render is expected.
+ */
 const ITFieldRenderer = ({
   config,
   columns = 12,
@@ -66,7 +133,8 @@ const ITFieldRenderer = ({
     return () => {
       context.unregisterField(config.name);
     };
-    // `config`/`context` son estables en el provider; solo el name define el registro.
+    // `config`/`context` are stable in the provider; only `name` defines the
+    // registration key.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [config.name]);
 
@@ -94,17 +162,20 @@ const ITFieldRenderer = ({
     rightIcon,
   } = activeConfig;
 
-  const { options: resolvedOptions, loading: optionsLoading } = useAsyncOptions(options, [options, dependentValues]);
+  const { options: resolvedOptions, loading: optionsLoading } = useAsyncOptions(
+    options,
+    [options, dependentValues],
+  );
 
   const handleChangeWrapper = useCallback(
     async (val: any) => {
-      const finalValue = val?.target ? val.target.value : val;
+      const finalValue = val && typeof val === "object" && "target" in val ? val.target.value : val;
       await context.setFieldValue(name, finalValue);
       if (activeConfig.onChangeAction) {
         await activeConfig.onChangeAction(finalValue, context);
       }
     },
-    [name, context, activeConfig]
+    [name, context, activeConfig],
   );
 
   if (!isVisible) return null;
@@ -140,15 +211,20 @@ const ITFieldRenderer = ({
         );
 
       case "select":
-        if (optionsLoading) {
-          return (
-            <div className="flex items-center gap-2 py-3">
-              <FaSpinner className="animate-spin text-primary-500" />
-              <ITText as="span" className="text-sm text-slate-500">Cargando opciones...</ITText>
-            </div>
-          );
-        }
         if (typeof options === "function") {
+          if (optionsLoading) {
+            return (
+              <div
+                className="flex items-center gap-2 py-3"
+                data-testid={`field-loading-${name}`}
+              >
+                <FaSpinner className="animate-spin text-primary-500" />
+                <ITText as="span" className="text-sm text-slate-500">
+                  Cargando opciones...
+                </ITText>
+              </div>
+            );
+          }
           return (
             <ITSearchSelect
               options={resolvedOptions}
@@ -159,7 +235,7 @@ const ITFieldRenderer = ({
               value={value !== undefined ? value : activeConfig.defaultValue || ""}
               valueField={valueField || "value"}
               labelField={labelField || "label"}
-              onChange={(val: any) => handleChangeWrapper(val)}
+              onChange={handleChangeWrapper}
               onBlur={context.handleBlur}
               touched={touched}
               error={error}
@@ -220,9 +296,28 @@ const ITFieldRenderer = ({
       case "custom":
         if (activeConfig.component) {
           const CustomComponent = activeConfig.component;
+          // Strip the builder-only keys before forwarding so the custom
+          // component receives a clean prop bag (no leaks of `component`,
+          // `fields`, `dynamicProps`, `renderWhen`, etc.).
+          const customProps: Record<string, unknown> = { ...activeConfig };
+          const BUILDER_ONLY_KEYS = [
+            "component",
+            "type",
+            "fields",
+            "renderWhen",
+            "dynamicProps",
+            "dependsOn",
+            "validation",
+            "asyncValidation",
+            "options",
+            "defaultValue",
+            "className",
+          ];
+          for (const key of BUILDER_ONLY_KEYS) delete customProps[key];
           return (
             <CustomComponent
-              {...activeConfig}
+              {...(customProps as any)}
+              name={name}
               value={value}
               onChange={handleChangeWrapper}
               onBlur={context.handleBlur}
@@ -232,17 +327,30 @@ const ITFieldRenderer = ({
             />
           );
         }
+        if (typeof console !== "undefined" && process.env.NODE_ENV !== "production") {
+          console.warn(
+            `[ITFormBuilder] Field "${name}" has type "custom" but no \`component\` was provided.`,
+          );
+        }
         return null;
 
       case "section":
         return (
           <div className={clsx("w-full col-span-full", activeConfig.className)}>
             {label && (
-              <ITText as="h4" className="text-lg font-semibold text-secondary-800 mb-4">
+              <ITText
+                as="h4"
+                className="text-lg font-semibold text-secondary-800 mb-4"
+              >
                 {label}
               </ITText>
             )}
-            <div className={clsx("grid gap-y-6 gap-x-5", getGridColsClass(columns as any))}>
+            <div
+              className={clsx(
+                "grid gap-y-6 gap-x-5",
+                getGridColsClass(columns as any),
+              )}
+            >
               {activeConfig.fields?.map((childConfig) => (
                 <ITFieldRenderer
                   key={childConfig.name}
@@ -264,12 +372,21 @@ const ITFieldRenderer = ({
         );
 
       default:
+        if (typeof console !== "undefined" && process.env.NODE_ENV !== "production") {
+          console.warn(
+            `[ITFormBuilder] Unknown V2 field type "${type}" for field "${name}". ` +
+              `Supported: text, number, password, email, select, date, time, custom, section, array.`,
+          );
+        }
         return null;
     }
   };
 
   return (
-    <div className={clsx(getColSpanClass(activeConfig.column, columns), activeConfig.className)}>
+    <div
+      className={clsx(getColSpanClass(activeConfig.column, columns), activeConfig.className)}
+      data-field-name={name}
+    >
       {renderField()}
     </div>
   );

package/src/components/organisms/form-builder/formBuilder.context.tsx

@@ -1,30 +1,79 @@
 import React, { createContext, useContext, useState } from 'react';
 import { FieldConfigV2, FieldContextV2 } from '@/types/field.types';
 
-interface ITFormBuilderContextType extends FieldContextV2 {
+/**
+ * Internal context shared between {@link ITFormBuilder} and any descendant
+ * (e.g. a custom submit button, a sidebar showing form progress). The shape
+ * extends the public {@link FieldContextV2} with bookkeeping for the V2
+ * architecture: a per-field config registry plus lifecycle flags mirroring
+ * Formik.
+ */
+export interface ITFormBuilderContextType extends FieldContextV2 {
+  /** The full V2 config array passed to `<ITFormBuilder config={...} />`. */
   config: FieldConfigV2[];
+  /** True while a Formik `submitForm` is in flight. */
   isSubmitting: boolean;
+  /** True while async validation is running for any field. */
   isValidating: boolean;
+  /** Number of times the parent form has been submitted. */
   submitCount: number;
+  /** Values present at `initialValues` time (reserved for future resets). */
   initialValues: Record<string, any>;
+  /** Validation errors keyed by field `name`. */
   errors: Record<string, string>;
+  /** Touch state keyed by field `name`. */
   touched: Record<string, boolean>;
-  handleBlur: (e: any) => void;
+  /** Generic change handler (Formik-style `(e) => void`). */
   handleChange: (e: any) => void;
+  /** Generic blur handler (Formik-style `(e) => void`). */
+  handleBlur: (e: any) => void;
+  /**
+   * Registers a field's config in the live registry. Called automatically by
+   * every `ITFieldRenderer` on mount; use `getFieldConfig` to read it back.
+   */
   registerField: (name: string, config: FieldConfigV2) => void;
+  /** Removes a field from the registry. Called on unmount. */
   unregisterField: (name: string) => void;
+  /** Returns the registered config for a given field name, or `undefined`. */
   getFieldConfig: (name: string) => FieldConfigV2 | undefined;
+  /** Returns the full list of registered field configs (snapshot). */
+  getAllFieldConfigs: () => FieldConfigV2[];
 }
 
 const ITFormBuilderContext = createContext<ITFormBuilderContextType | undefined>(undefined);
 
+export interface ITFormBuilderProviderProps {
+  /** The children rendered inside the provider (typically the grid of fields). */
+  children: React.ReactNode;
+  /**
+   * Pre-built value object containing everything except the per-field registry
+   * helpers (`registerField` / `unregisterField` / `getFieldConfig` /
+   * `getAllFieldConfigs`), which the provider injects itself.
+   */
+  value: Omit<
+    ITFormBuilderContextType,
+    'registerField' | 'unregisterField' | 'getFieldConfig' | 'getAllFieldConfigs'
+  >;
+}
+
+/**
+ * Wraps the V2 grid of fields with the shared context. You normally don't need
+ * to mount this manually — {@link ITFormBuilder} does it for you when the V2
+ * `config` prop is supplied. Mounting it yourself is useful for advanced
+ * compositions (e.g. embedding an `<ITFormBuilder />` inside another component
+ * that needs to read `useFormBuilder`).
+ *
+ * @example
+ * ```tsx
+ * <ITFormBuilderProvider value={{ values, errors, touched, ... }}>
+ *   <MyGrid />
+ * </ITFormBuilderProvider>
+ * ```
+ */
 export const ITFormBuilderProvider = ({
   children,
   value,
-}: {
-  children: React.ReactNode;
-  value: Omit<ITFormBuilderContextType, 'registerField' | 'unregisterField' | 'getFieldConfig'>;
-}) => {
+}: ITFormBuilderProviderProps) => {
   const [fieldRegistry, setFieldRegistry] = useState<Record<string, FieldConfigV2>>({});
 
   const registerField = React.useCallback((name: string, config: FieldConfigV2) => {
@@ -33,15 +82,21 @@ export const ITFormBuilderProvider = ({
 
   const unregisterField = React.useCallback((name: string) => {
     setFieldRegistry((prev) => {
-      const newRegistry = { ...prev };
-      delete newRegistry[name];
-      return newRegistry;
+      const next = { ...prev };
+      delete next[name];
+      return next;
     });
   }, []);
 
-  const getFieldConfig = React.useCallback((name: string) => {
-    return fieldRegistry[name];
-  }, [fieldRegistry]);
+  const getFieldConfig = React.useCallback(
+    (name: string) => fieldRegistry[name],
+    [fieldRegistry]
+  );
+
+  const getAllFieldConfigs = React.useCallback(
+    () => Object.values(fieldRegistry),
+    [fieldRegistry]
+  );
 
   const contextValue = React.useMemo(
     () => ({
@@ -49,8 +104,9 @@ export const ITFormBuilderProvider = ({
       registerField,
       unregisterField,
       getFieldConfig,
+      getAllFieldConfigs,
     }),
-    [value, registerField, unregisterField, getFieldConfig]
+    [value, registerField, unregisterField, getFieldConfig, getAllFieldConfigs]
   );
 
   return (
@@ -60,7 +116,13 @@ export const ITFormBuilderProvider = ({
   );
 };
 
-// Hook de acceso al contexto — patrón requerido junto al provider en el mismo archivo.
+/**
+ * Reads the live form context. Throws when called outside an
+ * `ITFormBuilderProvider` so misuse fails loudly in development.
+ *
+ * Prefer the higher-level {@link useFormBuilder} hook for typical use cases
+ * (progress, dirty state); this hook returns the un-augmented context shape.
+ */
 // eslint-disable-next-line react-refresh/only-export-components
 export const useITFormBuilderContext = () => {
   const context = useContext(ITFormBuilderContext);
@@ -68,4 +130,4 @@ export const useITFormBuilderContext = () => {
     throw new Error('useITFormBuilderContext must be used within an ITFormBuilderProvider');
   }
   return context;
-};
+};