attaform 0.29.0 → 0.30.1

package/dist/transforms.d.mts

@@ -1,50 +1,177 @@
 import { NodeTransform } from '@vue/compiler-core';
 
+/**
+ * Vue compiler node transform that bridges `v-register` into the binding
+ * shapes its consumers expect, on two kinds of host.
+ *
+ *   - `<select v-register>` gets `:value` on a single-select plus a
+ *     per-`<option>` `:selected`, so the runtime directive can pre-mark
+ *     selected options at SSR time.
+ *   - `<MyComponent v-register>`, and a kebab-case custom-element host,
+ *     gets a `:registerValue` bridge prop, so `useRegister` inside the
+ *     child sees the parent's RegisterValue. Any parent-authored slotted
+ *     `<option>` is marked exactly as the native path marks it, so a
+ *     `<select>` wrapped in a styled component keeps its SSR-selected
+ *     option (#394).
+ *
+ * `attaform/vite` and `attaform/nuxt` wire it for you; reach for it
+ * directly only when integrating a custom bundler.
+ */
+
 declare const componentBridgeTransform: NodeTransform;
 
 /**
- * Vue compiler node transform for `<input v-register>` and
- * `<textarea v-register>`. Injects the `:value` / `:checked`
- * bindings required for SSR-correct initial render.
+ * Vue compiler node transform for `<input v-register>` and `<textarea
+ * v-register>`, injecting the `:value` and `:checked` bindings an
+ * SSR-correct initial render needs.
  *
- * Wired automatically by `attaform/vite` and
- * `attaform/nuxt`. Use directly only when integrating with
- * a custom bundler.
+ * `attaform/vite` and `attaform/nuxt` wire it for you; reach for it
+ * directly only when integrating a custom bundler.
  */
 declare const inputTextAreaNodeTransform: NodeTransform;
 
 /**
- * Vue compiler node transform that warns about a redundant state
- * binding co-located with `v-register`, and stamps the
- * compile-active marker so the runtime diagnostic stands down.
+ * The compile-time half of the redundant-binding guard (#464). On every
+ * element carrying `v-register` it does two things.
+ *
+ *   1. Warns at build time when a `v-model` sits beside `v-register` on
+ *      a native `<input>`, `<select>` or `<textarea>`, which installs
+ *      Vue's own model directive next to Attaform's: two writers driving
+ *      one element with no fallback story between them.
+ *      `findRedundantStateBinding` below carries the full reasoning for
+ *      what does and does not count.
+ *
+ *   2. Stamps `V_REGISTER_COMPILED_MODIFIER` on the directive so the
+ *      runtime diagnostic in `core/directive.ts` stands down. This
+ *      transform runs BEFORE `inputTextAreaNodeTransform` and
+ *      `componentBridgeTransform` strip and inject the value channel, so
+ *      it sees the author's props verbatim where the runtime, seeing
+ *      only the post-injection props, cannot. Exactly one layer fires
+ *      per consumer.
+ *
+ * The carve-out: a `:value`, or a static `value=`, is the legitimate
+ * IDENTITY channel for a radio and an `<option>`, and `v-register` READS
+ * it. Those never warn; only the STATE attrs do.
+ *
+ * A dynamic `:type` cannot be classified at compile time, so that input
+ * is skipped for the warn, best-effort as in `inputTextAreaNodeTransform`
+ * and the runtime `resolveDynamicModel`. The marker is still stamped, so
+ * the runtime layer, which sees the resolved type, does not double-report.
+ *
+ * It is deliberately NOT `__DEV__`-gated: firing on every compile,
+ * production and CI included, is what lets a consumer retire a bespoke
+ * SFC-lint gate. Warnings only. A redundant binding never fails the
+ * build, the Vue compiler giving transforms no error channel and a
+ * library having no business nuking a consumer's build over a
+ * lint-level issue.
+ *
+ * `attaform/vite` and `attaform/nuxt` wire it first in `nodeTransforms`;
+ * reach for it directly only when integrating a custom bundler.
+ */
+
+/**
+ * Vue compiler node transform that warns about a redundant state binding
+ * sitting beside `v-register`, and stamps the compile-active marker so
+ * the runtime diagnostic stands down.
  *
- * Must run BEFORE `inputTextAreaNodeTransform` and
- * `componentBridgeTransform` so it reads the author's props before they
- * are stripped / injected. Wired first by `attaform/vite` and
- * `attaform/nuxt`.
+ * It MUST run before `inputTextAreaNodeTransform` and
+ * `componentBridgeTransform`, so it reads the author's props before they
+ * are stripped and injected. `attaform/vite` and `attaform/nuxt` wire it
+ * first.
  */
 declare const redundantBindingWarnTransform: NodeTransform;
 
 /**
- * Vue compiler node transform that wraps every `v-register`
- * expression in a small IIFE so the directive can flag a field as
- * connected during SSR. Eliminates the `false → true` flicker on
- * `getFieldState(path).connected` after hydration.
+ * Rewrites every `<element v-register="<expr>">` so the binding
+ * expression wraps `<expr>` in an IIFE that calls
+ * `markConnectedOptimistically()` on the resulting `RegisterValue` and
+ * hands back the same object:
+ *
+ *   ((__attaRv) => (__attaRv?.markConnectedOptimistically?.(), __attaRv))(<expr>)
+ *
+ * Vue deliberately skips directive lifecycle hooks during SSR (see the
+ * header of `core/directive.ts`), so the `v-register` directive's
+ * `created` hook, the one that flips `connected: true`, never fires on
+ * the server. Every SSR'd FieldState therefore serialises `connected:
+ * false`, then flickers to `true` when the directive runs on hydration,
+ * and anything reading `getFieldState(path).connected` in a
+ * server-rendered template sees the stale value baked into the HTML.
  *
- * Must run after `vRegisterPreambleTransform`. Wired automatically
- * by `attaform/vite` and `attaform/nuxt`.
+ * The IIFE captures the `RegisterValue` `<expr>` produced, fires the
+ * optimistic mark, itself guarded by `state.ssr` so it is a free no-op
+ * on the client, and returns the same object, so the directive receives
+ * exactly what the author wrote.
+ *
+ * It is agnostic to the shape of `<expr>`, inline, hoisted into a
+ * variable, or dynamically built: all three produce a `RegisterValue` at
+ * runtime and the wrapper never needs the path string. A setup-time
+ * `register()` call NEVER bound to `v-register` gets no wrapper, no
+ * mark, and stays `connected: false` after hydration, which is correct:
+ * it represents no rendered DOM element.
+ *
+ * Idempotent. Running twice on one AST, as some bundler configurations
+ * do, detects the marker on the second pass and skips re-wrapping.
+ */
+
+/**
+ * Vue compiler node transform that wraps every `v-register` expression
+ * in a small IIFE, so the directive can flag a field connected during
+ * SSR and `getFieldState(path).connected` does not flicker after
+ * hydration.
+ *
+ * It must run after `vRegisterPreambleTransform`. `attaform/vite` and
+ * `attaform/nuxt` wire both.
  */
 declare const vRegisterHintTransform: NodeTransform;
 
 /**
- * Vue compiler node transform that hoists `v-register`'s SSR
- * connection marks to the root of the template. Together with
- * `vRegisterHintTransform`, ensures expressions earlier in the
- * template that read `getFieldState(path).connected` see the
- * correct value during the server's single-pass render.
+ * Closes the render-order edge `vRegisterHintTransform` alone leaves
+ * open.
+ *
+ * The hint transform wraps each `v-register` expression in an IIFE that
+ * calls `markConnectedOptimistically()` when the element's vnode is
+ * created, which covers any expression evaluated AT or AFTER the input
+ * in render order. Vue's SSR is single-pass top to bottom, though, so in
+ *
+ *   <pre>{{ form.fields.password.connected }}</pre>
+ *   <input v-register="form.register('password')" />
+ *
+ * the `<pre>` evaluates BEFORE the wrapper has fired. The serialized
+ * HTML carries `connected: false`, the post-hydration steady state says
+ * `true`, and the user sees a one-tick flicker.
+ *
+ * So the marks hoist one level up. The walk collects every static
+ * `v-register` binding, skipping `v-for` descendants, whose expressions
+ * reference loop locals unavailable at root scope, and prepends a
+ * synthetic `:data-atta-pre-mark` directive to the first root element.
+ * Vue evaluates an element's prop bindings before recursing into its
+ * children, so that IIFE fires every collected mark before any
+ * descendant expression runs. Its own expression resolves to
+ * `undefined`, which the SSR renderer drops, so no attribute appears and
+ * the marks are the only output.
+ *
+ * Register it BEFORE `vRegisterHintTransform`. The pre-order pass here
+ * captures each expression's original, un-wrapped text into a
+ * per-template state map, the hint transform then wraps the in-place
+ * directive expression, and the exit hook on the first root element
+ * builds the preamble from the captured originals. An element's exit
+ * hooks fire before `transformElement`'s codegen exit, so the injected
+ * prop lands in the rendered output.
+ *
+ * For a `v-for` descendant the hint transform's per-element wrapper
+ * stays load-bearing: those bindings cannot hoist, their path
+ * expressions referencing loop-scoped identifiers.
+ */
+
+/**
+ * Vue compiler node transform that hoists `v-register`'s SSR connection
+ * marks to the root of the template. With `vRegisterHintTransform`, it
+ * is what lets an expression EARLIER in the template read
+ * `getFieldState(path).connected` correctly during the server's
+ * single-pass render.
  *
- * Must run before `vRegisterHintTransform`. Wired automatically
- * by `attaform/vite` and `attaform/nuxt`.
+ * It must run before `vRegisterHintTransform`. `attaform/vite` and
+ * `attaform/nuxt` wire both.
  */
 declare const vRegisterPreambleTransform: NodeTransform;
 

