@isi-ui7/bos7-shared 0.3.2 → 0.3.4

package/src/form-section-render.test.tsx

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { SchemaFormRenderer } from "./form-renderer";
+import type { FormSection } from "./form-types";
+
+type D = Record<string, unknown>;
+
+// Kait `render` pada FormSection — jalan keluar untuk panel yang harus MEMBACA
+// dan MENULIS state form sekaligus (mis. "Cek Identitas" di registrasi
+// nasabah), yang tidak bisa dinyatakan sebagai field.
+//
+// Dua hal yang diuji, dan yang KEDUA sama pentingnya: perubahan ini menyentuh
+// jalur render SETIAP section di seluruh platform. Kalau section tanpa `render`
+// ikut berubah, kerusakannya menyebar ke semua form sekaligus — dan bentuknya
+// bukan galat, melainkan field yang diam-diam hilang.
+
+const fieldsOnly: FormSection<D> = {
+  title: "Biasa",
+  fields: [{ key: "nama", label: "Nama Lengkap", type: "text", span: 4 }],
+};
+
+describe("FormSection.render", () => {
+  it("section BER-render menampilkan konten kustom dan TIDAK merender fields-nya", () => {
+    const section: FormSection<D> = {
+      title: "Verifikasi",
+      fields: [{ key: "nama", label: "Nama Lengkap", type: "text", span: 4 }],
+      render: () => <div>PANEL KUSTOM</div>,
+    };
+
+    render(
+      <SchemaFormRenderer<D> mode="create" value={{}} sections={[section]} onChange={() => {}} />,
+    );
+
+    expect(screen.getByText("PANEL KUSTOM")).toBeTruthy();
+    // `fields` sengaja tetap diisi di atas: kalau grid-nya ikut terender,
+    // panel dan field akan tampil bersamaan — bukan itu maksud "menggantikan".
+    expect(screen.queryByLabelText("Nama Lengkap")).toBeNull();
+  });
+
+  it("menerima value & mode, dan setValue meneruskan patch ke onChange", () => {
+    const onChange = vi.fn();
+    const seen: Record<string, unknown>[] = [];
+
+    const section: FormSection<D> = {
+      title: "Verifikasi",
+      fields: [],
+      render: (ctx) => {
+        seen.push({ value: ctx.value, mode: ctx.mode, disabled: ctx.disabled });
+        return <button onClick={() => ctx.setValue({ verify_status: "NEW" })}>Cek</button>;
+      },
+    };
+
+    render(
+      <SchemaFormRenderer<D>
+        mode="create"
+        value={{ identity_number: "327101" }}
+        sections={[section]}
+        onChange={onChange}
+      />,
+    );
+
+    expect(seen[0].value).toEqual({ identity_number: "327101" });
+    expect(seen[0].mode).toBe("create");
+    expect(seen[0].disabled).toBe(false);
+
+    screen.getByText("Cek").click();
+    expect(onChange).toHaveBeenCalledWith({ verify_status: "NEW" });
+  });
+
+  it("KONTROL REGRESI: section TANPA render tetap merender field-nya seperti sebelumnya", () => {
+    render(
+      <SchemaFormRenderer<D> mode="create" value={{}} sections={[fieldsOnly]} onChange={() => {}} />,
+    );
+    expect(screen.getByLabelText("Nama Lengkap")).toBeTruthy();
+  });
+
+  it("KONTROL REGRESI: dua section bercampur — yang polos tidak terpengaruh tetangganya", () => {
+    const custom: FormSection<D> = {
+      title: "Verifikasi",
+      fields: [],
+      render: () => <div>PANEL KUSTOM</div>,
+    };
+
+    render(
+      <SchemaFormRenderer<D>
+        mode="create"
+        value={{}}
+        sections={[custom, fieldsOnly]}
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByText("PANEL KUSTOM")).toBeTruthy();
+    expect(screen.getByLabelText("Nama Lengkap")).toBeTruthy();
+  });
+});

package/src/form-types.ts

