@ic-reactor/candid 3.0.11-beta.2 → 3.0.12-beta.0

package/src/visitor/arguments/index.ts

@@ -1,24 +1,27 @@
 import { isQuery } from "../helpers"
-import { IDL } from "../types"
 import type {
-  ArgumentField,
-  RecordArgumentField,
-  VariantArgumentField,
-  TupleArgumentField,
-  OptionalArgumentField,
-  VectorArgumentField,
-  BlobArgumentField,
-  RecursiveArgumentField,
-  PrincipalArgumentField,
-  NumberArgumentField,
-  BooleanArgumentField,
-  NullArgumentField,
-  TextArgumentField,
-  UnknownArgumentField,
-  MethodArgumentsMeta,
-  ServiceArgumentsMeta,
+  Field,
+  RecordField,
+  VariantField,
+  TupleField,
+  OptionalField,
+  VectorField,
+  BlobField,
+  RecursiveField,
+  PrincipalField,
+  NumberField,
+  BooleanField,
+  NullField,
+  TextField,
+  UnknownField,
+  ArgumentsMeta,
+  ArgumentsServiceMeta,
 } from "./types"
+
+import { IDL } from "@icp-sdk/core/candid"
+import { Principal } from "@icp-sdk/core/principal"
 import { BaseActor, FunctionName } from "@ic-reactor/core"
+import * as z from "zod"
 
 export * from "./types"
 
@@ -31,66 +34,87 @@ export * from "./types"
  * 2. **No value dependencies** - metadata is independent of actual values
  * 3. **Form-framework agnostic** - output can be used with TanStack, React Hook Form, etc.
  * 4. **Efficient** - single traversal, no runtime type checking
+ * 5. **TanStack Form optimized** - name paths compatible with TanStack Form patterns
  *
  * ## Output Structure
  *
  * Each field has:
  * - `type`: The field type (record, variant, text, number, etc.)
  * - `label`: Human-readable label from Candid
- * - `path`: Dot-notation path for form binding (e.g., "0.owner")
+ * - `name`: TanStack Form compatible path (e.g., "[0]", "[0].owner", "tags[1]")
  * - `defaultValue`: Initial value for the form
+ * - `schema`: Zod schema for validation
  * - Type-specific properties (options for variant, fields for record, etc.)
+ * - Helper methods for dynamic forms (getOptionDefault, getItemDefault, etc.)
+ *
+ * ## Usage with TanStack Form
  *
  * @example
  * ```typescript
+ * import { useForm } from '@tanstack/react-form'
+ * import { ArgumentFieldVisitor } from '@ic-reactor/candid'
+ *
  * const visitor = new ArgumentFieldVisitor()
  * const serviceMeta = service.accept(visitor, null)
- *
- * // For a specific method
  * const methodMeta = serviceMeta["icrc1_transfer"]
- * // methodMeta.fields = [{ type: "record", fields: [...] }]
- * // methodMeta.defaultValues = [{ to: "", amount: "" }]
+ *
+ * const form = useForm({
+ *   defaultValues: methodMeta.defaultValue,
+ *   validators: { onBlur: methodMeta.schema },
+ *   onSubmit: async ({ value }) => {
+ *     await actor.icrc1_transfer(...value)
+ *   }
+ * })
+ *
+ * // Render fields dynamically
+ * methodMeta.fields.map((field, index) => (
+ *   <form.Field key={index} name={field.name}>
+ *     {(fieldApi) => <DynamicInput field={field} fieldApi={fieldApi} />}
+ *   </form.Field>
+ * ))
  * ```
  */
 export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
   string,
