@profpowell/vb-project-planning 0.1.0

package/src/web-components/capacity-plan/_capacity-utils.js

@@ -0,0 +1,56 @@
+/**
+ * Pure helpers for <capacity-plan>.
+ *
+ * Sums: capacity (from iron-triangle) − quality spend (from
+ * quality-target's criticalSum) − feature spend (from slotted
+ * work-items by data-capacity-cost) = slack.
+ */
+
+/** Read a numeric data-capacity-cost from one element; default 0. */
+export function workItemCost(el) {
+  if (!el) return 0;
+  const raw = el.dataset?.capacityCost ?? el.getAttribute?.('data-capacity-cost');
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/** Sum capacity-cost across an iterable of elements (work-items, etc.). */
+export function sumWorkCosts(elements) {
+  let total = 0;
+  for (const el of elements || []) total += workItemCost(el);
+  return total;
+}
+
+/** Compute the ledger numbers given the three inputs. */
+export function computeLedger({ capacityPoints, qualitySum, featureSum }) {
+  const cap = Number.isFinite(capacityPoints) ? capacityPoints : Infinity;
+  const q = Math.max(0, Number(qualitySum) || 0);
+  const f = Math.max(0, Number(featureSum) || 0);
+  const slack = Number.isFinite(cap) ? cap - q - f : Infinity;
+  return { capacity: cap, quality: q, features: f, slack };
+}
+
+/**
+ * Compute proportional bar widths (as percentages 0..100) for the
+ * stacked bar visualization. When over budget, the chunks normalize
+ * against the actual spend so the bars overflow visibly.
+ */
+export function barProportions({ capacity, quality, features }) {
+  if (!Number.isFinite(capacity) || capacity <= 0) {
+    // Unbounded budget: scale against spend so chunks have any width at all
+    const total = quality + features;
+    if (total <= 0) return { quality: 0, features: 0, slack: 100 };
+    return {
+      quality:  (quality / total) * 100,
+      features: (features / total) * 100,
+      slack:    0,
+    };
+  }
+  const spend = quality + features;
+  const denom = Math.max(capacity, spend);
+  return {
+    quality:  (quality  / denom) * 100,
+    features: (features / denom) * 100,
+    slack:    Math.max(0, (capacity - spend) / denom * 100),
+  };
+}

package/src/web-components/capacity-plan/api.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "capacity-plan",
+  "type": "web-component",
+  "description": "Compact ledger that ties iron-triangle capacity, quality-target spend, and slotted work-item costs into a stacked-bar plan view. Auto-binds via data-bind-triangle and data-bind-quality.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": ["@flow"]
+  },
+  "attributes": [
+    { "name": "data-bind-triangle", "kind": "data", "purpose": "config", "type": "string", "description": "ID of a sibling <iron-triangle> to read capacityPoints from" },
+    { "name": "data-bind-quality",  "kind": "data", "purpose": "config", "type": "string", "description": "ID of a sibling <quality-target> to read criticalSum from" }
+  ],
+  "slots": [
+    { "name": "(default)", "description": "Slot any elements with data-capacity-cost (notably <work-item>) and the plan sums them as the feature spend" }
+  ],
+  "events": [
+    { "name": "capacity-plan:overdrawn", "detail": "{ ledger, source }", "description": "Fires when the slack crosses zero in either direction (edge-triggered)" }
+  ]
+}

package/src/web-components/capacity-plan/logic.js

