@nxgt/material-core 0.1.1 → 0.2.0

package/README.md

@@ -5,13 +5,16 @@ The framework-free core that [`@nxgt/material`](https://www.npmjs.com/package/@n
 (Vue) share, as one copy: the PDF document model and its react-pdf renderer,
 the print formatters, the PDF file helpers, the PDF viewer's framework-free
 half (page geometry, scroll spy, text search), the currency field's decimals,
-the fields' blur rule and the Vite plugin that bundles pdfkit's standard
-fonts.
+the file-size formatter, the fields' blur rule, the Vite plugin that bundles
+pdfkit's standard fonts, and the Node-only resolution of those fonts that the
+Next.js helper and the Nuxt module run at build time.
 
 **You usually do not install it yourself.** Both libraries depend on it and
 re-export what they always exported, at the same subpaths:
 `@nxgt/material/print`, `@nxgt/material-vue/pdf`, `/lib` and `/vite` read
-from here, and so do their `PdfReader`, `CurrencyField` and form fields. Import it directly when you want the model or a formatter without
+from here, and so do their `PdfReader`, `CurrencyField`, form fields, file
+list and upload field (`formatFileSize`), `@nxgt/material/next` and
+`@nxgt/material-vue/nuxt`. Import it directly when you want the model or a formatter without
 a UI library.
 
 ```ts
@@ -42,7 +45,10 @@ files are plain ES modules and also load in Node without a bundler.
 | `vite@^6 \|\| ^7 \|\| ^8` | `@nxgt/material-core/vite` — its declarations name Vite's `Plugin` type (types only); the plugin itself runs in your Vite config |
 
 Every other subpath imports none of them, and is safe to import on a server
-with no DOM.
+with no DOM. One subpath is **Node only**: `/pdfkit-fonts` imports `node:module`
+and `node:path`, for a framework's config at build time — never import it
+from code a browser bundle can reach. No other subpath imports a `node:`
+built-in.
 
 ## Subpaths
 
@@ -64,7 +70,9 @@ with no DOM.
 | `/pdf-viewer` | The PDF viewer's pure half: page geometry and fit (`readerFitScale`, `placeholderSize`, `rotatedSize`, `PdfPageSize`, `FitMode`), page sizes (`readPageSizes`, `createPageSizesLoader`), the scroll spy (`createScrollSpy`, `revealHit`), text search (`pageTextFromItems`, `findTextMatches`, `searchDocument`), `escapeHtml`, `mapPdfOutline` |
 | `/currency-digits` | `currencyFractionDigits` — the decimals `CurrencyField` shows |
 | `/field-blur-layers` | `layerOf`, `openerOf`, `FieldLayers` — whose overlay a layer of the page is, for a field's blur |
+| `/format-file-size` | `formatFileSize` — a byte count as `'1.5 KB'` |
 | `/vite` | `pdfkitStandardFonts()` — see below |
+| `/pdfkit-fonts` | **Node only.** `pdfkitStandardFontDirs`, `pdfkitStandardFontFiles`, `PDFKIT_STANDARD_FONTS`, the types `PdfkitStandardFont` and `PdfkitFontsWarn` — where the app's pdfkit keeps its standard fonts, for a server tracer |
 
 ## Usage
 
@@ -279,6 +287,23 @@ currencyFractionDigits('KWD'); // 3
 currencyFractionDigits('EUR', 0); // 0 — an explicit value wins, as in formatAmount
 ```
 
+### A file's size: `/format-file-size`
+
+1024-based, one decimal above bytes, capped at GB, locale-free: a server and
+a browser print the same string. What both libraries' `FileList`,
+`NetworkUploadField` (and its size limit message), `FileCard` and chat
+attachments show; both re-export it as `formatFileSize`.
+
+```ts
+import { formatFileSize } from '@nxgt/material-core/format-file-size';
+
+formatFileSize(0); // '0 B'
+formatFileSize(512); // '512 B'
+formatFileSize(1536); // '1.5 KB'
+formatFileSize(5 * 1024 ** 2); // '5.0 MB'
+formatFileSize(-1); // '' — as for NaN and Infinity
+```
+
 ### A field's blur across overlays: `/field-blur-layers`
 
 A field whose popover, listbox or dialog renders into `<body>` must not count
@@ -317,12 +342,53 @@ export default defineConfig({ plugins: [pdfkitStandardFonts()] });
 function. The doc comment on `pdfkitStandardFonts` explains when you need it
 and when keeping the library external is the lighter answer.
 
+### Tracing pdfkit's fonts: `/pdfkit-fonts` (Node only)
+
+A server that keeps `node_modules` but copies only what a tracer finds
+(`next build` with `output: 'standalone'`, Nitro's `.output/server`) gets
+pdfkit without its fonts: pdfkit loads them with a runtime
+`require('#standard-fonts/<Name>')` no tracer follows, and every PDF then
+fails with `Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'`.
+These functions find the real files, as the app at a project directory
+loads them — through `@react-pdf/renderer` and through `@react-pdf/font`,
+each of which may nest its own pdfkit — for you to hand to the tracer.
+
+```ts
+// A build script or a framework config: Node code.
+import { pdfkitStandardFontDirs, pdfkitStandardFontFiles } from '@nxgt/material-core/pdfkit-fonts';
+
+const warn = (message: string) => console.warn(`[my-build] ${message}`);
+
+pdfkitStandardFontDirs(process.cwd(), warn);
+// ['/app/node_modules/pdfkit/js/standard-fonts'] — one per distinct pdfkit;
+// each also holds the chunks/ the fonts require
+
+pdfkitStandardFontFiles(process.cwd(), warn);
+// ['/app/node_modules/pdfkit/js/standard-fonts/Courier.cjs', … 14 per pdfkit]
+```
+
+- **Without `@react-pdf/renderer`** (an optional peer: the app does not
+  print), both return `[]` and never call `warn`.
+- **Otherwise, whatever fails** (`@react-pdf/font` or pdfkit not
+  resolvable, a font missing) reaches `warn` **once per call**, every problem
+  in one line (each error's first line, without Node's `Require stack:`),
+  and the rest is still returned. Prefix it with your
+  tool's name; a font that cannot be traced is a PDF route that fails in
+  production.
+- A relative project directory is taken from the working directory. The
+  paths are real paths (symlinks resolved), as pnpm and bun lay them out.
+
+You rarely call it yourself: `withNxgtPrint` (`@nxgt/material/next`) turns
+the directories into `outputFileTracingIncludes` globs, and the Nuxt module
+of `@nxgt/material-vue` adds the files to `nitro.externals.traceInclude`.
+
 ## Traps
 
 | Symptom | Fix |
 | --- | --- |
 | `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 |
 
 Every message, with its cause, is in [troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md).
 

package/dist/lib/format-file-size.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A byte count as people read it: `'512 B'`, `'1.5 KB'`, `'2.0 MB'`,
+ * `'1.0 GB'` (1024-based, one decimal above bytes, capped at GB), and `''`
+ * for a negative, `NaN` or infinite size. Locale-free, so a server and a
+ * browser print the same thing. The file list, the upload field and its
+ * constraints, the file card and the chat attachment chip of both libraries
+ * use it.
+ */
+export declare function formatFileSize(bytes: number): string;
+//# sourceMappingURL=format-file-size.d.ts.map

package/dist/lib/format-file-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-file-size.d.ts","sourceRoot":"","sources":["../../src/lib/format-file-size.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUpD"}

package/dist/lib/format-file-size.js

@@ -0,0 +1,17 @@
+// src/lib/format-file-size.ts
+function formatFileSize(bytes) {
+  if (bytes < 0 || !Number.isFinite(bytes))
+    return "";
+  if (bytes === 0)
+    return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+  const value = bytes / 1024 ** exponent;
+  return `${exponent === 0 ? value : value.toFixed(1)} ${units[exponent]}`;
+}
+export {
+  formatFileSize
+};
+
+//# debugId=5CC787DB991D0F4A64756E2164756E21
+//# sourceMappingURL=format-file-size.js.map

package/dist/lib/format-file-size.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/format-file-size.ts"],
+  "sourcesContent": [
+    "/**\n * A byte count as people read it: `'512 B'`, `'1.5 KB'`, `'2.0 MB'`,\n * `'1.0 GB'` (1024-based, one decimal above bytes, capped at GB), and `''`\n * for a negative, `NaN` or infinite size. Locale-free, so a server and a\n * browser print the same thing. The file list, the upload field and its\n * constraints, the file card and the chat attachment chip of both libraries\n * use it.\n */\nexport function formatFileSize(bytes: number): string {\n\tif (bytes < 0 || !Number.isFinite(bytes)) return '';\n\tif (bytes === 0) return '0 B';\n\tconst units = ['B', 'KB', 'MB', 'GB'];\n\tconst exponent = Math.min(\n\t\tMath.floor(Math.log(bytes) / Math.log(1024)),\n\t\tunits.length - 1,\n\t);\n\tconst value = bytes / 1024 ** exponent;\n\treturn `${exponent === 0 ? value : value.toFixed(1)} ${units[exponent]}`;\n}\n"
+  ],
+  "mappings": ";AAQO,SAAS,cAAc,CAAC,OAAuB;AAAA,EACrD,IAAI,QAAQ,KAAK,CAAC,OAAO,SAAS,KAAK;AAAA,IAAG,OAAO;AAAA,EACjD,IAAI,UAAU;AAAA,IAAG,OAAO;AAAA,EACxB,MAAM,QAAQ,CAAC,KAAK,MAAM,MAAM,IAAI;AAAA,EACpC,MAAM,WAAW,KAAK,IACrB,KAAK,MAAM,KAAK,IAAI,KAAK,IAAI,KAAK,IAAI,IAAI,CAAC,GAC3C,MAAM,SAAS,CAChB;AAAA,EACA,MAAM,QAAQ,QAAQ,QAAQ;AAAA,EAC9B,OAAO,GAAG,aAAa,IAAI,QAAQ,MAAM,QAAQ,CAAC,KAAK,MAAM;AAAA;",
+  "debugId": "5CC787DB991D0F4A64756E2164756E21",
+  "names": []
+}

package/dist/pdfkit-fonts/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Where an app's pdfkit keeps its fourteen standard fonts, resolved the way
+ * that app loads them. Build-time code for a framework's config: the Next.js
+ * helper of `@nxgt/material` (`@nxgt/material/next`, which turns the
+ * directories into `outputFileTracingIncludes` globs) and the Nuxt module of
+ * `@nxgt/material-vue` (which adds the files to Nitro's `traceInclude`).
+ *
+ * **Node only.** This is the one subpath of `@nxgt/material-core` that
+ * imports `node:*` built-ins (`node:module`, `node:path`); `verify:ssr` fails
+ * the build if any other reaches one. Never import it from code that can end
+ * up in a browser bundle.
+ *
+ * Why it exists: pdfkit registers its fonts with a runtime
+ * `require('#standard-fonts/<Name>')`, a package-`imports` specifier private
+ * to pdfkit. A server tracer (Next.js's, Nitro's) does not follow a runtime
+ * `require`, so a traced server output has pdfkit but not its `.cjs` fonts,
+ * and every PDF rendered there fails with
+ * `Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'`.
+ *
+ * pdfkit is found through `@react-pdf/renderer` and through
+ * `@react-pdf/font` (resolved from the renderer), since each can nest a
+ * pdfkit of its own. Resolving `pdfkit/standard-fonts/<Name>` from them
+ * under the `require` condition lands on the `.cjs` file pdfkit's runtime
+ * `require` reads, as a real path, under npm, pnpm and bun alike.
+ *
+ * ```ts
+ * import { pdfkitStandardFontDirs } from '@nxgt/material-core/pdfkit-fonts';
+ *
+ * pdfkitStandardFontDirs(process.cwd(), (message) => console.warn(message));
+ * // ['/app/node_modules/pdfkit/js/standard-fonts']
+ * ```
+ */
+/** The fourteen standard PDF fonts, as pdfkit exports them. */
+export declare const PDFKIT_STANDARD_FONTS: readonly ["Courier", "CourierBold", "CourierBoldOblique", "CourierOblique", "Helvetica", "HelveticaBold", "HelveticaBoldOblique", "HelveticaOblique", "Symbol", "TimesBold", "TimesBoldItalic", "TimesItalic", "TimesRoman", "ZapfDingbats"];
+export type PdfkitStandardFont = (typeof PDFKIT_STANDARD_FONTS)[number];
+/** Receives the one warning a call can give. */
+export type PdfkitFontsWarn = (message: string) => void;
+/**
+ * pdfkit's `js/standard-fonts` directories, real paths, as the app at
+ * `projectDir` loads them: the one of the pdfkit `@react-pdf/renderer`
+ * depends on and the one of `@react-pdf/font`'s, without duplicates (one
+ * directory when both share a pdfkit, as they usually do). Each directory
+ * also holds the `chunks/` the fonts `require`.
+ *
+ * `[]`, silently, when `@react-pdf/renderer` is not installed. Anything else
+ * that fails is passed to `warn`, once per call: a font that cannot be traced
+ * is a PDF route that fails in production.
+ */
+export declare function pdfkitStandardFontDirs(projectDir: string, warn?: PdfkitFontsWarn): string[];
+/**
+ * pdfkit's fourteen standard-font modules (`.cjs`, real paths), as the app
+ * at `projectDir` loads them: through pdfkit's own `standard-fonts/<Name>`
+ * exports under the `require` condition, for the pdfkit
+ * `@react-pdf/renderer` depends on and the one `@react-pdf/font` depends on,
+ * without duplicates.
+ *
+ * `[]`, silently, when `@react-pdf/renderer` is not installed. Anything else
+ * that fails is passed to `warn`, once per call.
+ */
+export declare function pdfkitStandardFontFiles(projectDir: string, warn?: PdfkitFontsWarn): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/pdfkit-fonts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pdfkit-fonts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,qBAAqB,8OAexB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAyDxD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,eAA0B,GAC9B,MAAM,EAAE,CAYV;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACtC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,eAA0B,GAC9B,MAAM,EAAE,CAcV"}

package/dist/pdfkit-fonts/index.js

@@ -0,0 +1,80 @@
+// src/pdfkit-fonts/index.ts
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+var PDFKIT_STANDARD_FONTS = [
+  "Courier",
+  "CourierBold",
+  "CourierBoldOblique",
+  "CourierOblique",
+  "Helvetica",
+  "HelveticaBold",
+  "HelveticaBoldOblique",
+  "HelveticaOblique",
+  "Symbol",
+  "TimesBold",
+  "TimesBoldItalic",
+  "TimesItalic",
+  "TimesRoman",
+  "ZapfDingbats"
+];
+var isNotFound = (error) => error?.code === "MODULE_NOT_FOUND";
+var firstLine = (error) => String(error).split(`
+`, 1)[0] ?? "";
+function fromEachPdfkit(projectDir, warn, collect) {
+  const problems = [];
+  let renderer;
+  try {
+    renderer = createRequire(join(resolve(projectDir), "package.json")).resolve("@react-pdf/renderer");
+  } catch (error) {
+    if (!isNotFound(error)) {
+      warn(`could not resolve @react-pdf/renderer: ${firstLine(error)}`);
+    }
+    return;
+  }
+  const fromRenderer = createRequire(renderer);
+  const owners = [["@react-pdf/renderer", fromRenderer]];
+  try {
+    owners.push([
+      "@react-pdf/font",
+      createRequire(fromRenderer.resolve("@react-pdf/font"))
+    ]);
+  } catch (error) {
+    problems.push(`could not resolve @react-pdf/font: ${firstLine(error)}`);
+  }
+  for (const [owner, from] of owners)
+    collect(owner, from, problems);
+  if (problems.length > 0)
+    warn(problems.join("; "));
+}
+function pdfkitStandardFontDirs(projectDir, warn = () => {}) {
+  const dirs = new Set;
+  fromEachPdfkit(projectDir, warn, (owner, from, problems) => {
+    try {
+      dirs.add(dirname(from.resolve("pdfkit/standard-fonts/Helvetica")));
+    } catch (error) {
+      problems.push(`could not resolve pdfkit's fonts for ${owner}: ${firstLine(error)}`);
+    }
+  });
+  return [...dirs];
+}
+function pdfkitStandardFontFiles(projectDir, warn = () => {}) {
+  const files = new Set;
+  fromEachPdfkit(projectDir, warn, (owner, from, problems) => {
+    for (const font of PDFKIT_STANDARD_FONTS) {
+      try {
+        files.add(from.resolve(`pdfkit/standard-fonts/${font}`));
+      } catch (error) {
+        problems.push(`could not resolve pdfkit's ${font} font for ${owner}: ${firstLine(error)}`);
+      }
+    }
+  });
+  return [...files];
+}
+export {
+  PDFKIT_STANDARD_FONTS,
+  pdfkitStandardFontDirs,
+  pdfkitStandardFontFiles
+};
+
+//# debugId=D12CCCD8FE08400864756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/pdfkit-fonts/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/pdfkit-fonts/index.ts"],
+  "sourcesContent": [
+    "/**\n * Where an app's pdfkit keeps its fourteen standard fonts, resolved the way\n * that app loads them. Build-time code for a framework's config: the Next.js\n * helper of `@nxgt/material` (`@nxgt/material/next`, which turns the\n * directories into `outputFileTracingIncludes` globs) and the Nuxt module of\n * `@nxgt/material-vue` (which adds the files to Nitro's `traceInclude`).\n *\n * **Node only.** This is the one subpath of `@nxgt/material-core` that\n * imports `node:*` built-ins (`node:module`, `node:path`); `verify:ssr` fails\n * the build if any other reaches one. Never import it from code that can end\n * up in a browser bundle.\n *\n * Why it exists: pdfkit registers its fonts with a runtime\n * `require('#standard-fonts/<Name>')`, a package-`imports` specifier private\n * to pdfkit. A server tracer (Next.js's, Nitro's) does not follow a runtime\n * `require`, so a traced server output has pdfkit but not its `.cjs` fonts,\n * and every PDF rendered there fails with\n * `Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'`.\n *\n * pdfkit is found through `@react-pdf/renderer` and through\n * `@react-pdf/font` (resolved from the renderer), since each can nest a\n * pdfkit of its own. Resolving `pdfkit/standard-fonts/<Name>` from them\n * under the `require` condition lands on the `.cjs` file pdfkit's runtime\n * `require` reads, as a real path, under npm, pnpm and bun alike.\n *\n * ```ts\n * import { pdfkitStandardFontDirs } from '@nxgt/material-core/pdfkit-fonts';\n *\n * pdfkitStandardFontDirs(process.cwd(), (message) => console.warn(message));\n * // ['/app/node_modules/pdfkit/js/standard-fonts']\n * ```\n */\n\nimport { createRequire } from 'node:module';\nimport { dirname, join, resolve } from 'node:path';\n\n/** The fourteen standard PDF fonts, as pdfkit exports them. */\nexport const PDFKIT_STANDARD_FONTS = [\n\t'Courier',\n\t'CourierBold',\n\t'CourierBoldOblique',\n\t'CourierOblique',\n\t'Helvetica',\n\t'HelveticaBold',\n\t'HelveticaBoldOblique',\n\t'HelveticaOblique',\n\t'Symbol',\n\t'TimesBold',\n\t'TimesBoldItalic',\n\t'TimesItalic',\n\t'TimesRoman',\n\t'ZapfDingbats',\n] as const;\n\nexport type PdfkitStandardFont = (typeof PDFKIT_STANDARD_FONTS)[number];\n\n/** Receives the one warning a call can give. */\nexport type PdfkitFontsWarn = (message: string) => void;\n\ntype Require = ReturnType<typeof createRequire>;\n\nconst isNotFound = (error: unknown) =>\n\t(error as { code?: string } | null)?.code === 'MODULE_NOT_FOUND';\n\n/**\n * An error as one line: its text up to the first newline. Node's\n * `Cannot find module` error appends a multi-line `Require stack:`, and the\n * warning joins every problem into ONE line: kept whole, a single failure\n * buried the others under a dozen stack paths.\n */\nconst firstLine = (error: unknown): string =>\n\tString(error).split('\\n', 1)[0] ?? '';\n\n/**\n * Runs `collect` with the `require` of each package that depends on pdfkit\n * (`@react-pdf/renderer`, then `@react-pdf/font`), and hands every problem\n * met on the way to `warn` as ONE message, joined by `; `, each error cut\n * to its first line (`firstLine`). None, silently,\n * when the app does not install `@react-pdf/renderer`: it is an optional\n * peer, and an app that does not print has no fonts to find.\n */\nfunction fromEachPdfkit(\n\tprojectDir: string,\n\twarn: PdfkitFontsWarn,\n\tcollect: (owner: string, from: Require, problems: string[]) => void,\n): void {\n\tconst problems: string[] = [];\n\tlet renderer: string;\n\ttry {\n\t\t// createRequire takes an absolute path only: a relative `projectDir`\n\t\t// is taken from the working directory.\n\t\trenderer = createRequire(join(resolve(projectDir), 'package.json')).resolve(\n\t\t\t'@react-pdf/renderer',\n\t\t);\n\t} catch (error) {\n\t\tif (!isNotFound(error)) {\n\t\t\twarn(`could not resolve @react-pdf/renderer: ${firstLine(error)}`);\n\t\t}\n\t\treturn;\n\t}\n\tconst fromRenderer = createRequire(renderer);\n\tconst owners: [string, Require][] = [['@react-pdf/renderer', fromRenderer]];\n\ttry {\n\t\towners.push([\n\t\t\t'@react-pdf/font',\n\t\t\tcreateRequire(fromRenderer.resolve('@react-pdf/font')),\n\t\t]);\n\t} catch (error) {\n\t\tproblems.push(`could not resolve @react-pdf/font: ${firstLine(error)}`);\n\t}\n\tfor (const [owner, from] of owners) collect(owner, from, problems);\n\tif (problems.length > 0) warn(problems.join('; '));\n}\n\n/**\n * pdfkit's `js/standard-fonts` directories, real paths, as the app at\n * `projectDir` loads them: the one of the pdfkit `@react-pdf/renderer`\n * depends on and the one of `@react-pdf/font`'s, without duplicates (one\n * directory when both share a pdfkit, as they usually do). Each directory\n * also holds the `chunks/` the fonts `require`.\n *\n * `[]`, silently, when `@react-pdf/renderer` is not installed. Anything else\n * that fails is passed to `warn`, once per call: a font that cannot be traced\n * is a PDF route that fails in production.\n */\nexport function pdfkitStandardFontDirs(\n\tprojectDir: string,\n\twarn: PdfkitFontsWarn = () => {},\n): string[] {\n\tconst dirs = new Set<string>();\n\tfromEachPdfkit(projectDir, warn, (owner, from, problems) => {\n\t\ttry {\n\t\t\tdirs.add(dirname(from.resolve('pdfkit/standard-fonts/Helvetica')));\n\t\t} catch (error) {\n\t\t\tproblems.push(\n\t\t\t\t`could not resolve pdfkit's fonts for ${owner}: ${firstLine(error)}`,\n\t\t\t);\n\t\t}\n\t});\n\treturn [...dirs];\n}\n\n/**\n * pdfkit's fourteen standard-font modules (`.cjs`, real paths), as the app\n * at `projectDir` loads them: through pdfkit's own `standard-fonts/<Name>`\n * exports under the `require` condition, for the pdfkit\n * `@react-pdf/renderer` depends on and the one `@react-pdf/font` depends on,\n * without duplicates.\n *\n * `[]`, silently, when `@react-pdf/renderer` is not installed. Anything else\n * that fails is passed to `warn`, once per call.\n */\nexport function pdfkitStandardFontFiles(\n\tprojectDir: string,\n\twarn: PdfkitFontsWarn = () => {},\n): string[] {\n\tconst files = new Set<string>();\n\tfromEachPdfkit(projectDir, warn, (owner, from, problems) => {\n\t\tfor (const font of PDFKIT_STANDARD_FONTS) {\n\t\t\ttry {\n\t\t\t\tfiles.add(from.resolve(`pdfkit/standard-fonts/${font}`));\n\t\t\t} catch (error) {\n\t\t\t\tproblems.push(\n\t\t\t\t\t`could not resolve pdfkit's ${font} font for ${owner}: ${firstLine(error)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t});\n\treturn [...files];\n}\n"
+  ],
+  "mappings": ";AAiCA;AACA;AAGO,IAAM,wBAAwB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD;AASA,IAAM,aAAa,CAAC,UAClB,OAAoC,SAAS;AAQ/C,IAAM,YAAY,CAAC,UAClB,OAAO,KAAK,EAAE,MAAM;AAAA,GAAM,CAAC,EAAE,MAAM;AAUpC,SAAS,cAAc,CACtB,YACA,MACA,SACO;AAAA,EACP,MAAM,WAAqB,CAAC;AAAA,EAC5B,IAAI;AAAA,EACJ,IAAI;AAAA,IAGH,WAAW,cAAc,KAAK,QAAQ,UAAU,GAAG,cAAc,CAAC,EAAE,QACnE,qBACD;AAAA,IACC,OAAO,OAAO;AAAA,IACf,IAAI,CAAC,WAAW,KAAK,GAAG;AAAA,MACvB,KAAK,0CAA0C,UAAU,KAAK,GAAG;AAAA,IAClE;AAAA,IACA;AAAA;AAAA,EAED,MAAM,eAAe,cAAc,QAAQ;AAAA,EAC3C,MAAM,SAA8B,CAAC,CAAC,uBAAuB,YAAY,CAAC;AAAA,EAC1E,IAAI;AAAA,IACH,OAAO,KAAK;AAAA,MACX;AAAA,MACA,cAAc,aAAa,QAAQ,iBAAiB,CAAC;AAAA,IACtD,CAAC;AAAA,IACA,OAAO,OAAO;AAAA,IACf,SAAS,KAAK,sCAAsC,UAAU,KAAK,GAAG;AAAA;AAAA,EAEvE,YAAY,OAAO,SAAS;AAAA,IAAQ,QAAQ,OAAO,MAAM,QAAQ;AAAA,EACjE,IAAI,SAAS,SAAS;AAAA,IAAG,KAAK,SAAS,KAAK,IAAI,CAAC;AAAA;AAc3C,SAAS,sBAAsB,CACrC,YACA,OAAwB,MAAM,IACnB;AAAA,EACX,MAAM,OAAO,IAAI;AAAA,EACjB,eAAe,YAAY,MAAM,CAAC,OAAO,MAAM,aAAa;AAAA,IAC3D,IAAI;AAAA,MACH,KAAK,IAAI,QAAQ,KAAK,QAAQ,iCAAiC,CAAC,CAAC;AAAA,MAChE,OAAO,OAAO;AAAA,MACf,SAAS,KACR,wCAAwC,UAAU,UAAU,KAAK,GAClE;AAAA;AAAA,GAED;AAAA,EACD,OAAO,CAAC,GAAG,IAAI;AAAA;AAaT,SAAS,uBAAuB,CACtC,YACA,OAAwB,MAAM,IACnB;AAAA,EACX,MAAM,QAAQ,IAAI;AAAA,EAClB,eAAe,YAAY,MAAM,CAAC,OAAO,MAAM,aAAa;AAAA,IAC3D,WAAW,QAAQ,uBAAuB;AAAA,MACzC,IAAI;AAAA,QACH,MAAM,IAAI,KAAK,QAAQ,yBAAyB,MAAM,CAAC;AAAA,QACtD,OAAO,OAAO;AAAA,QACf,SAAS,KACR,8BAA8B,iBAAiB,UAAU,UAAU,KAAK,GACzE;AAAA;AAAA,IAEF;AAAA,GACA;AAAA,EACD,OAAO,CAAC,GAAG,KAAK;AAAA;",
+  "debugId": "D12CCCD8FE08400864756E2164756E21",
+  "names": []
+}

package/docs/roadmap.md

@@ -37,3 +37,8 @@ Nothing in progress right now; see Next.
   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

@@ -21,6 +21,9 @@ file) is an example — search for the words around it.
 
 - [`… still references '#standard-fonts/' after the transform — …`](#-still-references-standard-fonts-after-the-transform--)
 - [`Cannot find module '#standard-fonts/Helvetica' from '…'`](#cannot-find-module-standard-fontshelvetica-from-)
+- [`Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'`](#cannot-find-module-pdfkitjsstandard-fontshelveticacjs)
+- [`could not resolve …` (`@react-pdf/renderer`, `@react-pdf/font`, pdfkit's fonts)](#could-not-resolve-)
+- [`Module "node:module" has been externalized for browser compatibility`](#module-nodemodule-has-been-externalized-for-browser-compatibility)
 
 ## Install
 
@@ -103,3 +106,65 @@ rather than the server at its first request. Pin the previous
 A server bundle that contains pdfkit, run without `node_modules`. Add
 `pdfkitStandardFonts()` to that build (see the README's `/vite` section), or
 keep the library external so pdfkit loads from `node_modules`.
+
+### `Cannot find module '…/pdfkit/js/standard-fonts/Helvetica.cjs'`
+
+**When:** on every PDF a traced server output renders — `.next/standalone`
+(`output: 'standalone'`), Nitro's `.output/server` — while the dev server
+renders fine. The path points into the output's own `node_modules/pdfkit/`.
+**Why:** the tracer copies pdfkit, but pdfkit loads its fonts with a runtime
+`require('#standard-fonts/<Name>')` it never follows, so the `.cjs` fonts
+(and the `chunks/` they `require`) are left behind.
+**Fix:** hand the tracer the files. With `@nxgt/material`, wrap the Next.js
+config in `withNxgtPrint` (`@nxgt/material/next`); with
+`@nxgt/material-vue`, use its Nuxt module. Anything else calls
+`/pdfkit-fonts` in its config:
+
+```ts
+import { pdfkitStandardFontDirs } from '@nxgt/material-core/pdfkit-fonts';
+
+// every .cjs under each directory, chunks/ included
+const include = pdfkitStandardFontDirs(process.cwd(), console.warn).map(
+	(dir) => `${dir}/**/*.cjs`,
+);
+```
+
+### `could not resolve …`
+
+**When:** at build, from `pdfkitStandardFontDirs` or
+`pdfkitStandardFontFiles` — through `withNxgtPrint`
+(`[@nxgt/material/next] …`), the Nuxt module (`pdf fonts: …`) or your own
+`warn`. Every problem goes into one line, joined by `; `, each error cut to
+its first line (Node's `Require stack:` is left out):
+`could not resolve @react-pdf/renderer: …`,
+`could not resolve @react-pdf/font: …`,
+`could not resolve pdfkit's fonts for @react-pdf/renderer: …`,
+`could not resolve pdfkit's Courier font for …`.
+Without `@react-pdf/renderer` installed at all, nothing is printed.
+**Why:** `@react-pdf/renderer` is installed, but resolving it, the
+`@react-pdf/font` it uses or the pdfkit either depends on fails: a broken or
+partial install, or a layout that hides them from the renderer.
+**Fix:** reinstall (`rm -rf node_modules && <your package manager> install`),
+and check that `node -e "require.resolve('pdfkit/standard-fonts/Helvetica', { paths: [require.resolve('@react-pdf/renderer')] })"`
+prints a `.cjs` path. What could be resolved is still returned: the warning
+names only what a PDF route will miss.
+
+### `Module "node:module" has been externalized for browser compatibility`
+
+**When:** Vite (or a similar bundler) prints this, or a browser console shows
+`createRequire is not a function`, in an app that imports
+`@nxgt/material-core/pdfkit-fonts`.
+**Why:** `/pdfkit-fonts` is Node-only: it resolves files on disk with
+`node:module` and `node:path`. Imported from code that reaches the browser, the
+bundler swaps those built-ins for empty shims.
+**Fix:** import it only from build-time Node code — `next.config.ts`, a Nuxt
+module, a Vite config, a script. In a Next.js app use `withNxgtPrint` from
+`@nxgt/material/next`; in Nuxt the `@nxgt/material-vue` module already calls
+it.
+
+```ts
+// next.config.ts: runs in Node, never in the browser
+import { withNxgtPrint } from '@nxgt/material/next';
+
+export default withNxgtPrint({ output: 'standalone' });
+```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.1.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 field-blur layers and the pdfkit fonts Vite plugin",
+	"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",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -92,6 +92,11 @@
 			"import": "./dist/lib/field-blur-layers.js",
 			"default": "./dist/lib/field-blur-layers.js"
 		},
+		"./format-file-size": {
+			"types": "./dist/lib/format-file-size.d.ts",
+			"import": "./dist/lib/format-file-size.js",
+			"default": "./dist/lib/format-file-size.js"
+		},
 		"./pdf-viewer": {
 			"types": "./dist/pdf-viewer/index.d.ts",
 			"import": "./dist/pdf-viewer/index.js",
@@ -102,6 +107,11 @@
 			"import": "./dist/vite/index.js",
 			"default": "./dist/vite/index.js"
 		},
+		"./pdfkit-fonts": {
+			"types": "./dist/pdfkit-fonts/index.d.ts",
+			"import": "./dist/pdfkit-fonts/index.js",
+			"default": "./dist/pdfkit-fonts/index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"sideEffects": false,
@@ -146,8 +156,10 @@
 			"src/lib/pdf-download.ts",
 			"src/lib/currency-digits.ts",
 			"src/lib/field-blur-layers.ts",
+			"src/lib/format-file-size.ts",
 			"src/pdf-viewer/index.ts",
-			"src/vite/index.ts"
+			"src/vite/index.ts",
+			"src/pdfkit-fonts/index.ts"
 		]
 	},
 	"dependencies": {