beads-ui 0.3.1 → 0.4.1

package/app/protocol.md

@@ -1,66 +0,0 @@
-# beads-ui WebSocket Protocol (v2.0.0)
-
-Note (2025-10-26)
-
-- The server no longer implements legacy read RPCs `list-issues` and
-  `epic-status`. Clients must use the push-only protocol described in
-  `docs/protocol/issues-push-v2.md` (subscribe-list with per-subscription events
-  snapshot/upsert/delete). The shapes below are retained for historical
-  reference of v1.
-
-This document defines the JSON messages exchanged between the browser client and
-the local server.
-
-- Transport: single WebSocket connection
-- Encoding: JSON text frames
-- Correlation: all request/response pairs share the same `id`
-
-## Envelope Shapes
-
-- RequestEnvelope: `{ id: string, type: string, payload?: any }`
-- ReplyEnvelope:
-  `{ id: string, ok: boolean, type: string, payload?: any, error?: { code: string, message: string, details?: any } }`
-
-Server may send unsolicited events (e.g., subscription
-`snapshot`/`upsert`/`delete`) using the ReplyEnvelope shape with `ok: true` and
-a generated `id`.
-
-## Message Types
-
-- Removed in v2: `list-issues` (use subscriptions + push stores)
-- `update-status` payload:
-  `{ id: string, status: 'open'|'in_progress'|'closed' }`
-- `edit-text` payload:
-  `{ id: string, field: 'title'|'description'|'acceptance'|'notes'|'design', value: string }`
-- `update-priority` payload: `{ id: string, priority: 0|1|2|3|4 }`
-- `create-issue` payload:
-  `{ title: string, type?: 'bug'|'feature'|'task'|'epic'|'chore', priority?: 0|1|2|3|4, description?: string }`
-- `list-ready` payload: `{}`
-- Removed in v2: `subscribe-updates` and the `issues-changed` event. All list
-  and detail updates flow via per-subscription push envelopes
-  (`snapshot`/`upsert`/`delete`).
-- `dep-add` payload: `{ a: string, b: string, view_id?: string }` where `a`
-  depends on `b` (i.e., `a` is blocked by `b`). Reply payload is the updated
-  issue for `view_id` (or `a` when omitted).
-- `dep-remove` payload: `{ a: string, b: string, view_id?: string }` removing
-  the `a` depends on `b` link. Reply payload is the updated issue for `view_id`
-  (or `a`).
-
-## Mapping to `bd` CLI
-
-- Removed in v2: `list-issues` → use subscriptions and push
-  (`docs/protocol/issues-push-v2.md`)
-- `update-status` → `bd update <id> --status <status>`
-- `edit-text` → `bd update <id> --title <t>` or `--description <d>` or
-  `--acceptance-criteria <a>` or `--notes <n>` or `--design <z>`
-- `update-priority` → `bd update <id> --priority <n>`
-- `create-issue` → `bd create "title" -t <type> -p <prio> -d "desc"`
-- `list-ready` → `bd ready --json`
-
-## Errors
-
-Errors follow the shape `{ code, message, details? }`. Common codes:
-
-- `bad_request` – malformed payload or unknown type
-- `not_found` – entity not found (e.g., issue id)
-- `bd_error` – underlying `bd` command failed

package/app/router.js

