@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 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 structure inspector.
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 compiled
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
- `check` also takes `assets`, the files a template reads besides its input (shared settings, a logo), exactly as a request's `assets`: a template that reads `json("/export-settings.json")` can be checked with that file in place.
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
- `checkTemplate(template, { wasm, fonts, modes?, pdf?, assets? })` is the one-shot form that creates and disposes a checker.
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` also takes a template made with `defineTemplate`: it compiles only the files the template declares, with each input's JSON Schema at its path, so a file the template imports without declaring it fails, with what to do.
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
- `inputSchemaFiles(definitions, { toJSONSchema? })` returns the JSON Schema file of every input of these templates, partials or `defineInput(...)` results, 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' })`.
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
- for (const [path, text] of Object.entries(inputSchemaFiles([headerInput, outcomesInput]))) {
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 in `template.files`. 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.
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
- It reads 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.
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 CompilerOptions, type Diagnostic, type PartialDefinition, type PdfOptions, type PdfTemplate, type StandardSchemaV1, type TemplateDefinition, type TemplateInput } from '@typfolio/core';
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
- type Definition = TemplateDefinition<unknown, unknown> | PartialDefinition | TemplateInput;
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
- * `defineInput(...)` results, by its path, such as `common/header.schema.json`, as JSON text. Write
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 a request's `pdf`. */
29
+ /** Same options as `compile`'s `pdf`. */
24
30
  pdf?: PdfOptions;
25
31
  /**
26
- * Files the template reads besides its input, such as shared settings or a logo: same as a
27
- * request's `assets`. For a template made with `defineTemplate`, a schema file given here is used
28
- * as it is instead of one made from the input's schema.
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
- assets?: Readonly<Record<string, Uint8Array>>;
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
- /** Warnings when `ok`; the compile errors otherwise. */
47
+ /** The compile's warnings when it compiled; its errors otherwise. */
36
48
  diagnostics: readonly Diagnostic[];
37
- /** The `COMPILATION` error of a failed mode. */
49
+ /** The `COMPILATION` error of a mode that did not compile. */
38
50
  error?: TypstPdfError;
39
- /** The PDF of a successful mode. Held in memory only; nothing is written anywhere. */
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 compiled. */
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 schema
50
- * from `template.files` (at the path its `json.with(...)` names, relative to the file that writes it)
51
- * and builds the sample. A template made with `defineTemplate` is compiled from the files it
52
- * declares only, with each input's JSON Schema at its path (see `inputSchemaFiles`): a file it
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: PdfTemplate | TemplateDefinition<unknown, unknown>, options?: TemplateCheckOptions): Promise<TemplateCheckReport>;
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: PdfTemplate | TemplateDefinition<unknown, unknown>, options: CompilerOptions & TemplateCheckOptions): Promise<TemplateCheckReport>;
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 inputs, nested partials included, once per path.
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
- visit(partial.input);
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?.path === 'string') {
28
- const input = definition;
29
- add(input.path.replace(/^\/+/, ''), input.schema);
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 a defineInput(...)');
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
- * `defineInput(...)` results, by its path, such as `common/header.schema.json`, as JSON text. Write
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
- return { modes, pdf, assets, ...(toJSONSchema === undefined ? {} : { toJSONSchema }) };
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 defined template as the editor sees it: its declared files, and each input's JSON Schema at its path.
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
- return { template, input: null, pdf, ...(assets === undefined ? {} : { assets }) };
86
- const encoder = new TextEncoder();
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 (assets?.[path] !== undefined)
93
+ if (given.has(path))
90
94
  continue;
91
95
  if (schema === undefined) {
92
- throw new TypstPdfError('INVALID_REQUEST', `The input at ${path} has no schema: give its JSON Schema file in assets`);
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] = encoder.encode(JSON.stringify(jsonSchemaOf(schema, path, options)));
98
+ schemas[path] = jsonSchemaOf(schema, path, options);
95
99
  }
96
- return { template: { entrypoint: template.entrypoint, files: template.files }, input: null, pdf, assets: { ...assets, ...schemas } };
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
- const compiled = engine.compile(prepared, { mounts, inputs: [['typfolio-sample', mode]] });
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
  }
@@ -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>;