@fulate/ui 1.0.9 → 1.0.10

package/README.md

@@ -159,10 +159,13 @@ import { measureTextRun } from "@fulate/ui";
 const metrics = measureTextRun(ctx, text, root.skin.text, 14, 500);
 ```
 
-每次调用只执行一次 `ctx.measureText()`，返回 `font`、`width`、`lineHeight`、`drawY` 和
-`alphabeticBaseline`。空文本的 `width` 为 `0`，但仍测量一个空格以取得稳定基线。函数会把本次
-测量所需的文字状态写入 `ctx`，不会调用 `save()` 或 `restore()`；Canvas 生命周期以及业务特有的
-文字顺序、对齐和绘制仍由 Shape 自己拥有。
+每次调用只执行一次 `ctx.measureText()`，返回 `font`、`width`、`lineHeight`、`drawY`、
+`alphabeticBaseline`、`textBaseline` 和 `letterSpacing`。`drawY` 根据原生 Canvas 的
+`fontBoundingBoxAscent`/`fontBoundingBoxDescent` 把字体行框放到行框中心；`alphabeticBaseline`
+是同一行框内的规范 alphabetic baseline，因此不同字号的 run 可以直接对齐。空文本的 `width`
+为 `0`，但仍测量一个空格以取得稳定字体度量。函数会把本次测量所需的文字状态写入 `ctx`，不会
+调用 `save()` 或 `restore()`；Canvas 生命周期以及业务特有的文字顺序、对齐和绘制仍由 Shape
+自己拥有。
 
 ### 组合型多行文本
 

package/dist/index.js

@@ -8,8 +8,10 @@ import { Easing, Tween } from "@tweenjs/tween.js";
 var graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 var measurementListeners = /* @__PURE__ */ new Set();
 var observesFontLoading = false;
+var textLineBoxMetricsCache = /* @__PURE__ */ new Map();
 function invalidateFontMeasurements() {
 	clearCache();
+	textLineBoxMetricsCache.clear();
 	for (const listener of measurementListeners) listener();
 }
 /**
@@ -50,14 +52,35 @@ function measurePlainText(text, font) {
 	return context.measureText(text).width;
 }
 /**
-* Return the painted alphabetic baseline relative to the Canvas draw Y.
-* The same shared Canvas context and font string also own Text width metrics.
+* Resolve one line box from a native Canvas measurement. The font bounding
+* box is stable for the font state, while `alphabeticBaseline` translates the
+* selected Canvas baseline into the same canonical alphabetic coordinate used
+* by TextRow and composite owners.
 */
-function measureTextAlphabeticBaselineOffset(text, font, textBaseline) {
+function resolveTextLinePlacement(metrics, lineHeight) {
+	const drawY = (lineHeight + metrics.fontBoundingBoxAscent - metrics.fontBoundingBoxDescent) / 2;
+	return {
+		drawY,
+		alphabeticBaseline: drawY - metrics.alphabeticBaseline,
+		height: lineHeight
+	};
+}
+/**
+* Measure the font line box once and reuse it for Text painting, placeholders,
+* and composite TextBlock owners. The representative space supplies the
+* font-level Canvas metrics without making placement depend on the content of
+* an individual line.
+*/
+function measureTextLinePlacement(font, textBaseline, lineHeight) {
+	const key = `${font}\u0000${textBaseline}\u0000${lineHeight}`;
+	const cached = textLineBoxMetricsCache.get(key);
+	if (cached) return cached;
 	const context = getPlainMeasureContext();
 	context.font = font;
 	context.textBaseline = textBaseline;
-	return -context.measureText(text || " ").alphabeticBaseline;
+	const metrics = resolveTextLinePlacement(context.measureText(" "), lineHeight);
+	textLineBoxMetricsCache.set(key, metrics);
+	return metrics;
 }
 /** A no-wrap run can stay one Canvas string until rich layout is requested. */
 function canUsePlainText(text, letterSpacing) {
@@ -809,40 +832,39 @@ function clearTextShadow(ctx) {
 	ctx.shadowOffsetX = 0;
 	ctx.shadowOffsetY = 0;
 }
-function getTextLineStartY(textBaseline, lineHeight) {
-	return textBaseline === "middle" ? lineHeight / 2 : textBaseline === "bottom" ? lineHeight : 0;
-}
-function getTextLineDrawY(textBaseline, fontSize, lineHeight) {
-	return getTextLineStartY(textBaseline, lineHeight) + (lineHeight - fontSize) / 2;
-}
 /**
 * Measure one native Canvas text run with Fulate's resolved font and line-box
 * semantics. This performs one `measureText()` call and writes the run's font,
 * baseline, and letter spacing to the supplied context without saving or
-* restoring it. Empty text measures a space for baseline data but reports zero
+* restoring it. The font bounding box determines the centered draw position;
+* the returned alphabetic baseline is the canonical coordinate for row
+* alignment. Empty text measures a space for baseline data but reports zero
 * width.
 */
 function measureTextRun(ctx, text, style, fontSize = style.fontSize, fontWeight = style.fontWeight) {
 	const font = buildFontString(style, fontSize, fontWeight);
 	const lineHeight = fontSize * style.lineHeight;
-	const drawY = getTextLineDrawY(style.textBaseline, fontSize, lineHeight);
 	setTextState(ctx, font, style.letterSpacing);
 	ctx.textBaseline = style.textBaseline;
-	const metrics = ctx.measureText(text || " ");
+	const measured = ctx.measureText(text || " ");
+	const lineMetrics = resolveTextLinePlacement(measured, lineHeight);
 	return {
 		font,
-		width: text ? metrics.width : 0,
+		width: text ? measured.width : 0,
 		lineHeight,
-		drawY,
-		alphabeticBaseline: drawY - metrics.alphabeticBaseline
+		drawY: lineMetrics.drawY,
+		alphabeticBaseline: lineMetrics.alphabeticBaseline,
+		textBaseline: style.textBaseline,
+		letterSpacing: style.letterSpacing
 	};
 }
-/** Measure the line box produced by the existing Text painter. */
-function measureTextLineBoxMetrics(text, style) {
+/** Measure the line box shared by Text, Span, and composite text owners. */
+function measureTextLineBoxMetrics(style) {
 	const lineHeight = style.fontSize * style.lineHeight;
+	const { alphabeticBaseline, height } = measureTextLinePlacement(buildFontString(style), style.textBaseline, lineHeight);
 	return {
-		alphabeticBaseline: getTextLineDrawY(style.textBaseline, style.fontSize, lineHeight) + measureTextAlphabeticBaselineOffset(text, buildFontString(style), style.textBaseline),
-		height: lineHeight
+		alphabeticBaseline,
+		height
 	};
 }
 /**
@@ -856,7 +878,7 @@ function paintTextBlock(ctx, layout, style, width, height) {
 	if (layout.lines.length === 0) return;
 	const font = buildFontString(style);
 	const lineHeight = style.fontSize * style.lineHeight;
-	const drawY = getTextLineDrawY(style.textBaseline, style.fontSize, lineHeight);
+	const lineMetrics = measureTextLinePlacement(font, style.textBaseline, lineHeight);
 	const blockOffset = layout.getBlockVerticalOffset(height, style.verticalAlign);
 	setTextState(ctx, font, style.letterSpacing);
 	ctx.textAlign = "left";
@@ -871,7 +893,7 @@ function paintTextBlock(ctx, layout, style, width, height) {
 	for (let index = 0; index < layout.lines.length; index++) {
 		const line = layout.lines[index];
 		const x = isLeftAligned ? 0 : layout.getLineX(index, width, style.textAlign);
-		const y = drawY + index * lineHeight + blockOffset;
+		const y = lineMetrics.drawY + index * lineHeight + blockOffset;
 		if (hasTextShadow) applyTextShadow(ctx, style.textShadow);
 		if (hasStroke) {
 			ctx.strokeStyle = strokeColor;
@@ -898,7 +920,6 @@ function paintTextContent(self, ctx, offsetY = 0) {
 	const w = self.width || 0;
 	const h = self.height || 0;
 	const lineHeightPx = style.fontSize * style.lineHeight;
-	const drawY = getTextLineDrawY(style.textBaseline, style.fontSize, lineHeightPx);
 	const ls = style.letterSpacing;
 	const layout = self.textLayout;
 	const blockOffset = layout.getBlockVerticalOffset(h, style.verticalAlign);
@@ -944,7 +965,8 @@ function paintTextContent(self, ctx, offsetY = 0) {
 		const phWidth = measureTextWidth(self.placeholder, font, ls);
 		const phX = style.textAlign === "center" ? (w - phWidth) / 2 : style.textAlign === "right" ? w - phWidth : 0;
 		const phBlockOffset = layout.getBlockVerticalOffset(h, style.verticalAlign, lineHeightPx);
-		drawTextLine(ctx, self.placeholder, phX, drawY + phBlockOffset, font, ls, true, false);
+		const lineMetrics = measureTextLinePlacement(font, style.textBaseline, lineHeightPx);
+		drawTextLine(ctx, self.placeholder, phX, lineMetrics.drawY + phBlockOffset, font, ls, true, false);
 		ctx.fillStyle = fillStyle;
 	}
 	if (self.isEditing && self.caretVisible && self.textarea) {
@@ -3140,13 +3162,12 @@ var Text = class extends Rectangle {
 		return this.textBlock.layout;
 	}
 	/** @internal Shared by TextRow layout and the final Text painter. */
-	getTextLineBoxMetrics(text = this.text) {
+	getTextLineBoxMetrics() {
 		const style = this.getResolvedTextStyle();
 		const cached = this.textLineBoxMetricsCache;
-		if (cached?.text === text && cached.style === style) return cached.metrics;
-		const metrics = measureTextLineBoxMetrics(text, style);
+		if (cached?.style === style) return cached.metrics;
+		const metrics = measureTextLineBoxMetrics(style);
 		this.textLineBoxMetricsCache = {
-			text,
 			style,
 			metrics
 		};
@@ -3155,7 +3176,7 @@ var Text = class extends Rectangle {
 	/** @internal Alphabetic baseline relative to this Text box. */
 	getTextBlockFirstAlphabeticBaseline() {
 		const style = this.getResolvedTextStyle();
-		return this.textLayout.getBlockVerticalOffset(this.height ?? 0, style.verticalAlign) + this.getTextLineBoxMetrics(this.textLayout.lines[0]?.text ?? "").alphabeticBaseline;
+		return this.textLayout.getBlockVerticalOffset(this.height ?? 0, style.verticalAlign) + this.getTextLineBoxMetrics().alphabeticBaseline;
 	}
 	/** @internal The editor frame follows the Text box, not visible overflow. */
 	getSelectionFrameBounds() {

package/dist/text/index.d.ts

@@ -118,7 +118,7 @@ export declare class Text<P extends TextProperties = TextProperties, O extends T
     getFontString(style?: Required<TextStyleConfig>): string;
     get textLayout(): import("./layout").TextLayoutSnapshot;
     /** @internal Shared by TextRow layout and the final Text painter. */
-    getTextLineBoxMetrics(text?: string): TextLineBoxMetrics;
+    getTextLineBoxMetrics(): TextLineBoxMetrics;
     /** @internal Alphabetic baseline relative to this Text box. */
     getTextBlockFirstAlphabeticBaseline(): number;
     /** @internal The editor frame follows the Text box, not visible overflow. */

package/dist/text/layout.d.ts

@@ -1,4 +1,19 @@
 import { type LayoutLine } from "@chenglou/pretext";
+/**
+ * The vertical placement of a Canvas text run is a font property, not a
+ * `fontSize` approximation. Keep one resolved line box per native font state
+ * so painting can reuse the measurement without measuring on every frame.
+ */
+export interface TextLineBoxMetrics {
+    /** Alphabetic baseline relative to the line-box top. */
+    readonly alphabeticBaseline: number;
+    /** Line-box height in logical pixels. */
+    readonly height: number;
+}
+export interface TextLinePlacementMetrics extends TextLineBoxMetrics {
+    /** Canvas draw Y relative to the line-box top. */
+    readonly drawY: number;
+}
 /**
  * Subscribe a non-Text owner to browser font measurement completion.
  *
@@ -29,10 +44,23 @@ export interface TextLayoutMetrics {
     readonly truncated: boolean;
 }
 /**
- * Return the painted alphabetic baseline relative to the Canvas draw Y.
- * The same shared Canvas context and font string also own Text width metrics.
+ * Resolve one line box from a native Canvas measurement. The font bounding
+ * box is stable for the font state, while `alphabeticBaseline` translates the
+ * selected Canvas baseline into the same canonical alphabetic coordinate used
+ * by TextRow and composite owners.
+ */
+export declare function resolveTextLinePlacement(metrics: Pick<TextMetrics, "fontBoundingBoxAscent" | "fontBoundingBoxDescent" | "alphabeticBaseline">, lineHeight: number): {
+    drawY: number;
+    alphabeticBaseline: number;
+    height: number;
+};
+/**
+ * Measure the font line box once and reuse it for Text painting, placeholders,
+ * and composite TextBlock owners. The representative space supplies the
+ * font-level Canvas metrics without making placement depend on the content of
+ * an individual line.
  */
-export declare function measureTextAlphabeticBaselineOffset(text: string, font: string, textBaseline: CanvasTextBaseline): number;
+export declare function measureTextLinePlacement(font: string, textBaseline: CanvasTextBaseline, lineHeight: number): TextLinePlacementMetrics;
 /**
  * Measure one text run through the same engine used by Text and Span.
  * `white-space: pre-wrap` keeps the caller's spaces and hard breaks intact.

package/dist/text/paint.d.ts

@@ -1,7 +1,8 @@
-import { type TextLayoutSnapshot } from "./layout";
+import { type TextLayoutSnapshot, type TextLineBoxMetrics } from "./layout";
 import type { Text } from "./index";
 import { type ResolvedTextStyle } from "./style";
 import type { ShadowOption, TextStyleConfig } from "@fulate/core";
+export type { TextLineBoxMetrics } from "./layout";
 export declare function resolveColorFill(ctx: CanvasRenderingContext2D, color: ResolvedTextStyle["color"], w: number, h: number): string | CanvasGradient;
 export declare function drawTextLine(ctx: CanvasRenderingContext2D, line: string, x: number, y: number, font: string, letterSpacing: number, doFill: boolean, doStroke: boolean): void;
 export interface TextDecorationOptions {
@@ -29,21 +30,23 @@ export interface TextRunMetrics {
     readonly drawY: number;
     /** Alphabetic baseline relative to the run's line-box top. */
     readonly alphabeticBaseline: number;
+    /** Canvas baseline used when the run was measured. */
+    readonly textBaseline: CanvasTextBaseline;
+    /** Letter spacing used when the run was measured. */
+    readonly letterSpacing: number;
 }
 /**
  * Measure one native Canvas text run with Fulate's resolved font and line-box
  * semantics. This performs one `measureText()` call and writes the run's font,
  * baseline, and letter spacing to the supplied context without saving or
- * restoring it. Empty text measures a space for baseline data but reports zero
+ * restoring it. The font bounding box determines the centered draw position;
+ * the returned alphabetic baseline is the canonical coordinate for row
+ * alignment. Empty text measures a space for baseline data but reports zero
  * width.
  */
 export declare function measureTextRun(ctx: CanvasRenderingContext2D, text: string, style: Readonly<Required<TextStyleConfig>>, fontSize?: number, fontWeight?: string | number): TextRunMetrics;
-export interface TextLineBoxMetrics {
-    readonly alphabeticBaseline: number;
-    readonly height: number;
-}
-/** Measure the line box produced by the existing Text painter. */
-export declare function measureTextLineBoxMetrics(text: string, style: ResolvedTextStyle): TextLineBoxMetrics;
+/** Measure the line box shared by Text, Span, and composite text owners. */
+export declare function measureTextLineBoxMetrics(style: ResolvedTextStyle): TextLineBoxMetrics;
 /**
  * Paint a previously synchronized text block.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulate/ui",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",