@changfenhuang/dsh-genui 0.9.1

package/src/client/blocks/advanced.tsx

@@ -0,0 +1,435 @@
+/**
+ * Advanced family: callout/steps/keyvalue, plot/diff/json/code, tabs and
+ * accordion containers (recursing through renderNode), copy, mermaid,
+ * scene3d, timeline, file-tree, quiz, breadcrumb.
+ * @module @changfenhuang/dsh-genui/client/blocks/advanced
+ */
+import { memo, useEffect, useId, useMemo, useRef, useState, type ReactNode } from 'react'
+import { CodeBlock, DiffBlock, JsonTree } from '@deepseek-ai/dsh-client-ui-primitives'
+import css from '../GenuiBlock.module.css'
+import { GENUI_LIMITS } from '../guard.ts'
+import { PlotBlock } from '../PlotBlock.tsx'
+import { renderNode } from './render-node.tsx'
+import type { AnswersState, GenuiBlockProps } from './state.ts'
+import type {
+  GenuiAccordion, GenuiBreadcrumb, GenuiCallout, GenuiCode, GenuiCopy, GenuiDiff, GenuiFileTree, GenuiFileTreeNode,
+  GenuiJson, GenuiKeyValue, GenuiMermaid, GenuiPlot, GenuiQuiz, GenuiScene3D, GenuiSteps, GenuiTabs, GenuiTimeline,
+} from '../spec.ts'
+
+const CALLOUT_TONES: Record<string, string> = {
+  info: css.calloutInfo!, success: css.calloutSuccess!, warning: css.calloutWarning!, error: css.calloutError!,
+}
+
+/** Callout: a tinted notice box with an optional heading. */
+export const CalloutNode = memo(function CalloutNode({ node }: { node: GenuiCallout }) {
+  const tone = node.tone ?? 'info'
+  const toneClass = CALLOUT_TONES[tone] ?? css.calloutInfo
+  return (
+    <div className={`${css.callout} ${toneClass}`} data-genui-callout>
+      {node.title !== undefined && <div className={css.calloutTitle}>{node.title}</div>}
+      <div className={css.calloutBody}>{node.content}</div>
+    </div>
+  )
+})
+
+/** Steps: a vertical progress checklist with an optional current index. */
+export const StepsNode = memo(function StepsNode({ steps }: { steps: GenuiSteps }) {
+  const list = steps.steps.slice(0, GENUI_LIMITS.maxSteps)
+  const current = steps.current ?? list.length
+  return (
+    <ol className={css.steps}>
+      {list.map((step, i) => {
+        const done = i < current
+        const active = i === current
+        return (
+          <li key={i} className={`${css.step} ${done ? css.stepDone : ''} ${active ? css.stepActive : ''}`}>
+            <span className={css.stepMarker}>{done ? '✓' : String(i + 1)}</span>
+            <span className={css.stepContent}>
+              <span className={css.stepTitle}>{step.title}</span>
+              {step.desc !== undefined && <span className={css.stepDesc}>{step.desc}</span>}
+            </span>
+          </li>
+        )
+      })}
+    </ol>
+  )
+})
+
+/** KeyValue: a definition list for configs and metadata. */
+export const KeyValueNode = memo(function KeyValueNode({ node }: { node: GenuiKeyValue }) {
+  const pairs = node.pairs.slice(0, GENUI_LIMITS.maxKeyValuePairs)
+  return (
+    <dl className={css.keyvalue}>
+      {pairs.map((pair, i) => (
+        <div key={i} className={css.kvRow}>
+          <dt className={css.kvKey}>{pair.key}</dt>
+          <dd className={css.kvValue}>{pair.value}</dd>
+        </div>
+      ))}
+    </dl>
+  )
+})
+
+/** Plot: SVG function plot over the SafeMath evaluator. The series mapping
+ * is memoized on the stable spec node so the memo boundary actually skips
+ * sibling-state re-renders (a fresh mapped array would defeat it). */
+export const PlotNode = memo(function PlotNode({ plot }: { plot: GenuiPlot }) {
+  const series = useMemo(
+    () => plot.series.slice(0, GENUI_LIMITS.maxPlotSeries)
+      .map(s => ({ expr: s.expr, label: s.label, color: s.color, kind: s.kind, params: s.params })),
+    [plot],
+  )
+  return (
+    <PlotBlock
+      series={series}
+      xMin={plot.xMin} xMax={plot.xMax} yMin={plot.yMin} yMax={plot.yMax} title={plot.title}
+    />
+  )
+})
+
+/** Diff: 收编 dsh DiffBlock (same path/oldText/newText shape as DiffHunk). */
+export const DiffNode = memo(function DiffNode({ node }: { node: GenuiDiff }) {
+  return <DiffBlock diffs={node.diffs} />
+})
+
+/** Json: 收编 dsh JsonTree. */
+export const JsonNode = memo(function JsonNode({ node }: { node: GenuiJson }) {
+  const data = node.value
+  if (typeof data !== 'object' || data === null) {
+    return <div className={css.jsonScalar}>{String(data)}</div>
+  }
+  return <JsonTree data={data as object | unknown[]} copyable />
+})
+
+/** Code: 收编 dsh CodeBlock with explicit language. */
+export const CodeNode = memo(function CodeNode({ node }: { node: GenuiCode }) {
+  return <CodeBlock code={node.code.slice(0, GENUI_LIMITS.maxCode)} lang={node.lang} />
+})
+
+/**
+ * Table: LOCAL sorting (v2.9) — click a header to sort ascending, click
+ * again for descending, a third click restores the spec order. Zero model
+ * round trip. Numeric cells (numbers or numeric strings) compare numerically;
+ * everything else compares as text.
+ */
+export function TabsNode({ tabs, onAction, depth = 0, answers }: {
+  tabs: GenuiTabs
+  onAction?: GenuiBlockProps['onAction']
+  depth?: number
+  answers?: AnswersState | undefined
+}) {
+  const [active, setActive] = useState(0)
+  const uid = useId()
+  const list = tabs.tabs.slice(0, GENUI_LIMITS.maxTabs)
+  const current = list[active]
+  const move = (next: number): void => {
+    const n = (next + list.length) % list.length
+    setActive(n)
+    document.getElementById(`${uid}-tab-${n}`)?.focus()
+  }
+  return (
+    <div className={css.tabs}>
+      <div
+        className={css.tabBar}
+        role="tablist"
+        aria-orientation="horizontal"
+        onKeyDown={e => {
+          if (e.key === 'ArrowRight') { e.preventDefault(); move(active + 1) }
+          else if (e.key === 'ArrowLeft') { e.preventDefault(); move(active - 1) }
+          else if (e.key === 'Home') { e.preventDefault(); move(0) }
+          else if (e.key === 'End') { e.preventDefault(); move(list.length - 1) }
+        }}
+      >
+        {list.map((tab, i) => (
+          <button
+            key={i}
+            id={`${uid}-tab-${i}`}
+            type="button"
+            role="tab"
+            aria-selected={i === active}
+            aria-controls={`${uid}-panel-${i}`}
+            tabIndex={i === active ? 0 : -1}
+            className={`${css.tab} ${i === active ? css.tabActive : ''}`}
+            onClick={() => setActive(i)}
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+      {current !== undefined && (
+        <div className={css.col} role="tabpanel" id={`${uid}-panel-${active}`} aria-labelledby={`${uid}-tab-${active}`}>
+          {current.items.map((c, i) => renderNode(c, i, onAction, depth + 1, answers))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** Radio: one option from a group; local selection state. The group name is
+ * useId-based so sibling groups never collide (deterministic per mount).
+ *
+ * v2.5 aggregation: when `group` is set, the selection is recorded into the
+ * block-wide answers registry instead of firing a per-click action — a
+ * sibling `submit` node then grades the paper IN PLACE (v2.6, questions
+ * carry `answer` data) or collects all groups in ONE action. Without
+ * `group`, the legacy per-click action fires. After a local grading the
+ * group locks until 重新作答 resets it. */
+export function AccordionNode({ node, onAction, depth = 0, answers }: {
+  node: GenuiAccordion
+  onAction?: GenuiBlockProps['onAction']
+  depth?: number
+  answers?: AnswersState | undefined
+}) {
+  const [open, setOpen] = useState<number | null>(0)
+  const uid = useId()
+  const items = node.items.slice(0, GENUI_LIMITS.maxAccordionItems)
+  return (
+    <div className={css.accordion}>
+      {items.map((item, i) => (
+        <div key={i} className={css.accItem}>
+          <button
+            type="button"
+            className={css.accHead}
+            id={`${uid}-head-${i}`}
+            aria-expanded={open === i}
+            aria-controls={`${uid}-body-${i}`}
+            onClick={() => setOpen(open === i ? null : i)}
+          >
+            <span className={css.accTitle}>{item.title}</span>
+            <span className={css.accChevron}>{open === i ? '▾' : '▸'}</span>
+          </button>
+          {open === i && (
+            <div className={css.accBody} id={`${uid}-body-${i}`} aria-labelledby={`${uid}-head-${i}`}>
+              {item.items.map((c, ci) => renderNode(c, ci, onAction, depth + 1, answers))}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/** Copy: a one-click copy chip. The live region is a visually-hidden SIBLING
+ * (not inside the button) — button content is atomic to screen readers, so a
+ * live region inside it would never announce. */
+export const CopyNode = memo(function CopyNode({ node }: { node: GenuiCopy }) {
+  const [copied, setCopied] = useState(false)
+  return (
+    <>
+      <button
+        type="button"
+        className={`${css.copyChip} ${copied ? css.copyChipDone : ''}`}
+        onClick={() => {
+          void navigator.clipboard?.writeText(node.text).catch(() => {})
+          setCopied(true)
+          setTimeout(() => setCopied(false), 1500)
+        }}
+      >
+        {copied ? '✓ 已复制' : (node.label ?? '复制')}
+      </button>
+      <span className={css.visuallyHidden} role="status">{copied ? '已复制到剪贴板' : ''}</span>
+    </>
+  )
+})
+
+/** Mermaid: lazily loaded diagram renderer. */
+export const MermaidNode = memo(function MermaidNode({ node }: { node: GenuiMermaid }) {
+  const [html, setHtml] = useState<string | null>(null)
+  const [failed, setFailed] = useState(false)
+  const code = node.code.slice(0, GENUI_LIMITS.maxMermaid)
+  useEffect(() => {
+    let alive = true
+    void import('../mermaid-lazy.ts').then(async m => {
+      try {
+        const svg = await m.renderMermaid(code)
+        if (alive) setHtml(svg)
+      } catch {
+        if (alive) setFailed(true)
+      }
+    })
+    return () => { alive = false }
+  }, [code])
+  if (failed) return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidErr}>图语法有误，已降级显示源码</div></div>
+  if (html === null) return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidHint}>渲染中…</div></div>
+  return <div className={css.mermaid} dangerouslySetInnerHTML={{ __html: html }} data-genui-mermaid />
+})
+
+/** Scene3D: three.js WebGL canvas, lazily imported. */
+export const Scene3DNode = memo(function Scene3DNode({ node }: { node: GenuiScene3D }) {
+  const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading')
+  const ref = useRef<HTMLDivElement | null>(null)
+  // Mesh cap mirrored from the guard: a pathological scene never reaches
+  // three.js (per-frame cost scales with mesh count).
+  const scene = node.meshes.length > GENUI_LIMITS.maxMeshes ? { ...node, meshes: node.meshes.slice(0, GENUI_LIMITS.maxMeshes) } : node
+  useEffect(() => {
+    let alive = true
+    let dispose: (() => void) | undefined
+    void import('../scene3d-lazy.ts').then(async m => {
+      if (!alive || ref.current === null) return
+      try {
+        dispose = await m.mountScene(ref.current, scene)
+        if (alive) setStatus('ready')
+      } catch {
+        if (alive) setStatus('error')
+      }
+    })
+    return () => { alive = false; dispose?.() }
+  }, [scene])
+  return (
+    <div className={css.scene3dWrap} data-genui-scene3d>
+      {node.title !== undefined && <div className={css.scene3dTitle}>{node.title}</div>}
+      <div ref={ref} className={css.scene3dCanvas} />
+      {status === 'loading' && <div className={css.scene3dHint}>加载 3D 场景…</div>}
+      {status === 'error' && <div className={css.scene3dHint}>3D 渲染失败</div>}
+    </div>
+  )
+})
+
+/** Timeline: vertical event list with time markers. */
+export const TimelineNode = memo(function TimelineNode({ node }: { node: GenuiTimeline }) {
+  const items = node.items.slice(0, GENUI_LIMITS.maxTimelineItems)
+  return (
+    <div className={css.timeline}>
+      {items.map((item, i) => (
+        <div key={i} className={css.tlItem}>
+          <div className={css.tlRail}>
+            <span className={css.tlDot} />
+            {i < items.length - 1 && <span className={css.tlLine} />}
+          </div>
+          <div className={css.tlBody}>
+            <div className={css.tlHead}>
+              <span className={css.tlTitle}>{item.title}</span>
+              {item.time !== undefined && <span className={css.tlTime}>{item.time}</span>}
+            </div>
+            {item.desc !== undefined && <div className={css.tlDesc}>{item.desc}</div>}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+})
+
+/** FileTree: indented tree of files and folders. Directory rows are LOCAL
+ * collapsible (spec.ts promised "collapsible children"; this makes it true)
+ * — click a dir to fold/unfold, default fully open. Zero model round trip. */
+export const FileTreeNode = memo(function FileTreeNode({ node }: { node: GenuiFileTree }) {
+  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set())
+  const pathKey = (depth: number, i: number): string => `${depth}-${i}`
+  const toggle = (k: string): void => {
+    setCollapsed(prev => {
+      const next = new Set(prev)
+      if (next.has(k)) next.delete(k)
+      else next.add(k)
+      return next
+    })
+  }
+  const renderNode = (n: GenuiFileTreeNode, depth: number, i: number): ReactNode => {
+    if (depth > GENUI_LIMITS.maxTreeDepth) return null
+    const isDir = n.type === 'dir' || (n.children !== undefined && n.children.length > 0)
+    const k = pathKey(depth, i)
+    const folded = isDir && collapsed.has(k)
+    return (
+      <div key={k} className={css.ftRow} style={{ paddingLeft: `${depth * 16}px` }}>
+        <button
+          type="button"
+          className={css.ftNameBtn}
+          aria-expanded={isDir ? !folded : undefined}
+          onClick={isDir ? () => toggle(k) : undefined}
+        >
+          <span className={`${css.ftIcon} ${isDir ? css.ftIconDir : ''}`} aria-hidden>{isDir ? (folded ? '▸' : '▾') : '·'}</span>
+          <span className={`${css.ftName} ${isDir ? css.ftDir : ''}`}>{n.name}</span>
+        </button>
+        {isDir && !folded && (n.children ?? []).map((c, ci) => renderNode(c, depth + 1, ci))}
+      </div>
+    )
+  }
+  return <div className={css.fileTree}>{node.items.slice(0, GENUI_LIMITS.maxListItems).map((n, i) => renderNode(n, 0, i))}</div>
+})
+
+/** Quiz: a self-contained teaching question. Selecting an option marks it
+ * correct/incorrect in place and reveals feedback + explanation. With
+ * `action`, the chosen answer is ALSO sent back to the model
+ * (`{type:'quiz', question, answer, correct}`) so the model can collect or
+ * grade it — the in-place judging stays local (no round trip needed). */
+export const QuizNode = memo(function QuizNode({ node, onAction }: {
+  node: GenuiQuiz
+  onAction?: GenuiBlockProps['onAction']
+}) {
+  const [selected, setSelected] = useState<number | null>(null)
+  const options = node.options.slice(0, GENUI_LIMITS.maxQuizOptions)
+  const answered = selected !== null
+  const chosen = selected === null ? undefined : options[selected]
+  const correct = chosen?.correct === true
+  const action = node.action
+  return (
+    <div className={css.quiz} data-genui-quiz>
+      <div className={css.quizQuestion}>{node.question}</div>
+      <div className={css.quizOptions}>
+        {options.map((opt, i) => {
+          const isChosen = selected === i
+          const cls = answered
+            ? isChosen
+              ? opt.correct === true ? css.quizOptCorrect : css.quizOptWrong
+              : opt.correct === true ? css.quizOptReveal : css.quizOpt
+            : css.quizOpt
+          return (
+            <button
+              key={i}
+              type="button"
+              className={cls}
+              disabled={answered}
+              onClick={() => {
+                setSelected(i)
+                if (action !== undefined && onAction !== undefined) {
+                  onAction(action, {
+                    type: 'quiz',
+                    question: node.question,
+                    answer: opt.label,
+                    correct: opt.correct === true,
+                  })
+                }
+              }}
+            >
+              <span className={css.quizMarker}>{answered && (opt.correct === true ? '✓' : isChosen ? '✗' : '')}</span>
+              {opt.label}
+            </button>
+          )
+        })}
+      </div>
+      {answered && (
+        <div className={css.quizResult} aria-live="polite">
+          <div className={correct ? css.quizCorrectMsg : css.quizWrongMsg}>
+            {correct ? '✓ 回答正确！' : '✗ 再想想看'}
+            {chosen?.feedback !== undefined && <div className={css.quizFeedback}>{chosen.feedback}</div>}
+          </div>
+          {node.explanation !== undefined && <div className={css.quizExplanation}>{node.explanation}</div>}
+          <button type="button" className={css.quizRetry} onClick={() => setSelected(null)}>重新作答</button>
+        </div>
+      )}
+    </div>
+  )
+})
+
+/** Breadcrumb: path-style navigation trail. */
+export const BreadcrumbNode = memo(function BreadcrumbNode({ node }: { node: GenuiBreadcrumb }) {
+  const items = node.items.slice(0, GENUI_LIMITS.maxBreadcrumbItems)
+  return (
+    <nav className={css.breadcrumb} aria-label="breadcrumb">
+      {items.map((item, i) => (
+        <span key={i} className={css.bcItem}>
+          <span className={`${css.bcText} ${i === items.length - 1 ? css.bcCurrent : ''}`}>{item}</span>
+          {i < items.length - 1 && <span className={css.bcSep}>/</span>}
+        </span>
+      ))}
+    </nav>
+  )
+})
+
+/**
+ * Trailing debounce window (ms) for one `[genui-action]` name: rapid
+ * repeated interactions on one control (button mashing, switch flipping)
+ * collapse into a single action with the LAST payload. Different action
+ * names stay independent. The model round-trip takes seconds, so a few
+ * hundred ms of trailing delay is imperceptible — and it stops bursts of
+ * queued user turns.
+ */

package/src/client/blocks/basic.tsx

@@ -0,0 +1,116 @@
+/**
+ * Basic display family: avatar palette, and the local click-feedback button
+ * (the actionable-button chip). Used by the render dispatcher.
+ * @module @changfenhuang/dsh-genui/client/blocks/basic
+ */
+import { memo, useEffect, useRef, useState, type ReactNode } from 'react'
+import css from '../GenuiBlock.module.css'
+import type { GenuiAudio, GenuiVideo } from '../spec.ts'
+
+/** Deterministic avatar color by name hash. Host static tokens ONLY —
+ * design system v2: no off-brand hexes, the palette always matches the
+ * theme's families (deepseek/blue/green/amber/red/neutral). */
+const AVATAR_COLORS = [
+  'var(--dsw-static-deepseek-400)',
+  'var(--dsw-static-deepseek-450)',
+  'var(--dsw-static-blue-450)',
+  'var(--dsw-static-green-400)',
+  'var(--dsw-static-amber-400)',
+  'var(--dsw-static-red-400)',
+  'var(--dsw-static-deepseek-300)',
+  'var(--dsw-static-neutral-bluish-400)',
+]
+
+export function avatarColor(name: string): string {
+  let h = 0
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0
+  // The array is a literal with 8 entries; the index is always in range.
+  return AVATAR_COLORS[h % AVATAR_COLORS.length]!
+}
+
+/** Button with LOCAL click feedback: clicking an actionable button shows a
+ * brief "✓ 已触发" chip so the user sees the click registered even while the
+ * model round trip is in flight — no more "点了没反应" perception. The chip
+ * is purely cosmetic; the action fires through `onClick` as before. */
+export function ClickFeedbackButton({ className, disabled, onClick, children }: {
+  className: string
+  disabled?: boolean
+  onClick?: (() => void) | undefined
+  children: ReactNode
+}) {
+  const [sent, setSent] = useState(false)
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  useEffect(() => {
+    return () => {
+      if (timer.current !== null) clearTimeout(timer.current)
+    }
+  }, [])
+  return (
+    <>
+      <button
+        type="button"
+        className={className}
+        disabled={disabled}
+        onClick={onClick === undefined ? undefined : () => {
+          onClick()
+          if (timer.current !== null) clearTimeout(timer.current)
+          setSent(true)
+          timer.current = setTimeout(() => setSent(false), 1400)
+        }}
+      >
+        {children}
+        {sent && <span className={css.btnSent} aria-hidden>✓ 已触发</span>}
+      </button>
+      {/* Live-region sibling: button content is atomic to screen readers, so
+       * the "已触发" confirmation announces from a hidden status region. */}
+      <span className={css.visuallyHidden} role="status">{sent ? '已触发' : ''}</span>
+    </>
+  )
+}
+
+/** Native controls intentionally own play/pause/seek/volume. Model-authored
+ * autoplay and controls hints are ignored: media starts only after the user
+ * asks for it. */
+export const AudioNode = memo(function AudioNode({ node }: { node: GenuiAudio }): ReactNode {
+  const [failed, setFailed] = useState(false)
+  return (
+    <figure className={css.media}>
+      {node.alt !== undefined && <figcaption className={css.mediaLabel}>{node.alt}</figcaption>}
+      {failed
+        ? <div className={css.mediaError} role="alert">音频无法播放</div>
+        : <audio
+            className={css.mediaPlayer}
+            src={node.src}
+            aria-label={node.alt ?? '音频'}
+            controls
+            preload="metadata"
+            loop={node.loop === true}
+            onError={() => setFailed(true)}
+          />}
+    </figure>
+  )
+})
+
+export const VideoNode = memo(function VideoNode({ node }: { node: GenuiVideo }): ReactNode {
+  const [failed, setFailed] = useState(false)
+  return (
+    <figure className={css.media}>
+      {node.alt !== undefined && <figcaption className={css.mediaLabel}>{node.alt}</figcaption>}
+      {failed
+        ? <div className={css.mediaError} role="alert">视频无法播放</div>
+        : <video
+            className={`${css.mediaPlayer} ${css.videoPlayer}`}
+            src={node.src}
+            poster={node.poster}
+            aria-label={node.alt ?? '视频'}
+            controls
+            preload="metadata"
+            playsInline
+            loop={node.loop === true}
+            muted={node.muted === true}
+            style={node.aspectRatio === undefined ? undefined : { aspectRatio: node.aspectRatio.replace(':', ' / ') }}
+            onError={() => setFailed(true)}
+          />}
+    </figure>
+  )
+})