@profpowell/vb-project-planning 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profpowell/vb-project-planning",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Project- and UX-planning Web Components for Vanilla Breeze: personas, stories, journeys, empathy maps, impact/effort and quadrant grids, risk and traceability matrices, burndown, roadmap, kanban, story map, gantt, review surface, work items, ADRs, iron triangle, capacity plans, quality targets, and requirement cards.",
   "license": "MIT",
   "author": "Thomas A. Powell",
@@ -63,8 +63,10 @@
     "build:js": "esbuild src/index.js --bundle --format=esm --outfile=dist/vb-project-planning.js && esbuild src/index.js --bundle --format=esm --minify --outfile=dist/vb-project-planning.min.js",
     "build:css": "esbuild src/index.css --bundle --outfile=dist/vb-project-planning.css && esbuild src/index.css --bundle --minify --outfile=dist/vb-project-planning.min.css",
     "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:unit": "TZ=America/Los_Angeles node --test 'tests/unit/*.test.mjs'",
     "test:components": "playwright test",
-    "test": "playwright test"
+    "test": "npm run test:unit && playwright test"
   },
   "peerDependencies": {
     "vanilla-breeze": ">=0.3.0"
@@ -75,7 +77,8 @@
     }
   },
   "devDependencies": {
-    "@playwright/test": "^1.61.1",
-    "esbuild": "^0.27.0"
+    "@playwright/test": "^1.64.1",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.3"
   }
 }

package/src/lib/board-surface.js

