attaform 0.17.0 → 0.17.2

package/dist/shared/{attaform.BYbsV2Wv.d.ts → attaform.C_5aB6EQ.d.mts}

@@ -670,6 +670,34 @@ type AbstractSchema<Form, GetValueFormType> = {
      * callers treat that as "don't fill" and fall back to existing data.
      */
     getDefaultAtPath(path: Path): unknown;
+    /**
+     * Return the schema's "appropriate nullish value" at the given path
+     * — the underlying type's empty/falsy concrete, with `.default(x)`
+     * wrappers explicitly NOT honoured. Powers `form.clear(path)`:
+     * `clear` differs from `reset` precisely in that it ignores
+     * declared defaults and produces `false` / `0` / `''` / `[]` / a
+     * recursively-empty object instead.
+     *
+     * Semantics (mirrors `getDefaultAtPath`'s sub-path resolution,
+     * differs at leaves):
+     * - **Primitive leaf:** the primitive's falsy concrete
+     *   (`''` / `0` / `false` / `0n` / `new Date(0)`, etc.).
+     * - **Array / Set / Record:** empty.
+     * - **Optional<T>:** `undefined` (the wrapper's "absent" marker).
+     * - **Nullable<T>:** `null` (the wrapper's "explicit empty").
+     * - **Default<T> / Prefault<T> / Catch<T>:** inner-schema empty
+     *   — the declared default value is INTENTIONALLY skipped.
+     * - **Readonly<T> / preprocess(fn, T):** inner-schema empty.
+     * - **Object:** recursive — every property gets its own empty.
+     * - **Discriminated union:** first variant's recursive empty
+     *   (parallels `getDefaultAtPath`'s first-success precedent).
+     * - **Path doesn't exist in schema:** `undefined`.
+     *
+     * Adapters may return `undefined` when the path can't be resolved;
+     * callers treat that as "don't write" and leave existing storage
+     * unchanged.
+     */
+    getEmptyValueAtPath(path: Path): unknown;
     /**
      * Give the schema a chance to normalize the consumer's write value
      * before it lands in storage / hits the slim-primitive gate. Each
@@ -3016,23 +3044,30 @@ type FormMeta<F = unknown> = FieldState<F> & {
  * form.meta.submitting        // form-level reactive flag
  * ```
  *
- * Two generic slots split the input view from the output view:
+ * Three generic slots split the write view, parse view, and read view:
  *
- * - `Form` — the **input / storage shape** (`z.input<Schema>`). Used
- *   by `setValue`, `defaultValues`, `values`, `fields`, `register`,
- *   `toRef`, and every path-addressed API. Storage holds values as
- *   the consumer wrote them; preprocess normalization runs at the
- *   write boundary, but `.transform()`s are deferred to parse-time.
+ * - `Form` — the **input / write shape** (`z.input<Schema>`). Used
+ *   by `setValue`, `defaultValues`, and `register`'s write side.
+ *   Loose: preprocess paths accept `unknown` at the write boundary,
+ *   defaulted fields accept their inner type optionally.
  *
  * - `GetValueFormType` — the **output / parsed shape**
  *   (`z.output<Schema>`). Used by `handleSubmit`'s `onSubmit`
  *   callback and by `form.process()`'s success payload. This is the
  *   shape after refinements have fired and transforms have run.
  *
- * For schemas without transforms the two are identical, and the
- * default `GetValueFormType = Form` keeps the surface ergonomic.
+ * - `ReadForm` — the **read / storage shape**. Used by `values`,
+ *   `fields`, `register`'s read side, `toRef`. Per-key precise: at
+ *   the write-boundary wrappers (`default` / `prefault` / `catch` /
+ *   `readonly` / `preprocess`) the value is `z.output<Inner>`
+ *   (default has fired, preprocess has normalized); at transforms /
+ *   pipes the value stays `z.input<Inner>` (transforms are deferred
+ *   until parse). For schema-agnostic call sites defaults to `Form`.
+ *
+ * For schemas without write-boundary wrappers or transforms the three
+ * shapes coincide.
  */
-type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form> = {
+type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form> = {
     /**
      * Wraps your submit logic with validation and error routing.
      *
@@ -3079,7 +3114,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * value reads as `string`, not `boolean`. Use `handleSubmit` or
      * `form.process()` when you need the post-transform output shape.
      */
-    values: ValuesSurface<WriteShape<Form>>;
+    values: ValuesSurface<WriteShape<ReadForm>>;
     /**
      * Reactive per-field state proxy. Pinia-style nested object — read
      * leaf properties (`value`, `dirty`, `touched`, `errors`, `blurred`,
@@ -3108,7 +3143,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * Document edge case; rename the offending schema field if the
      * collision matters.
      */
-    fields: FieldStateMap<WriteShape<Form>>;
+    fields: FieldStateMap<WriteShape<ReadForm>>;
     /**
      * Write to the form programmatically. Two forms:
      *
@@ -3259,8 +3294,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * for storage activity to actually happen.
      */
     register: {
-        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, Path>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, JoinSegments<S>>>;
+        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, Path>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>;
     };
     /**
      * The form's identifier — either the explicit `key` passed to
@@ -3315,8 +3350,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * scripts; `toRef` is for ref-shaped interop only.
      */
     toRef: {
-        <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<Form>, Path>>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<Form>, JoinSegments<S>>>>;
+        <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, Path>>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>>;
     };
     /**
      * Replace every field error for this form with the provided list.
@@ -3430,6 +3465,51 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * from the persisted draft too.
      */
     resetField: (path: FlatPath<Form>) => void;
+    /**
+     * Wipe a field (or the whole form) to the "appropriate nullish
+     * value" for its declared type — the underlying type's empty/falsy
+     * concrete, with any `.default(x)` wrapper INTENTIONALLY skipped.
+     * Orthogonal to `reset` / `resetField` by design.
+     *
+     * ```ts
+     * const schema = z.object({
+     *   notify: z.boolean().default(true),
+     *   count: z.number().default(5),
+     * })
+     * const form = useForm({ schema })
+     *
+     * form.reset()         // notify → true,  count → 5  (defaults)
+     * form.clear()         // notify → false, count → 0  (falsy-for-type)
+     * form.clear('notify') // → false (NOT the declared default true)
+     * ```
+     *
+     * Per-wrapper semantics:
+     *
+     * - `.default(x)` / `.prefault(x)` / `.catch(x)` → inner-schema
+     *   empty (default is INTENTIONALLY skipped).
+     * - `.optional()` → `undefined` (the wrapper's "absent" marker).
+     * - `.nullable()` → `null` (the wrapper's "explicit empty").
+     * - Object → recursive (every property gets its own empty).
+     * - Array / Set / Record → empty.
+     *
+     * Returns `true` when the write was accepted, `false` when the
+     * adapter couldn't resolve an empty value at the path (e.g. the
+     * path doesn't exist in the schema). The form state is unchanged
+     * on a `false` return.
+     *
+     * Sugar over `setValue(path, schema.getEmptyValueAtPath(path))` —
+     * no separate bookkeeping. Variant memory, history, persistence,
+     * and listeners all see this as a regular write at the path.
+     *
+     * `clear()` (no arg) targets the whole form. `clear('')` targets
+     * the empty-string path slot SPECIFICALLY — the two are NOT
+     * interchangeable, matching `touch()` / `touch('')` from #184.
+     */
+    clear: {
+        (): boolean;
+        <Path extends FlatPath<Form> | ''>(path: Path): boolean;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form> | ''] ? unknown : never)): boolean;
+    };
     /**
      * Write the current value at `path` to storage immediately. Useful
      * for explicit "Save draft" buttons, `beforeunload` handlers, or

package/dist/shared/{attaform.BYbsV2Wv.d.cts → attaform.C_5aB6EQ.d.ts}

@@ -670,6 +670,34 @@ type AbstractSchema<Form, GetValueFormType> = {
      * callers treat that as "don't fill" and fall back to existing data.
      */
     getDefaultAtPath(path: Path): unknown;
