pa_font 0.3.0 → 0.3.1

package/USAGE.md

@@ -119,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`
@@ -137,6 +138,7 @@ console.log(metrics.width, metrics.bbox);
 - `gap`: 문단 사이 간격. `lineHeight` 배수이며 기본값은 `0.5`
 - `whiteSpace: "normal"`이면 문단 안 단일 줄바꿈은 공백으로 정리
 - `whiteSpace: "pre-wrap"`이면 문단 안 단일 줄바꿈 유지
+- `overflowY: "scroll"`을 쓰려면 `height`가 필요
 
 ## paParagraph API
 
@@ -182,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?)`
 

package/dist/paFont.cjs

@@ -3332,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 },
@@ -3358,9 +3360,12 @@ 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);
 	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,
@@ -3398,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),
@@ -3587,7 +3593,7 @@ 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) {
+	if (shouldClampLinesToHeight(options) && layoutBox.clipContentHeight != null) {
 		const visibleLineCount = countVisibleLinesForHeight(result, options, layoutBox.clipContentHeight);
 		lineLimit = lineLimit == null ? visibleLineCount : Math.min(lineLimit, visibleLineCount);
 	}
@@ -3812,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
 		}
 	};
 }
@@ -3828,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;
@@ -4264,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();
@@ -4272,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);
@@ -4328,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,
@@ -4422,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;