@skopon-cool/form-sdk 0.3.1 → 0.4.0

package/src/runtime/buildFormRuntimeSnapshot.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { buildFormRuntimeSnapshot } from './buildFormRuntimeSnapshot'
+import type { FormBlock } from '../types/index'
+
+describe('buildFormRuntimeSnapshot', () => {
+  const blocks: FormBlock[] = [
+    {
+      id: 'b1',
+      type: 'text',
+      name: 'title',
+      label: '标题',
+      required: true,
+    },
+    {
+      id: 'b2',
+      type: 'select',
+      name: 'city',
+      label: '城市',
+      options: [
+        { value: 'sh', label: '上海' },
+        { value: 'bj', label: '北京' },
+      ],
+    },
+    {
+      id: 'b3',
+      type: 'resume_multiselect',
+      name: 'resumes',
+      label: '简历',
+      options: [],
+    },
+  ]
+
+  it('builds flat form_values and schema blocks', () => {
+    const snapshot = buildFormRuntimeSnapshot({
+      title: 'Ask',
+      description: 'desc',
+      blocks,
+      values: {
+        title: 'hello',
+        city: 'sh',
+        resumes: ['r1'],
+        unused: undefined,
+      },
+      formChange: [],
+    })
+    expect(snapshot.form_schema.title).toBe('Ask')
+    expect(snapshot.form_schema.description).toBe('desc')
+    expect(snapshot.form_schema.blocks).toHaveLength(3)
+    expect(snapshot.form_values).toEqual({
+      title: 'hello',
+      city: 'sh',
+      resumes: ['r1'],
+    })
+    expect(snapshot.form_change).toEqual([])
+  })
+
+  it('overrides resume/case options from live registry', () => {
+    const live = new Map([
+      [
+        'resumes',
+        [
+          { value: 'r1', label: 'Alice' },
+          { value: 'r2', label: 'Bob' },
+        ],
+      ],
+    ])
+    const snapshot = buildFormRuntimeSnapshot({
+      blocks,
+      values: { resumes: ['r1'] },
+      liveOptions: live,
+      formChange: ['resumes'],
+    })
+    const resumeBlock = snapshot.form_schema.blocks[2] as FormBlock
+    expect(resumeBlock.options).toEqual([
+      { value: 'r1', label: 'Alice' },
+      { value: 'r2', label: 'Bob' },
+    ])
+    expect(snapshot.form_change).toEqual(['resumes'])
+  })
+
+  it('does not mutate static select options via live map for other types', () => {
+    const live = new Map([['city', [{ value: 'gz', label: '广州' }]]])
+    const snapshot = buildFormRuntimeSnapshot({
+      blocks,
+      values: { city: 'sh' },
+      liveOptions: live,
+    })
+    const cityBlock = snapshot.form_schema.blocks[1] as FormBlock
+    expect(cityBlock.options).toEqual([
+      { value: 'sh', label: '上海' },
+      { value: 'bj', label: '北京' },
+    ])
+  })
+})

package/src/runtime/buildFormRuntimeSnapshot.ts

@@ -0,0 +1,61 @@
+import type { FormBlock, FormBlockOption } from '../types/index'
+import type { FormRuntimeDataPayload } from './types'
+
+export type LiveOptionsMap = ReadonlyMap<string, FormBlockOption[]>
+
+function omitUndefinedValues(
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined) out[key] = value
+  }
+  return out
+}
+
+function applyLiveOptions(
+  block: FormBlock,
+  liveOptions: LiveOptionsMap | undefined,
+): FormBlock {
+  const name = block.name?.trim()
+  if (!name || !liveOptions) return { ...block }
+  const live = liveOptions.get(name)
+  if (!live) return { ...block }
+  if (block.type !== 'resume_multiselect' && block.type !== 'case_multiselect') {
+    return { ...block }
+  }
+  return { ...block, options: live.map((opt) => ({ ...opt })) }
+}
+
+export interface BuildFormRuntimeSnapshotInput {
+  title?: string
+  description?: string
+  blocks: FormBlock[]
+  values: Record<string, unknown>
+  liveOptions?: LiveOptionsMap
+  formChange?: string[]
+}
+
+/**
+ * 构建 form_runtime_data 快照：form_schema（block 格式）+ 扁平 form_values + form_change。
+ */
+export function buildFormRuntimeSnapshot(
+  input: BuildFormRuntimeSnapshotInput,
+): FormRuntimeDataPayload {
+  const blocks = (input.blocks ?? []).map((block) =>
+    applyLiveOptions(block, input.liveOptions),
+  )
+  const form_schema: FormRuntimeDataPayload['form_schema'] = {
+    blocks,
+  }
+  const title = input.title?.trim()
+  const description = input.description?.trim()
+  if (title) form_schema.title = title
+  if (description) form_schema.description = description
+
+  return {
+    form_schema,
+    form_values: omitUndefinedValues(input.values ?? {}),
+    form_change: [...(input.formChange ?? [])],
+  }
+}

