@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.
package/README.md CHANGED
@@ -56,12 +56,12 @@ const report = await inspectPdf(bytes); // the bytes of a compiled PDF
56
56
  // report.headings: [{ level, text }] in document order
57
57
  // report.figures: [{ alt? }], report.tables, report.fonts: [{ name, embedded }]
58
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
59
+ // report.structure: [{ page, elements: [{ role, text, alt?, lang?, summary?, scope?, id?, headers?, children }] }] the tags of each page
60
60
  ```
61
61
 
62
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.
63
63
 
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.
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. A table carries what Typst wrote for it: the table's `summary` (`pdf.table-summary`), a header cell's `scope` (`Row`, `Column` or `Both`) and `id`, and on each cell `headers`, the ids of the header cells that label it. A row header made with `pdf.header-cell(scope: "row")` is a `TH` with scope `Row`, and the cells of its row name it in `headers`. Text an artifact draws (a running header, a page number) belongs to no element.
65
65
 
66
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
67
 
@@ -92,7 +92,9 @@ await checkStructure(bytes); // the same, and one `untagged` warning for a PDF t
92
92
 
93
93
  ## Structure panel
94
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.
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. A header cell shows its scope, a table its summary, and a selected cell the header cells that label it, by their text.
96
+
97
+ Beside the tags the panel draws the page with the page's pdf.js and marks the selected tag on it; moving over the page marks the tag under the pointer, and a click selects it in the list. The mark covers what the tag holds, which is its text or a figure's own box: a cell's border and padding belong to no tag, so they are not covered, and an empty cell has nothing to mark. The box of text is estimated from its font size and fits upright Latin text. The "Page" button in the toolbar hides the page. A row shows one line of its tag's text, cut short; the selected tag's row shows all of it. A tag's row shows a "Copy" button while the pointer or focus is on it, which copies the tag's whole text (a figure's alt text); the selected tag's text and alt text have one too. In `mountStructureDevtools`, the toolbar's "Fill the page" button puts the panel over the whole page, for room to read the page view, and back. The lines between the tags, the page and the selected tag can be dragged to give each more or less room (or moved with the arrow keys when focused); a double click puts one back. The page is a second drawing of the PDF, apart from any preview your application shows. 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
98
 
97
99
  ```ts
98
100
  import * as pdfjs from 'pdfjs-dist';
package/dist/panel.d.ts CHANGED
@@ -1,7 +1,9 @@
1
1
  import type { PdfStructureSource } from './structure.js';
2
2
  /**
3
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.
4
+ * worker set up (`GlobalWorkerOptions.workerSrc`). The panel opens each PDF with it, keeps it open
5
+ * while it is the PDF on show so the page view can draw its pages, and frees it when another takes its place or the
6
+ * panel is removed.
5
7
  */
6
8
  export interface StructurePanelPdfJs {
7
9
  getDocument(source: {