@nxgt/material 2.0.1 → 2.2.0

package/dist/lib/lib/zod-error-map.d.ts

@@ -1,3 +1,4 @@
+import { LanguageProvider, MaterialLocaleKey, Translate } from '../i18n/types';
 /**
  * parsedType - Best-effort runtime type name for a Zod issue's `input`.
  *
@@ -5,15 +6,34 @@
  * used to interpolate `{received}` into the `invalid_type` message.
  */
 export declare const parsedType: (data: any) => string;
+export type ZodLocaleErrorOptions = {
+    /**
+     * `localStorage` key the language is read from. Defaults to `'language'`,
+     * `I18nProvider`'s default: pass the `storageKey` you gave the provider.
+     */
+    storageKey?: string;
+    /**
+     * The language, or a function returning it, used instead of storage: for a
+     * server render, or to follow `I18nProvider`'s state.
+     */
+    language?: LanguageProvider;
+    /**
+     * The translator to format with. Pass your app's
+     * `createTranslator(mergeResources(resources, appResources))` so your
+     * overrides of `material.zod.*` apply. Defaults to the package's own.
+     */
+    translate?: Translate<MaterialLocaleKey>;
+};
 /**
  * zodLocaleError - Zod v4 issue-code -> message error map, i18n'd through
  * `@nxgt/material`'s own reserved `material.zod.*` namespace.
  *
- * Self-contained on purpose: it reads the current language directly from
- * `localStorage` (the same key `I18nProvider` persists to) and formats
+ * With no options it is self-contained: it reads the language from
+ * `localStorage` (the key `I18nProvider` persists to by default) and formats
  * against this package's own base bundle, so it produces sensible
  * (English-fallback) messages even in an app that hasn't merged material's
- * i18n resources or mounted `I18nProvider`.
+ * i18n resources or mounted `I18nProvider`. Where there is no `localStorage`
+ * (a server), or reading it throws, it uses English.
  *
  * @example
  * ```ts
@@ -21,6 +41,8 @@ export declare const parsedType: (data: any) => string;
  * import { zodLocaleError } from '@nxgt/material/lib';
  *
  * z.config({ customError: zodLocaleError() });
+ * // a custom storage key, and the app's merged overrides:
+ * z.config({ customError: zodLocaleError({ storageKey: 'lang', translate }) });
  * ```
  */
-export declare const zodLocaleError: () => any;
+export declare const zodLocaleError: (options?: ZodLocaleErrorOptions) => any;

package/dist/lib/map/components/consts.d.ts

@@ -0,0 +1,6 @@
+export declare const POSITION_CLASSES: {
+    bottomleft: string;
+    bottomright: string;
+    topleft: string;
+    topright: string;
+};

package/dist/lib/map/components/index.d.ts

@@ -0,0 +1,5 @@
+export * from './consts';
+export * from './location-field';
+export * from './location-form-field';
+export * from './map';
+export * from './partials';

package/dist/lib/map/components/location-field.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+import { TextFieldProps } from '../../components/ui/fields/text-field/text-field';
+export type LocationFieldProps = {
+    value?: [number, number] | null;
+    onChange?: (value: [number, number]) => void;
+    closeLabel?: ReactNode;
+    dialogTitle?: ReactNode;
+    mapClassName?: string;
+} & Omit<TextFieldProps, 'value' | 'onChange'>;
+export declare function LocationField({ value, onChange, dialogTitle, closeLabel, mapClassName, placeholder, ...props }: LocationFieldProps): import("react").JSX.Element;

package/dist/lib/map/components/location-form-field.d.ts

@@ -0,0 +1,3 @@
+import { UseControllerProps } from 'react-hook-form';
+import { LocationFieldProps } from './location-field';
+export declare function LocationFormField<T extends Record<string, any>>({ control, name, ...props }: Pick<UseControllerProps<T>, 'control' | 'name'> & Omit<LocationFieldProps, 'name' | 'value' | 'onChange'>): import("react").JSX.Element;

package/dist/lib/map/components/map.d.ts

