Seriya: React Hook Form Dars 79

Wizard Form Architecture — Murakkab step-based form arxitekturasi

Modulli wizard arxitekturasi, FormProvider va useFormContext, bosqich konfiguratsiyasi (stepConfig), shartli validatsiya va draft saqlash.

79-dars

Wizard Form Architecture — Murakkab step-based form arxitekturasi

Oldingi 78-darsda biz ko'p bosqichli formalarning bazaviy mantig'i bilan tanishdik. Biroq real korporativ loyihalarda (masalan: SaaS Onboarding, Bank/Kredit arizalari, Elektron tijorat checkout tizimlari) bosqichlar soni 5-10 tagacha yetishi, har bir qadam murakkab UI bloklarini o'z ichiga olishi va foydalanuvchining avvalgi tanloviga qarab keyingi qadamlar dinamik o'zgarishi mumkin.

Bunday paytda barcha kodni bitta ulkan faylga jamlash arxitekturaviy xatodir. Wizard Form Architecture — bu loyihani modulli, testlash oson va kengaytiriladigan qilib qurish tizimidir.


1. Korporativ Wizard tuzilmasi

Katta tizimlarda features/onboarding-wizard papkasi quyidagi mantiqiy qismlarga bo'linadi:

graph TD
  A["OnboardingWizard (Wizard Shell)"] --> B["FormProvider (useForm)"]
  B --> C["Step Config (WIZARD_STEPS)"]
  B --> D1["WorkspaceStep (useFormContext)"]
  B --> D2["DetailsStep (useFormContext)"]
  B --> D3["ReviewStep (useFormContext)"]
  C -->|getFieldsToValidate| E["Markazlashgan trigger() tekshiruvi"]
  1. Schema & Types: Formaning umumiy interfeysi va bosqichlar identifikatorlari.
  2. Step Definitions (stepConfig): Har bir bosqichning sarlavhasi, identifikatori va aynan qaysi maydonlarni tekshirishi kerakligini aniqlovchi funksiya (getFieldsToValidate).
  3. Wizard Shell (FormProvider): Yuqori darajadagi ota qobiq. U formani boshqaradi, progress barni chizadi va handleNextStep paytida markazlashgan konfiguratsiyadan foydalanib trigger() chaqiradi.
  4. Mustaqil Step Komponentlari: Har bir bosqich o'zining shaxsiy faylida yashaydi va ota komponentdan keraksiz proplar olmay, to'g'ridan-to'g'ri useFormContext() orqali ishlaydi.

2. Real misol: SaaS Workspace Onboarding Wizard

Quyidagi misolda Workspace ochish jarayoni keltirilgan. DetailsStep bosqichida validatsiya qilinadigan maydonlar foydalanuvchi tanlagan tarifga (plan === "team") qarab dinamik o'zgaradi:

import React, { useState } from "react";
import {
  FormProvider,
  useForm,
  useFormContext,
  type Path,
  type SubmitHandler,
} from "react-hook-form";

// 1. Tiplar
type AccountPlan = "starter" | "team";

type WizardFormValues = {
  workspaceName: string;
  plan: AccountPlan;
  teamSize: string;
  ownerEmail: string;
  acceptPolicy: boolean;
};

type StepId = "workspace" | "details" | "review";

type StepDefinition = {
  id: StepId;
  title: string;
  getFieldsToValidate: (values: WizardFormValues) => Path<WizardFormValues>[];
};

// 2. Markazlashgan bosqichlar konfiguratsiyasi
const WIZARD_STEPS: StepDefinition[] = [
  {
    id: "workspace",
    title: "Workspace va tarif",
    getFieldsToValidate: () => ["workspaceName", "plan"],
  },
  {
    id: "details",
    title: "Qo'shimcha tafsilotlar",
    // SHARTLI VALIDATSIYA: Agar tarif "team" bo'lsa teamSize ham tekshiriladi
    getFieldsToValidate: (values) =>
      values.plan === "team" ? ["teamSize", "ownerEmail"] : ["ownerEmail"],
  },
  {
    id: "review",
    title: "Tasdiqlash va ishga tushirish",
    getFieldsToValidate: () => ["acceptPolicy"],
  },
];

// 3. QADAM 1: Workspace va Tarif komponenti
function WorkspaceStep() {
  const {
    register,
    formState: { errors },
  } = useFormContext<WizardFormValues>();

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "14px" }}>
      <div>
        <label htmlFor="workspaceName" style={{ display: "block", fontWeight: 600, marginBottom: "4px" }}>
          Workspace nomi *
        </label>
        <input
          id="workspaceName"
          {...register("workspaceName", {
            required: "Workspace nomi kiritilishi shart",
          })}
          placeholder="Masalan: Hanafi Workspace"
          style={{ width: "100%", padding: "8px", boxSizing: "border-box" }}
          aria-invalid={Boolean(errors.workspaceName)}
        />
        {errors.workspaceName && (
          <p role="alert" style={{ color: "#e11d48", fontSize: "12px", marginTop: "4px" }}>
            {errors.workspaceName.message}
          </p>
        )}
      </div>

      <div>
        <label htmlFor="plan" style={{ display: "block", fontWeight: 600, marginBottom: "4px" }}>
          Tarif rejasi *
        </label>
        <select id="plan" {...register("plan")} style={{ width: "100%", padding: "8px" }}>
          <option value="starter">Starter (Yakka tartibda / 1 foydalanuvchi)</option>
          <option value="team">Team (Jamoaviy boshqaruv)</option>
        </select>
      </div>
    </div>
  );
}

