From 3a3fc988971874b0500c47d8411db5ef05f9c1c4 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 25 Nov 2024 00:56:38 +0200 Subject: [PATCH] chore: more code comment docs in type output --- packages/core/src/useForm/useForm.ts | 34 ++++++---- packages/core/src/useForm/useFormActions.ts | 35 ++++++++-- .../src/useFormRepeater/useFormRepeater.ts | 37 ++++++++-- packages/core/src/useSlider/useSlider.ts | 67 ++++++++++++------- 4 files changed, 124 insertions(+), 49 deletions(-) diff --git a/packages/core/src/useForm/useForm.ts b/packages/core/src/useForm/useForm.ts index 6042822..cf651e0 100644 --- a/packages/core/src/useForm/useForm.ts +++ b/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> { +export interface FormProps> { /** * The form's unique identifier. */ @@ -81,16 +81,16 @@ export function useForm< TSchema extends GenericFormSchema, TInput extends FormObject = v1.InferInput, TOutput extends FormObject = v1.InferOutput, ->(opts?: Partial>) { - const touchedSnapshot = useFormSnapshots(opts?.initialTouched); - const valuesSnapshot = useFormSnapshots(opts?.initialValues, { +>(props?: Partial>) { + const touchedSnapshot = useFormSnapshots(props?.initialTouched); + const valuesSnapshot = useFormSnapshots(props?.initialValues, { onAsyncInit, - schema: opts?.schema as StandardSchema, + schema: props?.schema as StandardSchema, }); - 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; const touched = reactive(cloneDeep(touchedSnapshot.originals.value)) as TouchedSchema; const disabled = {} as DisabledSchema; @@ -101,7 +101,7 @@ export function useForm< values: values as TInput, touched, disabled, - schema: opts?.schema as StandardSchema, + schema: props?.schema as StandardSchema, errors, snapshots: { values: valuesSnapshot, @@ -128,7 +128,7 @@ export function useForm< const transactionsManager = useFormTransactions(ctx); const { actions, isSubmitting, ...privateActions } = useFormActions(ctx, { disabled, - schema: opts?.schema as StandardSchema, + schema: props?.schema as StandardSchema, }); 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; } diff --git a/packages/core/src/useForm/useFormActions.ts b/packages/core/src/useForm/useFormActions.ts index 3a822a2..2afa802 100644 --- a/packages/core/src/useForm/useFormActions.ts +++ b/packages/core/src/useForm/useFormActions.ts @@ -38,6 +38,29 @@ export interface SubmitContext { event?: Event | SubmitEvent; } +export interface FormActions { + /** + * Creates a submit handler for the form. + * @example + * ```ts + * const onSubmit = actions.handleSubmit((data, { form }) => { + * console.log(data.toObject(), form); + * }); + * ``` + */ + handleSubmit: ( + onSuccess: (payload: ConsumableData, ctx: SubmitContext) => MaybeAsync, + ) => (e?: Event) => Promise; + /** + * Resets the form to its initial state. + */ + reset: (state?: Partial>, opts?: SetValueOptions) => Promise; + /** + * Validates the form. + */ + validate: () => Promise>; +} + export function useFormActions( form: BaseFormContext, { disabled, schema }: FormActionsOptions, @@ -128,12 +151,14 @@ export function useFormActions = { + handleSubmit, + reset, + validate, + }; + return { - actions: { - handleSubmit, - reset, - validate, - }, + actions, requestValidation, onSubmitAttempt, onValidationDispatch, diff --git a/packages/core/src/useFormRepeater/useFormRepeater.ts b/packages/core/src/useFormRepeater/useFormRepeater.ts index f4577f9..7dcca7f 100644 --- a/packages/core/src/useFormRepeater/useFormRepeater.ts +++ b/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(_props: Reactivify & { new (): { $slots: { - default: (args: Simplify>) => VNode[]; + default: (args: FormRepeaterIterationSlotProps) => VNode[]; }; }; }, diff --git a/packages/core/src/useSlider/useSlider.ts b/packages/core/src/useSlider/useSlider.ts index 3f20051..a3fe113 100644 --- a/packages/core/src/useSlider/useSlider.ts +++ b/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 { /** * Gets the available range of values for the thumb that this registration is associated with. @@ -410,7 +450,7 @@ export function useSlider(_props: Reactivify, 'schem /** * Gets the metadata for a given thumb. */ - function useThumbMetadata(idx: number) { + function useThumbMetadata(idx: number): ComputedRef { return computed(() => { const value = getThumbValue(idx); if (isNullOrUndefined(value)) { @@ -430,35 +470,14 @@ export function useSlider(_props: Reactivify, '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; }); }