@ic-reactor/candid 3.0.11-beta.2 → 3.0.13-beta.0

package/dist/visitor/arguments/index.js

@@ -1,8 +1,86 @@
 import { isQuery } from "../helpers";
-import { IDL } from "../types";
+import { IDL } from "@icp-sdk/core/candid";
+import { Principal } from "@icp-sdk/core/principal";
+import * as z from "zod";
+import { formatLabel } from "./helpers";
 export * from "./types";
+// ════════════════════════════════════════════════════════════════════════════
+// Render Hint Helpers
+// ════════════════════════════════════════════════════════════════════════════
+const COMPOUND_RENDER_HINT = {
+    isCompound: true,
+    isPrimitive: false,
+};
+const TEXT_RENDER_HINT = {
+    isCompound: false,
+    isPrimitive: true,
+    inputType: "text",
+};
+const NUMBER_RENDER_HINT = {
+    isCompound: false,
+    isPrimitive: true,
+    inputType: "number",
+};
+const CHECKBOX_RENDER_HINT = {
+    isCompound: false,
+    isPrimitive: true,
+    inputType: "checkbox",
+};
+const FILE_RENDER_HINT = {
+    isCompound: false,
+    isPrimitive: true,
+    inputType: "file",
+};
+// ════════════════════════════════════════════════════════════════════════════
+// Blob Field Helpers
+// ════════════════════════════════════════════════════════════════════════════
+const DEFAULT_BLOB_LIMITS = {
+    maxHexBytes: 512,
+    maxFileBytes: 2 * 1024 * 1024, // 2MB
+    maxHexDisplayLength: 128,
+};
+function normalizeHex(input) {
+    // 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, limits) {
+    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
  *
@@ -10,55 +88,84 @@ export * from "./types";
  * 2. **No value dependencies** - metadata is independent of actual values
  * 3. **Form-framework agnostic** - output can be used with TanStack, React Hook Form, etc.
  * 4. **Efficient** - single traversal, no runtime type checking
+ * 5. **TanStack Form optimized** - name paths compatible with TanStack Form patterns
  *
  * ## Output Structure
  *
  * Each field has:
  * - `type`: The field type (record, variant, text, number, etc.)
- * - `label`: Human-readable label from Candid
- * - `path`: Dot-notation path for form binding (e.g., "0.owner")
+ * - `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.)
+ * - Helper methods for dynamic forms (getOptionDefault, getItemDefault, etc.)
+ *
+ * ## Usage with TanStack Form
  *
  * @example
  * ```typescript
- * const visitor = new ArgumentFieldVisitor()
- * const serviceMeta = service.accept(visitor, null)
+ * import { useForm } from '@tanstack/react-form'
+ * import { FieldVisitor } from '@ic-reactor/candid'
  *
- * // For a specific method
+ * const visitor = new FieldVisitor()
+ * const serviceMeta = service.accept(visitor, null)
  * const methodMeta = serviceMeta["icrc1_transfer"]
- * // methodMeta.fields = [{ type: "record", fields: [...] }]
- * // methodMeta.defaultValues = [{ to: "", amount: "" }]
+ *
+ * const form = useForm({
+ *   defaultValues: methodMeta.defaultValue,
+ *   validators: { onBlur: methodMeta.schema },
+ *   onSubmit: async ({ value }) => {
+ *     await actor.icrc1_transfer(...value)
+ *   }
+ * })
+ *
+ * // Render fields dynamically
+ * methodMeta.fields.map((field, index) => (
+ *   <form.Field key={index} name={field.name}>
+ *     {(fieldApi) => <DynamicInput field={field} fieldApi={fieldApi} />}
+ *   </form.Field>
+ * ))
  * ```
  */
-export class ArgumentFieldVisitor extends IDL.Visitor {
+export class FieldVisitor extends IDL.Visitor {
     constructor() {
         super(...arguments);
-        Object.defineProperty(this, "pathStack", {
+        Object.defineProperty(this, "recursiveSchemas", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "nameStack", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: []
         });
     }
-    withPath(path, fn) {
-        this.pathStack.push(path);
+    /**
+     * Execute function with a name segment pushed onto the stack.
+     * Automatically manages stack cleanup.
+     */
+    withName(name, fn) {
+        this.nameStack.push(name);
         try {
             return fn();
         }
         finally {
-            this.pathStack.pop();
+            this.nameStack.pop();
         }
     }
-    currentPath() {
-        return this.pathStack[this.pathStack.length - 1] ?? "";
-    }
-    childPath(key) {
-        const parent = this.currentPath();
-        if (typeof key === "number") {
-            return parent ? `${parent}[${key}]` : String(key);
-        }
-        return parent ? `${parent}.${key}` : key;
+    /**
+     * Get the current full name path for form binding.
+     * Returns empty string for root level.
+     */
+    currentName() {
+        return this.nameStack.join("");
     }
     // ════════════════════════════════════════════════════════════════════════
     // Service & Function Level
@@ -72,206 +179,486 @@ export class ArgumentFieldVisitor extends IDL.Visitor {
     }
     visitFunc(t, functionName) {
         const functionType = isQuery(t) ? "query" : "update";
+        const argCount = t.argTypes.length;
         const fields = t.argTypes.map((arg, index) => {
-            return this.withPath(`[${index}]`, () => arg.accept(this, `__arg${index}`));
+            return this.withName(`[${index}]`, () => arg.accept(this, `__arg${index}`));
         });
-        const defaultValues = fields.map((field) => this.extractDefaultValue(field));
+        const defaultValues = fields.map((field) => field.defaultValue);
+        // Handle empty args case for schema
+        // For no-arg functions, use an empty array schema
+        // For functions with args, use a proper tuple schema
+        const schema = argCount === 0
+            ? z.tuple([])
+            : z.tuple(fields.map((field) => field.schema));
         return {
             functionType,
             functionName,
             fields,
-            defaultValues,
+            defaultValues: defaultValues,
+            schema,
+            argCount,
+            isNoArgs: argCount === 0,
         };
     }
-    extractDefaultValue(field) {
-        if ("defaultValue" in field) {
-            return field.defaultValue;
-        }
-        if ("defaultValues" in field) {
-            return field.defaultValues;
-        }
-        return undefined;
-    }
     // ════════════════════════════════════════════════════════════════════════
     // Compound Types
     // ════════════════════════════════════════════════════════════════════════
     visitRecord(_t, fields_, label) {
-        const path = this.currentPath();
+        const name = this.currentName();
         const fields = [];
-        const defaultValues = {};
+        const fieldMap = new Map();
+        const defaultValue = {};
+        const schemaShape = {};
         for (const [key, type] of fields_) {
-            const field = this.withPath(this.childPath(key), () => type.accept(this, key));
+            const field = this.withName(name ? `.${key}` : key, () => type.accept(this, key));
             fields.push(field);
-            defaultValues[key] = this.extractDefaultValue(field);
+            fieldMap.set(key, field);
+            defaultValue[key] = field.defaultValue;
+            schemaShape[key] = field.schema;
         }
+        const schema = z.object(schemaShape);
         return {
             type: "record",
             label,
-            path,
+            displayLabel: formatLabel(label),
+            name,
+            component: "record-container",
+            renderHint: COMPOUND_RENDER_HINT,
             fields,
-            defaultValues,
+            fieldMap,
+            defaultValue,
+            schema,
+            candidType: "record",
         };
     }
     visitVariant(_t, fields_, label) {
-        const path = this.currentPath();
+        const name = this.currentName();
         const fields = [];
         const options = [];
+        const optionMap = new Map();
+        const variantSchemas = [];
         for (const [key, type] of fields_) {
-            const field = this.withPath(this.childPath(key), () => type.accept(this, key));
+            const field = this.withName(`.${key}`, () => type.accept(this, key));
             fields.push(field);
             options.push(key);
+            optionMap.set(key, field);
+            variantSchemas.push(z.object({ [key]: field.schema }));
         }
         const defaultOption = options[0];
-        const defaultValues = {
-            [defaultOption]: this.extractDefaultValue(fields[0]),
+        const firstField = fields[0];
+        const defaultValue = {
+            [defaultOption]: firstField.defaultValue,
+        };
+        const schema = z.union(variantSchemas);
+        // Helper to get default value for any option
+        const getOptionDefault = (option) => {
+            const optField = optionMap.get(option);
+            if (!optField) {
+                throw new Error(`Unknown variant option: ${option}`);
+            }
+            return { [option]: optField.defaultValue };
+        };
+        // Helper to get field for a specific option
+        const getField = (option) => {
+            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) => {
+            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) => {
+            const selectedOption = getSelectedOption(value);
+            return getField(selectedOption);
         };
         return {
             type: "variant",
             label,
-            path,
+            displayLabel: formatLabel(label),
+            name,
+            component: "variant-select",
+            renderHint: COMPOUND_RENDER_HINT,
             fields,
             options,
             defaultOption,
-            defaultValues,
+            optionMap,
+            defaultValue,
+            schema,
+            getOptionDefault,
+            getField,
+            getSelectedOption,
+            getSelectedField,
+            candidType: "variant",
         };
     }
     visitTuple(_t, components, label) {
-        const path = this.currentPath();
+        const name = this.currentName();
         const fields = [];
-        const defaultValues = [];
+        const defaultValue = [];
+        const schemas = [];
         for (let index = 0; index < components.length; index++) {
             const type = components[index];
-            const field = this.withPath(this.childPath(index), () => type.accept(this, `_${index}_`));
+            const field = this.withName(`[${index}]`, () => type.accept(this, `_${index}_`));
             fields.push(field);
-            defaultValues.push(this.extractDefaultValue(field));
+            defaultValue.push(field.defaultValue);
+            schemas.push(field.schema);
         }
+        const schema = z.tuple(schemas);
         return {
             type: "tuple",
             label,
-            path,
+            displayLabel: formatLabel(label),
+            name,
+            component: "tuple-container",
+            renderHint: COMPOUND_RENDER_HINT,
             fields,
-            defaultValues,
+            defaultValue,
+            schema,
+            candidType: "tuple",
         };
     }
     visitOpt(_t, ty, label) {
-        const path = this.currentPath();
-        const innerField = this.withPath(this.childPath(0), () => ty.accept(this, label));
+        const name = this.currentName();
+        // For optional, the inner field keeps the same name path
+        // because the value replaces null directly (not nested)
+        const innerField = ty.accept(this, label);
+        const schema = z.union([
+            innerField.schema,
+            z.null(),
+            z.undefined().transform(() => null),
+            z.literal("").transform(() => null),
+        ]);
+        // Helper to get the inner default when enabling the optional
+        const getInnerDefault = () => innerField.defaultValue;
+        // Helper to check if a value represents an enabled optional
+        const isEnabled = (value) => {
+            return value !== null && typeof value !== "undefined";
+        };
         return {
             type: "optional",
             label,
-            path,
+            displayLabel: formatLabel(label),
+            name,
+            component: "optional-toggle",
+            renderHint: COMPOUND_RENDER_HINT,
             innerField,
             defaultValue: null,
+            schema,
+            getInnerDefault,
+            isEnabled,
+            candidType: "opt",
         };
     }
     visitVec(_t, ty, label) {
-        const path = this.currentPath();
+        const name = this.currentName();
         // Check if it's blob (vec nat8)
         const isBlob = ty instanceof IDL.FixedNatClass && ty._bits === 8;
-        const itemField = this.withPath(this.childPath(0), () => ty.accept(this, label));
+        // Item field uses [0] as template path
+        const itemField = this.withName("[0]", () => ty.accept(this, `${label}_item`));
         if (isBlob) {
+            const schema = z.union([
+                z.string(),
+                z.array(z.number()),
+                z.instanceof(Uint8Array),
+            ]);
+            const limits = { ...DEFAULT_BLOB_LIMITS };
             return {
                 type: "blob",
                 label,
-                path,
+                displayLabel: formatLabel(label),
+                name,
+                component: "blob-upload",
+                renderHint: FILE_RENDER_HINT,
                 itemField,
                 defaultValue: "",
+                schema,
+                acceptedFormats: ["hex", "base64", "file"],
+                limits,
+                normalizeHex,
+                validateInput: (value) => validateBlobInput(value, limits),
+                candidType: "blob",
             };
         }
+        const schema = z.array(itemField.schema);
+        // Helper to get a new item with default values
+        const getItemDefault = () => itemField.defaultValue;
+        // Helper to create an item field for a specific index
+        const createItemField = (index, overrides) => {
+            // 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,
-            path,
+            displayLabel: formatLabel(label),
+            name,
+            component: "vector-list",
+            renderHint: COMPOUND_RENDER_HINT,
             itemField,
             defaultValue: [],
+            schema,
+            getItemDefault,
+            createItemField,
+            candidType: "vec",
         };
     }
     visitRec(_t, ty, label) {
-        const path = this.currentPath();
+        const name = this.currentName();
+        const typeName = ty.name || "RecursiveType";
+        let schema;
+        if (this.recursiveSchemas.has(typeName)) {
+            schema = this.recursiveSchemas.get(typeName);
+        }
+        else {
+            schema = z.lazy(() => ty.accept(this, label).schema);
+            this.recursiveSchemas.set(typeName, schema);
+        }
+        // Lazy extraction to prevent infinite loops
+        const extract = () => this.withName(name, () => ty.accept(this, label));
+        // Helper to get inner default (evaluates lazily)
+        const getInnerDefault = () => extract().defaultValue;
         return {
             type: "recursive",
             label,
-            path,
-            // Lazy extraction to prevent infinite loops
-            extract: () => this.withPath(path, () => ty.accept(this, label)),
+            displayLabel: formatLabel(label),
+            name,
+            component: "recursive-lazy",
+            renderHint: COMPOUND_RENDER_HINT,
+            typeName,
+            extract,
+            defaultValue: undefined,
+            schema,
+            getInnerDefault,
+            candidType: "rec",
         };
     }
     // ════════════════════════════════════════════════════════════════════════
     // Primitive Types
     // ════════════════════════════════════════════════════════════════════════
     visitPrincipal(_t, label) {
+        const schema = z.custom((val) => {
+            if (val instanceof Principal)
+                return true;
+            if (typeof val === "string") {
+                try {
+                    Principal.fromText(val);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+            return false;
+        }, {
+            message: "Invalid Principal format",
+        });
+        const inputProps = {
+            type: "text",
+            placeholder: "aaaaa-aa or full principal ID",
+            minLength: 7,
+            maxLength: 64,
+            spellCheck: false,
+            autoComplete: "off",
+        };
         return {
             type: "principal",
             label,
-            path: this.currentPath(),
+            displayLabel: formatLabel(label),
+            name: this.currentName(),
+            component: "principal-input",
+            renderHint: TEXT_RENDER_HINT,
             defaultValue: "",
             maxLength: 64,
             minLength: 7,
+            schema,
+            inputProps,
+            candidType: "principal",
         };
     }
     visitText(_t, label) {
+        const inputProps = {
+            type: "text",
+            placeholder: "Enter text...",
+            spellCheck: true,
+        };
         return {
             type: "text",
             label,
-            path: this.currentPath(),
+            displayLabel: formatLabel(label),
+            name: this.currentName(),
+            component: "text-input",
+            renderHint: TEXT_RENDER_HINT,
             defaultValue: "",
+            schema: z.string().min(1, "Required"),
+            inputProps,
+            candidType: "text",
         };
     }
     visitBool(_t, label) {
+        const inputProps = {
+            type: "checkbox",
+        };
         return {
             type: "boolean",
             label,
-            path: this.currentPath(),
+            displayLabel: formatLabel(label),
+            name: this.currentName(),
+            component: "boolean-checkbox",
+            renderHint: CHECKBOX_RENDER_HINT,
             defaultValue: false,
+            schema: z.boolean(),
+            inputProps,
+            candidType: "bool",
         };
     }
     visitNull(_t, label) {
         return {
             type: "null",
             label,
-            path: this.currentPath(),
+            displayLabel: formatLabel(label),
+            name: this.currentName(),
+            component: "null-hidden",
+            renderHint: {
+                isCompound: false,
+                isPrimitive: true,
+            },
             defaultValue: null,
+            schema: z.null(),
+            candidType: "null",
         };
     }
-    // Numbers - all use string for display format
-    visitNumberType(label, candidType) {
+    // ════════════════════════════════════════════════════════════════════════
+    // Number Types with Constraints
+    // ════════════════════════════════════════════════════════════════════════
+    visitNumberType(label, candidType, options) {
+        let schema = z.string().min(1, "Required");
+        if (options.isFloat) {
+            schema = schema.refine((val) => !isNaN(Number(val)), "Must be a number");
+        }
+        else if (options.unsigned) {
+            schema = schema.regex(/^\d+$/, "Must be a positive number");
+        }
+        else {
+            schema = schema.regex(/^-?\d+$/, "Must be a number");
+        }
+        // Use "text" type for large numbers (BigInt) to ensure precision and better UI handling
+        // Standard number input has issues with large integers
+        const isBigInt = !options.isFloat && (!options.bits || options.bits > 32);
+        const type = isBigInt ? "text" : "number";
+        if (type === "text") {
+            const inputProps = {
+                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: "",
+                candidType,
+                schema,
+                inputProps,
+            };
+        }
+        const inputProps = {
+            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,
-            path: this.currentPath(),
+            displayLabel: formatLabel(label),
+            name: this.currentName(),
+            component: "number-input",
+            renderHint: NUMBER_RENDER_HINT,
             defaultValue: "",
             candidType,
+            schema: schema,
+            inputProps,
+            ...options,
         };
     }
     visitInt(_t, label) {
-        return this.visitNumberType(label, "int");
+        return this.visitNumberType(label, "int", {
+            unsigned: false,
+            isFloat: false,
+        });
     }
     visitNat(_t, label) {
-        return this.visitNumberType(label, "nat");
+        return this.visitNumberType(label, "nat", {
+            unsigned: true,
+            isFloat: false,
+        });
     }
-    visitFloat(_t, label) {
-        return this.visitNumberType(label, "float");
+    visitFloat(t, label) {
+        return this.visitNumberType(label, `float${t._bits}`, {
+            unsigned: false,
+            isFloat: true,
+            bits: t._bits,
+        });
     }
     visitFixedInt(t, label) {
-        return this.visitNumberType(label, `int${t._bits}`);
+        const bits = t._bits;
+        // Calculate min/max for signed integers
+        const max = (BigInt(2) ** BigInt(bits - 1) - BigInt(1)).toString();
+        const min = (-(BigInt(2) ** BigInt(bits - 1))).toString();
+        return this.visitNumberType(label, `int${bits}`, {
+            unsigned: false,
+            isFloat: false,
+            bits,
+            min,
+            max,
+        });
     }
     visitFixedNat(t, label) {
-        return this.visitNumberType(label, `nat${t._bits}`);
+        const bits = t._bits;
+        // Calculate max for unsigned integers
+        const max = (BigInt(2) ** BigInt(bits) - BigInt(1)).toString();
+        return this.visitNumberType(label, `nat${bits}`, {
+            unsigned: true,
+            isFloat: false,
+            bits,
+            min: "0",
+            max,
+        });
     }
     visitType(_t, label) {
         return {
             type: "unknown",
             label,
-            path: this.currentPath(),
+            displayLabel: formatLabel(label),
+            name: this.currentName(),
+            component: "unknown-fallback",
+            renderHint: {
+                isCompound: false,
+                isPrimitive: false,
+            },
             defaultValue: undefined,
+            schema: z.any(),
         };
     }
 }
-// ════════════════════════════════════════════════════════════════════════════
-// Legacy Exports (for backward compatibility)
-// ════════════════════════════════════════════════════════════════════════════
-/**
- * @deprecated Use ArgumentFieldVisitor instead
- */
-export { ArgumentFieldVisitor as VisitTanstackField };
 //# sourceMappingURL=index.js.map