add toc, markdown jump, default docs

2026-03-31 18:54:57 -07:00
parent c1ee0b9acd
commit 10f8eee25c
5 changed files with 320 additions and 21 deletions
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -1970,6 +1970,24 @@ function Flow() {
    setHelpTabs((prev) => prev.map((t) => t.label === label ? { ...t, content } : t));
  }, []);

+  const openDocByFilename = useCallback(async (filename) => {
+    const title = filename.replace(/\.md$/i, '').replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    // If already open, just switch to it
+    setHelpTabs((prev) => {
+      if (prev.find((t) => t.label === title)) return prev;
+      return [...prev, { label: title, content: null }];
+    });
+    setActiveHelpTab(title);
+    try {
+      const r = await fetch(`/help-docs/${encodeURIComponent(filename)}`);
+      if (!r.ok) throw new Error('Not found');
+      const doc = await r.json();
+      setHelpTabs((prev) => prev.map((t) => t.label === title ? { ...t, content: doc.content } : t));
+    } catch {
+      setHelpTabs((prev) => prev.map((t) => t.label === title ? { ...t, content: `*Could not load ${filename}.*` } : t));
+    }
+  }, []);
+
  const contextValue = useMemo(() => ({
    onWidgetChange,
    onRuntimeValuesChange,
@@ -1996,9 +2014,18 @@ function Flow() {
    setEdges(hydrated.edges);
    nextIdRef.current = hydrated.nextNodeId;
    journalContentRef.current = data.journalContent || '';
-    setHelpTabs((prev) => prev.map((t) =>
-      t.label === 'Journal' ? { ...t, content: journalContentRef.current } : t,
-    ));
+    if (journalContentRef.current) {
+      setHelpTabs((prev) => {
+        const existing = prev.find((t) => t.label === 'Journal');
+        if (existing) return prev.map((t) => t.label === 'Journal' ? { ...t, content: journalContentRef.current } : t);
+        return [...prev, { label: 'Journal', type: 'journal', content: journalContentRef.current }];
+      });
+      setActiveHelpTab('Journal');
+    } else {
+      setHelpTabs((prev) => prev.map((t) =>
+        t.label === 'Journal' ? { ...t, content: '' } : t,
+      ));
+    }
    initializeDynamicNodes(hydrated.nodes);
  }, [initializeDynamicNodes, setNodes, setEdges]);

@@ -2038,6 +2065,20 @@ function Flow() {
    }).catch((err) => {
      setStatus({ text: 'Failed to load nodes: ' + err.message, level: 'error' });
    });
+
+    // Load any .md files from frontend/public/ as help tabs
+    fetch('/help-docs')
+      .then((r) => r.ok ? r.json() : [])
+      .then((docs) => {
+        if (!docs.length) return;
+        setHelpTabs((prev) => {
+          const existing = new Set(prev.map((t) => t.label));
+          const newTabs = docs.filter((d) => !existing.has(d.title)).map((d) => ({ label: d.title, content: d.content }));
+          return newTabs.length ? [...prev, ...newTabs] : prev;
+        });
+        setActiveHelpTab((cur) => cur || docs[0].title);
+      })
+      .catch(() => {});
  }, [loadDefaultWorkflow]);

  const stampLogoOnBlob = useCallback(async (blob) => {
@@ -2055,8 +2096,8 @@ function Flow() {
    ctx.drawImage(img, 0, 0);

    const margin = 16;
-    const size = Math.min(128, Math.floor(img.naturalWidth / 6), Math.floor(img.naturalHeight / 6));
-    if (size >= 16) {
+    const size = 64;
+    if (img.naturalWidth >= size + margin * 2 && img.naturalHeight >= size + margin * 2) {
      const logoX = img.naturalWidth - size - margin;
      const logoY = img.naturalHeight - size - margin;
      const fontSize = Math.max(11, Math.round(size * 0.18));
@@ -3011,6 +3052,7 @@ function Flow() {
        onTabClose={closeHelpTab}
        onTabContentChange={updateTabContent}
        onOpenJournal={openJournalTab}
+        onOpenDoc={openDocByFilename}
      />
    </NodeContext.Provider>
  );
--- a/frontend/src/HelpPanelManager.jsx
+++ b/frontend/src/HelpPanelManager.jsx
@@ -1,13 +1,165 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import ReactDOM from 'react-dom';
 import { marked } from 'marked';

-function JournalTab({ content, onChange }) {
+// ── Parse headings from markdown source ──────────────────────────────
+
+function parseHeadings(md) {
+  if (!md) return [];
+  const headings = [];
+  const lines = md.split('\n');
+  for (const line of lines) {
+    const m = line.match(/^(#{1,6})\s+(.+)/);
+    if (m) {
+      const text = m[2].replace(/[*_`~\[\]]/g, '').trim();
+      const id = text.toLowerCase().replace(/[^\w]+/g, '-').replace(/(^-|-$)/g, '');
+      headings.push({ level: m[1].length, text, id });
+    }
+  }
+  return headings;
+}
+
+// ── Inject id attributes into rendered HTML headings ─────────────────
+
+function injectHeadingIds(html, headings) {
+  let idx = 0;
+  return html.replace(/<(h[1-6])>/gi, (match, tag) => {
+    if (idx < headings.length) {
+      return `<${tag} id="${headings[idx++].id}">`;
+    }
+    return match;
+  });
+}
+
+// ── Build a tree from flat heading list ──────────────────────────────
+
+function buildTocTree(headings) {
+  const root = { children: [] };
+  const stack = [{ node: root, level: 0 }];
+  for (const h of headings) {
+    const item = { ...h, children: [] };
+    while (stack.length > 1 && stack[stack.length - 1].level >= h.level) stack.pop();
+    stack[stack.length - 1].node.children.push(item);
+    stack.push({ node: item, level: h.level });
+  }
+  return root.children;
+}
+
+// ── TOC sidebar component ────────────────────────────────────────────
+
+function TocItem({ item, collapsed, onToggle, onNavigate }) {
+  const hasChildren = item.children.length > 0;
+  const isCollapsed = collapsed[item.id];
+  return (
+    <li className="help-toc-item">
+      <div className="help-toc-row">
+        {hasChildren ? (
+          <button
+            className="help-toc-arrow"
+            onClick={(e) => { e.stopPropagation(); onToggle(item.id); }}
+          >
+            {isCollapsed ? '▶' : '▼'}
+          </button>
+        ) : (
+          <span className="help-toc-arrow-spacer" />
+        )}
+        <a
+          className="help-toc-link"
+          href={`#${item.id}`}
+          onClick={(e) => { e.preventDefault(); onNavigate(item.id); }}
+        >
+          {item.text}
+        </a>
+      </div>
+      {hasChildren && !isCollapsed && (
+        <ul className="help-toc-list">
+          {item.children.map((child) => (
+            <TocItem key={child.id} item={child} collapsed={collapsed} onToggle={onToggle} onNavigate={onNavigate} />
+          ))}
+        </ul>
+      )}
+    </li>
+  );
+}
+
+function Toc({ headings, contentRef }) {
+  const [collapsed, setCollapsed] = useState({});
+  const tree = useMemo(() => buildTocTree(headings), [headings]);
+
+  const onToggle = (id) => setCollapsed((prev) => ({ ...prev, [id]: !prev[id] }));
+
+  const onNavigate = (id) => {
+    const el = contentRef.current?.querySelector(`#${CSS.escape(id)}`);
+    if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+  };
+
+  if (tree.length === 0) return null;
+
+  return (
+    <nav className="help-toc nowheel">
+      <ul className="help-toc-list help-toc-root">
+        {tree.map((item) => (
+          <TocItem key={item.id} item={item} collapsed={collapsed} onToggle={onToggle} onNavigate={onNavigate} />
+        ))}
+      </ul>
+    </nav>
+  );
+}
+
+// ── Click handler for .md links ──────────────────────────────────────
+
+function useMdLinkHandler(onOpenDoc) {
+  return (e) => {
+    const a = e.target.closest('a[href]');
+    if (!a) return;
+    const href = a.getAttribute('href');
+    if (href && /\.md$/i.test(href) && !href.startsWith('http')) {
+      e.preventDefault();
+      const filename = href.split('/').pop();
+      onOpenDoc(filename);
+    }
+  };
+}
+
+// ── Content pane with TOC ────────────────────────────────────────────
+
+function HelpContent({ content, onOpenDoc }) {
+  const contentRef = useRef(null);
+  const handleClick = useMdLinkHandler(onOpenDoc);
+  const md = content || '*Loading…*';
+  const headings = useMemo(() => parseHeadings(md), [md]);
+  const html = useMemo(() => {
+    let rendered;
+    try { rendered = marked.parse(md); } catch { rendered = md; }
+    return injectHeadingIds(rendered, headings);
+  }, [md, headings]);
+
+  return (
+    <div className="help-content-row">
+      <Toc headings={headings} contentRef={contentRef} />
+      <div
+        ref={contentRef}
+        className="node-help-panel-body nowheel"
+        onClick={handleClick}
+        // eslint-disable-next-line react/no-danger
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    </div>
+  );
+}
+
+// ── Journal tab ──────────────────────────────────────────────────────
+
+function JournalTab({ content, onChange, onOpenDoc }) {
  const [isEditing, setIsEditing] = useState(false);
+  const contentRef = useRef(null);
+  const handleClick = useMdLinkHandler(onOpenDoc);

  let renderedHtml = '';
+  let headings = [];
  if (!isEditing && content?.trim()) {
-    try { renderedHtml = marked.parse(content); } catch { /* fallback to raw */ renderedHtml = content; }
+    headings = parseHeadings(content);
+    try { renderedHtml = injectHeadingIds(marked.parse(content), headings); } catch { renderedHtml = content; }
  }

  return (
@@ -39,12 +191,17 @@ function JournalTab({ content, onChange }) {
          autoFocus
        />
      ) : renderedHtml ? (
-        <div
-          className="node-help-panel-body node-help-journal-preview nowheel"
-          onDoubleClick={() => setIsEditing(true)}
-          // eslint-disable-next-line react/no-danger
-          dangerouslySetInnerHTML={{ __html: renderedHtml }}
-        />
+        <div className="help-content-row">
+          <Toc headings={headings} contentRef={contentRef} />
+          <div
+            ref={contentRef}
+            className="node-help-panel-body node-help-journal-preview nowheel"
+            onDoubleClick={() => setIsEditing(true)}
+            onClick={handleClick}
+            // eslint-disable-next-line react/no-danger
+            dangerouslySetInnerHTML={{ __html: renderedHtml }}
+          />
+        </div>
      ) : (
        <div
          className="node-help-panel-body node-help-journal-preview nowheel"
@@ -57,7 +214,9 @@ function JournalTab({ content, onChange }) {
  );
 }

-function HelpPanelManager({ tabs, activeTab, onTabSelect, onTabClose, onTabContentChange, onOpenJournal }) {
+// ── Main panel manager ───────────────────────────────────────────────
+
+function HelpPanelManager({ tabs, activeTab, onTabSelect, onTabClose, onTabContentChange, onOpenJournal, onOpenDoc }) {
  const [collapsed, setCollapsed] = useState(false);

  useEffect(() => {
@@ -116,13 +275,10 @@ function HelpPanelManager({ tabs, activeTab, onTabSelect, onTabClose, onTabConte
          <JournalTab
            content={active.content}
            onChange={(val) => onTabContentChange(active.label, val)}
+            onOpenDoc={onOpenDoc}
          />
        ) : (
-          <div
-            className="node-help-panel-body nowheel"
-            // eslint-disable-next-line react/no-danger
-            dangerouslySetInnerHTML={{ __html: marked.parse(active.content || '*Loading…*') }}
-          />
+          <HelpContent content={active.content} onOpenDoc={onOpenDoc} />
        )
      )}
    </div>,
--- a/frontend/src/styles.css
+++ b/frontend/src/styles.css
@@ -566,7 +566,7 @@ html, body, #root {
  position: fixed;
  top: 60px;
  right: 20px;
-  width: 420px;
+  width: 620px;
  max-height: calc(100vh - 80px);
  background: #1e293b;
  border: 1px solid #334155;
@@ -700,6 +700,82 @@ html, body, #root {

 .node-help-panel-body strong { color: #e2e8f0; }

+/* ── Help panel TOC + content layout ──────────────────────────────── */
+
+.help-content-row {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.help-content-row > .node-help-panel-body {
+  flex: 1;
+  min-width: 0;
+}
+
+.help-toc {
+  width: 160px;
+  flex-shrink: 0;
+  overflow-y: auto;
+  border-right: 1px solid #1e293b;
+  padding: 8px 0;
+  font-size: 11px;
+  background: #0f172a;
+}
+
+.help-toc-root { padding: 0; }
+
+.help-toc-list {
+  list-style: none;
+  margin: 0;
+  padding: 0 0 0 10px;
+}
+
+.help-toc-item {
+  margin: 0;
+}
+
+.help-toc-row {
+  display: flex;
+  align-items: baseline;
+  gap: 2px;
+}
+
+.help-toc-arrow {
+  background: none;
+  border: none;
+  color: #475569;
+  font-size: 7px;
+  padding: 0;
+  width: 12px;
+  flex-shrink: 0;
+  cursor: pointer;
+  text-align: center;
+  line-height: 1;
+  transition: color 0.12s;
+}
+.help-toc-arrow:hover { color: #94a3b8; }
+
+.help-toc-arrow-spacer {
+  display: inline-block;
+  width: 12px;
+  flex-shrink: 0;
+}
+
+.help-toc-link {
+  color: #94a3b8;
+  text-decoration: none;
+  padding: 2px 6px 2px 0;
+  display: block;
+  line-height: 1.4;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  transition: color 0.12s;
+}
+.help-toc-link:hover { color: #f1f5f9; }
+
 .node-body {
  padding: 4px 0;
  display: flex;