@profpowell/vb-project-planning 0.2.1 → 0.2.3

package/src/web-components/work-item/api.json

@@ -5,26 +5,28 @@
   "description": "General-purpose work unit card — tasks, bugs, chores, spikes, and features with slotted title, status, priority, assignee, and linked stories",
   "htmlvalidate": { "flow": true, "permittedContent": ["@flow"] },
   "attributes": [
-    { "name": "item-id",   "kind": "host-api", "purpose": "config", "type": "string",  "description": "Unique work item identifier, auto-sets HTML id" },
-    { "name": "type",      "kind": "host-api", "purpose": "config", "type": "string",  "description": "Item type: task | bug | chore | spike | feature" },
-    { "name": "priority",  "kind": "host-api", "purpose": "config", "type": "string",  "description": "Priority: critical | high | medium | low" },
-    { "name": "status",    "kind": "host-api", "purpose": "config", "type": "string",  "description": "Status: backlog | to-do | in-progress | review | done | blocked" },
+    { "name": "item-id",   "kind": "host-api", "purpose": "config", "type": "string",  "description": "Unique work item identifier; sets the HTML id on first connect when none is set" },
+    { "name": "type",      "kind": "host-api", "purpose": "config", "type": "enum", "values": ["task", "bug", "chore", "spike", "feature"], "default": "task", "description": "Item type" },
+    { "name": "priority",  "kind": "host-api", "purpose": "config", "type": "enum", "values": ["critical", "high", "medium", "low"], "default": "medium", "description": "Priority" },
+    { "name": "status",    "kind": "host-api", "purpose": "config", "type": "enum", "values": ["backlog", "to-do", "in-progress", "review", "done", "blocked"], "default": "backlog", "description": "Workflow status" },
     { "name": "estimate",  "kind": "host-api", "purpose": "config", "type": "string",  "description": "Effort estimate (points, hours, t-shirt size)" },
-    { "name": "assignee",  "kind": "host-api", "purpose": "config", "type": "string",  "description": "Assignee name" },
+    { "name": "assignee",  "kind": "host-api", "purpose": "config", "type": "string",  "description": "Assignee name (shown with initials avatar)" },
     { "name": "story-ids", "kind": "host-api", "purpose": "config", "type": "string",  "description": "Comma-separated linked user-story IDs" },
-    { "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, type 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 work-item record. Fetched once per value; a newer value aborts the older request." }
   ],
   "slots": [
-    { "name": "title",       "description": "Work item heading (e.g., <h3>)" },
+    { "name": "title",       "description": "Work item heading (e.g., <h3>). There is no title attribute." },
     { "name": "description", "description": "Work item description (e.g., <p>)" },
     { "name": "checklist",   "description": "Checklist or subtasks (e.g., <ul>)" },
     { "name": "notes",       "description": "Additional notes (e.g., <p>)" }
   ],
   "events": [
-    { "name": "work-item:ready",    "detail": "{ itemId, title, type, priority, status }", "description": "Fired after render" },
-    { "name": "work-item:status",   "detail": "{ status, itemId }",                        "description": "Fired when status changes" },
-    { "name": "work-item:priority", "detail": "{ priority, itemId }",                      "description": "Fired when priority changes" }
+    { "name": "work-item:ready",    "detail": "{ itemId, title, type, priority, 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": "work-item:status",   "detail": "{ status, itemId }",                        "description": "When updateStatus() is called with a known status" },
+    { "name": "work-item:priority", "detail": "{ priority, itemId }",                      "description": "When updatePriority() is called with a known priority" },
+    { "name": "work-item:upgraded", "detail": "", "description": "Once, in a microtask after first connect. Wait for this before assigning .data from a framework." },
+    { "name": "work-item:data-changed", "detail": "{ data, source: 'property' }", "description": "After .data is assigned" }
   ]
 }

package/src/web-components/work-item/logic.js

@@ -22,22 +22,24 @@
  * @attr {string}  story-ids - Comma-separated linked story IDs
  * @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 work-item:ready    - After render
- * @fires work-item:status   - When updateStatus() is called
- * @fires work-item:priority - When updatePriority() is called
+ * @fires work-item:ready        - Once, after the first render (after the src data renders when src is set)
+ * @fires work-item:status       - When updateStatus() is called
+ * @fires work-item:priority     - When updatePriority() is called
+ * @fires work-item:upgraded     - Once, after first connect
+ * @fires work-item:data-changed - After .data assignment, detail: { data, source: 'property' }
  *
  * @example
  * <work-item
  *   item-id="PROJ-42"
- *   title="Implement search API"
  *   type="task"
  *   status="in-progress"
  *   priority="high"
  *   assignee="Sarah Chen"
  *   estimate="5"
  *   story-ids="PROJ-101,PROJ-102">
+ *   <h3 slot="title">Implement search API</h3>
  *   <p slot="description">Build the /search endpoint with filters.</p>
  *   <ul slot="checklist">
  *     <li>Schema design</li>
