57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
# ETAF UI paired examples — postmortem / 组件配对示例复盘
|
||
|
||
## English
|
||
|
||
### Context
|
||
|
||
The playground originally mixed a large hand-written Host tree with an
|
||
optional catalog entry. That made the primary examples fail to teach the
|
||
official Component contract and encouraged example-only button/grid helpers.
|
||
|
||
### Decision and why
|
||
|
||
Each runnable example is now a same-basename `examples/<name>.etaf` + `.el`
|
||
pair. The `.etaf` file is safe static data and the companion owns state,
|
||
controllers, and callbacks through the public pair loader. This preserves the
|
||
formal data boundary and makes source/build/mount behavior testable. `etaf-ui`
|
||
is a required dependency because the examples are intended to prove the
|
||
official Button, Checkbox, Label, Panel, and DataGrid semantics—not a fallback
|
||
catalog.
|
||
|
||
The semantic behavior belongs in `etaf-ui`, not in playground compensation:
|
||
disabled controls lose callbacks and tab stops, and interactive DataGrid rows
|
||
receive stable refs, roles, and tab indexes. The Showcase layout uses a
|
||
vertical growable main region with a bottom status region, so geometry remains
|
||
the framework/layout contract rather than a collection of timing hacks.
|
||
|
||
### Follow-up
|
||
|
||
Keep pair files small and explicit. Extend the public catalog or core API when
|
||
a reusable semantic capability is missing; do not copy a private implementation
|
||
into an example.
|
||
|
||
## 中文
|
||
|
||
### 背景
|
||
|
||
旧 playground 把大段手写 Host 树与可选组件目录混在一起，主示例没有真正教授
|
||
官方 Component 契约，也容易催生只供示例使用的 button/grid helper。
|
||
|
||
### 决策与原因
|
||
|
||
现在每个可运行示例都是同名的 `examples/<name>.etaf` + `.el` 配对。`.etaf`
|
||
是安全的静态数据，companion 通过公共 pair loader 持有状态、controller 与
|
||
callback。这样保留正式数据边界，并且可以测试 source/build/mount 全流程。
|
||
`etaf-ui` 改为必需依赖，因为示例的目的就是证明官方 Button、Checkbox、Label、
|
||
Panel、DataGrid 的语义，而不是提供备用目录。
|
||
|
||
语义行为归 `etaf-ui` 所有，而不是由 playground 补偿：disabled 控件移除
|
||
callback 和 tab stop；可交互 DataGrid 行拥有稳定 ref、role 与 tab-index。
|
||
Showcase 使用可增长的纵向 main 和底部 status，使几何成为框架/布局契约，而
|
||
不是一组 timing hack。
|
||
|
||
### 后续
|
||
|
||
保持配对文件小而明确。若缺少可复用语义能力，应扩展公共目录或核心 API；不要
|
||
把私有实现复制进示例。
|