pdf-kalem 0.5.0 → 0.6.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +78 -41
  2. package/dist/{Page-Co_MgZDL.d.ts → Page-CgWtEMi-.d.ts} +5 -5
  3. package/dist/{PdfDoc-jjqPxRSC.d.ts → PdfDoc-CqZg8aqy.d.ts} +9 -11
  4. package/dist/{PdfPageSurface-1DVsuYJ2.d.ts → PdfPageSurface-BTqGIvbr.d.ts} +5 -5
  5. package/dist/{PdfRenderContext-C12DDr-w.d.ts → PdfRenderContext-BmY7wu2O.d.ts} +9 -9
  6. package/dist/{Table-DevmMUtU.d.ts → Table-cWARHMM3.d.ts} +2 -2
  7. package/dist/{Widget-DzXseZEZ.d.ts → Widget-b4xhwzqF.d.ts} +42 -27
  8. package/dist/{aspect-fit-C6ERLMZW.d.ts → aspect-fit-C4QKtECx.d.ts} +7 -7
  9. package/dist/{chunk-CGBZYXXD.js → chunk-3THFEGNW.js} +1 -1
  10. package/dist/chunk-3THFEGNW.js.map +1 -0
  11. package/dist/{chunk-6VRKPGB5.js → chunk-5333IIWA.js} +186 -21
  12. package/dist/chunk-5333IIWA.js.map +1 -0
  13. package/dist/{chunk-LYSHPJ3R.js → chunk-5GXIUBFG.js} +26 -15
  14. package/dist/chunk-5GXIUBFG.js.map +1 -0
  15. package/dist/{chunk-JU7VYYBJ.js → chunk-H7DHGUR6.js} +2 -2
  16. package/dist/{chunk-JU7VYYBJ.js.map → chunk-H7DHGUR6.js.map} +1 -1
  17. package/dist/chunk-IS7375N2.js +457 -0
  18. package/dist/chunk-IS7375N2.js.map +1 -0
  19. package/dist/{chunk-PIBYCKYY.js → chunk-JEV65QBH.js} +13 -14
  20. package/dist/chunk-JEV65QBH.js.map +1 -0
  21. package/dist/{chunk-SEKYHTYU.js → chunk-JPJ4TBXY.js} +89 -318
  22. package/dist/chunk-JPJ4TBXY.js.map +1 -0
  23. package/dist/{chunk-5ZRRZRCD.js → chunk-PCUD3B3X.js} +252 -87
  24. package/dist/chunk-PCUD3B3X.js.map +1 -0
  25. package/dist/{chunk-OS4HN6KV.js → chunk-T4UQRZSP.js} +15 -27
  26. package/dist/chunk-T4UQRZSP.js.map +1 -0
  27. package/dist/{doc-output-NLO_E7Qr.d.ts → doc-output-C-6LJ3Tr.d.ts} +2 -2
  28. package/dist/edit.d.ts +12 -12
  29. package/dist/edit.js +16 -15
  30. package/dist/edit.js.map +1 -1
  31. package/dist/forms.d.ts +33 -30
  32. package/dist/forms.js +77 -35
  33. package/dist/forms.js.map +1 -1
  34. package/dist/{image-format-Dvz7_MH4.d.ts → image-format-Bkj-TFkg.d.ts} +1 -1
  35. package/dist/index.d.ts +18 -33
  36. package/dist/index.js +8 -11
  37. package/dist/index.js.map +1 -1
  38. package/dist/internals.d.ts +20 -16
  39. package/dist/internals.js +5 -5
  40. package/dist/markdown.d.ts +11 -11
  41. package/dist/markdown.js +11 -12
  42. package/dist/markdown.js.map +1 -1
  43. package/dist/preview.d.ts +16 -9
  44. package/dist/preview.js +19 -9
  45. package/dist/preview.js.map +1 -1
  46. package/dist/{surface-hkLPm11r.d.ts → surface-Ctlxrrq0.d.ts} +3 -3
  47. package/dist/{types-ChQa4dgU.d.ts → types-DcnOoasz.d.ts} +3 -3
  48. package/dist/utils/color-utils.js +1 -1
  49. package/dist/widgets.d.ts +55 -73
  50. package/dist/widgets.js +20 -131
  51. package/dist/widgets.js.map +1 -1
  52. package/package.json +16 -15
  53. package/dist/chunk-5ZRRZRCD.js.map +0 -1
  54. package/dist/chunk-6VRKPGB5.js.map +0 -1
  55. package/dist/chunk-CGBZYXXD.js.map +0 -1
  56. package/dist/chunk-IGVDPDCZ.js +0 -258
  57. package/dist/chunk-IGVDPDCZ.js.map +0 -1
  58. package/dist/chunk-LYSHPJ3R.js.map +0 -1
  59. package/dist/chunk-OS4HN6KV.js.map +0 -1
  60. package/dist/chunk-PCKIGCEJ.js +0 -198
  61. package/dist/chunk-PCKIGCEJ.js.map +0 -1
  62. package/dist/chunk-PIBYCKYY.js.map +0 -1
  63. package/dist/chunk-SEKYHTYU.js.map +0 -1
package/README.md CHANGED
@@ -2,22 +2,22 @@
2
2
 
3
3
  > **For AI assistants:** read [`CONTEXT.md`](./CONTEXT.md) for a compact codebase orientation before diving into the source.
4
4
 
