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

package/src/visitor/arguments/types.ts

@@ -2,21 +2,34 @@ import type { BaseActor, FunctionName, FunctionType } from "@ic-reactor/core"
 import * as z from "zod"
 import type { VisitorDataType, TextFormat, NumberFormat } from "../types"
 
-export type { TextFormat, NumberFormat }
+export type { VisitorDataType, TextFormat, NumberFormat }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Field Type Union
+// Custom Error Class
 // ════════════════════════════════════════════════════════════════════════════
 
-export type ArgumentFieldType = VisitorDataType
+/**
+ * Custom error class for metadata-related errors.
+ * Provides additional context about the field path and Candid type.
+ */
+export class MetadataError extends Error {
+  constructor(
+    message: string,
+    public readonly fieldPath?: string,
+    public readonly candidType?: string
+  ) {
+    super(message)
+    this.name = "MetadataError"
+  }
+}
 
 // ════════════════════════════════════════════════════════════════════════════
-// Component Type Hints
+// Component & UI Types
 // ════════════════════════════════════════════════════════════════════════════
 
 /**
  * Suggested component type for rendering the field.
- * This eliminates the need for switch statements in the frontend.
+ * Use this to map field types to your UI components.
  */
 export type FieldComponentType =
   | "record-container"
@@ -33,13 +46,8 @@ export type FieldComponentType =
   | "recursive-lazy"
   | "unknown-fallback"
 
-// ════════════════════════════════════════════════════════════════════════════
-// Render Hints for UI Rendering Strategy
-// ════════════════════════════════════════════════════════════════════════════
-
 /**
  * Input type hints for HTML input elements.
- * Used by primitive fields to suggest the appropriate input type.
  */
 export type InputType =
   | "text"
@@ -51,49 +59,28 @@ export type InputType =
 
 /**
  * Rendering hints for the UI.
- * Eliminates the need for frontend to maintain COMPLEX_TYPES arrays.
  */
 export interface RenderHint {
-  /** Whether this field has its own container/card styling (compound types) */
   isCompound: boolean
-  /** Whether this is a leaf input (primitive types) */
   isPrimitive: boolean
-  /** Suggested input type for HTML input elements */
   inputType?: InputType
-  /** Description or help text for the field (derived from Candid) */
   description?: string
 }
 
-// ════════════════════════════════════════════════════════════════════════════
-// Primitive Input Props
-// ════════════════════════════════════════════════════════════════════════════
-
 /**
  * Pre-computed HTML input props for primitive fields.
- * Can be spread directly onto an input element.
  */
 export interface PrimitiveInputProps {
-  /** HTML input type - includes format-specific types */
   type?: "text" | "number" | "checkbox" | "email" | "url" | "tel"
-  /** Placeholder text */
   placeholder?: string
-  /** Minimum value for number inputs */
   min?: string | number
-  /** Maximum value for number inputs */
   max?: string | number
-  /** Step value for number inputs */
   step?: string | number
-  /** Pattern for text inputs (e.g., phone numbers) */
   pattern?: string
-  /** Input mode for virtual keyboards */
   inputMode?: "text" | "numeric" | "decimal" | "email" | "tel" | "url"
-  /** Autocomplete hint */
   autoComplete?: string
-  /** Whether to check spelling */
   spellCheck?: boolean
-  /** Minimum length for text inputs */
   minLength?: number
-  /** Maximum length for text inputs */
   maxLength?: number
 }
 
