@profpowell/vb-project-planning 0.1.0

package/src/web-components/quality-target/styles.css

@@ -0,0 +1,203 @@
+/* quality-target — polygon-as-UI quality picker + viz.
+
+   Three concentric reference rings (Critical 1.0 / Important 0.6 /
+   Acceptable 0.3) replace the old envelope polygon. Each axis
+   labels with the full ility name; set/unset states tint the label.
+   Capacity readout sits in a reserved hollow center. */
+
+quality-target {
+  display: block;
+  inline-size: 100%;
+  max-inline-size: var(--quality-target-max, 36rem);
+  margin-inline: auto;
+  container-type: inline-size;
+}
+
+quality-target > svg {
+  inline-size: 100%;
+  block-size: auto;
+  display: block;
+}
+
+/* ── Reference rings (Critical / Important / Acceptable) ──────── */
+
+quality-target svg .ring {
+  fill: none;
+  stroke: var(--color-border-muted, var(--color-border, #e5e7eb));
+  stroke-width: 1;
+  stroke-dasharray: 3 3;
+  pointer-events: none;
+}
+
+quality-target svg .ring-critical   { stroke: color-mix(in oklab, var(--color-error)   60%, transparent); }
+quality-target svg .ring-important  { stroke: color-mix(in oklab, var(--color-warning) 50%, transparent); }
+quality-target svg .ring-acceptable { stroke: color-mix(in oklab, var(--color-success) 50%, transparent); }
+
+/* ── Spokes ────────────────────────────────────────────────── */
+
+quality-target svg .spoke {
+  stroke: var(--color-border, #e5e7eb);
+  stroke-width: 0.75;
+  stroke-dasharray: 1 4;
+  pointer-events: none;
+}
+
+/* ── Vector polygon ───────────────────────────────────────── */
+
+quality-target svg .vector {
+  fill: var(--quality-target-vector-fill, color-mix(in oklab, var(--color-interactive) 22%, transparent));
+  stroke: var(--quality-target-vector-stroke, var(--color-interactive));
+  stroke-width: 1.5;
+  stroke-linejoin: round;
+  pointer-events: none;
+}
+
+quality-target svg .vector-spoke {
+  stroke: var(--quality-target-vector-stroke, var(--color-interactive));
+  stroke-width: 2;
+  stroke-linecap: round;
+  pointer-events: none;
+}
+
+/* ── Axis hit targets ──────────────────────────────────────── */
+
+quality-target svg .axis {
+  cursor: pointer;
+  outline: none;
+}
+
+quality-target svg .axis .hit {
+  fill: transparent;
+  stroke: transparent;
+  transition: fill 120ms ease, stroke 120ms ease;
+}
+
+quality-target svg .axis:hover .hit,
+quality-target svg .axis:focus-visible .hit {
+  fill: color-mix(in oklab, var(--color-interactive) 8%, transparent);
+  stroke: var(--color-interactive);
+  stroke-width: 1;
+  stroke-dasharray: 2 2;
+}
+
+quality-target svg .axis-label {
+  font-size: var(--quality-target-label-size, 0.625rem);
+  fill: var(--color-text-muted);
+  letter-spacing: 0.02em;
+  pointer-events: none;
+  font-weight: var(--font-weight-regular, 400);
+}
+
+/* Set/unset label styling — set axes get a colored, bolder label;
+   unset axes stay muted gray. */
+quality-target svg .axis[data-level] .axis-label {
+  font-weight: var(--font-weight-semibold, 600);
+}
+
+quality-target svg .axis[data-level="critical"]     .axis-label { fill: var(--color-error,   #dc2626); }
+quality-target svg .axis[data-level="important"]    .axis-label { fill: var(--color-warning, #b45309); }
+quality-target svg .axis[data-level="acceptable"]   .axis-label { fill: var(--color-success, #15803d); }
+quality-target svg .axis[data-level="not-relevant"] .axis-label {
+  fill: var(--color-text-muted, #6b7280);
+  text-decoration: line-through;
+  font-weight: var(--font-weight-regular, 400);
+}
+
+/* Markers — only render on set axes (component side); color-coded. */
+quality-target svg .axis .marker {
+  fill: var(--color-interactive);
+  stroke: var(--color-surface);
+  stroke-width: 1;
+  pointer-events: none;
+}
+quality-target svg .axis[data-level="critical"]     .marker { fill: var(--color-error,   #dc2626); }
+quality-target svg .axis[data-level="important"]    .marker { fill: var(--color-warning, #b45309); }
+quality-target svg .axis[data-level="acceptable"]   .marker { fill: var(--color-success, #16a34a); }
+quality-target svg .axis[data-level="not-relevant"] .marker { fill: var(--color-text-muted, #6b7280); opacity: 0.5; }
+
+/* ── Center capacity readout ──────────────────────────────── */
+
+quality-target svg .capacity-backdrop {
+  fill: var(--color-surface);
+  stroke: var(--color-border-muted, var(--color-border, #e5e7eb));
+  stroke-width: 1;
+  pointer-events: none;
+}
+
+quality-target svg .capacity-sum {
+  font-size: var(--quality-target-capacity-size, 1.25rem);
+  font-weight: var(--font-weight-bold, 700);
+  fill: var(--color-text);
+  font-variant-numeric: tabular-nums;
+  pointer-events: none;
+}
+quality-target svg .capacity-denom {
+  font-size: 0.55rem;
+  fill: var(--color-text-muted);
+  font-variant-numeric: tabular-nums;
+  pointer-events: none;
+}
+
+quality-target svg .center[data-over] .capacity-sum {
+  fill: var(--color-error);
+}
+quality-target:state(over-budget) svg .vector {
+  stroke: var(--color-warning);
+}
+
+/* ── Footer (overrun rationale + errors) ──────────────────── */
+
+quality-target .quality-footer {
+  margin-block-start: var(--size-m, 1rem);
+}
+
+quality-target [data-quality-overrun] {
+  padding: var(--size-m, 1rem);
+  border: var(--border-width-thin, 1px) solid var(--color-error);
+  border-radius: var(--radius-m);
+  background: var(--color-error-subtle, oklch(95% 0.05 27));
+  display: grid;
+  gap: var(--size-2xs, 0.25rem);
+}
+
+quality-target [data-quality-overrun][hidden] {
+  display: none;
+}
+
+quality-target [data-quality-errors] {
+  display: none;
+}
+quality-target:state(missing-rationale) [data-quality-errors] {
+  display: block;
+}
+
+/* ── Per-ility dialogs ──────────────────────────────────── */
+
+quality-target > dialog.quality-dialog {
+  inline-size: min(28rem, 92vw);
+  border: var(--border-width-thin, 1px) solid var(--color-border);
+  border-radius: var(--radius-l, 0.75rem);
+  padding: var(--size-l, 1.5rem);
+  background: var(--color-surface);
+  color: var(--color-text);
+}
+
+quality-target > dialog.quality-dialog::backdrop {
+  background: oklch(from var(--color-surface) l c h / 0.5);
+  backdrop-filter: blur(2px);
+}
+
+quality-target > dialog.quality-dialog h3 {
+  margin: 0 0 var(--size-m) 0;
+  font-size: var(--font-size-l, 1.125rem);
+}
+
+quality-target > dialog.quality-dialog fieldset {
+  border: 1px solid var(--color-border-muted, var(--color-border));
+}
+
+quality-target[disabled],
+quality-target[locked] {
+  opacity: 0.85;
+  pointer-events: none;
+}

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

@@ -0,0 +1,25 @@
+{
+  "$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>.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": ["@flow"]
+  },
+  "attributes": [
+    { "name": "data-priority", "kind": "data",     "purpose": "visual-variant", "type": "enum", "values": ["critical", "important", "acceptable", "not-relevant"], "description": "Drives :state(priority-*), default pill text, and accent color" },
+    { "name": "data-conflict", "kind": "data",     "purpose": "semantic-state", "type": "boolean", "description": "Flag a conflict / drift note; renders an emphasized border" },
+    { "name": "tabindex",      "kind": "native",   "purpose": "config",         "type": "number", "description": "Set to 0 to make the card directly focusable + activatable (otherwise wrap in <a>/<button>)" }
+  ],
+  "slots": [
+    { "name": "name",          "description": "Ility label (e.g. \"Performance\")" },
+    { "name": "badge",         "description": "Category / version / source tag (small uppercase muted text)" },
+    { "name": "priority-pill", "description": "Author-supplied custom pill; default pill renders from data-priority when this slot is empty" },
+    { "name": "rationale",     "description": "Why this priority was chosen (especially for Critical rows)" },
+    { "name": "conflicts",     "description": "Short conflict / drift note (paired with data-conflict)" }
+  ],
+  "events": [
+    { "name": "requirement-card:click", "detail": "{ priority, hasConflict, originalEvent }", "description": "Bubbles when the card is activated by mouse, keyboard, or touch (only when the card is interactive — wrapped in <a>/<button> or has tabindex)" }
+  ]
+}

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

@@ -0,0 +1,166 @@
+/**
+ * <requirement-card> — Display atom for ONE NFR ility row.
+ *
+ * Display-only. The prioritization decision lives in <nfr-compass>;
+ * 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.
+ *
+ * Slots:
+ *   name           — ility label (e.g. "Performance")
+ *   badge          — category / version / source tag
+ *   priority-pill  — author-supplied custom pill (otherwise the default
+ *                    pill renders from data-priority)
+ *   rationale      — why this priority was chosen (visible especially
+ *                    for Critical rows)
+ *   conflicts      — short conflict / drift note
+ *
+ * Attributes:
+ *   data-priority  — critical | important | acceptable | not-relevant
+ *   data-conflict  — boolean (presence flag)
+ *
+ * Emits:
+ *   requirement-card:click — bubbles a structured detail when the card
+ *                            is activated (mouse, keyboard, or touch);
+ *                            parent components can wire navigation.
+ *
+ * Pattern reference: matches the shadow-DOM + slot conventions from
+ * <score-card> (also a single-row dashboard atom).
+ */
+
+import { styles } from './styles.js';
+import { VBElement } from '../../lib/vb-element.js';
+import { registerComponent } from '../../lib/bundle-registry.js';
+
+const PRIORITIES = Object.freeze(['critical', 'important', 'acceptable', 'not-relevant']);
+const PRIORITY_LABELS = Object.freeze({
+  'critical':     'Critical',
+  'important':    'Important',
+  'acceptable':   'Acceptable',
+  'not-relevant': 'Not relevant',
+});
+const OPTIONAL_SLOTS = ['badge', 'priority-pill', 'rationale', 'conflicts'];
+
+const TEMPLATE = `
+  <style>${styles}</style>
+  <article class="card" part="card">
+    <header class="head" part="head">
+      <span class="name" part="name"><slot name="name"></slot></span>
+      <span class="badge" part="badge"><slot name="badge"></slot></span>
+    </header>
+    <span class="pill" part="pill">
+      <slot name="priority-pill"><span class="priority-default" part="priority-default" data-priority-default></span></slot>
+    </span>
+    <p class="rationale" part="rationale"><slot name="rationale"></slot></p>
+    <p class="conflicts" part="conflicts"><slot name="conflicts"></slot></p>
+  </article>
+`;
+
+class RequirementCard extends VBElement {
+  static get observedAttributes() {
+    return ['data-priority', 'data-conflict', 'tabindex'];
+  }
+
+  setup() {
+    if (!this.shadowRoot) {
+      const root = this.attachShadow({ mode: 'open' });
+      root.innerHTML = TEMPLATE;
+      for (const name of OPTIONAL_SLOTS) {
+        const slot = root.querySelector(`slot[name="${name}"]`);
+        slot?.addEventListener('slotchange', () => this.#syncSlot(name, slot));
+        this.#syncSlot(name, slot);
+      }
+    } else {
+      for (const name of OPTIONAL_SLOTS) {
+        const slot = this.shadowRoot.querySelector(`slot[name="${name}"]`);
+        this.#syncSlot(name, slot);
+      }
+    }
+    this.#syncPriority();
+    this.#syncDefaultPill();
+    this.#syncInteractive();
+
+    this.listen(this, 'click', (e) => this.#onActivate(e));
+    this.listen(this, 'keydown', (e) => {
+      const ke = /** @type {KeyboardEvent} */ (e);
+      if ((ke.key === 'Enter' || ke.key === ' ') && this.#interactive) {
+        ke.preventDefault();
+        this.#onActivate(ke);
+      }
+    });
+  }
+
+  attributeChangedCallback(name) {
+    if (!this.isConnected) return;
+    if (name === 'data-priority') {
+      this.#syncPriority();
+      this.#syncDefaultPill();
+    } else if (name === 'data-conflict') {
+      // Border + shadow are CSS-driven via [data-conflict]; no JS needed.
+    } else if (name === 'tabindex') {
+      this.#syncInteractive();
+    }
+  }
+
+  // ── Public API ────────────────────────────────────────────────────
+
+  get priority() { return (this.dataset.priority || '').toLowerCase(); }
+  set priority(v) {
+    const next = String(v || '').toLowerCase();
+    if (PRIORITIES.includes(next)) this.dataset.priority = next;
+    else delete this.dataset.priority;
+  }
+
+  get hasConflict() { return this.hasAttribute('data-conflict'); }
+  set hasConflict(v) {
+    if (v) this.setAttribute('data-conflict', '');
+    else this.removeAttribute('data-conflict');
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────
+
+  get #interactive() {
+    return this.hasAttribute('tabindex') || this.closest('a[href], button');
+  }
+
+  #syncSlot(name, slot) {
+    const hasContent = !!slot && slot.assignedNodes({ flatten: true }).some(n =>
+      n.nodeType === Node.ELEMENT_NODE ||
+      (n.nodeType === Node.TEXT_NODE && n.textContent.trim().length > 0)
+    );
+    this.setState(`has-${name}`, hasContent);
+  }
+
+  #syncPriority() {
+    const value = (this.dataset.priority || '').toLowerCase();
+    for (const p of PRIORITIES) this.setState(`priority-${p}`, p === value);
+  }
+
+  #syncDefaultPill() {
+    const value = (this.dataset.priority || '').toLowerCase();
+    const el = this.shadowRoot?.querySelector('[data-priority-default]');
+    if (!el) return;
+    el.textContent = PRIORITY_LABELS[value] || '';
+  }
+
+  #syncInteractive() {
+    this.setState('interactive', !!this.#interactive);
+  }
+
+  #onActivate(event) {
+    if (!this.#interactive) return;
+    this.dispatchEvent(new CustomEvent('requirement-card:click', {
+      bubbles: true, composed: true,
+      detail: {
+        priority: this.priority || null,
+        hasConflict: this.hasConflict,
+        originalEvent: event,
+      },
+    }));
+  }
+}
+
+registerComponent('requirement-card', RequirementCard);
+
+export { RequirementCard };

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

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>requirement-card (static fallback)</title>
+</head>
+<body>
+  <!--
+    Display-only card for ONE NFR ility row. The prioritization
+    decision lives in <nfr-compass>; this is the visual atom.
+    Pre-upgrade, the card renders as a plain article — no JS needed
+    for it to be readable.
+  -->
+  <requirement-card data-priority="critical">
+    <span slot="name">Performance</span>
+    <span slot="badge">Quality attribute</span>
+    <p slot="rationale">Sub-200ms TTI is our differentiator vs Competitor X.</p>
+  </requirement-card>
+
+  <requirement-card data-priority="not-relevant">
+    <span slot="name">Internationalization</span>
+    <span slot="badge">Quality attribute</span>
+  </requirement-card>
+
+  <!-- Drill-down: wrap in <a href> to make the whole card clickable -->
+  <a href="/requirements?ility=security">
+    <requirement-card data-priority="important" data-conflict>
+      <span slot="name">Security</span>
+      <span slot="badge">Quality attribute</span>
+      <p slot="rationale">SOC 2 audit pending Q2.</p>
+      <p slot="conflicts">Vector decided against an older Iron Triangle — re-review.</p>
+    </requirement-card>
+  </a>
+</body>
+</html>

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

@@ -0,0 +1,114 @@
+/**
+ * Shadow DOM styles for <requirement-card>
+ *
+ * Display-only card for one ility's prioritization decision.
+ * Theme tokens swap automatically across light/dark and brand themes.
+ */
+export const styles = `
+  :host {
+    --_padding:        var(--requirement-card-padding, var(--size-m, 1rem));
+    --_radius:         var(--requirement-card-radius, var(--radius-m, 0.5rem));
+    --_gap:            var(--requirement-card-gap, var(--size-2xs, 0.25rem));
+    --_surface:        var(--requirement-card-surface, var(--color-surface, #fff));
+    --_border:         var(--requirement-card-border, 1px solid var(--color-border, #e5e7eb));
+    --_text:           var(--requirement-card-text, var(--color-text, #1a1a1a));
+    --_muted:          var(--requirement-card-muted, var(--color-text-muted, #6b7280));
+    --_critical-bg:    var(--requirement-card-critical-bg,    var(--color-error-subtle, oklch(95% 0.05 27)));
+    --_critical-fg:    var(--requirement-card-critical-fg,    var(--color-error, #dc2626));
+    --_important-bg:   var(--requirement-card-important-bg,   var(--color-warning-subtle, oklch(95% 0.05 80)));
+    --_important-fg:   var(--requirement-card-important-fg,   var(--color-warning, #b45309));
+    --_acceptable-bg:  var(--requirement-card-acceptable-bg,  var(--color-success-subtle, oklch(95% 0.05 145)));
+    --_acceptable-fg:  var(--requirement-card-acceptable-fg,  var(--color-success, #15803d));
+    --_skipped-bg:     var(--requirement-card-skipped-bg,     var(--color-surface-raised, var(--color-surface, #f5f5f5)));
+    --_skipped-fg:     var(--requirement-card-skipped-fg,     var(--color-text-muted, #6b7280));
+    --_conflict:       var(--requirement-card-conflict-color, var(--color-error, #dc2626));
+
+    display: block;
+    padding: var(--_padding);
+    border-radius: var(--_radius);
+    background: var(--_surface);
+    border: var(--_border);
+    color: var(--_text);
+    container-type: inline-size;
+  }
+
+  .card {
+    display: grid;
+    gap: var(--_gap);
+  }
+
+  .head {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: var(--size-s, 0.75rem);
+  }
+
+  .name {
+    font-weight: var(--font-weight-semibold, 600);
+    font-size: var(--font-size-md, 1rem);
+  }
+
+  .badge ::slotted([slot="badge"]) {
+    font-size: var(--font-size-xs, 0.75em);
+    color: var(--_muted);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+
+  .pill ::slotted([slot="priority-pill"]),
+  .priority-default {
+    display: inline-block;
+    padding: 0.15em 0.6em;
+    border-radius: var(--radius-pill, 999px);
+    font-size: var(--font-size-xs, 0.75em);
+    font-weight: var(--font-weight-semibold, 600);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+
+  /* Priority-driven surface tinting on the card itself (when no slotted pill) */
+  :host(:state(priority-critical))     { border-color: var(--_critical-fg); }
+  :host(:state(priority-important))    { border-color: var(--_important-fg); }
+  :host(:state(priority-acceptable))   { border-color: var(--_acceptable-fg); }
+  :host(:state(priority-not-relevant)) { opacity: 0.6; }
+
+  :host(:state(priority-critical))     .priority-default { background: var(--_critical-bg);    color: var(--_critical-fg); }
+  :host(:state(priority-important))    .priority-default { background: var(--_important-bg);   color: var(--_important-fg); }
+  :host(:state(priority-acceptable))   .priority-default { background: var(--_acceptable-bg);  color: var(--_acceptable-fg); }
+  :host(:state(priority-not-relevant)) .priority-default { background: var(--_skipped-bg);     color: var(--_skipped-fg); text-decoration: line-through; }
+
+  /* Hide the default pill when the author supplied one via slot */
+  :host(:state(has-priority-pill)) .priority-default { display: none; }
+
+  .rationale ::slotted([slot="rationale"]) {
+    color: var(--_muted);
+    font-size: var(--font-size-sm, 0.875rem);
+    line-height: 1.45;
+  }
+
+  .conflicts ::slotted([slot="conflicts"]) {
+    color: var(--_conflict);
+    font-size: var(--font-size-sm, 0.875rem);
+    font-weight: var(--font-weight-semibold, 600);
+  }
+
+  /* When no rationale or conflicts content, collapse the slot row */
+  :host(:not(:state(has-rationale))) .rationale,
+  :host(:not(:state(has-conflicts))) .conflicts { display: none; }
+
+  /* Conflict flag */
+  :host([data-conflict]) {
+    border-color: var(--_conflict);
+    box-shadow: inset 0 0 0 1px var(--_conflict);
+  }
+
+  /* Interactive: bubble click event so parents can wire up navigation */
+  :host { cursor: default; }
+  :host(:state(interactive)) { cursor: pointer; }
+  :host(:state(interactive)):hover { background: color-mix(in oklab, var(--_surface) 92%, currentColor 8%); }
+  :host(:focus-visible) {
+    outline: 2px solid var(--color-focus-ring, var(--color-interactive, currentColor));
+    outline-offset: 2px;
+  }
+`;