@unbrained/pm-web 2026.8.7 → 2026.8.14

package/public/src/views/health.js.map

@@ -1 +1 @@
-{"version":3,"file":"health.js","sourceRoot":"","sources":["health.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"health.js","sourceRoot":"","sources":["health.ts"],"names":[],"mappings":"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"}

package/public/src/views/health.ts

@@ -20,6 +20,7 @@ function isHistoryDriftIssue(issue: HealthIssue): boolean {
   return msg.includes('history') && (msg.includes('drift') || msg.includes('repair') || msg.includes('mismatch'));
 }
 
+/** Renders the markup for one health issue, appending Repair and Dry Run buttons when the issue is history drift and a project item id is detected in the message. */
 function renderIssueRow(issue: HealthIssue, projectId: string): string {
   const msg = escHtml(issue.message || issue.description || String(issue));
   if (isHistoryDriftIssue(issue)) {
@@ -34,6 +35,7 @@ function renderIssueRow(issue: HealthIssue, projectId: string): string {
   return `<div class="health-issue-item">⚠ ${msg}</div>`;
 }
 
+/** Runs item history repair (or a dry-run preview) via the project's history-repair endpoint and toasts a summary of entries scanned, rehashed, and patched, including verification failures. */
 export async function repairItemHistory(projectId: string, itemId: string, dryRun: boolean): Promise<void> {
   try {
     const data = await api<HistoryRepairResponse>('POST', `/projects/${projectId}/pm/items/${encodeURIComponent(itemId)}/history-repair`, { dryRun });
@@ -63,6 +65,7 @@ export async function repairItemHistory(projectId: string, itemId: string, dryRu
   }
 }
 
+/** Renders the project health view: a numeric health score card colored by threshold and a list of issues (each rendered with repair actions when applicable), plus an optional summary. */
 export async function renderHealthView(): Promise<void> {
   const el = document.getElementById('content-health');
   if (!el) return;

package/public/src/views/items.js

@@ -16,9 +16,11 @@ import { EMPTY_FILTERS, filtersToQueryString, filtersFromSearchParams, hasActive
 // alive across the Preview → Apply call pair and is GC-friendly.
 const bulkUpdatePayloads = new WeakMap();
 const bulkClosePayloads = new WeakMap();
-// Mirror the active item filters into the URL query string (on the /items
-// path) so a filtered view is shareable and bookmarkable. Replaces the current
-// history entry to avoid polluting back/forward with every keystroke.
+/**
+ * Mirrors the current item filters into the page URL query string when the
+ * items view is active, using history.replaceState so the filtered view is
+ * shareable without adding back/forward entries. Does nothing on other views.
+ */
 function syncFiltersToUrl() {
     if (state.currentView !== 'items')
         return;
@@ -29,8 +31,12 @@ function syncFiltersToUrl() {
     }
     catch { /* ignore */ }
 }
-// Read filters from the current URL's query string into state. Called when the
-// Items view is opened so a shared link applies its filters.
+/**
+ * Reads item filters from the current URL query string into state. Only
+ * replaces the in-memory filters when the URL actually carries filter
+ * parameters, so navigating to /items without a query string preserves the
+ * existing filters.
+ */
 export function loadFiltersFromUrl() {
     const params = new URLSearchParams(window.location.search);
     // Only override when the URL actually carries filter params, so navigating
@@ -47,6 +53,12 @@ const DEP_REL_OPTIONS = [
     { value: 'child', label: 'Child' },
     { value: 'related', label: 'Related' },
 ];
+/**
+ * Normalizes a raw dependency relationship label to a canonical value by
+ * trimming, lowercasing, and converting dashes to underscores, then applying a
+ * known-alias map (e.g. blockedby → blocked_by). Returns the alias when one
+ * exists, otherwise the normalized input unchanged.
+ */
 function normalizeDepRelation(raw) {
     const aliases = {
         blockedby: 'blocked_by',
@@ -67,12 +79,22 @@ function normalizeDepRelation(raw) {
     const normalized = (raw || '').trim().toLowerCase().replace(/-/g, '_');
     return aliases[normalized] ?? normalized;
 }
+/**
+ * Builds the HTML <option> elements for a dependency relationship dropdown from
+ * the fixed DEP_REL_OPTIONS list, marking the option that matches the
+ * normalized selected value as selected.
+ */
 function renderDependencyOptions(selected) {
     const current = normalizeDepRelation(selected);
     return DEP_REL_OPTIONS
         .map((option) => `<option value="${option.value}"${option.value === current ? ' selected' : ''}>${option.label}</option>`)
         .join('');
 }
+/**
+ * Returns a human-readable display label for a dependency relationship by
+ * looking up its normalized value in a fixed label map, falling back to the
+ * original relationship string when no label is defined.
+ */
 function depLabel(rel) {
     const labels = {
         blocked_by: 'Blocked by',
@@ -92,6 +114,11 @@ function depRelation(dep) {
 // ═══════════════════════════════════════════════════════════════
 // BULK UPDATE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Opens the Bulk Update Items modal, which lets the user filter items and
+ * choose fields to change across many items at once. Shows an info toast and
+ * returns early when no project is currently selected.
+ */
 export function showBulkUpdateModal() {
     if (!state.currentProject) {
         toast('Select a project first', 'info');
@@ -166,6 +193,12 @@ export function showBulkUpdateModal() {
     </div>`, '');
     showModal('bulk-update-modal');
 }
+/**
+ * Runs a dry-run bulk update and renders a preview of the matched items and
+ * their field changes inside the modal. Requires at least one field to update,
+ * and stashes the actual (non-dry-run) payload on the Apply button so
+ * applyBulkUpdate can run without re-reading the form.
+ */
 export async function previewBulkUpdate() {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -255,6 +288,12 @@ export async function previewBulkUpdate() {
             previewEl.innerHTML = `<div style="color:var(--status-open);font-size:13px">Error: ${escHtml(err instanceof Error ? err.message : String(err))}</div>`;
     }
 }
+/**
+ * Applies the bulk update payload stashed on the Apply button by
+ * previewBulkUpdate, posting to the update-many endpoint. Reports the updated
+ * and failed counts via toast, closes the bulk update modal, and refreshes the
+ * items list and project badge.
+ */
 export async function applyBulkUpdate() {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -295,6 +334,11 @@ export async function applyBulkUpdate() {
 // ═══════════════════════════════════════════════════════════════
 // BULK CLOSE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Opens the Bulk Close Items modal, which lets the user filter items and close
+ * or cancel many of them at once with a required reason. Shows an info toast
+ * and returns early when no project is currently selected.
+ */
 export function showBulkCloseModal() {
     if (!state.currentProject) {
         toast('Select a project first', 'info');
@@ -352,6 +396,12 @@ export function showBulkCloseModal() {
     </div>`, '');
     showModal('bulk-close-modal');
 }
+/**
+ * Previews the items that would be closed or canceled by running an
+ * update-many dry-run, and renders the matched count and first few items
+ * inside the modal. Requires a close reason, and stashes the close payload on
+ * the Apply button for applyBulkClose to use.
+ */
 export async function previewBulkClose() {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -421,6 +471,13 @@ export async function previewBulkClose() {
             previewEl.innerHTML = `<div style="color:var(--status-blocked);font-size:13px">Error: ${escHtml(err instanceof Error ? err.message : String(err))}</div>`;
     }
 }
+/**
+ * Applies the bulk close payload stashed on the Apply button by
+ * previewBulkClose, posting to the close-many endpoint which closes or cancels
+ * each matched item with the chosen reason. Reports the closed and failed
+ * counts via toast, closes the modal, and refreshes the items list and project
+ * badge.
+ */
 export async function applyBulkClose() {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -472,6 +529,12 @@ export async function applyBulkClose() {
         }
     }
 }
+/**
+ * Renders the Items view into the page: a header with refresh and bulk
+ * actions, the status filter tabs, the multi-field filter bar, and a loading
+ * list placeholder, then fetches and renders the items. Shows an empty state
+ * and returns when no project is selected.
+ */
 export async function renderItemsView() {
     const el = document.getElementById('content-items');
     if (!el)
@@ -521,6 +584,12 @@ export async function renderItemsView() {
     <div id="items-list"><div class="loading-state"><div class="loading-spinner"></div></div></div>`;
     await fetchAndRenderItems();
 }
+/**
+ * Fetches items for the current project using the active filters (capped at
+ * 200, with tags filtered client-side because the list endpoint has no tag
+ * flag), stores them in state, updates the count subtitle, and renders the
+ * list. Shows an error state in the list element if the request fails.
+ */
 export async function fetchAndRenderItems() {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -561,6 +630,10 @@ export async function fetchAndRenderItems() {
             listEl.innerHTML = `<div class="empty-state"><div class="empty-state-text">Failed to load items: ${escHtml(err instanceof Error ? err.message : String(err))}</div></div>`;
     }
 }
+/**
+ * Renders the items list element from state.items, showing an empty-state
+ * placeholder when there are no items or the mapped item rows otherwise.
+ */
 function renderItemsList() {
     const el = document.getElementById('items-list');
     if (!el)
@@ -575,6 +648,11 @@ function renderItemsList() {
     }
     el.innerHTML = `<div class="item-list">${state.items.map(item => renderItemRow(item)).join('')}</div>`;
 }
+/**
+ * Returns the HTML markup for a single items-list row: a clickable card
+ * showing the item's type icon, id, title, tags, priority dot, and status
+ * badge that opens the item detail modal when clicked.
+ */
 export function renderItemRow(item) {
     const tags = (item.tags || []).map(t => `<span class="tag">${escHtml(t)}</span>`).join('');
     return `<div class="item-row" onclick="window.__app.openItemDetail('${escHtml(item.id)}')">
@@ -588,6 +666,11 @@ export function renderItemRow(item) {
     </div>
   </div>`;
 }
+/**
+ * Reads the current values from every items filter-bar control into
+ * state.itemFilters, mirrors them to the URL, and re-fetches and renders the
+ * list.
+ */
 export function applyItemFilters() {
     const fs = document.getElementById('filter-status');
     const ft = document.getElementById('filter-type');
@@ -606,6 +689,10 @@ export function applyItemFilters() {
     syncFiltersToUrl();
     fetchAndRenderItems();
 }
+/**
+ * Resets the item filters to empty, clears every filter-bar control in the
+ * DOM, mirrors the cleared filters to the URL, and re-renders the items list.
+ */
 export function clearFilters() {
     state.itemFilters = { ...EMPTY_FILTERS };
     const ids = ['filter-status', 'filter-type', 'filter-priority', 'filter-sprint', 'filter-release', 'filter-assignee', 'filter-tag'];
@@ -617,7 +704,11 @@ export function clearFilters() {
     syncFiltersToUrl();
     fetchAndRenderItems();
 }
-// Copy a shareable URL for the current filtered Items view to the clipboard.
+/**
+ * Builds a shareable URL for the current filtered items view and copies it to
+ * the clipboard, toasting success or, if the clipboard write fails, toasting
+ * the URL itself for manual copy.
+ */
 export async function copyFilterLink() {
     const qs = filtersToQueryString(state.itemFilters);
     const url = `${window.location.origin}/items${qs ? `?${qs}` : ''}`;
@@ -629,6 +720,10 @@ export async function copyFilterLink() {
         toast(url, 'info');
     }
 }
+/**
+ * Sets the status filter to the provided value, mirrors it to the URL, and
+ * re-renders the entire items view.
+ */
 export function setStatusFilter(status) {
     state.itemFilters.status = status;
     syncFiltersToUrl();
@@ -637,6 +732,12 @@ export function setStatusFilter(status) {
 // ═══════════════════════════════════════════════════════════════
 // ITEM DETAIL MODAL
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Opens the item detail modal and renders it. Fetches the item together with
+ * its comments, history, dependencies, learnings, notes, tests, and linked
+ * files in parallel (each detail call falls back to empty on failure) and
+ * builds the full tabbed detail view.
+ */
 export async function openItemDetail(itemId) {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -969,6 +1070,11 @@ export async function openItemDetail(itemId) {
             bodyEl.innerHTML = `<div class="empty-state"><div class="empty-state-text">Failed to load: ${escHtml(err instanceof Error ? err.message : String(err))}</div></div>`;
     }
 }
+/**
+ * Formats a timestamp as a human-readable relative age string (just now,
+ * Nm/Nh/Nd ago) for recent times, or a localized date for anything older than
+ * a week. Returns an empty string when the timestamp is missing.
+ */
 function relTime(ts) {
     if (!ts)
         return '';
@@ -990,6 +1096,12 @@ function fmtDate(ts) {
         return '';
     return new Date(ts).toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' });
 }
+/**
+ * Switches the item detail modal to the selected tab: toggles the active class
+ * on the tabs, shows the target tab panel while hiding the others, tears down
+ * the local graph when leaving the graph tab, and initializes the graph along
+ * with its depth-slider listener when entering the graph tab with a nodeId.
+ */
 export function switchDetailTab(tabEl, targetId, nodeId) {
     const allTabs = tabEl.parentElement?.querySelectorAll('.tab');
     allTabs?.forEach(t => t.classList.remove('active'));
@@ -1017,6 +1129,11 @@ export function switchDetailTab(tabEl, targetId, nodeId) {
         });
     }
 }
+/**
+ * Posts the comment typed into the detail modal's comment box to the item,
+ * requiring non-empty text. On success it clears the box, toasts confirmation,
+ * and reopens the item detail to refresh the comments tab.
+ */
 export async function addComment(itemId) {
     const el = document.getElementById('new-comment');
     if (!el)
@@ -1036,6 +1153,10 @@ export async function addComment(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Posts the note typed into the detail modal's note box to the item, requiring
+ * non-empty text. On success it clears the box and toasts confirmation.
+ */
 export async function addNote(itemId) {
     const el = document.getElementById('new-note');
     if (!el)
@@ -1054,6 +1175,11 @@ export async function addNote(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Appends the text from the detail modal's append box to the item's
+ * description, requiring non-empty text. On success it clears the box and
+ * toasts confirmation.
+ */
 export async function appendItem(itemId) {
     const el = document.getElementById('new-append');
     if (!el)
@@ -1072,6 +1198,11 @@ export async function appendItem(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Saves the item detail's Update form: reads every edit field, requires a
+ * title, and PATCHes the changed fields to the backend. On success it reopens
+ * the item detail and refreshes the items list and project badge.
+ */
 export async function updateItem(itemId) {
     const titleEl = document.getElementById('edit-title');
     const statusEl = document.getElementById('edit-status');
@@ -1132,6 +1263,12 @@ export async function updateItem(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Closes or cancels the item with a required reason. For canceled it first
+ * sets the status to canceled via the update endpoint before posting the close
+ * reason; for closed it posts the close reason directly. Reports the outcome,
+ * hides the detail modal, and refreshes the items list and project badge.
+ */
 export async function closeItem(itemId, targetStatus) {
     const reasonEl = document.getElementById('close-reason');
     const reason = reasonEl?.value?.trim();
@@ -1157,6 +1294,10 @@ export async function closeItem(itemId, targetStatus) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Shows a confirmation dialog and, on confirm, DELETEs the item, hides the
+ * detail modal, and refreshes the items list and project badge.
+ */
 export function confirmDeleteItem(itemId) {
     confirmDialog('Delete Item?', 'This action cannot be undone. The item and all its data will be permanently removed.', async () => {
         try {
@@ -1175,6 +1316,12 @@ export function confirmDeleteItem(itemId) {
 // ═══════════════════════════════════════════════════════════════
 // CLAIM / RELEASE / START / PAUSE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Claims the item for the current user via the claim endpoint, dimming the
+ * matching list row optimistically. On success it reopens the detail and
+ * refreshes the list; on failure it restores the row opacity and toasts the
+ * error.
+ */
 export async function claimItem(itemId) {
     const row = document.querySelector(`.item-row[onclick*="${itemId}"]`);
     if (row)
@@ -1192,6 +1339,10 @@ export async function claimItem(itemId) {
             row.style.opacity = '';
     }
 }
+/**
+ * Releases the current user's claim on the item via the release endpoint, then
+ * reopens the detail and refreshes the items list.
+ */
 export async function releaseItem(itemId) {
     try {
         await api('POST', `/projects/${state.currentProject.id}/pm/release/${itemId}`, {});
@@ -1204,6 +1355,10 @@ export async function releaseItem(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Starts the item (moving it into in_progress) via the start-task endpoint,
+ * then reopens the detail and refreshes the items list and project badge.
+ */
 export async function startItem(itemId) {
     try {
         await api('POST', `/projects/${state.currentProject.id}/pm/start-task/${itemId}`, {});
@@ -1217,6 +1372,10 @@ export async function startItem(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Pauses the in-progress item via the pause-task endpoint, then reopens the
+ * detail and refreshes the items list and project badge.
+ */
 export async function pauseItem(itemId) {
     try {
         await api('POST', `/projects/${state.currentProject.id}/pm/pause-task/${itemId}`, {});
@@ -1233,6 +1392,12 @@ export async function pauseItem(itemId) {
 // ═══════════════════════════════════════════════════════════════
 // DEPS / LEARNINGS / TESTS / FILES
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Adds a dependency to the item from the detail modal's dependency inputs:
+ * reads and normalizes the target id and relationship, rejects an empty or
+ * self-referential target, and posts to the deps endpoint. On success it
+ * reopens the item detail.
+ */
 export async function addDep(itemId) {
     const targetIdEl = document.getElementById('dep-target-id');
     const relEl = document.getElementById('dep-rel');
@@ -1255,6 +1420,11 @@ export async function addDep(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Removes a dependency from the item after confirming with the user. Normalizes
+ * the relationship, requires a target id, and DELETEs the dependency from the
+ * deps endpoint; on success it reopens the item detail.
+ */
 export async function removeDep(itemId, targetId, relation) {
     const rel = normalizeDepRelation(relation);
     if (!targetId) {
@@ -1272,6 +1442,11 @@ export async function removeDep(itemId, targetId, relation) {
         }
     }, true);
 }
+/**
+ * Records a learning typed into the detail modal on the item, requiring
+ * non-empty text. On success it toasts confirmation and reopens the item
+ * detail.
+ */
 export async function addLearning(itemId) {
     const el = document.getElementById('new-learning');
     const text = el?.value?.trim() || '';
@@ -1288,6 +1463,11 @@ export async function addLearning(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Adds a test command (required) with an optional description to the item via
+ * the tests endpoint. On success it toasts confirmation and reopens the item
+ * detail.
+ */
 export async function addTest(itemId) {
     const cmdEl = document.getElementById('new-test-cmd');
     const descEl = document.getElementById('new-test-desc');
@@ -1306,6 +1486,10 @@ export async function addTest(itemId) {
         toast(err instanceof Error ? err.message : String(err), 'error');
     }
 }
+/**
+ * Links a file path (required) to the item via the files endpoint. On success
+ * it toasts confirmation and reopens the item detail.
+ */
 export async function addFileLink(itemId) {
     const el = document.getElementById('file-path-input');
     const filePath = el?.value?.trim() || '';
@@ -1325,6 +1509,12 @@ export async function addFileLink(itemId) {
 // ═══════════════════════════════════════════════════════════════
 // USE ITEM AS TEMPLATE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Closes the item detail modal and opens the create view pre-filled from the
+ * given item's fields, prefixing the title with "Copy of" and focusing and
+ * selecting it so the user can immediately edit. The form is filled after a
+ * short delay to let the create view render.
+ */
 export function useItemAsTemplate(item) {
     // Close the item detail modal and navigate to create view
     hideModal('item-detail-modal');