@@ -101,197 +88,223 @@ export interface PrimitiveInputProps {
 // Base Field Interface
 // ════════════════════════════════════════════════════════════════════════════
 
+/**
+ * Base properties shared by all field nodes.
+ */
 interface FieldBase<T extends VisitorDataType = VisitorDataType> {
-  /** The field type */
+  /** The Candid type category (record, variant, text, number, etc.) */
   type: T
-  /** Raw label from Candid: "__arg0", "_0_" */
+  /** Raw label from Candid definition */
   label: string
-  /** Pre-formatted display label for UI rendering */
+  /** Human-readable formatted label for display */
   displayLabel: string
-  /** Form field name path for binding */
+  /** Form path compatible with TanStack Form (e.g., "[0]", "[0].owner") */
   name: string
-  /** Suggested component type for rendering this field */
+  /** Suggested component type for rendering */
   component: FieldComponentType
-  /** Rendering hints for UI strategy */
+  /** UI rendering hints */
   renderHint: RenderHint
-  /** Zod schema for field validation */
+  /** Zod validation schema */
   schema: z.ZodTypeAny
-  /** Original Candid type name for reference */
+  /** Original Candid type name */
   candidType: string
+  /** Default value for form initialization */
+  defaultValue: unknown
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Type-Specific Extras
+// Field Extras - Type-Specific Properties
 // ════════════════════════════════════════════════════════════════════════════
 
-/**
- * Blob field size limits.
- */
+/** Blob upload limits configuration */
 export interface BlobLimits {
-  /** Maximum bytes when entering as hex (e.g., 512 bytes) */
   maxHexBytes: number
-  /** Maximum file size in bytes (e.g., 2MB ICP limit) */
   maxFileBytes: number
-  /** Maximum hex display length before truncation */
   maxHexDisplayLength: number
 }
 
-/**
- * Validation result for blob input.
- */
+/** Blob validation result */
 export interface BlobValidationResult {
-  /** Whether the input is valid */
   valid: boolean
-  /** Error message if invalid */
   error?: string
 }
 
+interface RecordExtras {
+  /** Child fields of the record */
+  fields: FieldNode[]
+  /** Default value as object with all field defaults */
+  defaultValue: Record<string, unknown>
+}
+
+interface VariantExtras {
+  /** All variant options as fields */
+  options: FieldNode[]
+  /** The default selected option key */
+  defaultOption: string
+  /** Default value with the first option selected */
+  defaultValue: Record<string, unknown>
+  /** Get default value for a specific option */
+  getOptionDefault: (option: string) => Record<string, unknown>
+  /** Get field descriptor for a specific option */
+  getOption: (option: string) => FieldNode
+  /** Get currently selected option key from a value */
+  getSelectedKey: (value: Record<string, unknown>) => string
+  /** Get the field for the currently selected option */
+  getSelectedOption: (value: Record<string, unknown>) => FieldNode
+}
+
+interface TupleExtras {
+  /** Tuple element fields */
+  fields: FieldNode[]
+  /** Default value as array of element defaults */
+  defaultValue: unknown[]
+}
+
+interface OptionalExtras {
+  /** The inner type field */
+  innerField: FieldNode
+  /** Default value is always null */
+  defaultValue: null
+  /** Get default value of the inner type when enabling */
+  getInnerDefault: () => unknown
+  /** Check if a value represents an enabled optional */
+  isEnabled: (value: unknown) => boolean
+}
+
+interface VectorExtras {
+  /** Template field for vector items */
+  itemField: FieldNode
+  /** Default value is empty array */
+  defaultValue: unknown[]
+  /** Get default value for a new item */
+  getItemDefault: () => unknown
+  /** Create a field node for an item at a specific index */
+  createItemField: (index: number, overrides?: { label?: string }) => FieldNode
+}
+
+interface BlobExtras {
+  /** Template field for blob bytes */
+  itemField: FieldNode
+  /** Accepted input formats */
+  acceptedFormats: ("hex" | "base64" | "file")[]
+  /** Upload limits */
+  limits: BlobLimits
+  /** Normalize hex input string */
+  normalizeHex: (input: string) => string
+  /** Validate blob input */
+  validateInput: (value: string | Uint8Array) => BlobValidationResult
+  /** Default value is empty string */
+  defaultValue: string
+}
+
+interface RecursiveExtras {
+  /** The recursive type name */
+  typeName: string
+  /** Lazily extract the inner type */
+  extract: () => FieldNode
+  /** Get default value of the inner type */
+  getInnerDefault: () => unknown
+  /** Default value is undefined */
+  defaultValue: undefined
+}
+
+interface PrincipalExtras {
+  /** Maximum Principal string length */
+  maxLength: number
+  /** Minimum Principal string length */
+  minLength: number
+  /** Detected text format */
+  format: TextFormat
+  /** Pre-computed HTML input props */
+  inputProps: PrimitiveInputProps
+  /** Default value is empty string */
+  defaultValue: string
+}
+
+interface NumberExtras {
+  /** Whether the number is unsigned (nat vs int) */
+  unsigned: boolean
+  /** Whether the number is a float */
+  isFloat: boolean
+  /** Bit width (8, 16, 32, 64) */
+  bits?: number
+  /** Minimum value as string */
+  min?: string
+  /** Maximum value as string */
+  max?: string
+  /** Detected number format */
+  format: NumberFormat
+  /** Pre-computed HTML input props */
+  inputProps: PrimitiveInputProps
+  /** Default value is empty string */
+  defaultValue: string
+}
+
+interface TextExtras {
+  /** Minimum text length */
+  minLength?: number
+  /** Maximum text length */
+  maxLength?: number
+  /** Whether to use multiline input */
+  multiline?: boolean
+  /** Detected text format */
+  format: TextFormat
+  /** Pre-computed HTML input props */
+  inputProps: PrimitiveInputProps
+  /** Default value is empty string */
+  defaultValue: string
+}
+
+interface BooleanExtras {
+  /** Pre-computed HTML input props */
+  inputProps: PrimitiveInputProps
+  /** Default value is false */
+  defaultValue: boolean
+}
+
+interface NullExtras {
+  /** Default value is null */
+  defaultValue: null
+}
+
+interface UnknownExtras {
+  /** Default value is undefined */
+  defaultValue: undefined
+}
+
 type FieldExtras<T extends VisitorDataType> = T extends "record"
-  ? {
-      /** Child fields in the record */
-      fields: FieldNode[]
-      /** Map of field label to its metadata for quick lookup */
-      fieldMap: Map<string, FieldNode>
-      defaultValue: Record<string, unknown>
-    }
+  ? RecordExtras
   : T extends "variant"
-    ? {
-        /** All variant option fields */
-        fields: FieldNode[]
-        /** List of variant option names */
-        options: string[]
-        /** Default selected option */
-        defaultOption: string
-        /** Map of option name to its field metadata */
-        optionMap: Map<string, FieldNode>
-        defaultValue: Record<string, unknown>
-        /** Get default value for a specific option */
-        getOptionDefault: (option: string) => Record<string, unknown>
-        /** Get the field for a specific option */
-        getField: (option: string) => FieldNode
-        /** Get the currently selected option from a value */
-        getSelectedOption: (value: Record<string, unknown>) => string
-        /** Get the selected field from a value */
-        getSelectedField: (value: Record<string, unknown>) => FieldNode
-      }
+    ? VariantExtras
     : T extends "tuple"
-      ? {
-          /** Tuple element fields in order */
-          fields: FieldNode[]
-          defaultValue: unknown[]
-        }
+      ? TupleExtras
       : T extends "optional"
-        ? {
-            /** The inner field when value is present */
-            innerField: FieldNode
-            defaultValue: null
-            /** Get default value when enabling the optional */
-            getInnerDefault: () => unknown
-            /** Check if a value represents an enabled optional */
-            isEnabled: (value: unknown) => boolean
-          }
+        ? OptionalExtras
         : T extends "vector"
-          ? {
-              /** Template field for vector items */
-              itemField: FieldNode
-              defaultValue: unknown[]
-              /** Get a new item with default values */
-              getItemDefault: () => unknown
-              /** Create a properly configured item field for a specific index */
-              createItemField: (
-                index: number,
-                overrides?: { label?: string }
-              ) => FieldNode
-            }
+          ? VectorExtras
           : T extends "blob"
-            ? {
-                /** Item field for individual bytes (nat8) */
-                itemField: FieldNode
-                /** Accepted input formats */
-                acceptedFormats: ("hex" | "base64" | "file")[]
-                /** Size limits for blob input */
-                limits: BlobLimits
-                /** Normalize hex input */
-                normalizeHex: (input: string) => string
-                /** Validate blob input value */
-                validateInput: (
-                  value: string | Uint8Array
-                ) => BlobValidationResult
-                defaultValue: string
-              }
+            ? BlobExtras
             : T extends "recursive"
-              ? {
-                  /** Type name for the recursive type */
-                  typeName: string
-                  /** Lazily extract the inner field to prevent infinite loops */
-                  extract: () => FieldNode
-                  /** Get default value for the recursive type (evaluates lazily) */
-                  getInnerDefault: () => unknown
-                  defaultValue: undefined
-                }
+              ? RecursiveExtras
               : T extends "principal"
-                ? {
-                    maxLength: number
-                    minLength: number
-                    /** Detected format based on label heuristics */
-                    format: TextFormat
-                    /** Pre-computed HTML input props */
-                    inputProps: PrimitiveInputProps
-                    defaultValue: string
-                  }
+                ? PrincipalExtras
                 : T extends "number"
-                  ? {
-                      /** 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
-                      /** Detected format based on label heuristics */
-                      format: NumberFormat
-                      /** Pre-computed HTML input props */
-                      inputProps: PrimitiveInputProps
-                      defaultValue: string
-                    }
+                  ? NumberExtras
                   : T extends "text"
-                    ? {
-                        /** Minimum length constraint */
-                        minLength?: number
-                        /** Maximum length constraint */
-                        maxLength?: number
-                        /** Whether to render as multiline textarea */
-                        multiline?: boolean
-                        /** Detected format based on label heuristics */
-                        format: TextFormat
-                        /** Pre-computed HTML input props */
-                        inputProps: PrimitiveInputProps
-                        defaultValue: string
-                      }
+                    ? TextExtras
                     : T extends "boolean"
-                      ? {
-                          /** Pre-computed HTML input props */
-                          inputProps: PrimitiveInputProps
-                          defaultValue: boolean
-                        }
+                      ? BooleanExtras
                       : T extends "null"
-                        ? {
-                            defaultValue: null
-                          }
+                        ? NullExtras
                         : T extends "unknown"
-                          ? {
-                              defaultValue: undefined
-                            }
+                          ? UnknownExtras
                           : {}
 
 /**
  * A unified field node that contains all metadata needed for rendering.
  */
 export type FieldNode<T extends VisitorDataType = VisitorDataType> =
-  FieldBase<T> & FieldExtras<T>
+  T extends any ? FieldBase<T> & FieldExtras<T> : never
 
 export type RecordField = FieldNode<"record">
 export type VariantField = FieldNode<"variant">
@@ -308,74 +321,52 @@ export type NullField = FieldNode<"null">
 export type UnknownField = FieldNode<"unknown">
 
 // ════════════════════════════════════════════════════════════════════════════
-// Form Metadata - TanStack Form Integration
+// Form Metadata
 // ════════════════════════════════════════════════════════════════════════════
 
 /**
- * Form metadata for a Candid method.
- * Contains all information needed to create a TanStack Form instance.
+ * Metadata for a single method's input arguments.
+ * Use this to generate dynamic forms for calling canister methods.
  */
 export interface ArgumentsMeta<
   A = BaseActor,
   Name extends FunctionName<A> = FunctionName<A>,
 > {
-  /** Whether this is a "query" or "update" function */
+  /** Whether this is a "query" or "update" call */
   functionType: FunctionType
-  /** The function name */
+  /** The method name as defined in the Candid interface */
   functionName: Name
-  /** Argument field definitions for rendering */
-  fields: FieldNode[]
-  /** Default values for all arguments (as a tuple) */
-  defaultValues: unknown[]
-  /** Combined Zod schema for all arguments */
+  /** Array of field descriptors, one per argument */
+  args: FieldNode[]
+  /** Default values suitable for form initialization */
+  defaults: unknown[]
+  /** Zod schema for validating all arguments together */
   schema: z.ZodTuple<[z.ZodTypeAny, ...z.ZodTypeAny[]]>
-  /** Number of arguments */
+  /** Number of arguments (0 for no-arg methods) */
   argCount: number
-  /** Whether the function takes no arguments */
-  isNoArgs: boolean
-}
-
-/**
- * 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
-  }
+  /** True if this method takes no arguments */
+  isEmpty: boolean
 }
 
 /**
- * Service-level form metadata.
- * Maps each method name to its FormMeta.
+ * Service-level metadata mapping method names to their argument metadata.
  */
 export type ArgumentsServiceMeta<A = BaseActor> = {
   [K in FunctionName<A>]: ArgumentsMeta<A, K>
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Type Utilities & Guards
+// Type Utilities
 // ════════════════════════════════════════════════════════════════════════════
 
-/** Extract a specific field type */
-export type FieldByType<T extends ArgumentFieldType> = Extract<
+/**
+ * Extract field type by VisitorDataType.
+ */
+export type FieldByType<T extends VisitorDataType> = Extract<
   FieldNode,
   { type: T }
 >
 
-/**
- * Props type helper for field components.
- * Use this to type your field components for better DX.
- */
-export type FieldProps<T extends ArgumentFieldType> = {
-  field: FieldByType<T>
-  renderField?: (child: FieldNode) => React.ReactNode
-}
-
 /** Compound field types that contain other fields */
 export type CompoundField =
   | RecordField
@@ -385,7 +376,7 @@ export type CompoundField =
   | VectorField
   | RecursiveField
 
-/** Primitive field types */
+/** Primitive field types with direct values */
 export type PrimitiveField =
   | PrincipalField
   | NumberField

package/src/visitor/constants.ts

@@ -30,27 +30,36 @@ const CYCLE_KEYS_REGEX = new RegExp(
   "i"
 )
 
-const EMAIL_KEYS_REGEX = /email|mail/i
-const PHONE_KEYS_REGEX = /phone|tel|mobile/i
-const URL_KEYS_REGEX = /url|link|website/i
-const UUID_KEYS_REGEX = /uuid|guid/i
-const BITCOIN_KEYS_REGEX = /bitcoin|btc/i
-const ETHEREUM_KEYS_REGEX = /ethereum|eth/i
 const ACCOUNT_ID_KEYS_REGEX =
-  /account_id|account_identifier|ledger_account|block_hash|transaction_hash|tx_hash/i
-const PRINCIPAL_KEYS_REGEX = /canister|principal/i
+  /account_identifier|ledger_account|block_hash|transaction_hash|tx_hash/i
+
+const tokenize = (label: string): Set<string> => {
+  const parts = label
+    .replace(/_/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[\s-]+/)
+  return new Set(parts)
+}
 
 export const checkTextFormat = (label?: string): TextFormat => {
   if (!label) return "plain"
+
   if (TAMESTAMP_KEYS_REGEX.test(label)) return "timestamp"
-  if (EMAIL_KEYS_REGEX.test(label)) return "email"
-  if (PHONE_KEYS_REGEX.test(label)) return "phone"
-  if (URL_KEYS_REGEX.test(label)) return "url"
-  if (UUID_KEYS_REGEX.test(label)) return "uuid"
-  if (BITCOIN_KEYS_REGEX.test(label)) return "btc"
-  if (ETHEREUM_KEYS_REGEX.test(label)) return "eth"
   if (ACCOUNT_ID_KEYS_REGEX.test(label)) return "account-id"
-  if (PRINCIPAL_KEYS_REGEX.test(label)) return "principal"
+
+  const tokens = tokenize(label)
+
+  if (tokens.has("email") || tokens.has("mail")) return "email"
+  if (tokens.has("phone") || tokens.has("tel") || tokens.has("mobile"))
+    return "phone"
+  if (tokens.has("url") || tokens.has("link") || tokens.has("website"))
+    return "url"
+  if (tokens.has("uuid") || tokens.has("guid")) return "uuid"
+  if (tokens.has("btc") || tokens.has("bitcoin")) return "btc"
+  if (tokens.has("eth") || tokens.has("ethereum")) return "eth"
+  if (tokens.has("principal") || tokens.has("canister")) return "principal"
+
   return "plain"
 }