@zod-to-form/vite 0.1.1

package/dist/generate-mode/scan-jsx.js

@@ -0,0 +1,161 @@
+/**
+ * scanJsx — find candidate `<ZodForm schema={X}>` JSX elements in a source
+ * file. Pure: no I/O, no plugin context. Reports both candidate sites and
+ * skip diagnostics so the caller can buffer them through the logger.
+ *
+ * The substring fast-path is critical: most files in a typical project
+ * don't contain `'ZodForm'` anywhere, so a single `indexOf` check keeps
+ * generate-mode's per-file cost at zero for the common case (research R3).
+ *
+ * The Babel visitor only fires on `JSXElement` nodes. The traversal still
+ * walks the full AST — that's how `@babel/traverse` works — but the per-
+ * node cost outside the visitor is just a type check, so even a 5000-line
+ * file with one `<ZodForm>` call site stays cheap to scan in practice.
+ */
+import { parse } from '@babel/parser';
+import { traverse } from './babel-traverse.js';
+/**
+ * Scan a source string for `<ZodForm>` JSX elements. Returns candidates
+ * for further validation by `resolveSchema` plus an array of sites that
+ * structurally don't qualify (and thus need a DEBUG diagnostic).
+ *
+ * Returns `null` (a discriminator distinct from "scanned and found
+ * nothing") when the substring fast-path filtered the file out — the
+ * caller can short-circuit before allocating anything else.
+ *
+ * On a Babel parse failure, returns a `ScanResult` with zero candidates
+ * and a single skip diagnostic naming the parser error so it surfaces
+ * in the buildEnd summary. We deliberately don't propagate the parse
+ * error — Vite's main pipeline will report the user's syntax problem
+ * elsewhere with better context.
+ */
+export function scanJsx(source) {
+    // Substring fast-path. Most files won't contain ZodForm at all.
+    if (source.indexOf('ZodForm') === -1)
+        return null;
+    let ast;
+    try {
+        ast = parse(source, {
+            sourceType: 'module',
+            plugins: ['jsx', 'typescript'],
+            errorRecovery: false
+        });
+    }
+    catch (err) {
+        // Surface the parse failure as a buffered skip so the user sees one
+        // line in the buildEnd generate-mode summary instead of silently
+        // missing the transform. The parse error itself still propagates
+        // through Vite's normal pipeline and the user fixes it there.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            candidates: [],
+            skipped: [{ loc: { line: 0, column: 0 }, reason: `babel parse failed: ${message}` }]
+        };
+    }
+    const candidates = [];
+    const skipped = [];
+    traverse(ast, {
+        JSXElement(path) {
+            const opening = path.node.openingElement;
+            const nameNode = opening.name;
+            // Element name MUST be a bare `JSXIdentifier`, not `JSXMemberExpression`
+            // or `JSXNamespacedName`. `<x.ZodForm>` and `<x:ZodForm>` are skipped.
+            if (nameNode.type !== 'JSXIdentifier') {
+                // Only flag this as a skip if the rendered text actually contains
+                // `ZodForm` — otherwise we'd noise up the log with every member-
+                // expression element in the file.
+                if (containsZodForm(nameNode)) {
+                    skipped.push({
+                        loc: locOf(path.node),
+                        reason: 'JSX element uses member-expression name (e.g. <ns.ZodForm/>); only bare <ZodForm> is matched'
+                    });
+                }
+                return;
+            }
+            if (nameNode.name !== 'ZodForm')
+                return;
+            const loc = locOf(path.node);
+            // Find the schema attribute and collect all the others.
+            const attributes = [];
+            let schemaAttr = null;
+            for (const attr of opening.attributes) {
+                const range = rangeOf(attr);
+                const slice = source.slice(range.start, range.end);
+                if (attr.type === 'JSXSpreadAttribute') {
+                    attributes.push({ kind: 'spread', range, source: slice });
+                    continue;
+                }
+                const jsxAttr = attr;
+                const attrName = jsxAttr.name.type === 'JSXIdentifier' ? jsxAttr.name.name : null;
+                if (attrName !== null) {
+                    attributes.push({ kind: 'named', name: attrName, range, source: slice });
+                    if (attrName === 'schema')
+                        schemaAttr = jsxAttr;
+                }
+            }
+            if (schemaAttr === null) {
+                skipped.push({ loc, reason: '<ZodForm> has no schema={...} prop' });
+                return;
+            }
+            // schema must be a JSXExpressionContainer wrapping an Identifier.
+            const value = schemaAttr.value;
+            if (value === null || value === undefined || value.type !== 'JSXExpressionContainer') {
+                skipped.push({
+                    loc,
+                    reason: 'schema prop is not a JSXExpressionContainer (use schema={identifier})'
+                });
+                return;
+            }
+            const expr = value.expression;
+            if (expr.type !== 'Identifier') {
+                skipped.push({
+                    loc,
+                    reason: `schema prop expression is ${expr.type}, expected Identifier`
+                });
+                return;
+            }
+            const openingRange = rangeOf(opening);
+            const closingRange = path.node.closingElement === null || path.node.closingElement === undefined
+                ? null
+                : rangeOf(path.node.closingElement);
+            const childrenSource = closingRange === null ? '' : source.slice(openingRange.end, closingRange.start);
+            candidates.push({
+                openingRange,
+                closingRange,
+                loc,
+                selfClosing: opening.selfClosing,
+                attributes,
+                schemaIdentifier: expr.name,
+                childrenSource
+            });
+        }
+    });
+    return { candidates, skipped };
+}
+function rangeOf(node) {
+    if (node.start === null ||
+        node.start === undefined ||
+        node.end === null ||
+        node.end === undefined) {
+        throw new Error('Babel AST node missing byte range — parser was misconfigured');
+    }
+    return { start: node.start, end: node.end };
+}
+function locOf(node) {
+    const loc = node.loc;
+    if (loc === null || loc === undefined) {
+        return { line: 0, column: 0 };
+    }
+    return { line: loc.start.line, column: loc.start.column };
+}
+function containsZodForm(node) {
+    // Cheap check used to filter member-expression element names — we don't
+    // want every `<x.foo />` in the file to log a skip.
+    if (node.type === 'JSXIdentifier')
+        return node.name === 'ZodForm';
+    if (node.type === 'JSXMemberExpression') {
+        return containsZodForm(node.object) || containsZodForm(node.property);
+    }
+    return false;
+}
+//# sourceMappingURL=scan-jsx.js.map

