concept-atlas-dense-explain 2.0.0 → 3.0.1

package/template/src/app/App.jsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useMemo, useRef } from 'react';
+import { useState, useEffect, useMemo, useRef, useCallback } from 'react';
 import { Network, Compass, Sun, Moon, Search, X, Link as LinkIcon } from 'lucide-react';
 import { buildGraphModel } from '../model/concept-schema.js';
 import { extractConceptData } from '../model/normalize-content.js';
@@ -30,7 +30,14 @@ export function App({ mdxContent, initialData }) {
   });
 
   // Appearance state (skin x mode x component style), shared with the scroll carrier via localStorage
-  const { skin, mode: theme, style, setSkin, setStyle, toggleMode } = useAppearance({ defaultMode: 'light' });
+  const {
+    skin,
+    mode: theme,
+    style,
+    setSkin,
+    setStyle,
+    toggleMode
+  } = useAppearance({ defaultMode: 'light' });
 
   const toggleTheme = toggleMode;
 
@@ -42,11 +49,11 @@ export function App({ mdxContent, initialData }) {
   })();
 
   const [currentNodeId, setCurrentNodeId] = useState(
-    () => initialHashNode || graph.meta.rootId || '',
+    () => initialHashNode || graph.meta.rootId || ''
   );
   const [nav, setNav] = useState(() => ({
     entries: (initialHashNode ? [initialHashNode] : [graph.meta.rootId]).filter(Boolean),
-    index: 0,
+    index: 0
   }));
   // Popstate handlers must read the *current* history state, not the closure
   // captured when the effect was created.
