pa_font 0.2.8 → 0.3.1

package/USAGE.md

@@ -42,15 +42,19 @@ const points = shape.toPoints({ step: 8 });
 ### 2. 문단을 canvas에 그리고, 필요하면 geometry로 바꾸기
 
 ```js
-const paragraph = font.paragraph("캔버스에서 자동 줄바꿈되는 문단입니다.", {
-  x: 40,
-  y: 80,
-  size: 32,
-  lineHeight: 1.4,
-  align: "left",
-  wrap: "word",
-  padding: { x: 24, y: 20 },
-});
+const paragraph = font.paragraph(
+  "첫 번째 문단입니다. 자동 줄바꿈됩니다.\n\n두 번째 문단입니다.",
+  {
+    x: 40,
+    y: 80,
+    size: 32,
+    lineHeight: 1.4,
+    gap: 0.75,
+    align: "left",
+    wrap: "word",
+    padding: { x: 24, y: 20 },
+  }
+);
 
 paragraph.drawText(ctx, {
   fillStyle: "#111",
@@ -107,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`, `align`
+- `x`, `y`, `size`, `lineHeight`, `gap`, `align`
 
 세부 제어 옵션:
 
@@ -115,6 +119,7 @@ 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`
@@ -128,6 +133,13 @@ console.log(metrics.width, metrics.bbox);
 
 `wordBreak` / `overflowWrap`를 직접 주면 `wrap`보다 우선합니다.
 
+빈 줄 하나 이상은 새 문단으로 처리됩니다.
+
+- `gap`: 문단 사이 간격. `lineHeight` 배수이며 기본값은 `0.5`
+- `whiteSpace: "normal"`이면 문단 안 단일 줄바꿈은 공백으로 정리
+- `whiteSpace: "pre-wrap"`이면 문단 안 단일 줄바꿈 유지
+- `overflowY: "scroll"`을 쓰려면 `height`가 필요
+
 ## paParagraph API
 
 `font.paragraph()`는 `paParagraph`를 반환합니다.
@@ -172,6 +184,28 @@ 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?)`
 
@@ -281,6 +315,7 @@ const paragraph = font.paragraph(text, {
   y: 0,
   size: 20,
   lineHeight: 1.6,
+  gap: 0.5,
   padding: { x: 32, y: 24 },
   margin: "20 0 0 20",
   wrap: "char",

package/dist/paFont.cjs

@@ -3299,6 +3299,7 @@ function layoutWithLines(prepared, maxWidth, lineHeight) {
 //#endregion
 //#region src/paFont/paragraphLayout.js
 var DEFAULT_LINE_HEIGHT_RATIO = 1.2;
+var DEFAULT_PARAGRAPH_GAP = .5;
 var HUGE_LAYOUT_WIDTH = 1e9;
 var JUSTIFY_EPSILON = 1e-6;
 var QUOTE_RE = /"/g;
@@ -3312,13 +3313,14 @@ function layoutParagraph(fontInstance, text, options = {}, state = {}) {
 	const textValue = String(text ?? "");
 	const layoutBox = resolveLayoutBox(normalized, state);
 	const retainedPreparedState = resolveRetainedPreparedState(state, normalized);
-	const pretextState = shouldAttemptPretextLayout(normalized) ? layoutWithPretext(textValue, normalized, retainedPreparedState, layoutBox) : null;
-	const layoutState = pretextState != null && canUsePretextLayout(pretextState, normalized) ? pretextState : layoutWithNative(fontInstance, textValue, normalized, layoutBox);
+	const paragraphs = splitParagraphText(textValue, normalized.whiteSpace);
+	const pretextState = shouldAttemptPretextLayout(normalized) ? layoutParagraphsWithPretext(paragraphs, normalized, retainedPreparedState, layoutBox) : null;
+	const layoutState = pretextState != null && canUsePretextLayout(pretextState, normalized) ? pretextState : layoutParagraphsWithNative(fontInstance, paragraphs, normalized, layoutBox);
 	const measureWidth = createLazyTextMeasurer(fontInstance, normalized);
 	const lines = positionLines(fontInstance, applyOverflowClamping(layoutState.lines, normalized, layoutBox, measureWidth), normalized, layoutBox, measureWidth);
 	const textBBox = combineRects(lines.map((line) => line.bbox)) ?? emptyRect();
 	const textWidth = lines.reduce((max, line) => Math.max(max, line.width), 0);
-	const textHeight = lines.length * normalized.lineHeight;
+	const textHeight = resolvePositionedTextHeight(lines, layoutBox.contentY);
 	const finalLayoutBox = finalizeLayoutBox(layoutBox, normalized, textHeight);
 	const cachedPrepared = pretextState?.prepared ?? retainedPreparedState.prepared ?? null;
 	const cachedPreparedWhiteSpace = pretextState?.preparedWhiteSpace ?? retainedPreparedState.preparedWhiteSpace ?? null;
@@ -3330,6 +3332,8 @@ function layoutParagraph(fontInstance, text, options = {}, state = {}) {
 			y: finalLayoutBox.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 },
@@ -3355,8 +3359,13 @@ function normalizeParagraphOptions(fontInstance, options = {}) {
 	], null));
 	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);
 	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\".");
 	const font = resolveCanvasFont(fontInstance, textOptions.size, options);
 	return {
 		...textOptions,
@@ -3371,6 +3380,7 @@ function normalizeParagraphOptions(fontInstance, options = {}) {
 		], wrapDefaults.overflowWrap)),
 		width,
 		height,
