pdf-kalem 0.5.1 → 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.
- package/README.md +77 -40
- package/dist/{Page-CsUKWyUj.d.ts → Page-CgWtEMi-.d.ts} +5 -5
- package/dist/{PdfDoc-BrQ03kn0.d.ts → PdfDoc-CqZg8aqy.d.ts} +9 -11
- package/dist/{PdfPageSurface-Dzx68rek.d.ts → PdfPageSurface-BTqGIvbr.d.ts} +5 -5
- package/dist/{PdfRenderContext-DdmsufQc.d.ts → PdfRenderContext-BmY7wu2O.d.ts} +9 -9
- package/dist/{Table-B1JgJINU.d.ts → Table-cWARHMM3.d.ts} +2 -2
- package/dist/{Widget-D-wA9-fw.d.ts → Widget-b4xhwzqF.d.ts} +40 -28
- package/dist/{aspect-fit-C6ERLMZW.d.ts → aspect-fit-C4QKtECx.d.ts} +7 -7
- package/dist/{chunk-CGBZYXXD.js → chunk-3THFEGNW.js} +1 -1
- package/dist/chunk-3THFEGNW.js.map +1 -0
- package/dist/{chunk-2P5P7KF5.js → chunk-5333IIWA.js} +43 -33
- package/dist/chunk-5333IIWA.js.map +1 -0
- package/dist/{chunk-CKBKBBHC.js → chunk-5GXIUBFG.js} +25 -12
- package/dist/chunk-5GXIUBFG.js.map +1 -0
- package/dist/{chunk-JU7VYYBJ.js → chunk-H7DHGUR6.js} +2 -2
- package/dist/{chunk-JU7VYYBJ.js.map → chunk-H7DHGUR6.js.map} +1 -1
- package/dist/{chunk-MBZC4ZQH.js → chunk-IS7375N2.js} +11 -11
- package/dist/chunk-IS7375N2.js.map +1 -0
- package/dist/{chunk-SBH3Y5H7.js → chunk-JEV65QBH.js} +1 -1
- package/dist/chunk-JEV65QBH.js.map +1 -0
- package/dist/{chunk-AITTHKEP.js → chunk-JPJ4TBXY.js} +64 -274
- package/dist/chunk-JPJ4TBXY.js.map +1 -0
- package/dist/{chunk-2RBUCDMS.js → chunk-PCUD3B3X.js} +250 -85
- package/dist/chunk-PCUD3B3X.js.map +1 -0
- package/dist/{chunk-TWNM3K3Y.js → chunk-T4UQRZSP.js} +15 -27
- package/dist/chunk-T4UQRZSP.js.map +1 -0
- package/dist/{doc-output-NLO_E7Qr.d.ts → doc-output-C-6LJ3Tr.d.ts} +2 -2
- package/dist/edit.d.ts +12 -12
- package/dist/edit.js +16 -14
- package/dist/edit.js.map +1 -1
- package/dist/forms.d.ts +33 -30
- package/dist/forms.js +76 -32
- package/dist/forms.js.map +1 -1
- package/dist/{image-format-Dvz7_MH4.d.ts → image-format-Bkj-TFkg.d.ts} +1 -1
- package/dist/index.d.ts +18 -33
- package/dist/index.js +8 -10
- package/dist/index.js.map +1 -1
- package/dist/internals.d.ts +19 -23
- package/dist/internals.js +5 -5
- package/dist/markdown.d.ts +11 -11
- package/dist/markdown.js +11 -11
- package/dist/markdown.js.map +1 -1
- package/dist/preview.d.ts +5 -5
- package/dist/preview.js +2 -2
- package/dist/preview.js.map +1 -1
- package/dist/{surface-BJ7MIOTD.d.ts → surface-Ctlxrrq0.d.ts} +3 -3
- package/dist/{types-ChQa4dgU.d.ts → types-DcnOoasz.d.ts} +3 -3
- package/dist/utils/color-utils.js +1 -1
- package/dist/widgets.d.ts +44 -69
- package/dist/widgets.js +7 -7
- package/dist/widgets.js.map +1 -1
- package/package.json +16 -15
- package/dist/chunk-2P5P7KF5.js.map +0 -1
- package/dist/chunk-2RBUCDMS.js.map +0 -1
- package/dist/chunk-AITTHKEP.js.map +0 -1
- package/dist/chunk-CGBZYXXD.js.map +0 -1
- package/dist/chunk-CKBKBBHC.js.map +0 -1
- package/dist/chunk-MBZC4ZQH.js.map +0 -1
- package/dist/chunk-SBH3Y5H7.js.map +0 -1
- package/dist/chunk-TWNM3K3Y.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
|
|
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
|
|
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
|
|
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
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
|
|
18
|
-
- **Builds fillable forms** via `pdf-kalem/forms`: text fields, checkboxes, dropdowns, radio groups, and buttons as widget-tree nodes
|
|
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
|
|
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**
|
|
29
|
-
2. **Render layer**
|
|
30
|
-
3. **Shared services**
|
|
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`
|
|
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
|
|
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
|
|
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
|
|
105
|
+
pnpm dev
|
|
72
106
|
```
|
|
73
107
|
|
|
74
|
-
`pnpm
|
|
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
|
|
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**
|
|
124
|
-
2. **Paginate**
|
|
125
|
-
3. **Render**
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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: {
|
|
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
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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**
|
|
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
|
|
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)
|
|
364
|
-
- [pdf-lib](https://github.com/Hopding/pdf-lib)
|
|
365
|
-
- [Yoga](https://github.com/facebook/yoga)
|
|
366
|
-
- [`@chenglou/pretext`](https://github.com/chenglou/pretext)
|
|
367
|
-
- [@mdi/js](https://github.com/Templarian/MaterialDesign-JS)
|
|
368
|
-
- [@pdf-lib/fontkit](https://github.com/Hopding/pdf-lib/tree/master/fontkit)
|
|
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-
|
|
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
|
|
24
|
+
/** @internal - flow layout pass for pagination (used by Paginator). */
|
|
25
25
|
runFlowLayout(width: number, height: number | undefined): void;
|
|
26
|
-
/** @internal
|
|
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
|
|
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
|
|
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-
|
|
2
|
-
import { P as PdfRenderContext } from './PdfRenderContext-
|
|
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-
|
|
6
|
-
import { N as NodeBufferLike } from './doc-output-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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-
|
|
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"
|
|
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`
|
|
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
|
|
25
|
-
* streams, annotations, links, and form fields come along
|
|
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-
|
|
3
|
-
import { P as PdfPageSurface } from './PdfPageSurface-
|
|
4
|
-
import { P as PdfFormSurface } from './surface-
|
|
5
|
-
import { F as FontSet } from './types-
|
|
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
|
|
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
|
|
74
|
-
* annotations, links, and form fields come along
|
|
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`
|
|
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
|
|
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-
|
|
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
|
|
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;
|