attaform 0.14.0 → 0.15.0

package/dist/zod-v3.d.cts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { a8 as ValidateOnConfig, F as FormKey, x as OnInvalidSubmitPolicy, E as PersistConfig, v as HistoryConfig, C as CoercionRegistry, G as GenericForm, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, d as UseFormReturnType } from './shared/attaform.DDXrY-1Q.cjs';
-export { a6 as Unset, ad as isUnset, af as unset } from './shared/attaform.DDXrY-1Q.cjs';
-export { A as AttaformErrorCode, i as injectForm, u as useRegister } from './shared/attaform.CXZgUECn.cjs';
+import { ae as ValidateOnConfig, F as FormKey, B as OnInvalidSubmitPolicy, W as PersistConfig, x as HistoryConfig, C as CoercionRegistry, G as GenericForm, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, d as UseFormReturnType, n as FieldMetaPayload } from './shared/attaform.0Gxd_OOx.cjs';
+export { ac as Unset, am as isUnset, ao as unset } from './shared/attaform.0Gxd_OOx.cjs';
+export { A as AttaformErrorCode, i as injectForm, u as useRegister } from './shared/attaform.D-eHWfVx.cjs';
 import 'vue';
 
 /**
@@ -160,5 +160,78 @@ type ZodTypeMap = {
  */
 declare function isZodSchemaType<K extends keyof ZodTypeMap>(schema: unknown, expectedType: K): schema is ZodTypeMap[K];
 
-export { isZodSchemaType, useForm, zodAdapter };
+/**
+ * Field-metadata write/read API for the Zod v3 adapter.
+ *
+ * Zod 3 has no `z.registry()` mechanism, so we shim one with a
+ * module-scoped `WeakMap<ZodTypeAny, FieldMetaPayload>` plus a
+ * registry-shaped object exposing `add` / `get` / `has`. The public
+ * `withMeta(schema, payload)` write API matches `attaform/zod` so
+ * schema authoring reads identically across the two adapters.
+ *
+ * **Registration patterns:** both styles work — register on whatever
+ * schema reference you assign into the parent's shape, OR on the
+ * inner schema before wrapping. The adapter's resolver tries the
+ * walker-returned schema first, then falls back to the peeled
+ * inner so either ordering hits:
+ *
+ *     // both equivalent — registry hits at lookup time
+ *     withMeta(z.string(), { label: 'Email' }).optional()
+ *     withMeta(z.string().optional(), { label: 'Email' })
+ *
+ * The path walker returns the wrapper at terminal positions and
+ * peels at intermediate descent. The two-stage lookup covers both
+ * leaf and container registrations symmetrically.
+ */
+
+/**
+ * The shared registry every Attaform-aware Zod 3 schema can register
+ * field metadata against. Exposes a registry-shaped surface so that
+ * v3 user code can use the same idiom v4 users do (`fieldMeta.add(schema,
+ * payload)`); under the hood it's just a `WeakMap`.
+ */
+type FieldMetaRegistryV3 = {
+    /**
+     * Register `payload` against `schema`. Returns the registry to
+     * mirror Zod 4's `$ZodRegistry.add` chain shape.
+     */
+    add<S extends z.ZodTypeAny>(schema: S, payload: FieldMetaPayload): FieldMetaRegistryV3;
+    /**
+     * Read the registered payload for a schema, or `undefined` if
+     * nothing has been registered.
+     */
+    get(schema: z.ZodTypeAny): FieldMetaPayload | undefined;
+    /** True iff a payload has been registered for the schema. */
+    has(schema: z.ZodTypeAny): boolean;
+};
+declare const fieldMeta: FieldMetaRegistryV3;
+/**
+ * Attach `payload` to `schema` in the shared `fieldMeta` registry
+ * and return a clone of `schema` (chainable, with the new metadata).
+ * Cross-version with `attaform/zod`'s `withMeta()`.
+ *
+ * **Why clone, not mutate.** The WeakMap shim keys metadata on the
+ * schema reference. Calling `withMeta` twice on the same instance
+ * would overwrite (last-write-wins) — so a sub-schema reused at
+ * multiple form paths (e.g. an address schema shared between pickup
+ * and delivery) couldn't carry distinct metadata per path.
+ *
+ * `withMeta` sidesteps the footgun by reconstructing `schema` via
+ * its constructor + `_def` — Zod 3 schemas don't expose `.clone()`,
+ * but `new schema.constructor(schema._def)` is the equivalent. Each
+ * call gets a fresh identity and a fresh registry slot. Existing
+ * metadata on the original is merged through, so chaining
+ * `withMeta` accumulates payload fields rather than replacing.
+ *
+ * Inner field schemas (e.g. an object's `.shape.city`) are shared
+ * across clones — the def is held by reference — so leaf metadata
+ * registers once and surfaces at every path.
+ *
+ * `schema.register()` does NOT exist on Zod 3 — `withMeta` is the
+ * only write API. Register on the inner schema before wrapping;
+ * see the "Registration rule" note in this file's header.
+ */
+declare function withMeta<S extends z.ZodTypeAny>(schema: S, payload: FieldMetaPayload): S;
+
+export { FieldMetaPayload, fieldMeta, isZodSchemaType, useForm, withMeta, zodAdapter };
 export type { TypeWithNullableDynamicKeys, UnwrapZodObject, UseFormConfigurationWithZod, ZodTypeWithInnerType };

