@stratametriq/id-card-designer 1.10.0 → 1.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 A universal, dynamic, and highly customizable **ID Card Designer & Batch Print Dashboard** for React, Vue, Angular, and Vanilla JS.
 
-> **Current release:** 1.10.0
+> **Current release:** 1.12.0
 
 ---
 
@@ -10,8 +10,11 @@ A universal, dynamic, and highly customizable **ID Card Designer & Batch Print D
 
 - [Overview](#overview)
 - [Live Demo](#live-demo)
+- [What's New in v1.12.0](#whats-new-in-v1120)
+- [What's New in v1.11.0](#whats-new-in-v1110)
 - [What's New in v1.10.0](#whats-new-in-v1100)
 - [Features](#features)
+- [ID Card Verification & Card Lifecycle](#id-card-verification--card-lifecycle)
 - [How It Works](#how-it-works)
 - [Import Data](#import-data)
 - [Design Cards](#design-cards)
@@ -38,7 +41,7 @@ It is designed for applications such as:
 - Membership systems
 - Internal identity-card workflows
 
-The package combines **visual card design** with **structured data and batch generation** so developers do not need to build an ID-card production workflow from scratch.
+The package combines **visual card design** with **structured data, batch generation, card lifecycle management, and live digital verification** so developers do not need to build an ID-card production workflow from scratch.
 
 ---
 
@@ -50,52 +53,37 @@ You can launch a complete ID card design studio and batch print dashboard with j
 
 ---
 
-## What's New in v1.10.0
-- **Brand & Security Watermark Suite:** Complete watermarking support for card templates, live canvas editing, previews, and batch print exports.
-  - **Multi-Mode Watermarks:** Brand / Security Text (`STRATAMETRIQ`, `OFFICIAL`, `SAMPLE`, `CONFIDENTIAL`, `DRAFT`), Custom Logo/Seal Uploads, and Repeating SVG Security Tiles.
-  - **Dynamic Placeholders:** Watermarks support live field bindings like `{{companyName}}` or `{{employeeId}}`.
-  - **Inspector Controls:** Opacity sliders (`3%`–`40%`), rotation angle dials (`-45°` to `45°`), color and font size controls.
-  - **Layer & Side Targeting:** Background (behind text/photo) vs. Overlay (top security layer) placement with side targeting (`all`, `front`, `back`).
-  - **300 DPI Export Integrity:** Watermarks export crisp in PDFs, thermal CR80 PVC prints, and PNGs while ensuring 100% barcode/QR optical scannability.
+## What's New in v1.12.0
+- **Dynamic Custom Column / Field Creator (`+ Add Column`):** Add custom data columns (e.g. `Bus Route`, `Locker Number`, `RFID Badge UID`, `House Color`) directly inside the People Directory without re-uploading spreadsheets.
+  - **Auto-Generated Template Keys:** Automatically generates camelCase variables (e.g. `{{busRoute}}`) with customizable data types (`Text`, `Number`, `Date`, `Badge`).
+  - **Default Value Backfilling:** Automatically populates default values across all existing cards in the active department.
+  - **Live Table Controls:** Custom headers appear with `✦ Label`, 1-click ascending/descending sorting, and a one-click delete trigger (`[x]`).
+  - **Universal Propagation:** Custom columns appear in Add/Edit forms, resolve in `<IdCardPreview />`, export into `.xlsx`/`.csv`, bind as draggable tags in `<IdCardDesignerModal />`, and persist in IndexedDB (`idcd_customFieldDefsMap`) and `.stmq` project backups.
+- **Enterprise People Directory Suite:**
+  - **Directory Export to Excel (.xlsx) & CSV (.csv):** Export all or selected cards into formatted `.xlsx` workbooks and `.csv` files completely client-side. Checkbox selection allows printing or exporting a single card or custom batch.
+  - **Live Data Quality & Missing Photo Filters:** Automatic audits identifying cards missing real portraits (`⚠️ Missing Photo (X)`) or incomplete information (`⚠️ Incomplete (X)`) with visual warning badges.
+  - **Dynamic Sub-Group (Department / Class) Filter:** Auto-discovers unique sections, roles, or wards with live count badges (`Group: [All Groups (X) ▾]`).
+  - **Card Expiry Date & Renewal Tracking:** Dedicated `expiryDate` tracking with automatic `🟡 EXPIRED` flagging and filter chips.
+  - **Duplicate ID Collision Detection:** Real-time frequency analysis highlights duplicate badge IDs with `⚠️ DUPLICATE` warning pills.
 
 ---
 
-## What's New in v1.9.5
-- **Multi-Mode Scannable QR Codes:** Added support for Dynamic Field Binding (with URL prefixes), Static URLs, and vCard 3.0 Digital Contact Cards (instant smartphone scan-to-save contacts).
-- **Custom QR Colors & Error Correction Level (ECC):** Full foreground and background color pickers with selectable ECC levels (`L`, `M`, `Q`, `H`).
-- **1-Click Blank Excel Template Generator:** Download clean, pre-formatted `.xlsx` spreadsheets matching the columns of any active department.
-- **CR80 Thermal PVC Print Matrix Fix:** Accurate single-card sheet layout (`1 Col × 1 Row`, `54×86 mm`) calculations in the Live Sheet Grid Matrix.
-- **Enhanced Text Wrapping & Auto-Shrink:** Intelligent text break-word handling for long addresses and multi-line descriptions.
-- **Roster Monospace ID Badge Polish:** Added `whiteSpace: nowrap` to table ID badges in the Live Roster Directory.
-
----
-
-## What's New in v1.9.4
-- **Full Roster CRUD & IndexedDB Sync:** Added an interactive **"+ Add Record"** modal with integrated photo upload, an **"Edit Record"** modal for fixing details on the fly, individual row **"Delete"** with confirmation, and bulk **"Delete Selected"** actions—all synchronized with browser IndexedDB (`localforage`).
-- **Interactive Multi-Column Sorting:** 1-click column header sorting (Ascending / Descending) across Name & Avatar, Class/Designation, ID Number, Guardian/Department, and Contact Phone.
-- **Smart Roster Pagination:** High-performance pagination toolbar (`10`, `25`, `50`, `100`, `All`) with responsive page navigation controls, preventing DOM lag on large imported rosters (1,000+ cards).
-- **Production-Grade Scannable QR & 1D Barcodes:** Upgraded QR codes (`qrcode`) and 1D Code 128 Barcodes (`jsbarcode`) to produce mathematically accurate, industry-standard matrices readable by mobile cameras and hardware laser scanners.
-- **Multi-CSV Import Append:** Sequential importing now seamlessly merges new records and dynamic fields without overriding previously imported data.
-
----
-
-## What's New in v1.9.0
-- **AI Background Removal:** Integrated an advanced, fully client-side WebAssembly machine learning model (`@imgly/background-removal`) directly into the Live Roster Data Table. Users can now perfectly remove the background from uploaded profile photos or webcam captures with a single click, completely offline, without any backend processing or API keys.
-
----
-
-## What's New in v1.8.0
-- **Canva-Style Smart Alignment Guides:** Magnetically snap elements to the center of the card or align them perfectly with other elements using color-coded visual guides (Purple for center, Red for edges).
-- **High-Res ZIP Export:** Batch export individual ID cards as high-resolution (300 DPI) PNG files neatly packaged in a single ZIP archive.
-- **Thermal PVC Printer Support:** Native support for exporting a perfectly dimensioned CR80 layout (1 card per page) specifically optimized for Zebra, Fargo, and Magicard thermal printers.
-- **Dynamic Image Fallbacks:** Beautifully generated initial-based avatars with consistent gradient backgrounds are automatically inserted if a profile photo is missing.
-- **Curved Typography:** Advanced SVG text rendering to wrap and curve text along circular paths.
+## What's New in v1.11.0
+- **ID Card Digital Verification & Card Lifecycle Suite:** Upgrades `@stratametriq/id-card-designer` from a badge design canvas into a complete Enterprise Credential & Anti-Counterfeiting Platform.
+  - **Standalone `<IdCardVerificationModal />`:** Mobile-friendly digital verification certificate featuring real-time status banners (🟢 `Active`, 🟣 `Issued`, ⚪ `Draft`, 🟠 `Suspended`, 🔴 `Revoked`, 🚨 `Lost`), official database photo matching, and digital checksum verification.
+  - **Built-in HTML5 Camera Scanner:** Optical scanner using `getUserMedia` with targeting reticle overlay for instant badge scanning via laptop webcams or smartphone cameras.
+  - **Live Roster Lifecycle Controls:** Added interactive **Status Column** in `<IdCardManager />` with 1-click status switcher dropdowns, row-level **"Verify"** action buttons, and **Batch Action ▾** menu.
+  - **Smart Lifecycle Filter Tabs:** 1-Click filter toolbar (`All`, `Active`, `Issued`, `Draft`, `Suspended`, `Revoked`, `Selected`).
+  - **Automatic Print Issuance Promotion:** Batch PDF or ZIP export automatically promotes printed cards to **`Issued`** status with an ISO issuance timestamp (`issuedAt`).
+  - **Dynamic Verification QR Code Preset:** Dedicated "Verification QR" button and configuration in Property Editor with dynamic URL binding for live scanning.
 
 ---
 
 ## Features
 
 - **🎨 Visual ID Card Designer:** A complete workspace for designing ID cards with a visual canvas, configurable elements, templates, and preview capabilities.
+- **➕ Custom Column / Field Creator:** Dynamically create custom data fields (`+ Add Column`) on the fly, with automated template key generation, default value backfilling, live table sorting, and persistent IndexedDB sync.
+- **📊 Enterprise People Directory:** Export full or selected cards to formatted Excel (`.xlsx`) & CSV (`.csv`), filter by missing portraits or incomplete records, filter by class/department sub-groups, track card expiration dates, and detect duplicate ID collisions in real time.
 - **➕ Live Roster CRUD & Management:** Full inline editing ("Edit Record"), manual creation ("+ Add Record" with photo upload), individual deletion, and bulk selection deletion directly from the dashboard.
 - **🔀 Multi-Column Sorting & Smart Pagination:** 1-click column header sorting (Ascending / Descending) and customizable pagination (`10`, `25`, `50`, `100`, `All`) for smooth performance on large datasets.
 - **📥 CSV & Excel Import:** Import structured card data from `.csv`, `.xlsx`, and `.xls`. Imported columns can be used as dynamic fields inside templates.
@@ -104,9 +92,100 @@ You can launch a complete ID card design studio and batch print dashboard with j
 - **🔳 QR Codes & Barcodes:** Generate dynamic, scannable QR codes (`qrcode`) and 1D Code 128 barcodes (`jsbarcode`) and bind them to record values such as admission numbers, employee IDs, URLs, or other unique identifiers.
 - **🏷️ Dynamic Field Placeholders:** Bind template elements to imported data (e.g., `ID: {{admissionNo}}`).
 - **🧠 Conditional Rendering:** Text elements can use JavaScript expressions for conditional output (e.g., `{{ department === 'HR' ? 'Red' : 'Blue' }}`).
+- **🛡️ Digital ID Card Verification:** Built-in `<IdCardVerificationModal />` with real-time status banners, anti-tampering photo match, HTML5 camera scanner, and public verification URLs.
+- **🔄 Full Card Lifecycle Management:** Complete state machine tracking (`Active`, `Issued`, `Draft`, `Suspended`, `Revoked`, `Lost`), interactive table status pills, batch status transitions, and automatic issuance logging on print.
 - **🛡️ Brand & Security Watermark Suite:** Add customizable text watermarks (`STRATAMETRIQ`, `CONFIDENTIAL`, `SAMPLE`), uploaded brand seal logos, and repeating security tile patterns with live opacity, rotation, and layer controls.
 - **🔲 Smart Alignment Guides:** Snap elements to the center of the card or align them with other elements using visual color-coded guides (Purple for center, Red for edges).
 - **⌨️ Keyboard Shortcuts:** Navigate the editor faster using Undo/Redo (`Ctrl+Z`, `Ctrl+Y`), Duplicate (`Ctrl+C`, `Ctrl+V`), Delete, and Arrow Key nudging.
+
+---
+
+## ID Card Verification & Card Lifecycle
+
+### 1. Card Lifecycle State Machine
+
+Physical and digital ID credentials transition through an operational lifecycle:
+
+```text
+[Import / Add] ──► DRAFT
+                     │
+                     ▼
+                 APPROVED
+                     │
+                     ▼ (Batch Print / Export)
+                  ISSUED ──► ACTIVE ◄──► SUSPENDED (Temporary Freeze)
+                               │
+            ┌──────────────────┼──────────────────┐
+            ▼                  ▼                  ▼
+         EXPIRED            REVOKED         LOST / STOLEN
+      (Term Ended)       (Resigned/Exit)    (Blacklisted)
+```
+
+| Lifecycle State | Badge Indicator | Meaning & Access Rule |
+| :--- | :--- | :--- |
+| **Draft** | ⚪ `Gray` | Newly created record; pending administrative review before printing. |
+| **Approved** | 🔵 `Blue` | Validated and approved for inclusion in batch print runs. |
+| **Issued** | 🟣 `Purple` | High-DPI physical card printed; logs issuance timestamp (`issuedAt`). |
+| **Active** | 🟢 `Green` | Currently valid credential; full campus / facility entry authorized. |
+| **Suspended** | 🟠 `Amber` | Temporary administrative hold (fees, disciplinary, leave). Gate entry denied. |
+| **Revoked** | 🔴 `Red` | Credential invalidated permanently (student graduated, employee resigned). |
+| **Lost / Stolen** | 🚨 `Rose` | Badge blacklisted to prevent unauthorized impersonator entry. Confiscate on sight. |
+| **Expired** | 🟡 `Yellow` | Credential validity date passed; renewal required. |
+
+### 2. Live Anti-Counterfeiting Verification
+
+Every badge template can include a **Dynamic Verification QR Code** that points to an authentic verification certificate:
+```text
+https://verify.stratametriq.com/badge/{{id}}
+```
+
+When scanned by any smartphone camera or optical scanner:
+1. **Live Credential Status**: Instantly displays whether the badge is 🟢 `ACTIVE`, 🟠 `SUSPENDED`, or 🔴 `REVOKED`.
+2. **Official Database Photo Match**: Displays the high-resolution photo stored in the database to immediately expose photo-swapping tampering on physical PVC cards.
+3. **Audit Information**: Card serial number, emergency phone numbers, admission/employee code, and tamper-proof verification checksum.
+
+### 3. Verification Component Code Example
+
+```jsx
+import React, { useState } from 'react';
+import { IdCardVerificationModal } from '@stratametriq/id-card-designer';
+
+function SecurityGateApp() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeRecord, setActiveRecord] = useState(null);
+
+  const rosterRecords = [
+    {
+      id: 'ADM-2026-104',
+      studentName: 'Rahul Sharma',
+      classSec: 'Class X [A]',
+      status: 'active',
+      profilePhoto: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=300'
+    }
+  ];
+
+  return (
+    <div>
+      <button onClick={() => setIsOpen(true)}>
+        🛡️ Verify ID Badge
+      </button>
+
+      <IdCardVerificationModal
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        records={rosterRecords}
+        activeRecord={activeRecord}
+        onUpdateRecordStatus={(recordId, newStatus) => {
+          console.log(`Updated record ${recordId} to ${newStatus}`);
+        }}
+        theme="dark"
+        categoryLabel="Student Credential"
+      />
+    </div>
+  );
+}
+```
+
 ---
 
 ## How It Works