package/dist/generate-mode/scan-jsx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-jsx.js","sourceRoot":"","sources":["../../src/generate-mode/scan-jsx.ts"],"names":[],"mappings":"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"}

package/dist/hmr.d.ts

@@ -0,0 +1,44 @@
+/**
+ * HMR helpers.
+ *
+ * `computeHmrInvalidation` is the pure side: given a changed file path,
+ * the cache, and the config file path, it returns the list of evicted
+ * cache keys (which the dispatching `handleHotUpdate` hook converts to
+ * Vite module ids).
+ *
+ * The hook itself lives in `plugin.ts` — it converts the result of this
+ * function into the array of `ModuleNode` objects Vite expects to
+ * invalidate.
+ */
+import type { CompilationCache } from './cache.js';
+export interface HmrInvalidationInput {
+    /** Absolute path of the file that just changed. */
+    changedFile: string;
+    /** Absolute path of the project's `z2f.config.ts` (or undefined if unknown). */
+    configFile: string | undefined;
+    /** The plugin's compilation cache. */
+    cache: CompilationCache;
+}
+export interface HmrInvalidationResult {
+    /**
+     * `'config'` means the config file changed and the entire cache was
+     * evicted. `'schema'` means a tracked schema file changed and only
+     * entries depending on it were evicted.
+     */
+    kind: 'config' | 'schema';
+    /** The cache keys that were evicted. */
+    evictedKeys: string[];
+}
+/**
+ * Decide what to invalidate when a file changes.
+ *
+ * Returns `null` to signal "fall through to Vite's default HMR behavior"
+ * — the changed file is neither the config nor a tracked schema, so the
+ * plugin has nothing to do.
+ *
+ * Returns a result object when the plugin DID invalidate something. The
+ * caller is responsible for converting the evicted keys back into Vite
+ * module ids (each key has the form `<schemaFile>::<variant>::<configHash>`).
+ */
+export declare function computeHmrInvalidation(input: HmrInvalidationInput): HmrInvalidationResult | null;
+//# sourceMappingURL=hmr.d.ts.map

