pa_font 0.3.1 → 0.3.3

package/USAGE.md

@@ -111,7 +111,7 @@ console.log(metrics.width, metrics.bbox);
 - `margin`, `padding`: `24`, `"24 32"`, `[24, 32]`, `{ x: 32, y: 24 }`, `{ top, right, bottom, left }`
 - `width`: 생략하면 `drawText(ctx)` 시 현재 canvas 폭 기준으로 자동 계산
 - `height`: `overflow: "hidden"`과 같이 쓰면 clip/clamp
-- `x`, `y`, `size`, `lineHeight`, `gap`, `align`
+- `x`, `y`, `size`, `lineHeight`, `gap`, `anchor`, `align`
 
 세부 제어 옵션:
 
@@ -119,7 +119,6 @@ console.log(metrics.width, metrics.bbox);
 - `overflowWrap`: `normal | break-word | anywhere`
 - `wordBreak`: `normal | break-all | keep-all`
 - `overflow`: `visible | hidden`
-- `overflowY`: `visible | hidden | scroll`
 - `textOverflow`: `clip | ellipsis`
 - `fontFamily`, `fontWeight`, `fontStyle`, `font`
 - `engine`: `pretext | native`
@@ -136,9 +135,15 @@ console.log(metrics.width, metrics.bbox);
 빈 줄 하나 이상은 새 문단으로 처리됩니다.
 
 - `gap`: 문단 사이 간격. `lineHeight` 배수이며 기본값은 `0.5`
+- `anchor`: 기준점을 옮깁니다. `anchor: 0.5`면 CSS의 `translate(-50%, -50%)`처럼 동작
 - `whiteSpace: "normal"`이면 문단 안 단일 줄바꿈은 공백으로 정리
 - `whiteSpace: "pre-wrap"`이면 문단 안 단일 줄바꿈 유지
-- `overflowY: "scroll"`을 쓰려면 `height`가 필요
+
+`anchor`는 다음 형식을 지원합니다.
+
+- `0.5` -> `{ x: 0.5, y: 0.5 }`
+- `[0.5, 0]`
+- `{ x: 0.5, y: 0.5 }`
 
 ## paParagraph API
 
@@ -168,6 +173,19 @@ const mobile = paragraph.relayout({ width: 280 });
 엄격한 `overflowWrap: "normal"`이 필요한 경우만 native로 내려갑니다.
 실제로 사용된 엔진은 `paragraph.layoutEngine`에서 확인할 수 있습니다.
 
+가운데를 기준점으로 두고 싶다면:
+
+```js
+const paragraph = font.paragraph("asdf", {
+  x: window.innerWidth * 0.5,
+  y: window.innerHeight * 0.5,
+  width: window.innerWidth,
+  size: window.innerHeight * 0.5,
+  align: "center",
+  anchor: 0.5,
+});
+```
+
 ### `paragraph.drawText(ctx, options?)`
 
 현재 문단 레이아웃을 canvas 텍스트로 그립니다.
