@profpowell/vb-project-planning 0.1.0

package/src/web-components/adr-wc/styles.js

@@ -0,0 +1,338 @@
+/**
+ * Shadow DOM styles for <adr-wc>
+ *
+ * 3-tier token pattern:
+ *   var(--adr-wc-*, var(--color-*, fallback))
+ *
+ * MADR-format Architectural Decision Record card.
+ * Sibling to user-story and work-item in the UX Planning Pack.
+ */
+const styles = `
+:host {
+  --_bg:        var(--adr-wc-bg, var(--color-surface, #ffffff));
+  --_text:      var(--adr-wc-text, var(--color-text, #1a1a1a));
+  --_muted:     var(--adr-wc-muted, var(--color-text-muted, #666));
+  --_border:    var(--adr-wc-border, var(--color-border, #e0e0e0));
+  --_accent:    var(--adr-wc-accent, var(--color-interactive, #0066cc));
+  --_card-bg:   var(--adr-wc-card-bg, var(--color-surface-raised, #f8f9fa));
+  --_highlight: var(--adr-wc-highlight, color-mix(in srgb, var(--_accent) 8%, transparent));
+  --_radius:    var(--adr-wc-radius, var(--radius-l, 0.75rem));
+  --_shadow:       var(--adr-wc-shadow, var(--shadow-sm));
+  --_shadow-hover: var(--adr-wc-shadow-hover, var(--shadow-md));
+  --_duration:     var(--adr-wc-duration, var(--duration-normal, 200ms));
+  --_ease:         var(--adr-wc-ease, var(--ease-default, ease));
+  --_space-2xs:    var(--adr-wc-space-2xs, var(--size-2xs, 0.25rem));
+  --_space-xs:     var(--adr-wc-space-xs, var(--size-xs, 0.5rem));
+  --_space-s:      var(--adr-wc-space-s, var(--size-s, 0.75rem));
+  --_space-m:      var(--adr-wc-space-m, var(--size-m, 1rem));
+  --_font-xs:      var(--adr-wc-font-xs, var(--font-size-xs, 0.75rem));
+  --_font-sm:      var(--adr-wc-font-sm, var(--font-size-sm, 0.875rem));
+  --_font-md:      var(--adr-wc-font-md, var(--font-size-md, 1rem));
+  --_font-lg:      var(--adr-wc-font-lg, var(--font-size-lg, 1.125rem));
+  --_font-mono:    var(--adr-wc-font-mono, var(--font-mono, ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, monospace));
+  --_radius-s:     var(--adr-wc-radius-s, var(--radius-s, 0.25rem));
+  --_radius-full:  var(--adr-wc-radius-full, var(--radius-full, 9999px));
+
+  display: block;
+  font-family: var(--adr-wc-font, var(--font-sans, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif));
+}
+
+*, *::before, *::after { box-sizing: border-box; margin: 0; }
+
+/* ── Card ──────────────────────────────────────────── */
+.adr-card {
+  background: var(--_bg);
+  border: 1px solid var(--_border);
+  border-radius: var(--_radius);
+  overflow: hidden;
+  box-shadow: var(--_shadow);
+  transition: box-shadow var(--_duration) var(--_ease);
+}
+
+.adr-card:hover {
+  box-shadow: var(--_shadow-hover);
+}
+
+/* ── Header ────────────────────────────────────────── */
+.adr-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--_space-s) var(--_space-m);
+  background: var(--_card-bg);
+  border-block-end: 1px solid var(--_border);
+  gap: var(--_space-s);
+  flex-wrap: wrap;
+}
+
+.adr-meta {
+  display: flex;
+  align-items: center;
+  gap: var(--_space-xs);
+  flex-wrap: wrap;
+  min-width: 0;
+}
+
+.adr-id {
+  font-size: var(--_font-xs);
+  font-weight: 600;
+  color: var(--_muted);
+  font-family: var(--_font-mono);
+}
+
+/* ── Status badge ──────────────────────────────────── */
+.adr-badges {
+  display: flex;
+  align-items: center;
+  gap: var(--_space-xs);
+}
+
+.adr-status {
+  font-size: 11px;
+  padding: 4px 10px;
+  border-radius: var(--_radius-full);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+}
+
+/* ── Date (slotted <time>) ─────────────────────────── */
+.adr-date-wrap {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: var(--_font-xs);
+  color: var(--_muted);
+}
+
+.adr-date-wrap svg {
+  width: 12px;
+  height: 12px;
+  flex-shrink: 0;
+}
+
+::slotted([slot="date"]) {
+  font-size: var(--_font-xs);
+  font-family: var(--_font-mono);
+  color: var(--_muted);
+}
+
+/* ── Body ──────────────────────────────────────────── */
+.adr-body {
+  padding: 16px 20px;
+}
+
+/* ── Title (slotted heading) ───────────────────────── */
+.adr-title-wrap {
+  margin-block-end: 0;
+}
+
+::slotted([slot="title"]) {
+  font-size: var(--_font-lg) !important;
+  font-weight: 700 !important;
+  color: var(--_text) !important;
+  line-height: 1.4 !important;
+  margin: 0 !important;
+}
+
+/* Fallback title when no slot content */
+.adr-title-fallback {
+  font-size: var(--_font-lg);
+  font-weight: 700;
+  color: var(--_text);
+  line-height: 1.4;
+}
+
+/* ── Supersedes / Superseded-by links ──────────────── */
+.adr-links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  margin-block-start: var(--_space-s);
+}
+
+.adr-links-label {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--_muted);
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+  margin-inline-end: var(--_space-2xs);
+  align-self: center;
+}
+
+.adr-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-size: 11px;
+  font-weight: 500;
+  padding: 2px 8px;
+  border-radius: var(--_radius-s);
+  background: var(--_highlight);
+  color: var(--_accent);
+  text-decoration: none;
+}
+
+.adr-link:hover {
+  text-decoration: underline;
+}
+
+.adr-link svg {
+  width: 11px;
+  height: 11px;
+}
+
+/* ── Sections ──────────────────────────────────────── */
+.adr-sections {
+  border-block-start: 1px solid var(--_border);
+}
+
+.adr-section {
+  padding: 14px 20px;
+  border-block-end: 1px solid var(--_border);
+}
+
+.adr-section:last-child {
+  border-block-end: none;
+}
+
+.adr-section-header {
+  display: flex;
+  align-items: center;
+  gap: var(--_space-xs);
+  margin-block-end: var(--_space-s);
+}
+
+.adr-section-icon {
+  width: 22px;
+  height: 22px;
+  border-radius: 5px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.adr-section-icon svg {
+  width: 13px;
+  height: 13px;
+  fill: var(--color-text-inverted, #fff);
+}
+
+.adr-section-icon.context      { background: var(--color-accent,  #8b5cf6); }
+.adr-section-icon.decision     { background: var(--color-success, #22c55e); }
+.adr-section-icon.consequences { background: var(--color-warning, #f59e0b); }
+
+.adr-section-title {
+  font-size: var(--_font-xs);
+  font-weight: 600;
+  color: var(--_muted);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.adr-section-content {
+  color: var(--_text);
+  font-size: var(--_font-sm);
+  line-height: 1.6;
+}
+
+.adr-section-content ::slotted(ul),
+.adr-section-content ::slotted(ol) {
+  margin: 0;
+  padding-inline-start: 20px;
+}
+
+.adr-section-content ::slotted(p) {
+  margin: 0;
+}
+
+.slot-fallback {
+  color: var(--_muted);
+  font-style: italic;
+}
+
+/* ── Minimal detail ────────────────────────────────── */
+.adr-card--minimal {
+  padding: var(--_space-xs);
+  cursor: pointer;
+}
+
+.adr-card--minimal:hover {
+  box-shadow: var(--_shadow-hover);
+}
+
+.adr-card--minimal:focus-visible {
+  outline: 2px solid var(--_accent);
+  outline-offset: 2px;
+}
+
+.adr-card--minimal .adr-header { display: none; }
+.adr-card--minimal .adr-sections { display: none; }
+.adr-card--minimal .adr-links { display: none; }
+.adr-card--minimal .adr-date-wrap { display: none; }
+
+.adr-card--minimal .adr-body {
+  padding: var(--_space-xs) var(--_space-s);
+}
+
+.adr-card--minimal .adr-title-fallback,
+.adr-card--minimal ::slotted([slot="title"]) {
+  font-size: var(--_font-sm) !important;
+  font-weight: 600 !important;
+}
+
+.adr-card--minimal .adr-id {
+  display: block;
+  margin-block-end: var(--_space-2xs);
+}
+
+.adr-card--minimal .adr-status {
+  font-size: 10px;
+  padding: 2px 6px;
+}
+
+/* ── Compact detail — hide empty sections ──────────── */
+.adr-card--compact .adr-section[data-empty] {
+  display: none;
+}
+
+.adr-card--compact .slot-fallback {
+  display: none;
+}
+
+.adr-card--compact .adr-body {
+  padding: var(--_space-s) var(--_space-m);
+}
+
+/* ── Responsive ────────────────────────────────────── */
+@media (max-width: 480px) {
+  .adr-header {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .adr-badges {
+    width: 100%;
+    justify-content: flex-start;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .adr-card {
+    transition: none;
+  }
+}
+
+@media print {
+  .adr-card {
+    box-shadow: none;
+    break-inside: avoid;
+  }
+}
+
+.state-msg        { padding: var(--_space-m); font-size: var(--_font-sm); color: var(--_muted); font-style: italic; }
+.state-msg--error { color: var(--color-error-text, var(--color-error, #dc2626)); }
+`;
+
+export { styles };

