@stratametriq/id-card-designer 1.17.0 → 1.17.1

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.17.0
+> **Current release:** 1.17.1
 
 ---
 
@@ -11,9 +11,10 @@ A universal, dynamic, and highly customizable **ID Card Designer & Batch Print D
 - [Overview](#overview)
 - [Live Demo](#live-demo)
 - [Pricing / License](#pricing--licensing-important)
+- [What's New in v1.17.1](#whats-new-in-v1171)
 - [What's New in v1.17.0](#whats-new-in-v1170)
-- [What's New in v1.16.0](#whats-new-in-v1160)
-- [What's New in v1.15.0](#whats-new-in-v1150)
+- [What's New in v1.16.0](#whats-new-in-v160)
+- [What's New in v1.15.0](#whats-new-in-v150)
 - [Features](#features)
 - [Enterprise Roles & Permissions (RBAC)](#enterprise-roles--permissions-rbac)
 - [Enterprise Audit Logs & Access Trail](#enterprise-audit-logs--access-trail)
@@ -76,11 +77,27 @@ Free for personal projects, students, open-source initiatives, and non-profit or
 
 ---
 
+## What's New in v1.17.1
+- **👥 Team User Provisioning Cockpit & Granular Permission Editor:**
+  - Expanded `<RoleSwitcherModal />` with a full-featured operator management dashboard supporting **+ Add User**, **Edit User**, and **Delete User**.
+  - **15-Permission Granular Matrix:** Super Admins can customize exact privileges (Templates, Rosters, Issuance/Security, Compliance Audit) for any operator with live checkbox toggles and real-time counter badges (`X of 15 Perms`).
+  - **Protected Primary Super Admin:** Safety guardrails preventing accidental deletion or demotion of the root system administrator.
+- **🌐 Open-Source Neutral Identity Architecture:**
+  - Removed hardcoded personal names from the public library core in favor of neutral `System Administrator` (`admin@organization.com`, `isPrimaryAdmin: true`).
+  - Seamlessly accepts the host application's authenticated session user via `<IdCardManager currentUser={session.user} />` so that whoever signs in first becomes the active Super Admin.
+- **⚡ Production SaaS Real Database Synchronization:**
+  - Added turnkey database synchronization props: `users`, `onAddUser`, `onUpdateUser`, and `onDeleteUser` enabling direct connection to PostgreSQL, Supabase, MySQL, MongoDB, Firebase, Laravel, and REST/GraphQL backends.
+  - **Dual-Mode Persistence:** Automatically switches to browser IndexedDB (`localforage`) when database callback props are omitted, guaranteeing offline resilience and zero-config prototyping.
+- **🏷️ Master Header Operator Identity Pill:**
+  - Top-right profile pill and studio canvas persona pill dynamically reflect the authenticated operator's avatar, full name, and role badge, with instant 1-click access to the User & Role Management Cockpit.
+- **📦 Public Utility Exports:**
+  - Exported `getUserPermissions` and `STORAGE_KEY_USERS` (`ricd_users_v1`) from `@stratametriq/id-card-designer`.
+
 ## What's New in v1.17.0
 - **👥 Enterprise Role-Based Access Control (RBAC):** Complete, modular RBAC architecture designed for institutional ERPs, healthcare portals, universities, and enterprise identity deployments.
   - **15 Granular Permissions:** Structured across Card Templates (`templates:read`, `templates:write`, `templates:history`), Cardholder Rosters (`records:read`, `records:create`, `records:edit`, `records:delete`, `records:import`, `records:export`), Production & Issuance (`issuance:export`), Physical Security (`security:verify`, `security:revoke`), Organization & Branch Management (`org:manage`), and Compliance Audit Trails (`audit:view`, `audit:clear`).
   - **6 Pre-Configured Personas:** Complete with avatars, departments, colors, and badge tokens:
-    - 🛡️ **Super Admin** (`Dr. Arthur Pendelton`): Full unrestricted authority across all features, settings, and purge actions.
+    - 🛡️ **Super Admin** (`System Administrator` / Host App Session User): Full unrestricted authority across all features, settings, and purge actions.
     - 🎨 **Template Designer** (`Maya Lin`): Visual canvas drafting, element styling, watermark management, and revision history. Rosters and batch printing are locked.
     - 📋 **Data Registrar** (`Rahul Mehta`): Cardholder profiles, CSV/Excel/ZIP data imports, and webcam photo capture. Template layouts and record deletions are locked.
     - 🖨️ **Issuance Officer** (`Carlos Mendez`): High-resolution 300 DPI batch PDF rendering and ZIP package downloads. Template layouts and record deletions are locked.
@@ -309,6 +326,69 @@ function DevSandbox() {
     </>
   );
 }
+### 7. Real SaaS Production Database vs Offline Test Data
+
+`@stratametriq/id-card-designer` is designed with a **Dual-Architecture Model** so it works immediately out-of-the-box for prototyping, but easily connects to real cloud databases in live SaaS production:
+
+#### Mode A: Standalone / Offline Mode (Test Data)
+* **How it works:** When you don't provide backend callback props, the package uses browser `IndexedDB` (`localforage`).
+* **Use case:** Local testing, offline desktop applications, or quick client-side demos without needing a backend server.
+* **Behavior:** Any user created or permission modified is saved inside the local browser.
+
+#### Mode B: Live SaaS Production Mode (Real Cloud Database)
+* **How it works:** In multi-user SaaS deployments, connect `<IdCardManager />` directly to your real API endpoints (PostgreSQL, Supabase, MySQL, MongoDB, Firebase, Laravel, Node.js):
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import { IdCardManager } from '@stratametriq/id-card-designer';
+
+export default function SaaSIdentityApp({ activeAuthUser }) {
+  const [realUsers, setRealUsers] = useState([]);
+
+  // 1. Fetch real team users from your backend API
+  useEffect(() => {
+    fetch('/api/v1/organization/users')
+      .then(res => res.json())
+      .then(data => setRealUsers(data));
+  }, []);
+
+  return (
+    <IdCardManager
+      // Pass the real authenticated session user (Super Admin or Operator)
+      currentUser={activeAuthUser}
+      
+      // Pass live database users array
+      users={realUsers}
+
+      // Real Database Sync: Create user in your backend DB
+      onAddUser={async (newUser) => {
+        const response = await fetch('/api/v1/organization/users', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(newUser)
+        });
+        const savedUser = await response.json();
+        setRealUsers(prev => [...prev, savedUser]);
+      }}
+
+      // Real Database Sync: Update role / permissions in your backend DB
+      onUpdateUser={async (updatedUser) => {
+        await fetch(`/api/v1/organization/users/${updatedUser.id}`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(updatedUser)
+        });
+        setRealUsers(prev => prev.map(u => u.id === updatedUser.id ? updatedUser : u));
+      }}
+
+      // Real Database Sync: Delete user from your backend DB
+      onDeleteUser={async (userId) => {
+        await fetch(`/api/v1/organization/users/${userId}`, { method: 'DELETE' });
+        setRealUsers(prev => prev.filter(u => u.id !== userId));
+      }}
+    />
+  );
+}
 ```
 
 ---
@@ -610,6 +690,10 @@ Your application remains responsible for compliance with applicable privacy and
 | `showRoleSwitcher` | `boolean` | `true` | Toggle display of the header operator persona switcher pill / modal |
 | `initialAuditLogs` | `array` | `null` | Array of historical audit entries to populate `<AuditLogModal />` |
 | `onAuditLog` | `function` | `undefined` | Callback `(auditEntry) => void` fired whenever an auditable action occurs (ideal for SIEM / database sync) |
+| `users` | `array` | `null` | Real team users array from your backend database (`[{ id, name, email, role, ... }]`). When omitted, uses local IndexedDB |
+| `onAddUser` | `function` | `undefined` | Callback `async (newUser) => void` to persist a new operator in your backend database API |
+| `onUpdateUser` | `function` | `undefined` | Callback `async (updatedUser) => void` to persist modified operator permissions in your backend database API |
+| `onDeleteUser` | `function` | `undefined` | Callback `async (userId) => void` to delete an operator from your backend database API |
 
 ### Public Package Exports