pa_font 0.1.2 → 0.2.0

package/README.md

@@ -0,0 +1,175 @@
+# @hanyongpa/pa-font
+
+OpenType 폰트를 polygon, region, point 데이터로 바꿔 쓰기 위한 작은 geometry 라이브러리입니다.
+
+현재 `package.json` 기준 패키지 이름은 `@hanyongpa/pa-font`로 잡아두었습니다. 실제 publish 전에 원하는 scope나 이름이 있으면 이 값만 바꾸면 됩니다.
+
+## Install
+
+```bash
+npm install @hanyongpa/pa-font
+```
+
+## Quick Start
+
+```js
+import paFont from "@hanyongpa/pa-font";
+
+const font = await paFont.load("/assets/font.otf");
+
+const shape = font.text("안녕", {
+  x: 0,
+  y: 200,
+  size: 160,
+  flatten: 1,
+});
+
+const regions = shape.toRegions();
+const points = shape.toPoints({ step: 8 });
+```
+
+## Paragraph Layout
+
+`font.paragraph(...)`는 `pretext.js` 기반으로 자동 줄바꿈되는 문단 레이아웃을 만들고,
+같은 문단을 canvas 텍스트 렌더링과 `paFont` geometry 변환에 같이 쓸 수 있습니다.
+
+```js
+const paragraph = font.paragraph("캔버스에서 자동 줄바꿈되는 문단입니다.", {
+  x: 40,
+  y: 80,
+  width: 420,
+  size: 32,
+  fontFamily: "MyFont",
+  fontWeight: 400,
+  lineHeight: 1.4,
+  align: "left",
+  whiteSpace: "normal",
+  engine: "pretext",
+});
+
+paragraph.drawText(ctx, {
+  fillStyle: "#111",
+});
+
+const shape = paragraph.toShape();
+const regions = paragraph.toRegions({ step: 6, openWidth: 1 });
+const points = paragraph.toPoints({ step: 8, openWidth: 1 });
+```
+
+폭이 바뀌면 문단만 다시 레이아웃할 수 있습니다.
+
+```js
+const mobile = paragraph.relayout({ width: 280 });
+mobile.drawText(ctx);
+```
+
+정밀한 `paFont` export용으로는 `layout: "native"`를 사용할 수 있습니다.
+
+```js
+const exact = paragraph.toShape({
+  layout: "native",
+  step: 4,
+});
+```
+
+## Core Flow
+
+1. `paFont.load(...)`로 폰트를 로드합니다.
+2. `font.text(...)` 또는 `font.glyph(...)`로 `PAShape`를 만듭니다.
+3. `shape.toShape(...)`, `shape.toRegions(...)`, `shape.toPoints(...)` 중 필요한 결과를 꺼냅니다.
+
+## Loading Fonts
+
+브라우저에서 가장 단순한 방식:
+
+```js
+const font = await paFont.load("/assets/font.otf");
+```
+
+모듈 상대 경로를 기준으로 읽고 싶을 때:
+
+```js
+const font = await paFont.load("./font.otf", {
+  base: import.meta.url,
+});
+```
+
+Node에서 바이트로 읽어 넘길 때:
+
+```js
+import { readFile } from "node:fs/promises";
+import paFont from "@hanyongpa/pa-font";
+
+const bytes = await readFile("./fonts/font.otf");
+const font = await paFont.load(bytes);
+```
+
+## Public API
+
+### `font.text(value, options)`
+
+문자열 전체를 하나의 `PAShape`로 만듭니다.
+
+### `font.glyph(value, options)`
+
+한 글자만 `PAShape`로 만듭니다.
+
+### `font.metrics(value, options)`
+
+텍스트 폭과 bounding box만 빠르게 계산합니다.
+
+### `font.paragraph(value, options)`
+
+문단 레이아웃 객체 `paParagraph`를 만듭니다.
+
+자주 쓰는 옵션:
+
+- `width`: 문단 폭
+- `lineHeight`: 숫자 `<= 10`이면 배수, 그보다 크면 절대 px
+- `fontFamily`, `fontWeight`, `fontStyle`, `font`: canvas text 측정/렌더링용 폰트 설정
+- `align`: `left | center | right | justify`
+- `whiteSpace`: `normal | pre-wrap | nowrap`
+- `engine`: `pretext | native`
+
+주의:
+
+- `drawText()`는 canvas 텍스트 렌더링을 사용합니다.
+- `fontFamily` 또는 `font`는 브라우저에 실제 등록된 폰트와 맞아야 합니다.
+- `paragraph.toShape()`, `paragraph.toRegions()`, `paragraph.toPoints()`는 같은 문단 레이아웃을 `paFont` geometry로 변환합니다.
+
+### `shape.toShape({ step, openWidth })`
+
+hole 열기와 재샘플링을 적용한 뒤 새 `PAShape`를 반환합니다.
+
+### `shape.toRegions({ step, openWidth })`
+
+최종 도형을 plain polygon data로 반환합니다.
+
+```js
+const regions = font.glyph("영", { size: 160 }).toRegions({
+  step: 8,
+  openWidth: 1,
+});
+```
+
+### `shape.toPoints({ step, openWidth, includeHoles })`
+
+경계를 점 데이터로 샘플링합니다.
+
+### `shape.glyphs()`
+
+문장 shape를 글자별 shape 배열로 분리합니다.
+
+## Build
+
+라이브러리 빌드:
+
+```bash
+npm run build
+```
+
+패키징 확인:
+
+```bash
+npm run pack:check
+```