docs: clarify Box default layout

This commit is contained in:
Kinneyzhang 2026-08-26 01:39:14 +08:00
parent 6d38adb035
commit 76a849b25b
2 changed files with 22 additions and 14 deletions

View File

@ -52,9 +52,12 @@ The Box layout modes exposed by the target ETAF API are a closed set:
column | row | flex | grid column | row | flex | grid
``` ```
A plain Box defaults to vertical stacking, so users do not need to learn `flow`. A Box with multiple children must have an arrangement rule; the target ETAF contract
`flow` is Ebox's internal CSS-like default inner display value (the current plain defaults that arrangement to `column` (vertical stacking). Users therefore do not
Ebox default is `(block flow)`), not an ETAF business layout or Component. need a public layout type named `flow`. `flow` is a real ordinary-content layout
algorithm inside CSS/Ebox; current Ebox marks it with the CSS-like display pair
`(block flow)` for plain text/content boxes. It is not an ETAF public mode, Component,
or extra module.
`(box "text")` is shorthand for `(box (text "text"))`. ETAF must not expose `(box "text")` is shorthand for `(box (text "text"))`. ETAF must not expose
`(box :content "text")`; `:content` remains an Ebox backend field. `(box :content "text")`; `:content` remains an Ebox backend field.
@ -85,7 +88,8 @@ contributions downstream. It does not own Component lifecycle or data requests.
### Ebox ### Ebox
Ebox is the layout and rendering engine, not the ETAF Component Runtime. It owns text Ebox is the layout and rendering engine, not the ETAF Component Runtime. It owns text
measurement, wrapping, internal flow/row/column/flex/grid geometry, surface/scroll geometry, measurement, wrapping, ordinary Box content layout, row/column/flex/grid geometry,
surface/scroll geometry,
stable layout snapshots, and render/paint plans. It does not know Components, slots, stable layout snapshots, and render/paint plans. It does not know Components, slots,
Context, Actions, Behaviors, Data, or Resources. Context, Actions, Behaviors, Data, or Resources.
@ -142,7 +146,7 @@ never inject example protocols into core.
## 4. Rust and Elisp split ## 4. Rust and Elisp split
Rust is for deterministic, environment-independent computation: normalized Render IR, Rust is for deterministic, environment-independent computation: normalized Render IR,
keyed diff/patch, ECSS cascade, text measurement/wrapping, flow/flex/grid layout, keyed diff/patch, ECSS cascade, text measurement/wrapping, ordinary Box/flex/grid layout,
geometry snapshots, and paint-contribution merging. geometry snapshots, and paint-contribution merging.
Elisp/Emacs owns user Component execution, refs, Context, Actions, Data, Resources, Elisp/Emacs owns user Component execution, refs, Context, Actions, Data, Resources,
@ -161,6 +165,7 @@ last committed result.
The clean public direction is `Text + Box(layout) + Component`. If concise syntax is The clean public direction is `Text + Box(layout) + Component`. If concise syntax is
needed, `row`/`column`/`flex`/`grid` may be introduced as new compiler sugar, but they needed, `row`/`column`/`flex`/`grid` may be introduced as new compiler sugar, but they
are not compatibility aliases and must not become Runtime Components. `fragment` is are not compatibility aliases and must not become Runtime Components. `fragment` is
transparent structure. `spacer` and `flow` are not public ETAF types. The redesign does transparent structure. `spacer` and `flow` are not public ETAF types; `flow` is only
not preserve the old Host registry names or add a compatibility layer. This target is the current name for the ordinary Box default path. The redesign does not preserve the
not implemented merely by documenting it. old Host registry names or add a compatibility layer. This target is not implemented
merely by documenting it.

View File

@ -61,9 +61,11 @@ View = Text(content, typography)
column | row | flex | grid column | row | flex | grid
``` ```
普通 `Box` 默认采用纵向堆叠语义,因此用户不需要学习 `flow`。`flow` 是 Ebox 普通 `Box` 包含多个子节点时必须有明确的排列规则;目标 ETAF 规定默认排列为
内部 CSS-like display pair 的默认 inner value当前普通 Ebox 的默认值是 `column`(纵向堆叠)。因此用户不需要学习另一个叫 `flow` 的公共布局类型。
`(block flow)`),不是 ETAF 的业务布局类型,也不是 Component。 `flow` 在 CSS/Ebox 内部确实是普通内容布局算法;当前 Ebox 用 CSS-like display
pair `(block flow)` 表示它,主要服务普通文本/内容盒。它不是 ETAF 的公共模式、
Component 或额外模块。
语义映射大致为: 语义映射大致为:
@ -182,7 +184,7 @@ Ebox 是布局和渲染引擎,不是 ETAF Component Runtime。
拥有: 拥有:
- 文本测量、字宽、换行和内容高度; - 文本测量、字宽、换行和内容高度;
- Ebox 内部 flow、row、column、flex、grid 的几何算法; - 普通 Box 内容布局,以及 row、column、flex、grid 的几何算法;
- padding、border、surface、overflow、scroll 和 viewport 几何; - padding、border、surface、overflow、scroll 和 viewport 几何;
- 稳定的布局快照、节点 identity、增量几何更新 - 稳定的布局快照、节点 identity、增量几何更新
- 从布局结果到后端可提交 Render/Paint plan 的转换。 - 从布局结果到后端可提交 Render/Paint plan 的转换。
@ -354,7 +356,7 @@ ebox-playground ─▶ Ebox public API only
- Text/Box Render IR 的验证和规范化; - Text/Box Render IR 的验证和规范化;
- keyed diff、identity matching 和 patch batch - keyed diff、identity matching 和 patch batch
- ECSS selector/cascade/computed-style 计算; - ECSS selector/cascade/computed-style 计算;
- 字符宽度、换行、flow/flex/grid 测量和布局; - 字符宽度、换行、普通 Box/flex/grid 测量和布局;
- geometry snapshot、layout impact 和 paint contribution merge。 - geometry snapshot、layout impact 和 paint contribution merge。
保留在 Elisp/Emacs 适配层的内容: 保留在 Elisp/Emacs 适配层的内容:
@ -394,7 +396,8 @@ text · fragment · container · row · column · stack · flex · grid · space
当前 Renderer 直接把这些名称映射到 Ebox 构造器Ebox Playground 也直接使用 当前 Renderer 直接把这些名称映射到 Ebox 构造器Ebox Playground 也直接使用
自己的布局 API。这只是现状记录不是目标 API也不构成必须保留的兼容表面。 自己的布局 API。这只是现状记录不是目标 API也不构成必须保留的兼容表面。
`spacer``flow` 都不属于目标公共词汇。 `spacer``flow` 都不属于目标公共词汇;`flow` 是 Ebox 内部普通内容布局的
实现路径名称,不是 ETAF 用户需要选择的布局模式。
目标演进方向是: 目标演进方向是: