@profpowell/vb-project-planning 0.2.0 → 0.2.2

package/src/web-components/iron-triangle/_capacity.js

@@ -19,28 +19,10 @@ export function defaultFormula(time, cost, focusFactor) {
   return Math.ceil(weeks * fte * f);
 }
 
-/**
- * Format the formula string used as the human-readable explanation
- * shown beneath the readout. Matches the formula above; if either
- * factor is missing the string degrades gracefully.
- */
-export function defaultFormulaText(time, cost, focusFactor) {
-  const sprintCount = num(time?.sprintCount);
-  const sprintWeeks = num(time?.sprintWeeks) || 1;
-  const totalWeeks = sprintCount > 0 ? sprintCount * sprintWeeks : sprintWeeks;
-  const fte = num(cost?.teamFTE);
-  const f = clamp(num(focusFactor), 0, 1);
-  const points = defaultFormula(time, cost, focusFactor);
-  if (!points) return 'Set sprint length, team size, and focus factor to compute capacity.';
-  const weeksLabel = sprintCount > 0
-    ? `${sprintCount} × ${sprintWeeks}wk = ${totalWeeks}wk`
-    : `${sprintWeeks}wk`;
-  return `${weeksLabel} × ${fte} FTE × ${f} = ${(totalWeeks * fte * f).toFixed(1)} → ${points} points`;
-}
 
 /**
  * FNV-1a (32-bit) hash over a stable JSON serialization of the triangle.
- * Used for drift detection by downstream consumers (notably <nfr-compass>'s
+ * Used for drift detection by downstream consumers (notably <quality-target>'s
  * ironTriangleHash field).
  *
  * Matches the fnv1a in src/web-components/color-picker/_color-utils.js so

package/src/web-components/iron-triangle/_triangle-geometry.js

@@ -172,7 +172,7 @@ export function buildTriangleSvg({
   center.setAttribute('role', 'button');
   center.setAttribute(
     'aria-label',
-    `Quality — ${formatQualitySummary(qualitySummary)}. Activate to open the NFR compass.`,
+    `Quality — ${formatQualitySummary(qualitySummary)}. Activate to open the quality decision.`,
   );
 
   // Backdrop circle — sits behind the text, masks the polygon stroke.

package/src/web-components/iron-triangle/api.json

@@ -13,8 +13,8 @@
     { "name": "data-min-capacity",     "kind": "data",     "purpose": "config",         "type": "number",  "default": "1",        "description": "Floor for capacityPoints" },
     { "name": "data-quality-href",     "kind": "data",     "purpose": "config",         "type": "string",  "description": "Navigation fallback when iron-triangle:open-quality isn't preventDefault-ed" },
     { "name": "data-quality-summary",  "kind": "data",     "purpose": "config",         "type": "string",  "description": "Short summary text shown in the center's native tooltip + aria-label (e.g. '3 critical: perf, sec, a11y')" },
-    { "name": "disabled",              "kind": "native",   "purpose": "config",         "type": "boolean", "description": "All inputs disabled" },
-    { "name": "locked",                "kind": "host-api", "purpose": "semantic-state", "type": "boolean", "description": "Read-only mode for shipped vectors" }
+    { "name": "disabled",              "kind": "native",   "purpose": "config",         "type": "boolean", "description": "Fully off: vertex and centre Quality targets leave the tab order (aria-disabled), openEditor() is a no-op, the mode switch and all dialog controls are disabled. setManual() / setFormula() / revise() still work for the host." },
+    { "name": "locked",                "kind": "host-api", "purpose": "semantic-state", "type": "boolean", "description": "Read-only mode for shipped shapes: the same editing lock as disabled, but the centre Quality target still opens the quality decision (iron-triangle:open-quality / data-quality-href)" }
   ],
   "slots": [],
   "events": [

package/src/web-components/iron-triangle/logic.js

@@ -25,7 +25,7 @@
  *     is never colour-only.
  *
  * Optional: pass a `data-quality-summary` attribute or set the
- * `qualitySummary` property to surface the bound NFR compass's
+ * `qualitySummary` property to surface the bound quality-target's
  * decision on hover (e.g. "3 critical: perf, sec, a11y").
  */
 