package/dist/zod-v3.d.mts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { a8 as ValidateOnConfig, F as FormKey, x as OnInvalidSubmitPolicy, E as PersistConfig, v as HistoryConfig, C as CoercionRegistry, G as GenericForm, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, d as UseFormReturnType } from './shared/attaform.DDXrY-1Q.mjs';
-export { a6 as Unset, ad as isUnset, af as unset } from './shared/attaform.DDXrY-1Q.mjs';
-export { A as AttaformErrorCode, i as injectForm, u as useRegister } from './shared/attaform.DOKOyb3Y.mjs';
+import { ae as ValidateOnConfig, F as FormKey, B as OnInvalidSubmitPolicy, W as PersistConfig, x as HistoryConfig, C as CoercionRegistry, G as GenericForm, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, d as UseFormReturnType, n as FieldMetaPayload } from './shared/attaform.0Gxd_OOx.mjs';
+export { ac as Unset, am as isUnset, ao as unset } from './shared/attaform.0Gxd_OOx.mjs';
+export { A as AttaformErrorCode, i as injectForm, u as useRegister } from './shared/attaform.CPx7zTgS.mjs';
 import 'vue';
 
 /**
@@ -160,5 +160,78 @@ type ZodTypeMap = {
  */
 declare function isZodSchemaType<K extends keyof ZodTypeMap>(schema: unknown, expectedType: K): schema is ZodTypeMap[K];
 
