@fulate/yoga 1.0.0

package/README.md

@@ -0,0 +1,68 @@
+# `@fulate/yoga`
+
+> 文档角色：`GUIDE`。权威来源：Yoga adapter 源码与测试；Core/UI 的场景和元素契约由对应指南拥有。
+
+`@fulate/yoga` 用 `yoga-layout` 为 Canvas 元素提供 Flex 布局。`Div` 是带 Yoga 样式的矩形容器，
+`Span` 是带文本测量的 Yoga 文本元素；两者都仍是普通 Fulate Node/Element，不创建独立场景树。
+
+`Div`、`Span` 会在模块加载时注册为 `f-div`、`f-span`；重复导入只更新同一 renderer registry，
+不建立第二套元素类型系统。
+
+```ts
+import { Div, Span, FlexDirection, Justify } from "@fulate/yoga";
+
+const panel = new Div({
+  width: 320,
+  height: 120,
+  flexDirection: FlexDirection.Row,
+  justifyContent: Justify.SpaceBetween,
+  children: [new Span({ text: "Hello" })]
+});
+```
+
+## 样式与布局
+
+Yoga 样式（尺寸、margin/padding、flex、align、position、overflow 等）直接作为 `YogaOption` 传入。
+它们与普通 Element 属性共同存放在元素唯一 Properties 中；`setOptions()`、trusted batch、History、
+属性 snapshot 和 JSON 都读写这同一份 authored state。属性 hook 把最终 changed fields 直接交给
+`yogaNode.setWidth()`、`setFlexGrow()` 等 native setter，不建立 `yogaStyles` 镜像，也不借用 Core
+runtime options。
+
+连续的 Yoga 父子节点参与同一棵树；直接 parent 不是 Yoga 的节点自动成为 Yoga root，因此普通
+Element、ScrollView 等非 Yoga 节点自然形成布局边界。Yoga native tree 自己向上传播 dirty；只有
+实际 Yoga root 安装 `setDirtiedFunc`，由该 callback 把稳定 owner identity 合并进所属
+`RootFrameRuntime`。普通 style、measure 和 children 更新不手写 root 上溯或另建 scheduler。
+
+一帧先完成 authored mutation，再对每个 dirty Yoga root 计算一次布局。结果侧由 `hasNewLayout`
+裁剪读取分支，再由 Transform 的 resolved-frame commit 只安装数值真实变化的
+`left/top/width/height`。全部 layout owner 完成后，FrameRuntime 把实际 affected elements 合并为一次
+SceneRegistry 通知，随后进入既有 geometry、spatial 与 paint。计算结果不写回 authored
+Properties，也不进入 History。
+
+`layout()` 是同步 drain 入口：它只结清 FrameRuntime 已登记的工作，与 RAF 使用完全相同的 phase；
+clean 状态调用不会重新计算 Yoga。普通异步使用无需手动调用，等待 `root.nextTick()` 即可读取稳定结果。
+
+## Vue 注册
+
+导入 `@fulate/yoga` 会注册 `f-div` 与 `f-span` 元素，供 `@fulate/vue` renderer 使用：
+
+```tsx
+<f-div flexDirection={FlexDirection.Column}>
+  <f-span text="Ready" />
+</f-div>
+```
+
+## TextRow
+
+`TextRow` 保留 Yoga 对直接子项的横向尺寸和位置计算，并让直接 `Span` 与嵌套
+`TextRow` 使用同一条实际 alphabetic baseline。普通 `Div` 仍可作为固定或
+`flexGrow` spacer，不参与文字基线计算。
+
+```tsx
+<f-text-row width={520} gap={8}>
+  <f-span text="P:" fontSize={18} />
+  <f-div flexGrow={1} />
+  <f-span text="30036" fontSize={20} />
+  <f-span text="kW" fontSize={12} />
+</f-text-row>
+```

package/dist/div.d.ts