@@ -184,28 +202,6 @@ paragraph.drawText(ctx, {
 - `strokeStyle`
 - `fill`
 - `stroke`
-- `scrollTop`
-
-스크롤 가능한 viewport를 만들고 싶다면:
-
-```js
-const paragraph = font.paragraph(text, {
-  width: 320,
-  height: 220,
-  overflowY: "scroll",
-  lineHeight: 1.5,
-  gap: 0.5,
-});
-
-paragraph.drawText(ctx, {
-  fillStyle: "#111",
-  scrollTop: 48,
-});
-```
-
-전체 콘텐츠 높이는 `paragraph.metrics.height`,
-현재 viewport 높이는 `paragraph.metrics.viewportHeight`,
-최대 스크롤 값은 `paragraph.metrics.maxScrollTop`에서 확인할 수 있습니다.
 
 ### `paragraph.toShape(options?)`
 

package/dist/paFont.cjs

@@ -3321,30 +3321,28 @@ function layoutParagraph(fontInstance, text, options = {}, state = {}) {
 	const textBBox = combineRects(lines.map((line) => line.bbox)) ?? emptyRect();
 	const textWidth = lines.reduce((max, line) => Math.max(max, line.width), 0);
 	const textHeight = resolvePositionedTextHeight(lines, layoutBox.contentY);
-	const finalLayoutBox = finalizeLayoutBox(layoutBox, normalized, textHeight);
+	const anchoredLayout = applyParagraphAnchor(lines, textBBox, finalizeLayoutBox(layoutBox, normalized, textHeight), normalized.anchor);
 	const cachedPrepared = pretextState?.prepared ?? retainedPreparedState.prepared ?? null;
 	const cachedPreparedWhiteSpace = pretextState?.preparedWhiteSpace ?? retainedPreparedState.preparedWhiteSpace ?? null;
 	return {
 		options: normalized,
-		lines,
+		lines: anchoredLayout.lines,
 		metrics: {
-			x: finalLayoutBox.contentBox.x,
-			y: finalLayoutBox.contentBox.y,
+			x: anchoredLayout.layoutBox.contentBox.x,
+			y: anchoredLayout.layoutBox.contentBox.y,
 			width: textWidth,
 			height: textHeight,
-			viewportHeight: finalLayoutBox.contentBox.h,
-			maxScrollTop: Math.max(0, textHeight - finalLayoutBox.contentBox.h),
 			lineCount: lines.length,
-			bbox: textBBox,
-			contentBox: { ...finalLayoutBox.contentBox },
-			paddingBox: { ...finalLayoutBox.paddingBox },
-			marginBox: { ...finalLayoutBox.marginBox },
-			clipBox: { ...finalLayoutBox.clipBox }
+			bbox: anchoredLayout.textBBox,
+			contentBox: { ...anchoredLayout.layoutBox.contentBox },
+			paddingBox: { ...anchoredLayout.layoutBox.paddingBox },
+			marginBox: { ...anchoredLayout.layoutBox.marginBox },
+			clipBox: { ...anchoredLayout.layoutBox.clipBox }
 		},
 		prepared: cachedPrepared,
 		preparedWhiteSpace: cachedPreparedWhiteSpace,
 		layoutEngine: layoutState.layoutEngine,
-		layoutBox: finalLayoutBox,
+		layoutBox: anchoredLayout.layoutBox,
 		containerWidth: layoutBox.containerWidth,
 		containerHeight: layoutBox.containerHeight
 	};
@@ -3360,12 +3358,11 @@ function normalizeParagraphOptions(fontInstance, options = {}) {
 	const width = normalizeDimension(options.width);
 	const height = normalizeDimension(options.height);
 	const gap = normalizeGap(options.gap);
-	const overflow = normalizeEnum(options.overflow, ["visible", "hidden"], "visible");
-	const overflowY = resolveOverflowY(options.overflowY, overflow);
+	const anchor = normalizeAnchor(options.anchor);
 	if (options.width != null && width == null) throw new TypeError("font.paragraph() option \"width\" must be a positive number.");
 	if (options.height != null && height == null) throw new TypeError("font.paragraph() option \"height\" must be a positive number.");
 	if (options.gap != null && gap == null) throw new TypeError("font.paragraph() option \"gap\" must be a non-negative number.");
-	if (overflowY === "scroll" && height == null) throw new TypeError("font.paragraph() option \"height\" is required when \"overflowY\" is \"scroll\".");
+	if (options.anchor != null && anchor == null) throw new TypeError("font.paragraph() option \"anchor\" must be a number, [x, y], or { x, y }.");
 	const font = resolveCanvasFont(fontInstance, textOptions.size, options);
 	return {
 		...textOptions,
@@ -3381,6 +3378,10 @@ function normalizeParagraphOptions(fontInstance, options = {}) {
 		width,
 		height,
 		gap: gap ?? DEFAULT_PARAGRAPH_GAP,
+		anchor: anchor ?? {
+			x: 0,
+			y: 0
+		},
 		lineHeight: resolveLineHeight(options.lineHeight, textOptions.size),
 		align: normalizeEnum(options.align, [
 			"left",
@@ -3403,8 +3404,7 @@ function normalizeParagraphOptions(fontInstance, options = {}) {
 			"break-all",
 			"keep-all"
 		], wrapDefaults.wordBreak),
-		overflow,
-		overflowY,
+		overflow: normalizeEnum(options.overflow, ["visible", "hidden"], "visible"),
 		textOverflow: normalizeNullableEnum(options.textOverflow, ["clip", "ellipsis"], null),
 		maxLines: normalizeMaxLines(options.maxLines),
 		ellipsis: normalizeEllipsis(options.ellipsis),
@@ -3593,7 +3593,7 @@ function applyOverflowClamping(lines, options, layoutBox, measureWidth) {
 	const contentWidth = layoutBox.contentWidth;
 	const result = lines.map((line) => ({ ...line }));
 	let lineLimit = options.maxLines;
-	if (shouldClampLinesToHeight(options) && layoutBox.clipContentHeight != null) {
+	if (options.overflow === "hidden" && layoutBox.clipContentHeight != null) {
 		const visibleLineCount = countVisibleLinesForHeight(result, options, layoutBox.clipContentHeight);
 		lineLimit = lineLimit == null ? visibleLineCount : Math.min(lineLimit, visibleLineCount);
 	}
@@ -3818,10 +3818,48 @@ function finalizeLayoutBox(layoutBox, options, textHeight) {
 			x: layoutBox.contentX,
 			y: layoutBox.contentY,
 			w: layoutBox.contentWidth,
-			h: shouldClipToContentHeight(options) ? contentHeight : textHeight
+			h: options.overflow === "hidden" ? contentHeight : textHeight
 		}
 	};
 }
+function applyParagraphAnchor(lines, textBBox, layoutBox, anchor) {
+	if (anchor == null || Math.abs(anchor.x) <= JUSTIFY_EPSILON && Math.abs(anchor.y) <= JUSTIFY_EPSILON) return {
+		lines,
+		textBBox,
+		layoutBox
+	};
+	const tx = -layoutBox.contentBox.w * anchor.x;
+	const ty = -layoutBox.contentBox.h * anchor.y;
+	return {
+		lines: translatePositionedLines(lines, tx, ty),
+		textBBox: translateRect(textBBox, tx, ty),
+		layoutBox: translateLayoutBox(layoutBox, tx, ty)
+	};
+}
+function translatePositionedLines(lines, tx, ty) {
+	return lines.map((line) => ({
+		...line,
+		x: line.x + tx,
+		y: line.y + ty,
+		baseline: line.baseline + ty,
+		bbox: translateRect(line.bbox, tx, ty),
+		fragments: line.fragments.map((fragment) => ({
+			...fragment,
+			x: fragment.x + tx
+		}))
+	}));
+}
+function translateLayoutBox(layoutBox, tx, ty) {
+	return {
+		...layoutBox,
+		contentX: layoutBox.contentX + tx,
+		contentY: layoutBox.contentY + ty,
+		contentBox: translateRect(layoutBox.contentBox, tx, ty),
+		paddingBox: translateRect(layoutBox.paddingBox, tx, ty),
+		marginBox: translateRect(layoutBox.marginBox, tx, ty),
+		clipBox: translateRect(layoutBox.clipBox, tx, ty)
+	};
+}
 function resolveContainerDimension(explicit, fallback) {
 	if (Number.isFinite(explicit) && explicit > 0) return explicit;
 	if (Number.isFinite(fallback) && fallback > 0) return fallback;
@@ -3834,19 +3872,6 @@ function normalizeNullableEnum(value, supported, fallback) {
 	if (value == null) return fallback;
 	return typeof value === "string" && supported.includes(value) ? value : fallback;
 }
-function resolveOverflowY(value, overflow) {
-	return normalizeEnum(value, [
-		"visible",
-		"hidden",
-		"scroll"
-	], overflow === "hidden" ? "hidden" : "visible");
-}
-function shouldClampLinesToHeight(options) {
-	return options.overflowY === "hidden";
-}
-function shouldClipToContentHeight(options) {
-	return options.overflow === "hidden" || options.overflowY === "hidden" || options.overflowY === "scroll";
-}
 function normalizeEllipsis(value) {
 	if (value === false) return false;
 	if (typeof value === "string") return value;
@@ -3863,6 +3888,40 @@ function normalizeDimension(value) {
 function normalizeGap(value) {
 	return Number.isFinite(value) && value >= 0 ? Number(value) : null;
 }
+function normalizeAnchor(value) {
+	if (value == null) return null;
+	if (Number.isFinite(value)) {
+		const next = Number(value);
+		return {
+			x: next,
+			y: next
+		};
+	}
+	if (Array.isArray(value)) {
+		if (value.length === 1 && Number.isFinite(value[0])) {
+			const next = Number(value[0]);
+			return {
+				x: next,
+				y: next
+			};
+		}
+		if (value.length >= 2 && Number.isFinite(value[0]) && Number.isFinite(value[1])) return {
+			x: Number(value[0]),
+			y: Number(value[1])
+		};
+		return null;
+	}
+	if (typeof value === "object") {
+		const hasX = Number.isFinite(value.x);
+		const hasY = Number.isFinite(value.y);
+		if (!hasX && !hasY) return null;
+		return {
+			x: hasX ? Number(value.x) : 0,
+			y: hasY ? Number(value.y) : 0
+		};
+	}
+	return null;
+}
 function normalizeSpacing(value) {
 	if (value == null) return zeroSpacing();
 	if (Number.isFinite(value)) {
@@ -4283,7 +4342,6 @@ var paParagraph = class paParagraph {
 		if (!ctx || typeof ctx.fillText !== "function") throw new TypeError("drawText() expects a CanvasRenderingContext2D.");
 		const fill = options.fill !== false;
 		const stroke = options.stroke === true;
-		const scrollTop = clampScrollTop(options.scrollTop, this.metrics.maxScrollTop);
 		if (!fill && !stroke) return;
 		this._syncLayoutWithContext(ctx);
 		ctx.save();
@@ -4292,13 +4350,12 @@ var paParagraph = class paParagraph {
 		ctx.textBaseline = "alphabetic";
 		if (options.fillStyle != null) ctx.fillStyle = options.fillStyle;
 		if (options.strokeStyle != null) ctx.strokeStyle = options.strokeStyle;
-		if (shouldClipParagraph(this.options) && this._state.layoutBox?.clipBox) {
+		if (this.options.overflow === "hidden" && this._state.layoutBox?.clipBox) {
 			const clipBox = this._state.layoutBox.clipBox;
 			ctx.beginPath();
 			ctx.rect(clipBox.x, clipBox.y, clipBox.w, clipBox.h);
 			ctx.clip();
 		}
-		if (scrollTop > 0) ctx.translate(0, -scrollTop);
 		this._state.lines.forEach((line) => {
 			line.fragments.forEach((fragment) => {
 				if (fill) ctx.fillText(fragment.text, fragment.x, line.baseline);
@@ -4349,8 +4406,6 @@ var paParagraph = class paParagraph {
 		this.metrics = {
 			...state.metrics,
 			bbox: { ...state.metrics.bbox },
-			viewportHeight: state.metrics.viewportHeight,
-			maxScrollTop: state.metrics.maxScrollTop,
 			contentBox: state.metrics.contentBox ? { ...state.metrics.contentBox } : void 0,
 			paddingBox: state.metrics.paddingBox ? { ...state.metrics.paddingBox } : void 0,
 			marginBox: state.metrics.marginBox ? { ...state.metrics.marginBox } : void 0,
@@ -4445,13 +4500,6 @@ function normalizeParagraphPointOptions(options = {}) {
 		layout: options.layout ?? "current"
 	};
 }
-function shouldClipParagraph(options) {
-	return options.overflow === "hidden" || options.overflowY === "hidden" || options.overflowY === "scroll";
-}
-function clampScrollTop(value, maxScrollTop) {
-	if (!Number.isFinite(value) || value <= 0) return 0;
-	return Math.min(Number(value), maxScrollTop ?? 0);
-}
 //#endregion
 //#region src/paFont/paFont.js
 var browserFontRegistrationId = 0;