@@ -157,6 +157,26 @@ export type FormSection<TData extends Record<string, unknown>> = {
   /** Number of equal columns in the section grid. Default 1. */
   columns?: 1 | 2 | 3;
   fields: FormField<TData>[];
+  /**
+   * Jalan keluar: render konten sendiri MENGGANTIKAN grid `fields`.
+   *
+   * Ada untuk panel yang harus MEMBACA dan MENULIS state form sekaligus, yang
+   * tidak bisa dinyatakan sebagai field — mis. panel "Cek Identitas" pada
+   * registrasi nasabah, yang memanggil backend lalu menyetel penanda hasilnya
+   * agar gerbang `canLeavePage` bisa membacanya.
+   *
+   * `description` sudah ReactNode, tapi ia tidak punya akses ke `value` maupun
+   * cara menulis balik — jadi tidak cukup untuk keperluan ini.
+   *
+   * Opsional: section tanpa `render` dirender persis seperti sebelumnya.
+   * `fields` tetap wajib (pakai `[]`) supaya tipe section tidak bercabang dua.
+   */
+  render?: (ctx: {
+    value: TData;
+    setValue: (patch: Partial<TData>) => void;
+    mode: FormMode;
+    disabled: boolean;
+  }) => ReactNode;
 };
 
 // ── Layout ────────────────────────────────────────────────────────────────────