@@ -0,0 +1,222 @@
+/**
+ * <capacity-plan> — Tiny ledger that ties the planning chain together.
+ *
+ * Reads:
+ *   capacityPoints  ← <iron-triangle> via data-bind-triangle
+ *   qualitySum      ← <quality-target>'s criticalSum via data-bind-quality
+ *   featureSum      ← summed from slotted work-items' data-capacity-cost,
+ *                     OR set as a property
+ *
+ * Renders a compact two-column ledger:
+ *   numeric column (label + signed delta) + proportional stacked bar.
+ *
+ * Re-renders on bound triangle/quality changes and on slotted-children
+ * mutations.
+ */
+
+import { VBElement } from '../../lib/vb-element.js';
+import { registerComponent } from '../../lib/bundle-registry.js';
+import {
+  sumWorkCosts,
+  computeLedger,
+  barProportions,
+} from './_capacity-utils.js';
+
+class CapacityPlan extends VBElement {
+  static get observedAttributes() {
+    return ['data-bind-triangle', 'data-bind-quality'];
+  }
+
+  /** @type {(() => void) | null} */
+  #unbindTriangle = null;
+  /** @type {(() => void) | null} */
+  #unbindQuality = null;
+  /** @type {MutationObserver | null} */
+  #slotObserver = null;
+  /** @type {number | null} */
+  #featureSumOverride = null;
+  /** @type {boolean} */
+  #wasOver = false;
+
+  setup() {
+    this.#bindTriangle();
+    this.#bindQuality();
+    this.#observeSlotted();
+    this.#render();
+  }
+
+  teardown() {
+    this.#unbindTriangle?.();
+    this.#unbindQuality?.();
+    this.#slotObserver?.disconnect();
+    this.#unbindTriangle = null;
+    this.#unbindQuality = null;
+    this.#slotObserver = null;
+  }
+
+  attributeChangedCallback(name) {
+    if (!this.isConnected) return;
+    if (name === 'data-bind-triangle') { this.#bindTriangle(); this.#render(); }
+    else if (name === 'data-bind-quality') { this.#bindQuality(); this.#render(); }
+  }
+
+  // ── Public API ────────────────────────────────────────────────────
+
+  get capacityPoints() { return this.#triangleCap(); }
+  get qualitySum()     { return this.#qualitySum(); }
+
+  get featureSum() {
+    if (this.#featureSumOverride != null) return this.#featureSumOverride;
+    return sumWorkCosts(this.querySelectorAll('[data-capacity-cost]'));
+  }
+  set featureSum(n) {
+    this.#featureSumOverride = Number.isFinite(+n) ? +n : null;
+    this.#render();
+  }
+
+  get slack() {
+    return computeLedger({
+      capacityPoints: this.#triangleCap(),
+      qualitySum: this.#qualitySum(),
+      featureSum: this.featureSum,
+    }).slack;
+  }
+
+  // ── Internal: bindings ────────────────────────────────────────────
+
+  #findById(id) {
+    if (!id) return null;
+    const root = /** @type {any} */ (this.getRootNode());
+    return root.getElementById ? root.getElementById(id) : document.getElementById(id);
+  }
+
+  #bindTriangle() {
+    this.#unbindTriangle?.();
+    this.#unbindTriangle = null;
+    const el = this.#findById(this.dataset.bindTriangle);
+    if (!el || el.localName !== 'iron-triangle') return;
+    const handler = () => this.#render();
+    el.addEventListener('iron-triangle:change', handler);
+    this.#unbindTriangle = () => el.removeEventListener('iron-triangle:change', handler);
+  }
+
+  #bindQuality() {
+    this.#unbindQuality?.();
+    this.#unbindQuality = null;
+    const el = this.#findById(this.dataset.bindQuality);
+    if (!el || el.localName !== 'quality-target') return;
+    const handler = () => this.#render();
+    el.addEventListener('quality-target:change', handler);
+    this.#unbindQuality = () => el.removeEventListener('quality-target:change', handler);
+  }
+
+  #observeSlotted() {
+    if (this.#slotObserver) return;
+    this.#slotObserver = new MutationObserver((records) => {
+      // Ignore mutations that happen inside the rendered ledger table —
+      // otherwise we'd loop on our own innerHTML writes.
+      const meaningful = records.some(r => {
+        const target = /** @type {any} */ (r.target);
+        return !target.closest?.('[data-capacity-table]');
+      });
+      if (meaningful) this.#render();
+    });
+    this.#slotObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-capacity-cost'],
+    });
+  }
+
+  #triangleCap() {
+    const el = this.#findById(this.dataset.bindTriangle);
+    if (!el || el.localName !== 'iron-triangle') return Infinity;
+    const v = el.capacityPoints;
+    return Number.isFinite(v) && v > 0 ? v : Infinity;
+  }
+
+  #qualitySum() {
+    const el = this.#findById(this.dataset.bindQuality);
+    if (!el || el.localName !== 'quality-target') return 0;
+    return Number(el.criticalSum) || 0;
+  }
+
+  // ── Internal: render ──────────────────────────────────────────────
+
+  #render() {
+    const ledger = computeLedger({
+      capacityPoints: this.#triangleCap(),
+      qualitySum: this.#qualitySum(),
+      featureSum: this.featureSum,
+    });
+    const bars = barProportions(ledger);
+
+    let table = /** @type {HTMLElement | null} */ (this.querySelector(':scope > [data-capacity-table]'));
+    if (!table) {
+      table = document.createElement('section');
+      table.dataset.capacityTable = '';
+      // Prepend so the ledger is the headline; slotted work-items
+      // (the underlying data) render below.
+      this.prepend(table);
+    }
+
+    const capCell  = formatPts(ledger.capacity);
+    const qCell    = ledger.quality  > 0 ? `−${ledger.quality} pts`  : '0 pts';
+    const fCell    = ledger.features > 0 ? `−${ledger.features} pts` : '0 pts';
+    const slackCell = formatSignedSlack(ledger.slack);
+
+    table.innerHTML = `
+      <dl data-layout="grid" class="capacity-ledger" aria-label="Capacity ledger">
+        <div data-row="capacity">
+          <dt>Capacity</dt>
+          <dd class="num">${capCell}</dd>
+          <dd class="bar"><span class="bar-track"><span class="bar-fill bar-capacity" style="--w:100%"></span></span></dd>
+        </div>
+        <div data-row="quality">
+          <dt>Quality</dt>
+          <dd class="num">${qCell}</dd>
+          <dd class="bar"><span class="bar-track"><span class="bar-fill bar-quality" style="--w:${bars.quality.toFixed(1)}%"></span></span></dd>
+        </div>
+        <div data-row="features">
+          <dt>Features</dt>
+          <dd class="num">${fCell}</dd>
+          <dd class="bar"><span class="bar-track"><span class="bar-fill bar-features" style="--w:${bars.features.toFixed(1)}%"></span></span></dd>
+        </div>
+        <div data-row="slack" data-state="${ledger.slack < 0 ? 'over' : 'under'}">
+          <dt>Slack</dt>
+          <dd class="num">${slackCell}</dd>
+          <dd class="bar"><span class="bar-track"><span class="bar-fill bar-slack" style="--w:${bars.slack.toFixed(1)}%"></span></span></dd>
+        </div>
+      </dl>
+    `;
+
+    this.setState('overdrawn', ledger.slack < 0);
+
+    // Edge-triggered overdrawn event.
+    const isOver = ledger.slack < 0;
+    if (isOver !== this.#wasOver) {
+      this.dispatchEvent(new CustomEvent('capacity-plan:overdrawn', {
+        bubbles: true, composed: true,
+        detail: { ledger, source: 'render' },
+      }));
+      this.#wasOver = isOver;
+    }
+  }
+}
+
+function formatPts(n) {
+  if (!Number.isFinite(n)) return '∞';
+  return `${n} pts`;
+}
+
+function formatSignedSlack(n) {
+  if (!Number.isFinite(n)) return '∞';
+  if (n === 0) return '0 pts';
+  if (n > 0)   return `+${n} pts`;
+  return `${n} pts`;   // already signed (negative)
+}
+
+registerComponent('capacity-plan', CapacityPlan);
+
+export { CapacityPlan };

