@stratametriq/id-card-designer 1.6.1 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/LICENSE +13 -16
  2. package/README.md +166 -147
  3. package/dist/index.css +1 -1155
  4. package/dist/index.es.js +39764 -14894
  5. package/dist/index.js +180 -127
  6. package/package.json +18 -21
package/LICENSE CHANGED
@@ -1,21 +1,18 @@
1
- MIT License
1
+ STRATAMETRIQ DUAL LICENSE
2
2
 
3
3
  Copyright (c) 2026 Stratametriq
4
4
 
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
5
+ This software is licensed under a dual-tier model:
11
6
 
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
7
+ 1. COMMUNITY TIER (Non-Commercial Use)
8
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, merge, publish, and distribute the Software solely for personal, educational, open-source, or non-commercial purposes.
14
9
 
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
10
+ You may NOT use this Software in any commercial product, for-profit SaaS application, internal corporate tool, or revenue-generating service without purchasing a Commercial Enterprise License.
11
+
12
+ 2. COMMERCIAL ENTERPRISE TIER (Commercial Use)
13
+ If you intend to use this Software in a commercial capacity (e.g., School ERP systems, HR suites, SaaS platforms, or production deployments within a for-profit organization), you MUST purchase a valid Commercial Enterprise License.
14
+
15
+ A Commercial Enterprise License can be purchased at:
16
+ https://waniabid.gumroad.com/l/id-card-designer-pro
17
+
18
+ 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 CHANGED
@@ -1,227 +1,246 @@
1
1
  # 📦 @stratametriq/id-card-designer
2
2
 
