@profpowell/vb-project-planning 0.2.1 → 0.2.3

package/src/web-components/adr-wc/api.json

@@ -5,13 +5,13 @@
   "description": "MADR-format Architectural Decision Record card with status, context, decision, consequences, and cross-referencing via supersedes chains",
   "htmlvalidate": { "flow": true, "permittedContent": ["@flow"] },
   "attributes": [
-    { "name": "adr-id",        "kind": "host-api", "purpose": "config", "type": "string",  "description": "ADR identifier (e.g., ADR-001), auto-sets HTML id" },
-    { "name": "status",        "kind": "host-api", "purpose": "config", "type": "string",  "description": "Status: proposed | accepted | deprecated | superseded" },
+    { "name": "adr-id",        "kind": "host-api", "purpose": "config", "type": "string",  "description": "ADR identifier (e.g., ADR-001); sets the HTML id on first connect when none is set" },
+    { "name": "status",        "kind": "host-api", "purpose": "config", "type": "enum", "values": ["proposed", "accepted", "deprecated", "superseded"], "default": "proposed", "description": "Decision status" },
     { "name": "supersedes",    "kind": "host-api", "purpose": "config", "type": "string",  "description": "Comma-separated ADR IDs this supersedes" },
     { "name": "superseded-by", "kind": "host-api", "purpose": "config", "type": "string",  "description": "Comma-separated ADR IDs that supersede this" },
-    { "name": "detail",        "kind": "host-api", "purpose": "config", "type": "string",  "description": "Detail level: full | compact | minimal" },
+    { "name": "detail",        "kind": "host-api", "purpose": "config", "type": "enum", "values": ["full", "compact", "minimal"], "default": "full", "description": "Detail level. minimal shows id, status and title only." },
     { "name": "compact",       "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Alias for detail=compact" },
-    { "name": "src",           "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL to JSON data" }
+    { "name": "src",           "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL of a JSON ADR record. Fetched once per value; a newer value aborts the older request. A YYYY-MM-DD date is shown as that calendar day in every time zone." }
   ],
   "slots": [
     { "name": "title",        "description": "Decision heading (e.g., <h2>)" },
@@ -21,6 +21,8 @@
     { "name": "consequences", "description": "Outcomes (positive and negative)" }
   ],
   "events": [
-    { "name": "adr-wc:ready", "detail": "{ adrId, title, status }", "description": "Fired after render" }
+    { "name": "adr-wc:ready", "detail": "{ adrId, title, status }", "description": "Once per element, after the first render at any detail level. With src, after the fetched data renders (not fired if the fetch fails). Not re-fired by attribute changes or moves." },
+    { "name": "adr-wc:upgraded", "detail": "", "description": "Once, in a microtask after first connect. Wait for this before assigning .data from a framework." },
+    { "name": "adr-wc:data-changed", "detail": "{ data, source: 'property' }", "description": "After .data is assigned" }
   ]
 }

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

@@ -19,9 +19,11 @@
  * @attr {string}  superseded-by - Comma-separated ADR IDs that supersede this
  * @attr {string}  detail        - full | compact | minimal
  * @attr {boolean} compact       - Alias for detail="compact"
- * @attr {string}  src           - URL to JSON data
+ * @attr {string}  src           - URL to JSON data (fetched once per value)
  *
- * @fires adr-wc:ready - After render with { adrId, status }
+ * @fires adr-wc:ready        - Once, after the first render (after the src data renders when src is set), detail: { adrId, title, status }
+ * @fires adr-wc:upgraded     - Once, after first connect
+ * @fires adr-wc:data-changed - After .data assignment, detail: { data, source: 'property' }
  *
  * @example
  * <adr-wc adr-id="ADR-001" status="accepted">
@@ -38,7 +40,10 @@
 
 import { styles } from './styles.js';
 import { registerComponent } from '../../lib/bundle-registry.js';
-import { esc, lucideSvg } from '../_ux-base.js';
+import { parseISODate, formatDate } from '../../lib/dates.js';
+import {
+  esc, lucideSvg, UXShadowElement, lookup, fillSlot, slottedChild, splitList, detailLevel, markEmptySections,
+} from '../_ux-base.js';
 
 /* ── Status metadata ──────────────────────────────── */
 
