@vtex/faststore 0.0.5 → 0.0.6

package/dist/particles/field/field.js

@@ -1,13 +1,370 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
+import { Checkbox } from "../checkbox/checkbox.js";
+import { registerFieldClearer } from "./bound-field-registry.js";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 import { Field } from "@base-ui/react/field";
+import { useController, useFormContext, useFormState } from "react-hook-form";
 //#region src/particles/field/field.tsx
+/**
+* The one place `RegisterOptions` is named as a value type. `FieldRule`'s members are declared
+* independently of react-hook-form's (Decision 5), but each already carries react-hook-form's own
+* runtime shape (a bare value, or `{ value, message }`), so this is an assertion, not a per-member
+* transform. `field-rule.type-test.tsx` pins the boundary from the other side: it fails to compile if
+* `FieldRule` ever widens back to a bare `RegisterOptions` alias.
+*/
+function toRegisterOptions(rule) {
+	return rule;
+}
+/**
+* react-hook-form's own reading of `required`: `.value` for the object form
+* (`{ value: boolean; message: string }`), plain truthiness otherwise (a boolean or a message
+* string). A message string is itself the copy, which is why the two are read together.
+*/
+function readBaseline(rule) {
+	const required = rule?.required;
+	if (typeof required === "object" && required !== null) return {
+		required: Boolean(required.value),
+		message: required.value ? required.message : void 0
+	};
+	if (typeof required === "string") return {
+		required: true,
+		message: required
+	};
+	return { required: Boolean(required) };
+}
+/** A `validate` member is either one function or a record of named ones; downstream only wants the record. */
+function normaliseValidators(validate) {
+	if (!validate) return {};
+	return typeof validate === "function" ? { validate } : { ...validate };
+}
+/**
+* Composes `validator` into `rule` under `name`, alongside whatever the rule already validates —
+* never instead of it. The two composites reach for this to keep their own format check while a
+* fieldset-supplied validator stays in force; before it, both discarded their own validation whole
+* the moment the fieldset supplied any.
+*/
+function mergeFieldValidator(rule, name, validator) {
+	return {
+		...rule,
+		validate: {
+			...normaliseValidators(rule?.validate),
+			[name]: validator
+		}
+	};
+}
+/**
+* The one resolution of `required = baselineRequired || authorRaise`. The fieldset's `FieldRule` is
+* the baseline; a control may raise a field to required and never lower one, so `raise.required`
+* only ever adds. Read-only deliberately plays no part: a field that is read-only and required stays
+* required, and an unsatisfiable form is the declared baseline's fault, not this function's.
+*
+* Baseline copy wins over the raise's, matching react-hook-form's own order — it evaluates `required`
+* before `validate`, so the fieldset's message was already the one a shopper saw whenever both existed.
+*
+* `required` catches an empty string but not a space-filled one (`inputValue === ''` is
+* react-hook-form's only emptiness test for a string), so the blank check goes in beside it. It is
+* installed last, so it cannot be displaced by a same-named validator from the rule.
+*/
+function resolveRequiredness(rule, raise) {
+	const baseline = readBaseline(rule);
+	const required = baseline.required || Boolean(raise?.required);
+	if (!required) return {
+		required: false,
+		rule
+	};
+	const message = baseline.message ?? (baseline.required ? void 0 : raise?.message);
+	const notBlank = (value) => String(value ?? "").trim().length > 0 || message || false;
+	return {
+		required,
+		message,
+		rule: {
+			...mergeFieldValidator(rule, "notBlank", notBlank),
+			required: message ?? true
+		}
+	};
+}
+const FieldContext = createContext(null);
+/** Reads the field contract. Returns null when no binding is above the caller. */
+function useField() {
+	return useContext(FieldContext);
+}
+/**
+* Per (control, field name), the seed the *fieldset supplied* for that name — `contract.defaultValue`
+* as handed down, not the value any one part narrowed it to before calling `resetField`. The
+* distinction only shows up where the RFC says two parts may bind one name ("A fieldset registers
+* once, collecting the field names its own children mount, refcounted so that a part remounting, or
+* two parts binding one name, never unregisters a name still in use"): a text part and a checkbox
+* part over the same name narrow one seed to two different types, so a ledger holding the narrowed
+* value disagrees with itself on every render — neither part's entry ever satisfies the other's
+* `seedsEqual` check, and the two reset each other forever. Keyed on what the fieldset supplied, both
+* parts read the same entry, the first to run adopts and the rest skip. The second part's own
+* `useController` registration still carries its own narrowing, so it reads dirty against a baseline
+* it did not set — the honest outcome, and better than a hang.
+*
+* Keyed by the `control` object itself rather than by any `FieldBinding` component instance. Adoption is a
+* property of the field name within this form, not of whichever component instance happens to be
+* mounted right now: a fieldset's own conditional control (the `documentType` gate on
+* `ClientProfileDocumentControl`, a country-descriptor swap in `ShippingAddressFieldset`) unmounts and
+* remounts its `FieldBinding` with a brand-new instance that remembers nothing, while the shopper's
+* edit survives the unmount in `control._formValues` — nothing in this codebase sets
+* `shouldUnregister`. A `useRef` latch scoped to the instance cannot see that history and re-adopts the
+* stale seed over the surviving edit; this ledger can, because it outlives the instance. A `WeakMap` so
+* a form that itself unmounts (a fresh `useForm()` call, a fresh `control`) starts over empty, exactly
+* as it should.
+*
+* A `Map` of seeds, not a `Set` of names: recording only that a name was adopted cannot distinguish a
+* seed already in force from a different one that supersedes it, so a later `defaultValue` could never
+* reach the form — that was the whole bug this ledger replaces. `has(name)` is read separately from
+* `get(name)` everywhere below, so "never adopted" and "adopted `undefined`" stay distinguishable
+* states.
+*/
+const adoptedSeeds = /* @__PURE__ */ new WeakMap();
+function adoptedSeedsFor(control) {
+	let seeds = adoptedSeeds.get(control);
+	if (!seeds) {
+		seeds = /* @__PURE__ */ new Map();
+		adoptedSeeds.set(control, seeds);
+	}
+	return seeds;
+}
+/**
+* Structural rather than referential equality between two seeds, mirroring `valuesEqual` in
+* `form.tsx:128-130` and its documented reasoning: a field's seed is a primitive or plain record a
+* bound Control's contract carries (a string, a boolean, a small object) — never a function or a
+* circular structure — so a `JSON.stringify` comparison is a safe stand-in for a real deep-equal.
+* Duplicated rather than imported: `field.tsx` imports nothing from `form.tsx`, and the particles are
+* deliberately independent modules.
+*
+* `Object.is` is rejected here even though neither shipped shape's `normalise` (`TEXT_FIELD_VALUE`,
+* `BOOLEAN_FIELD_VALUE`) can hand this function anything but a primitive today — this guard is
+* defensive against a shape that does not exist yet, not against a reachable path. The day a shape's
+* `normalise` returns a record or an array, a fieldset that hands out a freshly-allocated seed with
+* the same content on every render would fail `Object.is` against itself, and the
+* resetField → formState → render → resetField chain below would never terminate (measured: swapping
+* in `Object.is` hung the suite past 150 seconds, until a render ceiling was added that turns the same
+* mutation into a named failure in seconds). Do not remove this as dead code on the
+* grounds that no object-shaped seed reaches it today — the regression test that pins it is
+* `field.test.tsx`'s `'terminates when the seed is a fresh, structurally identical object literal on
+* every render'`, which exercises `useSeedAdoption` through a test-only shape precisely because no
+* shipped shape can.
+*/
+function seedsEqual(a, b) {
+	return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+* react-hook-form copies a per-field `defaultValue` into control._defaultValues only when
+* shouldUnregister is set, which nothing here sets — so without this, the pristine comparison for a
+* seeded field runs against `undefined` and any touched field stays dirty for good. Adopted once per
+* (control, name) for a given seed, tracked in `adoptedSeeds`, which survives this component instance
+* unmounting and remounting — so a remount with the same stale seed prop never overwrites a shopper's
+* live edit, and a later, *different* seed reaches a field the shopper has not touched without the
+* shopper having to reload the page.
+*
+* Called from `useBoundField`, not from `FieldBinding` (relocated, T57): the caller is now the very
+* part whose own `useController` call registers `name`. `useController` calls `control.register(name,
+* …)` from a `useRef` initialiser during the first render, and `register` adds to `_names.mount`
+* synchronously — before that render returns, let alone before this effect's first run. So the mount
+* guard below is satisfied on this effect's very first run for the caller's own name; the ordering
+* `FieldBinding` could not rely on (a descendant control mounting on a *later* commit than the binding
+* around it) no longer arises, because binder and adopter are now one and the same component instance.
+* The T-5 test (`field.test.tsx`, a control that shows up on a later render than its enclosing
+* `FieldBinding`) still passes — not because that race is still possible, but because nothing here
+* special-cases it away: the guard simply reads true the one time it is asked.
+*
+* No dependency array all the same: this effect must still re-run on every render, because the guards
+* below can otherwise miss their only remaining chance — the dirty-then-clean case. A seed arriving
+* while the field is dirty is skipped by the third guard and never recorded; the only later signal that
+* it can now be adopted is the field itself turning clean, which changes neither `name` nor the
+* normalised seed this hook receives, so a dependency array keyed to its own arguments would never
+* re-invoke it. Re-running on every render costs nothing extra here: every guard below but the
+* adopting one is a no-op, and useFormContext() already forces a re-render on every formState emission
+* regardless (Invariant 4 is violated in letter, not by this effect), so this adds no new re-render of
+* its own.
+*
+* The first guard below is what does termination, not just correctness: react-hook-form rebuilds
+* formState on every emission and FormProvider memoises its context value with formState in its own
+* dependency list, so useFormContext()'s return value changes identity after every resetField call.
+* Without that guard, that identity change would drive another render, which would call resetField
+* again, which would change formState again — an unbounded loop. Its early return breaks it: once the
+* ledger's recorded seed for this name is equal (by `seedsEqual`) to the current `defaultValue`, every
+* further run for that name exits before reaching resetField — which is also why it must be the first
+* check after the ledger lookup, ahead of even the mount guard.
+*
+* Precondition this re-seed relies on and does not itself enforce: `defaultValue` regressing to a
+* reactive fragment's incomplete-read fallback once the field has already adopted real data.
+* Probing this against `useReactiveEntity`'s fallback expression (`use-reactive-entity.ts:57`), mounting
+* a clean field over real, complete data and then trying to make `fragmentResult.complete` flip back to
+* false: measured as **reachable**, not merely suspected. Two of the three probes reproduced it —
+* evicting a field the fragment selects (`cache.evict({ id, fieldName })`, then `cache.gc()`) and
+* moving the root query's entity id to one never written to the cache (a session or orderForm change)
+* both regress the read, and this effect cannot tell that apart from a genuine, saved change: the
+* second probe blanked a clean control from "Ada" to "", and an independent audit reproduced it.
+* `client.clearStore()` on a still-mounted, still-referenced entity did not reproduce it. The
+* fieldsets close that gap above this hook: they withhold their controls until `useEntityDataResolved`
+* reports their entity resolved, so a regressed read never reaches this effect through a fieldset.
+*/
+function useSeedAdoption(name, suppliedSeed, narrowedSeed) {
+	const form = useFormContext();
+	useEffect(() => {
+		if (!form) return;
+		const seeds = adoptedSeedsFor(form.control);
+		if (seeds.has(name) && seedsEqual(seeds.get(name), suppliedSeed)) return;
+		if (!form.control._names.mount.has(name)) return;
+		if (seeds.has(name) && form.getFieldState(name).isDirty) return;
+		form.resetField(name, { defaultValue: narrowedSeed });
+		seeds.set(name, suppliedSeed);
+	});
+}
+function FieldBinding({ name, label, placeholder, defaultValue, rule, options, disabled, readOnly, autoComplete, inputMode, children }) {
+	const contract = useMemo(() => ({
+		name,
+		label,
+		placeholder,
+		defaultValue,
+		rule,
+		options,
+		disabled,
+		readOnly,
+		autoComplete,
+		inputMode
+	}), [
+		name,
+		label,
+		placeholder,
+		defaultValue,
+		rule,
+		options,
+		disabled,
+		readOnly,
+		autoComplete,
+		inputMode
+	]);
+	return /* @__PURE__ */ jsx(FieldContext.Provider, {
+		value: contract,
+		children
+	});
+}
+/** A text-shaped bound field: empty is `''`, and a non-string seed narrows to `''`. */
+const TEXT_FIELD_VALUE = {
+	empty: "",
+	normalise: (seed) => typeof seed === "string" ? seed : ""
+};
+/** A boolean-shaped bound field: empty is `false`, and any seed narrows through `Boolean(...)`. */
+const BOOLEAN_FIELD_VALUE = {
+	empty: false,
+	normalise: (seed) => Boolean(seed)
+};
+/**
+* The only caller of `useController` in this package (I-1). Registers the field with react-hook-form,
+* adopts the same normalised seed as the dirty baseline (Decision 1), and registers a clearer that
+* writes the shape's own empty value for as long as the part stays mounted (FR-5) — three facts a
+* bound part previously scattered across its own call site, `FieldBinding` and `FormClear`.
+*
+* The effective rule is `rule ?? contract.rule`: a part with no rule of its own (`BoundFieldControl`,
+* `BoundFieldCheckbox`, `BoundFieldSelectRoot`) falls back to the contract's; `BoundPhoneField` and
+* `BoundDocumentField` pass their own `useMemo`-derived rule, which already merges the particle's
+* format check into `contract.rule` rather than replacing it.
+*
+* Requiredness resolves here rather than at each call site (FR: one chokepoint), so no bound control
+* can register a rule whose enforcement and announcement disagree, or forget the blank check. A
+* control that wants its field required passes a `raise`; only `FieldSelectTrigger`, which announces
+* from a different component than the one that binds, calls `resolveRequiredness` for itself.
+*/
+function useBoundField(contract, shape, rule, raise) {
+	const { control, setValue } = useFormContext();
+	const raiseRequired = raise?.required;
+	const raiseMessage = raise?.message;
+	const requiredness = useMemo(() => resolveRequiredness(rule ?? contract.rule, {
+		required: raiseRequired,
+		message: raiseMessage
+	}), [
+		rule,
+		contract.rule,
+		raiseRequired,
+		raiseMessage
+	]);
+	const seed = shape.normalise(contract.defaultValue);
+	const { field } = useController({
+		name: contract.name,
+		rules: toRegisterOptions(requiredness.rule),
+		defaultValue: seed
+	});
+	useSeedAdoption(contract.name, contract.defaultValue, seed);
+	useEffect(() => registerFieldClearer(control, contract.name, () => setValue(contract.name, shape.empty, { shouldDirty: true })), [
+		control,
+		contract.name,
+		setValue,
+		shape.empty
+	]);
+	return {
+		...field,
+		required: requiredness.required
+	};
+}
+/** Exported so those tasks import it rather than redefine it. */
+const FieldsetFieldContext = createContext(null);
+/** Unchanged: the registry above the caller, or null. Now carrying a namespace. */
+function useFieldsetContext() {
+	return useContext(FieldsetFieldContext);
+}
+/**
+* Registers `${namespace}.${key}` with the enclosing fieldset while the caller is mounted, and returns
+* that full name. Throws during render when a registry is above the caller and declares a different
+* namespace. Registers nothing and throws nothing when no registry is above. Holds no state: the
+* refcount belongs to the provider.
+*/
+function useFieldsetField(namespace, key) {
+	const registry = useFieldsetContext();
+	const name = `${namespace}.${key}`;
+	if (registry && registry.namespace !== namespace) throw new Error(`A control asked to register "${name}", but the fieldset registry above it owns the namespace "${registry.namespace}". A registry serves exactly one namespace, declared by the fieldset that provides it.`);
+	useEffect(() => {
+		if (!registry) return;
+		return registry.registerFieldName(name);
+	}, [registry, name]);
+	return name;
+}
+/**
+* The field-name bookkeeping a fieldset provides. Refcounted, so two callers of one name collapse to one
+* entry however they arrived — including a caller that reaches `registerFieldName` directly.
+*/
+function useFieldsetFieldNames(namespace) {
+	const counts = useRef(/* @__PURE__ */ new Map());
+	const registerFieldName = useCallback((name) => {
+		counts.current.set(name, (counts.current.get(name) ?? 0) + 1);
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const remaining = (counts.current.get(name) ?? 0) - 1;
+			if (remaining > 0) counts.current.set(name, remaining);
+			else counts.current.delete(name);
+		};
+	}, []);
+	const getFieldNames = useCallback(() => Array.from(counts.current.keys()), []);
+	return {
+		registry: useMemo(() => ({
+			namespace,
+			registerFieldName
+		}), [namespace, registerFieldName]),
+		getFieldNames
+	};
+}
+/**
+* Throws during render when an ancestor fieldset is already providing field registration for this
+* subtree. Every fieldset calls it in one line.
+*/
+function useNoAncestorFieldset(componentName) {
+	const ancestor = useFieldsetContext();
+	if (ancestor) throw new Error(`${componentName} cannot be nested inside another fieldset. An ancestor fieldset owning the namespace "${ancestor.namespace}" already provides field registration for this subtree, so this fieldset's controls would register under that namespace instead of their own. Compose fieldsets as siblings under the same FormRoot instead of nesting them.`);
+}
 const FieldRootDefinition = defineComponent({
 	name: "FieldRoot",
 	importPath: "@vtex/faststore/components",
 	component: FieldRoot,
+	providesContext: "field",
 	editor: {
 		label: "Field Root",
 		category: "layout"
@@ -17,34 +374,37 @@ const FieldRootDefinition = defineComponent({
 		default: false,
 		label: "Disabled"
 	} },
-	guideline: "Form field container that connects a label, input, and validation messages via ARIA. Use Field.Control as the input element, or place a compatible Base UI input (Input, Checkbox, Select) as a direct child. Set invalid=true to trigger Field.Error display."
+	guideline: "Form field container that connects a label, input, and validation messages via ARIA. Use Field.Control as the input element, or place a compatible Base UI input (Input, Checkbox, Select) as a direct child. Set invalid=true to trigger Field.Error display. Wrapping a bound Control feeds invalid/dirty/touched from react-hook-form automatically."
 });
 const FieldLabelDefinition = defineComponent({
 	name: "FieldLabel",
 	importPath: "@vtex/faststore/components",
 	component: FieldLabel,
+	requiresContext: "field",
 	editor: {
 		label: "Field Label",
 		category: "layout"
 	},
 	schema: {},
-	guideline: "Accessible label inside Field.Root. Automatically associated with Field.Control's input via ARIA. Place before Field.Control in the DOM."
+	guideline: "Accessible label inside Field.Root. Automatically associated with Field.Control's input via ARIA. Place before Field.Control in the DOM. Under a bound Control, a childless Field.Label renders the field contract's label."
 });
 const FieldControlDefinition = defineComponent({
 	name: "FieldControl",
 	importPath: "@vtex/faststore/components",
 	component: FieldControl,
+	requiresContext: "field",
 	editor: {
 		label: "Field Control",
 		category: "layout"
 	},
 	schema: {},
-	guideline: "Renders a native `<input>` element directly. It IS the input — do not place any child inside it. Pass input attributes (type, placeholder, required, etc.) directly as props. It is automatically linked to Field.Label and Field.Error via ARIA."
+	guideline: "Renders a native `<input>` element directly. It IS the input — do not place any child inside it. Pass input attributes (type, placeholder, required, etc.) directly as props. It is automatically linked to Field.Label and Field.Error via ARIA. Under a bound Control, it registers with react-hook-form using the field contract's name, seed value, and validation rule."
 });
 const FieldDescriptionDefinition = defineComponent({
 	name: "FieldDescription",
 	importPath: "@vtex/faststore/components",
 	component: FieldDescription,
+	requiresContext: "field",
 	editor: {
 		label: "Field Description",
 		category: "layout"
@@ -56,17 +416,19 @@ const FieldErrorDefinition = defineComponent({
 	name: "FieldError",
 	importPath: "@vtex/faststore/components",
 	component: FieldError,
+	requiresContext: "field",
 	editor: {
 		label: "Field Error",
 		category: "layout"
 	},
 	schema: {},
-	guideline: "Validation error message inside Field.Root. Shown when the field is in an invalid state. Linked to the control via aria-describedby."
+	guideline: "Validation error message inside Field.Root. Shown when the field is in an invalid state. Linked to the control via aria-describedby. Under a bound Control, it renders react-hook-form's error message for the field contract's name."
 });
 const FieldValidityDefinition = defineComponent({
 	name: "FieldValidity",
 	importPath: "@vtex/faststore/components",
 	component: FieldValidity,
+	requiresContext: "field",
 	editor: {
 		label: "Field Validity",
 		category: "layout"
@@ -74,7 +436,30 @@ const FieldValidityDefinition = defineComponent({
 	schema: {},
 	guideline: "Validation feedback slot using a render prop for custom messages derived from the field's validity state. Use for dynamic messages when Field.Error text is not fixed."
 });
+const FieldCheckboxDefinition = defineComponent({
+	name: "FieldCheckbox",
+	importPath: "@vtex/faststore/components",
+	component: FieldCheckbox,
+	requiresContext: "field",
+	editor: {
+		label: "Field Checkbox",
+		category: "action"
+	},
+	schema: {},
+	guideline: "Bound boolean control over the shipped Checkbox particle: reads the enclosing field contract and drives Checkbox.Root through react-hook-form. Compose Checkbox.Indicator as a child for the visual check mark. Place inside Field.Root, the only ancestor that provides the field context it requires today — a bound Control will satisfy it too, once one ships."
+});
 function FieldRoot({ disabled, invalid, name, className, children, ...props }) {
+	const contract = useField();
+	const formContext = useFormContext();
+	if (contract && formContext) return /* @__PURE__ */ jsx(BoundFieldRoot, {
+		...props,
+		contract,
+		disabled,
+		invalid,
+		name,
+		className,
+		children
+	});
 	return /* @__PURE__ */ jsx(Field.Root, {
 		...props,
 		disabled,
@@ -85,7 +470,31 @@ function FieldRoot({ disabled, invalid, name, className, children, ...props }) {
 		children
 	});
 }
+function BoundFieldRoot({ contract, disabled, invalid, name, className, children, ...props }) {
+	const { getFieldState, control } = useFormContext();
+	const { invalid: rhfInvalid, isDirty, isTouched } = getFieldState(contract.name, useFormState({ name: contract.name }));
+	const isRegistered = control._names.mount.has(contract.name);
+	return /* @__PURE__ */ jsx(Field.Root, {
+		...props,
+		name: name ?? contract.name,
+		disabled: disabled ?? contract.disabled,
+		invalid: invalid ?? rhfInvalid,
+		dirty: isRegistered ? isDirty : void 0,
+		touched: isRegistered ? isTouched : void 0,
+		className,
+		"data-fs-field-root": "",
+		children
+	});
+}
 function FieldLabel({ className, children, ...props }) {
+	const contract = useField();
+	const formContext = useFormContext();
+	if (contract && formContext) return /* @__PURE__ */ jsx(BoundFieldLabel, {
+		...props,
+		contract,
+		className,
+		children
+	});
 	return /* @__PURE__ */ jsx(Field.Label, {
 		...props,
 		className,
@@ -93,9 +502,43 @@ function FieldLabel({ className, children, ...props }) {
 		children
 	});
 }
+function BoundFieldLabel({ contract, className, children, ...props }) {
+	return /* @__PURE__ */ jsx(Field.Label, {
+		...props,
+		className,
+		"data-fs-field-label": "",
+		children: children ?? contract.label
+	});
+}
 function FieldControl({ className, ...props }) {
+	const contract = useField();
+	const formContext = useFormContext();
+	if (contract && formContext) return /* @__PURE__ */ jsx(BoundFieldControl, {
+		...props,
+		contract,
+		className
+	});
+	return /* @__PURE__ */ jsx(Field.Control, {
+		...props,
+		className,
+		"data-fs-field-control": ""
+	});
+}
+function BoundFieldControl({ contract, placeholder, disabled, readOnly, autoComplete, inputMode, className, ...props }) {
+	const field = useBoundField(contract, TEXT_FIELD_VALUE);
 	return /* @__PURE__ */ jsx(Field.Control, {
 		...props,
+		name: field.name,
+		value: field.value,
+		onChange: field.onChange,
+		onBlur: field.onBlur,
+		ref: field.ref,
+		placeholder: placeholder ?? contract.placeholder,
+		disabled: disabled ?? contract.disabled,
+		readOnly: readOnly ?? contract.readOnly,
+		autoComplete: autoComplete ?? contract.autoComplete,
+		inputMode: inputMode ?? contract.inputMode,
+		"aria-required": field.required || void 0,
 		className,
 		"data-fs-field-control": ""
 	});
@@ -109,6 +552,14 @@ function FieldDescription({ className, children, ...props }) {
 	});
 }
 function FieldError({ className, children, ...props }) {
+	const contract = useField();
+	const formContext = useFormContext();
+	if (contract && formContext) return /* @__PURE__ */ jsx(BoundFieldError, {
+		...props,
+		contract,
+		className,
+		children
+	});
 	return /* @__PURE__ */ jsx(Field.Error, {
 		...props,
 		className,
@@ -116,18 +567,58 @@ function FieldError({ className, children, ...props }) {
 		children
 	});
 }
+function BoundFieldError({ contract, className, children, match: _match, ...props }) {
+	const { getFieldState } = useFormContext();
+	const { error } = getFieldState(contract.name, useFormState({ name: contract.name }));
+	if (!error) return null;
+	if (!children && !error.message) return null;
+	return /* @__PURE__ */ jsx(Field.Error, {
+		...props,
+		match: true,
+		className,
+		"data-fs-field-error": "",
+		children: children ?? error.message
+	});
+}
 function FieldValidity({ children }) {
 	return /* @__PURE__ */ jsx(Field.Validity, { children });
 }
+function FieldCheckbox({ className, children }) {
+	const contract = useField();
+	const formContext = useFormContext();
+	if (contract && formContext) return /* @__PURE__ */ jsx(BoundFieldCheckbox, {
+		contract,
+		className,
+		children
+	});
+	return /* @__PURE__ */ jsx(Checkbox.Root, {
+		className,
+		children
+	});
+}
+function BoundFieldCheckbox({ contract, className, children }) {
+	const field = useBoundField(contract, BOOLEAN_FIELD_VALUE);
+	return /* @__PURE__ */ jsx(Checkbox.Root, {
+		checked: field.value,
+		onCheckedChange: field.onChange,
+		onBlur: field.onBlur,
+		ref: field.ref,
+		disabled: contract.disabled,
+		className,
+		"data-fs-field-checkbox": "",
+		children
+	});
+}
 const Field$1 = {
 	Root: FieldRoot,
 	Label: FieldLabel,
 	Control: FieldControl,
 	Description: FieldDescription,
 	Error: FieldError,
-	Validity: FieldValidity
+	Validity: FieldValidity,
+	Checkbox: FieldCheckbox
 };
 //#endregion
-export { Field$1 as Field, FieldControl, FieldControlDefinition, FieldDescription, FieldDescriptionDefinition, FieldError, FieldErrorDefinition, FieldLabel, FieldLabelDefinition, FieldRoot, FieldRootDefinition, FieldValidity, FieldValidityDefinition };
+export { BOOLEAN_FIELD_VALUE, Field$1 as Field, FieldBinding, FieldCheckbox, FieldCheckboxDefinition, FieldControl, FieldControlDefinition, FieldDescription, FieldDescriptionDefinition, FieldError, FieldErrorDefinition, FieldLabel, FieldLabelDefinition, FieldRoot, FieldRootDefinition, FieldValidity, FieldValidityDefinition, FieldsetFieldContext, TEXT_FIELD_VALUE, mergeFieldValidator, resolveRequiredness, useBoundField, useField, useFieldsetContext, useFieldsetField, useFieldsetFieldNames, useNoAncestorFieldset };
 
 //# sourceMappingURL=field.js.map