pa_font 0.3.4 → 0.3.7

package/USAGE.md

@@ -39,6 +39,26 @@ const regions = shape.toRegions();
 const points = shape.toPoints({ step: 8 });
 ```
 
+문자열 길이에 따라 비슷한 최종 폭으로 맞추고 싶다면 `size`에 객체를 넣을 수 있습니다.
+
+```js
+const short = font.text("펑", {
+  x: canvasWidth * 0.5,
+  y: canvasHeight * 0.5,
+  anchor: 0.5,
+  size: { width: canvasWidth * 0.7, basis: "bbox" },
+});
+
+const long = font.text("왕밤빵", {
+  x: canvasWidth * 0.5,
+  y: canvasHeight * 0.5,
+  anchor: 0.5,
+  size: { width: canvasWidth * 0.7, basis: "bbox", min: 48, max: 320 },
+});
+
+console.log(short.metrics.size, long.metrics.size);
+```
+
 ### 2. 문단을 canvas에 그리고, 필요하면 geometry로 바꾸기
 
 ```js
@@ -82,12 +102,20 @@ const regions = paragraph.toRegions({ step: 6, openWidth: 1 });
 
 주요 옵션:
 
-- `x`, `y`: baseline 시작 위치
-- `size`: 글자 크기
+- `x`, `y`: 기본값은 baseline 시작 위치
+- `anchor`: 주면 `x`, `y`를 실제 글자 bbox 기준점으로 사용
+- `size`: 글자 크기. `number` 또는 `{ width, basis?, min?, max? }`
 - `flatten`: 곡선 평탄화 허용 오차
 - `kerning`, `letterSpacing`, `tracking`
 - `script`, `language`, `features`
 
+`size` 객체를 주면 내부에서 최종 숫자 size를 계산한 뒤 기존 텍스트 생성 로직으로 이어집니다.
+
+- `width`: 목표 폭
+- `basis`: `"bbox"` 또는 `"advance"`, 기본값은 `"bbox"`
+- `min`: 최소 size, 기본값은 `0`
+- `max`: 최대 size, 기본값은 `Infinity`
+
 ### `font.glyph(value, options?)`
 
 한 글자만 `PAShape`로 만듭니다.
@@ -95,10 +123,19 @@ const regions = paragraph.toRegions({ step: 6, openWidth: 1 });
 ### `font.metrics(value, options?)`
 
 텍스트 폭과 bounding box만 빠르게 계산합니다.
+`anchor`를 주면 반환되는 `bbox`도 같은 기준점으로 이동된 값입니다.
 
 ```js
 const metrics = font.metrics("안녕", { size: 120 });
-console.log(metrics.width, metrics.bbox);
+console.log(metrics.size, metrics.width, metrics.bbox);
+```
+
+```js
+const metrics = font.metrics("왕밤빵", {
+  size: { width: 600, basis: "advance", min: 80, max: 240 },
+});
+
+console.log(metrics.size, metrics.width, metrics.bbox);
 ```
 
 ### `font.paragraph(value, options?)`
@@ -113,6 +150,8 @@ console.log(metrics.width, metrics.bbox);
 - `height`: `overflow: "hidden"`과 같이 쓰면 clip/clamp
 - `x`, `y`, `size`, `lineHeight`, `gap`, `anchor`, `align`
 
+`font.paragraph()`의 `size`는 현재도 숫자만 받습니다.
+
 세부 제어 옵션:
 
 - `whiteSpace`: `normal | pre-wrap | nowrap`
@@ -135,7 +174,7 @@ console.log(metrics.width, metrics.bbox);
 빈 줄 하나 이상은 새 문단으로 처리됩니다.
 
 - `gap`: 문단 사이 간격. `lineHeight` 배수이며 기본값은 `0.5`
-- `anchor`: 기준점을 옮깁니다. `anchor: 0.5`면 CSS의 `translate(-50%, -50%)`처럼 동작
+- `anchor`: 실제 렌더된 글자 bbox 기준으로 기준점을 옮깁니다. `anchor: 0.5`면 CSS의 `translate(-50%, -50%)`처럼 동작
 - `whiteSpace: "normal"`이면 문단 안 단일 줄바꿈은 공백으로 정리
 - `whiteSpace: "pre-wrap"`이면 문단 안 단일 줄바꿈 유지
 