package/src/runtime/formLiveOptionsContext.tsx

@@ -0,0 +1,118 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import type { FormBlockOption } from '../types/index'
+
+export type PublishLiveOptionsFn = (
+  fieldName: string,
+  options: FormBlockOption[],
+) => void
+
+export interface FormLiveOptionsContextValue {
+  publishLiveOptions: PublishLiveOptionsFn
+  /** 当前 live options 的不可变快照（供读取）。 */
+  liveOptions: ReadonlyMap<string, FormBlockOption[]>
+  /** 最近一次签名变化导致的变更字段（debounce 归集前由 Provider 消费后清空）。 */
+  pendingChangeFields: readonly string[]
+  /** 版本号：live options 有实质变更时递增，用于触发上报 effect。 */
+  version: number
+  clearPendingChangeFields: () => void
+}
+
+const FormLiveOptionsContext = createContext<FormLiveOptionsContextValue | null>(
+  null,
+)
+
+function optionsSignature(options: FormBlockOption[]): string {
+  try {
+    return JSON.stringify(options)
+  } catch {
+    return String(options.length)
+  }
+}
+
+const noopLiveOptions: FormLiveOptionsContextValue = {
+  publishLiveOptions: () => {},
+  liveOptions: new Map(),
+  pendingChangeFields: [],
+  version: 0,
+  clearPendingChangeFields: () => {},
+}
+
+export interface FormLiveOptionsProviderProps {
+  children: ReactNode
+}
+
+export function FormLiveOptionsProvider({ children }: FormLiveOptionsProviderProps) {
+  const optionsRef = useRef(new Map<string, FormBlockOption[]>())
+  const signaturesRef = useRef(new Map<string, string>())
+  const pendingRef = useRef<string[]>([])
+  const [version, setVersion] = useState(0)
+  const [liveOptions, setLiveOptions] = useState<
+    ReadonlyMap<string, FormBlockOption[]>
+  >(() => new Map())
+  const [pendingChangeFields, setPendingChangeFields] = useState<readonly string[]>(
+    [],
+  )
+
+  const publishLiveOptions = useCallback(
+    (fieldName: string, options: FormBlockOption[]) => {
+      const name = fieldName.trim()
+      if (!name) return
+      const next = options.map((opt) => ({
+        value: String(opt.value ?? ''),
+        label: String(opt.label ?? opt.value ?? ''),
+      }))
+      const sig = optionsSignature(next)
+      if (signaturesRef.current.get(name) === sig) return
+      signaturesRef.current.set(name, sig)
+      optionsRef.current.set(name, next)
+      if (!pendingRef.current.includes(name)) {
+        pendingRef.current = [...pendingRef.current, name]
+      }
+      setLiveOptions(new Map(optionsRef.current))
+      setPendingChangeFields(pendingRef.current)
+      setVersion((v) => v + 1)
+    },
+    [],
+  )
+
+  const clearPendingChangeFields = useCallback(() => {
+    pendingRef.current = []
+    setPendingChangeFields([])
+  }, [])
+
+  const value = useMemo(
+    (): FormLiveOptionsContextValue => ({
+      publishLiveOptions,
+      liveOptions,
+      pendingChangeFields,
+      version,
+      clearPendingChangeFields,
+    }),
+    [
+      publishLiveOptions,
+      liveOptions,
+      pendingChangeFields,
+      version,
+      clearPendingChangeFields,
+    ],
+  )
+
+  return (
+    <FormLiveOptionsContext.Provider value={value}>
+      {children}
+    </FormLiveOptionsContext.Provider>
+  )
+}
+
+/** 无 Provider 时 no-op（编辑器预览不受影响）。 */
+export function useFormLiveOptions(): FormLiveOptionsContextValue {
+  return useContext(FormLiveOptionsContext) ?? noopLiveOptions
+}

