@profpowell/vb-project-planning 0.2.1 → 0.2.2

package/src/web-components/empathy-map/logic.js

@@ -24,34 +24,44 @@
  *     "goals": ["goal1"],
  *     "painPoints": ["pain1"]
  *   }
+ *
+ * Title and summary are content: `<h2 slot="title">`, `<p slot="summary">`
+ * (or the `title` / `summary` JSON fields, which create those children).
+ * Once a quadrant has been edited, it renders from the edited items; its
+ * slotted light-DOM content is no longer projected.
+ *
+ * @fires empathy-map:ready        - Once, after the first render (after the src data renders when src is set), detail: { title, persona }
+ * @fires empathy-map:update       - After an edit is committed (Done / Escape / closeQuadrant()), detail: { quadrant, items }
+ * @fires empathy-map:upgraded     - Once, after first connect
+ * @fires empathy-map:data-changed - After .data assignment, detail: { data, source: 'property' }
  */
 
 import { styles } from './styles.js';
 import { registerComponent } from '../../lib/bundle-registry.js';
 import { viewTransitionSwap } from '../../lib/vb-view-transition.js';
-import { esc, QUADRANT_META, EMOTION_META, lucideSvg, UX_ICONS } from '../_ux-base.js';
+import {
+  esc, QUADRANT_META, emotionMeta, isEmotion, lucideSvg, UX_ICONS, UXShadowElement, fillSlot, slottedChild,
+} from '../_ux-base.js';
 
 const QUADRANT_KEYS = ['says', 'thinks', 'does', 'feels'];
 