@@ -0,0 +1,158 @@
+/**
+ * Shared helpers for the drag-surface "board" components
+ * (kanban-board, story-map, impact-effort, quadrant-grid).
+ *
+ * Small, DOM-only utilities: live-region announcements, human labels for
+ * cards, empty-column placeholders, and building a <user-story> card from a
+ * JSON record using the slots user-story actually reads.
+ */
+
+/**
+ * Convert a hyphenated or lowercase id to Title Case.
+ * @param {string} str
+ * @returns {string}
+ */
+export function titleCase(str) {
+  return String(str ?? '')
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Create a polite, atomic status region for move announcements.
+ * @param {string} className
+ * @returns {HTMLDivElement}
+ */
+export function createLiveRegion(className) {
+  const region = document.createElement('div');
+  region.className = className;
+  region.setAttribute('role', 'status');
+  region.setAttribute('aria-live', 'polite');
+  region.setAttribute('aria-atomic', 'true');
+  return region;
+}
+
+/**
+ * Announce a message: clear, then set on the next frame so repeated
+ * identical messages are re-read.
+ * @param {HTMLElement | null} region
+ * @param {string} msg
+ */
+export function announce(region, msg) {
+  if (!region) return;
+  region.textContent = '';
+  requestAnimationFrame(() => { region.textContent = msg; });
+}
+
+/**
+ * A human-readable label for a card: its title slot, its action slot, an
+ * aria-label, or its visible text. Generated ids are only a last resort.
+ * @param {Element | null | undefined} item
+ * @returns {string}
+ */
+export function itemLabel(item) {
+  if (!item) return 'item';
+  const clean = (/** @type {string | null | undefined} */ s) => (s || '').replace(/\s+/g, ' ').trim();
+  const slotted = clean(item.querySelector(':scope > [slot="title"]')?.textContent)
+    || clean(item.querySelector(':scope > [slot="action"]')?.textContent);
+  if (slotted) return truncate(slotted);
+  const aria = clean(item.getAttribute('aria-label'));
+  if (aria) return truncate(aria);
+  const text = clean(item.textContent);
+  if (text) return truncate(text);
+  return item.getAttribute('story-id') || item.getAttribute('data-id') || 'item';
+}
+
+/** @param {string} s */
+function truncate(s) {
+  return s.length > 60 ? `${s.slice(0, 59).trimEnd()}…` : s;
+}
+
+/**
+ * Add or remove the "empty" placeholder so it shows only when the surface
+ * holds no draggable cards.
+ * @param {Element} surface
+ * @param {string} className
+ * @param {string} text
+ */
+export function syncPlaceholder(surface, className, text) {
+  const hasCards = !!surface.querySelector(':scope > [draggable="true"]');
+  const placeholder = surface.querySelector(`:scope > .${className}`);
+  if (!hasCards && !placeholder) {
+    const p = document.createElement('p');
+    p.className = className;
+    p.textContent = text;
+    surface.appendChild(p);
+  } else if (hasCards && placeholder) {
+    placeholder.remove();
+  }
+}
+
+/**
+ * Does this JSON record describe a user story (rather than a plain card)?
+ * @param {Record<string, any>} record
+ */
+export function isStoryRecord(record) {
+  return !!(record && (record.persona || record.action || record.benefit || record.storyId));
+}
+
+/**
+ * Build a `<user-story>` from a JSON record. State goes on the attributes
+ * user-story observes; text content goes into the slots it reads
+ * (persona, action, benefit, title, acceptance-criteria, tasks, notes).
+ * Works whether or not user-story has been defined yet.
+ *
+ * @param {Record<string, any>} record
+ * @param {string} [defaultDetail] - detail level when the record has none
+ * @returns {HTMLElement}
+ */
+export function createStoryCard(record, defaultDetail) {
+  const el = document.createElement('user-story');
+  /** @type {Array<[string, string]>} */
+  const attrs = [
+    ['storyId', 'story-id'], ['personaId', 'persona-id'], ['priority', 'priority'],
+    ['status', 'status'], ['points', 'points'], ['epic', 'epic'],
+  ];
+  for (const [key, attr] of attrs) {
+    if (record[key] != null && record[key] !== '') el.setAttribute(attr, String(record[key]));
+  }
+  const detail = record.detail || defaultDetail;
+  if (detail) el.setAttribute('detail', String(detail));
+
+  for (const slot of ['persona', 'action', 'benefit']) {
+    if (record[slot]) el.appendChild(slotted('span', slot, record[slot]));
+  }
+  if (record.title) el.appendChild(slotted('h3', 'title', record.title));
+  for (const [key, slot] of [['acceptanceCriteria', 'acceptance-criteria'], ['tasks', 'tasks'], ['notes', 'notes']]) {
+    const value = record[key];
+    if (!value) continue;
+    if (Array.isArray(value)) {
+      const ul = document.createElement('ul');
+      ul.slot = slot;
+      for (const entry of value) {
+        const li = document.createElement('li');
+        li.textContent = String(entry);
+        ul.appendChild(li);
+      }
+      el.appendChild(ul);
+    } else {
+      el.appendChild(slotted('p', slot, value));
+    }
+  }
+  return el;
+}
+
+/**
+ * @param {string} tag
+ * @param {string} slot
+ * @param {unknown} text
+ */
+function slotted(tag, slot, text) {
+  const el = document.createElement(tag);
+  el.slot = slot;
+  el.textContent = String(text);
+  return el;
+}
+
+// SrcLoader lives in its own module; re-exported here for existing imports.
+export { SrcLoader } from './src-loader.js';

package/src/lib/bundle-registry.js

@@ -1,83 +1,10 @@
 /**
  * Bundle Registry — Vanilla Breeze
  *
- * Provides infrastructure for modular bundles to register effects,
- * components, and activate full bundles at runtime.
+ * Provides infrastructure for modular bundles to register components
+ * and activate full bundles at runtime.
  */
 
-// ─── Effect registry ─────────────────────────────────────────────────────────
-
-const effects = new Map()
-let observer = null
-const reducedMotionMq = window.matchMedia('(prefers-reduced-motion: reduce)')
-
-function startObserver() {
-  if (observer) return
-  observer = new MutationObserver(mutations => {
-    for (const mutation of mutations) {
-      for (const node of mutation.addedNodes) {
-        if (node.nodeType !== Node.ELEMENT_NODE) continue
-        const el = /** @type {Element} */ (node)
-        matchEffects(el)
-        el.querySelectorAll('*').forEach(matchEffects)
-      }
-      for (const node of mutation.removedNodes) {
-        if (node.nodeType !== Node.ELEMENT_NODE) continue
-        const el = /** @type {Element} */ (node)
-        unmatchEffects(el)
-        el.querySelectorAll('*').forEach(unmatchEffects)
-      }
-    }
-  })
-  observer.observe(document.body, { childList: true, subtree: true })
-}
-
-function matchEffects(el) {
-  for (const [, def] of effects) {
-    if (el.matches?.(def.selector)) {
-      if (reducedMotionMq.matches && def.reducedMotionFallback) {
-        def.reducedMotionFallback(el)
-      } else {
-        def.init(el)
-      }
-    }
-  }
-}
-
-function unmatchEffects(el) {
-  for (const [, def] of effects) {
-    if (el.matches?.(def.selector) && def.destroy) {
-      def.destroy(el)
-    }
-  }
-}
-
-/**
- * Register a DOM effect that auto-initializes on matching elements.
- *
- * @param {string} name - Unique effect name
- * @param {{ selector: string, init: (el: Element) => void, destroy?: (el: Element) => void, reducedMotionFallback?: (el: Element) => void }} def
- */
-export function registerEffect(name, def) {
-  effects.set(name, def)
-
-  // Initialize on existing matching elements
-  document.querySelectorAll(def.selector).forEach(el => {
-    if (reducedMotionMq.matches && def.reducedMotionFallback) {
-      def.reducedMotionFallback(el)
-    } else {
-      def.init(el)
-    }
-  })
-
-  // Start shared observer lazily
-  if (document.body) {
-    startObserver()
-  } else {
-    document.addEventListener('DOMContentLoaded', startObserver, { once: true })
-  }
-}
-
 // ─── Component registry ──────────────────────────────────────────────────────
 
 const components = new Map()

package/src/lib/dates.js

@@ -0,0 +1,125 @@
+/**
+ * Calendar-date helpers shared by the date-driven components
+ * (gantt-chart, burndown-chart, product-roadmap, adr-wc).
+ *
+ * Planning dates are calendar days, not instants. Two rules keep them
+ * stable in every time zone:
+ *
+ *  1. `YYYY-MM-DD` is parsed as LOCAL midnight. `new Date('2026-04-01')`
+ *     is UTC midnight, which renders as March 31 anywhere west of UTC.
+ *  2. Days are stepped with setDate(), never by adding 86 400 000 ms,
+ *     which repeats or skips a day across a daylight-saving change.
+ */
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?![\d:T])/;
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
+
+/**
+ * Parse a calendar date. `YYYY-MM-DD` becomes local midnight; Date objects
+ * are copied and truncated to local midnight; ISO timestamps
+ * (`YYYY-MM-DDTHH:mm…`) and numbers are accepted and truncated too.
+ * Everything else returns null: the native Date parser is far too lenient
+ * (it turns "<img 1>" into 2001-01-01).
+ * @param {unknown} value
+ * @returns {Date | null}
+ */
+export function parseISODate(value) {
+  if (value == null || value === '') return null;
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : startOfDay(value);
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? startOfDay(new Date(value)) : null;
+  }
+  const s = String(value).trim();
+  const m = s.match(ISO_DATE);
+  if (m) {
+    const d = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    // Reject roll-overs such as 2026-02-31.
+    if (d.getMonth() !== Number(m[2]) - 1 || d.getDate() !== Number(m[3])) return null;
+    return d;
+  }
+  if (!ISO_TIMESTAMP.test(s)) return null;
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? null : startOfDay(d);
+}
+
+/** @param {Date} d @returns {Date} local midnight of the same calendar day */
+export function startOfDay(d) {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+
+/** @param {Date} d @returns {string} `YYYY-MM-DD` in local time */
+export function toISODate(d) {
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${m}-${day}`;
+}
+
+/** Calendar-day addition (DST-safe). @param {Date} d @param {number} n @returns {Date} */
+export function addDays(d, n) {
+  const out = startOfDay(d);
+  out.setDate(out.getDate() + n);
+  return out;
+}
+
+/**
+ * Whole calendar days from `a` to `b` (b − a), ignoring DST hour shifts.
+ * @param {Date} a @param {Date} b @returns {number}
+ */
+export function daysBetween(a, b) {
+  const ua = Date.UTC(a.getFullYear(), a.getMonth(), a.getDate());
+  const ub = Date.UTC(b.getFullYear(), b.getMonth(), b.getDate());
+  return Math.round((ub - ua) / 86_400_000);
+}
+
+/**
+ * Every calendar day from `start` to `end` inclusive, as `YYYY-MM-DD`.
+ * @param {Date} start @param {Date} end @returns {string[]}
+ */
+export function enumerateDays(start, end) {
+  const out = [];
+  for (let d = startOfDay(start); d <= end; d = addDays(d, 1)) out.push(toISODate(d));
+  return out;
+}
+
+/** @param {Date} d @returns {Date} first day of the month */
+export function startOfMonth(d) {
+  return new Date(d.getFullYear(), d.getMonth(), 1);
+}
+
+/** @param {Date} d @returns {Date} last day of the month */
+export function endOfMonth(d) {
+  return new Date(d.getFullYear(), d.getMonth() + 1, 0);
+}
+
+/** @param {Date} d @returns {Date} first day of the calendar quarter */
+export function startOfQuarter(d) {
+  return new Date(d.getFullYear(), Math.floor(d.getMonth() / 3) * 3, 1);
+}
+
+/** @param {Date} d @returns {Date} last day of the calendar quarter */
+export function endOfQuarter(d) {
+  return new Date(d.getFullYear(), Math.floor(d.getMonth() / 3) * 3 + 3, 0);
+}
+
+/**
+ * Add whole months, clamping the day so Jan 31 + 1 month is Feb 28/29,
+ * not March 3.
+ * @param {Date} d @param {number} n @returns {Date}
+ */
+export function addMonths(d, n) {
+  const first = new Date(d.getFullYear(), d.getMonth() + n, 1);
+  const last = endOfMonth(first).getDate();
+  return new Date(first.getFullYear(), first.getMonth(), Math.min(d.getDate(), last));
+}
+
+/**
+ * Locale display of a calendar date. Defaults to e.g. "April 1, 2026".
+ * @param {Date} d
+ * @param {Intl.DateTimeFormatOptions} [opts]
+ * @param {string | string[]} [locale]
+ */
+export function formatDate(d, opts = { year: 'numeric', month: 'long', day: 'numeric' }, locale = undefined) {
+  return d.toLocaleDateString(locale, opts);
+}

package/src/lib/escape.js

@@ -0,0 +1,34 @@
+/**
+ * The pack's one HTML escaper. Use it for every author- or data-supplied
+ * string interpolated into an innerHTML template, in both text and
+ * attribute positions (single- or double-quoted).
+ *
+ * Do NOT use it for values passed to setAttribute() or textContent: those
+ * are already literal, and escaping them shows "&" to users and screen
+ * readers.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function esc(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (c) => ESCAPES[c]);
+}
+
+/** @type {Record<string, string>} */
+const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+/**
+ * Escape a URL for use inside a CSS `url("…")` token in an inline style.
+ * Returns the full `url("…")` so callers can't forget the quotes. Only
+ * http(s), protocol-relative, relative, and data:image URLs are allowed;
+ * anything else yields `none`.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function cssUrl(value) {
+  const s = String(value ?? '').trim();
+  if (!s) return 'none';
+  if (/^[a-z][a-z0-9+.-]*:/i.test(s) && !/^(https?:|data:image\/)/i.test(s)) return 'none';
+  const escaped = s.replace(/["\\\n\r\f]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `);
+  return esc(`url("${escaped}")`);
+}