-  ArgumentField | MethodArgumentsMeta<A> | ServiceArgumentsMeta<A>
+  Field | ArgumentsMeta<A> | ArgumentsServiceMeta<A>
 > {
-  private pathStack: string[] = []
+  public recursiveSchemas: Map<string, z.ZodTypeAny> = new Map()
 
-  private withPath<T>(path: string, fn: () => T): T {
-    this.pathStack.push(path)
+  private nameStack: string[] = []
+
+  /**
+   * Execute function with a name segment pushed onto the stack.
+   * Automatically manages stack cleanup.
+   */
+  private withName<T>(name: string, fn: () => T): T {
+    this.nameStack.push(name)
     try {
       return fn()
     } finally {
-      this.pathStack.pop()
+      this.nameStack.pop()
     }
   }
 
-  private currentPath(): string {
-    return this.pathStack[this.pathStack.length - 1] ?? ""
-  }
-
-  private childPath(key: string | number): string {
-    const parent = this.currentPath()
-    if (typeof key === "number") {
-      return parent ? `${parent}[${key}]` : String(key)
-    }
-    return parent ? `${parent}.${key}` : key
+  /**
+   * Get the current full name path for form binding.
+   * Returns empty string for root level.
+   */
+  private currentName(): string {
+    return this.nameStack.join("")
   }
 
   // ════════════════════════════════════════════════════════════════════════
   // Service & Function Level
   // ════════════════════════════════════════════════════════════════════════
 
-  public visitService(t: IDL.ServiceClass): ServiceArgumentsMeta<A> {
-    const result = {} as ServiceArgumentsMeta<A>
+  public visitService(t: IDL.ServiceClass): ArgumentsServiceMeta<A> {
+    const result = {} as ArgumentsServiceMeta<A>
 
     for (const [functionName, func] of t._fields) {
       result[functionName as FunctionName<A>] = func.accept(
         this,
         functionName
-      ) as MethodArgumentsMeta<A>
+      ) as ArgumentsMeta<A>
     }
 
     return result
@@ -99,35 +123,44 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
   public visitFunc(
     t: IDL.FuncClass,
     functionName: FunctionName<A>
-  ): MethodArgumentsMeta<A> {
+  ): ArgumentsMeta<A> {
     const functionType = isQuery(t) ? "query" : "update"
+    const argCount = t.argTypes.length
 
     const fields = t.argTypes.map((arg, index) => {
-      return this.withPath(`[${index}]`, () =>
+      return this.withName(`[${index}]`, () =>
         arg.accept(this, `__arg${index}`)
-      ) as ArgumentField
+      ) as Field
     })
 
-    const defaultValues = fields.map((field) => this.extractDefaultValue(field))
+    const defaultValues = fields.map((field) => field.defaultValue)
+
+    // Handle empty args case for schema
+    // For no-arg functions, use an empty array schema
+    // For functions with args, use a proper tuple schema
+    const schema =
+      argCount === 0
+        ? (z.tuple([]) as unknown as z.ZodTuple<
+            [z.ZodTypeAny, ...z.ZodTypeAny[]]
+          >)
+        : z.tuple(
+            fields.map((field) => field.schema) as [
+              z.ZodTypeAny,
+              ...z.ZodTypeAny[],
+            ]
+          )
 
     return {
       functionType,
       functionName,
       fields,
-      defaultValues,
+      defaultValues: defaultValues,
+      schema,
+      argCount,
+      isNoArgs: argCount === 0,
     }
   }
 
-  private extractDefaultValue(field: ArgumentField): unknown {
-    if ("defaultValue" in field) {
-      return field.defaultValue
-    }
-    if ("defaultValues" in field) {
-      return field.defaultValues
-    }
-    return undefined
-  }
-
   // ════════════════════════════════════════════════════════════════════════
   // Compound Types
   // ════════════════════════════════════════════════════════════════════════
@@ -136,26 +169,35 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     _t: IDL.RecordClass,
     fields_: Array<[string, IDL.Type]>,
     label: string
-  ): RecordArgumentField {
-    const path = this.currentPath()
-    const fields: ArgumentField[] = []
-    const defaultValues: Record<string, unknown> = {}
+  ): RecordField {
+    const name = this.currentName()
+    const fields: Field[] = []
+    const fieldMap = new Map<string, Field>()
+    const defaultValue: Record<string, unknown> = {}
+    const schemaShape: Record<string, z.ZodTypeAny> = {}
 
     for (const [key, type] of fields_) {
-      const field = this.withPath(this.childPath(key), () =>
+      const field = this.withName(name ? `.${key}` : key, () =>
         type.accept(this, key)
-      ) as ArgumentField
+      ) as Field
 
       fields.push(field)
-      defaultValues[key] = this.extractDefaultValue(field)
+      fieldMap.set(key, field)
+      defaultValue[key] = field.defaultValue
+      schemaShape[key] = field.schema
     }
 
+    const schema = z.object(schemaShape)
+
     return {
       type: "record",
       label,
-      path,
+      name,
       fields,
-      defaultValues,
+      fieldMap,
+      defaultValue,
+      schema,
+      candidType: "record",
     }
   }
 
@@ -163,33 +205,53 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     _t: IDL.VariantClass,
     fields_: Array<[string, IDL.Type]>,
     label: string
-  ): VariantArgumentField {
-    const path = this.currentPath()
-    const fields: ArgumentField[] = []
+  ): VariantField {
+    const name = this.currentName()
+    const fields: Field[] = []
     const options: string[] = []
+    const optionMap = new Map<string, Field>()
+    const variantSchemas: z.ZodTypeAny[] = []
 
     for (const [key, type] of fields_) {
-      const field = this.withPath(this.childPath(key), () =>
+      const field = this.withName(`.${key}`, () =>
         type.accept(this, key)
-      ) as ArgumentField
+      ) as Field
 
       fields.push(field)
       options.push(key)
+      optionMap.set(key, field)
+      variantSchemas.push(z.object({ [key]: field.schema }))
     }
 
     const defaultOption = options[0]
-    const defaultValues = {
-      [defaultOption]: this.extractDefaultValue(fields[0]),
+    const firstField = fields[0]
+    const defaultValue = {
+      [defaultOption]: firstField.defaultValue,
+    }
+
+    const schema = z.union(variantSchemas as [z.ZodTypeAny, ...z.ZodTypeAny[]])
+
+    // Helper to get default value for any option
+    const getOptionDefault = (option: string): Record<string, unknown> => {
+      const optField = optionMap.get(option)
+      if (!optField) {
+        throw new Error(`Unknown variant option: ${option}`)
+      }
+      return { [option]: optField.defaultValue }
     }
 
     return {
       type: "variant",
       label,
-      path,
+      name,
       fields,
       options,
       defaultOption,
-      defaultValues,
+      optionMap,
+      defaultValue,
+      schema,
+      getOptionDefault,
+      candidType: "variant",
     }
   }
 
@@ -197,27 +259,33 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     _t: IDL.TupleClass<T>,
     components: IDL.Type[],
     label: string
-  ): TupleArgumentField {
-    const path = this.currentPath()
-    const fields: ArgumentField[] = []
-    const defaultValues: unknown[] = []
+  ): TupleField {
+    const name = this.currentName()
+    const fields: Field[] = []
+    const defaultValue: unknown[] = []
+    const schemas: z.ZodTypeAny[] = []
 
     for (let index = 0; index < components.length; index++) {
       const type = components[index]
-      const field = this.withPath(this.childPath(index), () =>
+      const field = this.withName(`[${index}]`, () =>
         type.accept(this, `_${index}_`)
-      ) as ArgumentField
+      ) as Field
 
       fields.push(field)
-      defaultValues.push(this.extractDefaultValue(field))
+      defaultValue.push(field.defaultValue)
+      schemas.push(field.schema)
     }
 
+    const schema = z.tuple(schemas as [z.ZodTypeAny, ...z.ZodTypeAny[]])
+
     return {
       type: "tuple",
       label,
-      path,
+      name,
       fields,
-      defaultValues,
+      defaultValue,
+      schema,
+      candidType: "tuple",
     }
   }
 
@@ -225,19 +293,32 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     _t: IDL.OptClass<T>,
     ty: IDL.Type<T>,
     label: string
-  ): OptionalArgumentField {
-    const path = this.currentPath()
+  ): OptionalField {
+    const name = this.currentName()
+
+    // For optional, the inner field keeps the same name path
+    // because the value replaces null directly (not nested)
+    const innerField = ty.accept(this, label) as Field
+
+    const schema = z.union([
+      innerField.schema,
+      z.null(),
+      z.undefined().transform(() => null),
+      z.literal("").transform(() => null),
+    ])
 
-    const innerField = this.withPath(this.childPath(0), () =>
-      ty.accept(this, label)
-    ) as ArgumentField
+    // Helper to get the inner default when enabling the optional
+    const getInnerDefault = (): unknown => innerField.defaultValue
 
     return {
       type: "optional",
       label,
-      path,
+      name,
       innerField,
       defaultValue: null,
+      schema,
+      getInnerDefault,
+      candidType: "opt",
     }
   }
 
@@ -245,32 +326,49 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     _t: IDL.VecClass<T>,
     ty: IDL.Type<T>,
     label: string
-  ): VectorArgumentField | BlobArgumentField {
-    const path = this.currentPath()
+  ): VectorField | BlobField {
+    const name = this.currentName()
 
     // Check if it's blob (vec nat8)
     const isBlob = ty instanceof IDL.FixedNatClass && ty._bits === 8
 
-    const itemField = this.withPath(this.childPath(0), () =>
-      ty.accept(this, label)
-    ) as ArgumentField
+    // Item field uses [0] as template path
+    const itemField = this.withName("[0]", () =>
+      ty.accept(this, `${label}_item`)
+    ) as Field
 
     if (isBlob) {
+      const schema = z.union([
+        z.string(),
+        z.array(z.number()),
+        z.instanceof(Uint8Array),
+      ])
       return {
         type: "blob",
         label,
-        path,
+        name,
         itemField,
         defaultValue: "",
+        schema,
+        acceptedFormats: ["hex", "base64", "file"],
+        candidType: "blob",
       }
     }
 
+    const schema = z.array(itemField.schema)
+
+    // Helper to get a new item with default values
+    const getItemDefault = (): unknown => itemField.defaultValue
+
     return {
       type: "vector",
       label,
-      path,
+      name,
       itemField,
       defaultValue: [],
+      schema,
+      getItemDefault,
+      candidType: "vec",
     }
   }
 
