@profpowell/vb-project-planning 0.2.1 → 0.2.2

package/src/utils/copy-init.js

@@ -26,6 +26,16 @@
  * <input id="dest" type="text">
  * <button data-paste-target="#dest">Paste</button>
  *
+ * Events: successful copies dispatch `vb:copy` ({ text } or { payload })
+ * and pastes dispatch `vb:paste` ({ text }) from the button, bubbling.
+ * (Before 0.2.2 these were synthetic `copy` / `paste` events, which
+ * collided with native ClipboardEvent handlers that read
+ * `e.clipboardData`.)
+ *
+ * Announcements go to one persistent, visually hidden live region
+ * appended to <body>, never inside the button, so the button's
+ * accessible name is unchanged.
+ *
  * @example Programmatic
  * import { copyText, copyRich, pasteFromClipboard } from '/src/utils/copy-init.js';
  * await copyText('hello', { button: myButton });
@@ -34,7 +44,10 @@
  */
 
 const COPIED_DURATION = 1500;
-const ANNOUNCE_DURATION = 1000;
+/** How long an announcement stays in the live region before it is cleared. */
+const ANNOUNCE_DURATION = 5000;
+const COPY_EVENT = 'vb:copy';
+const PASTE_EVENT = 'vb:paste';
 const SELECTOR = '[data-copy], [data-copy-target], [data-paste-target]';
 const DEFAULT_ANNOUNCE = 'Copied to clipboard';
 const DEFAULT_PASTE_ANNOUNCE = 'Pasted from clipboard';
@@ -45,8 +58,8 @@ const resetTimers = new WeakMap();
  * Copy text to the clipboard with VB's standard feedback semantics.
  *
  * Performs writeText, sets data-state="copied" on the button (if given),
- * announces to screen readers, and dispatches a `copy` CustomEvent from
- * the button. Safe to call when the Clipboard API is unavailable or
+ * announces to screen readers, and dispatches a `vb:copy` CustomEvent
+ * from the button. Safe to call when the Clipboard API is unavailable or
  * permission is denied — returns false silently.
  *
  * @param {string} text - The text to copy.
