@typfolio/dev-tools 0.5.0 → 0.6.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.
@@ -8,6 +8,14 @@ export interface PdfStructureElement {
8
8
  alt?: string;
9
9
  /** The element's `/Lang`. */
10
10
  lang?: string;
11
+ /** A `Table`'s `/Summary`: what the table is about, for a reader who cannot see it. */
12
+ summary?: string;
13
+ /** A `TH`'s `/Scope`: whether it labels its row, its column or both. */
14
+ scope?: 'Row' | 'Column' | 'Both';
15
+ /** A `TH`'s `/ID`, which other cells' `headers` name. */
16
+ id?: string;
17
+ /** A `TH` or `TD`'s `/Headers`: the `id` of each header cell that labels it. */
18
+ headers?: string[];
11
19
  children: PdfStructureElement[];
12
20
  }
13
21
  /**
@@ -45,6 +53,10 @@ export interface PdfStructureSource {
45
53
  }>;
46
54
  }>;
47
55
  }
56
+ /** A rectangle on a page in PDF units, origin at the bottom left: `[left, bottom, right, top]`. */
57
+ export type PdfRect = [number, number, number, number];
58
+ /** Where each element's content is drawn on its page; an element without drawn content has no entry. */
59
+ export type PdfElementBoxes = WeakMap<PdfStructureElement, PdfRect>;
48
60
  /** What pdf.js's `getMarkInfo()` resolves to. */
