@growthbeaker/vscode-help-docs 0.1.0

package/src/webview/main.js

@@ -0,0 +1,312 @@
+// @ts-nocheck
+/* Webview-side script for the Help Viewer panel */
+
+(function () {
+  const vscode = acquireVsCodeApi();
+  let currentPath = null;
+  let mermaidReady = false;
+
+  /** Initialize the application */
+  function initialize() {
+    // Restore previous state
+    const state = vscode.getState();
+    if (state) {
+      currentPath = state.currentPath || null;
+    }
+
+    // Listen for messages from the extension host
+    window.addEventListener('message', handleMessage);
+
+    // Intercept link clicks in content area
+    const contentBody = document.getElementById('content-body');
+    if (contentBody) {
+      contentBody.addEventListener('click', handleLinkClick);
+    }
+
+    // Initialize mermaid if available
+    initMermaid();
+
+    // Signal ready to extension host
+    vscode.postMessage({ type: 'ready' });
+  }
+
+  /** Initialize mermaid.js if it's loaded */
+  function initMermaid() {
+    if (typeof window.mermaid === 'undefined') {
+      return;
+    }
+
+    // Detect dark/light theme from VS Code CSS variables
+    var isDark = getComputedStyle(document.body)
+      .getPropertyValue('--vscode-editor-background')
+      .trim()
+      .match(/^#([0-9a-f]{2})/i);
+    var theme = 'default';
+    if (isDark) {
+      // If the red channel of the background is below 0x80, it's a dark theme
+      var brightness = parseInt(isDark[1], 16);
+      theme = brightness < 128 ? 'dark' : 'default';
+    }
+
+    window.mermaid.initialize({
+      startOnLoad: false,
+      theme: theme,
+      securityLevel: 'strict',
+    });
+    mermaidReady = true;
+  }
+
+  /** Render any mermaid diagrams in the content pane */
+  function renderMermaidDiagrams() {
+    if (!mermaidReady) return;
+
+    var mermaidDivs = document.querySelectorAll('#content-body .mermaid');
+    if (mermaidDivs.length === 0) return;
+
+    // mermaid.run() finds and renders all .mermaid elements
+    try {
+      window.mermaid.run({ nodes: mermaidDivs });
+    } catch (e) {
+      console.warn('Mermaid rendering error:', e);
+    }
+  }
+
+  /** Handle messages from the extension host */
+  function handleMessage(event) {
+    const message = event.data;
+
+    switch (message.type) {
+      case 'contentLoaded':
+        handleContentLoaded(message);
+        break;
+
+      case 'navTree':
+        renderNavTree(message.tree);
+        break;
+
+      case 'error':
+        showErrorBanner(message.message);
+        break;
+
+      case 'anchorNotFound':
+        showNotification(
+          'Section \u0060' + message.anchor + '\u0060 not found on this page'
+        );
+        scrollToTop();
+        break;
+
+      case 'scrollToAnchor':
+        scrollToAnchor(message.anchor);
+        break;
+
+      case 'scrollToTop':
+        scrollToTop();
+        break;
+    }
+  }
+
+  /** Update the content pane with rendered HTML */
+  function handleContentLoaded(message) {
+    const contentBody = document.getElementById('content-body');
+    if (contentBody) {
+      contentBody.innerHTML = message.html;
+    }
+
+    currentPath = message.path;
+
+    // Update active nav item
+    updateActiveNavItem();
+
+    // Persist state
+    vscode.setState({ currentPath });
+
+    // Hide any previous error banner
+    hideErrorBanner();
+
+    // Scroll to top of content
+    scrollToTop();
+
+    // Render any mermaid diagrams
+    renderMermaidDiagrams();
+  }
+
+  /** Build and render the navigation tree sidebar */
+  function renderNavTree(tree) {
+    const sidebar = document.getElementById('nav-sidebar');
+    if (!sidebar) return;
+
+    sidebar.innerHTML = '';
+    const fragment = document.createDocumentFragment();
+
+    for (const node of tree) {
+      fragment.appendChild(createNavNode(node));
+    }
+
+    sidebar.appendChild(fragment);
+  }
+
+  /** Create a DOM element for a nav tree node */
+  function createNavNode(node) {
+    if (node.type === 'folder') {
+      const details = document.createElement('details');
+      details.className = 'nav-folder';
+      if (!node.collapsed) {
+        details.open = true;
+      }
+
+      const summary = document.createElement('summary');
+      summary.className = 'nav-folder-header';
+      summary.textContent = node.title;
+      details.appendChild(summary);
+
+      // Persist collapse state
+      details.addEventListener('toggle', function () {
+        vscode.setState({
+          ...vscode.getState(),
+          ['collapse_' + node.path]: !details.open,
+        });
+      });
+
+      // Restore collapse state
+      const state = vscode.getState();
+      if (state && state['collapse_' + node.path] !== undefined) {
+        details.open = !state['collapse_' + node.path];
+      }
+
+      if (node.children) {
+        for (const child of node.children) {
+          details.appendChild(createNavNode(child));
+        }
+      }
+
+      return details;
+    } else {
+      const link = document.createElement('a');
+      link.className = 'nav-item';
+      link.textContent = node.title;
+      link.href = '#';
+      link.dataset.path = node.path;
+
+      link.addEventListener('click', function (e) {
+        e.preventDefault();
+        vscode.postMessage({ type: 'navigateTo', path: node.path });
+      });
+
+      return link;
+    }
+  }
+
+  /** Intercept clicks on links within the content pane */
+  function handleLinkClick(event) {
+    const link = event.target.closest('a');
+    if (!link) return;
+
+    const href = link.getAttribute('href');
+    if (!href) return;
+
+    event.preventDefault();
+
+    // External links
+    if (href.startsWith('http://') || href.startsWith('https://')) {
+      vscode.postMessage({ type: 'openExternal', url: href });
+      return;
+    }
+
+    // Anchor-only links (#section-name)
+    if (href.startsWith('#')) {
+      const anchor = href.substring(1);
+      scrollToAnchor(anchor);
+      return;
+    }
+
+    // Internal links — may include anchor (page.md#section)
+    const hashIndex = href.indexOf('#');
+    if (hashIndex !== -1) {
+      const pagePath = href.substring(0, hashIndex);
+      const anchor = href.substring(hashIndex + 1);
+      vscode.postMessage({
+        type: 'navigateToAnchor',
+        path: pagePath || undefined,
+        anchor: anchor,
+      });
+    } else {
+      vscode.postMessage({ type: 'navigateTo', path: href });
+    }
+  }
+
+  /** Scroll to an anchor element by ID */
+  function scrollToAnchor(anchor) {
+    const element = document.getElementById(anchor);
+    if (element) {
+      element.scrollIntoView({ behavior: 'smooth' });
+    } else {
+      // AC 1.5.5: anchor not found — show notification and scroll to top
+      showNotification(
+        'Section \u0060' + anchor + '\u0060 not found on this page'
+      );
+      scrollToTop();
+    }
+  }
+
+  /** Scroll the content pane to the top */
+  function scrollToTop() {
+    const contentPane = document.getElementById('content-pane');
+    if (contentPane) {
+      contentPane.scrollTop = 0;
+    }
+  }
+
+  /** Show a non-blocking error banner (AC 1.5.4) */
+  function showErrorBanner(message) {
+    const banner = document.getElementById('error-banner');
+    if (!banner) return;
+
+    banner.textContent = message;
+    banner.style.display = 'block';
+
+    // Auto-dismiss after 5 seconds
+    setTimeout(function () {
+      hideErrorBanner();
+    }, 5000);
+  }
+
+  /** Hide the error banner */
+  function hideErrorBanner() {
+    const banner = document.getElementById('error-banner');
+    if (banner) {
+      banner.style.display = 'none';
+    }
+  }
+
+  /** Show a brief notification toast (AC 1.5.5) */
+  function showNotification(message) {
+    const toast = document.getElementById('notification-toast');
+    if (!toast) return;
+
+    toast.textContent = message;
+    toast.style.display = 'block';
+
+    setTimeout(function () {
+      toast.style.display = 'none';
+    }, 3000);
+  }
+
+  /** Update the active state on nav items */
+  function updateActiveNavItem() {
+    document.querySelectorAll('.nav-item.active').forEach(function (el) {
+      el.classList.remove('active');
+    });
+    document.querySelectorAll('.nav-item').forEach(function (el) {
+      if (el.dataset.path === currentPath) {
+        el.classList.add('active');
+      }
+    });
+  }
+
+  // Initialize when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initialize);
+  } else {
+    initialize();
+  }
+})();

