@nxgt/material-vue 0.24.0 → 0.25.0

package/docs/roadmap.md

@@ -6,31 +6,22 @@ the version something shipped in.
 
 ## Now
 
-- **Spinner `light` colour renders** — a `Spinner` with `color="light"` shows
-  its light ring, for loading states on dark or coloured surfaces.
-- **Range filters announce their field name** — the slider thumbs and the
-  `Min`/`Max` inputs of a `slider-range` or `number-range` filter are named
-  after the field, so a screen reader says which range is changing.
-- **Alert keeps long content inside** — a long title, description or unbroken
-  string wraps inside the `Alert` instead of running past its edge.
-- **Slider thumb follows the theme in dark mode** — the `Slider` thumb takes
-  the dark theme's colours instead of staying light. Vue only.
-- **Stepper: unique ids, announced steps and truncated titles** — two steppers
-  on one page no longer share ids, a screen reader hears which step is current
-  and whether each is done or in error, and a long step title truncates.
-- **Layouts that hold long content** — `ListTile`, `StatCard` and `Banner`
-  keep long titles, values and actions inside their box instead of overflowing.
-- **The same exports as `@nxgt/material`** — a `Checkbox` with its own
-  `label` and `helper-text` (the bare box is unchanged) and
-  `CheckboxFormField`, `InlineEditFormField`, `CodeEditorFormField`,
-  `PaginationBar` with `paginationItems` and `PaginationLink`, `CopyValue`,
-  `MermaidDiagram`, and the `Doc` parts `DocArticle`, `DocNav`, `DocLink`,
-  `DefaultDocLink` and `DocCopyPage`, under the names they have in React.
-  ([forms](guides/forms.md#what-each-field-emits))
-- **DataTable loading and empty states** — skeleton rows while the data loads
-  (the rows already shown stay in place, dimmed, during a refresh), the table
-  announced as busy, and your own content when there are no rows, told
-  whether a filter emptied it.
+- **TreeSelectField** — pick one or several items from a tree inside a form
+  field, as chips when several, with an optional filter that keeps each match
+  under its ancestors (`TreeSelectField`, `TreeSelectFormField`).
+- **The same options as `@nxgt/material`** — a generic `Autocomplete` and
+  `FilesFormField` typed by your items, a `ConfirmationDialog` that holds a
+  form, date fields that disable chosen days, `SliderField` ticks and
+  leading/trailing content, a presence status on `Avatar`, a logo slot on the
+  QR code, slots on `AccordionCard`, an option slot on `SelectField`, Monaco's
+  own options on `CodeEditor` and a line variant for `Tabs`.
+- **DateRangeField presets and time** — one-click ranges such as Today, Last 7
+  days and This month, or your own, beside the calendar (`presets`), and a time
+  of day on each end of the range (`with-time`), and `min-date` / `max-date`.
+- **FilePreview** — preview a file picked by its type, in one component: an
+  image, a PDF in `PdfReader`, a video or audio file, the text of a text, JSON,
+  CSV or Markdown file, or a card with a download link for anything else
+  (`FilePreview`, `@error`). Safe on a server.
 
 ## Next
 
@@ -40,18 +31,6 @@ the version something shipped in.
   Vue only: `@nxgt/material`'s print blocks already produce a PDF.
 - **`StepperIndicator`, as in `@nxgt/material`** — the step markers on their
   own, for a stepper laid out your way.
-- **The same options as `@nxgt/material`** — a generic `Autocomplete` and
-  `FilesFormField` typed by your items, a `ConfirmationDialog` that holds a
-  form, date fields that disable chosen days, `SliderField` ticks and
-  leading/trailing content, a presence status on `Avatar`, a logo in the QR
-  code, slots on `AccordionCard`, an option slot on `SelectField`, editor
-  options on `CodeEditor` and a line variant for `Tabs`.
-- **DateRangeField presets and time** — one-click ranges such as Today, Last 7
-  days and This month, and a time of day on each end of the range.
-- **TreeSelectField** — pick one or several items from a tree inside a form
-  field.
-- **FilePreview** — preview an image, PDF, video or text file, chosen by its
-  type, in one component.
 
 ## Later
 
@@ -128,6 +107,33 @@ the version something shipped in.
 
 ## Shipped
 
+- **Spinner `light` colour renders** — a `Spinner` with `color="light"` shows
+  its light ring, for loading states on dark or coloured surfaces. 0.24.0.
+- **Range filters announce their field name** — the slider thumbs and the
+  `Min`/`Max` inputs of a `slider-range` or `number-range` filter are named
+  after the field, so a screen reader says which range is changing. 0.24.0.
+- **Alert keeps long content inside** — a long title, description or unbroken
+  string wraps inside the `Alert` instead of running past its edge. 0.24.0.
+- **Slider thumb follows the theme in dark mode** — the `Slider` thumb takes
+  the dark theme's colours instead of staying light. Vue only. 0.24.0.
+- **Stepper: unique ids, announced steps and truncated titles** — two steppers
+  on one page no longer share ids, a screen reader hears which step is current
+  and whether each is done or in error, and a long step title truncates. 0.24.0.
+- **Layouts that hold long content** — `ListTile`, `StatCard` and `Banner`
+  keep long titles, values and actions inside their box instead of overflowing.
+  0.24.0.
+- **The same exports as `@nxgt/material`** — a `Checkbox` with its own
+  `label` and `helper-text` (the bare box is unchanged) and
+  `CheckboxFormField`, `InlineEditFormField`, `CodeEditorFormField`,
+  `PaginationBar` with `paginationItems` and `PaginationLink`, `CopyValue`,
+  `MermaidDiagram`, and the `Doc` parts `DocArticle`, `DocNav`, `DocLink`,
+  `DefaultDocLink` and `DocCopyPage`, under the names they have in React.
+  0.24.0.
+  ([forms](guides/forms.md#what-each-field-emits))
+- **DataTable loading and empty states** — skeleton rows while the data loads
+  (the rows already shown stay in place, dimmed, during a refresh), the table
+  announced as busy, and your own content when there are no rows, told
+  whether a filter emptied it. 0.24.0.
 - **One copy of the framework-free code, shared with `@nxgt/material`** —
   the PDF document model and renderer, the print formatters, the PDF file
   helpers, `PdfReader`'s page geometry, scroll spy and search, the

package/docs/troubleshooting.md

@@ -49,6 +49,11 @@ words in your error.
 - [A `*FormField` is missing from the submitted values, or never shows an error](#a-formfield-is-missing-from-the-submitted-values-or-never-shows-an-error)
 - [`meta.touched` stays false after leaving a field](#metatouched-stays-false-after-leaving-a-field)
 - [A multi-step form reopens at a later step](#a-multi-step-form-reopens-at-a-later-step)
+- [The form could not be loaded.](#the-form-could-not-be-loaded)
+
+**TypeScript**
+
+- [`does not satisfy the constraint 'abstract new (...args: any) => any'`](#does-not-satisfy-the-constraint-abstract-new-args-any--any)
 
 **Printing**
 
@@ -136,6 +141,9 @@ words in your error.
 - [A PDF page shows sideways in `PdfReader`](#a-pdf-page-shows-sideways-in-pdfreader)
 - [The zoom changes by itself while a long PDF is open](#the-zoom-changes-by-itself-while-a-long-pdf-is-open)
 - [`@page-change` is not called when `initialPage` is past the end, or after a new file](#page-change-is-not-called-when-initialpage-is-past-the-end-or-after-a-new-file)
+- [`@page-change` reports another page after opening on `initialPage`](#page-change-reports-another-page-after-opening-on-initialpage)
+- [`FilePreview` shows a file card with a Download link for a PDF](#filepreview-shows-a-file-card-with-a-download-link-for-a-pdf)
+- [`FilePreview` says "This file could not be previewed."](#filepreview-says-this-file-could-not-be-previewed)
 - [Reporting a bug](#reporting-a-bug)
 
 ---
@@ -564,7 +572,7 @@ hidden hint sits inside the helper element, so match its text with
 
 ### A `Table`'s `id`, `aria-*` or `style` is no longer on its scrolling container
 
-**When:** after upgrading, either:
+**When:** after upgrading to 0.24.0, either:
 
 - a selector or listener aimed at the attributes you put on `<Table>` finds
   nothing on `div[data-slot="table-container"]` (`#orders` matches the
@@ -966,6 +974,52 @@ In an SSR app the server renders step 0. A client hydrating that page renders
 step 0 too and resumes at the stored step once mounted, so hydration matches
 without `clientOnly`: see [forms](guides/forms.md#a-multi-step-form).
 
+### The form could not be loaded.
+
+**When:** a `ConfirmationDialog` with `form-options` shows this line
+("Le formulaire n’a pas pu être chargé." in French,
+`material.confirm-dialog.form-failed`) where its form should be, and its
+confirm button stays disabled. The form's code is a separate chunk, loaded the
+first time such a dialog renders it, and that load failed twice: the browser
+was offline, or a deploy removed the chunk the page still names.
+**Why:** each dialog tries the load once more after a failure, then gives up
+and keeps that result: reopening the same dialog shows the message again
+without a new attempt. A dialog rendered anew (another page, a remounted
+component) tries again from the start.
+**Fix:** reload the page — after a deploy, that fetches the new chunk names.
+If it keeps happening, check that your server or CDN serves the chunk that holds
+the dialog's form (its name usually starts with `form-scope`) with the rest of
+the same build, and keeps the previous build's chunks for pages already open.
+
+## TypeScript
+
+### `does not satisfy the constraint 'abstract new (...args: any) => any'`
+
+**When:** `vue-tsc` on code that types a template ref with
+`InstanceType<typeof Autocomplete>` (or `AutocompleteFormField`,
+`ConfirmationDialog`, `FilesFormField`). The whole message reads:
+
+```text
+error TS2344: Type '<T extends AutocompleteOption = AutocompleteOption>(__VLS_props: …) => …' does not satisfy the constraint 'abstract new (...args: any) => any'.
+  … provides no match for the signature 'new (...args: any): any'.
+```
+
+**Why:** these four components are generic (`<script setup generic>`): your
+option type, or your form schema, types their props and slots. A generic
+component's default export is a function, not a component constructor, so
+`InstanceType` has nothing to read.
+**Fix:** use `ComponentExposed` from `vue-component-type-helpers` (the helpers
+`vue-tsc` itself ships; add it as a dev dependency if your app does not list
+it):
+
+```ts
+import { useTemplateRef } from 'vue';
+import type { ComponentExposed } from 'vue-component-type-helpers';
+import { Autocomplete } from '@nxgt/material-vue/components';
+
+const field = useTemplateRef<ComponentExposed<typeof Autocomplete>>('field');
+```
+
 ## Printing
 
 ### The table header and the total row print blank
@@ -2379,6 +2433,61 @@ last page without reporting it; or `file` changes and the reader goes back to
 to itself. Since 0.22.0 both are reported, once.
 **Fix:** update `@nxgt/material-vue`. A page you kept in sync by hand can go.
 
+### `@page-change` reports another page after opening on `initialPage`
+
+**When:** the reader opens on `initialPage` and, without the user scrolling,
+`@page-change` reports another page, most often the last one, and the page field
+shows it. Seen on slow devices and busy machines, near the end of a
+document, with `@nxgt/material-vue` 0.24.0 and earlier.
+**Why:** after placing the opening page, the reader ignored scrolling for
+only 150 ms. When the placement scroll landed later (a late frame), it was
+read as the user's, and at the end of the pages that is the last page.
+**Fix:** update `@nxgt/material-vue`. The opening page now keeps the page number while
+the view stays on it; the user's own scroll, find in page or a screen
+reader moving the view still report the page they reach.
+
+### `FilePreview` shows a file card with a Download link for a PDF
+
+**When:** a PDF given to `FilePreview` shows its name, size and a Download
+link instead of the reader.
+**Why:** `FilePreview` imports `PdfReader` the first time it previews a PDF,
+and falls back to the file card when that import fails: the viewer's chunk
+could not be fetched (a deploy replaced the chunks the open page was built
+with, or a network error), or the bundle has no `pdfjs-dist` — they are
+dependencies of `@nxgt/material-vue`, not optional peers, so this is a bundler
+configuration that left them out. Nothing is thrown; the next PDF previewed
+tries again.
+**Fix:** reload the page after a deploy; otherwise check that your bundler
+keeps `pdfjs-dist` and pdf.js's worker (see `PdfReader` in
+[Media & files](components/media-and-files.md#pdfreader)). The same file in a
+`PdfReader` of its own shows the underlying error. A PDF the reader loaded
+but cannot open (a corrupt or password-protected file, a URL that answers an
+error page) is different: the preview stays `ready` and `PdfReader` shows its
+own error inside it.
+
+### `FilePreview` says "This file could not be previewed."
+
+**When:** a `FilePreview` given a URL, or a file it cannot show, renders that
+message (and `@error` receives the error).
+**Why:** a text, JSON, CSV or Markdown URL is fetched with `fetch`: an HTTP
+error is a `FilePreviewHttpError` with its `status`, and a cross-origin URL
+without CORS headers is a `TypeError: Failed to fetch`. An image, video or
+audio file the browser cannot decode (a corrupt file, a codec the browser
+lacks, a URL that answers an error page) fails in its own element. A URL
+that is not `http(s):`, relative, `blob:`, or a `data:` URL of an image,
+video, audio file, plain text, CSV, Markdown, JSON or PDF (`javascript:`,
+`data:text/html`, and also a `data:` URL of XML, TSV or YAML, though
+`FilePreview` would show those kinds from a `Blob`) is refused before
+anything is linked, loaded or fetched: the error is a
+`FilePreviewUnsafeUrlError`, "Refused to preview a URL with an unsafe scheme", and there is no
+Download link.
+**Fix:** serve the file with `Access-Control-Allow-Origin` for your page's
+origin, or fetch it yourself (with your credentials) and pass the `Blob`;
+pass `type` when the server answers `application/octet-stream` for a file
+whose URL has no extension; pass a refused URL's file as a `Blob`, or from
+an `https:` URL. A text file larger than `max-text-bytes` is not an error: its
+beginning is shown, with "Showing the first … of this file." below.
+
 ---
 
 ## Reporting a bug

package/lib/nuxt/component-names.ts

@@ -247,6 +247,8 @@ export const COMPONENT_NAMES = [
 	'FileListFormField',
 	'FileListS3Field',
 	'FileListS3FormField',
+	'FilePreview',
+	'FilesFormField',
 	'Filter',
 	'FilterActions',
 	'FilterChips',
@@ -567,6 +569,8 @@ export const COMPONENT_NAMES = [
 	'TransferListFormField',
 	'Tree',
 	'TreeItem',
+	'TreeSelectField',
+	'TreeSelectFormField',
 	'TrendCard',
 	'Typography',
 	'UploadField',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material-vue",
-	"version": "0.24.0",
+	"version": "0.25.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -118,7 +118,7 @@
 		"docs:previews": "vitest run --project previews"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.2.0",
+		"@nxgt/material-core": "^0.3.0",
 		"@floating-ui/dom": "^1.8.0",
 		"@fortawesome/fontawesome-common-types": "7.3.1",
 		"@lucide/vue": "^1.45.0",