@changfenhuang/dsh-genui 0.9.1

package/src/client/blocks/render-node.tsx

@@ -0,0 +1,260 @@
+/**
+ * The recursive render dispatcher: maps the white-listed GenuiNode union to
+ * concrete components. Leaf cases render inline; compound families live in
+ * the sibling block modules. Depth-guarded against pathological specs.
+ * @module @changfenhuang/dsh-genui/client/blocks/render-node
+ */
+import { type ReactNode, type ComponentType } from 'react'
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
+import css from '../GenuiBlock.module.css'
+import { GENUI_LIMITS } from '../guard.ts'
+import type { GenuiList, GenuiNode } from '../spec.ts'
+import type { AnswersState, GenuiBlockProps } from './state.ts'
+import { AudioNode, avatarColor, ClickFeedbackButton, VideoNode } from './basic.tsx'
+import { ChartNode, TableNode } from './charts.tsx'
+import {
+  InputNode, RadioNode, SelectNode, SliderNode, SubmitNode, SwitchNode, TextareaNode,
+} from './forms.tsx'
+import {
+  AccordionNode, BreadcrumbNode, CalloutNode, CodeNode, CopyNode, DiffNode, FileTreeNode, JsonNode, KeyValueNode,
+  MermaidNode, PlotNode, QuizNode, Scene3DNode, StepsNode, TabsNode, TimelineNode,
+} from './advanced.tsx'
+import { DiagramNode } from './diagram/index.tsx'
+
+import { EChartNode } from '../EChartNode.tsx'
+
+/** Custom node data shape (declared locally: pristine hosts export no type). */
+interface GenuiCustomNode {
+  type: string
+  [key: string]: unknown
+}
+
+/** Props a registered custom renderer receives. */
+interface GenuiCustomProps {
+  node: GenuiCustomNode
+  onAction?: GenuiBlockProps['onAction']
+  renderChildren: (nodes: unknown[], keyBase: string) => unknown
+}
+
+/** Custom-component registry lookup, feature-detected (contract hosts only). */
+type HostGenuiExt = {
+  getGenuiComponent?: (type: string) => ComponentType<GenuiCustomProps> | undefined
+}
+const getGenuiComponent = (primitives as unknown as HostGenuiExt).getGenuiComponent
+
+function isListItemNode(item: GenuiList['items'][number]): item is GenuiNode {
+  return typeof item === 'object' && item !== null && 'type' in item
+}
+
+export function renderNode(
+  node: GenuiNode,
+  key: number,
+  onAction: GenuiBlockProps['onAction'] | undefined,
+  depth = 0,
+  answers?: AnswersState,
+): ReactNode {
+  // Depth guard: a pathological spec must never recurse past the limit
+  // (stack overflow / DOM explosion). The fence path already repairs specs
+  // against the same limit; this is the belt-and-suspenders for direct
+  // GenuiBlock use and plugin-registered custom renderers.
+  if (depth > GENUI_LIMITS.maxDepth) return null
+  switch (node.type) {
+    case 'text': {
+      const size = node.size ?? 'body'
+      return (
+        <div key={key} className={`${css.text} ${css[size]}` + (node.center ? ` ${css.center}` : '')}>
+          {node.content}
+        </div>
+      )
+    }
+    case 'row': {
+      return (
+        <div key={key} className={css.row + (node.wrap ? ` ${css.wrap}` : '')}>
+          {node.items.map((c, i) => renderNode(c, i, onAction, depth + 1, answers))}
+          {node.spacer && <div className={css.spacer} />}
+        </div>
+      )
+    }
+    case 'col': {
+      return (
+        <div key={key} className={css.col} style={node.gap !== undefined ? { gap: `${node.gap}px` } : undefined}>
+          {node.items.map((c, i) => renderNode(c, i, onAction, depth + 1, answers))}
+        </div>
+      )
+    }
+    case 'grid': {
+      return (
+        <div key={key} className={css.grid} style={{ gridTemplateColumns: `repeat(${Math.max(1, node.cols)}, minmax(0, 1fr))` }}>
+          {node.items.map((c, i) => renderNode(c, i, onAction, depth + 1, answers))}
+        </div>
+      )
+    }
+    case 'card': {
+      return (
+        <div key={key} className={css.card}>
+          {node.title !== undefined && <div className={css.cardTitle}>{node.title}</div>}
+          {node.items.map((c, i) => renderNode(c, i, onAction, depth + 1, answers))}
+        </div>
+      )
+    }
+    case 'button': {
+      const tone = node.tone ?? ''
+      const cls = `${css.button} ${css[tone] || ''}` + (node.full ? ` ${css.full}` : '') + (node.small ? ` ${css.small}` : '')
+      const action = node.action
+      // A button without an action (or without an action provider) is a
+      // display-only control: render it DISABLED so the affordance is honest
+      // — clickable-looking dead buttons were the top complaint in the field.
+      const interactive = action !== undefined && onAction !== undefined
+      return (
+        <ClickFeedbackButton
+          key={key}
+          className={cls}
+          disabled={!interactive}
+          onClick={interactive ? () => onAction(action, { type: 'button', label: node.label }) : undefined}
+        >
+          {node.icon !== undefined && <span aria-hidden>{node.icon} </span>}
+          {node.label}
+        </ClickFeedbackButton>
+      )
+    }
+    case 'input': return <InputNode key={key} node={node} onAction={onAction} answers={answers} />
+    case 'select': return <SelectNode key={key} node={node} onAction={onAction} answers={answers} />
+    case 'checkbox': {
+      const action = node.action
+      return (
+        <label key={key} className={css.checkbox}>
+          <input
+            type="checkbox"
+            defaultChecked={node.checked === true}
+            onChange={action !== undefined && onAction !== undefined
+              ? e => onAction(action, { type: 'checkbox', checked: e.currentTarget.checked })
+              : undefined}
+          />
+          <span>{node.label}</span>
+        </label>
+      )
+    }
+    case 'link': {
+      // Honest affordance: with a whitelisted href this is a REAL anchor;
+      // without one it is plain styled text (a dead clickable-looking button
+      // was the same complaint class as the disabled-button fix).
+      const href = node.href
+      return href !== undefined
+        ? <a key={key} className={css.link} href={href} target="_blank" rel="noopener noreferrer">{node.label}</a>
+        : <span key={key} className={css.linkText}>{node.label}</span>
+    }
+    case 'audio': return <AudioNode key={`${key}:${node.src}`} node={node} />
+    case 'video': return <VideoNode key={`${key}:${node.src}`} node={node} />
+    case 'badge': {
+      const tone = node.tone ?? ''
+      return (
+        <span key={key} className={`${css.badge} ${css[tone] || ''}`}>
+          {node.icon !== undefined && <span aria-hidden>{node.icon} </span>}
+          {node.label}
+        </span>
+      )
+    }
+    case 'stat': {
+      const down = node.delta !== undefined && node.delta.startsWith('-')
+      return (
+        <div key={key} className={css.stat}>
+          <span className={css.statLabel}>{node.label}</span>
+          <span className={css.statValue}>{node.value}</span>
+          {node.delta !== undefined && <span className={`${css.statDelta} ${down ? css.down : css.up}`}>{node.delta}</span>}
+        </div>
+      )
+    }
+    case 'progress': {
+      const v = Math.max(0, Math.min(100, Number(node.value) || 0))
+      return (
+        <div
+          key={key}
+          className={css.progress}
+          role="progressbar"
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={v}
+          aria-label={node.label ?? node.valueLabel ?? undefined}
+        >
+          {(node.label !== undefined || node.valueLabel !== undefined) && (
+            <div className={css.progressRow}>
+              <span>{node.label}</span>
+              {node.valueLabel !== undefined && <span>{node.valueLabel}</span>}
+            </div>
+          )}
+          <div className={css.track}><div className={css.fill} style={{ width: `${v}%` }} /></div>
+        </div>
+      )
+    }
+    case 'divider': return <hr key={key} className={css.divider} />
+    case 'list': {
+      const items = node.items.slice(0, GENUI_LIMITS.maxListItems)
+      return (
+        <div key={key} className={css.list}>
+          {items.map((item, i) => (
+            <div key={i} className={css.li}>
+              {isListItemNode(item)
+                ? renderNode(item, i, onAction, depth + 1, answers)
+                : <><span className={css.liTitle}>{typeof item === 'string' ? item : item.title}</span>{typeof item !== 'string' && item.desc !== undefined && <span className={css.liDesc}>{item.desc}</span>}</>}
+            </div>
+          ))}
+        </div>
+      )
+    }
+    case 'table': return <TableNode key={key} node={node} />
+    case 'chart': return <ChartNode key={key} chart={node} />
+    case 'tabs': return <TabsNode key={key} tabs={node} onAction={onAction} depth={depth + 1} answers={answers} />
+    case 'avatar': {
+      return (
+        <div key={key} className={css.avatar} style={{ background: node.color ?? avatarColor(node.name) }}>
+          {node.name.slice(0, 1).toUpperCase()}
+        </div>
+      )
+    }
+    case 'spacer': return <div key={key} className={css.spacer} />
+    case 'plot': return <PlotNode key={key} plot={node} />
+    case 'callout': return <CalloutNode key={key} node={node} />
+    case 'steps': return <StepsNode key={key} steps={node} />
+    case 'keyvalue': return <KeyValueNode key={key} node={node} />
+    case 'diff': return <DiffNode key={key} node={node} />
+    case 'json': return <JsonNode key={key} node={node} />
+    case 'code': return <CodeNode key={key} node={node} />
+    case 'radio': return <RadioNode key={`${key}:r${answers?.round ?? 0}`} node={node} onAction={onAction} answers={answers} />
+    case 'submit': return <SubmitNode key={key} node={node} onAction={onAction} answers={answers} />
+    case 'switch': return <SwitchNode key={key} node={node} onAction={onAction} />
+    case 'slider': return <SliderNode key={key} node={node} onAction={onAction} answers={answers} />
+    case 'textarea': return <TextareaNode key={key} node={node} onAction={onAction} answers={answers} />
+    case 'accordion': return <AccordionNode key={key} node={node} onAction={onAction} depth={depth + 1} answers={answers} />
+    case 'copy': return <CopyNode key={key} node={node} />
+    case 'mermaid': return <MermaidNode key={key} node={node} />
+    case 'scene3d': return <Scene3DNode key={key} node={node} />
+    case 'timeline': return <TimelineNode key={key} node={node} />
+    case 'file-tree': return <FileTreeNode key={key} node={node} />
+    case 'breadcrumb': return <BreadcrumbNode key={key} node={node} />
+    case 'quiz': return <QuizNode key={key} node={node} onAction={onAction} />
+    case 'diagram': return <DiagramNode key={key} node={node} />
+
+    case 'echart': return <EChartNode key={key} node={node} />
+    default: {
+      // Plugin-registered custom types: a plugin ships a renderer through
+      // registerGenuiComponent; unregistered unknowns render nothing. The
+      // spec union is exhaustive, so an unknown node arrives as a plugin
+      // extension — treat it as a generic data node.
+      const custom = node as unknown as GenuiCustomNode
+      const Custom = getGenuiComponent?.(custom.type)
+      if (Custom !== undefined) {
+        return (
+          <Custom
+            key={key}
+            node={custom}
+            onAction={onAction}
+            renderChildren={(nodes, base) => nodes.map((c, i) => renderNode(c as GenuiNode, Number(base) + i, onAction, depth + 1, answers))}
+          />
+        )
+      }
+      return null
+    }
+  }
+}
+
+/* ---------------- v1.1 nodes ---------------- */