@@ -0,0 +1,6 @@
+import { MapContainerProps } from 'react-leaflet';
+export type MapProps = {
+    showMinicardControl?: boolean;
+} & MapContainerProps;
+export declare function MapComponent({ className, children, showMinicardControl, zoom, zoomControl, scrollWheelZoom, ...props }: MapProps): import("react").JSX.Element;
+export { MapComponent as Map };

package/dist/lib/map/components/partials/index.d.ts

@@ -0,0 +1,5 @@
+export * from './location-marker';
+export * from './location-preview';
+export * from './map-actions';
+export * from './marker';
+export * from './minimap-control';

package/dist/lib/map/components/partials/location-marker.d.ts

@@ -0,0 +1,5 @@
+import { MarkerProps } from './marker';
+export type LocationMarkerProps = {
+    icon?: MarkerProps['icon'];
+} & Omit<MarkerProps, 'position' | 'draggable' | 'icon' | 'onChange'>;
+export declare function LocationMarker({ ...props }: LocationMarkerProps): import("react").JSX.Element | null;

package/dist/lib/map/components/partials/location-preview.d.ts

@@ -0,0 +1,7 @@
+import { LatLngExpression } from 'leaflet';
+import { PropsWithChildren } from 'react';
+export type LocationPreviewProps = {
+    position: LatLngExpression;
+    name?: string;
+} & PropsWithChildren;
+export declare function LocationPreview({ name, position, children, }: LocationPreviewProps): import("react").JSX.Element;

package/dist/lib/map/components/partials/map-actions.d.ts

@@ -0,0 +1,6 @@
+import { ComponentProps } from 'react';
+import { POSITION_CLASSES } from '../consts';
+export type MapActionsProps = {
+    position?: keyof typeof POSITION_CLASSES;
+} & ComponentProps<'div'>;
+export declare function MapActions({ position, className, ...props }: MapActionsProps): import("react").JSX.Element;

package/dist/lib/map/components/partials/marker.d.ts

@@ -0,0 +1,11 @@
+import { MarkerProps as BaseMarkerProps } from '@adamscybot/react-leaflet-component-marker';
+import { LatLng } from 'leaflet';
+import { ReactNode } from 'react';
+export type MarkerProps = {
+    onChange?: (position: LatLng) => void;
+    popup?: ReactNode;
+    tooltip?: ReactNode;
+    reference?: boolean;
+    icon?: BaseMarkerProps['icon'] | null;
+} & Omit<BaseMarkerProps, 'icon'>;
+export declare function Marker({ title, position, onChange, draggable, children, tooltip, reference, icon, ...props }: MarkerProps): import("react").JSX.Element;

package/dist/lib/map/components/partials/minimap-control.d.ts

@@ -0,0 +1,5 @@
+import { POSITION_CLASSES } from '../consts';
+export declare function MinimapControl({ position, zoom, }: {
+    position?: keyof typeof POSITION_CLASSES;
+    zoom?: number;
+}): import("react").JSX.Element;

package/dist/lib/map/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Leaflet maps: the map itself, its markers and controls, a location field and
+ * its react-hook-form wrapper, and the geolocation hook they share.
+ *
+ * **This entry cannot be imported in a process without a DOM.** `leaflet` reads
+ * `window` at module scope — `import 'leaflet'` in bun or node throws
+ * `window is not defined` before any of this code runs — and `react-leaflet`,
+ * `@react-leaflet/core` and `@adamscybot/react-leaflet-component-marker` all
+ * import leaflet, so they throw too. Measured 2026-09-22.
+ *
+ * That is why it is a separate entry, and why it must stay out of every barrel:
+ * `.`, `./components` and the rest are imported by SSR servers at boot, and one
+ * `export * from './map'` in `lib/main.ts` would kill every consumer that renders
+ * on a server — the same failure `@nxgt/material/print` was split out for, with a
+ * different dependency. `scripts/verify-ssr-safe.ts` fails the build if `leaflet`
+ * appears in any built entry but `map.js`, and deliberately does not try to import
+ * `map.js` itself.
+ *
+ * So a consumer renders these components **client-side only**: behind a
+ * `clientOnly` boundary, a `useEffect`, or in an SPA, where there is no server
+ * pass at all. An SSR app that renders `<Map>` directly gets a blank page and
+ * `window is not defined` in its server log.
+ *
+ * `leaflet`, `react-leaflet`, `@react-leaflet/core`,
+ * `@adamscybot/react-leaflet-component-marker` and `react-geolocated` are
+ * **optional peer dependencies**: an app that imports this entry installs them
+ * itself, and an app that does not never has them in its tree. Leaflet's own CSS
+ * comes from `@nxgt/material/map.css`, which is not part of `styles.css`.
+ *
+ * This code was `@nxgt/map` until 2026-09-22, extracted into its own package for
+ * exactly the SSR crash described above. The optional-peer entry solves it without
+ * a second repository, a second release train, or a second copy of
+ * `@nxgt/material` in the consumer's bundle — which is what that split actually
+ * cost: `@nxgt/map` pinned `@nxgt/material: ^1.0.0`, so an app using both could
+ * not take the 2.x major at all.
+ */
+export * from './components';
+export * from './use-geolocation';