@@ -57,35 +64,64 @@ export function App({ mdxContent, initialData }) {
 
   const searchResults = useMemo(
     () => searchNodes(Array.from(graph.nodes.values()), globalQuery),
-    [globalQuery, graph.nodes],
+    [globalQuery, graph.nodes]
   );
 
-  const navigateToNode = (nodeId, { replace = false } = {}) => {
-    if (!nodeId || !graph.nodes.has(nodeId)) return;
-    const next = pushNode(nav, nodeId);
-    setCurrentNodeId(nodeId);
-    setNav(next);
-    const nextHash = `#node=${encodeURIComponent(nodeId)}`;
-    // Each browser entry remembers which in-app history index it maps to, so
-    // popstate can restore the exact entry even when hashes repeat.
-    const historyState = { atlasIndex: next.index };
-    if (next === nav && !replace) return; // re-selecting the current node: don't grow browser history
-    if (replace) window.history.replaceState(historyState, '', nextHash);
-    else window.history.pushState(historyState, '', nextHash);
-  };
-
-  const moveHistory = (direction) => {
-    // Browser history mirrors the in-app entries one-for-one (every navigation
-    // pushState'd the matching { atlasIndex }), so step through the real
-    // browser history. pushState here used to fork the two stacks and grow
-    // browser history unboundedly; the popstate handler applies the result.
-    if (!stepHistory(nav, direction)) return;
-    window.history.go(direction);
-  };
+  // Combobox state for the global search. The highlight resets whenever the
+  // query changes so the first arrow key lands on the first result.
+  const [activeResultIndex, setActiveResultIndex] = useState(-1);
+  const searchOpen = globalQuery.trim().length > 0 && searchResults.length > 0;
+  const activeResultId =
+    searchOpen && activeResultIndex >= 0 && searchResults[activeResultIndex]
+      ? `global-search-option-${searchResults[activeResultIndex].id}`
+      : undefined;
+
+  useEffect(() => {
+    setActiveResultIndex(-1);
+  }, [globalQuery]);
+
+  const navigateToNode = useCallback(
+    (nodeId, { replace = false } = {}) => {
+      if (!nodeId || !graph.nodes.has(nodeId)) return;
+      const next = pushNode(nav, nodeId);
+      setCurrentNodeId(nodeId);
+      setNav(next);
+      const nextHash = `#node=${encodeURIComponent(nodeId)}`;
+      // Each browser entry remembers which in-app history index it maps to, so
+      // popstate can restore the exact entry even when hashes repeat.
+      const historyState = { atlasIndex: next.index };
+      if (next === nav && !replace) return; // re-selecting the current node: don't grow browser history
+      if (replace) window.history.replaceState(historyState, '', nextHash);
+      else window.history.pushState(historyState, '', nextHash);
+    },
+    [nav, graph.nodes]
+  );
+
+  const selectSearchResult = useCallback(
+    node => {
+      if (!node) return;
+      navigateToNode(node.id);
+      setGlobalQuery('');
+      setActiveResultIndex(-1);
+    },
+    [navigateToNode]
+  );
+
+  const moveHistory = useCallback(
+    direction => {
+      // Browser history mirrors the in-app entries one-for-one (every navigation
+      // pushState'd the matching { atlasIndex }), so step through the real
+      // browser history. pushState here used to fork the two stacks and grow
+      // browser history unboundedly; the popstate handler applies the result.
+      if (!stepHistory(nav, direction)) return;
+      window.history.go(direction);
+    },
+    [nav]
+  );
 
   // Keyboard navigation shortcuts
   useEffect(() => {
-    const handleKeyDown = (e) => {
+    const handleKeyDown = e => {
       if (e.isComposing) return;
 
       // Alt + arrows move through browsing history. Handled before the modifier
@@ -103,7 +139,8 @@ export function App({ mdxContent, initialData }) {
 
       // Toggle views with 1 and 2 or 'g' and 'e' if not focused on input.
       const target = document.activeElement;
-      const typing = ['INPUT', 'TEXTAREA', 'SELECT'].includes(target?.tagName) || target?.isContentEditable;
+      const typing =
+        ['INPUT', 'TEXTAREA', 'SELECT'].includes(target?.tagName) || target?.isContentEditable;
       if (e.metaKey || e.ctrlKey || e.altKey || typing) return;
 
       const key = e.key.toLowerCase();
@@ -124,25 +161,25 @@ export function App({ mdxContent, initialData }) {
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [graph, currentNodeId, nav]);
+  }, [graph, currentNodeId, navigateToNode, moveHistory, toggleTheme]);
 
   useEffect(() => {
-    const handlePopState = (event) => {
+    const handlePopState = event => {
       const current = navRef.current;
       const nodeId = readNodeFromHash();
       if (nodeId && !graph.nodes.has(nodeId)) return; // stale/foreign hash: ignore
-      const tagged = event.state && Number.isInteger(event.state.atlasIndex)
-        ? event.state.atlasIndex
-        : null;
+      const tagged =
+        event.state && Number.isInteger(event.state.atlasIndex) ? event.state.atlasIndex : null;
       const taggedValid = tagged !== null && tagged >= 0 && tagged < current.entries.length;
       let next = null;
       if (nodeId) {
         // Prefer the index stamped on the entry: entries may contain the same
         // node twice, and lastIndexOf alone would resolve backwards steps to a
         // later duplicate.
-        next = taggedValid && current.entries[tagged] === nodeId
-          ? { entries: current.entries, index: tagged }
-          : syncFromLocation(current, nodeId);
+        next =
+          taggedValid && current.entries[tagged] === nodeId
+            ? { entries: current.entries, index: tagged }
+            : syncFromLocation(current, nodeId);
       } else if (taggedValid) {
         // Back to the hash-less entry the page loaded on: restore it by index.
         next = { entries: current.entries, index: tagged };
@@ -190,16 +227,67 @@ export function App({ mdxContent, initialData }) {
             <input
               value={globalQuery}
               onChange={event => setGlobalQuery(event.target.value)}
-              onKeyDown={event => { if (event.key === 'Escape') setGlobalQuery(''); }}
+              onKeyDown={event => {
+                if (event.key === 'Escape') {
+                  setGlobalQuery('');
+                  setActiveResultIndex(-1);
+                  return;
+                }
+                if (!searchOpen) return;
+                if (event.key === 'ArrowDown') {
+                  event.preventDefault();
+                  setActiveResultIndex(index => (index + 1) % searchResults.length);
+                } else if (event.key === 'ArrowUp') {
+                  event.preventDefault();
+                  setActiveResultIndex(index =>
+                    index <= 0 ? searchResults.length - 1 : index - 1
+                  );
+                } else if (event.key === 'Enter' && activeResultIndex >= 0) {
+                  event.preventDefault();
+                  selectSearchResult(searchResults[activeResultIndex]);
+                }
+              }}
               placeholder="搜索所有节点…"
               aria-label="搜索所有节点"
+              role="combobox"
+              aria-expanded={searchOpen}
+              aria-controls="global-search-results"
+              aria-autocomplete="list"
+              aria-activedescendant={activeResultId}
             />
-            {globalQuery && <button type="button" onClick={() => setGlobalQuery('')} aria-label="清除搜索"><X size={13} /></button>}
-            {searchResults.length > 0 && (
-              <div className="global-search-results" role="listbox">
-                {searchResults.map(node => (
-                  <button type="button" key={node.id} onClick={() => { navigateToNode(node.id); setGlobalQuery(''); }} role="option">
-                    <span>{node.title}</span><small>{node.level}{node.kind && NODE_KINDS[node.kind] ? ` · ${NODE_KINDS[node.kind].label}` : ''} · {node.summary || node.id}</small>
+            {globalQuery && (
+              <button
+                type="button"
+                onClick={() => {
+                  setGlobalQuery('');
+                  setActiveResultIndex(-1);
+                }}
+                aria-label="清除搜索"
+              >
+                <X size={13} />
+              </button>
+            )}
+            {searchOpen && (
+              <div id="global-search-results" className="global-search-results" role="listbox">
+                {searchResults.map((node, index) => (
+                  <button
+                    type="button"
+                    key={node.id}
+                    id={`global-search-option-${node.id}`}
+                    className={index === activeResultIndex ? 'active' : ''}
+                    onMouseEnter={() => setActiveResultIndex(index)}
+                    onClick={() => selectSearchResult(node)}
+                    role="option"
+                    aria-selected={index === activeResultIndex}
+                  >
+                    <span>{node.title}</span>
+                    <small>
+                      {node.level}
+                      {node.kind && NODE_KINDS[node.kind]
+                        ? ` · ${NODE_KINDS[node.kind].label}`
+                        : ''}{' '}
+                      · {node.summary || node.id}
+                    </small>
                   </button>
                 ))}
               </div>

package/template/src/app/search.js

@@ -10,7 +10,8 @@ const MAX_LENGTH = 4000;
  * a pathological tree cannot stall the search box.
  */
 export function collectText(value, depth = 0) {
-  if (depth > MAX_DEPTH || value === null || value === undefined || typeof value === 'boolean') return '';
+  if (depth > MAX_DEPTH || value === null || value === undefined || typeof value === 'boolean')
+    return '';
   if (typeof value === 'string' || typeof value === 'number') return String(value);
   if (Array.isArray(value)) {
     return value.map(item => collectText(item, depth + 1)).join(' ');
@@ -28,7 +29,9 @@ export function collectText(value, depth = 0) {
     return parts.join(' ');
   }
   if (typeof value === 'object') {
-    return Object.values(value).map(item => collectText(item, depth + 1)).join(' ');
+    return Object.values(value)
+      .map(item => collectText(item, depth + 1))
+      .join(' ');
   }
   return '';
 }
@@ -66,14 +69,20 @@ export function nodeSearchText(node) {
     node.invariants,
     node.failureModes,
     node.tradeoffs,
-    node.customSections,
+    node.customSections
   ];
-  return parts.map(part => collectText(part)).join(' ').slice(0, MAX_LENGTH).toLowerCase();
+  return parts
+    .map(part => collectText(part))
+    .join(' ')
+    .slice(0, MAX_LENGTH)
+    .toLowerCase();
 }
 
 /** Rank-free substring search returning at most `limit` nodes. */
 export function searchNodes(nodes, query, limit = 8) {
-  const needle = String(query || '').trim().toLowerCase();
+  const needle = String(query || '')
+    .trim()
+    .toLowerCase();
   if (!needle) return [];
   const results = [];
   for (const node of nodes) {

package/template/src/app/use-appearance.js

@@ -13,15 +13,19 @@ function normalizeMode(value, fallback = 'dark') {
  * Compile-time defaults injected via Vite `define` (CLI --skin/--default-mode
  * or CONCEPT_ATLAS_* env vars). Absent defines resolve to the carrier fallbacks.
  */
-const BUILD_DEFAULT_SKIN = typeof __ATLAS_DEFAULT_SKIN__ === 'string'
-  ? (normalizeSkin(__ATLAS_DEFAULT_SKIN__) || DEFAULT_SKIN)
-  : DEFAULT_SKIN;
-const BUILD_DEFAULT_MODE = typeof __ATLAS_DEFAULT_MODE__ === 'string' && (__ATLAS_DEFAULT_MODE__ === 'dark' || __ATLAS_DEFAULT_MODE__ === 'light')
-  ? __ATLAS_DEFAULT_MODE__
-  : null;
-const BUILD_DEFAULT_STYLE = typeof __ATLAS_DEFAULT_STYLE__ === 'string'
-  ? (normalizeStyle(__ATLAS_DEFAULT_STYLE__) || DEFAULT_STYLE)
-  : DEFAULT_STYLE;
+const BUILD_DEFAULT_SKIN =
+  typeof __ATLAS_DEFAULT_SKIN__ === 'string'
+    ? normalizeSkin(__ATLAS_DEFAULT_SKIN__) || DEFAULT_SKIN
+    : DEFAULT_SKIN;
+const BUILD_DEFAULT_MODE =
+  typeof __ATLAS_DEFAULT_MODE__ === 'string' &&
+  (__ATLAS_DEFAULT_MODE__ === 'dark' || __ATLAS_DEFAULT_MODE__ === 'light')
+    ? __ATLAS_DEFAULT_MODE__
+    : null;
+const BUILD_DEFAULT_STYLE =
+  typeof __ATLAS_DEFAULT_STYLE__ === 'string'
+    ? normalizeStyle(__ATLAS_DEFAULT_STYLE__) || DEFAULT_STYLE
+    : DEFAULT_STYLE;
 
 function readStoredAppearance(fallbackMode) {
   const fallback = normalizeMode(fallbackMode, 'dark');
@@ -34,7 +38,7 @@ function readStoredAppearance(fallbackMode) {
         // Corrupt/missing mode falls back to the carrier default instead of
         // silently coercing to dark.
         mode: normalizeMode(parsed?.mode, fallback),
-        style: normalizeStyle(parsed?.style) || BUILD_DEFAULT_STYLE,
+        style: normalizeStyle(parsed?.style) || BUILD_DEFAULT_STYLE
       };
     }
   } catch {
@@ -67,7 +71,9 @@ export { readStoredAppearance, normalizeMode };
  * localStorage key so both pages stay in sync.
  */
 export function useAppearance({ defaultMode = 'dark' } = {}) {
-  const [appearance, setAppearance] = useState(() => readStoredAppearance(BUILD_DEFAULT_MODE || defaultMode));
+  const [appearance, setAppearance] = useState(() =>
+    readStoredAppearance(BUILD_DEFAULT_MODE || defaultMode)
+  );
 
   useEffect(() => {
     document.documentElement.setAttribute('data-skin', appearance.skin);
@@ -80,18 +86,26 @@ export function useAppearance({ defaultMode = 'dark' } = {}) {
     }
   }, [appearance]);
 
-  const setSkin = useCallback((skin) => {
+  const setSkin = useCallback(skin => {
     setAppearance(prev => ({ ...prev, skin: normalizeSkin(skin) || prev.skin }));
   }, []);
-  const setMode = useCallback((mode) => {
+  const setMode = useCallback(mode => {
     setAppearance(prev => ({ ...prev, mode: normalizeMode(mode, prev.mode) }));
   }, []);
   const toggleMode = useCallback(() => {
     setAppearance(prev => ({ ...prev, mode: prev.mode === 'dark' ? 'light' : 'dark' }));
   }, []);
-  const setStyle = useCallback((style) => {
+  const setStyle = useCallback(style => {
     setAppearance(prev => ({ ...prev, style: normalizeStyle(style) || prev.style }));
   }, []);
 
-  return { skin: appearance.skin, mode: appearance.mode, style: appearance.style, setSkin, setMode, toggleMode, setStyle };
+  return {
+    skin: appearance.skin,
+    mode: appearance.mode,
+    style: appearance.style,
+    setSkin,
+    setMode,
+    toggleMode,
+    setStyle
+  };
 }