@@ -171,7 +191,31 @@ export type FormPageDef<TData extends Record<string, unknown>> = {
 export type FormLayout<TData extends Record<string, unknown>> =
   | { type: "single-page"; sections: FormSection<TData>[] }
   | { type: "tabs"; pages: FormPageDef<TData>[] }
-  | { type: "wizard"; pages: FormPageDef<TData>[]; validateOnNext?: boolean };
+  | {
+      type: "wizard";
+      pages: FormPageDef<TData>[];
+      validateOnNext?: boolean;
+      /**
+       * Gerbang antar-langkah. Dipanggil SEBELUM pindah dari `fromPage`;
+       * mengembalikan `{ ok: false, message }` membatalkan navigasi dan
+       * menampilkan pesannya.
+       *
+       * Ada karena sebagian wizard punya langkah yang berfungsi sebagai
+       * GERBANG, bukan sekadar formulir — mis. registrasi nasabah: verifikasi
+       * identitas di Langkah 1 harus berhasil sebelum data lengkap boleh
+       * diisi, supaya dua CIF untuk satu orang tidak pernah terbentuk.
+       *
+       * Tanpa ini, satu-satunya cara menegakkannya adalah membangun wizard
+       * bespoke per layar — dan ada EMPAT layar registrasi (perorangan,
+       * badan usaha, WIC perorangan, WIC badan usaha) yang butuh gerbang yang
+       * sama persis.
+       *
+       * ⚠️ Ini penjaga NAVIGASI, bukan penjaga keamanan. Ia mencegah operator
+       * melangkah lebih jauh; ia TIDAK mencegah payload dikirim langsung ke
+       * backend. Aturan yang sama WAJIB ditegakkan lagi di server.
+       */
+      canLeavePage?: (fromPage: number, data: TData) => { ok: boolean; message?: string };
+    };
 
 // ── CrudForm (schema-driven) ──────────────────────────────────────────────────
 

package/src/wizard-step-gate.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { CrudForm } from './form-types';
+
+type D = Record<string, unknown>;
+
+// Gerbang antar-langkah wizard. Diuji sebagai KONTRAK, bukan lewat render:
+// yang penting bentuk & urutan pemanggilannya, dan itu bisa dipastikan tanpa
+// memasang seluruh form.
+//
+// Kenapa diuji sama sekali: gerbang yang gagal-terbuka tidak terlihat sebagai
+// galat — operator sekadar melewati langkah yang seharusnya mengunci, dan
+// akibatnya (dua CIF untuk satu orang) baru muncul jauh kemudian.
+
+function makeSchema(gate: NonNullable<Extract<CrudForm<D>['layout'], { type: 'wizard' }>['canLeavePage']>): CrudForm<D> {
+  return {
+    title: { create: 'c', edit: 'e', view: 'v' },
+    emptyData: {},
+    layout: {
+      type: 'wizard',
+      validateOnNext: true,
+      canLeavePage: gate,
+      pages: [
+        { label: 'Verifikasi', sections: [] },
+        { label: 'Data', sections: [] },
+      ],
+    },
+  } as CrudForm<D>;
+}
+
+describe('wizard canLeavePage', () => {
+  it('menolak pindah ketika gerbang mengembalikan ok:false, dan membawa pesannya', () => {
+    const gate = vi.fn().mockReturnValue({ ok: false, message: 'Verifikasi identitas dulu.' });
+    const schema = makeSchema(gate);
+    const layout = schema.layout as Extract<typeof schema.layout, { type: 'wizard' }>;
+
+    const res = layout.canLeavePage!(0, { verified: false });
+    expect(res.ok).toBe(false);
+    expect(res.message).toBe('Verifikasi identitas dulu.');
+  });
+
+  it('mengizinkan pindah ketika gerbang ok', () => {
+    const layout = makeSchema(() => ({ ok: true })).layout as Extract<
+      CrudForm<D>['layout'],
+      { type: 'wizard' }
+    >;
+    expect(layout.canLeavePage!(0, { verified: true }).ok).toBe(true);
+  });
+
+  it('menerima nomor halaman ASAL, bukan tujuan — gerbang milik langkah yang ditinggalkan', () => {
+    const gate = vi.fn().mockReturnValue({ ok: true });
+    const layout = makeSchema(gate).layout as Extract<CrudForm<D>['layout'], { type: 'wizard' }>;
+    layout.canLeavePage!(0, {});
+    expect(gate).toHaveBeenCalledWith(0, {});
+  });
+
+  it('opsional — wizard tanpa gerbang tetap sah secara tipe', () => {
+    const schema: CrudForm<D> = {
+      title: { create: 'c', edit: 'e', view: 'v' },
+      emptyData: {},
+      layout: { type: 'wizard', pages: [{ label: 'A', sections: [] }] },
+    } as CrudForm<D>;
+    const layout = schema.layout as Extract<typeof schema.layout, { type: 'wizard' }>;
+    expect(layout.canLeavePage).toBeUndefined();
+  });
+});

package/src/workflow/use-crud-form-gate.test.tsx

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useCrudForm } from "./use-crud-form";
+import type { CrudForm } from "../form-types";
+
+type D = Record<string, unknown>;
+
+// Gerbang antar-langkah wizard, diuji lewat PERILAKU goNext.
+//
+// Kenapa ada tes kedua padahal sudah ada wizard-step-gate.test.ts: tes itu
+// hanya memastikan BENTUK tipenya — ia akan tetap hijau meski goNext tidak
+// pernah memanggil canLeavePage sama sekali. Persis kegagalan yang gerbang ini
+// ada untuk mencegahnya: gagal-terbuka tidak berbunyi sebagai galat, operator
+// sekadar melewati langkah yang seharusnya mengunci, dan akibatnya (dua CIF
+// untuk satu orang) baru muncul jauh kemudian.
+//
+// Tes di bawah memeriksa `page` — halaman yang BENAR-BENAR ditempati — bukan
+// nilai balik gerbangnya. Itu satu-satunya yang membedakan "terpasang" dari
+// "sekadar ada".
+
+function schemaWith(
+  gate?: (from: number, d: D) => { ok: boolean; message?: string },
+  opts: { validateOnNext?: boolean } = {},
+): CrudForm<D> {
+  return {
+    title: { create: "c", edit: "e", view: "v" },
+    emptyData: { verified: false } as D,
+    layout: {
+      type: "wizard",
+      validateOnNext: opts.validateOnNext ?? false,
+      canLeavePage: gate,
+      pages: [
+        {
+          label: "Verifikasi",
+          sections: [
+            {
+              title: "s",
+              fields: [
+                {
+                  key: "nama",
+                  label: "Nama",
+                  type: "text",
+                  span: 4,
+                  validation: { required: true },
+                },
+              ],
+            },
+          ],
+        },
+        { label: "Data", sections: [] },
+      ],
+    },
+  } as unknown as CrudForm<D>;
+}
+
+describe("useCrudForm — gerbang canLeavePage", () => {
+  it("gerbang ok:false MENAHAN halaman di 0 dan menampilkan pesannya", async () => {
+    const { result } = renderHook(() =>
+      useCrudForm<D>({
+        schema: schemaWith(() => ({ ok: false, message: "Cek identitas dulu." })),
+        mode: "create",
+      }),
+    );
+
+    expect(result.current.page).toBe(0);
+    await act(async () => {
+      await result.current.goNext();
+    });
+
+    expect(result.current.page).toBe(0);
+    expect(result.current.error).toBe("Cek identitas dulu.");
+  });
+
+  it("gerbang ok:true MEMBIARKAN pindah ke halaman 1", async () => {
+    const { result } = renderHook(() =>
+      useCrudForm<D>({ schema: schemaWith(() => ({ ok: true })), mode: "create" }),
+    );
+
+    await act(async () => {
+      await result.current.goNext();
+    });
+
+    expect(result.current.page).toBe(1);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("gerbang menerima nomor halaman ASAL beserta isi form saat itu", async () => {
+    const gate = vi.fn().mockReturnValue({ ok: true });
+    const { result } = renderHook(() =>
+      useCrudForm<D>({ schema: schemaWith(gate), mode: "create" }),
+    );
+
+    await act(async () => {
+      result.current.setForm({ verified: true });
+    });
+    await act(async () => {
+      await result.current.goNext();
+    });
+
+    expect(gate).toHaveBeenCalledWith(0, { verified: true });
+  });
+
+  it("gerbang berjalan SEBELUM validasi field — pesan yang muncul alasan sebenarnya, bukan galat field", async () => {
+    // `nama` wajib dan kosong, jadi validasi PASTI gagal juga. Kalau urutannya
+    // terbalik, yang tampil adalah galat validasi generik dan operator tidak
+    // pernah tahu bahwa yang sesungguhnya menahan adalah verifikasi identitas.
+    const { result } = renderHook(() =>
+      useCrudForm<D>({
+        schema: schemaWith(() => ({ ok: false, message: "Cek identitas dulu." }), {
+          validateOnNext: true,
+        }),
+        mode: "create",
+      }),
+    );
+
+    await act(async () => {
+      await result.current.goNext();
+    });
+
+    expect(result.current.page).toBe(0);
+    expect(result.current.error).toBe("Cek identitas dulu.");
+    expect(result.current.fieldErrors).toEqual({});
+  });
+
+  it("KONTROL negatif: wizard tanpa gerbang tetap bisa pindah halaman", async () => {
+    // Kalau tes ini ikut gagal ketika gerbang dicabut, berarti yang diukur
+    // bukan gerbangnya melainkan navigasinya secara umum.
+    const { result } = renderHook(() =>
+      useCrudForm<D>({ schema: schemaWith(undefined), mode: "create" }),
+    );
+
+    await act(async () => {
+      await result.current.goNext();
+    });
+
+    expect(result.current.page).toBe(1);
+  });
+});

package/src/workflow/use-crud-form.ts

@@ -100,6 +100,19 @@ export function useCrudForm<TData extends Record<string, unknown>>({
     setServerError(null);
     setHasValidationError(false);
     const layout = schema.layout;
+
+    // Gerbang antar-langkah — diperiksa SEBELUM validasi field, karena gerbang
+    // yang gagal berarti langkah ini belum boleh ditinggalkan sama sekali;
+    // menjalankan validasi lebih dulu akan menampilkan galat field yang tidak
+    // relevan dan menutupi alasan sebenarnya.
+    if (layout.type === "wizard" && layout.canLeavePage) {
+      const gate = layout.canLeavePage(page, form);
+      if (!gate.ok) {
+        setServerError(gate.message ?? "Langkah ini belum bisa dilanjutkan.");
+        return;
+      }
+    }
+
     if (layout.type === "wizard" && layout.validateOnNext) {
       const errs = validatePage(page);
       setFieldErrors(errs);