feat: Allow restricting field component to field value

packages/react-form/src/createFormHook.tsx

@@ -4,14 +4,14 @@
   AnyFieldApi,
   AnyFormApi,
   FieldApi,
-  FormApi,
   FormAsyncValidateOrFn,
   FormOptions,
   FormValidateOrFn,
 } from '@tanstack/form-core'
 import type { ComponentType, Context, JSX, PropsWithChildren } from 'react'
 import type { FieldComponent } from './useField'
 import type { ReactFormExtendedApi } from './useForm'
+import type { AppFieldComponents, AppFormComponents, DataTag } from './types'
 
 /**
  * TypeScript inferencing is weird.
@@ -50,6 +50,39 @@
     : T
   : T
 
+/**
+ * Create a field component based on a provided React component.
+ * If `TFieldValue` is provided, it will restrict its use to AppFields
+ * that extend that value.
+ *
+ * @example
+ * ```tsx
+ * interface TextFieldProps {
+ *   label: string;
+ * }
+ * function TextField(props: TextFieldProps) {
+ *   const field = useFieldContext<string>();
+ *   // ...
+ *   return <></>
+ * }
+ * // create a TextField component that may only be used in string AppFields
+ * const TextFieldComponent = createFieldComponent<string, TextFieldProps>(TextField);
+ *
+ * // in your form hook
+ * createFormHook({
+ *   // ...
+ *   fieldComponents: {
+ *     TextField: TextFieldComponent
+ *   }
+ * })
+ * ```
+ */
+function createFieldComponent<TFieldValue, TProps>(
+  component: ComponentType<TProps>,
+): DataTag<ComponentType<TProps>, TFieldValue> {
+  return component as never
+}
+
 export function createFormHookContexts() {
   // We should never hit the `null` case here
   const fieldContext = createContext<AnyFieldApi>(null as never)
@@ -115,12 +148,18 @@
     >
   }
 
-  return { fieldContext, useFieldContext, useFormContext, formContext }
+  return {
+    fieldContext,
+    useFieldContext,
+    useFormContext,
+    formContext,
+    createFieldComponent,
+  }
 }
 
 interface CreateFormHookProps<
-  TFieldComponents extends Record<string, ComponentType<any>>,
-  TFormComponents extends Record<string, ComponentType<any>>,
+  TFieldComponents extends AppFieldComponents,
+  TFormComponents extends AppFormComponents,
 > {
   fieldComponents: TFieldComponents
   fieldContext: Context<AnyFieldApi>
@@ -139,8 +178,8 @@
   TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
   TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
   TSubmitMeta,
-  TFieldComponents extends Record<string, ComponentType<any>>,
-  TFormComponents extends Record<string, ComponentType<any>>,
+  TFieldComponents extends AppFieldComponents,
+  TFormComponents extends AppFormComponents,
 > = ReactFormExtendedApi<
   TFormData,
   TOnMount,
@@ -181,8 +220,8 @@
   TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
   TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
   TSubmitMeta,
-  TFieldComponents extends Record<string, ComponentType<any>>,
-  TFormComponents extends Record<string, ComponentType<any>>,
+  TFieldComponents extends AppFieldComponents,
+  TFormComponents extends AppFormComponents,
   TRenderProps extends object = Record<string, never>,
 > extends FormOptions<
     TFormData,
@@ -221,8 +260,8 @@
 }
 
 export function createFormHook<