package/src/lib/hash.js

@@ -0,0 +1,16 @@
+/**
+ * Small deterministic string hash (Java-style `h * 31 + c`, written as
+ * `(h << 5) - h`). Used for stable avatar colours and portrait picks, so the
+ * exact output matters: changing it changes every generated avatar.
+ * @param {string} str
+ * @returns {number} integer (deliberately not truncated to 32 bits, to match
+ *   the original copies byte for byte)
+ */
+export function stringHash(str) {
+  let h = 0;
+  const s = String(str ?? '');
+  for (let i = 0; i < s.length; i++) {
+    h = s.charCodeAt(i) + ((h << 5) - h);
+  }
+  return h;
+}

package/src/lib/portrait-url.js

@@ -15,22 +15,11 @@
  * // → 'https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/male/256/82.jpg'
  */
 
+import { stringHash } from './hash.js';
+
 const CDN = 'https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait';
 const SIZES = [32, 64, 128, 256, 512];
 
-/**
- * Simple string hash (same algorithm as _ux-base.js hashColor).
- * @param {string} str
- * @returns {number}
- */
-function hash(str) {
-  let h = 0;
-  for (let i = 0; i < str.length; i++) {
-    h = str.charCodeAt(i) + ((h << 5) - h);
-  }
-  return h;
-}
-
 /**
  * Snap a pixel value to the nearest available portrait size.
  * @param {number} px - Desired size in pixels
@@ -61,27 +50,12 @@ function snapSize(px) {
  * @returns {string} CDN URL for the portrait JPEG
  */
 export function portraitUrl(seed, size = 128) {
-  const h = hash(String(seed));
+  const h = stringHash(String(seed));
   const index = ((h % 100) + 100) % 100;
   const sex = ((h >>> 16) & 1) === 0 ? 'female' : 'male';
   const snapped = snapSize(size);
   return `${CDN}/${sex}/${snapped}/${index}.jpg`;
 }
 
