rh-form-base

rh-form-base egy kisméretű, újrafelhasználható alapcsomag, ami React Hook Form-mal és Zod validációval segít gyorsan űrlapokat építeni.

Két fő API-t ad:

• useRHForm(...): létrehozza a useForm-ot Zod resolverrel, és egységes “submit handler” visszaadással segít.
• RHForm(...): egy kényelmi komponens, ami FormProvider-rel átfogja az űrlapot, és render-prop vagy children mintával jeleníti meg a tartalmat.

Mire jó?

Ha több formot is építesz ugyanazzal a mintával (Zod schema + React Hook Form + hibakezelés + egységes submit), ez a csomag segít:

• csökkenteni a duplikációt (resolver, defaultValues, submit handler összerakása),
• egységesíteni a form inicializálást,
• egyszerűen render-prop/pattern-t használni az űrlapon belül,
• tipizált (generics) felületet adni a schema->form values kapcsolat miatt.

Követelmények (peer dependencies)

A csomag peer dependency-ként várja a következőket:

• react (>= 18)
• react-dom (>= 18)
• react-hook-form (>= 7)
• zod (>= 3)
• @hookform/resolvers (>= 5)

Fejlesztői dependency-k külön kerülnek telepítésre a csomagban, de futáskor a host app biztosítja őket.

Telepítés

Ha monorepo-ban használod (pl. workspace), akkor tipikusan:

npm i @repo/rh-form-base

Ha nem publikus csomag, akkor a saját workspace workflow-d szerint illeszd (pl. pnpm -r / yarn workspaces).

Gyorsindító példa (Zod + RHF + useRHForm)

1) Schema

import { z } from 'zod';

export const userSchema = z.object({
  email: z.string().email(),
  age: z.number().int().min(0).optional(),
});

2) Komponens

import { zodResolver } from '@hookform/resolvers/zod'; // csak ha külön akarod, a hook kezeli
import { useRHForm, RHForm } from '@repo/rh-form-base';
import type { SubmitHandler } from 'react-hook-form';
import { z } from 'zod';
import { Controller } from 'react-hook-form';

import { userSchema } from './schema';

type UserValues = z.infer<typeof userSchema>;

function MyForm() {
  const { form, submitHandler } = useRHForm({
    validationSchema: userSchema,
    defaultValues: { email: '', age: undefined },
    onSubmit: async (data) => {
      console.log('submitted', data);
    },
    onError: (errors) => {
      // errors: FieldErrors<UserValues>
      console.log('validation errors', errors);
    },
    // formOptions: {...} // opcionális, ld. lejjebb
  });

  return (
    <RHForm form={form} submitHandler={submitHandler} formProps={{}}>
      {/* példaként: csak egy mező */}
      <input {...form.register('email')} placeholder="email" />
      <button type="submit">Mentés</button>
    </RHForm>
  );
}

Megjegyzés:

• a useRHForm belül beállítja a resolver-t a Zod schema alapján,
• submitHandler már az onSubmit + opcionális onError összerakott handleSubmit-ből származik,
• a RHForm körbefogja a FormProvider-rel az űrlapot, így a child komponensek gond nélkül tudják használni pl. a useFormContext()-et.

API referencia

useRHForm(...)

Implements: React Hook Form useForm + Zod resolver + egységes submit handler.

Signature (tippek alapján):

useRHForm({
  validationSchema,
  inputSchema?,
  defaultValues,
  onSubmit,
  onError?,
  formOptions?,
})

Paraméterek

validationSchema (kötelező)

• Típus: ZodTypeAny
• A csomag ettől vezeti le a form value típusokat (a generics révén).

inputSchema (opcionális)

• Alapértelmezés: validationSchema
• Hasznos, ha a “típus” és a “validáció” eltérő schema-ból jön (ritkább eset).

defaultValues (kötelező)

• A form mezők kezdő értékei.
• A generics alapján a schema infóból ( z.infer ) származik.

onSubmit (kötelező)