package/dist/hmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.d.ts","sourceRoot":"","sources":["../src/hmr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,sCAAsC;IACtC,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,IAAI,CAiBhG"}

package/dist/hmr.js

@@ -0,0 +1,28 @@
+/**
+ * Decide what to invalidate when a file changes.
+ *
+ * Returns `null` to signal "fall through to Vite's default HMR behavior"
+ * — the changed file is neither the config nor a tracked schema, so the
+ * plugin has nothing to do.
+ *
+ * Returns a result object when the plugin DID invalidate something. The
+ * caller is responsible for converting the evicted keys back into Vite
+ * module ids (each key has the form `<schemaFile>::<variant>::<configHash>`).
+ */
+export function computeHmrInvalidation(input) {
+    const { changedFile, configFile, cache } = input;
+    // Config file changed → wipe everything
+    if (configFile !== undefined && changedFile === configFile) {
+        const evictedKeys = cache.invalidateAll();
+        return { kind: 'config', evictedKeys };
+    }
+    // Schema file changed → surgical eviction
+    const evictedKeys = cache.invalidateByFile(changedFile);
+    if (evictedKeys.length === 0) {
+        // The cache had nothing for this file. The plugin has no business
+        // here; let Vite handle the file via its normal HMR machinery.
+        return null;
+    }
+    return { kind: 'schema', evictedKeys };
+}
+//# sourceMappingURL=hmr.js.map

