@changfenhuang/dsh-genui 0.11.2 → 0.11.4

package/src/client/submission-registry.ts

@@ -0,0 +1,150 @@
+import { GENUI_LIMITS } from './genui-runtime/index.ts'
+import type { GenuiSpec } from './spec.ts'
+import { walkGenuiNodes } from './walk-spec.ts'
+
+export type SubmissionMember = RadioSubmissionMember | CheckboxSubmissionMember | FieldSubmissionMember
+
+export interface RadioSubmissionMember {
+  kind: 'radio'
+  key: string
+  label: string
+  options: string[]
+  answer?: number | string
+  explanation?: string
+}
+
+export interface CheckboxSubmissionMember {
+  kind: 'checkbox'
+  key: string
+}
+
+export interface FieldSubmissionMember {
+  kind: 'field'
+  key: string
+  fieldType: 'input' | 'textarea' | 'select' | 'slider'
+  secret: boolean
+}
+
+export interface SubmissionRegistry {
+  members: ReadonlyMap<string, SubmissionMember>
+}
+
+export interface SubmitInteractionState {
+  answers: Record<string, string>
+  multiAnswers: Record<string, string[]>
+  fields: Record<string, string>
+  secretFields: ReadonlySet<string>
+}
+
+export interface ResolvedSubmitState {
+  scope: SubmissionMember[]
+  answered: number
+  total: number
+  localGradeEligible: boolean
+  hasOutOfScopePayload: boolean
+}
+
+/** 从 spec 建立成员表，并诊断 submission key 和 submit.groups。 */
+export function analyzeSubmissionRegistry(spec: GenuiSpec): { registry: SubmissionRegistry; diagnostics: string[] } {
+  const members = new Map<string, SubmissionMember>()
+  const paths = new Map<string, string>()
+  const diagnostics: string[] = []
+  const submits: Array<{ groups: string[]; path: string }> = []
+
+  walkGenuiNodes(spec, (node, path) => {
+    if (node.type === 'submit') {
+      if (node.groups !== undefined) submits.push({ groups: node.groups, path })
+      return
+    }
+    let member: SubmissionMember | undefined
+    let keyPath: string
+    switch (node.type) {
+      case 'radio':
+        if (node.group === undefined) return
+        member = { kind: 'radio', key: node.group, label: node.label ?? node.group, options: node.options.slice(0, GENUI_LIMITS.maxOptions), ...(node.answer === undefined ? {} : { answer: node.answer }), ...(node.explanation === undefined ? {} : { explanation: node.explanation }) }
+        keyPath = `${path}.group`
+        break
+      case 'checkbox':
+        if (node.group === undefined) return
+        member = { kind: 'checkbox', key: node.group }
+        keyPath = `${path}.group`
+        break
+      case 'input':
+      case 'textarea':
+      case 'select':
+      case 'slider':
+        if (node.id === undefined) return
+        member = { kind: 'field', key: node.id, fieldType: node.type, secret: node.type === 'input' && node.inputType === 'password' }
+        keyPath = `${path}.id`
+        break
+      default:
+        return
+    }
+    if (member === undefined) return
+    const existing = members.get(member.key)
+    if (existing !== undefined) {
+      if (existing.kind !== 'checkbox' || member.kind !== 'checkbox') {
+        diagnostics.push(`${keyPath} conflicts with ${paths.get(member.key)}: submission key '${member.key}' is already used`)
+      }
+      return
+    }
+    members.set(member.key, member)
+    paths.set(member.key, keyPath)
+  })
+
+  for (const { groups, path } of submits) {
+    const seen = new Set<string>()
+    groups.forEach((key, index) => {
+      const at = `${path}.groups[${index}]`
+      if (seen.has(key)) diagnostics.push(`${at}: duplicate submission member '${key}'`)
+      seen.add(key)
+      const member = members.get(key)
+      if (member === undefined) diagnostics.push(`${at}: submit.groups references unknown submission member '${key}'`)
+      else if (member.kind === 'field' && member.secret) diagnostics.push(`${at}: submit.groups cannot require secret field '${key}'`)
+    })
+  }
+  return { registry: { members }, diagnostics }
+}
+
+/** 编译供运行时读取的静态 submission 成员表。 */
+export function compileSubmissionRegistry(spec: GenuiSpec): SubmissionRegistry {
+  return analyzeSubmissionRegistry(spec).registry
+}
+
+/** 根据当前交互状态判断一个 submission member 是否完成。 */
+export function isSubmissionMemberAnswered(member: SubmissionMember, state: SubmitInteractionState): boolean {
+  switch (member.kind) {
+    case 'radio': return state.answers[member.key] !== undefined
+    case 'checkbox': return (state.multiAnswers[member.key]?.length ?? 0) > 0
+    case 'field': {
+      if (member.secret) return false
+      const value = state.fields[member.key]
+      return value !== undefined && value.trim() !== ''
+    }
+  }
+}
+
+/** 计算 submit 进度和纯本地判卷条件。 */
+export function resolveSubmitState({ registry, groups, state }: {
+  registry: SubmissionRegistry
+  groups?: string[]
+  state: SubmitInteractionState
+}): ResolvedSubmitState {
+  const hasUnknownMember = groups?.some(key => !registry.members.has(key)) ?? false
+  const scope = groups === undefined
+    ? [...registry.members.values()].filter(member => isSubmissionMemberAnswered(member, state))
+    : groups.flatMap(key => {
+      const member = registry.members.get(key)
+      return member === undefined ? [] : [member]
+    })
+  const answered = scope.filter(member => isSubmissionMemberAnswered(member, state)).length
+  const total = groups?.length ?? scope.length
+  const scopeKeys = new Set(scope.map(member => member.key))
+  const hasOutOfScopePayload = Object.keys(state.answers).some(key => !scopeKeys.has(key))
+    || Object.keys(state.multiAnswers).some(key => !scopeKeys.has(key))
+    || Object.entries(state.fields).some(([key, value]) => value.trim() !== '' && !state.secretFields.has(key) && !scopeKeys.has(key))
+  const localGradeEligible = !hasUnknownMember && scope.length > 0
+    && scope.every(member => member.kind === 'radio')
+    && scope.some(member => member.kind === 'radio' && member.answer !== undefined)
+  return { scope, answered, total, localGradeEligible, hasOutOfScopePayload }
+}

