From 362f5bd03646c2272a7fcd488de2982a926e95d8 Mon Sep 17 00:00:00 2001
From: ZDDC <caseywitt@proton.me>
Date: Mon, 8 Jun 2026 18:50:48 -0500
Subject: [PATCH] chore(embedded): cut v0.0.27-beta

---
 zddc/internal/apps/embedded/archive.html     |   2 +-
 zddc/internal/apps/embedded/browse.html      |   2 +-
 zddc/internal/apps/embedded/classifier.html  |   2 +-
 zddc/internal/apps/embedded/index.html       |   2 +-
 zddc/internal/apps/embedded/transmittal.html |   2 +-
 zddc/internal/apps/embedded/versions.txt     |  14 +-
 zddc/internal/handler/tables.html            | 188 +++++++++++++++++--
 7 files changed, 184 insertions(+), 28 deletions(-)

diff --git a/zddc/internal/apps/embedded/archive.html b/zddc/internal/apps/embedded/archive.html
index 4afc32e..4ceaffa 100644
--- a/zddc/internal/apps/embedded/archive.html
+++ b/zddc/internal/apps/embedded/archive.html
@@ -2665,7 +2665,7 @@ td[data-field="trackingNumber"] {
                 </svg>
                 <div class="header-title-group">
                     <span class="app-header__title">ZDDC Archive</span>
-                    <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 20:19:35 · ec9c9c7</span></span>
+                    <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 23:50:40 · 0326d46</span></span>
                 </div>
                 <button id="addDirectoryBtn" class="btn btn-primary">Use Local Directory</button>
                 <button id="refreshHeaderBtn" class="btn btn-secondary hidden" title="Refresh Data">⟳</button>
diff --git a/zddc/internal/apps/embedded/browse.html b/zddc/internal/apps/embedded/browse.html
index 317cbe0..f01bcf4 100644
--- a/zddc/internal/apps/embedded/browse.html
+++ b/zddc/internal/apps/embedded/browse.html
@@ -2772,7 +2772,7 @@ li.CodeMirror-hint-active {
             </svg>
             <div class="header-title-group">
                 <span class="app-header__title">ZDDC Browse</span>
-                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7</span></span>
+                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46</span></span>
             </div>
             <button id="addDirectoryBtn" class="btn btn-primary">Use Local Directory</button>
             <button id="refreshHeaderBtn" class="btn btn-secondary hidden" title="Refresh listing" aria-label="Refresh listing">⟳</button>
diff --git a/zddc/internal/apps/embedded/classifier.html b/zddc/internal/apps/embedded/classifier.html
index 8b0857a..50df92d 100644
--- a/zddc/internal/apps/embedded/classifier.html
+++ b/zddc/internal/apps/embedded/classifier.html
@@ -1876,7 +1876,7 @@ body.is-elevated::after {
                     </svg>
                     <div class="header-title-group">
                         <span class="app-header__title">ZDDC Classifier</span>
-                        <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7</span></span>
+                        <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46</span></span>
                     </div>
                     <button id="addDirectoryBtn" class="btn btn-primary">Use Local Directory</button>
                     <button id="refreshHeaderBtn" class="btn btn-secondary hidden" title="Refresh and rescan directory" aria-label="Refresh" style="font-size:1.1rem;">⟳</button>
diff --git a/zddc/internal/apps/embedded/index.html b/zddc/internal/apps/embedded/index.html
index 3f002c4..56a2d06 100644
--- a/zddc/internal/apps/embedded/index.html
+++ b/zddc/internal/apps/embedded/index.html
@@ -1619,7 +1619,7 @@ body {
             </svg>
             <div class="header-title-group">
                 <span class="app-header__title">ZDDC</span>
-                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7</span></span>
+                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46</span></span>
             </div>
         </div>
         <div class="header-right">
diff --git a/zddc/internal/apps/embedded/transmittal.html b/zddc/internal/apps/embedded/transmittal.html
index e2a9a4d..62d14d4 100644
--- a/zddc/internal/apps/embedded/transmittal.html
+++ b/zddc/internal/apps/embedded/transmittal.html
@@ -2718,7 +2718,7 @@ dialog.modal--narrow {
             </svg>
             <div class="header-title-group">
                 <span class="app-header__title">ZDDC Transmittal</span>
-                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 20:19:35 · ec9c9c7</span></span>
+                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 23:50:40 · 0326d46</span></span>
             </div>
             <span id="no-js-notice" class="text-gray-400 text-xs italic">JavaScript not available</span>
             <!-- Publish split-button (Transmittal-specific primary action;
diff --git a/zddc/internal/apps/embedded/versions.txt b/zddc/internal/apps/embedded/versions.txt
index 8745b26..4ad0f7c 100644
--- a/zddc/internal/apps/embedded/versions.txt
+++ b/zddc/internal/apps/embedded/versions.txt
@@ -1,8 +1,8 @@
 # Generated by build.sh — do not edit. One <app>=<build label> per line.
-archive=v0.0.27-beta · 2026-06-08 20:19:35 · ec9c9c7
-transmittal=v0.0.27-beta · 2026-06-08 20:19:35 · ec9c9c7
-classifier=v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7
-landing=v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7
-form=v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7
-tables=v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7
-browse=v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7
+archive=v0.0.27-beta · 2026-06-08 23:50:40 · 0326d46
+transmittal=v0.0.27-beta · 2026-06-08 23:50:40 · 0326d46
+classifier=v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46
+landing=v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46
+form=v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46
+tables=v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46
+browse=v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46
diff --git a/zddc/internal/handler/tables.html b/zddc/internal/handler/tables.html
index efbdd3e..0c9a0a3 100644
--- a/zddc/internal/handler/tables.html
+++ b/zddc/internal/handler/tables.html
@@ -1398,6 +1398,28 @@ body.is-elevated::after {
     color: var(--color-text, #111);
 }
 
+/* Mandatory-column marker in the header. */
+.zddc-table__req {
+    color: var(--color-error, #c14242);
+    font-weight: 700;
+}
+.zddc-table__th--required {
+    /* subtle cue beyond the asterisk */
+}
+
+/* Inline error row — a full-width message inserted directly beneath a row
+   that failed to save, so the reason is visible in place (not just a hover
+   tooltip or the status bar). */
+.zddc-table__error-row > .zddc-table__error-cell {
+    padding: 5px var(--spacing-md, 0.8rem);
+    background: var(--color-bg-error, rgba(193, 66, 66, 0.10));
+    color: var(--color-error, #c14242);
+    border-bottom: 1px solid var(--color-error, #c14242);
+    font-size: 0.85rem;
+    line-height: 1.4;
+    white-space: normal;
+}
+
 .table-empty {
     padding: var(--spacing-lg) var(--spacing-md);
     text-align: center;
@@ -1648,7 +1670,7 @@ body.is-elevated::after {
             </svg>
             <div class="header-title-group">
                 <span class="app-header__title" id="table-title">ZDDC Table</span>
-                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 20:19:36 · ec9c9c7</span></span>
+                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.27-beta · 2026-06-08 23:50:41 · 0326d46</span></span>
             </div>
         </div>
         <div class="header-right">
@@ -4629,7 +4651,9 @@ body.is-elevated::after {
         if (!t) return null;
         const tbody = t.querySelector('tbody');
         if (!tbody) return null;
-        const tr = tbody.children[r];
+        // Index over DATA rows only — inline error rows (no data-row-id,
+        // see save.js showRowError) must not shift the editor's row indices.
+        const tr = tbody.querySelectorAll('tr[data-row-id]')[r];
         if (!tr) return null;
         return tr.querySelector('[role="gridcell"][data-col-idx="' + c + '"]');
     }
@@ -4648,7 +4672,7 @@ body.is-elevated::after {
     function rowCount() {
         const t = tableEl();
         if (!t) return 0;
-        return t.querySelectorAll('tbody > tr').length;
+        return t.querySelectorAll('tbody > tr[data-row-id]').length;
     }
 
     function colCount() {
@@ -4668,7 +4692,7 @@ body.is-elevated::after {
         // in sync by main.js paint()).
         const t = tableEl();
         if (!t) return null;
-        const tr = t.querySelectorAll('tbody > tr')[r];
+        const tr = t.querySelectorAll('tbody > tr[data-row-id]')[r];
         if (!tr) return null;
         const rowId = tr.getAttribute('data-row-id');
         if (rowId == null) return null;
@@ -5614,15 +5638,18 @@ body.is-elevated::after {
     };
 })(window.tablesApp);
 
-// add-row.js — inline new-row creation.
+// add-row.js — new-row creation.
 //
-// Click "+ Add row" → append a draft row at the end of state.rows,
-// focus its first editable cell, accumulate user typing into the
-// drafts buffer like any other row. On row-blur, save.js detects the
-// row.isNew flag and POSTs to <dir>/form.html (the form-create
-// endpoint). The 201 response carries the new row's Location; we swap
-// the synthetic url/yamlUrl for the real ones and the draft row
-// becomes a normal saved row.
+// Two paths, chosen by the table's schema:
+//   - Record-tables (identity composed from required fields that aren't
+//     columns — e.g. the risk register's tracking-number components): "+ Add
+//     row" navigates to the compose form (<dir>/form.html), the only place
+//     those components can be supplied. See needsComposeForm().
+//   - Simple tables (all required fields are columns): "+ Add row" appends a
+//     draft row at the end of state.rows, focuses its first editable cell, and
+//     accumulates typing into the drafts buffer like any other row. On
+//     row-blur, save.js detects row.isNew and POSTs to <dir>/form.html; the
+//     201 Location swaps the synthetic url and the draft becomes a saved row.
 //
 // Synthetic identity: each new row gets a temporary "__new-<N>" url
 // so rowKey() returns something unique for selection + draft tracking.
@@ -5650,8 +5677,29 @@ body.is-elevated::after {
         return dir + 'form.html';
     }
 
-    // Create-and-paint: the user-facing path.
+    // True when a new record's identity is composed from required fields that
+    // AREN'T table columns (e.g. the risk register's project/discipline/
+    // sequence tracking-number components). Such rows can't be created by
+    // typing into the grid — they need the compose form. Server mode only
+    // (the form handler is server-side).
+    function needsComposeForm() {
+        const ctx = app.context || {};
+        if (!app.state || app.state.source !== 'server') return false;
+        const req = (ctx.rowSchema && Array.isArray(ctx.rowSchema.required)) ? ctx.rowSchema.required : [];
+        if (!req.length) return false;
+        const colFields = {};
+        (ctx.columns || []).forEach(function (c) { if (c && c.field) colFields[c.field] = true; });
+        return req.some(function (f) { return !colFields[f]; });
+    }
+
+    // Create-and-paint: the user-facing path. Record-tables (composed identity)
+    // open the compose form directly — the grid can't supply their
+    // tracking-number components; simple tables append an inline draft row.
     function invoke() {
+        if (needsComposeForm()) {
+            window.location.href = formCreateUrl();
+            return;
+        }
         const key = createSilent();
         if (typeof app.repaint === 'function') app.repaint();
         focusNewRow(key);
@@ -5856,6 +5904,85 @@ body.is-elevated::after {
         }
     }
 
+    // --- Required-field validation + inline row errors ----------------
+
+    // Required fields the table can actually enforce: the row schema's
+    // `required` list intersected with the visible COLUMNS. Required fields
+    // that aren't columns (e.g. the risk register's project/discipline/
+    // sequence tracking-number components, composed server-side or set via the
+    // add-row form) are NOT inline-fillable, so the client must not block on
+    // them — the server validates those (and composes them) authoritatively.
+    function requiredFields() {
+        const ctx = app.context || {};
+        const req = (ctx.rowSchema && Array.isArray(ctx.rowSchema.required)) ? ctx.rowSchema.required : [];
+        const colFields = {};
+        (ctx.columns || []).forEach(function (c) { if (c && c.field) colFields[c.field] = true; });
+        return req.filter(function (f) { return colFields[f]; });
+    }
+
+    // Human label for a field — the column title, else the field name.
+    function colTitle(field) {
+        const cols = (app.context && app.context.columns) || [];
+        for (let i = 0; i < cols.length; i++) {
+            if (cols[i].field === field) return cols[i].title || field;
+        }
+        return field;
+    }
+
+    function isEmptyValue(v) {
+        return v === undefined || v === null
+            || (typeof v === 'string' && v.trim() === '')
+            || (Array.isArray(v) && v.length === 0);
+    }
+
+    // Client-side required check before a PUT/POST. Marks the empty required
+    // cells, shows an inline row error naming them, and returns true (invalid)
+    // so the caller skips the request. The server still validates (422) as the
+    // authority; this is immediate, names the fields, and avoids a round-trip.
+    function validateRequired(rowId, merged) {
+        const req = requiredFields();
+        if (!req.length) return false;
+        const missing = [];
+        for (let i = 0; i < req.length; i++) {
+            if (isEmptyValue(merged ? merged[req[i]] : undefined)) missing.push(req[i]);
+        }
+        if (!missing.length) return false;
+        clearCellInvalid(rowId);
+        for (let j = 0; j < missing.length; j++) markCellInvalid(rowId, missing[j], 'Required');
+        setRowState(rowId, 'invalid');
+        showRowError(rowId, 'Can’t save — required: ' + missing.map(colTitle).join(', '));
+        return true;
+    }
+
+    // Inline error row: a full-width message inserted directly beneath the
+    // offending data row, so "why it won't save" is visible in place (not just
+    // a hover title or the far-off status bar). Carries data-error-for (NOT
+    // data-row-id) so the editor's row indexing skips it.
+    function showRowError(rowId, message) {
+        const tbody = document.querySelector('#table-root tbody');
+        if (!tbody) return;
+        const tr = tbody.querySelector('tr[data-row-id="' + cssEscape(rowId) + '"]');
+        if (!tr) return;
+        clearRowError(rowId);
+        const cols = (app.context && app.context.columns) || [];
+        const er = document.createElement('tr');
+        er.className = 'zddc-table__error-row';
+        er.setAttribute('data-error-for', rowId);
+        const td = document.createElement('td');
+        td.className = 'zddc-table__error-cell';
+        td.colSpan = Math.max(1, cols.length);
+        td.textContent = '⚠ ' + message;
+        er.appendChild(td);
+        tr.parentNode.insertBefore(er, tr.nextSibling);
+    }
+
+    function clearRowError(rowId) {
+        const tbody = document.querySelector('#table-root tbody');
+        if (!tbody) return;
+        const er = tbody.querySelector('tr.zddc-table__error-row[data-error-for="' + cssEscape(rowId) + '"]');
+        if (er && er.parentNode) er.parentNode.removeChild(er);
+    }
+
     function cssEscape(s) {
         // CSS.escape if available; otherwise a defensive escape for
         // the characters that appear in URL paths used as data-row-id
@@ -5939,8 +6066,9 @@ body.is-elevated::after {
             return { status: 'readonly' };
         }
 
-        setRowState(rowId, 'saving');
         const merged = mergeRow(row.data, drafts);
+        if (validateRequired(rowId, merged)) return { status: 'invalid-required' };
+        setRowState(rowId, 'saving');
         const yamlBody = window.jsyaml.dump(merged);
 
         const headers = { 'Content-Type': 'application/yaml; charset=utf-8' };
@@ -5966,6 +6094,7 @@ body.is-elevated::after {
             // network error. Mark errored, drafts stay.
             console.error('[tables] save network error', err);
             setRowState(rowId, 'errored');
+            showRowError(rowId, 'Couldn’t save — network error. Your edits are kept; try again.');
             return { status: 'network-error', error: err };
         }
 
@@ -5992,6 +6121,7 @@ body.is-elevated::after {
             row.data = serverData || merged;
             delete app.state.drafts[rowId];
             clearCellInvalid(rowId);
+            clearRowError(rowId);
             setRowState(rowId, '');
             // If a status prompt was up for this row, drop it.
             const sb = document.getElementById('table-status');
@@ -6033,17 +6163,21 @@ body.is-elevated::after {
             try { body = await resp.json(); } catch (_) { /* ignore */ }
             clearCellInvalid(rowId);
             const errs = body.errors || [];
+            const parts = [];
             for (let i = 0; i < errs.length; i++) {
                 const e = errs[i];
                 const field = String(e.path || '').replace(/^\//, '').split('/')[0];
                 if (field) markCellInvalid(rowId, field, e.message || 'invalid');
+                parts.push((field ? colTitle(field) + ': ' : '') + (e.message || 'invalid'));
             }
             setRowState(rowId, 'invalid');
+            showRowError(rowId, 'Can’t save — ' + (parts.length ? parts.join('; ') : 'validation failed.'));
             return { status: 'invalid', errors: errs };
         }
 
         if (resp.status === 403) {
             setRowState(rowId, 'errored');
+            showRowError(rowId, 'Can’t save — you don’t have permission to write here.');
             if (window.zddc && window.zddc.cap) {
                 window.zddc.cap.handleForbidden(resp, {
                     context: 'Save row',
@@ -6056,6 +6190,7 @@ body.is-elevated::after {
         // Other status — generic error.
         console.warn('[tables] save returned', resp.status);
         setRowState(rowId, 'errored');
+        showRowError(rowId, 'Can’t save — server error (HTTP ' + resp.status + ').');
         return { status: 'http-error', code: resp.status };
     }
 
@@ -6072,6 +6207,7 @@ body.is-elevated::after {
         }
         const createUrl = addRow.formCreateUrl();
         const merged = mergeRow(row.data, drafts);
+        if (validateRequired(rowId, merged)) return { status: 'invalid-required' };
         const yamlBody = window.jsyaml.dump(merged);
 
         const headers = { 'Content-Type': 'application/yaml; charset=utf-8' };
@@ -6129,6 +6265,7 @@ body.is-elevated::after {
             // the new url, then clear it (data has the merged values).
             delete app.state.drafts[rowId];
             clearCellInvalid(rowId);
+            clearRowError(rowId);
             setRowState(rowId, '');
             const sb = document.getElementById('table-status');
             if (sb && sb.getAttribute('data-row-id') === rowId) clearStatus();
@@ -6143,17 +6280,21 @@ body.is-elevated::after {
             try { body = await resp.json(); } catch (_) { /* ignore */ }
             clearCellInvalid(rowId);
             const errs = body.errors || [];
+            const parts = [];
             for (let i = 0; i < errs.length; i++) {
                 const e = errs[i];
                 const field = String(e.path || '').replace(/^\//, '').split('/')[0];
                 if (field) markCellInvalid(rowId, field, e.message || 'invalid');
+                parts.push((field ? colTitle(field) + ': ' : '') + (e.message || 'invalid'));
             }
             setRowState(rowId, 'invalid');
+            showRowError(rowId, 'Can’t add — ' + (parts.length ? parts.join('; ') : 'validation failed.'));
             return { status: 'invalid', errors: errs };
         }
 
         if (resp.status === 403) {
             setRowState(rowId, 'errored');
+            showRowError(rowId, 'Can’t add — you don’t have permission to create rows here.');
             if (window.zddc && window.zddc.cap) {
                 window.zddc.cap.handleForbidden(resp, {
                     context: 'Add row',
@@ -6174,11 +6315,13 @@ body.is-elevated::after {
             clearCellInvalid(rowId);
             markCellInvalid(rowId, 'sequence', msg);
             setRowState(rowId, 'invalid');
+            showRowError(rowId, 'Can’t add — ' + msg);
             return { status: 'duplicate', message: msg };
         }
 
         console.warn('[tables] createRow returned', resp.status);
         setRowState(rowId, 'errored');
+        showRowError(rowId, 'Can’t add — server error (HTTP ' + resp.status + ').');
         return { status: 'http-error', code: resp.status };
     }
 
@@ -6218,6 +6361,7 @@ body.is-elevated::after {
         } catch (_) { return; }
         delete app.state.drafts[rowId];
         clearCellInvalid(rowId);
+        clearRowError(rowId);
         setRowState(rowId, '');
         clearStatus();
         // Trigger a re-paint via the public app callback if one exists.
@@ -6256,7 +6400,9 @@ body.is-elevated::after {
     }
 
     function rowIdAtIndex(visibleRowIdx) {
-        const tr = document.querySelectorAll('#table-root tbody > tr')[visibleRowIdx];
+        // Data rows only — inline error rows have no data-row-id and must not
+        // offset the index.
+        const tr = document.querySelectorAll('#table-root tbody > tr[data-row-id]')[visibleRowIdx];
         return tr ? tr.getAttribute('data-row-id') : null;
     }
 
@@ -6968,18 +7114,28 @@ body.is-elevated::after {
         const sort = app.modules.sort;
         theadEl.innerHTML = '';
 
+        // Required fields come from the row schema (form.yaml schema.required).
+        const ctx = app.context || {};
+        const reqList = (ctx.rowSchema && Array.isArray(ctx.rowSchema.required)) ? ctx.rowSchema.required : [];
+        const requiredSet = {};
+        for (let r = 0; r < reqList.length; r++) requiredSet[reqList[r]] = true;
+
         const titleRow = util.h('tr', { className: 'zddc-table__title-row' });
         const filterRow = util.h('tr', { className: 'zddc-table__filter-row' });
 
         for (let i = 0; i < columns.length; i++) {
             const col = columns[i];
             const indicator = sort.indicator(sortState, col.field);
+            const isReq = !!requiredSet[col.field];
             const th = util.h('th', {
-                className: 'zddc-table__th',
+                className: 'zddc-table__th' + (isReq ? ' zddc-table__th--required' : ''),
                 'data-field': col.field,
+                title: isReq ? 'Required' : null,
                 style: col.width ? 'width:' + col.width : null,
                 onClick: function (ev) { onHeaderClick(col.field, ev.shiftKey); }
             }, col.title || col.field, indicator);
+            // Mandatory marker — a red asterisk after the column title.
+            if (isReq) th.insertBefore(util.h('span', { className: 'zddc-table__req', 'aria-hidden': 'true' }, ' *'), th.childNodes[1] || null);
             titleRow.appendChild(th);
 
             const td = util.h('td', { className: 'zddc-table__filter-cell' });