react-f0rm 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -151,9 +151,11 @@ declare function useFormContext<T extends Record<string, any> = any>(): Form$1<T
  * (`Ctx.useField({name: 'user.name'})` gets its `name` constrained by
  * `FieldPath<Values>` and its `value` typed accordingly), so call sites stop
  * hand-writing generics, and each instance's Provider scopes a strictly
- * separate form.
+ * separate form. The bundle also carries its raw React context
+ * (`Ctx.context`) so `<Form context={Ctx.context}>` can provide into it.
  */
 declare function createFormContext<TValues extends Record<string, any> = any>(): {
+    context: React.Context<Form$1<TValues> | null>;
     FormProvider: ({ form, children }: {
         form: Form$1<TValues>;
         children: ReactNode;
@@ -316,6 +318,16 @@ declare function subscribe(form: Form$1, options: SubscribeOptions): () => void;
  */
 interface FormProps<T extends Record<string, any> = any> extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
     form?: Form<T>;
+    /**
+     * Provide into an isolated context from `createFormContext()` instead of
+     * the module-level one — `<Form context={ProfileForm.context}>` keeps the
+     * component's full submit machinery while the factory's bound hooks
+     * (`ProfileForm.useField`, `ProfileForm.useFormContext`, ...) resolve this
+     * form from their private context. The module-level `useFormContext()` /
+     * `useField` do not see it; that is the point of the isolation. Omitted,
+     * the form lands in the module-level FormContext as before.
+     */
+    context?: React.Context<Form<any> | null>;
     initialValues?: T;
     /**
      * Controlled external values. When the `values` reference changes, the
@@ -349,14 +361,34 @@ interface FormProps<T extends Record<string, any> = any> extends Omit<React.Form
      */
     shouldFocusError?: boolean;
 }
-declare function Form<T extends Record<string, any> = any>({ form: f1, initialValues, values, onSubmit, onValidSubmit, onInvalidSubmit, shouldFocusError, ...props }: FormProps<T>): React.JSX.Element;
+declare function Form<T extends Record<string, any> = any>({ form: f1, context, initialValues, values, onSubmit, onValidSubmit, onInvalidSubmit, shouldFocusError, ...props }: FormProps<T>): React.JSX.Element;
 
-interface UseFieldOptions {
-    form?: any;
-    name?: Name;
+/**
+ * Props shared by Field/Checkbox/Select. Generic so a typed form flows into
+ * the `validate` callback: with `form` (a `Form<Values>`) and `name`
+ * (a `FieldPath<Values>`) provided, `validate` receives the value at that
+ * path — `PathValueOf<Values, P>` — instead of `any`. The defaults keep the
+ * bare `<Field name="x" />` (context-resolved, untyped) call sites exactly
+ * as permissive as before.
+ */
+interface UseFieldOptions<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> {
+    form?: Form$1<TValues>;
+    name?: TPath;
     initialValue?: any;
     shouldUnregister?: boolean;
-    validate?: Validator;
+    /**
+     * Field-level validator. The value argument is typed when the field is
+     * tied to a typed form (via the `form` prop); the return shape mirrors
+     * {@link Validator} — an error (string / FieldError / mixed array) or
+     * undefined when valid, possibly a Promise for async validation. The
+     * second argument carries the validation context (`meta.signal` aborts
+     * when the round is superseded).
+     */
+    validate?: (value: PathValueOf<TValues, TPath>, meta: {
+        form: Form$1;
+        path: Path;
+        signal: AbortSignal;
+    }) => ReturnType<Validator>;
     /**
      * Declarative rules (required/min/max/minLength/maxLength/pattern),
      * compiled into a validator that runs before `validate`; failures land
@@ -388,7 +420,7 @@ interface UseFieldOptions {
     delayError?: number;
     [key: string]: any;
 }
-interface FieldProps extends UseFieldOptions {
+interface FieldProps<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> extends UseFieldOptions<TValues, TPath> {
     as?: React.ComponentType<any>;
     asProps?: Record<string, any>;
     eventToValue?: (e: any) => any;
@@ -402,15 +434,39 @@ interface FieldProps extends UseFieldOptions {
      */
     renderError?: (error: string, id: string) => React.ReactNode;
 }
-declare const Field: React.ForwardRefExoticComponent<Omit<FieldProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
-interface CheckboxProps extends UseFieldOptions {
+/**
+ * The callable shape of {@link Field}: `form` + `name` flow their generics
+ * into `validate`'s value argument (`PathValueOf<TValues, TPath>`). A named
+ * interface rather than an inline `as <TValues, ...>() => ...` signature —
+ * same types, and the inline form trips no-use-before-define on the type
+ * parameters.
+ */
+interface FieldComponent {
+    <TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name>(props: FieldProps<TValues, TPath> & React.RefAttributes<HTMLInputElement>): React.ReactElement | null;
+}
+declare const Field: FieldComponent;
+interface CheckboxProps<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> extends UseFieldOptions<TValues, TPath> {
+}
+/**
+ * Callable shape of {@link Checkbox}: the same form-typed `validate`
+ * inference contract as {@link FieldComponent}.
+ */
+interface CheckboxComponent {
+    <TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name>(props: CheckboxProps<TValues, TPath> & React.RefAttributes<HTMLInputElement>): React.ReactElement | null;
 }
-declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
-interface SelectProps extends UseFieldOptions {
+declare const Checkbox: CheckboxComponent;
+interface SelectProps<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> extends UseFieldOptions<TValues, TPath> {
     multiple?: boolean;
     children?: React.ReactNode;
 }
-declare const Select: React.ForwardRefExoticComponent<Omit<SelectProps, "ref"> & React.RefAttributes<HTMLSelectElement>>;
+/**
+ * Callable shape of {@link Select}: the same form-typed `validate`
+ * inference contract as {@link FieldComponent}.
+ */
+interface SelectComponent {
+    <TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name>(props: SelectProps<TValues, TPath> & React.RefAttributes<HTMLSelectElement>): React.ReactElement | null;
+}
+declare const Select: SelectComponent;
 
 export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, FieldError, FieldPath, Form, FormContext, Form$1 as FormInstance, FormProvider, Name, Options, PathValueOf, Select, createFormContext, subscribe, useCheckboxGroupContext, useDirtyFields, useError, useErrorByPath, useField, useFieldArray, useFieldErrors, useFieldErrorsByPath, useForm, useFormContext, useHasErrors, useIsDirty, useIsSubmitting, useSubmitCount, useTouched, useTouchedByPath, useTouchedFields, useValue, useValueByPath, useWatch };
 export type { FieldRules, SubscribeEvent, SubscribeOptions, WatchScope };

package/dist/index.mjs

@@ -1421,7 +1421,13 @@ function createFormContext() {
   function useFieldArray(options) {
     return useFieldArrayCore(options, Context);
   }
-  return { FormProvider: FormProvider2, useFormContext: useFormContext2, useField, useFieldArray };
+  return {
+    context: Context,
+    FormProvider: FormProvider2,
+    useFormContext: useFormContext2,
+    useField,
+    useFieldArray
+  };
 }
 const CheckboxGroupContext = createContext(null);
 const CheckboxGroupProvider = CheckboxGroupContext.Provider;
@@ -1433,6 +1439,7 @@ function useCheckboxGroupContext() {
 
 function Form({
   form: f1,
+  context,
   initialValues,
   values,
   onSubmit,
@@ -1449,7 +1456,8 @@ function Form({
     onInvalidSubmit,
     shouldFocusError
   });
-  return /* @__PURE__ */ React.createElement(FormProvider, { value: form }, /* @__PURE__ */ React.createElement("form", { ...props, noValidate: true, onSubmit: submit }));
+  const { Provider } = context ?? FormContext;
+  return /* @__PURE__ */ React.createElement(Provider, { value: form }, /* @__PURE__ */ React.createElement("form", { ...props, noValidate: true, onSubmit: submit }));
 }
 
 function setRef(ref, value) {