pa_font 0.2.1 → 0.2.2

package/README.md

@@ -0,0 +1,39 @@
+# paFont
+
+`paFont`는 OpenType 폰트에서 텍스트 geometry를 만들고, 같은 폰트로 canvas 문단 레이아웃까지 처리하는 작은 라이브러리입니다.
+
+## 설치
+
+```sh
+npm install pa_font
+```
+
+## 빠른 예시
+
+```js
+import paFont from "pa_font";
+
+const font = await paFont.load("/assets/font.otf");
+
+const paragraph = font.paragraph("Canvas paragraph with fast wrapping.", {
+  x: 40,
+  y: 80,
+  size: 32,
+  width: 420,
+  wrap: "word",
+  padding: { x: 24, y: 20 },
+});
+
+paragraph.drawText(ctx, { fillStyle: "#111" });
+
+const shape = paragraph.toShape({ step: 6 });
+```
+
+## 문단 API 핵심
+
+- `wrap: "word" | "char" | "keep"`로 대부분의 줄바꿈 모드를 짧게 지정할 수 있습니다.
+- `padding` / `margin`은 `24`, `"24 32"`, `[24, 32]`, `{ x: 32, y: 24 }`, `{ top, right, bottom, left }`를 지원합니다.
+- 기본 문단 레이아웃은 `pretext` hot path를 우선 사용하고, 필요한 경우만 native 측정으로 fallback 합니다.
+- 실제 사용 엔진은 `paragraph.layoutEngine`에서 확인할 수 있습니다.
+
+자세한 사용법은 [USAGE.md](./USAGE.md)를 참고하세요.

package/USAGE.md