+		gap: gap ?? DEFAULT_PARAGRAPH_GAP,
 		lineHeight: resolveLineHeight(options.lineHeight, textOptions.size),
 		align: normalizeEnum(options.align, [
 			"left",
@@ -3393,7 +3403,8 @@ function normalizeParagraphOptions(fontInstance, options = {}) {
 			"break-all",
 			"keep-all"
 		], wrapDefaults.wordBreak),
-		overflow: normalizeEnum(options.overflow, ["visible", "hidden"], "visible"),
+		overflow,
+		overflowY,
 		textOverflow: normalizeNullableEnum(options.textOverflow, ["clip", "ellipsis"], null),
 		maxLines: normalizeMaxLines(options.maxLines),
 		ellipsis: normalizeEllipsis(options.ellipsis),
@@ -3421,6 +3432,44 @@ function resolveCanvasFont(fontInstance, size, options = {}) {
 function canReusePreparedParagraphState(previousState, previousOptions, nextOptions) {
 	return previousState?.prepared != null && previousState.preparedWhiteSpace === resolvePretextWhiteSpace(nextOptions.whiteSpace) && previousOptions?.font === nextOptions.font;
 }
+function layoutParagraphsWithPretext(paragraphs, options, state, layoutBox) {
+	const retainedPrepared = Array.isArray(state.prepared) ? state.prepared : state.prepared != null ? [state.prepared] : [];
+	const paragraphStates = paragraphs.map((paragraph, paragraphIndex) => layoutWithPretext(paragraph, options, {
+		prepared: retainedPrepared[paragraphIndex] ?? null,
+		preparedWhiteSpace: state.preparedWhiteSpace,
+		font: options.font
+	}, layoutBox));
+	return {
+		lines: annotateParagraphLines(paragraphStates),
+		prepared: paragraphStates.map((paragraphState) => paragraphState.prepared ?? null),
+		preparedWhiteSpace: paragraphStates[0]?.preparedWhiteSpace ?? resolvePretextWhiteSpace(options.whiteSpace),
+		layoutEngine: "pretext",
+		usedOverflowWrapFallbackBreaks: paragraphStates.some((paragraphState) => paragraphState.usedOverflowWrapFallbackBreaks)
+	};
+}
+function layoutParagraphsWithNative(fontInstance, paragraphs, options, layoutBox) {
+	return {
+		lines: annotateParagraphLines(paragraphs.map((paragraph) => layoutWithNative(fontInstance, paragraph, options, layoutBox))),
+		prepared: null,
+		preparedWhiteSpace: null,
+		layoutEngine: "native"
+	};
+}
+function annotateParagraphLines(paragraphStates) {
+	const lines = [];
+	paragraphStates.forEach((paragraphState, paragraphIndex) => {
+		paragraphState.lines.forEach((line, lineIndex) => {
+			lines.push({
+				...line,
+				start: null,
+				end: null,
+				paragraphIndex,
+				paragraphEnd: lineIndex === paragraphState.lines.length - 1
+			});
+		});
+	});
+	return lines;
+}
 function layoutWithPretext(text, options, state, layoutBox) {
 	const preparedWhiteSpace = resolvePretextWhiteSpace(options.whiteSpace);
 	const prepared = state.prepared != null && state.preparedWhiteSpace === preparedWhiteSpace && state.font === options.font ? state.prepared : prepareWithSegments(text, options.font, { whiteSpace: preparedWhiteSpace });
@@ -3544,8 +3593,8 @@ function applyOverflowClamping(lines, options, layoutBox, measureWidth) {
 	const contentWidth = layoutBox.contentWidth;
 	const result = lines.map((line) => ({ ...line }));
 	let lineLimit = options.maxLines;
-	if (options.overflow === "hidden" && layoutBox.clipContentHeight != null) {
-		const visibleLineCount = Math.max(0, Math.floor((layoutBox.clipContentHeight + JUSTIFY_EPSILON) / options.lineHeight));
+	if (shouldClampLinesToHeight(options) && layoutBox.clipContentHeight != null) {
+		const visibleLineCount = countVisibleLinesForHeight(result, options, layoutBox.clipContentHeight);
 		lineLimit = lineLimit == null ? visibleLineCount : Math.min(lineLimit, visibleLineCount);
 	}
 	let clippedByCount = false;
@@ -3557,14 +3606,30 @@ function applyOverflowClamping(lines, options, layoutBox, measureWidth) {
 		}
 	}
 	if (result.length === 0) return result;
-	if (options.overflow === "hidden" && options.whiteSpace === "nowrap" && result[0].width > contentWidth + JUSTIFY_EPSILON) result[0] = truncateLineToWidth(result[0], contentWidth, measureWidth, options.textOverflow === "ellipsis" ? options.ellipsis : false);
-	else if (clippedByCount && shouldEllipsizeClampedLines(options)) {
+	if (options.overflow === "hidden" && options.whiteSpace === "nowrap") {
+		for (let index = 0; index < result.length; index += 1) if (result[index].width > contentWidth + JUSTIFY_EPSILON) result[index] = truncateLineToWidth(result[index], contentWidth, measureWidth, options.textOverflow === "ellipsis" ? options.ellipsis : false);
+	}
+	if (clippedByCount && shouldEllipsizeClampedLines(options)) {
 		const lastIndex = result.length - 1;
 		result[lastIndex] = truncateLineToWidth(result[lastIndex], contentWidth, measureWidth, options.ellipsis);
 		result[lastIndex].hardBreak = false;
+		result[lastIndex].paragraphEnd = true;
 	}
 	return result;
 }
+function countVisibleLinesForHeight(lines, options, maxHeight) {
+	let visibleLineCount = 0;
+	let consumedHeight = 0;
+	const lineBoxHeight = options.lineHeight;
+	const paragraphGap = lineBoxHeight * options.gap;
+	for (let index = 0; index < lines.length; index += 1) {
+		if (consumedHeight + lineBoxHeight > maxHeight + JUSTIFY_EPSILON) break;
+		consumedHeight += lineBoxHeight;
+		visibleLineCount += 1;
+		if (lines[index].paragraphEnd && index < lines.length - 1) consumedHeight += paragraphGap;
+	}
+	return visibleLineCount;
+}
 function truncateLineToWidth(line, maxWidth, measureWidth, suffix) {
 	const suffixText = suffix === false ? "" : suffix;
 	if ((suffixText.length > 0 ? measureWidth(suffixText) : 0) > maxWidth + JUSTIFY_EPSILON) return {
@@ -3589,13 +3654,17 @@ function shouldEllipsizeClampedLines(options) {
 function positionLines(fontInstance, lines, options, layoutBox, measureWidth) {
 	const ascent = getFontAscender(fontInstance, options.size);
 	const lineBoxHeight = options.lineHeight;
+	const paragraphGap = lineBoxHeight * options.gap;
 	let cursor = 0;
+	let cursorY = layoutBox.contentY;
 	return lines.map((line, index) => {
 		const justified = shouldJustifyLine(line, index, lines.length, options);
 		const offsetX = justified ? 0 : resolveAlignOffset(options.align, line.width, layoutBox.contentWidth);
 		const x = layoutBox.contentX + offsetX;
-		const y = layoutBox.contentY + index * lineBoxHeight;
+		const y = cursorY;
 		const baseline = y + ascent;
+		const start = line.start ?? cursor;
+		const end = line.end ?? start + line.text.length;
 		const fragments = justified ? buildJustifiedFragments(line, layoutBox.contentX, layoutBox.contentWidth, measureWidth) : [{
 			text: line.text,
 			x,
@@ -3612,8 +3681,8 @@ function positionLines(fontInstance, lines, options, layoutBox, measureWidth) {
 		const positioned = {
 			index,
 			text: line.text,
-			start: line.start ?? cursor,
-			end: line.end ?? cursor + line.text.length,
+			start,
+			end,
 			x,
 			y,
 			width,
@@ -3623,10 +3692,21 @@ function positionLines(fontInstance, lines, options, layoutBox, measureWidth) {
 			hardBreak: line.hardBreak,
 			fragments
 		};
-		cursor = positioned.end + (line.hardBreak ? 1 : 0);
+		cursor = end;
+		if (line.hardBreak) cursor += 1;
+		if (line.paragraphEnd && index < lines.length - 1) {
+			cursor += 2;
+			cursorY += paragraphGap;
+		}
+		cursorY += lineBoxHeight;
 		return positioned;
 	});
 }
+function resolvePositionedTextHeight(lines, contentY) {
+	if (lines.length === 0) return 0;
+	const lastLine = lines[lines.length - 1];
+	return lastLine.y + lastLine.height - contentY;
+}
 function buildJustifiedFragments(line, contentX, contentWidth, measureWidth) {
 	const tokens = splitPreservingWhitespace(line.text);
 	const expandable = tokens.reduce((count, token, index) => {
@@ -3657,7 +3737,7 @@ function buildJustifiedFragments(line, contentX, contentWidth, measureWidth) {
 	return fragments;
 }
 function shouldJustifyLine(line, index, lineCount, options) {
-	return options.align === "justify" && index < lineCount - 1 && !line.hardBreak && /\S\s+\S/u.test(line.text);
+	return options.align === "justify" && index < lineCount - 1 && !line.hardBreak && !line.paragraphEnd && /\S\s+\S/u.test(line.text);
 }
 function resolveAlignOffset(align, lineWidth, maxWidth) {
 	if (align === "center") return (maxWidth - lineWidth) * .5;
@@ -3738,7 +3818,7 @@ function finalizeLayoutBox(layoutBox, options, textHeight) {
 			x: layoutBox.contentX,
 			y: layoutBox.contentY,
 			w: layoutBox.contentWidth,
-			h: options.overflow === "hidden" ? contentHeight : textHeight
+			h: shouldClipToContentHeight(options) ? contentHeight : textHeight
 		}
 	};
 }
@@ -3754,6 +3834,19 @@ 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;
@@ -3767,6 +3860,9 @@ function normalizeMaxLines(value) {
 function normalizeDimension(value) {
 	return Number.isFinite(value) && value > 0 ? value : null;
 }
+function normalizeGap(value) {
+	return Number.isFinite(value) && value >= 0 ? Number(value) : null;
+}
 function normalizeSpacing(value) {
 	if (value == null) return zeroSpacing();
 	if (Number.isFinite(value)) {
@@ -3881,6 +3977,27 @@ function resolveRetainedPreparedState(state, options) {
 function isHardBreak(prepared, line) {
 	return prepared.kinds?.[line.end.segmentIndex] === "hard-break";
 }
+function splitParagraphText(text, whiteSpace) {
+	const normalized = String(text ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	const paragraphs = [];
+	const lines = normalized.split("\n");
+	let currentLines = [];
+	const pushCurrentParagraph = () => {
+		if (currentLines.length === 0) return;
+		const paragraph = whiteSpace === "pre-wrap" ? currentLines.join("\n") : currentLines.join("\n").replace(/\s+/gu, " ").trim();
+		currentLines = [];
+		if (paragraph.length > 0) paragraphs.push(paragraph);
+	};
+	lines.forEach((line) => {
+		if (/^[\t ]*$/u.test(line)) {
+			pushCurrentParagraph();
+			return;
+		}
+		currentLines.push(line);
+	});
+	pushCurrentParagraph();
+	return paragraphs;
+}
 function normalizeNativeText(text, whiteSpace) {
 	if (whiteSpace === "pre-wrap") return String(text ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 	return String(text ?? "").replace(/\s+/gu, " ").trim();
@@ -4166,6 +4283,7 @@ 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();
@@ -4174,12 +4292,13 @@ var paParagraph = class paParagraph {
 		ctx.textBaseline = "alphabetic";
 		if (options.fillStyle != null) ctx.fillStyle = options.fillStyle;
 		if (options.strokeStyle != null) ctx.strokeStyle = options.strokeStyle;
-		if (this.options.overflow === "hidden" && this._state.layoutBox?.clipBox) {
+		if (shouldClipParagraph(this.options) && 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);
@@ -4230,6 +4349,8 @@ 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,
@@ -4324,6 +4445,13 @@ 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;