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

package/src/visitor/arguments/schema.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect } from "vitest"
+import { IDL } from "@icp-sdk/core/candid"
+import { Principal } from "@icp-sdk/core/principal"
+import { ArgumentFieldVisitor } from "./index"
+import * as z from "zod"
+
+describe("ArgumentFieldVisitor Schema Generation", () => {
+  const visitor = new ArgumentFieldVisitor()
+
+  // ════════════════════════════════════════════════════════════════════════
+  // Primitive Types
+  // ════════════════════════════════════════════════════════════════════════
+
+  describe("Primitive Types", () => {
+    it("should generate string schema for text", () => {
+      const field = visitor.visitText(IDL.Text, "username")
+      const schema = field.schema
+
+      expect(schema).toBeDefined()
+      expect(schema.parse("hello")).toBe("hello")
+      expect(() => schema.parse(123)).toThrow()
+    })
+
+    it("should generate boolean schema for bool", () => {
+      const field = visitor.visitBool(IDL.Bool, "isActive")
+      const schema = field.schema
+
+      expect(schema.parse(true)).toBe(true)
+      expect(schema.parse(false)).toBe(false)
+      expect(() => schema.parse("true")).toThrow()
+    })
+
+    it("should generate null schema for null", () => {
+      const field = visitor.visitNull(IDL.Null, "void")
+      const schema = field.schema
+
+      expect(schema.parse(null)).toBe(null)
+      expect(() => schema.parse(undefined)).toThrow()
+    })
+
+    it("should generate string schema for numbers (form input matching)", () => {
+      // The visitor currently generates string schemas for numbers to match form inputs
+      const natField = visitor.visitNat(IDL.Nat, "amount")
+      expect(natField.schema.parse("100")).toBe("100")
+
+      const intField = visitor.visitInt(IDL.Int, "balance")
+      expect(intField.schema.parse("-50")).toBe("-50")
+    })
+
+    it("should generate principal schema", () => {
+      const field = visitor.visitPrincipal(IDL.Principal, "owner")
+      const schema = field.schema
+
+      const p = Principal.fromText("2vxsx-fae")
+      // Should accept Principal instance
+      expect(schema.parse(p)).toEqual(p)
+      // Should accept valid string representation
+      expect(schema.parse("2vxsx-fae")).toBe("2vxsx-fae")
+
+      // Should reject invalid
+      expect(() => schema.parse("invalid-principal")).toThrow()
+    })
+  })
+
+  // ════════════════════════════════════════════════════════════════════════
+  // Compound Types
+  // ════════════════════════════════════════════════════════════════════════
+
+  describe("Record Types", () => {
+    it("should generate object schema for record", () => {
+      const recordType = IDL.Record({
+        name: IDL.Text,
+        age: IDL.Nat,
+      })
+      const field = visitor.visitRecord(
+        recordType,
+        [
+          ["name", IDL.Text],
+          ["age", IDL.Nat],
+        ],
+        "person"
+      )
+      const schema = field.schema as z.ZodObject<any>
+
+      const validData = { name: "John", age: "30" }
+      expect(schema.parse(validData)).toEqual(validData)
+
+      expect(() => schema.parse({ name: "John" })).toThrow() // missing age
+      expect(() => schema.parse({ name: 123, age: "30" })).toThrow() // invalid type
+    })
+  })
+
+  describe("Variant Types", () => {
+    it("should generate union schema for variant", () => {
+      const variantType = IDL.Variant({
+        Ok: IDL.Text,
+        Err: IDL.Text,
+      })
+      const field = visitor.visitVariant(
+        variantType,
+        [
+          ["Ok", IDL.Text],
+          ["Err", IDL.Text],
+        ],
+        "result"
+      )
+      const schema = field.schema as z.ZodUnion<any>
+
+      expect(schema.parse({ Ok: "Success" })).toEqual({ Ok: "Success" })
+      expect(schema.parse({ Err: "Error" })).toEqual({ Err: "Error" })
+
+      expect(() => schema.parse({ Other: "value" })).toThrow()
+    })
+  })
+
+  describe("Tuple Types", () => {
+    it("should generate tuple schema", () => {
+      const tupleType = IDL.Tuple(IDL.Text, IDL.Nat)
+      const field = visitor.visitTuple(tupleType, [IDL.Text, IDL.Nat], "pair")
+      const schema = field.schema as z.ZodTuple<any>
+
+      expect(schema.parse(["key", "100"])).toEqual(["key", "100"])
+      expect(() => schema.parse(["key"])).toThrow()
+    })
+  })
+
+  describe("Optional Types", () => {
+    it("should generate nullable/optional schema", () => {
+      const optType = IDL.Opt(IDL.Text)
+      const field = visitor.visitOpt(optType, IDL.Text, "maybe")
+      const schema = field.schema
+
+      expect(schema.parse("value")).toBe("value")
+      expect(schema.parse(null)).toBe(null)
+      expect(schema.parse(undefined)).toBe(null) // nullish() allows undefined -> null
+    })
+  })
+
+  describe("Vector Types", () => {
+    it("should generate array schema", () => {
+      const vecType = IDL.Vec(IDL.Text)
+      const field = visitor.visitVec(vecType, IDL.Text, "tags")
+      const schema = field.schema
+
+      expect(schema.parse(["a", "b"])).toEqual(["a", "b"])
+      expect(schema.parse([])).toEqual([])
+      expect(() => schema.parse("not array")).toThrow()
+    })
+
+    it("should generate special schema for blob", () => {
+      const blobType = IDL.Vec(IDL.Nat8)
+      const field = visitor.visitVec(blobType, IDL.Nat8, "data")
+      const schema = field.schema
+
+      // Blob accepts string (hex) or array of numbers
+      expect(schema.parse("deadbeef")).toBe("deadbeef")
+      expect(schema.parse([1, 2, 3])).toEqual([1, 2, 3])
+      expect(() => schema.parse(123)).toThrow()
+    })
+  })
+
+  // ════════════════════════════════════════════════════════════════════════
+  // Recursive Types
+  // ════════════════════════════════════════════════════════════════════════
+
+  describe("Recursive Types", () => {
+    it("should handle recursive schemas", () => {
+      const List = IDL.Rec()
+      const ListVariant = IDL.Variant({
+        Nil: IDL.Null,
+        Cons: IDL.Record({
+          head: IDL.Nat,
+          tail: List,
+        }),
+      })
+      List.fill(ListVariant)
+
+      const field = visitor.visitRec(List, ListVariant, "list")
+      const schema = field.schema
+
+      const validList = {
+        Cons: {
+          head: "1",
+          tail: {
+            Cons: {
+              head: "2",
+              tail: { Nil: null },
+            },
+          },
+        },
+      }
+
+      expect(schema.parse(validList)).toEqual(validList)
+    })
+  })
+
+  // ════════════════════════════════════════════════════════════════════════
+  // Method Schema
+  // ════════════════════════════════════════════════════════════════════════
+
+  describe("Method Schema", () => {
+    it("should generate tuple schema for function arguments", () => {
+      const funcType = IDL.Func([IDL.Text, IDL.Nat], [], [])
+      const meta = visitor.visitFunc(funcType, "myMethod")
+
+      const schema = meta.schema
+      expect(schema).toBeDefined()
+
+      const validArgs = ["hello", "123"]
+      expect(schema.parse(validArgs)).toEqual(validArgs)
+
+      expect(() => schema.parse(["hello"])).toThrow()
+    })
+  })
+})

