@ic-reactor/candid 3.0.12-beta.0 → 3.0.14-beta.0

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,
@@ -16,17 +17,119 @@ import type {
   UnknownField,
   ArgumentsMeta,
   ArgumentsServiceMeta,
+  RenderHint,
+  PrimitiveInputProps,
+  BlobLimits,
+  BlobValidationResult,
+  TextFormat,
+  NumberFormat,
 } 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"
+import { formatLabel } from "./helpers"
 
 export * from "./types"
+export * from "./helpers"
+export { checkTextFormat, checkNumberFormat } from "../constants"
+
+// ════════════════════════════════════════════════════════════════════════════
+// Render Hint Helpers
+// ════════════════════════════════════════════════════════════════════════════
+
+const COMPOUND_RENDER_HINT: RenderHint = {
+  isCompound: true,
+  isPrimitive: false,
+}
+
+const TEXT_RENDER_HINT: RenderHint = {
+  isCompound: false,
+  isPrimitive: true,
+  inputType: "text",
+}
+
+const NUMBER_RENDER_HINT: RenderHint = {
+  isCompound: false,
+  isPrimitive: true,
+  inputType: "number",
+}
+
+const CHECKBOX_RENDER_HINT: RenderHint = {
+  isCompound: false,
+  isPrimitive: true,
+  inputType: "checkbox",
+}
+
+const FILE_RENDER_HINT: RenderHint = {
+  isCompound: false,
+  isPrimitive: true,
+  inputType: "file",
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Blob Field Helpers
+// ════════════════════════════════════════════════════════════════════════════
+
+const DEFAULT_BLOB_LIMITS: BlobLimits = {
+  maxHexBytes: 512,
+  maxFileBytes: 2 * 1024 * 1024, // 2MB
+  maxHexDisplayLength: 128,
+}
+
+function normalizeHex(input: string): string {
+  // Remove 0x prefix and convert to lowercase
+  let hex = input.toLowerCase()
+  if (hex.startsWith("0x")) {
+    hex = hex.slice(2)
+  }
+  // Remove any whitespace
+  hex = hex.replace(/\s/g, "")
+  return hex
+}
+
+function validateBlobInput(
+  value: string | Uint8Array,
+  limits: BlobLimits
+): BlobValidationResult {
+  if (value instanceof Uint8Array) {
+    if (value.length > limits.maxFileBytes) {
+      return {
+        valid: false,
+        error: `File size exceeds maximum of ${limits.maxFileBytes} bytes`,
+      }
+    }
+    return { valid: true }
+  }
+
+  // String input (hex)
+  const normalized = normalizeHex(value)
+  if (normalized.length === 0) {
+    return { valid: true } // Empty is valid
+  }
+
+  if (!/^[0-9a-f]*$/.test(normalized)) {
+    return { valid: false, error: "Invalid hex characters" }
+  }
+
+  if (normalized.length % 2 !== 0) {
+    return { valid: false, error: "Hex string must have even length" }
+  }
+
+  const byteLength = normalized.length / 2
+  if (byteLength > limits.maxHexBytes) {
+    return {
+      valid: false,
+      error: `Hex input exceeds maximum of ${limits.maxHexBytes} bytes`,
+    }
+  }
+
+  return { valid: true }
+}
 
 /**
- * ArgumentFieldVisitor generates metadata for form input fields from Candid IDL types.
+ * FieldVisitor generates metadata for form input fields from Candid IDL types.
  *
  * ## Design Principles
  *
@@ -40,8 +143,11 @@ export * from "./types"
  *
  * Each field has:
  * - `type`: The field type (record, variant, text, number, etc.)
- * - `label`: Human-readable label from Candid
+ * - `label`: Raw label from Candid
+ * - `displayLabel`: Human-readable formatted label
  * - `name`: TanStack Form compatible path (e.g., "[0]", "[0].owner", "tags[1]")
+ * - `component`: Suggested component type for rendering
+ * - `renderHint`: Hints for UI rendering strategy
  * - `defaultValue`: Initial value for the form
  * - `schema`: Zod schema for validation
  * - Type-specific properties (options for variant, fields for record, etc.)
@@ -52,9 +158,9 @@ export * from "./types"
  * @example
  * ```typescript
  * import { useForm } from '@tanstack/react-form'
- * import { ArgumentFieldVisitor } from '@ic-reactor/candid'
+ * import { FieldVisitor } from '@ic-reactor/candid'
  *
- * const visitor = new ArgumentFieldVisitor()
+ * const visitor = new FieldVisitor()
  * const serviceMeta = service.accept(visitor, null)
  * const methodMeta = serviceMeta["icrc1_transfer"]
  *
@@ -74,9 +180,9 @@ export * from "./types"
  * ))
  * ```
  */
-export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
+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()
 
@@ -130,7 +236,7 @@ export class ArgumentFieldVisitor<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)
@@ -171,15 +277,15 @@ export class ArgumentFieldVisitor<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 fieldMap = new Map<string, 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)
@@ -192,7 +298,10 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     return {
       type: "record",
       label,
+      displayLabel: formatLabel(label),
       name,
+      component: "record-container",
+      renderHint: COMPOUND_RENDER_HINT,
       fields,
       fieldMap,
       defaultValue,
@@ -207,29 +316,44 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     label: string
   ): VariantField {
     const name = this.currentName()
-    const fields: Field[] = []
+    const fields: FieldNode[] = []
     const options: string[] = []
-    const optionMap = new Map<string, Field>()
+    const optionMap = new Map<string, 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 schema = z.union(variantSchemas as [z.ZodTypeAny, ...z.ZodTypeAny[]])
+    const defaultValue =
+      firstField.type === "null"
+        ? { _type: defaultOption }
+        : {
+            _type: defaultOption,
+            [defaultOption]: firstField.defaultValue,
+          }
+
+    const schema = z.union(variantSchemas)
 
     // Helper to get default value for any option
     const getOptionDefault = (option: string): Record<string, unknown> => {
@@ -237,13 +361,42 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
       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): FieldNode => {
+      const optField = optionMap.get(option)
+      if (!optField) {
+        throw new Error(`Unknown variant option: ${option}`)
+      }
+      return optField
+    }
+
+    // Helper to get currently selected option from a value
+    const getSelectedOption = (value: Record<string, unknown>): string => {
+      if (value._type && typeof value._type === "string") {
+        return value._type
+      }
+      const validKeys = Object.keys(value).filter((k) => options.includes(k))
+      return validKeys[0] ?? defaultOption
+    }
+
+    // Helper to get selected field from a value
+    const getSelectedField = (value: Record<string, unknown>): FieldNode => {
+      const selectedOption = getSelectedOption(value)
+      return getField(selectedOption)
     }
 
     return {
       type: "variant",
       label,
+      displayLabel: formatLabel(label),
       name,
+      component: "variant-select",
+      renderHint: COMPOUND_RENDER_HINT,
       fields,
       options,
       defaultOption,
@@ -251,6 +404,9 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
       defaultValue,
       schema,
       getOptionDefault,
+      getField,
+      getSelectedOption,
+      getSelectedField,
       candidType: "variant",
     }
   }