49
61
  export type PdfMarkInfo = {
50
62
  Marked?: boolean;
@@ -52,8 +64,8 @@ export type PdfMarkInfo = {
52
64
  /** The catalog's `/MarkInfo /Marked` is true. */
53
65
  export declare const isMarked: (markInfo: PdfMarkInfo) => boolean;
54
66
  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>;
67
+ /** A page's part of the structure tree; null when the page has none. With `boxes`, also where each element is drawn. */
68
+ export declare function pageStructure(page: Awaited<ReturnType<PdfStructureSource['getPage']>>, boxes?: PdfElementBoxes): Promise<PdfStructureElement[] | null>;
57
69
  /** Calls `visit` on every element of every page, parents before children, in reading order. */
58
70
  export declare function eachElement(pages: readonly PdfStructurePage[], visit: (element: PdfStructureElement, page: number) => void): void;
59
71
  /**
@@ -87,7 +99,7 @@ export declare function structureWarnings(pages: readonly PdfStructurePage[]): P
87
99
  */
88
100
  export declare function readDocument(document: PdfStructureSource & {
89
101
  getMarkInfo(): Promise<PdfMarkInfo>;
90
- }): Promise<{
102
+ }, boxes?: PdfElementBoxes): Promise<{
91
103
  tagged: boolean;
92
104
  pages: PdfStructurePage[];
93
105
  warnings: PdfStructureWarning[];
package/dist/structure.js CHANGED
@@ -1,6 +1,15 @@
1
1
  // The structure tree, as a screen reader gets it, and the rules that read it. Internal: `@typfolio/dev-tools/pdf`
2
2
  // exports the public part, and the structure panel bundles it. Nothing here loads pdf.js; callers pass a document.
3
3
  import { TypstPdfError } from '@typfolio/core';
4
+ const union = (a, b) => !a ? b : !b ? a : [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.max(a[2], b[2]), Math.max(a[3], b[3])];
5
+ // The box of a run of text: pdf.js gives its baseline origin, its advance and its font size. The share of the font
6
+ // size above and below the baseline is an estimate that fits Latin text; upright text only.
7
+ function textRect({ str, transform, width, height }) {
8
+ if (!str?.trim() || !Array.isArray(transform) || typeof width !== 'number' || typeof height !== 'number' || !(width > 0) || !(height > 0))
9
+ return undefined;
10
+ const [, , , , x, y] = transform;
11
+ return [x, y - height * 0.22, x + width, y + height * 0.8];
12
+ }
4
13
  /** The catalog's `/MarkInfo /Marked` is true. */
5
14
  export const isMarked = (markInfo) => (markInfo instanceof Map ? markInfo.get('Marked') : markInfo?.Marked) === true;
6
15
  export const headingLevel = (role) => {
@@ -11,7 +20,7 @@ export const headingLevel = (role) => {
11
20
  * The text of each marked-content section that has an id, by id. Text goes to its innermost section with an id;
12
21
  * an artifact's text (a running header, a page number) goes to none, as a screen reader skips it.
13
22
  */
14
- function textByContentId(items) {
23
+ function textByContentId(items, rects) {
15
24
  const byId = new Map();
16
25
  const open = [];
17
26
  for (const item of items) {
@@ -25,6 +34,9 @@ function textByContentId(items) {
25
34
  const id = open.at(-1);
26
35
  if (id)
27
36
  byId.set(id, (byId.get(id) ?? '') + item.str + (item.hasEOL ? ' ' : ''));
37
+ const rect = id && rects ? union(rects.get(id), textRect(item)) : undefined;
38
+ if (id && rect)
39
+ rects.set(id, rect);
28
40
  }
29
41
  }
30
42
  return byId;
@@ -33,37 +45,54 @@ function textByContentId(items) {
33
45
  // them, where a block element's text is a separate run.
34
46
  const inlineRoles = new Set(['Span', 'Quote', 'Note', 'Reference', 'BibEntry', 'Code', 'Link', 'Annot', 'Ruby', 'RB', 'RT', 'RP', 'Warichu', 'WT', 'WP', 'Em', 'Strong', 'Sub']);
35
47
  const isElement = (node) => typeof node.role === 'string';
36
- function toElement(node, textById) {
48
+ // An element's `/BBox`, as a figure has. pdf.js gives a `/Width` and `/Height` without a position as a box at the
49
+ // origin, which is not a place on the page.
50
+ function ownBox(bbox) {
51
+ if (!Array.isArray(bbox) || bbox.length !== 4 || !bbox.every(value => typeof value === 'number' && Number.isFinite(value)))
52
+ return undefined;
53
+ const [left, bottom, right, top] = bbox;
54
+ return (left === 0 && bottom === 0) || !(right > left) || !(top > bottom) ? undefined : [left, bottom, right, top];
55
+ }
56
+ function toElement(node, textById, placement) {
37
57
  const children = [];
38
58
  let raw = '';
59
+ let box = placement ? ownBox(node.bbox) : undefined;
39
60
  for (const child of node.children ?? []) {
40
61
  if (isElement(child)) {
41
- const built = toElement(child, textById);
62
+ const built = toElement(child, textById, placement);
42
63
  children.push(built.element);
43
64
  raw += inlineRoles.has(built.element.role) ? built.raw : ` ${built.raw} `;
65
+ box = union(box, built.box);
44
66
  }
45
- else if (child.type === 'content' && typeof child.id === 'string')
67
+ else if (child.type === 'content' && typeof child.id === 'string') {
46
68
  raw += textById.get(child.id) ?? '';
69
+ box = union(box, placement?.rects.get(child.id));
70
+ }
47
71
  }
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,
72
+ const element = {
73
+ role: node.role,
74
+ text: raw.replace(/\s+/g, ' ').trim(),
75
+ ...(typeof node.alt === 'string' ? { alt: node.alt } : {}),
76
+ ...(typeof node.lang === 'string' ? { lang: node.lang } : {}),
77
+ ...(typeof node.summary === 'string' ? { summary: node.summary } : {}),
78
+ ...(node.scope === 'Row' || node.scope === 'Column' || node.scope === 'Both' ? { scope: node.scope } : {}),
79
+ ...(typeof node.structId === 'string' ? { id: node.structId } : {}),
80
+ ...(Array.isArray(node.headers) ? { headers: node.headers.filter((id) => typeof id === 'string') } : {}),
81
+ children,
57
82
  };
83
+ if (box)
84
+ placement.boxes.set(element, box);
85
+ return { element, raw, box };
58
86
  }
59
- /** A page's part of the structure tree; null when the page has none. */
60
- export async function pageStructure(page) {
87
+ /** A page's part of the structure tree; null when the page has none. With `boxes`, also where each element is drawn. */
88
+ export async function pageStructure(page, boxes) {
61
89
  const tree = await page.getStructTree();
62
90
  if (!tree)
63
91
  return null;
64
92
  const { items } = await page.getTextContent({ includeMarkedContent: true });
65
- const textById = textByContentId(items);
66
- return (tree.children ?? []).filter(isElement).map(child => toElement(child, textById).element);
93
+ const placement = boxes && { rects: new Map(), boxes };
94
+ const textById = textByContentId(items, placement?.rects);
95
+ return (tree.children ?? []).filter(isElement).map(child => toElement(child, textById, placement).element);
67
96
  }
68
97
  /** Calls `visit` on every element of every page, parents before children, in reading order. */
69
98
  export function eachElement(pages, visit) {
@@ -81,13 +110,16 @@ export function eachElement(pages, visit) {
81
110
  * has, such as one a browser page loaded with its own pdf.js. Needs nothing installed: `inspectPdf` returns the
82
111
  * same pages as `structure`.
83
112
  */
84
- export async function readStructure(document) {
113
+ export function readStructure(document) {
114
+ return readPages(document);
115
+ }
116
+ async function readPages(document, boxes) {
85
117
  if (!document || typeof document.getPage !== 'function' || !Number.isSafeInteger(document.numPages)) {
86
118
  throw new TypstPdfError('INVALID_REQUEST', 'readStructure takes a pdf.js document (PDFDocumentProxy)');
87
119
  }
88
120
  const pages = [];
89
121
  for (let page = 1; page <= document.numPages; page += 1) {
90
- pages.push({ page, elements: await pageStructure(await document.getPage(page)) ?? [] });
122
+ pages.push({ page, elements: await pageStructure(await document.getPage(page), boxes) ?? [] });
91
123
  }
92
124
  return pages;
93
125
  }
@@ -167,9 +199,9 @@ export function structureWarnings(pages) {
167
199
  * A pdf.js document's pages and their warnings: one `untagged` warning when it is not tagged, else the
168
200
  * `structureWarnings` of its pages. What `checkStructure` reports, and what the panel shows.
169
201
  */
170
- export async function readDocument(document) {
202
+ export async function readDocument(document, boxes) {
171
203
  const tagged = isMarked(await document.getMarkInfo());
172
- const pages = await readStructure(document);
204
+ const pages = await readPages(document, boxes);
173
205
  const warnings = tagged
174
206
  ? structureWarnings(pages)
175
207
  : [{ kind: 'untagged', message: 'The PDF is not tagged, so a screen reader gets its text with no headings, tables or figures.' }];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typfolio/dev-tools",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
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",