@@ -0,0 +1,33 @@
+import type { Layer, PropertyChanges, Root } from "@fulate/core";
+import type { Rect } from "@fulate/share";
+import { Rectangle, RectangleProperties } from "@fulate/ui";
+import { type YogaOption, type YogaOptionPatch } from "./style";
+import { YogaNodeRuntime, yogaRuntimeKey, type YogaElementHost } from "./runtime";
+export type { YogaOption, YogaOptionPatch } from "./style";
+export { Align, BoxSizing, Display, Edge, FlexDirection, Gutter, Justify, Overflow, PositionType, Wrap } from "yoga-layout";
+declare class DivProperties extends RectangleProperties {
+    constructor(options?: YogaOption);
+    getImpact(changes: PropertyChanges): import("@fulate/core").ChangeImpact;
+}
+/** Rectangle paint surface whose authored frame and flex style are owned by Yoga. */
+export declare class Div extends Rectangle<DivProperties, any> implements YogaElementHost {
+    readonly [yogaRuntimeKey]: YogaNodeRuntime;
+    constructor(options?: YogaOption);
+    get yogaNode(): import("yoga-layout").Node;
+    get left(): number;
+    get top(): number;
+    get width(): number;
+    get height(): number;
+    get overflow(): "visible" | "hidden";
+    setOptions(options?: YogaOptionPatch): this;
+    layout(): this;
+    /** @internal RootFrameRuntime 采用一次 Yoga 最终 frame。 */
+    commitYogaFrame(frame: Readonly<Rect>): boolean;
+    protected onParentChanged(): void;
+    protected onMount(): void;
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    protected onChildrenChanged(): void;
+    protected onPropertiesChanged(current: DivProperties, changes: PropertyChanges): void;
+    protected onUnmount(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Div } from "./div";
+export type { YogaOption, YogaOptionPatch } from "./div";
+export { Span } from "./span";
+export type { SpanOption, SpanOptionPatch } from "./span";
+export { TextRow } from "./text-row";
+export type { TextRowOption, TextRowOptionPatch } from "./text-row";
+export { Align, BoxSizing, Display, Edge, FlexDirection, Gutter, Justify, Overflow, PositionType, Wrap } from "./div";

package/dist/index.js

@@ -0,0 +1,642 @@
+import { Rectangle, RectangleProperties, RectangleTransform, Text, TextProperties, TextTransform } from "@fulate/ui";
+import Yoga, { Align, Align as Align$1, BoxSizing, BoxSizing as BoxSizing$1, Display, Display as Display$1, Edge, Edge as Edge$1, FlexDirection, FlexDirection as FlexDirection$1, Gutter, Gutter as Gutter$1, Justify, Justify as Justify$1, MeasureMode, Overflow, Overflow as Overflow$1, PositionType, PositionType as PositionType$1, Wrap, Wrap as Wrap$1 } from "yoga-layout";
+import { registerElement } from "@fulate/vue";
+//#region packages/yoga/src/style.ts
+var YOGA_STYLE_KEYS = [
+	"display",
+	"left",
+	"top",
+	"bottom",
+	"right",
+	"width",
+	"height",
+	"minWidth",
+	"minHeight",
+	"maxWidth",
+	"maxHeight",
+	"alignContent",
+	"alignItems",
+	"alignSelf",
+	"aspectRatio",
+	"flex",
+	"flexBasis",
+	"flexDirection",
+	"flexGrow",
+	"flexShrink",
+	"flexWrap",
+	"justifyContent",
+	"overflow",
+	"paddingTop",
+	"paddingLeft",
+	"paddingRight",
+	"paddingBottom",
+	"padding",
+	"marginTop",
+	"marginLeft",
+	"marginRight",
+	"marginBottom",
+	"margin",
+	"position",
+	"gap",
+	"inset",
+	"boxSizing"
+];
+var YOGA_STYLE_KEY_SET = new Set(YOGA_STYLE_KEYS);
+var RESOLVED_FRAME_KEYS = new Set([
+	"left",
+	"top",
+	"width",
+	"height"
+]);
+var NO_PROPERTY_CHANGES = /* @__PURE__ */ new Map();
+/** 把 Yoga authored fields 安装到元素唯一 Properties，不建立旁路 style state。 */
+function initializeYogaStyleProperties(properties, options) {
+	properties.left = options.left;
+	properties.top = options.top;
+	for (const key of YOGA_STYLE_KEYS) if (!(key in properties)) properties[key] = options[key];
+}
+/** resolved frame fields 只由 Yoga 计算结果驱动 Core transform impact。 */
+function withoutYogaResolvedFrameChanges(changes) {
+	let frameChanges = 0;
+	for (const key of RESOLVED_FRAME_KEYS) if (changes.has(key)) frameChanges++;
+	if (frameChanges === 0) return changes;
+	if (frameChanges === changes.size) return NO_PROPERTY_CHANGES;
+	return new Map([...changes].filter(([key]) => !RESOLVED_FRAME_KEYS.has(key)));
+}
+//#endregion
+//#region packages/yoga/src/runtime.ts
+var yogaRuntimeKey = Symbol();
+function getYogaRuntime(node) {
+	return node?.[yogaRuntimeKey];
+}
+/** 一个 Yoga Element 唯一的 native node、tree relation 与 derived layout owner。 */
+var YogaNodeRuntime = class {
+	node = Yoga.Node.create();
+	yogaChildren = [];
+	ownsDirtiedCallback = false;
+	handleDirtied = () => {
+		if (!this.host.isActive || !this.isLayoutRoot()) return;
+		this.host.activeRoot?.frameRuntime.scheduleLayout(this);
+	};
+	constructor(host) {
+		this.host = host;
+		this.applyStyles();
+		this.syncChildren();
+	}
+	get key() {
+		return this.host.key;
+	}
+	get styles() {
+		return this.host.properties;
+	}
+	getParentRuntime() {
+		return getYogaRuntime(this.host.parent);
+	}
+	isLayoutRoot() {
+		return !this.getParentRuntime();
+	}
+	mount() {
+		this.syncChildren();
+	}
+	activate() {
+		this.syncChildren();
+		this.syncLayoutRootRole();
+	}
+	deactivate(root) {
+		this.unsetDirtiedCallback();
+		root?.frameRuntime.forgetLayout(this);
+	}
+	unmount() {
+		this.host.activeRoot?.frameRuntime.forgetLayout(this);
+		this.unsetDirtiedCallback();
+		this.yogaChildren = [];
+		this.node?.free();
+		this.node = null;
+	}
+	parentChanged() {
+		this.syncLayoutRootRole();
+	}
+	childrenChanged() {
+		this.syncChildren();
+	}
+	propertiesChanged(changes) {
+		for (const key of changes.keys()) {
+			if (!YOGA_STYLE_KEY_SET.has(key)) continue;
+			this.applyStyle(key);
+		}
+		if (changes.has("display") && !changes.has("flexDirection")) this.applyStyle("flexDirection");
+		if (changes.has("borderWidth")) this.node?.setBorder(Edge$1.All, this.host.borderWidth);
+	}
+	markMeasureDirty() {
+		this.node?.markDirty();
+	}
+	layout() {
+		this.host.activeRoot?.frameRuntime.drain();
+	}
+	flushLayout() {
+		const node = this.node;
+		if (!node || !this.host.isActive || this.host.isUnmounted || !this.isLayoutRoot()) return;
+		node.calculateLayout("auto", "auto");
+		const affected = [];
+		this.commitComputedTree(affected);
+		return affected;
+	}
+	syncLayoutRootRole() {
+		const node = this.node;
+		const frameRuntime = this.host.activeRoot?.frameRuntime;
+		if (node && this.host.isActive && this.isLayoutRoot()) {
+			if (this.ownsDirtiedCallback) return;
+			node.setDirtiedFunc(this.handleDirtied);
+			this.ownsDirtiedCallback = true;
+			frameRuntime?.scheduleLayout(this);
+			return;
+		}
+		this.unsetDirtiedCallback();
+		frameRuntime?.forgetLayout(this);
+	}
+	unsetDirtiedCallback() {
+		if (!this.ownsDirtiedCallback) return;
+		this.node?.unsetDirtiedFunc();
+		this.ownsDirtiedCallback = false;
+	}
+	commitComputedTree(affected) {
+		const node = this.node;
+		if (!node || !this.host.isActive || !node.hasNewLayout()) return;
+		const frame = node.getComputedLayout();
+		node.markLayoutSeen();
+		if (this.host.commitYogaFrame(frame)) affected.push(this.host);
+		for (const child of this.host.children) getYogaRuntime(child)?.commitComputedTree(affected);
+	}
+	syncChildren() {
+		const node = this.node;
+		if (!node) return;
+		const children = this.host.children.flatMap((child) => {
+			const runtime = getYogaRuntime(child);
+			return runtime?.node ? [runtime.node] : [];
+		});
+		if (this.yogaChildren.length === children.length && children.every((child, index) => this.yogaChildren[index] === child)) return;
+		const current = [...this.yogaChildren];
+		const next = new Set(children);
+		for (let index = current.length - 1; index >= 0; index--) {
+			const child = current[index];
+			if (next.has(child)) continue;
+			node.removeChild(child);
+			current.splice(index, 1);
+		}
+		for (let index = 0; index < children.length; index++) {
+			const child = children[index];
+			if (current[index] === child) continue;
+			const previousIndex = current.indexOf(child, index + 1);
+			if (previousIndex !== -1) {
+				node.removeChild(child);
+				current.splice(previousIndex, 1);
+			}
+			node.insertChild(child, index);
+			current.splice(index, 0, child);
+		}
+		this.yogaChildren = children;
+	}
+	applyStyles() {
+		for (const key of YOGA_STYLE_KEYS) this.applyStyle(key);
+		this.node?.setBorder(Edge$1.All, this.host.borderWidth);
+	}
+	applyStyle(key) {
+		const node = this.node;
+		if (!node) return;
+		const styles = this.styles;
+		switch (key) {
+			case "display":
+				node.setDisplay(styles.display ?? Display$1.Flex);
+				return;
+			case "width":
+				node.setWidth(styles.width);
+				return;
+			case "height":
+				node.setHeight(styles.height);
+				return;
+			case "minWidth":
+				node.setMinWidth(styles.minWidth);
+				return;
+			case "minHeight":
+				node.setMinHeight(styles.minHeight);
+				return;
+			case "maxWidth":
+				node.setMaxWidth(styles.maxWidth);
+				return;
+			case "maxHeight":
+				node.setMaxHeight(styles.maxHeight);
+				return;
+			case "justifyContent":
+				node.setJustifyContent(styles.justifyContent ?? Justify$1.FlexStart);
+				return;
+			case "alignContent":
+				node.setAlignContent(styles.alignContent ?? Align$1.Stretch);
+				return;
+			case "alignItems":
+				node.setAlignItems(styles.alignItems ?? Align$1.Stretch);
+				return;
+			case "alignSelf":
+				node.setAlignSelf(styles.alignSelf ?? Align$1.Auto);
+				return;
+			case "aspectRatio":
+				node.setAspectRatio(styles.aspectRatio);
+				return;
+			case "flex":
+				node.setFlex(styles.flex);
+				return;
+			case "flexBasis":
+				node.setFlexBasis(styles.flexBasis);
+				return;
+			case "flexDirection":
+				node.setFlexDirection(styles.flexDirection ?? (styles.display === Display$1.Flex ? FlexDirection$1.Row : FlexDirection$1.Column));
+				return;
+			case "flexGrow":
+				node.setFlexGrow(styles.flexGrow);
+				return;
+			case "flexShrink":
+				node.setFlexShrink(styles.flexShrink ?? 1);
+				return;
+			case "flexWrap":
+				node.setFlexWrap(styles.flexWrap ?? Wrap$1.NoWrap);
+				return;
+			case "overflow":
+				node.setOverflow(styles.overflow === "hidden" ? Overflow$1.Hidden : styles.overflow === "visible" ? Overflow$1.Visible : styles.overflow ?? Overflow$1.Visible);
+				return;
+			case "gap":
+				node.setGap(Gutter$1.All, styles.gap);
+				return;
+			case "padding":
+				node.setPadding(Edge$1.All, styles.padding);
+				return;
+			case "paddingLeft":
+				node.setPadding(Edge$1.Left, styles.paddingLeft);
+				return;
+			case "paddingTop":
+				node.setPadding(Edge$1.Top, styles.paddingTop);
+				return;
+			case "paddingRight":
+				node.setPadding(Edge$1.Right, styles.paddingRight);
+				return;
+			case "paddingBottom":
+				node.setPadding(Edge$1.Bottom, styles.paddingBottom);
+				return;
+			case "margin":
+				node.setMargin(Edge$1.All, styles.margin);
+				return;
+			case "marginLeft":
+				node.setMargin(Edge$1.Left, styles.marginLeft);
+				return;
+			case "marginTop":
+				node.setMargin(Edge$1.Top, styles.marginTop);
+				return;
+			case "marginRight":
+				node.setMargin(Edge$1.Right, styles.marginRight);
+				return;
+			case "marginBottom":
+				node.setMargin(Edge$1.Bottom, styles.marginBottom);
+				return;
+			case "position":
+				node.setPositionType(styles.position ?? PositionType$1.Relative);
+				return;
+			case "inset":
+				node.setPosition(Edge$1.All, styles.inset);
+				return;
+			case "left":
+				node.setPosition(Edge$1.Left, styles.left);
+				return;
+			case "top":
+				node.setPosition(Edge$1.Top, styles.top);
+				return;
+			case "bottom":
+				node.setPosition(Edge$1.Bottom, styles.bottom);
+				return;
+			case "right":
+				node.setPosition(Edge$1.Right, styles.right);
+				return;
+			case "boxSizing": node.setBoxSizing(styles.boxSizing ?? BoxSizing$1.BorderBox);
+		}
+	}
+};
+//#endregion
+//#region packages/yoga/src/div.ts
+var DivProperties = class extends RectangleProperties {
+	constructor(options = {}) {
+		super(options);
+		initializeYogaStyleProperties(this, options);
+	}
+	getImpact(changes) {
+		return super.getImpact(withoutYogaResolvedFrameChanges(changes));
+	}
+};
+var DivTransform = class extends RectangleTransform {
+	resolveFitSize() {}
+};
+/** Rectangle paint surface whose authored frame and flex style are owned by Yoga. */
+var Div = class extends Rectangle {
+	[yogaRuntimeKey];
+	constructor(options = {}) {
+		super(options, new DivProperties(options), DivTransform);
+		this[yogaRuntimeKey] = new YogaNodeRuntime(this);
+	}
+	get yogaNode() {
+		return this[yogaRuntimeKey].node;
+	}
+	get left() {
+		return this.transform.resolvedLeft ?? 0;
+	}
+	get top() {
+		return this.transform.resolvedTop ?? 0;
+	}
+	get width() {
+		return this.transform.resolvedWidth;
+	}
+	get height() {
+		return this.transform.resolvedHeight;
+	}
+	get overflow() {
+		const value = this.properties.overflow;
+		return value === void 0 || value === "visible" || value === Overflow$1.Visible ? "visible" : "hidden";
+	}
+	setOptions(options) {
+		return super.setOptions(options);
+	}
+	layout() {
+		this[yogaRuntimeKey].layout();
+		return this;
+	}
+	/** @internal RootFrameRuntime 采用一次 Yoga 最终 frame。 */
+	commitYogaFrame(frame) {
+		return this.transform.commitResolvedFrame(frame);
+	}
+	onParentChanged() {
+		super.onParentChanged();
+		this[yogaRuntimeKey].parentChanged();
+	}
+	onMount() {
+		super.onMount();
+		this[yogaRuntimeKey].mount();
+	}
+	onActivate(root, layer) {
+		super.onActivate(root, layer);
+		this[yogaRuntimeKey].activate();
+	}
+	onDeactivate(root, layer) {
+		this[yogaRuntimeKey].deactivate(root);
+		super.onDeactivate(root, layer);
+	}
+	onChildrenChanged() {
+		super.onChildrenChanged();
+		this[yogaRuntimeKey].childrenChanged();
+	}
+	onPropertiesChanged(current, changes) {
+		super.onPropertiesChanged(current, changes);
+		this[yogaRuntimeKey].propertiesChanged(changes);
+	}
+	onUnmount() {
+		this[yogaRuntimeKey].unmount();
+		super.onUnmount();
+	}
+};
+//#endregion
+//#region packages/yoga/src/text-row/contract.ts
+var textRowParticipantKey = Symbol();
+var textRowProviderKey = Symbol();
+function getTextRowParticipant(node) {
+	return node[textRowParticipantKey];
+}
+function getTextRowProvider(node) {
+	return node?.[textRowProviderKey];
+}
+//#endregion
+//#region packages/yoga/src/span.ts
+var TEXT_MEASURE_KEYS = new Set([
+	"text",
+	"fontSize",
+	"fontFamily",
+	"fontWeight",
+	"fontStyle",
+	"lineHeight",
+	"wordWrap",
+	"ellipsis",
+	"letterSpacing",
+	"maxLines"
+]);
+var SpanProperties = class extends TextProperties {
+	constructor(options = {}) {
+		super(options);
+		initializeYogaStyleProperties(this, options);
+	}
+	getImpact(changes) {
+		return super.getImpact(withoutYogaResolvedFrameChanges(changes));
+	}
+};
+var SpanTransform = class extends TextTransform {
+	resolveFitSize() {}
+};
+/** Text paint surface measured and framed by its owning Yoga tree. */
+var Span = class extends Text {
+	[yogaRuntimeKey];
+	[textRowParticipantKey] = this;
+	measureYogaText = (width, widthMode, height, heightMode) => this.measureText(width, widthMode, height, heightMode);
+	constructor(options = {}) {
+		const prepared = {
+			textAlign: "left",
+			verticalAlign: "top",
+			...options
+		};
+		super(prepared, new SpanProperties(prepared), SpanTransform);
+		this[yogaRuntimeKey] = new YogaNodeRuntime(this);
+		this.yogaNode?.setMeasureFunc(this.measureYogaText);
+	}
+	get yogaNode() {
+		return this[yogaRuntimeKey].node;
+	}
+	get left() {
+		return this.transform.resolvedLeft ?? 0;
+	}
+	get top() {
+		return this.transform.resolvedTop ?? 0;
+	}
+	get width() {
+		return this.transform.resolvedWidth;
+	}
+	get height() {
+		return this.transform.resolvedHeight;
+	}
+	get overflow() {
+		const value = this.properties.overflow;
+		return value === void 0 || value === "visible" || value === Overflow$1.Visible ? "visible" : "hidden";
+	}
+	setOptions(options) {
+		return super.setOptions(options);
+	}
+	layout() {
+		this[yogaRuntimeKey].layout();
+		return this;
+	}
+	getTextRowLineMetrics() {
+		return this.getTextLineBoxMetrics();
+	}
+	textRowMetricsChanged() {
+		this[yogaRuntimeKey].markMeasureDirty();
+		this.transform.markGeometryNeedsLayout(false);
+	}
+	getVisibleTextBounds() {
+		const bounds = super.getVisibleTextBounds();
+		if (!bounds) return null;
+		const offsetY = this.getTextRowPaintOffset();
+		return offsetY === 0 ? bounds : {
+			...bounds,
+			top: bounds.top + offsetY
+		};
+	}
+	/** @internal RootFrameRuntime 采用一次 Yoga 最终 frame 后同步唯一 TextBlock。 */
+	commitYogaFrame(frame) {
+		const changed = this.transform.commitResolvedFrame(frame);
+		this.syncTextLayout();
+		return changed;
+	}
+	onParentChanged() {
+		super.onParentChanged();
+		this[yogaRuntimeKey].parentChanged();
+	}
+	commitTextLayoutSize(_width, _height) {}
+	getLayoutWidth() {
+		return Math.max(this.width ?? 0, 0);
+	}
+	getResolvedHeight() {
+		return this.height ?? 0;
+	}
+	onMount() {
+		super.onMount();
+		this[yogaRuntimeKey].mount();
+	}
+	onActivate(root, layer) {
+		super.onActivate(root, layer);
+		this[yogaRuntimeKey].activate();
+		getTextRowProvider(this.parent)?.syncTextRowMetrics();
+	}
+	onDeactivate(root, layer) {
+		this[yogaRuntimeKey].deactivate(root);
+		super.onDeactivate(root, layer);
+	}
+	onChildrenChanged() {
+		super.onChildrenChanged();
+		this[yogaRuntimeKey].childrenChanged();
+	}
+	onPropertiesChanged(current, changes) {
+		super.onPropertiesChanged(current, changes);
+		this[yogaRuntimeKey].propertiesChanged(changes);
+		let textRowMetricsChanged = changes.has("textBaseline");
+		for (const key of changes.keys()) {
+			if (!TEXT_MEASURE_KEYS.has(key)) continue;
+			this[yogaRuntimeKey].markMeasureDirty();
+			textRowMetricsChanged = true;
+			break;
+		}
+		if (textRowMetricsChanged) getTextRowProvider(this.parent)?.syncTextRowMetrics();
+	}
+	onTextLayoutInvalidated() {
+		if (this.isActive && this.yogaNode) this[yogaRuntimeKey].markMeasureDirty();
+		getTextRowProvider(this.parent)?.syncTextRowMetrics();
+	}
+	paintContent(ctx) {
+		this.paintTextContent(ctx, this.getTextRowPaintOffset());
+	}
+	onUnmount() {
+		this[yogaRuntimeKey].unmount();
+		super.onUnmount();
+	}
+	measureText(constraintWidth, widthMode, constraintHeight, heightMode) {
+		const style = this.getResolvedTextStyle();
+		const lineHeightPx = style.fontSize * style.lineHeight;
+		const textRowHeight = getTextRowProvider(this.parent)?.textRowContentHeight ?? 0;
+		if (!this.text) return {
+			width: 0,
+			height: Math.max(lineHeightPx, textRowHeight)
+		};
+		const wrapWidth = widthMode === MeasureMode.Undefined ? Infinity : constraintWidth;
+		const metrics = this.measureTextLayout(wrapWidth, heightMode === MeasureMode.Undefined ? void 0 : constraintHeight);
+		const measuredHeight = Math.max(Math.max(metrics.lineCount, 1) * lineHeightPx, textRowHeight);
+		if (widthMode === MeasureMode.Exactly) return {
+			width: constraintWidth,
+			height: measuredHeight
+		};
+		return {
+			width: widthMode === MeasureMode.AtMost ? Math.min(metrics.maxLineWidth, constraintWidth) : metrics.maxLineWidth,
+			height: measuredHeight
+		};
+	}
+	getTextRowPaintOffset() {
+		const provider = getTextRowProvider(this.parent);
+		if (!provider) return 0;
+		const baseline = this.getTextBlockFirstAlphabeticBaseline();
+		return provider.getTextRowAlphabeticBaseline() - this.top - baseline;
+	}
+};
+//#endregion
+//#region packages/yoga/src/text-row/index.ts
+/** A Yoga row whose direct text participants share one painted baseline. */
+var TextRow = class extends Div {
+	[textRowParticipantKey] = this;
+	[textRowProviderKey] = this;
+	alphabeticBaseline = 0;
+	intrinsicContentHeight = 0;
+	constructor(options = {}) {
+		super({
+			...options,
+			alignItems: Align$1.FlexStart,
+			flexDirection: FlexDirection$1.Row
+		});
+		this.syncTextRowMetrics();
+	}
+	setOptions(options) {
+		return super.setOptions(options);
+	}
+	getTextRowLineMetrics() {
+		return {
+			alphabeticBaseline: this.alphabeticBaseline,
+			height: this.intrinsicContentHeight
+		};
+	}
+	get textRowContentHeight() {
+		return Math.max(this.intrinsicContentHeight, getTextRowProvider(this.parent)?.textRowContentHeight ?? 0);
+	}
+	getTextRowAlphabeticBaseline() {
+		const parent = getTextRowProvider(this.parent);
+		if (parent) return parent.getTextRowAlphabeticBaseline() - this.top;
+		return (this.yogaNode?.getComputedBorder(Edge$1.Top) ?? 0) + (this.yogaNode?.getComputedPadding(Edge$1.Top) ?? 0) + this.alphabeticBaseline;
+	}
+	syncTextRowMetrics() {
+		let alphabeticBaseline = 0;
+		let belowBaseline = 0;
+		for (const child of this.children) {
+			const participant = getTextRowParticipant(child);
+			if (!participant) continue;
+			const metrics = participant.getTextRowLineMetrics();
+			alphabeticBaseline = Math.max(alphabeticBaseline, metrics.alphabeticBaseline);
+			belowBaseline = Math.max(belowBaseline, metrics.height - metrics.alphabeticBaseline);
+		}
+		const contentHeight = alphabeticBaseline + belowBaseline;
+		if (alphabeticBaseline === this.alphabeticBaseline && contentHeight === this.intrinsicContentHeight) return;
+		this.alphabeticBaseline = alphabeticBaseline;
+		this.intrinsicContentHeight = contentHeight;
+		for (const child of this.children) getTextRowParticipant(child)?.textRowMetricsChanged();
+		getTextRowProvider(this.parent)?.syncTextRowMetrics();
+	}
+	textRowMetricsChanged() {
+		for (const child of this.children) getTextRowParticipant(child)?.textRowMetricsChanged();
+		this.transform.markGeometryNeedsLayout(false);
+	}
+	onChildrenChanged() {
+		super.onChildrenChanged();
+		this.syncTextRowMetrics();
+	}
+};
+//#endregion
+//#region packages/yoga/src/index.ts
+registerElement("f-div", Div);
+registerElement("f-span", Span);
+registerElement("f-text-row", TextRow);
+//#endregion
+export { Align, BoxSizing, Display, Div, Edge, FlexDirection, Gutter, Justify, Overflow, PositionType, Span, TextRow, Wrap };

package/dist/runtime.d.ts

@@ -0,0 +1,39 @@
+import type { Element, PropertyChanges, Root, RootFrameLayoutOwner } from "@fulate/core";
+import type { Rect } from "@fulate/share";
+import Yoga from "yoga-layout";
+export type YogaNode = ReturnType<typeof Yoga.Node.create>;
+export declare const yogaRuntimeKey: unique symbol;
+export interface YogaElementHost extends Element {
+    readonly [yogaRuntimeKey]: YogaNodeRuntime;
+    readonly borderWidth: number;
+    commitYogaFrame(frame: Readonly<Rect>): boolean;
+}
+/** 一个 Yoga Element 唯一的 native node、tree relation 与 derived layout owner。 */
+export declare class YogaNodeRuntime implements RootFrameLayoutOwner {
+    private readonly host;
+    node: YogaNode | null;
+    private yogaChildren;
+    private ownsDirtiedCallback;
+    private readonly handleDirtied;
+    constructor(host: YogaElementHost);
+    get key(): string;
+    private get styles();
+    private getParentRuntime;
+    private isLayoutRoot;
+    mount(): void;
+    activate(): void;
+    deactivate(root: Root | null): void;
+    unmount(): void;
+    parentChanged(): void;
+    childrenChanged(): void;
+    propertiesChanged(changes: PropertyChanges): void;
+    markMeasureDirty(): void;
+    layout(): void;
+    flushLayout(): Element<import("@fulate/core").ElementProperties, import("@fulate/core").BaseElementOption<any>, Partial<Omit<import("@fulate/core").BaseElementOption<any>, "children" | "key">>>[];
+    private syncLayoutRootRole;
+    private unsetDirtiedCallback;
+    private commitComputedTree;
+    private syncChildren;
+    private applyStyles;
+    private applyStyle;
+}

package/dist/span.d.ts

@@ -0,0 +1,45 @@
+import type { Layer, PropertyChanges, Root } from "@fulate/core";
+import type { Rect } from "@fulate/share";
+import { Text, TextProperties, type TextLineBoxMetrics } from "@fulate/ui";
+import { type SpanOption, type SpanOptionPatch } from "./style";
+import { YogaNodeRuntime, yogaRuntimeKey, type YogaElementHost } from "./runtime";
+import { textRowParticipantKey, type TextRowParticipant } from "./text-row/contract";
+declare class SpanProperties extends TextProperties {
+    constructor(options?: SpanOption);
+    getImpact(changes: PropertyChanges): import("@fulate/core").ChangeImpact;
+}
+/** Text paint surface measured and framed by its owning Yoga tree. */
+export declare class Span extends Text<SpanProperties, any> implements TextRowParticipant, YogaElementHost {
+    readonly [yogaRuntimeKey]: YogaNodeRuntime;
+    readonly [textRowParticipantKey]: this;
+    private readonly measureYogaText;
+    constructor(options?: SpanOption);
+    get yogaNode(): import("yoga-layout").Node;
+    get left(): number;
+    get top(): number;
+    get width(): number;
+    get height(): number;
+    get overflow(): "visible" | "hidden";
+    setOptions(options?: SpanOptionPatch): this;
+    layout(): this;
+    getTextRowLineMetrics(): TextLineBoxMetrics;
+    textRowMetricsChanged(): void;
+    getVisibleTextBounds(): Rect;
+    /** @internal RootFrameRuntime 采用一次 Yoga 最终 frame 后同步唯一 TextBlock。 */
+    commitYogaFrame(frame: Readonly<Rect>): boolean;
+    protected onParentChanged(): void;
+    protected commitTextLayoutSize(_width: number | undefined, _height: number | undefined): void;
+    protected getLayoutWidth(): number;
+    protected getResolvedHeight(): number;
+    protected onMount(): void;
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    protected onChildrenChanged(): void;
+    protected onPropertiesChanged(current: SpanProperties, changes: PropertyChanges): void;
+    protected onTextLayoutInvalidated(): void;
+    protected paintContent(ctx: CanvasRenderingContext2D): void;
+    protected onUnmount(): void;
+    private measureText;
+    private getTextRowPaintOffset;
+}
+export type { SpanOption, SpanOptionPatch } from "./style";

package/dist/style.d.ts

@@ -0,0 +1,59 @@
+import type { PropertyChanges } from "@fulate/core";
+import type { RectangleOption, TextOption } from "@fulate/ui";
+import type { Align, BoxSizing, Display, FlexDirection, Justify, Overflow, PositionType, Wrap } from "yoga-layout";
+type YogaStyleSize = number | `${number}%`;
+type YogaStyleSizeAndAuto = YogaStyleSize | "auto";
+export interface YogaStyleOptions {
+    display?: Display;
+    width?: YogaStyleSizeAndAuto;
+    height?: YogaStyleSizeAndAuto;
+    minWidth?: YogaStyleSize;
+    minHeight?: YogaStyleSize;
+    maxWidth?: YogaStyleSize;
+    maxHeight?: YogaStyleSize;
+    alignContent?: Align;
+    alignItems?: Align;
+    alignSelf?: Align;
+    aspectRatio?: number;
+    flex?: number;
+    flexBasis?: YogaStyleSizeAndAuto;
+    flexDirection?: FlexDirection;
+    flexGrow?: number;
+    flexShrink?: number;
+    flexWrap?: Wrap;
+    justifyContent?: Justify;
+    overflow?: Overflow | "visible" | "hidden";
+    paddingTop?: YogaStyleSize;
+    paddingLeft?: YogaStyleSize;
+    paddingRight?: YogaStyleSize;
+    paddingBottom?: YogaStyleSize;
+    padding?: YogaStyleSize;
+    marginTop?: YogaStyleSizeAndAuto;
+    marginLeft?: YogaStyleSizeAndAuto;
+    marginRight?: YogaStyleSizeAndAuto;
+    marginBottom?: YogaStyleSizeAndAuto;
+    margin?: YogaStyleSizeAndAuto;
+    position?: PositionType;
+    left?: YogaStyleSize;
+    top?: YogaStyleSize;
+    bottom?: YogaStyleSize;
+    right?: YogaStyleSize;
+    gap?: YogaStyleSize;
+    inset?: YogaStyleSize;
+    boxSizing?: BoxSizing;
+}
+type YogaOwnedBaseKeys = keyof YogaStyleOptions | "fitWidth" | "fitHeight";
+/** Div 的唯一 authored creation state。 */
+export type YogaOption = Omit<RectangleOption<any>, YogaOwnedBaseKeys> & YogaStyleOptions;
+/** Span 的唯一 authored creation state。 */
+export type SpanOption = Omit<TextOption<any>, YogaOwnedBaseKeys> & YogaStyleOptions;
+export type YogaOptionPatch = Partial<Omit<YogaOption, "key" | "children">>;
+export type SpanOptionPatch = Partial<Omit<SpanOption, "key" | "children">>;
+export declare const YOGA_STYLE_KEYS: readonly ["display", "left", "top", "bottom", "right", "width", "height", "minWidth", "minHeight", "maxWidth", "maxHeight", "alignContent", "alignItems", "alignSelf", "aspectRatio", "flex", "flexBasis", "flexDirection", "flexGrow", "flexShrink", "flexWrap", "justifyContent", "overflow", "paddingTop", "paddingLeft", "paddingRight", "paddingBottom", "padding", "marginTop", "marginLeft", "marginRight", "marginBottom", "margin", "position", "gap", "inset", "boxSizing"];
+export type YogaStyleKey = typeof YOGA_STYLE_KEYS[number];
+export declare const YOGA_STYLE_KEY_SET: Set<"display" | "width" | "height" | "minWidth" | "minHeight" | "maxWidth" | "maxHeight" | "alignContent" | "alignItems" | "alignSelf" | "aspectRatio" | "flex" | "flexBasis" | "flexDirection" | "flexGrow" | "flexShrink" | "flexWrap" | "justifyContent" | "overflow" | "paddingTop" | "paddingLeft" | "paddingRight" | "paddingBottom" | "padding" | "marginTop" | "marginLeft" | "marginRight" | "marginBottom" | "margin" | "position" | "left" | "top" | "bottom" | "right" | "gap" | "inset" | "boxSizing">;
+/** 把 Yoga authored fields 安装到元素唯一 Properties，不建立旁路 style state。 */
+export declare function initializeYogaStyleProperties(properties: Record<string, any>, options: YogaStyleOptions): void;
+/** resolved frame fields 只由 Yoga 计算结果驱动 Core transform impact。 */
+export declare function withoutYogaResolvedFrameChanges(changes: PropertyChanges): PropertyChanges;
+export {};

package/dist/text-row/contract.d.ts

@@ -0,0 +1,15 @@
+import type { Node } from "@fulate/core";
+import type { TextLineBoxMetrics } from "@fulate/ui";
+export declare const textRowParticipantKey: unique symbol;
+export declare const textRowProviderKey: unique symbol;
+export interface TextRowParticipant {
+    getTextRowLineMetrics(): TextLineBoxMetrics;
+    textRowMetricsChanged(): void;
+}
+export interface TextRowProvider {
+    readonly textRowContentHeight: number;
+    getTextRowAlphabeticBaseline(): number;
+    syncTextRowMetrics(): void;
+}
+export declare function getTextRowParticipant(node: Node): TextRowParticipant;
+export declare function getTextRowProvider(node: Node | undefined): TextRowProvider;

package/dist/text-row/index.d.ts

@@ -0,0 +1,24 @@
+import { Div, type YogaOption } from "../div";
+import { textRowParticipantKey, textRowProviderKey, type TextRowParticipant, type TextRowProvider } from "./contract";
+type TextRowOwnedStyle = "alignItems" | "flexDirection";
+export type TextRowOption = Omit<YogaOption, TextRowOwnedStyle>;
+export type TextRowOptionPatch = Partial<Omit<TextRowOption, "key" | "children">>;
+/** A Yoga row whose direct text participants share one painted baseline. */
+export declare class TextRow extends Div implements TextRowParticipant, TextRowProvider {
+    readonly [textRowParticipantKey]: this;
+    readonly [textRowProviderKey]: this;
+    private alphabeticBaseline;
+    private intrinsicContentHeight;
+    constructor(options?: TextRowOption);
+    setOptions(options?: TextRowOptionPatch): this;
+    getTextRowLineMetrics(): {
+        alphabeticBaseline: number;
+        height: number;
+    };
+    get textRowContentHeight(): number;
+    getTextRowAlphabeticBaseline(): number;
+    syncTextRowMetrics(): void;
+    textRowMetricsChanged(): void;
+    protected onChildrenChanged(): void;
+}
+export {};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@fulate/yoga",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@fulate/core": "*",
+    "@fulate/ui": "*",
+    "@fulate/vue": "*",
+    "yoga-layout": "^3.2.1"
+  }
+}