@@ -261,7 +417,7 @@ export class ArgumentFieldVisitor<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[] = []
 
@@ -269,7 +425,7 @@ export class ArgumentFieldVisitor<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)
@@ -281,7 +437,10 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     return {
       type: "tuple",
       label,
+      displayLabel: formatLabel(label),
       name,
+      component: "tuple-container",
+      renderHint: COMPOUND_RENDER_HINT,
       fields,
       defaultValue,
       schema,
@@ -298,7 +457,7 @@ export class ArgumentFieldVisitor<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,
@@ -310,14 +469,23 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     // Helper to get the inner default when enabling the optional
     const getInnerDefault = (): unknown => innerField.defaultValue
 
+    // Helper to check if a value represents an enabled optional
+    const isEnabled = (value: unknown): boolean => {
+      return value !== null && typeof value !== "undefined"
+    }
+
     return {
       type: "optional",
       label,
+      displayLabel: formatLabel(label),
       name,
+      component: "optional-toggle",
+      renderHint: COMPOUND_RENDER_HINT,
       innerField,
       defaultValue: null,
       schema,
       getInnerDefault,
+      isEnabled,
       candidType: "opt",
     }
   }
@@ -335,7 +503,7 @@ export class ArgumentFieldVisitor<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([
@@ -343,14 +511,24 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
         z.array(z.number()),
         z.instanceof(Uint8Array),
       ])
+
+      const limits = { ...DEFAULT_BLOB_LIMITS }
+
       return {
         type: "blob",
         label,
+        displayLabel: formatLabel(label),
         name,
+        component: "blob-upload",
+        renderHint: FILE_RENDER_HINT,
         itemField,
         defaultValue: "",
         schema,
         acceptedFormats: ["hex", "base64", "file"],
+        limits,
+        normalizeHex,
+        validateInput: (value: string | Uint8Array) =>
+          validateBlobInput(value, limits),
         candidType: "blob",
       }
     }
@@ -360,14 +538,35 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     // Helper to get a new item with default values
     const getItemDefault = (): unknown => itemField.defaultValue
 
