@profpowell/vb-project-planning 0.1.0 → 0.2.1

package/src/web-components/quality-target/logic.js

@@ -4,9 +4,10 @@
  * One component, two roles. The radar polygon IS the picker: each
  * axis is a clickable hit-target that opens a per-ility <dialog>
  * editor (level radio group + rationale textarea). The same SVG
- * also visualizes the chosen vector against the project's capacity
- * envelope (read from a paired <iron-triangle> via data-bind-to or
- * supplied via data-capacity-points).
+ * also shows the Critical spend against the project's capacity in a
+ * centre readout ("5 / of 4"), with capacity read from a paired
+ * <iron-triangle> via data-bind-to or supplied via data-capacity-points.
+ * There is no envelope polygon: three level rings are the only backdrop.
  *
  * Replaces both <nfr-compass> and <nfr-radar> from earlier rounds.
  *
@@ -37,12 +38,14 @@ import {
   buildTargetSvg,
 } from './_quality-utils.js';
 
+let instanceCount = 0;
+
 class QualityTarget extends VBElement {
   static formAssociated = true;
   static get observedAttributes() {
     return [
       'data-bind-to', 'data-capacity-points', 'data-cost-weights',
-      'data-radius', 'data-show-envelope',
+      'data-radius',
       'data-min-rationale', 'data-max-rationale',
       'data-min-overrun-rationale', 'data-max-overrun-rationale',
       'disabled', 'locked',
@@ -71,6 +74,9 @@ class QualityTarget extends VBElement {
   #dialogs = {};
   /** @type {HTMLElement | null} */
   #footer = null;
+  /** Per-instance prefix so generated label/control ids never collide
+   *  when a page holds more than one target. */
+  #uid = `quality-target-${++instanceCount}`;
 
   constructor() {
     super();
@@ -83,6 +89,7 @@ class QualityTarget extends VBElement {
     this.#bindToTriangle();
     this.#renderViz();
     this.#ensureFooter();
+    this.#publishFormValue();
 
     this.listen(this, 'click', (e) => this.#onClick(e));
     this.listen(this, 'keydown', (e) => this.#onKeydown(e));
@@ -104,8 +111,11 @@ class QualityTarget extends VBElement {
     } else if (name === 'data-cost-weights') {
       this.#refreshCostWeights();
       this.#renderViz();
-    } else if (name === 'data-radius' || name === 'data-show-envelope') {
+    } else if (name === 'data-radius') {
       this.#renderViz();
+    } else if (name === 'data-min-overrun-rationale' || name === 'data-max-overrun-rationale') {
+      this.#updateFooter();
+      this.#publishFormValue();
     } else if (name === 'disabled' || name === 'locked') {
       this.#syncDisabledLocked();
     }
@@ -153,7 +163,7 @@ class QualityTarget extends VBElement {
 
   /** Imperatively open one axis's editor. */
   openEditor(ility) {
-    if (!this.#ilities.includes(ility)) return;
+    if (!this.#ilities.includes(ility) || this.#inert) return;
     const dialog = this.#ensureDialog(ility);
     if (typeof dialog.showModal === 'function') dialog.showModal();
     else dialog.setAttribute('open', '');
@@ -244,10 +254,10 @@ class QualityTarget extends VBElement {
     // Rationale form-field (required when Critical).
     const ff = document.createElement('form-field');
     const rl = document.createElement('label');
-    rl.setAttribute('for', `quality-${ility}-rationale`);
+    rl.setAttribute('for', `${this.#uid}-${ility}-rationale`);
     rl.textContent = 'Rationale (required when Critical)';
     const ta = document.createElement('textarea');
-    ta.id = `quality-${ility}-rationale`;
+    ta.id = `${this.#uid}-${ility}-rationale`;
     ta.name = 'rationale';
     ta.rows = 3;
     ta.minLength = this.#minRationale();
@@ -304,6 +314,7 @@ class QualityTarget extends VBElement {
     });
 
     this.#syncDialogFromState(ility);
+    this.#syncDisabledLocked();
     return dialog;
   }
 
@@ -338,8 +349,8 @@ class QualityTarget extends VBElement {
       <strong>Over budget — explain why.</strong>
       <small data-overrun-prompt></small>
       <form-field>
-        <label for="quality-overrun">Overrun rationale (≥ ${this.#minOverrunRationale()} chars)</label>
-        <textarea id="quality-overrun" name="overrunRationale"
+        <label for="${this.#uid}-overrun">Overrun rationale (≥ ${this.#minOverrunRationale()} chars)</label>
+        <textarea id="${this.#uid}-overrun" name="overrunRationale"
                   minlength="${this.#minOverrunRationale()}"
                   maxlength="${this.#maxOverrunRationale()}"
                   rows="3"></textarea>
@@ -355,6 +366,7 @@ class QualityTarget extends VBElement {
 
     this.append(footer);
     this.#footer = footer;
+    this.#syncDisabledLocked();
   }
 
   #updateFooter() {
@@ -366,9 +378,19 @@ class QualityTarget extends VBElement {
     if (overrun) {
       overrun.hidden = !isOver;
       const prompt = overrun.querySelector('[data-overrun-prompt]');
-      if (prompt && Number.isFinite(cap)) {
-        prompt.textContent = `You're over budget by ${sum - cap} points (${sum}/${cap}).`;
+      if (prompt) {
+        const over = sum - cap;
+        prompt.textContent = isOver
+          ? `You're over budget by ${over} ${over === 1 ? 'point' : 'points'} (${sum}/${cap}).`
+          : '';
       }
+      // Keep the label and limits in step with the data-*-overrun-rationale
+      // attributes, which may change after the footer was built.
+      const min = this.#minOverrunRationale();
+      const label = overrun.querySelector('label');
+      if (label) label.textContent = `Overrun rationale (≥ ${min} chars)`;
+      const ta = /** @type {HTMLTextAreaElement | null} */ (overrun.querySelector('textarea'));
+      if (ta) { ta.minLength = min; ta.maxLength = this.#maxOverrunRationale(); }
     }
   }
 
@@ -461,6 +483,7 @@ class QualityTarget extends VBElement {
     const existing = this.querySelector(':scope > svg');
     if (existing) existing.replaceWith(svg);
     else this.prepend(svg);
+    this.#syncAxesInert();
   }
 
   #publish(source, field) {
@@ -490,15 +513,64 @@ class QualityTarget extends VBElement {
     try {
       this.#internals.setFormValue(JSON.stringify(this.value));
     } catch { /* older Safari */ }
+    this.#syncValidity();
   }
 
+  /**
+   * Mirror validateVector() into ElementInternals so a parent <form>'s
+   * checkValidity() / submit is blocked too, not just this element's own
+   * checkValidity() method. The overrun textarea anchors the message when
+   * the overrun rationale is the problem.
+   */
+  #syncValidity() {
+    if (typeof this.#internals.setValidity !== 'function') return;
+    const { valid, errors } = validateVector({
+      vector: this.#vector,
+      rationales: this.#rationales,
+      costWeights: this.#costWeights,
+      capacityPoints: this.#resolveCapacity(),
+      overrunRationale: this.#overrunRationale,
+      minRationale: this.#minRationale(),
+      minOverrunRationale: this.#minOverrunRationale(),
+    });
+    if (valid) { this.#internals.setValidity({}); return; }
+    const overrunTa = /** @type {HTMLElement | null} */ (
+      this.overBudget ? this.querySelector('[data-quality-overrun] textarea') : null);
+    try {
+      this.#internals.setValidity({ customError: true }, errors.join(' '), overrunTa ?? undefined);
+    } catch { /* anchor not yet connected */
+      this.#internals.setValidity({ customError: true }, errors.join(' '));
+    }
+  }
+
+  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
+   * (axes leave the tab order, openEditor() is a no-op) and disables every
+   * dialog and footer control, including dialogs built later.
+   */
   #syncDisabledLocked() {
-    const off = this.hasAttribute('disabled') || this.hasAttribute('locked');
+    const off = this.#inert;
     for (const dialog of Object.values(this.#dialogs)) {
       for (const el of dialog.querySelectorAll('input, textarea, select, button')) {
         /** @type {HTMLInputElement} */ (el).disabled = off;
       }
     }
+    for (const el of this.#footer?.querySelectorAll('textarea') ?? []) {
+      /** @type {HTMLTextAreaElement} */ (el).disabled = off;
+    }
+    this.#syncAxesInert();
+  }
+
+  #syncAxesInert() {
+    const off = this.#inert;
+    for (const axis of this.querySelectorAll(':scope > svg .axis[data-ility]')) {
+      axis.setAttribute('tabindex', off ? '-1' : '0');
+      if (off) axis.setAttribute('aria-disabled', 'true');
+      else axis.removeAttribute('aria-disabled');
+    }
   }
 
   // ── Internal: config readers ──────────────────────────────────────

package/src/web-components/requirement-card/api.json

@@ -2,7 +2,7 @@
   "$schema": "../../../schemas/api.schema.json",
   "element": "requirement-card",
   "type": "web-component",
-  "description": "Display-only card for ONE NFR ility row. Renders priority + rationale + optional conflict flag for status dashboards and ADR appendices. The prioritization decision itself lives in <nfr-compass>.",
+  "description": "Display-only card for ONE NFR ility row. Renders priority + rationale + optional conflict flag for status dashboards and ADR appendices. The prioritization decision itself lives in <quality-target>.",
   "htmlvalidate": {
     "flow": true,
     "permittedContent": ["@flow"]

package/src/web-components/requirement-card/logic.js

@@ -1,11 +1,11 @@
 /**
  * <requirement-card> — Display atom for ONE NFR ility row.
  *
- * Display-only. The prioritization decision lives in <nfr-compass>;
+ * Display-only. The prioritization decision lives in <quality-target>;
  * this component just renders one row's worth of state — name +
  * category badge + priority pill + rationale + (optional) conflict flag —
  * for use on status dashboards, ADR appendices, or anywhere a project
- * wants to surface a single ility outside the compass.
+ * wants to surface a single ility outside the target.
  *
  * Slots:
  *   name           — ility label (e.g. "Performance")
@@ -24,6 +24,8 @@
  *   requirement-card:click — bubbles a structured detail when the card
  *                            is activated (mouse, keyboard, or touch);
  *                            parent components can wire navigation.
+ *                            Inside an <a>/<button> wrapper, the
+ *                            wrapper's own keyboard activation counts.
  *
  * Pattern reference: matches the shadow-DOM + slot conventions from
  * <score-card> (also a single-row dashboard atom).
@@ -58,6 +60,9 @@ const TEMPLATE = `
 `;
 
 class RequirementCard extends VBElement {
+  /** True when this element added role="button" itself (so it may remove it). */
+  #ownsRole = false;
+
   static get observedAttributes() {
     return ['data-priority', 'data-conflict', 'tabindex'];
   }
@@ -82,6 +87,15 @@ class RequirementCard extends VBElement {
     this.#syncInteractive();
 
     this.listen(this, 'click', (e) => this.#onActivate(e));
+    // Keyboard activation of a wrapping <a>/<button> fires `click` on the
+    // wrapper itself, which never reaches the card's own listener. Clicks
+    // that started inside the card are already handled above.
+    const wrapper = this.closest('a[href], button');
+    if (wrapper) {
+      this.listen(wrapper, 'click', (e) => {
+        if (!this.contains(/** @type {Node} */ (e.target))) this.#onActivate(e);
+      });
+    }
     this.listen(this, 'keydown', (e) => {
       const ke = /** @type {KeyboardEvent} */ (e);
       if ((ke.key === 'Enter' || ke.key === ' ') && this.#interactive) {
@@ -125,7 +139,7 @@ class RequirementCard extends VBElement {
   }
 
   #syncSlot(name, slot) {
-    const hasContent = !!slot && slot.assignedNodes({ flatten: true }).some(n =>
+    const hasContent = !!slot && slot.assignedNodes().some(n =>
       n.nodeType === Node.ELEMENT_NODE ||
       (n.nodeType === Node.TEXT_NODE && n.textContent.trim().length > 0)
     );
@@ -146,6 +160,16 @@ class RequirementCard extends VBElement {
 
   #syncInteractive() {
     this.setState('interactive', !!this.#interactive);
+    // A focusable card that is not inside a native control needs a role
+    // so assistive tech announces it as activatable. Author roles win.
+    const needsRole = this.hasAttribute('tabindex') && !this.closest('a[href], button');
+    if (needsRole && !this.hasAttribute('role')) {
+      this.setAttribute('role', 'button');
+      this.#ownsRole = true;
+    } else if (!needsRole && this.#ownsRole) {
+      this.removeAttribute('role');
+      this.#ownsRole = false;
+    }
   }
 
   #onActivate(event) {

package/src/web-components/requirement-card/static.html

@@ -8,7 +8,7 @@
 <body>
   <!--
     Display-only card for ONE NFR ility row. The prioritization
-    decision lives in <nfr-compass>; this is the visual atom.
+    decision lives in <quality-target>; this is the visual atom.
     Pre-upgrade, the card renders as a plain article — no JS needed
     for it to be readable.
   -->

package/src/web-components/user-persona/logic.js

@@ -105,7 +105,7 @@ class UserPersona extends HTMLElement {
     if (!this.id) return [];
     const root = /** @type {ParentNode} */ (this.getRootNode());
     const scope = /** @type {ParentNode} */ (/** @type {any} */ (root).querySelectorAll ? root : document);
-    return Array.from(scope.querySelectorAll(`user-story[persona-id="${cssEscape(this.id)}"]`));
+    return Array.from(scope.querySelectorAll(`user-story[persona-id="${cssEscape(this.id)}"]:not([data-detail-clone])`));
   }
 
   #cacheSlotValues() {

package/src/web-components/user-story/logic.js

@@ -210,7 +210,7 @@ class UserStory extends HTMLElement {
 
   connectedCallback() {
     this.#cacheSlotValues();
-    if (this.storyId && !this.id) this.id = this.storyId;
+    if (this.storyId && !this.id && !this.hasAttribute('data-detail-clone')) this.id = this.storyId;
     if (this.hasAttribute('src')) {
       this._loadSrc(this.getAttribute('src'));
     }
@@ -410,6 +410,7 @@ class UserStory extends HTMLElement {
     const hasSlottedContent = [...this.children].some(c => c.getAttribute('slot') && c.tagName !== 'DIALOG');
     full.setAttribute('detail', hasSlottedContent ? 'full' : 'compact');
     full.removeAttribute('id');
+    full.setAttribute('data-detail-clone', ''); // keep the clone out of id/persona lookups
     for (const child of [...this.children]) {
       if (child.tagName === 'DIALOG') continue;
       full.appendChild(child.cloneNode(true));