@@ -171,7 +171,7 @@ class IronTriangle extends VBElement {
 
   /** Imperatively open a vertex editor. */
   openEditor(axis) {
-    if (!SECTIONS.includes(axis)) return;
+    if (!SECTIONS.includes(axis) || this.#inert) return;
     const dialog = this.#ensureDialog(axis);
     if (typeof dialog.showModal === 'function') dialog.showModal();
     else dialog.setAttribute('open', '');
@@ -235,7 +235,7 @@ class IronTriangle extends VBElement {
     const center = event.target.closest?.('.center[data-target="quality"]');
     if (center && this.contains(center)) {
       event.preventDefault();
-      this.#fireQualityOpen();
+      if (!this.hasAttribute('disabled')) this.#fireQualityOpen();
     }
   }
 
@@ -250,7 +250,7 @@ class IronTriangle extends VBElement {
     const center = event.target.closest?.('.center[data-target="quality"]');
     if (center && this.contains(center)) {
       event.preventDefault();
-      this.#fireQualityOpen();
+      if (!this.hasAttribute('disabled')) this.#fireQualityOpen();
     }
   }
 
@@ -314,6 +314,7 @@ class IronTriangle extends VBElement {
       this.#recompute({ source: 'dialog', field: axis });
     });
 
+    this.#syncDisabledLocked();
     return dialog;
   }
 
@@ -399,6 +400,7 @@ class IronTriangle extends VBElement {
     const existing = this.querySelector(':scope > svg');
     if (existing) existing.replaceWith(svg);
     else this.prepend(svg);
+    this.#syncHitTargetsInert();
     this.dataset.capacityPoints = String(this.#value.capacityPoints);
     this.dataset.capacitySource = this.#value.capacitySource;
   }
@@ -422,12 +424,40 @@ class IronTriangle extends VBElement {
     } catch { /* older Safari */ }
   }
 
+  get #inert() { return this.hasAttribute('disabled') || this.hasAttribute('locked'); }
+
+  /**
+   * disabled / locked: no editing path stays open. styles.css already sets
+   * pointer-events: none; this closes the keyboard and programmatic paths
+   * (vertex targets leave the tab order, openEditor() is a no-op) and
+   * disables the mode switch and every dialog control, including dialogs
+   * built later.
+   *
+   * The centre Quality target is navigation, not editing, so under `locked`
+   * it stays focusable and clickable (styles.css re-enables its pointer).
+   * Under `disabled` it goes inert too: browsers suppress mouse events
+   * inside a disabled form-associated element, so keeping only its
+   * keyboard path alive would be inconsistent.
+   */
   #syncDisabledLocked() {
-    const off = this.hasAttribute('disabled') || this.hasAttribute('locked');
+    const off = this.#inert;
     if (this.#modeButton) this.#modeButton.disabled = off;
     for (const dialog of Object.values(this.#dialogs)) {
       for (const el of dialog.querySelectorAll('input, select, textarea, button')) /** @type {any} */ (el).disabled = off;
     }
+    this.#syncHitTargetsInert();
+  }
+
+  /** Hit targets follow disabled / locked across re-renders. */
+  #syncHitTargetsInert() {
+    const editingOff = this.#inert;
+    const navOff = this.hasAttribute('disabled');
+    for (const target of this.querySelectorAll(':scope > svg [role="button"][tabindex]')) {
+      const off = target.matches('.center[data-target="quality"]') ? navOff : editingOff;
+      target.setAttribute('tabindex', off ? '-1' : '0');
+      if (off) target.setAttribute('aria-disabled', 'true');
+      else target.removeAttribute('aria-disabled');
+    }
   }
 
   // ── Internal: status strip (a11y hooks) ──────────────────────────
@@ -448,7 +478,9 @@ class IronTriangle extends VBElement {
 
     const button = document.createElement('button');
     button.type = 'button';
-    button.className = 'iron-triangle-mode';
+    // VB's `ghost` variant keeps the switch secondary to the triangle;
+    // styles.css trims it further to sit inside the small status strip.
+    button.className = 'iron-triangle-mode ghost';
     button.setAttribute('aria-pressed', 'false');
     button.textContent = 'Manual capacity';
     button.addEventListener('click', () => this.#openCapacityDialog());
@@ -486,9 +518,14 @@ class IronTriangle extends VBElement {
 
     if (this.#modeButton) {
       this.#modeButton.setAttribute('aria-pressed', manual ? 'true' : 'false');
-      this.#modeButton.setAttribute('aria-label',
-        manual ? `Manual capacity: ${capacityPoints} points. Activate to edit or return to the formula.`
-               : 'Manual capacity. Activate to override the formula with a fixed number.');
+      // Pressed state is carried by the visible text too, not only by the
+      // underline. The aria-label starts with that visible text so voice
+      // users can say what they see (WCAG 2.5.3 Label in Name).
+      const label = manual && capacityPoints > 0 ? `Manual capacity: ${capacityPoints} pts` : 'Manual capacity';
+      if (this.#modeButton.textContent !== label) this.#modeButton.textContent = label;
+      this.#modeButton.setAttribute('aria-label', manual
+        ? `${label}. Activate to edit or return to the formula.`
+        : `${label}. Activate to override the formula with a fixed number.`);
     }
     if (this.#deadlineWarning) {
       this.#deadlineWarning.textContent = overDeadline ? `Deadline has passed (${deadline})` : '';
@@ -566,6 +603,7 @@ class IronTriangle extends VBElement {
       if (Number.isFinite(n) && n > 0) this.setManual(n);
     });
 
+    this.#syncDisabledLocked();
     return dialog;
   }
 

package/src/web-components/iron-triangle/styles.css

@@ -150,13 +150,27 @@ iron-triangle > .iron-triangle-status .iron-triangle-readout {
   border: 0;
 }
 
+/* Quiet, secondary switch: ghost button, compact, muted until hovered or
+   pressed. VB's touch-target minimum block size is kept. Pressed adds an underline (plus the "Manual capacity: N pts" label) so
+   the state never rests on colour alone. */
 iron-triangle > .iron-triangle-status .iron-triangle-mode {
   font-size: inherit;
+  font-weight: var(--font-weight-normal, 400);
+  padding-block: 0;
+  padding-inline: var(--size-xs, 0.5rem);
+  border-color: transparent;
+  color: var(--color-text-muted);
+}
+
+iron-triangle > .iron-triangle-status .iron-triangle-mode:hover {
+  color: var(--color-text);
 }
 
 iron-triangle > .iron-triangle-status .iron-triangle-mode[aria-pressed="true"] {
-  border-color: var(--color-interactive);
   color: var(--color-interactive);
+  text-decoration: underline;
+  text-decoration-thickness: var(--border-width-medium, 2px);
+  text-underline-offset: 0.25em;
 }
 
 /* Visible, text-bearing warning — never colour-only. */
@@ -193,6 +207,13 @@ iron-triangle[locked] {
   pointer-events: none;
 }
 
+/* The centre Quality target navigates to the quality decision rather than
+   editing the shape, so it keeps working on a locked (read-only) triangle.
+   A disabled triangle stays fully off, like any disabled control. */
+iron-triangle[locked]:not([disabled]) svg .center[data-target="quality"] {
+  pointer-events: auto;
+}
+
 /* ── Dialog chrome ────────────────────────────────────────────── */
 
 iron-triangle > dialog.iron-triangle-dialog {

package/src/web-components/kanban-board/api.json

@@ -5,8 +5,8 @@
   "description": "Columnar drag-and-drop board with user-defined columns, count badges, and optional WIP limits",
   "htmlvalidate": { "flow": true, "permittedContent": ["section"] },
   "attributes": [
-    { "name": "src",     "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL to JSON data for columns and items" },
-    { "name": "title",   "kind": "host-api", "purpose": "config", "type": "string",  "description": "Optional heading above the board" },
+    { "name": "src",     "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL to JSON data for columns and items. Fetched once per value; a new value replaces the board and aborts an older in-flight request" },
+    { "name": "title",   "kind": "host-api", "purpose": "config", "type": "string",  "description": "Optional heading above the board; also names the board region" },
     { "name": "compact", "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Reduced spacing variant" }
   ],
   "childAttributes": [
@@ -16,9 +16,11 @@
     { "name": "data-column-color", "on": "section", "type": "string",  "description": "Color token for column tint (success, warning, error, info)" }
   ],
   "events": [
-    { "name": "kanban-board:transfer",     "detail": "{ itemId, fromColumn, toColumn, newIndex, item }",  "description": "Item moved between columns" },
-    { "name": "kanban-board:reorder",      "detail": "{ itemId, column, oldIndex, newIndex }",            "description": "Item reordered within a column" },
-    { "name": "kanban-board:ready",        "detail": "{ columnCount, itemCount }",                        "description": "Fired after component initializes" },
-    { "name": "kanban-board:wip-exceeded", "detail": "{ column, limit, count }",                          "description": "Fired when a column exceeds its WIP limit" }
+    { "name": "kanban-board:transfer",      "detail": "{ itemId, fromColumn, toColumn, newIndex, item }", "description": "Item moved between columns" },
+    { "name": "kanban-board:reorder",       "detail": "{ itemId, column, oldIndex, newIndex }",           "description": "Item reordered within a column" },
+    { "name": "kanban-board:ready",         "detail": "{ columnCount, itemCount }",                       "description": "Fired once after the first render. With src, fired once the JSON has loaded and rendered. Once per element: not re-fired by a later src change (watch items-changed with source 'src') or when the board is moved in the DOM" },
+    { "name": "kanban-board:wip-exceeded",  "detail": "{ column, limit, count }",                         "description": "Fired when a drop takes a column over its WIP limit" },
+    { "name": "kanban-board:items-changed", "detail": "{ items, source: 'api' | 'drag' | 'src' }",        "description": "Fired after the items array changes: an .items assignment, or a .columns assignment that drops cards (source 'api'), a drag (source 'drag'), or each src load once its data has rendered (source 'src'). Filter on source to avoid feedback loops" },
+    { "name": "kanban-board:upgraded",      "detail": "",                                                 "description": "Fired (in a microtask) each time the board connects and upgrades; a safe signal for assigning .columns / .items from a framework" }
   ]
 }