package/src/webview/styles.css

@@ -0,0 +1,256 @@
+/* Help Viewer — VS Code theme-aware styles */
+
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  color: var(--vscode-foreground);
+  background: var(--vscode-editor-background);
+  font-family: var(--vscode-font-family);
+  font-size: var(--vscode-font-size);
+  line-height: 1.6;
+  height: 100vh;
+  overflow: hidden;
+}
+
+.help-viewer {
+  display: flex;
+  height: 100vh;
+}
+
+/* --- Navigation Sidebar --- */
+
+.nav-sidebar {
+  width: 220px;
+  min-width: 180px;
+  background: var(--vscode-sideBar-background);
+  border-right: 1px solid var(--vscode-panel-border);
+  overflow-y: auto;
+  padding: 8px 0;
+  flex-shrink: 0;
+}
+
+.nav-folder {
+  margin: 0;
+}
+
+.nav-folder-header {
+  display: block;
+  padding: 6px 16px;
+  cursor: pointer;
+  font-weight: 600;
+  font-size: 0.85em;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--vscode-sideBarSectionHeader-foreground, var(--vscode-foreground));
+  user-select: none;
+  list-style: none;
+}
+
+.nav-folder-header::-webkit-details-marker {
+  display: none;
+}
+
+.nav-folder-header::before {
+  content: '\25B6';
+  display: inline-block;
+  margin-right: 6px;
+  font-size: 0.7em;
+  transition: transform 0.15s ease;
+}
+
+details[open] > .nav-folder-header::before {
+  transform: rotate(90deg);
+}
+
+.nav-folder-header:hover {
+  background: var(--vscode-list-hoverBackground);
+}
+
+.nav-item {
+  display: block;
+  padding: 4px 16px 4px 32px;
+  color: var(--vscode-foreground);
+  text-decoration: none;
+  font-size: 0.9em;
+  cursor: pointer;
+  border-left: 2px solid transparent;
+}
+
+.nav-item:hover {
+  background: var(--vscode-list-hoverBackground);
+}
+
+.nav-item.active {
+  background: var(--vscode-list-activeSelectionBackground);
+  color: var(--vscode-list-activeSelectionForeground, var(--vscode-foreground));
+  border-left-color: var(--vscode-focusBorder);
+}
+
+/* --- Content Pane --- */
+
+.content-pane {
+  flex: 1;
+  overflow-y: auto;
+  padding: 24px 32px;
+  position: relative;
+}
+
+#content-body {
+  max-width: 780px;
+  margin: 0 auto;
+}
+
+/* --- Error Banner (AC 1.5.4) --- */
+
+.error-banner {
+  background: var(--vscode-inputValidation-errorBackground, #5a1d1d);
+  border: 1px solid var(--vscode-inputValidation-errorBorder, #be1100);
+  color: var(--vscode-errorForeground, var(--vscode-foreground));
+  padding: 8px 16px;
+  border-radius: 4px;
+  margin-bottom: 16px;
+  font-size: 0.9em;
+}
+
+/* --- Notification Toast (AC 1.5.5) --- */
+
+.notification-toast {
+  position: fixed;
+  bottom: 24px;
+  right: 24px;
+  background: var(--vscode-notifications-background, var(--vscode-editor-background));
+  border: 1px solid var(--vscode-notifications-border, var(--vscode-panel-border));
+  color: var(--vscode-notifications-foreground, var(--vscode-foreground));
+  padding: 10px 16px;
+  border-radius: 4px;
+  font-size: 0.85em;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+  z-index: 100;
+  max-width: 350px;
+}
+
+/* --- Typography --- */
+
+#content-body h1,
+#content-body h2,
+#content-body h3,
+#content-body h4,
+#content-body h5,
+#content-body h6 {
+  color: var(--vscode-foreground);
+  margin-top: 1.5em;
+  margin-bottom: 0.5em;
+  line-height: 1.3;
+}
+
+#content-body h1 { font-size: 1.8em; margin-top: 0; }
+#content-body h2 { font-size: 1.4em; border-bottom: 1px solid var(--vscode-panel-border); padding-bottom: 0.3em; }
+#content-body h3 { font-size: 1.15em; }
+
+#content-body p {
+  margin-bottom: 1em;
+}
+
+#content-body a {
+  color: var(--vscode-textLink-foreground);
+  text-decoration: none;
+}
+
+#content-body a:hover {
+  text-decoration: underline;
+  color: var(--vscode-textLink-activeForeground, var(--vscode-textLink-foreground));
+}
+
+#content-body code {
+  background: var(--vscode-textCodeBlock-background);
+  padding: 2px 5px;
+  border-radius: 3px;
+  font-family: var(--vscode-editor-font-family, monospace);
+  font-size: 0.9em;
+}
+
+#content-body pre {
+  background: var(--vscode-textCodeBlock-background);
+  padding: 16px;
+  border-radius: 4px;
+  overflow-x: auto;
+  margin-bottom: 1em;
+}
+
+#content-body pre code {
+  background: none;
+  padding: 0;
+}
+
+#content-body ul,
+#content-body ol {
+  margin-bottom: 1em;
+  padding-left: 2em;
+}
+
+#content-body li {
+  margin-bottom: 0.25em;
+}
+
+#content-body blockquote {
+  border-left: 3px solid var(--vscode-textBlockQuote-border, var(--vscode-panel-border));
+  margin: 0 0 1em 0;
+  padding: 8px 16px;
+  color: var(--vscode-textBlockQuote-foreground, var(--vscode-foreground));
+  background: var(--vscode-textBlockQuote-background, transparent);
+}
+
+#content-body hr {
+  border: none;
+  border-top: 1px solid var(--vscode-panel-border);
+  margin: 1.5em 0;
+}
+
+#content-body table {
+  border-collapse: collapse;
+  margin-bottom: 1em;
+  width: 100%;
+}
+
+#content-body th,
+#content-body td {
+  border: 1px solid var(--vscode-panel-border);
+  padding: 8px 12px;
+  text-align: left;
+}
+
+#content-body th {
+  background: var(--vscode-editorGroupHeader-tabsBackground, var(--vscode-sideBar-background));
+  font-weight: 600;
+}
+
+#content-body img {
+  max-width: 100%;
+  height: auto;
+}
+
+/* --- Responsive --- */
+
+@media (max-width: 500px) {
+  .nav-sidebar {
+    position: fixed;
+    left: -100%;
+    top: 0;
+    height: 100vh;
+    z-index: 50;
+    transition: left 0.2s ease;
+    width: 260px;
+  }
+
+  .nav-sidebar.open {
+    left: 0;
+  }
+
+  .content-pane {
+    padding: 16px;
+  }
+}