package/src/client/blocks/state.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared block-level state types: the block props contract and the answers
+ * registry (grouped radios → submit grading). Lives OUTSIDE GenuiBlock.tsx so
+ * the per-family block modules can import the types without a cycle back
+ * into the block shell.
+ * @module @changfenhuang/dsh-genui/client/blocks/state
+ */
+import type { GenuiSpec } from '../spec.ts'
+
+export interface GenuiBlockProps {
+  /** Parsed spec to render. */
+  spec: GenuiSpec
+  /**
+   * v2: optional action callback. Interactive components carrying an
+   * `action` field fire it (button click, switch toggle, form submit);
+   * absent = components are display-only (v1 behavior).
+   */
+  onAction?: ((action: string, payload: Record<string, unknown>) => void) | undefined
+  /**
+   * v2.7: durable-state key (session + slot + content fingerprint). When set,
+   * interaction state (radio answers, submit lock, field values) persists to
+   * localStorage and restores on refresh / re-render of the same content.
+   */
+  stateKey?: string | undefined
+}
+
+/** Per-question metadata registered by grouped radios for local grading. */
+export interface QuestionMeta {
+  label: string
+  options: string[]
+  /** Correct option: index (number) or label (string); absent = no local grading. */
+  answer?: number | string | undefined
+  /** Shown after local grading. */
+  explanation?: string | undefined
+}
+
+/** Block-wide answers registry (v2.5/v2.6): grouped radios record selections
+ * and register their question metadata here; a sibling `submit` node either
+ * grades IN PLACE (questions carry `answer` data) or collects everything
+ * into ONE action. Lives in GenuiBlock state so re-renders keep the
+ * selections, threaded down through the recursive render walk. Answers are
+ * plain group → chosen-option-label strings (the display label lives in
+ * QuestionMeta; localStorage stores the same string table — no migration). */
+export interface AnswersState {
+  answers: Record<string, string>
+  /** Field values by id (input/textarea with an `id`), collected by submit. */
+  fields: Record<string, string>
+  /** Field ids whose value must never be persisted or collected (secrets). */
+  secretFields: ReadonlySet<string>
+  meta: Record<string, QuestionMeta>
+  /** True after a local grading: questions are locked until 重新作答. */
+  locked: boolean
+  /** Bumped by every reset; radios use it as their remount key. */
+  round: number
+  setAnswer: (group: string, choice: string) => void
+  setField: (id: string, value: string) => void
+  registerSecretField: (id: string) => void
+  registerMeta: (group: string, meta: QuestionMeta) => void
+  clear: () => void
+  setLocked: (locked: boolean) => void
+}