#moonform

#安装

# 核心包 + 内置规则（零第三方依赖）
moon add 2d5rrr333/moonform/core
moon add 2d5rrr333/moonform/rules

// moon.mod.json 中出现：
"deps": { "2d5rrr333/moonform": "0.1.1" }

// 按需在包的 moon.pkg 中引入：
{
  "import": [
    "2d5rrr333/moonform/core",
    "2d5rrr333/moonform/rules"
  ]
}

#是什么

• Headless 表单状态机：字段值、dirty/touched、错误派生、按需订阅、提交编排——语义对标 @tanstack/form-core@1.33.5（上游测试集行为等价翻译，见 upstream/PARITY.md）
• 结构化字段访问器（lens）：替代 dot-path 字符串——(key, get, set) 三元组组合子，编译期安全、重构改名不失配；数组字段操作（push/insert/remove/swap/move/replace）+ meta 迁移
• 字段组（FormGroup）：以 lens 为前缀的字段分组——组级校验器（组错误 + 错误分发到子字段，未挂载字段延迟浮现）、组内提交（不触碰表单提交态）、form 级 onChange/onChangeGroup 监听器（独立防抖）
• Resolver 协议：校验器即插即用——内置轻量规则包（required/min/max/pattern/闭包）+ moonschema（zod-style JSON Schema）适配；schema 可作字段校验器（schema_field_validator）或组校验器（schema_group_validator，错误按组内相对路径分发给子字段）
• Adapter 协议：核心不渲染；tiye/react 适配器经 use_sync_external_store 桥接
• 跨目标：core/rules 零第三方依赖，js/wasm/native 三目标可编译；同一校验定义服务端/前端复用（同构）
• 虚拟时钟：防抖/竞态中止/异步提交对注入的 Clock 协议实现——测试确定性推进虚拟时间，不依赖真实定时器

#包结构

#快速开始

struct Login {
  email : String
  password : String
} derive(Eq, Debug)

fn email_l() -> @core.Lens[Login, String] {
  @core.field("email", v => v.email, (v, e) => { ..v, email: e })
}

let form = @core.FormApi::make({ email: "", password: "" })
let email = form.field(
  email_l(),
  on_change_validate=@rules.required().then(@rules.min_length(3)),
)
email.mount()
email.set_value("ab")            // → errors: ["Must be at least 3 characters"]
email.handle_blur()              // → touched + blurred
form.handle_submit(submit_options=...) // 校验拦截 / 提交生命周期

// fn friends_l() -> Lens[Form, Array[Friend]] —— 访问器定义同上
form.push_value(friends_l(), friend)
form.remove_value(friends_l(), 0)  // friends[1].name 的错误迁移到 friends[0].name
form.swap_values(friends_l(), 0, 2)

let clock = @core.VirtualClock::make()
let form = @core.FormApi::make(values).with_clock(clock.clock())
let field = form.field(
  email_l(),
  on_change_async_debounce_ms=500,
  on_change_async_validate=@core.async_validator(...),
)
field.set_value("x")
clock.run_all()   // 防抖窗口 + 校验完成，一次推进

// fn step1_l() -> Lens[Form, Step] —— 访问器定义同上
let step1 = form.group(
  step1_l(),
  on_submit_validate=@core.group_validator_value(g => {
    if g.name == "" {
      @core.GroupValidationResult::group_and_fields(
        "Step incomplete",
        [(@core.Key::field("name"), "Name is required")],
      )
    } else {
      @core.GroupValidationResult::valid()
    }
  }),
)
step1.mount()
step1.handle_submit(
  on_group_submit=(value, _meta) => submit_step1(value),  // 表单提交态不受影响
  on_group_submit_invalid=() => show_group_errors(),
)

let step_schema = @builder.object({ "name": @builder.string().min_len(2) }).compile()...
let step1 = form.group(
  step1_l(),
  on_submit_validate=@formSchema.schema_group_validator(step_schema),
)

let bridge = @formreact.FieldBridge::make(form, email_l())
let handle = @formreact.use_field_handle(bridge)
let state = @react.use_sync_external_store(
  () => handle.subscribe(),
  () => handle.get_snapshot(),
)
// state.value / state.errors / state.is_touched ...

let step1 = form.group(step1_l(), on_submit_validate=...)
let gbridge = @formreact.GroupBridge::make(step1)
let ghandle = @formreact.use_group_handle(gbridge)
let gstate = @react.use_sync_external_store(
  () => ghandle.subscribe(),
  () => ghandle.get_snapshot(),
)
// gstate.value / gstate.errors / gstate.is_valid / gstate.can_submit ...
gbridge.submit(on_group_submit=(v, _) => submit_step1(v))

let fbridge = @formreact.FormBridge::make(form)
let fhandle = @formreact.use_form_handle(fbridge)
let fstate = @react.use_sync_external_store(
  () => fhandle.subscribe(),
  () => fhandle.get_snapshot(),
)
// fstate.is_submitting / fstate.can_submit / fstate.submit_error ...
fbridge.submit(submit_options=...)

let form = @core.FormApi::make(values).with_clock(@formreact.real_clock())
// 防抖/异步提交走真实时间；测试中换成 VirtualClock 即确定性推进

#测试与验收

moon test --target js      # 306 tests（含上游译文 + 文档测试）
moon test --target wasm    # 286 tests
moon test --target native  # CI 已验证（GitHub Actions 五作业全绿）
moon run src/examples/login --target js   # 示例验收

#致谢

• TanStack Form（MIT）——行为语义基准
• QuietlyChan/moonschema（Apache-2.0）——schema 校验引擎，源码 vendor 于 src/vendor/moonschema
• tiye/react——React 绑定

#License