package/src/web-components/burndown-chart/api.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "burndown-chart",
+  "type": "web-component",
+  "description": "Sprint burndown plot. Wraps <chart-wc> with auto-computed ideal line and scope-change annotations.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "start",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Sprint start date (ISO 8601, required)"
+    },
+    {
+      "name": "end",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Sprint end date (ISO 8601, inclusive, required)"
+    },
+    {
+      "name": "total",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "number",
+      "description": "Total points/items at sprint start (required)"
+    },
+    {
+      "name": "unit",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Display unit, default \"points\""
+    },
+    {
+      "name": "label",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Optional heading text (e.g. \"Sprint 14\")"
+    },
+    {
+      "name": "weekends",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "enum",
+      "values": [
+        "include",
+        "exclude"
+      ],
+      "description": "Whether weekends count toward the ideal-line slope"
+    }
+  ],
+  "structure": [
+    {
+      "element": "<template>",
+      "description": "Inline data source: <tr> rows with cells [date YYYY-MM-DD, remaining, optional ±delta scope-change]"
+    }
+  ],
+  "childAttributes": [],
+  "events": [
+    {
+      "name": "burndown-chart:ready",
+      "detail": "{ dayCount, total, scopeChanges }",
+      "description": "Fired after the chart renders"
+    }
+  ]
+}

