docs(forms): transformedValue parse error wiring

sonukapoor · thePunderWoman · commit fe7b26e403fe · 2026-02-25T16:13:16.000Z
(cherry picked from commit 547ed65)
diff --git a/packages/forms/signals/src/api/transformed_value.ts b/packages/forms/signals/src/api/transformed_value.ts
@@ -23,7 +23,7 @@ import type {OneOrMany} from './types';
  */
 export interface ParseResult<TValue> {
   /**
-   * The parsed value, if parsing was successful.
+   * The parsed value. If omitted, the model is not updated.
    */
   readonly value?: TValue;
   /**
@@ -75,6 +75,14 @@ export interface TransformedValueSignal<TRaw> extends WritableSignal<TRaw> {
  * representation into an underlying model value. For example, a numeric input that displays and
  * accepts string values but stores a number.
  *
+ * Parse errors are exposed via the returned signal&rsquo;s `parseErrors()` property.
+ * When `transformedValue` is used within a Signal Forms field context, parse errors are also
+ * reported to the nearest field automatically. When no field context is present, no automatic
+ * reporting occurs and `parseErrors` can be consumed directly.
+ *
+ * Note: `parse` may return both a `value` and an `error`. Returning `value` updates the model;
+ * omitting it leaves the model unchanged.
+ *
  * @param value The model signal to synchronize with.
  * @param options Configuration including `parse` and `format` functions.
  * @returns A `TransformedValueSignal` representing the raw value with parse error tracking.
