pa_font 0.3.5 → 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
@@ -84,11 +104,18 @@ const regions = paragraph.toRegions({ step: 6, openWidth: 1 });
 
 - `x`, `y`: 기본값은 baseline 시작 위치
 - `anchor`: 주면 `x`, `y`를 실제 글자 bbox 기준점으로 사용
-- `size`: 글자 크기
+- `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`로 만듭니다.
@@ -100,7 +127,15 @@ const regions = paragraph.toRegions({ step: 6, openWidth: 1 });
 
 ```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?)`
@@ -115,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`

package/dist/paFont.cjs

@@ -276,6 +276,8 @@ 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);
@@ -325,12 +327,14 @@ function measureText(font, value, opts) {
 	const renderOptions = toRenderOptions(opts);
 	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: translateRect(bbox, tx, ty)
 	};
@@ -548,8 +552,30 @@ 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),
@@ -617,6 +643,28 @@ function resolveMeasuredBBox(box, fallbackX, fallbackY) {
 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;
@@ -4597,14 +4645,17 @@ var paFont = class paFont {
 		return new paFont(await (0, opentype_js.load)(target, void 0, loadOptions));
 	}
 	text(value, options = {}) {
-		const opts = normalizeTextOptions(options);
-		assertValidAnchorOption("font.text()", options, opts.anchor);
-		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);
-		assertValidAnchorOption("font.glyph()", options, opts.anchor);
 		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,
@@ -4625,9 +4676,11 @@ var paFont = class paFont {
 		return createTextShape(anchorSingleGlyphLayout(this.font, text, layout, opts), opts, this);
 	}
 	metrics(value, options = {}) {
-		const opts = normalizeTextOptions(options);
-		assertValidAnchorOption("font.metrics()", options, opts.anchor);
-		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);