package/dist/transforms.mjs

@@ -1 +1 @@
-export { c as componentBridgeTransform, i as inputTextAreaNodeTransform, r as redundantBindingWarnTransform, v as vRegisterHintTransform, a as vRegisterPreambleTransform } from './shared/attaform.BK0cgu2K.mjs';
+export { c as componentBridgeTransform, i as inputTextAreaNodeTransform, r as redundantBindingWarnTransform, v as vRegisterHintTransform, a as vRegisterPreambleTransform } from './shared/attaform.ZYn2ahzJ.mjs';

package/dist/vite.d.mts

@@ -28,9 +28,9 @@ import { Plugin } from 'vite';
  * can be called at all.
  *
  * Deliberately absent (reach for these with an explicit import):
- *   - `useAbstractForm` — the schema-agnostic escape hatch on
- *     `attaform/abstract`, an advanced surface, not the default form.
- *   - `createAttaform` — the plugin install, a setup-level one-liner that
+ *   - `useAbstractForm`, the schema-agnostic escape hatch on
+ *     `attaform/abstract`: an advanced surface, not the default form.
+ *   - `createAttaform`, the plugin install, a setup-level one-liner that
  *     belongs beside the app bootstrap, not in every component's scope.
  *   - `unset` / `isUnset` and the serialize helpers: plain values and
  *     functions with no component affinity, equally at home in a store, a