// 4. QADAM 2: Tafsilotlar komponenti (Shartli input bilan)
function DetailsStep() {
  const {
    register,
    watch,
    formState: { errors },
  } = useFormContext<WizardFormValues>();

  const plan = watch("plan");

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "14px" }}>
      {plan === "team" && (
        <div style={{ padding: "10px", background: "#f0fdf4", border: "1px solid #bbf7d0", borderRadius: "6px" }}>
          <label htmlFor="teamSize" style={{ display: "block", fontWeight: 600, marginBottom: "4px" }}>
            Jamoa a'zolari kutilayotgan soni *
          </label>
          <input
            id="teamSize"
            type="number"
            {...register("teamSize", {
              required: plan === "team" ? "A'zolar sonini kiriting" : false,
              min: { value: 2, message: "Jamoa tarifi uchun kamida 2 kishi kerak" },
            })}
            placeholder="Masalan: 5"
            style={{ width: "100%", padding: "8px", boxSizing: "border-box" }}
            aria-invalid={Boolean(errors.teamSize)}
          />
          {errors.teamSize && (
            <p role="alert" style={{ color: "#e11d48", fontSize: "12px", marginTop: "4px" }}>
              {errors.teamSize.message}
            </p>
          )}
        </div>
      )}

      <div>
        <label htmlFor="ownerEmail" style={{ display: "block", fontWeight: 600, marginBottom: "4px" }}>
          Mas'ul rahbar elektron pochtasi *
        </label>
        <input
          id="ownerEmail"
          type="email"
          {...register("ownerEmail", {
            required: "Mas'ul email kiritilishi shart",
            pattern: {
              value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
              message: "Email formati noto'g'ri",
            },
          })}
          placeholder="[email protected]"
          style={{ width: "100%", padding: "8px", boxSizing: "border-box" }}
          aria-invalid={Boolean(errors.ownerEmail)}
        />
        {errors.ownerEmail && (
          <p role="alert" style={{ color: "#e11d48", fontSize: "12px", marginTop: "4px" }}>
            {errors.ownerEmail.message}
          </p>
        )}
      </div>
    </div>
  );
}

// 5. QADAM 3: Xulosa va Maxfiylik siyosati
function ReviewStep() {
  const {
    register,
    getValues,
    formState: { errors },
  } = useFormContext<WizardFormValues>();

  const values = getValues();

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "14px" }}>
      <div
        style={{
          padding: "12px",
          background: "#f8fafc",
          borderRadius: "6px",
          border: "1px solid #cbd5e1",
          fontSize: "13px",
          lineHeight: "1.6",
        }}
      >
        <h4 style={{ margin: "0 0 6px 0", fontSize: "14px" }}>Yaratilayotgan parametrlar xulosasi:</h4>
        <p style={{ margin: 0 }}><strong>Workspace nomi:</strong> {values.workspaceName}</p>
        <p style={{ margin: 0 }}><strong>Tanlangan tarif:</strong> {values.plan.toUpperCase()}</p>
        {values.plan === "team" && (
          <p style={{ margin: 0 }}><strong>Kutilayotgan jamoa:</strong> {values.teamSize} kishi</p>
        )}
        <p style={{ margin: 0 }}><strong>Admin email:</strong> {values.ownerEmail}</p>
      </div>

      <div>
        <label style={{ display: "flex", alignItems: "center", gap: "8px", cursor: "pointer", fontSize: "13px" }}>
          <input
            type="checkbox"
            {...register("acceptPolicy", {
              required: "Davom etish uchun maxfiylik siyosatiga rozilik bering",
            })}
          />
          Foydalanish shartlari va maxfiylik qoidalariga to'liq roziman
        </label>
        {errors.acceptPolicy && (
          <p role="alert" style={{ color: "#e11d48", fontSize: "12px", marginTop: "4px" }}>
            {errors.acceptPolicy.message}
          </p>
        )}
      </div>
    </div>
  );
}

