@formdef/core 0.1.2 → 0.3.0

package/dist/index.cjs

@@ -2,6 +2,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _tanstack_react_form = require("@tanstack/react-form");
 let react = require("react");
 let react_jsx_runtime = require("react/jsx-runtime");
+// src/widget/declares-empty-value.ts
+/** Whether `widget` declares its empty value, the value it holds while nothing is entered. */
+function declaresEmptyValue(widget) {
+	return Object.hasOwn(widget, "emptyValue");
+}
 // src/render/array-entry.tsx
 const removeLabelOf = (removeLabel, item, index) => typeof removeLabel === "function" ? removeLabel(item, index) : String(removeLabel);
 const itemControlsOf = (options, value) => {
@@ -103,6 +108,17 @@ const Derived = ({ form, entry, children }) => {
 		}
 	});
 };
+// src/render/path-pattern.ts
+const ITEM_INDEX = /\[\d+\]/g;
+const ANY_ITEM = "[]";
+/** The path with every array index left open: `contacts[2].name` becomes `contacts[].name`. */
+function pathPattern(path) {
+	return path.replaceAll(ITEM_INDEX, ANY_ITEM);
+}
+// src/render/required-paths.ts
+const NO_REQUIRED_PATHS = /* @__PURE__ */ new Set();
+/** The path patterns of the required fields of the level being rendered. */
+const RequiredPaths = (0, react.createContext)(NO_REQUIRED_PATHS);
 const OWN_ENTRY_KEY_SET = /* @__PURE__ */ new Set([
 	"widget",
 	"props",
@@ -161,13 +177,16 @@ const Item = ({ parts, form, entry, path, index, extra }) => {
 };
 const FieldContent = ({ parts, form, entry, path, props, extra }) => {
 	const { own, fieldOptions } = entry;
+	const requiredPaths = (0, react.use)(RequiredPaths);
 	if (typeof own.widget === "string") {
 		const Widget = byName(parts.widgets, own.widget);
 		if (Widget === void 0) throw new Error(`formdef: field "${path}" names the unregistered widget "${own.widget}".`);
+		const found = declaresEmptyValue(Widget) ? { required: requiredPaths.has(pathPattern(path)) } : void 0;
 		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(form.AppField, {
 			...fieldOptions,
 			name: path,
 			children: (field) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Widget, {
+				...found,
 				...props,
 				...extra,
 				field
@@ -333,15 +352,75 @@ const LevelEntries = ({ layout, ...level }) => {
 * into sections and rows and places form components and inline entries. A leaf renders as its
 * widget, an object as its own level, a custom entry through its `render`, an array through the
 * registered `structure.arrayFrame` or the bare default. An object entry with TanStack options of
-* its own also mounts a field at its path, so its validators run.
+* its own also mounts a field at its path, so its validators run. A `Fields` nested in a form finds
+* no required fields of its own, since its paths may be relative to a field group.
 */
-const Fields = ({ parts, form, fields, layout }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LevelEntries, {
-	parts,
-	form,
-	fields,
-	layout,
-	path: void 0
+const Fields = ({ parts, form, fields, layout, requiredPaths }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RequiredPaths, {
+	value: requiredPaths ?? NO_REQUIRED_PATHS,
+	children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LevelEntries, {
+		parts,
+		form,
+		fields,
+		layout,
+		path: void 0
+	})
 });
+// src/form/find-required-paths.ts
+const NONE = { paths: /* @__PURE__ */ new Set() };
+const ASYNC_SCHEMA = "formdef: the schema validates asynchronously, so no field is found to be required; pass required in props.";
+const UNSETTLED_SCHEMA = "formdef: the schema did not validate empty values synchronously, so no field is found to be required; pass required in props.";
+const THROWING_SCHEMA = "formdef: the schema threw on empty values, so no field is found to be required";
+const FIRST_ITEM = 0;
+const isStandardSchema = (schema) => typeof schema === "object" && schema !== null && "~standard" in schema;
+const emptyLevel = (fields, path, empty) => Object.fromEntries(Object.entries(fields).map(([key, entry]) => [key, emptyEntry(entry, childPath(path, key), empty)]));
+function emptyEntry(entry, path, empty) {
+	const { own } = splitEntry(entry);
+	if (typeof own.widget === "string") {
+		const widget = byName(empty.widgets, own.widget);
+		if (widget === void 0 || !declaresEmptyValue(widget)) return;
+		empty.declared.add(pathPattern(path));
+		return widget.emptyValue;
+	}
+	if (typeof own.item === "object" && own.item !== null) return [emptyEntry(own.item, childPath(path, FIRST_ITEM), empty)];
+	if (typeof own.fields === "object" && own.fields !== null) return emptyLevel(own.fields, path, empty);
+}
+const issuePath = (issue) => pathPattern((issue.path ?? []).reduce((parent, segment) => {
+	const key = typeof segment === "object" ? segment.key : segment;
+	return childPath(parent, typeof key === "number" ? key : String(key));
+}, void 0) ?? "");
+const parentOf = (path) => path.slice(0, Math.max(path.lastIndexOf("."), path.lastIndexOf("[")));
+const leafOf = (path, leaves) => {
+	for (let candidate = path; candidate !== ""; candidate = parentOf(candidate)) if (leaves.has(candidate)) return candidate;
+};
+const ignoreRejection = () => void 0;
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+/**
+* Finds the required fields of a config: validates `schema` once, synchronously, with every leaf
+* holding its widget's empty value and every array one such item. A leaf whose widget declares an
+* empty value and whose path receives an issue is required. A schema the config validates
+* asynchronously is not run, so its asynchronous checks send nothing.
+*/
+function findRequiredPaths({ schema, validatesAsync, fields, widgets }) {
+	if (!isStandardSchema(schema)) return NONE;
+	if (validatesAsync) return { problem: ASYNC_SCHEMA };
+	const empty = {
+		widgets,
+		declared: /* @__PURE__ */ new Set()
+	};
+	const values = emptyLevel(fields, void 0, empty);
+	let result;
+	try {
+		result = schema["~standard"].validate(values);
+	} catch (error) {
+		return { problem: `${THROWING_SCHEMA}: ${errorText(error)}` };
+	}
+	if (result instanceof Promise) {
+		result.then(void 0, ignoreRejection);
+		return { problem: UNSETTLED_SCHEMA };
+	}
+	const leaves = (result.issues ?? []).map((issue) => leafOf(issuePath(issue), empty.declared));
+	return { paths: new Set(leaves.filter((leaf) => leaf !== void 0)) };
+}
 // src/form/blur-then-change.ts
 const isSchemaDue = ({ event, form }) => {
 	if (event.type === "blur" || event.type === "submit") return true;
@@ -416,7 +495,7 @@ function formOptionsFor({ config, options }) {
 }
 // src/form/create-form.tsx
 const MISSING_DEFAULT_VALUES = "formdef: the form has no default values; set defaultValues in its config or in its options.";
-const ConfiguredForm = ({ binding, config, options, ...formProps }) => {
+const ConfiguredForm = ({ binding, config, requiredPaths, options, ...formProps }) => {
 	const formOptions = formOptionsFor({
 		config,
 		options
@@ -428,7 +507,8 @@ const ConfiguredForm = ({ binding, config, options, ...formProps }) => {
 		parts: binding.parts,
 		form,
 		fields: config.fields,
-		layout: config.layout
+		layout: config.layout,
+		requiredPaths
 	});
 	const handleSubmit = (event) => {
 		event.preventDefault();
@@ -442,17 +522,36 @@ const ConfiguredForm = ({ binding, config, options, ...formProps }) => {
 		children: Body === void 0 ? content : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Body, { children: content })
 	}) });
 };
+const isAsyncValidation = (validation) => typeof validation === "object" && validation !== null && "async" in validation ? validation.async === true : false;
+const requiredPathsOf = (binding, config) => {
+	const result = findRequiredPaths({
+		schema: config.schema,
+		validatesAsync: isAsyncValidation(config.validation),
+		fields: config.fields ?? {},
+		widgets: binding.parts.widgets
+	});
+	if ("problem" in result) {
+		warnOnce(config, result.problem);
+		return /* @__PURE__ */ new Set();
+	}
+	return result.paths;
+};
 /**
 * Turns a form config into a form component bound to `binding`: TanStack's form with the merged
 * options, a `<form>` element that submits through it, the registered body and the config's fields.
+* When it first renders, it finds the config's required fields once.
 */
 function createForm(binding, config) {
-	const Form = (props) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ConfiguredForm, {
-		...props,
-		binding,
-		config
-	});
-	return Form;
+	let requiredPaths;
+	return (props) => {
+		requiredPaths ??= requiredPathsOf(binding, config);
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ConfiguredForm, {
+			...props,
+			binding,
+			config,
+			requiredPaths
+		});
+	};
 }
 // src/registry/create-registry.ts
 function buildRegistry(parts) {
@@ -463,13 +562,14 @@ function buildRegistry(parts) {
 		formComponents: parts.formComponents
 	});
 	function extendRegistry(extension) {
+		const addedWidgets = extension.widgets ?? {};
 		const addedStructure = extension.structure ?? {};
 		return buildRegistry({
 			fieldContext: parts.fieldContext,
 			formContext: parts.formContext,
 			widgets: {
 				...parts.widgets,
-				...extension.widgets
+				...addedWidgets
 			},
 			formComponents: {
 				...parts.formComponents,
@@ -513,7 +613,8 @@ function buildRegistry(parts) {
 * @param config - The contexts and what the registry holds.
 * @param config.fieldContext - The field context from `createFormHookContexts()`.
 * @param config.formContext - The form context from `createFormHookContexts()`.
-* @param config.widgets - The widgets by name.
+* @param config.widgets - The widgets by name. A widget's static `emptyValue`, the value it holds
+*   while nothing is entered, must be of the value type it serves.
 * @param config.formComponents - The form components by name.
 * @param config.structure - The components that render the structure slots.
 * @defaultValue `config.formComponents` and `config.structure`: none registered.
@@ -582,7 +683,7 @@ function errorsOf(field) {
 const PATH_SEPARATORS = /[.[\]]+/g;
 const SELECTOR_SAFE_SEPARATOR = "__";
 /**
-* Builds the DOM id that `fieldParts` gives the control of a field, for code that has no
+* Builds the DOM id that `useFieldParts` gives the control of a field, for code that has no
 * field at hand — an error summary above the form that links to each invalid field, for example.
 *
 * The id is the form's id, a hyphen, and the field's path with every run of dots and brackets
@@ -609,17 +710,42 @@ function fieldId(formId, path) {
 const DESCRIPTION_SUFFIX = "-description";
 const ERROR_SUFFIX = "-error";
 const IDREF_SEPARATOR = " ";
-function isErrorDueFor(field) {
+function isErrorDueFor(field, wasSubmitted) {
 	const { isBlurred, isDirty, isValid } = field.state.meta;
-	const wasEditedAndLeft = isBlurred && isDirty;
-	const wasSubmitted = field.form.state.submissionAttempts > 0;
-	return !isValid && (wasEditedAndLeft || wasSubmitted);
+	return !isValid && (isBlurred && isDirty || wasSubmitted);
 }
 function idrefsOf(ids) {
 	const present = ids.filter((id) => id !== void 0);
 	return present.length > 0 ? present.join(IDREF_SEPARATOR) : void 0;
 }
 /**
+* The parts of `field` with the submit state passed in, so the result depends on nothing the
+* caller cannot see.
+*/
+function fieldPartsFor(field, options) {
+	const id = fieldId(field.form.formId, field.name);
+	const descriptionId = `${id}${DESCRIPTION_SUFFIX}`;
+	const errorId = `${id}${ERROR_SUFFIX}`;
+	const isErrorDue = isErrorDueFor(field, options.wasSubmitted);
+	const errors = errorsOf(field);
+	const isErrorNamed = isErrorDue && errors.length > 0;
+	const hasDescription = options.description !== void 0 && options.description !== "";
+	return {
+		control: {
+			id,
+			name: field.name,
+			onBlur: field.handleBlur,
+			"aria-invalid": isErrorDue || void 0,
+			"aria-describedby": idrefsOf([hasDescription ? descriptionId : void 0, isErrorNamed ? errorId : void 0]),
+			"aria-errormessage": isErrorNamed ? errorId : void 0
+		},
+		descriptionId,
+		errorId,
+		isErrorDue,
+		errors
+	};
+}
+/**
 * Wires a widget's control to its field: its id and name, the blur report, and the aria
 * attributes that tie it to its description and its errors.
 *
@@ -628,6 +754,11 @@ function idrefsOf(ids) {
 * points at the error element through `aria-describedby` and `aria-errormessage`. An id appears in
 * them only when its element is rendered.
 *
+* `fieldParts` reads whether the form was submitted without subscribing to it, so a widget whose
+* field state does not change on a submit keeps its error hidden until it renders again.
+*
+* @deprecated Use {@link useFieldParts}, which subscribes to the submit and renders the widget
+*   again.
 * @typeParam TValue - The value type of the field.
 * @param field - The field the widget renders.
 * @param options - What the widget renders besides the control.
@@ -654,31 +785,60 @@ function idrefsOf(ids) {
 * ```
 */
 function fieldParts(field, options = {}) {
-	const id = fieldId(field.form.formId, field.name);
-	const descriptionId = `${id}${DESCRIPTION_SUFFIX}`;
-	const errorId = `${id}${ERROR_SUFFIX}`;
-	const isErrorDue = isErrorDueFor(field);
-	const errors = errorsOf(field);
-	const isErrorNamed = isErrorDue && errors.length > 0;
-	const hasDescription = options.description !== void 0 && options.description !== "";
-	return {
-		control: {
-			id,
-			name: field.name,
-			onBlur: field.handleBlur,
-			"aria-invalid": isErrorDue || void 0,
-			"aria-describedby": idrefsOf([hasDescription ? descriptionId : void 0, isErrorNamed ? errorId : void 0]),
-			"aria-errormessage": isErrorNamed ? errorId : void 0
-		},
-		descriptionId,
-		errorId,
-		isErrorDue,
-		errors
-	};
+	return fieldPartsFor(field, {
+		...options,
+		wasSubmitted: field.form.state.submissionAttempts > 0
+	});
+}
+// src/widget/use-field-parts.ts
+/**
+* Wires a widget's control to its field: its id and name, the blur report, and the aria
+* attributes that tie it to its description and its errors.
+*
+* An error is due once the field is invalid and was edited and left, or once the form was
+* submitted. While one is due, `aria-invalid` is `true`; while one with text is due, the control
+* points at the error element through `aria-describedby` and `aria-errormessage`. An id appears in
+* them only when its element is rendered.
+*
+* The hook subscribes to whether the form was submitted, so a submit renders the widget again even
+* when its field state does not change, as for a field that was left before without an edit.
+*
+* @typeParam TValue - The value type of the field.
+* @param field - The field the widget renders.
+* @param options - What the widget renders besides the control.
+* @param options.description - The description the widget renders below its label, if any. Only
+*   whether it is a non-empty string is read.
+* @defaultValue `options.description`: `undefined`, no description is rendered.
+* @returns The props for the control, the ids for the description and error elements, whether an
+*   error is due, and the error texts.
+*
+* @example
+* ```tsx
+* const TextField = ({ field, label, description }: FieldOf<string> & { label: string; description?: string }) => {
+*   const { control, descriptionId, errorId, isErrorDue, errors } = useFieldParts(field, { description })
+*
+*   return (
+*     <div>
+*       <label htmlFor={control.id}>{label}</label>
+*       {description && <p id={descriptionId}>{description}</p>}
+*       <input {...control} value={field.state.value} onChange={(event) => field.handleChange(event.target.value)} />
+*       {isErrorDue && errors.length > 0 && <p id={errorId}>{errors.join(' ')}</p>}
+*     </div>
+*   )
+* }
+* ```
+*/
+function useFieldParts(field, options = {}) {
+	const wasSubmitted = (0, _tanstack_react_form.useSelector)(field.form.store, (state) => state.submissionAttempts > 0);
+	return fieldPartsFor(field, {
+		...options,
+		wasSubmitted
+	});
 }
 exports.createRegistry = createRegistry;
 exports.errorsOf = errorsOf;
 exports.fieldId = fieldId;
 exports.fieldParts = fieldParts;
+exports.useFieldParts = useFieldParts;
 
 //# sourceMappingURL=index.cjs.map