@@ -63,41 +63,14 @@ declare const attaformAutoImports: AttaformAutoImport[];
 declare const attaformAutoImportsMap: Record<string, string[]>;
 
 /**
- * `attaform/vite` — Vite plugin that wires the compile-time node
- * transforms with @vitejs/plugin-vue, binds `v-register` into each
- * compiled template that uses it (so no app-level directive
- * registration exists or is needed), AND rewrites `attaform` and
- * `attaform/zod` imports to either `attaform/zod-v3` or `attaform/zod-v4`
- * at build time, based on the consumer's installed Zod major. The result
- * is one Zod adapter shipped per bundle, with no manual subpath choice.
+ * `attaform/vite`, the Vite plugin. See {@link attaform} for what it
+ * does and how to register it.
  *
- * Usage (bare Vue 3 consumers):
- *
- *   // vite.config.ts
- *   import vue from '@vitejs/plugin-vue'
- *   import { attaform } from 'attaform/vite'
- *
- *   export default defineConfig({
- *     plugins: [vue(), attaform()],
- *   })
- *
- * The transforms inject `:value`, `:checked`, and `:selected` bindings
- * into elements that use the `v-register` directive — load-bearing for
- * SSR initial-render correctness. Omitting this plugin under CSR is
- * tolerable (one-frame flash on mount); omitting it under SSR produces
- * visibly wrong initial HTML.
- *
- * The `resolveZodAlias` option (default `true`) controls the build-time
- * rewrite of `attaform` / `attaform/zod`. Set to `false` if your project
- * intentionally mixes Zod versions or has a non-standard Zod resolution;
- * the unified entry's runtime dispatch covers that case at the cost of
- * bundling both adapters.
- *
- * Implementation note: this plugin mutates @vitejs/plugin-vue's options
- * via the documented but somewhat informal `api.options` surface used
- * by VueUse, Vite PWA, and other Vue ecosystem plugins. If you're
- * using a custom Vue plugin wrapper, fall back to `attaform/transforms`
- * and wire them yourself.
+ * It mutates @vitejs/plugin-vue's options through the documented but
+ * somewhat informal `api.options` surface that VueUse, Vite PWA and
+ * other Vue ecosystem plugins also use. Behind a custom Vue plugin
+ * wrapper, fall back to `attaform/transforms` and wire the transforms
+ * yourself.
  */
 
 /** Options for `attaform()`. */