-export { isZodSchemaType, useForm, zodAdapter };
+/**
+ * Field-metadata write/read API for the Zod v3 adapter.
+ *
+ * Zod 3 has no `z.registry()` mechanism, so we shim one with a
+ * module-scoped `WeakMap<ZodTypeAny, FieldMetaPayload>` plus a
+ * registry-shaped object exposing `add` / `get` / `has`. The public
+ * `withMeta(schema, payload)` write API matches `attaform/zod` so
+ * schema authoring reads identically across the two adapters.
+ *
+ * **Registration patterns:** both styles work — register on whatever
+ * schema reference you assign into the parent's shape, OR on the
+ * inner schema before wrapping. The adapter's resolver tries the
+ * walker-returned schema first, then falls back to the peeled
+ * inner so either ordering hits:
+ *
+ *     // both equivalent — registry hits at lookup time
+ *     withMeta(z.string(), { label: 'Email' }).optional()
+ *     withMeta(z.string().optional(), { label: 'Email' })
+ *
+ * The path walker returns the wrapper at terminal positions and
+ * peels at intermediate descent. The two-stage lookup covers both
+ * leaf and container registrations symmetrically.
+ */
+
+/**
+ * The shared registry every Attaform-aware Zod 3 schema can register
+ * field metadata against. Exposes a registry-shaped surface so that
+ * v3 user code can use the same idiom v4 users do (`fieldMeta.add(schema,
+ * payload)`); under the hood it's just a `WeakMap`.
+ */
+type FieldMetaRegistryV3 = {
+    /**
+     * Register `payload` against `schema`. Returns the registry to
+     * mirror Zod 4's `$ZodRegistry.add` chain shape.
+     */
+    add<S extends z.ZodTypeAny>(schema: S, payload: FieldMetaPayload): FieldMetaRegistryV3;
+    /**
+     * Read the registered payload for a schema, or `undefined` if
+     * nothing has been registered.
+     */
+    get(schema: z.ZodTypeAny): FieldMetaPayload | undefined;
+    /** True iff a payload has been registered for the schema. */
+    has(schema: z.ZodTypeAny): boolean;
+};
+declare const fieldMeta: FieldMetaRegistryV3;
+/**
+ * Attach `payload` to `schema` in the shared `fieldMeta` registry
+ * and return a clone of `schema` (chainable, with the new metadata).
+ * Cross-version with `attaform/zod`'s `withMeta()`.
+ *
+ * **Why clone, not mutate.** The WeakMap shim keys metadata on the
+ * schema reference. Calling `withMeta` twice on the same instance
+ * would overwrite (last-write-wins) — so a sub-schema reused at
+ * multiple form paths (e.g. an address schema shared between pickup
+ * and delivery) couldn't carry distinct metadata per path.
+ *
+ * `withMeta` sidesteps the footgun by reconstructing `schema` via
+ * its constructor + `_def` — Zod 3 schemas don't expose `.clone()`,
+ * but `new schema.constructor(schema._def)` is the equivalent. Each
+ * call gets a fresh identity and a fresh registry slot. Existing
+ * metadata on the original is merged through, so chaining
+ * `withMeta` accumulates payload fields rather than replacing.
+ *
+ * Inner field schemas (e.g. an object's `.shape.city`) are shared
+ * across clones — the def is held by reference — so leaf metadata
+ * registers once and surfaces at every path.
+ *
+ * `schema.register()` does NOT exist on Zod 3 — `withMeta` is the
+ * only write API. Register on the inner schema before wrapping;
+ * see the "Registration rule" note in this file's header.
+ */
+declare function withMeta<S extends z.ZodTypeAny>(schema: S, payload: FieldMetaPayload): S;
+
+export { FieldMetaPayload, fieldMeta, isZodSchemaType, useForm, withMeta, zodAdapter };
 export type { TypeWithNullableDynamicKeys, UnwrapZodObject, UseFormConfigurationWithZod, ZodTypeWithInnerType };

package/dist/zod-v3.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { a8 as ValidateOnConfig, F as FormKey, x as OnInvalidSubmitPolicy, E as PersistConfig, v as HistoryConfig, C as CoercionRegistry, G as GenericForm, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, d as UseFormReturnType } from './shared/attaform.DDXrY-1Q.js';
-export { a6 as Unset, ad as isUnset, af as unset } from './shared/attaform.DDXrY-1Q.js';
-export { A as AttaformErrorCode, i as injectForm, u as useRegister } from './shared/attaform.BYc9kugA.js';
+import { ae as ValidateOnConfig, F as FormKey, B as OnInvalidSubmitPolicy, W as PersistConfig, x as HistoryConfig, C as CoercionRegistry, G as GenericForm, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, d as UseFormReturnType, n as FieldMetaPayload } from './shared/attaform.0Gxd_OOx.js';
+export { ac as Unset, am as isUnset, ao as unset } from './shared/attaform.0Gxd_OOx.js';
+export { A as AttaformErrorCode, i as injectForm, u as useRegister } from './shared/attaform.riAENZQM.js';
 import 'vue';
 
 /**
@@ -160,5 +160,78 @@ type ZodTypeMap = {
  */
 declare function isZodSchemaType<K extends keyof ZodTypeMap>(schema: unknown, expectedType: K): schema is ZodTypeMap[K];
 