package/dist/hmr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.js","sourceRoot":"","sources":["../src/hmr.ts"],"names":[],"mappings":"AAkCA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAA2B;IAChE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAEjD,wCAAwC;IACxC,IAAI,UAAU,KAAK,SAAS,IAAI,WAAW,KAAK,UAAU,EAAE,CAAC;QAC3D,MAAM,WAAW,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IACzC,CAAC;IAED,0CAA0C;IAC1C,MAAM,WAAW,GAAG,KAAK,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACxD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,kEAAkE;QAClE,+DAA+D;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Vite plugin for schema-driven form generation.
+ *
+ * Two modes:
+ * - **Query mode** (`?z2f` imports): import a schema file with a `?z2f` query
+ *   parameter to receive a fully-generated React form component as a virtual
+ *   module. Zero build step — the plugin compiles on demand.
+ * - **Generate mode** (`options.generate`): scan JSX source files for
+ *   `<ZodForm>` call sites and replace statically-resolvable ones with
+ *   generated form components at build time. Opt-in via `generate: {}`.
+ *
+ * Config resolution order:
+ *   1. `options.configPath` if explicitly provided
+ *   2. Auto-discovery of `z2f.config.{ts,mts,js,mjs}` in the Vite root
+ *   3. `DEFAULT_CONFIG` merged with `options.configOverride`
+ *
+ * @remarks
+ * Requires Zod v4 and `@zod-to-form/core`. The plugin uses Vite's
+ * `ssrLoadModule` to evaluate schema files — the same Vite resolver pipeline
+ * that handles your app code, so aliases and tsconfig paths all work.
+ *
+ * HMR contract: schema file changes invalidate only the affected virtual
+ * modules. Config file (`z2f.config.ts`) changes invalidate all cached
+ * compiled forms and trigger re-compilation on the next import.
+ *
+ * @useWhen
+ * - You want zero-config form generation directly from `import './schema?z2f'`
+ * - You have a Vite-based app and want to skip the CLI generate step
+ * - You need per-variant forms (mobile/desktop) from the same schema
+ * - You want HMR-aware form recompilation during development
+ *
+ * @avoidWhen
+ * - You are NOT using Vite (use `@zod-to-form/cli` for non-Vite builds)
+ * - Your schema files have cyclic type references — the `?z2f` rewriter
+ *   recurses on Zod's type graph and will hang on cycles
+ * - You need SSR-safe form HTML without a client-side React bundle
+ * - You are on Zod v3 — the plugin only supports Zod v4 schemas
+ *
+ * @pitfalls
+ * - NEVER use `?z2f` on schemas with cyclic type references — the schema
+ *   walker recurses on Zod's type graph and hits infinite recursion on cycles
+ * - NEVER enable `rewrite` (generate mode) with HMR simultaneously without
+ *   testing — the in-memory compilation cache has invalidation gaps when
+ *   source files are changed mid-session and the module graph is stale
+ * - NEVER assume Zod schema objects survive Vite's module graph isolation
+ *   intact — always re-export schemas from a dedicated file so `ssrLoadModule`
+ *   can evaluate them without pulling in unrelated runtime dependencies
+ * - NEVER put your `z2f.config.ts` outside the Vite root — auto-discovery
+ *   only searches `resolvedConfig.root`; files outside that boundary are
+ *   silently skipped and the plugin falls back to defaults
+ * - NEVER mix `configOverride` with a `z2f.config.ts` that overlaps the
+ *   same keys — `configOverride` wins unconditionally (shallow merge), so
+ *   config-file fields with the same name are silently dropped
+ *
+ * @packageDocumentation
+ */
+export { z2fVite, default } from './plugin.js';
+export type { PluginOptions, Z2FViteConfig, VariantConfigs, WriteOptions, GenerationTarget, CompilationEntry, GenerateSite, HMRInvalidationMap } from './types.js';
+export { Z2FViteError, formatZ2FViteError } from './errors.js';
+export type { Z2FViteErrorCode, Z2FViteErrorLocation } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE/C,YAAY,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,59 @@
+/**
+ * Vite plugin for schema-driven form generation.
+ *
+ * Two modes:
+ * - **Query mode** (`?z2f` imports): import a schema file with a `?z2f` query
+ *   parameter to receive a fully-generated React form component as a virtual
+ *   module. Zero build step — the plugin compiles on demand.
+ * - **Generate mode** (`options.generate`): scan JSX source files for
+ *   `<ZodForm>` call sites and replace statically-resolvable ones with
+ *   generated form components at build time. Opt-in via `generate: {}`.
+ *
+ * Config resolution order:
+ *   1. `options.configPath` if explicitly provided
+ *   2. Auto-discovery of `z2f.config.{ts,mts,js,mjs}` in the Vite root
+ *   3. `DEFAULT_CONFIG` merged with `options.configOverride`
+ *
+ * @remarks
+ * Requires Zod v4 and `@zod-to-form/core`. The plugin uses Vite's
+ * `ssrLoadModule` to evaluate schema files — the same Vite resolver pipeline
+ * that handles your app code, so aliases and tsconfig paths all work.
+ *
+ * HMR contract: schema file changes invalidate only the affected virtual
+ * modules. Config file (`z2f.config.ts`) changes invalidate all cached
+ * compiled forms and trigger re-compilation on the next import.
+ *
+ * @useWhen
+ * - You want zero-config form generation directly from `import './schema?z2f'`
+ * - You have a Vite-based app and want to skip the CLI generate step
+ * - You need per-variant forms (mobile/desktop) from the same schema
+ * - You want HMR-aware form recompilation during development
+ *
+ * @avoidWhen
+ * - You are NOT using Vite (use `@zod-to-form/cli` for non-Vite builds)
+ * - Your schema files have cyclic type references — the `?z2f` rewriter
+ *   recurses on Zod's type graph and will hang on cycles
+ * - You need SSR-safe form HTML without a client-side React bundle
+ * - You are on Zod v3 — the plugin only supports Zod v4 schemas
+ *
+ * @pitfalls
+ * - NEVER use `?z2f` on schemas with cyclic type references — the schema
+ *   walker recurses on Zod's type graph and hits infinite recursion on cycles
+ * - NEVER enable `rewrite` (generate mode) with HMR simultaneously without
+ *   testing — the in-memory compilation cache has invalidation gaps when
+ *   source files are changed mid-session and the module graph is stale
+ * - NEVER assume Zod schema objects survive Vite's module graph isolation
+ *   intact — always re-export schemas from a dedicated file so `ssrLoadModule`
+ *   can evaluate them without pulling in unrelated runtime dependencies
+ * - NEVER put your `z2f.config.ts` outside the Vite root — auto-discovery
+ *   only searches `resolvedConfig.root`; files outside that boundary are
+ *   silently skipped and the plugin falls back to defaults
+ * - NEVER mix `configOverride` with a `z2f.config.ts` that overlaps the
+ *   same keys — `configOverride` wins unconditionally (shallow merge), so
+ *   config-file fields with the same name are silently dropped
+ *
+ * @packageDocumentation
+ */
+export { z2fVite, default } from './plugin.js';
+export { Z2FViteError, formatZ2FViteError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAY/C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Plugin logger.
+ *
+ * A small level-based logger independent of Vite's own logger. Used so the
+ * plugin can stay quiet by default but emit DEBUG-level diagnostics for
+ * generate-mode skipped sites and cache misses without polluting Vite's
+ * normal output.
+ */
+export type LogLevel = 'silent' | 'warn' | 'info' | 'debug';
+export interface Logger {
+    warn(message: string): void;
+    info(message: string): void;
+    debug(message: string): void;
+    /**
+     * Buffer a generate-mode skip diagnostic for end-of-build summary output.
+     * Diagnostics are flushed via `flushGenerateSummary()`.
+     */
+    bufferGenerateSkip(file: string, line: number, column: number, reason: string): void;
+    /**
+     * Emit the buffered generate-mode skip summary at INFO level (or higher),
+     * matching the format documented in `contracts/generate-mode.md`. Returns
+     * the number of skips that were summarized.
+     */
+    flushGenerateSummary(processed: number, rewritten: number): number;
+}
+export declare function createLogger(level?: LogLevel): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAW5D,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACrF;;;;OAIG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACpE;AASD,wBAAgB,YAAY,CAAC,KAAK,GAAE,QAAiB,GAAG,MAAM,CAoC7D"}

package/dist/logger.js

@@ -0,0 +1,46 @@
+const LEVEL_RANK = {
+    silent: 0,
+    warn: 1,
+    info: 2,
+    debug: 3
+};
+const PREFIX = '[@zod-to-form/vite]';
+export function createLogger(level = 'info') {
+    const rank = LEVEL_RANK[level];
+    const skips = [];
+    const shouldLog = (target) => LEVEL_RANK[target] <= rank;
+    return {
+        warn(message) {
+            if (shouldLog('warn'))
+                console.warn(`${PREFIX} ${message}`);
+        },
+        info(message) {
+            if (shouldLog('info'))
+                console.info(`${PREFIX} ${message}`);
+        },
+        debug(message) {
+            if (shouldLog('debug'))
+                console.debug(`${PREFIX} ${message}`);
+        },
+        bufferGenerateSkip(file, line, column, reason) {
+            skips.push({ file, line, column, reason });
+        },
+        flushGenerateSummary(processed, rewritten) {
+            const count = skips.length;
+            if (!shouldLog('info')) {
+                skips.length = 0;
+                return count;
+            }
+            const lines = [
+                `${PREFIX} Generate mode processed ${processed} files, rewrote ${rewritten} call sites, skipped ${count}:`
+            ];
+            for (const skip of skips) {
+                lines.push(`  ${skip.file}:${skip.line}:${skip.column} — ${skip.reason}`);
+            }
+            console.info(lines.join('\n'));
+            skips.length = 0;
+            return count;
+        }
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,GAA6B;IAC3C,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,GAAG,qBAAqB,CAAC;AA0BrC,MAAM,UAAU,YAAY,CAAC,KAAK,GAAa,MAAM;IACnD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAmB,EAAE,CAAC;IAEjC,MAAM,SAAS,GAAG,CAAC,MAAgB,EAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;IAE5E,OAAO;QACL,IAAI,CAAC,OAAe;YAClB,IAAI,SAAS,CAAC,MAAM,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,OAAe;YAClB,IAAI,SAAS,CAAC,MAAM,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,KAAK,CAAC,OAAe;YACnB,IAAI,SAAS,CAAC,OAAO,CAAC;gBAAE,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,OAAO,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM;YAC3C,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,oBAAoB,CAAC,SAAS,EAAE,SAAS;YACvC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;YAC3B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvB,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;gBACjB,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,KAAK,GAAa;gBACtB,GAAG,MAAM,4BAA4B,SAAS,mBAAmB,SAAS,wBAAwB,KAAK,GAAG;aAC3G,CAAC;YACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5E,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YAC/B,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,61 @@
+import { type Plugin } from 'vite';
+import type { PluginOptions } from './types.js';
+/**
+ * Vite plugin factory for `@zod-to-form/vite`.
+ *
+ * Registers Vite hooks for:
+ * - **Query mode** (`resolveId` + `load`): intercepts `*.ts?z2f[=variant]` imports,
+ *   evaluates the schema via `ssrLoadModule`, and returns a virtual module containing
+ *   the generated React form component.
+ * - **Generate mode** (`transform`): when `options.generate` is set, scans JSX source
+ *   files for `<ZodForm schema={X}>` and rewrites resolvable call sites with generated
+ *   components at build time.
+ * - **Resolver tree-shake** (`transform`): removes `zodResolver` calls from `useZodForm`
+ *   at build time when `validationLevel` is set, allowing bundlers to drop the
+ *   `@hookform/resolvers` dependency.
+ * - **HMR** (`handleHotUpdate`): invalidates cached compiled forms when their schema or
+ *   the `z2f.config.ts` changes.
+ *
+ * @param options - Optional plugin configuration. All fields are optional; `z2fVite()`
+ *   with no arguments produces a working plugin using auto-discovered config.
+ * @returns A Vite `Plugin` object to include in `vite.config.ts`.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { z2fVite } from '@zod-to-form/vite';
+ *
+ * export default defineConfig({
+ *   plugins: [z2fVite()],
+ * });
+ * ```
+ *
+ * @useWhen
+ * - You want `import SignupForm from './signup.schema?z2f'` to Just Work in a Vite app
+ * - You want HMR-aware form recompilation when schemas change in development
+ * - You want to run generate mode to pre-compile forms from `<ZodForm>` call sites
+ *
+ * @avoidWhen
+ * - You are building with webpack, esbuild, Rollup, or any non-Vite bundler
+ * - Your schemas have cyclic references — the walker will recurse infinitely on them
+ * - You need server-side form rendering without a React runtime
+ *
+ * @pitfalls
+ * - NEVER use `?z2f` on schemas with cyclic type references — the schema walker
+ *   recurses on Zod's internal type graph and hangs on cycles
+ * - NEVER enable `generate` mode and then rely on HMR without testing — the
+ *   generate-mode transform cache does not integrate with Vite's standard HMR
+ *   module invalidation for rewritten JSX files
+ * - NEVER assume Zod types survive Vite's module graph isolation — always export
+ *   schemas from a dedicated `.schema.ts` file; importing from a module that
+ *   re-exports through complex chains can fail under `ssrLoadModule`
+ * - NEVER configure `configPath` to point outside the Vite `root` — the plugin
+ *   uses `ssrLoadModule` with a dev server scoped to `root`, so files outside
+ *   that boundary may fail to resolve their own imports
+ *
+ * @category Plugin
+ */
+export declare function z2fVite(options?: PluginOptions): Plugin;
+export default z2fVite;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,MAAM,EAGZ,MAAM,MAAM,CAAC;AAcd,OAAO,KAAK,EAAoB,aAAa,EAAiB,MAAM,YAAY,CAAC;AAyDjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAiV3D;eAEc,OAAO"}