@typfolio/dev-tools 0.2.0 → 0.4.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 +73 -10
- package/THIRD_PARTY_NOTICES.md +35 -0
- package/dist/index.d.ts +32 -19
- package/dist/index.js +38 -20
- package/dist/panel.d.ts +54 -0
- package/dist/panel.js +316 -0
- package/dist/pdf.d.ts +14 -3
- package/dist/pdf.js +57 -90
- package/dist/structure.d.ts +94 -0
- package/dist/structure.js +177 -0
- package/package.json +9 -7
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 and a PDF
|
|
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.
|
|
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
|
|
|
@@ -10,30 +10,40 @@ import { createTemplateChecker } from '@typfolio/dev-tools';
|
|
|
10
10
|
const checker = await createTemplateChecker({ wasm, fonts }); // the options of createCompiler
|
|
11
11
|
try {
|
|
12
12
|
const report = await checker.check(template, { modes: ['minimal', 'full'], pdf: { standards: ['ua-1'] } });
|
|
13
|
-
// report.ok: true only if every mode
|
|
14
|
-
// report.results: { mode, ok, diagnostics, error?, bytes? } per mode
|
|
13
|
+
// report.ok: true only if every mode is ok
|
|
14
|
+
// report.results: { mode, ok, diagnostics, error?, bytes?, structure? } per mode
|
|
15
15
|
} finally {
|
|
16
16
|
await checker.dispose();
|
|
17
17
|
}
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
`
|
|
20
|
+
`template` is a template made with `defineTemplate`. The check compiles only the files it declares, with each piece of data's JSON Schema at its `schemaPath`, made from its schema, so a file the template imports without declaring it fails, with what to do.
|
|
21
21
|
|
|
22
|
-
`
|
|
22
|
+
`check` also takes `assets`, the files a template reads besides its data (a logo), exactly as `compile`'s `assets`. A JSON Schema file given there at a data path is used as it is instead of one made from the schema: this is how data without a schema, or a schema without Standard JSON Schema, is checked.
|
|
23
23
|
|
|
24
|
-
`check`
|
|
24
|
+
`check` takes `structure`, a function that reads each compiled mode's PDF and returns warnings: a mode with any is not `ok`, and its result lists them in `structure`. Pass `checkStructure` from `@typfolio/dev-tools/pdf` (below), or wrap it to accept a warning. The main entry never loads pdf.js itself, so the function is passed in rather than switched on.
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
```ts
|
|
27
|
+
import { checkStructure } from '@typfolio/dev-tools/pdf'; // needs pdfjs-dist
|
|
28
|
+
|
|
29
|
+
const report = await checker.check(template, { pdf: { standards: ['ua-1'] }, structure: checkStructure });
|
|
30
|
+
// full: { ok: false, structure: [{ kind: 'table-without-headers', page: 1, message: 'The table starting "Sample text" has no header cells (TH), …' }] }
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`checkTemplate(template, { wasm, fonts, modes?, pdf?, assets?, structure? })` is the one-shot form that creates and disposes a checker.
|
|
34
|
+
|
|
35
|
+
`inputSchemaFiles(definitions, { toJSONSchema? })` returns the JSON Schema file of every piece of data these templates and partials read (nested partials included), or of `{ schema, schemaPath }` pairs, by path, as JSON text. It writes nothing: a script writes the files where the editor reads them, and a test compares them, so a schema that changed without its file fails CI. Schemas that implement Standard JSON Schema (`~standard.jsonSchema`, as Zod's do) need no option; for Zod Mini, pass `toJSONSchema: schema => z.toJSONSchema(schema, { io: 'input' })`.
|
|
27
36
|
|
|
28
37
|
```ts
|
|
29
38
|
import { inputSchemaFiles } from '@typfolio/dev-tools';
|
|
30
39
|
|
|
31
|
-
|
|
40
|
+
// Every template's own schema file and each of its partials', once per path.
|
|
41
|
+
for (const [path, text] of Object.entries(inputSchemaFiles([outcomes, results]))) {
|
|
32
42
|
assert.deepEqual(JSON.parse(await readFile(new URL(path, templatesRoot), 'utf8')), JSON.parse(text), `${path} is out of date`);
|
|
33
43
|
}
|
|
34
44
|
```
|
|
35
45
|
|
|
36
|
-
A check compiles the template once per sample mode (`minimal`, then `full`) the way an editor does, so `input()` builds a sample from the JSON Schema
|
|
46
|
+
A check compiles the template once per sample mode (`minimal`, then `full`) the way an editor does, so `input()` builds a sample from the JSON Schema at each data path. A compile error is reported in that mode's result; a malformed template or option is thrown. Nothing is written to disk. See "Build-time checks" in [docs/template-authoring.md](../../docs/template-authoring.md) for the rules and a test recipe.
|
|
37
47
|
|
|
38
48
|
## `inspectPdf`
|
|
39
49
|
|
|
@@ -46,10 +56,63 @@ const report = await inspectPdf(bytes); // the bytes of a compiled PDF
|
|
|
46
56
|
// report.headings: [{ level, text }] in document order
|
|
47
57
|
// report.figures: [{ alt? }], report.tables, report.fonts: [{ name, embedded }]
|
|
48
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
|
|
49
60
|
```
|
|
50
61
|
|
|
51
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.
|
|
52
63
|
|
|
53
|
-
|
|
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.
|
|
65
|
+
|
|
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
|
+
|
|
68
|
+
## Structure warnings
|
|
69
|
+
|
|
70
|
+
A PDF/UA-1 compile refuses some missing structure but accepts some that a screen reader user still needs. A validator such as veraPDF checks that the tags present are well formed, not that the content has the ones it needs. Checked against the pinned compiler (Typst 0.15.1):
|
|
71
|
+
|
|
72
|
+
| | PDF/UA-1 compile | Tagged compile (the default) | `structureWarnings` |
|
|
73
|
+
|---|---|---|---|
|
|
74
|
+
| Headings that skip a level, or start below H1 | refused | accepted | `heading-skips-level` |
|
|
75
|
+
| An image without alt text | refused | accepted | `figure-without-alt` |
|
|
76
|
+
| A table without header cells | accepted | accepted | `table-without-headers` |
|
|
77
|
+
| Several pages and no headings (titles drawn as large text) | accepted | accepted | `no-headings` |
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { checkStructure, inspectPdf, structureWarnings } from '@typfolio/dev-tools/pdf';
|
|
81
|
+
|
|
82
|
+
const warnings = structureWarnings((await inspectPdf(bytes)).structure);
|
|
83
|
+
// [{ kind: 'no-headings', message: '6 pages and no headings, so a screen reader user cannot move between sections.' }]
|
|
84
|
+
// [{ kind, page, element, message }] in reading order; element is the one in the pages given
|
|
85
|
+
|
|
86
|
+
await checkStructure(bytes); // the same, and one `untagged` warning for a PDF that is not tagged at all
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`structureWarnings(pages)` is a plain function of the pages and needs nothing installed. A table that runs over a page break is checked once, on the page it starts: pdf.js gives each page its own part of the tree, and the part that carries on has no header row unless the header repeats. Its limits: a new table that starts a page right after another table ended the previous one is taken for a continuation and not checked, and the warnings say nothing about reading order, wording or whether alt text describes anything. An empty list is not a verdict.
|
|
90
|
+
|
|
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
|
+
|
|
93
|
+
## Structure panel
|
|
94
|
+
|
|
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 the text, alt text and language of the tag you select. 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
|
+
|
|
97
|
+
```ts
|
|
98
|
+
import * as pdfjs from 'pdfjs-dist';
|
|
99
|
+
import workerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url';
|
|
100
|
+
import { mountStructureDevtools } from '@typfolio/dev-tools/panel';
|
|
101
|
+
|
|
102
|
+
pdfjs.GlobalWorkerOptions.workerSrc = workerSrc;
|
|
103
|
+
const devtools = mountStructureDevtools({ pdfjs }); // a button in a corner, with the number of problems found
|
|
104
|
+
devtools.update({ bytes: result.bytes }); // after each compile: the panel reads the new PDF
|
|
105
|
+
devtools.unmount();
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- `mountStructureDevtools(options)` adds a button to a corner of the page (`buttonPosition`: `'bottom-right'`, the default, `'bottom-left'`, `'top-right'` or `'top-left'`) that opens the panel along a side of the page (`position`: `'bottom'`, the default, `'top'`, `'left'` or `'right'`), like React Query's devtools. The buttons in its toolbar move it to another side, and `update({ position })` does too. Drag its inner edge to resize it, or use the arrow keys on that edge; Escape closes it. `initialIsOpen: true` starts it open. The PDF is read while the panel is closed too, for the button's count.
|
|
109
|
+
- `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
|
+
- 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
|
+
|
|
112
|
+
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
|
+
|
|
114
|
+
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.
|
|
115
|
+
|
|
116
|
+
`dist/panel.js` carries React's production build; [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) has its licence.
|
|
54
117
|
|
|
55
118
|
The package builds on `@typfolio/core/internal`, which is unstable and meant only for Typfolio's own packages.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
`dist/panel.js` (the `@typfolio/dev-tools/panel` entry) bundles the production builds of the packages below, so a page can show the panel without React of its own. The rest of `@typfolio/dev-tools` bundles no third-party code.
|
|
4
|
+
|
|
5
|
+
| Package | Licence |
|
|
6
|
+
|---|---|
|
|
7
|
+
| [react](https://github.com/facebook/react) | MIT |
|
|
8
|
+
| [react-dom](https://github.com/facebook/react), which carries code derived from Modernizr (MIT) | MIT |
|
|
9
|
+
| [scheduler](https://github.com/facebook/react) | MIT |
|
|
10
|
+
|
|
11
|
+
All three are published from the React repository under this licence:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
MIT License
|
|
15
|
+
|
|
16
|
+
Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
17
|
+
|
|
18
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
19
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
20
|
+
in the Software without restriction, including without limitation the rights
|
|
21
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
22
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
23
|
+
furnished to do so, subject to the following conditions:
|
|
24
|
+
|
|
25
|
+
The above copyright notice and this permission notice shall be included in all
|
|
26
|
+
copies or substantial portions of the Software.
|
|
27
|
+
|
|
28
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
29
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
30
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
31
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
32
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
33
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
34
|
+
SOFTWARE.
|
|
35
|
+
```
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { TypstPdfError, type
|
|
1
|
+
import { TypstPdfError, type AnyTemplate, type Assets, type CompilerOptions, type Diagnostic, type PartialDefinition, type PdfOptions, type StandardSchemaV1 } from '@typfolio/core';
|
|
2
|
+
import type { PdfStructureWarning } from './pdf.js';
|
|
2
3
|
/** Which sample `@local/typfolio`'s `input()` builds: every property, or only what the schema requires. */
|
|
3
4
|
export type SampleMode = 'minimal' | 'full';
|
|
4
5
|
export interface JSONSchemaOptions {
|
|
@@ -8,10 +9,15 @@ export interface JSONSchemaOptions {
|
|
|
8
9
|
*/
|
|
9
10
|
toJSONSchema?(schema: StandardSchemaV1): unknown;
|
|
10
11
|
}
|
|
11
|
-
|
|
12
|
+
/** A schema and the path its Typst file reads the data from, for a script that cannot import the definitions. */
|
|
13
|
+
export interface SchemaFile {
|
|
14
|
+
readonly schema: StandardSchemaV1;
|
|
15
|
+
readonly schemaPath: string;
|
|
16
|
+
}
|
|
17
|
+
type Definition = AnyTemplate | PartialDefinition | SchemaFile;
|
|
12
18
|
/**
|
|
13
19
|
* The JSON Schema file of each input of these templates, partials (nested ones included) or
|
|
14
|
-
* `
|
|
20
|
+
* `{ schema, schemaPath }` pairs, by its path, such as `common/header.schema.json`, as JSON text. Write
|
|
15
21
|
* each next to the Typst files, where its `input(json.with("./header.schema.json"))` reads it in an
|
|
16
22
|
* editor for a sample, and in a test compare the parsed files with these to catch a schema that
|
|
17
23
|
* changed without its file. An input without a schema is left out. Nothing is written here.
|
|
@@ -20,45 +26,52 @@ export declare function inputSchemaFiles(definitions: Definition | readonly Defi
|
|
|
20
26
|
export interface TemplateCheckOptions extends JSONSchemaOptions {
|
|
21
27
|
/** Defaults to `['minimal', 'full']`. Each mode is a separate compile. */
|
|
22
28
|
modes?: readonly SampleMode[];
|
|
23
|
-
/** Same options as
|
|
29
|
+
/** Same options as `compile`'s `pdf`. */
|
|
24
30
|
pdf?: PdfOptions;
|
|
25
31
|
/**
|
|
26
|
-
* Files the template reads besides its
|
|
27
|
-
*
|
|
28
|
-
|
|
32
|
+
* Files the template reads besides its data, such as a logo: as `compile`'s `assets`. A JSON Schema
|
|
33
|
+
* file given here at a data path is used as it is, instead of one made from the schema.
|
|
34
|
+
*/
|
|
35
|
+
assets?: Assets;
|
|
36
|
+
/**
|
|
37
|
+
* Reads the PDF of each mode that compiled and fails the mode on any warning it returns: `checkStructure` from
|
|
38
|
+
* `@typfolio/dev-tools/pdf` (which needs pdfjs-dist), or a function of your own, such as one that filters its
|
|
39
|
+
* warnings. A function that rejects rejects the check.
|
|
29
40
|
*/
|
|
30
|
-
|
|
41
|
+
structure?: (bytes: Uint8Array) => Promise<readonly PdfStructureWarning[]>;
|
|
31
42
|
}
|
|
32
43
|
export interface TemplateCheckResult {
|
|
33
44
|
mode: SampleMode;
|
|
45
|
+
/** The mode compiled and, with `structure`, its PDF has no structure warnings. */
|
|
34
46
|
ok: boolean;
|
|
35
|
-
/**
|
|
47
|
+
/** The compile's warnings when it compiled; its errors otherwise. */
|
|
36
48
|
diagnostics: readonly Diagnostic[];
|
|
37
|
-
/** The `COMPILATION` error of a
|
|
49
|
+
/** The `COMPILATION` error of a mode that did not compile. */
|
|
38
50
|
error?: TypstPdfError;
|
|
39
|
-
/** The PDF of a
|
|
51
|
+
/** The PDF of a mode that compiled. Held in memory only; nothing is written anywhere. */
|
|
40
52
|
bytes?: Uint8Array;
|
|
53
|
+
/** With `structure`: what it found in the PDF of a mode that compiled. */
|
|
54
|
+
structure?: readonly PdfStructureWarning[];
|
|
41
55
|
}
|
|
42
56
|
export interface TemplateCheckReport {
|
|
43
|
-
/** True only if every requested mode
|
|
57
|
+
/** True only if every requested mode is `ok`. */
|
|
44
58
|
ok: boolean;
|
|
45
59
|
results: TemplateCheckResult[];
|
|
46
60
|
}
|
|
47
61
|
export interface TemplateChecker {
|
|
48
62
|
/**
|
|
49
|
-
* Compiles `template` once per mode in editor mode: no runtime marker, so `input()` reads the
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
* imports without declaring it fails, with what to do. A failed compile is reported in its result;
|
|
63
|
+
* Compiles `template` once per mode in editor mode: no runtime marker, so `input()` reads the JSON
|
|
64
|
+
* Schema at each data path (made from the schema, see `inputSchemaFiles`, or given in `assets`) and
|
|
65
|
+
* builds the sample. The template is compiled from the files it declares only: a file it imports
|
|
66
|
+
* without declaring it fails, with what to do. A failed compile is reported in its result;
|
|
54
67
|
* a malformed template or option rejects with `INVALID_REQUEST` or `UNSUPPORTED_OPTION`.
|
|
55
68
|
*/
|
|
56
|
-
check(template:
|
|
69
|
+
check(template: AnyTemplate, options?: TemplateCheckOptions): Promise<TemplateCheckReport>;
|
|
57
70
|
/** Stops accepting checks; waits for an accepted one and frees the compiler. */
|
|
58
71
|
dispose(): Promise<void>;
|
|
59
72
|
}
|
|
60
73
|
/** Same options as `createCompiler`. One active check per checker. */
|
|
61
74
|
export declare function createTemplateChecker(options: CompilerOptions): Promise<TemplateChecker>;
|
|
62
75
|
/** One-shot form of `createTemplateChecker`: creates a checker, runs one check, disposes it. */
|
|
63
|
-
export declare function checkTemplate(template:
|
|
76
|
+
export declare function checkTemplate(template: AnyTemplate, options: CompilerOptions & TemplateCheckOptions): Promise<TemplateCheckReport>;
|
|
64
77
|
export {};
|
package/dist/index.js
CHANGED
|
@@ -4,7 +4,7 @@ import { TypstPdfError, } from '@typfolio/core';
|
|
|
4
4
|
import { bundledPackageDirectory, createEngine, explainCompileError, initialize, isTemplateDefinition, packageFileMounts, prepareRequest, resolveFonts, } from '@typfolio/core/internal';
|
|
5
5
|
import { sampleFile, sampleSource } from './sample-source.generated.js';
|
|
6
6
|
const sampleModes = ['minimal', 'full'];
|
|
7
|
-
// Each input of these templates, partials and
|
|
7
|
+
// Each input of these templates, partials and schema files, nested partials included, once per path.
|
|
8
8
|
function inputsOf(definitions) {
|
|
9
9
|
const found = new Map();
|
|
10
10
|
const add = (path, schema) => {
|
|
@@ -20,16 +20,16 @@ function inputsOf(definitions) {
|
|
|
20
20
|
}
|
|
21
21
|
else if (definition?.kind === 'typfolio-partial') {
|
|
22
22
|
const partial = definition;
|
|
23
|
-
|
|
23
|
+
add(partial.schemaPath, partial.schema);
|
|
24
24
|
for (const nested of Object.values(partial.partials))
|
|
25
25
|
visit(nested);
|
|
26
26
|
}
|
|
27
|
-
else if (typeof definition?.
|
|
28
|
-
const
|
|
29
|
-
add(
|
|
27
|
+
else if (typeof definition?.schemaPath === 'string') {
|
|
28
|
+
const file = definition;
|
|
29
|
+
add(file.schemaPath.replace(/^\/+/, ''), file.schema);
|
|
30
30
|
}
|
|
31
31
|
else {
|
|
32
|
-
throw new TypstPdfError('INVALID_REQUEST', 'Expected a defineTemplate(...), a definePartial(...) or
|
|
32
|
+
throw new TypstPdfError('INVALID_REQUEST', 'Expected a defineTemplate(...), a definePartial(...) or { schema, schemaPath }');
|
|
33
33
|
}
|
|
34
34
|
};
|
|
35
35
|
for (const definition of definitions)
|
|
@@ -46,7 +46,7 @@ function jsonSchemaOf(schema, path, options) {
|
|
|
46
46
|
}
|
|
47
47
|
/**
|
|
48
48
|
* The JSON Schema file of each input of these templates, partials (nested ones included) or
|
|
49
|
-
* `
|
|
49
|
+
* `{ schema, schemaPath }` pairs, by its path, such as `common/header.schema.json`, as JSON text. Write
|
|
50
50
|
* each next to the Typst files, where its `input(json.with("./header.schema.json"))` reads it in an
|
|
51
51
|
* editor for a sample, and in a test compare the parsed files with these to catch a schema that
|
|
52
52
|
* changed without its file. An input without a schema is left out. Nothing is written here.
|
|
@@ -64,7 +64,7 @@ function parseOptions(options) {
|
|
|
64
64
|
return { modes: sampleModes };
|
|
65
65
|
if (!options || typeof options !== 'object' || Array.isArray(options))
|
|
66
66
|
throw new TypstPdfError('INVALID_REQUEST', 'check options must be a plain object');
|
|
67
|
-
const { modes = sampleModes, pdf, assets, toJSONSchema, ...rest } = options;
|
|
67
|
+
const { modes = sampleModes, pdf, assets, toJSONSchema, structure, ...rest } = options;
|
|
68
68
|
for (const key of Object.keys(rest))
|
|
69
69
|
throw new TypstPdfError('UNSUPPORTED_OPTION', `Unsupported check option ${key}`);
|
|
70
70
|
if (!Array.isArray(modes) || !modes.length)
|
|
@@ -76,24 +76,34 @@ function parseOptions(options) {
|
|
|
76
76
|
throw new TypstPdfError('INVALID_REQUEST', 'modes must not repeat');
|
|
77
77
|
if (toJSONSchema !== undefined && typeof toJSONSchema !== 'function')
|
|
78
78
|
throw new TypstPdfError('INVALID_REQUEST', 'toJSONSchema must be a function');
|
|
79
|
-
|
|
79
|
+
if (structure !== undefined && typeof structure !== 'function') {
|
|
80
|
+
throw new TypstPdfError('INVALID_REQUEST', 'structure must be a function that reads the PDF bytes, such as checkStructure from @typfolio/dev-tools/pdf');
|
|
81
|
+
}
|
|
82
|
+
return { modes, pdf, assets, structure, ...(toJSONSchema === undefined ? {} : { toJSONSchema }) };
|
|
80
83
|
}
|
|
81
|
-
// A
|
|
84
|
+
// A template as the editor sees it: its declared files, and each input's JSON Schema at the path its data is read.
|
|
82
85
|
function editorRequest(template, options) {
|
|
83
86
|
const { pdf, assets } = options;
|
|
84
87
|
if (!isTemplateDefinition(template))
|
|
85
|
-
|
|
86
|
-
|
|
88
|
+
throw new TypstPdfError('INVALID_REQUEST', 'check takes a template made with defineTemplate');
|
|
89
|
+
// A JSON Schema is JSON: mounted like data, where `input(json.with(...))` reads it in the editor branch.
|
|
87
90
|
const schemas = {};
|
|
91
|
+
const given = new Set(Object.keys(assets ?? {}).map(path => path.replace(/^\/+/, '')));
|
|
88
92
|
for (const [path, schema] of inputsOf([template])) {
|
|
89
|
-
if (
|
|
93
|
+
if (given.has(path))
|
|
90
94
|
continue;
|
|
91
95
|
if (schema === undefined) {
|
|
92
|
-
throw new TypstPdfError('INVALID_REQUEST', `The
|
|
96
|
+
throw new TypstPdfError('INVALID_REQUEST', `The data at ${path} has no schema: give its JSON Schema file in assets`);
|
|
93
97
|
}
|
|
94
|
-
schemas[path] =
|
|
98
|
+
schemas[path] = jsonSchemaOf(schema, path, options);
|
|
95
99
|
}
|
|
96
|
-
return {
|
|
100
|
+
return {
|
|
101
|
+
entrypoint: template.entrypoint,
|
|
102
|
+
files: template.files,
|
|
103
|
+
documents: schemas,
|
|
104
|
+
...(assets === undefined ? {} : { assets }),
|
|
105
|
+
...(pdf === undefined ? {} : { pdf }),
|
|
106
|
+
};
|
|
97
107
|
}
|
|
98
108
|
/** Same options as `createCompiler`. One active check per checker. */
|
|
99
109
|
export async function createTemplateChecker(options) {
|
|
@@ -113,8 +123,7 @@ export async function createTemplateChecker(options) {
|
|
|
113
123
|
throw new TypstPdfError('DISPOSED', 'The template checker is disposed');
|
|
114
124
|
if (busy)
|
|
115
125
|
throw new TypstPdfError('BUSY', 'The template checker already has an active check');
|
|
116
|
-
const { modes, ...rest } = parseOptions(checkOptions);
|
|
117
|
-
// `input: null` only fills the reserved /input.json; the editor branch never reads it.
|
|
126
|
+
const { modes, structure, ...rest } = parseOptions(checkOptions);
|
|
118
127
|
const prepared = prepareRequest(editorRequest(template, rest));
|
|
119
128
|
busy = true;
|
|
120
129
|
let release;
|
|
@@ -123,16 +132,25 @@ export async function createTemplateChecker(options) {
|
|
|
123
132
|
const results = [];
|
|
124
133
|
for (const mode of modes) {
|
|
125
134
|
await Promise.resolve();
|
|
135
|
+
let compiled;
|
|
126
136
|
try {
|
|
127
|
-
|
|
128
|
-
results.push({ mode, ok: true, diagnostics: compiled.diagnostics, bytes: compiled.bytes });
|
|
137
|
+
compiled = engine.compile(prepared, { mounts, inputs: [['typfolio-sample', mode]] });
|
|
129
138
|
}
|
|
130
139
|
catch (error) {
|
|
131
140
|
if (!(error instanceof TypstPdfError) || error.code !== 'COMPILATION')
|
|
132
141
|
throw error;
|
|
133
142
|
const explained = explainCompileError(error, prepared.files);
|
|
134
143
|
results.push({ mode, ok: false, diagnostics: explained.diagnostics, error: explained });
|
|
144
|
+
continue;
|
|
145
|
+
}
|
|
146
|
+
if (structure === undefined) {
|
|
147
|
+
results.push({ mode, ok: true, diagnostics: compiled.diagnostics, bytes: compiled.bytes });
|
|
148
|
+
continue;
|
|
135
149
|
}
|
|
150
|
+
const warnings = await structure(compiled.bytes);
|
|
151
|
+
if (!Array.isArray(warnings))
|
|
152
|
+
throw new TypstPdfError('INVALID_REQUEST', 'structure must resolve to an array of warnings');
|
|
153
|
+
results.push({ mode, ok: warnings.length === 0, diagnostics: compiled.diagnostics, bytes: compiled.bytes, structure: warnings });
|
|
136
154
|
}
|
|
137
155
|
return { ok: results.every(result => result.ok), results };
|
|
138
156
|
}
|
package/dist/panel.d.ts
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { PdfStructureSource } from './structure.js';
|
|
2
|
+
/**
|
|
3
|
+
* 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 and frees it once read.
|
|
5
|
+
*/
|
|
6
|
+
export interface StructurePanelPdfJs {
|
|
7
|
+
getDocument(source: {
|
|
8
|
+
data: Uint8Array;
|
|
9
|
+
verbosity?: number;
|
|
10
|
+
isEvalSupported?: boolean;
|
|
11
|
+
disableFontFace?: boolean;
|
|
12
|
+
useSystemFonts?: boolean;
|
|
13
|
+
}): {
|
|
14
|
+
promise: Promise<PdfStructureSource & {
|
|
15
|
+
getMarkInfo(): Promise<unknown>;
|
|
16
|
+
}>;
|
|
17
|
+
destroy(): Promise<void>;
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
export interface StructurePanelOptions {
|
|
21
|
+
readonly pdfjs: StructurePanelPdfJs;
|
|
22
|
+
/**
|
|
23
|
+
* The PDF to show, such as `usePdf`'s `result?.bytes`; absent until there is one. Each new one is read in place of
|
|
24
|
+
* the last, which stays on show until it is; the bytes themselves are left as they are.
|
|
25
|
+
*/
|
|
26
|
+
readonly bytes?: Uint8Array;
|
|
27
|
+
/** `'system'` follows the page's colour scheme preference. Defaults to `'system'`. */
|
|
28
|
+
readonly theme?: 'system' | 'light' | 'dark';
|
|
29
|
+
}
|
|
30
|
+
export interface StructureDevtoolsOptions extends StructurePanelOptions {
|
|
31
|
+
/** The side of the page the panel opens along. Its toolbar moves it to another. Defaults to `'bottom'`. */
|
|
32
|
+
readonly position?: 'bottom' | 'top' | 'left' | 'right';
|
|
33
|
+
/** The corner the button sits in. Defaults to `'bottom-right'`. */
|
|
34
|
+
readonly buttonPosition?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
|
|
35
|
+
/** Whether the panel starts open. Defaults to false. */
|
|
36
|
+
readonly initialIsOpen?: boolean;
|
|
37
|
+
}
|
|
38
|
+
export interface MountedStructurePanel<Options> {
|
|
39
|
+
/** Changes the options given, such as `{ bytes }` for a new PDF; the others stay as they are. */
|
|
40
|
+
update(options: Partial<Options>): void;
|
|
41
|
+
/** Removes the panel. Later calls of `update` and `unmount` do nothing. */
|
|
42
|
+
unmount(): void;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Shows the panel inside `element`, filling it: for a page of its own, or a tab beside a PDF preview. Give the element
|
|
46
|
+
* a height. Throws `INVALID_REQUEST` for options it cannot use.
|
|
47
|
+
*/
|
|
48
|
+
export declare function mountStructurePanel(element: Element, options: StructurePanelOptions): MountedStructurePanel<StructurePanelOptions>;
|
|
49
|
+
/**
|
|
50
|
+
* Adds a button to a corner of the page that opens the panel along a side of it, like a devtools panel; the button
|
|
51
|
+
* shows the number of problems found. The PDF is read while the panel is closed too. Throws `INVALID_REQUEST` for
|
|
52
|
+
* options it cannot use.
|
|
53
|
+
*/
|
|
54
|
+
export declare function mountStructureDevtools(options: StructureDevtoolsOptions): MountedStructurePanel<StructureDevtoolsOptions>;
|