@profpowell/vb-project-planning 0.2.1 → 0.2.2

package/src/web-components/product-roadmap/styles.css

@@ -129,6 +129,44 @@ product-roadmap > section[data-lane] {
     border-end-end-radius: var(--radius-s, 0.25rem);
   }
 
+  .rm-bar:focus-visible {
+    outline: var(--border-width-medium, 2px) solid var(--color-focus, var(--color-interactive, #0066cc));
+    outline-offset: 2px;
+  }
+
+  .rm-bar[data-dragging] {
+    cursor: grabbing;
+    z-index: 3;
+    box-shadow: 0 4px 10px rgba(0, 0, 0, 0.25);
+  }
+
+  /* Status as text too, so it is not conveyed by colour alone. */
+  .rm-bar-status {
+    flex: none;
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: 600;
+    opacity: 0.9;
+    white-space: nowrap;
+    padding-inline-end: var(--size-xs, 0.5rem);
+  }
+
+  .rm-track[data-drop-target] {
+    outline: var(--border-width-medium, 2px) dashed var(--color-interactive, #0066cc);
+    outline-offset: -2px;
+  }
+
+  .rm-sr-only {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
   .rm-bar[data-status="planned"]      { background: var(--color-info, oklch(60% 0.12 240)); }
   .rm-bar[data-status="in-progress"]  { background: var(--color-accent, oklch(50% 0.16 260)); }
   .rm-bar[data-status="at-risk"]      { background: var(--color-warning, oklch(65% 0.16 60)); color: var(--color-text, #1a1a1a); }
@@ -152,6 +190,8 @@ product-roadmap > section[data-lane] {
 /* Read-only roadmap: bars don't show grab cursor or resize handle. */
 product-roadmap:not([editable]) .rm-bar { cursor: default; }
 product-roadmap:not([editable]) .rm-bar-handle { display: none; }
+/* Editable bars handle their own pointer gestures (no touch scroll/pan). */
+product-roadmap[editable] .rm-bar { touch-action: none; }
 
 @media (prefers-reduced-motion: reduce) {
   product-roadmap .rm-bar { transition: none; }

package/src/web-components/quadrant-grid/api.json

@@ -79,7 +79,7 @@
       "kind": "host-api",
       "purpose": "config",
       "type": "boolean",
-      "description": "Enable drag-and-drop between quadrants (composes <drag-surface>)"
+      "description": "Enable drag-and-drop between quadrants (composes one <drag-surface> per quadrant)"
     }
   ],
   "childAttributes": [
@@ -93,13 +93,13 @@
       "name": "data-x",
       "on": "*",
       "type": "number",
-      "description": "Normalized x coordinate 0..1; quadrant is computed from coords"
+      "description": "Normalized x coordinate 0..1; quadrant is computed from coords; removed when the child is dragged to another quadrant"
     },
     {
       "name": "data-y",
       "on": "*",
       "type": "number",
-      "description": "Normalized y coordinate 0..1; quadrant is computed from coords"
+      "description": "Normalized y coordinate 0..1; quadrant is computed from coords; removed when the child is dragged to another quadrant"
     },
     {
       "name": "data-id",
@@ -112,7 +112,12 @@
     {
       "name": "quadrant-grid:move",
       "detail": "{ item, itemId, from, to }",
-      "description": "Fired when a draggable child moves between quadrants"
+      "description": "Fired when a draggable child moves between quadrants (from / to are indices 0..3). A coordinate-pinned child dropped in another quadrant loses its data-x / data-y and joins that quadrant's stack"
+    },
+    {
+      "name": "quadrant-grid:upgraded",
+      "detail": "",
+      "description": "Fired (in a microtask) each time the grid connects and upgrades"
     }
   ],
   "structure": [],

package/src/web-components/quadrant-grid/logic.js

@@ -45,7 +45,9 @@
  * @attr {number} data-y        - 0..1 normalized y coordinate
  * @attr {string} data-id       - Stable identifier for moves
  *
- * @fires quadrant-grid:move - { item, itemId, from, to, x?, y? }
+ * @fires quadrant-grid:move - { item, itemId, from, to }. A coordinate-pinned
+ *   child that is dragged to another quadrant drops its data-x/data-y (a drop
+ *   has no position) and joins that quadrant's stack as a regular card.
  */
 
 import { registerComponent } from '../../lib/bundle-registry.js';
@@ -54,8 +56,19 @@ import { VBElement } from '../../lib/vb-element.js';
 class QuadrantGrid extends VBElement {
   static #instanceCount = 0;
 
+  /** Quadrant indices in visual reading order: TL (Q2), TR (Q1), BL (Q3), BR (Q4). */
+  static VISUAL_ORDER = [1, 0, 2, 3];
+
   setup() {
-    this.#groupId = `qg-${++QuadrantGrid.#instanceCount}`;
+    if (!this.#groupId) this.#groupId = `qg-${++QuadrantGrid.#instanceCount}`;
+
+    // Reconnect (or a repeated setup() call): the grid is already built and
+    // still holds every child, so only re-attach listeners and observers.
+    if (this.#built) {
+      this.#wire();
+      return;
+    }
+    this.#built = true;
 
     const xLabel = this.getAttribute('x-label') || '';
     const yLabel = this.getAttribute('y-label') || '';
@@ -86,7 +99,7 @@ class QuadrantGrid extends VBElement {
     const yScale = document.createElement('aside');
     yScale.className = 'qg-y-scale';
     yScale.setAttribute('aria-hidden', 'true');
-    yScale.innerHTML = `<span>${yHigh}</span><span>${yLow}</span>`;
+    yScale.append(QuadrantGrid.#span(yHigh), QuadrantGrid.#span(yLow));
 
     const grid = document.createElement('div');
     grid.className = 'qg-grid';
@@ -94,16 +107,18 @@ class QuadrantGrid extends VBElement {
     const xScale = document.createElement('aside');
     xScale.className = 'qg-x-scale';
     xScale.setAttribute('aria-hidden', 'true');
-    xScale.innerHTML = `<span>${xLow}</span><span>${xHigh}</span>`;
+    xScale.append(QuadrantGrid.#span(xLow), QuadrantGrid.#span(xHigh));
 
     const xLabelEl = document.createElement('footer');
     xLabelEl.className = 'qg-x-label';
     xLabelEl.setAttribute('aria-hidden', 'true');
     xLabelEl.textContent = `${xLabel} →`;
 
-    /* Cartesian DOM order: place sections in the visual grid by index.
-       Indices 0..3 correspond to Q1..Q4. CSS grid-area positions them. */
-    for (let q = 0; q < 4; q++) {
+    /* Indices 0..3 are Cartesian Q1..Q4 (Q1 top-right, Q2 top-left).
+       Append in visual reading order (top-left, top-right, bottom-left,
+       bottom-right) so DOM, reading and tab order match what is seen;
+       CSS still places each zone by data-quadrant-zone. */
+    for (const q of QuadrantGrid.VISUAL_ORDER) {
       const section = document.createElement('section');
       section.className = 'qg-quadrant';
       section.dataset.quadrantZone = String(q);
@@ -167,11 +182,14 @@ class QuadrantGrid extends VBElement {
         }
       }
 
-      // Wrap non-drag children in <li> so list semantics hold.
+      // Wrap non-drag children in <li> so list semantics hold. A pinned
+      // child is absolutely positioned out of its <li>, so that <li> must
+      // not draw a chip of its own.
       if (draggable) {
         target.appendChild(child);
       } else {
         const li = document.createElement('li');
+        if (child.classList.contains('qg-pinned')) li.className = 'qg-pin-item';
         li.appendChild(child);
         target.appendChild(li);
       }
@@ -192,11 +210,18 @@ class QuadrantGrid extends VBElement {
     this.appendChild(wrapper);
     this.appendChild(liveRegion);
 
-    this.#grid = grid;
     this.#liveRegion = liveRegion;
     this.#qLabels = qLabels;
+    this.#draggable = draggable;
 
-    if (draggable) {
+    this.#wire();
+  }
+
+  /** Attach listeners and pin observers once per connection. */
+  #wire() {
+    if (this.#wired) return;
+    this.#wired = true;
+    if (this.#draggable) {
       this.listen(this, 'drag-surface:transfer', this.#onTransfer);
     }
 
@@ -208,6 +233,13 @@ class QuadrantGrid extends VBElement {
     this.#observePins();
   }
 
+  /** @param {string} text */
+  static #span(text) {
+    const span = document.createElement('span');
+    span.textContent = text;
+    return span;
+  }
+
   #observePins() {
     if (typeof ResizeObserver === 'undefined') return;
     const measure = (el) => {
@@ -250,6 +282,10 @@ class QuadrantGrid extends VBElement {
         pin.removeAttribute('tabindex');
         delete pin.dataset.qgTabbed;
       }
+      if (pin.dataset.qgRole !== undefined) {
+        pin.removeAttribute('role');
+        delete pin.dataset.qgRole;
+      }
     }
 
     let clusterSeq = 0;
@@ -284,9 +320,16 @@ class QuadrantGrid extends VBElement {
           pin.dataset.cluster = id;
           pin.style.setProperty('--qg-cluster-i', String(i));
           pin.style.setProperty('--qg-cluster-n', String(members.length));
+          // Clustered pins become focusable so keyboard users can fan the
+          // cluster out (:focus-within); a focusable generic element needs a
+          // role, so expose it as a group.
           if (!pin.hasAttribute('tabindex') && !pin.matches('a, button, [contenteditable]')) {
             pin.setAttribute('tabindex', '0');
             pin.dataset.qgTabbed = '';
+            if (!pin.hasAttribute('role')) {
+              pin.setAttribute('role', 'group');
+              pin.dataset.qgRole = '';
+            }
           }
         });
       }
@@ -294,6 +337,9 @@ class QuadrantGrid extends VBElement {
   }
 
   teardown() {
+    // Listeners are removed by VBElement; the built grid and its children
+    // stay in place so a moved grid keeps its content.
+    this.#wired = false;
     this.#pinObserver?.disconnect();
     this.#pinObserver = null;
     if (this.#clusterRaf) cancelAnimationFrame(this.#clusterRaf);
@@ -320,6 +366,8 @@ class QuadrantGrid extends VBElement {
     if (from == null || to == null) return;
 
     item.setAttribute('data-quadrant', String(to));
+    if (item.classList.contains('qg-pinned')) this.#unpin(item);
+    this.#scheduleClusterPass();
     this.#announce(`Moved ${this.#itemLabel(item)} to ${this.#qLabels[to]}`);
 
     this.dispatchEvent(new CustomEvent('quadrant-grid:move', {
@@ -333,6 +381,25 @@ class QuadrantGrid extends VBElement {
     }));
   };
 
+  /**
+   * A dropped pin has no coordinates in its new quadrant: drop data-x /
+   * data-y and the pin styling so it joins the quadrant's stack.
+   * @param {HTMLElement} item
+   */
+  #unpin(item) {
+    this.#pinObserver?.unobserve(item);
+    item.removeAttribute('data-x');
+    item.removeAttribute('data-y');
+    item.classList.remove('qg-pinned', 'qg-clustered');
+    for (const prop of ['--qg-local-x', '--qg-local-y', '--qg-pin-half-w', '--qg-pin-half-h',
+      '--qg-cluster-i', '--qg-cluster-n']) {
+      item.style.removeProperty(prop);
+    }
+    delete item.dataset.cluster;
+    if (item.dataset.qgTabbed !== undefined) { item.removeAttribute('tabindex'); delete item.dataset.qgTabbed; }
+    if (item.dataset.qgRole !== undefined) { item.removeAttribute('role'); delete item.dataset.qgRole; }
+  }
+
   #resolveQuadrant(child) {
     const q = parseInt(child.getAttribute('data-quadrant'), 10);
     if (q >= 0 && q <= 3) return q;
@@ -374,6 +441,9 @@ class QuadrantGrid extends VBElement {
   }
 
   #groupId = '';
+  #built = false;
+  #wired = false;
+  #draggable = false;
   /** @type {Record<number, HTMLElement>} */
   #surfaces = {};
   /** @type {Record<number, HTMLElement>} */
@@ -381,8 +451,6 @@ class QuadrantGrid extends VBElement {
   /** @type {Record<number, HTMLElement>} */
   #sections = {};
   /** @type {HTMLElement | null} */
-  #grid = null;
-  /** @type {HTMLElement | null} */
   #liveRegion = null;
   /** @type {string[]} */
   #qLabels = [];

package/src/web-components/quadrant-grid/styles.css

@@ -122,6 +122,13 @@ quadrant-grid {
     font-size: var(--font-size-sm, 0.875rem);
   }
 
+  /* The <li> around a coordinate-pinned child: the pin is absolutely
+     positioned against the quadrant, so the <li> draws no chip and takes
+     no space in the list. */
+  .qg-items > li.qg-pin-item {
+    display: contents;
+  }
+
   /* Coordinate-pinned children get absolute placement.
      Section-local coords (0..1) are computed by JS and stored as
      --qg-local-x / --qg-local-y. The component also measures each pin

package/src/web-components/quality-target/_quality-utils.js

@@ -3,7 +3,7 @@
  *
  * Combines the prior _nfr-utils.js (default ilities, default cost
  * weights, validation invariants) with _radar-geometry.js (axis
- * angles, vector/envelope points, SVG builder), with the addition
+ * angles, vector points, SVG builder), with the addition
  * of click-to-edit dialog state helpers.
  *
  * Domain-neutral schema property names are unchanged: vector,
@@ -37,7 +37,7 @@ export const LEVEL_LABELS = Object.freeze({
 });
 
 /** Default cost weights when picking an ility as Critical. Sum = 40. */
-export const DEFAULT_COST_WEIGHTS = Object.freeze({
+const DEFAULT_COST_WEIGHTS = Object.freeze({
   accessibility: 3,
   performance: 5,
   security: 5,
@@ -65,20 +65,6 @@ const ILITY_LABELS = Object.freeze({
   privacy: 'Privacy',
 });
 
-const ILITY_ABBR = Object.freeze({
-  accessibility: 'a11y',
-  internationalization: 'i18n',
-  maintainability: 'maint',
-  observability: 'obs',
-  compatibility: 'compat',
-  portability: 'porta',
-  performance: 'perf',
-  reliability: 'rely',
-  scalability: 'scale',
-  security: 'sec',
-  privacy: 'priv',
-});
-
 const LEVEL_RATIO = Object.freeze({
   critical:       1,
   important:      0.6,
@@ -95,10 +81,6 @@ export function ilityLabel(ility) {
     .replace(/\b\w/g, c => c.toUpperCase());
 }
 
-export function ilityAbbr(ility) {
-  return ILITY_ABBR[ility] || ility;
-}
-
 // ── Cost weights ──────────────────────────────────────────────────
 
 export function mergeCostWeights(ilities, overrides = {}) {
@@ -213,20 +195,6 @@ export function axisAngles(n) {
   return out;
 }
 
-/**
- * Fraction of `radius` the capacity envelope reaches per axis.
- * Returns null when capacity is unbounded.
- */
-export function envelopeRatio({ costWeights = {}, capacityPoints, ilities }) {
-  if (!Number.isFinite(capacityPoints)) return null;
-  const total = ilities.reduce((s, k) => {
-    const w = Number(costWeights[k]);
-    return s + (Number.isFinite(w) && w > 0 ? w : 0);
-  }, 0);
-  if (total <= 0) return 0;
-  return Math.min(1, Math.max(0, capacityPoints / total));
-}
-
 /** Per-ility {x, y, ility, level} points for the chosen vector. */
 export function vectorPoints({ ilities, vector = {}, radius }) {
   const angles = axisAngles(ilities.length);
@@ -242,18 +210,6 @@ export function vectorPoints({ ilities, vector = {}, radius }) {
   });
 }
 
-/** Per-ility {x, y, ility} points for the capacity envelope. */
-export function envelopePoints({ ilities, costWeights, capacityPoints, radius }) {
-  const ratio = envelopeRatio({ costWeights, capacityPoints, ilities });
-  if (ratio == null) return null;
-  const angles = axisAngles(ilities.length);
-  return ilities.map((k, i) => ({
-    ility: k,
-    x: round(Math.cos(angles[i]) * radius * ratio),
-    y: round(Math.sin(angles[i]) * radius * ratio),
-  }));
-}
-
 /** Outer axis endpoints — used for the spoke + label positions. */
 export function axisOuterPoints({ ilities, radius }) {
   const angles = axisAngles(ilities.length);

package/src/web-components/review-surface/README.md

@@ -92,13 +92,15 @@ With JavaScript:
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `review-surface:ready` | `{ pinCount }` | After render |
+| `review-surface:upgraded` | — | Once, on first connect |
+| `review-surface:ready` | `{ pinCount }` | Once, after the initial pins render |
 | `review-surface:add` | `{ pin }` | Pin created |
 | `review-surface:update` | `{ pin, changes }` | Pin modified |
 | `review-surface:remove` | `{ pin }` | Pin deleted |
 | `review-surface:resolve` | `{ pin }` | Pin resolved |
 | `review-surface:select` | `{ pin }` | Popover opened |
 | `review-surface:mode` | `{ mode }` | Mode toggled |
+| `review-surface:pins-changed` | `{ pins, source }` | After `.pins` assignment |
 
 ## Adapters
 
@@ -121,22 +123,24 @@ Set via property:
 ```js
 document.querySelector('review-surface').adapter = myCustomAdapter;
 ```
-Must implement: `load()`, `save(pin)`, `update(id, changes)`, `remove(id)`.
+Must implement: `load()`, `save(pin)`, `update(id, changes, pin)`, `remove(id)`.
+`update` receives the component's full pin as a third argument so it can
+upsert pins it did not create (loaded via `src` or `.pins`).
 
 ## Failure Modes
 
 - **No JavaScript:** Child content renders normally; pins are not shown.
 - **No CSS:** Shadow DOM styles are self-contained; layout degrades gracefully.
-- **Keyboard Only:** Tab navigates pins; Enter opens popover; Escape closes.
+- **Keyboard Only:** Tab navigates pins; Enter opens popover (focus moves into it); Escape closes and returns focus to the pin.
 - **Screen Reader:** Pin markers announced as "Pin N: [text preview]";
   live region announces create/delete/resolve actions.
 
 ## Accessibility
 
-- Pin markers are `<button>` with `aria-label`, `aria-expanded`, `aria-haspopup="dialog"`
+- Pin markers are `<button>` with `aria-label`, `aria-expanded`, `aria-haspopup="dialog"`, inside a `role="group"` overlay labelled "Review pins"
 - Popover uses `role="dialog"` with `aria-labelledby`
 - Toolbar uses `role="toolbar"` with `aria-label`
-- `aria-live="polite"` region announces pin actions
+- One persistent `aria-live="polite"` region announces pin actions
 - All transitions respect `prefers-reduced-motion: reduce`
 
 ## CSS Tokens

package/src/web-components/review-surface/api.json

@@ -5,7 +5,7 @@
   "description": "Pin-based annotation overlay for design review — wraps any content and adds interactive comment pins with pluggable persistence",
   "htmlvalidate": { "flow": true, "permittedContent": ["@flow"] },
   "attributes": [
-    { "name": "src",           "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL to JSON file containing pin data" },
+    { "name": "src",           "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL to JSON file containing pin data (an array, or { pins }). A newer value aborts an older in-flight request; removing it, or assigning .pins / importPins(), aborts a pending request (removing it mid-load falls back to the adapter)" },
     { "name": "editable",      "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Enables annotate mode toolbar and pin creation" },
     { "name": "adapter",       "kind": "host-api", "purpose": "config", "type": "string",  "description": "Persistence backend: memory | local | rest" },
     { "name": "endpoint",      "kind": "host-api", "purpose": "config", "type": "string",  "description": "REST endpoint URL (when adapter=rest)" },
@@ -19,12 +19,14 @@
     { "name": "(default)", "description": "The content to annotate (any HTML)" }
   ],
   "events": [
-    { "name": "review-surface:ready",   "detail": "{ pinCount }",      "description": "Fired after initial render" },
-    { "name": "review-surface:add",     "detail": "{ pin }",           "description": "Fired when a pin is created" },
-    { "name": "review-surface:update",  "detail": "{ pin, changes }",  "description": "Fired when a pin is modified" },
-    { "name": "review-surface:remove",  "detail": "{ pin }",           "description": "Fired when a pin is deleted" },
-    { "name": "review-surface:resolve", "detail": "{ pin }",           "description": "Fired when a pin is marked resolved" },
-    { "name": "review-surface:select",  "detail": "{ pin }",           "description": "Fired when a pin popover is opened" },
-    { "name": "review-surface:mode",    "detail": "{ mode }",          "description": "Fired when view/annotate mode toggles" }
+    { "name": "review-surface:upgraded",     "detail": "—",                            "description": "Fired once, on first connect, after the adapter is resolved and before the initial pin load. Not re-fired when the element is moved." },
+    { "name": "review-surface:ready",        "detail": "{ pinCount }",                 "description": "Fired once, after the initial pins (from src, the adapter, or a pre-connect .pins assignment) have loaded and rendered. Not re-fired on later renders." },
+    { "name": "review-surface:add",          "detail": "{ pin }",                      "description": "Fired when a pin is created (annotate-mode click or addPin())" },
+    { "name": "review-surface:update",       "detail": "{ pin, changes }",             "description": "Fired when a pin is modified (reply added, text set, re-opened)" },
+    { "name": "review-surface:remove",       "detail": "{ pin }",                      "description": "Fired when a pin is deleted" },
+    { "name": "review-surface:resolve",      "detail": "{ pin }",                      "description": "Fired when a pin is marked resolved" },
+    { "name": "review-surface:select",       "detail": "{ pin }",                      "description": "Fired when a pin popover is opened" },
+    { "name": "review-surface:mode",         "detail": "{ mode: 'view' | 'annotate' }", "description": "Fired when view/annotate mode toggles" },
+    { "name": "review-surface:pins-changed", "detail": "{ pins, source: 'property' }", "description": "Fired after a .pins assignment (not for adapter loads or addPin())" }
   ]
 }