concept-atlas-dense-explain 0.10.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.10.0",
+  "version": "1.0.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {

package/template/guides/scroll-guide.mdx

@@ -100,6 +100,38 @@ npm run dev`}</CodeBlock>
     <RelationMap title="关系速览" items={[{from:'MDX',type:'produces',to:'Graph',note:'生成关系图'},{from:'Node',type:'uses',to:'Mermaid',note:'展示局部流程'}]} />
   </ScrollSection>
 
+  <ScrollSection title="附录：大图的框内适配与放大阅读">
+    <ScrollProse>较大的流程图会被等比收进框内，而不是画出边框。点击图面或标题栏的「放大阅读」可以打开全屏视图，用滚轮缩放、拖拽平移、Esc 关闭。</ScrollProse>
+    <Mermaid title="图谱生成管线" width="100%" height="360px" chart={`flowchart TD
+  S[MDX 源文件] --> P[解析与校验]
+  P --> G[概念图谱]
+  P --> F[图表与公式]
+  G --> D[节点探索]
+  G --> R[关系图谱]
+  D --> M[Mermaid 局部流程图]
+  R --> M
+  F --> M
+  M --> Z[框内自适应缩放]
+  Z --> O[点击放大阅读]
+  O --> W[拖拽平移]
+  O --> K[滚轮缩放]
+  O --> E[Esc 关闭]
+  style S fill:#172554,stroke:#38bdf8,color:#e0f2fe
+  style Z fill:#14532d,stroke:#34d399,color:#ecfdf5
+  style O fill:#78350f,stroke:#fbbf24,color:#fffbeb`} />
+    <ScrollGrid columns="2">
+      <Mermaid title="窄栏中的纵向长图" width="100%" height="220px" chart={`flowchart TD
+  A[读取] --> B[解析]
+  B --> C[建模]
+  C --> D[渲染]
+  D --> E[校验]
+  E --> F[发布]
+  F --> G[归档]
+  G --> H[复盘]`} />
+      <RelationPath title="阅读路径" steps={[{level:'L0',node:'总览',note:'建立直觉',tone:'info'},{level:'L1',node:'机制',note:'理解过程',tone:'success'},{level:'L2',node:'边界',note:'检查反例',tone:'warn'}]} />
+    </ScrollGrid>
+  </ScrollSection>
+
   <ScrollSection title="参考文献">
     <References title="本页引用" items={[{id:'tufte1983',authors:'Tufte, E. R.',year:'1983',title:'The Visual Display of Quantitative Information',source:'Graphics Press',note:'关于以图形压缩与呈现证据的经典论述。'}]} />
   </ScrollSection>

package/template/src/components/MDXComponents.jsx

@@ -726,13 +726,48 @@ export function Tabs({ items = [], children }) {
 }
 Tabs.displayName = 'Tabs';
 
