@nxgt/material-core 0.2.0 → 0.3.1

package/docs/roadmap.md

@@ -31,14 +31,24 @@ Nothing in progress right now; see Next.
 
 ## 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,7 +1,7 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.2.0",
-	"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 pdfkit fonts Vite plugin and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
+	"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": {
 		"email": "stevegires@gmail.com"
@@ -97,6 +97,21 @@
 			"import": "./dist/lib/format-file-size.js",
 			"default": "./dist/lib/format-file-size.js"
 		},
+		"./slider-ticks": {
+			"types": "./dist/lib/slider-ticks.d.ts",
+			"import": "./dist/lib/slider-ticks.js",
+			"default": "./dist/lib/slider-ticks.js"
+		},
+		"./date-range": {
+			"types": "./dist/lib/date-range.d.ts",
+			"import": "./dist/lib/date-range.js",
+			"default": "./dist/lib/date-range.js"
+		},
+		"./file-preview": {
+			"types": "./dist/file-preview/index.d.ts",
+			"import": "./dist/file-preview/index.js",
+			"default": "./dist/file-preview/index.js"
+		},
 		"./pdf-viewer": {
 			"types": "./dist/pdf-viewer/index.d.ts",
 			"import": "./dist/pdf-viewer/index.js",
@@ -157,6 +172,9 @@
 			"src/lib/currency-digits.ts",
 			"src/lib/field-blur-layers.ts",
 			"src/lib/format-file-size.ts",
+			"src/lib/slider-ticks.ts",
+			"src/lib/date-range.ts",
+			"src/file-preview/index.ts",
 			"src/pdf-viewer/index.ts",
 			"src/vite/index.ts",
 			"src/pdfkit-fonts/index.ts"