+    // Helper to create an item field for a specific index
+    const createItemField = (
+      index: number,
+      overrides?: { label?: string }
+    ): FieldNode => {
+      // Replace [0] in template with actual index
+      const itemName = name ? `${name}[${index}]` : `[${index}]`
+      const itemLabel = overrides?.label ?? `Item ${index}`
+
+      return {
+        ...itemField,
+        name: itemName,
+        label: itemLabel,
+        displayLabel: formatLabel(itemLabel),
+      }
+    }
+
     return {
       type: "vector",
       label,
+      displayLabel: formatLabel(label),
       name,
+      component: "vector-list",
+      renderHint: COMPOUND_RENDER_HINT,
       itemField,
       defaultValue: [],
       schema,
       getItemDefault,
+      createItemField,
       candidType: "vec",
     }
   }
@@ -385,13 +584,13 @@ export class ArgumentFieldVisitor<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
@@ -399,7 +598,10 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     return {
       type: "recursive",
       label,
+      displayLabel: formatLabel(label),
       name,
+      component: "recursive-lazy",
+      renderHint: COMPOUND_RENDER_HINT,
       typeName,
       extract,
       defaultValue: undefined,
@@ -432,42 +634,167 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
       }
     )
 
+    const inputProps: PrimitiveInputProps = {
+      type: "text",
+      placeholder: "aaaaa-aa or full principal ID",
+      minLength: 7,
+      maxLength: 64,
+      spellCheck: false,
+      autoComplete: "off",
+    }
+
     return {
       type: "principal",
       label,
+      displayLabel: formatLabel(label),
       name: this.currentName(),
+      component: "principal-input",
+      renderHint: TEXT_RENDER_HINT,
       defaultValue: "",
       maxLength: 64,
       minLength: 7,
+      format: checkTextFormat(label) as TextFormat,
       schema,
+      inputProps,
       candidType: "principal",
-      ui: {
-        placeholder: "aaaaa-aa or full principal ID",
-      },
     }
   }
 
   public visitText(_t: IDL.TextClass, label: string): TextField {
+    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",
       label,
+      displayLabel: formatLabel(label),
       name: this.currentName(),
+      component: "text-input",
+      renderHint: TEXT_RENDER_HINT,
       defaultValue: "",
-      schema: z.string().min(1, "Required"),
+      format,
+      schema,
+      inputProps,
       candidType: "text",
-      ui: {
-        placeholder: "Enter 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",
+    }
+
     return {
       type: "boolean",
       label,
+      displayLabel: formatLabel(label),
       name: this.currentName(),
+      component: "boolean-checkbox",
+      renderHint: CHECKBOX_RENDER_HINT,
       defaultValue: false,
       schema: z.boolean(),
+      inputProps,
       candidType: "bool",
     }
   }
@@ -476,7 +803,13 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     return {
       type: "null",
       label,
+      displayLabel: formatLabel(label),
       name: this.currentName(),
+      component: "null-hidden",
+      renderHint: {
+        isCompound: false,
+        isPrimitive: true,
+      },
       defaultValue: null,
       schema: z.null(),
       candidType: "null",
@@ -498,6 +831,8 @@ export class ArgumentFieldVisitor<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) {
@@ -514,30 +849,57 @@ export class ArgumentFieldVisitor<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",
+        inputMode: "numeric",
+        pattern: options.unsigned ? "\\d+" : "-?\\d+",
+        spellCheck: false,
+        autoComplete: "off",
+      }
+
       return {
         type: "text",
         label,
+        displayLabel: formatLabel(label),
         name: this.currentName(),
+        component: "text-input",
+        renderHint: TEXT_RENDER_HINT,
         defaultValue: "",
+        format: textFormat,
         candidType,
         schema,
-        ui: {
-          placeholder: options.unsigned ? "e.g. 100000" : "e.g. -100000",
-        },
+        inputProps,
       }
     }
 
+    const inputProps: PrimitiveInputProps = {
+      type: "number",
+      placeholder: options.isFloat ? "0.0" : "0",
+      inputMode: options.isFloat ? "decimal" : "numeric",
+      min: options.min,
+      max: options.max,
+      step: options.isFloat ? "any" : "1",
+    }
+
     return {
       type: "number",
       label,
+      displayLabel: formatLabel(label),
       name: this.currentName(),
+      component: "number-input",
+      renderHint: NUMBER_RENDER_HINT,
       defaultValue: "",
       candidType,
-      schema: schema,
+      format,
+      schema,
+      inputProps,
       ...options,
-      ui: {
-        placeholder: options.isFloat ? "0.0" : "0",
-      },
     }
   }
 
@@ -602,8 +964,15 @@ export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
     return {
       type: "unknown",
       label,
+      displayLabel: formatLabel(label),
       name: this.currentName(),
+      component: "unknown-fallback",
+      renderHint: {
+        isCompound: false,
+        isPrimitive: false,
+      },
       defaultValue: undefined,
+      candidType: "unknown",
       schema: z.any(),
     }
   }