@nxgt/material-core 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# @nxgt/material-core
+
+## 0.3.2
+
+### Patch Changes
+
+- [#429](https://github.com/softistx/nxgt-material/pull/429) [`13c3eda`](https://github.com/softistx/nxgt-material/commit/13c3edad01f08656ca196aca7c37a21e8c003466) Thanks [@SteveGT96](https://github.com/SteveGT96)! - The package ships its `CHANGELOG.md` (now in `files`), so the notes of every
+  version are in `node_modules/<package>/CHANGELOG.md` next to the docs, for
+  reading offline and for the upgrade agents of the Claude Code plugins.
+  The getting-started pages of `@nxgt/material` and `@nxgt/material-vue`
+  list it among the tarball's contents.
+
+## 0.3.1
+
+### Patch Changes
+
+- [#427](https://github.com/softistx/nxgt-material/pull/427) [`d4e953f`](https://github.com/softistx/nxgt-material/commit/d4e953fd4fc147b366c5d9d70ebfb1aa3a3c0ba7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Docs: the roadmap lists what 0.3.0 shipped (`/date-range`, `/file-preview`, `/slider-ticks`) under Shipped, newest first. Troubleshooting has entries for `FilePreviewHttpError` (`Could not read <url>: HTTP <status>`) and `FilePreviewUnsafeUrlError` (`Refused to preview a URL with an unsafe scheme`), so every message the package prints is there again. The README's `/pdf-viewer` section documents `pinToPage`'s `onRelease` and `pinHolds`, with an example.
+
+## 0.3.0
+
+### Minor Changes
+
+- [#424](https://github.com/softistx/nxgt-material/pull/424) [`d90a68b`](https://github.com/softistx/nxgt-material/commit/d90a68b8f16759b44929effc426b6c3964e92a4c) Thanks [@SteveGT96](https://github.com/SteveGT96)! - New subpath `/date-range`, the pure half of both libraries' `DateRangeField`
+  presets and times: `DATE_RANGE_PRESET_IDS` (`today`, `yesterday`,
+  `last-7-days`, `last-30-days`, `this-month`, `last-month`, `this-year`),
+  `presetRange(id, now?)`, `resolvePresetRange(preset, now?, { withTime })`,
+  `isSameDayRange`, `isRangeDisabled(range, { min, max, isDayDisabled })`
+  (also true for a range whose end comes before its start),
+  `withTimeOf`, `endOfDayTime`, `clampRangeEnd`, `keepRangeTimes` (a new end
+  at 23:59), and the types
+  `DayRange`, `PartialDayRange`, `DateRangePreset`, `DateRangePresetId`,
+  `DateRangePresetOption` and `DateRangeRules`.
+
+- [#426](https://github.com/softistx/nxgt-material/pull/426) [`812c101`](https://github.com/softistx/nxgt-material/commit/812c10115278480852852084ddf06b016239e6d4) Thanks [@SteveGT96](https://github.com/SteveGT96)! - New subpath `/file-preview`, the pure half of both libraries' `FilePreview`:
+  `fileKind({ type, name, url })` picks a `FileKind` (`image`, `pdf`, `video`,
+  `audio`, `text`, `json`, `csv`, `markdown` or `other`) from the MIME type
+  when it names one (a `data:` URL's included), else from the extension of the
+  name, then of the URL; `describeFile(file, { type, name })` does it for a
+  `File` / `Blob` or a URL and returns its name, type and size;
+  `safePreviewUrl(url)` returns the URL when it may reach an `href` or a `src`
+  (`http(s):`, relative, `blob:`, or a `data:` URL of an image, video, audio
+  file, plain text, CSV, Markdown, JSON or PDF) and `null` for anything else
+  (`javascript:`, `data:text/html`, and also a `data:` URL of XML, TSV or
+  YAML), with `FilePreviewUnsafeUrlError` ("Refused to preview a URL with an unsafe scheme") for the one refused;
+  `readTextPreview(source, { maxBytes, signal })` reads the first `maxBytes`
+  (`TEXT_PREVIEW_MAX_BYTES`, 256 KB, by default) of a `Blob` or of what a URL
+  answers, decoded with the `charset` of the `Content-Type` (or of the `Blob`'s
+  `type`) when `TextDecoder` supports it and as UTF-8 otherwise, stopping the
+  download past the cap; it throws `FilePreviewHttpError` (with its `status`)
+  on an HTTP error, and rejects with the signal's reason once aborted, for a
+  `Blob` too. Also
+  `fileExtension`, `fileNameFromUrl`, `dataUrlType`, `kindOfMimeType`,
+  `normaliseMimeType`, `isTextFileKind`, `TEXT_FILE_KINDS` and the types
+  `FileKind`, `FileKindInput`, `DescribedFile`, `FilePreviewSource` and
+  `TextPreview`. Nothing runs at import.
+
+- [#420](https://github.com/softistx/nxgt-material/pull/420) [`f4ca69b`](https://github.com/softistx/nxgt-material/commit/f4ca69ba5dd7b80f92cdd5374cf6fd01f155784d) Thanks [@SteveGT96](https://github.com/SteveGT96)! - New subpath `/slider-ticks`: `tickValues(min, max, ticks, step?)`, the values a slider's tick marks sit at. Both libraries' `SliderField` (`ticks`) now read it from here instead of keeping a copy each.
+
+### Patch Changes
+
+- [#419](https://github.com/softistx/nxgt-material/pull/419) [`99878c9`](https://github.com/softistx/nxgt-material/commit/99878c9bdb0d4c33fd6a777970c4f3735bd5ef3b) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `PdfReader`: opening on an `initialPage` no longer reports another page on a
+  slow device. The placement scroll could land after the scroll spy's hold had
+  run out, and near the end of the document it read as the last page. While
+  the view stays where the opening page's pin put it (that page at the top,
+  or the page area at its end with that page not above the top), a scroll is the reader's own and is not
+  reported; a scroll that moves the view elsewhere — the user's, find in page,
+  a screen reader's cursor — lets go of the pin and is reported. A wheel,
+  touch, pointer or key in the page area also ends the hold on the reader's
+  own scroll, so the scrolling after it is reported at once. In
+  `@nxgt/material-core/pdf-viewer`, `pinToPage` takes an optional `onRelease`,
+  called once when the pin lets go, and `pinHolds(node)` tells whether the view
+  is still where the pin puts it.
+
+## 0.2.0
+
+### Minor Changes
+
+- [#406](https://github.com/softistx/nxgt-material/pull/406) [`b890457`](https://github.com/softistx/nxgt-material/commit/b8904573f18dc6d0cdd16f62146183ff0b7aef18) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Two new subpaths, each the one copy of code `@nxgt/material` and
+  `@nxgt/material-vue` used to keep twice:
+  
+  - **`@nxgt/material-core/format-file-size`**: `formatFileSize(bytes)`, the
+    byte count both libraries' `FileList`, `NetworkUploadField`, `FileCard` and
+    chat attachments show (`'1.5 KB'`; `''` for a negative, `NaN` or infinite
+    size).
+  - **`@nxgt/material-core/pdfkit-fonts`** (Node only): `pdfkitStandardFontDirs`,
+    `pdfkitStandardFontFiles` and `PDFKIT_STANDARD_FONTS` find the real files of
+    pdfkit's standard fonts as an app loads them, through `@react-pdf/renderer`
+    and `@react-pdf/font`, for a server tracer (`@nxgt/material/next`, the Nuxt
+    module of `@nxgt/material-vue`). Without `@react-pdf/renderer` they return
+    `[]` silently; any other failure reaches your `warn` callback once per
+    call. It is the only subpath that imports `node:` built-ins: never import it
+    from browser code.
+  
+  ```ts
+  import { formatFileSize } from '@nxgt/material-core/format-file-size';
+  import { pdfkitStandardFontDirs } from '@nxgt/material-core/pdfkit-fonts';
+  
+  formatFileSize(1536); // '1.5 KB'
+  pdfkitStandardFontDirs(process.cwd(), console.warn); // ['/app/node_modules/pdfkit/js/standard-fonts']
+  ```
+
+### Patch Changes
+
+- [#407](https://github.com/softistx/nxgt-material/pull/407) [`bf43a14`](https://github.com/softistx/nxgt-material/commit/bf43a14abb147e6dcd2bcac5f1e0e359b0aae6a2) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `pdfkitStandardFontDirs` and `pdfkitStandardFontFiles` (`/pdfkit-fonts`) keep
+  only the first line of each error in the one warning they give. Node's
+  `Cannot find module` error carries a multi-line `Require stack:`, and joined
+  whole into the `; `-separated message it made one warning dozens of lines
+  long; it now reads `could not resolve @react-pdf/font: Error: Cannot find
+  module '@react-pdf/font'; could not resolve pdfkit's fonts for …`.
+
+## 0.1.1
+
+### Patch Changes
+
+- [#399](https://github.com/softistx/nxgt-material/pull/399) [`1abb908`](https://github.com/softistx/nxgt-material/commit/1abb90800ec213d8ec98abd7df5dda9f65c14204) Thanks [@SteveGT96](https://github.com/SteveGT96)! - The package manifest no longer carries a `repository` field. The source
+  repository is private, so the link npm showed for it led to a 404; the
+  README and the `docs/` shipped in the tarball remain the public reference.
+
+- [#398](https://github.com/softistx/nxgt-material/pull/398) [`b4e5770`](https://github.com/softistx/nxgt-material/commit/b4e5770922ad4582a1ad2dcca439f7c8c999a0c7) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Docs: the roadmap's Shipped list now has 0.1.0 — the first release, holding the framework-free code `@nxgt/material` and `@nxgt/material-vue` share.
+
+## 0.1.0
+
+### Minor Changes
+
+- [#391](https://github.com/softistx/nxgt-material/pull/391) [`deaf0c4`](https://github.com/softistx/nxgt-material/commit/deaf0c49cbc2268fd20e9e2272104dbd27e4ce7f) Thanks [@SteveGT96](https://github.com/SteveGT96)! - First release of `@nxgt/material-core`: the framework-free core that
+  `@nxgt/material` (React) and `@nxgt/material-vue` (Vue) share, as one copy.
+  The PDF document model (`/pdf/model`) and its react-pdf renderer
+  (`/pdf/render`, both also from `/pdf`), the print formatters (`/print-format`, `/print-value`,
+  `/print-table`, `/print-fraction-digits`), the PDF file helpers
+  (`/pdf-source`, `/pdf-file-name`, `/pdf-download`), serving a PDF
+  (`/pdf/http`, `/pdf/file-loader`), the PDF viewer's framework-free modules
+  (`/pdf-viewer`: page geometry, page sizes, scroll spy, text search), the
+  currency field's decimals (`/currency-digits`), the fields' blur layers
+  (`/field-blur-layers`) and the pdfkit fonts plugin (`/vite`).
+  `react` and `@react-pdf/renderer` are optional peers, needed only to render;
+  `vite` (6, 7 or 8) is one too, for the types of `/vite`.
+  Most apps get it through `@nxgt/material` or `@nxgt/material-vue`; a server
+  bundle that inlines either library (`ssr.noExternal`) must list
+  `@nxgt/material-core` beside it.

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.2",
 	"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": {
@@ -13,6 +13,7 @@
 		"dist",
 		"docs",
 		"README.md",
+		"CHANGELOG.md",
 		"package.json",
 		"LICENSE"
 	],