chore: more code comment docs in type output

packages/core/src/useForm/useForm.ts

@@ -17,7 +17,7 @@ import {
 } from '../types';
 import { createFormContext, BaseFormContext } from './formContext';
 import { FormTransactionManager, useFormTransactions } from './useFormTransactions';
-import { useFormActions } from './useFormActions';
+import { FormActions, useFormActions } from './useFormActions';
 import { useFormSnapshots } from './formSnapshot';
 import { findLeaf } from '../utils/path';
 import { getConfig } from '../config';
@@ -26,7 +26,7 @@ import { appendToFormData, clearFormData } from '../utils/formData';
 import { PartialDeep } from 'type-fest';
 import { createDisabledContext } from '../helpers/createDisabledContext';
 
-export interface FormOptions<TSchema extends GenericFormSchema, TInput extends FormObject = v1.InferInput<TSchema>> {
+export interface FormProps<TSchema extends GenericFormSchema, TInput extends FormObject = v1.InferInput<TSchema>> {
   /**
    * The form's unique identifier.
    */
@@ -81,16 +81,16 @@ export function useForm<
   TSchema extends GenericFormSchema,
   TInput extends FormObject = v1.InferInput<TSchema>,
   TOutput extends FormObject = v1.InferOutput<TSchema>,
->(opts?: Partial<FormOptions<TSchema, TInput>>) {
-  const touchedSnapshot = useFormSnapshots(opts?.initialTouched);
-  const valuesSnapshot = useFormSnapshots<TInput, TOutput>(opts?.initialValues, {
+>(props?: Partial<FormProps<TSchema, TInput>>) {
+  const touchedSnapshot = useFormSnapshots(props?.initialTouched);
+  const valuesSnapshot = useFormSnapshots<TInput, TOutput>(props?.initialValues, {
     onAsyncInit,
-    schema: opts?.schema as StandardSchema<TInput, TOutput>,
+    schema: props?.schema as StandardSchema<TInput, TOutput>,
   });
 
-  const id = opts?.id || useUniqId(FieldTypePrefixes.Form);
-  const isDisabled = createDisabledContext(opts?.disabled);
-  const isHtmlValidationDisabled = () => opts?.disableHtmlValidation ?? getConfig().disableHtmlValidation;
+  const id = props?.id || useUniqId(FieldTypePrefixes.Form);
+  const isDisabled = createDisabledContext(props?.disabled);
+  const isHtmlValidationDisabled = () => props?.disableHtmlValidation ?? getConfig().disableHtmlValidation;
   const values = reactive(cloneDeep(valuesSnapshot.originals.value)) as PartialDeep<TInput>;
   const touched = reactive(cloneDeep(touchedSnapshot.originals.value)) as TouchedSchema<TInput>;
   const disabled = {} as DisabledSchema<TInput>;
@@ -101,7 +101,7 @@ export function useForm<
     values: values as TInput,
     touched,
     disabled,
-    schema: opts?.schema as StandardSchema<TInput, TOutput>,
+    schema: props?.schema as StandardSchema<TInput, TOutput>,
     errors,
     snapshots: {
       values: valuesSnapshot,
@@ -128,7 +128,7 @@ export function useForm<
   const transactionsManager = useFormTransactions(ctx);
   const { actions, isSubmitting, ...privateActions } = useFormActions<TInput, TOutput>(ctx, {
     disabled,
-    schema: opts?.schema as StandardSchema<TInput, TOutput>,
+    schema: props?.schema as StandardSchema<TInput, TOutput>,
   });
 
   function getErrors() {
@@ -174,11 +174,15 @@ export function useForm<
     onFormdata,
   };
 
-  return {
+  const baseReturns = {
     /**
      * The current values of the form.
      */
     values: readonly(values),
+    /**
+     * The form context object, for internal use.
+     * @private
+     */
     context: ctx,
     /**
      * Whether the form is submitting.
@@ -244,6 +248,10 @@ export function useForm<
      * Props for the form element.
      */
     formProps,
-    ...actions,
   };
+
+  return {
+    ...baseReturns,
+    ...actions,
+  } as typeof baseReturns & FormActions<TInput, TOutput>;
 }

packages/core/src/useForm/useFormActions.ts

@@ -38,6 +38,29 @@ export interface SubmitContext {
   event?: Event | SubmitEvent;
 }
 
+export interface FormActions<TForm extends FormObject, TOutput extends FormObject> {
+  /**
+   * Creates a submit handler for the form.
+   * @example
+   * ```ts
+   * const onSubmit = actions.handleSubmit((data, { form }) => {
+   *   console.log(data.toObject(), form);
+   * });
+   * ```
+   */
+  handleSubmit: (
+    onSuccess: (payload: ConsumableData<TOutput>, ctx: SubmitContext) => MaybeAsync<unknown>,
+  ) => (e?: Event) => Promise<unknown>;
+  /**
+   * Resets the form to its initial state.
+   */
+  reset: (state?: Partial<ResetState<TForm>>, opts?: SetValueOptions) => Promise<void>;
+  /**
+   * Validates the form.
+   */
+  validate: () => Promise<FormValidationResult<TOutput>>;
+}
+
 export function useFormActions<TForm extends FormObject = FormObject, TOutput extends FormObject = TForm>(
   form: BaseFormContext<TForm>,
   { disabled, schema }: FormActionsOptions<TForm, TOutput>,
@@ -128,12 +151,14 @@ export function useFormActions<TForm extends FormObject = FormObject, TOutput ex
     return Promise.resolve();
   }
 
+  const actions: FormActions<TForm, TOutput> = {
+    handleSubmit,
+    reset,
+    validate,
+  };
+
   return {
-    actions: {
-      handleSubmit,
-      reset,
-      validate,
-    },
+    actions,
     requestValidation,
     onSubmitAttempt,
     onValidationDispatch,

packages/core/src/useFormRepeater/useFormRepeater.ts

@@ -1,9 +1,10 @@
 import {
   computed,
+  type DefineComponent,
   defineComponent,
   h,
   inject,
-  MaybeRefOrGetter,
+  type MaybeRefOrGetter,
   nextTick,
   onMounted,
   readonly,
@@ -27,7 +28,6 @@ import {
 import { FieldTypePrefixes } from '../constants';
 import { createPathPrefixer } from '../helpers/usePathPrefixer';
 import { prefixPath } from '../utils/path';
-import { Simplify } from 'type-fest';
 
 export interface FormRepeaterProps {
   /**
@@ -81,12 +81,32 @@ export interface FormRepeaterButtonDomProps {
   onClick: () => void;
 }
 
-export interface FormRepeaterIterationSlotProps {
+export interface FormRepeaterIterationProps {
+  /**
+   * The index of the current repeated item. This is required.
+   */
   index: number;
-  path: string;
-  key: string;
+
+  /**
+   * The tag name to render the iteration as.
+   */
+  as?: string;
+}
+
+export interface FormRepeaterIterationSlotProps {
+  /**
+   * Props for the move item down button.
+   */
   moveDownButtonProps: FormRepeaterButtonDomProps;
+
+  /**
+   * Props for the move item up button.
+   */
   moveUpButtonProps: FormRepeaterButtonDomProps;
+
+  /**
+   * Props for the remove item button.
+   */
   removeButtonProps: FormRepeaterButtonDomProps;
 }
 
@@ -309,10 +329,13 @@ export function useFormRepeater<TItem = unknown>(_props: Reactivify<FormRepeater
     remove,
     move,
     insert,
-    Iteration: Iteration as typeof Iteration & {
+    /**
+     * The iteration component. You should use this component to wrap each repeated item.
+     */
+    Iteration: Iteration as DefineComponent<FormRepeaterIterationProps> & {
       new (): {
         $slots: {
-          default: (args: Simplify<Omit<FormRepeaterIterationSlotProps, 'index' | 'path' | 'key'>>) => VNode[];
+          default: (args: FormRepeaterIterationSlotProps) => VNode[];
         };
       };
     },

packages/core/src/useSlider/useSlider.ts

@@ -1,4 +1,13 @@
-import { type CSSProperties, type InjectionKey, computed, onBeforeUnmount, provide, ref, toValue } from 'vue';
+import {
+  type CSSProperties,
+  ComputedRef,
+  type InjectionKey,
+  computed,
+  onBeforeUnmount,
+  provide,
+  ref,
+  toValue,
+} from 'vue';
 import { useLabel } from '../a11y/useLabel';
 import { AriaLabelableProps, Arrayable, Direction, Numberish, Orientation, Reactivify, StandardSchema } from '../types';
 import {
@@ -99,6 +108,37 @@ export interface ValueRange {
   max: number;
 }
 
+interface ThumbMetadata {
+  /**
+   * The current value of the thumb.
+   */
+  value: number;
+  /**
+   * The percent of the slider that the thumb is at.
+   */
+  percent: number;
+  /**
+   * The minimum value of the slider.
+   */
+  min: number;
+  /**
+   * The maximum value of the slider.
+   */
+  max: number;
+  /**
+   * The percent of the slider that the thumb is at.
+   */
+  sliderPercent: number;
+  /**
+   * The minimum value of the slider.
+   */
+  sliderMin: number;
+  /**
+   * The maximum value of the slider.
+   */
+  sliderMax: number;
+}
+
 export interface SliderRegistration<TValue = number> {
   /**
    * Gets the available range of values for the thumb that this registration is associated with.
@@ -410,7 +450,7 @@ export function useSlider<TValue>(_props: Reactivify<SliderProps<TValue>, 'schem
   /**
    * Gets the metadata for a given thumb.
    */
-  function useThumbMetadata(idx: number) {
+  function useThumbMetadata(idx: number): ComputedRef<ThumbMetadata> {
     return computed(() => {
       const value = getThumbValue(idx);
       if (isNullOrUndefined(value)) {
@@ -430,35 +470,14 @@ export function useSlider<TValue>(_props: Reactivify<SliderProps<TValue>, 'schem
       const percent = (value - min) / (max - min);
 
       return {
-        /**
-         * The current value of the thumb.
-         */
         value,
-        /**
-         * The percent of the slider that the thumb is at.
-         */
         percent,
-        /**
-         * The minimum value of the slider.
-         */
         min,
-        /**
-         * The maximum value of the slider.
-         */
         max,
-        /**
-         * The percent of the slider that the thumb is at.
-         */
         sliderPercent: absolutePercent,
-        /**
-         * The minimum value of the slider.
-         */
         sliderMin: absoluteMin,
-        /**
-         * The maximum value of the slider.
-         */
         sliderMax: absoluteMax,
-      };
+      } satisfies ThumbMetadata;
     });
   }