@skopon-cool/form-sdk 0.2.5 → 0.3.1

package/src/components/AskUserFormCard.tsx

@@ -1,7 +1,10 @@
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Button, Spin, Tag, Tooltip } from 'antd'
 import type { FormDetailResult, FormSchema, SubmitMode } from '../types/index'
-import { resolveSubmitAuthHeaders } from '../client/authStorage'
+import {
+  resolveRealtimeWsUrl,
+  resolveSubmitAuthHeaders,
+} from '../client/authStorage'
 import { buildAskUserSurface } from '../adapter/resolveSurface'
 import {
   buildAnswerAgentBody,
@@ -23,6 +26,10 @@ import {
 import { validateFormSubmitValues } from '../submit/validateFormSubmit'
 import type { CaseSearchFn } from '../catalog/caseSearchContext'
 import type { ResumeSearchFn } from '../catalog/resumeSearchContext'
+import { FormRuntimeProvider, useFormRuntime } from '../runtime/formRuntimeContext'
+import { FormRuntimeWsClient } from '../runtime/formRuntimeWs'
+import { executeFormAutoControl } from '../runtime/formAutoControl'
+import type { FormAutoControlEventData } from '../runtime/types'
 import SkoponFormRenderer, { type SkoponFormRendererRef } from './SkoponFormRenderer'
 import CurlSubmitBlock from './CurlSubmitBlock'
 import SkoponFormProvider from './SkoponFormProvider'
@@ -44,6 +51,11 @@ export interface AskUserFormCardProps {
   payload: unknown
   /** 可选；无则跳过拉取 vt_forms，仅用 payload blocks fallback */
   formUniqueId?: string | null
+  /**
+   * ask_source_unique_id（Flow/QA 业务 id）。
+   * 有值且 sessionStorage.auth_user.realtime_ws_url 存在、且渲染出表单控件时按卡建连。
+   */
+  askUserMessageId?: string | null
   callbackUrl?: string | null
   submitMode?: SubmitMode
   answerAgentContext?: AskUserAnswerAgentContext
@@ -58,9 +70,15 @@ export interface AskUserFormCardProps {
   caseSearch?: CaseSearchFn | null
 }
 
-export default function AskUserFormCard({
+interface AskUserFormCardBodyProps extends AskUserFormCardProps {
+  onSurfaceReadyChange: (ready: boolean) => void
+  onAutoControlReady: (handler: ((data: FormAutoControlEventData) => void) | null) => void
+}
+
+function AskUserFormCardBody({
   payload,
   formUniqueId,
+  askUserMessageId,
   callbackUrl,
   submitMode = 'curl',
   answerAgentContext,
@@ -69,17 +87,22 @@ export default function AskUserFormCard({
   onNotify,
   resumeSearch = null,
   caseSearch = null,
-}: AskUserFormCardProps) {
+  onSurfaceReadyChange,
+  onAutoControlReady,
+}: AskUserFormCardBodyProps) {
   const [formDef, setFormDef] = useState<FormSchema | null>(null)
   const [formDisabled, setFormDisabled] = useState(false)
   const [loading, setLoading] = useState(true)
   const [submitting, setSubmitting] = useState(false)
   const rendererRef = useRef<SkoponFormRendererRef>(null)
+  const cardRootRef = useRef<HTMLDivElement>(null)
   const mountedRef = useRef(true)
   const onNotifyRef = useRef(onNotify)
   onNotifyRef.current = onNotify
+  const runtime = useFormRuntime()
 
   const resolvedFormUniqueId = formUniqueId?.trim() ?? ''
+  const resolvedAskUserMessageId = askUserMessageId?.trim() ?? ''
 
   const resolvedSubmitHeaders = useMemo(
     () => resolveSubmitAuthHeaders(submitHeaders),
@@ -180,32 +203,14 @@ export default function AskUserFormCard({
     ? `ask-user-${resolvedFormUniqueId}`
     : 'ask-user-payload'
 
-  if (loading) {
-    return (
-      <SkoponFormProvider>
-        <div className="ask-user-form-card">
-          <Spin size="small" />
-        </div>
-      </SkoponFormProvider>
-    )
-  }
+  const hasFormSurface = Boolean(!loading && payloadDef && renderBlocks.length > 0 && surfaceDoc)
 
-  if (!payloadDef || renderBlocks.length === 0) {
-    return (
-      <SkoponFormProvider>
-        <CurlSubmitBlock
-          payload={payload}
-          callbackUrl={callbackUrl}
-          answerAgentContext={resolvedAnswerAgentContext}
-          submitHeaders={submitHeaders}
-          unpublishedFormId={formDisabled && resolvedFormUniqueId ? resolvedFormUniqueId : undefined}
-          onNotify={onNotify}
-        />
-      </SkoponFormProvider>
-    )
-  }
+  useEffect(() => {
+    onSurfaceReadyChange(hasFormSurface)
+    return () => onSurfaceReadyChange(false)
+  }, [hasFormSurface, onSurfaceReadyChange])
 
-  async function handleSubmit() {
+  const handleSubmit = useCallback(async () => {
     if (submitting) return
     setSubmitting(true)
     try {
@@ -217,6 +222,12 @@ export default function AskUserFormCard({
       }
       const answer = { ...cardValues, ...extraValues }
 
+      runtime.reportData(answer)
+      runtime.reportEvent({
+        action: 'submit',
+        component: 'SubmitButton',
+      })
+
       if (submitMode === 'post') {
         const url = (callbackUrl ?? '').trim()
         if (!url) {
@@ -254,11 +265,79 @@ export default function AskUserFormCard({
     } finally {
       if (mountedRef.current) setSubmitting(false)
     }
+  }, [
+    submitting,
+    fieldNames,
+    renderBlocks,
+    extraValues,
+    runtime,
+    submitMode,
+    callbackUrl,
+    resolvedSubmitHeaders,
+    resolvedAnswerAgentContext,
+    payload,
+    formDef,
+    payloadDef,
+  ])
+
+  const handleSubmitRef = useRef(handleSubmit)
+  handleSubmitRef.current = handleSubmit
+
+  const applyAutoControl = useCallback(
+    (data: FormAutoControlEventData) => {
+      executeFormAutoControl(
+        data,
+        {
+          setValues: (values) => rendererRef.current?.setValues(values),
+          getValues: (names) => rendererRef.current?.getValues(names) ?? {},
+          submit: () => handleSubmitRef.current(),
+          rootElement: cardRootRef.current,
+        },
+        {
+          reportEvent: runtime.reportEvent,
+          runAutoControl: runtime.runAutoControl,
+        },
+      )
+    },
+    [runtime],
+  )
+
+  useEffect(() => {
+    if (!hasFormSurface) {
+      onAutoControlReady(null)
+      return
+    }
+    onAutoControlReady(applyAutoControl)
+    return () => onAutoControlReady(null)
+  }, [hasFormSurface, applyAutoControl, onAutoControlReady])
+
+  if (loading) {
+    return (
+      <div className="ask-user-form-card">
+        <Spin size="small" />
+      </div>
+    )
+  }
+
+  if (!payloadDef || renderBlocks.length === 0) {
+    return (
+      <CurlSubmitBlock
+        payload={payload}
+        callbackUrl={callbackUrl}
+        answerAgentContext={resolvedAnswerAgentContext}
+        submitHeaders={submitHeaders}
+        unpublishedFormId={formDisabled && resolvedFormUniqueId ? resolvedFormUniqueId : undefined}
+        onNotify={onNotify}
+      />
+    )
   }
 
   return (
-    <SkoponFormProvider>
-      <div className="ask-user-form-card">
+    <div
+      className="ask-user-form-card"
+      ref={cardRootRef}
+      data-ask-user-message-id={resolvedAskUserMessageId || undefined}
+    >
       {formDisabled && resolvedFormUniqueId ? (
         <div className="ask-user-form-card-status">
           <Tooltip title={resolvedFormUniqueId}>
@@ -296,7 +375,61 @@ export default function AskUserFormCard({
           </Button>
         </Tooltip>
       </div>
-      </div>
+    </div>
+  )
+}
+
+export default function AskUserFormCard(props: AskUserFormCardProps) {
+  const resolvedAskUserMessageId = props.askUserMessageId?.trim() ?? ''
+  const realtimeWsUrl = useMemo(() => resolveRealtimeWsUrl(), [])
+  const [surfaceReady, setSurfaceReady] = useState(false)
+  const [wsClient, setWsClient] = useState<FormRuntimeWsClient | null>(null)
+  const autoControlHandlerRef = useRef<((data: FormAutoControlEventData) => void) | null>(null)
+
+  const onSurfaceReadyChange = useCallback((ready: boolean) => {
+    setSurfaceReady(ready)
+  }, [])
+
+  const onAutoControlReady = useCallback(
+    (handler: ((data: FormAutoControlEventData) => void) | null) => {
+      autoControlHandlerRef.current = handler
+    },
+    [],
+  )
+
+  const shouldConnect = Boolean(
+    realtimeWsUrl && resolvedAskUserMessageId && surfaceReady,
+  )
+
+  useEffect(() => {
+    if (!shouldConnect || !realtimeWsUrl || !resolvedAskUserMessageId) {
+      setWsClient(null)
+      return
+    }
+    const client = new FormRuntimeWsClient({
+      url: realtimeWsUrl,
+      askUserMessageId: resolvedAskUserMessageId,
+      onAutoControl: (data) => {
+        autoControlHandlerRef.current?.(data)
+      },
+    })
+    client.connect()
+    setWsClient(client)
+    return () => {
+      client.close()
+      setWsClient(null)
+    }
+  }, [shouldConnect, realtimeWsUrl, resolvedAskUserMessageId])
+
+  return (
+    <SkoponFormProvider>
+      <FormRuntimeProvider client={wsClient}>
+        <AskUserFormCardBody
+          {...props}
+          onSurfaceReadyChange={onSurfaceReadyChange}
+          onAutoControlReady={onAutoControlReady}
+        />
+      </FormRuntimeProvider>
     </SkoponFormProvider>
   )
 }

package/src/components/SkoponFormRenderer.tsx

@@ -21,6 +21,7 @@ import SkoponFormProvider from './SkoponFormProvider'
 
 export interface SkoponFormRendererRef {
   getValues: (fieldNames?: string[]) => Record<string, unknown>
+  setValues: (values: Record<string, unknown>) => void
 }
 
 export interface SkoponFormRendererProps {
@@ -104,6 +105,17 @@ const SkoponFormRenderer = forwardRef<SkoponFormRendererRef, SkoponFormRendererP
           const resolvedNames = (names ?? fieldNamesRef.current).map((n) => n.trim()).filter(Boolean)
           return extractSurfaceValues(processor, surfaceId, resolvedNames)
         },
+        setValues(values) {
+          const processor = processorRef.current
+          if (!processor) return
+          const surface = processor.model.surfacesMap.get(surfaceId)
+          if (!surface) return
+          for (const [name, value] of Object.entries(values)) {
+            const trimmed = name.trim()
+            if (!trimmed) continue
+            surface.dataModel.set(`/${trimmed}`, value)
+          }
+        },
       }),
       [surfaceId],
     )

package/src/index.ts

@@ -79,12 +79,14 @@ export {
 } from './submit/submitAnswerAgent'
 export {
   resolveAnswerAgentCallbackUrl,
+  resolveRealtimeWsUrl,
   resolveSkoponAuthHeaders,
   resolveSubmitAuthHeaders,
   resolveClientHeaders,
   DEFAULT_AUTH_STORAGE_KEY,
   DEFAULT_AUTH_TOKEN_FIELD,
   DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD,
+  DEFAULT_AUTH_REALTIME_WS_URL_FIELD,
   DEFAULT_ANSWER_AGENT_CALLBACK_URL,
   type SkoponAuthStorageOptions,
   type ClientHeadersOptions,

package/src/runtime/formAutoControl.test.ts

@@ -0,0 +1,127 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { executeFormAutoControl } from './formAutoControl'
+import type { FormAutoControlEventData } from './types'
+
+/** 模拟 FormRuntimeProvider.runAutoControl：Promise settle 前保持 depth。 */
+function createDepthTrackingRunAutoControl(depthRef: { current: number }) {
+  return <T,>(fn: () => T): T => {
+    depthRef.current += 1
+    let syncResult: T
+    try {
+      syncResult = fn()
+    } catch (error) {
+      depthRef.current = Math.max(0, depthRef.current - 1)
+      throw error
+    }
+    if (
+      syncResult != null &&
+      (typeof syncResult === 'object' || typeof syncResult === 'function') &&
+      typeof (syncResult as PromiseLike<unknown>).then === 'function'
+    ) {
+      const promise = Promise.resolve(syncResult).finally(() => {
+        depthRef.current = Math.max(0, depthRef.current - 1)
+      })
+      return promise as T
+    }
+    depthRef.current = Math.max(0, depthRef.current - 1)
+    return syncResult
+  }
+}
+
+describe('executeFormAutoControl', () => {
+  it('writes values and reports bac change event', () => {
+    const setValues = vi.fn()
+    const reportEvent = vi.fn()
+    const runAutoControl = vi.fn((fn: () => unknown) => fn())
+    const data: FormAutoControlEventData = {
+      action: 'change',
+      field: 'name',
+      value: 'Alice',
+      component: 'TextField',
+    }
+    executeFormAutoControl(
+      data,
+      {
+        setValues,
+        getValues: () => ({}),
+        submit: vi.fn(),
+        rootElement: null,
+      },
+      { reportEvent, runAutoControl },
+    )
+    expect(runAutoControl).toHaveBeenCalled()
+    expect(setValues).toHaveBeenCalledWith({ name: 'Alice' })
+    expect(reportEvent).toHaveBeenCalledWith({
+      action: 'change',
+      component: 'TextField',
+      field: 'name',
+      value: 'Alice',
+    })
+  })
+
+  it('ignores change without field', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const setValues = vi.fn()
+    executeFormAutoControl(
+      { action: 'change', value: 'x' },
+      {
+        setValues,
+        getValues: () => ({}),
+        submit: vi.fn(),
+        rootElement: null,
+      },
+      { reportEvent: vi.fn(), runAutoControl: (fn) => fn() },
+    )
+    expect(setValues).not.toHaveBeenCalled()
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  it('invokes submit for submit action', () => {
+    const submit = vi.fn()
+    executeFormAutoControl(
+      { action: 'submit' },
+      {
+        setValues: vi.fn(),
+        getValues: () => ({}),
+        submit,
+        rootElement: null,
+      },
+      { reportEvent: vi.fn(), runAutoControl: (fn) => fn() },
+    )
+    expect(submit).toHaveBeenCalled()
+  })
+
+  it('keeps autoControl depth until async submit settles', async () => {
+    const depthRef = { current: 0 }
+    const runAutoControl = createDepthTrackingRunAutoControl(depthRef)
+    let resolveSubmit!: () => void
+    const submit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveSubmit = resolve
+        }),
+    )
+
+    executeFormAutoControl(
+      { action: 'submit' },
+      {
+        setValues: vi.fn(),
+        getValues: () => ({}),
+        submit,
+        rootElement: null,
+      },
+      { reportEvent: vi.fn(), runAutoControl },
+    )
+
+    expect(submit).toHaveBeenCalled()
+    expect(depthRef.current).toBe(1)
+    resolveSubmit()
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(depthRef.current).toBe(0)
+  })
+})

package/src/runtime/formAutoControl.ts

@@ -0,0 +1,110 @@
+import type { FormAutoControlEventData, FormRuntimeEventData } from './types'
+
+export interface FormAutoControlTargets {
+  setValues: (values: Record<string, unknown>) => void
+  getValues: (fieldNames?: string[]) => Record<string, unknown>
+  submit: () => void | Promise<void>
+  /** 卡片根节点，用于按 data-skopon-field 定位 DOM */
+  rootElement: HTMLElement | null
+}
+
+export interface FormAutoControlHelpers {
+  reportEvent: (event: FormRuntimeEventData) => void
+  /** 支持同步或返回 Promise（async submit 期间保持 autoControlDepth） */
+  runAutoControl: <T>(fn: () => T) => T
+}
+
+function escapeAttrSelector(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(value)
+  }
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+function focusField(root: HTMLElement | null, field: string): boolean {
+  if (!root) return false
+  const container = root.querySelector(`[data-skopon-field="${escapeAttrSelector(field)}"]`)
+  if (!(container instanceof HTMLElement)) return false
+  const focusable =
+    container.querySelector<HTMLElement>(
+      'input, textarea, select, button, [tabindex]:not([tabindex="-1"])',
+    ) ?? container
+  focusable.focus()
+  return true
+}
+
+function clickField(root: HTMLElement | null, field: string): boolean {
+  if (!root) return false
+  const container = root.querySelector(`[data-skopon-field="${escapeAttrSelector(field)}"]`)
+  if (!(container instanceof HTMLElement)) return false
+  const clickable =
+    container.querySelector<HTMLElement>(
+      'button, [role="button"], .skopon-resume-select-card, input, label',
+    ) ?? container
+  clickable.click()
+  return true
+}
+
+/** 执行下行 form_auto_control_event；缺参或未知 action 时 warn 并忽略。 */
+export function executeFormAutoControl(
+  data: FormAutoControlEventData,
+  targets: FormAutoControlTargets,
+  helpers: FormAutoControlHelpers,
+): void {
+  const action = data.action
+  if (
+    action !== 'change' &&
+    action !== 'select' &&
+    action !== 'focus' &&
+    action !== 'click' &&
+    action !== 'submit'
+  ) {
+    console.warn('[FormAutoControl] unknown action', action)
+    return
+  }
+
+  helpers.runAutoControl(() => {
+    if (action === 'submit') {
+      // 返回 Promise，使 runAutoControl 在 settle 前保持 depth
+      return targets.submit()
+    }
+
+    const field = typeof data.field === 'string' ? data.field.trim() : ''
+    if (!field) {
+      console.warn('[FormAutoControl] missing field for action', action)
+      return
+    }
+
+    const component = data.component?.trim() || 'Unknown'
+
+    if (action === 'change' || action === 'select') {
+      if (data.value === undefined) {
+        console.warn('[FormAutoControl] missing value for action', action)
+        return
+      }
+      targets.setValues({ [field]: data.value })
+      helpers.reportEvent({
+        action,
+        component,
+        field,
+        value: data.value,
+      })
+      return
+    }
+
+    if (action === 'focus') {
+      focusField(targets.rootElement, field)
+      helpers.reportEvent({
+        action: 'focus',
+        component,
+        field,
+      })
+      return
+    }
+
+    // click：由组件 onClick 打点回传（autoControlDepth 生效）
+    if (!clickField(targets.rootElement, field)) {
+      console.warn('[FormAutoControl] click target not found', field)
+    }
+  })
+}

package/src/runtime/formRuntimeContext.tsx

@@ -0,0 +1,129 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react'
+import type { FormRuntimeWsClient } from './formRuntimeWs'
+import type { FormRuntimeEventData } from './types'
+
+export interface FormRuntimeContextValue {
+  reportEvent: (event: FormRuntimeEventData) => void
+  reportData: (values: Record<string, unknown>) => void
+  /**
+   * 在自动控上下文中执行 fn。若 fn 返回 Promise，depth 保持到 settle，
+   * 使异步 submit 内的 reportEvent 仍为 form_auto_control_bac_event。
+   */
+  runAutoControl: <T>(fn: () => T) => T
+  isAutoControl: () => boolean
+}
+
+const FormRuntimeContext = createContext<FormRuntimeContextValue | null>(null)
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value != null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof (value as PromiseLike<unknown>).then === 'function'
+  )
+}
+
+const noopRuntime: FormRuntimeContextValue = {
+  reportEvent: () => {},
+  reportData: () => {},
+  runAutoControl: (fn) => fn(),
+  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
+  }
+  return out
+}
+
+export interface FormRuntimeProviderProps {
+  client: FormRuntimeWsClient | null
+  children: ReactNode
+}
+
+export function FormRuntimeProvider({
+  client,
+  children,
+}: FormRuntimeProviderProps) {
+  const autoControlDepthRef = useRef(0)
+  const clientRef = useRef(client)
+  clientRef.current = client
+
+  const reportEvent = useCallback((event: FormRuntimeEventData) => {
+    const ws = clientRef.current
+    if (!ws) return
+    const data: Record<string, unknown> = {
+      action: event.action,
+      component: event.component,
+    }
+    if (event.field !== undefined) data.field = event.field
+    if (event.value !== undefined) data.value = event.value
+    const type =
+      autoControlDepthRef.current > 0
+        ? 'form_auto_control_bac_event'
+        : 'form_runtime_event'
+    ws.send(type, data)
+  }, [])
+
+  const reportData = useCallback((values: Record<string, unknown>) => {
+    const ws = clientRef.current
+    if (!ws) return
+    ws.send('form_runtime_data', omitUndefinedValues(values))
+  }, [])
+
+  const runAutoControl = useCallback(<T,>(fn: () => T): T => {
+    autoControlDepthRef.current += 1
+    let syncResult: T
+    try {
+      syncResult = fn()
+    } catch (error) {
+      autoControlDepthRef.current = Math.max(0, autoControlDepthRef.current - 1)
+      throw error
+    }
+    if (isThenable(syncResult)) {
+      const promise = Promise.resolve(syncResult).finally(() => {
+        autoControlDepthRef.current = Math.max(0, autoControlDepthRef.current - 1)
+      })
+      return promise as T
+    }
+    autoControlDepthRef.current = Math.max(0, autoControlDepthRef.current - 1)
+    return syncResult
+  }, [])
+
+  const isAutoControl = useCallback(
+    () => autoControlDepthRef.current > 0,
+    [],
+  )
+
+  const value = useMemo(
+    (): FormRuntimeContextValue => ({
+      reportEvent,
+      reportData,
+      runAutoControl,
+      isAutoControl,
+    }),
+    [reportEvent, reportData, runAutoControl, isAutoControl],
+  )
+
+  return (
+    <FormRuntimeContext.Provider value={value}>
+      {children}
+    </FormRuntimeContext.Provider>
+  )
+}
+
+/** 无 Provider 时 no-op（表单管理端预览不受影响）。 */
+export function useFormRuntime(): FormRuntimeContextValue {
+  return useContext(FormRuntimeContext) ?? noopRuntime
+}