pdfmkr
Version:
Generate PDF documents from JavaScript objects
258 lines (257 loc) • 8.35 kB
TypeScript
import type { Block } from './layout.ts';
import type { BoxLengths, Length, Orientation, PaperSize } from './sizes.ts';
import type { TextProps } from './text.ts';
/**
* The complete definition of a PDF document to create.
*/
export type DocumentDefinition = {
/**
* The default language of the document, expressed as a BCP 47 tag
* (e.g. `'en'`, `'de'`, `'ar'`, `'zh-Hans'`).
*
* Setting the language helps assistive technologies and improves
* language-aware text shaping when no more specific language is
* provided.
*/
language?: string;
/**
* A content block that is printed at the top of each page.
* A function can be passed to create page-specific headers.
*/
header?: Block | ((info: PageInfo) => Block);
/**
* A content block that is printed at the bottom of each page.
* A function can be passed to create page-specific footers.
*/
footer?: Block | ((info: PageInfo) => Block);
/**
* The sequence of blocks that contain the document's content.
*/
content: Block[];
/**
* The default style properties to use in the document.
*/
defaultStyle?: TextProps;
/**
* The page size of the document. Defaults to A4.
*/
pageSize?: PaperSize;
/**
* The orientation of the pages in the document. When this parameter is set, width and height
* of the given page size will be reversed if necessary to match the given orientation.
*/
pageOrientation?: Orientation;
/**
* The margin to leave around the page content area, relative to header and footer.
* That is, if a header is specified, the top margin defines the vertical distance from the
* header, otherwise from the top of the page.
* The bottom margin defines the vertical distance from the footer or, if there is no footer,
* from the bottom of the page.
* A function can be passed to create page-specific margins.
*
* Defaults to `50pt` on each side.
*/
margin?: Length | BoxLengths | ((info: PageInfo) => Length | BoxLengths);
/**
* Metadata to include in the PDF's *document information dictionary*.
*/
info?: InfoProps & CustomInfoProps;
/**
* Custom data to be added to the PDF *document catalog*. This
* property should only be used by PDF applications that need to
* include custom data in a PDF document. To avoid name collisions,
* keys should be prefixed with `XX`.
*
* See [PDF 1.7, Appendix E - PDF Name
* Registry](https://archive.org/details/pdf1.7/page/n1017/mode/2up)
*/
customData?: Record<`XX${string}`, string | Uint8Array>;
/**
* Files to be stored directly within a PDF document. These files can
* be displayed and extracted by PDF viewers and other tools.
*/
embeddedFiles?: EmbeddedFile[];
/**
* Output intents that describe the intended output conditions for the
* document (e.g. for PDF/A or PDF/X conformance).
*/
outputIntents?: OutputIntent[];
/**
* Custom XMP metadata fragments to merge into the document's
* auto-generated XMP metadata. Each fragment declares a namespace
* and provides raw XML content for that namespace.
*/
xmpFragments?: XmpFragment[];
dev?: {
/**
* When set to true, additional guides are drawn to help analyzing
* the layout. A thin rectangle is drawn around each rendered frame.
* Margins are given a semi-transparent yellow background and
* padding areas are shown in blue.
*/
guides?: boolean;
};
};
/**
* Describes the relationship between the embedded file and the PDF
* document.
* - `Source`: The embedded file is the source material for the
* document.
* - `Data`: The embedded file contains data related to the document.
* - `Alternative`: The embedded file is an alternative representation
* of the document.
* - `Supplement`: The embedded file supplements the document.
* - `EncryptedPayload`: The embedded file is an encrypted payload.
* - `FormData`: The embedded file contains form data.
* - `Schema`: The embedded file contains a schema.
* - `Unspecified`: No specific relationship.
*/
export type FileRelationShip = 'Source' | 'Data' | 'Alternative' | 'Supplement' | 'EncryptedPayload' | 'FormData' | 'Schema' | 'Unspecified';
export type EmbeddedFile = {
/**
* The binary content of the file.
*/
content: Uint8Array;
/**
* The MIME type of the file.
*/
mimeType: string;
/**
* The name of the file as it will appear in the list of attachments
* in the PDF viewer.
*/
fileName: string;
/**
* A brief description of the file's content or purpose. This text
* can also be displayed by the PDF viewer.
*/
description?: string;
/**
* The date and time when the file was created.
*/
creationDate?: Date;
/**
* The date and time when the file was last modified.
*/
modificationDate?: Date;
/**
* The relationship between the file and the PDF document.
*/
relationship?: FileRelationShip;
};
/**
* Standard metadata properties to include in the PDF's *document
* information dictionary*. These properties are usually displayed by
* PDF viewers.
*/
export type InfoProps = {
/**
* The document’s title.
*/
title?: string;
/**
* The name of the person who created the document.
*/
author?: string;
/**
* The subject of the document.
*/
subject?: string;
/**
* Keywords associated with the document.
*/
keywords?: string[];
/**
* The date and time the document was created (defaults to current
* time).
*/
creationDate?: Date;
/**
* The name of the application that created the original content.
*/
creator?: string;
/**
* The name of the application that created the PDF.
*/
producer?: string;
};
/**
* Custom metadata properties to include in the PDF's *document
* information dictionary*. These properties should be prefixed with
* `XX` to avoid name collisions.
*/
export type CustomInfoProps = Record<`XX${string}`, string>;
/**
* Information about the current page, provided to functions that create
* page-specific headers, footers, and margins.
*/
export type PageInfo = {
/**
* The size of the current page in pt.
*/
readonly pageSize: {
width: number;
height: number;
};
/**
* The number of the current page, starting at 1.
*/
readonly pageNumber: number;
/**
* The total number of pages.
* This value is only available after the layout of the entire document has finished.
* Before that, it is `undefined`.
*/
readonly pageCount?: number;
};
/**
* An output intent that describes the intended output condition for the
* document. Output intents are required for PDF/A and PDF/X conformance.
*/
export type OutputIntent = {
/**
* The output intent subtype, e.g. `'GTS_PDFA1'` for PDF/A or
* `'GTS_PDFX'` for PDF/X.
*/
subtype: string;
/**
* An identifier for the intended output condition, e.g.
* `'sRGB IEC61966-2.1'`.
*/
outputConditionIdentifier: string;
/**
* The raw ICC profile data for the destination output condition.
*/
iccProfile: Uint8Array;
/**
* A human-readable description of the intended output condition.
*/
outputCondition?: string;
/**
* A URL for an ICC profile registry where the condition is defined.
*/
registryName?: string;
/**
* Additional information about the intended output condition.
*/
info?: string;
};
/**
* A fragment of XMP metadata scoped to a single namespace, to be
* merged into the document's auto-generated XMP.
*/
export type XmpFragment = {
/**
* The namespace URI (e.g. `'http://www.aiim.org/pdfa/ns/id/'`).
*/
namespaceUri: string;
/**
* The namespace prefix used in the XML content (e.g. `'pdfaid'`).
*/
prefix: string;
/**
* Raw XML content to place inside the `rdf:Description` element.
* The caller is responsible for ensuring the XML is well-formed.
*/
unsafeInnerXML: string;
};