@fulate/ui 1.0.3 → 1.0.5

package/README.md

@@ -163,6 +163,57 @@ const metrics = measureTextRun(ctx, text, root.skin.text, 14, 500);
 测量所需的文字状态写入 `ctx`，不会调用 `save()` 或 `restore()`；Canvas 生命周期以及业务特有的
 文字顺序、对齐和绘制仍由 Shape 自己拥有。
 
+### 组合型多行文本
+
+需要在一个非 `Text` Element 中放置可换行文字时，使用公开的 `TextBlock` 组合原语。它与 `Text`
+共用同一份 hard-break、grapheme、`wordWrap`、`maxLines` 和 `ellipsis` 排版实现：
+
+```ts
+import {
+  TextBlock,
+  getTextBlockVisualBounds,
+  paintTextBlock,
+  resolveTextStyle
+} from "@fulate/ui";
+
+const style = resolveTextStyle(
+  {
+    fontSize: 14,
+    fontWeight: 500,
+    textAlign: "left",
+    textBaseline: "top",
+    verticalAlign: "top",
+    wordWrap: true
+  },
+  root.skin.text
+);
+const block = new TextBlock();
+const snapshot = block.sync({
+  text,
+  style,
+  width: 120,
+  height: 80,
+  overflow: "visible",
+  wordWrap: true,
+  ellipsis: false
+});
+
+paintTextBlock(ctx, snapshot, style, 120, 80);
+const visualBounds = getTextBlockVisualBounds(snapshot, style, 120, 80);
+```
+
+`measure()` 只返回紧凑的聚合 metrics；最终宽高确定后调用一次 `sync()`，并把同一个 snapshot
+同时交给 `paintTextBlock()` 和 `getTextBlockVisualBounds()`。`paintTextBlock()` 不会替调用者
+`save()`/`restore()`、安装 clip 或决定坐标变换；组合 owner 自己负责 Canvas 生命周期、裁剪和把
+视觉 bounds 接入自己的 transform/dirty-rect 计算。`overflow: "visible"` 不会自动把文字裁掉，
+也不会自动改变 owner 的 authored 宽高；使用 `overflow: "hidden"` 时，真正的 Canvas clip 仍由
+组合 owner 安装。
+
+`TextBlock` 不属于任何 `Element`、`Root`、History 或 frame runtime。组合 owner 负责保存 block、
+在输入或 Skin 变化时调用 `invalidate()`，并在需要响应浏览器字体加载完成时订阅
+`subscribeTextMeasurementChanges()`；返回的函数用于解除订阅。不要绕过 `@fulate/ui` 根入口导入
+`TextBlock` 的内部实现，也不要为同一段文字另建一套换行或测量器。
+
 ## Editor capabilities
 
 UI 元素通过对象 identity token 直接提供 Selection、Transform、Snap、Point 与 Content capability；

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-export { measureTextWidth, fitTextWithEllipsis } from "./text/layout";
+export { measureTextWidth, fitTextWithEllipsis, subscribeTextMeasurementChanges } from "./text/layout";
+export type { TextLayoutLine, TextLayoutMetrics, TextLayoutOptions, TextLayoutSnapshot } from "./text/layout";
 export { measureTextRun } from "./text/paint";
+export { paintTextBlock } from "./text/paint";
 export type { TextLineBoxMetrics, TextRunMetrics } from "./text/paint";
+export { TextBlock, getTextBlockVisualBounds } from "./text/block";
+export type { TextBlockLayoutInput } from "./text/block";
 export { Rectangle, RectangleProperties, RectangleTransform } from "./rectangle";
 export type { RectangleOption, RectangleOptionPatch } from "./rectangle";
 export { Circle, CircleTransform } from "./circle";
@@ -9,8 +13,8 @@ export { Polygon, PolygonTransform } from "./polygon";
 export type { PolygonOption } from "./polygon";
 export { VectorPath, VectorPathProperties, VectorPathTransform } from "./vector-path";
 export type { VectorPathCommand, VectorPathGeometry, VectorPathOption } from "./vector-path";
-export { Text, TextProperties, TextTransform } from "./text";
-export type { TextOption } from "./text";
+export { Text, TextProperties, TextTransform, resolveTextStyle } from "./text";
+export type { TextOption, TextStyleConfig, TextStyleKey, ResolvedTextStyle } from "./text";
 export { Image, ImageProperties, ImageTransform } from "./image";
 export type { ImageOption, ImageResizeOption, ImageResizeMode } from "./image";
 export { Bitmap } from "./bitmap";

package/dist/index.js

@@ -12,13 +12,21 @@ function invalidateFontMeasurements() {
 	clearCache();
 	for (const listener of measurementListeners) listener();
 }
