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

package/src/visitor/arguments/types.ts

@@ -1,246 +1,311 @@
 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"
+export type ArgumentFieldType = VisitorDataType
+
+// ════════════════════════════════════════════════════════════════════════════
+// Component Type Hints
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Suggested component type for rendering the field.
+ * This eliminates the need for switch statements in the frontend.
+ */
+export type FieldComponentType =
+  | "record-container"
+  | "tuple-container"
+  | "variant-select"
+  | "optional-toggle"
+  | "vector-list"
+  | "blob-upload"
+  | "principal-input"
+  | "text-input"
+  | "number-input"
+  | "boolean-checkbox"
+  | "null-hidden"
+  | "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"
-  | "boolean"
-  | "null"
-  | "unknown"
+  | "number"
+  | "checkbox"
+  | "select"
+  | "file"
+  | "textarea"
+
+/**
+ * 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
+}
 
 // ════════════════════════════════════════════════════════════════════════════
-// UI Hints for Form Rendering
+// Primitive Input Props
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface FieldUIHints {
-  /** Placeholder text for the input */
+/**
+ * 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
-  /** 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
+  /** 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
 }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Base Field Interface
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface FieldBase<TValue = unknown> {
+interface FieldBase<T extends VisitorDataType = VisitorDataType> {
   /** The field type */
-  type: ArgumentFieldType
-  /** Human-readable label from Candid */
+  type: T
+  /** Raw label from Candid: "__arg0", "_0_" */
   label: 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>
-   * ```
-   */
+  /** Pre-formatted display label for UI rendering */
+  displayLabel: string
+  /** Form field name path for binding */
   name: string
+  /** Suggested component type for rendering this field */
+  component: FieldComponentType
+  /** 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
-  /** UI rendering hints */
-  ui?: FieldUIHints
-}
-
-// ════════════════════════════════════════════════════════════════════════════
-// Compound Types
-// ════════════════════════════════════════════════════════════════════════════
-
-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>
-}
-
-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
-}
-
-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
-}
-
-export interface BlobField extends FieldBase<string> {
-  type: "blob"
-  /** Item field for individual bytes (nat8) */
-  itemField: Field
-  /** Accepted input formats */
-  acceptedFormats: ("hex" | "base64" | "file")[]
-}
-
-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
+  candidType: string
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Primitive Types
+// Type-Specific Extras
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface PrincipalField extends FieldBase<string> {
-  type: "principal"
-  maxLength: number
-  minLength: number
-}
-
-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
-}
-
-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
-}
-
-export interface BooleanField extends FieldBase<boolean> {
-  type: "boolean"
-}
-
-export interface NullField extends FieldBase<null> {
-  type: "null"
+/**
+ * Blob field size limits.
+ */
+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
 }
 
-export interface UnknownField extends FieldBase<undefined> {
-  type: "unknown"
+/**
+ * Validation result for blob input.
+ */
+export interface BlobValidationResult {
+  /** Whether the input is valid */
+  valid: boolean
+  /** Error message if invalid */
+  error?: string
 }
 
-// ════════════════════════════════════════════════════════════════════════════
-// Union Type
-// ════════════════════════════════════════════════════════════════════════════
+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
+                            }
+                          : {}
 
-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
@@ -249,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,
@@ -284,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 */
@@ -323,10 +363,19 @@ 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.
+ */
+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
@@ -343,52 +392,3 @@ export type PrimitiveField =
   | 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/returns/types.ts

@@ -4,25 +4,15 @@ import type {
   FunctionType,
   ActorMethodReturnType,
 } from "@ic-reactor/core"
+import type { VisitorDataType, TextFormat, NumberFormat } from "../types"
+
+export type { TextFormat, NumberFormat }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Core Types & Formats
 // ════════════════════════════════════════════════════════════════════════════
 
-export type NodeType =
-  | "record"
-  | "variant"
-  | "tuple"
-  | "optional"
-  | "vector"
-  | "blob"
-  | "recursive"
-  | "principal"
-  | "number"
-  | "text"
-  | "boolean"
-  | "null"
-  | "unknown"
+export type NodeType = VisitorDataType
 
 export type DisplayType =
   | "string"
@@ -38,19 +28,6 @@ export type DisplayType =
   | "blob"
   | "unknown"
 
-export type NumberFormat = "timestamp" | "cycle" | "value" | "token" | "normal"
-export type TextFormat =
-  | "plain"
-  | "timestamp"
-  | "uuid"
-  | "url"
-  | "email"
-  | "phone"
-  | "btc"
-  | "eth"
-  | "account-id"
-  | "principal"
-
 // ════════════════════════════════════════════════════════════════════════════
 // Unified Result Node - Single Structure for Schema & Resolved Data
 // ════════════════════════════════════════════════════════════════════════════