@typfolio/dev-tools 0.3.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,8 +10,8 @@ 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
  }
@@ -21,7 +21,16 @@ try {
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
- `checkTemplate(template, { wasm, fonts, modes?, pdf?, assets? })` is the one-shot form that creates and disposes a checker.
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
+
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.
25
34
 
26
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
 
@@ -47,10 +56,63 @@ const report = await inspectPdf(bytes); // the bytes of a compiled PDF
47
56
  // report.headings: [{ level, text }] in document order
48
57
  // report.figures: [{ alt? }], report.tables, report.fonts: [{ name, embedded }]
49
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
50
60
  ```
51
61
 
52
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.
53
63
 
54
- 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.
55
117
 
56
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
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 {
@@ -32,19 +33,28 @@ export interface TemplateCheckOptions extends JSONSchemaOptions {
32
33
  * file given here at a data path is used as it is, instead of one made from the schema.
33
34
  */
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.
40
+ */
41
+ structure?: (bytes: Uint8Array) => Promise<readonly PdfStructureWarning[]>;
35
42
  }
36
43
  export interface TemplateCheckResult {
37
44
  mode: SampleMode;
45
+ /** The mode compiled and, with `structure`, its PDF has no structure warnings. */
38
46
  ok: boolean;
39
- /** Warnings when `ok`; the compile errors otherwise. */
47
+ /** The compile's warnings when it compiled; its errors otherwise. */
40
48
  diagnostics: readonly Diagnostic[];
41
- /** The `COMPILATION` error of a failed mode. */
49
+ /** The `COMPILATION` error of a mode that did not compile. */
42
50
  error?: TypstPdfError;
43
- /** 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. */
44
52
  bytes?: Uint8Array;
53
+ /** With `structure`: what it found in the PDF of a mode that compiled. */
54
+ structure?: readonly PdfStructureWarning[];
45
55
  }
46
56
  export interface TemplateCheckReport {
47
- /** True only if every requested mode compiled. */
57
+ /** True only if every requested mode is `ok`. */
48
58
  ok: boolean;
49
59
  results: TemplateCheckResult[];
50
60
  }
package/dist/index.js CHANGED
@@ -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,7 +76,10 @@ 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
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) {
@@ -120,7 +123,7 @@ export async function createTemplateChecker(options) {
120
123
  throw new TypstPdfError('DISPOSED', 'The template checker is disposed');
121
124
  if (busy)
122
125
  throw new TypstPdfError('BUSY', 'The template checker already has an active check');
123
- const { modes, ...rest } = parseOptions(checkOptions);
126
+ const { modes, structure, ...rest } = parseOptions(checkOptions);
124
127
  const prepared = prepareRequest(editorRequest(template, rest));
125
128
  busy = true;
126
129
  let release;
@@ -129,16 +132,25 @@ export async function createTemplateChecker(options) {
129
132
  const results = [];
130
133
  for (const mode of modes) {
131
134
  await Promise.resolve();
135
+ let compiled;
132
136
  try {
133
- const compiled = engine.compile(prepared, { mounts, inputs: [['typfolio-sample', mode]] });
134
- results.push({ mode, ok: true, diagnostics: compiled.diagnostics, bytes: compiled.bytes });
137
+ compiled = engine.compile(prepared, { mounts, inputs: [['typfolio-sample', mode]] });
135
138
  }
136
139
  catch (error) {
137
140
  if (!(error instanceof TypstPdfError) || error.code !== 'COMPILATION')
138
141
  throw error;
139
142
  const explained = explainCompileError(error, prepared.files);
140
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;
141
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 });
142
154
  }
143
155
  return { ok: results.every(result => result.ok), results };
144
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>;