@@ -49,7 +51,10 @@
 
 import { styles } from './styles.js';
 import { registerComponent } from '../../lib/bundle-registry.js';
-import { esc, initials, hashColor, lucideSvg, UX_ICONS } from '../_ux-base.js';
+import {
+  esc, initials, hashColor, lucideSvg, UXShadowElement,
+  PRIORITIES, STATUSES as BASE_STATUSES, lookup, fillSlot, splitList, detailLevel, markEmptySections,
+} from '../_ux-base.js';
 
 /* ── Type icons (Lucide SVG fragments) ─────────────── */
 
@@ -63,25 +68,16 @@ const TYPE_ICONS = {
 
 /* ── Static lookups ────────────────────────────────── */
 
-const PRIORITIES = {
-  critical: { label: 'Critical', color: '#dc2626', bg: 'rgba(220, 38, 38, 0.1)' },
-  high:     { label: 'High',     color: '#ea580c', bg: 'rgba(234, 88, 12, 0.1)' },
-  medium:   { label: 'Medium',   color: '#ca8a04', bg: 'rgba(202, 138, 4, 0.1)' },
-  low:      { label: 'Low',      color: '#16a34a', bg: 'rgba(22, 163, 74, 0.1)' },
-};
-
-const STATUSES = {
-  backlog:       { label: 'Backlog',     color: '#6b7280', bg: 'rgba(107, 114, 128, 0.1)' },
-  'to-do':       { label: 'To Do',       color: '#3b82f6', bg: 'rgba(59, 130, 246, 0.1)' },
-  'in-progress': { label: 'In Progress', color: '#8b5cf6', bg: 'rgba(139, 92, 246, 0.1)' },
-  review:        { label: 'Review',      color: '#f59e0b', bg: 'rgba(245, 158, 11, 0.1)' },
-  done:          { label: 'Done',        color: '#22c55e', bg: 'rgba(34, 197, 94, 0.1)' },
-  blocked:       { label: 'Blocked',     color: '#dc2626', bg: 'rgba(220, 38, 38, 0.1)' },
-};
+const STATUSES = Object.freeze({
+  ...BASE_STATUSES,
+  blocked: { label: 'Blocked', color: '#dc2626', bg: 'rgba(220, 38, 38, 0.1)' },
+});
 
 /* ── Component ─────────────────────────────────────── */
 
-class WorkItem extends HTMLElement {
+class WorkItem extends UXShadowElement {
+  static readyEvent = 'work-item:ready';
+
   static get observedAttributes() {
     return [
       'item-id', 'type', 'priority', 'status',
@@ -89,77 +85,35 @@ class WorkItem 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());
-      }
-    }
-  }
-
-  _resolve(attr) {
-    return this.getAttribute(attr) || this.#slotCache.get(attr) || '';
-  }
+  /* ── Lifecycle (see UXShadowElement) ──────────── */
 
-  /* ── Lifecycle ─────────────────────────────────── */
-
-  connectedCallback() {
-    this.#cacheSlotValues();
+  _setup() {
     if (this.itemId && !this.id) this.id = this.itemId;
-    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 {
+      itemId: this.itemId,
+      title: this.itemTitle,
+      type: this.itemType,
+      priority: this.priority,
+      status: this.status,
+    };
   }
 
   /* ── Getters ───────────────────────────────────── */
 
   get itemId()    { return this.getAttribute('item-id') || ''; }
-  get itemTitle() {
-    const slotted = this.querySelector('[slot="title"]');
-    return slotted?.textContent?.trim() || this.#slotCache.get('title') || '';
-  }
+  get itemTitle() { return this._slotText('title'); }
   get itemType()  { return this.getAttribute('type') || 'task'; }
   get priority()  { return this.getAttribute('priority') || 'medium'; }
   get status()    { return this.getAttribute('status') || 'backlog'; }
   get estimate()  { return this.getAttribute('estimate') || ''; }
   get assignee()  { return this.getAttribute('assignee') || ''; }
 
-  get storyIds() {
-    const raw = this.getAttribute('story-ids') || '';
-    return raw ? raw.split(',').map(s => s.trim()).filter(Boolean) : [];
-  }
+  get storyIds() { return splitList(this.getAttribute('story-ids')); }
 
-  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.itemTitle || this.itemId || 'Work item';
@@ -168,7 +122,7 @@ class WorkItem extends HTMLElement {
   /* ── Public API ────────────────────────────────── */
 
   updateStatus(newStatus) {
-    if (STATUSES[newStatus]) {
+    if (Object.hasOwn(STATUSES, newStatus)) {
       this.setAttribute('status', newStatus);
       this.dispatchEvent(new CustomEvent('work-item:status', {
         detail: { status: newStatus, itemId: this.itemId },
@@ -178,7 +132,7 @@ class WorkItem extends HTMLElement {
   }
 
   updatePriority(newPriority) {
-    if (PRIORITIES[newPriority]) {
+    if (Object.hasOwn(PRIORITIES, newPriority)) {
       this.setAttribute('priority', newPriority);
       this.dispatchEvent(new CustomEvent('work-item:priority', {
         detail: { priority: newPriority, itemId: this.itemId },
@@ -213,18 +167,13 @@ class WorkItem extends HTMLElement {
    * Idempotent for repeat calls.
    */
   set data(value) {
-    if (!value || typeof value !== 'object') return;
-    this._applyData(value);
-    if (this.shadowRoot) this.#render();
-    this.dispatchEvent(new CustomEvent('work-item: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. No render or event emit — caller decides.
+   * .data setter and the src loader. Slotted children are created only when
+   * absent (authored content wins). No render or event emit — caller decides.
    * @param {Record<string, unknown>} data
    */
   _applyData(data) {
@@ -239,66 +188,39 @@ class WorkItem extends HTMLElement {
       this.setAttribute('story-ids', Array.isArray(data.storyIds) ? data.storyIds.join(',') : String(data.storyIds));
     }
 
-    if (data.title && !this.querySelector('[slot="title"]')) {
-      const el = document.createElement('h3');
-      el.slot = 'title';
-      el.textContent = String(data.title);
-      this.appendChild(el);
-    }
-    for (const key of ['description', 'notes']) {
-      if (data[key] && !this.querySelector(`[slot="${key}"]`)) {
-        const el = document.createElement('p');
-        el.slot = key;
-        el.textContent = String(data[key]);
-        this.appendChild(el);
-      }
-    }
-    if (data.checklist && !this.querySelector('[slot="checklist"]')) {
-      const ul = document.createElement('ul');
-      ul.slot = 'checklist';
-      const items = Array.isArray(data.checklist) ? data.checklist : [data.checklist];
-      for (const item of items) {
-        const li = document.createElement('li');
-        li.textContent = String(item);
-        ul.appendChild(li);
-      }
-      this.appendChild(ul);
-    }
+    fillSlot(this, 'title', data.title, { tag: 'h3' });
+    fillSlot(this, 'description', data.description);
+    fillSlot(this, 'notes', data.notes);
+    fillSlot(this, 'checklist', data.checklist, { 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.#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 priorityInfo = PRIORITIES[this.priority] || PRIORITIES.medium;
-    const statusInfo = STATUSES[this.status] || STATUSES.backlog;
+    const priorityInfo = lookup(PRIORITIES, this.priority, 'medium');
+    const statusInfo = lookup(STATUSES, this.status, 'backlog');
     const type = this.itemType;
-    const typeIcon = TYPE_ICONS[type] || TYPE_ICONS.task;
+    const typeIcon = lookup(TYPE_ICONS, type, 'task');
     const level = this._detailLevel;
     const ariaLabel = this.itemId ? `Work item: ${esc(this.itemId)}` : 'Work item';
 
     if (level === 'minimal') {
       root.innerHTML = `<style>${styles}</style>
-        <article class="wi-card wi-card--minimal" role="article" aria-label="${ariaLabel}"
-          tabindex="0">
+        <article class="wi-card wi-card--minimal" role="article" aria-label="${ariaLabel}">
           <div class="wi-body">
             <div class="wi-meta">
               ${this.itemId ? `<span class="wi-id">${esc(this.itemId)}</span>` : ''}
@@ -312,6 +234,7 @@ class WorkItem extends HTMLElement {
       return;
     }
 
+
     root.innerHTML = `<style>${styles}</style>
       <article class="wi-card wi-card--${level}" role="article" aria-label="${ariaLabel}">
 
@@ -334,7 +257,7 @@ class WorkItem extends HTMLElement {
 
           ${this.assignee ? `
             <div class="wi-assignee">
-              <span class="wi-assignee__avatar" style="background:${hashColor(this.assignee)}">${initials(this.assignee)}</span>
+              <span class="wi-assignee__avatar" style="background:${hashColor(this.assignee)}">${esc(initials(this.assignee))}</span>
               ${esc(this.assignee)}
             </div>` : ''}
 
@@ -386,26 +309,7 @@ class WorkItem extends HTMLElement {
 
       </article>`;
 
-    // Compact: mark empty slot sections
-    if (level === 'compact') {
-      for (const section of root.querySelectorAll('.wi-section')) {
-        const slot = section.querySelector('slot');
-        if (slot && slot.assignedNodes().length === 0) {
-          section.setAttribute('data-empty', '');
-        }
-      }
-    }
-
-    this.dispatchEvent(new CustomEvent('work-item:ready', {
-      detail: {
-        itemId: this.itemId,
-        title: this.itemTitle,
-        type,
-        priority: this.priority,
-        status: this.status,
-      },
-      bubbles: true, composed: true,
-    }));
+    if (level === 'compact') markEmptySections(root, '.wi-section');
   }
 }