+/**
+ * Enlarged reader for a diagram. It re-renders the chart under a fresh id so
+ * the full-size copy never collides with the inline SVG, then hands the result
+ * to the shared zoom overlay (wheel zoom, drag to pan, Esc to close).
+ */
+function MermaidZoom({ chart, title, onClose }) {
+  const ref = React.useRef(null);
+  const appearanceKey = useAppearanceKey();
+  const [error, setError] = React.useState('');
+
+  React.useEffect(() => {
+    let cancelled = false;
+    async function renderZoom() {
+      if (!ref.current || !chart.trim()) return;
+      try {
+        configureMermaid();
+        const renderId = `mermaid-zoom-${Math.random().toString(36).slice(2, 10)}`;
+        const { svg } = await mermaid.render(renderId, chart.trim());
+        if (!cancelled && ref.current) ref.current.innerHTML = svg;
+      } catch (err) {
+        if (!cancelled) setError(err.message || 'Mermaid 图表语法错误');
+      }
+    }
+    renderZoom();
+    return () => { cancelled = true; };
+  }, [chart, appearanceKey]);
+
+  return (
+    <ZoomOverlay title={title || '关系草图'} caption={title} onClose={onClose}>
+      {error
+        ? <pre className="mermaid-error">{error}</pre>
+        : <div className="mermaid-zoom-canvas" ref={ref} />}
+    </ZoomOverlay>
+  );
+}
+
 export function Mermaid({ chart = '', title = '关系草图', width = 'auto', height = 'auto', x = 0, y = 0, position = 'flow' }) {
   const ref = React.useRef(null);
   const id = React.useId().replace(/:/g, '');
   const appearanceKey = useAppearanceKey();
   const [error, setError] = React.useState('');
-  const [scale, setScale] = React.useState(1);
-  const [pan, setPan] = React.useState({ x: 0, y: 0 });
+  const [zoomed, setZoomed] = React.useState(false);
 
   React.useEffect(() => {
     let cancelled = false;
@@ -754,15 +789,41 @@ export function Mermaid({ chart = '', title = '关系草图', width = 'auto', he
     return () => { cancelled = true; };
   }, [chart, id, appearanceKey]);
 
-  const zoom = (delta) => setScale(value => Math.max(0.5, Math.min(3, +(value + delta).toFixed(2))));
-  const reset = () => { setScale(1); setPan({ x: 0, y: 0 }); };
+  const canZoom = Boolean(chart.trim()) && !error;
+  const openZoom = () => { if (canZoom) setZoomed(true); };
+  const onKeyDown = event => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      openZoom();
+    }
+  };
+
   return (
     <div className={`semantic-mermaid ${widgetClass(position)}`} style={widgetStyle({ width, height, x, y, position })}>
       <div className="semantic-widget-head">
         <span>{title}</span>
-        <div className="mermaid-tools"><code>MERMAID</code><button type="button" onClick={() => zoom(-0.1)} aria-label="缩小图表">−</button><span>{Math.round(scale * 100)}%</span><button type="button" onClick={() => zoom(0.1)} aria-label="放大图表">＋</button><button type="button" onClick={reset} aria-label="重置图表">↺</button></div>
+        <div className="mermaid-tools">
+          <code>MERMAID</code>
+          <button type="button" onClick={openZoom} disabled={!canZoom} aria-label={`放大阅读：${title}`}>
+            <ZoomIn size={12} />放大阅读
+          </button>
+        </div>
       </div>
-      {error ? <pre className="mermaid-error">{error}</pre> : <div className="mermaid-canvas" onWheel={(event) => { event.preventDefault(); zoom(event.deltaY < 0 ? 0.1 : -0.1); }}><div className="mermaid-canvas-inner" style={{ transform: `translate(${pan.x}px, ${pan.y}px) scale(${scale})` }} ref={ref} /></div>}
+      {error ? (
+        <pre className="mermaid-error">{error}</pre>
+      ) : (
+        <div
+          className="mermaid-canvas"
+          role="button"
+          tabIndex={0}
+          aria-label={`放大阅读：${title}`}
+          onClick={openZoom}
+          onKeyDown={onKeyDown}
+        >
+          <div className="mermaid-canvas-inner" ref={ref} />
+        </div>
+      )}
+      {zoomed && <MermaidZoom chart={chart} title={title} onClose={() => setZoomed(false)} />}
     </div>
   );
 }
@@ -1047,12 +1108,12 @@ const ZOOM_MIN = 0.5;
 const ZOOM_MAX = 6;
 
 /**
- * Full-viewport image viewer. Rendered through a portal so it escapes the
- * transformed/rotated ancestor surfaces (`position: fixed` would otherwise be
- * contained by them). Supports wheel zoom, drag to pan, double-click to toggle
- * 1x/2x, and Escape to close.
+ * Full-viewport zoom viewer shared by images and diagrams. Rendered through a
+ * portal so it escapes the transformed/rotated ancestor surfaces (`position:
+ * fixed` would otherwise be contained by them). Supports wheel zoom, drag to
+ * pan, double-click to toggle 1x/2x, and Escape to close.
  */