@@ -105,8 +78,8 @@ interface AttaformVitePluginOptions {
     /**
      * Rewrite `attaform` and `attaform/zod` imports at build time to
      * either `attaform/zod-v3` or `attaform/zod-v4`, based on the
-     * consumer's installed Zod major. Default `true` — produces a leaner
-     * bundle for the common case of one Zod version per project.
+     * consumer's installed Zod major. Default `true`, which produces a
+     * leaner bundle for the common case of one Zod version per project.
      *
      * Set to `false` to fall through to the unified entry's runtime
      * dispatch. Useful when:
@@ -120,12 +93,10 @@ interface AttaformVitePluginOptions {
     resolveZodAlias?: boolean;
 }
 /**
- * Vite plugin that wires the form library's compile-time template
- * transforms into `@vitejs/plugin-vue`, binds the `v-register`
- * directive into each compiled template that uses it, and rewrites the
- * bare `attaform` barrel and the unified `attaform/zod` import to the
- * matching adapter subpath. Required for SSR and for hydration
- * accuracy under bare Vue 3.
+ * Vite plugin that wires Attaform's compile-time template transforms
+ * into `@vitejs/plugin-vue`, binds `v-register` into each compiled
+ * template that uses it, and rewrites the bare `attaform` barrel and
+ * the unified `attaform/zod` import to the matching adapter subpath.
  *
  * ```ts
  * // vite.config.ts
@@ -137,14 +108,20 @@ interface AttaformVitePluginOptions {
  * })
  * ```
  *
- * Place the call after `vue()` in the plugins array. Nuxt projects
- * don't need this — `attaform/nuxt` handles it.
+ * Place the call after `vue()`. Nuxt projects do not need it;
+ * `attaform/nuxt` handles this.
+ *
+ * The transforms inject `:value`, `:checked` and `:selected` onto
+ * elements using `v-register`, which is load-bearing for SSR
+ * initial-render correctness. Omitting the plugin under CSR costs a
+ * one-frame flash on mount; omitting it under SSR produces visibly
+ * wrong initial HTML.
  *
- * Returns a two-plugin array (Vite flattens nested plugin arrays): the
- * main pre-plugin above, plus a post-plugin that rewrites each compiled
- * SFC's `resolveDirective("register")` to a static import from
- * `attaform/directive`. The rewrite is why no app-level directive
- * registration exists or is needed here — see
+ * Returns a two-plugin array, since Vite flattens nested plugin arrays:
+ * the main pre-plugin, plus a post-plugin rewriting each compiled SFC's
+ * `resolveDirective("register")` to a static import from
+ * `attaform/directive`. That rewrite is why no app-level directive
+ * registration is needed here; see
  * `runtime/lib/core/transforms/directive-delivery-transform.ts` for the
  * mechanism and its scope.
  */

package/dist/vite.mjs

@@ -1,5 +1,5 @@
-import { r as resolveZodAliasTarget, i as isRewritableZodSpecifier } from './shared/attaform.DhnPb6nK.mjs';
-import { a as vRegisterPreambleTransform, r as redundantBindingWarnTransform, c as componentBridgeTransform, i as inputTextAreaNodeTransform, v as vRegisterHintTransform } from './shared/attaform.BK0cgu2K.mjs';
+import { r as resolveZodAliasTarget, i as isRewritableZodSpecifier } from './shared/attaform.BAf3UNn4.mjs';
+import { a as vRegisterPreambleTransform, r as redundantBindingWarnTransform, c as componentBridgeTransform, i as inputTextAreaNodeTransform, v as vRegisterHintTransform } from './shared/attaform.ZYn2ahzJ.mjs';
 import { parse, babelParse } from '@vue/compiler-sfc';
 import { NodeTypes } from '@vue/compiler-core';
 
@@ -60,8 +60,13 @@ class SourceEditor {
     return out;
   }
 }
