STC SPTAP App Frontend NSS SDK Modal

คอมโพเนนต์ Modal สำหรับใช้งานข้ามโปรเจกต์ (SDK Modal) รองรับการปรับแต่งที่หลากหลาย เช่น เปลี่ยนสถานะ, รองรับการแบ่งบรรทัด, ควบคุมผ่านคีย์บอร์ด (Enter / ESC), และการปิดกั้นไม่ให้ปิดด้วยการคลิกพื้นหลังแบบตายตัว

📦 1. การติดตั้ง (Installation)

รันคำสั่งด้านล่างในโปรเจกต์หลักที่คุณต้องการจะนำ SDK ตัวนี้ไปใช้งาน:

npm install stc-spt-sptap-app-frontend-nss-sdk-modal

(หมายเหตุ: หากโปรเจกต์ของคุณใช้ React 19 อาจพบปัญหา Peer Dependency ขัดแย้ง ให้ใช้คำสั่ง npm install --legacy-peer-deps)

🚀 2. การตั้งค่าและนำไปใช้งาน (Usage Guide)

เราแนะนำให้ใช้งานร่วมกับ Zustand (Global State) เพื่อให้สามารถสั่งเปิด Modal ได้จากทุกที่ของแอปพลิเคชัน ไม่ว่าจะลึกแค่ไหนก็ตาม

ขั้นตอนที่ 2.1: Import CSS ในไฟล์ตั้งต้น

เข้าไปที่ไฟล์ที่เป็นรากฐานของโปรเจกต์ (เช่น main.tsx หรือ index.tsx) และนำเข้า CSS เพื่อโหลดสไตล์พื้นฐาน

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import 'stc-spt-sptap-app-frontend-nss-sdk-modal/style.css'; // 👈 สำคัญ: ต้องนำเข้า CSS

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

ขั้นตอนที่ 2.2: สร้าง Store สำหรับควบคุม Modal (Zustand)

สร้างไฟล์แยกมา 1 ไฟล์ เช่น src/store/useModalStore.ts เพื่อจัดการ state ของ Modal

// src/store/useModalStore.ts
import { create } from 'zustand';
import type { ModalStatus } from 'stc-spt-sptap-app-frontend-nss-sdk-modal';

interface ButtonConfig {
    label: string;
    variant: 'solid' | 'outline';
    onClick: () => void;
}

interface ModalState {
  isOpen: boolean;
  status: ModalStatus;
  title: string;
  description: string;
  buttonLayout: 'horizontal' | 'vertical';
  buttons: ButtonConfig[];
  openModal: (config: Partial<Omit<ModalState, 'isOpen' | 'openModal' | 'closeModal'>>) => void;
  closeModal: () => void;
}

export const useModalStore = create<ModalState>((set) => ({
  isOpen: false,
  status: 'warning',
  title: '',
  description: '',
  buttonLayout: 'horizontal',
  buttons: [],
  openModal: (config) => set((state) => ({ ...state, ...config, isOpen: true })),
  closeModal: () => set({ isOpen: false }),
}));

ขั้นตอนที่ 2.3: นำตัว Component ไปฝังไว้ชั้นนอกสุด

ในไฟล์ App.tsx เพื่อให้ทำงานได้ชัวร์และไม่ซ้อนทับใคร ให้นำ Component ของ SDK มาแปะไว้แล้วผูก Prop ตรงกับ Store

// src/App.tsx
import { Routes, Route } from 'react-router-dom';
import { ModalWarning } from 'stc-spt-sptap-app-frontend-nss-sdk-modal';
import { useModalStore } from './store/useModalStore';
import HomePage from './pages/HomePage';

function App() {
  const modal = useModalStore();

  return (
    <>
      <ModalWarning
        isOpen={modal.isOpen}
        status={modal.status}
        title={modal.title}
        description={modal.description}
        buttonLayout={modal.buttonLayout}
        buttons={modal.buttons}
      />
      
      {/* โค้ดของแอปพลิเคชันคุณ... */}
      <Routes>
        <Route path="/" element={<HomePage />} />
      </Routes>
    </>
  );
}

export default App;

ขั้นตอนที่ 2.4: วิธีสั่งเรียกเปิด Modal จากที่ไหนก็ได้!

ตอนนี้เมื่อคุณอยู่ที่ไฟล์ใด หรือหน้าจอไหน ก็แค่ดึง openModal และ closeModal จาก Store มาใช้งานได้เลย

// src/pages/HomePage.tsx
import { useModalStore } from '../store/useModalStore';

function HomePage() {
  const { openModal, closeModal } = useModalStore();

  const handleDelete = () => {
    openModal({
      status: 'error',
      title: 'ต้องการลบใช่หรือไม่?',
      description: 'ข้อมูลของคุณจะหายไปทั้งหมด\nโปรดยืนยันการทำรายการ', // รองรับ \n เพื่อขึ้นบรรทัดใหม่
      buttonLayout: 'horizontal',
      buttons: [
        { 
          label: 'ยกเลิก', 
          variant: 'outline', 
          onClick: closeModal // กดแล้วเรียกฟังก์ชันปิด Modal
        },
        { 
          label: 'ยืนยันการลบ', 
          variant: 'solid', 
          onClick: () => {
             console.log("ลบข้อมูลสำเร็จ!");
             closeModal();
          }
        }
      ]
    });
  }

  return (
    <div className="p-10">
      <h1>หน้าหลัก</h1>
      <button onClick={handleDelete} className="bg-red-500 text-white px-4 py-2 rounded">
        ลบข้อมูลเลย
      </button>
    </div>
  );
}

export default HomePage;

⌨️ 3. การทำงานของปุ่มลัด (Keyboard Support)

SDK ตัวนี้มีการดักจับคีย์บอร์ดที่ชั้นบนสุดให้แล้วอัตโนมัติ (Event Interception) การันตีว่าจะไม่รบกวนหน้าอื่นใด

• หากตั้งค่าไว้ 2 ปุ่ม:
  • กด ESC จะทริกเกอร์ onClick ของปุ่มที่ 1 ทันที
  • กด Enter จะทริกเกอร์ onClick ของปุ่มที่ 2 ทันที
• หากตั้งค่าไว้ 1 ปุ่ม:
  • กด Enter จะทริกเกอร์ onClick ของปุ่มที่ 1 ทันที

⛔ 4. พื้นหลัง (Backdrop)

การปิด Modal สามารถทำได้โดยผ่านการคลิกปุ่มต่างๆใน Modal และกดปุ่มบนคีย์บอร์ดตามเงื่อนไขเท่านั้น จะ ไม่สามารถปิด Modal จากการคลิกพื้นที่หน้าจอว่างๆ ด้านหลังได้ ทำให้ปลอดภัยและบังคับให้ผู้ใช้งานต้องกดที่ปุ่มตัดสินใจเท่านั้น