@profpowell/vb-project-planning 0.1.0

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

@@ -0,0 +1,445 @@
+/**
+ * story-map: Horizontal user story map with activity columns
+ *
+ * Light DOM component that creates a horizontal story map with activity
+ * columns, each containing a <drag-surface> for cross-column drag-and-drop.
+ *
+ * @attr {string} src - URL to JSON data
+ * @attr {string} title - Optional heading displayed above the map
+ * @attr {boolean} compact - Reduced spacing variant
+ *
+ * Children use:
+ * @attr {string} data-activity - Activity column identifier (on <section>)
+ * @attr {string} data-activity-label - Display label for the column header (on <section>)
+ * @attr {string} data-journey-phase - Optional link to a user-journey phase (on <section>)
+ *
+ * @fires story-map:reorder - Item reordered within a column
+ * @fires story-map:transfer - Item moved between columns
+ * @fires story-map:ready - Fired after component initializes
+ *
+ * @example
+ * <story-map>
+ *   <section data-activity="discovery" data-activity-label="Discovery">
+ *     <article draggable="true" data-id="PROJ-1">Interview users</article>
+ *   </section>
+ * </story-map>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+import { viewTransitionSwap } from '../../lib/vb-view-transition.js';
+
+class StoryMap extends VBElement {
+  static get observedAttributes() { return ['src', 'compact', 'title']; }
+
+  static #instanceCount = 0;
+
+  /** @type {HTMLDivElement | null} */
+  #scroll = null;
+  /** @type {HTMLDivElement | null} */
+  #columnsEl = null;
+  /** @type {Record<string, HTMLElement>} */
+  #surfaces = {};
+  /** @type {HTMLDivElement | null} */
+  #liveRegion = null;
+  /** @type {string} */
+  #groupId = '';
+  /** @type {Array<{ id: string, label: string, journeyPhase: string | null, children: HTMLElement[] }>} */
+  #activities = [];
+
+  setup() {
+    this.#groupId = `sm-${++StoryMap.#instanceCount}`;
+
+    // 1. Snapshot <section data-activity> children
+    const sections = /** @type {HTMLElement[]} */ ([
+      ...this.querySelectorAll(':scope > section[data-activity]')
+    ]);
+
+    this.#activities = sections.map(section => {
+      const id = section.getAttribute('data-activity') || '';
+      const rawLabel = section.getAttribute('data-activity-label') || '';
+      const label = rawLabel || this.#titleCase(id);
+      const journeyPhase = section.getAttribute('data-journey-phase') || null;
+      const children = /** @type {HTMLElement[]} */ ([...section.children]);
+      return { id, label, journeyPhase, children };
+    });
+
+    // 2. Remove original sections (children already captured)
+    for (const section of sections) {
+      section.remove();
+    }
+
+    // 3. Build scroll container
+    this.#scroll = document.createElement('div');
+    this.#scroll.className = 'sm-scroll';
+    this.#scroll.setAttribute('role', 'region');
+    this.#scroll.setAttribute('aria-label', 'Story map');
+    this.#scroll.setAttribute('tabindex', '0');
+
+    // 4. Build columns container
+    this.#columnsEl = document.createElement('div');
+    this.#columnsEl.className = 'sm-columns';
+
+    // 5. Build each activity column
+    let totalStories = 0;
+
+    for (const activity of this.#activities) {
+      const column = document.createElement('section');
+      column.className = 'sm-column';
+      column.setAttribute('data-activity-column', activity.id);
+
+      // Header with count badge
+      const header = document.createElement('header');
+      header.className = 'sm-activity-header';
+      const h3 = document.createElement('h3');
+      h3.textContent = activity.label;
+      const countBadge = document.createElement('span');
+      countBadge.className = 'sm-activity-count';
+      countBadge.textContent = String(activity.children.length);
+      h3.appendChild(countBadge);
+      header.appendChild(h3);
+      column.appendChild(header);
+
+      // Drag surface
+      const surface = document.createElement('drag-surface');
+      surface.setAttribute('group', this.#groupId);
+      surface.setAttribute('aria-label', `${activity.label} stories`);
+      surface.setAttribute('data-layout', 'stack');
+      surface.setAttribute('data-layout-gap', 'xs');
+
+      // Move captured children into the drag-surface
+      if (activity.children.length > 0) {
+        for (const child of activity.children) {
+          surface.appendChild(child);
+        }
+        totalStories += activity.children.length;
+      } else {
+        const placeholder = document.createElement('p');
+        placeholder.className = 'sm-empty';
+        placeholder.textContent = 'No stories yet';
+        surface.appendChild(placeholder);
+      }
+
+      column.appendChild(surface);
+      this.#columnsEl.appendChild(column);
+      this.#surfaces[activity.id] = surface;
+    }
+
+    // 6. Assemble: title + scroll > columns, append to this
+    const title = this.getAttribute('title');
+    if (title) {
+      const heading = document.createElement('h2');
+      heading.className = 'sm-title';
+      heading.textContent = title;
+      this.appendChild(heading);
+    }
+
+    this.#scroll.appendChild(this.#columnsEl);
+    this.appendChild(this.#scroll);
+
+    // 7. Create live region
+    this.#liveRegion = document.createElement('div');
+    this.#liveRegion.className = 'sm-live-region';
+    this.#liveRegion.setAttribute('role', 'status');
+    this.#liveRegion.setAttribute('aria-live', 'polite');
+    this.#liveRegion.setAttribute('aria-atomic', 'true');
+    this.appendChild(this.#liveRegion);
+
+    // 8. Listen for drag-surface:reorder
+    this.listen(this, 'drag-surface:reorder', (e) => {
+      const detail = /** @type {CustomEvent} */ (e).detail;
+      const surface = /** @type {HTMLElement | null} */ (/** @type {HTMLElement} */ (e.target).closest('drag-surface'));
+      const activityId = this.#findActivityForSurface(surface);
+      if (!activityId) return;
+
+      this.#updateCount(activityId);
+
+      this.dispatchEvent(new CustomEvent('story-map:reorder', {
+        bubbles: true,
+        detail: {
+          itemId: detail.itemId,
+          activity: activityId,
+          oldIndex: detail.oldIndex,
+          newIndex: detail.newIndex,
+        },
+      }));
+    });
+
+    // 9. Listen for drag-surface:transfer
+    this.listen(this, 'drag-surface:transfer', (e) => {
+      const detail = /** @type {CustomEvent} */ (e).detail;
+      const fromSurface = detail.fromSurface;
+      const toSurface = detail.toSurface;
+      const fromActivity = this.#findActivityForSurface(fromSurface);
+      const toActivity = this.#findActivityForSurface(toSurface);
+      if (!fromActivity || !toActivity) return;
+
+      // Update count badges
+      this.#updateCount(fromActivity);
+      this.#updateCount(toActivity);
+
+      // Remove placeholder from receiving column if it had one
+      const toPlaceholder = toSurface.querySelector('.sm-empty');
+      if (toPlaceholder) toPlaceholder.remove();
+
+      // Add placeholder to sending column if now empty
+      const fromDraggables = fromSurface.querySelectorAll(':scope > [draggable="true"]');
+      if (fromDraggables.length === 0 && !fromSurface.querySelector('.sm-empty')) {
+        const placeholder = document.createElement('p');
+        placeholder.className = 'sm-empty';
+        placeholder.textContent = 'No stories yet';
+        fromSurface.appendChild(placeholder);
+      }
+
+      // Announce via live region
+      const itemLabel = this.#itemLabel(detail.item);
+      this.#announce(`${itemLabel} moved from ${fromActivity} to ${toActivity}`);
+
+      this.dispatchEvent(new CustomEvent('story-map:transfer', {
+        bubbles: true,
+        detail: {
+          itemId: detail.itemId,
+          fromActivity,
+          toActivity,
+          newIndex: detail.newIndex,
+        },
+      }));
+    });
+
+    // 10. Handle src attribute for data mode
+    const src = this.getAttribute('src');
+    if (src) {
+      this._loadSrc(src);
+      return; // ready event fires after src loads
+    }
+
+    // 11. Dispatch ready event
+    this.dispatchEvent(new CustomEvent('story-map:ready', {
+      bubbles: true,
+      detail: {
+        activityCount: this.#activities.length,
+        storyCount: totalStories,
+      },
+    }));
+  }
+
+  teardown() {
+    if (this.#scroll) {
+      this.#scroll.remove();
+      this.#scroll = null;
+    }
+    if (this.#liveRegion) {
+      this.#liveRegion.remove();
+      this.#liveRegion = null;
+    }
+    this.#columnsEl = null;
+    this.#surfaces = {};
+    this.#activities = [];
+  }
+
+  // ── Data API (HTML-first / JS-first dual contract) ──────────────
+
+  /**
+   * Read the current activities + stories as a nested data array.
+   * Each activity: `{ id, label, journeyPhase?, stories: [...] }`.
+   * Each story: `{ id?, title?, ... }` (passed through to renderItem).
+   */
+  get activities() {
+    return this.#activities.map(a => ({
+      id: a.id,
+      label: a.label,
+      journeyPhase: a.journeyPhase || undefined,
+      stories: [...(this.#surfaces[a.id]?.querySelectorAll(':scope > [draggable="true"]') || [])]
+        .map(el => ({
+          id: el.getAttribute('data-id') || undefined,
+          storyId: el.getAttribute('story-id') || undefined,
+          title: el.querySelector('[slot="title"]')?.textContent?.trim() || undefined,
+        })),
+    }));
+  }
+
+  /**
+   * Replace the entire story map. Accepts a nested tree:
+   *   [{ id, label, journeyPhase?, stories: [{ id, ... }] }]
+   * Stories are rendered as <user-story> elements (via .data) by default;
+   * override via `.renderStory`.
+   *
+   * v1 is record-shaped — full rebuild on assignment. Per-story
+   * preservation across diffs is on the roadmap.
+   *
+   * Emits story-map:activities-changed { activities, source: 'property' }.
+   */
+  set activities(value) {
+    const next = Array.isArray(value) ? value : [];
+
+    // Clear children, then synthesize the <section data-activity> markup
+    // that setup() expects. Re-run setup().
+    while (this.firstChild) this.firstChild.remove();
+    for (const a of next) {
+      const section = document.createElement('section');
+      section.setAttribute('data-activity', a.id || '');
+      if (a.label) section.setAttribute('data-activity-label', a.label);
+      if (a.journeyPhase) section.setAttribute('data-journey-phase', a.journeyPhase);
+      for (const story of (a.stories || [])) {
+        let el;
+        const self = /** @type {any} */ (this);
+        if (typeof self.renderStory === 'function') {
+          const out = self.renderStory(story);
+          el = out instanceof Element ? out : null;
+        }
+        if (!el) {
+          if (customElements.get('user-story')) {
+            el = document.createElement('user-story');
+            /** @type {any} */ (el).data = story;
+          } else {
+            el = document.createElement('article');
+            el.className = 'sm-card';
+            el.textContent = story.title || story.id || '';
+          }
+        }
+        if (!el.hasAttribute('draggable')) el.setAttribute('draggable', 'true');
+        if (story.id && !el.hasAttribute('data-id')) el.setAttribute('data-id', String(story.id));
+        section.appendChild(el);
+      }
+      this.appendChild(section);
+    }
+
+    const swap = () => {
+      this.teardown();
+      this.removeAttribute('data-upgraded');
+      this.setup();
+    };
+    if (this.hasAttribute('data-upgraded') && this.#scroll) {
+      viewTransitionSwap(this, swap, 'sm-vt');
+    } else {
+      swap();
+    }
+
+    this.dispatchEvent(new CustomEvent('story-map:activities-changed', {
+      detail: { activities: next, source: 'property' },
+      bubbles: true,
+    }));
+  }
+
+  // ── Attribute changes ────────────────────────────────
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue || !this.isConnected) return;
+    if (name === 'src') this._loadSrc(newValue);
+  }
+
+  // ── JSON loading ────────────────────────────────────
+
+  async _loadSrc(url) {
+    if (!url) return;
+    try {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      // Clear existing children
+      while (this.firstChild) this.firstChild.remove();
+      // Create sections from activities
+      for (const activity of (data.activities || [])) {
+        const section = document.createElement('section');
+        section.setAttribute('data-activity', activity.id);
+        section.setAttribute('data-activity-label', activity.label || activity.id);
+        if (activity.journeyPhase) section.setAttribute('data-journey-phase', activity.journeyPhase);
+        for (const story of (activity.stories || [])) {
+          const el = document.createElement('user-story');
+          el.setAttribute('draggable', 'true');
+          el.dataset.id = story.id || story.storyId;
+          if (story.storyId || story.id) el.setAttribute('story-id', story.storyId || story.id);
+          if (story.title) el.setAttribute('title', story.title);
+          if (story.persona) el.setAttribute('persona', story.persona);
+          if (story.action) el.setAttribute('action', story.action);
+          if (story.benefit) el.setAttribute('benefit', story.benefit);
+          if (story.priority) el.setAttribute('priority', story.priority);
+          if (story.status) el.setAttribute('status', story.status);
+          if (story.points) el.setAttribute('points', String(story.points));
+          el.setAttribute('detail', story.detail || 'compact');
+          section.appendChild(el);
+        }
+        this.appendChild(section);
+      }
+      const swap = () => {
+        this.teardown();
+        this.removeAttribute('data-upgraded');
+        this.setup();
+      };
+      if (this.hasAttribute('data-upgraded') && this.#scroll) {
+        viewTransitionSwap(this, swap, 'sm-vt');
+      } else {
+        swap();
+      }
+    } catch (err) {
+      console.warn(`[story-map] Failed to load src="${url}":`, err);
+    }
+  }
+
+  // ── Helpers ──────────────────────────────────────────
+
+  /**
+   * Reverse-lookup: find the activity id that owns a given drag-surface.
+   * @param {HTMLElement | null} surface
+   * @returns {string | null}
+   */
+  #findActivityForSurface(surface) {
+    if (!surface) return null;
+    for (const [id, ref] of Object.entries(this.#surfaces)) {
+      if (ref === surface) return id;
+    }
+    return null;
+  }
+
+  /**
+   * Update the count badge in the column header for a given activity.
+   * @param {string} activityId
+   */
+  #updateCount(activityId) {
+    const surface = this.#surfaces[activityId];
+    if (!surface) return;
+    const count = surface.querySelectorAll(':scope > [draggable="true"]').length;
+    const column = surface.closest('[data-activity-column]');
+    if (!column) return;
+    const badge = column.querySelector('.sm-activity-count');
+    if (badge) badge.textContent = String(count);
+  }
+
+  /**
+   * Announce a message via the live region.
+   * @param {string} msg
+   */
+  #announce(msg) {
+    if (!this.#liveRegion) return;
+    this.#liveRegion.textContent = '';
+    requestAnimationFrame(() => {
+      if (this.#liveRegion) this.#liveRegion.textContent = msg;
+    });
+  }
+
+  /**
+   * Get a human-readable label for a story item.
+   * @param {HTMLElement} item
+   * @returns {string}
+   */
+  #itemLabel(item) {
+    return item.getAttribute('story-id')
+      || item.getAttribute('data-id')
+      || item.textContent?.trim().slice(0, 40)
+      || 'item';
+  }
+
+  /**
+   * Convert a hyphenated or lowercase id to Title Case.
+   * @param {string} str
+   * @returns {string}
+   */
+  #titleCase(str) {
+    return str
+      .replace(/[-_]/g, ' ')
+      .replace(/\b\w/g, c => c.toUpperCase());
+  }
+}
+
+registerComponent('story-map', StoryMap);
+export { StoryMap };

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

