pa_font 0.2.0 → 0.2.2

package/README.md

@@ -1,175 +1,39 @@
-# @hanyongpa/pa-font
+# paFont
 
-OpenType 폰트를 polygon, region, point 데이터로 바꿔 쓰기 위한 작은 geometry 라이브러리입니다.
+`paFont`는 OpenType 폰트에서 텍스트 geometry를 만들고, 같은 폰트로 canvas 문단 레이아웃까지 처리하는 작은 라이브러리입니다.
 
-현재 `package.json` 기준 패키지 이름은 `@hanyongpa/pa-font`로 잡아두었습니다. 실제 publish 전에 원하는 scope나 이름이 있으면 이 값만 바꾸면 됩니다.
+## 설치
 
-## Install
-
-```bash
-npm install @hanyongpa/pa-font
+```sh
+npm install pa_font
 ```
 
-## Quick Start
+## 빠른 예시
 
 ```js
-import paFont from "@hanyongpa/pa-font";
+import paFont from "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("캔버스에서 자동 줄바꿈되는 문단입니다.", {
+const paragraph = font.paragraph("Canvas paragraph with fast wrapping.", {
   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,
+  width: 420,
+  wrap: "word",
+  padding: { x: 24, y: 20 },
 });
-```
 
-Node에서 바이트로 읽어 넘길 때:
+paragraph.drawText(ctx, { fillStyle: "#111" });
 
-```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);
+const shape = paragraph.toShape({ step: 6 });
 ```
 
-## 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 })`
+## 문단 API 핵심
 
-hole 열기와 재샘플링을 적용한 뒤 새 `PAShape`를 반환합니다.
+- `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`에서 확인할 수 있습니다.
 
-### `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
-```
+자세한 사용법은 [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`는 모두 절대 좌표 단위입니다.