@@ -122,10 +135,10 @@ async function copyRich(payload, options = {}) {
 
 /**
  * Apply the VB-standard post-write feedback: data-state, screen-reader
- * announce, and a CustomEvent from the button.
+ * announce, and a `vb:copy` / `vb:paste` CustomEvent from the button.
  * @param {{ button?: HTMLElement, duration: number, announceMessage: string, eventDetail: object, state?: string, eventName?: string }} args
  */
-function applyFeedback({ button, duration, announceMessage, eventDetail, state = 'copied', eventName = 'copy' }) {
+function applyFeedback({ button, duration, announceMessage, eventDetail, state = 'copied', eventName = COPY_EVENT }) {
   if (button) {
     button.dataset.state = state;
     const prior = resetTimers.get(button);
@@ -141,7 +154,7 @@ function applyFeedback({ button, duration, announceMessage, eventDetail, state =
     }));
   }
 
-  announce(announceMessage, button ?? document.body);
+  announce(announceMessage);
 }
 
 /**
@@ -151,7 +164,7 @@ function applyFeedback({ button, duration, announceMessage, eventDetail, state =
  * elements receive `.textContent`. After writing, an `input` event
  * is dispatched on the target so framework listeners notice the change.
  * Sets data-state="pasted" on the button, announces to screen readers,
- * and dispatches a `paste` CustomEvent from the button.
+ * and dispatches a `vb:paste` CustomEvent from the button.
  *
  * Safe to call when the Clipboard API is unavailable or the user
  * denies permission — returns null silently.
@@ -188,7 +201,7 @@ async function pasteFromClipboard(target, options = {}) {
     announceMessage,
     eventDetail: { text },
     state: 'pasted',
-    eventName: 'paste',
+    eventName: PASTE_EVENT,
   });
   return text;
 }
@@ -242,19 +255,45 @@ function getText(button) {
   return '';
 }
 
+/** @type {ReturnType<typeof setTimeout> | undefined} */
+let clearTimer;
+
 /**
- * Announce a message to screen readers
- * @param {string} message
- * @param {Element} context - Element to append announcement to
+ * The page's single clipboard live region: visually hidden, appended to
+ * <body> once and reused (shared across copies of this module).
+ * @returns {HTMLElement}
  */
-function announce(message, context) {
-  const el = document.createElement('div');
+function liveRegion() {
+  let el = /** @type {HTMLElement | null} */ (document.querySelector('body > [data-vb-clipboard-status]'));
+  if (el) return el;
+  el = document.createElement('div');
+  el.setAttribute('data-vb-clipboard-status', '');
   el.setAttribute('role', 'status');
   el.setAttribute('aria-live', 'polite');
-  el.className = 'visually-hidden';
-  el.textContent = message;
-  context.appendChild(el);
-  setTimeout(() => el.remove(), ANNOUNCE_DURATION);
+  el.setAttribute('aria-atomic', 'true');
+  el.style.cssText = 'position:absolute;inline-size:1px;block-size:1px;margin:-1px;padding:0;' +
+    'overflow:hidden;clip-path:inset(50%);white-space:nowrap;border:0;';
+  document.body.appendChild(el);
+  return el;
+}
+
+/**
+ * Announce a message to screen readers. The region already exists (or is
+ * created now, empty) and the text is set on the next frame, so the
+ * change is announced even on first use and for repeated messages.
+ * @param {string} message
+ */
+function announce(message) {
+  if (!document.body) return;
+  const region = liveRegion();
+  region.textContent = '';
+  requestAnimationFrame(() => {
+    region.textContent = message;
+    clearTimeout(clearTimer);
+    clearTimer = setTimeout(() => {
+      if (region.textContent === message) region.textContent = '';
+    }, ANNOUNCE_DURATION);
+  });
 }
 
 // Auto-init on DOMContentLoaded

package/src/web-components/_ux-base.js

@@ -1,23 +1,24 @@
 /**
- * Shared utilities for UX planning web components
- * (user-persona, user-story, user-journey, empathy-map, impact-effort, story-map)
+ * Shared utilities for the pack's planning web components.
  *
- * Shadow DOM components extend HTMLElement directly.
- * Light DOM components (impact-effort, story-map) extend VBElement.
+ * - Helpers (`esc`, `initials`, `hashColor`, `lucideSvg`, `UX_ICONS`,
+ *   `QUADRANT_META`, `EMOTION_META`) are used by user-persona, user-story,
+ *   user-journey, empathy-map, work-item, adr-wc, impact-effort, story-map
+ *   and review-surface.
+ * - `UXShadowElement` is the Shadow DOM base class for the six record cards
+ *   (user-persona, user-story, user-journey, empathy-map, work-item, adr-wc).
+ *   It owns the one-time setup / reconnect guard, the single-fetch `src`
+ *   loader, the once-only `*:ready` event and the `*:upgraded` event.
+ *   Light DOM components (impact-effort, story-map, kanban-board, …) extend
+ *   VBElement from src/lib/vb-element.js instead.
  */
 
-/**
- * HTML-escape a string to prevent XSS in shadow DOM innerHTML.
- * @param {string} s
- * @returns {string}
- */
-export function esc(s) {
-  return String(s)
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+import { stringHash } from '../lib/hash.js';
+import { SrcLoader } from '../lib/src-loader.js';
+
+import { esc } from '../lib/escape.js';
+
+export { esc };
 
 /**
  * Extract up to 2 initials from a name.
@@ -39,18 +40,11 @@ export function initials(name) {
  * @returns {string} HSL color string
  */
 export function hashColor(name) {
-  let hash = 0;
-  for (let i = 0; i < name.length; i++) {
-    hash = name.charCodeAt(i) + ((hash << 5) - hash);
-  }
+  const hash = stringHash(name);
   const hue = ((hash % 360) + 360) % 360;
   return `hsl(${hue}, 65%, 55%)`;
 }
 
-/**
- * Emotion metadata used by user-journey (and potentially other planning components).
- * Maps emotion names to emoji, normalized score (0–1), and color.
- */
 /**
  * Build a Lucide-style inline SVG string (24x24, stroke-based).
  * @param {string} inner - SVG child elements (path, circle, line, etc.)
@@ -104,3 +98,394 @@ export const EMOTION_META = {
   frustrated: { emoji: '😤', score: 0.18, color: '#ef4444' },
   angry:      { emoji: '😠', score: 0.05, color: '#dc2626' },
 };
+
+/**
+ * Look up emotion metadata by name. Own-property lookup only, so data such
+ * as `"__proto__"` or `"constructor"` falls back to `neutral`.
+ * @param {unknown} name
+ * @returns {{ emoji: string, score: number, color: string }}
+ */
+export function emotionMeta(name) {
+  const key = String(name ?? '').toLowerCase().trim();
+  return Object.hasOwn(EMOTION_META, key) ? EMOTION_META[key] : EMOTION_META.neutral;
+}
+
+/**
+ * Whether `name` is a known emotion (own property of EMOTION_META).
+ * @param {unknown} name
+ * @returns {boolean}
+ */
+export function isEmotion(name) {
+  return Object.hasOwn(EMOTION_META, String(name ?? '').toLowerCase().trim());
+}
+
+/* ── Card status / priority vocabularies ─────────────────────────── */
+
+/** Priority badges shared by user-story and work-item. */
+export const PRIORITIES = Object.freeze({
+  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)' },
+});
+
+/** Workflow statuses shared by user-story and work-item (work-item adds `blocked`). */
+export const STATUSES = Object.freeze({
+  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)' },
+});
+
+/**
+ * Own-property lookup in a vocabulary table, with a fallback key.
+ * @template T
+ * @param {Record<string, T>} table
+ * @param {string} key
+ * @param {string} fallback
+ * @returns {T}
+ */
+export function lookup(table, key, fallback) {
+  return Object.hasOwn(table, key) ? table[key] : table[fallback];
+}
+
+/* ── Small DOM / data helpers ────────────────────────────────────── */
+
+/**
+ * `href` value for an in-page fragment link to an element id, escaped for
+ * an attribute position in an innerHTML template.
+ * @param {unknown} id
+ * @returns {string}
+ */
+export function fragmentHref(id) {
+  return esc(`#${encodeURIComponent(String(id ?? ''))}`);
+}
+
+/**
+ * Split a comma-separated attribute value into trimmed, non-empty parts.
+ * @param {string | null} raw
+ * @returns {string[]}
+ */
+export function splitList(raw) {
+  return raw ? raw.split(',').map(s => s.trim()).filter(Boolean) : [];
+}
+
+/**
+ * Normalise a data field to an array of strings: arrays are kept, a single
+ * scalar becomes a one-item array, null/undefined/'' become [].
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+export function asList(value) {
+  if (Array.isArray(value)) return value.map(v => String(v ?? ''));
+  if (value == null || value === '') return [];
+  return [String(value)];
+}
+
+/**
+ * The light-DOM child assigned to `slot`, if any (direct children only:
+ * nothing deeper can be slotted).
+ * @param {Element} host
+ * @param {string} slot
+ * @returns {Element | undefined}
+ */
+export function slottedChild(host, slot) {
+  return [...host.children].find(c => c.getAttribute('slot') === slot);
+}
+
+/**
+ * Create (or, with `replace`, update) the light-DOM child for a slot from a
+ * data value. Arrays become a `<ul>` of `<li>`s; anything else becomes
+ * `tag` with the value as text. Text is set with textContent, never parsed.
+ *
+ * @param {Element} host
+ * @param {string} slot
+ * @param {unknown} value
+ * @param {{ tag?: string, list?: boolean, replace?: boolean }} [opts]
+ *   tag: element for scalar values (default `p`); list: always render a
+ *   list (wrapping a scalar); replace: update an existing child instead of
+ *   leaving it alone.
+ */
+export function fillSlot(host, slot, value, { tag = 'p', list = false, replace = false } = {}) {
+  if (value == null || value === '') return;
+  const existing = slottedChild(host, slot);
+  if (existing && !replace) return;
+  const wantList = list || Array.isArray(value);
+  const isList = (/** @type {Element} */ el) => el.tagName === 'UL' || el.tagName === 'OL';
+  let el = existing;
+  if (!el || wantList !== isList(el)) {
+    const fresh = document.createElement(wantList ? 'ul' : tag);
+    fresh.slot = slot;
+    if (el) el.replaceWith(fresh); else host.appendChild(fresh);
+    el = fresh;
+  }
+  if (wantList) {
+    el.replaceChildren(...asList(value).map(item => {
+      const li = document.createElement('li');
+      li.textContent = item;
+      return li;
+    }));
+  } else {
+    el.textContent = String(value);
+  }
+}
+
+/**
+ * Read a slotted child back as data: list items as a string array, any
+ * other element as its trimmed text. Returns undefined when absent/empty.
+ * @param {Element} host
+ * @param {string} slot
+ * @returns {string | string[] | undefined}
+ */
+export function readSlot(host, slot) {
+  const el = slottedChild(host, slot);
+  if (!el) return undefined;
+  if (el.tagName === 'UL' || el.tagName === 'OL') {
+    const items = [...el.querySelectorAll('li')].map(li => li.textContent?.trim() ?? '').filter(Boolean);
+    return items.length ? items : undefined;
+  }
+  return el.textContent?.trim() || undefined;
+}
+
+/**
+ * Detail level from the `detail` / `compact` attributes.
+ * @param {Element} host
+ * @returns {string} full | compact | minimal
+ */
+export function detailLevel(host) {
+  return host.getAttribute('detail') || (host.hasAttribute('compact') ? 'compact' : 'full');
+}
+
+/**
+ * Mark every section whose first `<slot>` has no assigned nodes with
+ * `data-empty` (compact cards hide those).
+ * @param {ParentNode} root
+ * @param {string} sectionSelector
+ */
+export function markEmptySections(root, sectionSelector) {
+  for (const section of root.querySelectorAll(sectionSelector)) {
+    const slot = section.querySelector('slot');
+    if (slot && slot.assignedNodes().length === 0) section.setAttribute('data-empty', '');
+  }
+}
+
+/* ── Base class for the Shadow DOM record cards ──────────────────── */
+
+/**
+ * Shadow DOM base for user-persona, user-story, user-journey, empathy-map,
+ * work-item and adr-wc.
+ *
+ * Lifecycle contract:
+ * - First connect runs `_setup()`, then either renders and fires the ready
+ *   event, or (with `src`) fetches once and fires ready after the fetched
+ *   data renders. Then `_connect()` runs, `data-upgraded` is set and
+ *   `<tag>:upgraded` is dispatched in a microtask.
+ * - Reconnects (e.g. a kanban drag moving the card) only run `_connect()`:
+ *   no re-fetch, no re-render, no second ready event.
+ * - Disconnect runs `_disconnect()` (stop observers). A pending fetch keeps
+ *   going, so a card moved mid-load still fills in.
+ * - Attribute changes before first setup are ignored (setup reads them).
+ *   After setup, a `src` change refetches (aborting the earlier request and
+ *   dropping its response, via SrcLoader); removing `src` aborts a pending
+ *   fetch and renders the authored content (firing ready if it has not
+ *   fired yet). Other changes call `_attributeEffects(name)` and then
+ *   `_attributeChanged(name)`.
+ * - A data record (`.data` or `src`) sets attributes without a render per
+ *   attribute; once it is applied, `_attributeEffects(name)` runs for each
+ *   attribute it changed, then the card renders once.
+ *
+ * Subclasses set `static readyEvent` and implement `_render()`,
+ * `_readyDetail()` and, if they load JSON, `_applyData(data)`. Side effects
+ * of an attribute (observers, …) belong in `_attributeEffects()`, not in
+ * `_attributeChanged()`, so they also run when a data record sets it.
+ */
+export class UXShadowElement extends HTMLElement {
+  /** Ready event name, e.g. `story-ready`. */
+  static readyEvent = '';
+
+  /** Fallback text for slots whose light-DOM child was removed after setup. */
+  _slotCache = new Map();
+
+  #setUp = false;
+  #readyFired = false;
+  #loader = new SrcLoader();
+  #quiet = 0;
+  /** Attributes changed while quiet (a data record being applied). */
+  /** @type {Set<string>} */
+  #quietChanges = new Set();
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  /** True once first-connect setup has run. */
+  get _isSetUp() { return this.#setUp; }
+
+  connectedCallback() {
+    if (this.#setUp) {
+      this._connect();
+      return;
+    }
+    this.#setUp = true;
+    this._cacheSlotValues();
+    this._setup();
+    const src = this.getAttribute('src');
+    if (src) {
+      this._loadSrc(src);
+    } else {
+      this._render();
+      this._fireReady();
+    }
+    this._connect();
+    this.setAttribute('data-upgraded', '');
+    queueMicrotask(() => {
+      this.dispatchEvent(new CustomEvent(`${this.localName}:upgraded`, { bubbles: true }));
+    });
+  }
+
+  disconnectedCallback() {
+    this._disconnect();
+  }
+
+  /**
+   * @param {string} name
+   * @param {string | null} oldValue
+   * @param {string | null} newValue
+   */
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (!this.#setUp || oldValue === newValue) return;
+    if (this.#quiet) {
+      if (name !== 'src') this.#quietChanges.add(name);
+      return;
+    }
+    if (name === 'src') {
+      this._loadSrc(newValue);
+      return;
+    }
+    this._attributeEffects(name);
+    this._attributeChanged(name);
+  }
+
+  /* ── Hooks (override as needed) ─────────────────── */
+
+  /** One-time setup before the first render (e.g. id from story-id). */
+  _setup() {}
+  /** Every connect, after setup on the first: (re)attach observers. */
+  _connect() {}
+  /** Every disconnect: detach observers. */
+  _disconnect() {}
+  /**
+   * Non-render side effects of an attribute change (e.g. re-pointing an
+   * observer). Runs before `_attributeChanged()`, and also after a data
+   * record that changed the attribute has been applied.
+   * @param {string} _name
+   */
+  _attributeEffects(_name) {}
+  /** @param {string} _name */
+  _attributeChanged(_name) { this._render(); }
+  /** Render the full shadow tree. */
+  _render() {}
+  /** @returns {object} detail for the ready event */
+  _readyDetail() { return {}; }
+  /** @param {Record<string, any>} _data apply a JSON record to attributes/slots/properties */
+  _applyData(_data) {}
+  /** Shown while `src` loads. Default: render what is already known. */
+  _renderLoading() { this._render(); }
+  /** @param {Error} err shown when `src` fails. Default: a console warning. */
+  _renderError(err) {
+    console.warn(`[${this.localName}] Failed to load src="${this.getAttribute('src')}":`, err);
+  }
+
+  /* ── Shared behaviour ───────────────────────────── */
+
+  _cacheSlotValues() {
+    for (const child of this.children) {
+      const slot = child.getAttribute('slot');
+      if (slot) this._slotCache.set(slot, child.textContent?.trim() ?? '');
+    }
+  }
+
+  /**
+   * Trimmed text of the slotted child for `slot`, else the cached value.
+   * @param {string} slot
+   * @returns {string}
+   */
+  _slotText(slot) {
+    return slottedChild(this, slot)?.textContent?.trim() || this._slotCache.get(slot) || '';
+  }
+
+  /**
+   * Run `fn` without attribute changes triggering re-renders (used while a
+   * data record sets several attributes; the caller renders once after).
+   * @param {() => void} fn
+   */
+  _quietly(fn) {
+    this.#quiet++;
+    try { fn(); } finally { this.#quiet--; }
+    if (this.#quiet === 0 && this.#quietChanges.size) {
+      const changed = [...this.#quietChanges];
+      this.#quietChanges.clear();
+      for (const name of changed) this._attributeEffects(name);
+    }
+  }
+
+  /**
+   * Apply a record assigned to `.data`, re-render, and emit
+   * `<tag>:data-changed` { data, source: 'property' }.
+   * @param {unknown} value
+   */
+  _setData(value) {
+    if (!value || typeof value !== 'object') return;
+    this._quietly(() => this._applyData(/** @type {Record<string, any>} */ (value)));
+    this._cacheSlotValues();
+    this._render();
+    this.dispatchEvent(new CustomEvent(`${this.localName}:data-changed`, {
+      detail: { data: /** @type {any} */ (this).data, source: 'property' },
+      bubbles: true, composed: true,
+    }));
+  }
+
+  /** Dispatch the ready event, at most once per element. */
+  _fireReady() {
+    if (this.#readyFired) return;
+    const type = /** @type {typeof UXShadowElement} */ (this.constructor).readyEvent;
+    if (!type) return;
+    this.#readyFired = true;
+    this.dispatchEvent(new CustomEvent(type, {
+      detail: this._readyDetail(),
+      bubbles: true, composed: true,
+    }));
+  }
+
+  /**
+   * Fetch `url` as JSON and apply it. Each call supersedes the previous
+   * one: the earlier request is aborted and its response, if it still
+   * arrives, is ignored. A null/empty `url` (src removed) aborts any
+   * pending request and renders the authored content instead.
+   * @param {string | null} url
+   */
+  async _loadSrc(url) {
+    if (!url) {
+      this.#loader.cancel();
+      this._render();
+      this._fireReady();
+      return;
+    }
+    this._renderLoading();
+    let result;
+    try {
+      result = await this.#loader.fetchJson(url);
+    } catch (err) {
+      this._renderError(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    if (!result) return;
+    const { data } = result;
+    this._quietly(() => this._applyData(data && typeof data === 'object' ? data : {}));
+    this._cacheSlotValues();
+    this._render();
+    this._fireReady();
+  }
+}

package/src/web-components/adr-wc/README.md

@@ -1,11 +1,11 @@
 ---
 title: "ADR Record Specification"
-component: adr-record
+component: adr-wc
 version: 1.0.0
 status: stable
 ---
 
-# ADR Record
+# ADR Record (`<adr-wc>`)
 
 MADR-format Architectural Decision Record card with status tracking and cross-referencing.
 
@@ -18,48 +18,50 @@ Part of the **UX Planning Pack**. Works standalone or inside `<kanban-board>`, `
 ## Static HTML Form
 
 ```html
-<adr-record
+<adr-wc
   adr-id="ADR-001"
-  title="Use PostgreSQL for persistence"
   status="accepted"
-  date="2026-01-15"
   superseded-by="ADR-003">
+  <h2 slot="title">Use PostgreSQL for persistence</h2>
+  <time slot="date" datetime="2026-01-15">January 15, 2026</time>
   <p slot="context">We need a relational database for complex queries.</p>
   <p slot="decision">Use PostgreSQL 16 with pgvector extension.</p>
   <ul slot="consequences">
     <li>Good: mature ecosystem, strong SQL support</li>
     <li>Bad: operational overhead vs managed NoSQL</li>
   </ul>
-</adr-record>
+</adr-wc>
 ```
 
 ## Attributes
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `adr-id` | string | -- | ADR identifier (also sets HTML `id`) |
-| `title` | string | -- | Decision title |
-| `status` | string | `"proposed"` | `proposed`, `accepted`, `deprecated`, `superseded` |
-| `date` | string | -- | ISO date string |
+| `adr-id` | string | -- | ADR identifier (e.g., ADR-001); sets the HTML id on first connect when none is set |
+| `status` | `proposed`, `accepted`, `deprecated`, `superseded` | `"proposed"` | Decision status |
 | `supersedes` | string | -- | Comma-separated ADR IDs this supersedes |
 | `superseded-by` | string | -- | Comma-separated ADR IDs that supersede this |
-| `detail` | string | `"full"` | `full`, `compact`, `minimal` |
-| `compact` | boolean | -- | Alias for `detail="compact"` |
-| `src` | string | -- | JSON data URL |
+| `detail` | `full`, `compact`, `minimal` | `"full"` | Detail level. minimal shows id, status and title only. |
+| `compact` | boolean | -- | Alias for detail=compact |
+| `src` | string | -- | 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
 
 | Slot | Description |
 |------|-------------|
+| `title` | Decision heading (e.g., `<h2>`) |
+| `date` | Decision date (e.g., `<time datetime="...">`) |
 | `context` | Why the decision was needed |
 | `decision` | What was decided |
 | `consequences` | Outcomes (positive and negative) |
 
 ## Events
 
-| Event | Detail |
-|-------|--------|
-| `adr-record:ready` | `{ adrId, title, status }` |
+| Event | Detail | When |
+|-------|--------|------|
+| `adr-wc:ready` | `{ adrId, title, status }` | 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. |
+| `adr-wc:upgraded` | -- | Once, in a microtask after first connect. Wait for this before assigning .data from a framework. |
+| `adr-wc:data-changed` | `{ data, source: 'property' }` | After .data is assigned |
 
 ## Status Colors