@typfolio/dev-tools 0.5.0 → 0.7.0
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 +68 -5
- package/dist/panel.d.ts +25 -1
- package/dist/panel.js +125 -23
- package/dist/structure.d.ts +15 -3
- package/dist/structure.js +53 -21
- package/dist/validate-cli.d.ts +2 -0
- package/dist/validate-cli.js +110 -0
- package/dist/validate.d.ts +58 -0
- package/dist/validate.js +134 -0
- package/dist/validation.d.ts +63 -0
- package/dist/validation.js +11 -0
- package/package.json +10 -3
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @typfolio/dev-tools
|
|
2
2
|
|
|
3
|
-
Dev-time tools for Typfolio templates. Build-time template checks, a PDF structure inspector with checks for the structure a screen reader needs, and a panel that shows a PDF's tags in the page while you work.
|
|
3
|
+
Dev-time tools for Typfolio templates. Build-time template checks, a PDF structure inspector with checks for the structure a screen reader needs, PDF/UA and PDF/A validation with veraPDF, and a panel that shows a PDF's tags in the page while you work.
|
|
4
4
|
|
|
5
5
|
Install it as a devDependency. Nothing here is needed at runtime: `@typfolio/core` never imports this package, so none of it reaches a production bundle.
|
|
6
6
|
|
|
@@ -56,12 +56,12 @@ const report = await inspectPdf(bytes); // the bytes of a compiled PDF
|
|
|
56
56
|
// report.headings: [{ level, text }] in document order
|
|
57
57
|
// report.figures: [{ alt? }], report.tables, report.fonts: [{ name, embedded }]
|
|
58
58
|
// report.structureRoles: { H1: 1, Table: 1, ... } how often each structure role occurs
|
|
59
|
-
// report.structure: [{ page, elements: [{ role, text, alt?, lang?, children }] }] the tags of each page
|
|
59
|
+
// report.structure: [{ page, elements: [{ role, text, alt?, lang?, summary?, scope?, id?, headers?, children }] }] the tags of each page
|
|
60
60
|
```
|
|
61
61
|
|
|
62
|
-
`inspectPdf` reports facts about the file so a test can assert on them. It never says a file conforms to anything: a tagged PDF with PDF/UA metadata, a title, a language and alt text can still fail PDF/UA. Use a validator such as veraPDF for conformance.
|
|
62
|
+
`inspectPdf` reports facts about the file so a test can assert on them. It never says a file conforms to anything: a tagged PDF with PDF/UA metadata, a title, a language and alt text can still fail PDF/UA. Use a validator such as veraPDF for conformance; [`@typfolio/dev-tools/validate`](#validation-with-verapdf) runs it.
|
|
63
63
|
|
|
64
|
-
`structure` is the structure tree as a screen reader gets it: each page's elements in reading order, with the text drawn in them, a figure's alt text and the language an element sets. Text an artifact draws (a running header, a page number) belongs to no element.
|
|
64
|
+
`structure` is the structure tree as a screen reader gets it: each page's elements in reading order, with the text drawn in them, a figure's alt text and the language an element sets. A table carries what Typst wrote for it: the table's `summary` (`pdf.table-summary`), a header cell's `scope` (`Row`, `Column` or `Both`) and `id`, and on each cell `headers`, the ids of the header cells that label it. A row header made with `pdf.header-cell(scope: "row")` is a `TH` with scope `Row`, and the cells of its row name it in `headers`. Text an artifact draws (a running header, a page number) belongs to no element.
|
|
65
65
|
|
|
66
66
|
`inspectPdf` and `checkStructure` read the file with [`pdfjs-dist`](https://www.npmjs.com/package/pdfjs-dist), an **optional peer dependency** (`^6.3.0`) that you install yourself when you use this entry. It is loaded on the first call and only from `@typfolio/dev-tools/pdf`: the main entry never imports it. Without it, the call rejects with a `TypstPdfError` (`INITIALIZATION`) that says to install `pdfjs-dist`; bytes that are not a readable PDF reject with `INVALID_REQUEST`. Counts are per page (an element that continues over a page break is counted for each page), see "Inspecting the output" in [docs/template-authoring.md](../../docs/template-authoring.md) for this and the other limits.
|
|
67
67
|
|
|
@@ -90,9 +90,58 @@ await checkStructure(bytes); // the same, and one `untagged` warning for a PDF t
|
|
|
90
90
|
|
|
91
91
|
`readStructure(document)` reads the same pages from a pdf.js document (`PDFDocumentProxy`) you already have, such as one a browser page loaded with its own pdf.js build, so a page can show the tags and their warnings without this package loading pdf.js.
|
|
92
92
|
|
|
93
|
+
## Validation with veraPDF
|
|
94
|
+
|
|
95
|
+
`@typfolio/dev-tools/validate` validates a PDF against PDF/UA or PDF/A with [veraPDF](https://verapdf.org/), compiled to WebAssembly: no Java, in Node and in a browser.
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
import { formatValidationReport, validatePdf } from '@typfolio/dev-tools/validate'; // needs @typfolio/verapdf-wasm
|
|
99
|
+
|
|
100
|
+
const report = await validatePdf(result.bytes, { flavour: 'ua1' });
|
|
101
|
+
// report.compliant: whether the file passes every rule of the flavour
|
|
102
|
+
// report.totalAssertions: how many checks were run
|
|
103
|
+
// report.profile: { name, description, rules } the validation profile that was applied
|
|
104
|
+
// report.failedRules: [{ specification, clause, test, failedChecks, message, tags, object, condition, checks, context }], ordered by clause
|
|
105
|
+
// message: what the standard requires; tags: veraPDF's topics, such as ['structure', 'table']
|
|
106
|
+
// checks: [{ error, context }] each failed check: what was wrong, with the values found, and where
|
|
107
|
+
// report.logs: [{ level, message, occurrences }] what veraPDF logged while reading the file
|
|
108
|
+
assert.ok(report.compliant, formatValidationReport(report));
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
- `validatePdf(bytes, { flavour, wasm? })` starts a validator on the first call and keeps it. In Node it reads the binary from the installed package; a browser passes `wasm`, the bytes of `@typfolio/verapdf-wasm/verapdf.wasm` (about 31 MB, 10 MB gzipped) or a compiled `WebAssembly.Module`.
|
|
112
|
+
- `createPdfValidator({ wasm? })` gives a validator of your own, whose `validate(bytes, { flavour })` is synchronous: for many files, or to run in a worker. The first validation takes about 0.3 s, later ones tens of milliseconds for a few pages.
|
|
113
|
+
- `validateDeclaredPdf(bytes)` validates against every standard the file declares in its metadata (`pdfuaid:part`, `pdfaid:part` with `pdfaid:conformance`) and returns one report for each, in an array: for files you did not produce, or a folder of mixed outputs. A file that declares nothing gives an empty array, which is not a pass, so check the length. For a test that a template produces a given standard, name the flavour with `validatePdf`: this only checks what the file claims. A validator's `detectFlavours(bytes)` returns the declared ids alone.
|
|
114
|
+
- `flavour` is one of veraPDF's ids: `ua1`, `ua2`, `1a`, `1b`, `2a`, `2b`, `2u`, `3a`, `3b`, `3u`, `4`, `4e`, `4f`, `wt1a`, `wt1r`. `pdfValidationFlavours` names each (`'PDF/UA-1'`) and `pdfValidationFlavourIds` lists them. `validatePdf` does not read the flavour from the file: say which standard you compiled for.
|
|
115
|
+
- A rule that fails often lists its first 20 checks; `maxChecksPerRule` (1 to 10000) changes that, and `failedChecks` is exact either way. A check's `error` is veraPDF's own sentence with the values it found, such as `The "part" property of the PDF/UA Identification Schema is 1 instead of 2`. Its `context` is a path in veraPDF's model of the file, with PDF object numbers (`…/pages[0](14 0 obj PDPage)/…`); for a glyph it contains a number that changes from run to run.
|
|
116
|
+
- `logs` is what veraPDF logged at `WARNING` or `SEVERE` while it read the file, such as a font program or a content stream it could not parse. A file can pass with messages there: veraPDF then validated what it could read, so for a strict test require `report.compliant && report.logs.length === 0`.
|
|
117
|
+
- `formatValidationReport(report, name?)` is the report as text: each failed rule, under it the checks that are listed, and veraPDF's messages.
|
|
118
|
+
- Errors are `TypstPdfError`s: `INITIALIZATION` when `@typfolio/verapdf-wasm` is not installed or its binary cannot be started, `INVALID_REQUEST` for a flavour that does not exist, for bytes veraPDF cannot read as a PDF, and in a browser when no `wasm` is given.
|
|
119
|
+
|
|
120
|
+
`typfolio-validate` does the same from a shell or a CI step:
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
npx typfolio-validate --flavour ua1 out/report.pdf out/letter.pdf
|
|
124
|
+
# out/report.pdf: PASS PDF/UA-1 (734 checks)
|
|
125
|
+
# out/letter.pdf: FAIL PDF/UA-1: 2 rules, 2 of 730 checks
|
|
126
|
+
# ISO 14289-1:2014 5, test 1 (1x) [metadata]: The PDF/UA version and conformance level of a file shall be specified using the PDF/UA Identification extension schema
|
|
127
|
+
# The document metadata stream doesn't contain PDF/UA Identification Schema
|
|
128
|
+
# at root/document[0]/metadata[0](45 0 obj PDMetadata)/XMPPackage[0]
|
|
129
|
+
# ISO 14289-1:2014 7.1, test 10 (1x) [syntax]: The document catalog dictionary shall include a ViewerPreferences dictionary containing a DisplayDocTitle key, whose value shall be true
|
|
130
|
+
# ViewerPreferences dictionary is not present in the document Catalog, or DisplayDocTitle key is set to false or is not present in the ViewerPreferences dictionary (ViewerPreferences = dictionary(size = 1), DisplayDocTitle = null)
|
|
131
|
+
# at root
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`--flavour` (`-f`) defaults to `ua1`; `--flavour auto` validates each file against every standard it declares, and reports a file that declares none as not validated (status 2). Further, `--format json` prints the reports as JSON, `--max-checks <n>` sets how many failed checks of one rule are listed (3 as text, 20 as JSON), and `--wasm <file>` names another binary. It exits with 0 when every file passes, 1 when one fails, and 2 for wrong usage or a file that could not be validated.
|
|
135
|
+
|
|
136
|
+
What a pass means: the file meets the rules of that standard that a machine can check, as veraPDF implements them. It does not show that the document is accessible. Whether the tags fit the content, the reading order makes sense and the alternative text says what the figure shows still needs a person, and `structureWarnings` above catches some of what the standard accepts.
|
|
137
|
+
|
|
138
|
+
`@typfolio/verapdf-wasm` is an **optional peer dependency** that you install yourself, loaded on the first call and only from this entry. It is a package of its own because its binary is not open source as a whole: it contains veraPDF (MPL 2.0) and a runtime under Oracle's GraalVM Free Terms and Conditions, which allow use, also inside a company, and free redistribution, but not shipping it as part of something a fee is charged for. Nothing in `@typfolio/dev-tools` contains it. Install it beside dev-tools: `npm install --save-dev @typfolio/verapdf-wasm`.
|
|
139
|
+
|
|
93
140
|
## Structure panel
|
|
94
141
|
|
|
95
|
-
`@typfolio/dev-tools/panel` shows a PDF's tags in the page while you work on a template: each page's tags in reading order, the warnings above with a link to the tag each is about, and
|
|
142
|
+
`@typfolio/dev-tools/panel` shows a PDF's tags in the page while you work on a template: each page's tags in reading order, the warnings above with a link to the tag each is about, and, under the row of the tag you select, what the row does not say: its path in the tree, a figure's alt text, a table's columns and summary, a header cell's scope, the header cells that label a cell (by their text), and what it holds.
|
|
143
|
+
|
|
144
|
+
Beside the tags the panel draws the page with the page's pdf.js and marks the selected tag on it; moving over the page marks the tag under the pointer, and a click selects it in the list. The mark covers what the tag holds, which is its text or a figure's own box: a cell's border and padding belong to no tag, so they are not covered, and an empty cell has nothing to mark. The box of text is estimated from its font size and fits upright Latin text. The "Page" button in the toolbar hides the page. A row shows one line of its tag's text, cut short; the selected tag's row shows all of it. A tag's row shows a "Copy" button while the pointer or focus is on it, which copies the tag's whole text (a figure's alt text). In `mountStructureDevtools`, the toolbar's "Fill the page" button puts the panel over the whole page, for room to read the page view, and back. The lines between the tags, the page and, with a validator, veraPDF's findings can be dragged to give each more or less room (or moved with the arrow keys when focused); a double click puts one back. The page is a second drawing of the PDF, apart from any preview your application shows. It is written in React and ships with React bundled in (about 75 kB gzipped), so a page needs no React of its own, and in a React page it runs apart from the page's React. It loads no pdf.js: pass the one your page uses, with its worker set up.
|
|
96
145
|
|
|
97
146
|
```ts
|
|
98
147
|
import * as pdfjs from 'pdfjs-dist';
|
|
@@ -109,6 +158,20 @@ devtools.unmount();
|
|
|
109
158
|
- `mountStructurePanel(element, options)` shows the panel inside an element of yours instead, such as a tab beside a PDF preview. Give the element a height.
|
|
110
159
|
- Both take `pdfjs`, `bytes` (absent until there is a PDF) and `theme` (`'system'`, the default, `'light'` or `'dark'`), and return `update(options)`, which changes the options given, and `unmount()`. Options they cannot use throw `INVALID_REQUEST`. The panel gives pdf.js a copy of the bytes and frees each document once it is read; a new PDF replaces the one being read.
|
|
111
160
|
|
|
161
|
+
Both also take `validator`, which gives the panel a third view beside the tags and the page: veraPDF's findings. It has what to validate against, a "Validate" button, and the verdict with every failed rule: its clause, what the standard requires and veraPDF's topics for it, and, when opened, each failed check with what was wrong and where. Each new PDF is validated the same way as the last, so the verdict follows the template you are editing. For a PDF whose tags cannot be shown (an untagged one), the findings have the panel to themselves.
|
|
162
|
+
|
|
163
|
+
With a validator that has `detectFlavours`, as `createPdfValidator`'s has, the panel validates without being asked: every PDF is validated against each standard its metadata names, as soon as it is on show, and a PDF that names none says so instead of passing. Pick a standard and use the button to validate against that one instead. A devtools panel that is closed validates nothing; the PDF on show is validated when it opens. With a validator that cannot detect, nothing is validated until the button is used. The panel loads no validator itself: pass what `createPdfValidator` gives, or an object of your own whose `validate(bytes, { flavour })` (and `detectFlavours(bytes)`) forward to one in a worker and return promises. Validation is synchronous in `createPdfValidator`'s validator: about 0.3 s for the first PDF and tens of milliseconds after that for a few pages, on the page's own thread.
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
import { createPdfValidator } from '@typfolio/dev-tools/validate';
|
|
167
|
+
import wasmUrl from '@typfolio/verapdf-wasm/verapdf.wasm?url';
|
|
168
|
+
|
|
169
|
+
const validator = await createPdfValidator({ wasm: await (await fetch(wasmUrl)).arrayBuffer() });
|
|
170
|
+
const devtools = mountStructureDevtools({ pdfjs, validator });
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
A failed check is shown with veraPDF's own path to the object (`root/document[0]/StructTreeRoot[0]/…`); it is not linked to a tag in the list, because that path and the tags pdf.js reads do not line up one to one.
|
|
174
|
+
|
|
112
175
|
Load it only in development, so that neither it nor pdf.js reaches a production bundle: behind `import.meta.env.DEV` (or your bundler's flag), with dynamic `import()`s. [`examples/vite-react/src/structureDevtools.ts`](../../examples/vite-react/src/structureDevtools.ts) does this for `usePdf`'s `result?.bytes`.
|
|
113
176
|
|
|
114
177
|
What it shows is what `structureWarnings` and `readStructure` give, read the same way pdf.js gives it to a screen reader. pdf.js gives each page its own part of the tree, so a table over a page break shows on each page it is on, and the later parts say "Continued from page N" and are counted once. pdf.js also lists every row of a table on each of its pages, so a run of rows drawn on another page shows as one line. Which tags are open, the selection and the filter are kept by position, so they stay across a recompile of the same template. The panel has the warnings' limits: no problems found is not a verdict.
|
package/dist/panel.d.ts
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
import type { PdfStructureSource } from './structure.js';
|
|
2
|
+
import type { PdfValidationFlavour, PdfValidationReport } from './validation.js';
|
|
2
3
|
/**
|
|
3
4
|
* The part of pdf.js the panel uses: the module the page imports (`import * as pdfjs from 'pdfjs-dist'`), with its
|
|
4
|
-
* worker set up (`GlobalWorkerOptions.workerSrc`). The panel opens each PDF with it
|
|
5
|
+
* worker set up (`GlobalWorkerOptions.workerSrc`). The panel opens each PDF with it, keeps it open
|
|
6
|
+
* while it is the PDF on show so the page view can draw its pages, and frees it when another takes its place or the
|
|
7
|
+
* panel is removed.
|
|
5
8
|
*/
|
|
6
9
|
export interface StructurePanelPdfJs {
|
|
7
10
|
getDocument(source: {
|
|
@@ -17,8 +20,29 @@ export interface StructurePanelPdfJs {
|
|
|
17
20
|
destroy(): Promise<void>;
|
|
18
21
|
};
|
|
19
22
|
}
|
|
23
|
+
/**
|
|
24
|
+
* A veraPDF validator for the panel's "veraPDF" view: what `createPdfValidator` of `@typfolio/dev-tools/validate`
|
|
25
|
+
* or `createValidator` of `@typfolio/verapdf-wasm` gives, or an object of your own that forwards to one in a worker
|
|
26
|
+
* and returns a promise. The panel loads no validator itself.
|
|
27
|
+
*/
|
|
28
|
+
export interface StructurePanelValidator {
|
|
29
|
+
validate(pdf: Uint8Array, options: {
|
|
30
|
+
flavour: PdfValidationFlavour;
|
|
31
|
+
maxChecksPerRule?: number;
|
|
32
|
+
}): PdfValidationReport | Promise<PdfValidationReport>;
|
|
33
|
+
/**
|
|
34
|
+
* The flavours the file declares. With it, the panel validates each PDF against those without being asked, while
|
|
35
|
+
* it is open.
|
|
36
|
+
*/
|
|
37
|
+
detectFlavours?(pdf: Uint8Array): PdfValidationFlavour[] | Promise<PdfValidationFlavour[]>;
|
|
38
|
+
}
|
|
20
39
|
export interface StructurePanelOptions {
|
|
21
40
|
readonly pdfjs: StructurePanelPdfJs;
|
|
41
|
+
/**
|
|
42
|
+
* Adds veraPDF's findings as a view beside the tags and the page, which validates the PDF on show. Without it the
|
|
43
|
+
* panel shows the tags and the page only.
|
|
44
|
+
*/
|
|
45
|
+
readonly validator?: StructurePanelValidator;
|
|
22
46
|
/**
|
|
23
47
|
* The PDF to show, such as `usePdf`'s `result?.bytes`; absent until there is one. Each new one is read in place of
|
|
24
48
|
* the last, which stays on show until it is; the bytes themselves are left as they are.
|