package/src/visitor/arguments/types.ts

@@ -1,4 +1,5 @@
 import type { BaseActor, FunctionName, FunctionType } from "@ic-reactor/core"
+import * as z from "zod"
 
 // ════════════════════════════════════════════════════════════════════════════
 // Field Type Union
@@ -19,150 +20,375 @@ export type ArgumentFieldType =
   | "null"
   | "unknown"
 
+// ════════════════════════════════════════════════════════════════════════════
+// UI Hints for Form Rendering
+// ════════════════════════════════════════════════════════════════════════════
+
+export interface FieldUIHints {
+  /** Placeholder text for the input */
+  placeholder?: string
+  /** Description or help text for the field */
+  description?: string
+  /** Whether the field is required */
+  required?: boolean
+  /** Whether the field should be disabled */
+  disabled?: boolean
+  /** Additional CSS class names */
+  className?: string
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // Base Field Interface
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface ArgumentFieldBase {
+export interface FieldBase<TValue = unknown> {
   /** The field type */
   type: ArgumentFieldType
   /** Human-readable label from Candid */
   label: string
-  /** Dot-notation path for form binding (e.g., "0.owner", "[0].to") */
-  path: string
+  /**
+   * Form field name path for binding.
+   * Uses bracket notation for array indices: `[0]`, `args[0].owner`, `tags[1]`
+   * Compatible with TanStack Form's `form.Field` name prop.
+   *
+   * @example
+   * ```tsx
+   * <form.Field name={field.name}>
+   *   {(fieldApi) => <input {...} />}
+   * </form.Field>
+   * ```
+   */
+  name: string
+  /** Zod schema for field validation */
+  schema: z.ZodTypeAny
+  /** Default value for the field */
+  defaultValue: TValue
+  /** Original Candid type name for reference */
+  candidType?: string
+  /** UI rendering hints */
+  ui?: FieldUIHints
 }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Compound Types
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface RecordArgumentField extends ArgumentFieldBase {
+export interface RecordField extends FieldBase<Record<string, unknown>> {
   type: "record"
-  fields: ArgumentField[]
-  defaultValues: Record<string, unknown>
+  /** Child fields in the record */
+  fields: Field[]
+  /** Map of field label to its metadata for quick lookup */
+  fieldMap: Map<string, Field>
 }
 
-export interface VariantArgumentField extends ArgumentFieldBase {
+export interface VariantField extends FieldBase<Record<string, unknown>> {
   type: "variant"
-  fields: ArgumentField[]
+  /** All variant option fields */
+  fields: Field[]
+  /** List of variant option names */
   options: string[]
+  /** Default selected option */
   defaultOption: string
-  defaultValues: Record<string, unknown>
+  /** Map of option name to its field metadata */
+  optionMap: Map<string, Field>
+  /**
+   * Get default value for a specific option.
+   * Useful when switching between variant options.
+   *
+   * @example
+   * ```tsx
+   * const handleOptionChange = (newOption: string) => {
+   *   const newDefault = field.getOptionDefault(newOption)
+   *   fieldApi.handleChange(newDefault)
+   * }
+   * ```
+   */
+  getOptionDefault: (option: string) => Record<string, unknown>
 }
 
-export interface TupleArgumentField extends ArgumentFieldBase {
+export interface TupleField extends FieldBase<unknown[]> {
   type: "tuple"
-  fields: ArgumentField[]
-  defaultValues: unknown[]
+  /** Tuple element fields in order */
+  fields: Field[]
 }
 
-export interface OptionalArgumentField extends ArgumentFieldBase {
+export interface OptionalField extends FieldBase<null> {
   type: "optional"
-  innerField: ArgumentField
-  defaultValue: null
+  /** The inner field when value is present */
+  innerField: Field
+  /**
+   * Get default value when enabling the optional.
+   * Returns the inner field's default value.
+   *
+   * @example
+   * ```tsx
+   * const handleToggle = (enabled: boolean) => {
+   *   if (enabled) {
+   *     fieldApi.handleChange(field.getInnerDefault())
+   *   } else {
+   *     fieldApi.handleChange(null)
+   *   }
+   * }
+   * ```
+   */
+  getInnerDefault: () => unknown
 }
 
-export interface VectorArgumentField extends ArgumentFieldBase {
+export interface VectorField extends FieldBase<unknown[]> {
   type: "vector"
-  itemField: ArgumentField
-  defaultValue: []
+  /** Template field for vector items */
+  itemField: Field
+  /**
+   * Get a new item with default values.
+   * Used when adding items to the vector.
+   *
+   * @example
+   * ```tsx
+   * <button onClick={() => fieldApi.pushValue(field.getItemDefault())}>
+   *   Add Item
+   * </button>
+   * ```
+   */
+  getItemDefault: () => unknown
 }
 
-export interface BlobArgumentField extends ArgumentFieldBase {
+export interface BlobField extends FieldBase<string> {
   type: "blob"
-  itemField: ArgumentField
-  /** Default is empty hex string */
-  defaultValue: string
+  /** Item field for individual bytes (nat8) */
+  itemField: Field
+  /** Accepted input formats */
+  acceptedFormats: ("hex" | "base64" | "file")[]
 }
 
-export interface RecursiveArgumentField extends ArgumentFieldBase {
+export interface RecursiveField extends FieldBase<undefined> {
   type: "recursive"
+  /** Type name for the recursive type */
+  typeName: string
   /** Lazily extract the inner field to prevent infinite loops */
-  extract: () => ArgumentField
+  extract: () => Field
+  /**
+   * Get default value for the recursive type.
+   * Evaluates the inner type on demand.
+   */
+  getInnerDefault: () => unknown
 }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Primitive Types
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface PrincipalArgumentField extends ArgumentFieldBase {
+export interface PrincipalField extends FieldBase<string> {
   type: "principal"
-  /** Display format: string */
-  defaultValue: string
   maxLength: number
   minLength: number
 }
 
-export interface NumberArgumentField extends ArgumentFieldBase {
+export interface NumberField extends FieldBase<string> {
   type: "number"
-  /** Display format: string (for bigint compatibility) */
-  defaultValue: string
-  /** Original Candid type: nat, int, nat64, etc. */
+  /**
+   * Original Candid type: nat, int, nat8, nat16, nat32, nat64, int8, int16, int32, int64, float32, float64
+   */
   candidType: string
+  /** Whether this is an unsigned type */
+  unsigned: boolean
+  /** Whether this is a floating point type */
+  isFloat: boolean
+  /** Bit width if applicable (8, 16, 32, 64, or undefined for unbounded) */
+  bits?: number
+  /** Minimum value constraint (for bounded types) */
+  min?: string
+  /** Maximum value constraint (for bounded types) */
+  max?: string
 }
 
-export interface TextArgumentField extends ArgumentFieldBase {
+export interface TextField extends FieldBase<string> {
   type: "text"
-  defaultValue: string
+  /** Minimum length constraint */
+  minLength?: number
+  /** Maximum length constraint */
+  maxLength?: number
+  /** Whether to render as multiline textarea */
+  multiline?: boolean
 }
 
-export interface BooleanArgumentField extends ArgumentFieldBase {
+export interface BooleanField extends FieldBase<boolean> {
   type: "boolean"
-  defaultValue: boolean
 }
 
-export interface NullArgumentField extends ArgumentFieldBase {
+export interface NullField extends FieldBase<null> {
   type: "null"
-  defaultValue: null
 }
 
-export interface UnknownArgumentField extends ArgumentFieldBase {
+export interface UnknownField extends FieldBase<undefined> {
   type: "unknown"
-  defaultValue: undefined
 }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Union Type
 // ════════════════════════════════════════════════════════════════════════════
 
-export type ArgumentField =
-  | RecordArgumentField
-  | VariantArgumentField
-  | TupleArgumentField
-  | OptionalArgumentField
-  | VectorArgumentField
-  | BlobArgumentField
-  | RecursiveArgumentField
-  | PrincipalArgumentField
-  | NumberArgumentField
-  | TextArgumentField
-  | BooleanArgumentField
-  | NullArgumentField
-  | UnknownArgumentField
+export type Field =
+  | RecordField
+  | VariantField
+  | TupleField
+  | OptionalField
+  | VectorField
+  | BlobField
+  | RecursiveField
+  | PrincipalField
+  | NumberField
+  | TextField
+  | BooleanField
+  | NullField
+  | UnknownField
 
 // ════════════════════════════════════════════════════════════════════════════
-// Method & Service Level
+// Form Metadata - TanStack Form Integration
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface MethodArgumentsMeta<
+/**
+ * Form metadata for a Candid method.
+ * Contains all information needed to create a TanStack Form instance.
+ *
+ * @example
+ * ```tsx
+ * import { useForm } from '@tanstack/react-form'
+ *
+ * function MethodForm({ meta }: { meta: FormMeta }) {
+ *   const form = useForm({
+ *     ...meta.formOptions,
+ *     onSubmit: async ({ value }) => {
+ *       await actor[meta.functionName](...value)
+ *     }
+ *   })
+ *
+ *   return (
+ *     <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit() }}>
+ *       {meta.fields.map(field => (
+ *         <form.Field key={field.name} name={field.name}>
+ *           {(fieldApi) => <DynamicInput field={field} fieldApi={fieldApi} />}
+ *         </form.Field>
+ *       ))}
+ *       <button type="submit">Submit</button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
+export interface ArgumentsMeta<
   A = BaseActor,
   Name extends FunctionName<A> = FunctionName<A>,
 > {
+  /** Whether this is a "query" or "update" function */
   functionType: FunctionType
+  /** The function name */
   functionName: Name
-  fields: ArgumentField[]
+  /** Argument field definitions for rendering */
+  fields: Field[]
+  /** Default values for all arguments (as a tuple) */
   defaultValues: unknown[]
+  /** Combined Zod schema for all arguments */
+  schema: z.ZodTuple<[z.ZodTypeAny, ...z.ZodTypeAny[]]>
+  /** Number of arguments */
+  argCount: number
+  /** Whether the function takes no arguments */
+  isNoArgs: boolean
 }
 
-export type ServiceArgumentsMeta<A = BaseActor> = {
-  [K in FunctionName<A>]: MethodArgumentsMeta<A, K>
+/**
+ * Options that can be spread into useForm().
+ * Pre-configured with defaultValues and validators.
+ */
+export interface FormOptions {
+  /** Initial form values */
+  defaultValues: unknown[]
+  /** Validators using the Zod schema */
+  validators: {
+    onChange: z.ZodTypeAny
+    onBlur: z.ZodTypeAny
+  }
+}
+
+/**
+ * Service-level form metadata.
+ * Maps each method name to its FormMeta.
+ */
+export type ArgumentsServiceMeta<A = BaseActor> = {
+  [K in FunctionName<A>]: ArgumentsMeta<A, K>
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Type Utilities
+// Type Utilities & Guards
 // ════════════════════════════════════════════════════════════════════════════
 
-export type ArgumentFieldByType<T extends ArgumentFieldType> = Extract<
-  ArgumentField,
+/** Extract a specific field type */
+export type FieldByType<T extends ArgumentFieldType> = Extract<
+  Field,
   { type: T }
 >
+
+/** Compound field types that contain other fields */
+export type CompoundField =
+  | RecordField
+  | VariantField
+  | TupleField
+  | OptionalField
+  | VectorField
+  | RecursiveField
+
+/** Primitive field types */
+export type PrimitiveField =
+  | PrincipalField
+  | NumberField
+  | TextField
+  | BooleanField
+  | NullField
+
+/**
+ * Type guard for checking specific field types.
+ *
+ * @example
+ * ```tsx
+ * function FieldInput({ field }: { field: Field }) {
+ *   if (isFieldType(field, 'record')) {
+ *     // field is now typed as RecordField
+ *     return <RecordInput field={field} />
+ *   }
+ *   if (isFieldType(field, 'text')) {
+ *     // field is now typed as TextField
+ *     return <TextInput field={field} />
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export function isFieldType<T extends ArgumentFieldType>(
+  field: Field,
+  type: T
+): field is FieldByType<T> {
+  return field.type === type
+}
+
+/** Check if a field is a compound type (contains other fields) */
+export function isCompoundField(field: Field): field is CompoundField {
+  return [
+    "record",
+    "variant",
+    "tuple",
+    "optional",
+    "vector",
+    "recursive",
+  ].includes(field.type)
+}
+
+/** Check if a field is a primitive type */
+export function isPrimitiveField(field: Field): field is PrimitiveField {
+  return ["principal", "number", "text", "boolean", "null"].includes(field.type)
+}
+
+/** Check if a field has children (for iteration) */
+export function hasChildFields(
+  field: Field
+): field is RecordField | VariantField | TupleField {
+  return "fields" in field && Array.isArray((field as RecordField).fields)
+}

package/src/visitor/helpers.ts

@@ -1,4 +1,4 @@
-import { IDL } from "./types"
+import { IDL } from "@icp-sdk/core/candid"
 
 export const extractAndSortArgs = <T extends Record<string, unknown>>(
   argsObject: T