@profpowell/vb-project-planning 0.2.0 → 0.2.2

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) {
@@ -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/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())" }
   ]
 }