+    /**
+     * Return the schema's "appropriate nullish value" at the given path
+     * — the underlying type's empty/falsy concrete, with `.default(x)`
+     * wrappers explicitly NOT honoured. Powers `form.clear(path)`:
+     * `clear` differs from `reset` precisely in that it ignores
+     * declared defaults and produces `false` / `0` / `''` / `[]` / a
+     * recursively-empty object instead.
+     *
+     * Semantics (mirrors `getDefaultAtPath`'s sub-path resolution,
+     * differs at leaves):
+     * - **Primitive leaf:** the primitive's falsy concrete
+     *   (`''` / `0` / `false` / `0n` / `new Date(0)`, etc.).
+     * - **Array / Set / Record:** empty.
+     * - **Optional<T>:** `undefined` (the wrapper's "absent" marker).
+     * - **Nullable<T>:** `null` (the wrapper's "explicit empty").
+     * - **Default<T> / Prefault<T> / Catch<T>:** inner-schema empty
+     *   — the declared default value is INTENTIONALLY skipped.
+     * - **Readonly<T> / preprocess(fn, T):** inner-schema empty.
+     * - **Object:** recursive — every property gets its own empty.
+     * - **Discriminated union:** first variant's recursive empty
+     *   (parallels `getDefaultAtPath`'s first-success precedent).
+     * - **Path doesn't exist in schema:** `undefined`.
+     *
+     * Adapters may return `undefined` when the path can't be resolved;
+     * callers treat that as "don't write" and leave existing storage
+     * unchanged.
+     */
+    getEmptyValueAtPath(path: Path): unknown;
     /**
      * Give the schema a chance to normalize the consumer's write value
      * before it lands in storage / hits the slim-primitive gate. Each
@@ -3016,23 +3044,30 @@ type FormMeta<F = unknown> = FieldState<F> & {
  * form.meta.submitting        // form-level reactive flag
  * ```
  *
- * Two generic slots split the input view from the output view:
+ * Three generic slots split the write view, parse view, and read view:
  *
- * - `Form` — the **input / storage shape** (`z.input<Schema>`). Used
- *   by `setValue`, `defaultValues`, `values`, `fields`, `register`,
- *   `toRef`, and every path-addressed API. Storage holds values as
- *   the consumer wrote them; preprocess normalization runs at the
- *   write boundary, but `.transform()`s are deferred to parse-time.
+ * - `Form` — the **input / write shape** (`z.input<Schema>`). Used
+ *   by `setValue`, `defaultValues`, and `register`'s write side.
+ *   Loose: preprocess paths accept `unknown` at the write boundary,
+ *   defaulted fields accept their inner type optionally.
  *
  * - `GetValueFormType` — the **output / parsed shape**
  *   (`z.output<Schema>`). Used by `handleSubmit`'s `onSubmit`
  *   callback and by `form.process()`'s success payload. This is the
  *   shape after refinements have fired and transforms have run.
  *
- * For schemas without transforms the two are identical, and the
- * default `GetValueFormType = Form` keeps the surface ergonomic.
+ * - `ReadForm` — the **read / storage shape**. Used by `values`,
+ *   `fields`, `register`'s read side, `toRef`. Per-key precise: at
+ *   the write-boundary wrappers (`default` / `prefault` / `catch` /
+ *   `readonly` / `preprocess`) the value is `z.output<Inner>`
+ *   (default has fired, preprocess has normalized); at transforms /
+ *   pipes the value stays `z.input<Inner>` (transforms are deferred
+ *   until parse). For schema-agnostic call sites defaults to `Form`.
+ *
+ * For schemas without write-boundary wrappers or transforms the three
+ * shapes coincide.
  */
