feat: Allow restricting field component to field value

packages/react-form/src/createFormHook.tsx

@@ -16,6 +16,7 @@ import type {
 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'
 import type { AppFieldExtendedReactFieldGroupApi } from './useFieldGroup'
 
 // We should never hit the `null` case here
@@ -59,6 +60,39 @@ type UnwrapDefaultOrAny<DefaultT, T> = [DefaultT] extends [T]
     : 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() {
   function useFieldContext<TData>() {
     const field = useContext(fieldContext)
@@ -124,12 +158,18 @@ export function createFormHookContexts() {
     >
   }
 
-  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>
@@ -153,8 +193,8 @@ export type AppFieldExtendedReactFormApi<
   TOnDynamicAsync 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,
@@ -201,8 +241,8 @@ export interface WithFormProps<
   TOnDynamicAsync 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,
@@ -282,8 +322,8 @@ export interface WithFieldGroupProps<
 }
 
 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

@@ -12,7 +12,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,
@@ -26,7 +31,7 @@ interface ReactFieldApi<
   TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
   TFormOnDynamicAsync 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.
@@ -43,7 +48,7 @@ interface ReactFieldApi<
     TFormOnDynamic,
     TFormOnDynamicAsync,
     TFormOnServer,
-    TPatentSubmitMeta
+    TParentSubmitMeta
   >
 }
 
@@ -64,7 +69,7 @@ export type UseField<
   TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
   TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
 > = <
   TName extends DeepKeys<TParentData>,
   TData extends DeepValue<TParentData, TName>,
@@ -123,7 +128,7 @@ export type UseField<
   TFormOnDynamic,
   TFormOnDynamicAsync,
   TFormOnServer,
-  TPatentSubmitMeta
+  TParentSubmitMeta
 >
 
 /**
@@ -163,7 +168,7 @@ export function useField<
   TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
   TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
 >(
   opts: UseFieldOptions<
     TParentData,
@@ -188,7 +193,7 @@ export function useField<
     TFormOnDynamic,
     TFormOnDynamicAsync,
     TFormOnServer,
-    TPatentSubmitMeta
+    TParentSubmitMeta
   >,
 ) {
   const [fieldApi] = useState(() => {
@@ -211,7 +216,7 @@ export function useField<
         TFormOnDynamic,
         TFormOnDynamicAsync,
         TFormOnServer,
-        TPatentSubmitMeta
+        TParentSubmitMeta
       > = api as never
 
     extendedApi.Field = Field as never
@@ -278,8 +283,8 @@ interface FieldComponentProps<
   TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
   TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
-  ExtendedApi = {},
+  TParentSubmitMeta,
+  ExtendedApi extends AppFieldComponents = {},
 > extends UseFieldOptions<
     TParentData,
     TName,
@@ -303,7 +308,7 @@ interface FieldComponentProps<
     TFormOnDynamic,
     TFormOnDynamicAsync,
     TFormOnServer,
-    TPatentSubmitMeta
+    TParentSubmitMeta
   > {
   children: (
     fieldApi: FieldApi<
@@ -329,9 +334,9 @@ interface FieldComponentProps<
       TFormOnDynamic,
       TFormOnDynamicAsync,
       TFormOnServer,
-      TPatentSubmitMeta
+      TParentSubmitMeta
     > &
-      ExtendedApi,
+      AppFieldComponentsOfType<TData, ExtendedApi>,
   ) => ReactNode
 }
 
@@ -366,8 +371,8 @@ interface FieldComponentBoundProps<
   TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
   TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
-  ExtendedApi = {},
+  TParentSubmitMeta,
+  ExtendedApi extends AppFieldComponents = {},
 > extends UseFieldOptionsBound<
     TParentData,
     TName,
@@ -406,9 +411,9 @@ interface FieldComponentBoundProps<
       TFormOnDynamic,
       TFormOnDynamicAsync,
       TFormOnServer,
-      TPatentSubmitMeta
+      TParentSubmitMeta
     > &
-      ExtendedApi,
+      AppFieldComponentsOfType<TData, ExtendedApi>,
   ) => ReactNode
 }
 
@@ -435,8 +440,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>,
@@ -483,7 +488,7 @@ export type FieldComponent<
   TFormOnDynamic,
   TFormOnDynamicAsync,
   TFormOnServer,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
   ExtendedApi
 >) => ReactNode
 
@@ -611,7 +616,7 @@ export const Field = (<
   TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
   TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
-  TPatentSubmitMeta,
+  TParentSubmitMeta,
 >({
   children,
   ...fieldOptions
@@ -638,7 +643,7 @@ export const Field = (<
   TFormOnDynamic,
   TFormOnDynamicAsync,
   TFormOnServer,
-  TPatentSubmitMeta
+  TParentSubmitMeta
 >): ReactNode => {
   const fieldApi = useField(fieldOptions as any)