-function ImageZoom({ src, alt, caption, label, onClose }) {
+function ZoomOverlay({ title, caption, label, onClose, children }) {
   const [scale, setScale] = React.useState(1);
   const [offset, setOffset] = React.useState({ x: 0, y: 0 });
   const [dragging, setDragging] = React.useState(false);
@@ -1126,8 +1187,6 @@ function ImageZoom({ src, alt, caption, label, onClose }) {
     }
   };
 
-  const title = alt || caption || '图片';
-
   return createPortal(
     <div
       className="image-zoom-overlay"
@@ -1146,14 +1205,11 @@ function ImageZoom({ src, alt, caption, label, onClose }) {
         onDoubleClick={() => { const next = scaleRef.current > 1 ? 1 : 2; setScale(next); settle(next); }}
         onClick={event => { if (movedRef.current) { event.stopPropagation(); movedRef.current = false; } }}
       >
-        <img
-          src={src}
-          alt={alt || ''}
-          draggable="false"
-          style={{ transform: `translate(${offset.x}px, ${offset.y}px) scale(${scale})` }}
-        />
+        <div className="image-zoom-target" style={{ transform: `translate(${offset.x}px, ${offset.y}px) scale(${scale})` }}>
+          {children}
+        </div>
       </div>
-      {title && <p className="image-zoom-caption">{label && <b>{label}</b>}{caption || alt}</p>}
+      {title && <p className="image-zoom-caption">{label && <b>{label}</b>}{caption}</p>}
       <div className="image-zoom-toolbar">
         <button type="button" onClick={() => zoomBy(-0.25)} aria-label="缩小" title="缩小（−）">−</button>
         <span aria-live="polite">{Math.round(scale * 100)}%</span>
@@ -1166,6 +1222,15 @@ function ImageZoom({ src, alt, caption, label, onClose }) {
   );
 }
 
+function ImageZoom({ src, alt, caption, label, onClose }) {
+  const title = alt || caption || '图片';
+  return (
+    <ZoomOverlay title={title} caption={caption || alt} label={label} onClose={onClose}>
+      <img src={src} alt={alt || ''} draggable="false" />
+    </ZoomOverlay>
+  );
+}
+
 export function Figure({ src, alt = '', caption, label, width = 'auto', height = 'auto', x = 0, y = 0, position = 'flow' }) {
   const [zoomed, setZoomed] = React.useState(false);
   const title = alt || caption || '图片';

package/template/src/styles/core.css

@@ -94,11 +94,45 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 .gap-sm { gap: 8px; } .gap-md { gap: 16px; } .gap-lg { gap: 28px; }
 .semantic-tabs details { border-bottom: 1px solid var(--border-subtle); padding: 8px 0; }
 .semantic-tabs summary { cursor: pointer; font-weight: 700; color: var(--text-primary); }
-.mermaid-tools { display: inline-flex; align-items: center; gap: 5px; }
-.mermaid-tools button { width: 22px; height: 22px; border: 1px solid var(--border-medium); border-radius: 4px; background: var(--bg-subtle); font-weight: 700; }
+.mermaid-tools { display: inline-flex; align-items: center; gap: 6px; }
+.mermaid-tools button {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  height: 22px;
+  padding: 0 8px;
+  border: 1px solid var(--border-medium);
+  border-radius: var(--radius-1);
+  background: var(--bg-subtle);
+  color: var(--text-secondary);
+  font-size: 11px;
+  font-weight: 700;
+}
 .mermaid-tools button:hover { color: var(--primary); border-color: var(--primary); }
-.mermaid-canvas { overflow: hidden; min-height: 120px; display: grid; place-items: center; cursor: grab; }
-.mermaid-canvas-inner { display: inline-block; min-width: 100%; transform-origin: center center; transition: transform .15s ease; }
+.mermaid-tools button:disabled { opacity: .5; cursor: not-allowed; }
+
+/* The diagram frame is a bounded viewport, not a loose box: the head keeps its
+   own height and the canvas takes the rest, so a fixed `height` prop contains
+   the drawing instead of letting it paint past the border. The SVG is scaled to
+   fit with its own preserveAspectRatio; clicking opens the full-size viewer. */
+.mermaid-canvas {
+  position: relative;
+  flex: 1 1 auto;
+  min-height: 0;
+  min-width: 0;
+  max-width: 100%;
+  overflow: hidden;
+  padding: 4px;
+  cursor: zoom-in;
+}
+.mermaid-canvas-inner {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  transform-origin: center center;
+}
+.mermaid-canvas svg { display: block; width: 100%; height: 100%; max-width: 100%; max-height: 100%; }
 
 /* Scrollbar beautification */
 ::-webkit-scrollbar {
@@ -2070,6 +2104,16 @@ button.flow-box {
   min-width: 0;
 }
 
+/* The diagram frame clips and hands its remaining height to the canvas, so a
+   fixed `height` prop can never let the drawing escape the border. */
+.semantic-mermaid {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.semantic-mermaid > .semantic-widget-head { flex: 0 0 auto; }
+
 .draft-board .custom-section {
   padding: 12px 14px;
 }
@@ -2130,9 +2174,10 @@ button.flow-box {
 .draft-board .semantic-relation-map {
   width: fit-content;
   max-width: 100%;
-  overflow: visible;
 }
 
+.draft-board .semantic-relation-map { overflow: visible; }
+
 .draft-board .semantic-insight,
 .draft-board .semantic-note-grid {
   width: fit-content;
@@ -2156,22 +2201,18 @@ button.flow-box {
   font-size: 9px;
 }
 
-.mermaid-canvas {
-  min-height: 100px;
-  overflow: auto;
-  padding: 4px;
-  max-width: 100%;
-  min-width: 0;
-}
-
-.mermaid-canvas svg {
-  max-width: none;
-  min-width: 100%;
-  height: auto;
+/* The inline diagram is a preview: clicking it, or the head button, opens the
+   full-size viewer. The cursor is the only affordance on the drawing itself, so
+   nothing competes with the diagram for attention. */
+.mermaid-canvas:focus-visible {
+  outline: 2px solid var(--accent-cyan);
+  outline-offset: 2px;
 }
 
 .mermaid-error {
   margin: 0;
+  min-height: 0;
+  overflow: auto;
   color: var(--accent-rose);
   font-size: 11px;
   white-space: pre-wrap;
@@ -3760,6 +3801,10 @@ html[data-carrier='scroll'] #root {
   place-items: center;
   padding: 28px;
   background: var(--overlay-scrim);
+  /* Clip at the viewport, not at the media box: the zoom transform does not
+     change layout size, so a stage-sized clip would only ever reveal what the
+     un-zoomed element already covered. */
+  overflow: hidden;
 }
 
 .image-zoom-stage {
@@ -3767,13 +3812,22 @@ html[data-carrier='scroll'] #root {
   place-items: center;
   max-width: 100%;
   max-height: 100%;
-  overflow: hidden;
+  overflow: visible;
   cursor: grab;
   touch-action: none;
 }
 
 .image-zoom-stage.is-dragging { cursor: grabbing; }
 
+/* The pan/zoom transform rides a wrapper so the viewer can hold an <img> or a
+   rendered diagram without duplicating the gesture logic. */
+.image-zoom-target {
+  display: block;
+  transition: transform 0.12s ease-out;
+  will-change: transform;
+  user-select: none;
+}
+
 .image-zoom-stage img {
   display: block;
   width: auto;
@@ -3783,12 +3837,22 @@ html[data-carrier='scroll'] #root {
   border-radius: var(--radius-2);
   background: var(--bg-surface);
   box-shadow: var(--shadow-modal);
-  transition: transform 0.12s ease-out;
-  will-change: transform;
   user-select: none;
 }
 
-.image-zoom-stage.is-dragging img { transition: none; }
+.image-zoom-stage.is-dragging .image-zoom-target { transition: none; }
+
+/* A diagram keeps its natural aspect inside the viewer and paints on the
+   Mermaid canvas tone, so labels stay legible over the dark scrim. */
+.mermaid-zoom-canvas svg {
+  display: block;
+  width: min(94vw, 1800px);
+  height: auto;
+  max-height: 84vh;
+  border-radius: var(--radius-3);
+  background: var(--mermaid-canvas);
+  box-shadow: var(--shadow-modal);
+}
 
 .image-zoom-caption {
   position: absolute;
@@ -3847,14 +3911,14 @@ html[data-carrier='scroll'] #root {
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .image-zoom-stage img { transition: none; }
+  .image-zoom-target { transition: none; }
 }
 
 @media (max-width: 760px) {
   .image-zoom-overlay { padding: 12px; }
   .image-zoom-stage img { max-height: 74vh; }
+  .mermaid-zoom-canvas svg { max-height: 74vh; }
   .image-zoom-caption { top: 10px; font-size: 12px; }
-  .image-zoom-hint { opacity: 0.9; }
 }
 
 .semantic-figure figcaption {