@nxgt/material-vue 0.23.4 → 0.25.0

package/docs/troubleshooting.md

@@ -23,6 +23,7 @@ words in your error.
 - [A `Toc`, `Pager`, `SeeAlso` or `ScrollProgress` inside `Doc` selected by `data-slot` stops matching](#a-toc-pager-seealso-or-scrollprogress-inside-doc-selected-by-data-slot-stops-matching)
 - [A `ResponsiveButton` selected by `[aria-expanded]` stops matching](#a-responsivebutton-selected-by-aria-expanded-stops-matching)
 - [A menu item selected by `[data-variant=destructive]` stops matching](#a-menu-item-selected-by-data-variantdestructive-stops-matching)
+- [A `Stepper` step selected by `#step-N` stops matching](#a-stepper-step-selected-by-step-n-stops-matching)
 - [A test no longer finds a date or time picker by the `button` role, or a slider thumb by the exact name `Minimum`](#a-test-no-longer-finds-a-date-or-time-picker-by-the-button-role-or-a-slider-thumb-by-the-exact-name-minimum)
 - [An end-to-end test no longer finds a required field by a name ending in `*`](#an-end-to-end-test-no-longer-finds-a-required-field-by-a-name-ending-in-)
 - [A test no longer finds `aria-invalid` on an upload field's group or drop zone](#a-test-no-longer-finds-aria-invalid-on-an-upload-fields-group-or-drop-zone)
@@ -30,6 +31,7 @@ words in your error.
 - [A test no longer finds the breadcrumb's home button](#a-test-no-longer-finds-the-breadcrumbs-home-button)
 - [A `QRCode`'s `aria-label` is no longer on its wrapper](#a-qrcodes-aria-label-is-no-longer-on-its-wrapper)
 - [A `CheckboxGroup` or `RadioGroupField` option selected by `#<id>-<value>` stops matching](#a-checkboxgroup-or-radiogroupfield-option-selected-by-id-value-stops-matching)
+- [A `Table`'s `id`, `aria-*` or `style` is no longer on its scrolling container](#a-tables-id-aria--or-style-is-no-longer-on-its-scrolling-container)
 
 **SSR & build**
 
@@ -47,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**
 
@@ -100,6 +107,7 @@ words in your error.
 - [A test no longer finds a pagination, breadcrumb or other built-in label by its English name](#a-test-no-longer-finds-a-pagination-breadcrumb-or-other-built-in-label-by-its-english-name)
 - [A test no longer finds a chip's remove button by the exact name `Remove`, or a `LocationPreview` by its place name](#a-test-no-longer-finds-a-chips-remove-button-by-the-exact-name-remove-or-a-locationpreview-by-its-place-name)
 - [A test no longer finds an icon badge by role `button`, or an `Icon` named "Icon {name}" inside a button](#a-test-no-longer-finds-an-icon-badge-by-role-button-or-an-icon-named-icon-name-inside-a-button)
+- [A button named "Icon plus Add" is now named "Add"](#a-button-named-icon-plus-add-is-now-named-add)
 - [`An invalid form control with name='…' is not focusable` (an `UploadField`)](#an-invalid-form-control-with-name-is-not-focusable)
 - [An `id`, `aria-describedby` or `data-testid` on a `DateField`, `DateRangeField` or `TimeField` is nowhere in the page](#an-id-aria-describedby-or-data-testid-on-a-datefield-daterangefield-or-timefield-is-nowhere-in-the-page)
 - [A test no longer finds the label or helper text inside a date or time picker's trigger](#a-test-no-longer-finds-the-label-or-helper-text-inside-a-date-or-time-pickers-trigger)
@@ -133,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)
 
 ---
@@ -401,6 +412,30 @@ menubar colour had no token, so Tailwind generated nothing).
 [data-slot='dropdown-menu-item'][data-variant='error'] { font-weight: 600; }
 ```
 
+### A `Stepper` step selected by `#step-N` stops matching
+
+**When:** after upgrading to 0.24.0, a test or a stylesheet that targets a
+step by its id — `#step-0`, `page.locator('#step-1')`,
+`document.getElementById('step-2')` — finds nothing.
+**Why:** every `Stepper` gave its steps the same ids, `step-0`, `step-1`, …,
+so two steppers on one page produced duplicate ids, which is invalid HTML and
+breaks any `aria-*` reference to them. Each id is now prefixed with one
+unique to its stepper (Vue's `useId`). The steps are also an `<ol>` of `<li>`
+now, and the current one carries `aria-current="step"`. A selector
+written against the old markup, such as `div[data-slot="stepper-step"]`,
+stops matching too, since a step is now an `li`: drop the tag
+(`[data-slot="stepper-step"]`).
+**Fix:** select by `data-pw`: `step-N`, or `<name>-step-N` when you passed
+`name` — the same values as in `@nxgt/material`, now on each step here too:
+
+```ts
+await page.locator('[data-pw="step-1"]').click();
+// with <Stepper name="checkout" … />
+await page.locator('[data-pw="checkout-step-1"]').click();
+// or the current step
+await expect(page.locator('[aria-current="step"]')).toContainText('Shipping');
+```
+
 ### A test no longer finds a date or time picker by the `button` role, or a slider thumb by the exact name `Minimum`
 
 **When:** after upgrading to 0.22.0, a spec such as
@@ -535,6 +570,36 @@ which a `group` may not carry: assert its description instead,
 hidden hint sits inside the helper element, so match its text with
 `getByText('Pick any.', { exact: false })` or the description with a RegExp.
 
+### A `Table`'s `id`, `aria-*` or `style` is no longer on its scrolling container
+
+**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
+  `<table>` instead, `[data-testid]` / `[aria-label]` queries return the
+  table, a `@scroll` listener on `<Table>` never fires); or
+- a `style` such as `max-height` on `<Table>` no longer limits the height,
+  and the table stops scrolling.
+
+**Why:** `Table` passed every attribute but `class` to its scrolling
+container. It now puts them on the `<table>`, as `@nxgt/material` does, so
+`aria-busy`, `aria-label` or `id` describe the table itself. A
+`max-height` on a `<table>` has no effect: the table grows instead of
+scrolling.
+**Fix:** select the container by its slot, or the table by role, and put a
+height limit on a wrapper of your own:
+
+```vue
+<div class="max-h-96 overflow-auto">
+  <Table aria-label="Orders">…</Table>
+</div>
+```
+
+```ts
+page.getByRole('table', { name: 'Orders' });
+page.locator('[data-slot="table-container"]'); // the scrolling container
+```
+
 ### An end-to-end test no longer finds a required field by a name ending in `*`
 
 **When:** after upgrading to 0.22.0, `getByRole('textbox', { name: 'Email*' })`
@@ -909,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
@@ -1486,6 +1597,26 @@ const filter = useFilterContext(); // fine: this component is below FilterProvid
 </template>
 ```
 
+For a documentation shell of your own (`DocNav`, `DocArticle`, `DocLink`
+without `<Doc>`), provide the state yourself in the component that renders
+the parts:
+
+```vue
+<script setup lang="ts">
+import { type DocNavItem, provideDoc, useDoc } from '@nxgt/material-vue/components';
+
+const props = defineProps<{ items: DocNavItem[]; pathname: string }>();
+provideDoc(
+  useDoc({
+    items: props.items,
+    get pathname() {
+      return props.pathname;
+    },
+  }),
+);
+</script>
+```
+
 ### `Clipboard is not available`
 
 **When:** calling `copyToClipboard(value)` on a page served over plain `http`
@@ -1728,6 +1859,33 @@ await expect(page.getByRole('img', { name: 'Phone' })).toBeVisible();
 await page.getByRole('button', { name: 'Delete' }).click();
 ```
 
+### A button named "Icon plus Add" is now named "Add"
+
+**When:** after upgrading to 0.24.0, `getByRole('button', { name: 'Icon plus Add' })`
+(or any name that starts with "Icon {name}") finds nothing, or a
+`getByRole('img', { name: 'Icon plus' })` inside a `Button` that also has text.
+**Why:** an `Icon` is named "Icon {name}" by default, and a `Button` takes its
+name from its content, so a `Button` holding an `Icon` and the text "Add" was
+announced "Icon plus Add". A `Button` with text, an `aria-label` or an
+`aria-labelledby` now hides an `Icon` inside it (`aria-hidden="true"`), as a
+named `IconButton` already did. A `Button` holding only an `Icon` still reads
+it, since that is the only name it has; give it an `aria-label` instead. Text
+a component produces from its props (a translation component) is not seen:
+pass the button an `aria-label` then. Text inside an `aria-hidden` element
+(a decorative count, `<span aria-hidden="true">3</span>`) does not name the
+button either, so beside it the `Icon` stays named.
+**Fix:** select the button by its text:
+
+```ts
+await page.getByRole('button', { name: 'Add' }).click();
+```
+
+and name an icon-only button yourself:
+
+```vue
+<Button aria-label="Add"><Icon name="plus" /></Button>
+```
+
 ### `An invalid form control with name='…' is not focusable`
 
 **When:** submitting a form with an empty `required` `UploadField`, with
@@ -2275,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

@@ -99,6 +99,7 @@ export const COMPONENT_NAMES = [
 	'CheckCardField',
 	'CheckCardFormField',
 	'Checkbox',
+	'CheckboxFormField',
 	'CheckboxGroup',
 	'CheckboxGroupFormField',
 	'ChecklistCard',
@@ -107,6 +108,7 @@ export const COMPONENT_NAMES = [
 	'CodeBlock',
 	'CodeDiff',
 	'CodeEditor',
+	'CodeEditorFormField',
 	'CodeGroup',
 	'Collapsible',
 	'CollapsibleContent',
@@ -146,6 +148,7 @@ export const COMPONENT_NAMES = [
 	'ContextMenuSubTrigger',
 	'ContextMenuTrigger',
 	'CopyButton',
+	'CopyValue',
 	'CountBadge',
 	'CountryField',
 	'CountryFormField',
@@ -162,6 +165,7 @@ export const COMPONENT_NAMES = [
 	'DateFormField',
 	'DateRangeField',
 	'DateRangeFormField',
+	'DefaultDocLink',
 	'DeltaListCard',
 	'Description',
 	'Dialog',
@@ -177,10 +181,14 @@ export const COMPONENT_NAMES = [
 	'DndOverlay',
 	'DndProvider',
 	'Doc',
+	'DocArticle',
 	'DocChildCards',
 	'DocCopyMarkdown',
+	'DocCopyPage',
 	'DocEmpty',
 	'DocHeader',
+	'DocLink',
+	'DocNav',
 	'DocPage',
 	'DocPager',
 	'DocProgress',
@@ -239,6 +247,8 @@ export const COMPONENT_NAMES = [
 	'FileListFormField',
 	'FileListS3Field',
 	'FileListS3FormField',
+	'FilePreview',
+	'FilesFormField',
 	'Filter',
 	'FilterActions',
 	'FilterChips',
@@ -280,6 +290,7 @@ export const COMPONENT_NAMES = [
 	'ImageS3Field',
 	'ImageS3FormField',
 	'InlineEdit',
+	'InlineEditFormField',
 	'Input',
 	'InputGroup',
 	'InputGroupAddon',
@@ -328,6 +339,7 @@ export const COMPONENT_NAMES = [
 	'MenubarSubContent',
 	'MenubarSubTrigger',
 	'MenubarTrigger',
+	'MermaidDiagram',
 	'MessageCard',
 	'MiniGallery',
 	'NativeSelect',
@@ -351,11 +363,13 @@ export const COMPONENT_NAMES = [
 	'PaceCard',
 	'Pager',
 	'Pagination',
+	'PaginationBar',
 	'PaginationContent',
 	'PaginationEllipsis',
 	'PaginationFirst',
 	'PaginationItem',
 	'PaginationLast',
+	'PaginationLink',
 	'PaginationNext',
 	'PaginationPrevious',
 	'PaneLayout',
@@ -555,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.23.4",
+	"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",