// 6. ASOSIY QOBIQ: OnboardingWizard
export function OnboardingWizard() {
  const [stepIndex, setStepIndex] = useState<number>(0);

  const methods = useForm<WizardFormValues>({
    mode: "onTouched",
    defaultValues: {
      workspaceName: "",
      plan: "starter",
      teamSize: "2",
      ownerEmail: "",
      acceptPolicy: false,
    },
  });

  const { handleSubmit, trigger, getValues, reset } = methods;
  const currentStep = WIZARD_STEPS[stepIndex];
  const isLastStep = stepIndex === WIZARD_STEPS.length - 1;

  // Markazlashgan tekshiruv va keyingi bosqichga o'tish
  const handleNextStep = async () => {
    // Joriy qadamga mos maydonlar ro'yxatini olamiz
    const fieldsToCheck = currentStep.getFieldsToValidate(getValues());
    const isValid = await trigger(fieldsToCheck);

    if (isValid && !isLastStep) {
      setStepIndex((prev) => prev + 1);
    }
  };

  const handlePrevStep = () => {
    setStepIndex((prev) => Math.max(0, prev - 1));
  };

  const onSubmit: SubmitHandler<WizardFormValues> = async (data) => {
    await new Promise((resolve) => setTimeout(resolve, 400));
    console.log("Wizard muvaffaqiyatli topshirildi:", data);
    alert(`Workspace "${data.workspaceName}" muvaffaqiyatli ishga tushirildi!`);
    reset();
    setStepIndex(0);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={handleSubmit(onSubmit)} noValidate style={{ maxWidth: "540px" }}>
        {/* Bosqichlar indikatori */}
        <div style={{ marginBottom: "20px" }}>
          <div style={{ display: "flex", gap: "8px", marginBottom: "8px" }}>
            {WIZARD_STEPS.map((step, idx) => (
              <div
                key={step.id}
                style={{
                  flex: 1,
                  height: "4px",
                  borderRadius: "2px",
                  background: idx <= stepIndex ? "#2563eb" : "#e2e8f0",
                }}
              />
            ))}
          </div>

          <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}>
            <span style={{ fontSize: "12px", color: "#64748b", fontWeight: 500 }}>
              Qadam {stepIndex + 1} / {WIZARD_STEPS.length}
            </span>
            <span style={{ fontSize: "14px", fontWeight: 700, color: "#1e293b" }}>
              {currentStep.title}
            </span>
          </div>
        </div>

        {/* Faol bosqich komponentini render qilish */}
        <div style={{ minHeight: "180px", marginBottom: "20px" }}>
          {currentStep.id === "workspace" && <WorkspaceStep />}
          {currentStep.id === "details" && <DetailsStep />}
          {currentStep.id === "review" && <ReviewStep />}
        </div>

        {/* Navigatsiya tugmalari */}
        <div style={{ display: "flex", gap: "10px", borderTop: "1px solid #f1f5f9", paddingTop: "16px" }}>
          {stepIndex > 0 && (
            <button
              type="button"
              onClick={handlePrevStep}
              style={{
                padding: "8px 16px",
                background: "#f1f5f9",
                color: "#475569",
                border: "1px solid #cbd5e1",
                borderRadius: "6px",
                cursor: "pointer",
              }}
            >
              ← Oldingi
            </button>
          )}

          {!isLastStep ? (
            <button
              type="button"
              onClick={handleNextStep}
              style={{
                padding: "8px 20px",
                background: "#2563eb",
                color: "#fff",
                border: "none",
                borderRadius: "6px",
                cursor: "pointer",
                fontWeight: 600,
              }}
            >
              Keyingi qadam →
            </button>
          ) : (
            <button
              type="submit"
              style={{
                padding: "8px 22px",
                background: "#10b981",
                color: "#fff",
                border: "none",
                borderRadius: "6px",
                cursor: "pointer",
                fontWeight: 600,
              }}
            >
              Workspace Yaratish
            </button>
          )}
        </div>
      </form>
    </FormProvider>
  );
}

3. Katta tizimlarda muhim amaliyotlar

  1. Markazlashgan getFieldsToValidate: Har bir qadamda qaysi maydonlar tekshirilishi kerakligi WIZARD_STEPS konfiguratsiyasida saqlanadi. Agar yangi bosqich qo'shilsa yoki tekshiruv shartlari o'zgarsa, ota komponent kodini o'zgartirish shart emas — faqat konfiguratsiyaga yangi qator kiritiladi.
  2. Qoralamalarni (Draft) avtomatik saqlash: Foydalanuvchi tasodifan sahifani yangilab yuborsa yoki brauzerni yopsa, kiritilgan ma'lumotlar yo'qolmasligi uchun watch() hodisasi orqali ma'lumotlarni localStorage ga saqlab borish yoki har bosqichdan o'tganda backend'dagi draft API'ga yuborish mumkin. Sahifa qayta ochilganda reset(savedDraft) orqali tiklanadi.
  3. Step indikatorlaridan sakrash (Direct Navigation): Agar foydalanuvchi yuqoridagi qadamlar chizig'ini bosib to'g'ridan-to'g'ri 3-bosqichga o'tmoqchi bo'lsa, avval 1- va 2-bosqich maydonlarini trigger() qilib, xatolik bo'lmasa ruxsat berish xavfsizlikni ta'minlaydi.