@nxgt/material-core 0.3.0 → 0.3.1

package/README.md

@@ -279,6 +279,37 @@ const page = pageTextFromItems([{ str: 'Café au', hasEOL: true }, { str: 'lait'
 findTextMatches(page.text, 'cafe au lait'); // [{ start: 0, end: 12 }] — case, accents and line breaks ignored
 ```
 
+To open a reader on a page, `pinToPage(node, beforeScroll, onRelease?)`
+keeps that page at the top of the page area (an element inside the
+`[data-slot="scroll-area-viewport"]` of a `[data-slot="scroll-area"]`) while
+the pages above it change size, until a wheel, touch, pointer or key in the
+page area, or the function it returns. `beforeScroll` runs before each
+correction (hold your scroll spy there); `onRelease` runs once when the pin
+lets go — at once when there is nothing to pin, or no `ResizeObserver` (a
+server). `pinHolds(node)` tells whether the view still shows `node` where the
+pin puts it: at the top, or as near as the area can scroll at its end. A
+scroll that leaves it elsewhere came from find in page, a screen reader's
+cursor or your own `scrollTop`, none of which the pin hears: treat it as the
+user's.
+
+```ts
+import { pinHolds, pinToPage } from '@nxgt/material-core/pdf-viewer';
+
+// pages: Map<number, HTMLElement>; spy: from createScrollSpy
+let pinned = true;
+const unpin = pinToPage(
+  () => pages.get(3), // the page's element, looked up again on each correction
+  () => spy.hold(), // the corrections are not the user's scrolling
+  () => { pinned = false; }, // the pin let go
+);
+
+function onScroll(page: number) {
+  if (pinned && pinHolds(pages.get(3))) return; // still the reader's own scroll
+  unpin(); // the view moved elsewhere: let go, then report
+  reportPage(page);
+}
+```
+
 ### A currency's decimals: `/currency-digits`
 
 ```ts
@@ -377,14 +408,16 @@ and a `data:` URL of an image, video, audio file, plain text, CSV, Markdown,
 JSON or PDF; it returns `null` for anything else (`javascript:`,
 `vbscript:`, `data:text/html`, …), after removing what the browser ignores
 (spaces and control characters at the ends, tabs and newlines anywhere), and
-`FilePreviewUnsafeUrlError` is what `FilePreview` reports for one it refused.
+`FilePreviewUnsafeUrlError` ("Refused to preview a URL with an unsafe
+scheme") is what `FilePreview` reports for one it refused.
 `readTextPreview` reads the first bytes of a `Blob`, or of what a URL answers
 (it stops downloading past the cap), decoded with the `charset` of the
 response's `Content-Type` (or of the `Blob`'s `type`) when `TextDecoder`
 supports it, else as UTF-8, and says whether there was more; an HTTP error
-throws `FilePreviewHttpError` with its `status`, and an aborted `signal`
-rejects with its reason, for a `Blob` too. Nothing runs at import, so it is
-safe on a server; only `readTextPreview` touches `fetch`.
+throws `FilePreviewHttpError` (`Could not read <url>: HTTP <status>`) with
+its `status`, and an aborted `signal` rejects with its reason, for a `Blob`
+too. Nothing runs at import, so it is safe on a server; only
+`readTextPreview` touches `fetch`.
 
 ```ts
 import {
@@ -496,6 +529,8 @@ of `@nxgt/material-vue` adds the files to `nitro.externals.traceInclude`.
 | `Cannot find package '@react-pdf/renderer'` (or `'react'`) when importing `/pdf` or `/pdf/render` | `bun add react @react-pdf/renderer@^4.9` — or import from `/pdf/model` where you only build documents |
 | `Cannot find module '#standard-fonts/Helvetica'` on every request of a bundled server | `pdfkitStandardFonts()` from `/vite`, or keep the renderer external |
 | `Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'` from a traced server output | add `pdfkitStandardFontFiles()` (or the directories' `**/*.cjs`) to the tracer's includes — `withNxgtPrint` and the Nuxt module do |
+| `Could not read <url>: HTTP 401` (`FilePreviewHttpError`) for a file behind authentication | fetch it with your credentials and pass the `Blob` to `readTextPreview` / `FilePreview` |
+| `Refused to preview a URL with an unsafe scheme` (`FilePreviewUnsafeUrlError`) | pass an `https:` or relative URL, or the content as a `Blob` |
 
 Every message, with its cause, is in [troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md).
 

package/docs/roadmap.md

@@ -5,13 +5,7 @@ version an item shipped in is the only number on this page.
 
 ## Now
 
-- **Date range presets and times** (`/date-range`) — the built-in presets'
-  ranges, whether a field's rules rule a range out, and the time of day on
-  each end, for both libraries' `DateRangeField`.
-- **File preview** (`/file-preview`) — which kind of preview a file gets from
-  its MIME type or extension, which URLs it may link to or load, and the
-  first bytes of a text file read with a size cap in its own charset, for
-  both libraries' `FilePreview`.
+Nothing in progress right now; see Next.
 
 ## Next
 
@@ -37,14 +31,24 @@ version an item shipped in is the only number on this page.
 
 ## Shipped
 
+- **Date range presets and times** (`/date-range`) — the built-in presets'
+  ranges, whether a field's rules rule a range out, and the time of day on
+  each end, for both libraries' `DateRangeField`. 0.3.0.
+- **File preview** (`/file-preview`) — which kind of preview a file gets from
+  its MIME type or extension, which URLs it may link to or load, and the
+  first bytes of a text file read with a size cap in its own charset, for
+  both libraries' `FilePreview`. 0.3.0.
+- **Slider ticks** (`/slider-ticks`) — the values a slider's tick marks sit
+  at, which both libraries' `SliderField` (`ticks`) read from here instead of
+  keeping a copy each. 0.3.0.
+- **`formatFileSize` and the pdfkit fonts resolution** — the byte-count
+  formatter both libraries' file list and upload field use
+  (`/format-file-size`), and the Node-only resolution of pdfkit's standard
+  fonts behind `@nxgt/material/next` and `@nxgt/material-vue`'s Nuxt module
+  (`/pdfkit-fonts`), each kept once instead of in both libraries. 0.2.0.
 - **A first release** — the PDF model and renderer, the print formatters,
   the PDF file helpers, the PDF reader's framework-free modules
   (`/pdf-viewer`: search, geometry, page sizes, scroll spy), the currency
   digits, the fields' blur layers and the fonts plugin, which
   `@nxgt/material` and `@nxgt/material-vue` shared file by file, are this one
   package, and both libraries depend on it. 0.1.0.
-- **`formatFileSize` and the pdfkit fonts resolution** — the byte-count
-  formatter both libraries' file list and upload field use
-  (`/format-file-size`), and the Node-only resolution of pdfkit's standard
-  fonts behind `@nxgt/material/next` and `@nxgt/material-vue`'s Nuxt module
-  (`/pdfkit-fonts`), each kept once instead of in both libraries. 0.2.0.

package/docs/troubleshooting.md

@@ -17,6 +17,11 @@ file) is an example — search for the words around it.
 
 - [`PdfReader cannot open …: pass a URL, a Blob, an ArrayBuffer, a Uint8Array or { url, httpHeaders }.`](#pdfreader-cannot-open--pass-a-url-a-blob-an-arraybuffer-a-uint8array-or--url-httpheaders-)
 
+**File preview**
+
+- [`Could not read <url>: HTTP <status>` (`FilePreviewHttpError`)](#could-not-read-url-http-status-filepreviewhttperror)
+- [`Refused to preview a URL with an unsafe scheme` (`FilePreviewUnsafeUrlError`)](#refused-to-preview-a-url-with-an-unsafe-scheme-filepreviewunsafeurlerror)
+
 **Build**
 
 - [`… still references '#standard-fonts/' after the transform — …`](#-still-references-standard-fonts-after-the-transform--)
@@ -92,6 +97,66 @@ yet, or a `Response` instead of its bytes:
 const bytes = await (await fetch(url)).arrayBuffer(); // not the Response
 ```
 
+## File preview
+
+### `Could not read <url>: HTTP <status>` (`FilePreviewHttpError`)
+
+**When:** `readTextPreview(url)` from `/file-preview` — behind both
+libraries' `FilePreview`, for a text, JSON, CSV or Markdown file given as a
+URL — rejects with a `FilePreviewHttpError`, its message the URL as passed
+and the status, as in `Could not read /files/notes.txt: HTTP 404`, and its
+`status` the number. `FilePreview` shows "This file could not be previewed."
+and hands this error to `onError` (`@error` in Vue).
+**Why:** the server answered, but not with a `2xx`: a missing file (`404`),
+a URL that needs credentials the request did not carry (`401`, `403` —
+`fetch` sends cookies to the same origin only, and no `Authorization`
+header), or a server error (`5xx`). Nothing of the body is read.
+**Fix:** check the URL in the message. For a file behind authentication,
+fetch it yourself with your credentials and pass the `Blob`, which is read
+without a request; branch on `status` to tell a missing file from the rest:
+
+```ts
+import { FilePreviewHttpError, readTextPreview } from '@nxgt/material-core/file-preview';
+
+const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+const preview = await readTextPreview(await response.blob()); // a Blob: no request
+
+try {
+  await readTextPreview(url);
+} catch (error) {
+  if (error instanceof FilePreviewHttpError && error.status === 404) showMissing();
+  else throw error;
+}
+```
+
+A cross-origin URL whose server sends no CORS headers is not this error: it
+is `fetch`'s own `TypeError` (`Failed to fetch` in Chrome), with no status.
+
+### `Refused to preview a URL with an unsafe scheme` (`FilePreviewUnsafeUrlError`)
+
+**When:** both libraries' `FilePreview` is given a URL that
+`safePreviewUrl` returns `null` for: it shows "This file could not be
+previewed." with no Download link, and `onError` (`@error` in Vue) receives
+this error. Nothing was linked, loaded or fetched.
+**Why:** only `http:`, `https:`, a relative URL, `blob:` and a `data:` URL
+of an image, video, audio file, plain text, CSV, Markdown, JSON or PDF may
+reach an `href`, a `src` or `fetch`. Anything else — `javascript:`,
+`data:text/html`, `file:`, and also a `data:` URL of XML, TSV or YAML — could
+run script in your page or reach what it should not, so it is refused
+whatever the file would have been. A URL with a colon before its first `/`,
+`?` or `#` (`c:/files/a.txt`) reads as a scheme and is refused too.
+**Fix:** serve the file over `https:` (or from your own origin), or turn its
+content into a `Blob` and pass that — a `Blob` is previewed
+through a `blob:` URL. Check a URL before rendering with `safePreviewUrl`:
+
+```ts
+import { safePreviewUrl } from '@nxgt/material-core/file-preview';
+
+safePreviewUrl('https://example.com/a.csv'); // 'https://example.com/a.csv'
+safePreviewUrl('javascript:alert(1)'); // null
+const file = safePreviewUrl(url) ?? new Blob([text], { type: 'text/yaml' });
+```
+
 ## Build
 
 ### `… still references '#standard-fonts/' after the transform — …`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, the date range presets, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
 	"license": "MIT",
 	"bugs": {