@moatamed-sce/pdf-builder

A4 document primitives and HTML-to-PDF export for the SCE Platform. A document is composed from Angular components that already know about page geometry, then rasterised page-by-page into a PDF that paginates where you said it should — not wherever the browser's print engine happened to break.

Like the form platform, it has a declarative half and a runtime half: a PdfDefinition is a serializable document description, compilePdfDefinition turns it into a PdfDocumentModel, and the view components render that model.

Status — not published

This package is not currently on npmjs.org. It exists in the SCE monorepo and in the build output, and resolves through a TypeScript path alias inside it.

What's in it

Page primitives — sce-pdf-page (an A4 sheet with real margins), sce-pdf-section, sce-pdf-field-grid, sce-pdf-data-table, sce-pdf-numbered-list, sce-pdf-image, sce-pdf-signature, sce-pdf-qr-code, sce-pdf-footer, sce-pdf-watermark, plus sce-pdf-export-text and sce-pdf-export-stack for text that must survive rasterisation intact.

Geometry — PDF_PX_PER_MM, PDF_PAGE_SIZE_NAMES, DEFAULT_PDF_PAGE_CONFIG. Page size is expressed in millimetres and converted once, so a component never guesses at pixels.

The document schema — PdfDefinition and the element types beneath it (PdfDocumentPage, PdfDocumentSection, PdfDocumentField, PdfDocumentTableSection, PdfDocumentQr, PdfDocumentSignature, PdfDocumentCover …), compiled by compilePdfDefinition(definition, context) into a PdfDocumentModel.

Data binding — createPdfRenderContext, withPdfDataScope, resolvePdfPath. Paths are resolved against a data scope, and isValidPdfPath refuses __proto__, constructor and prototype segments: a document that can name a path is a document that could otherwise walk onto the prototype chain.

The trust boundary — parsePdfDefinition is where an untrusted JSON template is accepted or refused. Compile still never throws; the parser is what keeps a stored data: image or a prototype bind out of the designer.

Export — exportPagedHtmlPdfBlob(options) rasterises the rendered pages (via @zumer/snapdom) and assembles them with jsPDF; downloadPagedHtmlPdf(blob, fileName) hands the result to the user, falling back to opening a tab where a download is blocked.

RTL and formatters — isPdfRtl plus the number, date and currency formatters, so an Arabic document does not silently render Western digits or a mirrored table.

Peer dependencies

@moatamed-sce/core, @zumer/snapdom, jspdf, qrcode and RxJS 7.8.

Quick start

The views are driven by a compiled model, not by loose props: each component takes the model node it renders ([page], [section], [table]), which is what keeps a stored definition and a hand-composed document rendering through exactly the same code.

Compile a definition against its data:

import { compilePdfDefinition, createPdfRenderContext } from '@moatamed-sce/pdf-builder';

const context = createPdfRenderContext({ locale: 'ar', data: contract });
const model = compilePdfDefinition(definition, context);

Render the pages it produced:

@for (page of model.pages; track page.id; let i = $index) {
<sce-pdf-page [page]="page" [pageIndex]="i" [totalPages]="model.pages.length">
  @for (section of page.sections; track section.id) {
  <sce-pdf-section [section]="section" />
  }
</sce-pdf-page>
}

Then export what was rendered. The exporter captures the DOM, so it needs the element wrapping the page stack and the selector matching one element per page — plus the page box in both CSS pixels (what the DOM was laid out at) and millimetres (what jsPDF writes):

import { exportPagedHtmlPdfBlob, downloadPagedHtmlPdf, PDF_PX_PER_MM } from '@moatamed-sce/pdf-builder';

const blob = await exportPagedHtmlPdfBlob({
  rootElement: this.stack().nativeElement,
  pageSelector: '.sce-pdf-page',
  fileName: 'contract.pdf',
  widthPx: 210 * PDF_PX_PER_MM,
  heightPx: 297 * PDF_PX_PER_MM,
  widthMm: 210,
  heightMm: 297,
  onProgress: (current, total) => this.progress.set(current / total),
});

downloadPagedHtmlPdf(blob, 'contract.pdf');

MINIMAL_INVOICE_PDF_DEFINITION is exported as a worked example of the schema.

Why rasterised, and what that costs

Pages are captured as images and placed into the PDF. That is what makes the output match the screen exactly — Arabic shaping, custom fonts, CSS grid, chart canvases all survive, which a text-drawing PDF library cannot promise. The cost is that body text is not selectable or searchable in the result. Where text must stay real, use sce-pdf-export-text / sce-pdf-export-stack, which are drawn as text rather than captured.

Physical CSS properties (left, top) are correct inside PDF rendering and are an explicit exception to the repo's logical-properties rule: a page being rasterised at a fixed size is not a responsive layout.

Docs

• PDF architecture and extraction plan
• The generic PDF engine

License

MIT