[P1][事件 / Events] 实用事件载荷绑定 / Practical event payload bindings

Start with Respo/dom-ffi.mbt#23, which provides the pending ClipboardEvent and DataTransfer types/items readers, then review the remaining React event-accessor scope described here. Done means clipboard/DataTransfer payload access is implemented with explicit nullable or absent behavior and reports the same unit-test, Chromium, documentation, and production-build metrics.

中文

当前状态（2026-09-08）

tiye/dom-ffi 0.4.0 已发布并完成下游验证；React #51 已合并到 main。第一阶段已提供不透明、受检的 SyntheticEvent → 原生 Pointer/Wheel 访问路径，并复用 dom-ffi FormData。这些能力已通过 #52 / PR #53 随 React v0.4.0 发布，发布与下游验证均成功。

已完成

• DOMEvent::native_event 提供显式、文档化且不透明的 native-event-compatible 视图；
• native_pointer_event / native_wheel_event 在完整结构检查后返回 dom-ffi 类型；
• 事件族不匹配及仅含 pointerId 的部分载荷返回 None；
• 真实 Chromium pointermove / wheel 各触发 1 次并验证精确载荷；
• 保持 React SyntheticEvent 的 prevent_default / propagation 路径。

本轮实现范围（PR #56 已合并）

• target_files() -> FileList?：复用 dom-ffi，区分空选择与非文件目标。
• submitter() -> Element?：只接受真实 submit 事件，保留 React 事件控制。
• 验证单/多文件与清空、按钮身份、无 submitter、错误对象、同源 iframe。
• clipboard/DataTransfer 留在本 Issue 后续切片；该切片已完成，本 Issue 仅跟踪剩余事件能力。

剩余高价值范围

• PR #58 已合并：受检拖放 DataTransfer；复用 dom-ffi 0.4.0，63/63 单测、17/17 Chromium、245/245 文档。真实拖拽与构造文件事件分别验证；clipboard/items/types 仍未实现。

• input files 与 submitter 受检访问：PR #56 已合并（60/60 单测、14/14 Chromium、237/237 文档）。

• clipboard / DataTransfer payload（与 dom-ffi 后续 Clipboard/DataTransfer.items/types 能力协调）；

• 每个新增事件族继续明确 nullable/缺失行为。

可量化验收

• 已迁移 Pointer/Wheel accessor 具有类型转换单元测试和真实浏览器测试；
• #51 报告 accessor、浏览器场景、事件触发次数和实际载荷值；
• nullable/部分/错误事件族行为明确且被测试；
• prevent_default / propagation 行为保持回归覆盖；
• #51 的非预期 diagnostics、page errors、unhandled rejections 为 0，production build 通过；
• 后续 input files / submitter / clipboard 切片分别报告相同指标。

下一切片：Respo/dom-ffi.mbt#23 已提交 ClipboardEvent 与 types/items 读取基础，待审核；先合并并通过 Release → Actions 发布，再升级 React。条目增删与 getAsString 仍待后续。

English

Current status (2026-09-08)

tiye/dom-ffi 0.4.0 is published with downstream verification, and React #51 is merged into main. Phase one provides an opaque, checked SyntheticEvent-to-native Pointer/Wheel path and reuses dom-ffi FormData. These capabilities shipped in React v0.4.0 through #52 / PR #53; publication and downstream verification succeeded.

Completed

• DOMEvent::native_event provides an explicit, documented, opaque native-event-compatible view;
• native_pointer_event / native_wheel_event return dom-ffi types only after complete structural checks;
• mismatched event families and a partial payload containing only pointerId return None;
• real Chromium pointermove / wheel each fire once with exact payload validation;
• React SyntheticEvent prevent_default / propagation paths remain intact.

Current implementation scope (PR #56 merged)

• target_files() -> FileList?: reuse dom-ffi and distinguish empty selections from non-file targets.
• submitter() -> Element?: accept native submit events and preserve React event control.
• Verify single/multiple/cleared files, button identity, null submitters, invalid objects, and same-origin iframes.
• Clipboard/DataTransfer remains a later slice; the slice is complete; this issue tracks remaining event capabilities.

Remaining high-value scope

• PR #58 merged: checked drag DataTransfer; reuses dom-ffi 0.4.0, with 63/63 unit tests, 17/17 Chromium, and 245/245 docs. Genuine dragging and constructed file events are tested separately; clipboard/items/types are not yet implemented.

• Checked input files/submitter access: PR #56 merged (60/60 unit tests, 14/14 Chromium, 237/237 docs).

• clipboard / DataTransfer payloads, coordinated with later dom-ffi Clipboard and DataTransfer.items/types support;

• explicit nullable/absent behavior for every added event family.

Quantitative acceptance

• migrated Pointer/Wheel accessors have type-conversion unit tests and real-browser tests;
• #51 reports accessors, browser scenarios, event invocations, and observed payloads;
• nullable, partial, and mismatched event-family behavior is specified and tested;
• prevent_default and propagation retain regression coverage;
• #51 has zero unexpected diagnostics, page errors, or unhandled rejections, and its production build passes;
• later input-file / submitter / clipboard slices report the same metrics.

Next slice: Respo/dom-ffi.mbt#23 supplies ClipboardEvent and types/items readers, pending review. Merge and publish through Release → Actions before upgrading React. Item mutation and getAsString remain follow-ups.