package/src/client/table-details.ts

@@ -0,0 +1,151 @@
+import { GENUI_LIMITS } from './genui-runtime/index.ts'
+
+/** 保存 repair 所需的原始 table 字段。 */
+export interface TableDetailSource {
+  columns?: unknown
+  rows?: unknown
+  data?: unknown
+  types?: unknown
+}
+
+/** 保存 repair 后的 table 列和行。 */
+export interface PreparedTableRows {
+  columns: string[]
+  rows: Array<Array<string | number>>
+}
+
+/** 使用 table repair 相同的转换规则处理列和行。 */
+export function prepareTableRows(table: TableDetailSource): PreparedTableRows | null {
+  const declaredColumns = table.columns
+  const columnsSpecified = Array.isArray(declaredColumns) && declaredColumns.length > 0
+  const rawColumns = columnsSpecified && Array.isArray(declaredColumns)
+    && typeof declaredColumns[0] === 'object' && declaredColumns[0] !== null
+    ? declaredColumns.map(columnHeaderText)
+    : declaredColumns
+  let columns = repairColumnValues(rawColumns)
+  let rawRows = table.rows !== undefined ? table.rows : table.data
+
+  if (Array.isArray(rawRows) && rawRows.length > 0
+    && typeof rawRows[0] === 'object' && rawRows[0] !== null && !Array.isArray(rawRows[0])) {
+    const keys = Array.isArray(table.columns) && table.columns.length > 0
+      && typeof table.columns[0] === 'object' && table.columns[0] !== null
+      ? table.columns.map(columnKeyOf).filter((key): key is string => key !== undefined)
+      : Object.keys(rawRows[0] as Record<string, unknown>)
+    rawRows = rawRows.map(row => keys.map(key => cellText((row as Record<string, unknown>)[key])))
+  }
+
+  let derived: PreparedTableRows | null = null
+  if (!columnsSpecified && Array.isArray(rawRows) && rawRows.length > 0 && Array.isArray(rawRows[0])) {
+    const grid = repairRows(rawRows)
+    const candidate = grid.length === 0 ? null : deriveTableColumns(grid)
+    if (candidate !== null && repairRows(candidate.rows).length === candidate.rows.length) {
+      derived = candidate
+      columns = candidate.columns.map(column => column.slice(0, 128))
+    }
+  }
+
+  if (columns.length === 0 && !Array.isArray(table.columns)) return null
+  const rows = repairRows(derived === null ? rawRows : derived.rows)
+  if (!Array.isArray(rawRows)) return null
+  return { columns: columns.slice(0, GENUI_LIMITS.maxTableCols), rows }
+}
+
+/** 返回 repair 后可显示详情的 table 行。 */
+export function tableRowsForDetails<Row = unknown>(table: TableDetailSource): Row[] {
+  return (prepareTableRows(table)?.rows ?? []) as Row[]
+}
+
+/** 按照 table renderer 的规则识别分组标题行。 */
+export function isTableGroupHeaderRow(row: unknown, types: unknown): boolean {
+  if (!Array.isArray(row) || !Array.isArray(types) || types[0] !== 'group') return false
+  return String(row[0] ?? '').trim() !== ''
+    && row.slice(1).every(cell => String(cell ?? '').trim() === '')
+}
+
+/** 判断详情索引对应的行是否可展开并显示。 */
+export function isTableDetailReachable(table: TableDetailSource, rowIndex: number): boolean {
+  const rows = tableRowsForDetails(table)
+  return rowIndex >= 0
+    && rowIndex < rows.length
+    && !isTableGroupHeaderRow(rows[rowIndex], table.types)
+}
+
+/** 按照 guard 接受的 object alias 规则修复 table 列。 */
+function repairColumnValues(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  const columns: string[] = []
+  for (const item of value) {
+    if (columns.length >= GENUI_LIMITS.maxTableCols) break
+    if (typeof item === 'string') columns.push(item.slice(0, 128))
+    else if (item !== null && typeof item === 'object') {
+      const column = item as Record<string, unknown>
+      const label = typeof column.label === 'string' ? column.label
+        : typeof column.value === 'string' ? column.value
+          : typeof column.title === 'string' ? column.title
+            : JSON.stringify(item)
+      columns.push(label.slice(0, 128))
+    }
+  }
+  return columns
+}
+
+/** 按照 table repair 的单元格规则裁剪并清理行。 */
+function repairRows(value: unknown): Array<Array<string | number>> {
+  if (!Array.isArray(value)) return []
+  const rows: Array<Array<string | number>> = []
+  for (const row of value) {
+    if (rows.length >= GENUI_LIMITS.maxTableRows) break
+    if (!Array.isArray(row)) continue
+    const cells: Array<string | number> = []
+    for (const cell of row) {
+      if (cells.length >= GENUI_LIMITS.maxTableCols) break
+      if (typeof cell === 'string') cells.push(cell.slice(0, 256))
+      else if (typeof cell === 'number' && Number.isFinite(cell)) cells.push(cell)
+    }
+    if (cells.length > 0) rows.push(cells)
+  }
+  return rows
+}
+
+/** 从有效的首行表头生成 table 列。 */
+function deriveTableColumns(rows: Array<Array<string | number>>): PreparedTableRows | null {
+  const header = rows[0]
+  if (header === undefined || header.length === 0) return null
+  const body = rows.slice(1)
+  if (body.length === 0) {
+    const columns = header.map(cell => String(cell).trim())
+    return columns.every(column => column !== '') ? { columns, rows: [] } : null
+  }
+  if (body.every(row => row.length === header.length)) {
+    return { columns: header.map(cell => String(cell).trim()), rows: body }
+  }
+  return { columns: Array.from({ length: header.length }, (_unused, index) => `列${index + 1}`), rows }
+}
+
+/** 读取 object row 映射到列时使用的 key。 */
+function columnKeyOf(value: unknown): string | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const column = value as Record<string, unknown>
+  for (const key of ['key', 'dataIndex', 'title', 'label'] as const) {
+    if (typeof column[key] === 'string' && column[key] !== '') return column[key]
+  }
+  return undefined
+}
+
+/** 将 object row 中的值转换为 table 单元格，并保留列位置。 */
+function cellText(value: unknown): string | number {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (value === null || value === undefined) return ''
+  return JSON.stringify(value)
+}
+
+/** 读取 object column 显示的标题。 */
+function columnHeaderText(value: unknown): string {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return String(value)
+  const column = value as Record<string, unknown>
+  for (const key of ['title', 'label', 'key', 'dataIndex'] as const) {
+    if (typeof column[key] === 'string' && column[key] !== '') return column[key]
+  }
+  return JSON.stringify(value)
+}

