beads-ui 0.1.2 → 0.3.0

package/app/views/new-issue-dialog.js

@@ -0,0 +1,345 @@
+import { ISSUE_TYPES, typeLabel } from '../utils/issue-type.js';
+import { priority_levels } from '../utils/priority.js';
+
+/**
+ * Create and manage the New Issue dialog (native <dialog>).
+ * @param {HTMLElement} mount_element - Container to attach dialog (e.g., main#app)
+ * @param {(type: import('../protocol.js').MessageType, payload?: unknown) => Promise<unknown>} sendFn - Transport function
+ * @param {{ gotoIssue: (id: string) => void }} router - Router for opening details after create
+ * @param {{ setState: (patch: any) => void, getState: () => any }} [store]
+ * @returns {{ open: () => void, close: () => void }}
+ */
+export function createNewIssueDialog(mount_element, sendFn, router, store) {
+  const dialog = /** @type {HTMLDialogElement} */ (
+    document.createElement('dialog')
+  );
+  dialog.id = 'new-issue-dialog';
+  dialog.setAttribute('role', 'dialog');
+  dialog.setAttribute('aria-modal', 'true');
+
+  dialog.innerHTML = `
+    <div class="new-issue__container" part="container">
+      <header class="new-issue__header">
+        <div class="new-issue__title">New Issue</div>
+        <button type="button" class="new-issue__close" aria-label="Close">×</button>
+      </header>
+      <div class="new-issue__body">
+        <form id="new-issue-form" class="new-issue__form">
+          <label for="new-title">Title</label>
+          <input id="new-title" name="title" type="text" required placeholder="Short summary" />
+
+          <label for="new-type">Type</label>
+          <select id="new-type" name="type" aria-label="Issue type"></select>
+
+          <label for="new-priority">Priority</label>
+          <select id="new-priority" name="priority" aria-label="Priority"></select>
+
+          <label for="new-labels">Labels</label>
+          <input id="new-labels" name="labels" type="text" placeholder="comma,separated" />
+
+          <label for="new-description">Description</label>
+          <textarea id="new-description" name="description" rows="6" placeholder="Optional markdown description"></textarea>
+
+          <div aria-live="polite" role="status" class="new-issue__error" id="new-issue-error"></div>
+
+          <div class="new-issue__actions" style="grid-column: 1 / -1">
+            <button type="button" id="btn-cancel">Cancel (Esc)</button>
+            <button type="submit" id="btn-create">Create</button>
+          </div>
+        </form>
+      </div>
+    </div>
+  `;
+
+  mount_element.appendChild(dialog);
+
+  const form = /** @type {HTMLFormElement} */ (
+    dialog.querySelector('#new-issue-form')
+  );
+  const input_title = /** @type {HTMLInputElement} */ (
+    dialog.querySelector('#new-title')
+  );
+  const sel_type = /** @type {HTMLSelectElement} */ (
+    dialog.querySelector('#new-type')
+  );
+  const sel_priority = /** @type {HTMLSelectElement} */ (
+    dialog.querySelector('#new-priority')
+  );
+  const input_labels = /** @type {HTMLInputElement} */ (
+    dialog.querySelector('#new-labels')
+  );
+  const input_description = /** @type {HTMLTextAreaElement} */ (
+    dialog.querySelector('#new-description')
+  );
+  const error_box = /** @type {HTMLDivElement} */ (
+    dialog.querySelector('#new-issue-error')
+  );
+  const btn_cancel = /** @type {HTMLButtonElement} */ (
+    dialog.querySelector('#btn-cancel')
+  );
+  const btn_create = /** @type {HTMLButtonElement} */ (
+    dialog.querySelector('#btn-create')
+  );
+  const btn_close = /** @type {HTMLButtonElement} */ (
+    dialog.querySelector('.new-issue__close')
+  );
+
+  // Populate selects
+  function populateSelects() {
+    sel_type.replaceChildren();
+    // Empty option to allow leaving type unspecified
+    const optEmpty = document.createElement('option');
+    optEmpty.value = '';
+    optEmpty.textContent = '— Select —';
+    sel_type.appendChild(optEmpty);
+    for (const t of ISSUE_TYPES) {
+      const o = document.createElement('option');
+      o.value = t;
+      o.textContent = typeLabel(t);
+      sel_type.appendChild(o);
+    }
+
+    sel_priority.replaceChildren();
+    for (let i = 0; i <= 4; i += 1) {
+      const o = document.createElement('option');
+      o.value = String(i);
+      const label = priority_levels[i] || 'Medium';
+      o.textContent = `${i} – ${label}`;
+      sel_priority.appendChild(o);
+    }
+  }
+  populateSelects();
+
+  function requestClose() {
+    try {
+      if (typeof dialog.close === 'function') {
+        dialog.close();
+      } else {
+        dialog.removeAttribute('open');
+      }
+    } catch {
+      dialog.removeAttribute('open');
+    }
+  }
+
+  /**
+   * @param {boolean} is_busy
+   */
+  function setBusy(is_busy) {
+    input_title.disabled = is_busy;
+    sel_type.disabled = is_busy;
+    sel_priority.disabled = is_busy;
+    input_labels.disabled = is_busy;
+    input_description.disabled = is_busy;
+    btn_cancel.disabled = is_busy;
+    btn_create.disabled = is_busy;
+    btn_create.textContent = is_busy ? 'Creating…' : 'Create';
+  }
+
+  function clearError() {
+    error_box.textContent = '';
+  }
+
+  /**
+   * @param {string} msg
+   */
+  function setError(msg) {
+    error_box.textContent = msg;
+  }
+
+  function loadDefaults() {
+    try {
+      const t = window.localStorage.getItem('beads-ui.new.type');
+      if (t) {
+        sel_type.value = t;
+      } else {
+        sel_type.value = '';
+      }
+      const p = window.localStorage.getItem('beads-ui.new.priority');
+      if (p && /^\d$/.test(p)) {
+        sel_priority.value = p;
+      } else {
+        sel_priority.value = '2';
+      }
+    } catch {
+      sel_type.value = '';
+      sel_priority.value = '2';
+    }
+  }
+
+  function saveDefaults() {
+    try {
+      const t = sel_type.value || '';
+      const p = sel_priority.value || '';
+      if (t.length > 0) {
+        window.localStorage.setItem('beads-ui.new.type', t);
+      }
+      if (p.length > 0) {
+        window.localStorage.setItem('beads-ui.new.priority', p);
+      }
+    } catch {
+      // ignore persistence errors
+    }
+  }
+
+  /**
+   * Extract numeric suffix from an id like "UI-123"; return -1 when absent.
+   * @param {string} id
+   */
+  function idNumeric(id) {
+    const m = /-(\d+)$/.exec(String(id || ''));
+    return m && m[1] ? Number(m[1]) : -1;
+  }
+
+  /**
+   * Submit handler: validate, create, then open the created issue details.
+   * @returns {Promise<void>}
+   */
+  async function createNow() {
+    clearError();
+    const title = String(input_title.value || '').trim();
+    if (title.length === 0) {
+      setError('Title is required');
+      input_title.focus();
+      return;
+    }
+    const prio = Number(sel_priority.value || '2');
+    if (!(prio >= 0 && prio <= 4)) {
+      setError('Priority must be 0..4');
+      sel_priority.focus();
+      return;
+    }
+    const type = String(sel_type.value || '');
+    const desc = String(input_description.value || '');
+    const labels = String(input_labels.value || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+
+    /** @type {{ title: string, type?: string, priority?: number, description?: string }} */
+    const payload = { title };
+    if (type.length > 0) {
+      payload.type = type;
+    }
+    if (String(prio).length > 0) {
+      payload.priority = prio;
+    }
+    if (desc.length > 0) {
+      payload.description = desc;
+    }
+
+    setBusy(true);
+    try {
+      await sendFn('create-issue', payload);
+    } catch {
+      setBusy(false);
+      setError('Failed to create issue');
+      return;
+    }
+
+    saveDefaults();
+
+    // Best-effort: find the created id by matching title among open issues and picking the highest numeric id
+    /** @type {any} */
+    let list = null;
+    try {
+      list = await sendFn('list-issues', {
+        filters: { status: 'open', limit: 50 }
+      });
+    } catch {
+      list = null;
+    }
+    let created_id = '';
+    if (Array.isArray(list)) {
+      const matches = list.filter((it) => String(it.title || '') === title);
+      if (matches.length > 0) {
+        /** @type {any} */
+        let best = matches[0];
+        for (const it of matches) {
+          const ai = idNumeric(best.id || '');
+          const bi = idNumeric(it.id || '');
+          if (bi > ai) {
+            best = it;
+          }
+        }
+        created_id = String(best.id || '');
+      }
+    }
+
+    // Apply labels if any
+    if (created_id && labels.length > 0) {
+      for (const label of labels) {
+        try {
+          await sendFn('label-add', { id: created_id, label });
+        } catch {
+          // ignore label failures
+        }
+      }
+    }
+
+    // Navigate to created issue if found
+    if (created_id) {
+      try {
+        router.gotoIssue(created_id);
+      } catch {
+        // ignore routing errors
+      }
+      // Also set state directly to ensure dialog opens even if hash routing is suppressed in tests
+      try {
+        if (store) {
+          store.setState({ selected_id: created_id });
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    setBusy(false);
+    requestClose();
+  }
+
+  // Events
+  dialog.addEventListener('cancel', (ev) => {
+    ev.preventDefault();
+    requestClose();
+  });
+  btn_close.addEventListener('click', () => requestClose());
+  btn_cancel.addEventListener('click', () => requestClose());
+  dialog.addEventListener('keydown', (ev) => {
+    if (ev.key === 'Enter' && (ev.ctrlKey || ev.metaKey)) {
+      ev.preventDefault();
+      void createNow();
+    }
+  });
+  form.addEventListener('submit', (ev) => {
+    ev.preventDefault();
+    void createNow();
+  });
+
+  return {
+    open() {
+      form.reset();
+      clearError();
+      loadDefaults();
+      try {
+        if ('showModal' in dialog && typeof dialog.showModal === 'function') {
+          dialog.showModal();
+        } else {
+          dialog.setAttribute('open', '');
+        }
+      } catch {
+        dialog.setAttribute('open', '');
+      }
+      setTimeout(() => {
+        try {
+          input_title.focus();
+        } catch {
+          // ignore
+        }
+      }, 0);
+    },
+    close() {
+      requestClose();
+    }
+  };
+}

package/app/ws.js

@@ -9,7 +9,7 @@
  * Usage:
  *   const ws = createWsClient();
  *   const data = await ws.send('list-issues', { filters: {} });
- *   const off = ws.on('issues-changed', (payload) => { ... });
+ *   const off = ws.on('snapshot', (payload) => { <push event> });
  */
 import { MESSAGE_TYPES, makeRequest, nextId } from './protocol.js';
 
@@ -73,12 +73,28 @@ export function createWsClient(options = {}) {
   const queue = [];
   /** @type {Map<string, Set<(payload: any) => void>>} */
   const handlers = new Map();
+  /** @type {Set<(s: ConnectionState) => void>} */
+  const connection_handlers = new Set();
+
+  /**
+   * @param {ConnectionState} s
+   */
+  function notifyConnection(s) {
+    for (const fn of Array.from(connection_handlers)) {
+      try {
+        fn(s);
+      } catch {
+        // ignore listener errors
+      }
+    }
+  }
 
   function scheduleReconnect() {
     if (!should_reconnect || reconnect_timer) {
       return;
     }
     state = 'reconnecting';
+    notifyConnection(state);
     const base = Math.min(
       backoff.maxMs || 0,
       (backoff.initialMs || 0) * Math.pow(backoff.factor || 1, attempts)
@@ -105,9 +121,8 @@ export function createWsClient(options = {}) {
 
   function onOpen() {
     state = 'open';
+    notifyConnection(state);
     attempts = 0;
-    // subscribe first
-    sendRaw(makeRequest('subscribe-updates', {}));
     // flush queue
     while (queue.length) {
       const req = queue.shift();
@@ -160,6 +175,7 @@ export function createWsClient(options = {}) {
 
   function onClose() {
     state = 'closed';
+    notifyConnection(state);
     // fail all pending
     for (const [id, p] of pending.entries()) {
       p.reject(new Error('ws disconnected'));
@@ -175,15 +191,15 @@ export function createWsClient(options = {}) {
     }
     const url = resolveUrl();
     try {
-      ws = /** @type {any} */ (new WebSocket(url));
+      ws = new WebSocket(url);
       state = 'connecting';
-      const s = /** @type {any} */ (ws);
-      s.addEventListener('open', onOpen);
-      s.addEventListener('message', onMessage);
-      s.addEventListener('error', () => {
+      notifyConnection(state);
+      ws.addEventListener('open', onOpen);
+      ws.addEventListener('message', onMessage);
+      ws.addEventListener('error', () => {
         // let close handler handle reconnect
       });
-      s.addEventListener('close', onClose);
+      ws.addEventListener('close', onClose);
     } catch (err) {
       logger.error('ws connect failed', err);
       scheduleReconnect();
@@ -231,6 +247,17 @@ export function createWsClient(options = {}) {
         set?.delete(handler);
       };
     },
+    /**
+     * Subscribe to connection state changes.
+     * @param {(state: ConnectionState) => void} handler
+     * @returns {() => void}
+     */
+    onConnection(handler) {
+      connection_handlers.add(handler);
+      return () => {
+        connection_handlers.delete(handler);
+      };
+    },
     /** Close and stop reconnecting. */
     close() {
       should_reconnect = false;

package/bin/bdui.js

@@ -10,7 +10,7 @@ const argv = process.argv.slice(2);
 try {
   const code = await main(argv);
   if (Number.isFinite(code)) {
-    process.exitCode = /** @type {number} */ (code);
+    process.exitCode = code;
   }
 } catch (err) {
   console.error(String(/** @type {any} */ (err)?.message || err));

package/docs/adr/001-push-only-lists.md

@@ -0,0 +1,134 @@
+# ADR 001 — Push‑Only Lists (v2)
+
+```
+Date: 2025-10-26
+Status: Accepted (data‑flow details superseded by ADR 002)
+Owner: agent
+```
+
+## Context
+
+The UI currently mixes push updates with read RPCs like `list-issues` and
+`epic-status`. This ADR establishes the push‑only direction for list data and
+removing read RPCs in list views. It predated ADR 002 which later simplified the
+data flow further (per‑subscription stores + full‑issue payloads).
+
+- Push streams provide everything lists need to render. See
+  `docs/protocol/issues-push-v2.md` and ADR 002. Earlier iterations used a
+  central `issues` entity cache plus `list-delta` membership; this has been
+  replaced by per‑subscription stores receiving full issue payloads.
+
+We want every list‑shaped view (Issues, Board, Epics → children) to render
+exclusively from local push data. Reads remain only for mutations that return a
+single updated entity (e.g. detail view refresh).
+
+Related docs:
+
+- Protocol: `docs/protocol/issues-push-v2.md`
+- Server plan: `docs/data-exchange-subscription-plan.md`
+
+## Decision
+
+- One active subscription per visible list. Examples (client ids):
+  - Issues tab: `tab:issues` with spec from filters via `computeIssuesSpec()`
+  - Board: `tab:board:ready|in-progress|closed|blocked`
+  - Epics list: `tab:epics` (for epic entities); children subscribe on expand as
+    `detail:{id}` with `{ type: 'issue-detail', params: { id } }`
+- Rendering reads from two local stores only:
+  - `per‑subscription stores`: one store per active client subscription id.
+    Stores receive versioned `snapshot`/`upsert`/`delete` push envelopes with
+    full issue payloads and expose deterministic, sorted snapshots for the
+    owning view.
+  - `subscriptions`: manages subscription lifecycle and keys. Rendering reads
+    from per‑subscription stores, not from membership ids.
+- Introduce a small selectors utility to apply view‑specific sort rules on store
+  snapshots (no composition from a central cache).
+- Remove read RPCs used for lists: `list-issues`, `epic-status`. Keep mutation
+  RPCs and `show-issue` until detail view also reads from push cache.
+- Tests drive views with push envelopes and `list-delta`; no RPC stubs for
+  reads.
+
+## API Shape (Client)
+
+Subscriptions store (already implemented):
+
+```js
+// app/data/subscriptions-store.js
+createSubscriptionStore(send) -> {
+  wireEvents(on), subscribeList(client_id, spec) -> unsubscribe,
+  selectors: { getIds(client_id), has(client_id), count(client_id) }
+}
+```
+
+Selectors utility (implemented):
+
+```js
+// app/data/list-selectors.js
+/** Compose from per‑subscription store snapshots and apply stable sort. */
+export function createListSelectors(issueStores) {
+  return {
+    selectIssuesFor(client_id) {},
+    selectBoardColumn(client_id, mode) {},
+    selectEpicChildren(epic_id) {},
+    subscribe(fn) {}
+  };
+}
+```
+
+Sorting rules:
+
+- Issues list: priority asc (0..4), then `created_at` desc, then id asc.
+- Board columns: preserve existing view rules (ready → priority asc, then
+  `updated_at` desc; in‑progress → `updated_at` desc; closed → `closed_at`
+  desc).
+- Epics children: same as Issues list unless view specifies otherwise.
+
+## Consequences
+
+Pros:
+
+- Consistent, snappy UI with minimal fetch logic; views are pure derives.
+- Server can batch and coalesce; client renders at most once per envelope.
+- Clear separation: mutations via RPC, reads via push caches.
+
+Cons / Risks:
+
+- Initial implementation work in views and tests.
+- Need disciplined subscription lifecycle on route/tab changes.
+- Requires follow‑up to migrate detail view fully to the push cache.
+
+## Migration Checklist
+
+Views
+
+- [x] Issues view renders from per‑subscription stores; no `list-issues`.
+- [x] Board renders from per‑subscription stores; no `get*` list reads.
+- [x] Epics list/children render from per‑subscription stores; children use
+      `issue-detail` for the epic id; children come from `dependents`.
+
+Client Data Layer
+
+- [x] Add `app/data/list-selectors.js` with helpers listed above (UI-156).
+- [x] Remove list read functions from `app/data/providers.js` (UI-159).
+- [ ] Keep `getIssue` and all mutation helpers until detail view push migration
+      happens (follow‑up).
+
+Tests
+
+- [x] Update list/board/epics tests to use per‑subscription push envelopes
+      (UI-158).
+- [x] Remove RPC read stubs from tests.
+
+Docs
+
+- [x] This ADR committed (UI-152).
+- [x] Update protocol and architecture docs for push‑only model (UI-160).
+
+## Notes
+
+- Client ids used in this repo today:
+  - `tab:issues` for the Issues view
+  - `tab:board:ready|in-progress|closed|blocked` for Board columns
+  - `tab:epics` for the Epics tab; `epic:${id}` for expanded children
+- See `app/main.js` for current subscription wiring, filter → spec mapping, and
+  per‑subscription push routing.