-  const TComponents extends Record<string, ComponentType<any>>,
-  const TFormComponents extends Record<string, ComponentType<any>>,
+  const TComponents extends AppFieldComponents,
+  const TFormComponents extends AppFormComponents,
 >({
   fieldComponents,
   fieldContext,

packages/react-form/src/types.ts

@@ -8,6 +8,51 @@ import type {
   FormAsyncValidateOrFn,
   FormValidateOrFn,
 } from '@tanstack/form-core'
+import type { ComponentType } from 'react'
+
+declare const dataTagFieldValueSymbol: unique symbol
+
+type AnyDataTag = {
+  [dataTagFieldValueSymbol]: any
+}
+
+/**
+ * @private
+ */
+export type DataTag<TType, TFieldValue> = TType extends AnyDataTag
+  ? TType
+  : TType & {
+      [dataTagFieldValueSymbol]: TFieldValue
+    }
+/**
+ * @private
+ */
+export type AppFieldComponents = Record<
+  string,
+  ComponentType<any> | DataTag<ComponentType<any>, any>
+>
+
+/**
+ * @private
+ */
+export type AppFieldComponentsOfType<
+  TFieldValue,
+  TRecord extends AppFieldComponents,
+> = {
+  [K in keyof TRecord as TRecord[K] extends DataTag<
+    unknown,
+    infer TaggedFieldValue
+  >
+    ? TaggedFieldValue extends TFieldValue // does the brand match?
+      ? K
+      : never // brand doesn't match
+    : K]: TRecord[K]
+}
+
+/**
+ * @private
+ */
+export type AppFormComponents = Record<string, ComponentType<any>>
 
 interface FieldOptionsMode {
   mode?: 'value' | 'array'

packages/react-form/src/useField.tsx

@@ -11,7 +11,12 @@ import type {
   FormValidateOrFn,
 } from '@tanstack/form-core'
 import type { FunctionComponent, ReactNode } from 'react'
-import type { UseFieldOptions, UseFieldOptionsBound } from './types'
+import type {
+  AppFieldComponents,
+  AppFieldComponentsOfType,
+  UseFieldOptions,
+  UseFieldOptionsBound,
+} from './types'
 
 interface ReactFieldApi<
   TParentData,
@@ -23,7 +28,7 @@ interface ReactFieldApi<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
 > {
   /**
    * A pre-bound and type-safe sub-field component using this field as a root.
@@ -38,7 +43,7 @@ interface ReactFieldApi<
     TFormOnSubmit,
     TFormOnSubmitAsync,
     TFormOnServer,
-    TPatentSubmitMeta
+    TParentSubmitMeta
   >
 }
 
@@ -57,7 +62,7 @@ export type UseField<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
 > = <
   TName extends DeepKeys<TParentData>,
   TData extends DeepValue<TParentData, TName>,
@@ -106,7 +111,7 @@ export type UseField<
   TFormOnSubmit,
   TFormOnSubmitAsync,
   TFormOnServer,
-  TPatentSubmitMeta
+  TParentSubmitMeta
 >
 
 /**
@@ -140,7 +145,7 @@ export function useField<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
 >(
   opts: UseFieldOptions<
     TParentData,
@@ -161,7 +166,7 @@ export function useField<
     TFormOnSubmit,
     TFormOnSubmitAsync,
     TFormOnServer,
-    TPatentSubmitMeta
+    TParentSubmitMeta
   >,
 ) {
   const [fieldApi] = useState(() => {
@@ -182,7 +187,7 @@ export function useField<
         TFormOnSubmit,
         TFormOnSubmitAsync,
         TFormOnServer,
-        TPatentSubmitMeta
+        TParentSubmitMeta
       > = api as never
 
     extendedApi.Field = Field as never
@@ -243,8 +248,8 @@ interface FieldComponentProps<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
-  ExtendedApi = {},
+  TParentSubmitMeta,
+  ExtendedApi extends AppFieldComponents = {},
 > extends UseFieldOptions<
     TParentData,
     TName,
@@ -264,7 +269,7 @@ interface FieldComponentProps<
     TFormOnSubmit,
     TFormOnSubmitAsync,
     TFormOnServer,
-    TPatentSubmitMeta
+    TParentSubmitMeta
   > {
   children: (
     fieldApi: FieldApi<
@@ -286,9 +291,9 @@ interface FieldComponentProps<
       TFormOnSubmit,
       TFormOnSubmitAsync,
       TFormOnServer,
-      TPatentSubmitMeta
+      TParentSubmitMeta
     > &
-      ExtendedApi,
+      AppFieldComponentsOfType<TData, ExtendedApi>,
   ) => ReactNode
 }
 
@@ -317,8 +322,8 @@ interface FieldComponentBoundProps<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
-  ExtendedApi = {},
+  TParentSubmitMeta,
+  ExtendedApi extends AppFieldComponents = {},
 > extends UseFieldOptionsBound<
     TParentData,
     TName,
@@ -351,9 +356,9 @@ interface FieldComponentBoundProps<
       TFormOnSubmit,
       TFormOnSubmitAsync,
       TFormOnServer,
-      TPatentSubmitMeta
+      TParentSubmitMeta
     > &
-      ExtendedApi,
+      AppFieldComponentsOfType<TData, ExtendedApi>,
   ) => ReactNode
 }
 
@@ -376,8 +381,8 @@ export type FieldComponent<
     | undefined
     | FormAsyncValidateOrFn<TParentData>,
   in out TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  in out TPatentSubmitMeta,
-  in out ExtendedApi = {},
+  in out TParentSubmitMeta,
+  in out ExtendedApi extends AppFieldComponents = {},
 > = <
   const TName extends DeepKeys<TParentData>,
   TData extends DeepValue<TParentData, TName>,
@@ -416,7 +421,7 @@ export type FieldComponent<
   TFormOnSubmit,
   TFormOnSubmitAsync,
   TFormOnServer,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
   ExtendedApi
 >) => ReactNode
 
@@ -450,7 +455,7 @@ export const Field = (<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
 >({
   children,
   ...fieldOptions
@@ -473,7 +478,7 @@ export const Field = (<
   TFormOnSubmit,
   TFormOnSubmitAsync,
   TFormOnServer,
-  TPatentSubmitMeta
+  TParentSubmitMeta
 >): ReactNode => {
   const fieldApi = useField(fieldOptions as any)