@ic-reactor/candid 3.0.13-beta.0 → 3.0.14-beta.1

package/src/visitor/arguments/index.ts

@@ -1,6 +1,7 @@
 import { isQuery } from "../helpers"
+import { checkTextFormat, checkNumberFormat } from "../constants"
 import type {
-  Field,
+  FieldNode,
   RecordField,
   VariantField,
   TupleField,
@@ -20,6 +21,8 @@ import type {
   PrimitiveInputProps,
   BlobLimits,
   BlobValidationResult,
+  TextFormat,
+  NumberFormat,
 } from "./types"
 
 import { IDL } from "@icp-sdk/core/candid"
@@ -29,6 +32,8 @@ import * as z from "zod"
 import { formatLabel } from "./helpers"
 
 export * from "./types"
+export * from "./helpers"
+export { checkTextFormat, checkNumberFormat } from "../constants"
 
 // ════════════════════════════════════════════════════════════════════════════
 // Render Hint Helpers
@@ -177,7 +182,7 @@ function validateBlobInput(
  */
 export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
   string,
-  Field | ArgumentsMeta<A> | ArgumentsServiceMeta<A>
+  FieldNode | ArgumentsMeta<A> | ArgumentsServiceMeta<A>
 > {
   public recursiveSchemas: Map<string, z.ZodTypeAny> = new Map()
 
@@ -231,7 +236,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     const fields = t.argTypes.map((arg, index) => {
       return this.withName(`[${index}]`, () =>
         arg.accept(this, `__arg${index}`)
-      ) as Field
+      ) as FieldNode
     })
 
     const defaultValues = fields.map((field) => field.defaultValue)
@@ -272,18 +277,16 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     label: string
   ): RecordField {
     const name = this.currentName()
-    const fields: Field[] = []
-    const fieldMap = new Map<string, Field>()
+    const fields: FieldNode[] = []
     const defaultValue: Record<string, unknown> = {}
     const schemaShape: Record<string, z.ZodTypeAny> = {}
 
     for (const [key, type] of fields_) {
       const field = this.withName(name ? `.${key}` : key, () =>
         type.accept(this, key)
-      ) as Field
+      ) as FieldNode
 
       fields.push(field)
-      fieldMap.set(key, field)
       defaultValue[key] = field.defaultValue
       schemaShape[key] = field.schema
     }
@@ -298,7 +301,6 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
       component: "record-container",
       renderHint: COMPOUND_RENDER_HINT,
       fields,
-      fieldMap,
       defaultValue,
       schema,
       candidType: "record",
@@ -311,42 +313,55 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     label: string
   ): VariantField {
     const name = this.currentName()
-    const fields: Field[] = []
-    const options: string[] = []
-    const optionMap = new Map<string, Field>()
+    const fields: FieldNode[] = []
     const variantSchemas: z.ZodTypeAny[] = []
 
     for (const [key, type] of fields_) {
       const field = this.withName(`.${key}`, () =>
         type.accept(this, key)
-      ) as Field
+      ) as FieldNode
 
       fields.push(field)
-      options.push(key)
-      optionMap.set(key, field)
-      variantSchemas.push(z.object({ [key]: field.schema }))
+
+      if (field.type === "null") {
+        variantSchemas.push(z.object({ _type: z.literal(key) }))
+      } else {
+        variantSchemas.push(
+          z.object({
+            _type: z.literal(key),
+            [key]: field.schema,
+          })
+        )
+      }
     }
 
-    const defaultOption = options[0]
     const firstField = fields[0]
-    const defaultValue = {
-      [defaultOption]: firstField.defaultValue,
-    }
+    const defaultOption = firstField.label
+
+    const defaultValue =
+      firstField.type === "null"
+        ? { _type: defaultOption }
+        : {
+            _type: defaultOption,
+            [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)
+      const optField = fields.find((f) => f.label === option)
       if (!optField) {
         throw new Error(`Unknown variant option: ${option}`)
       }
-      return { [option]: optField.defaultValue }
+      return optField.type === "null"
+        ? { _type: option }
+        : { _type: option, [option]: optField.defaultValue }
     }
 
     // Helper to get field for a specific option