• Függvény, amit a form validáció után hív.
• Típus: (data) => void | Promise<void>

onError (opcionális)

• Olyan hiba-állapotok esetén hívódik, amikor a validáció elbukik.
• Típus: (errors) => void
• errors típusa: FieldErrors<TFormValues>

formOptions (opcionális)

• A host app useForm opcióinak egy részhalmaza, kivéve a resolver-t (mert azt a csomag állítja be).
• Típus: Omit<UseFormProps<TFormValues>, 'resolver'>

Visszatérés

{
  form: UseFormReturn<TDefaultValues>,
  submitHandler: TOnSubmitFn
}

• form: az useForm által adott objektum, benne a register, control, watch, stb.
• submitHandler: tipikusan ezt adod át a RHForm-nak (vagy közvetlenül a <form onSubmit={...} />-nek).

RHForm(...)

Kérem a komponens mintáját: egyszerű “űrlap wrapper”, ami:

• FormProvider-rel beburkolja a form contextet,
• megjeleníti az űrlap <form> tag-et submitHandler-rel,
• a tartalmat children vagy render prop segítségével adja vissza.

Signature (tipizálva):

RHForm({
  form,
  submitHandler,
  render?,
  children?,
  formProps?,
})

form (kötelező)

• Típus: UseFormReturn<TFieldValues>
• A useRHForm().form-ból jön.

submitHandler (kötelező)

• Típus: SubmitEventHandler
• A useRHForm().submitHandler-ből jön.

formProps (opcionális)

• Extra props a <form> elemhez.
• Nem tartalmazhatja a onSubmit-et és a children-t (mert azokat a komponens kezeli).

Children minta

<RHForm form={form} submitHandler={submitHandler}>
  <input {...form.register('email')} />
  <button type="submit">OK</button>
</RHForm>

Render prop minta (hasznos, ha több “layout”/feltételes belső van)

<RHForm
  form={form}
  submitHandler={submitHandler}
  render={(form) => (
    <>
      <input {...form.register('email')} />
      <button type="submit">OK</button>
    </>
  )}
/>

Hibakezelés minták

1) onError (Zod/RHF validációs hibák)

A useRHForm-ban az onError segítségével központosíthatod a validációs hibák feldolgozását.

const { form, submitHandler } = useRHForm({
  validationSchema: userSchema,
  defaultValues: { email: '', age: undefined },
  onSubmit: () => {},
  onError: (errors) => {
    // pl. toast / log / fókusz
    console.log(errors.email);
  },
});

2) Mezőszintű hibák megjelenítése

A form.formState.errors elérhető a form objektumból.

const emailError = form.formState.errors.email;

return (
  <RHForm form={form} submitHandler={submitHandler}>
    <input {...form.register('email')} />
    {emailError ? <p>{emailError.message}</p> : null}
    <button type="submit">Mentés</button>
  </RHForm>
);

Advanced: eltérő inputSchema használata

Ritkább esetben van, amikor a “form values” típusa a validationSchema-ból kell, miközben a resolver egy másik inputSchema-t használ.

Alap: inputSchema ha nincs megadva, akkor validationSchema lesz.

const { form, submitHandler } = useRHForm({
  validationSchema: outputSchema,
  inputSchema: inputSchema,
  defaultValues,
  onSubmit,
});

Build / kimenet (dist) és modul formátum

A csomag tsup-pal build-el:

• format: ['esm', 'cjs']
• dts: true (generált .d.ts)
• outDir: dist

Az exports mező miatt a fogyasztónak tipikusan elég az import:

import { useRHForm, RHForm } from '@repo/rh-form-base';

CommonJS környezetben:

const { useRHForm, RHForm } = require('@repo/rh-form-base');

Fejlesztés a repo-ban

Elérhető script-ek:

• npm run build: tsup build
• npm run prepare: build futtatása install során
• npm run type-check: tsc --noEmit
• npm run lint: eslint .
• npm run lint:fix: eslint . --fix

Licenc

ISC