package/dist/lib/map/use-geolocation.d.ts

@@ -0,0 +1,2 @@
+import { GeolocatedConfig } from 'react-geolocated';
+export declare function useGeolocation(options?: GeolocatedConfig): import('react-geolocated').GeolocatedResult;

package/dist/lib/pdf-core/file-loader.d.ts

@@ -0,0 +1,18 @@
+export type PdfFileSnapshot = {
+    blob: Blob | null;
+    /** An object URL of `blob`, for an `<iframe>`, a `PdfReader` or a link. */
+    url: string | null;
+    loading: boolean;
+    error: Error | null;
+};
+export declare const IDLE_PDF_FILE: PdfFileSnapshot;
+/**
+ * What `usePdfFile` (React) and `usePdf` (Vue) run, framework-free: renders a
+ * document with `render`, keeps one object URL alive at a time and revokes it
+ * when replaced or disposed, and drops the result of a render that a newer
+ * `load` (or `dispose`) overtook.
+ */
+export declare function createPdfFileLoader<I, O = undefined>(onChange: (snapshot: PdfFileSnapshot) => void, render: (input: I, options?: O) => Promise<Blob>): {
+    load(input: I | null, options?: O): Promise<void>;
+    dispose(): void;
+};

package/dist/lib/pdf-core/http.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Serving a rendered PDF, framework-free: the headers of a response and a
+ * Web stream over react-pdf's Node stream. No `node:*` import, so a browser
+ * bundle stays clean.
+ */
+export type PdfResponseOptions = {
+    /** Name of the file; `.pdf` is added when missing. `document.pdf` by default. */
+    fileName?: string;
+    /** `'inline'` shows it in the browser; `'attachment'` (default) saves it. */
+    disposition?: 'inline' | 'attachment';
+    /** More headers, such as `Cache-Control`. */
+    headers?: HeadersInit;
+};
+/**
+ * `Content-Disposition` with an ASCII `filename` every client reads and a
+ * UTF-8 `filename*` for the rest (RFC 6266).
+ */
+export declare function contentDisposition(disposition: 'inline' | 'attachment', fileName: string): string;
+/** A Web `Response` carrying PDF bytes, with type, length and file name. */
+export declare function pdfBytesResponse(bytes: Uint8Array<ArrayBuffer>, options?: PdfResponseOptions): Response;
+/** A Web `ReadableStream` over an async iterable of chunks (react-pdf's stream). */
+export declare function toWebStream(source: AsyncIterable<Uint8Array | string>): ReadableStream<Uint8Array>;

package/dist/lib/pdf-core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The document model and its react-pdf renderer, shared by
+ * `@nxgt/material/print` and `@nxgt/material-vue/pdf`.
+ *
+ * `model/` is plain data and imports nothing from React. `render/` imports
+ * `react` and `@react-pdf/renderer` — optional peers in both libraries — so
+ * it is reached from the print (React) and pdf (Vue) entries only, never from
+ * a barrel: `scripts/verify-ssr-safe.ts` fails the build otherwise.
+ */
+export * from './model';
+export * from './render';

package/dist/lib/pdf-core/model/builders.d.ts