-export { isZodSchemaType, useForm, zodAdapter };
+/**
+ * Field-metadata write/read API for the Zod v3 adapter.
+ *
+ * Zod 3 has no `z.registry()` mechanism, so we shim one with a
+ * module-scoped `WeakMap<ZodTypeAny, FieldMetaPayload>` plus a
+ * registry-shaped object exposing `add` / `get` / `has`. The public
+ * `withMeta(schema, payload)` write API matches `attaform/zod` so
+ * schema authoring reads identically across the two adapters.
+ *
+ * **Registration patterns:** both styles work — register on whatever
+ * schema reference you assign into the parent's shape, OR on the
+ * inner schema before wrapping. The adapter's resolver tries the
+ * walker-returned schema first, then falls back to the peeled
+ * inner so either ordering hits:
+ *
+ *     // both equivalent — registry hits at lookup time
+ *     withMeta(z.string(), { label: 'Email' }).optional()
+ *     withMeta(z.string().optional(), { label: 'Email' })
+ *
+ * The path walker returns the wrapper at terminal positions and
+ * peels at intermediate descent. The two-stage lookup covers both
+ * leaf and container registrations symmetrically.
+ */
+
+/**
+ * The shared registry every Attaform-aware Zod 3 schema can register
+ * field metadata against. Exposes a registry-shaped surface so that
+ * v3 user code can use the same idiom v4 users do (`fieldMeta.add(schema,
+ * payload)`); under the hood it's just a `WeakMap`.
+ */
+type FieldMetaRegistryV3 = {
+    /**
+     * Register `payload` against `schema`. Returns the registry to
+     * mirror Zod 4's `$ZodRegistry.add` chain shape.
+     */
+    add<S extends z.ZodTypeAny>(schema: S, payload: FieldMetaPayload): FieldMetaRegistryV3;
+    /**
+     * Read the registered payload for a schema, or `undefined` if
+     * nothing has been registered.
+     */
+    get(schema: z.ZodTypeAny): FieldMetaPayload | undefined;
+    /** True iff a payload has been registered for the schema. */
+    has(schema: z.ZodTypeAny): boolean;
+};
+declare const fieldMeta: FieldMetaRegistryV3;
+/**
+ * Attach `payload` to `schema` in the shared `fieldMeta` registry
+ * and return a clone of `schema` (chainable, with the new metadata).
+ * Cross-version with `attaform/zod`'s `withMeta()`.
+ *
+ * **Why clone, not mutate.** The WeakMap shim keys metadata on the
+ * schema reference. Calling `withMeta` twice on the same instance
+ * would overwrite (last-write-wins) — so a sub-schema reused at
+ * multiple form paths (e.g. an address schema shared between pickup
+ * and delivery) couldn't carry distinct metadata per path.
+ *
+ * `withMeta` sidesteps the footgun by reconstructing `schema` via
+ * its constructor + `_def` — Zod 3 schemas don't expose `.clone()`,
+ * but `new schema.constructor(schema._def)` is the equivalent. Each
+ * call gets a fresh identity and a fresh registry slot. Existing
+ * metadata on the original is merged through, so chaining
+ * `withMeta` accumulates payload fields rather than replacing.
+ *
+ * Inner field schemas (e.g. an object's `.shape.city`) are shared
+ * across clones — the def is held by reference — so leaf metadata
+ * registers once and surfaces at every path.
+ *
+ * `schema.register()` does NOT exist on Zod 3 — `withMeta` is the
+ * only write API. Register on the inner schema before wrapping;
+ * see the "Registration rule" note in this file's header.
+ */
+declare function withMeta<S extends z.ZodTypeAny>(schema: S, payload: FieldMetaPayload): S;
+
+export { FieldMetaPayload, fieldMeta, isZodSchemaType, useForm, withMeta, zodAdapter };
 export type { TypeWithNullableDynamicKeys, UnwrapZodObject, UseFormConfigurationWithZod, ZodTypeWithInnerType };

package/dist/zod-v3.mjs

@@ -1,10 +1,34 @@
 import { merge, set, isFunction, cloneDeep } from 'lodash-es';
 import { z } from 'zod';
