@tanstack/vue-form 1.33.4 → 2.0.0-alpha.0

package/src/FieldGroup/FieldGroupApi.public.ts

@@ -0,0 +1,148 @@
+import type {
+  DeepKeys,
+  DeepKeysWhereValueIncludes,
+  DeepValue,
+  FieldValidators,
+  FormApiArrayMethods,
+  FormApiFieldMethods,
+  FormErrorTypes,
+  FormState,
+  ToFieldError,
+  ValidationIssue,
+} from '@tanstack/form-core'
+import type { Component, PublicProps } from 'vue'
+import type { ReadonlyAtom } from '@tanstack/vue-store'
+import type {
+  VueFieldApi,
+  VueFormFieldProps,
+  VueFormSubscribeProps,
+} from '../VueForm/Components.public'
+import type { VueComponentInstance } from '../vueTypes.lib'
+
+export type FieldGroupFieldComponent<
+  in out TFieldData,
+  in out TFieldComponents extends Record<string, Component>,
+> = new <const TFieldName extends DeepKeys<TFieldData>>(
+  props: VueFormFieldProps<
+    TFieldData,
+    TFieldName,
+    DeepValue<TFieldData, TFieldName>,
+    FieldValidators<TFieldData, TFieldName, DeepValue<TFieldData, TFieldName>>,
+    ValidationIssue,
+    unknown,
+    FormErrorTypes,
+    TFieldComponents
+  > &
+    PublicProps,
+) => VueComponentInstance<
+  VueFormFieldProps<
+    TFieldData,
+    TFieldName,
+    DeepValue<TFieldData, TFieldName>,
+    FieldValidators<TFieldData, TFieldName, DeepValue<TFieldData, TFieldName>>,
+    ValidationIssue,
+    unknown,
+    FormErrorTypes,
+    TFieldComponents
+  >,
+  {
+    default: {
+      field: VueFieldApi<
+        TFieldName,
+        DeepValue<TFieldData, TFieldName>,
+        ToFieldError<
+          FieldValidators<
+            TFieldData,
+            TFieldName,
+            DeepValue<TFieldData, TFieldName>
+          >,
+          ValidationIssue,
+          FormErrorTypes
+        >,
+        unknown,
+        FormErrorTypes,
+        TFieldComponents
+      >
+    }
+  }
+>
+
+export type FieldGroupArrayFieldComponent<
+  in out TFieldData,
+  in out TFieldComponents extends Record<string, Component>,
+> = new <
+  const TFieldName extends DeepKeysWhereValueIncludes<TFieldData, Array<any>>,
+>(
+  props: VueFormFieldProps<
+    TFieldData,
+    TFieldName,
+    DeepValue<TFieldData, TFieldName>,
+    FieldValidators<TFieldData, TFieldName, DeepValue<TFieldData, TFieldName>>,
+    ValidationIssue,
+    unknown,
+    FormErrorTypes,
+    TFieldComponents
+  > &
+    PublicProps,
+) => VueComponentInstance<
+  VueFormFieldProps<
+    TFieldData,
+    TFieldName,
+    DeepValue<TFieldData, TFieldName>,
+    FieldValidators<TFieldData, TFieldName, DeepValue<TFieldData, TFieldName>>,
+    ValidationIssue,
+    unknown,
+    FormErrorTypes,
+    TFieldComponents
+  >,
+  {
+    default: {
+      field: VueFieldApi<
+        TFieldName,
+        DeepValue<TFieldData, TFieldName>,
+        ToFieldError<
+          FieldValidators<
+            TFieldData,
+            TFieldName,
+            DeepValue<TFieldData, TFieldName>
+          >,
+          ValidationIssue,
+          FormErrorTypes
+        >,
+        unknown,
+        FormErrorTypes,
+        TFieldComponents
+      >
+    }
+  }
+>
+
+export type FieldGroupSubscribeProps<TSelected> = VueFormSubscribeProps<
+  unknown,
+  FormErrorTypes,
+  TSelected
+>
+
+export type FieldGroupSubscribeComponent = new <TSelected>(
+  props: FieldGroupSubscribeProps<TSelected> & PublicProps,
+) => VueComponentInstance<
+  FieldGroupSubscribeProps<TSelected>,
+  { default: NoInfer<TSelected> }
+>
+
+export interface FieldGroupApi<
+  in out TFieldData,
+  in out TFieldComponents extends Record<string, Component> = Record<
+    never,
+    never
+  >,
+>
+  extends FormApiFieldMethods<TFieldData>, FormApiArrayMethods<TFieldData> {
+  atom: ReadonlyAtom<TFieldData>
+  Field: FieldGroupFieldComponent<TFieldData, TFieldComponents>
+  ArrayField: FieldGroupArrayFieldComponent<TFieldData, TFieldComponents>
+  Subscribe: FieldGroupSubscribeComponent
+}
+
+export type AnyFieldGroupApi = FieldGroupApi<any, Record<string, Component>>
+export type FieldGroupFormState = FormState<unknown, FormErrorTypes>