@@ -0,0 +1,35 @@
+<!--
+  story-map — static (zero-JS) form
+  Activity sections with user-story children render as vertical flow before
+  JS upgrades to horizontal columns with drag-and-drop.
+-->
+<story-map>
+  <section data-activity="discovery" data-activity-label="Discovery">
+    <user-story draggable="true" data-id="PROJ-101"
+      story-id="PROJ-101" persona="Researcher" action="interview target users"
+      priority="high" status="done" points="5" detail="compact">
+    </user-story>
+    <user-story draggable="true" data-id="PROJ-102"
+      story-id="PROJ-102" persona="PM" action="review analytics data"
+      priority="medium" status="done" points="3" detail="compact">
+    </user-story>
+  </section>
+  <section data-activity="design" data-activity-label="Design">
+    <user-story draggable="true" data-id="PROJ-201"
+      story-id="PROJ-201" persona="Designer" action="create wireframes"
+      priority="high" status="in-progress" points="5" detail="compact">
+    </user-story>
+  </section>
+  <section data-activity="build" data-activity-label="Build">
+    <user-story draggable="true" data-id="PROJ-301"
+      story-id="PROJ-301" persona="Developer" action="implement API endpoints"
+      priority="high" status="to-do" points="8" detail="compact">
+    </user-story>
+  </section>
+  <section data-activity="validate" data-activity-label="Validate">
+    <user-story draggable="true" data-id="PROJ-401"
+      story-id="PROJ-401" persona="QA" action="run usability testing"
+      priority="high" status="backlog" points="5" detail="compact">
+    </user-story>
+  </section>
+</story-map>

