@nxgt/material 2.1.0 → 2.2.0

package/docs/roadmap.md

@@ -0,0 +1,208 @@
+# Roadmap
+
+What is being worked on, what is likely to follow, and what has been decided
+against. This is a direction, not a commitment: the only number on this page is
+the version something shipped in.
+
+## Now
+
+Nothing in progress right now; see Next.
+
+## Next
+
+- **Dark-mode previews** — each component preview also shown in the dark theme,
+  so you can check contrast without running it.
+- **Previews that cannot go stale** — a CI check that fails when a story changes
+  but its preview image does not, so the picture in the docs is the component
+  you install.
+
+## Later
+
+- **3.0: the same amounts and dates on every machine** — `formatAmount` and
+  `formatDate` stop falling back to the runtime's locale when you pass none, so
+  a server and a browser always print the same string.
+- **3.0: react-hook-form becomes optional** — a `@nxgt/material/forms` subpath
+  with react-hook-form as an optional peer, carrying the `*FormField` wrappers,
+  `ConfirmationDialog` and the attribute editors, so an app without
+  react-hook-form never installs it. `ContactItem` and `OpeningHoursItem`,
+  deprecated in 2.x, are removed then: use `ContactsFormField` and
+  `OpeningHoursFormField`.
+  The `Switch` row's misspelt `data-filed` attribute goes too: select
+  `[data-checked="true"]` instead. `DateField` / `DateRangeField` stop
+  accepting a day rule as `disabled`: pass it as `disabledDays`.
+- **Multi-month calendar with custom caption** — the month, caption and grid
+  slots together with `numberOfMonths` greater than one; today that combination
+  is not supported.
+- **Range filters in generated filter forms** — slider ranges and number ranges
+  rendered by the schema-driven filter fields, not only by hand-written ones.
+- **Ready-made documents** — invoice, quote, receipt, report, certificate and
+  label-sheet templates that take your data and return a document, their labels
+  translated.
+- **Your brand on the page** — a print theme whose defaults follow the screen
+  theme, and your own font files registered in one call (the library bundles
+  no fonts).
+- **QR codes, barcodes and charts in a PDF** — pass the value or the chart
+  options and get vector output, no data URL to prepare.
+- **Rich text and Markdown in a PDF** — the rich-text editor's content and
+  Markdown rendered as PDF headings, paragraphs, lists, tables and links.
+- **A live preview inside `PdfReader`** — `PdfReader` takes a document and
+  renders it itself, refreshing a moment after its data stops changing. Today
+  `usePdfFile` and a `PdfReader` given its `url` make the preview by hand.
+- **Test helpers for generated PDFs** — read a generated PDF's text, page count
+  and metadata in a unit test, without a browser.
+- **Archive-ready PDFs** — PDF/A output through one option, for invoices and
+  records that must be kept.
+- **Electronic invoices (Factur-X)** — an invoice PDF that carries its
+  machine-readable data, built on archive-ready PDFs and the invoice template,
+  for e-invoicing mandates such as France's.
+
+## Not planned
+
+- **Shipping the Font Awesome Pro sprite sheets** — the Pro licence covers use
+  in your own products, not redistribution inside a library. Serve the sheets
+  from your app; the package's `files` excludes them so a build cannot leak
+  them.
+- **A separate package for the map (or any browser-only widget)** — it existed
+  as `@nxgt/map` and pinned `@nxgt/material` to one major, so an app using both
+  could not upgrade. Browser-only and node-only dependencies are contained in
+  this package, behind their own entry and optional peers or behind
+  `clientOnly`.
+- **Print components back on the main entry** — `@react-pdf/renderer` reaches a
+  dependency that crashes any SSR server that bundles it, on every request.
+  Print stays on `@nxgt/material/print`, with its dependencies as optional
+  peers.
+- **Right-to-left and complex-script PDFs** — `@react-pdf/renderer` does not
+  shape Arabic or Hebrew text reliably. Render such a document as HTML and print
+  it to PDF with a browser on a server, such as Playwright or Gotenberg.
+- **Importing `@nxgt/material/map` without a DOM** — leaflet reads `window` as
+  it is evaluated. An SSR app renders the map client-side, behind `clientOnly`.
+- **An app shell that builds its own menu** — `items` stays a prop and labels
+  stay already-translated `ReactNode`s, because each app filters its menu by its
+  own permissions and translates in its own namespace.
+
+## Shipped
+
+- **Forms that validate on blur, and a lighter map entry** — every
+  `*FormField` marks its field touched when focus leaves it, so
+  `mode: 'onBlur'` and `'onTouched'` work; `@nxgt/material/map` no longer loads
+  the rest of the library (about 0.4 MiB of static imports instead of 5.5 MiB).
+  2.2.0. ([forms](guides/forms.md#touched-on-blur))
+- **Accessible names, ids and focus across the catalogue** — every field is
+  named by its label and says it is required on the element a screen reader
+  lands on (the input, the picker's `combobox`, the slider thumbs, the
+  group), with the asterisk hidden from it; groups are named by their question
+  and describe their error instead of carrying `aria-invalid` where ARIA does
+  not allow it; ids are generated rather than taken from a field's `name` or
+  an option's `value`, so two forms on one page no longer collide; icon
+  buttons, crumbs, carousel arrows, codes and the camera have names; and a
+  dialog, sheet or drawer takes focus when it opens and gives it back when it
+  closes. 2.2.0. ([upgrading](getting-started.md#220-ids-names-and-aria-invalid-moved))
+- **PdfReader, turned pages and a steady zoom** — a page the PDF turns
+  (`/Rotate`) shows the right way up, the fit zoom settles once when the
+  document opens instead of moving while you read, `onPageChange` also reports
+  the page the reader moves to itself, links to websites open in a new tab
+  (`externalLinkTarget`), the toolbar's tooltips show in fullscreen, the
+  password field has a name, and a layout of your own opens bytes without
+  detaching them. 2.2.0. ([PdfReader](components/media-and-files.md#pdfreader))
+- **One document model for React and Vue** — `@nxgt/material/print` renders
+  documents written as plain data (`pdfDocument` and its builders,
+  `definePdfDocument` templates, `dataTable` from column definitions) alongside
+  the JSX components, and `@nxgt/material-vue/pdf` (0.22.0) renders the same
+  model, so a template renders the same pages in both libraries (experimental: the model
+  may still change in a minor release). 2.2.0.
+  ([printing](guides/printing.md#documents-as-data))
+- **One call to a PDF file** — `downloadPdf` and `openPdf` in the browser (a
+  blocked tab falls back to a download), `usePdfFile` for a preview that keeps
+  up with its data, `pdfResponse` for a server route on Node or Bun, and
+  `renderPdfBlob`, `renderPdfBuffer` and `renderPdfStream` for the file
+  itself, so you never touch `@react-pdf/renderer`'s output API or leak an
+  object URL. They also render documents written as plain data with
+  `pdfDocument` and its builders (experimental). 2.2.0.
+  ([printing](guides/printing.md#rendering-the-document))
+- **Tables from columns and rows** — `PrintDataTable` takes `columns` (label,
+  width, alignment, formatter, total) and `rows`, stripes them, keeps each row
+  whole, repeats the header on each page it crosses and closes with a totals
+  row; `PrintKeyValue` prints one record as label and value pairs and
+  `PrintMetric` a figure with its change. The `PrintTable` blocks you already
+  use keep working as they are. 2.2.0.
+  ([printing](guides/printing.md#tables-from-columns-and-rows))
+- **A page shell with page numbers** — `PrintDocument` sets page size,
+  orientation, margins and metadata, repeats your header and footer on every
+  page, prints "Page 2 of 5" in the document's language and can add a
+  watermark; `PrintHeader` takes a logo image. 2.2.0.
+  ([printing](guides/printing.md#the-page-shell-printdocument))
+- **`Stepper` without the SSR warning** — `Stepper` answers its screen-width
+  question on the server like the other responsive components, so SSR logs
+  stay clean and a desktop hydrates its server HTML without a mismatch.
+  `TimeField`'s OK button follows the language. 2.2.0.
+  ([SSR](guides/ssr.md#hydration))
+- **A PDF viewer that opens any source** — `PdfReader` opens a `Blob`, a
+  `File`, an `ArrayBuffer` or a `Uint8Array` as well as a URL, or a URL with
+  request headers (`{ url, httpHeaders }`), without reloading on every render;
+  its zoom menu works from the keyboard and in fullscreen. 2.2.0.
+  ([PdfReader](components/media-and-files.md#pdfreader))
+- **Amounts and dates in your locale** — `formatAmount` and `formatDate` take a
+  locale and time zone, use each currency's own decimals (`{ fractionDigits: 2 }`
+  keeps two) and keep a date-only value on its day; `useFormatters()` binds them
+  to the `I18nProvider` language and `createFormatters()` to a locale you pass,
+  so a document rendered on a server reads like the screen. 2.2.0.
+  ([printing](guides/printing.md#formatamount-and-formatdate))
+- **More built-in labels follow the language** — calendar navigation,
+  the data table's selection checkboxes, filter presets and
+  `Min`/`Max`, the spinner, scroll-to-top, upload `Retry`/`Remove`, the map's
+  `You are here` and zoom buttons, icon-only close buttons, and the editor's
+  slash menu (searchable in either language), font names and table alignment;
+  then the filter's empty state and chips, breadcrumb and pagination names,
+  `MessageCard`'s "Unread", the upload field's replace button and errors, the
+  editor's placeholder and emoji buttons, `CircularProgress`, `StxPlayer`,
+  `PaneLayoutPane`'s sheet title, `JsonViewer`'s "Empty JSON" and
+  `TimePicker`'s AM/PM. 2.2.0.
+  ([i18n](guides/i18n.md#the-material-namespace))
+- **PdfReader fixes** — downloads finish in every browser and take the file name
+  you give instead of `document.pdf`, a protected PDF asks for its password and
+  says when it is wrong, Escape closes the search bar before the dialog around
+  the reader, `onPageChange` reports a page inside the document, A4 and
+  landscape pages fit the width or the page, search counts matches on pages you
+  have not scrolled to yet, the page number follows scrolling, the reader opens
+  on `initialPage`, and your editor no longer shows `PdfReader` as deprecated.
+  2.2.0.
+- **Form wrappers honour your `disabled` and `helperText`** — every
+  `*FormField` follows one rule: disabled when you pass `disabled` or the form
+  disables it, and your `helperText` shows until there is an error. Composite
+  fields (contacts, opening hours, attributes) show array-level errors. 2.2.0.
+- **Formatted i18n fallbacks** — without an `I18nProvider`, components show
+  `Step 01` or `3 items`, not raw `{step}` placeholders. 2.2.0.
+- **Server-safe `zodLocaleError`** — English Zod messages in the English
+  bundle, no throw on a server or with blocked storage, and your own
+  `storageKey`, language and translator. 2.2.0.
+- **One shared theme** — every `useTheme()` reads one store, so code blocks and
+  editors follow a toggle straight away, and `ThemeToggle` no longer flashes the
+  server's guess while hydrating. 2.2.0.
+- **Declaration files that always resolve** — a packed or linked build types
+  `react` like the npm one, instead of as `any`. 2.2.0.
+- **Component documentation with previews** — every component has an entry
+  with a picture of how it renders, an example that compiles and the options
+  that matter, under the same twelve categories in the README and `docs/`. A forms guide covers React Hook Form, Zod, composite values and
+  server errors. 2.2.0.
+- **`@nxgt/material/map`** — the leaflet map, markers, location field and
+  `useGeolocation` as an entry of this package, with leaflet as optional peers.
+  2.1.0.
+- **`formatAmount` and `formatDate` on the main entry** — no need to import the
+  print entry for two `Intl` helpers. 2.1.0.
+- **Print as its own entry** — `@nxgt/material/print`, PDF dependencies as
+  optional peers, and `pdfkitStandardFonts()` for Vite. 2.0.0.
+- **No phantom self-dependency** — installing the package no longer adds a
+  second copy of it to your lockfile. 1.16.6.
+- **Importable in any node process** — `import '@nxgt/material'` no longer
+  throws at server boot. 1.16.5.
+- **Gallery lightbox fits the viewport** — media is fitted instead of cropped.
+  1.16.4.
+- **Uniform gallery tiles** — media cropped to one aspect, restyled carousel
+  controls. 1.16.3.
+- **Mention list closes on select** — in the chat composer. 1.16.2.
+- **Modern emoji picker** — refreshed picker, with stories for emoji, mentions,
+  chat and markdown. 1.16.1.
+- **`MentionList`** — mention suggestions with local search, for chat and the
+  rich text editor. 1.16.0.
+
+Older releases: the [version list on npm](https://www.npmjs.com/package/@nxgt/material?activeTab=versions).