package/src/FieldGroup/withFields.lib.ts

@@ -0,0 +1,103 @@
+import {
+  InternalFieldGroupApi,
+  defineFieldGroupFieldsRuntime,
+  fieldGroupHelperRuntime,
+} from '@tanstack/form-core/internals'
+import { computed, defineComponent, h } from 'vue'
+import type { Component } from 'vue'
+import type {
+  AnyFieldApiOptions,
+  InternalFieldGroupBindings,
+} from '@tanstack/form-core/internals'
+import type { AnyFieldGroupApi } from './FieldGroupApi.public'
+
+function attachVueFieldGroupComponents(
+  group: InternalFieldGroupApi,
+  form: any,
+): AnyFieldGroupApi {
+  const forwardField = (component: Component, name: string) =>
+    defineComponent(
+      (_props, context) => {
+        const resolved = computed(() => {
+          const options = {
+            ...context.attrs,
+          } as unknown as AnyFieldApiOptions
+          return group._getFormFieldOptions(options, (base, overrides) => ({
+            ...base,
+            ...overrides,
+          }))
+        })
+        return () => h(component, resolved.value as never, context.slots)
+      },
+      { name, inheritAttrs: false },
+    )
+
+  const Field = forwardField(form.Field, 'TanStackForm.FieldGroup.Field')
+  const ArrayField = forwardField(
+    form.ArrayField,
+    'TanStackForm.FieldGroup.ArrayField',
+  )
+  const Subscribe = defineComponent(
+    (_props, context) => () =>
+      h(form.Subscribe, { ...context.attrs } as never, context.slots),
+    { name: 'TanStackForm.FieldGroup.Subscribe', inheritAttrs: false },
+  )
+
+  return Object.assign(group, {
+    Field,
+    ArrayField,
+    Subscribe,
+  }) as never
+}
+
+export function defineFieldGroupRuntime<
+  TFields extends Record<string, unknown>,
+>(defineFieldGroupFn: (helperRuntime: any) => TFields) {
+  const fields = defineFieldGroupFieldsRuntime(
+    defineFieldGroupFn(fieldGroupHelperRuntime),
+  )
+
+  return {
+    fields,
+    bindComponent: (component: Component, fieldsPropName: string) =>
+      withFieldsRuntime(fields, component, fieldsPropName),
+  }
+}
+
+function withFieldsRuntime(
+  fields: Record<string, unknown>,
+  component: Component,
+  fieldsPropName: string,
+) {
+  const fieldNames = Object.keys(fields)
+
+  return defineComponent(
+    (_props, context) => {
+      const form = context.attrs.form as any
+      if (!form) {
+        throw new Error(
+          'TanStack Form: Field groups must receive a `form` prop.',
+        )
+      }
+
+      const fieldGroupApi = attachVueFieldGroupComponents(
+        new InternalFieldGroupApi({
+          form,
+          fieldNames,
+          getBindings: () =>
+            context.attrs[fieldsPropName] as InternalFieldGroupBindings,
+        }),
+        form,
+      )
+
+      return () => {
+        const componentProps = { ...context.attrs }
+        delete componentProps.form
+        delete componentProps[fieldsPropName]
+        componentProps[fieldsPropName] = fieldGroupApi
+        return h(component, componentProps, context.slots)
+      }
+    },
+    { name: 'TanStackForm.FieldGroup', inheritAttrs: false },
+  )
+}