@@ -0,0 +1,54 @@
+import { PdfDocument, PdfInline, PdfNode, PdfPage, PrintValue } from './types';
+type NodeOf<T extends PdfNode['type']> = Extract<PdfNode, {
+    type: T;
+}>;
+type Options<T extends PdfNode['type'], K extends string = never> = Omit<NodeOf<T>, 'type' | K>;
+export declare const text: (content: string | PdfInline[], options?: Omit<Options<"text">, "content">) => NodeOf<"text">;
+export declare const heading: (text: string, level?: 1 | 2 | 3) => NodeOf<"heading">;
+export declare const stack: (children: PdfNode[], options?: Omit<Options<"stack">, "children">) => NodeOf<"stack">;
+export declare const row: (children: PdfNode[], options?: Omit<Options<"row">, "children">) => NodeOf<"row">;
+export declare const section: (title: string, children: PdfNode[]) => NodeOf<"section">;
+export declare const image: (src: string, options?: Omit<Options<"image">, "src">) => NodeOf<"image">;
+export declare const link: (href: string, text: string) => NodeOf<"link">;
+export declare const spacer: (size: number) => NodeOf<"spacer">;
+export declare const divider: () => NodeOf<"divider">;
+export declare const pageBreak: () => NodeOf<"pageBreak">;
+export declare const table: (options: Options<"table">) => NodeOf<"table">;
+export declare const keyValue: (items: {
+    label: string;
+    value: PrintValue;
+}[], options?: Omit<Options<"keyValue">, "items">) => NodeOf<"keyValue">;
+export declare const totals: (rows: NodeOf<"totals">["rows"]) => NodeOf<"totals">;
+export declare const metric: (options: Options<"metric">) => NodeOf<"metric">;
+export declare const badge: (text: string, color?: string) => NodeOf<"badge">;
+export declare const header: (options: Options<"header">) => NodeOf<"header">;
+export declare const pageNumber: (options?: Options<"pageNumber">) => NodeOf<"pageNumber">;
+export declare const page: (options: PdfPage) => PdfPage;
+/** A whole document; `version` is stamped for you. */
+export declare const pdfDocument: (options: Omit<PdfDocument, "version">) => PdfDocument;
+/**
+ * What `definePdfDocument` accepts: a function from your data (and more
+ * parameters, if you like) to a document without its `version`. A method
+ * signature, so that its parameters are checked both ways: an annotated
+ * `(inv: Invoice)` fits, while an unannotated first parameter is typed
+ * `unknown` (use it only after narrowing) and a later one with a default
+ * (`language = 'en'`) takes its type from the default.
+ */
+type PdfTemplate = {
+    build(data: unknown, ...rest: never[]): Omit<PdfDocument, 'version'>;
+}['build'];
+/**
+ * Types a template: a function from your data to a document. It returns the
+ * function unchanged, stamping `version` on what it builds. Annotate the
+ * data parameter; the others may have defaults (`language = 'en'`). Left
+ * unannotated, the data is `unknown`, so reading a property of it fails to
+ * compile in the template rather than where the template is called.
+ *
+ * @example
+ * const invoicePdf = definePdfDocument((inv: Invoice, language = 'en') => ({
+ *   language,
+ *   pages: [page({ pageNumbers: true, body: [heading(inv.number)] })],
+ * }));
+ */
+export declare function definePdfDocument<F extends PdfTemplate>(build: F): (...args: Parameters<F>) => PdfDocument;
+export {};

package/dist/lib/pdf-core/model/data-table.d.ts

@@ -0,0 +1,24 @@
+import { PrintColumn, PrintTableOptions } from '../../lib/print-table.utils';
+import { PdfNode } from './types';
+type TableNode = Extract<PdfNode, {
+    type: 'table';
+}>;
+type KeyValueNode = Extract<PdfNode, {
+    type: 'keyValue';
+}>;
+export type DataTableOptions = PrintTableOptions & Pick<TableNode, 'striped' | 'repeatHeader' | 'keepRowsWhole' | 'emptyText' | 'hideWhenEmpty'>;
+/**
+ * A `table` node from column definitions and plain rows — the model twin of
+ * `PrintDataTable`. Without `totalLabel`, the totals row reads "Total" in the
+ * document's language.
+ *
+ * @example
+ * dataTable(definePrintColumns<Line>([
+ *   { key: 'item', label: 'Item', flex: 3 },
+ *   { key: 'amount', label: 'Amount', format: 'amount', total: 'sum' },
+ * ]), invoice.lines, { currency: 'EUR' })
+ */
+export declare function dataTable<T>(columns: PrintColumn<T>[], rows: T[], options?: DataTableOptions): TableNode;
+/** A `keyValue` node from one row, read through column definitions. */
+export declare function keyValueOf<T>(fields: PrintColumn<T>[], data: T, options?: Pick<PrintTableOptions, 'currency'> & Pick<KeyValueNode, 'columns' | 'keepEmpty'>): KeyValueNode;
+export {};

