@html-schema/html-form-engine

html-form-engine 是框架无关的 HTML 表单模板核心库。它负责解析工程表单模板、构建字段 schema、管理字段值、校验字段值，并把运行时字段值序列化回 HTML 快照。

此包不包含页面、Vue 组件、字段控件、渲染器或 playground。官方预览、编辑和调试 UI 位于 apps/template-preview；业务系统可以在 apps/web 中基于本包 API 实现自己的 UI。

当前能力

• 识别 outside / inner 两类模板。
• 解析模板字段、字段属性、默认值、选项和校验规则。
• 解析 table / group / paragraph 布局结构。
• 支持 inline embedded template 与 runtime reference nested template。
• 支持最大嵌套深度、循环引用、重复字段、缺失模板等 warning。
• 可选 source location，用于 Monaco marker 或源码定位。
• 提供运行时状态容器：字段值读写、校验、序列化。
• 支持字段 option provider，把运行时选项注入字段 schema。

使用

import {
  buildTemplateSchema,
  createFormState,
  parseTemplate,
  serializeHtml,
  serializeTemplateTree,
  validateFieldValues
} from "@html-schema/html-form-engine";

const schema = buildTemplateSchema({
  sourceMode: "rawHtml",
  rawHtml: `<div class="table_formfield table_formfield_name" data-fv="required"></div>`,
  rootKind: "inner"
});

const formState = createFormState(schema.fields, schema.templateTree);
formState.setFieldValues({ name: "张三" });
const result = formState.validate();
const html = formState.serializeHtml();

公共 API

• parseTemplate(source)：解析根模板 HTML，支持 rootKind、nestedTemplateMap、maxDepth 和 diagnostics。
• buildTemplateSchema(source)：从 TemplateSource 构建 TemplateSchema。
• createEmptyTemplateSchema(rootKind)：创建空 schema。
• applyFieldOptions(schema, optionProvider)：把运行时字段选项合并进 schema。
• createFormState(fields, sourceHtmlOrTree)：创建字段状态容器，并提供字段值读写、校验和序列化能力。
• serializeHtml(html, values)：对单个 HTML 片段回填字段值。
• serializeTemplateTree(root, values)：基于 TemplateNode 树生成展开后的 runtime HTML 快照。
• validateFieldValues(fields, values)：按字段 schema 校验字段值。

模板约定

• 字段容器默认 class：table_formfield。
• 字段 ID 优先读取 data-fk，其次从 table_formfield_<fieldId> class 推断。
• 字段类型可通过 data-fc、data-ft 或旧 class 名推断。
• 模板 ID 使用 data-tid，模板版本使用 data-tver。
• runtime nested template 占位使用 data-inner-template。

开发命令

pnpm --filter @html-schema/html-form-engine test
pnpm --filter @html-schema/html-form-engine typecheck
pnpm --filter @html-schema/html-form-engine build

边界约束

• 只从包入口导入，不依赖内部 src/* 路径。
• 不在本包内实现 UI，不引入 Vue、React 或其他前端框架。
• 不静态引用 demo/form-template；需要测试样本时使用包内 fixture。
• 当前目标是浏览器/DOM 环境下的框架无关核心，不在本阶段强制实现 Node 无 DOM 兼容。