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

package/src/visitor/arguments/types.ts

@@ -1,24 +1,14 @@
 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 }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Field Type Union
 // ════════════════════════════════════════════════════════════════════════════
 
-export type ArgumentFieldType =
-  | "record"
-  | "variant"
-  | "tuple"
-  | "optional"
-  | "vector"
-  | "blob"
-  | "recursive"
-  | "principal"
-  | "number"
-  | "text"
-  | "boolean"
-  | "null"
-  | "unknown"
+export type ArgumentFieldType = VisitorDataType
 
 // ════════════════════════════════════════════════════════════════════════════
 // Component Type Hints
@@ -27,18 +17,6 @@ export type ArgumentFieldType =
 /**
  * Suggested component type for rendering the field.
  * This eliminates the need for switch statements in the frontend.
- *
- * @example
- * ```tsx
- * const componentMap = {
- *   'text-input': TextField,
- *   'number-input': NumberField,
- *   'boolean-checkbox': BooleanField,
- *   // ...
- * }
- * const Component = componentMap[field.component]
- * return <Component field={field} />
- * ```
  */
 export type FieldComponentType =
   | "record-container"
@@ -74,18 +52,6 @@ export type InputType =
 /**
  * Rendering hints for the UI.
  * Eliminates the need for frontend to maintain COMPLEX_TYPES arrays.
- *
- * @example
- * ```tsx
- * // Frontend no longer needs:
- * // const COMPLEX_TYPES = ["record", "tuple", "variant", "vector", "optional"]
- *
- * // Instead use:
- * if (field.renderHint.isCompound) {
- *   return <CompoundFieldRenderer field={field} />
- * }
- * return <PrimitiveInput field={field} />
- * ```
  */
 export interface RenderHint {
   /** Whether this field has its own container/card styling (compound types) */
@@ -105,15 +71,10 @@ export interface RenderHint {
 /**
  * Pre-computed HTML input props for primitive fields.
  * Can be spread directly onto an input element.
- *
- * @example
- * ```tsx
- * <input {...field.inputProps} value={value} onChange={handleChange} />
- * ```
  */
 export interface PrimitiveInputProps {
-  /** HTML input type */
-  type?: "text" | "number" | "checkbox"
+  /** HTML input type - includes format-specific types */
+  type?: "text" | "number" | "checkbox" | "email" | "url" | "tel"
   /** Placeholder text */
   placeholder?: string
   /** Minimum value for number inputs */
@@ -122,10 +83,10 @@ export interface PrimitiveInputProps {
   max?: string | number
   /** Step value for number inputs */
   step?: string | number
-  /** Pattern for text inputs */
+  /** Pattern for text inputs (e.g., phone numbers) */
   pattern?: string
   /** Input mode for virtual keyboards */
-  inputMode?: "text" | "numeric" | "decimal"
+  inputMode?: "text" | "numeric" | "decimal" | "email" | "tel" | "url"
   /** Autocomplete hint */
   autoComplete?: string
   /** Whether to check spelling */
@@ -140,205 +101,29 @@ export interface PrimitiveInputProps {
 // Base Field Interface
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface FieldBase<TValue = unknown> {
+interface FieldBase<T extends VisitorDataType = VisitorDataType> {
   /** The field type */
-  type: ArgumentFieldType
+  type: T
   /** Raw label from Candid: "__arg0", "_0_" */
   label: string
-  /**
-   * Pre-formatted display label for UI rendering.
-   * Transforms raw labels into human-readable format.
-   *
-   * @example
-   * "__arg0" => "Arg 0"
-   * "_0_" => "Item 0"
-   * "created_at_time" => "Created At Time"
-   */
+  /** Pre-formatted display label for UI rendering */
   displayLabel: 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>
-   * ```
-   */
+  /** Form field name path for binding */
   name: string
-  /**
-   * Suggested component type for rendering this field.
-   * Eliminates the need for switch statements in the frontend.
-   */
+  /** Suggested component type for rendering this field */
   component: FieldComponentType
-  /**
-   * Rendering hints for UI strategy.
-   * Use this to determine if the field needs a container or is a simple input.
-   */
+  /** Rendering hints for UI strategy */
   renderHint: RenderHint
   /** Zod schema for field validation */
   schema: z.ZodTypeAny
-  /** Default value for the field */
-  defaultValue: TValue
   /** Original Candid type name for reference */
-  candidType?: string
+  candidType: string
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Compound Types
+// Type-Specific Extras
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface RecordField extends FieldBase<Record<string, unknown>> {
-  type: "record"
-  /** Child fields in the record */
-  fields: Field[]
-  /** Map of field label to its metadata for quick lookup */
-  fieldMap: Map<string, Field>
-}
-
-export interface VariantField extends FieldBase<Record<string, unknown>> {
-  type: "variant"
-  /** All variant option fields */
-  fields: Field[]
-  /** List of variant option names */
-  options: string[]
-  /** Default selected option */
-  defaultOption: string
-  /** 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>
-  /**
-   * Get the field for a specific option.
-   *
-   * @example
-   * ```tsx
-   * const transferField = field.getField("Transfer")
-   * ```
-   */
-  getField: (option: string) => Field
-  /**
-   * Get the currently selected option from a value.
-   * Returns the first valid key found, or the default option.
-   *
-   * @example
-   * ```tsx
-   * const selectedOption = field.getSelectedOption(currentValue)
-   * // { Transfer: {...} } => "Transfer"
-   * ```
-   */
-  getSelectedOption: (value: Record<string, unknown>) => string
-  /**
-   * Get the selected field from a value.
-   * Combines getSelectedOption and getField for convenience.
-   *
-   * @example
-   * ```tsx
-   * // Current (verbose):
-   * const validKeys = Object.keys(currentValue).filter(k => field.options.includes(k))
-   * const selected = validKeys[0] ?? field.options[0]
-   * const selectedIndex = Math.max(0, field.options.indexOf(selected))
-   * const selectedField = field.fields[selectedIndex]
-   *
-   * // Proposed (simple):
-   * const selectedField = field.getSelectedField(currentValue)
-   * ```
-   */
-  getSelectedField: (value: Record<string, unknown>) => Field
-}
-
-export interface TupleField extends FieldBase<unknown[]> {
-  type: "tuple"
-  /** Tuple element fields in order */
-  fields: Field[]
-}
-
-export interface OptionalField extends FieldBase<null> {
-  type: "optional"
-  /** 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
-  /**
-   * Check if a value represents an enabled optional.
-   * Returns true if the value is not null or undefined.
-   *
-   * @example
-   * ```tsx
-   * // Current:
-   * const enabled = fieldApi.state.value !== null && typeof fieldApi.state.value !== "undefined"
-   *
-   * // Proposed:
-   * const enabled = field.isEnabled(fieldApi.state.value)
-   * ```
-   */
-  isEnabled: (value: unknown) => boolean
-}
-
-export interface VectorField extends FieldBase<unknown[]> {
-  type: "vector"
-  /** 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
-  /**
-   * Create a properly configured item field for a specific index.
-   * Handles name path and label generation.
-   *
-   * @example
-   * ```tsx
-   * // Current:
-   * renderField({
-   *   ...field.itemField,
-   *   label: itemLabel,
-   *   name: itemFieldName
-   * })
-   *
-   * // Proposed:
-   * const itemField = field.createItemField(index, { label: itemLabel })
-   * renderField(itemField)
-   * ```
-   */
-  createItemField: (index: number, overrides?: { label?: string }) => Field
-}
-
 /**
  * Blob field size limits.
  */
@@ -361,151 +146,166 @@ export interface BlobValidationResult {
   error?: string
 }
 
-export interface BlobField extends FieldBase<string> {
-  type: "blob"
-  /** Item field for individual bytes (nat8) */
-  itemField: Field
-  /** Accepted input formats */
-  acceptedFormats: ("hex" | "base64" | "file")[]
-  /** Size limits for blob input */
-  limits: BlobLimits
-  /**
-   * Normalize hex input (remove 0x prefix, lowercase, etc.)
-   *
-   * @example
-   * ```tsx
-   * const normalized = field.normalizeHex("0xDEADBEEF")
-   * // => "deadbeef"
-   * ```
-   */
-  normalizeHex: (input: string) => string
-  /**
-   * Validate blob input value.
-   *
-   * @example
-   * ```tsx
-   * const result = field.validateInput(value)
-   * if (!result.valid) {
-   *   setError(result.error)
-   * }
-   * ```
-   */
-  validateInput: (value: string | Uint8Array) => BlobValidationResult
-}
-
-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: () => Field
-  /**
-   * Get default value for the recursive type.
-   * Evaluates the inner type on demand.
-   */
-  getInnerDefault: () => unknown
-}
-
-// ════════════════════════════════════════════════════════════════════════════
-// Primitive Types
-// ════════════════════════════════════════════════════════════════════════════
-
-export interface PrincipalField extends FieldBase<string> {
-  type: "principal"
-  maxLength: number
-  minLength: number
-  /**
-   * Pre-computed HTML input props for direct spreading.
-   * @example
-   * ```tsx
-   * <input {...field.inputProps} value={value} onChange={handleChange} />
-   * ```
-   */
-  inputProps: PrimitiveInputProps
-}
-
-export interface NumberField extends FieldBase<string> {
-  type: "number"
-  /**
-   * 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
-  /**
-   * Pre-computed HTML input props for direct spreading.
-   * @example
-   * ```tsx
-   * <input {...field.inputProps} value={value} onChange={handleChange} />
-   * ```
-   */
-  inputProps: PrimitiveInputProps
-}
-
-export interface TextField extends FieldBase<string> {
-  type: "text"
-  /** Minimum length constraint */
-  minLength?: number
-  /** Maximum length constraint */
-  maxLength?: number
-  /** Whether to render as multiline textarea */
-  multiline?: boolean
-  /**
-   * Pre-computed HTML input props for direct spreading.
-   * @example
-   * ```tsx
-   * <input {...field.inputProps} value={value} onChange={handleChange} />
-   * ```
-   */
-  inputProps: PrimitiveInputProps
-}
-
-export interface BooleanField extends FieldBase<boolean> {
-  type: "boolean"
-  /**
-   * Pre-computed HTML input props for direct spreading.
-   * @example
-   * ```tsx
-   * <input {...field.inputProps} checked={value} onChange={handleChange} />
-   * ```
-   */
-  inputProps: PrimitiveInputProps
-}
-
-export interface NullField extends FieldBase<null> {
-  type: "null"
-}
-
-export interface UnknownField extends FieldBase<undefined> {
-  type: "unknown"
-}
+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>
+    }
+  : 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
+      }
+    : T extends "tuple"
+      ? {
+          /** Tuple element fields in order */
+          fields: FieldNode[]
+          defaultValue: unknown[]
+        }
+      : 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
+          }
+        : 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
+            }
+          : 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
+              }
+            : 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
+                }
+              : T extends "principal"
+                ? {
+                    maxLength: number
+                    minLength: number
+                    /** Detected format based on label heuristics */
+                    format: TextFormat
+                    /** Pre-computed HTML input props */
+                    inputProps: PrimitiveInputProps
+                    defaultValue: string
+                  }
+                : 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
+                    }
+                  : 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
+                      }
+                    : T extends "boolean"
+                      ? {
+                          /** Pre-computed HTML input props */
+                          inputProps: PrimitiveInputProps
+                          defaultValue: boolean
+                        }
+                      : T extends "null"
+                        ? {
+                            defaultValue: null
+                          }
+                        : T extends "unknown"
+                          ? {
+                              defaultValue: undefined
+                            }
+                          : {}
 
-// ════════════════════════════════════════════════════════════════════════════
-// Union Type
-// ════════════════════════════════════════════════════════════════════════════
-
-export type Field =
-  | RecordField
-  | VariantField
-  | TupleField
-  | OptionalField
-  | VectorField
-  | BlobField
-  | RecursiveField
-  | PrincipalField
-  | NumberField
-  | TextField
-  | BooleanField
-  | NullField
-  | UnknownField
+/**
+ * A unified field node that contains all metadata needed for rendering.
+ */
+export type FieldNode<T extends VisitorDataType = VisitorDataType> =
+  FieldBase<T> & FieldExtras<T>
+
+export type RecordField = FieldNode<"record">
+export type VariantField = FieldNode<"variant">
+export type TupleField = FieldNode<"tuple">
+export type OptionalField = FieldNode<"optional">
+export type VectorField = FieldNode<"vector">
+export type BlobField = FieldNode<"blob">
+export type RecursiveField = FieldNode<"recursive">
+export type PrincipalField = FieldNode<"principal">
+export type NumberField = FieldNode<"number">
+export type TextField = FieldNode<"text">
+export type BooleanField = FieldNode<"boolean">
+export type NullField = FieldNode<"null">
+export type UnknownField = FieldNode<"unknown">
 
 // ════════════════════════════════════════════════════════════════════════════
 // Form Metadata - TanStack Form Integration
@@ -514,31 +314,6 @@ export type Field =
 /**
  * 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,
@@ -549,7 +324,7 @@ export interface ArgumentsMeta<
   /** The function name */
   functionName: Name
   /** Argument field definitions for rendering */
-  fields: Field[]
+  fields: FieldNode[]
   /** Default values for all arguments (as a tuple) */
   defaultValues: unknown[]
   /** Combined Zod schema for all arguments */
@@ -588,30 +363,17 @@ export type ArgumentsServiceMeta<A = BaseActor> = {
 
 /** Extract a specific field type */
 export type FieldByType<T extends ArgumentFieldType> = Extract<
-  Field,
+  FieldNode,
   { type: T }
 >
 
 /**
  * Props type helper for field components.
  * Use this to type your field components for better DX.
- *
- * @example
- * ```tsx
- * const VariantField: React.FC<FieldProps<'variant'>> = ({ field, renderField }) => {
- *   // field is properly typed as VariantField
- *   return (
- *     <div>
- *       <select>{field.options.map(opt => ...)}</select>
- *       {renderField?.(field.getSelectedField(currentValue))}
- *     </div>
- *   )
- * }
- * ```
  */
 export type FieldProps<T extends ArgumentFieldType> = {
   field: FieldByType<T>
-  renderField?: (child: Field) => React.ReactNode
+  renderField?: (child: FieldNode) => React.ReactNode
 }
 
 /** Compound field types that contain other fields */
@@ -630,31 +392,3 @@ export type PrimitiveField =
   | TextField
   | BooleanField
   | NullField
-
-/**
- * A complete mapping of component types to React components.
- * Use this type when defining your component map.
- *
- * @example
- * ```tsx
- * const componentMap: ComponentMap<typeof MyTextInput, typeof MyNumberInput, ...> = {
- *   'text-input': MyTextInput,
- *   'number-input': MyNumberInput,
- *   // ...
- * }
- * ```
- */
-export type ComponentMap<
-  TComponents extends Record<FieldComponentType, unknown>,
-> = {
-  [K in FieldComponentType]: TComponents[K]
-}
-
-/**
- * Get the component type for a given field component type.
- * Useful for typing dynamic component lookups.
- */
-export type GetComponentType<
-  TMap extends Partial<Record<FieldComponentType, unknown>>,
-  TKey extends FieldComponentType,
-> = TKey extends keyof TMap ? TMap[TKey] : never