@stratametriq/id-card-designer 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stratametriq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,352 @@
+# 📦 @stratametriq/id-card-designer
+
+A universal, dynamic, and highly customizable ID Card Designer, Turnkey Dashboard & A4 Multi-Page PDF Rendering Engine for React, Vue, Angular, and Vanilla JS.
+
+Whether you are building an **Educational ERP / Student Information System**, **Faculty & Staff Directory**, **Hospital / Medical Access Portal**, **Corporate Employee Directory**, or **Event Badge Generator**, `@stratametriq/id-card-designer` gives your users a professional visual canvas right inside your application to design, customize, preview, and batch export PVC ID cards.
+
+---
+
+## 🌟 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.
+- **✨ 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).
+- **📝 Signature & Image File Uploads:** Upload Principal/Director signatures, employee photos, or organization logos (`PNG/JPG`) directly from the property inspector with live base64 conversion.
+- **🔄 Multi-Orientation Support:** Seamless switching between standard PVC card dimensions: **Vertical (54×86 mm)** and **Horizontal (86×54 mm)**.
+- **⚡ Professional Built-in Presets:** Starter templates including *Classic Traditional*, *Minimalist Modern*, *Sage Table Banner*, *Corporate Executive*, and *Medical Staff Pass*.
+- **🧩 Universal Element Types:** Dynamic text fields, static labels, custom shapes/dividers, profile photos, organization logos, signature slots, and visual barcodes/QRs.
+- **🔍 Inspector Panel & Property Editor:** Fine-grained styling for font family, size, weight, text alignment, text casing (`uppercase`, `lowercase`, `capitalize`, `togglecase`), background/border colors, radii, and prefixes/suffixes.
+- **📄 High-Resolution Batch PDF Export Engine:** Built-in multi-page A4 / Letter grid layout calculation with toggleable hardware guillotine cut marks, perimeter outlines, and registration headers (`html2canvas` + `jspdf`).
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @stratametriq/id-card-designer
+# or
+yarn add @stratametriq/id-card-designer
+```
+
+Include the stylesheet in your project root (`main.jsx` or `App.jsx`):
+
+```javascript
+import "@stratametriq/id-card-designer/dist/index.css";
+```
+
+---
+
+## 🌐 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**:
+
+### 1. Using in React & Next.js (`React 18 / Vite / Remix / Next.js`)
+Simply import our components directly into your React JSX/TSX tree:
+```jsx
+import { IdCardManager } from "@stratametriq/id-card-designer";
+```
+
+### 2. Using in Vue, Angular, Svelte, or Vanilla HTML (`Micro-Frontend Mounting`)
+If your application is built with **Vue.js**, **Angular**, **Svelte**, or plain **HTML/JS**, you can easily mount the turnkey `<IdCardManager />` dashboard into any DOM element using `createRoot` in just a few lines of code:
+
+```html
+<!-- Inside index.html or your Vue/Angular/Svelte component template -->
+<div id="id-card-manager-root"></div>
+
+<script type="module">
+  import React from 'react';
+  import { createRoot } from 'react-dom/client';
+  import { IdCardManager } from '@stratametriq/id-card-designer';
+  import '@stratametriq/id-card-designer/dist/index.css';
+
+  // Mount the visual ID Card Dashboard cleanly inside any HTML div
+  const rootElement = document.getElementById('id-card-manager-root');
+  const root = createRoot(rootElement);
+  
+  root.render(React.createElement(IdCardManager, {
+    onBatchExportComplete: (category, records) => {
+      console.log(`Exported ${records.length} cards in ${category}`);
+    }
+  }));
+</script>
+```
+
+### 3. Framework-Agnostic Pure JS Batch Print Engine (`generateIdCardsPdf`)
+The core multi-page A4 and US Letter PDF rendering engine (**`generateIdCardsPdf`**) is completely framework-agnostic! Whether you are writing pure TypeScript, Node/Express frontend scripts, Vue, or Angular, you can import and run `generateIdCardsPdf()` directly without mounting any React UI components:
+
+```javascript
+import { generateIdCardsPdf } from "@stratametriq/id-card-designer";
+
+// Works natively across Vue, Angular, Svelte, and Vanilla JS!
+await generateIdCardsPdf({
+  records: myDatabaseArray,
+  templateSchema: myLoadedJsonSchema,
+  orientation: "vertical",
+  fileName: "Batch_Job_Output.pdf"
+});
+```
+
+---
+
+## 📖 Public API & Turnkey Dashboard Reference
+
+When developers install `@stratametriq/id-card-designer` via npm, they can choose between two usage modes:
+1. **Turnkey Dashboard Mode (`<IdCardManager />`)**: Drop in a single component to instantly display the complete multi-department dashboard (navigation tabs, live card stage, roster directory table, and batch PDF export engine).
+2. **Custom Building Blocks Mode (`<IdCardDesignerModal />` + `<IdCardPreview />`)**: Import atomic components to embed only the popup studio or live card preview into custom-built interfaces.
+
+---
+
+### 1. `<IdCardManager />` (Turnkey All-in-One Dashboard & 4-Step Master Workflow)
+
+The `<IdCardManager />` is the complete, out-of-the-box management suite. We engineered a **clean, full-width unified layout** with zero redundant navigation tabs so operators and end-users get a sleek, ultra-fast 4-step workflow:
+
+```jsx
+import React from "react";
+import { IdCardManager } from "@stratametriq/id-card-designer";
+import "@stratametriq/id-card-designer/dist/index.css";
+
+export function MyOrganizationPortal() {
+  return (
+    <IdCardManager
+      onSaveCategoryTemplate={(categoryKey, newTemplate) => {
+        console.log(`Saved template for ${categoryKey}:`, newTemplate);
+      }}
+      onBatchExportComplete={(categoryKey, exportedRecords) => {
+        console.log(`Exported ${exportedRecords.length} cards for ${categoryKey}`);
+      }}
+    />
+  );
+}
+```
+
+#### 🧩 The Clean 4-Step Master Workflow Architecture
+
+When users open `<IdCardManager />`, they interact with a unified, professional full-width screen broken into four logical steps:
+
+| Workflow Step | Section Title & Purpose | Detailed Functionality & Mathematical Features |
+| :--- | :--- | :--- |
+| **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! |
+
+---
+
+#### ⚡ Zero-Configuration Automatic Field Discovery (`Auto-Detecting User Database Columns`)
+
+You **never have to worry about missing fields**. If your database or user records contain custom columns that are not explicitly defined in `fieldDefinitions`, `<IdCardManager />` and our Studio Canvas (`ElementPropertyEditor`) handle them automatically:
+1. **Auto-Discovery Scan:** When you open the Studio Canvas, our property engine scans `Object.keys(sampleData[0])` directly from the live database records you passed in.
+2. **Auto-Formatting:** Raw database keys like `bloodGroup`, `busRouteNo`, `emergencyPhone`, `allergyAlert`, or `parkingSlot` are automatically transformed into clean human-readable titles (e.g., **"Bus Route No (`busRouteNo`)"**).
+3. **Instant Binding:** Every discovered key is automatically merged into the **`Data Field Key`** dropdown in the right sidebar under `4. ELEMENT PROPERTIES`. Any user can click `+ Add Element` ➡️ `Dynamic Field`, select their custom database key, and bind it immediately without writing a single line of code!
+
+---
+
+### 2. Customizing Categories & Dynamic Fields (`categories` & `sampleRecords` Props)
+
+By default, `<IdCardManager />` includes four global starter categories: **Student ID Cards (Education)**, **Faculty & Administration**, **Corporate Employee Badges**, and **Healthcare & Medical Pass**.
+
+You can pass your own custom categories and live database records directly via props without editing the library:
+
+```jsx
+const myCustomCategories = {
+  university: {
+    id: "university",
+    label: "University Engineering Students",
+    badge: "🎓 Higher Education",
+    themeColor: "#0d6efd",
+    defaultOrientation: "vertical",
+    templateCount: 2,
+    description: "Dynamic field binding tailored for enrollment numbers, engineering departments, and library barcodes.",
+    fieldDefinitions: [
+      { key: "studentName", label: "Student Full Name", defaultValue: "Aarav Sharma" },
+      { key: "enrollmentNo", label: "Enrollment Number", defaultValue: "ENR-2026-991" },
+      { key: "branch", label: "Engineering Branch", defaultValue: "Computer Science & Engineering" },
+      { key: "year", label: "Academic Year", defaultValue: "B.Tech Year 3" },
+      { key: "bloodGroup", label: "Blood Group", defaultValue: 'O+ POSITIVE' }
+    ]
+  },
+  executives: {
+    id: "executives",
+    label: "Global Executive Badges",
+    badge: "🏢 Corporate HQ",
+    themeColor: "#6f42c1",
+    defaultOrientation: "horizontal",
+    templateCount: 1,
+    description: "Dynamic field binding tailored for corporate executive designations, floor security clearance, and access barcodes.",
+    fieldDefinitions: [
+      { key: "execName", label: "Executive Full Name", defaultValue: "Elena Rostova" },
+      { key: "designation", label: "Designation / Role", defaultValue: "VP of Cloud Engineering" },
+      { key: "empCode", label: "Employee ID Code", defaultValue: "EMP-HQ-402" },
+      { key: "clearance", label: "Security Clearance", defaultValue: "Level 5 (All Floors & Server Rooms)" }
+    ]
+  }
+};
+
+const myLiveRecords = {
+  university: [
+    { studentName: "Aarav Sharma", enrollmentNo: "ENR-2026-991", branch: "Computer Science", year: "B.Tech Year 3", bloodGroup: "O+ POSITIVE" },
+    { studentName: "Diya Patel", enrollmentNo: "ENR-2026-992", branch: "Electronics & Comm", year: "B.Tech Year 2", bloodGroup: "B+ POSITIVE" }
+  ],
+  executives: [
+    { execName: "Elena Rostova", designation: "VP of Cloud Engineering", empCode: "EMP-HQ-402", clearance: "Level 5" }
+  ]
+};
+
+export function CustomApp() {
+  return (
+    <IdCardManager
+      categories={myCustomCategories}
+      sampleRecords={myLiveRecords}
+    />
+  );
+}
+```
+
+---
+
+### 3. `<IdCardDesignerModal />` (Standalone Studio Modal)
+
+The standalone interactive modal component for designing and modifying ID card templates. Use this when embedding only the popup studio inside your own custom interface without the turnkey dashboard.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `show` | `boolean` | `false` | Controls visibility of the designer modal. |
+| `onHide` | `function` | `() => {}` | Callback triggered when closing the modal. |
+| `initialOrientation` | `string` | `"vertical"` | Default card orientation (`"vertical"` \| `"horizontal"`). |
+| `initialTemplate` | `object` | `null` | Existing JSON template schema to edit. If null, loads preset. |
+| `fieldDefinitions` | `array` | `[]` | Array of dynamic field options (`[{ key, label, defaultValue }]`). |
+| `sampleData` | `array` | `[]` | Array of data records to preview during designing. |
+| `themeColors` | `object` | `{ primary: "#424343", text: "#faf4f4" }` | Default primary header and text colors. |
+| `orgAssets` | `object` | `{ logoUrl, signatureUrl, defaultAvatarUrl }` | Default image URLs for logo, signature, and fallback photo. |
+| `onSaveTemplate` | `function` | `(templateSchema) => {}` | Callback returning the finalized JSON template object on save. |
+
+---
+
+### 4. `<IdCardPreview />` (Atomic Card Renderer)
+
+A lightweight component for rendering a single high-resolution vector ID card anywhere in your UI.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `templateSchema` | `object` | *Required* | The JSON template schema generated by the designer. |
+| `data` | `object` | `{}` | The record object containing dynamic field values to display. |
+| `orientation` | `string` | `"vertical"` | Orientation (`"vertical"` or `"horizontal"`). |
+| `zoom` | `number` | `1` | Scaling factor (`1` = exact physical dimensions, `1.5` = 150% size). |
+| `className` | `string` | `""` | Optional CSS class name for outer wrapper. |
+
+---
+
+### 5. `generateIdCardsPdf(options)` (Programmatic Batch Print Utility)
+
+An asynchronous utility function to generate multi-page, high-resolution A4 or Letter PDFs for batch printing from anywhere in your application.
+
+```javascript
+import { generateIdCardsPdf } from "@stratametriq/id-card-designer";
+
+await generateIdCardsPdf({
+  records: [...],             // Array of data records to render
+  templateSchema: {...},      // JSON template schema object
+  orientation: "vertical",    // "vertical" | "horizontal"
+  fileName: "ID_Cards_Sheet.pdf", // Name of the downloaded file
+  pageOptions: {
+    format: "a4",             // Paper size ("a4" | "letter")
+    scale: 2,                 // Resolution scale for html2canvas (2 = High DPI)
+    marginMm: 10,             // Top/side page margins in mm
+    spacingMm: 10,            // Gap between cards in mm
+    showCropMarks: true,      // Add corner crosshair cut guides
+    showCutOutline: true,     // Add faint card perimeter borders
+    showHeader: true          // Add technical registration header
+  },
+  onProgress: (current, total) => {
+    console.log(`Rendered page ${current} of ${total}`);
+  }
+});
+```
+
+---
+
+### 6. JSON Template Schema Structure (`templateSchema`)
+
+Every design created in `<IdCardDesignerModal />` is stored and exported as a clean, serializable JSON schema:
+
+```json
+{
+  "id": "tpl_school_vertical_01",
+  "name": "Classic Vertical ID",
+  "orientation": "vertical",
+  "width": 54,
+  "height": 86,
+  "background": {
+    "color": "#ffffff",
+    "image": "https://myportal.com/assets/card-bg-watermark.png",
+    "size": "cover"
+  },
+  "elements": [
+    {
+      "id": "el_header_box",
+      "type": "shape",
+      "label": "Top Header Box",
+      "x": 0, "y": 0, "width": 54, "height": 14,
+      "backgroundColor": "#0d6efd",
+      "zIndex": 1
+    },
+    {
+      "id": "el_photo_slot",
+      "type": "image",
+      "subtype": "photo",
+      "fieldKey": "profilePhoto",
+      "label": "Student Photo",
+      "x": 14, "y": 18, "width": 26, "height": 28,
+      "borderWidth": 1.5, "borderColor": "#0d6efd", "borderRadius": 4,
+      "zIndex": 3
+    },
+    {
+      "id": "el_student_name",
+      "type": "field",
+      "fieldKey": "studentName",
+      "label": "Student Name",
+      "x": 2, "y": 48, "width": 50, "height": 7,
+      "fontFamily": "Inter, sans-serif",
+      "fontSize": 11, "fontWeight": "bold", "color": "#111111",
+      "textAlign": "center", "textTransform": "uppercase",
+      "zIndex": 4
+    }
+  ]
+}
+```
+
+---
+
+## 🏢 Multi-Department Architecture (The Dictionary Pattern)
+
+If your software serves multiple organizational departments (e.g., **Students** vs. **Teachers** vs. **Hospital Doctors** vs. **Corporate HR**), you **do not need multiple modal components or hardcoded libraries**. Instead, use the **Dictionary Pattern** to silo category schemas while sharing a single universal `<IdCardDesignerModal />` or `<IdCardManager />` instance:
+
+```javascript
+const CATEGORY_CONFIGS = {
+  student: {
+    title: "Student ID Cards",
+    defaultOrientation: "vertical",
+    fieldDefinitions: [
+      { key: "studentName", label: "Student Full Name", defaultValue: "Aarav Sharma" },
+      { key: "admissionNo", label: "Admission Number", defaultValue: "ADM-2026-089" },
+      { key: "classSec", label: "Class & Section", defaultValue: "Grade 10 [A]" }
+    ]
+  },
+  staff: {
+    title: "Faculty & Staff Directory",
+    defaultOrientation: "horizontal",
+    fieldDefinitions: [
+      { key: "facultyName", label: "Faculty / Staff Name", defaultValue: "Dr. Ananya Iyer" },
+      { key: "empCode", label: "Employee ID Code", defaultValue: "EMP-FAC-104" },
+      { key: "designation", label: "Job Designation", defaultValue: "Senior Physics Lecturer" }
+    ]
+  }
+};
+```
+
+---
+
+## 📜 License
+
+MIT © Stratametriq