@@ -0,0 +1,294 @@
+# paFont Usage
+
+`paFont`는 OpenType 폰트를 읽어:
+
+- canvas 문단 텍스트로 그리거나
+- polygon / region / point geometry로 변환하는 라이브러리입니다.
+
+## 기본 흐름
+
+### 1. 폰트 로드
+
+```js
+import paFont from "./src/paFont.js";
+
+const font = await paFont.load("/assets/font.otf");
+```
+
+모듈 상대 경로를 쓰고 싶으면:
+
+```js
+const font = await paFont.load("./font.otf", {
+  base: import.meta.url,
+});
+```
+
+## 빠른 예시
+
+### 1. 텍스트를 geometry로 만들기
+
+```js
+const shape = font.text("안녕", {
+  x: 0,
+  y: 200,
+  size: 160,
+  flatten: 1,
+});
+
+const regions = shape.toRegions();
+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 },
+});
+
+paragraph.drawText(ctx, {
+  fillStyle: "#111",
+});
+
+const shape = paragraph.toShape();
+const regions = paragraph.toRegions({ step: 6, openWidth: 1 });
+```
+
+## Font API
+
+### `paFont.load(source, options?)`
+
+폰트를 로드합니다.
+
+- `source`: `string | URL | ArrayBuffer | ArrayBufferView`
+- `options.base`: 모듈 기준 상대 경로 해석용
+
+브라우저에서는 `load()`한 폰트가 canvas용으로도 자동 등록되며,
+`font.paragraph(...).drawText()`는 기본적으로 이 폰트를 사용합니다.
+
+### `font.text(value, options?)`
+
+문자열 전체를 `PAShape`로 만듭니다.
+
+주요 옵션:
+
+- `x`, `y`: baseline 시작 위치
+- `size`: 글자 크기
+- `flatten`: 곡선 평탄화 허용 오차
+- `kerning`, `letterSpacing`, `tracking`
+- `script`, `language`, `features`
+
+### `font.glyph(value, options?)`
+
+한 글자만 `PAShape`로 만듭니다.
+
+### `font.metrics(value, options?)`
+
+텍스트 폭과 bounding box만 빠르게 계산합니다.
+
+```js
+const metrics = font.metrics("안녕", { size: 120 });
+console.log(metrics.width, metrics.bbox);
+```
+
+### `font.paragraph(value, options?)`
+
+문단 레이아웃 객체 `paParagraph`를 만듭니다.
+
+추천 옵션:
+
+- `wrap`: `word | char | keep`
+- `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`
+
+세부 제어 옵션:
+
+- `whiteSpace`: `normal | pre-wrap | nowrap`
+- `overflowWrap`: `normal | break-word | anywhere`
+- `wordBreak`: `normal | break-all | keep-all`
+- `overflow`: `visible | hidden`
+- `textOverflow`: `clip | ellipsis`
+- `fontFamily`, `fontWeight`, `fontStyle`, `font`
+- `engine`: `pretext | native`
+- `maxLines`, `ellipsis`
+
+`wrap` 기본값은 `word`이며, 다음 조합의 shorthand입니다.
+
+- `word`: `wordBreak: "normal"` + `overflowWrap: "break-word"`
+- `char`: `wordBreak: "break-all"`
+- `keep`: `wordBreak: "keep-all"` + `overflowWrap: "normal"`
+
+`wordBreak` / `overflowWrap`를 직접 주면 `wrap`보다 우선합니다.
+
+## paParagraph API
+
+`font.paragraph()`는 `paParagraph`를 반환합니다.
+
+주요 속성:
+
+- `paragraph.text`
+- `paragraph.lines`
+- `paragraph.metrics`
+- `paragraph.options`
+- `paragraph.layoutEngine`
+
+주요 메서드:
+
+### `paragraph.relayout(next?)`
+
+폭이나 정렬이 바뀌었을 때 문단을 다시 레이아웃합니다.
+
+```js
+const mobile = paragraph.relayout({ width: 280 });
+```
+
+`width`를 생략한 문단은 `drawText(ctx)` 시 현재 canvas 폭에 맞춰 자동으로 다시 레이아웃됩니다.
+
+기본 `wrap: "word"` 경로는 `pretext`를 우선 사용하고, `break-all` / `keep-all` 또는
+엄격한 `overflowWrap: "normal"`이 필요한 경우만 native로 내려갑니다.
+실제로 사용된 엔진은 `paragraph.layoutEngine`에서 확인할 수 있습니다.
+
+### `paragraph.drawText(ctx, options?)`
+
+현재 문단 레이아웃을 canvas 텍스트로 그립니다.
+
+```js
+paragraph.drawText(ctx, {
+  fillStyle: "#111",
+});
+```
+
+옵션:
+
+- `fillStyle`
+- `strokeStyle`
+- `fill`
+- `stroke`
+
+### `paragraph.toShape(options?)`
+
+문단 전체를 하나의 `PAShape`로 변환합니다.
+
+```js
+const shape = paragraph.toShape({
+  layout: "current",
+  step: 6,
+  openWidth: 1,
+});
+```
+
+### `paragraph.toRegions(options?)`
+
+문단 전체를 plain region 데이터로 반환합니다.
+
+### `paragraph.toPoints(options?)`
+
+문단 전체를 점 샘플로 반환합니다.
+
+공통 옵션:
+
+- `layout`: `current | pretext | native`
+- `step`
+- `openWidth`
+- `includeHoles` (`toPoints()` 전용)
+
+`layout` 의미:
+
+- `current`: 현재 문단 줄바꿈 그대로 사용
+- `pretext`: `pretext` 기준으로 다시 줄 계산
+- `native`: `opentype.js` 측정 기준으로 다시 줄 계산
+
+## PAShape API
+
+`font.text()`와 `font.glyph()`는 `PAShape`를 반환합니다.
+
+주요 속성:
+
+- `shape.text`
+- `shape.bbox`
+- `shape.metrics`
+- `shape.polygons`
+
+주요 메서드:
+
+### `shape.glyphs()`
+
+문장을 글자별 `PAShape[]`로 나눕니다.
+
+### `shape.toShape({ step, openWidth })`
+
+변형된 새 `PAShape`를 반환합니다.
+
+- `step`: polygon 재샘플링 간격
+- `openWidth`: hole을 slit처럼 열기 위한 폭
+
+### `shape.toRegions({ step, openWidth })`
+
+최종 polygon 데이터를 반환합니다.
+
+반환 형태:
+
+```js
+[
+  {
+    outer: [[x, y], ...],
+    holes: [
+      [[x, y], ...],
+    ],
+    bbox: { x, y, w, h },
+  },
+];
+```
+
+### `shape.toPoints({ step, openWidth, includeHoles })`
+
+경계를 일정 간격의 점들로 샘플링합니다.
+
+### `shape.hit(x, y)` / `shape.contains(x, y)`
+
+도형 hit test를 합니다.
+
+## 언제 무엇을 쓰나
+
+- 편집/후처리를 계속할 거면 `toShape()`
+- 정확한 polygon 데이터가 필요하면 `toRegions()`
+- 점 기반 효과나 입자용이면 `toPoints()`
+- 문단을 화면에 바로 그리고 싶으면 `paragraph.drawText(ctx)`
+- 같은 문단을 geometry로 쓰고 싶으면 `paragraph.toShape()`
+
+## CSS-like 예시
+
+```js
+const paragraph = font.paragraph(text, {
+  x: 0,
+  y: 0,
+  size: 20,
+  lineHeight: 1.6,
+  padding: { x: 32, y: 24 },
+  margin: "20 0 0 20",
+  wrap: "char",
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+});
+
+paragraph.drawText(ctx);
+```
+
+이 구현은 CSS를 완전히 복제하는 엔진은 아니지만, canvas 문단 작업에 필요한
+`width auto`, `padding`, `margin`, `wordBreak`, `overflow`, `textOverflow`를
+가깝게 사용할 수 있도록 설계되어 있습니다.
+
+## 주의
+
+- `paragraph.drawText()`는 canvas 텍스트 렌더링입니다.
+- `fontFamily`를 생략하면 브라우저에서는 `paFont.load()`로 불러온 폰트가 기본값으로 사용됩니다.
+- 별도의 CSS webfont를 쓰고 싶으면 `fontFamily` 또는 `font`로 override하면 됩니다.
+- `step`, `openWidth`는 모두 절대 좌표 단위입니다.