From da602f69af738fb697d26f4991958cd909876782 Mon Sep 17 00:00:00 2001 From: jason Date: Sat, 7 Mar 2026 21:46:30 -0600 Subject: [PATCH] docs: update ReadmeModal admin guide for acknowledgment signature and toast notifications - Added acknowledgment signature workflow to "Logging a Violation" section (step 7) - Added toast notification step to violation logging workflow (step 9) - Updated Violation History section: amend now includes acknowledged-by/date fields - Added PDF acknowledgment rendering note to Violation History - Added "Toast Notifications" as standalone feature section - Updated Amendable Fields to include acknowledged_by and acknowledged_date - Updated Immutability Rules table with ack fields - Moved acknowledgment signature and toast system to Shipped in roadmap - Removed acknowledgment signature from Near-term (already shipped) --- client/src/components/ReadmeModal.jsx | 39 ++++++++++++++++++++------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/client/src/components/ReadmeModal.jsx b/client/src/components/ReadmeModal.jsx index 8819b89..fee0a27 100644 --- a/client/src/components/ReadmeModal.jsx +++ b/client/src/components/ReadmeModal.jsx @@ -23,8 +23,8 @@ function mdToHtml(md) { const hm = line.match(/^(#{1,4})\s+(.+)/); if (hm) { close(); const lv=hm[1].length, id=hm[2].toLowerCase().replace(/[^a-z0-9]+/g,'-'); out.push(`${inline(hm[2])}`); i++; continue; } if (line.trim().startsWith('|')) { - const cells = line.trim().replace(/^\||\|$/g,'').split('|').map(c=>c.trim()); - if (!inTable) { close(); inTable=true; out.push(''); cells.forEach(c=>out.push(``)); out.push(''); i++; if (i < lines.length && /^[\|\s\-:]+$/.test(lines[i])) i++; continue; } + const cells = line.trim().replace(/^\|||\|$/g,'').split('|').map(c=>c.trim()); + if (!inTable) { close(); inTable=true; out.push('
${inline(c)}
'); cells.forEach(c=>out.push(``)); out.push(''); i++; if (i < lines.length && /^[\|\s\:\-]+$/.test(lines[i])) i++; continue; } else { out.push(''); cells.forEach(c=>out.push(``)); out.push(''); i++; continue; } } const ul = line.match(/^[-*]\s+(.*)/); @@ -46,7 +46,7 @@ function buildToc(md) { }, []); } -// ─── Styles ─────────────────────────────────────────────────────────────────── +// ——— Styles —————————————————————————————————————————————————————————————————— const S = { overlay: { position:'fixed', inset:0, background:'rgba(0,0,0,0.75)', zIndex:2000, display:'flex', alignItems:'flex-start', justifyContent:'flex-end' }, panel: { background:'#111217', color:'#f8f9fa', width:'760px', maxWidth:'95vw', height:'100vh', overflowY:'auto', boxShadow:'-4px 0 32px rgba(0,0,0,0.85)', display:'flex', flexDirection:'column' }, @@ -76,7 +76,7 @@ const CSS = ` .adm tr:hover td { background:#1e1f2e } `; -// ─── Admin guide content (no install / Docker content) ──────────────────────── +// ——— Admin guide content (no install / Docker content) ———————————————————— const GUIDE_MD = `# CPAS Tracker — Admin Guide Internal tool for CPAS violation documentation, workforce standing management, and audit compliance. All data is stored locally in the Docker container volume — there is no external dependency. @@ -129,7 +129,9 @@ Use the **+ New Violation** tab. 4. If the employee has a prior violation of the same type, the **recidivist auto-escalation** rule triggers — the points slider jumps to the maximum allowed for that violation type. 5. The **tier crossing warning** previews what tier the submission would land the employee in. Review before submitting. 6. Adjust points using the slider if discretionary reduction is warranted (within the violation's allowed min/max range). -7. Submit. A **PDF download link** appears immediately — download it for the employee's file. +7. **Employee Acknowledgment** (optional): if the employee is present and acknowledges receipt, enter their printed name and the acknowledgment date. This replaces the blank signature line on the PDF with a recorded acknowledgment and an "Acknowledged" badge. Leave blank if the employee is not present or declines. +8. Submit. A **PDF download link** appears immediately — download it for the employee's file. +9. **Toast notifications** confirm success or surface errors at the top right of the screen. Toasts auto-dismiss after a few seconds. --- @@ -149,10 +151,12 @@ Visible when the employee has active points. Shows each active violation as a pr #### Violation History Full record of all submissions — active, negated, and resolved. -- **Amend** — edit non-scoring fields (location, details, witness, submitted-by, incident time) on any active violation. Every change is logged as a field-level diff (old → new) with timestamp. Points, type, and incident date are immutable. +- **Amend** — edit non-scoring fields (location, details, witness, submitted-by, incident time, acknowledged-by, acknowledged-date) on any active violation. Every change is logged as a field-level diff (old → new) with timestamp. Points, type, and incident date are immutable. - **Negate** — soft-delete a violation with a resolution type and notes. The record is preserved in history; the points are immediately removed from the score. Fully reversible via **Restore**. - **Hard delete** — permanent removal. Use only for genuine data entry errors. -- **PDF** — download the formal violation document for any historical record. +- **PDF** — download the formal violation document for any historical record. If the violation has an employee acknowledgment on record, the PDF shows the filled-in name and date instead of blank signature lines. + +All actions trigger **toast notifications** confirming success or surfacing errors. #### Edit Employee Update name, department, or supervisor. Changes are logged to the audit trail. @@ -178,7 +182,7 @@ The audit log is the authoritative record for compliance review. Nothing in it c Amendments allow corrections to a violation's non-scoring fields without deleting and re-submitting, which would disrupt the audit trail and the prior-points snapshot. -**Amendable fields:** incident time, location, details, submitted-by, witness name. +**Amendable fields:** incident time, location, details, submitted-by, witness name, acknowledged-by, acknowledged-date. **Immutable fields:** violation type, incident date, point value. @@ -186,6 +190,19 @@ Each amendment stores a before/after diff for every changed field. Amendment his --- +### Toast Notifications + +All user actions across the application produce **toast notifications** — small slide-in messages at the top right of the screen. + +- **Success** (green) — violation submitted, PDF downloaded, employee updated, etc. +- **Error** (red) — API failures, validation errors, PDF generation issues +- **Warning** (gold) — missing required fields, policy alerts +- **Info** (blue) — general informational messages + +Toasts auto-dismiss after a few seconds (errors persist longer). Each toast has a progress bar countdown and a manual dismiss button. Up to 5 toasts can stack simultaneously. + +--- + ## Immutability Rules — Quick Reference | Action | Allowed? | Notes | @@ -194,6 +211,7 @@ Each amendment stores a before/after diff for every changed field. Amendment his | Edit incident date | No | Immutable after submission | | Edit point value | No | Immutable after submission | | Edit location / details / witness | Yes | Via Amend | +| Edit acknowledged-by / acknowledged-date | Yes | Via Amend | | Negate (void) a violation | Yes | Soft delete; reversible | | Hard delete a violation | Yes | Permanent; use sparingly | | Edit employee name / dept / supervisor | Yes | Logged to audit trail | @@ -217,6 +235,8 @@ Each amendment stores a before/after diff for every changed field. Amendment his - Employee notes and flags with quick-add HR tags - Point expiration timeline with tier-drop projections - In-app admin guide (this panel) +- Acknowledgment signature field — employee name + date on form and PDF +- Toast notification system — global feedback for all user actions --- @@ -224,7 +244,6 @@ Each amendment stores a before/after diff for every changed field. Amendment his These are well-scoped additions that fit the current architecture without major changes. -- **Acknowledgment signature field** — "received by employee" name + date on the violation form; prints on the PDF in place of the blank signature line. Addresses the most common field workflow gap. - **CSV export** — one endpoint returning violations or dashboard data as a downloadable CSV for payroll or external reporting. - **Supervisor-scoped view** — filter the dashboard to a single supervisor's team via URL param; useful in multi-supervisor environments without requiring full auth. @@ -253,7 +272,7 @@ These require meaningful infrastructure additions and should be evaluated agains - **Dark/light theme toggle** — UI is currently dark-only. `; -// ─── Component ──────────────────────────────────────────────────────────────── +// ——— Component —————————————————————————————————————————————————————————————— export default function ReadmeModal({ onClose }) { const bodyRef = useRef(null); const html = mdToHtml(GUIDE_MD);
${inline(c)}
${inline(c)}