@@ -278,16 +376,36 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     _t: IDL.RecClass<T>,
     ty: IDL.ConstructType<T>,
     label: string
-  ): RecursiveArgumentField {
-    const path = this.currentPath()
+  ): RecursiveField {
+    const name = this.currentName()
+    const typeName = ty.name || "RecursiveType"
+
+    let schema: z.ZodTypeAny
+
+    if (this.recursiveSchemas.has(typeName)) {
+      schema = this.recursiveSchemas.get(typeName)!
+    } else {
+      schema = z.lazy(() => (ty.accept(this, label) as Field).schema)
+      this.recursiveSchemas.set(typeName, schema)
+    }
+
+    // Lazy extraction to prevent infinite loops
+    const extract = (): Field =>
+      this.withName(name, () => ty.accept(this, label)) as Field
+
+    // Helper to get inner default (evaluates lazily)
+    const getInnerDefault = (): unknown => extract().defaultValue
 
     return {
       type: "recursive",
       label,
-      path,
-      // Lazy extraction to prevent infinite loops
-      extract: () =>
-        this.withPath(path, () => ty.accept(this, label)) as ArgumentField,
+      name,
+      typeName,
+      extract,
+      defaultValue: undefined,
+      schema,
+      getInnerDefault,
+      candidType: "rec",
     }
   }
 