5
- > **Status: early alpha.** The API is not yet stable and may change between versions. Not recommended for production use yet — feedback and bug reports are welcome.
5
+ > **Status: early alpha.** The API is not yet stable and may change between versions. Not recommended for production use yet - feedback and bug reports are welcome. Known limitation: oversized atomic content can paint into page padding; review generated output carefully.
6
6
 
7
7
  pdf-kalem is a widget-tree UI library for document-style layout and generation.
8
8
 
9
- The core idea is to describe content as a tree of widgets — pages, containers, rows, columns, text, images, links, tables, and SVG paths — run [Yoga](https://github.com/facebook/yoga) for flexbox layout, and render the tree through a backend-specific renderer. The PDF backend (`pdf-lib`).
9
+ The core idea is to describe content as a tree of widgets - pages, containers, rows, columns, text, images, links, tables, and SVG paths - run [Yoga](https://github.com/facebook/yoga) for flexbox layout, and render the tree through a backend-specific renderer. The PDF backend (`pdf-lib`).
10
10
 
11
- The design is heavily inspired by [Flutter](https://flutter.dev)'s widget-tree model — the idea of composing documents from declarative widget trees with flexbox layout, theme tokens, and per-widget overrides. pdf-kalem adapts that mental model to the document/PDF domain.
11
+ The design is heavily inspired by [Flutter](https://flutter.dev)'s widget-tree model - the idea of composing documents from declarative widget trees with flexbox layout, theme tokens, and per-widget overrides. pdf-kalem adapts that mental model to the document/PDF domain.
12
12
 
13
13
  ## What It Does
14
14
 
15
15
  - Builds page-based layouts with Yoga (flexbox: `Row`, `Column`, `gap`, `flexGrow`, `%` widths, absolute positioning).
16
- - **Pagination**: content taller than one page automatically flows onto additional pages. Text blocks split by line, table rows stay whole and headers repeat, and each `Page` re-renders its chrome per output page. Opt out per page with `Page({ overflow: false })` or keep a text block together with `Text(..., { breakable: false })`.
17
- - **Edits existing PDFs** via `pdf-kalem/edit`: load a PDF as Page widgets, overlay widgets on its pages, restructure/merge, save — original content, annotations, and form fields preserved.
18
- - **Builds fillable forms** via `pdf-kalem/forms`: text fields, checkboxes, dropdowns, radio groups, and buttons as widget-tree nodes — real AcroForm fields in the output, with `formData` data binding (template + data).
16
+ - **Pagination**: content taller than one page automatically flows onto additional pages. Text blocks split by line, table rows stay whole and headers repeat, and each `Page` re-renders its chrome per output page; whitespace-only pages (an overflowing trailing `Spacer`) are dropped. Opt out per page with `Page({ overflow: false })` or keep a text block together with `Text(..., { breakable: false })`.
17
+ - **Edits existing PDFs** via `pdf-kalem/edit`: load a PDF as Page widgets, overlay widgets on its pages, restructure/merge, save - original content, annotations, and form fields preserved.
18
+ - **Builds fillable forms** via `pdf-kalem/forms`: text fields, checkboxes, dropdowns, radio groups, and buttons as widget-tree nodes - real AcroForm fields in the output, with `formData` data binding (template + data).
19
19
  - Exports PDFs through `pdf-lib` with metadata, custom fonts, link annotations, and SVG paths.
20
- - Provides a shared text engine (powered by [`@chenglou/pretext`](https://github.com/chenglou/pretext)) with grapheme-aware wrapping, `maxLines`, and `ellipsis` overflow.
20
+ - Provides a shared text engine that uses PDF font metrics for grapheme-aware wrapping, `maxLines`, and `ellipsis` overflow in both Node and browsers.
21
21
  - Supports document-scoped themes (color tokens, font aliases, text variants, table/container defaults) with per-widget overrides.
22
22
  - Runs in browser and Node (output helpers: `save`, `getBlob`, `download`, `getBuffer`, `writeToFile`).
23
23
 
@@ -25,20 +25,50 @@ The design is heavily inspired by [Flutter](https://flutter.dev)'s widget-tree m
25
25
 
26
26
  The project is split into three layers:
27
27
 
28
- 1. **Widget tree** — `PdfDoc`, `Page`, `Container`, `Text`, `Row`, `Column`, `Image`, `Link`, `FixedContainer`, `SVGPath`, `Table`, `HLine`, and related layout primitives. Widgets depend on a backend-neutral `RenderContext` interface, not on any concrete backend.
29
- 2. **Render layer** — `PdfRenderContext` (implements `RenderContext`) drives `pdf-lib`; `PdfRenderer` walks the page tree and drives the context. The PDF coordinate flip (y grows up from the bottom-left) is applied inside `PdfRenderContext`, so widgets deal in layout boxes, not PDF math.
30
- 3. **Shared services** — `FontRegistry` (singleton) owns registered font bytes, the fontkit instance, and browser `FontFace` loading. `TextLayoutEngine` (pure text measurement/wrapping/truncation) and `TextPainter` (draws a laid-out text block via a `RenderContext`) are shared by `Text` and `Link`.
28
+ 1. **Widget tree** - `PdfDoc`, `Page`, `Container`, `Text`, `Row`, `Column`, `Image`, `Link`, `FixedContainer`, `SVGPath`, `Table`, `HLine`, and related layout primitives. Widgets depend on a backend-neutral `RenderContext` interface, not on any concrete backend.
29
+ 2. **Render layer** - `PdfRenderContext` (implements `RenderContext`) drives `pdf-lib`; `PdfRenderer` walks the page tree and drives the context. The PDF coordinate flip (y grows up from the bottom-left) is applied inside `PdfRenderContext`, so widgets deal in layout boxes, not PDF math.
30
+ 3. **Shared services** - `FontRegistry` (singleton) owns registered font bytes, the fontkit instance, and browser `FontFace` loading. `TextLayoutEngine` (pure text measurement/wrapping/truncation) and `TextPainter` (draws a laid-out text block via a `RenderContext`) are shared by `Text` and `Link`.
31
31
 
32
- `PdfDoc` is the document model: it owns the page tree, theme, metadata, and lifecycle hooks. It is intentionally **not** a `Widget` — a document is not a layout node. Rendering is delegated to `PdfRenderer`, and runtime helpers (`save`/`getBlob`/`download`/`getBuffer`/`writeToFile`) live on `PdfDoc` as convenience methods.
32
+ `PdfDoc` is the document model: it owns the page tree, theme, metadata, and lifecycle hooks. It is intentionally **not** a `Widget` - a document is not a layout node. Rendering is delegated to `PdfRenderer`, and runtime helpers (`save`/`getBlob`/`download`/`getBuffer`/`writeToFile`) live on `PdfDoc` as convenience methods.
33
33
 
34
34
  ## Install
35
35
 
36
+ Requires **Node.js 22.18.0 or newer** for Node usage and local development. Node 22 is the development baseline (`nvm use` reads `.nvmrc`); the examples use its built-in TypeScript type stripping.
37
+
36
38
  From npm:
37
39
 
38
40
  ```bash
39
41
  pnpm add pdf-kalem
40
42
  ```
41
43
 
44
+ ## Your first PDF
45
+
46
+ Create `hello.mjs`:
47
+
48
+ ```js
49
+ import { PdfDoc } from 'pdf-kalem';
50
+ import { Page, Text } from 'pdf-kalem/widgets';
51
+
52
+ const doc = new PdfDoc({
53
+ children: [
54
+ Page({
55
+ padding: 24,
56
+ children: [Text('Hello world', { size: 18 })],
57
+ }),
58
+ ],
59
+ });
60
+
61
+ await doc.writeToFile('hello.pdf');
62
+ ```
63
+
64
+ Run `node hello.mjs`, then open `hello.pdf` in the same directory. No font files or extra configuration are required.
65
+
66
+ In a browser app, use the same widget tree and replace the last line with:
67
+
68
+ ```js
69
+ await doc.download('hello.pdf');
70
+ ```
71
+
42
72
  For local development in this repository:
43
73
 
44
74
  ```bash
@@ -47,12 +77,12 @@ pnpm install
47
77
 
48
78
  ## Examples
49
79
 
50
- The [`examples/`](./examples) folder holds self-contained, copyable projects — a one-file hello-world, an invoice, a multi-page report, and a markdown-to-PDF CLI. Each is a plain ESM TypeScript folder (no per-example npm setup) with its own theme, components, and data, structured so you can lift one into your own project and adapt it:
80
+ The [`examples/`](./examples) folder holds self-contained, copyable projects - a one-file hello-world, an invoice, a multi-page report, and a markdown-to-PDF CLI. Each is a plain ESM TypeScript folder (no per-example npm setup) with its own theme, components, and data, structured so you can lift one into your own project and adapt it:
51
81
 
52
82
  ```bash
53
83
  pnpm build # examples import the built library
54
84
  pnpm example # run every example; each writes its PDF next to its code
55
- # or: pnpm example invoice — just one
85
+ # or: pnpm example invoice - just one
56
86
  ```
57
87
 
58
88
  See [`examples/README.md`](./examples/README.md) for what each one demonstrates and how to copy one.
@@ -67,11 +97,15 @@ pnpm build
67
97
 
68
98
  ## Docs
69
99
 
100
+ Browse the [hosted documentation](https://alaypanov.github.io/pdf-kalem/) for guides and live playgrounds.
101
+
102
+ To run the documentation site locally:
103
+
70
104
  ```bash
71
- pnpm docs:dev
105
+ pnpm dev
72
106
  ```
73
107
 
74
- `pnpm docs:dev` runs the VitePress documentation site (Vue 3 + UnoCSS, in `docs/`) with a guide and dedicated playground pages for the widget-tree API and the markdown converter (both playgrounds are live workbenches). `pnpm docs:build` emits the static site into `docs/.vitepress/dist/`.
108
+ `pnpm dev` runs the VitePress documentation site (Vue 3 + UnoCSS, in `docs/`) with a guide and dedicated playground pages for the widget-tree API and the markdown converter (both playgrounds are live workbenches). `pnpm docs:build` emits the static site into `docs/.vitepress/dist/`.
75
109
 
76
110
  ## Example
77
111
 
@@ -114,15 +148,15 @@ const buffer = await doc.getBuffer();
114
148
  await doc.writeToFile('invoice.pdf');
115
149
  ```
116
150
 
117
- `getBuffer()` and `writeToFile()` are intended for Node runtimes. `download()`, `getBlob()`, and `print()` are browser-only — `print()` loads the PDF into a hidden iframe and opens the browser's print dialog (Safari's PDF viewer doesn't support programmatic printing; download-and-print manually there).
151
+ `getBuffer()` and `writeToFile()` are intended for Node runtimes. `download()`, `getBlob()`, and `print()` are browser-only - `print()` loads the PDF into a hidden iframe and opens the browser's print dialog (Safari's PDF viewer doesn't support programmatic printing; download-and-print manually there).
118
152
 
119
153
  ### Pagination
120
154
 
121
155
  When a page's content is taller than the page, pdf-kalem splits it across additional pages. It does this with a three-pass approach (layout → paginate → render), similar to react-pdf:
122
156
 
123
- 1. **Layout** — the whole page tree is laid out once on a single tall canvas.
124
- 2. **Paginate** — the laid-out tree is walked and split into per-page *fragment* trees. Each fragment is a lightweight view onto a widget for one output page (it reuses the same Yoga node, so there's no re-layout).
125
- 3. **Render** — each output page adds a PDF page and renders its fragments, shifting coordinates by `-pageIndex × pageHeight` so each slice lands correctly.
157
+ 1. **Layout** - the whole page tree is laid out once on a single tall canvas.
158
+ 2. **Paginate** - the laid-out tree is walked and split into per-page *fragment* trees. Each fragment is a lightweight view onto a widget for one output page (it reuses the same Yoga node, so there's no re-layout).
159
+ 3. **Render** - each output page adds a PDF page and renders its fragments, shifting coordinates by `-pageIndex × pageHeight` so each slice lands correctly.
126
160
 
127
161
  Splitting rules by widget:
128
162
 
@@ -186,7 +220,7 @@ Text(
186
220
  { size: 12 }
187
221
  );
188
222
 
189
- // Runs can carry their own links — each line fragment of the run gets its
223
+ // Runs can carry their own links - each line fragment of the run gets its
190
224
  // own clickable annotation, so a run that wraps stays clickable everywhere.
191
225
  Text([{ text: 'Read the ' }, { text: 'full report', href: 'https://example.com' }]);
192
226
 
@@ -195,13 +229,13 @@ Text([{ text: 'Read the ' }, { text: 'full report', href: 'https://example.com'
195
229
  Text([{ text: 'const x = 1', mono: true }]);
196
230
  ```
197
231
 
198
- Run fields: `fontWeight`, `fontStyle`, `strike`, `href`, `mono`, `font`, `color`. Weight follows CSS matching — 100–500 renders regular, 600–900 renders bold — and each axis replaces the base style (an explicit `fontWeight: 400` un-bolds a bold base). Faces resolve through the run's family with the usual fallback chain, so `{ fontWeight: 700 }` in an `inter` text uses `inter-bold` when loaded and falls back with a warning otherwise. Words that span run boundaries (`he` + `**llo**`) never break internally; wrapping, `maxLines`, and `ellipsis` all work across runs.
232
+ Run fields: `fontWeight`, `fontStyle`, `strike`, `href`, `mono`, `font`, `color`. Weight follows CSS matching - 100–500 renders regular, 600–900 renders bold - and each axis replaces the base style (an explicit `fontWeight: 400` un-bolds a bold base). Faces resolve through the run's family with the usual fallback chain, so `{ fontWeight: 700 }` in an `inter` text uses `inter-bold` when loaded and falls back with a warning otherwise. Words that span run boundaries (`he` + `**llo**`) never break internally; wrapping, `maxLines`, and `ellipsis` all work across runs.
199
233
 
200
234
  ## Fonts
201
235
 
202
236
  Built-in aliases work without registration: `sans`, `sans-bold`, `sans-italic`, `sans-bold-italic`, `serif` (+ variants), `mono` (+ variants).
203
237
 
204
- For real typography, load a font set once and pass it to the document. Families come from your own font files — the repo's examples load Inter this way (the OFL-licensed TTFs live in [`examples/fonts/`](./examples/fonts)):
238
+ For real typography, load a font set once and pass it to the document. Families come from your own font files - the repo's examples load Inter this way (the OFL-licensed TTFs live in [`examples/fonts/`](./examples/fonts)):
205
239
 
206
240
  ```ts
207
241
  import { PdfDoc, useFonts } from 'pdf-kalem';
@@ -214,9 +248,9 @@ const fonts = await useFonts(
214
248
  const doc = new PdfDoc({ fonts, children: [/* ... */] });
215
249
  ```
216
250
 
217
- A family entry is either a single source (its regular face) or an object of per-face sources; a string is fetched (browser/http URL — pass bytes for Node filesystem loading). Code falls back to the builtin `mono` alias (Courier); load a real mono family via `files` when you need one.
251
+ A family entry is either a single source (its regular face) or an object of per-face sources; a string is fetched (browser/http URL - pass bytes for Node filesystem loading). Code falls back to the builtin `mono` alias (Courier); load a real mono family via `files` when you need one.
218
252
 
219
- A family carries faces: `regular` plus optional `bold`, `italic`, and `boldItalic`. A face is referenced by suffixing the family name — `inter-bold`, `inter-italic`, `inter-bold-italic` — the same convention the builtin aliases use. Missing faces fall back at embed time (bold-italic → bold → italic → regular) with a console warning, so a family can ship incrementally.
253
+ A family carries faces: `regular` plus optional `bold`, `italic`, and `boldItalic`. A face is referenced by suffixing the family name - `inter-bold`, `inter-italic`, `inter-bold-italic` - the same convention the builtin aliases use. Missing faces fall back at embed time (bold-italic → bold → italic → regular) with a console warning, so a family can ship incrementally.
220
254
 
221
255
  Bring your own fonts per face:
222
256
 
@@ -225,7 +259,10 @@ const fonts = await useFonts(
225
259
  { body: 'inter' },
226
260
  {
227
261
  files: {
228
- inter: { bold: '/fonts/MyInter-Bold.ttf' }, // one face as a URL
262
+ inter: {
263
+ regular: '/fonts/MyInter-Regular.ttf',
264
+ bold: '/fonts/MyInter-Bold.ttf',
265
+ },
229
266
  'my-serif': {
230
267
  regular: '/fonts/MySerif.ttf',
231
268
  italic: '/fonts/MySerif-Italic.ttf',
@@ -235,7 +272,7 @@ const fonts = await useFonts(
235
272
  );
236
273
  ```
237
274
 
238
- No `registerFontkit` call is needed — fontkit loads lazily on the first custom-font embed. Legacy global registration (`PdfDoc.registerFont` / `registerFonts` / `registerFontFromUrl`) still works as a process-wide fallback; doc-scoped `FontSet`s always resolve first.
275
+ No `registerFontkit` call is needed - fontkit loads lazily on the first custom-font embed. Legacy global registration (`PdfDoc.registerFont` / `registerFonts` / `registerFontFromUrl`) still works as a process-wide fallback; doc-scoped `FontSet`s always resolve first.
239
276
 
240
277
  ## Markdown
241
278
 
@@ -246,7 +283,7 @@ import { markdownToPdf, markdownToWidgets } from 'pdf-kalem/markdown';
246
283
 
247
284
  // Sugar: one paginated Page, markdown theme defaults merged under your theme.
248
285
  const doc = await markdownToPdf('# Report\n\nBody text with **emphasis**.', {
249
- theme: myTheme, // optional — user values win over the defaults
286
+ theme: myTheme, // optional - user values win over the defaults
250
287
  fonts, // optional FontSet (see Fonts above)
251
288
  page: { padding: 48 },
252
289
  });
@@ -257,15 +294,15 @@ await doc.save();
257
294
  const blocks = await markdownToWidgets(md, { styles: { spacing: 8 } });
258
295
  ```
259
296
 
260
- Supported: headings (`h1`..`h6` theme variants, bold), emphasis (`**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``), links (clickable per line fragment, underlined, `link` color token), ordered/unordered/nested/task lists (tasks render as `✓`/`□`), fenced code blocks (monospace, `pre-wrap`, background), blockquotes (left rule + italic), GFM tables (per-column alignment, padded cells, header row), horizontal rules, and images (png/jpeg — the format is sniffed from the fetched bytes; other formats are skipped with a warning).
297
+ Supported: headings (`h1`..`h6` theme variants, bold), emphasis (`**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``), links (clickable per line fragment, underlined, `link` color token), ordered/unordered/nested/task lists (tasks render as `✓`/`□`), fenced code blocks (monospace, `pre-wrap`, background), blockquotes (left rule + italic), GFM tables (per-column alignment, padded cells, header row), horizontal rules, and images (png/jpeg - the format is sniffed from the fetched bytes; other formats are skipped with a warning).
261
298
 
262
299
  Styling is theme-driven: headings resolve the `h1`..`h6` text variants, links resolve the `link` color token, and `MarkdownStyles` overrides the rest (code font/colors, blockquote rule, list indent, spacing, image width, table options). `markdownThemeDefaults` is exported so custom docs can merge the same baseline.
263
300
 
264
- A copyable converter project ships in [`examples/markdown/`](./examples/markdown) — a small CLI that turns any markdown file (or an embedded sample) into a paginated PDF.
301
+ A copyable converter project ships in [`examples/markdown/`](./examples/markdown) - a small CLI that turns any markdown file (or an embedded sample) into a paginated PDF.
265
302
 
266
303
  ## Forms
267
304
 
268
- The `pdf-kalem/forms` subpath adds **real AcroForm fields** to the widget tree — the saved PDF is fillable in any PDF reader:
305
+ The `pdf-kalem/forms` subpath adds **real AcroForm fields** to the widget tree - the saved PDF is fillable in any PDF reader:
269
306
 
270
307
  ```ts
271
308
  import { TextField, CheckBox, Dropdown, RadioGroup, Radio, Button, Signature } from 'pdf-kalem/forms';
@@ -277,15 +314,15 @@ Page({
277
314
  Dropdown('country', { options: ['Germany', 'Kazakhstan'] }),
278
315
  RadioGroup('plan', { children: [Radio('basic'), Radio('pro')] }),
279
316
  CheckBox('consent'),
280
- Button('submit', { label: 'Register' }), // visual only — pdf-lib has no action API
317
+ Button('submit', { label: 'Register' }), // visual only - pdf-lib has no action API
281
318
  Signature(), // drawn signing line, not a field
282
319
  ],
283
320
  });
284
321
  ```
285
322
 
286
- Every field takes a unique `name` (the AcroForm field name), ships a usable default size, and is atomic — on overflow it moves whole to the next page. Labels are plain `Text` widgets you compose yourself.
323
+ Every field takes a unique `name` (the AcroForm field name), ships a usable default size, and is atomic - on overflow it moves whole to the next page. Labels are plain `Text` widgets you compose yourself.
287
324
 
288
- **Data binding**: `new PdfDoc({ children, formData })` applies values by field name, winning over per-widget `value`/`checked` options — the same tree-builder with different `formData` produces filled variants of one template. Type mismatches throw at construction; keys matching no field warn.
325
+ **Data binding**: `new PdfDoc({ children, formData })` applies values by field name, winning over per-widget `value`/`checked` options - the same tree-builder with different `formData` produces filled variants of one template. Type mismatches throw at construction; keys matching no field warn.
289
326
 
290
327
  A copyable form project ships in [`examples/forms/`](./examples/forms) (blank template + filled variant). See the [form widgets guide](https://alaypanov.github.io/pdf-kalem/guide/forms) for the full field set and limitations (field text is Helvetica; buttons carry no actions; `Signature` is a drawn placeholder, not a signature field).
291
328
 
@@ -345,7 +382,7 @@ The current direction is:
345
382
 
346
383
  - keep the widget tree focused on document layout
347
384
  - keep PDF behavior explicit and first-class via `PdfDoc` / `PdfRenderContext`
348
- - **PDF-only focus** — no image/HTML backends are planned ([ADR 0001](./docs/adr/0001-pdf-only-focus.md)). PDF-specific features live in PDF-typed modules (e.g. `pdf-kalem/edit`) instead of widening the backend-neutral interface.
385
+ - **PDF-only focus** - no image/HTML backends are planned ([ADR 0001](./docs/adr/0001-pdf-only-focus.md)). PDF-specific features live in PDF-typed modules (e.g. `pdf-kalem/edit`) instead of widening the backend-neutral interface.
349
386
 
350
387
  The `RenderContext` seam stays because it is load-bearing, not as a backend hook: pagination's per-page `PageScope` composes through it, and the PDF Y-flip lives in one place (`mapContentBox`).
351
388
 
@@ -354,18 +391,18 @@ The `RenderContext` seam stays because it is load-bearing, not as a backend hook
354
391
  - `pnpm build` builds the npm package into `dist/`.
355
392
  - `pnpm example` builds the package and runs every example (each writes its PDF next to its code); pass names to run a subset: `pnpm example invoice report`.
356
393
  - `pnpm typecheck` runs TypeScript without emitting files.
357
- - `pnpm docs:dev` runs the documentation site.
394
+ - `pnpm dev` runs the documentation site.
358
395
 
359
396
  ## Special Thanks
360
397
 
361
398
  pdf-kalem stands on the shoulders of several excellent open-source projects:
362
399
 
363
- - [Flutter](https://flutter.dev) — the widget-tree mental model that inspired pdf-kalem's design.
364
- - [pdf-lib](https://github.com/Hopding/pdf-lib) — the PDF generation engine that powers the PDF backend.
365
- - [Yoga](https://github.com/facebook/yoga) — the flexbox layout engine (from Meta/Facebook) that handles all layout computation.
366
- - [`@chenglou/pretext`](https://github.com/chenglou/pretext) — the grapheme-aware text measurement and wrapping engine.
367
- - [@mdi/js](https://github.com/Templarian/MaterialDesign-JS) — Material Design Icons path data, used by the `Icon` widget.
368
- - [@pdf-lib/fontkit](https://github.com/Hopding/pdf-lib/tree/master/fontkit) — custom font subsetting and embedding for PDFs.
400
+ - [Flutter](https://flutter.dev) - the widget-tree mental model that inspired pdf-kalem's design.
401
+ - [pdf-lib](https://github.com/Hopding/pdf-lib) - the PDF generation engine that powers the PDF backend.
402
+ - [Yoga](https://github.com/facebook/yoga) - the flexbox layout engine (from Meta/Facebook) that handles all layout computation.
403
+ - [`@chenglou/pretext`](https://github.com/chenglou/pretext) - powered grapheme-aware wrapping in earlier versions.
404
+ - [@mdi/js](https://github.com/Templarian/MaterialDesign-JS) - Material Design Icons path data, used by the `Icon` widget.
405
+ - [@pdf-lib/fontkit](https://github.com/Hopding/pdf-lib/tree/master/fontkit) - custom font subsetting and embedding for PDFs.
369
406
 
370
407
  # Tools
371
408
  - Zed Editor
@@ -1,4 +1,4 @@
1
- import { W as Widget, a as WidgetOptions, R as RenderContext, s as LayoutBox } from './Widget-DzXseZEZ.js';
1
+ import { W as Widget, a as WidgetOptions, R as RenderContext, s as LayoutBox } from './Widget-b4xhwzqF.js';
2
2
  import { a as PageSize } from './doc-sizes-BP4GVKGs.js';
3
3
 
4
4
  interface PageOptions extends WidgetOptions {
@@ -21,17 +21,17 @@ declare class PageWidget extends Widget {
21
21
  getDimensions(context: RenderContext): [number, number];
22
22
  /** Whether content overflowing this page splits across continuation pages. */
23
23
  get paginates(): boolean;
24
- /** @internal — flow layout pass for pagination (used by Paginator). */
24
+ /** @internal - flow layout pass for pagination (used by Paginator). */
25
25
  runFlowLayout(width: number, height: number | undefined): void;
26
- /** @internal — content box after layout, page-relative top-left origin. */
26
+ /** @internal - content box after layout, page-relative top-left origin. */
27
27
  getContentBox(dimensions: [number, number]): LayoutBox;
28
28
  /**
29
29
  * Opens the backend surface this page paints onto. LoadedPage overrides
30
- * this to a no-op — its surface is an adopted existing page, opened in
30
+ * this to a no-op - its surface is an adopted existing page, opened in
31
31
  * render() before the layout pass.
32
32
  *
33
33
  * Page lifecycle is PDF mechanics (PdfPageSurface), not part of the
34
- * neutral RenderContext — pages are where drawing surfaces are created.
34
+ * neutral RenderContext - pages are where drawing surfaces are created.
35
35
  */
36
36
  protected openPage(context: RenderContext, dimensions: [number, number]): Promise<void>;
37
37
  render(context: RenderContext): Promise<void>;
@@ -1,9 +1,9 @@
1
- import { T as Theme, W as Widget, a as WidgetOptions } from './Widget-DzXseZEZ.js';
2
- import { P as PdfRenderContext } from './PdfRenderContext-C12DDr-w.js';
1
+ import { T as Theme, W as Widget, a as WidgetOptions } from './Widget-b4xhwzqF.js';
2
+ import { P as PdfRenderContext } from './PdfRenderContext-BmY7wu2O.js';
3
3
  import { a as PageSize } from './doc-sizes-BP4GVKGs.js';
4
4
  import { PDFDocument } from 'pdf-lib';
5
- import { F as FontSet } from './types-ChQa4dgU.js';
6
- import { N as NodeBufferLike } from './doc-output-NLO_E7Qr.js';
5
+ import { F as FontSet } from './types-DcnOoasz.js';
6
+ import { N as NodeBufferLike } from './doc-output-C-6LJ3Tr.js';
7
7
 
8
8
  type Awaitable<T> = T | Promise<T>;
9
9
  interface PdfDocOptions extends WidgetOptions {
@@ -19,7 +19,7 @@ interface PdfDocOptions extends WidgetOptions {
19
19
  fonts?: FontSet;
20
20
  /**
21
21
  * Data binding: values applied to the tree's form widgets (`pdf-kalem/forms`)
22
- * by AcroForm field name — the widgets' `name`. Applied in the constructor;
22
+ * by AcroForm field name - the widgets' `name`. Applied in the constructor;
23
23
  * wins over per-widget `value`/`checked` options. Type mismatches throw
24
24
  * (text wants a string, checkbox a boolean, dropdown/radio a declared
25
25
  * option); keys matching no field warn. The same tree-builder with
@@ -56,7 +56,7 @@ interface PdfDocAfterSaveArgs {
56
56
  }
57
57
  /**
58
58
  * PdfDoc is the document model: it owns the page tree, theme, metadata, and
59
- * lifecycle hooks. It is intentionally not a Widget — a document is not a
59
+ * lifecycle hooks. It is intentionally not a Widget - a document is not a
60
60
  * layout node. Rendering is the save-time walk over the page tree; output
61
61
  * mechanics (blob/download/buffer/file) delegate to the runtime adapters in
62
62
  * `doc-output.ts`.
@@ -79,8 +79,7 @@ declare class PdfDoc {
79
79
  */
80
80
  static registerFont(fontName: string, fontData: Uint8Array | ArrayBuffer): void;
81
81
  static registerFontkit(fontkit: any): void;
82
- protected size?: PageSize;
83
- protected dimensions?: [number, number];
82
+ protected dimensions: [number, number];
84
83
  protected layout: 'portrait' | 'landscape';
85
84
  protected theme?: Theme;
86
85
  protected fonts?: FontSet;
@@ -95,7 +94,7 @@ declare class PdfDoc {
95
94
  /**
96
95
  * Total number of output pages, computed by running the pagination plan
97
96
  * for every Page widget (a dry run: no drawing, no pages added).
98
- * Memoized — plans are pure, so the count is stable for an unchanged tree.
97
+ * Memoized - plans are pure, so the count is stable for an unchanged tree.
99
98
  *
100
99
  * Text metrics are exact once fonts have been embedded by {@link save};
101
100
  * before that, un-embedded fonts fall back to estimated widths. Trees
@@ -109,12 +108,11 @@ declare class PdfDoc {
109
108
  getFonts(): FontSet | undefined;
110
109
  /**
111
110
  * The doc's effective theme: the user's theme with the FontSet's font
112
- * tokens applied over it (doc-level wins). Returns a NEW object — the
111
+ * tokens applied over it (doc-level wins). Returns a NEW object - the
113
112
  * user's theme value is never mutated, so theme objects can be shared
114
113
  * across documents safely.
115
114
  */
116
115
  private deriveTheme;
117
- private getDimensions;
118
116
  getWidth(): number;
119
117
  getHeight(): number;
120
118
  savePdf(): Promise<Uint8Array>;
@@ -1,17 +1,17 @@
1
1
  import { PDFPage, PDFDocument } from 'pdf-lib';
2
- import { R as RenderContext } from './Widget-DzXseZEZ.js';
2
+ import { R as RenderContext } from './Widget-b4xhwzqF.js';
3
3
 
4
4
  /**
5
5
  * The PDF-specific page-lifecycle surface (ARCHITECTURE #10).
6
6
  *
7
7
  * ADR 0001's rule is "PDF-specific features get PDF-typed modules, never
8
- * interface widening" — but `adoptPage` and the page-handle members lived on
8
+ * interface widening" - but `adoptPage` and the page-handle members lived on
9
9
  * the "backend-neutral" `RenderContext`, typed `unknown` to hide that they
10
10
  * are pdf-lib mechanics. This interface moves them where they belong: the
11
11
  * PDF-typed layer.
12
12
  *
13
13
  * `PdfRenderContext` implements both interfaces (it already had every
14
- * method); the edit module's `LoadedPage` — the one consumer of adoption —
14
+ * method); the edit module's `LoadedPage` - the one consumer of adoption -
15
15
  * narrows to this surface at render time.
16
16
  */
17
17
  interface PdfPageSurface {
@@ -21,8 +21,8 @@ interface PdfPageSurface {
21
21
  setCurrentPage(page: PDFPage): void;
22
22
  /**
23
23
  * Adopts a page from a foreign `PDFDocument` as the current drawing
24
- * surface: the page object is copied into the output document — content
25
- * streams, annotations, links, and form fields come along — so subsequent
24
+ * surface: the page object is copied into the output document - content
25
+ * streams, annotations, links, and form fields come along - so subsequent
26
26
  * drawing lands on top of the original content. Used by the edit module
27
27
  * (`pdf-kalem/edit`).
28
28
  */
@@ -1,8 +1,8 @@
1
1
  import { PDFDocument, PDFForm, PDFPage, StandardFonts, PDFFont } from 'pdf-lib';
2
- import { R as RenderContext, h as RenderContextOptions, T as Theme, W as Widget, i as RenderImage, d as DrawRectangleArgs, f as DrawTextArgs, c as DrawLineArgs, D as DrawImageArgs, e as DrawSvgPathArgs, L as LinkAnnotationArgs } from './Widget-DzXseZEZ.js';
3
- import { P as PdfPageSurface } from './PdfPageSurface-1DVsuYJ2.js';
4
- import { P as PdfFormSurface } from './surface-hkLPm11r.js';
5
- import { F as FontSet } from './types-ChQa4dgU.js';
2
+ import { R as RenderContext, h as RenderContextOptions, T as Theme, W as Widget, i as RenderImage, d as DrawRectangleArgs, f as DrawTextArgs, c as DrawLineArgs, D as DrawImageArgs, e as DrawSvgPathArgs, L as LinkAnnotationArgs } from './Widget-b4xhwzqF.js';
3
+ import { P as PdfPageSurface } from './PdfPageSurface-BTqGIvbr.js';
4
+ import { P as PdfFormSurface } from './surface-Ctlxrrq0.js';
5
+ import { F as FontSet } from './types-DcnOoasz.js';
6
6
 
7
7
  /**
8
8
  * PDF backend for {@link RenderContext}. Drives a `pdf-lib` `PDFDocument`:
@@ -61,7 +61,7 @@ declare class PdfRenderContext implements RenderContext, PdfPageSurface, PdfForm
61
61
  /**
62
62
  * The document's interactive form (created in the catalog on first use).
63
63
  * Form widgets (`src/lib/forms/`) narrow to {@link PdfFormSurface} at render
64
- * time and create their fields through it — PDF-typed per ADR 0001, never
64
+ * time and create their fields through it - PDF-typed per ADR 0001, never
65
65
  * part of the neutral `RenderContext`.
66
66
  */
67
67
  getForm(): PDFForm;
@@ -70,8 +70,8 @@ declare class PdfRenderContext implements RenderContext, PdfPageSurface, PdfForm
70
70
  setCurrentPage(currentPage: PDFPage): void;
71
71
  /**
72
72
  * Adopts a page from a foreign `PDFDocument` (e.g. one loaded by the edit
73
- * module): the page object is copied into this document — content streams,
74
- * annotations, links, and form fields come along — and becomes the current
73
+ * module): the page object is copied into this document - content streams,
74
+ * annotations, links, and form fields come along - and becomes the current
75
75
  * page, so subsequent drawing lands on top of the original content.
76
76
  */
77
77
  adoptPage(source: unknown, pageIndex: number): Promise<void>;
@@ -114,7 +114,7 @@ declare class PdfRenderContext implements RenderContext, PdfPageSurface, PdfForm
114
114
  /**
115
115
  * The fontkit instance used to embed custom fonts: an explicitly
116
116
  * registered one (via {@link FontRegistry}) first, then a lazy dynamic
117
- * import of `@pdf-lib/fontkit` — so documents with custom fonts need no
117
+ * import of `@pdf-lib/fontkit` - so documents with custom fonts need no
118
118
  * `registerFontkit` call.
119
119
  */
120
120
  private ensureFontkit;
@@ -122,7 +122,7 @@ declare class PdfRenderContext implements RenderContext, PdfPageSurface, PdfForm
122
122
  measureTextWidth(text: string, size: number, fontName?: StandardFonts | string): number;
123
123
  /**
124
124
  * Typographic (hhea) metrics for embedded custom fonts, via pdf-lib's
125
- * fontkit embedder. pdf-lib's `heightAtSize` is bbox-based — its
125
+ * fontkit embedder. pdf-lib's `heightAtSize` is bbox-based - its
126
126
  * `descender: false` variant returns the bbox yMax, which sits far below
127
127
  * the real ascender for fonts like Inter and made line boxes bottom-heavy.
128
128
  * Standard fonts have no fontkit font; their AFM metrics are already
@@ -1,4 +1,4 @@
1
- import { a as WidgetOptions, W as Widget, b as ThemeColorValue, Y as YogaStyleValue, R as RenderContext, g as RenderColor, B as BreakUnit } from './Widget-DzXseZEZ.js';
1
+ import { a as WidgetOptions, W as Widget, b as ThemeColorValue, Y as YogaStyleValue, R as RenderContext, g as RenderColor, B as BreakUnit } from './Widget-b4xhwzqF.js';
2
2
 
3
3
  interface TableOptions extends WidgetOptions {
4
4
  head?: TableHeadWidget;
@@ -103,7 +103,7 @@ declare class TableWidget extends Widget {
103
103
  * continuation page) and `keepWithNext` (never orphaned at a page bottom);
104
104
  * rows are atomic because a TableRow is row-direction, so the base-class
105
105
  * default returns null for them and the paginator moves rows whole. The
106
- * render side needs no pagination awareness — rows are real widgets the
106
+ * render side needs no pagination awareness - rows are real widgets the
107
107
  * plan places like any other.
108
108
  */
109
109
  getBreakUnits(): BreakUnit[] | null;