@skopon-cool/form-sdk 0.3.2 → 0.4.1

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)
+      }
+    }
+  }
+}

package/src/runtime/formRuntimeContext.tsx

@@ -7,11 +7,11 @@ import {
   type ReactNode,
 } from 'react'
 import type { FormRuntimeWsClient } from './formRuntimeWs'
-import type { FormRuntimeEventData } from './types'
+import type { FormRuntimeDataPayload, FormRuntimeEventData } from './types'
 
 export interface FormRuntimeContextValue {
   reportEvent: (event: FormRuntimeEventData) => void
-  reportData: (values: Record<string, unknown>) => void
+  reportData: (payload: FormRuntimeDataPayload) => void
   /**
    * 在自动控上下文中执行 fn。若 fn 返回 Promise，depth 保持到 settle，
    * 使异步 submit 内的 reportEvent 仍为 form_auto_control_bac_event。
@@ -37,14 +37,16 @@ const noopRuntime: FormRuntimeContextValue = {
   isAutoControl: () => false,
 }
 
-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
+function sanitizePayload(payload: FormRuntimeDataPayload): FormRuntimeDataPayload {
+  const form_values: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(payload.form_values ?? {})) {
+    if (value !== undefined) form_values[key] = value
+  }
+  return {
+    form_schema: payload.form_schema,
+    form_values,
+    form_change: Array.isArray(payload.form_change) ? [...payload.form_change] : [],
   }
-  return out
 }
 
 export interface FormRuntimeProviderProps {
@@ -76,10 +78,10 @@ export function FormRuntimeProvider({
     ws.send(type, data)
   }, [])
 
-  const reportData = useCallback((values: Record<string, unknown>) => {
+  const reportData = useCallback((payload: FormRuntimeDataPayload) => {
     const ws = clientRef.current
     if (!ws) return
-    ws.send('form_runtime_data', omitUndefinedValues(values))
+    ws.send('form_runtime_data', sanitizePayload(payload) as unknown as Record<string, unknown>)
   }, [])
 
   const runAutoControl = useCallback(<T,>(fn: () => T): T => {