package/dist/lib/pdf-core/model/index.d.ts

@@ -0,0 +1,4 @@
+export * from './builders';
+export * from './data-table';
+export * from './theme';
+export * from './types';

package/dist/lib/pdf-core/model/nodes.d.ts

@@ -0,0 +1,133 @@
+import { PdfAlign, PdfColor, PdfJsonValue, PdfStyle, PrintValue } from './types';
+export type PdfInline = string | {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    color?: PdfColor;
+    href?: string;
+};
+export type PdfTableColumn = {
+    label: string;
+    align?: PdfAlign;
+    /** Points, or a percentage of the table (`'25%'`); otherwise it flexes. */
+    width?: number | `${number}%`;
+    /** Share of the remaining width; 1 by default. */
+    flex?: number;
+};
+export type PdfNode = {
+    type: 'stack';
+    children: PdfNode[];
+    gap?: number;
+    style?: PdfStyle;
+} | {
+    type: 'row';
+    children: PdfNode[];
+    gap?: number;
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    justify?: 'start' | 'center' | 'end' | 'between';
+    style?: PdfStyle;
+} | {
+    type: 'text';
+    content: string | PdfInline[];
+    variant?: 'body' | 'muted' | 'caption' | 'label';
+    style?: PdfStyle;
+} | {
+    type: 'heading';
+    text: string;
+    level?: 1 | 2 | 3;
+} | {
+    type: 'section';
+    title: string;
+    children: PdfNode[];
+} | {
+    type: 'image';
+    /** A URL or a data URL; PNG or JPEG. */
+    src: string;
+    width?: number;
+    height?: number;
+    fit?: 'contain' | 'cover';
+} | {
+    type: 'link';
+    href: string;
+    text: string;
+} | {
+    type: 'spacer';
+    size: number;
+} | {
+    type: 'divider';
+} | {
+    type: 'pageBreak';
+} | {
+    type: 'table';
+    columns: PdfTableColumn[];
+    rows: PrintValue[][];
+    /** Rows after the body, such as totals; kept together. */
+    footer?: PrintValue[][];
+    /** An empty first cell of a footer row reads "Total", translated. */
+    labelTotals?: boolean;
+    /** Zebra rows; `true` by default. */
+    striped?: boolean;
+    /** The header again at the top of each page; `true` by default. */
+    repeatHeader?: boolean;
+    /** A row never splits across pages; `true` by default. */
+    keepRowsWhole?: boolean;
+    /** Shown in one muted row when there are no rows. */
+    emptyText?: string;
+    /** Render nothing, not even the header, when there are no rows. */
+    hideWhenEmpty?: boolean;
+} | {
+    type: 'keyValue';
+    items: {
+        label: string;
+        value: PrintValue;
+    }[];
+    /** 1 or 2 columns of pairs; 1 by default. */
+    columns?: 1 | 2;
+    /** Print a pair whose value is empty, as `'—'`. */
+    keepEmpty?: boolean;
+} | {
+    type: 'totals';
+    rows: {
+        label: string;
+        value: PrintValue;
+        emphasis?: boolean;
+    }[];
+} | {
+    type: 'metric';
+    label: string;
+    value: PrintValue;
+    hint?: string;
+    /** A change in percent, shown as `+4%` or `-2%`. */
+    delta?: number;
+} | {
+    type: 'badge';
+    text: string;
+    color?: PdfColor;
+} | {
+    type: 'header';
+    title: string;
+    subtitle?: string;
+    reference?: string;
+    /** Printed before `reference`; `'#'` by default. */
+    referencePrefix?: string;
+    /** A URL or a data URL, PNG or JPEG. */
+    logo?: string | {
+        src: string;
+        width?: number;
+        height?: number;
+    };
+    /** Shown in the logo box when there is no `logo`. */
+    logoText?: string;
+    /** A QR code already rendered as a PNG data URL. */
+    qrDataUrl?: string | null;
+} | {
+    type: 'pageNumber';
+    format?: 'page-of' | 'page';
+    align?: PdfAlign;
+} | {
+    type: 'custom';
+    /** The renderer's name in the `custom` option. */
+    name: string;
+    props?: Record<string, PdfJsonValue>;
+};
+export type PdfNodeType = PdfNode['type'];