@@ -1,117 +0,0 @@
-import { issueHashFor } from './utils/issue-url.js';
-
-/**
- * Hash-based router for tabs (issues/epics/board) and deep-linked issue ids.
- */
-
-/**
- * Parse an application hash and extract the selected issue id.
- * Supports canonical form "#/(issues|epics|board)?issue=<id>" and legacy
- * "#/issue/<id>" which we will rewrite to the canonical form.
- *
- * @param {string} hash
- * @returns {string | null}
- */
-export function parseHash(hash) {
-  const h = String(hash || '');
-  // Extract the fragment sans leading '#'
-  const frag = h.startsWith('#') ? h.slice(1) : h;
-  const qIndex = frag.indexOf('?');
-  const query = qIndex >= 0 ? frag.slice(qIndex + 1) : '';
-  if (query) {
-    const params = new URLSearchParams(query);
-    const id = params.get('issue');
-    if (id) {
-      return decodeURIComponent(id);
-    }
-  }
-  // Legacy pattern: #/issue/<id>
-  const m = /^\/issue\/([^\s?#]+)/.exec(frag);
-  return m && m[1] ? decodeURIComponent(m[1]) : null;
-}
-
-/**
- * Parse the current view from hash.
- *
- * @param {string} hash
- * @returns {'issues'|'epics'|'board'}
- */
-export function parseView(hash) {
-  const h = String(hash || '');
-  if (/^#\/epics(\b|\/|$)/.test(h)) {
-    return 'epics';
-  }
-  if (/^#\/board(\b|\/|$)/.test(h)) {
-    return 'board';
-  }
-  // Default to issues (also covers #/issues and unknown/empty)
-  return 'issues';
-}
-
-/**
- * @param {{ getState: () => any, setState: (patch: any) => void }} store
- */
-export function createHashRouter(store) {
-  /** @type {(ev?: HashChangeEvent) => any} */
-  const onHashChange = () => {
-    const hash = window.location.hash || '';
-    // Rewrite legacy #/issue/<id> to canonical #/issues?issue=<id>
-    const legacyMatch = /^#\/issue\/([^\s?#]+)/.exec(hash);
-    if (legacyMatch && legacyMatch[1]) {
-      const id = decodeURIComponent(legacyMatch[1]);
-      // Update state immediately for consumers expecting sync selection
-      store.setState({ selected_id: id, view: 'issues' });
-      const next = `#/issues?issue=${encodeURIComponent(id)}`;
-      if (window.location.hash !== next) {
-        window.location.hash = next;
-        return; // will trigger handler again
-      }
-    }
-    const id = parseHash(hash);
-    const view = parseView(hash);
-    store.setState({ selected_id: id, view });
-  };
-
-  return {
-    start() {
-      window.addEventListener('hashchange', onHashChange);
-      onHashChange();
-    },
-    stop() {
-      window.removeEventListener('hashchange', onHashChange);
-    },
-    /**
-     * @param {string} id
-     */
-    gotoIssue(id) {
-      // Keep current view in hash and append issue param via helper
-      const s = store.getState ? store.getState() : { view: 'issues' };
-      const view = s.view || 'issues';
-      const next = issueHashFor(view, id);
-      if (window.location.hash !== next) {
-        window.location.hash = next;
-      } else {
-        // Force state update even if hash is the same
-        store.setState({ selected_id: id, view });
-      }
-    },
-    /**
-     * Navigate to a top-level view.
-     *
-     * @param {'issues'|'epics'|'board'} view
-     */
-    /**
-     * @param {'issues'|'epics'|'board'} view
-     */
-    gotoView(view) {
-      const s = store.getState ? store.getState() : { selected_id: null };
-      const id = s.selected_id;
-      const next = id ? issueHashFor(view, id) : `#/${view}`;
-      if (window.location.hash !== next) {
-        window.location.hash = next;
-      } else {
-        store.setState({ view, selected_id: null });
-      }
-    }
-  };
-}

package/app/state.js

@@ -1,105 +0,0 @@
-/**
- * Minimal app state store with subscription.
- */
-
-/**
- * @typedef {'all'|'open'|'in_progress'|'closed'|'ready'} StatusFilter
- */
-
-/**
- * @typedef {{ status: StatusFilter, search: string, type: string }} Filters
- */
-
-/**
- * @typedef {'issues'|'epics'|'board'} ViewName
- */
-
-/**
- * @typedef {'today'|'3'|'7'} ClosedFilter
- */
-
-/**
- * @typedef {{ closed_filter: ClosedFilter }} BoardState
- */
-
-/**
- * @typedef {{ selected_id: string | null, view: ViewName, filters: Filters, board: BoardState }} AppState
- */
-
-/**
- * Create a simple store for application state.
- *
- * @param {Partial<AppState>} [initial]
- * @returns {{ getState: () => AppState, setState: (patch: { selected_id?: string | null, filters?: Partial<Filters> }) => void, subscribe: (fn: (s: AppState) => void) => () => void }}
- */
-export function createStore(initial = {}) {
-  /** @type {AppState} */
-  let state = {
-    selected_id: initial.selected_id ?? null,
-    view: initial.view ?? 'issues',
-    filters: {
-      status: initial.filters?.status ?? 'all',
-      search: initial.filters?.search ?? '',
-      type:
-        typeof initial.filters?.type === 'string' ? initial.filters?.type : ''
-    },
-    board: {
-      closed_filter:
-        initial.board?.closed_filter === '3' ||
-        initial.board?.closed_filter === '7' ||
-        initial.board?.closed_filter === 'today'
-          ? initial.board?.closed_filter
-          : 'today'
-    }
-  };
-
-  /** @type {Set<(s: AppState) => void>} */
-  const subs = new Set();
-
-  function emit() {
-    for (const fn of Array.from(subs)) {
-      try {
-        fn(state);
-      } catch {
-        // ignore
-      }
-    }
-  }
-
-  return {
-    getState() {
-      return state;
-    },
-    /**
-     * Update state. Nested filters can be partial.
-     *
-     * @param {{ selected_id?: string | null, filters?: Partial<Filters>, board?: Partial<BoardState> }} patch
-     */
-    setState(patch) {
-      /** @type {AppState} */
-      const next = {
-        ...state,
-        ...patch,
-        filters: { ...state.filters, ...(patch.filters || {}) },
-        board: { ...state.board, ...(patch.board || {}) }
-      };
-      // Avoid emitting if nothing changed (shallow compare)
-      if (
-        next.selected_id === state.selected_id &&
-        next.view === state.view &&
-        next.filters.status === state.filters.status &&
-        next.filters.search === state.filters.search &&
-        next.filters.type === state.filters.type &&
-        next.board.closed_filter === state.board.closed_filter
-      ) {
-        return;
-      }
-      state = next;
-      emit();
-    },
-    subscribe(fn) {
-      subs.add(fn);
-      return () => subs.delete(fn);
-    }
-  };
-}

package/app/utils/issue-id-renderer.js

@@ -1,72 +0,0 @@
-import { issueDisplayId } from './issue-id.js';
-
-/**
- * Create a reusable, copy-to-clipboard issue ID renderer.
- * Looks like the current inline ID (monospace `#123`) but acts as a button
- * that copies the full, prefixed ID (e.g., `UI-123`) when activated.
- * Shows transient "Copied" feedback and then restores the ID.
- *
- * @param {string} id - Full issue id including the prefix (e.g., "UI-123").
- * @param {{ class_name?: string, duration_ms?: number }} [opts]
- * @returns {HTMLButtonElement}
- */
-export function createIssueIdRenderer(id, opts) {
-  /** @type {number} */
-  const duration =
-    typeof opts?.duration_ms === 'number' ? opts.duration_ms : 1200;
-  /** @type {HTMLButtonElement} */
-  const btn = document.createElement('button');
-  // Visual: match inline ID look; keep it neutral and text-like
-  btn.className =
-    (opts?.class_name ? opts.class_name + ' ' : '') + 'mono id-copy';
-  btn.type = 'button';
-  btn.setAttribute('aria-live', 'polite');
-  btn.setAttribute('title', 'Copy issue ID');
-  btn.setAttribute('aria-label', `Copy issue ID ${id}`);
-  const label = issueDisplayId(id);
-  btn.textContent = label;
-
-  /** Copy handler with feedback. */
-  async function doCopy() {
-    // Prevent accidental row navigation and parent handlers
-    // (click/key handlers call this inside an event context)
-    try {
-      if (
-        navigator.clipboard &&
-        typeof navigator.clipboard.writeText === 'function'
-      ) {
-        await navigator.clipboard.writeText(String(id));
-      }
-      const prev = btn.textContent || label;
-      btn.textContent = 'Copied';
-      // Keep accessible label consistent with feedback
-      const oldAria = btn.getAttribute('aria-label') || '';
-      btn.setAttribute('aria-label', 'Copied');
-      setTimeout(
-        () => {
-          btn.textContent = prev;
-          btn.setAttribute('aria-label', oldAria);
-        },
-        Math.max(80, duration)
-      );
-    } catch {
-      // On failure, leave text as-is; no throw to avoid disruptive UX
-    }
-  }
-
-  btn.addEventListener('click', (ev) => {
-    ev.preventDefault();
-    ev.stopPropagation();
-    void doCopy();
-  });
-  btn.addEventListener('keydown', (ev) => {
-    // Ensure keyboard activation works even in non-interactive test envs
-    if (ev.key === 'Enter' || ev.key === ' ') {
-      ev.preventDefault();
-      ev.stopPropagation();
-      void doCopy();
-    }
-  });
-
-  return btn;
-}

package/app/utils/issue-id.js

@@ -1,11 +0,0 @@
-/**
- * Format a beads issue id as a user-facing display string `#${n}`.
- * Extracts the trailing numeric portion of the id and prefixes with '#'.
- *
- * @param {string | null | undefined} id
- * @returns {string}
- */
-export function issueDisplayId(id) {
-  const m = String(id || '').match(/(\d+)$/);
-  return m ? `#${m[1]}` : '#';
-}

package/app/utils/issue-type.js

@@ -1,29 +0,0 @@
-/**
- * Known issue types in canonical order for dropdowns.
- *
- * @type {Array<'bug'|'feature'|'task'|'epic'|'chore'>}
- */
-export const ISSUE_TYPES = ['bug', 'feature', 'task', 'epic', 'chore'];
-
-/**
- * Return a human-friendly label for an issue type.
- *
- * @param {string | null | undefined} type
- * @returns {string}
- */
-export function typeLabel(type) {
-  switch ((type || '').toString().toLowerCase()) {
-    case 'bug':
-      return 'Bug';
-    case 'feature':
-      return 'Feature';
-    case 'task':
-      return 'Task';
-    case 'epic':
-      return 'Epic';
-    case 'chore':
-      return 'Chore';
-    default:
-      return '';
-  }
-}

package/app/utils/issue-url.js

@@ -1,10 +0,0 @@
-/**
- * Build a canonical issue hash that retains the view.
- *
- * @param {'issues'|'epics'|'board'} view
- * @param {string} id
- */
-export function issueHashFor(view, id) {
-  const v = view === 'epics' || view === 'board' ? view : 'issues';
-  return `#/${v}?issue=${encodeURIComponent(id)}`;
-}

package/app/utils/markdown.js

@@ -1,16 +0,0 @@
-import DOMPurify from 'dompurify';
-import { unsafeHTML } from 'lit-html/directives/unsafe-html.js';
-import { marked } from 'marked';
-
-/**
- * Render Markdown safely as HTML using marked and DOMPurify.
- * Returns a lit-html TemplateResult via the unsafeHTML directive so it can be
- * embedded directly in templates.
- *
- * @param {string} markdown - Markdown source text
- */
-export function renderMarkdown(markdown) {
-  const parsed = /** @type {string} */ (marked.parse(markdown));
-  const html_string = DOMPurify.sanitize(parsed);
-  return unsafeHTML(html_string);
-}

package/app/utils/priority-badge.js

@@ -1,48 +0,0 @@
-import { priority_levels } from './priority.js';
-
-/**
- * Create a colored badge for a priority value (0..4).
- *
- * @param {number | null | undefined} priority
- * @returns {HTMLSpanElement}
- */
-export function createPriorityBadge(priority) {
-  const p = typeof priority === 'number' ? priority : 2;
-  const el = document.createElement('span');
-  el.className = 'priority-badge';
-  el.classList.add(`is-p${Math.max(0, Math.min(4, p))}`);
-  el.setAttribute('role', 'img');
-  const label = labelForPriority(p);
-  el.setAttribute('title', label);
-  el.setAttribute('aria-label', `Priority: ${label}`);
-  el.textContent = emojiForPriority(p) + ' ' + label;
-  return el;
-}
-
-/**
- * @param {number} p
- */
-function labelForPriority(p) {
-  const i = Math.max(0, Math.min(4, p));
-  return priority_levels[i] || 'Medium';
-}
-
-/**
- * @param {number} p
- */
-export function emojiForPriority(p) {
-  switch (p) {
-    case 0:
-      return '🔥';
-    case 1:
-      return '⚡️';
-    case 2:
-      return '🔧';
-    case 3:
-      return '🪶';
-    case 4:
-      return '💤';
-    default:
-      return '🔧';
-  }
-}

package/app/utils/priority.js

@@ -1 +0,0 @@
-export const priority_levels = ['Critical', 'High', 'Medium', 'Low', 'Backlog'];

package/app/utils/status-badge.js

@@ -1,33 +0,0 @@
-/**
- * Create a colored badge for a status value.
- *
- * @param {string | null | undefined} status - 'open' | 'in_progress' | 'closed'
- * @returns {HTMLSpanElement}
- */
-export function createStatusBadge(status) {
-  const el = document.createElement('span');
-  el.className = 'status-badge';
-  const s = String(status || 'open');
-  el.classList.add(`is-${s}`);
-  el.setAttribute('role', 'img');
-  el.setAttribute('title', labelForStatus(s));
-  el.setAttribute('aria-label', `Status: ${labelForStatus(s)}`);
-  el.textContent = labelForStatus(s);
-  return el;
-}
-
-/**
- * @param {string} s
- */
-function labelForStatus(s) {
-  switch (s) {
-    case 'open':
-      return 'Open';
-    case 'in_progress':
-      return 'In progress';
-    case 'closed':
-      return 'Closed';
-    default:
-      return 'Unknown';
-  }
-}

package/app/utils/status.js

@@ -1,25 +0,0 @@
-/**
- * Known status values in canonical order.
- *
- * @type {Array<'open'|'in_progress'|'closed'>}
- */
-export const STATUSES = ['open', 'in_progress', 'closed'];
-
-/**
- * Map canonical status to display label.
- *
- * @param {string | null | undefined} status
- * @returns {string}
- */
-export function statusLabel(status) {
-  switch ((status || '').toString()) {
-    case 'open':
-      return 'Open';
-    case 'in_progress':
-      return 'In progress';
-    case 'closed':
-      return 'Closed';
-    default:
-      return (status || '').toString() || 'Open';
-  }
-}

package/app/utils/toast.js

@@ -1,35 +0,0 @@
-/**
- * Show a transient global toast message anchored to the viewport.
- *
- * @param {string} text - Message text.
- * @param {'info'|'success'|'error'} [variant] - Visual variant.
- * @param {number} [duration_ms] - Auto-dismiss delay in milliseconds.
- */
-export function showToast(text, variant = 'info', duration_ms = 2800) {
-  const el = document.createElement('div');
-  el.className = 'toast';
-  el.textContent = text;
-  el.style.position = 'fixed';
-  el.style.right = '12px';
-  el.style.bottom = '12px';
-  el.style.zIndex = '1000';
-  el.style.color = '#fff';
-  el.style.padding = '8px 10px';
-  el.style.borderRadius = '4px';
-  el.style.fontSize = '12px';
-  if (variant === 'success') {
-    el.style.background = '#156d36';
-  } else if (variant === 'error') {
-    el.style.background = '#9f2011';
-  } else {
-    el.style.background = 'rgba(0,0,0,0.85)';
-  }
-  (document.body || document.documentElement).appendChild(el);
-  setTimeout(() => {
-    try {
-      el.remove();
-    } catch {
-      /* ignore */
-    }
-  }, duration_ms);
-}

package/app/utils/type-badge.js

@@ -1,34 +0,0 @@
-/**
- * Create a compact, colored badge for an issue type.
- *
- * @param {string | undefined | null} issue_type - One of: bug, feature, task, epic, chore
- * @returns {HTMLSpanElement}
- */
-export function createTypeBadge(issue_type) {
-  const el = document.createElement('span');
-  el.className = 'type-badge';
-
-  const t = (issue_type || '').toString().toLowerCase();
-  const KNOWN = new Set(['bug', 'feature', 'task', 'epic', 'chore']);
-  const kind = KNOWN.has(t) ? t : 'neutral';
-  el.classList.add(`type-badge--${kind}`);
-  el.setAttribute('role', 'img');
-  const label = KNOWN.has(t)
-    ? t === 'bug'
-      ? 'Bug'
-      : t === 'feature'
-        ? 'Feature'
-        : t === 'task'
-          ? 'Task'
-          : t === 'epic'
-            ? 'Epic'
-            : 'Chore'
-    : '—';
-  el.setAttribute(
-    'aria-label',
-    KNOWN.has(t) ? `Issue type: ${label}` : 'Issue type: unknown'
-  );
-  el.setAttribute('title', KNOWN.has(t) ? `Type: ${label}` : 'Type: unknown');
-  el.textContent = label;
-  return el;
-}