3
- ![NPM Version](https://img.shields.io/npm/v/@stratametriq/id-card-designer?style=for-the-badge&color=blue)
4
- ![NPM Downloads](https://img.shields.io/npm/dm/@stratametriq/id-card-designer?style=for-the-badge&color=success)
5
- ![License](https://img.shields.io/npm/l/@stratametriq/id-card-designer?style=for-the-badge&color=orange)
6
-
7
3
  A universal, dynamic, and highly customizable **ID Card Designer & Batch Print Dashboard** for React, Vue, Angular, and Vanilla JS.
8
4
 
9
- Whether you are building a **Student Information System**, **HR Employee Directory**, or **Event Badge Generator**, this package gives your users a professional visual canvas to design, customize, preview, and batch export PVC ID cards directly inside your app.
5
+ > **Current release:** 1.7.0
10
6
 
11
7
  ---
12
8
 
13
9
  ## 📑 Table of Contents
14
10
 
15
- - [Installation](#installation)
16
- - [Quick Start](#quick-start)
11
+ - [Overview](#overview)
12
+ - [Live Demo](#live-demo)
17
13
  - [Features](#features)
18
- - [Props](#props)
19
- - [Templates](#templates)
20
- - [Customization](#customization)
21
- - [Events](#events)
22
- - [Examples](#examples)
14
+ - [How It Works](#how-it-works)
15
+ - [Import Data](#import-data)
16
+ - [Design Cards](#design-cards)
17
+ - [Batch Printing](#batch-printing)
18
+ - [Offline Mode](#offline-mode)
19
+ - [Privacy](#privacy)
20
+ - [Developer Docs](#developer-docs)
21
+ - [NPM](#npm)
22
+ - [Pricing / License](#pricing--license)
23
23
  - [FAQ](#faq)
24
- - [License](#license)
25
24
 
26
25
  ---
27
26
 
28
- ## 💻 Installation
27
+ ## Overview
29
28
 
30
- Install the package using NPM or Yarn:
29
+ `@stratametriq/id-card-designer` is a developer-focused ID-card design and generation package.
31
30
 
32
- ```bash
33
- npm install @stratametriq/id-card-designer
34
- # or
35
- yarn add @stratametriq/id-card-designer
36
- ```
31
+ It is designed for applications such as:
32
+ - Student Information Systems
33
+ - School and College ERP systems
34
+ - HR and Employee Management systems
35
+ - Event and Conference Badge systems
36
+ - Membership systems
37
+ - Internal identity-card workflows
37
38
 
38
- ---
39
+ 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.
39
40
 
40
- ## ⚡ Quick Start
41
+ ---
41
42
 
42
- ### 🚀 [Try the Live Interactive Demo on StackBlitz](https://stackblitz.com/edit/vitejs-vite-nurmeilk?file=package.json,src%2FApp.tsx,src%2FApp.css,src%2Findex.css&terminal=dev)
43
+ ## Live Demo
43
44
 
44
45
  You can launch a complete ID card design studio and batch print dashboard with just **two lines of code**. It comes with pre-built dummy data so you can test it immediately!
45
46
 
46
- ```jsx
47
- import { IdCardManager } from '@stratametriq/id-card-designer';
48
- import '@stratametriq/id-card-designer/dist/index.css';
47
+ ### 🚀 [Try the Live Interactive Demo on StackBlitz](https://stackblitz.com/edit/vitejs-vite-jtyvdj5g?file=src%2FApp.tsx)
49
48
 
50
- export default function App() {
51
- // This will render the complete turnkey dashboard with demo data!
52
- return <IdCardManager />;
53
- }
54
- ```
49
+ ---
50
+
51
+ ## Features
52
+
53
+ - **🎨 Visual ID Card Designer:** A complete workspace for designing ID cards with a visual canvas, configurable elements, templates, and preview capabilities.
54
+ - **📥 CSV & Excel Import:** Import structured card data from `.csv`, `.xlsx`, and `.xls`. Imported columns can be used as dynamic fields inside templates.
55
+ - **🖼️ Bulk ZIP Photo Import:** Upload a ZIP archive containing your spreadsheet/CSV and images. The importer can fuzzy-match image filenames with records, making it possible to prepare large batches of cards without manually attaching every photo.
56
+ - **🔳 QR Codes & Barcodes:** Generate dynamic QR codes and 1D barcodes and bind them to record values such as admission numbers, employee IDs, URLs, or other unique identifiers.
57
+ - **🏷️ Dynamic Field Placeholders:** Bind template elements to imported data (e.g., `ID: {{admissionNo}}`).
58
+ - **🧠 Conditional Rendering:** Text elements can use JavaScript expressions for conditional output (e.g., `{{ department === 'HR' ? 'Red' : 'Blue' }}`).
59
+ - **📐 Printer Calibration:** X/Y offsets can be applied to compensate for mechanical print alignment differences when producing physical PVC cards.
55
60
 
56
61
  ---
57
62
 
58
- ## 🌟 Features
63
+ ## How It Works
64
+
65
+ The package is designed around a client-side card-generation workflow.
66
+
67
+ ```text
68
+ CSV / Excel / JSON
69
+ ↓
70
+ Import Records
71
+ ↓
72
+ Match Photos
73
+ ↓
74
+ Design Template
75
+ ↓
76
+ Bind Dynamic Fields
77
+ ↓
78
+ Add QR / Barcode
79
+ ↓
80
+ Preview
81
+ ↓
82
+ Batch Generate
83
+ ↓
84
+ PDF / PNG
85
+ ```
59
86
 
60
- - **🎨 Turnkey Dashboard:** A complete workspace with department tabs, vector stage, and batch printing ready out-of-the-box.
61
- - **📥 Batch CSV Import:** Let users upload spreadsheets to instantly generate hundreds of cards.
62
- - **🔳 QR & Barcodes:** Built-in dynamic 1D Barcode and 2D QR Code generation.
63
- - **🏷️ Variable Placeholders:** Easily map database fields to card text (e.g., `ID: {{admissionNo}}`).
64
- - **🖼️ High-Res PDF/PNG Export:** Batch export to A3/A4/A5/Letter size PDF sheets with hardware cut marks.
65
- - **🌐 Framework Agnostic:** Works natively with React and Next.js, and easily mounts into Vue, Angular, and Vanilla HTML.
87
+ The package can be embedded into an existing web application. Your application remains responsible for its own backend, authentication, database, and business logic.
66
88
 
67
89
  ---
68
90
 
69
- ## ⚙️ Props
91
+ ## Import Data
70
92
 
71
- The main `<IdCardManager />` component accepts the following props:
93
+ ### CSV / Excel
94
+ Select **Import Data** and upload `.csv`, `.xlsx`, or `.xls` files. The importer automatically maps spreadsheet columns into dynamic fields.
72
95
 
73
- | Prop | Type | Default | Description |
74
- |---|---|---|---|
75
- | `sampleRecords` | `object` | `default data` | Pass your own database records to populate the dashboard. |
76
- | `categories` | `object` | `default config` | Custom category definitions for different ID types. |
77
- | `onBatchExportComplete` | `function` | `undefined` | Callback fired when PDF generation completes. |
78
-
79
- ### Standalone `<IdCardDesigner />` Props
80
-
81
- If you are using the standalone designer component directly, you can pass these props to configure the editor:
82
-
83
- ```jsx
84
- <IdCardDesigner
85
- width={350}
86
- height={200}
87
- template={template}
88
- onSave={handleSave}
89
- onExport={handleExport}
90
- />
96
+ ### ZIP + Photos
97
+ Prepare a ZIP containing the spreadsheet/CSV and image files.
98
+ ```text
99
+ id-cards.zip
100
+ ├── students.xlsx
101
+ └── photos/
102
+ ├── aarav_sharma.jpg
103
+ └── diya_patel.jpg
91
104
  ```
105
+ The importer attempts to fuzzy-match image filenames to the corresponding records.
92
106
 
93
107
  ---
94
108
 
95
- ## 🧩 Templates
109
+ ## Design Cards
96
110
 
97
- Designs are saved and loaded as clean JSON schemas.
111
+ Open **Launch Studio Canvas**.
98
112
 
99
- ```json
100
- {
101
- "id": "tpl_school_vertical_01",
102
- "orientation": "vertical",
103
- "width": 54,
104
- "height": 86,
105
- "elements": [
106
- {
107
- "id": "el_student_name",
108
- "type": "field",
109
- "fieldKey": "studentName",
110
- "label": "Student Name",
111
- "x": 2, "y": 48, "width": 50, "height": 7
112
- }
113
- ]
114
- }
113
+ ### Dynamic Text
114
+ Use a field placeholder:
115
+ ```text
116
+ {{studentName}}
115
117
  ```
116
118
 
119
+ ### Conditional Text
120
+ Use Javascript expressions:
121
+ ```text
122
+ {{ department === 'HR' ? 'Red' : 'Blue' }}
123
+ ```
124
+
125
+ ### QR / Barcode
126
+ Add a QR or barcode element and bind it to a unique field.
127
+
128
+ ### Background
129
+ Upload a high-resolution card background from your computer or URL, and position other elements above it.
130
+
117
131
  ---
118
132
 
119
- ## 🎨 Customization
133
+ ## Batch Printing
120
134
 
121
- You can define custom categories to control exactly what fields your ID cards should support.
135
+ Select **Batch Export A4 PDF** or the applicable export workflow.
122
136
 
123
- ```jsx
124
- const myCategories = {
125
- university: {
126
- id: "university",
127
- label: "University Students",
128
- fieldDefinitions: [
129
- { key: "studentName", label: "Student Full Name" },
130
- { key: "enrollmentNo", label: "Enrollment Number" }
131
- ]
132
- }
133
- };
137
+ The engine processes the records and places cards into printable sheets. The documented workflow includes:
138
+ - CR80 card dimensions
139
+ - A3, A4, A5, and Letter sheet sizes
140
+ - Multiple cards per sheet
141
+ - Hardware cutting marks
142
+ - X/Y print calibration offsets
134
143
 
135
- <IdCardManager categories={myCategories} />
136
- ```
144
+ ---
145
+
146
+ ## Offline Mode
137
147
 
138
- ### Modular Components
148
+ The package is designed to support workflows where ID-card data should remain on the user's machine.
139
149
 
140
- If you don't want the full dashboard, you can use our modular components:
150
+ ### Offline Workspace Persistence
151
+ The dashboard stores workspace state in the browser's IndexedDB, including imported data, templates, and active workspace information. Refreshing or reopening the browser does not automatically discard the saved workspace.
141
152
 
142
- * **`<IdCardPreview />`**: Embed a live ID card directly on a user profile page.
143
- * **`<IdCardDesignerModal />`**: Open the drag-and-drop design studio inside your own popup.
144
- * **`generateIdCardsPdf()`**: Trigger a high-resolution PDF export programmatically.
153
+ ### `.stmq` Project Backup
154
+ Export a complete project workspace as a `.stmq` JSON project file. This provides a portable way to move a workspace between machines, including offline/air-gapped workflows.
145
155
 
146
156
  ---
147
157
 
148
- ## 📡 Events
158
+ ## Privacy
149
159
 
150
- You can hook into various lifecycle and user action events across the components:
160
+ ID-card applications commonly process personal information such as Names, Student IDs, Employee IDs, Photos, and Admission numbers.
151
161
 
152
- ### `<IdCardManager />` Events
153
- - **`onBatchExportComplete(category, records)`**: Fired when a user successfully exports a batch of IDs to PDF.
162
+ The documented generation workflow is entirely **client-side**.
163
+ - Local browser processing
164
+ - IndexedDB workspace persistence
165
+ - Local `.stmq` project backup
166
+ - Local PDF/image generation
167
+ - No backend server required for the core generation workflow
154
168
 
155
- ### `<IdCardDesigner />` Events
156
- - **`onSave(templateData)`**: Fired when the user clicks the save button. Returns the full JSON schema of the current design.
157
- - **`onExport(format, data)`**: Fired when an export action is triggered (e.g., exporting a single card to PNG or PDF).
158
- - **`onChange(elementData)`**: Fired continuously as the user drags, resizes, or modifies elements on the canvas.
159
- - **`onDelete(elementId)`**: Fired when a specific element is deleted from the canvas.
160
- - **`onTemplateChange(templateId)`**: Fired when the user switches to a different template.
169
+ Your application remains responsible for compliance with applicable privacy and data-protection requirements.
161
170
 
162
171
  ---
163
172
 
164
- ## 💡 Examples
173
+ ## Developer Docs
165
174
 
166
- ### Connect Your Own Data (React)
175
+ ### Components
176
+ - `<IdCardManager />`: Complete dashboard experience. Use this when you want the complete import → design → preview → batch-export workflow.
177
+ - `<IdCardDesigner />`: Standalone visual designer.
178
+ - `<IdCardPreview />`: Embed a live ID-card preview inside another application screen.
179
+ - `<IdCardDesignerModal />`: Open the designer inside your application's modal/dialog workflow.
167
180
 
168
- ```jsx
169
- import { IdCardManager } from '@stratametriq/id-card-designer';
170
- import '@stratametriq/id-card-designer/dist/index.css';
171
-
172
- export default function MyPortal() {
173
- const myRealStudents = [
174
- { studentName: "Aarav Sharma", admissionNo: "101", bloodGroup: "O+" },
175
- { studentName: "Diya Patel", admissionNo: "102", bloodGroup: "B+" }
176
- ];
181
+ ### Props (IdCardManager)
182
+ | Prop | Type | Default | Description |
183
+ |---|---|---|---|
184
+ | `sampleRecords` | `object` | Default data | Records used to populate the dashboard |
185
+ | `categories` | `object` | Default config | Custom ID-card categories |
186
+ | `onBatchExportComplete` | `function` | `undefined` | Callback after batch PDF generation |
177
187
 
178
- return (
179
- <IdCardManager sampleRecords={{ student: myRealStudents }} />
180
- );
188
+ ### Templates
189
+ Designs are represented as JSON-compatible template structures.
190
+ ```json
191
+ {
192
+ "id": "tpl_school_vertical",
193
+ "orientation": "vertical",
194
+ "width": 54,
195
+ "height": 86,
196
+ "elements": []
181
197
  }
182
198
  ```
183
199
 
184
- ### Mounting in Vue, Angular, or Vanilla HTML
200
+ ---
201
+
202
+ ## NPM
185
203
 
186
- ```html
187
- <div id="id-card-manager-root"></div>
188
- <script type="module">
189
- import React from 'react';
190
- import { createRoot } from 'react-dom/client';
191
- import { IdCardManager } from '@stratametriq/id-card-designer';
192
- import '@stratametriq/id-card-designer/dist/index.css';
204
+ Install using NPM:
205
+ ```bash
206
+ npm install @stratametriq/id-card-designer
207
+ ```
193
208
 
194
- const root = createRoot(document.getElementById('id-card-manager-root'));
195
- root.render(React.createElement(IdCardManager));
196
- </script>
209
+ Or Yarn:
210
+ ```bash
211
+ yarn add @stratametriq/id-card-designer
197
212
  ```
198
213
 
199
214
  ---
200
215
 
201
- ## ❓ FAQ & Comparisons
216
+ ## Pricing / License
202
217
 
203
- **Q: How is this different from Canva?**
204
- **A:** Canva is fantastic for creating manual, one-off designs. However, if you need to generate 500 student ID cards with unique photos, barcodes, and names, Canva becomes tedious. This package is an **automation pipeline**—you design the template once, feed it an array of JSON data, and instantly generate thousands of unique cards.
218
+ `@stratametriq/id-card-designer` operates under a **Dual Licensing Model** to support both the open-source community and enterprise development.
205
219
 
206
- **Q: Why not just use standard HTML-to-Image libraries directly?**
207
- **A:** Building a production-ready ID card designer from scratch using standard HTML-to-canvas libraries is incredibly frustrating. You have to handle exact hardware printing dimensions (like CR80 PVC card aspect ratios), perfect image scaling, drag-and-drop boundary logic, and multi-page A4 PDF rendering with precise cut-marks. We've solved all of that complex math for you out-of-the-box.
220
+ ### 1. Community Tier (Free)
221
+ Free for personal projects, students, open-source initiatives, and non-profit organizations. Under this tier, you may not use the software in any commercial product or revenue-generating service.
208
222
 
209
- **Q: How does this compare to enterprise desktop ID software?**
210
- **A:** Traditional ID software usually requires heavy Windows installations and expensive per-seat licenses. This package allows you to bring that exact same enterprise-level design capability directly into your web app as a lightweight React component that works on Mac, Windows, and Linux.
223
+ ### 2. Commercial / Enterprise Tier (Paid)
224
+ Required for any commercial use, including:
225
+ - Commercial SaaS applications
226
+ - School & College ERP systems
227
+ - HR & Employee Management suites
228
+ - Internal corporate production deployments
229
+ - White-label applications
211
230
 
212
- **Q: Does our sensitive data leave our servers?**
213
- **A:** **Absolutely not.** Employee and student data (PII) is a massive security concern. That is why this engine runs **100% Client-Side** in the browser. Zero network requests are made to external servers. The PDFs and images are generated purely on the user's local machine.
231
+ 👉 **[Purchase a Commercial Enterprise License Here](https://waniabid.gumroad.com/l/id-card-designer-pro)**
214
232
 
215
- **Q: Can I remove your branding? (White-labeling)**
216
- **A:** Yes! The enterprise license is 100% white-label, allowing you to seamlessly integrate the designer into your own SaaS product without your users ever knowing you are using our software.
233
+ *For full legal terms, please review the `LICENSE` file included in this repository.*
217
234
 
218
235
  ---
219
236
 
220
- ## 📜 License
237
+ ## FAQ
221
238
 
222
- `@stratametriq/id-card-designer` is dual-licensed:
239
+ **How is this different from Canva?**
240
+ Canva is designed primarily for visual design. `@stratametriq/id-card-designer` focuses on an automated data-driven ID-card workflow: One Template + Many Records = Batch Printable ID Cards.
223
241
 
224
- 1. **Community / Open Source Tier (MIT License):** Free for non-commercial evaluation and personal open-source projects. See [MIT License](./LICENSE).
225
- 2. **Commercial / Enterprise Tier:** Required for commercial SaaS applications, School ERPs, HR suites, and production use.
242
+ **Does the core workflow require a StrataMetriq server?**
243
+ No backend server from StrataMetriq is required for the documented client-side card-generation workflow.
226
244
 
227
- 👉 **[Purchase a Commercial Enterprise License to Unlock Production Usage & Priority Support](https://waniabid.gumroad.com/l/id-card-designer-pro)**
245
+ **Can it be used for offline workflows?**
246
+ Yes. The package includes IndexedDB workspace persistence and `.stmq` project backup capabilities intended to support local and offline-capable workflows.