pa_font 0.1.3 → 0.2.0

package/README.md

@@ -28,6 +28,50 @@ 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(...)`로 폰트를 로드합니다.
@@ -74,6 +118,25 @@ const font = await paFont.load(bytes);
 
 텍스트 폭과 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`를 반환합니다.