package/dist/lib/pdf-core/model/theme.d.ts

@@ -0,0 +1,16 @@
+import { PdfColor, PdfThemeColor, PdfThemeOverrides } from './types';
+export type PdfTheme = {
+    colors: Record<PdfThemeColor, string>;
+    fonts: Record<'sans' | 'serif' | 'mono', string>;
+};
+/**
+ * The light screen theme, in colours react-pdf reads (it takes no oklch):
+ * `primary`, `secondary`, `muted`, `border` and `qrBg` are the screen's
+ * `--primary`, `--secondary`, `--muted-foreground`, `--border` and `--muted`.
+ * Fonts are PDF standard fonts, so nothing has to be registered.
+ */
+export declare const defaultPdfTheme: PdfTheme;
+/** The default theme with `overrides` applied. */
+export declare function resolvePdfTheme(overrides?: PdfThemeOverrides): PdfTheme;
+/** A theme colour name resolved to its value; any other colour as it is. */
+export declare function resolvePdfColor(color: PdfColor | undefined, theme: PdfTheme): string | undefined;

package/dist/lib/pdf-core/model/types.d.ts

@@ -0,0 +1,108 @@
+import { PrintValue } from '../../lib/print-value.utils';
+import { PdfNode } from './nodes';
+export type * from './nodes';
+export type { PrintValue };
+/** A theme colour name (`'primary'`, `'muted'`, …) or a CSS colour (`'#0b7a4b'`). */
+export type PdfColor = PdfThemeColor | (string & {});
+/** A JSON value: what a document may carry, so it survives `JSON.stringify`. */
+export type PdfJsonValue = string | number | boolean | null | PdfJsonValue[] | {
+    [key: string]: PdfJsonValue;
+};
+/** A JSON-safe subset of react-pdf's style: numbers are points. */
+export type PdfStyle = {
+    margin?: number;
+    marginTop?: number;
+    marginRight?: number;
+    marginBottom?: number;
+    marginLeft?: number;
+    padding?: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    width?: number | string;
+    height?: number | string;
+    flex?: number;
+    gap?: number;
+    /** One of the theme's fonts; `'sans'` by default. */
+    fontFamily?: 'sans' | 'serif' | 'mono';
+    fontSize?: number;
+    fontWeight?: 'normal' | 'bold';
+    fontStyle?: 'normal' | 'italic';
+    textAlign?: 'left' | 'center' | 'right' | 'justify';
+    color?: PdfColor;
+    backgroundColor?: PdfColor;
+    borderWidth?: number;
+    borderColor?: PdfColor;
+    borderRadius?: number;
+};
+/** Points on each side; `x` and `y` set both sides of an axis. */
+export type PdfBox = {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    x?: number;
+    y?: number;
+};
+export type PdfPageSize = 'A3' | 'A4' | 'A5' | 'LETTER' | 'LEGAL' | [number, number];
+export type PdfAlign = 'left' | 'center' | 'right';
+/** `true` prints "Page 2 of 5" centred at the bottom of every page. */
+export type PdfPageNumbers = boolean | {
+    align?: PdfAlign;
+    format?: 'page-of' | 'page';
+};
+export type PdfWatermark = string | {
+    text: string;
+    /** 0 to 1; 0.08 by default. */
+    opacity?: number;
+    /** Degrees, counter-clockwise; 35 by default. */
+    angle?: number;
+    color?: PdfColor;
+    /** Points; 72 by default. */
+    fontSize?: number;
+};
+/** Document information, as PDF readers show it. */
+export type PdfMeta = {
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords?: string;
+    creator?: string;
+    producer?: string;
+};
+/** Colours and fonts; every field is optional and falls back to the default. */
+export type PdfThemeOverrides = {
+    colors?: Partial<Record<PdfThemeColor, string>>;
+    fonts?: Partial<Record<'sans' | 'serif' | 'mono', string>>;
+};
+export type PdfThemeColor = 'primary' | 'secondary' | 'text' | 'muted' | 'border' | 'headerBg' | 'headerText' | 'rowAlt' | 'logoBg' | 'qrBg' | 'success' | 'error';
+/** The page shell: size, margins and what repeats on every page. */
+export type PdfPageOptions = {
+    size?: PdfPageSize;
+    orientation?: 'portrait' | 'landscape';
+    /** Points; a number for every side. */
+    margins?: number | PdfBox;
+    /** Space kept at the bottom for the footer and page numbers; 24 by default. */
+    footerHeight?: number;
+    pageNumbers?: PdfPageNumbers;
+    watermark?: PdfWatermark;
+};
+export type PdfPage = PdfPageOptions & {
+    /** Repeated at the top of every page, in the flow. */
+    header?: PdfNode[];
+    /** Repeated at the bottom of every page. */
+    footer?: PdfNode[];
+    body: PdfNode[];
+};
+export type PdfDocument = {
+    version: 1;
+    meta?: PdfMeta;
+    /** Picks the built-in strings (`'en'`, `'fr'`) and the PDF's language. */
+    language?: string;
+    /** Formats amounts, dates and numbers; defaults to `language`. */
+    locale?: string;
+    timeZone?: string;
+    theme?: PdfThemeOverrides;
+    pages: PdfPage[];
+};