package/dist/paFont.cjs

@@ -276,10 +276,12 @@ function mod(value, divisor) {
 }
 //#endregion
 //#region src/paFont/core.js
+var DEFAULT_TEXT_SIZE = 72;
+var DEFAULT_TEXT_SIZE_BASIS = "bbox";
 function layoutGlyphs(font, value, opts) {
 	const glyphs = [];
 	const renderOptions = toRenderOptions(opts);
-	return {
+	return applyAnchorToGlyphLayout(font, value, {
 		text: value,
 		glyphs,
 		metrics: {
@@ -296,19 +298,45 @@ function layoutGlyphs(font, value, opts) {
 			y: opts.y,
 			size: opts.size
 		}
+	}, opts);
+}
+function applyAnchorToGlyphLayout(font, value, layout, opts) {
+	if (opts.anchor == null || layout.glyphs.length === 0) return layout;
+	const { bbox } = measureText(font, value, {
+		...opts,
+		anchor: null
+	});
+	const tx = opts.x - (bbox.x + bbox.w * opts.anchor.x);
+	const ty = opts.y - (bbox.y + bbox.h * opts.anchor.y);
+	if (tx === 0 && ty === 0) return layout;
+	return {
+		text: value,
+		glyphs: layout.glyphs.map((glyph) => ({
+			...glyph,
+			x: glyph.x + tx,
+			y: glyph.y + ty
+		})),
+		metrics: {
+			...layout.metrics,
+			x: layout.metrics.x + tx,
+			y: layout.metrics.y + ty
+		}
 	};
 }
 function measureText(font, value, opts) {
 	const renderOptions = toRenderOptions(opts);
-	const box = font.getPath(value, opts.x, opts.y, opts.size, renderOptions).getBoundingBox();
+	const bbox = resolveMeasuredBBox(font.getPath(value, opts.x, opts.y, opts.size, renderOptions).getBoundingBox(), opts.x, opts.y);
+	if (opts.anchor == null) return {
+		size: opts.size,
+		width: measureAdvanceWidth(font, value, opts),
+		bbox
+	};
+	const tx = opts.x - (bbox.x + bbox.w * opts.anchor.x);
+	const ty = opts.y - (bbox.y + bbox.h * opts.anchor.y);
 	return {
+		size: opts.size,
 		width: measureAdvanceWidth(font, value, opts),
-		bbox: {
-			x: box.x1,
-			y: box.y1,
-			w: box.x2 - box.x1,
-			h: box.y2 - box.y1
-		}
+		bbox: translateRect(bbox, tx, ty)
 	};
 }
 function measureAdvanceWidth(font, value, opts) {
@@ -524,8 +552,31 @@ function translateGlyphGeometry(geometry, tx, ty, glyphPosition) {
 		bbox: translateRect(geometry.bbox, tx, ty)
 	};
 }
+function resolveTextOptions(font, value, options = {}, config = {}) {
+	const sourceOptions = options ?? {};
+	return normalizeTextOptions({
+		...sourceOptions,
+		size: resolveTextSize(font, value, sourceOptions, config)
+	});
+}
+function resolveTextSize(font, value, options = {}, config = {}) {
+	const sourceOptions = options ?? {};
+	const sizeOption = sourceOptions.size;
+	if (!isTextSizeConstraint(sizeOption)) return normalizePositive(sizeOption, DEFAULT_TEXT_SIZE);
+	const fit = normalizeTextSizeConstraint(sizeOption, config.methodName);
+	const referenceSize = DEFAULT_TEXT_SIZE;
+	const measurement = measureText(font, String(value ?? ""), normalizeTextOptions({
+		...sourceOptions,
+		anchor: null,
+		size: referenceSize
+	}));
+	const measuredWidth = fit.basis === "advance" ? measurement.width : measurement.bbox.w;
+	if (!Number.isFinite(measuredWidth) || measuredWidth <= 0) return clampTextSize(referenceSize, fit.min, fit.max);
+	return clampTextSize(referenceSize * fit.width / measuredWidth, fit.min, fit.max);
+}
 function normalizeTextOptions(options = {}) {
-	const size = normalizePositive(options.size, 72);
+	const size = normalizePositive(options.size, DEFAULT_TEXT_SIZE);
+	const anchor = normalizeAnchor(options.anchor);
 	return {
 		x: normalizeNumber(options.x, 0),
 		y: normalizeNumber(options.y, 0),
@@ -535,14 +586,85 @@ function normalizeTextOptions(options = {}) {
 		kerning: options.kerning !== false,
 		letterSpacing: options.letterSpacing == null ? void 0 : normalizeNumber(options.letterSpacing, 0),
 		tracking: options.tracking == null ? void 0 : normalizeNumber(options.tracking, 0),
+		anchor,
 		script: options.script,
 		language: options.language,
 		features: options.features
 	};
 }
+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 resolveMeasuredBBox(box, fallbackX, fallbackY) {
+	if (Number.isFinite(box?.x1) && Number.isFinite(box?.y1) && Number.isFinite(box?.x2) && Number.isFinite(box?.y2)) return {
+		x: box.x1,
+		y: box.y1,
+		w: box.x2 - box.x1,
+		h: box.y2 - box.y1
+	};
+	return {
+		x: normalizeNumber(fallbackX, 0),
+		y: normalizeNumber(fallbackY, 0),
+		w: 0,
+		h: 0
+	};
+}
 function defaultEdgeEpsilon(size) {
 	return Math.min(1, Math.max(.01, size * .0025));
 }
+function isTextSizeConstraint(value) {
+	return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeTextSizeConstraint(value, methodName) {
+	const width = normalizeNonNegativeNumber(value.width, NaN);
+	if (!Number.isFinite(width)) throw new TypeError(`${methodName ?? "Text"} option "size.width" must be a non-negative number.`);
+	const min = normalizeNonNegativeNumber(value.min, 0);
+	const maxValue = value.max === Infinity ? Infinity : normalizeNonNegativeNumber(value.max, Number.POSITIVE_INFINITY);
+	const max = Number.isFinite(maxValue) ? Math.max(min, maxValue) : Infinity;
+	return {
+		width,
+		basis: value.basis === "advance" ? "advance" : DEFAULT_TEXT_SIZE_BASIS,
+		min,
+		max
+	};
+}
+function normalizeNonNegativeNumber(value, fallback) {
+	return Number.isFinite(value) && value >= 0 ? Number(value) : fallback;
+}
+function clampTextSize(value, min, max) {
+	return Math.min(max, Math.max(min, normalizeNonNegativeNumber(value, min)));
+}
 function toRenderOptions(opts) {
 	const renderOptions = { kerning: opts.kerning };
 	if (opts.letterSpacing != null) renderOptions.letterSpacing = opts.letterSpacing;
@@ -3318,7 +3440,7 @@ function layoutParagraph(fontInstance, text, options = {}, state = {}) {
 	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 textBBox = normalized.anchor == null ? combineRects(lines.map((line) => line.bbox)) ?? emptyRect() : measurePositionedTextBBox(fontInstance, lines, normalized);
 	const textWidth = lines.reduce((max, line) => Math.max(max, line.width), 0);
 	const textHeight = resolvePositionedTextHeight(lines, layoutBox.contentY);
 	const anchoredLayout = applyParagraphAnchor(lines, textBBox, finalizeLayoutBox(layoutBox, normalized, textHeight), normalized.anchor);
@@ -3857,6 +3979,35 @@ function translateLayoutBox(layoutBox, tx, ty) {
 		clipBox: translateRect(layoutBox.clipBox, tx, ty)
 	};
 }
+function measurePositionedTextBBox(fontInstance, lines, options) {
+	const visibleBoxes = [];
+	const measureOptions = {
+		x: 0,
+		y: 0,
+		size: options.size,
+		flatten: options.flatten,
+		edgeEpsilon: options.edgeEpsilon,
+		kerning: options.kerning,
+		letterSpacing: options.letterSpacing,
+		tracking: options.tracking,
+		anchor: null,
+		script: options.script,
+		language: options.language,
+		features: options.features
+	};
+	lines.forEach((line) => {
+		line.fragments.forEach((fragment) => {
+			if (fragment.text.length === 0) return;
+			const { bbox } = measureText(fontInstance.font, fragment.text, {
+				...measureOptions,
+				x: fragment.x,
+				y: line.baseline
+			});
+			if (bbox.w > 0 || bbox.h > 0) visibleBoxes.push(bbox);
+		});
+	});
+	return combineRects(visibleBoxes) ?? combineRects(lines.map((line) => line.bbox)) ?? emptyRect();
+}
 function resolveContainerDimension(explicit, fallback) {
 	if (Number.isFinite(explicit) && explicit > 0) return explicit;
 	if (Number.isFinite(fallback) && fallback > 0) return fallback;
@@ -3885,40 +4036,6 @@ 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)) {
@@ -4528,14 +4645,20 @@ var paFont = class paFont {
 		return new paFont(await (0, opentype_js.load)(target, void 0, loadOptions));
 	}
 	text(value, options = {}) {
-		const opts = normalizeTextOptions(options);
-		return createTextShape(this._layoutText(String(value ?? ""), opts), opts, this);
+		const text = String(value ?? "");
+		const sourceOptions = options ?? {};
+		const opts = resolveTextOptions(this.font, text, sourceOptions, { methodName: "font.text()" });
+		assertValidAnchorOption("font.text()", sourceOptions, opts.anchor);
+		return createTextShape(this._layoutText(text, opts), opts, this);
 	}
 	glyph(value, options = {}) {
-		const opts = normalizeTextOptions(options);
-		const glyph = this.font.charToGlyph(String(value ?? ""));
-		return createTextShape({
-			text: String(value ?? ""),
+		const text = Array.from(String(value ?? ""))[0] ?? "";
+		const sourceOptions = options ?? {};
+		const opts = resolveTextOptions(this.font, text, sourceOptions, { methodName: "font.glyph()" });
+		assertValidAnchorOption("font.glyph()", sourceOptions, opts.anchor);
+		const glyph = this.font.charToGlyph(text);
+		const layout = {
+			text,
 			glyphs: [{
 				glyph,
 				x: opts.x,
@@ -4549,11 +4672,15 @@ var paFont = class paFont {
 				y: opts.y,
 				size: opts.size
 			}
-		}, opts, this);
+		};
+		return createTextShape(anchorSingleGlyphLayout(this.font, text, layout, opts), opts, this);
 	}
 	metrics(value, options = {}) {
-		const opts = normalizeTextOptions(options);
-		return measureText(this.font, String(value ?? ""), opts);
+		const text = String(value ?? "");
+		const sourceOptions = options ?? {};
+		const opts = resolveTextOptions(this.font, text, sourceOptions, { methodName: "font.metrics()" });
+		assertValidAnchorOption("font.metrics()", sourceOptions, opts.anchor);
+		return measureText(this.font, text, opts);
 	}
 	paragraph(value, options = {}) {
 		return createParagraph(this, String(value ?? ""), options);
@@ -4607,6 +4734,32 @@ function normalizeShapeVariantValue(value) {
 function toShapeVariantKey(value) {
 	return normalizeShapeVariantValue(value).toFixed(6);
 }
+function assertValidAnchorOption(methodName, sourceOptions, anchor) {
+	if (sourceOptions?.anchor != null && anchor == null) throw new TypeError(`${methodName} option "anchor" must be a number, [x, y], or { x, y }.`);
+}
+function anchorSingleGlyphLayout(font, text, layout, opts) {
+	if (opts.anchor == null || text.length === 0) return layout;
+	const { bbox } = measureText(font, text, {
+		...opts,
+		anchor: null
+	});
+	const tx = opts.x - (bbox.x + bbox.w * opts.anchor.x);
+	const ty = opts.y - (bbox.y + bbox.h * opts.anchor.y);
+	if (tx === 0 && ty === 0) return layout;
+	return {
+		...layout,
+		glyphs: layout.glyphs.map((glyph) => ({
+			...glyph,
+			x: glyph.x + tx,
+			y: glyph.y + ty
+		})),
+		metrics: {
+			...layout.metrics,
+			x: layout.metrics.x + tx,
+			y: layout.metrics.y + ty
+		}
+	};
+}
 async function fetchFontBytes(source) {
 	const response = await fetch(source);
 	if (!response.ok) throw new Error(`Failed to load font from ${source}: ${response.status} ${response.statusText}`);