package/src/FieldGroup/withFields.public.ts

@@ -0,0 +1,191 @@
+import { defineFieldGroupRuntime } from './withFields.lib'
+import type {
+  DeepKeys,
+  DeepKeysWhereValueIncludes,
+  DeepValue,
+  FormApi,
+} from '@tanstack/form-core'
+import type { Component, PublicProps } from 'vue'
+import type { VueTanStackFormComponents } from '../VueForm/Components.public'
+import type { FieldGroupApi } from './FieldGroupApi.public'
+import type { VueComponentInstance } from '../vueTypes.lib'
+
+declare const fieldGroupFieldSlotValueSymbol: unique symbol
+declare const fieldGroupFieldsSymbol: unique symbol
+
+export type FieldGroupFieldSlotMode = 'strict' | 'loose'
+export interface FieldGroupFieldSlot<
+  out TValue,
+  out TMode extends FieldGroupFieldSlotMode = FieldGroupFieldSlotMode,
+> {
+  readonly mode: TMode
+  readonly [fieldGroupFieldSlotValueSymbol]: TValue
+}
+export type AnyFieldGroupFieldSlot = FieldGroupFieldSlot<any>
+export type StrictFieldGroupFieldSlot<TValue> = FieldGroupFieldSlot<
+  TValue,
+  'strict'
+>
+export type LooseFieldGroupFieldSlot<TValue> = FieldGroupFieldSlot<
+  TValue,
+  'loose'
+>
+export type FieldGroupFieldSlotValue<TSlot> =
+  TSlot extends FieldGroupFieldSlot<infer TValue> ? TValue : never
+export type FieldGroupFieldSlotModeOf<TSlot> =
+  TSlot extends FieldGroupFieldSlot<any, infer TMode> ? TMode : never
+
+type IsSame<TTypeA, TTypeB> = [TTypeA] extends [TTypeB]
+  ? [TTypeB] extends [TTypeA]
+    ? true
+    : false
+  : false
+
+export type FieldGroupFieldSlotAllows<TSlot, TValue> =
+  TSlot extends FieldGroupFieldSlot<infer TAcceptedValue, infer TMode>
+    ? TMode extends 'strict'
+      ? IsSame<TValue, TAcceptedValue>
+      : [TValue] extends [TAcceptedValue]
+        ? true
+        : false
+    : false
+
+export type FieldGroupFieldNameForSlot<
+  TFieldData,
+  TSlot extends AnyFieldGroupFieldSlot,
+> = {
+  [TFieldName in DeepKeys<TFieldData>]: FieldGroupFieldSlotAllows<
+    TSlot,
+    DeepValue<TFieldData, TFieldName>
+  > extends true
+    ? TFieldName
+    : never
+}[DeepKeys<TFieldData>]
+
+export type FieldGroupFields = Record<string, AnyFieldGroupFieldSlot>
+export type FieldGroupFieldNames<
+  TFieldData,
+  TFields extends FieldGroupFields,
+> = {
+  [TFieldName in keyof TFields]: FieldGroupFieldNameForSlot<
+    TFieldData,
+    TFields[TFieldName]
+  >
+}
+export type FieldGroupFieldData<TFields extends FieldGroupFields> = {
+  [
+    TFieldName in keyof TFields
+  ]: TFields[TFieldName] extends FieldGroupFieldSlot<infer TValue, any>
+    ? TValue
+    : never
+}
+export type FieldGroupFieldsOf<TFieldGroup> = TFieldGroup extends {
+  readonly [fieldGroupFieldsSymbol]: infer TFields
+}
+  ? TFields
+  : never
+
+export type VueFieldGroup<
+  TFields extends FieldGroupFields,
+  TFieldComponents extends Record<string, Component> = Record<never, never>,
+> = FieldGroupApi<FieldGroupFieldData<TFields>, TFieldComponents> & {
+  readonly [fieldGroupFieldsSymbol]: TFields
+}
+export type FieldGroupFieldComponentsOf<TFieldGroup> =
+  TFieldGroup extends VueFieldGroup<any, infer TFieldComponents>
+    ? TFieldComponents
+    : never
+export type FieldGroupForm<
+  TFieldComponents extends Record<string, Component> = Record<never, never>,
+  TFormData = any,
+> = FormApi<TFormData, any> &
+  VueTanStackFormComponents<TFormData, any, TFieldComponents>
+
+export type FieldGroupFieldBindingForSlot<
+  TFormData,
+  TSlot extends AnyFieldGroupFieldSlot,
+> =
+  TSlot extends FieldGroupFieldSlot<infer TValue, infer TMode>
+    ? TMode extends 'strict'
+      ? FieldGroupFieldNameForSlot<TFormData, TSlot>
+      : DeepKeysWhereValueIncludes<TFormData, TValue>
+    : never
+export type FieldGroupFieldBindings<
+  TFields extends FieldGroupFields,
+  TFormData = any,
+> = {
+  [TFieldName in keyof TFields]: FieldGroupFieldBindingForSlot<
+    TFormData,
+    TFields[TFieldName]
+  >
+}
+export type FieldGroupFieldBindingsOf<TFieldGroup, TFormData> =
+  FieldGroupFieldsOf<TFieldGroup> extends FieldGroupFields
+    ? FieldGroupFieldBindings<FieldGroupFieldsOf<TFieldGroup>, TFormData>
+    : never
+export type FieldGroupFieldsPropName<
+  TProps,
+  TFieldGroup extends VueFieldGroup<any, any>,
+> = {
+  [TPropName in keyof TProps]-?: IsSame<
+    TProps[TPropName],
+    TFieldGroup
+  > extends true
+    ? TPropName
+    : never
+}[keyof TProps]
+
+export type FieldGroupWithFieldsFn<
+  TFieldGroup extends VueFieldGroup<any, any>,
+> = <TProps extends object, const TFieldsPropName extends PropertyKey>(
+  component: Component & (new (props: TProps & PublicProps) => any),
+  fieldsPropName: TFieldsPropName &
+    FieldGroupFieldsPropName<TProps, TFieldGroup>,
+) => new <TFormData>(
+  props: Omit<TProps, TFieldsPropName | 'form'> & {
+    form: FieldGroupForm<FieldGroupFieldComponentsOf<TFieldGroup>, TFormData>
+  } & {
+    [TPropName in TFieldsPropName]: FieldGroupFieldBindingsOf<
+      TFieldGroup,
+      TFormData
+    >
+  } & PublicProps,
+) => VueComponentInstance<
+  Omit<TProps, TFieldsPropName | 'form'> & {
+    form: FieldGroupForm<FieldGroupFieldComponentsOf<TFieldGroup>, TFormData>
+  } & {
+    [TPropName in TFieldsPropName]: FieldGroupFieldBindingsOf<
+      TFieldGroup,
+      TFormData
+    >
+  } & Record<string, any>,
+  {}
+>
+
+export interface FieldGroupHelper {
+  strict: <TValue>() => StrictFieldGroupFieldSlot<TValue>
+  loose: <TValue>() => LooseFieldGroupFieldSlot<TValue>
+}
+
+export interface FieldGroupDefinition<
+  TFields extends FieldGroupFields,
+  TFieldComponents extends Record<string, Component>,
+> {
+  /** The virtual field-group API injected into the bound component. */
+  fields: VueFieldGroup<TFields, TFieldComponents>
+  /** Binds a component's virtual field API to concrete paths in a form. */
+  bindComponent: FieldGroupWithFieldsFn<
+    VueFieldGroup<TFields, TFieldComponents>
+  >
+}
+
+/** Signature shared by `defineFieldGroup` and app-form field-group definers. */
+export type DefineFieldGroupFn<
+  TFieldComponents extends Record<string, Component>,
+> = <const TFields extends FieldGroupFields>(
+  defineFn: (helper: FieldGroupHelper) => TFields,
+) => FieldGroupDefinition<TFields, TFieldComponents>
+
+/** Defines a reusable group of virtual fields. */
+export const defineFieldGroup: DefineFieldGroupFn<Record<never, never>> =
+  defineFieldGroupRuntime as never