-class EmpathyMap extends HTMLElement {
+class EmpathyMap extends UXShadowElement {
+  static readyEvent = 'empathy-map:ready';
+
   static get observedAttributes() {
     return ['persona', 'persona-id', 'src', 'editable', 'compact'];
   }
 
-  #slotCache = new Map();
-
-  constructor() {
-    super();
-    this.attachShadow({ mode: 'open' });
-    /** @type {Object<string, string[]>|null} */
-    this.__quadrants = null;
-    /** @type {string[]|null} */
-    this.__goals = null;
-    /** @type {string[]|null} */
-    this.__painPoints = null;
-    /** @type {Set<string>} */
-    this._editingQuadrants = new Set();
-  }
+  /** @type {Object<string, string[]>|null} */
+  __quadrants = null;
+  /** @type {string[]|null} */
+  __goals = null;
+  /** @type {string[]|null} */
+  __painPoints = null;
+  /** @type {Set<string>} quadrants whose editor is open */
+  _editingQuadrants = new Set();
+  /** @type {Set<string>} quadrants edited at least once (render from data, not the slot) */
+  _editedQuadrants = new Set();
 
   /* ── Properties ─────────────────────────────────── */
 
@@ -61,7 +71,7 @@ class EmpathyMap extends HTMLElement {
   /** @param {Object<string, string[]>|null} data */
   set quadrants(data) {
     this.__quadrants = data;
-    if (this.isConnected) this._render();
+    if (this._isSetUp) this._render();
   }
 
   /** @returns {string[]|null} */
@@ -70,7 +80,7 @@ class EmpathyMap extends HTMLElement {
   /** @param {string[]|null} data */
   set goals(data) {
     this.__goals = data;
-    if (this.isConnected) this._render();
+    if (this._isSetUp) this._render();
   }
 
   /** @returns {string[]|null} */
@@ -79,45 +89,20 @@ class EmpathyMap extends HTMLElement {
   /** @param {string[]|null} data */
   set painPoints(data) {
     this.__painPoints = data;
-    if (this.isConnected) this._render();
-  }
-
-  /* ── Slot caching ───────────────────────────────── */
-
-  #cacheSlotValues() {
-    for (const child of this.children) {
-      const slot = child.getAttribute('slot');
-      if (slot) this.#slotCache.set(slot, child.textContent.trim());
-    }
+    if (this._isSetUp) this._render();
   }
 
+  /**
+   * Attribute value, else the text of a same-named light-DOM child (e.g.
+   * `<span slot="persona">`, read as data; it is not projected).
+   * @param {string} attr
+   */
   _resolve(attr) {
-    return this.getAttribute(attr) || this.#slotCache.get(attr) || '';
-  }
-
-  /* ── Lifecycle ─────────────────────────────────── */
-
-  connectedCallback() {
-    this.#cacheSlotValues();
-    this.setAttribute('data-upgraded', '');
-    if (this.hasAttribute('src')) {
-      this._loadSrc(this.getAttribute('src'));
-    } else {
-      this._render();
-    }
-  }
-
-  disconnectedCallback() {
-    this.removeAttribute('data-upgraded');
+    return this.getAttribute(attr) || this._slotCache.get(attr) || '';
   }
 
-  attributeChangedCallback(name) {
-    if (!this.isConnected) return;
-    if (name === 'src') {
-      this._loadSrc(this.getAttribute('src'));
-    } else {
-      this._render();
-    }
+  _readyDetail() {
+    return { title: this._slotText('title') || 'Empathy Map', persona: this._resolve('persona') };
   }
 
   // ── Data API (HTML-first / JS-first dual contract) ──────────────
@@ -127,8 +112,8 @@ class EmpathyMap extends HTMLElement {
    * slotted content. Mirrors what a consumer would assign to .data.
    */
   get data() {
-    const titleEl = this.querySelector('[slot="title"]');
-    const summaryEl = this.querySelector('[slot="summary"]');
+    const titleEl = slottedChild(this, 'title');
+    const summaryEl = slottedChild(this, 'summary');
     return {
       persona: this.getAttribute('persona') || undefined,
       personaId: this.getAttribute('persona-id') || undefined,
@@ -146,29 +131,22 @@ class EmpathyMap extends HTMLElement {
    * Emits empathy-map:data-changed { data, source: 'property' }.
    */
   set data(value) {
-    if (!value || typeof value !== 'object') return;
-    if (value.persona)   this.setAttribute('persona',    String(value.persona));
-    if (value.personaId) this.setAttribute('persona-id', String(value.personaId));
-    if (value.title && !this.querySelector('[slot="title"]')) {
-      const el = document.createElement('h2');
-      el.slot = 'title';
-      el.textContent = value.title;
-      this.appendChild(el);
-    }
-    if (value.summary && !this.querySelector('[slot="summary"]')) {
-      const el = document.createElement('p');
-      el.slot = 'summary';
-      el.textContent = value.summary;
-      this.appendChild(el);
-    }
-    if (value.quadrants  != null) this.__quadrants  = value.quadrants;
-    if (value.goals      != null) this.__goals      = value.goals;
-    if (value.painPoints != null) this.__painPoints = value.painPoints;
-    if (this.isConnected) this._render();
-    this.dispatchEvent(new CustomEvent('empathy-map:data-changed', {
-      detail: { data: this.data, source: 'property' },
-      bubbles: true, composed: true,
-    }));
+    this._setData(value);
+  }
+
+  /**
+   * Apply an empathy-map record (from .data or src). Title / summary create
+   * slotted children only when none are authored.
+   * @param {Record<string, any>} data
+   */
+  _applyData(data) {
+    if (data.persona)   this.setAttribute('persona',    String(data.persona));
+    if (data.personaId) this.setAttribute('persona-id', String(data.personaId));
+    fillSlot(this, 'title', data.title, { tag: 'h2' });
+    fillSlot(this, 'summary', data.summary);
+    if (data.quadrants  != null) this.__quadrants  = data.quadrants;
+    if (data.goals      != null) this.__goals      = data.goals;
+    if (data.painPoints != null) this.__painPoints = data.painPoints;
   }
 
   /* ── Public API ────────────────────────────────── */
@@ -184,7 +162,8 @@ class EmpathyMap extends HTMLElement {
   }
 
   /**
-   * Close a quadrant edit and save.
+   * Close a quadrant edit and save. No-op (and no update event) unless the
+   * quadrant's editor is open.
    * @param {string} name - Quadrant key: says|thinks|does|feels
    */
   closeQuadrant(name) {
@@ -192,41 +171,17 @@ class EmpathyMap extends HTMLElement {
     this._closeEdit(name);
   }
 
-  /* ── JSON loading ──────────────────────────────── */
+  /* ── JSON loading states ───────────────────────── */
 
-  async _loadSrc(src) {
-    if (!src || !this.shadowRoot) return;
-    this.shadowRoot.innerHTML = `<style>${styles}</style>` +
+  _renderLoading() {
+    /** @type {ShadowRoot} */ (this.shadowRoot).innerHTML = `<style>${styles}</style>` +
       `<div class="state-msg">Loading\u2026</div>`;
-    try {
-      const res = await fetch(src);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      const data = await res.json();
-      if (data.persona)   this.setAttribute('persona',    data.persona);
-      if (data.personaId) this.setAttribute('persona-id', data.personaId);
-      // Content → slotted elements
-      if (data.title && !this.querySelector('[slot="title"]')) {
-        const el = document.createElement('h2');
-        el.slot = 'title';
-        el.textContent = data.title;
-        this.appendChild(el);
-      }
-      if (data.summary && !this.querySelector('[slot="summary"]')) {
-        const el = document.createElement('p');
-        el.slot = 'summary';
-        el.textContent = data.summary;
-        this.appendChild(el);
-      }
-      this.__quadrants  = data.quadrants || null;
-      this.__goals      = data.goals || null;
-      this.__painPoints = data.painPoints || null;
-      this._render();
-    } catch (err) {
-      if (!this.shadowRoot) return;
-      const msg = err instanceof Error ? err.message : String(err);
-      this.shadowRoot.innerHTML = `<style>${styles}</style>` +
-        `<div class="state-msg state-msg--error">Could not load empathy map: ${esc(msg)}</div>`;
-    }
+  }
+
+  /** @param {Error} err */
+  _renderError(err) {
+    /** @type {ShadowRoot} */ (this.shadowRoot).innerHTML = `<style>${styles}</style>` +
+      `<div class="state-msg state-msg--error">Could not load empathy map: ${esc(err.message)}</div>`;
   }
 
   /* ── Render ────────────────────────────────────── */
@@ -236,11 +191,10 @@ class EmpathyMap extends HTMLElement {
     const personaId = this._resolve('persona-id') || '';
     const compact   = this.hasAttribute('compact');
     const editable  = this.hasAttribute('editable');
-    const hasTitle  = !!this.querySelector('[slot="title"]') || this.#slotCache.has('title');
-    const hasSummary = !!this.querySelector('[slot="summary"]') || this.#slotCache.has('summary');
+    const hasSummary = !!slottedChild(this, 'summary') || this._slotCache.has('summary');
 
-    const hasGoals = this.__goals?.length || this.querySelector('[slot="goals"]');
-    const hasPains = this.__painPoints?.length || this.querySelector('[slot="pain-points"]');
+    const hasGoals = this.__goals?.length || slottedChild(this, 'goals');
+    const hasPains = this.__painPoints?.length || slottedChild(this, 'pain-points');
 
     const html = `<style>${styles}</style>
       <article class="empathy-map${compact ? ' empathy-map--compact' : ''}">
@@ -281,21 +235,19 @@ class EmpathyMap extends HTMLElement {
        swaps. Skip on the first render — nothing to fade from. */
     const swap = () => {
       if (!this.shadowRoot) return;
+      // An open editor's unsaved text (and focus) survives the re-render.
+      const drafts = this.#captureDrafts();
       this.shadowRoot.innerHTML = html;
-      if (editable) this._bindEditListeners();
+      if (editable) {
+        this._bindEditListeners();
+        this.#restoreDrafts(drafts);
+      }
     };
     if (this.shadowRoot?.querySelector('article')) {
       viewTransitionSwap(this, swap, 'em-vt');
     } else {
       swap();
     }
-
-    /* Dispatch ready event */
-    this.dispatchEvent(new CustomEvent('empathy-map:ready', {
-      bubbles: true,
-      composed: true,
-      detail: { title: this.querySelector('[slot="title"]')?.textContent?.trim() || 'Empathy Map', persona },
-    }));
   }
 
   /* ── Render quadrant ───────────────────────────── */
@@ -305,20 +257,18 @@ class EmpathyMap extends HTMLElement {
     const items = this.__quadrants?.[key];
     const isEditing = this._editingQuadrants.has(key);
 
-    const frontContent = items && items.length
-      ? (key === 'feels'
-          ? items.map(item => this._renderEmotion(item)).join('')
-          : items.map(item => `<p>${esc(item)}</p>`).join(''))
+    const frontContent = (items && items.length) || this._editedQuadrants.has(key)
+      ? this._quadrantItemsHtml(key)
       : `<slot name="${key}"><p class="placeholder">Add ${meta.label.toLowerCase()} items\u2026</p></slot>`;
 
-    const textareaValue = items?.length ? items.join('\n') : '';
+    const textareaValue = this.#editorSeed(key);
 
     return `
       <section class="quadrant quadrant--${key}"${isEditing ? ' data-editing' : ''}>
         <div class="quadrant__inner">
           <div class="quadrant__header">
             <div class="quadrant__icon" aria-hidden="true">${lucideSvg(meta.icon)}</div>
-            <span class="quadrant__label">${meta.label}</span>
+            <h3 class="quadrant__label">${meta.label}</h3>
             ${editable ? `<button class="quadrant__edit-btn" data-quadrant="${key}"
               aria-label="Edit ${meta.label}" title="Edit ${meta.label}">${lucideSvg(UX_ICONS.pencil)}</button>` : ''}
           </div>
@@ -342,12 +292,25 @@ class EmpathyMap extends HTMLElement {
       </section>`;
   }
 
+  /**
+   * Front-face markup for a quadrant rendered from data (no slot).
+   * @param {string} key
+   */
+  _quadrantItemsHtml(key) {
+    const items = this.__quadrants?.[key] || [];
+    if (!items.length) {
+      return `<p class="placeholder">Add ${QUADRANT_META[key].label.toLowerCase()} items\u2026</p>`;
+    }
+    return key === 'feels'
+      ? items.map(item => this._renderEmotion(item)).join('')
+      : items.map(item => `<p>${esc(item)}</p>`).join('');
+  }
+
   /* ── Render emotion tag ────────────────────────── */
 
   _renderEmotion(item) {
-    const normalized = item.toLowerCase().trim();
-    const meta = EMOTION_META[normalized];
-    if (meta) {
+    if (isEmotion(item)) {
+      const meta = emotionMeta(item);
       return `<span class="emotion-tag" style="--ec:${meta.color}"><span role="img" aria-label="${esc(item)}">${meta.emoji}</span> ${esc(item)}</span>`;
     }
     return `<p>${esc(item)}</p>`;
@@ -407,10 +370,9 @@ class EmpathyMap extends HTMLElement {
   }
 
   _openEdit(key) {
-    this._editingQuadrants.add(key);
-
     const section = this.shadowRoot?.querySelector(`.quadrant--${key}`);
     if (!section) return;
+    this._editingQuadrants.add(key);
 
     section.setAttribute('data-editing', '');
 
@@ -421,34 +383,66 @@ class EmpathyMap extends HTMLElement {
 
     const textarea = /** @type {HTMLTextAreaElement | null} */ (section.querySelector('.quadrant__editor'));
     if (textarea) {
-      /* Pre-fill: prefer JSON data; fall back to slotted text */
-      const items = this.__quadrants?.[key];
-      if (items?.length) {
-        textarea.value = items.join('\n');
-      } else {
-        const slot = /** @type {HTMLSlotElement | null} */ (section.querySelector(`slot[name="${key}"]`));
-        if (slot) {
-          const assigned = slot.assignedElements();
-          if (assigned.length) {
-            /** @type {string[]} */
-            const lines = [];
-            assigned.forEach(el => {
-              const lis = el.querySelectorAll('li');
-              if (lis.length) {
-                lis.forEach(li => lines.push(li.textContent?.trim() ?? ''));
-              } else {
-                lines.push(el.textContent?.trim() ?? '');
-              }
-            });
-            textarea.value = lines.filter(Boolean).join('\n');
-          }
-        }
-      }
+      textarea.value = this.#editorSeed(key);
       textarea.focus();
     }
   }
 
+  /**
+   * Text an editor opens with: the saved items, else (for a quadrant never
+   * edited) its slotted light-DOM items, one per line.
+   * @param {string} key
+   * @returns {string}
+   */
+  #editorSeed(key) {
+    const items = this.__quadrants?.[key];
+    if (items?.length) return items.join('\n');
+    if (this._editedQuadrants.has(key)) return '';
+    /** @type {string[]} */
+    const lines = [];
+    for (const el of this.children) {
+      if (el.getAttribute('slot') !== key) continue;
+      const lis = el.querySelectorAll('li');
+      if (lis.length) lis.forEach(li => lines.push(li.textContent?.trim() ?? ''));
+      else lines.push(el.textContent?.trim() ?? '');
+    }
+    return lines.filter(Boolean).join('\n');
+  }
+
+  /**
+   * Snapshot open editors (value, selection, focus) before the shadow
+   * tree is replaced.
+   * @returns {Map<string, { value: string, start: number, end: number, focused: boolean }>}
+   */
+  #captureDrafts() {
+    const drafts = new Map();
+    const root = this.shadowRoot;
+    if (!root) return drafts;
+    for (const key of this._editingQuadrants) {
+      const ta = /** @type {HTMLTextAreaElement | null} */ (root.querySelector(`.quadrant__editor[data-quadrant="${key}"]`));
+      if (!ta) continue;
+      drafts.set(key, {
+        value: ta.value, start: ta.selectionStart, end: ta.selectionEnd, focused: root.activeElement === ta,
+      });
+    }
+    return drafts;
+  }
+
+  /** @param {Map<string, { value: string, start: number, end: number, focused: boolean }>} drafts */
+  #restoreDrafts(drafts) {
+    const root = this.shadowRoot;
+    if (!root) return;
+    for (const [key, d] of drafts) {
+      const ta = /** @type {HTMLTextAreaElement | null} */ (root.querySelector(`.quadrant__editor[data-quadrant="${key}"]`));
+      if (!ta) continue;
+      ta.value = d.value;
+      ta.setSelectionRange(d.start, d.end);
+      if (d.focused) ta.focus();
+    }
+  }
+
   _closeEdit(key) {
+    if (!this._editingQuadrants.has(key)) return;
     const section = this.shadowRoot?.querySelector(`.quadrant--${key}`);
     if (!section) return;
 
@@ -462,19 +456,12 @@ class EmpathyMap extends HTMLElement {
       /* Ensure __quadrants object exists */
       if (!this.__quadrants) this.__quadrants = {};
       this.__quadrants[key] = items;
+      /* From now on this quadrant renders from data, even when emptied,
+         so later full renders don't resurrect the original slotted items. */
+      this._editedQuadrants.add(key);
 
-      /* Partially re-render front face content */
       const contentEl = section.querySelector('.quadrant__content');
-      if (contentEl) {
-        if (items.length) {
-          contentEl.innerHTML = key === 'feels'
-            ? items.map(item => this._renderEmotion(item)).join('')
-            : items.map(item => `<p>${esc(item)}</p>`).join('');
-        } else {
-          const meta = QUADRANT_META[key];
-          contentEl.innerHTML = `<p class="placeholder">Add ${meta.label.toLowerCase()} items\u2026</p>`;
-        }
-      }
+      if (contentEl) contentEl.innerHTML = this._quadrantItemsHtml(key);
     }
 
     this._editingQuadrants.delete(key);
@@ -482,6 +469,12 @@ class EmpathyMap extends HTMLElement {
 
     const front = section.querySelector('.quadrant__face--front');
     const back  = section.querySelector('.quadrant__face--back');
+    /* Move focus out of the face that is about to become inert, back to
+       the quadrant's edit button, so it doesn't fall to <body>. */
+    const active = this.shadowRoot?.activeElement;
+    if (back && active && back.contains(active)) {
+      /** @type {HTMLElement | null} */ (section.querySelector('.quadrant__edit-btn'))?.focus();
+    }
     if (front) front.removeAttribute('inert');
     if (back)  back.setAttribute('inert', '');
 

package/src/web-components/empathy-map/static.html

@@ -3,10 +3,10 @@
   Slotted content renders as normal children before upgrade.
 -->
 <empathy-map
-  title="Developer Onboarding"
   persona="Sarah Chen"
-  persona-id="persona-sarah-chen"
-  summary="Based on user interview round 2">
+  persona-id="persona-sarah-chen">
+  <h2 slot="title">Developer Onboarding</h2>
+  <p slot="summary">Based on user interview round 2</p>
   <ul slot="says">
     <li>"I just want it to work"</li>
     <li>"The documentation is confusing"</li>

package/src/web-components/empathy-map/styles.js

@@ -234,6 +234,7 @@ const styles = `
   .quadrant--feels  .quadrant__icon { background: var(--_feels-bg);  color: var(--_feels); }
 
   .quadrant__label {
+    margin: 0;
     font-size: 13px;
     font-weight: 700;
     text-transform: uppercase;

package/src/web-components/gantt-chart/README.md

@@ -58,26 +58,32 @@ Part of the **UX Planning Pack**.
 | `data-assignee` | string | Assignee name |
 | `data-milestone` | boolean | Render as diamond marker |
 | `data-color` | string | Custom bar color |
+| `data-story-ids` | string | Comma-separated linked user-story IDs |
+| `data-item-ids` | string | Comma-separated linked work-item IDs |
+
+Dates are `YYYY-MM-DD` calendar days in local time. Progress in `.tasks` / JSON: > 1 is a percentage, 0–1 a fraction; `<progress>` is `value / max`.
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `gantt-chart:ready` | `{ taskCount, dateRange }` | After render |
-| `gantt-chart:task-click` | `{ task }` | Bar clicked |
+| `gantt-chart:upgraded` | — | Once per connect (also for an empty chart) |
+| `gantt-chart:ready` | `{ taskCount, dateRange: { start, end } }` | After a render with tasks on connect, and after a `src` load (YYYY-MM-DD) |
+| `gantt-chart:task-click` | `{ task }` | Bar/milestone clicked or activated with Enter/Space |
+| `gantt-chart:tasks-changed` | `{ tasks, source: 'property' \| 'src' }` | After `.tasks` assignment or a `src` load |
 
 ## Failure Modes
 
 - **No JavaScript:** Table renders normally with progress bars and time elements.
 - **No CSS:** Table renders as default HTML table.
-- **Keyboard Only:** Tab navigates bars; Enter triggers click event.
+- **Keyboard Only:** Tab navigates bars; Enter or Space fires `task-click`.
 - **Screen Reader:** Original table is preserved (visually hidden) for full table semantics.
 
 ## Accessibility
 
-- Original table stays in DOM (sr-only) for screen reader access
-- Bars have `role="img"` with descriptive `aria-label`
-- Bars are focusable with `tabindex="0"`
+- Original table stays in DOM (sr-only) for screen reader access; for `.tasks`/`src` data a table is generated from the tasks
+- Bars and milestones are focusable `role="button"` with an `aria-label` giving name, dates, status, progress and assignee
+- Status is shown as text in the task list, not by colour alone
 - `aria-live="polite"` region announces task selection
 - `prefers-reduced-motion: reduce` disables transitions
 - Print shows the original table, hides the visual chart

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

@@ -5,16 +5,32 @@
   "description": "HTML-first Gantt chart using native table, progress, and time elements with progressive enhancement to an interactive timeline",
   "htmlvalidate": { "flow": true, "permittedContent": ["@flow"] },
   "attributes": [
-    { "name": "title",             "kind": "host-api", "purpose": "config", "type": "string",  "description": "Chart heading" },
-    { "name": "src",               "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL to JSON task data" },
-    { "name": "view",              "kind": "host-api", "purpose": "config", "type": "string",  "description": "Timeline granularity: auto | day | week | month | quarter" },
+    { "name": "title",             "kind": "host-api", "purpose": "config", "type": "string",  "description": "Chart heading (a src JSON \"title\" sets it)" },
+    { "name": "src",               "kind": "host-api", "purpose": "config", "type": "string",  "description": "URL of JSON task data ({ title?, tasks: [...] }). Fetched once on connect or when the attribute changes; the fetched tasks replace the child table. A newer value aborts an older in-flight request. Skipped on connect when .tasks was already assigned, and an in-flight request is aborted when .tasks is assigned (.tasks takes precedence)" },
+    { "name": "view",              "kind": "host-api", "purpose": "config", "type": "enum", "values": ["auto", "day", "week", "month", "quarter"], "default": "\"auto\"", "description": "Timeline granularity. auto picks day (≤ 3 weeks), week (≤ 90 days), month (≤ 1 year) or quarter" },
     { "name": "show-today",        "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Show vertical today marker line" },
     { "name": "show-progress",     "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Show progress fill inside bars" },
-    { "name": "show-dependencies", "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Draw dependency arrows between tasks" },
-    { "name": "compact",           "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Reduced spacing variant" }
+    { "name": "show-dependencies", "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Draw dependency arrows between tasks (row positions are measured, so compact and grouped charts line up)" },
+    { "name": "compact",           "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Reduced row height and spacing" }
+  ],
+  "structure": [
+    { "element": "<table>", "required": false, "description": "Task source: one <tbody> <tr> per task; first cell is the name, two <time datetime=\"YYYY-MM-DD\"> give start and end, an optional <progress> gives progress. Kept in the DOM, visually hidden, for screen readers and print" }
+  ],
+  "childAttributes": [
+    { "name": "data-task-id",   "on": "tr", "type": "string",  "description": "Unique task identifier (used by data-depends)" },
+    { "name": "data-group",     "on": "tr", "type": "string",  "description": "Swim lane group; with two or more groups each gets a header row" },
+    { "name": "data-depends",   "on": "tr", "type": "string",  "description": "Comma-separated task IDs this task depends on (drawn with show-dependencies)" },
+    { "name": "data-status",    "on": "tr", "type": "enum", "values": ["not-started", "in-progress", "done", "blocked"], "description": "Task status: shown as text in the task list and in the bar's accessible name; also tints the bar" },
+    { "name": "data-assignee",  "on": "tr", "type": "string",  "description": "Assignee name (included in the bar's accessible name)" },
+    { "name": "data-milestone", "on": "tr", "type": "boolean", "description": "Render a diamond marker at the start date instead of a duration bar" },
+    { "name": "data-color",     "on": "tr", "type": "string",  "description": "Custom bar colour (any CSS colour)" },
+    { "name": "data-story-ids", "on": "tr", "type": "string",  "description": "Comma-separated linked user-story IDs (exposed as task.storyIds)" },
+    { "name": "data-item-ids",  "on": "tr", "type": "string",  "description": "Comma-separated linked work-item IDs (exposed as task.itemIds)" }
   ],
   "events": [
-    { "name": "gantt-chart:ready",      "detail": "{ taskCount, dateRange }",  "description": "Fired after initial render" },
-    { "name": "gantt-chart:task-click",  "detail": "{ task }",                  "description": "Fired when a task bar is clicked" }
+    { "name": "gantt-chart:upgraded",      "detail": "", "description": "Once per connect, in a microtask after setup; a safe signal for the first .tasks assignment (fires for an empty chart too)" },
+    { "name": "gantt-chart:ready",         "detail": "{ taskCount, dateRange: { start, end } }", "description": "Once per element: after the first connect render that has tasks (table or .tasks), or else after the first src load. Not re-fired on reconnect or by later src loads (those fire tasks-changed with source 'src'). dateRange values are YYYY-MM-DD" },
+    { "name": "gantt-chart:task-click",    "detail": "{ task }", "description": "When a bar or milestone is clicked or activated with Enter/Space" },
+    { "name": "gantt-chart:tasks-changed", "detail": "{ tasks, source: 'property' | 'src' }", "description": "After .tasks is assigned (source 'property') or src data loads (source 'src'), with the normalized tasks" }
   ]
 }