-type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form> = {
+type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form> = {
     /**
      * Wraps your submit logic with validation and error routing.
      *
@@ -3079,7 +3114,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * value reads as `string`, not `boolean`. Use `handleSubmit` or
      * `form.process()` when you need the post-transform output shape.
      */
-    values: ValuesSurface<WriteShape<Form>>;
+    values: ValuesSurface<WriteShape<ReadForm>>;
     /**
      * Reactive per-field state proxy. Pinia-style nested object — read
      * leaf properties (`value`, `dirty`, `touched`, `errors`, `blurred`,
@@ -3108,7 +3143,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * Document edge case; rename the offending schema field if the
      * collision matters.
      */
-    fields: FieldStateMap<WriteShape<Form>>;
+    fields: FieldStateMap<WriteShape<ReadForm>>;
     /**
      * Write to the form programmatically. Two forms:
      *
@@ -3259,8 +3294,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * for storage activity to actually happen.
      */
     register: {
-        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, Path>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, JoinSegments<S>>>;
+        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, Path>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>;
     };
     /**
      * The form's identifier — either the explicit `key` passed to
@@ -3315,8 +3350,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * scripts; `toRef` is for ref-shaped interop only.
      */
     toRef: {
-        <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<Form>, Path>>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<Form>, JoinSegments<S>>>>;
+        <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, Path>>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>>;
     };
     /**
      * Replace every field error for this form with the provided list.
@@ -3430,6 +3465,51 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * from the persisted draft too.
      */
     resetField: (path: FlatPath<Form>) => void;
+    /**
+     * Wipe a field (or the whole form) to the "appropriate nullish
+     * value" for its declared type — the underlying type's empty/falsy
+     * concrete, with any `.default(x)` wrapper INTENTIONALLY skipped.
+     * Orthogonal to `reset` / `resetField` by design.
+     *
+     * ```ts
+     * const schema = z.object({
+     *   notify: z.boolean().default(true),
+     *   count: z.number().default(5),
+     * })
+     * const form = useForm({ schema })
+     *
+     * form.reset()         // notify → true,  count → 5  (defaults)
+     * form.clear()         // notify → false, count → 0  (falsy-for-type)
+     * form.clear('notify') // → false (NOT the declared default true)
+     * ```
+     *
+     * Per-wrapper semantics:
+     *
+     * - `.default(x)` / `.prefault(x)` / `.catch(x)` → inner-schema
+     *   empty (default is INTENTIONALLY skipped).
+     * - `.optional()` → `undefined` (the wrapper's "absent" marker).
+     * - `.nullable()` → `null` (the wrapper's "explicit empty").
+     * - Object → recursive (every property gets its own empty).
+     * - Array / Set / Record → empty.
+     *
+     * Returns `true` when the write was accepted, `false` when the
+     * adapter couldn't resolve an empty value at the path (e.g. the
+     * path doesn't exist in the schema). The form state is unchanged
+     * on a `false` return.
+     *
+     * Sugar over `setValue(path, schema.getEmptyValueAtPath(path))` —
+     * no separate bookkeeping. Variant memory, history, persistence,
+     * and listeners all see this as a regular write at the path.
+     *
+     * `clear()` (no arg) targets the whole form. `clear('')` targets
+     * the empty-string path slot SPECIFICALLY — the two are NOT
+     * interchangeable, matching `touch()` / `touch('')` from #184.
+     */
+    clear: {
+        (): boolean;
+        <Path extends FlatPath<Form> | ''>(path: Path): boolean;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form> | ''] ? unknown : never)): boolean;
+    };
     /**
      * Write the current value at `path` to storage immediately. Useful
      * for explicit "Save draft" buttons, `beforeunload` handlers, or

package/dist/shared/{attaform.BFumZXY2.cjs → attaform.Cer8JO_P.cjs}

@@ -2458,6 +2458,10 @@ function buildFormApi(state, formInstanceId, options = {}) {
       void persistence.clearPersistedDraft(segments).catch(() => void 0);
     }
   };
+  function clear(pathInput) {
+    const segments = pathInput === void 0 ? paths.ROOT_PATH : paths.canonicalizePath(pathInput).segments;
+    return state.clear(segments);
+  }
   const persist = async (pathInput, options2) => {
     const segments = paths.canonicalizePath(pathInput).segments;
     plugin.enforceSensitiveCheck(segments, options2?.acknowledgeSensitive === true, state.isSensitivePath);
@@ -2520,6 +2524,7 @@ function buildFormApi(state, formInstanceId, options = {}) {
     meta: formMeta,
     reset,
     resetField,
+    clear,
     persist,
     clearPersistedDraft,
     focusFirstError,
@@ -3406,6 +3411,9 @@ function createFormStore(options) {
       );
     }
   }
+  function clear(path) {
+    return setValueAtPath(path, schema.getEmptyValueAtPath(path));
+  }
   function reset(nextDefaultValues) {
     const resetSource = nextDefaultValues ?? defaultValues;
     const completedResetConstraints = resetSource === void 0 ? void 0 : mergeStructural(schema, [], resetSource);
@@ -3616,6 +3624,7 @@ function createFormStore(options) {
     getValueAtPath,
     reset,
     resetField,
+    clear,
     setSchemaErrorsForPath,
     setAllSchemaErrors,
     clearSchemaErrors,
@@ -4328,7 +4337,11 @@ function useAbstractForm(configuration) {
   if (merged.rememberVariants !== void 0) {
     apiOptions.rememberVariants = merged.rememberVariants;
   }
-  return buildFormApi(state, formInstanceId, apiOptions);
+  return buildFormApi(
+    state,
+    formInstanceId,
+    apiOptions
+  );
 }
 function mergeWithDefaults(defaults, configuration) {
   const strict = configuration.strict ?? defaults.strict;
@@ -4819,4 +4832,4 @@ exports.setAtPath = setAtPath;
 exports.slimKindOf = slimKindOf;
 exports.unset = unset;
 exports.useAbstractForm = useAbstractForm;
-//# sourceMappingURL=attaform.BFumZXY2.cjs.map
+//# sourceMappingURL=attaform.Cer8JO_P.cjs.map