package/src/Subscribe.public.ts

@@ -0,0 +1,46 @@
+import { shallow, useSelector } from '@tanstack/vue-store'
+import { defineComponent } from 'vue'
+import type {
+  Atom,
+  ReadonlyAtom,
+  ReadonlyStore,
+  Store,
+} from '@tanstack/vue-store'
+import type { VueComponentWithSlots } from './vueTypes.lib'
+
+export type SubscribeSource<TValue> =
+  Atom<TValue> | ReadonlyAtom<TValue> | Store<TValue> | ReadonlyStore<TValue>
+
+export interface SubscribeProps<in out TSourceData, in out TSelected> {
+  source: SubscribeSource<TSourceData>
+  selector: (state: TSourceData) => TSelected
+  when?: (selected: NoInfer<TSelected>) => boolean
+}
+
+export type SubscribeComponent = new <TSourceData, const TSelected>(
+  props: SubscribeProps<TSourceData, TSelected>,
+) => InstanceType<
+  VueComponentWithSlots<
+    SubscribeProps<TSourceData, TSelected>,
+    { default: NoInfer<TSelected> }
+  >
+>
+
+const SubscribeImpl = defineComponent<SubscribeProps<any, any>>(
+  (props, { slots }) => {
+    const selected = useSelector(props.source, props.selector, {
+      compare: shallow,
+    })
+
+    return () => {
+      if (props.when?.(selected.value) === false) return null
+      return slots.default?.(selected.value)
+    }
+  },
+  {
+    name: 'TanStackForm.Subscribe',
+    props: ['source', 'selector', 'when'],
+  },
+)
+
+export const Subscribe = SubscribeImpl as never as SubscribeComponent