package/src/web-components/story-map/styles.css

@@ -0,0 +1,169 @@
+/* story-map — Light DOM styles (element selector) */
+
+story-map {
+  display: block;
+  container-type: inline-size;
+}
+
+story-map:not(:defined) {
+  display: block;
+}
+
+/* ── Scroll region ────────────────────────────────────── */
+
+.sm-scroll {
+  overflow-x: auto;
+  overflow-y: visible;
+  -webkit-overflow-scrolling: touch;
+}
+
+/* ── Columns container ────────────────────────────────── */
+
+.sm-columns {
+  display: flex;
+  gap: 1px;
+  background: var(--color-border, #e0e0e0);
+  min-inline-size: min-content;
+  border: 1px solid var(--color-border, #e0e0e0);
+  border-radius: var(--radius-l, 0.75rem);
+  overflow: hidden;
+}
+
+/* ── Individual column ────────────────────────────────── */
+
+.sm-column {
+  min-inline-size: 14rem;
+  max-inline-size: 22rem;
+  flex: 1 0 14rem;
+  display: flex;
+  flex-direction: column;
+  background: var(--color-surface, #fff);
+}
+
+/* ── Activity header ──────────────────────────────────── */
+
+.sm-activity-header {
+  position: sticky;
+  inset-block-start: 0;
+  z-index: 2;
+  padding: var(--size-s, 12px) var(--size-m, 16px);
+  background: var(--color-surface-raised, #f8f9fa);
+  border-block-end: 2px solid var(--color-border, #e0e0e0);
+}
+
+.sm-activity-header h3 {
+  margin: 0;
+  font-size: 0.875rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--color-text, #1a1a1a);
+}
+
+/* ── Count badge ──────────────────────────────────────── */
+
+.sm-activity-count {
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: var(--color-text-muted, #666);
+  background: var(--color-border, #e0e0e0);
+  border-radius: var(--radius-full, 9999px);
+  padding: 1px 8px;
+  margin-inline-start: 8px;
+}
+
+/* ── Drag surfaces inside columns ─────────────────────── */
+
+story-map drag-surface {
+  padding: var(--size-s, 12px);
+  min-block-size: 8rem;
+  flex: 1;
+}
+
+story-map drag-surface > * {
+  margin-block-end: var(--size-xs, 8px);
+}
+
+story-map drag-surface > *:last-child {
+  margin-block-end: 0;
+}
+
+/* ── Empty column placeholder ─────────────────────────── */
+
+.sm-empty {
+  color: var(--color-text-muted, #888);
+  font-size: 0.8rem;
+  font-style: italic;
+  padding: var(--size-s, 12px);
+  margin: 0;
+}
+
+/* ── Live region (visually hidden) ────────────────────── */
+
+.sm-live-region {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+}
+
+/* ── Compact variant ──────────────────────────────────── */
+
+story-map[compact] .sm-column {
+  min-inline-size: 11rem;
+  flex: 1 0 11rem;
+}
+
+story-map[compact] .sm-activity-header {
+  padding: var(--size-xs, 8px) var(--size-s, 12px);
+}
+
+story-map[compact] .sm-activity-header h3 {
+  font-size: 0.75rem;
+}
+
+story-map[compact] drag-surface {
+  padding: var(--size-xs, 8px);
+}
+
+/* ── Container query: single-column stacking ──────────── */
+
+@container (max-width: 30rem) {
+  .sm-columns {
+    flex-direction: column;
+  }
+
+  .sm-column {
+    max-inline-size: none;
+  }
+}
+
+/* ── Reduced motion ───────────────────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+  .sm-scroll {
+    scroll-behavior: auto;
+  }
+}
+
+/* ── Print ────────────────────────────────────────────── */
+
+@media print {
+  .sm-scroll {
+    overflow: visible;
+  }
+
+  .sm-activity-header {
+    position: static;
+  }
+
+  .sm-columns {
+    flex-wrap: wrap;
+  }
+
+  .sm-column {
+    break-inside: avoid;
+  }
+}