@vtex/faststore 0.0.4 → 0.0.6

package/dist/particles/document-field/document-field.d.ts

@@ -1,28 +1,52 @@
 import { ComponentDefinition } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
 import { applyMask } from "../shared/input-mask.js";
-import { ComponentPropsWithRef, FocusEvent } from "react";
+import { ComponentPropsWithRef, FocusEvent, ReactNode, Ref } from "react";
 //#region src/particles/document-field/document-field.d.ts
 export type DocumentType = 'CPF';
+type DocumentFieldRequirement = 'mandatory' | 'optional';
 export type DocumentSpec = {
   id: DocumentType;
   name: string;
   mask: string;
   validate: (value: string) => boolean;
 };
-export type DocumentFieldProps = Omit<ComponentPropsWithRef<'div'>, 'defaultValue' | 'value' | 'onChange' | 'onBlur'> & {
+export type DocumentFieldProps = Omit<ComponentPropsWithRef<'div'>, 'defaultValue' | 'value' | 'onChange' | 'onBlur' | 'ref' | 'dangerouslySetInnerHTML'> & {
+  /** Unused on the bound path — react-hook-form owns the value. */
   value?: string;
+  /** Unused on the bound path — the field contract's `defaultValue` seeds it instead. */
   defaultValue?: string;
   onValueChange?: (value: string) => void;
   onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
   invalid?: boolean;
   errorMessage?: string;
+  /** Falls back to the field contract's `label` when bound. */
   label?: string;
+  /** Falls back to the field contract's `placeholder` when bound. */
   placeholder?: string;
+  /** Falls back to the field contract's `disabled` when bound. */
   disabled?: boolean;
-  required?: boolean;
+  /**
+   * Raises the field to required, the same word `PhoneField` uses. It only ever raises: bound to a
+   * fieldset whose rule already says required, `'optional'` does not lower it. Left unset it is no
+   * opinion, which keeps CPF optional by recommendation.
+   */
+  requirement?: DocumentFieldRequirement;
   name?: string;
   documentType?: DocumentType;
+  /**
+   * Lands on the `<input>` `Field.Control` renders — not on the wrapper `<div>`, as it did before
+   * (a deliberate, source-breaking re-route: the previous ref pointed at an untabbable div). Composed
+   * with react-hook-form's own ref on the bound path.
+   */
+  ref?: Ref<HTMLInputElement>;
+  /**
+   * Given, replaces the default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy — any
+   * order, any subset. `DocumentFieldInput` is the one part that carries the mask, the composed ref
+   * and the particle's own value/handlers; a composed generic `Field.Control` would call
+   * `useController` a second time for the same name (RFC's named, accepted double-binder hole).
+   */
+  children?: ReactNode;
 };
 /**
  * CPF check-digit validation, ported from the legacy `validateCPF`. Strips non-digits, requires
@@ -31,7 +55,15 @@ export type DocumentFieldProps = Omit<ComponentPropsWithRef<'div'>, 'defaultValu
  */
 export declare function validateCPF(value: string): boolean;
 export declare const DOCUMENTS: Record<DocumentType, DocumentSpec>;
-/** True when `type` is a document type this build supports (lets a host gate the field by locale). */
+/**
+ * True when `type` is a document type this build supports (lets a host gate the field by locale).
+ *
+ * `Object.hasOwn`, not the `in` operator: `in` walks the prototype chain, so `constructor`,
+ * `__proto__` and `toString` all satisfied it and were then trusted as a `DocumentType` by callers
+ * (`client-profile-fieldset.tsx` renders the field on the strength of this narrowing). The value is
+ * author-only — a literal written into `page.json`, never a runtime expression — so this is
+ * robustness rather than a reachable defect, but the narrowing should not be able to lie.
+ */
 export declare function isSupportedDocumentType(type: unknown): type is DocumentType;
 /**
  * Apply a document type's mask to raw input: strip non-digits for digit-only masks, then truncate to
@@ -54,8 +86,19 @@ export declare const DocumentFieldDefinition: ComponentDefinition<DocumentFieldP
  * when the check digit fails or when the host forces `invalid` (e.g. a server error surfaced by the
  * form that owns the write). It consumes no GraphQL and no domain context — value flows through
  * `value`/`defaultValue`/`onValueChange`, and `documentType` selects the mask + validator.
+ *
+ * Reads the field contract through `useField()` and `useFormContext()` and dispatches to a bound or an
+ * unbound sub-component — "bound" means both are present. Every react-hook-form hook lives in
+ * `BoundDocumentField`, so hook order never changes under a mounted component. Both sub-components
+ * render the same `DocumentFieldView`, so the two paths cannot drift into different DOM.
  */
-export declare function DocumentField({ value, defaultValue, onValueChange, onBlur, invalid, errorMessage, label, placeholder, disabled, required, name, documentType, className, ...props }: DocumentFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function DocumentField(props: DocumentFieldProps): ReactNode;
+export type DocumentFieldInputProps = {
+  className?: string;
+};
+export declare const DocumentFieldInputDefinition: ComponentDefinition<DocumentFieldInputProps>;
+/** Renders the masked document `<input>`, reading its value/handlers/ref from the enclosing `DocumentField`. */
+export declare function DocumentFieldInput({ className }: DocumentFieldInputProps): ReactNode;
 //#endregion
 export { applyMask };
 //# sourceMappingURL=document-field.d.ts.map

package/dist/particles/document-field/document-field.js

@@ -1,10 +1,13 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
-import { Field } from "../field/field.js";
+import { FieldBinding, TEXT_FIELD_VALUE, mergeFieldValidator, useBoundField, useField } from "../field/field.js";
+import { useComposedRef } from "../shared/compose-refs.js";
 import { applyMask, countSlots, isDigitOnly } from "../shared/input-mask.js";
-import { useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Field } from "@base-ui/react/field";
+import { useFormContext, useFormState } from "react-hook-form";
 //#region src/particles/document-field/document-field.tsx
 /**
 * CPF check-digit validation, ported from the legacy `validateCPF`. Strips non-digits, requires
@@ -24,9 +27,17 @@ const DOCUMENTS = { CPF: {
 	mask: "999.999.999-99",
 	validate: validateCPF
 } };
-/** True when `type` is a document type this build supports (lets a host gate the field by locale). */
+/**
+* True when `type` is a document type this build supports (lets a host gate the field by locale).
+*
+* `Object.hasOwn`, not the `in` operator: `in` walks the prototype chain, so `constructor`,
+* `__proto__` and `toString` all satisfied it and were then trusted as a `DocumentType` by callers
+* (`client-profile-fieldset.tsx` renders the field on the strength of this narrowing). The value is
+* author-only — a literal written into `page.json`, never a runtime expression — so this is
+* robustness rather than a reachable defect, but the narrowing should not be able to lie.
+*/
 function isSupportedDocumentType(type) {
-	return typeof type === "string" && type in DOCUMENTS;
+	return typeof type === "string" && Object.hasOwn(DOCUMENTS, type);
 }
 /**
 * Apply a document type's mask to raw input: strip non-digits for digit-only masks, then truncate to
@@ -52,6 +63,7 @@ const DocumentFieldDefinition = defineComponent({
 	name: "DocumentField",
 	importPath: "@vtex/faststore/components",
 	component: DocumentField,
+	providesContext: "document-field",
 	editor: {
 		label: "Document Field",
 		category: "content"
@@ -74,10 +86,9 @@ const DocumentFieldDefinition = defineComponent({
 			default: "CPF",
 			label: "Document type"
 		},
-		required: {
-			type: "boolean",
-			default: false,
-			label: "Required"
+		requirement: {
+			type: ["mandatory", "optional"],
+			label: "Requirement"
 		},
 		disabled: {
 			type: "boolean",
@@ -85,7 +96,7 @@ const DocumentFieldDefinition = defineComponent({
 			label: "Disabled"
 		}
 	},
-	guideline: "Presentational tax-document input composing the Field particle; applies the locale mask on change and runs check-digit validation on blur/submit. Data-agnostic (value/defaultValue/onValueChange); a host wires it to the shopper profile. CPF is optional by default."
+	guideline: "Presentational tax-document input composing the Field particle; applies the locale mask on change and runs check-digit validation on blur/submit. Data-agnostic (value/defaultValue/onValueChange); a host wires it to the shopper profile. CPF is optional by default: requirement only ever raises the field to required, announced as aria-required, and bound to a fieldset whose rule already says required it cannot lower it back. Recomposable (RFC:503): given children, they replace the default Field.Label + DocumentFieldInput + Field.Error anatomy, in any order."
 });
 /**
 * Presentational tax-document input (particle). Composes the `Field` particle (`Field.Root` +
@@ -95,8 +106,104 @@ const DocumentFieldDefinition = defineComponent({
 * when the check digit fails or when the host forces `invalid` (e.g. a server error surfaced by the
 * form that owns the write). It consumes no GraphQL and no domain context — value flows through
 * `value`/`defaultValue`/`onValueChange`, and `documentType` selects the mask + validator.
+*
+* Reads the field contract through `useField()` and `useFormContext()` and dispatches to a bound or an
+* unbound sub-component — "bound" means both are present. Every react-hook-form hook lives in
+* `BoundDocumentField`, so hook order never changes under a mounted component. Both sub-components
+* render the same `DocumentFieldView`, so the two paths cannot drift into different DOM.
 */
-function DocumentField({ value, defaultValue = "", onValueChange, onBlur, invalid = false, errorMessage, label, placeholder, disabled = false, required = false, name = "document", documentType = "CPF", className, ...props }) {
+function DocumentField(props) {
+	const contract = useField();
+	const formContext = useFormContext();
+	if (contract && formContext) return /* @__PURE__ */ jsx(BoundDocumentField, {
+		...props,
+		contract
+	});
+	return /* @__PURE__ */ jsx(UnboundDocumentField, { ...props });
+}
+const DocumentFieldInputContext = createContext(null);
+function useDocumentFieldInputContext() {
+	const context = useContext(DocumentFieldInputContext);
+	if (!context) throw new Error("DocumentFieldInput must be a descendant of DocumentField.");
+	return context;
+}
+const DocumentFieldInputDefinition = defineComponent({
+	name: "DocumentFieldInput",
+	importPath: "@vtex/faststore/components",
+	component: DocumentFieldInput,
+	requiresContext: "document-field",
+	editor: {
+		label: "Document Field Input",
+		category: "action"
+	},
+	schema: {},
+	guideline: "The masked document <input> DocumentField owns. Must sit inside DocumentField, in either the default anatomy or an author's composed children. Carries the locale mask, the composed ref, and DocumentField's own onChange/onBlur — a composed Field.Control here instead re-registers the field with react-hook-form and loses the mask (unsupported, RFC's named double-binder hole)."
+});
+/** Renders the masked document `<input>`, reading its value/handlers/ref from the enclosing `DocumentField`. */
+function DocumentFieldInput({ className }) {
+	const { ref, name, value, placeholder, disabled, required, numericOnly, onChange, onBlur } = useDocumentFieldInputContext();
+	return /* @__PURE__ */ jsx(Field.Control, {
+		ref,
+		name,
+		"aria-required": required || void 0,
+		placeholder,
+		disabled,
+		value,
+		...numericOnly ? { inputMode: "numeric" } : {},
+		onChange,
+		onBlur,
+		className,
+		"data-fs-field-control": ""
+	});
+}
+function DocumentFieldView({ className, name, label, placeholder, disabled, required, numericOnly, displayValue, showInvalid, errorMessage, onChange, onBlur, ref, children, ...props }) {
+	const inputContext = useMemo(() => ({
+		ref,
+		name,
+		value: displayValue,
+		placeholder,
+		disabled,
+		required,
+		numericOnly,
+		onChange,
+		onBlur
+	}), [
+		ref,
+		name,
+		displayValue,
+		placeholder,
+		disabled,
+		required,
+		numericOnly,
+		onChange,
+		onBlur
+	]);
+	return /* @__PURE__ */ jsx(Field.Root, {
+		...props,
+		className,
+		name,
+		invalid: showInvalid,
+		disabled,
+		"data-fs-document-field": "",
+		"data-fs-field-root": "",
+		children: /* @__PURE__ */ jsx(DocumentFieldInputContext.Provider, {
+			value: inputContext,
+			children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+				label ? /* @__PURE__ */ jsx(Field.Label, {
+					"data-fs-field-label": "",
+					children: label
+				}) : null,
+				/* @__PURE__ */ jsx(DocumentFieldInput, {}),
+				showInvalid && errorMessage ? /* @__PURE__ */ jsx(Field.Error, {
+					match: true,
+					"data-fs-field-error": "",
+					children: errorMessage
+				}) : null
+			] })
+		})
+	});
+}
+function UnboundDocumentField({ value, defaultValue = "", onValueChange, onBlur, invalid = false, errorMessage, label, placeholder, disabled = false, requirement, name = "document", documentType = "CPF", className, ref, children, ...props }) {
 	const isControlled = value !== void 0;
 	const [internalValue, setInternalValue] = useState(() => maskDocumentValue(defaultValue, documentType));
 	const [checkInvalid, setCheckInvalid] = useState(false);
@@ -114,33 +221,83 @@ function DocumentField({ value, defaultValue = "", onValueChange, onBlur, invali
 		setCheckInvalid(!isValidDocument(currentValue, documentType));
 		onBlur?.(event);
 	}
-	return /* @__PURE__ */ jsxs(Field.Root, {
+	return /* @__PURE__ */ jsx(DocumentFieldView, {
 		...props,
+		ref,
 		className,
 		name,
-		invalid: showInvalid,
+		label,
+		placeholder,
 		disabled,
-		"data-fs-document-field": "",
-		children: [
-			label ? /* @__PURE__ */ jsx(Field.Label, { children: label }) : null,
-			/* @__PURE__ */ jsx(Field.Control, {
-				name,
-				required,
-				placeholder,
-				disabled,
-				value: displayValue,
-				...numericOnly ? { inputMode: "numeric" } : {},
-				onChange: handleChange,
-				onBlur: handleBlur
-			}),
-			showInvalid && errorMessage ? /* @__PURE__ */ jsx(Field.Error, {
-				match: true,
-				children: errorMessage
-			}) : null
-		]
+		required: requirement === "mandatory",
+		numericOnly,
+		displayValue,
+		showInvalid,
+		errorMessage,
+		onChange: handleChange,
+		onBlur: handleBlur,
+		children
+	});
+}
+function BoundDocumentField({ value: _value, defaultValue: _defaultValue, onValueChange, onBlur, invalid = false, errorMessage, label, placeholder, disabled, requirement, name, documentType = "CPF", className, ref: callerRef, contract, children, ...props }) {
+	const rule = useMemo(() => mergeFieldValidator(contract.rule, "checkDigit", (rawValue) => {
+		return isValidDocument(typeof rawValue === "string" ? rawValue : String(rawValue ?? ""), documentType) || (errorMessage ?? false);
+	}), [
+		contract.rule,
+		documentType,
+		errorMessage
+	]);
+	const field = useBoundField(contract, TEXT_FIELD_VALUE, rule, { required: requirement === "mandatory" });
+	const { getFieldState } = useFormContext();
+	const { invalid: rhfInvalid } = getFieldState(contract.name, useFormState({ name: contract.name }));
+	const composedRef = useComposedRef(callerRef, field.ref);
+	const displayValue = maskDocumentValue(typeof field.value === "string" ? field.value : String(field.value ?? ""), documentType);
+	const showInvalid = invalid || rhfInvalid;
+	const numericOnly = isDigitOnly(DOCUMENTS[documentType].mask);
+	const resolvedLabel = label ?? contract.label;
+	const resolvedPlaceholder = placeholder ?? contract.placeholder;
+	const resolvedDisabled = disabled ?? contract.disabled ?? false;
+	const resolvedName = name ?? contract.name;
+	function handleChange(event) {
+		const masked = maskDocumentValue(event.target.value, documentType);
+		field.onChange(masked);
+		onValueChange?.(masked);
+	}
+	function handleBlur(event) {
+		field.onBlur();
+		onBlur?.(event);
+	}
+	return /* @__PURE__ */ jsx(FieldBinding, {
+		name: contract.name,
+		label: resolvedLabel,
+		placeholder: resolvedPlaceholder,
+		defaultValue: contract.defaultValue,
+		rule: contract.rule,
+		options: contract.options,
+		disabled: resolvedDisabled,
+		readOnly: contract.readOnly,
+		autoComplete: contract.autoComplete,
+		inputMode: contract.inputMode,
+		children: /* @__PURE__ */ jsx(DocumentFieldView, {
+			...props,
+			ref: composedRef,
+			className,
+			name: resolvedName,
+			label: resolvedLabel,
+			placeholder: resolvedPlaceholder,
+			disabled: resolvedDisabled,
+			required: field.required,
+			numericOnly,
+			displayValue,
+			showInvalid,
+			errorMessage,
+			onChange: handleChange,
+			onBlur: handleBlur,
+			children
+		})
 	});
 }
 //#endregion
-export { DOCUMENTS, DocumentField, DocumentFieldDefinition, applyMask, isSupportedDocumentType, isValidDocument, maskDocumentValue, validateCPF };
+export { DOCUMENTS, DocumentField, DocumentFieldDefinition, DocumentFieldInput, DocumentFieldInputDefinition, applyMask, isSupportedDocumentType, isValidDocument, maskDocumentValue, validateCPF };
 
 //# sourceMappingURL=document-field.js.map

package/dist/particles/document-field/document-field.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-field.js","names":[],"sources":["../../../src/particles/document-field/document-field.tsx"],"sourcesContent":["'use client';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ChangeEvent, ComponentPropsWithRef, FocusEvent } from 'react';\nimport { useState } from 'react';\nimport { Field } from '../field/field.js';\nimport { applyMask, countSlots, isDigitOnly } from '../shared/input-mask.js';\n\n// `applyMask` was public from this module before the engine moved out; keep the export path stable.\nexport { applyMask } from '../shared/input-mask.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type DocumentType = 'CPF';\n\nexport type DocumentSpec = {\n  id: DocumentType;\n  name: string;\n  mask: string;\n  validate: (value: string) => boolean;\n};\n\nexport type DocumentFieldProps = Omit<\n  ComponentPropsWithRef<'div'>,\n  'defaultValue' | 'value' | 'onChange' | 'onBlur'\n> & {\n  value?: string;\n  defaultValue?: string;\n  onValueChange?: (value: string) => void;\n  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;\n  invalid?: boolean;\n  errorMessage?: string;\n  label?: string;\n  placeholder?: string;\n  disabled?: boolean;\n  required?: boolean;\n  name?: string;\n  documentType?: DocumentType;\n};\n\n// ---------------------------------------------------------------------------\n// Ported check-digit validation (fastcheckout `packages/libs/validators/src/document`).\n// ---------------------------------------------------------------------------\n\n/**\n * CPF check-digit validation, ported from the legacy `validateCPF`. Strips non-digits, requires\n * exactly 11 digits, rejects all-equal sequences (e.g. `111.111.111-11`), and verifies both check\n * digits. Runs on blur/submit only, never per keystroke.\n */\nexport function validateCPF(value: string): boolean {\n  const digits = value.replace(/[^\\d]+/g, '');\n\n  if (digits.length !== 11 || /(\\d)\\1{10}/.test(digits)) {\n    return false;\n  }\n\n  const values = digits.split('').map((el) => +el);\n  const rest = (count: number) =>\n    ((values.slice(0, count - 12).reduce((sum, el, index) => sum + el * (count - index), 0) * 10) % 11) % 10;\n\n  return rest(10) === values[9] && rest(11) === values[10];\n}\n\n// ---------------------------------------------------------------------------\n// Document table (subset needed for the CPF launch). `documentType` selects the mask +\n// validator + digit-only input mode. Extendable later (SSN | SIN | CURP) without touching callers.\n// ---------------------------------------------------------------------------\n\nexport const DOCUMENTS: Record<DocumentType, DocumentSpec> = {\n  CPF: {\n    id: 'CPF',\n    name: 'CPF',\n    mask: '999.999.999-99',\n    validate: validateCPF,\n  },\n};\n\n/** True when `type` is a document type this build supports (lets a host gate the field by locale). */\nexport function isSupportedDocumentType(type: unknown): type is DocumentType {\n  return typeof type === 'string' && type in DOCUMENTS;\n}\n\n/**\n * Apply a document type's mask to raw input: strip non-digits for digit-only masks, then truncate to\n * the mask's slot count so excess characters never trail past the mask (e.g. a 15-digit paste into\n * the 11-slot CPF mask yields `111.444.777-35`, not `111.444.777-358888`).\n */\nexport function maskDocumentValue(rawValue: string, documentType: DocumentType): string {\n  const spec = DOCUMENTS[documentType];\n  const sanitized = isDigitOnly(spec.mask) ? rawValue.replace(/\\D/g, '') : rawValue;\n  const maxSlots = Math.max(...spec.mask.split('|').map(countSlots));\n  return applyMask(sanitized.slice(0, maxSlots), spec.mask);\n}\n\n/**\n * Check-digit validity for a document value. An **empty** value is valid (the field is optional),\n * mirroring the legacy `validateCardholderDocument`; a non-empty value must pass the document\n * type's check-digit validation.\n */\nexport function isValidDocument(value: string, documentType: DocumentType): boolean {\n  if (!value.trim()) return true;\n  return DOCUMENTS[documentType].validate(value);\n}\n\n// ---------------------------------------------------------------------------\n// Component\n// ---------------------------------------------------------------------------\n\nexport const DocumentFieldDefinition = defineComponent<DocumentFieldProps>({\n  name: 'DocumentField',\n  importPath: '@vtex/faststore/components',\n  component: DocumentField,\n  editor: { label: 'Document Field', category: 'content' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    errorMessage: { type: 'string', label: 'Error message' },\n    documentType: { type: 'string', default: 'CPF', label: 'Document type' },\n    required: { type: 'boolean', default: false, label: 'Required' },\n    disabled: { type: 'boolean', default: false, label: 'Disabled' },\n  },\n  guideline:\n    'Presentational tax-document input composing the Field particle; applies the locale mask on change and runs check-digit validation on blur/submit. Data-agnostic (value/defaultValue/onValueChange); a host wires it to the shopper profile. CPF is optional by default.',\n});\n\n/**\n * Presentational tax-document input (particle). Composes the `Field` particle (`Field.Root` +\n * `Field.Label` + `Field.Control` + `Field.Error`) and owns the locale mask (applied progressively on\n * every change, never blocking typing) plus check-digit validation (run on blur/submit only — never\n * per keystroke). An empty value is valid (the field is optional). It surfaces `errorMessage` inline\n * when the check digit fails or when the host forces `invalid` (e.g. a server error surfaced by the\n * form that owns the write). It consumes no GraphQL and no domain context — value flows through\n * `value`/`defaultValue`/`onValueChange`, and `documentType` selects the mask + validator.\n */\nexport function DocumentField({\n  value,\n  defaultValue = '',\n  onValueChange,\n  onBlur,\n  invalid = false,\n  errorMessage,\n  label,\n  placeholder,\n  disabled = false,\n  required = false,\n  name = 'document',\n  documentType = 'CPF',\n  className,\n  ...props\n}: DocumentFieldProps) {\n  const isControlled = value !== undefined;\n  const [internalValue, setInternalValue] = useState(() => maskDocumentValue(defaultValue, documentType));\n  const [checkInvalid, setCheckInvalid] = useState(false);\n\n  const currentValue = isControlled ? value : internalValue;\n  // Masking is idempotent, so masking here formats both a raw pre-fill (a controlled `value` seeded\n  // from the saved profile) and an already-masked typed value identically.\n  const displayValue = maskDocumentValue(currentValue, documentType);\n  const showInvalid = invalid || checkInvalid;\n  const numericOnly = isDigitOnly(DOCUMENTS[documentType].mask);\n\n  function handleChange(event: ChangeEvent<HTMLInputElement>) {\n    const masked = maskDocumentValue(event.target.value, documentType);\n    if (!isControlled) setInternalValue(masked);\n    // Clear a prior check-digit error while typing; it is re-evaluated on the next blur.\n    if (checkInvalid) setCheckInvalid(false);\n    onValueChange?.(masked);\n  }\n\n  function handleBlur(event: FocusEvent<HTMLInputElement>) {\n    // Validation runs only after the complete number is entered; empty is valid (optional field).\n    setCheckInvalid(!isValidDocument(currentValue, documentType));\n    onBlur?.(event);\n  }\n\n  return (\n    <Field.Root\n      {...props}\n      className={className}\n      name={name}\n      invalid={showInvalid}\n      disabled={disabled}\n      data-fs-document-field=\"\"\n    >\n      {label ? <Field.Label>{label}</Field.Label> : null}\n      <Field.Control\n        name={name}\n        required={required}\n        placeholder={placeholder}\n        disabled={disabled}\n        value={displayValue}\n        {...(numericOnly ? { inputMode: 'numeric' as const } : {})}\n        onChange={handleChange}\n        onBlur={handleBlur}\n      />\n      {showInvalid && errorMessage ? <Field.Error match>{errorMessage}</Field.Error> : null}\n    </Field.Root>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"document-field.js","names":["BaseField"],"sources":["../../../src/particles/document-field/document-field.tsx"],"sourcesContent":["'use client';\nimport { Field as BaseField } from '@base-ui/react/field';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ChangeEvent, ComponentPropsWithRef, FocusEvent, ReactNode, Ref } from 'react';\nimport { createContext, useContext, useMemo, useState } from 'react';\nimport { useFormContext, useFormState } from 'react-hook-form';\nimport {\n  FieldBinding,\n  type FieldContract,\n  type FieldRule,\n  mergeFieldValidator,\n  TEXT_FIELD_VALUE,\n  useBoundField,\n  useField,\n} from '../field/field.js';\nimport { useComposedRef } from '../shared/compose-refs.js';\nimport { applyMask, countSlots, isDigitOnly } from '../shared/input-mask.js';\n\n// `applyMask` was public from this module before the engine moved out; keep the export path stable.\nexport { applyMask } from '../shared/input-mask.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type DocumentType = 'CPF';\n\ntype DocumentFieldRequirement = 'mandatory' | 'optional';\n\nexport type DocumentSpec = {\n  id: DocumentType;\n  name: string;\n  mask: string;\n  validate: (value: string) => boolean;\n};\n\n// `dangerouslySetInnerHTML` is excluded — the rest spread this props type feeds forwards straight to\n// `Field.Root`, and a schema-authored `page.json` can supply it with no allowlist in between.\nexport type DocumentFieldProps = Omit<\n  ComponentPropsWithRef<'div'>,\n  'defaultValue' | 'value' | 'onChange' | 'onBlur' | 'ref' | 'dangerouslySetInnerHTML'\n> & {\n  /** Unused on the bound path — react-hook-form owns the value. */\n  value?: string;\n  /** Unused on the bound path — the field contract's `defaultValue` seeds it instead. */\n  defaultValue?: string;\n  onValueChange?: (value: string) => void;\n  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;\n  invalid?: boolean;\n  errorMessage?: string;\n  /** Falls back to the field contract's `label` when bound. */\n  label?: string;\n  /** Falls back to the field contract's `placeholder` when bound. */\n  placeholder?: string;\n  /** Falls back to the field contract's `disabled` when bound. */\n  disabled?: boolean;\n  /**\n   * Raises the field to required, the same word `PhoneField` uses. It only ever raises: bound to a\n   * fieldset whose rule already says required, `'optional'` does not lower it. Left unset it is no\n   * opinion, which keeps CPF optional by recommendation.\n   */\n  requirement?: DocumentFieldRequirement;\n  name?: string;\n  documentType?: DocumentType;\n  /**\n   * Lands on the `<input>` `Field.Control` renders — not on the wrapper `<div>`, as it did before\n   * (a deliberate, source-breaking re-route: the previous ref pointed at an untabbable div). Composed\n   * with react-hook-form's own ref on the bound path.\n   */\n  ref?: Ref<HTMLInputElement>;\n  /**\n   * Given, replaces the default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy — any\n   * order, any subset. `DocumentFieldInput` is the one part that carries the mask, the composed ref\n   * and the particle's own value/handlers; a composed generic `Field.Control` would call\n   * `useController` a second time for the same name (RFC's named, accepted double-binder hole).\n   */\n  children?: ReactNode;\n};\n\n// ---------------------------------------------------------------------------\n// Ported check-digit validation (fastcheckout `packages/libs/validators/src/document`).\n// ---------------------------------------------------------------------------\n\n/**\n * CPF check-digit validation, ported from the legacy `validateCPF`. Strips non-digits, requires\n * exactly 11 digits, rejects all-equal sequences (e.g. `111.111.111-11`), and verifies both check\n * digits. Runs on blur/submit only, never per keystroke.\n */\nexport function validateCPF(value: string): boolean {\n  const digits = value.replace(/[^\\d]+/g, '');\n\n  if (digits.length !== 11 || /(\\d)\\1{10}/.test(digits)) {\n    return false;\n  }\n\n  const values = digits.split('').map((el) => +el);\n  const rest = (count: number) =>\n    ((values.slice(0, count - 12).reduce((sum, el, index) => sum + el * (count - index), 0) * 10) % 11) % 10;\n\n  return rest(10) === values[9] && rest(11) === values[10];\n}\n\n// ---------------------------------------------------------------------------\n// Document table (subset needed for the CPF launch). `documentType` selects the mask +\n// validator + digit-only input mode. Extendable later (SSN | SIN | CURP) without touching callers.\n// ---------------------------------------------------------------------------\n\nexport const DOCUMENTS: Record<DocumentType, DocumentSpec> = {\n  CPF: {\n    id: 'CPF',\n    name: 'CPF',\n    mask: '999.999.999-99',\n    validate: validateCPF,\n  },\n};\n\n/**\n * True when `type` is a document type this build supports (lets a host gate the field by locale).\n *\n * `Object.hasOwn`, not the `in` operator: `in` walks the prototype chain, so `constructor`,\n * `__proto__` and `toString` all satisfied it and were then trusted as a `DocumentType` by callers\n * (`client-profile-fieldset.tsx` renders the field on the strength of this narrowing). The value is\n * author-only — a literal written into `page.json`, never a runtime expression — so this is\n * robustness rather than a reachable defect, but the narrowing should not be able to lie.\n */\nexport function isSupportedDocumentType(type: unknown): type is DocumentType {\n  return typeof type === 'string' && Object.hasOwn(DOCUMENTS, type);\n}\n\n/**\n * Apply a document type's mask to raw input: strip non-digits for digit-only masks, then truncate to\n * the mask's slot count so excess characters never trail past the mask (e.g. a 15-digit paste into\n * the 11-slot CPF mask yields `111.444.777-35`, not `111.444.777-358888`).\n */\nexport function maskDocumentValue(rawValue: string, documentType: DocumentType): string {\n  const spec = DOCUMENTS[documentType];\n  const sanitized = isDigitOnly(spec.mask) ? rawValue.replace(/\\D/g, '') : rawValue;\n  const maxSlots = Math.max(...spec.mask.split('|').map(countSlots));\n  return applyMask(sanitized.slice(0, maxSlots), spec.mask);\n}\n\n/**\n * Check-digit validity for a document value. An **empty** value is valid (the field is optional),\n * mirroring the legacy `validateCardholderDocument`; a non-empty value must pass the document\n * type's check-digit validation.\n */\nexport function isValidDocument(value: string, documentType: DocumentType): boolean {\n  if (!value.trim()) return true;\n  return DOCUMENTS[documentType].validate(value);\n}\n\n// ---------------------------------------------------------------------------\n// Component\n// ---------------------------------------------------------------------------\n\nexport const DocumentFieldDefinition = defineComponent<DocumentFieldProps>({\n  name: 'DocumentField',\n  importPath: '@vtex/faststore/components',\n  component: DocumentField,\n  providesContext: 'document-field',\n  editor: { label: 'Document Field', category: 'content' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    errorMessage: { type: 'string', label: 'Error message' },\n    documentType: { type: 'string', default: 'CPF', label: 'Document type' },\n    requirement: { type: ['mandatory', 'optional'] as const, label: 'Requirement' },\n    disabled: { type: 'boolean', default: false, label: 'Disabled' },\n  },\n  guideline:\n    'Presentational tax-document input composing the Field particle; applies the locale mask on change and runs check-digit validation on blur/submit. Data-agnostic (value/defaultValue/onValueChange); a host wires it to the shopper profile. CPF is optional by default: requirement only ever raises the field to required, announced as aria-required, and bound to a fieldset whose rule already says required it cannot lower it back. Recomposable (RFC:503): given children, they replace the default Field.Label + DocumentFieldInput + Field.Error anatomy, in any order.',\n});\n\n/**\n * Presentational tax-document input (particle). Composes the `Field` particle (`Field.Root` +\n * `Field.Label` + `Field.Control` + `Field.Error`) and owns the locale mask (applied progressively on\n * every change, never blocking typing) plus check-digit validation (run on blur/submit only — never\n * per keystroke). An empty value is valid (the field is optional). It surfaces `errorMessage` inline\n * when the check digit fails or when the host forces `invalid` (e.g. a server error surfaced by the\n * form that owns the write). It consumes no GraphQL and no domain context — value flows through\n * `value`/`defaultValue`/`onValueChange`, and `documentType` selects the mask + validator.\n *\n * Reads the field contract through `useField()` and `useFormContext()` and dispatches to a bound or an\n * unbound sub-component — \"bound\" means both are present. Every react-hook-form hook lives in\n * `BoundDocumentField`, so hook order never changes under a mounted component. Both sub-components\n * render the same `DocumentFieldView`, so the two paths cannot drift into different DOM.\n */\nexport function DocumentField(props: DocumentFieldProps): ReactNode {\n  const contract = useField();\n  const formContext = useFormContext();\n\n  if (contract && formContext) {\n    return <BoundDocumentField {...props} contract={contract} />;\n  }\n\n  return <UnboundDocumentField {...props} />;\n}\n\n// ---------------------------------------------------------------------------\n// Input part — catalogued, placeable (Decision 4). Carries the mask, the composed ref, and the\n// particle's own onChange/onBlur. Renders the RAW Base UI Field.Control, not this package's own\n// Field.Control wrapper — the latter would see the real ambient contract Decision 3 now provides\n// and call useController a second time for the same name, overwriting the composite's masked value\n// (the exact double-registration bug the removed FieldContractBoundary used to prevent globally).\n// ---------------------------------------------------------------------------\n\ntype DocumentFieldInputContextValue = {\n  ref?: Ref<HTMLInputElement>;\n  name?: string;\n  value: string;\n  placeholder?: string;\n  disabled: boolean;\n  /** Resolved by the binder, threaded here because this part is not the one that binds. */\n  required: boolean;\n  numericOnly: boolean;\n  onChange: (event: ChangeEvent<HTMLInputElement>) => void;\n  onBlur: (event: FocusEvent<HTMLInputElement>) => void;\n};\n\nconst DocumentFieldInputContext = createContext<DocumentFieldInputContextValue | null>(null);\n\nfunction useDocumentFieldInputContext(): DocumentFieldInputContextValue {\n  const context = useContext(DocumentFieldInputContext);\n  if (!context) {\n    throw new Error('DocumentFieldInput must be a descendant of DocumentField.');\n  }\n  return context;\n}\n\nexport type DocumentFieldInputProps = { className?: string };\n\nexport const DocumentFieldInputDefinition = defineComponent<DocumentFieldInputProps>({\n  name: 'DocumentFieldInput',\n  importPath: '@vtex/faststore/components',\n  component: DocumentFieldInput,\n  requiresContext: 'document-field',\n  editor: { label: 'Document Field Input', category: 'action' },\n  schema: {},\n  guideline:\n    \"The masked document <input> DocumentField owns. Must sit inside DocumentField, in either the default anatomy or an author's composed children. Carries the locale mask, the composed ref, and DocumentField's own onChange/onBlur — a composed Field.Control here instead re-registers the field with react-hook-form and loses the mask (unsupported, RFC's named double-binder hole).\",\n});\n\n/** Renders the masked document `<input>`, reading its value/handlers/ref from the enclosing `DocumentField`. */\nexport function DocumentFieldInput({ className }: DocumentFieldInputProps): ReactNode {\n  const { ref, name, value, placeholder, disabled, required, numericOnly, onChange, onBlur } =\n    useDocumentFieldInputContext();\n\n  return (\n    <BaseField.Control\n      ref={ref}\n      name={name}\n      // `aria-required`, not native `required`, for the reason password-field.tsx:89-91 records:\n      // this is a Base UI `Field.Control`, and native constraint tracking would flip `aria-invalid`\n      // on its own, ahead of react-hook-form's own validation.\n      aria-required={required || undefined}\n      placeholder={placeholder}\n      disabled={disabled}\n      value={value}\n      {...(numericOnly ? { inputMode: 'numeric' as const } : {})}\n      onChange={onChange}\n      onBlur={onBlur}\n      className={className}\n      data-fs-field-control=\"\"\n    />\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Shared view — identical DOM whether bound or unbound\n// ---------------------------------------------------------------------------\n\ntype DocumentFieldViewProps = Omit<\n  ComponentPropsWithRef<'div'>,\n  'defaultValue' | 'value' | 'onChange' | 'onBlur' | 'ref'\n> & {\n  ref?: Ref<HTMLInputElement>;\n  name?: string;\n  label?: string;\n  placeholder?: string;\n  disabled: boolean;\n  required: boolean;\n  numericOnly: boolean;\n  displayValue: string;\n  showInvalid: boolean;\n  errorMessage?: string;\n  onChange: (event: ChangeEvent<HTMLInputElement>) => void;\n  onBlur: (event: FocusEvent<HTMLInputElement>) => void;\n  children?: ReactNode;\n};\n\nfunction DocumentFieldView({\n  className,\n  name,\n  label,\n  placeholder,\n  disabled,\n  required,\n  numericOnly,\n  displayValue,\n  showInvalid,\n  errorMessage,\n  onChange,\n  onBlur,\n  ref,\n  children,\n  ...props\n}: DocumentFieldViewProps) {\n  const inputContext = useMemo<DocumentFieldInputContextValue>(\n    () => ({ ref, name, value: displayValue, placeholder, disabled, required, numericOnly, onChange, onBlur }),\n    [ref, name, displayValue, placeholder, disabled, required, numericOnly, onChange, onBlur],\n  );\n\n  return (\n    // Deliberately the RAW Base UI Field.Root/Label/Error, not this package's own Field.* wrapper,\n    // for the default anatomy — reproduces exactly what rendered before FieldContractBoundary was\n    // removed (Decision 3), including the host `invalid`/`errorMessage` override working\n    // unconditionally. Composed children, below, use the package's own Field.* parts on purpose —\n    // that is what makes a childless Field.Label / Field.Error resolve real text (FR-5).\n    <BaseField.Root\n      {...props}\n      className={className}\n      name={name}\n      invalid={showInvalid}\n      disabled={disabled}\n      data-fs-document-field=\"\"\n      data-fs-field-root=\"\"\n    >\n      <DocumentFieldInputContext.Provider value={inputContext}>\n        {children ?? (\n          <>\n            {label ? <BaseField.Label data-fs-field-label=\"\">{label}</BaseField.Label> : null}\n            <DocumentFieldInput />\n            {showInvalid && errorMessage ? (\n              <BaseField.Error match data-fs-field-error=\"\">\n                {errorMessage}\n              </BaseField.Error>\n            ) : null}\n          </>\n        )}\n      </DocumentFieldInputContext.Provider>\n    </BaseField.Root>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Unbound — today's body, moved verbatim\n// ---------------------------------------------------------------------------\n\nfunction UnboundDocumentField({\n  value,\n  defaultValue = '',\n  onValueChange,\n  onBlur,\n  invalid = false,\n  errorMessage,\n  label,\n  placeholder,\n  disabled = false,\n  requirement,\n  name = 'document',\n  documentType = 'CPF',\n  className,\n  ref,\n  children,\n  ...props\n}: DocumentFieldProps) {\n  const isControlled = value !== undefined;\n  const [internalValue, setInternalValue] = useState(() => maskDocumentValue(defaultValue, documentType));\n  const [checkInvalid, setCheckInvalid] = useState(false);\n\n  const currentValue = isControlled ? value : internalValue;\n  // Masking is idempotent, so masking here formats both a raw pre-fill (a controlled `value` seeded\n  // from the saved profile) and an already-masked typed value identically.\n  const displayValue = maskDocumentValue(currentValue, documentType);\n  const showInvalid = invalid || checkInvalid;\n  const numericOnly = isDigitOnly(DOCUMENTS[documentType].mask);\n\n  function handleChange(event: ChangeEvent<HTMLInputElement>) {\n    const masked = maskDocumentValue(event.target.value, documentType);\n    if (!isControlled) setInternalValue(masked);\n    // Clear a prior check-digit error while typing; it is re-evaluated on the next blur.\n    if (checkInvalid) setCheckInvalid(false);\n    onValueChange?.(masked);\n  }\n\n  function handleBlur(event: FocusEvent<HTMLInputElement>) {\n    // Validation runs only after the complete number is entered; empty is valid (optional field).\n    setCheckInvalid(!isValidDocument(currentValue, documentType));\n    onBlur?.(event);\n  }\n\n  return (\n    <DocumentFieldView\n      {...props}\n      ref={ref}\n      className={className}\n      name={name}\n      label={label}\n      placeholder={placeholder}\n      disabled={disabled}\n      required={requirement === 'mandatory'}\n      numericOnly={numericOnly}\n      displayValue={displayValue}\n      showInvalid={showInvalid}\n      errorMessage={errorMessage}\n      onChange={handleChange}\n      onBlur={handleBlur}\n    >\n      {children}\n    </DocumentFieldView>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Bound — reads the field contract, binds through useController\n// ---------------------------------------------------------------------------\n\ntype BoundDocumentFieldProps = DocumentFieldProps & { contract: FieldContract };\n\nfunction BoundDocumentField({\n  value: _value,\n  defaultValue: _defaultValue,\n  onValueChange,\n  onBlur,\n  invalid = false,\n  errorMessage,\n  label,\n  placeholder,\n  disabled,\n  requirement,\n  name,\n  documentType = 'CPF',\n  className,\n  ref: callerRef,\n  contract,\n  children,\n  ...props\n}: BoundDocumentFieldProps) {\n  // Check digit only. Requiredness is not decided here: `useBoundField` resolves it from the\n  // fieldset's baseline and the raise below. Returning the `errorMessage` prop (or a bare `false`\n  // when it is unset) keeps today's behaviour: the field goes invalid, and — since the composite's\n  // own inline text is driven by the `errorMessage` prop, not by react-hook-form's error message —\n  // text renders only when supplied. The check composes alongside whatever the fieldset validates;\n  // before this merge, any contract validator discarded the particle's own validation whole.\n  const rule = useMemo<FieldRule>(\n    () =>\n      mergeFieldValidator(contract.rule, 'checkDigit', (rawValue) => {\n        const raw = typeof rawValue === 'string' ? rawValue : String(rawValue ?? '');\n        return isValidDocument(raw, documentType) || (errorMessage ?? false);\n      }),\n    [contract.rule, documentType, errorMessage],\n  );\n\n  const field = useBoundField(contract, TEXT_FIELD_VALUE, rule, { required: requirement === 'mandatory' });\n  const { getFieldState } = useFormContext();\n  const { invalid: rhfInvalid } = getFieldState(contract.name, useFormState({ name: contract.name }));\n\n  const composedRef = useComposedRef<HTMLInputElement>(callerRef, field.ref);\n\n  const currentValue = typeof field.value === 'string' ? field.value : String(field.value ?? '');\n  const displayValue = maskDocumentValue(currentValue, documentType);\n  const showInvalid = invalid || rhfInvalid;\n  const numericOnly = isDigitOnly(DOCUMENTS[documentType].mask);\n  const resolvedLabel = label ?? contract.label;\n  const resolvedPlaceholder = placeholder ?? contract.placeholder;\n  const resolvedDisabled = disabled ?? contract.disabled ?? false;\n  // Unlike `UnboundDocumentField`, `name` carries no signature default here — a signature default\n  // would always win over the contract's name (Decision 5), colliding two bound fieldsets (e.g.\n  // `profile.document` and `billing.document`) on the same rendered `name=\"document\"`.\n  const resolvedName = name ?? contract.name;\n\n  function handleChange(event: ChangeEvent<HTMLInputElement>) {\n    const masked = maskDocumentValue(event.target.value, documentType);\n    field.onChange(masked);\n    onValueChange?.(masked);\n  }\n\n  function handleBlur(event: FocusEvent<HTMLInputElement>) {\n    field.onBlur();\n    onBlur?.(event);\n  }\n\n  return (\n    // Decision 3: replaces the empty-contract FieldContractBoundary with a re-provided contract\n    // carrying the RESOLVED name/label/placeholder — the values a composed childless Field.Label /\n    // Field.Error actually need, as opposed to the raw (possibly-undefined) ones the ambient\n    // contract from the enclosing FieldBinding carries. useBoundField above remains the sole binder\n    // for contract.name; this FieldBinding never registers anything itself.\n    <FieldBinding\n      name={contract.name}\n      label={resolvedLabel}\n      placeholder={resolvedPlaceholder}\n      defaultValue={contract.defaultValue}\n      rule={contract.rule}\n      options={contract.options}\n      disabled={resolvedDisabled}\n      readOnly={contract.readOnly}\n      autoComplete={contract.autoComplete}\n      inputMode={contract.inputMode}\n    >\n      <DocumentFieldView\n        {...props}\n        ref={composedRef}\n        className={className}\n        name={resolvedName}\n        label={resolvedLabel}\n        placeholder={resolvedPlaceholder}\n        disabled={resolvedDisabled}\n        required={field.required}\n        numericOnly={numericOnly}\n        displayValue={displayValue}\n        showInvalid={showInvalid}\n        errorMessage={errorMessage}\n        onChange={handleChange}\n        onBlur={handleBlur}\n      >\n        {children}\n      </DocumentFieldView>\n    </FieldBinding>\n  );\n}\n"],"mappings":"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"}

package/dist/particles/field/bound-field-registry.js

@@ -0,0 +1,52 @@
+//#region src/particles/field/bound-field-registry.ts
+/**
+* Every clearer currently registered for a (control, name) pair. A `Set` per name, not a single
+* function: two bound parts registering the same name — the RFC's named, unsupported double-binder
+* composition, reachable via `PhoneField`'s and `DocumentField`'s own re-provided `FieldBinding` — both
+* run on Clear instead of one silently winning, and releasing one leaves the other intact.
+*
+* Keyed by `control` — the same object identity `field.tsx`'s adoption ledger (`adoptedSeeds`) uses,
+* and for the same reason: a `WeakMap` so a form that itself unmounts (a fresh `useForm()` call, a
+* fresh `control`) starts over empty and is collected once nothing else references it.
+*/
+const clearers = /* @__PURE__ */ new WeakMap();
+function clearersFor(control) {
+	let byName = clearers.get(control);
+	if (!byName) {
+		byName = /* @__PURE__ */ new Map();
+		clearers.set(control, byName);
+	}
+	return byName;
+}
+/**
+* Registers `clear` for `name` on `control` and returns its release. The release is one-shot —
+* calling it a second time removes nothing further, mirroring `useFieldsetFieldNames`'s own `released`
+* latch (`field.tsx`) — and it deletes `name`'s entry entirely once its set empties, so a name no bound
+* part still claims leaves no residue in the map.
+*/
+function registerFieldClearer(control, name, clear) {
+	const byName = clearersFor(control);
+	let forName = byName.get(name);
+	if (!forName) {
+		forName = /* @__PURE__ */ new Set();
+		byName.set(name, forName);
+	}
+	forName.add(clear);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		forName.delete(clear);
+		if (forName.size === 0) byName.delete(name);
+	};
+}
+/** Runs every clearer registered for `name` on `control`. A name with none registered is a no-op. */
+function clearBoundField(control, name) {
+	const forName = clearers.get(control)?.get(name);
+	if (!forName) return;
+	for (const clear of forName) clear();
+}
+//#endregion
+export { clearBoundField, registerFieldClearer };
+
+//# sourceMappingURL=bound-field-registry.js.map

package/dist/particles/field/bound-field-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bound-field-registry.js","names":[],"sources":["../../../src/particles/field/bound-field-registry.ts"],"sourcesContent":["import type { Control } from 'react-hook-form';\n\n/** Clears one bound part's own field back to its empty value. Owned and invoked by `clearBoundField`. */\ntype FieldClearer = () => void;\n\n/**\n * Every clearer currently registered for a (control, name) pair. A `Set` per name, not a single\n * function: two bound parts registering the same name — the RFC's named, unsupported double-binder\n * composition, reachable via `PhoneField`'s and `DocumentField`'s own re-provided `FieldBinding` — both\n * run on Clear instead of one silently winning, and releasing one leaves the other intact.\n *\n * Keyed by `control` — the same object identity `field.tsx`'s adoption ledger (`adoptedSeeds`) uses,\n * and for the same reason: a `WeakMap` so a form that itself unmounts (a fresh `useForm()` call, a\n * fresh `control`) starts over empty and is collected once nothing else references it.\n */\nconst clearers = new WeakMap<Control, Map<string, Set<FieldClearer>>>();\n\nfunction clearersFor(control: Control): Map<string, Set<FieldClearer>> {\n  let byName = clearers.get(control);\n  if (!byName) {\n    byName = new Map();\n    clearers.set(control, byName);\n  }\n  return byName;\n}\n\n/**\n * Registers `clear` for `name` on `control` and returns its release. The release is one-shot —\n * calling it a second time removes nothing further, mirroring `useFieldsetFieldNames`'s own `released`\n * latch (`field.tsx`) — and it deletes `name`'s entry entirely once its set empties, so a name no bound\n * part still claims leaves no residue in the map.\n */\nexport function registerFieldClearer(control: Control, name: string, clear: FieldClearer): () => void {\n  const byName = clearersFor(control);\n  let forName = byName.get(name);\n  if (!forName) {\n    forName = new Set();\n    byName.set(name, forName);\n  }\n  forName.add(clear);\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n\n    forName.delete(clear);\n    if (forName.size === 0) {\n      byName.delete(name);\n    }\n  };\n}\n\n/** Runs every clearer registered for `name` on `control`. A name with none registered is a no-op. */\nexport function clearBoundField(control: Control, name: string): void {\n  const forName = clearers.get(control)?.get(name);\n  if (!forName) return;\n  for (const clear of forName) {\n    clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;AAeA,MAAM,2BAAW,IAAI,QAAiD;AAEtE,SAAS,YAAY,SAAkD;CACrE,IAAI,SAAS,SAAS,IAAI,OAAO;CACjC,IAAI,CAAC,QAAQ;EACX,yBAAS,IAAI,IAAI;EACjB,SAAS,IAAI,SAAS,MAAM;CAC9B;CACA,OAAO;AACT;;;;;;;AAQA,SAAgB,qBAAqB,SAAkB,MAAc,OAAiC;CACpG,MAAM,SAAS,YAAY,OAAO;CAClC,IAAI,UAAU,OAAO,IAAI,IAAI;CAC7B,IAAI,CAAC,SAAS;EACZ,0BAAU,IAAI,IAAI;EAClB,OAAO,IAAI,MAAM,OAAO;CAC1B;CACA,QAAQ,IAAI,KAAK;CAEjB,IAAI,WAAW;CACf,aAAa;EACX,IAAI,UAAU;EACd,WAAW;EAEX,QAAQ,OAAO,KAAK;EACpB,IAAI,QAAQ,SAAS,GACnB,OAAO,OAAO,IAAI;CAEtB;AACF;;AAGA,SAAgB,gBAAgB,SAAkB,MAAoB;CACpE,MAAM,UAAU,SAAS,IAAI,OAAO,CAAC,EAAE,IAAI,IAAI;CAC/C,IAAI,CAAC,SAAS;CACd,KAAK,MAAM,SAAS,SAClB,MAAM;AAEV"}