package/src/VueForm/Components.lib.ts

@@ -0,0 +1,182 @@
+import { shallow, useSelector } from '@tanstack/vue-store'
+import { InternalFormGroupApi } from '@tanstack/form-core/internals'
+import {
+  defineComponent,
+  h,
+  onMounted,
+  onUnmounted,
+  provide,
+  watchEffect,
+} from 'vue'
+import { Subscribe } from '../Subscribe.public'
+import {
+  createArrayFieldSubscription,
+  createValueFieldSubscription,
+} from './fieldSubscriptions.lib'
+import { useField } from './useField.lib'
+import type { Component, InjectionKey, Slots } from 'vue'
+import type {
+  AnyFieldApiOptions,
+  AnyInternalFieldApi,
+  AnyInternalFormApi,
+  InternalFormGroupApi as InternalFormGroupApiType,
+} from '@tanstack/form-core/internals'
+import type { InternalVueFormApi } from './VueFormApi.lib'
+
+export function attachVueFormComponents(
+  form: AnyInternalFormApi,
+  fieldComponents: Record<string, Component> | null,
+  fieldContext?: InjectionKey<AnyInternalFieldApi>,
+): InternalVueFormApi {
+  const resultForm = form as InternalVueFormApi
+  resultForm.Field = createFieldComponent(
+    form,
+    fieldComponents,
+    false,
+    fieldContext,
+  ) as never
+  resultForm.ArrayField = createFieldComponent(
+    form,
+    fieldComponents,
+    true,
+    fieldContext,
+  ) as never
+  resultForm.Subscribe = createSubscribeComponent(form) as never
+  resultForm.FormGroup = createFormGroupComponent(resultForm) as never
+  return resultForm
+}
+
+function createFieldComponent(
+  form: AnyInternalFormApi,
+  fieldComponents: Record<string, Component> | null,
+  array: boolean,
+  fieldContext?: InjectionKey<AnyInternalFieldApi>,
+) {
+  return defineComponent(
+    (_props, context) => {
+      const options = () => ({ ...context.attrs, form }) as never
+      const fieldApi = useField(options, fieldComponents)
+      const selection = array
+        ? createArrayFieldSubscription(fieldApi)
+        : createValueFieldSubscription(fieldApi)
+
+      if (fieldContext) {
+        // Field APIs are stable for a mounted name. Supplying the current API
+        // mirrors Vue v1 composition components while the parent subscription
+        // handles state-driven renders.
+        provide(fieldContext, fieldApi.value)
+      }
+
+      return () => {
+        void selection.value
+        return context.slots.default?.({ field: fieldApi.value })
+      }
+    },
+    {
+      name: array ? 'TanStackForm.ArrayField' : 'TanStackForm.Field',
+      inheritAttrs: false,
+    },
+  )
+}
+
+function createSubscribeComponent(form: AnyInternalFormApi) {
+  return defineComponent(
+    (_props, context) => () =>
+      h(
+        Subscribe as never,
+        { ...context.attrs, source: form.atom } as never,
+        context.slots,
+      ),
+    {
+      name: 'TanStackForm.Subscribe',
+      inheritAttrs: false,
+    },
+  )
+}
+
+function createFormGroupComponent(form: InternalVueFormApi) {
+  return defineComponent(
+    (_props, context) => {
+      const options = () => ({ ...context.attrs, form })
+      const group = attachVueFormGroupComponents(
+        new InternalFormGroupApi(options() as never),
+        form,
+      )
+
+      watchEffect(() => group.update(options() as never))
+
+      let mounted = false
+      onMounted(() => {
+        mounted = true
+        group.mount()
+      })
+      onUnmounted(() => {
+        if (mounted) group._cleanup()
+      })
+
+      const state = useSelector(group.atom, (value) => value, {
+        compare: shallow,
+      })
+
+      return () => {
+        void state.value
+        return context.slots.default?.({ group })
+      }
+    },
+    {
+      name: 'TanStackForm.FormGroup',
+      inheritAttrs: false,
+    },
+  )
+}
+
+function forwardToField(
+  component: Component,
+  group: InternalFormGroupApiType<any, any, any, any, any>,
+) {
+  return defineComponent(
+    (_props, context) => () => {
+      const options = { ...context.attrs } as unknown as AnyFieldApiOptions
+      return h(
+        component,
+        group._getFormFieldOptions(options, (base, overrides) => ({
+          ...base,
+          ...overrides,
+        })) as never,
+        context.slots,
+      )
+    },
+    { inheritAttrs: false },
+  )
+}
+
+function attachVueFormGroupComponents(
+  group: InternalFormGroupApiType<any, any, any, any, any>,
+  form: InternalVueFormApi,
+) {
+  type GroupWithComponents = InternalFormGroupApiType<
+    any,
+    any,
+    any,
+    any,
+    any
+  > & {
+    Field: Component
+    ArrayField: Component
+    Subscribe: Component
+  }
+
+  const resultGroup = group as GroupWithComponents
+  resultGroup.Field = forwardToField(form.Field as never, group)
+  resultGroup.ArrayField = forwardToField(form.ArrayField as never, group)
+  resultGroup.Subscribe = defineComponent(
+    (_props, context) => () =>
+      h(
+        Subscribe as never,
+        { ...context.attrs, source: group.atom } as never,
+        context.slots as Slots,
+      ),
+    { name: 'TanStackForm.FormGroup.Subscribe', inheritAttrs: false },
+  )
+  return resultGroup
+}