@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 +67 -5
- package/THIRD_PARTY_NOTICES.md +35 -0
- package/dist/index.d.ts +14 -4
- package/dist/index.js +17 -5
- 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/dist/pdf.d.ts
CHANGED
|
@@ -1,3 +1,6 @@
|
|
|
1
|
+
import { type PdfStructurePage, type PdfStructureWarning } from './structure.js';
|
|
2
|
+
export { readStructure, structureWarnings } from './structure.js';
|
|
3
|
+
export type { PdfStructureElement, PdfStructurePage, PdfStructureSource, PdfStructureWarning, PdfStructureWarningKind } from './structure.js';
|
|
1
4
|
export interface PdfHeading {
|
|
2
5
|
/** 1 to 6 for `H1`..`H6`; 0 for a plain `H`. */
|
|
3
6
|
level: number;
|
|
@@ -43,14 +46,22 @@ export interface PdfInspection {
|
|
|
43
46
|
fonts: PdfFont[];
|
|
44
47
|
/** How often each structure role occurs, whatever it is. */
|
|
45
48
|
structureRoles: Record<string, number>;
|
|
49
|
+
/** Every page's part of the structure tree, in page order. */
|
|
50
|
+
structure: PdfStructurePage[];
|
|
46
51
|
}
|
|
47
52
|
/**
|
|
48
53
|
* Reads a compiled PDF and reports facts that matter for accessibility and output policy: tagging, title,
|
|
49
|
-
* language, the standards its XMP metadata declares, headings, figure alternative text,
|
|
50
|
-
* It reports facts only. A tagged PDF with PDF/UA metadata and all the right-looking structure
|
|
51
|
-
* conformant; use a validator such as veraPDF for that.
|
|
54
|
+
* language, the standards its XMP metadata declares, the structure tree, headings, figure alternative text,
|
|
55
|
+
* tables and fonts. It reports facts only. A tagged PDF with PDF/UA metadata and all the right-looking structure
|
|
56
|
+
* is not thereby conformant; use a validator such as veraPDF for that.
|
|
52
57
|
*
|
|
53
58
|
* Needs `pdfjs-dist` (an optional peer dependency); rejects with a `TypstPdfError` that says so if it is missing.
|
|
54
59
|
* Input that is not a readable PDF rejects with `INVALID_REQUEST`.
|
|
55
60
|
*/
|
|
56
61
|
export declare function inspectPdf(bytes: Uint8Array): Promise<PdfInspection>;
|
|
62
|
+
/**
|
|
63
|
+
* The PDF in `bytes`, read with pdf.js: one `untagged` warning when it is not tagged (`/MarkInfo /Marked`), else
|
|
64
|
+
* the `structureWarnings` of its pages. The function to pass as a template check's `structure` option. Needs
|
|
65
|
+
* `pdfjs-dist`, and rejects as `inspectPdf` does.
|
|
66
|
+
*/
|
|
67
|
+
export declare function checkStructure(bytes: Uint8Array): Promise<PdfStructureWarning[]>;
|
package/dist/pdf.js
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
// a file conforms to anything. `pdfjs-dist` is an optional peer dependency, loaded on the first call and only
|
|
3
3
|
// from this entry, so the main `@typfolio/dev-tools` entry (and every bundle that uses only that) never sees it.
|
|
4
4
|
import { TypstPdfError } from '@typfolio/core';
|
|
5
|
+
import { eachElement, headingLevel, isMarked, pageStructure, readDocument } from './structure.js';
|
|
6
|
+
export { readStructure, structureWarnings } from './structure.js';
|
|
5
7
|
let loader;
|
|
6
8
|
/** Shared by concurrent callers, so it carries no call identity. */
|
|
7
9
|
class PdfJsImportError extends Error {
|
|
@@ -28,14 +30,14 @@ function getPdfJs() {
|
|
|
28
30
|
});
|
|
29
31
|
return loader;
|
|
30
32
|
}
|
|
31
|
-
async function requirePdfJs() {
|
|
33
|
+
async function requirePdfJs(caller) {
|
|
32
34
|
try {
|
|
33
35
|
return await getPdfJs();
|
|
34
36
|
}
|
|
35
37
|
catch (error) {
|
|
36
38
|
if (!(error instanceof PdfJsImportError))
|
|
37
39
|
throw error;
|
|
38
|
-
throw new TypstPdfError('INITIALIZATION',
|
|
40
|
+
throw new TypstPdfError('INITIALIZATION', `${caller} could not load pdfjs-dist. Install pdfjs-dist (an optional peer dependency of @typfolio/dev-tools) to use @typfolio/dev-tools/pdf.`, [], { cause: error.cause });
|
|
39
41
|
}
|
|
40
42
|
}
|
|
41
43
|
const text = (value) => typeof value === 'string' && value ? value : undefined;
|
|
@@ -55,57 +57,6 @@ function creationDate(pdfjs, info, metadata) {
|
|
|
55
57
|
const date = fromXmp === undefined ? undefined : new Date(fromXmp);
|
|
56
58
|
return date && !Number.isNaN(date.getTime()) ? date : undefined;
|
|
57
59
|
}
|
|
58
|
-
const headingLevel = (role) => {
|
|
59
|
-
const match = /^H([1-6])?$/.exec(role);
|
|
60
|
-
return match ? Number(match[1] ?? 0) : undefined;
|
|
61
|
-
};
|
|
62
|
-
function contentIds(node, into = []) {
|
|
63
|
-
for (const child of node.children ?? []) {
|
|
64
|
-
if (child.type === 'content' && typeof child.id === 'string')
|
|
65
|
-
into.push(child.id);
|
|
66
|
-
else
|
|
67
|
-
contentIds(child, into);
|
|
68
|
-
}
|
|
69
|
-
return into;
|
|
70
|
-
}
|
|
71
|
-
function walk(node, roles, facts) {
|
|
72
|
-
const role = text(node.role);
|
|
73
|
-
if (role !== undefined) {
|
|
74
|
-
roles.set(role, (roles.get(role) ?? 0) + 1);
|
|
75
|
-
const level = headingLevel(role);
|
|
76
|
-
if (level !== undefined)
|
|
77
|
-
facts.headings.push({ level, contentIds: contentIds(node) });
|
|
78
|
-
else if (role === 'Figure')
|
|
79
|
-
facts.figures.push(typeof node.alt === 'string' ? { alt: node.alt } : {});
|
|
80
|
-
else if (role === 'Table')
|
|
81
|
-
facts.tables += 1;
|
|
82
|
-
}
|
|
83
|
-
for (const child of node.children ?? [])
|
|
84
|
-
if (child.role !== undefined)
|
|
85
|
-
walk(child, roles, facts);
|
|
86
|
-
}
|
|
87
|
-
/** The text of each marked-content section that has an id, by id. Text goes to its innermost section with an id. */
|
|
88
|
-
async function textByContentId(page) {
|
|
89
|
-
const { items } = await page.getTextContent({ includeMarkedContent: true });
|
|
90
|
-
const byId = new Map();
|
|
91
|
-
const open = [];
|
|
92
|
-
for (const item of items) {
|
|
93
|
-
if (item.type === 'beginMarkedContentProps')
|
|
94
|
-
open.push(typeof item.id === 'string' ? item.id : null);
|
|
95
|
-
else if (item.type === 'beginMarkedContent')
|
|
96
|
-
open.push(null);
|
|
97
|
-
else if (item.type === 'endMarkedContent')
|
|
98
|
-
open.pop();
|
|
99
|
-
else if (typeof item.str === 'string') {
|
|
100
|
-
let id = null;
|
|
101
|
-
for (let depth = open.length - 1; depth >= 0 && id === null; depth -= 1)
|
|
102
|
-
id = open[depth] ?? null;
|
|
103
|
-
if (id)
|
|
104
|
-
byId.set(id, (byId.get(id) ?? '') + item.str + (item.hasEOL ? ' ' : ''));
|
|
105
|
-
}
|
|
106
|
-
}
|
|
107
|
-
return byId;
|
|
108
|
-
}
|
|
109
60
|
async function pageFonts(pdfjs, page, fonts) {
|
|
110
61
|
const { fnArray, argsArray } = await page.getOperatorList();
|
|
111
62
|
fnArray.forEach((fn, index) => {
|
|
@@ -123,21 +74,13 @@ function isPdf(bytes) {
|
|
|
123
74
|
const head = new TextDecoder('latin1').decode(bytes.subarray(0, 1024));
|
|
124
75
|
return head.includes('%PDF-');
|
|
125
76
|
}
|
|
126
|
-
/**
|
|
127
|
-
|
|
128
|
-
* language, the standards its XMP metadata declares, headings, figure alternative text, tables and fonts.
|
|
129
|
-
* It reports facts only. A tagged PDF with PDF/UA metadata and all the right-looking structure is not thereby
|
|
130
|
-
* conformant; use a validator such as veraPDF for that.
|
|
131
|
-
*
|
|
132
|
-
* Needs `pdfjs-dist` (an optional peer dependency); rejects with a `TypstPdfError` that says so if it is missing.
|
|
133
|
-
* Input that is not a readable PDF rejects with `INVALID_REQUEST`.
|
|
134
|
-
*/
|
|
135
|
-
export async function inspectPdf(bytes) {
|
|
77
|
+
/** Opens the PDF in `bytes` with pdf.js, hands it to `use` and frees it. */
|
|
78
|
+
async function withDocument(caller, bytes, use) {
|
|
136
79
|
if (!(bytes instanceof Uint8Array))
|
|
137
|
-
throw new TypstPdfError('INVALID_REQUEST',
|
|
80
|
+
throw new TypstPdfError('INVALID_REQUEST', `${caller} needs the PDF bytes as a Uint8Array`);
|
|
138
81
|
if (!isPdf(bytes))
|
|
139
|
-
throw new TypstPdfError('INVALID_REQUEST',
|
|
140
|
-
const pdfjs = await requirePdfJs();
|
|
82
|
+
throw new TypstPdfError('INVALID_REQUEST', `${caller} input is not a PDF: no %PDF- header in the first 1024 bytes`);
|
|
83
|
+
const pdfjs = await requirePdfJs(caller);
|
|
141
84
|
// pdf.js takes ownership of the buffer it is given and detaches it, so give it a copy.
|
|
142
85
|
const task = pdfjs.getDocument({
|
|
143
86
|
data: new Uint8Array(bytes),
|
|
@@ -153,40 +96,58 @@ export async function inspectPdf(bytes) {
|
|
|
153
96
|
}
|
|
154
97
|
catch (cause) {
|
|
155
98
|
const detail = cause instanceof Error && cause.message ? `: ${cause.message}` : '';
|
|
156
|
-
throw new TypstPdfError('INVALID_REQUEST',
|
|
99
|
+
throw new TypstPdfError('INVALID_REQUEST', `${caller} could not read the PDF${detail}`, [], { cause });
|
|
157
100
|
}
|
|
101
|
+
return await use(pdfjs, doc);
|
|
102
|
+
}
|
|
103
|
+
finally {
|
|
104
|
+
await task.destroy();
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Reads a compiled PDF and reports facts that matter for accessibility and output policy: tagging, title,
|
|
109
|
+
* language, the standards its XMP metadata declares, the structure tree, headings, figure alternative text,
|
|
110
|
+
* tables and fonts. It reports facts only. A tagged PDF with PDF/UA metadata and all the right-looking structure
|
|
111
|
+
* is not thereby conformant; use a validator such as veraPDF for that.
|
|
112
|
+
*
|
|
113
|
+
* Needs `pdfjs-dist` (an optional peer dependency); rejects with a `TypstPdfError` that says so if it is missing.
|
|
114
|
+
* Input that is not a readable PDF rejects with `INVALID_REQUEST`.
|
|
115
|
+
*/
|
|
116
|
+
export function inspectPdf(bytes) {
|
|
117
|
+
return withDocument('inspectPdf', bytes, async (pdfjs, doc) => {
|
|
158
118
|
const { info, metadata } = await doc.getMetadata();
|
|
159
119
|
const markInfo = await doc.getMarkInfo();
|
|
160
|
-
const
|
|
161
|
-
const headings = [];
|
|
162
|
-
const figures = [];
|
|
120
|
+
const structure = [];
|
|
163
121
|
const fonts = new Map();
|
|
164
|
-
let tables = 0;
|
|
165
122
|
let structureTree = false;
|
|
166
123
|
for (let number = 1; number <= doc.numPages; number += 1) {
|
|
167
124
|
const page = await doc.getPage(number);
|
|
168
|
-
const
|
|
169
|
-
if (
|
|
125
|
+
const elements = await pageStructure(page);
|
|
126
|
+
if (elements)
|
|
170
127
|
structureTree = true;
|
|
171
|
-
|
|
172
|
-
for (const child of tree.children ?? [])
|
|
173
|
-
walk(child, roles, facts);
|
|
174
|
-
const textById = facts.headings.length ? await textByContentId(page) : new Map();
|
|
175
|
-
for (const heading of facts.headings) {
|
|
176
|
-
const joined = heading.contentIds.map(id => textById.get(id) ?? '').join('');
|
|
177
|
-
headings.push({ level: heading.level, text: joined.replace(/\s+/g, ' ').trim() });
|
|
178
|
-
}
|
|
179
|
-
figures.push(...facts.figures);
|
|
180
|
-
tables += facts.tables;
|
|
181
|
-
}
|
|
128
|
+
structure.push({ page: number, elements: elements ?? [] });
|
|
182
129
|
await pageFonts(pdfjs, page, fonts);
|
|
183
130
|
}
|
|
184
|
-
const
|
|
131
|
+
const roles = new Map();
|
|
132
|
+
const headings = [];
|
|
133
|
+
const figures = [];
|
|
134
|
+
let tables = 0;
|
|
135
|
+
eachElement(structure, element => {
|
|
136
|
+
if (element.role)
|
|
137
|
+
roles.set(element.role, (roles.get(element.role) ?? 0) + 1);
|
|
138
|
+
const level = headingLevel(element.role);
|
|
139
|
+
if (level !== undefined)
|
|
140
|
+
headings.push({ level, text: element.text });
|
|
141
|
+
else if (element.role === 'Figure')
|
|
142
|
+
figures.push(element.alt === undefined ? {} : { alt: element.alt });
|
|
143
|
+
else if (element.role === 'Table')
|
|
144
|
+
tables += 1;
|
|
145
|
+
});
|
|
185
146
|
const part = integer(metadataValue(metadata, 'pdfaid:part'));
|
|
186
147
|
const conformance = text(metadataValue(metadata, 'pdfaid:conformance'));
|
|
187
148
|
return {
|
|
188
149
|
pages: doc.numPages,
|
|
189
|
-
tagged:
|
|
150
|
+
tagged: isMarked(markInfo),
|
|
190
151
|
structureTree,
|
|
191
152
|
title: text(info?.Title) ?? text(metadataValue(metadata, 'dc:title')),
|
|
192
153
|
language: text(info?.Language),
|
|
@@ -200,9 +161,15 @@ export async function inspectPdf(bytes) {
|
|
|
200
161
|
tables,
|
|
201
162
|
fonts: [...fonts.values()],
|
|
202
163
|
structureRoles: Object.fromEntries(roles),
|
|
164
|
+
structure,
|
|
203
165
|
};
|
|
204
|
-
}
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
166
|
+
});
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* The PDF in `bytes`, read with pdf.js: one `untagged` warning when it is not tagged (`/MarkInfo /Marked`), else
|
|
170
|
+
* the `structureWarnings` of its pages. The function to pass as a template check's `structure` option. Needs
|
|
171
|
+
* `pdfjs-dist`, and rejects as `inspectPdf` does.
|
|
172
|
+
*/
|
|
173
|
+
export function checkStructure(bytes) {
|
|
174
|
+
return withDocument('checkStructure', bytes, async (_pdfjs, doc) => (await readDocument(doc)).warnings);
|
|
208
175
|
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/** One structure element (tag), as a screen reader gets it. */
|
|
2
|
+
export interface PdfStructureElement {
|
|
3
|
+
/** The role after pdf.js resolves the file's `/RoleMap`: `Document`, `H1`, `P`, `Table`, `TH`, `Figure`, … */
|
|
4
|
+
role: string;
|
|
5
|
+
/** The text drawn in the element and its children on this page, whitespace collapsed; empty when there is none. */
|
|
6
|
+
text: string;
|
|
7
|
+
/** The element's `/Alt`. */
|
|
8
|
+
alt?: string;
|
|
9
|
+
/** The element's `/Lang`. */
|
|
10
|
+
lang?: string;
|
|
11
|
+
children: PdfStructureElement[];
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* One page's part of the structure tree: the elements with content on the page and their parents. Like pdf.js, it
|
|
15
|
+
* lists every row of a table and every item of a list that has content on the page, so a screen reader knows their
|
|
16
|
+
* size; a row or item drawn on another page is there with no text.
|
|
17
|
+
*/
|
|
18
|
+
export interface PdfStructurePage {
|
|
19
|
+
/** The page number, from 1. */
|
|
20
|
+
page: number;
|
|
21
|
+
/** The top of the page's tree, usually one `Document`; empty for a page without tags. */
|
|
22
|
+
elements: PdfStructureElement[];
|
|
23
|
+
}
|
|
24
|
+
export type PdfStructureWarningKind = 'untagged' | 'no-headings' | 'heading-skips-level' | 'figure-without-alt' | 'table-without-headers';
|
|
25
|
+
export interface PdfStructureWarning {
|
|
26
|
+
kind: PdfStructureWarningKind;
|
|
27
|
+
/** The page it is on; absent for a problem with the whole document. */
|
|
28
|
+
page?: number;
|
|
29
|
+
/** The element it is about, from the pages given; absent for a problem with the whole document. */
|
|
30
|
+
element?: PdfStructureElement;
|
|
31
|
+
message: string;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* The part of a pdf.js document (`PDFDocumentProxy`, from the Node or the browser build) that `readStructure`
|
|
35
|
+
* reads, so a page that already has pdf.js can pass its own document.
|
|
36
|
+
*/
|
|
37
|
+
export interface PdfStructureSource {
|
|
38
|
+
numPages: number;
|
|
39
|
+
getPage(number: number): Promise<{
|
|
40
|
+
getStructTree(): Promise<unknown>;
|
|
41
|
+
getTextContent(options: {
|
|
42
|
+
includeMarkedContent: boolean;
|
|
43
|
+
}): Promise<{
|
|
44
|
+
items: unknown[];
|
|
45
|
+
}>;
|
|
46
|
+
}>;
|
|
47
|
+
}
|
|
48
|
+
/** What pdf.js's `getMarkInfo()` resolves to. */
|
|
49
|
+
export type PdfMarkInfo = {
|
|
50
|
+
Marked?: boolean;
|
|
51
|
+
} | Map<string, unknown> | null;
|
|
52
|
+
/** The catalog's `/MarkInfo /Marked` is true. */
|
|
53
|
+
export declare const isMarked: (markInfo: PdfMarkInfo) => boolean;
|
|
54
|
+
export declare const headingLevel: (role: string) => number | undefined;
|
|
55
|
+
/** A page's part of the structure tree; null when the page has none. */
|
|
56
|
+
export declare function pageStructure(page: Awaited<ReturnType<PdfStructureSource['getPage']>>): Promise<PdfStructureElement[] | null>;
|
|
57
|
+
/** Calls `visit` on every element of every page, parents before children, in reading order. */
|
|
58
|
+
export declare function eachElement(pages: readonly PdfStructurePage[], visit: (element: PdfStructureElement, page: number) => void): void;
|
|
59
|
+
/**
|
|
60
|
+
* Every page's part of the structure tree, read from a pdf.js document (`PDFDocumentProxy`) the caller already
|
|
61
|
+
* has, such as one a browser page loaded with its own pdf.js. Needs nothing installed: `inspectPdf` returns the
|
|
62
|
+
* same pages as `structure`.
|
|
63
|
+
*/
|
|
64
|
+
export declare function readStructure(document: PdfStructureSource): Promise<PdfStructurePage[]>;
|
|
65
|
+
/**
|
|
66
|
+
* The elements at the top of a page that go on from the previous page. pdf.js gives each page its own part of the
|
|
67
|
+
* tree, so a table that runs over a page break appears on both pages, the second time without its header row.
|
|
68
|
+
* Followed down the first child here and the last child there for as long as the roles match, so a new table that
|
|
69
|
+
* starts a page right after another table ended the previous one is taken for its continuation.
|
|
70
|
+
*/
|
|
71
|
+
export declare function continued(previous: readonly PdfStructureElement[], current: readonly PdfStructureElement[]): Set<PdfStructureElement>;
|
|
72
|
+
/**
|
|
73
|
+
* What a screen reader user would trip over in these pages (`inspectPdf`'s `structure`, or `readStructure`'s
|
|
74
|
+
* result): several pages and no headings to move between, headings that skip a level, a figure with no alt text
|
|
75
|
+
* and a table with no header cells. In reading order; empty when it finds none of these. Whether the file is
|
|
76
|
+
* tagged at all is not in its pages: `checkStructure` and `inspectPdf`'s `tagged` say that.
|
|
77
|
+
*
|
|
78
|
+
* These are not conformance checks, and an empty result is not a verdict. A PDF/UA-1 compile already refuses
|
|
79
|
+
* skipped heading levels and images without alt text; it accepts a table without header cells and a document
|
|
80
|
+
* without headings, and so does a validator such as veraPDF. Whether the reading order and wording make sense
|
|
81
|
+
* still needs a person.
|
|
82
|
+
*/
|
|
83
|
+
export declare function structureWarnings(pages: readonly PdfStructurePage[]): PdfStructureWarning[];
|
|
84
|
+
/**
|
|
85
|
+
* A pdf.js document's pages and their warnings: one `untagged` warning when it is not tagged, else the
|
|
86
|
+
* `structureWarnings` of its pages. What `checkStructure` reports, and what the panel shows.
|
|
87
|
+
*/
|
|
88
|
+
export declare function readDocument(document: PdfStructureSource & {
|
|
89
|
+
getMarkInfo(): Promise<PdfMarkInfo>;
|
|
90
|
+
}): Promise<{
|
|
91
|
+
tagged: boolean;
|
|
92
|
+
pages: PdfStructurePage[];
|
|
93
|
+
warnings: PdfStructureWarning[];
|
|
94
|
+
}>;
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
// The structure tree, as a screen reader gets it, and the rules that read it. Internal: `@typfolio/dev-tools/pdf`
|
|
2
|
+
// exports the public part, and the structure panel bundles it. Nothing here loads pdf.js; callers pass a document.
|
|
3
|
+
import { TypstPdfError } from '@typfolio/core';
|
|
4
|
+
/** The catalog's `/MarkInfo /Marked` is true. */
|
|
5
|
+
export const isMarked = (markInfo) => (markInfo instanceof Map ? markInfo.get('Marked') : markInfo?.Marked) === true;
|
|
6
|
+
export const headingLevel = (role) => {
|
|
7
|
+
const match = /^H([1-6])?$/.exec(role);
|
|
8
|
+
return match ? Number(match[1] ?? 0) : undefined;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* The text of each marked-content section that has an id, by id. Text goes to its innermost section with an id;
|
|
12
|
+
* an artifact's text (a running header, a page number) goes to none, as a screen reader skips it.
|
|
13
|
+
*/
|
|
14
|
+
function textByContentId(items) {
|
|
15
|
+
const byId = new Map();
|
|
16
|
+
const open = [];
|
|
17
|
+
for (const item of items) {
|
|
18
|
+
if (item.type === 'beginMarkedContentProps' || item.type === 'beginMarkedContent') {
|
|
19
|
+
const own = typeof item.id === 'string' && item.id ? item.id : undefined;
|
|
20
|
+
open.push(own ?? (item.tag === 'Artifact' ? null : open.at(-1) ?? null));
|
|
21
|
+
}
|
|
22
|
+
else if (item.type === 'endMarkedContent')
|
|
23
|
+
open.pop();
|
|
24
|
+
else if (typeof item.str === 'string') {
|
|
25
|
+
const id = open.at(-1);
|
|
26
|
+
if (id)
|
|
27
|
+
byId.set(id, (byId.get(id) ?? '') + item.str + (item.hasEOL ? ' ' : ''));
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
return byId;
|
|
31
|
+
}
|
|
32
|
+
// Inline roles (ISO 32000-1 14.8.4.4, and PDF 2.0's Em, Strong and Sub): their text runs on with the text around
|
|
33
|
+
// them, where a block element's text is a separate run.
|
|
34
|
+
const inlineRoles = new Set(['Span', 'Quote', 'Note', 'Reference', 'BibEntry', 'Code', 'Link', 'Annot', 'Ruby', 'RB', 'RT', 'RP', 'Warichu', 'WT', 'WP', 'Em', 'Strong', 'Sub']);
|
|
35
|
+
const isElement = (node) => typeof node.role === 'string';
|
|
36
|
+
function toElement(node, textById) {
|
|
37
|
+
const children = [];
|
|
38
|
+
let raw = '';
|
|
39
|
+
for (const child of node.children ?? []) {
|
|
40
|
+
if (isElement(child)) {
|
|
41
|
+
const built = toElement(child, textById);
|
|
42
|
+
children.push(built.element);
|
|
43
|
+
raw += inlineRoles.has(built.element.role) ? built.raw : ` ${built.raw} `;
|
|
44
|
+
}
|
|
45
|
+
else if (child.type === 'content' && typeof child.id === 'string')
|
|
46
|
+
raw += textById.get(child.id) ?? '';
|
|
47
|
+
}
|
|
48
|
+
return {
|
|
49
|
+
element: {
|
|
50
|
+
role: node.role,
|
|
51
|
+
text: raw.replace(/\s+/g, ' ').trim(),
|
|
52
|
+
...(typeof node.alt === 'string' ? { alt: node.alt } : {}),
|
|
53
|
+
...(typeof node.lang === 'string' ? { lang: node.lang } : {}),
|
|
54
|
+
children,
|
|
55
|
+
},
|
|
56
|
+
raw,
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
/** A page's part of the structure tree; null when the page has none. */
|
|
60
|
+
export async function pageStructure(page) {
|
|
61
|
+
const tree = await page.getStructTree();
|
|
62
|
+
if (!tree)
|
|
63
|
+
return null;
|
|
64
|
+
const { items } = await page.getTextContent({ includeMarkedContent: true });
|
|
65
|
+
const textById = textByContentId(items);
|
|
66
|
+
return (tree.children ?? []).filter(isElement).map(child => toElement(child, textById).element);
|
|
67
|
+
}
|
|
68
|
+
/** Calls `visit` on every element of every page, parents before children, in reading order. */
|
|
69
|
+
export function eachElement(pages, visit) {
|
|
70
|
+
const walk = (element, page) => {
|
|
71
|
+
visit(element, page);
|
|
72
|
+
for (const child of element.children)
|
|
73
|
+
walk(child, page);
|
|
74
|
+
};
|
|
75
|
+
for (const { page, elements } of pages)
|
|
76
|
+
for (const element of elements)
|
|
77
|
+
walk(element, page);
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Every page's part of the structure tree, read from a pdf.js document (`PDFDocumentProxy`) the caller already
|
|
81
|
+
* has, such as one a browser page loaded with its own pdf.js. Needs nothing installed: `inspectPdf` returns the
|
|
82
|
+
* same pages as `structure`.
|
|
83
|
+
*/
|
|
84
|
+
export async function readStructure(document) {
|
|
85
|
+
if (!document || typeof document.getPage !== 'function' || !Number.isSafeInteger(document.numPages)) {
|
|
86
|
+
throw new TypstPdfError('INVALID_REQUEST', 'readStructure takes a pdf.js document (PDFDocumentProxy)');
|
|
87
|
+
}
|
|
88
|
+
const pages = [];
|
|
89
|
+
for (let page = 1; page <= document.numPages; page += 1) {
|
|
90
|
+
pages.push({ page, elements: await pageStructure(await document.getPage(page)) ?? [] });
|
|
91
|
+
}
|
|
92
|
+
return pages;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* The elements at the top of a page that go on from the previous page. pdf.js gives each page its own part of the
|
|
96
|
+
* tree, so a table that runs over a page break appears on both pages, the second time without its header row.
|
|
97
|
+
* Followed down the first child here and the last child there for as long as the roles match, so a new table that
|
|
98
|
+
* starts a page right after another table ended the previous one is taken for its continuation.
|
|
99
|
+
*/
|
|
100
|
+
export function continued(previous, current) {
|
|
101
|
+
const carried = new Set();
|
|
102
|
+
let before = previous.at(-1);
|
|
103
|
+
let after = current[0];
|
|
104
|
+
while (before && after && before.role === after.role) {
|
|
105
|
+
carried.add(after);
|
|
106
|
+
before = before.children.at(-1);
|
|
107
|
+
after = after.children[0];
|
|
108
|
+
}
|
|
109
|
+
return carried;
|
|
110
|
+
}
|
|
111
|
+
/** A `TH` in the table, not counting the ones of a table nested in it. */
|
|
112
|
+
const hasHeaderCell = (table) => table.children.some(child => child.role === 'TH' || (child.role !== 'Table' && hasHeaderCell(child)));
|
|
113
|
+
const quote = (value) => `"${value.length > 60 ? `${value.slice(0, 57)}…` : value}"`;
|
|
114
|
+
/**
|
|
115
|
+
* What a screen reader user would trip over in these pages (`inspectPdf`'s `structure`, or `readStructure`'s
|
|
116
|
+
* result): several pages and no headings to move between, headings that skip a level, a figure with no alt text
|
|
117
|
+
* and a table with no header cells. In reading order; empty when it finds none of these. Whether the file is
|
|
118
|
+
* tagged at all is not in its pages: `checkStructure` and `inspectPdf`'s `tagged` say that.
|
|
119
|
+
*
|
|
120
|
+
* These are not conformance checks, and an empty result is not a verdict. A PDF/UA-1 compile already refuses
|
|
121
|
+
* skipped heading levels and images without alt text; it accepts a table without header cells and a document
|
|
122
|
+
* without headings, and so does a validator such as veraPDF. Whether the reading order and wording make sense
|
|
123
|
+
* still needs a person.
|
|
124
|
+
*/
|
|
125
|
+
export function structureWarnings(pages) {
|
|
126
|
+
if (!Array.isArray(pages) || !pages.every(page => Array.isArray(page?.elements))) {
|
|
127
|
+
throw new TypstPdfError('INVALID_REQUEST', 'structureWarnings takes the pages of a structure tree: the structure of inspectPdf, or what readStructure returns');
|
|
128
|
+
}
|
|
129
|
+
const warnings = [];
|
|
130
|
+
let headings = 0;
|
|
131
|
+
let previousLevel = 0;
|
|
132
|
+
pages.forEach(({ page, elements }, index) => {
|
|
133
|
+
const carried = index === 0 ? new Set() : continued(pages[index - 1].elements, elements);
|
|
134
|
+
eachElement([{ page, elements }], element => {
|
|
135
|
+
const level = headingLevel(element.role);
|
|
136
|
+
if (level !== undefined) {
|
|
137
|
+
headings += 1;
|
|
138
|
+
if (level === 0)
|
|
139
|
+
return;
|
|
140
|
+
if (level > previousLevel + 1) {
|
|
141
|
+
warnings.push({
|
|
142
|
+
kind: 'heading-skips-level',
|
|
143
|
+
page,
|
|
144
|
+
element,
|
|
145
|
+
message: previousLevel === 0
|
|
146
|
+
? `The first heading, ${quote(element.text)}, is H${level}; headings start at H1.`
|
|
147
|
+
: `${quote(element.text)} is H${level} right after an H${previousLevel}, skipping a level.`,
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
previousLevel = level;
|
|
151
|
+
}
|
|
152
|
+
else if (element.role === 'Figure' && !element.alt?.trim()) {
|
|
153
|
+
warnings.push({ kind: 'figure-without-alt', page, element, message: 'A figure has no alt text, so a screen reader cannot describe it.' });
|
|
154
|
+
}
|
|
155
|
+
else if (element.role === 'Table' && !carried.has(element) && !hasHeaderCell(element)) {
|
|
156
|
+
const which = element.text ? `The table starting ${quote(element.text)}` : 'A table';
|
|
157
|
+
warnings.push({ kind: 'table-without-headers', page, element, message: `${which} has no header cells (TH), so a screen reader cannot name its columns.` });
|
|
158
|
+
}
|
|
159
|
+
});
|
|
160
|
+
});
|
|
161
|
+
if (pages.length > 1 && headings === 0) {
|
|
162
|
+
warnings.unshift({ kind: 'no-headings', message: `${pages.length} pages and no headings, so a screen reader user cannot move between sections.` });
|
|
163
|
+
}
|
|
164
|
+
return warnings;
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* A pdf.js document's pages and their warnings: one `untagged` warning when it is not tagged, else the
|
|
168
|
+
* `structureWarnings` of its pages. What `checkStructure` reports, and what the panel shows.
|
|
169
|
+
*/
|
|
170
|
+
export async function readDocument(document) {
|
|
171
|
+
const tagged = isMarked(await document.getMarkInfo());
|
|
172
|
+
const pages = await readStructure(document);
|
|
173
|
+
const warnings = tagged
|
|
174
|
+
? structureWarnings(pages)
|
|
175
|
+
: [{ kind: 'untagged', message: 'The PDF is not tagged, so a screen reader gets its text with no headings, tables or figures.' }];
|
|
176
|
+
return { tagged, pages, warnings };
|
|
177
|
+
}
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@typfolio/dev-tools",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Dev-time tools for Typfolio templates: schema-based template checks
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Dev-time tools for Typfolio templates: schema-based template checks, PDF inspection and an in-page structure panel (install as a devDependency)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
|
-
"keywords": ["typst", "pdf", "pdf-ua", "accessibility", "template", "testing", "ci", "json-schema"],
|
|
7
|
+
"keywords": ["typst", "pdf", "pdf-ua", "accessibility", "template", "testing", "ci", "json-schema", "devtools"],
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
10
10
|
"url": "git+https://github.com/HelioCampus/typfolio.git",
|
|
@@ -12,19 +12,21 @@
|
|
|
12
12
|
},
|
|
13
13
|
"homepage": "https://github.com/HelioCampus/typfolio#readme",
|
|
14
14
|
"bugs": { "url": "https://github.com/HelioCampus/typfolio/issues" },
|
|
15
|
-
"files": ["dist", "README.md"],
|
|
15
|
+
"files": ["dist", "README.md", "THIRD_PARTY_NOTICES.md"],
|
|
16
16
|
"types": "./dist/index.d.ts",
|
|
17
17
|
"exports": {
|
|
18
18
|
".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
|
|
19
|
-
"./pdf": { "types": "./dist/pdf.d.ts", "import": "./dist/pdf.js" }
|
|
19
|
+
"./pdf": { "types": "./dist/pdf.d.ts", "import": "./dist/pdf.js" },
|
|
20
|
+
"./panel": { "types": "./dist/panel.d.ts", "import": "./dist/panel.js" }
|
|
20
21
|
},
|
|
21
22
|
"typesVersions": {
|
|
22
23
|
"*": {
|
|
23
|
-
"pdf": ["./dist/pdf.d.ts"]
|
|
24
|
+
"pdf": ["./dist/pdf.d.ts"],
|
|
25
|
+
"panel": ["./dist/panel.d.ts"]
|
|
24
26
|
}
|
|
25
27
|
},
|
|
26
28
|
"dependencies": {
|
|
27
|
-
"@typfolio/core": "^0.
|
|
29
|
+
"@typfolio/core": "^0.4.0"
|
|
28
30
|
},
|
|
29
31
|
"peerDependencies": {
|
|
30
32
|
"pdfjs-dist": "^6.3.0"
|