package/dist/lib/pdf-core/render/context.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+import { PrintValue, PrintValueOptions } from '../../lib/print-value.utils';
+import { PdfTheme } from '../model/theme';
+import { PdfNode, PdfThemeOverrides } from '../model/types';
+import { PdfStyles } from './styles';
+/** Translates a built-in string: its key, English fallback and values. */
+export type PdfTranslate = (key: string, fallback: string, values?: Record<string, string | number>) => string;
+/** Renders a `{ type: 'custom' }` node registered under its `name`. */
+export type PdfCustomRenderer = (props: Record<string, unknown>, context: PdfRenderContext) => ReactNode;
+/**
+ * Everything a node renderer needs, resolved once per document. It is plain
+ * data and functions — never a hook — because react-pdf calls the `render`
+ * callbacks of page numbers and fixed elements at layout time, outside React,
+ * where a hook throws.
+ */
+export type PdfRenderContext = {
+    language: string;
+    locale?: string;
+    timeZone?: string;
+    theme: PdfTheme;
+    styles: PdfStyles;
+    t: PdfTranslate;
+    /**
+     * Formats a value with the document's locale and time zone, as text the
+     * standard fonts can print ({@link toPdfText}).
+     */
+    format: (value: PrintValue, options?: Pick<PrintValueOptions, 'empty'>) => string;
+    /** Renders child nodes; set by `createPdfRenderContext`. */
+    renderNodes: (nodes: PdfNode[] | undefined) => ReactNode[];
+    custom: Record<string, PdfCustomRenderer>;
+};
+export type PdfRenderOptions = {
+    /** `'en'` or `'fr'` pick the built-in strings; `'en'` by default. */
+    language?: string;
+    /** Formats amounts and dates; defaults to `language`. */
+    locale?: string;
+    timeZone?: string;
+    theme?: PdfThemeOverrides;
+    /**
+     * Translates the built-in strings (`material.print.*` keys); without it,
+     * the English fallbacks are printed.
+     */
+    translate?: PdfTranslate;
+    /** Renderers for `{ type: 'custom', name }` nodes. */
+    custom?: Record<string, PdfCustomRenderer>;
+};
+export declare const DEFAULT_PDF_LANGUAGE = "en";
+/** Text with the characters the standard fonts lack replaced by ones they have. */
+export declare function toPdfText(text: string): string;
+export declare function createPdfRenderContext(options: PdfRenderOptions, renderNodes: (nodes: PdfNode[] | undefined, context: PdfRenderContext) => ReactNode[]): PdfRenderContext;