+/**
+* Subscribe a non-Text owner to browser font measurement completion.
+*
+* TextBlock has no Root lifecycle of its own, so composite owners use this
+* hook to invalidate their block and publish the resulting visual change.
+*/
 function subscribeTextMeasurementChanges(listener) {
 	if (!observesFontLoading && document.fonts) {
 		observesFontLoading = true;
 		document.fonts.addEventListener("loadingdone", invalidateFontMeasurements);
 	}
 	measurementListeners.add(listener);
-	return () => measurementListeners.delete(listener);
+	return () => {
+		measurementListeners.delete(listener);
+	};
 }
 function normalizeText(text) {
 	return text.replace(/\r\n/g, "\n").replace(/[\r\f]/g, "\n");
@@ -749,7 +757,7 @@ var TEXT_STYLE_KEYS = Object.keys(TEXT_STYLE_DEFAULTS);
 function buildFontString(style, fontSize = style.fontSize, fontWeight = style.fontWeight) {
 	return `${style.fontStyle} ${fontWeight} ${fontSize}px ${style.fontFamily}`;
 }
-function resolveTextStyle(instance, defaults) {
+function resolveTextStyle(instance, defaults = TEXT_STYLE_DEFAULTS) {
 	const resolved = {};
 	for (const key of TEXT_STYLE_KEYS) {
 		const authored = instance[key];
@@ -841,7 +849,13 @@ function measureTextLineBoxMetrics(text, style) {
 		height: lineHeight
 	};
 }
-/** 绘制一份已排版文字块；Text 与内部组合共同使用。 */
+/**
+* Paint a previously synchronized text block.
+*
+* The painter deliberately does not call `save()`/`restore()` or install a
+* clip. The owner chooses the transform and clipping policy, then uses the
+* same snapshot for `getTextBlockVisualBounds`.
+*/
 function paintTextBlock(ctx, layout, style, width, height) {
 	if (layout.lines.length === 0) return;
 	const font = buildFontString(style);
@@ -952,17 +966,18 @@ function paintTextContent(self, ctx, offsetY = 0) {
 	ctx.restore();
 }
 //#endregion
-//#region packages/ui/src/paint/circle.ts
-/** 在当前 Canvas path 中加入圆形；不创建场景或 Geometry 对象。 */
-function traceCirclePath(ctx, center, radius) {
-	ctx.arc(center.x, center.y, radius, 0, Math.PI * 2);
-}
-//#endregion
 //#region packages/ui/src/text/block.ts
 function sameLayoutKey(left, right) {
 	return left !== null && left.text === right.text && left.font === right.font && left.letterSpacing === right.letterSpacing && left.width === right.width && left.height === right.height && left.lineHeight === right.lineHeight && left.wordWrap === right.wordWrap && left.maxLines === right.maxLines && left.overflow === right.overflow && left.ellipsis === right.ellipsis;
 }
-/** Text 与内部组合共享的唯一准备和最终排版 owner。 */
+/**
+* The canonical layout owner for a non-Element text block.
+*
+* A block owns prepared text and the latest final snapshot only; it does not
+* own an Element, Root, transform, clip, dirty rectangle, or History entry.
+* Composite owners should call `measure()` for aggregate metrics, then call
+* `sync()` with the final width/height before painting or computing bounds.
+*/
 var TextBlock = class {
 	prepared = null;
 	metrics = null;
@@ -1023,7 +1038,7 @@ var TextBlock = class {
 		};
 	}
 };
-/** 返回与共享 glyph painter 一致的文字 visual bounds。 */
+/** Return visual bounds for the same snapshot consumed by `paintTextBlock`. */
 function getTextBlockVisualBounds(layout, style, width, height) {
 	if (layout.lines.length === 0) return null;
 	let left = Infinity;
@@ -1059,6 +1074,12 @@ function getTextBlockVisualBounds(layout, style, width, height) {
 	};
 }
 //#endregion
+//#region packages/ui/src/paint/circle.ts
+/** 在当前 Canvas path 中加入圆形；不创建场景或 Geometry 对象。 */
+function traceCirclePath(ctx, center, radius) {
+	ctx.arc(center.x, center.y, radius, 0, Math.PI * 2);
+}
+//#endregion
 //#region packages/ui/src/connection-port-decoration.ts
 var DOT_RADIUS = 4;
 var LABEL_GAP = 3;
@@ -5946,4 +5967,4 @@ function applyLineTreeTopologyDelta(topology, delta, direction) {
 	};
 }
 //#endregion
-export { BaseLine, Bitmap, Circle, CircleTransform, ContentEditingCapabilityToken, DEFAULT_LINE_TREE_BRANCH_STYLE, EMPTY_LINE_TREE_TOPOLOGY, EditorFrameFlush, EndpointRelationIndex, Group, GroupTransform, Image, ImageProperties, ImageTransform, Line, LineTransform, LineTree, LineTreeProperties, LineTreeTransform, PointEditingCapabilityToken, Polygon, PolygonTransform, Rectangle, RectangleProperties, RectangleTransform, RippleOverlay, ScrollView, ScrollViewTransform, SelectionBehaviorCapabilityToken, SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, SnapSourceCapabilityToken, Text, TextProperties, TextTransform, TransformInteractionCapabilityToken, Triangle, TriangleTransform, VectorPath, VectorPathProperties, VectorPathTransform, WorkerSurfacePool, Workspace, WorkspaceProperties, addLineTreeBranchAtTail, applyLineTreeTopologyDelta, arrow, autoPlacement, computePosition, connectEndpoint, connectionPortAccepts, createFloatingPlatform, createLineTreeTopology, createLineTreeTopologyDelta, defineEditorCapability, detectOverflow, disconnectEndpoint, fitTextWithEllipsis, fitWorkspace, flip, getEditorCapability, getEditorFrameFlush, getEndpointRelationIndex, getLineTreeBindableEndpoints, getLineTreeBranch, getLineTreeEndpointRelationBindings, getLineTreeJunctionAnchorIds, getLineTreePoint, getLineTreePointReferenceCounts, hasConnectionPortCapacity, hide, insertLineTreePoint, isEditorCapabilityHost, isEndpointRelationSource, limitShift, measureTextRun, measureTextWidth, moveLineTreePoint, offset, remapLineTreeRelations, removeLineTreeBranch, removeLineTreePoint, resolveConnectEndpointChange, resolveConnectionPortChanges, resolveDisconnectEndpointChanges, scaleLineTreeTopology, shift, size, updateLineTreeBranchStyle, workspaceFocusInsetsKey };
+export { BaseLine, Bitmap, Circle, CircleTransform, ContentEditingCapabilityToken, DEFAULT_LINE_TREE_BRANCH_STYLE, EMPTY_LINE_TREE_TOPOLOGY, EditorFrameFlush, EndpointRelationIndex, Group, GroupTransform, Image, ImageProperties, ImageTransform, Line, LineTransform, LineTree, LineTreeProperties, LineTreeTransform, PointEditingCapabilityToken, Polygon, PolygonTransform, Rectangle, RectangleProperties, RectangleTransform, RippleOverlay, ScrollView, ScrollViewTransform, SelectionBehaviorCapabilityToken, SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, SnapSourceCapabilityToken, Text, TextBlock, TextProperties, TextTransform, TransformInteractionCapabilityToken, Triangle, TriangleTransform, VectorPath, VectorPathProperties, VectorPathTransform, WorkerSurfacePool, Workspace, WorkspaceProperties, addLineTreeBranchAtTail, applyLineTreeTopologyDelta, arrow, autoPlacement, computePosition, connectEndpoint, connectionPortAccepts, createFloatingPlatform, createLineTreeTopology, createLineTreeTopologyDelta, defineEditorCapability, detectOverflow, disconnectEndpoint, fitTextWithEllipsis, fitWorkspace, flip, getEditorCapability, getEditorFrameFlush, getEndpointRelationIndex, getLineTreeBindableEndpoints, getLineTreeBranch, getLineTreeEndpointRelationBindings, getLineTreeJunctionAnchorIds, getLineTreePoint, getLineTreePointReferenceCounts, getTextBlockVisualBounds, hasConnectionPortCapacity, hide, insertLineTreePoint, isEditorCapabilityHost, isEndpointRelationSource, limitShift, measureTextRun, measureTextWidth, moveLineTreePoint, offset, paintTextBlock, remapLineTreeRelations, removeLineTreeBranch, removeLineTreePoint, resolveConnectEndpointChange, resolveConnectionPortChanges, resolveDisconnectEndpointChanges, resolveTextStyle, scaleLineTreeTopology, shift, size, subscribeTextMeasurementChanges, updateLineTreeBranchStyle, workspaceFocusInsetsKey };

package/dist/text/block.d.ts

@@ -1,9 +1,10 @@
 import type { Rect } from "@fulate/share";
 import { TextLayoutSnapshot, type TextLayoutMetrics } from "./layout";
 import { type ResolvedTextStyle } from "./style";
+/** Input for one composite text layout owner. */
 export interface TextBlockLayoutInput {
     readonly text: string;
-    readonly style: ResolvedTextStyle;
+    readonly style: Readonly<ResolvedTextStyle>;
     readonly width?: number;
     readonly height?: number;
     readonly overflow: "hidden" | "visible";
@@ -11,7 +12,14 @@ export interface TextBlockLayoutInput {
     readonly maxLines?: number;
     readonly ellipsis?: boolean;
 }
-/** Text 与内部组合共享的唯一准备和最终排版 owner。 */
+/**
+ * The canonical layout owner for a non-Element text block.
+ *
+ * A block owns prepared text and the latest final snapshot only; it does not
+ * own an Element, Root, transform, clip, dirty rectangle, or History entry.
+ * Composite owners should call `measure()` for aggregate metrics, then call
+ * `sync()` with the final width/height before painting or computing bounds.
+ */
 export declare class TextBlock {
     private prepared;
     private metrics;
@@ -27,5 +35,5 @@ export declare class TextBlock {
     private getPrepared;
     private getLayoutKey;
 }
-/** 返回与共享 glyph painter 一致的文字 visual bounds。 */
-export declare function getTextBlockVisualBounds(layout: TextLayoutSnapshot, style: ResolvedTextStyle, width: number, height: number): Rect | null;
+/** Return visual bounds for the same snapshot consumed by `paintTextBlock`. */
+export declare function getTextBlockVisualBounds(layout: TextLayoutSnapshot, style: Readonly<ResolvedTextStyle>, width: number, height: number): Rect | null;

package/dist/text/index.d.ts

@@ -2,10 +2,10 @@ import { ChangeImpact, type ElementTransformClass, type GeometrySnapshot, type L
 import { Rectangle, RectangleProperties, RectangleTransform, type RectangleOption } from "../rectangle";
 import { type BackgroundColor, type PointView, type Rect } from "@fulate/share";
 import { type TextLineBoxMetrics } from "./paint";
-import { TEXT_STYLE_DEFAULTS, type TextStyleKey, type TextStyleConfig, type ResolvedTextStyle, buildFontString } from "./style";
+import { TEXT_STYLE_DEFAULTS, type TextStyleKey, type TextStyleConfig, type ResolvedTextStyle, buildFontString, resolveTextStyle } from "./style";
 import { type ContentEditingConsumer, type ContentEditingSession, type EditorCapabilityToken } from "../editor/capability";
 export type { TextStyleConfig, TextStyleKey, ResolvedTextStyle };
-export { buildFontString, TEXT_STYLE_DEFAULTS };
+export { buildFontString, resolveTextStyle, TEXT_STYLE_DEFAULTS };
 export { measureTextRun } from "./paint";
 export type { TextLineBoxMetrics, TextRunMetrics } from "./paint";
 /**

package/dist/text/layout.d.ts

@@ -1,5 +1,11 @@
 import { type LayoutLine } from "@chenglou/pretext";
-export declare function subscribeTextMeasurementChanges(listener: () => void): () => boolean;
+/**
+ * Subscribe a non-Text owner to browser font measurement completion.
+ *
+ * TextBlock has no Root lifecycle of its own, so composite owners use this
+ * hook to invalidate their block and publish the resulting visual change.
+ */
+export declare function subscribeTextMeasurementChanges(listener: () => void): () => void;
 export interface TextLayoutLine {
     readonly text: string;
     readonly width: number;

package/dist/text/paint.d.ts

@@ -54,6 +54,12 @@ export interface TextLineBoxMetrics {
 }
 /** Measure the line box produced by the existing Text painter. */
 export declare function measureTextLineBoxMetrics(text: string, style: ResolvedTextStyle): TextLineBoxMetrics;
-/** 绘制一份已排版文字块；Text 与内部组合共同使用。 */
-export declare function paintTextBlock(ctx: CanvasRenderingContext2D, layout: TextLayoutSnapshot, style: ResolvedTextStyle, width: number, height: number): void;
+/**
+ * Paint a previously synchronized text block.
+ *
+ * The painter deliberately does not call `save()`/`restore()` or install a
+ * clip. The owner chooses the transform and clipping policy, then uses the
+ * same snapshot for `getTextBlockVisualBounds`.
+ */
+export declare function paintTextBlock(ctx: CanvasRenderingContext2D, layout: TextLayoutSnapshot, style: Readonly<ResolvedTextStyle>, width: number, height: number): void;
 export declare function paintTextContent(self: Text, ctx: CanvasRenderingContext2D, offsetY?: number): void;

package/dist/text/style.d.ts

@@ -10,4 +10,4 @@ export declare function buildFontString(style: {
     fontSize?: number;
     fontFamily?: string;
 }, fontSize?: number, fontWeight?: string | number): string;
-export declare function resolveTextStyle(instance: Record<string, any>, defaults: Record<string, any>): ResolvedTextStyle;
+export declare function resolveTextStyle(instance: Partial<TextStyleConfig>, defaults?: Readonly<Required<TextStyleConfig>>): ResolvedTextStyle;

package/package.json

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