-    const getField = (option: string): Field => {
-      const optField = optionMap.get(option)
+    const getField = (option: string): FieldNode => {
+      const optField = fields.find((f) => f.label === option)
       if (!optField) {
         throw new Error(`Unknown variant option: ${option}`)
       }
@@ -355,12 +370,17 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
 
     // Helper to get currently selected option from a value
     const getSelectedOption = (value: Record<string, unknown>): string => {
-      const validKeys = Object.keys(value).filter((k) => options.includes(k))
+      if (value._type && typeof value._type === "string") {
+        return value._type
+      }
+      const validKeys = Object.keys(value).filter((k) =>
+        fields.some((f) => f.label === k)
+      )
       return validKeys[0] ?? defaultOption
     }
 
     // Helper to get selected field from a value
-    const getSelectedField = (value: Record<string, unknown>): Field => {
+    const getSelectedField = (value: Record<string, unknown>): FieldNode => {
       const selectedOption = getSelectedOption(value)
       return getField(selectedOption)
     }
@@ -373,9 +393,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
       component: "variant-select",
       renderHint: COMPOUND_RENDER_HINT,
       fields,
-      options,
       defaultOption,
-      optionMap,
       defaultValue,
       schema,
       getOptionDefault,
@@ -392,7 +410,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     label: string
   ): TupleField {
     const name = this.currentName()
-    const fields: Field[] = []
+    const fields: FieldNode[] = []
     const defaultValue: unknown[] = []
     const schemas: z.ZodTypeAny[] = []
 
@@ -400,7 +418,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
       const type = components[index]
       const field = this.withName(`[${index}]`, () =>
         type.accept(this, `_${index}_`)
-      ) as Field
+      ) as FieldNode
 
       fields.push(field)
       defaultValue.push(field.defaultValue)
@@ -432,7 +450,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
 
     // 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 innerField = ty.accept(this, label) as FieldNode
 
     const schema = z.union([
       innerField.schema,
@@ -478,7 +496,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     // Item field uses [0] as template path
     const itemField = this.withName("[0]", () =>
       ty.accept(this, `${label}_item`)
-    ) as Field
+    ) as FieldNode
 
     if (isBlob) {
       const schema = z.union([
@@ -517,7 +535,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     const createItemField = (
       index: number,
       overrides?: { label?: string }
-    ): Field => {
+    ): FieldNode => {
       // Replace [0] in template with actual index
       const itemName = name ? `${name}[${index}]` : `[${index}]`
       const itemLabel = overrides?.label ?? `Item ${index}`
@@ -559,13 +577,13 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     if (this.recursiveSchemas.has(typeName)) {
       schema = this.recursiveSchemas.get(typeName)!
     } else {
-      schema = z.lazy(() => (ty.accept(this, label) as Field).schema)
+      schema = z.lazy(() => (ty.accept(this, label) as FieldNode).schema)
       this.recursiveSchemas.set(typeName, schema)
     }
 
     // Lazy extraction to prevent infinite loops
-    const extract = (): Field =>
-      this.withName(name, () => ty.accept(this, label)) as Field
+    const extract = (): FieldNode =>
+      this.withName(name, () => ty.accept(this, label)) as FieldNode
 
     // Helper to get inner default (evaluates lazily)
     const getInnerDefault = (): unknown => extract().defaultValue
@@ -628,6 +646,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
       defaultValue: "",
       maxLength: 64,
       minLength: 7,
+      format: checkTextFormat(label) as TextFormat,
       schema,
       inputProps,
       candidType: "principal",
@@ -635,11 +654,13 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
   }
 
   public visitText(_t: IDL.TextClass, label: string): TextField {
-    const inputProps: PrimitiveInputProps = {
-      type: "text",
-      placeholder: "Enter text...",
-      spellCheck: true,
-    }
+    const format = checkTextFormat(label) as TextFormat
+
+    // Generate format-specific inputProps
+    const inputProps = this.getTextInputProps(format)
+
+    // Generate format-specific schema
+    const schema = this.getTextSchema(format)
 
     return {
       type: "text",
@@ -649,12 +670,109 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
       component: "text-input",
       renderHint: TEXT_RENDER_HINT,
       defaultValue: "",
-      schema: z.string().min(1, "Required"),
+      format,
+      schema,
       inputProps,
       candidType: "text",
     }
   }
 
+  /**
+   * Generate format-specific input props for text fields.
+   */
+  private getTextInputProps(format: TextFormat): PrimitiveInputProps {
+    switch (format) {
+      case "email":
+        return {
+          type: "email",
+          placeholder: "email@example.com",
+          inputMode: "email",
+          autoComplete: "email",
+          spellCheck: false,
+        }
+      case "url":
+        return {
+          type: "url",
+          placeholder: "https://example.com",
+          inputMode: "url",
+          autoComplete: "url",
+          spellCheck: false,
+        }
+      case "phone":
+        return {
+          type: "tel",
+          placeholder: "+1 (555) 123-4567",
+          inputMode: "tel",
+          autoComplete: "tel",
+          spellCheck: false,
+        }
+      case "uuid":
+        return {
+          type: "text",
+          placeholder: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          pattern:
+            "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}",
+          spellCheck: false,
+          autoComplete: "off",
+        }
+      case "btc":
+        return {
+          type: "text",
+          placeholder: "bc1... or 1... or 3...",
+          spellCheck: false,
+          autoComplete: "off",
+        }
+      case "eth":
+        return {
+          type: "text",
+          placeholder: "0x...",
+          pattern: "0x[0-9a-fA-F]{40}",
+          spellCheck: false,
+          autoComplete: "off",
+        }
+      case "account-id":
+        return {
+          type: "text",
+          placeholder: "64-character hex string",
+          pattern: "[0-9a-fA-F]{64}",
+          maxLength: 64,
+          spellCheck: false,
+          autoComplete: "off",
+        }
+      case "principal":
+        return {
+          type: "text",
+          placeholder: "aaaaa-aa or full principal ID",
+          minLength: 7,
+          maxLength: 64,
+          spellCheck: false,
+          autoComplete: "off",
+        }
+      default:
+        return {
+          type: "text",
+          placeholder: "Enter text...",
+          spellCheck: true,
+        }
+    }
+  }
+
+  /**
+   * Generate format-specific zod schema for text fields.
+   */
+  private getTextSchema(format: TextFormat): z.ZodTypeAny {
+    switch (format) {
+      case "email":
+        return z.email("Invalid email address")
+      case "url":
+        return z.url("Invalid URL")
+      case "uuid":
+        return z.uuid("Invalid UUID")
+      default:
+        return z.string().min(1, "Required")
+    }
+  }
+
   public visitBool(_t: IDL.BoolClass, label: string): BooleanField {
     const inputProps: PrimitiveInputProps = {
       type: "checkbox",
@@ -706,6 +824,8 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
       max?: string
     }
   ): NumberField | TextField {
+    const format = checkNumberFormat(label) as NumberFormat
+
     let schema = z.string().min(1, "Required")
 
     if (options.isFloat) {
@@ -722,6 +842,11 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
     const type = isBigInt ? "text" : "number"
 
     if (type === "text") {
+      // Propagate timestamp/cycle format if detected, otherwise default to plain
+      let textFormat: TextFormat = "plain"
+      if (format === "timestamp") textFormat = "timestamp"
+      if (format === "cycle") textFormat = "cycle"
+
       const inputProps: PrimitiveInputProps = {
         type: "text",
         placeholder: options.unsigned ? "e.g. 100000" : "e.g. -100000",
@@ -739,6 +864,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
         component: "text-input",
         renderHint: TEXT_RENDER_HINT,
         defaultValue: "",
+        format: textFormat,
         candidType,
         schema,
         inputProps,
@@ -763,7 +889,8 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
       renderHint: NUMBER_RENDER_HINT,
       defaultValue: "",
       candidType,
-      schema: schema,
+      format,
+      schema,
       inputProps,
       ...options,
     }
@@ -838,6 +965,7 @@ export class FieldVisitor<A = BaseActor> extends IDL.Visitor<
         isPrimitive: false,
       },
       defaultValue: undefined,
+      candidType: "unknown",
       schema: z.any(),
     }
   }

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

@@ -62,6 +62,108 @@ describe("FieldVisitor Schema Generation", () => {
     })
   })
 
+  // ════════════════════════════════════════════════════════════════════════
+  // Format Detection & Validation
+  // ════════════════════════════════════════════════════════════════════════
+
+  describe("Format Detection & Validation", () => {
+    describe("Text Formats", () => {
+      it("should detect email format", () => {
+        const field = visitor.visitText(IDL.Text, "user_email")
+
+        expect(field.format).toBe("email")
+        expect(field.inputProps).toMatchObject({
+          type: "email",
+          inputMode: "email",
+        })
+
+        // Valid email
+        expect(field.schema.parse("test@example.com")).toBe("test@example.com")
+        // Invalid email
+        expect(() => field.schema.parse("invalid-email")).toThrow()
+      })
+
+      it("should detect url format", () => {
+        const field = visitor.visitText(IDL.Text, "website_link")
+
+        expect(field.format).toBe("url")
+        expect(field.inputProps).toMatchObject({
+          type: "url",
+          inputMode: "url",
+        })
+
+        // Valid URL
+        expect(field.schema.parse("https://example.com")).toBe(
+          "https://example.com"
+        )
+        // Invalid URL
+        expect(() => field.schema.parse("not-a-url")).toThrow()
+      })
+
+      it("should detect uuid format", () => {
+        const field = visitor.visitText(IDL.Text, "transaction_uuid")
+
+        expect(field.format).toBe("uuid")
+
+        const validUuid = "123e4567-e89b-12d3-a456-426614174000"
+        expect(field.schema.parse(validUuid)).toBe(validUuid)
+
+        expect(() => field.schema.parse("invalid-uuid")).toThrow()
+      })
+
+      it("should detect ethereum address format", () => {
+        const field = visitor.visitText(IDL.Text, "eth_address")
+
+        expect(field.format).toBe("eth")
+        expect(field.inputProps.pattern).toContain("0x")
+      })
+
+      it("should fallback to plain text for unknown formats", () => {
+        const field = visitor.visitText(IDL.Text, "some_random_field")
+
+        expect(field.format).toBe("plain")
+        expect(field.inputProps).toMatchObject({
+          type: "text",
+        })
+      })
+    })
+
+    describe("Number Formats", () => {
+      it("should detect timestamp format", () => {
+        const field = visitor.visitInt(IDL.Int, "created_at")
+
+        expect(field.format).toBe("timestamp")
+      })
+
+      it("should detect cycle format", () => {
+        const field = visitor.visitNat(IDL.Nat, "cycles_balance")
+
+        expect(field.format).toBe("cycle")
+      })
+
+      it("should fallback to normal format", () => {
+        const field = visitor.visitNat(IDL.Nat, "quantity")
+
+        expect(field.format).toBe("plain")
+      })
+    })
+
+    describe("Principal Format", () => {
+      it("should detect principal format and set properties", () => {
+        const field = visitor.visitPrincipal(
+          IDL.Principal,
+          "controller_principal"
+        )
+
+        expect(field.format).toBe("principal")
+        expect(field.inputProps).toMatchObject({
+          minLength: 7,
+          maxLength: 64,
+        })
+      })
+    })
+  })
+
   // ════════════════════════════════════════════════════════════════════════
   // Compound Types
   // ════════════════════════════════════════════════════════════════════════
@@ -106,10 +208,16 @@ describe("FieldVisitor Schema Generation", () => {
       )
       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({ _type: "Ok", Ok: "Success" })).toEqual({
+        _type: "Ok",
+        Ok: "Success",
+      })
+      expect(schema.parse({ _type: "Err", Err: "Error" })).toEqual({
+        _type: "Err",
+        Err: "Error",
+      })
 
-      expect(() => schema.parse({ Other: "value" })).toThrow()
+      expect(() => schema.parse({ _type: "Other", Other: "value" })).toThrow()
     })
   })
 
@@ -179,12 +287,14 @@ describe("FieldVisitor Schema Generation", () => {
       const schema = field.schema
 
       const validList = {
+        _type: "Cons",
         Cons: {
           head: "1",
           tail: {
+            _type: "Cons",
             Cons: {
               head: "2",
-              tail: { Nil: null },
+              tail: { _type: "Nil" },
             },
           },
         },