@@ -61,7 +66,9 @@ const ICONS = {
 
 /* ── Component ─────────────────────────────────────── */
 
-class AdrWc extends HTMLElement {
+class AdrWc extends UXShadowElement {
+  static readyEvent = 'adr-wc:ready';
+
   static get observedAttributes() {
     return [
       'adr-id', 'status',
@@ -70,48 +77,14 @@ class AdrWc extends HTMLElement {
     ];
   }
 
-  #slotCache = new Map();
-
-  constructor() {
-    super();
-    this.attachShadow({ mode: 'open' });
-  }
-
-  /* ── Slot caching ───────────────────────────────── */
-
-  #cacheSlotValues() {
-    for (const child of [...this.children]) {
-      const slotName = child.getAttribute('slot');
-      if (slotName) {
-        this.#slotCache.set(slotName, child.textContent.trim());
-      }
-    }
-  }
-
-  /* ── Lifecycle ─────────────────────────────────── */
+  /* ── Lifecycle (see UXShadowElement) ──────────── */
 
-  connectedCallback() {
-    this.#cacheSlotValues();
+  _setup() {
     if (this.adrId && !this.id) this.id = this.adrId;
-    if (this.hasAttribute('src')) {
-      this._loadSrc(this.getAttribute('src'));
-    }
-    this.#render();
-    this.setAttribute('data-upgraded', '');
   }
 
-  disconnectedCallback() {
-    this.removeAttribute('data-upgraded');
-  }
-
-  attributeChangedCallback(name, oldValue, newValue) {
-    if (oldValue !== newValue && this.shadowRoot) {
-      if (name === 'src' && this.isConnected) {
-        this._loadSrc(newValue);
-      } else {
-        this.#render();
-      }
-    }
+  _readyDetail() {
+    return { adrId: this.adrId, title: this.adrTitle, status: this.status };
   }
 
   /* ── Getters ───────────────────────────────────── */
@@ -121,31 +94,20 @@ class AdrWc extends HTMLElement {
 
   /** Read the title from the slotted heading's text content */
   get adrTitle() {
-    const slotted = this.querySelector('[slot="title"]');
-    return slotted?.textContent?.trim() || this.#slotCache.get('title') || '';
+    return this._slotText('title');
   }
 
   /** Read the date from the slotted <time>'s datetime attribute or text */
   get adrDate() {
-    const slotted = this.querySelector('[slot="date"]');
-    return slotted?.getAttribute('datetime') || slotted?.textContent?.trim() || this.#slotCache.get('date') || '';
+    const slotted = slottedChild(this, 'date');
+    return slotted?.getAttribute('datetime') || this._slotText('date');
   }
 
-  get supersedes() {
-    const raw = this.getAttribute('supersedes') || '';
-    return raw ? raw.split(',').map(s => s.trim()).filter(Boolean) : [];
-  }
+  get supersedes() { return splitList(this.getAttribute('supersedes')); }
 
-  get supersededBy() {
-    const raw = this.getAttribute('superseded-by') || '';
-    return raw ? raw.split(',').map(s => s.trim()).filter(Boolean) : [];
-  }
+  get supersededBy() { return splitList(this.getAttribute('superseded-by')); }
 
-  get _detailLevel() {
-    if (this.getAttribute('detail')) return this.getAttribute('detail');
-    if (this.hasAttribute('compact')) return 'compact';
-    return 'full';
-  }
+  get _detailLevel() { return detailLevel(this); }
 
   get _minimalLabel() {
     return this.adrTitle || this.adrId || 'ADR';
@@ -174,19 +136,13 @@ class AdrWc extends HTMLElement {
    * call. Idempotent for repeat calls.
    */
   set data(value) {
-    if (!value || typeof value !== 'object') return;
-    this._applyData(value);
-    this.#cacheSlotValues();
-    if (this.shadowRoot) this.#render();
-    this.dispatchEvent(new CustomEvent('adr-wc:data-changed', {
-      detail: { data: this.data, source: 'property' },
-      bubbles: true, composed: true,
-    }));
+    this._setData(value);
   }
 
   /**
    * Apply a data record to attributes + slotted children. Used by both
-   * the .data setter and async _loadSrc.
+   * the .data setter and the src loader. Slotted children are created only
+   * when absent (authored content wins).
    * @param {Record<string, unknown>} data
    */
   _applyData(data) {
@@ -201,73 +157,48 @@ class AdrWc extends HTMLElement {
       this.setAttribute('superseded-by', Array.isArray(data.supersededBy) ? data.supersededBy.join(',') : String(data.supersededBy));
     }
 
-    if (data.title && !this.querySelector('[slot="title"]')) {
-      const h = document.createElement('h3');
-      h.slot = 'title';
-      h.textContent = String(data.title);
-      this.appendChild(h);
-    }
-    if (data.date && !this.querySelector('[slot="date"]')) {
+    fillSlot(this, 'title', data.title, { tag: 'h3' });
+    if (data.date && !slottedChild(this, 'date')) {
+      // A calendar date: YYYY-MM-DD is local midnight, so April 1 stays
+      // April 1 west of UTC (new Date('2026-04-01') would show March 31).
+      const raw = String(data.date);
+      const day = parseISODate(raw);
       const t = document.createElement('time');
       t.slot = 'date';
-      t.setAttribute('datetime', String(data.date));
-      t.textContent = new Date(String(data.date)).toLocaleDateString(undefined, { year: 'numeric', month: 'long', day: 'numeric' });
+      t.setAttribute('datetime', raw);
+      t.textContent = day ? formatDate(day) : raw;
       this.appendChild(t);
     }
-    for (const key of ['context', 'decision']) {
-      if (data[key] && !this.querySelector(`[slot="${key}"]`)) {
-        const p = document.createElement('p');
-        p.slot = key;
-        p.textContent = String(data[key]);
-        this.appendChild(p);
-      }
-    }
-    if (data.consequences && !this.querySelector('[slot="consequences"]')) {
-      const ul = document.createElement('ul');
-      ul.slot = 'consequences';
-      const items = Array.isArray(data.consequences) ? data.consequences : [data.consequences];
-      for (const item of items) {
-        const li = document.createElement('li');
-        li.textContent = String(item);
-        ul.appendChild(li);
-      }
-      this.appendChild(ul);
-    }
+    fillSlot(this, 'context', data.context);
+    fillSlot(this, 'decision', data.decision);
+    fillSlot(this, 'consequences', data.consequences, { list: true });
   }
 
-  /* ── JSON loading ──────────────────────────────── */
+  /* ── JSON loading states ───────────────────────── */
 
-  async _loadSrc(url) {
-    if (!url) return;
-    const root = /** @type {ShadowRoot} */ (this.shadowRoot);
-    root.innerHTML = `<style>${styles}</style><div class="state-msg">Loading\u2026</div>`;
-    try {
-      const res = await fetch(url);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      const data = await res.json();
-
-      this._applyData(data);
-      this.#cacheSlotValues();
-      this.#render();
-    } catch (err) {
-      root.innerHTML = `<style>${styles}</style>` +
-        `<div class="state-msg state-msg--error">Could not load: ${esc(/** @type {Error} */ (err).message)}</div>`;
-    }
+  _renderLoading() {
+    /** @type {ShadowRoot} */ (this.shadowRoot).innerHTML =
+      `<style>${styles}</style><div class="state-msg">Loading\u2026</div>`;
+  }
+
+  /** @param {Error} err */
+  _renderError(err) {
+    /** @type {ShadowRoot} */ (this.shadowRoot).innerHTML = `<style>${styles}</style>` +
+      `<div class="state-msg state-msg--error">Could not load: ${esc(err.message)}</div>`;
   }
 
   /* ── Render ────────────────────────────────────── */
 
-  #render() {
+  _render() {
     const root = /** @type {ShadowRoot} */ (this.shadowRoot);
-    const statusInfo = STATUSES[this.status] || STATUSES.proposed;
+    const statusInfo = lookup(STATUSES, this.status, 'proposed');
     const level = this._detailLevel;
     const ariaLabel = this.adrId ? `ADR: ${esc(this.adrId)}` : 'Architectural Decision Record';
-    const hasDate = !!this.querySelector('[slot="date"]') || this.#slotCache.has('date');
+    const hasDate = !!slottedChild(this, 'date') || this._slotCache.has('date');
 
     if (level === 'minimal') {
       root.innerHTML = `<style>${styles}</style>
-        <article class="adr-card adr-card--minimal" role="article" aria-label="${ariaLabel}"
-          tabindex="0">
+        <article class="adr-card adr-card--minimal" role="article" aria-label="${ariaLabel}">
           <div class="adr-body">
             <div class="adr-meta">
               ${this.adrId ? `<span class="adr-id">${esc(this.adrId)}</span>` : ''}
@@ -350,24 +281,7 @@ class AdrWc extends HTMLElement {
 
       </article>`;
 
-    // Compact: mark empty slot sections
-    if (level === 'compact') {
-      for (const section of root.querySelectorAll('.adr-section')) {
-        const slot = section.querySelector('slot');
-        if (slot && slot.assignedNodes().length === 0) {
-          section.setAttribute('data-empty', '');
-        }
-      }
-    }
-
-    this.dispatchEvent(new CustomEvent('adr-wc:ready', {
-      detail: {
-        adrId: this.adrId,
-        title: this.adrTitle,
-        status: this.status,
-      },
-      bubbles: true, composed: true,
-    }));
+    if (level === 'compact') markEmptySections(root, '.adr-section');
   }
 }
 

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

@@ -2,7 +2,7 @@
   "$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.",
+  "description": "Sprint burndown plot. Wraps <chart-wc> with auto-computed ideal line and scope-change annotations. All attributes are observed: changing one on a live element re-renders.",
   "htmlvalidate": {
     "flow": true,
     "permittedContent": [
@@ -15,14 +15,14 @@
       "kind": "host-api",
       "purpose": "config",
       "type": "string",
-      "description": "Sprint start date (ISO 8601, required)"
+      "description": "Sprint start date (YYYY-MM-DD, local calendar day; required)"
     },
     {
       "name": "end",
       "kind": "host-api",
       "purpose": "config",
       "type": "string",
-      "description": "Sprint end date (ISO 8601, inclusive, required)"
+      "description": "Sprint end date (YYYY-MM-DD, inclusive; required)"
     },
     {
       "name": "total",
@@ -36,7 +36,8 @@
       "kind": "host-api",
       "purpose": "config",
       "type": "string",
-      "description": "Display unit, default \"points\""
+      "description": "Display unit for the y-axis and scope-change notes (rendered as text)",
+      "default": "\"points\""
     },
     {
       "name": "label",
@@ -54,7 +55,8 @@
         "include",
         "exclude"
       ],
-      "description": "Whether weekends count toward the ideal-line slope"
+      "description": "Whether weekends count toward the ideal-line slope",
+      "default": "\"include\""
     }
   ],
   "structure": [
@@ -68,7 +70,7 @@
     {
       "name": "burndown-chart:ready",
       "detail": "{ dayCount, total, scopeChanges }",
-      "description": "Fired after the chart renders"
+      "description": "Fired after each upgrade (first connect, reconnect, or a retried upgrade), in a microtask. Not re-fired when a live attribute change re-renders"
     }
   ]
 }

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

@@ -25,16 +25,68 @@
  * @attr {string} label    - Optional heading text (e.g., "Sprint 14")
  * @attr {string} weekends - "include" (default) or "exclude" from ideal slope
  *
+ * All six attributes are observed: changing any of them on a live element
+ * re-renders the chart in place. Dates are calendar days in local time
+ * (see src/lib/dates.js), so the day axis is stable across DST changes.
+ *
  * @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;
+import { parseISODate, toISODate, enumerateDays } from '../../lib/dates.js';
 
 class BurndownChart extends VBElement {
+  static get observedAttributes() {
+    return ['start', 'end', 'total', 'unit', 'label', 'weekends'];
+  }
+
+  /** True between connectedCallback and disconnectedCallback. */
+  #live = false;
+
+  connectedCallback() {
+    this.#live = true;
+    super.connectedCallback();
+  }
+
+  disconnectedCallback() {
+    this.#live = false;
+    super.disconnectedCallback();
+  }
+
+  attributeChangedCallback(_name, oldValue, newValue) {
+    if (oldValue === newValue || !this.#live) return;
+    if (this.hasAttribute('data-upgraded')) {
+      /* Live re-render. If the new config is invalid, drop the stale chart
+         rather than leave it showing the old range. */
+      if (!this.#renderFromAttributes()) this.#clearRendered();
+    } else {
+      /* An earlier upgrade was refused (e.g. total missing): retry now. */
+      super.connectedCallback();
+    }
+  }
+
   setup() {
+    if (!this.#renderFromAttributes()) return false;
+    const { dayCount, total, scopeChanges } = this.#lastRender;
+    queueMicrotask(() => {
+      this.dispatchEvent(new CustomEvent('burndown-chart:ready', {
+        bubbles: true,
+        detail: { dayCount, total, scopeChanges },
+      }));
+    });
+    return true;
+  }
+
+  /** @type {{ dayCount: number, total: number, scopeChanges: number }} */
+  #lastRender = { dayCount: 0, total: 0, scopeChanges: 0 };
+
+  #clearRendered() {
+    [...this.children].forEach((c) => { if (c.tagName !== 'TEMPLATE') c.remove(); });
+  }
+
+  /** Read attributes + template and render. Returns false when the config is invalid. */
+  #renderFromAttributes() {
     const start = this.getAttribute('start');
     const end = this.getAttribute('end');
     const total = parseFloat(this.getAttribute('total') || '');
@@ -44,8 +96,8 @@ class BurndownChart extends VBElement {
       return false;
     }
 
-    const startDate = BurndownChart.#parseDate(start);
-    const endDate = BurndownChart.#parseDate(end);
+    const startDate = parseISODate(start);
+    const endDate = parseISODate(end);
     if (!startDate || !endDate || endDate < startDate) {
       console.warn('burndown-chart: start/end dates invalid', start, end);
       return false;
@@ -59,23 +111,17 @@ class BurndownChart extends VBElement {
     const samples = tmpl ? BurndownChart.#parseTemplate(tmpl) : [];
     const scopeChanges = samples.filter((s) => s.delta !== 0);
 
-    const dayLabels = BurndownChart.#enumerateDays(startDate, endDate);
+    const dayLabels = 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 },
-      }));
-    });
+    this.#lastRender = { 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(); });
+    this.#clearRendered();
 
     if (label) {
       const h = document.createElement('header');
@@ -113,9 +159,16 @@ class BurndownChart extends VBElement {
       notes.appendChild(heading);
       const list = document.createElement('ul');
       for (const change of scopeChanges) {
+        /* Built with textContent: template cells and the unit attribute are
+           author data and must never be parsed as markup. */
         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>`;
+        const time = document.createElement('time');
+        time.setAttribute('datetime', change.date);
+        time.textContent = change.date;
+        const strong = document.createElement('strong');
+        strong.textContent = `${sign}${change.delta} ${unit}`;
+        li.append(time, ': ', strong);
         list.appendChild(li);
       }
       notes.appendChild(list);
@@ -128,40 +181,23 @@ class BurndownChart extends VBElement {
     const trs = tmpl.content.querySelectorAll('tr');
     for (const tr of trs) {
       const cells = [...tr.children];
-      const date = cells[0]?.textContent?.trim();
+      const raw = cells[0]?.textContent?.trim();
       const remaining = parseFloat(cells[1]?.textContent ?? '');
       const delta = parseFloat(cells[2]?.textContent ?? '0') || 0;
-      if (!date || !Number.isFinite(remaining)) continue;
+      if (!raw || !Number.isFinite(remaining)) continue;
+      /* Normalise YYYY-MM-DD[Thh:mm…] to YYYY-MM-DD so samples key against
+         the day axis. Anything else is kept verbatim (shown, never plotted);
+         Date's lenient fallback parsing would invent dates from junk. */
+      const parsed = /^\d{4}-\d{2}-\d{2}/.test(raw) ? parseISODate(raw) : null;
+      const date = parsed ? toISODate(parsed) : raw;
       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);
+      const d = parseISODate(label);
       if (!d) return false;
       const w = d.getDay();
       return w === 0 || w === 6;

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

@@ -5,27 +5,27 @@
   "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": "persona-id", "kind": "host-api", "purpose": "config", "type": "string",  "description": "Links the persona name to a user-persona element by id" },
+    { "name": "src",        "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL of a JSON record (title, persona, personaId, summary, quadrants, goals, painPoints). Fetched once per value; a newer value aborts the older request." },
     { "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": "title",       "description": "Map heading (e.g. <h2>). Defaults to \"Empathy Map\"." },
+    { "name": "summary",     "description": "One-line description (e.g. <p>)" },
+    { "name": "persona",     "description": "Not projected: the text of a slot=\"persona\" child is read as the persona name when the persona attribute is absent" },
+    { "name": "says",        "description": "Content for the Says quadrant (until the quadrant is edited)" },
+    { "name": "thinks",      "description": "Content for the Thinks quadrant (until the quadrant is edited)" },
+    { "name": "does",        "description": "Content for the Does quadrant (until the quadrant is edited)" },
+    { "name": "feels",       "description": "Content for the Feels quadrant (until the quadrant is edited)" },
     { "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" }
+    { "name": "empathy-map:ready",  "detail": "{ title, persona }",    "description": "Once per element, after the first render. With src, after the fetched data renders (not fired if the fetch fails). Not re-fired by later renders or moves." },
+    { "name": "empathy-map:update", "detail": "{ quadrant, items }", "description": "When an open quadrant editor is closed (Done, Escape, or closeQuadrant()). Not fired when no editor is open." },
+    { "name": "empathy-map:upgraded", "detail": "", "description": "Once, in a microtask after first connect. Wait for this before assigning .data from a framework." },
+    { "name": "empathy-map:data-changed", "detail": "{ data, source: 'property' }", "description": "After .data is assigned" }
   ]
 }