+function canPossiblyInject(code) {
+  if (!code.includes("attaform")) return false;
+  return code.includes("useForm") || code.includes("injectForm");
+}
 function transformSsrAccessed(code, id) {
   if (!id.endsWith(".vue")) return null;
+  if (!canPossiblyInject(code)) return null;
   const { descriptor } = parse(code, { filename: id });
   if (descriptor.scriptSetup === null || descriptor.template === null) return null;
   const scriptSource = descriptor.scriptSetup.content;
@@ -303,7 +308,7 @@ function attaform(options = {}) {
 
       // The panel runs inside Nuxt DevTools' overlay iframe, which itself
       // is nested in the consumer's main page. \`window.parent\` only
-      // crosses one frame boundary \u2014 the overlay UI \u2014 which doesn't have
+      // crosses one frame boundary (the overlay UI), which doesn't have
       // the bridge attached. The bridge lives on the consumer's main
       // page, which sits at the top of the frame hierarchy. Walk the
       // chain checking each ancestor frame so the same code works whether

package/dist/webpack.d.mts

@@ -1,13 +1,14 @@
 import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './shared/attaform.C9fPTxjB.mjs';
 
 /**
- * `attaform/webpack` — webpack plugin that rewrites `attaform/zod`
+ * `attaform/webpack`, the webpack plugin that rewrites `attaform/zod`
  * imports to the single matching adapter subpath (`attaform/zod-v3` or
  * `attaform/zod-v4`) at build time, based on the consumer's installed Zod
  * major. Without it, webpack ships both adapters because the unified
  * `attaform/zod` entry imports both for runtime dispatch.
  *
- * Usage (ESM config — the plugin is ESM-only, matching attaform's package):
+ * Usage, in an ESM config, since the plugin is ESM-only like the rest of
+ * the package:
  *
  *   // webpack.config.mjs
  *   import { attaform } from 'attaform/webpack'
@@ -16,16 +17,12 @@ import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './sha
  *     plugins: [attaform()],
  *   }
  *
- * This plugin only does the adapter rewrite. The Vue SFC `v-register`
- * transforms that `attaform/vite` wires (load-bearing for SSR initial
- * render) are `@vitejs/plugin-vue`-specific and do not transfer; a
- * non-Vite consumer that needs them wires `attaform/transforms` into
- * their Vue compiler separately. The `v-register` directive itself is
- * also delivered by the Vite plugin's compile-time binding, so outside
- * that pipeline register it once per app:
- *
- *   import { installVRegister } from 'attaform/directive'
- *   installVRegister(app)
+ * The adapter rewrite is all this plugin does. Two things
+ * `attaform/vite` also provides do NOT transfer, because both are
+ * `@vitejs/plugin-vue`-specific: wire `attaform/transforms` into your
+ * Vue compiler for the SSR-critical template transforms, and register
+ * the directive once per app with `installVRegister(app)` from
+ * `attaform/directive`.
  *
  * Zero-dep: the plugin imports nothing from `webpack` (it taps the resolve
  * hook the compiler injects at the consumer's build). Shares its body with
@@ -36,6 +33,17 @@ import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './sha
 type AttaformWebpackPluginOptions = WebpackFamilyPluginOptions;
 /** The structural shape webpack requires of the plugin. */
 type AttaformWebpackPlugin = WebpackFamilyPlugin;
+/**
+ * webpack plugin that resolves `attaform/zod` to the one adapter subpath
+ * matching the installed Zod major, so the build ships a single adapter
+ * instead of both.
+ *
+ * ```js
+ * const { attaform } = require('attaform/webpack')
+ *
+ * module.exports = { plugins: [attaform()] }
+ * ```
+ */
 declare function attaform(options?: AttaformWebpackPluginOptions): AttaformWebpackPlugin;
 
 export { attaform };

package/dist/webpack.mjs

@@ -1,4 +1,4 @@
-import { c as createWebpackFamilyPlugin } from './shared/attaform.v0fQtWyA.mjs';
+import { c as createWebpackFamilyPlugin } from './shared/attaform.B1rH9ht6.mjs';
 
 function attaform(options = {}) {
   return createWebpackFamilyPlugin("attaform/webpack", options);