package/src/web-components/burndown-chart/logic.js

@@ -0,0 +1,198 @@
+/**
+ * burndown-chart: Sprint burndown plot
+ *
+ * Thin composing preset that wraps <chart-wc type="line"> with two
+ * series: an `Actual` series from the author's daily remaining counts
+ * and an `Ideal` series the component computes from start/end/total.
+ *
+ * Replaces the boilerplate of hand-computing the ideal trend line and
+ * formatting two parallel data series. Authors supply only the daily
+ * actuals (and optional scope-change deltas) — the ideal slope is
+ * mechanical.
+ *
+ * Data source: a <template> child whose <tr> rows are
+ *   <tr><td>YYYY-MM-DD</td><td>remaining</td></tr>
+ *   <tr><td>YYYY-MM-DD</td><td>remaining</td><td>±N</td></tr>
+ * The optional 3rd cell is a scope-change delta on that day; the
+ * component renders an inline annotation note (no chart marker primitive
+ * exists in chart-wc yet, so we surface scope changes via a captioned
+ * list under the chart).
+ *
+ * @attr {string} start    - Sprint start date (ISO 8601, required)
+ * @attr {string} end      - Sprint end date (ISO 8601, required, inclusive)
+ * @attr {number} total    - Total points/items at sprint start (required)
+ * @attr {string} unit     - Display unit, default "points"
+ * @attr {string} label    - Optional heading text (e.g., "Sprint 14")
+ * @attr {string} weekends - "include" (default) or "exclude" from ideal slope
+ *
+ * @fires burndown-chart:ready - { dayCount, total, scopeChanges }
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+const MS_PER_DAY = 86_400_000;
+
+class BurndownChart extends VBElement {
+  setup() {
+    const start = this.getAttribute('start');
+    const end = this.getAttribute('end');
+    const total = parseFloat(this.getAttribute('total') || '');
+
+    if (!start || !end || !Number.isFinite(total)) {
+      console.warn('burndown-chart: requires start, end, and total attributes');
+      return false;
+    }
+
+    const startDate = BurndownChart.#parseDate(start);
+    const endDate = BurndownChart.#parseDate(end);
+    if (!startDate || !endDate || endDate < startDate) {
+      console.warn('burndown-chart: start/end dates invalid', start, end);
+      return false;
+    }
+
+    const includeWeekends = (this.getAttribute('weekends') || 'include') !== 'exclude';
+    const unit = this.getAttribute('unit') || 'points';
+    const label = this.getAttribute('label') || '';
+
+    const tmpl = this.querySelector(':scope > template');
+    const samples = tmpl ? BurndownChart.#parseTemplate(tmpl) : [];
+    const scopeChanges = samples.filter((s) => s.delta !== 0);
+
+    const dayLabels = BurndownChart.#enumerateDays(startDate, endDate);
+    const ideal = BurndownChart.#idealSeries(dayLabels, total, includeWeekends);
+    const actual = BurndownChart.#actualSeries(dayLabels, samples);
+
+    this.#render({ label, unit, dayLabels, actual, ideal, scopeChanges });
+
+    queueMicrotask(() => {
+      this.dispatchEvent(new CustomEvent('burndown-chart:ready', {
+        bubbles: true,
+        detail: { dayCount: dayLabels.length, total, scopeChanges: scopeChanges.length },
+      }));
+    });
+    return true;
+  }
+
+  #render({ label, unit, dayLabels, actual, ideal, scopeChanges }) {
+    [...this.children].forEach((c) => { if (c.tagName !== 'TEMPLATE') c.remove(); });
+
+    if (label) {
+      const h = document.createElement('header');
+      h.className = 'bdc-label';
+      h.textContent = label;
+      this.appendChild(h);
+    }
+
+    const chart = document.createElement('chart-wc');
+    chart.setAttribute('data-type', 'line');
+    chart.setAttribute('data-legend', '');
+    chart.setAttribute('data-tooltip', '');
+    chart.setAttribute('data-label-x', 'Day');
+    chart.setAttribute('data-label-y', unit);
+
+    const idealValues = {};
+    const actualValues = {};
+    dayLabels.forEach((d, i) => {
+      idealValues[d] = ideal[i];
+      if (actual[i] !== null) actualValues[d] = actual[i];
+    });
+
+    const payload = [
+      { name: 'Actual', values: actualValues },
+      { name: 'Ideal',  values: idealValues },
+    ];
+    chart.setAttribute('data-values', JSON.stringify(payload));
+    this.appendChild(chart);
+
+    if (scopeChanges.length) {
+      const notes = document.createElement('aside');
+      notes.className = 'bdc-scope-changes';
+      const heading = document.createElement('h4');
+      heading.textContent = 'Scope changes';
+      notes.appendChild(heading);
+      const list = document.createElement('ul');
+      for (const change of scopeChanges) {
+        const li = document.createElement('li');
+        const sign = change.delta > 0 ? '+' : '';
+        li.innerHTML = `<time datetime="${change.date}">${change.date}</time>: <strong>${sign}${change.delta} ${unit}</strong>`;
+        list.appendChild(li);
+      }
+      notes.appendChild(list);
+      this.appendChild(notes);
+    }
+  }
+
+  static #parseTemplate(tmpl) {
+    const out = [];
+    const trs = tmpl.content.querySelectorAll('tr');
+    for (const tr of trs) {
+      const cells = [...tr.children];
+      const date = cells[0]?.textContent?.trim();
+      const remaining = parseFloat(cells[1]?.textContent ?? '');
+      const delta = parseFloat(cells[2]?.textContent ?? '0') || 0;
+      if (!date || !Number.isFinite(remaining)) continue;
+      out.push({ date, remaining, delta });
+    }
+    return out;
+  }
+
+  static #parseDate(s) {
+    /* Treat YYYY-MM-DD as a local-midnight date so weekend math is
+       deterministic across viewer time zones. */
+    const m = String(s).match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (!m) return null;
+    return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  }
+
+  static #toISO(d) {
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${d.getFullYear()}-${m}-${day}`;
+  }
+
+  static #enumerateDays(start, end) {
+    const days = [];
+    for (let t = start.getTime(); t <= end.getTime(); t += MS_PER_DAY) {
+      days.push(BurndownChart.#toISO(new Date(t)));
+    }
+    return days;
+  }
+
+  static #idealSeries(dayLabels, total, includeWeekends) {
+    const isWeekend = (label) => {
+      const d = BurndownChart.#parseDate(label);
+      if (!d) return false;
+      const w = d.getDay();
+      return w === 0 || w === 6;
+    };
+    const workingIndices = dayLabels
+      .map((d, i) => ({ d, i, weekend: isWeekend(d) }))
+      .filter((entry) => includeWeekends || !entry.weekend);
+    const decrement = workingIndices.length > 1 ? total / (workingIndices.length - 1) : 0;
+    const out = new Array(dayLabels.length).fill(null);
+    let lastIdeal = total;
+    let workingSeen = 0;
+    for (let i = 0; i < dayLabels.length; i++) {
+      const isWeekendDay = isWeekend(dayLabels[i]);
+      if (includeWeekends || !isWeekendDay) {
+        out[i] = Math.max(0, total - decrement * workingSeen);
+        workingSeen++;
+        lastIdeal = out[i];
+      } else {
+        /* Weekend in exclude mode: hold previous ideal flat. */
+        out[i] = lastIdeal;
+      }
+    }
+    return out;
+  }
+
+  static #actualSeries(dayLabels, samples) {
+    const byDate = new Map(samples.map((s) => [s.date, s.remaining]));
+    return dayLabels.map((d) => (byDate.has(d) ? byDate.get(d) : null));
+  }
+}
+
+registerComponent('burndown-chart', BurndownChart);
+
+export { BurndownChart };

package/src/web-components/burndown-chart/static.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Burndown Chart — Static Fallback</title>
+</head>
+<body>
+  <!--
+    Static fallback for <burndown-chart>.
+
+    Upgrade relationship:
+    - Without JS: the <template> below is invisible (templates do not
+      render). The component is purely additive over <chart-wc>.
+    - With JS: the component reads start/end/total + the <template>
+      rows, computes the ideal-line series, builds a <chart-wc> with
+      two series (Actual + Ideal), and renders scope-change notes
+      below the chart when the optional 3rd cell is present.
+  -->
+
+  <burndown-chart start="2026-05-04" end="2026-05-15" total="42" label="Sprint 14">
+    <template>
+      <tr><td>2026-05-04</td><td>42</td></tr>
+      <tr><td>2026-05-05</td><td>40</td></tr>
+      <tr><td>2026-05-06</td><td>37</td></tr>
+      <tr><td>2026-05-07</td><td>32</td><td>+5</td></tr>
+      <tr><td>2026-05-08</td><td>28</td></tr>
+    </template>
+  </burndown-chart>
+</body>
+</html>

package/src/web-components/burndown-chart/styles.css

@@ -0,0 +1,59 @@
+/* burndown-chart: Sprint burndown plot */
+
+burndown-chart:not(:defined) {
+  display: block;
+}
+
+burndown-chart {
+  display: block;
+  font-family: var(--font-sans, system-ui);
+  color: var(--color-text, #1a1a1a);
+}
+
+@scope (burndown-chart) {
+  .bdc-label {
+    display: block;
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-text-muted, #666);
+    margin-block-end: var(--size-s, 0.75rem);
+  }
+
+  chart-wc {
+    display: block;
+    min-block-size: var(--burndown-min-height, 18rem);
+  }
+
+  .bdc-scope-changes {
+    margin-block-start: var(--size-m, 1rem);
+    padding: var(--size-s, 0.75rem) var(--size-m, 1rem);
+    background: var(--color-surface-raised, oklch(96% 0 0));
+    border-inline-start: var(--border-width-medium, 3px) solid var(--color-warning, oklch(70% 0.15 60));
+    border-radius: var(--radius-s, 0.25rem);
+    font-size: var(--font-size-sm, 0.875rem);
+  }
+
+  .bdc-scope-changes h4 {
+    margin: 0 0 var(--size-2xs, 0.25rem);
+    font-size: var(--font-size-xs, 0.75rem);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-text-muted, #666);
+  }
+
+  .bdc-scope-changes ul {
+    margin: 0;
+    padding-inline-start: var(--size-m, 1rem);
+  }
+
+  .bdc-scope-changes li {
+    margin-block: var(--size-3xs, 0.125rem);
+  }
+
+  .bdc-scope-changes time {
+    font-family: var(--font-mono, ui-monospace, monospace);
+    color: var(--color-text-muted, #666);
+  }
+}