package/src/client/walk-spec.ts

@@ -0,0 +1,43 @@
+import type { GenuiNode, GenuiSpec } from './spec.ts'
+import { GENUI_LIMITS } from './genui-runtime/index.ts'
+import { isTableDetailReachable, tableRowsForDetails } from './table-details.ts'
+
+/** 遍历完整 GenUI 组件树，并提供每个组件在 spec 中的路径。 */
+export function walkGenuiNodes(spec: GenuiSpec, visitor: (node: GenuiNode, path: string) => void): void {
+  const walk = (nodes: GenuiNode[], path: string, depth: number): void => {
+    if (depth > GENUI_LIMITS.maxDepth) return
+    nodes.forEach((node, index) => visit(node, `${path}[${index}]`, depth))
+  }
+  const visit = (node: GenuiNode, at: string, depth: number): void => {
+    if (depth > GENUI_LIMITS.maxDepth) return
+    visitor(node, at)
+    if (depth >= GENUI_LIMITS.maxDepth) return
+    switch (node.type) {
+      case 'row':
+      case 'col':
+      case 'grid':
+      case 'card':
+        walk(node.items, `${at}.items`, depth + 1)
+        break
+      case 'tabs':
+        node.tabs.forEach((tab, tabIndex) => walk(tab.items, `${at}.tabs[${tabIndex}].items`, depth + 1))
+        break
+      case 'accordion':
+        node.items.forEach((item, itemIndex) => walk(item.items, `${at}.items[${itemIndex}].items`, depth + 1))
+        break
+      case 'list':
+        node.items.forEach((item, itemIndex) => {
+          if (item !== null && typeof item === 'object' && 'type' in item) visit(item, `${at}.items[${itemIndex}]`, depth + 1)
+        })
+        break
+      case 'table':
+        node.details?.slice(0, tableRowsForDetails(node).length).forEach((detail, rowIndex) => {
+          if (detail !== null && isTableDetailReachable(node, rowIndex)) {
+            walk(detail, `${at}.details[${rowIndex}]`, depth + 1)
+          }
+        })
+        break
+    }
+  }
+  walk(spec.items, 'items', 0)
+}