package/src/web-components/capacity-plan/static.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Capacity Plan (static fallback)</title>
+  <link rel="stylesheet" href="/src/main.css">
+</head>
+<body>
+  <!--
+    The ledger ties iron-triangle's capacity, quality-target's spend,
+    and slotted work-items' data-capacity-cost into one view.
+    Pre-upgrade: empty (the math is JS-only). For a no-JS path the
+    server can render the same ledger as a static <dl>.
+  -->
+  <iron-triangle id="shape"></iron-triangle>
+  <quality-target id="quality" data-bind-to="shape"></quality-target>
+
+  <capacity-plan data-bind-triangle="shape" data-bind-quality="quality">
+    <work-item data-capacity-cost="3">Bulk import</work-item>
+    <work-item data-capacity-cost="2">API webhooks</work-item>
+  </capacity-plan>
+</body>
+</html>

package/src/web-components/capacity-plan/styles.css

@@ -0,0 +1,84 @@
+/* capacity-plan — compact ledger tying triangle, quality, and work-items.
+
+   Pure CSS layout (no SVG). Two-column rows: numeric label/value on
+   the left, proportional stacked bar on the right. */
+
+capacity-plan {
+  display: block;
+  inline-size: 100%;
+  max-inline-size: var(--capacity-plan-max, 32rem);
+  margin-inline: auto;
+}
+
+capacity-plan .capacity-ledger {
+  display: grid;
+  grid-template-columns: minmax(8rem, 14rem) 1fr;
+  gap: var(--size-2xs, 0.25rem) var(--size-m, 1rem);
+  margin: 0;
+}
+
+capacity-plan .capacity-ledger > div {
+  display: contents;
+}
+
+capacity-plan .capacity-ledger dt {
+  font-weight: var(--font-weight-semibold, 600);
+  color: var(--color-text);
+}
+
+capacity-plan .capacity-ledger .num {
+  margin: 0;
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text-muted);
+  text-align: end;
+  padding-inline-end: var(--size-s);
+}
+
+capacity-plan .capacity-ledger .bar {
+  margin: 0;
+  align-self: center;
+}
+
+capacity-plan .bar-track {
+  display: block;
+  inline-size: 100%;
+  block-size: 0.6rem;
+  background: var(--color-surface-raised, color-mix(in oklab, var(--color-surface) 92%, currentColor 8%));
+  border-radius: var(--radius-pill, 999px);
+  overflow: hidden;
+}
+
+capacity-plan .bar-fill {
+  display: block;
+  block-size: 100%;
+  inline-size: var(--w, 0%);
+  border-radius: inherit;
+  transition: inline-size 200ms ease;
+}
+
+capacity-plan .bar-capacity {
+  background: color-mix(in oklab, var(--color-text) 25%, transparent);
+}
+capacity-plan .bar-quality {
+  background: var(--color-interactive);
+}
+capacity-plan .bar-features {
+  background: var(--color-success);
+}
+capacity-plan .bar-slack {
+  background: color-mix(in oklab, var(--color-text-muted) 35%, transparent);
+}
+
+capacity-plan [data-row="slack"][data-state="over"] .num {
+  color: var(--color-error);
+  font-weight: var(--font-weight-semibold, 600);
+}
+capacity-plan [data-row="slack"][data-state="over"] .bar-slack {
+  background: var(--color-error);
+}
+
+capacity-plan:state(overdrawn) .capacity-ledger {
+  outline: 2px solid var(--color-error);
+  outline-offset: var(--size-2xs);
+  border-radius: var(--radius-m);
+}

