@stratametriq/id-card-designer 1.1.0 → 1.2.0

package/README.md

@@ -9,6 +9,7 @@ Whether you are building an **Educational ERP / Student Information System**, **
 ## 🌟 Features
 
 - **🎨 Turnkey All-In-One Dashboard (`<IdCardManager />`):** Drop in a complete, ready-to-use workspace containing department tabs, live vector stage, batch A4 print setup, and roster selection table.
+- **🔍 Instant Roster Search & Status Filters:** Real-time search bar across names, ID numbers, departments, and phone numbers, plus quick status filter pill tabs (`All | Selected | Unselected`) with smart batch selection.
 - **✨ Interactive Visual Studio Canvas:** Drag-and-drop element positioning (`react-draggable`), real-time zoom controls (`80% - 200%`), grid snapping (`1mm / 5mm`), and Z-index layering.
 - **📏 Technical Precision Rulers & Grid Overlay:** Toggleable millimeter measurement rulers (`0mm - 86mm`) and radial matrix grid overlays for exact PVC card alignment.
 - **🔄 Undo & Redo History Control:** Full history stack tracking (`Ctrl+Z` / `Cmd+Z` to undo, `Ctrl+Y` / `Cmd+Shift+Z` to redo) alongside keyboard arrow key precision nudging (`1px` or `5px` with Shift).
@@ -37,6 +38,123 @@ import "@stratametriq/id-card-designer/dist/index.css";
 
 ---
 