-import { g as getAtPath, s as slimKindOf, A as AttaformErrorCode, c as useAbstractForm } from './shared/attaform.BRTxpA3q.mjs';
-export { i as injectForm, b as isUnset, u as unset } from './shared/attaform.BRTxpA3q.mjs';
-import { c as canonicalizePath } from './shared/attaform.Cc93zNzD.mjs';
-import { a as AttaformError, _ as __DEV__ } from './shared/attaform.al_rpt7_.mjs';
-export { u as useRegister } from './shared/attaform.al_rpt7_.mjs';
+import { g as getAtPath, s as slimKindOf, A as AttaformErrorCode, h as humanize, c as useAbstractForm } from './shared/attaform.qxyip_aN.mjs';
+export { i as injectForm, b as isUnset, u as unset } from './shared/attaform.qxyip_aN.mjs';
+import { c as canonicalizePath } from './shared/attaform.DXye3JKf.mjs';
+import { a as AttaformError, _ as __DEV__ } from './shared/attaform.a99dQV7Q.mjs';
+export { u as useRegister } from './shared/attaform.a99dQV7Q.mjs';
+
+const store = /* @__PURE__ */ new WeakMap();
+const fieldMeta = {
+  add(schema, payload) {
+    store.set(schema, payload);
+    return fieldMeta;
+  },
+  get(schema) {
+    return store.get(schema);
+  },
+  has(schema) {
+    return store.has(schema);
+  }
+};
+function withMeta(schema, payload) {
+  const existing = store.get(schema) ?? {};
+  const Ctor = schema.constructor;
+  const cloned = new Ctor(schema._def);
+  store.set(cloned, { ...existing, ...payload });
+  return cloned;
+}
+function getFieldMeta(schema) {
+  return store.get(schema);
+}
 
 class UnsupportedSchemaError extends AttaformError {
 }
@@ -659,6 +683,9 @@ function zodAdapter(zodSchema) {
         if (!leaf) return false;
         return isLeafRequiredV3(leaf);
       },
+      getFieldMetaAtPath(path) {
+        return resolveFieldMetaAtPathV3(_zodSchema, path);
+      },
       getUnionDiscriminatorAtPath(path) {
         const candidates = path.length === 0 ? [_zodSchema] : getNestedZodSchemasAtPath(_zodSchema, path);
         let matchedUnion;
@@ -1486,6 +1513,29 @@ function getSlimSchema(config) {
   const processedRootSchema = stripRootSchema(config.schema, config.stripConfig)[0];
   return _getSlimSchema(processedRootSchema);
 }
+function resolveFieldMetaAtPathV3(rootSchema, path) {
+  const lastSegment = path.length === 0 ? "" : path[path.length - 1];
+  const target = path.length === 0 ? rootSchema : walkV3ToLeafSchema(rootSchema, path);
+  if (target === void 0) {
+    return {
+      label: humanize(lastSegment),
+      description: void 0,
+      placeholder: void 0,
+      meta: Object.freeze({})
+    };
+  }
+  const peeled = peelV3Wrappers(target);
+  const payload = getFieldMeta(target) ?? (peeled !== target ? getFieldMeta(peeled) : void 0);
+  const targetDescription = typeof target.description === "string" ? target.description : void 0;
+  const peeledDescription = peeled !== target && typeof peeled.description === "string" ? peeled.description : void 0;
+  const schemaDescription = targetDescription ?? peeledDescription;
+  return {
+    label: payload?.label ?? humanize(lastSegment),
+    description: payload?.description ?? schemaDescription ?? void 0,
+    placeholder: payload?.placeholder ?? void 0,
+    meta: Object.freeze({ ...payload ?? {} })
+  };
+}
 
 function useForm(configuration) {
   function isZodType(value) {
@@ -1500,5 +1550,5 @@ function useForm(configuration) {
   });
 }
 
-export { AttaformErrorCode, isZodSchemaType, useForm, zodAdapter };
+export { AttaformErrorCode, fieldMeta, isZodSchemaType, useForm, withMeta, zodAdapter };
 //# sourceMappingURL=zod-v3.mjs.map