package/src/runtime/formRuntimeConnection.test.ts

@@ -0,0 +1,155 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  acquireFormRuntimeConnection,
+  resetFormRuntimeConnectionsForTests,
+} from './formRuntimeConnection'
+import { FormRuntimeWsClient } from './formRuntimeWs'
+
+type WsListener = (event?: { data?: unknown }) => void
+
+class MockWebSocket {
+  static OPEN = 1
+  static CONNECTING = 0
+  static CLOSING = 2
+  static CLOSED = 3
+  static instances: MockWebSocket[] = []
+
+  readyState = MockWebSocket.CONNECTING
+  onopen: WsListener | null = null
+  onmessage: WsListener | null = null
+  onclose: WsListener | null = null
+  onerror: WsListener | null = null
+  sent: string[] = []
+  url: string
+
+  constructor(url: string) {
+    this.url = url
+    MockWebSocket.instances.push(this)
+    queueMicrotask(() => {
+      this.readyState = MockWebSocket.OPEN
+      this.onopen?.()
+    })
+  }
+
+  send(data: string): void {
+    this.sent.push(data)
+  }
+
+  close(): void {
+    this.readyState = MockWebSocket.CLOSED
+    this.onclose?.()
+  }
+
+  /** 模拟服务端推送。 */
+  emitMessage(data: string): void {
+    this.onmessage?.({ data })
+  }
+}
+
+describe('FormRuntimeConnection singleton', () => {
+  beforeEach(() => {
+    MockWebSocket.instances = []
+    vi.stubGlobal('WebSocket', MockWebSocket)
+    resetFormRuntimeConnectionsForTests()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    resetFormRuntimeConnectionsForTests()
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  it('reuses one socket per URL across sessions', async () => {
+    const a = new FormRuntimeWsClient({
+      url: 'ws://test/runtime',
+      askUserMessageId: 'flow-a',
+    })
+    const b = new FormRuntimeWsClient({
+      url: 'ws://test/runtime',
+      askUserMessageId: 'flow-b',
+    })
+    a.connect()
+    b.connect()
+    await vi.runAllTimersAsync()
+    expect(MockWebSocket.instances).toHaveLength(1)
+    a.close()
+    b.close()
+  })
+
+  it('routes inbound auto_control by ask_user_message_id', async () => {
+    const onA = vi.fn()
+    const onB = vi.fn()
+    const a = new FormRuntimeWsClient({
+      url: 'ws://test/runtime',
+      askUserMessageId: 'id-a',
+      onAutoControl: onA,
+    })
+    const b = new FormRuntimeWsClient({
+      url: 'ws://test/runtime',
+      askUserMessageId: 'id-b',
+      onAutoControl: onB,
+    })
+    a.connect()
+    await vi.runAllTimersAsync()
+    const ws = MockWebSocket.instances[0]
+    ws.emitMessage(
+      JSON.stringify({
+        type: 'form_auto_control_event',
+        ask_user_message_id: 'id-a',
+        data: { action: 'change', field: 'name', value: 'x' },
+      }),
+    )
+    expect(onA).toHaveBeenCalledTimes(1)
+    expect(onB).not.toHaveBeenCalled()
+    a.close()
+    b.close()
+  })
+
+  it('tags outbound messages with ask_user_message_id', async () => {
+    const client = new FormRuntimeWsClient({
+      url: 'ws://test/runtime',
+      askUserMessageId: 'flow-x',
+    })
+    client.connect()
+    await vi.runAllTimersAsync()
+    client.send('form_runtime_data', {
+      form_schema: { blocks: [] },
+      form_values: {},
+      form_change: [],
+    })
+    const ws = MockWebSocket.instances[0]
+    expect(ws.sent).toHaveLength(1)
+    const parsed = JSON.parse(ws.sent[0]) as {
+      type: string
+      ask_user_message_id: string
+      data: Record<string, unknown>
+    }
+    expect(parsed.type).toBe('form_runtime_data')
+    expect(parsed.ask_user_message_id).toBe('flow-x')
+    expect(parsed.data.form_change).toEqual([])
+    client.close()
+  })
+
+  it('keeps connection during release grace period', async () => {
+    const conn = acquireFormRuntimeConnection('ws://test/grace')
+    conn.connect()
+    await vi.runAllTimersAsync()
+    expect(MockWebSocket.instances).toHaveLength(1)
+    conn.release()
+    // still within grace
+    vi.advanceTimersByTime(500)
+    expect(MockWebSocket.instances[0].readyState).toBe(MockWebSocket.OPEN)
+    // re-acquire cancels teardown
+    const again = acquireFormRuntimeConnection('ws://test/grace')
+    expect(again).toBe(conn)
+    vi.advanceTimersByTime(2000)
+    expect(MockWebSocket.instances[0].readyState).toBe(MockWebSocket.OPEN)
+    again.release()
+    vi.advanceTimersByTime(1600)
+    expect(MockWebSocket.instances[0].readyState).toBe(MockWebSocket.CLOSED)
+  })
+})

package/src/runtime/formRuntimeConnection.ts

@@ -0,0 +1,251 @@
+import type {
+  FormAutoControlEventData,
+  FormRuntimeEnvelope,
+  FormRuntimeOutboundType,
+} from './types'
+
+const SEND_QUEUE_MAX = 100
+const RECONNECT_MAX_MS = 30_000
+const RELEASE_GRACE_MS = 1_500
+
+export type FormAutoControlHandler = (
+  data: FormAutoControlEventData,
+  envelope: FormRuntimeEnvelope<FormAutoControlEventData>,
+) => void
+
+const connections = new Map<string, FormRuntimeConnection>()
+
+/** 测试用：清空所有单例连接。 */
+export function resetFormRuntimeConnectionsForTests(): void {
+  for (const conn of connections.values()) {
+    conn.forceClose()
+  }
+  connections.clear()
+}
+
+export function acquireFormRuntimeConnection(url: string): FormRuntimeConnection {
+  const trimmed = url.trim()
+  let conn = connections.get(trimmed)
+  if (!conn) {
+    conn = new FormRuntimeConnection(trimmed)
+    connections.set(trimmed, conn)
+  }
+  conn.acquire()
+  return conn
+}
+
+export class FormRuntimeConnection {
+  private readonly url: string
+  private ws: WebSocket | null = null
+  private refCount = 0
+  private connectRequested = false
+  private reconnectAttempt = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private releaseTimer: ReturnType<typeof setTimeout> | null = null
+  private sendQueue: string[] = []
+  private readonly handlers = new Map<string, Set<FormAutoControlHandler>>()
+
+  constructor(url: string) {
+    this.url = url
+  }
+
+  acquire(): void {
+    this.refCount += 1
+    this.clearReleaseTimer()
+  }
+
+  release(): void {
+    this.refCount = Math.max(0, this.refCount - 1)
+    if (this.refCount > 0) return
+    this.clearReleaseTimer()
+    this.releaseTimer = setTimeout(() => {
+      this.releaseTimer = null
+      if (this.refCount > 0) return
+      this.teardown()
+      if (connections.get(this.url) === this) {
+        connections.delete(this.url)
+      }
+    }, RELEASE_GRACE_MS)
+  }
+
+  /** 强制关闭（测试用），跳过宽限期。 */
+  forceClose(): void {
+    this.refCount = 0
+    this.teardown()
+    if (connections.get(this.url) === this) {
+      connections.delete(this.url)
+    }
+  }
+
+  subscribe(askUserMessageId: string, handler: FormAutoControlHandler): () => void {
+    const id = askUserMessageId.trim()
+    if (!id) return () => {}
+    let set = this.handlers.get(id)
+    if (!set) {
+      set = new Set()
+      this.handlers.set(id, set)
+    }
+    set.add(handler)
+    return () => {
+      const current = this.handlers.get(id)
+      if (!current) return
+      current.delete(handler)
+      if (current.size === 0) this.handlers.delete(id)
+    }
+  }
+
+  /** 懒建连：首个会话 connect() 时才真正打开 socket。 */
+  connect(): void {
+    if (typeof WebSocket === 'undefined') return
+    this.connectRequested = true
+    if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)) {
+      return
+    }
+    this.openSocket()
+  }
+
+  send(
+    askUserMessageId: string,
+    type: FormRuntimeOutboundType,
+    data: Record<string, unknown>,
+  ): void {
+    if (this.refCount <= 0 && !this.connectRequested) return
+    const payload: FormRuntimeEnvelope = {
+      type,
+      ask_user_message_id: askUserMessageId,
+      data,
+    }
+    let serialized: string
+    try {
+      serialized = JSON.stringify(payload)
+    } catch (error) {
+      console.warn('[FormRuntimeConnection] serialize failed', error)
+      return
+    }
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(serialized)
+      return
+    }
+    this.enqueue(serialized)
+  }
+
+  private openSocket(): void {
+    if (!this.connectRequested || this.refCount <= 0) return
+    this.clearReconnectTimer()
+    this.disposeSocket()
+    try {
+      const ws = new WebSocket(this.url)
+      this.ws = ws
+      ws.onopen = () => {
+        this.reconnectAttempt = 0
+        this.flushQueue()
+      }
+      ws.onmessage = (event) => {
+        this.handleMessage(event.data)
+      }
+      ws.onclose = () => {
+        if (this.ws === ws) this.ws = null
+        this.scheduleReconnect()
+      }
+      ws.onerror = () => {
+        // onclose will follow
+      }
+    } catch (error) {
+      console.warn('[FormRuntimeConnection] connect failed', error)
+      this.scheduleReconnect()
+    }
+  }
+
+  private teardown(): void {
+    this.connectRequested = false
+    this.clearReconnectTimer()
+    this.clearReleaseTimer()
+    this.sendQueue = []
+    this.handlers.clear()
+    this.disposeSocket()
+  }
+
+  private disposeSocket(): void {
+    if (!this.ws) return
+    this.ws.onopen = null
+    this.ws.onmessage = null
+    this.ws.onclose = null
+    this.ws.onerror = null
+    try {
+      this.ws.close()
+    } catch {
+      // ignore
+    }
+    this.ws = null
+  }
+
+  private enqueue(serialized: string): void {
+    this.sendQueue.push(serialized)
+    while (this.sendQueue.length > SEND_QUEUE_MAX) {
+      this.sendQueue.shift()
+    }
+  }
+
+  private flushQueue(): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return
+    const pending = this.sendQueue
+    this.sendQueue = []
+    for (const item of pending) {
+      this.ws.send(item)
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.connectRequested || this.refCount <= 0) return
+    this.clearReconnectTimer()
+    const delay = Math.min(
+      RECONNECT_MAX_MS,
+      1000 * 2 ** Math.min(this.reconnectAttempt, 5),
+    )
+    this.reconnectAttempt += 1
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.openSocket()
+    }, delay)
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer != null) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+  }
+
+  private clearReleaseTimer(): void {
+    if (this.releaseTimer != null) {
+      clearTimeout(this.releaseTimer)
+      this.releaseTimer = null
+    }
+  }
+
+  private handleMessage(raw: unknown): void {
+    if (typeof raw !== 'string') return
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw)
+    } catch {
+      return
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return
+    const envelope = parsed as FormRuntimeEnvelope<FormAutoControlEventData>
+    if (envelope.type !== 'form_auto_control_event') return
+    const id = String(envelope.ask_user_message_id ?? '').trim()
+    if (!id) return
+    const data = envelope.data
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return
+    const set = this.handlers.get(id)
+    if (!set || set.size === 0) return
+    for (const handler of [...set]) {
+      try {
+        handler(data, envelope)
+      } catch (error) {
+        console.warn('[FormRuntimeConnection] handler error', error)
+      }
+    }
+  }
+}