+## 🚀 Sweet & Simple Guide: How to Use with Real Data & Features
+
+Whether you want a **1-Minute Turnkey Dashboard** (`<IdCardManager />`) or want to build your own **Custom Portal** using individual modular features (`<IdCardPreview />`, `<IdCardDesignerModal />`, `generateIdCardsPdf`), connecting your real database or API data is effortless!
+
+### Option 1: Turnkey All-In-One Dashboard (`<IdCardManager />`)
+
+By default, rendering `<IdCardManager />` without props opens our full interactive demo screen. To connect your **real API or database records**, simply pass them into the `sampleRecords` prop:
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import { IdCardManager } from '@stratametriq/id-card-designer';
+import '@stratametriq/id-card-designer/dist/index.css';
+
+export default function SchoolPortal() {
+  const [dbRecords, setDbRecords] = useState({ student: [], staff: [] });
+
+  // 1. Fetch real students/employees from your backend (Node.js, Laravel, Supabase, etc.)
+  useEffect(() => {
+    fetch('https://api.yourschool.com/students')
+      .then(res => res.json())
+      .then(data => setDbRecords({ student: data }));
+  }, []);
+
+  // 2. Pass your live data right into <IdCardManager />!
+  return (
+    <IdCardManager
+      sampleRecords={dbRecords}
+      
+      // Save customized card designs back to your database
+      onSaveCategoryTemplate={(category, templateSchema) => {
+        console.log(`Saving ${category} template to DB:`, templateSchema);
+      }}
+
+      // Listen when batch PDF export completes
+      onBatchExportComplete={(category, exportedRecords) => {
+        console.log(`Generated A4 PDF for ${exportedRecords.length} records!`);
+      }}
+    />
+  );
+}
+```
+
+---
+
+### Option 2: Building Custom Screens (Using Modular Features)
+
+If you don't want our full dashboard and instead want to embed specific ID card features directly into your own custom pages, tables, or profile screens, use our **standalone building blocks**:
+
+#### A. Show a Live ID Card on a Student Profile Page (`<IdCardPreview />`)
+```jsx
+import { IdCardPreview } from '@stratametriq/id-card-designer';
+
+function StudentProfilePage({ realStudentData, savedTemplateJson }) {
+  return (
+    <div className="profile-card-widget">
+      <h3>Student ID Card</h3>
+      
+      {/* Automatically binds realStudentData fields into the template */}
+      <IdCardPreview
+        templateSchema={savedTemplateJson}
+        data={realStudentData} // e.g. { studentName: 'Aarav Patel', admissionNo: 'ADM-101', profilePhoto: '...' }
+        orientation="vertical"
+        zoom={1.2}
+      />
+    </div>
+  );
+}
+```
+
+#### B. Trigger Batch A4 PDF Export from Your Own Custom Button (`generateIdCardsPdf`)
+```jsx
+import { generateIdCardsPdf } from '@stratametriq/id-card-designer';
+
+function CustomRosterTable({ selectedStudents, activeTemplate }) {
+  const handlePrint = async () => {
+    // Generate high-resolution A4 multi-page PDF directly from your data array
+    await generateIdCardsPdf({
+      records: selectedStudents,
+      templateSchema: activeTemplate,
+      orientation: 'vertical',
+      fileName: `Student_Cards_Batch_${new Date().toISOString().slice(0,10)}.pdf`,
+      pageOptions: { format: 'a4', showCropMarks: true }
+    });
+  };
+
+  return <button onClick={handlePrint}>Download A4 Print Sheet ({selectedStudents.length} Cards)</button>;
+}
+```
+
+#### C. Open the Drag-and-Drop Studio inside Your Own Modal (`<IdCardDesignerModal />`)
+```jsx
+import { IdCardDesignerModal } from '@stratametriq/id-card-designer';
+
+function DesignButton({ currentTemplate, onSaveToDatabase }) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>✨ Design Card Layout</button>
+      
+      <IdCardDesignerModal
+        show={isOpen}
+        onHide={() => setIsOpen(false)}
+        initialTemplate={currentTemplate}
+        sampleData={[{ studentName: 'Sample Student', admissionNo: '101' }]}
+        onSaveTemplate={(newTemplate) => {
+          onSaveToDatabase(newTemplate);
+          setIsOpen(false);
+        }}
+      />
+    </>
+  );
+}
+```
+
+---
+
 ## 🌐 Multi-Framework & Vanilla JS Support (`Vue`, `Angular`, `Svelte`, `Next.js` & `HTML`)
 
 While the visual UI components (`<IdCardManager />` and `<IdCardDesignerModal />`) are built with React hooks and drag-and-drop vector canvas state (`react-draggable`), **this npm package can be used across any frontend framework or vanilla JavaScript project**:
@@ -129,7 +247,7 @@ When users open `<IdCardManager />`, they interact with a unified, professional
 | **Step 1** | **Select Department / Organization Category** | A clean 4-card header grid showing your configured organization categories (e.g., *Student IDs*, *Faculty & Admin*, *Corporate HR*, *Hospital Portal*). Each card displays the number of bound data fields (`{fieldDefinitions.length} fields`) and template layouts (`{templateCount} template`). Clicking any card instantly switches the active category, isolating state, templates, and roster tables cleanly. |
 | **Step 2** | **Live Stage Preview & Studio Launcher** | A high-resolution vector canvas preview displaying the currently selected person's ID card in real-time. Includes:<br>• **Interactive Zoom Controls (`80% - 150%`)** alongside instant reset buttons.<br>• **Toggleable Grid & Measurement Rulers (`0-80mm`)** for visual precision inspection.<br>• **Launch Studio Canvas Button:** Opens our popup drag-and-drop design studio modal where operators can add new text fields, upload background textures, bind database keys, and drag elements around with snap-to-grid accuracy. |
 | **Step 3** | **Batch A4 Print Engine (`⚡ Live Sheet Matrix`)** | A commercial print-engine sidebar that calculates and exports production-ready multi-page grid sheets:<br>• **⚡ Live Sheet Matrix Calculation Box:** Dynamically computes physical sheet mathematics in real-time right before your eyes! When you toggle **Paper Sheet Size (`A4` vs `US Letter`)**, **Orientation (`Portrait` vs `Landscape` Sheet)**, or **Card Cut Size (`86×54mm Standard ID-1`, `90×50mm Business Card`, `100×70mm Event Badge`)**, the matrix immediately recalculates the exact column × row capacity (`e.g., 3 Cols × 3 Rows = 9 cards/page`) and total job pages required.<br>• **Hardware Cut Guides Checkboxes:** Toggle corner crosshair cut marks (`0.35mm stroke`), card perimeter cut outline guides, and technical registration headers (`PRECISION CUT SHEET — JOB SPECIFICATIONS`) for print shop operators. |
-| **Step 4** | **Live Roster Directory Table** | Displays a dynamic, paginated table of all people in that department. Columns automatically reflect your category's database fields (`studentName`, `admissionNo`, `classSec`, etc.). Check or uncheck individual records to include them in the Batch A4 Print Engine, or click any row to preview their rendered card live in Step 2! |
+| **Step 4** | **Live Roster Directory Table & Instant Search** | Displays an interactive data table of all records in that department equipped with:<br>• **🔍 Instant Search Input:** Type any name, admission/employee number, department, or phone number to instantly filter records right before your eyes.<br>• **🏷️ Quick Status Filter Pills (`All \| Selected \| Unselected`):** Isolate checked vs unchecked records instantly before batch printing.<br>• **⚡ Smart Batch Selection:** Clicking **Select Shown / Unselect Shown** smartly checks or unchecks *only the records matching your current search or filter* without disrupting unrelated records outside your filter! Clicking any row previews their rendered card live on stage in Step 2. |
 
 ---
 
@@ -347,6 +465,156 @@ const CATEGORY_CONFIGS = {
 
 ---
 
+## 🏗️ Recommended Consumer App Architecture (`my-consumer-app/`)
+
+When integrating `@stratametriq/id-card-designer` into an enterprise or institutional web application (e.g., School Management System, Hospital Portal, or Corporate HR Suite), we recommend structuring your project with clean separation of concerns:
+
+```text
+my-consumer-app/
+├── src/
+│   ├── config/
+│   │   └── idCardFields.js          # 1. Centralized field definitions & mappings across categories
+│   │
+│   ├── services/
+│   │   └── idCardApi.js             # 2. API helper methods to load/save JSON templates & records from backend
+│   │
+│   ├── components/
+│   │   └── id-cards/
+│   │       ├── CardTemplateStudio.jsx   # 3. Admin component wrapping <IdCardDesignerModal />
+│   │       ├── CardPreviewBadge.jsx     # 4. Reusable UI component wrapping <IdCardPreview />
+│   │       └── BatchPrintActions.jsx    # 5. Component managing high-DPI PDF generation & progress (`generateIdCardsPdf`)
+│   │
+│   ├── pages/
+│   │   ├── AdminSettingsPage.jsx    # Uses <CardTemplateStudio /> for administrators to design ID cards
+│   │   └── StaffDirectoryPage.jsx   # Uses <CardPreviewBadge /> and <BatchPrintActions /> for staff/student rosters
+│   └── main.jsx                     # Imports global "@stratametriq/id-card-designer/dist/index.css"
+```
+
+### 🗂️ Explanation of Key Architectural Components
+
+1. **`src/config/idCardFields.js` (Centralized Configuration)**  
+   Maintains all available data fields for each department. By isolating fields in config, adding new custom fields (`bloodGroup`, `busRoute`, `rfidTag`) never requires modifying UI components:
+   ```javascript
+   export const ID_CARD_FIELDS = {
+     student: [
+       { key: "studentName", label: "Student Full Name" },
+       { key: "admissionNo", label: "Admission Number" },
+       { key: "bloodGroup", label: "Blood Group" }
+     ],
+     staff: [
+       { key: "staffName", label: "Staff Member Name" },
+       { key: "designation", label: "Job Title / Role" }
+     ]
+   };
+   ```
+
+2. **`src/services/idCardApi.js` (API & Storage Layer)**  
+   Handles communicating with your backend server or local storage to persist the JSON template schemas (`templateSchema`) saved by administrators:
+   ```javascript
+   export async function fetchCategoryTemplate(categoryKey) {
+     const res = await fetch(`/api/id-cards/templates/${categoryKey}`);
+     return res.json();
+   }
+
+   export async function saveCategoryTemplate(categoryKey, schema) {
+     return fetch(`/api/id-cards/templates/${categoryKey}`, {
+       method: "POST",
+       headers: { "Content-Type": "application/json" },
+       body: JSON.stringify(schema)
+     });
+   }
+   ```
+
+3. **`src/components/id-cards/CardTemplateStudio.jsx` (Admin Studio Wrapper)**  
+   Wraps `<IdCardDesignerModal />` with your application's custom saving logic and category switcher:
+   ```jsx
+   import React, { useState } from "react";
+   import { IdCardDesignerModal } from "@stratametriq/id-card-designer";
+   import { ID_CARD_FIELDS } from "../../config/idCardFields";
+   import { saveCategoryTemplate } from "../../services/idCardApi";
+
+   export function CardTemplateStudio({ categoryKey = "student", initialSchema }) {
+     const [showModal, setShowModal] = useState(false);
+
+     return (
+       <div>
+         <button onClick={() => setShowModal(true)}>Open ID Card Designer</button>
+         <IdCardDesignerModal
+           show={showModal}
+           onHide={() => setShowModal(false)}
+           initialTemplate={initialSchema}
+           fieldDefinitions={ID_CARD_FIELDS[categoryKey]}
+           onSaveTemplate={async (schema) => {
+             await saveCategoryTemplate(categoryKey, schema);
+             setShowModal(false);
+           }}
+         />
+       </div>
+     );
+   }
+   ```
+
+4. **`src/components/id-cards/CardPreviewBadge.jsx` (Reusable Live Badge)**  
+   Wraps `<IdCardPreview />` to render clean vector ID cards in directory listings, profile popups, or student tables:
+   ```jsx
+   import React from "react";
+   import { IdCardPreview } from "@stratametriq/id-card-designer";
+
+   export function CardPreviewBadge({ recordData, templateSchema }) {
+     return (
+       <div className="card-preview-wrapper shadow-md rounded-lg overflow-hidden">
+         <IdCardPreview
+           templateSchema={templateSchema}
+           data={recordData}
+           zoom={1}
+         />
+       </div>
+     );
+   }
+   ```
+
+5. **`src/components/id-cards/BatchPrintActions.jsx` (Batch Print Utility Button)**  
+   Manages batch exporting checked staff or student records into multi-page A4 or Letter sheets:
+   ```jsx
+   import React, { useState } from "react";
+   import { generateIdCardsPdf } from "@stratametriq/id-card-designer";
+
+   export function BatchPrintActions({ selectedRecords, templateSchema }) {
+     const [exporting, setExporting] = useState(false);
+
+     const handleExport = async () => {
+       setExporting(true);
+       await generateIdCardsPdf({
+         records: selectedRecords,
+         templateSchema: templateSchema,
+         orientation: templateSchema?.orientation || "vertical",
+         fileName: "Batch_ID_Cards_Job.pdf",
+         pageOptions: { format: "a4", showCropMarks: true, showCutOutline: true }
+       });
+       setExporting(false);
+     };
+
+     return (
+       <button onClick={handleExport} disabled={exporting || selectedRecords.length === 0}>
+         {exporting ? "Generating PDF Sheets..." : `Batch Print (${selectedRecords.length} Cards)`}
+       </button>
+     );
+   }
+   ```
+
+6. **`src/main.jsx` (Global Stylesheet Import)**  
+   Always import the universal stylesheet right at the root entry point of your application:
+   ```javascript
+   import React from 'react';
+   import ReactDOM from 'react-dom/client';
+   import App from './App.jsx';
+   import "@stratametriq/id-card-designer/dist/index.css";
+
+   ReactDOM.createRoot(document.getElementById('root')).render(<App />);
+   ```
+
+---
+
 ## 📜 License
 
 MIT © Stratametriq