package/src/web-components/empathy-map/api.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "empathy-map",
+  "type": "web-component",
+  "description": "Four-quadrant empathy map visualization (Says, Thinks, Does, Feels) with optional flip-to-edit interaction",
+  "htmlvalidate": { "flow": true, "permittedContent": ["@flow"] },
+  "attributes": [
+    { "name": "title",      "kind": "host-api", "purpose": "config", "type": "string",  "description": "Map heading" },
+    { "name": "persona",    "kind": "host-api", "purpose": "config", "type": "string",  "description": "Persona name displayed in header" },
+    { "name": "persona-id", "kind": "host-api", "purpose": "config", "type": "string",  "description": "Links to a user-persona element by id" },
+    { "name": "summary",    "kind": "host-api", "purpose": "config", "type": "string",  "description": "One-line description" },
+    { "name": "src",        "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL to JSON file containing quadrant data" },
+    { "name": "editable",   "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Enables flip-to-edit on quadrants" },
+    { "name": "compact",    "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Reduced spacing variant" }
+  ],
+  "slots": [
+    { "name": "title",       "description": "Map heading (slot fallback for attribute)" },
+    { "name": "persona",     "description": "Persona name (slot fallback for attribute)" },
+    { "name": "summary",     "description": "One-line description (slot fallback for attribute)" },
+    { "name": "says",        "description": "Content for the Says quadrant" },
+    { "name": "thinks",      "description": "Content for the Thinks quadrant" },
+    { "name": "does",        "description": "Content for the Does quadrant" },
+    { "name": "feels",       "description": "Content for the Feels quadrant" },
+    { "name": "goals",       "description": "Optional goals summary below the grid" },
+    { "name": "pain-points", "description": "Optional pain points summary below the grid" }
+  ],
+  "events": [
+    { "name": "empathy-map:ready",  "detail": "{ title, persona }",    "description": "Fired after initial render" },
+    { "name": "empathy-map:update", "detail": "{ quadrant, items }", "description": "Fired when quadrant content changes via edit" }
+  ]
+}