-/**
- * Get a portrait URL by explicit numeric index (0–199).
- * 0–99 = female, 100–199 = male.
- *
- * @param {number} index - Portrait index (0–199)
- * @param {number} [size=128] - Desired image size in px
- * @returns {string} CDN URL
- */
-export function portraitByIndex(index, size = 128) {
-  const i = ((index % 200) + 200) % 200;
-  const sex = i < 100 ? 'female' : 'male';
-  const fileIndex = i < 100 ? i : i - 100;
-  const snapped = snapSize(size);
-  return `${CDN}/${sex}/${snapped}/${fileIndex}.jpg`;
-}
 
 export { SIZES as PORTRAIT_SIZES, CDN as PORTRAIT_CDN };

package/src/lib/src-loader.js

@@ -0,0 +1,78 @@
+/**
+ * SrcLoader — one in-flight `src` fetch per component.
+ *
+ * Every component with a `src` attribute (the UXShadowElement cards, the
+ * boards, gantt-chart, review-surface) loads through this so the same
+ * rules hold everywhere:
+ *
+ * - A newer `start()` / `fetchJson()` aborts the previous request, and the
+ *   superseded response (if it still arrives) is dropped.
+ * - `cancel()` aborts the in-flight request without starting another (the
+ *   `src` attribute was removed, or `.tasks` / `.pins` took over).
+ * - `url` is the last URL requested, so connect-time code can skip a
+ *   refetch of the same value; it is cleared on failure (allowing a retry)
+ *   and by `cancel()`.
+ */
+export class SrcLoader {
+  /** @type {AbortController | null} */
+  #ctrl = null;
+  /** @type {string | null} */
+  url = null;
+
+  /** True while a fetchJson() request is in flight (not settled or cancelled). */
+  #busy = false;
+  get pending() { return this.#busy; }
+
+  /**
+   * Abort any earlier request and begin tracking a new one.
+   * @param {string} url
+   * @returns {{ signal: AbortSignal, isCurrent: () => boolean }}
+   */
+  start(url) {
+    this.#ctrl?.abort();
+    const ctrl = new AbortController();
+    this.#ctrl = ctrl;
+    this.#busy = false;
+    this.url = url;
+    return { signal: ctrl.signal, isCurrent: () => this.#ctrl === ctrl && !ctrl.signal.aborted };
+  }
+
+  /**
+   * Abort the in-flight request (if any) and forget the URL. Returns true
+   * when a request was actually in flight.
+   * @returns {boolean}
+   */
+  cancel() {
+    const wasPending = this.pending;
+    this.#ctrl?.abort();
+    this.#ctrl = null;
+    this.#busy = false;
+    this.url = null;
+    return wasPending;
+  }
+
+  /**
+   * Fetch JSON for `url`, aborting any earlier request. Resolves to
+   * `undefined` when superseded, cancelled or aborted; rejects (only while
+   * still current) on a network error, a non-2xx status or invalid JSON.
+   * @param {string} url
+   * @returns {Promise<{ data: any, isCurrent: () => boolean } | undefined>}
+   */
+  async fetchJson(url) {
+    const { signal, isCurrent } = this.start(url);
+    this.#busy = true;
+    try {
+      const res = await fetch(url, { signal });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      if (!isCurrent()) return undefined;
+      this.#busy = false;
+      return { data, isCurrent };
+    } catch (err) {
+      if (/** @type {any} */ (err)?.name === 'AbortError' || !isCurrent()) return undefined;
+      this.#busy = false;
+      this.url = null;
+      throw err;
+    }
+  }
+}

package/src/lib/vb-view-transition.js

@@ -35,7 +35,13 @@ export function viewTransitionSwap(host, swap, prefix = 'vb-vt') {
   const name = `${prefix}-${++counter}`;
   host.style.viewTransitionName = name;
   const tx = document.startViewTransition(swap);
-  tx.finished.finally(() => {
+  // The browser aborts a transition when, e.g., the viewport resizes or
+  // another transition starts. That rejects `ready` (and can reject
+  // `finished`); unhandled, it surfaces as an uncaught exception even though
+  // the DOM swap itself already ran. The swap's own errors still reach
+  // callers through `updateCallbackDone`.
+  tx.ready.catch(() => {});
+  tx.finished.catch(() => {}).finally(() => {
     if (host.style.viewTransitionName === name) {
       host.style.viewTransitionName = '';
     }