@@ -295,111 +413,198 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
   // Primitive Types
   // ════════════════════════════════════════════════════════════════════════
 
-  public visitPrincipal(
-    _t: IDL.PrincipalClass,
-    label: string
-  ): PrincipalArgumentField {
+  public visitPrincipal(_t: IDL.PrincipalClass, label: string): PrincipalField {
+    const schema = z.custom<Principal>(
+      (val) => {
+        if (val instanceof Principal) return true
+        if (typeof val === "string") {
+          try {
+            Principal.fromText(val)
+            return true
+          } catch {
+            return false
+          }
+        }
+        return false
+      },
+      {
+        message: "Invalid Principal format",
+      }
+    )
+
     return {
       type: "principal",
       label,
-      path: this.currentPath(),
+      name: this.currentName(),
       defaultValue: "",
       maxLength: 64,
       minLength: 7,
+      schema,
+      candidType: "principal",
+      ui: {
+        placeholder: "aaaaa-aa or full principal ID",
+      },
     }
   }
 
-  public visitText(_t: IDL.TextClass, label: string): TextArgumentField {
+  public visitText(_t: IDL.TextClass, label: string): TextField {
     return {
       type: "text",
       label,
-      path: this.currentPath(),
+      name: this.currentName(),
       defaultValue: "",
+      schema: z.string().min(1, "Required"),
+      candidType: "text",
+      ui: {
+        placeholder: "Enter text...",
+      },
     }
   }
 
-  public visitBool(_t: IDL.BoolClass, label: string): BooleanArgumentField {
+  public visitBool(_t: IDL.BoolClass, label: string): BooleanField {
     return {
       type: "boolean",
       label,
-      path: this.currentPath(),
+      name: this.currentName(),
       defaultValue: false,
+      schema: z.boolean(),
+      candidType: "bool",
     }
   }
 
-  public visitNull(_t: IDL.NullClass, label: string): NullArgumentField {
+  public visitNull(_t: IDL.NullClass, label: string): NullField {
     return {
       type: "null",
       label,
-      path: this.currentPath(),
+      name: this.currentName(),
       defaultValue: null,
+      schema: z.null(),
+      candidType: "null",
     }
   }
 
-  // Numbers - all use string for display format
+  // ════════════════════════════════════════════════════════════════════════
+  // Number Types with Constraints
+  // ════════════════════════════════════════════════════════════════════════
+
   private visitNumberType(
     label: string,
-    candidType: string
-  ): NumberArgumentField {
+    candidType: string,
+    options: {
+      unsigned: boolean
+      isFloat: boolean
+      bits?: number
+      min?: string
+      max?: string
+    }
+  ): NumberField | TextField {
+    let schema = z.string().min(1, "Required")
+
+    if (options.isFloat) {
+      schema = schema.refine((val) => !isNaN(Number(val)), "Must be a number")
+    } else if (options.unsigned) {
+      schema = schema.regex(/^\d+$/, "Must be a positive number")
+    } else {
+      schema = schema.regex(/^-?\d+$/, "Must be a number")
+    }
+
+    // Use "text" type for large numbers (BigInt) to ensure precision and better UI handling
+    // Standard number input has issues with large integers
+    const isBigInt = !options.isFloat && (!options.bits || options.bits > 32)
+    const type = isBigInt ? "text" : "number"
+
+    if (type === "text") {
+      return {
+        type: "text",
+        label,
+        name: this.currentName(),
+        defaultValue: "",
+        candidType,
+        schema,
+        ui: {
+          placeholder: options.unsigned ? "e.g. 100000" : "e.g. -100000",
+        },
+      }
+    }
+
     return {
       type: "number",
       label,
-      path: this.currentPath(),
+      name: this.currentName(),
       defaultValue: "",
       candidType,
+      schema: schema,
+      ...options,
+      ui: {
+        placeholder: options.isFloat ? "0.0" : "0",
+      },
     }
   }
 
-  public visitInt(_t: IDL.IntClass, label: string): NumberArgumentField {
-    return this.visitNumberType(label, "int")
+  public visitInt(_t: IDL.IntClass, label: string): NumberField | TextField {
+    return this.visitNumberType(label, "int", {
+      unsigned: false,
+      isFloat: false,
+    })
   }
 
-  public visitNat(_t: IDL.NatClass, label: string): NumberArgumentField {
-    return this.visitNumberType(label, "nat")
+  public visitNat(_t: IDL.NatClass, label: string): NumberField | TextField {
+    return this.visitNumberType(label, "nat", {
+      unsigned: true,
+      isFloat: false,
+    })
   }
 
-  public visitFloat(_t: IDL.FloatClass, label: string): NumberArgumentField {
-    return this.visitNumberType(label, "float")
+  public visitFloat(t: IDL.FloatClass, label: string): NumberField {
+    return this.visitNumberType(label, `float${t._bits}`, {
+      unsigned: false,
+      isFloat: true,
+      bits: t._bits,
+    }) as NumberField
   }
 
   public visitFixedInt(
     t: IDL.FixedIntClass,
     label: string
-  ): NumberArgumentField {
-    return this.visitNumberType(label, `int${t._bits}`)
+  ): NumberField | TextField {
+    const bits = t._bits
+    // Calculate min/max for signed integers
+    const max = (BigInt(2) ** BigInt(bits - 1) - BigInt(1)).toString()
+    const min = (-(BigInt(2) ** BigInt(bits - 1))).toString()
+
+    return this.visitNumberType(label, `int${bits}`, {
+      unsigned: false,
+      isFloat: false,
+      bits,
+      min,
+      max,
+    })
   }
 
   public visitFixedNat(
     t: IDL.FixedNatClass,
     label: string
-  ): NumberArgumentField {
-    return this.visitNumberType(label, `nat${t._bits}`)
+  ): NumberField | TextField {
+    const bits = t._bits
+    // Calculate max for unsigned integers
+    const max = (BigInt(2) ** BigInt(bits) - BigInt(1)).toString()
+
+    return this.visitNumberType(label, `nat${bits}`, {
+      unsigned: true,
+      isFloat: false,
+      bits,
+      min: "0",
+      max,
+    })
   }
 
-  public visitType<T>(_t: IDL.Type<T>, label: string): UnknownArgumentField {
+  public visitType<T>(_t: IDL.Type<T>, label: string): UnknownField {
     return {
       type: "unknown",
       label,
-      path: this.currentPath(),
+      name: this.currentName(),
       defaultValue: undefined,
+      schema: z.any(),
     }
   }
 }
-
-// ════════════════════════════════════════════════════════════════════════════
-// Legacy Exports (for backward compatibility)
-// ════════════════════════════════════════════════════════════════════════════
-
-/**
- * @deprecated Use ArgumentFieldVisitor instead
- */
-export { ArgumentFieldVisitor as VisitTanstackField }
-
-/**
- * @deprecated Use ArgumentField instead
- */
-export type {
-  ArgumentField as TanstackAllArgTypes,
-  MethodArgumentsMeta as TanstackMethodField,
-  ServiceArgumentsMeta as TanstackServiceField,
-}