docs: improve comment by adding example

src/lib/form/useWatchToTrigger/docs.stories.tsx

@@ -0,0 +1,134 @@
+import { Button, Stack } from '@chakra-ui/react';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+
+import {
+ Form,
+ FormField,
+ FormFieldController,
+ FormFieldLabel,
+} from '@/components/Form';
+import { getFieldPath } from '@/lib/form/getFieldPath';
+
+import { useWatchToTrigger } from '.';
+
+export default {
+ title: 'Hooks/useWatchToTrigger',
+};
+
+type FormType = z.infer<ReturnType<typeof formSchema>>;
+const formSchema = () =>
+ z
+ .object({ min: z.number(), default: z.number(), max: z.number() })
+ .superRefine((val, ctx) => {
+ if (val.min > val.default) {
+ ctx.addIssue({
+ code: 'custom',
+ path: getFieldPath<FormType>('min'),
+ message: 'The min should be <= to default',
+ });
+ }
+
+ if (val.default > val.max) {
+ ctx.addIssue({
+ code: 'custom',
+ path: getFieldPath<FormType>('default'),
+ message: 'The default should be <= to the max',
+ });
+ }
+ });
+
+export const WithoutHook = () => {
+ const form = useForm({
+ mode: 'onBlur',
+ resolver: zodResolver(formSchema()),
+ defaultValues: {
+ min: 2,
+ default: 4,
+ max: 6,
+ },
+ });
+
+ return (
+ <Form {...form}>
+ <Stack>
+ <FormField>
+ <FormFieldLabel>Min</FormFieldLabel>
+ <FormFieldController
+ control={form.control}
+ name="min"
+ type="number"
+ />
+ </FormField>
+ <FormField>
+ <FormFieldLabel>Default</FormFieldLabel>
+ <FormFieldController
+ control={form.control}
+ name="default"
+ type="number"
+ />
+ </FormField>
+ <FormField>
+ <FormFieldLabel>Max</FormFieldLabel>
+ <FormFieldController
+ control={form.control}
+ name="max"
+ type="number"
+ />
+ </FormField>
+ <Button type="submit" variant="@primary">
+ Submit
+ </Button>
+ </Stack>
+ </Form>
+ );
+};
+
+export const WithHook = () => {
+ const form = useForm({
+ mode: 'onBlur',
+ resolver: zodResolver(formSchema()),
+ defaultValues: {
+ min: 2,
+ default: 4,
+ max: 6,
+ },
+ });
+
+ useWatchToTrigger({ form, names: ['min', 'default', 'max'] });
+
+ return (
+ <Form {...form}>
+ <Stack>
+ <FormField>
+ <FormFieldLabel>Min</FormFieldLabel>
+ <FormFieldController
+ control={form.control}
+ name="min"
+ type="number"
+ />
+ </FormField>
+ <FormField>
+ <FormFieldLabel>Default</FormFieldLabel>
+ <FormFieldController
+ control={form.control}
+ name="default"
+ type="number"
+ />
+ </FormField>
+ <FormField>
+ <FormFieldLabel>Max</FormFieldLabel>
+ <FormFieldController
+ control={form.control}
+ name="max"
+ type="number"
+ />
+ </FormField>
+ <Button type="submit" variant="@primary">
+ Submit
+ </Button>
+ </Stack>
+ </Form>
+ );
+};

src/lib/form/useWatchToTrigger.ts → src/lib/form/useWatchToTrigger/index.ts

@@ -16,7 +16,17 @@ import { FieldPath, FieldValues, UseFormReturn } from 'react-hook-form';
  * You update the `min` so the value is 5, the form (using superRefine and
  * custom issues) will tell you that the `min` should be lower than the default.
  * You update the `default` so the new value is 5.5. Without this hook, the
- * field `min` will not revalidate. With this hook, if you gave the name, it will.
+ * field `min` will not revalidate. With this hook, if you give the field name,
+ * it will.
+ *
+ * @example
+ * // Get the form
+ * const form = useFormContext<FormType>();
+ *
+ * // Subscribe to fields validation
+ * // If `default` changes, `min`, `default` and `max` will validate and trigger
+ * // error if any.
+ * useWatchToTrigger({ form, names: ['min', 'default', 'max']})
  */
 export const useWatchToTrigger = <
  TFieldValues extends FieldValues = FieldValues,