@lpdfio/lpdf 0.29.0 → 0.31.0

package/LICENSE

@@ -70,7 +70,7 @@ Unlicensed Use is not a substitute for a Professional or Enterprise License. An
 
 Unlicensed Use is subject to the following restriction:
 
-**Attribution.** Each document rendered shall include an attribution notice in the form specified in the Software documentation. This notice may not be suppressed, removed, or obscured.
+**Attribution.** Each document rendered shall include the Lpdf attribution in the top-right corner. This notice may not be suppressed, removed, or obscured.
 
 This restriction is lifted upon obtaining a valid license key. Community keys are available at no cost at lpdf.io.
 

package/README.md

@@ -25,10 +25,10 @@ const doc = L.document({ size: 'letter' }, [
             L.column({ gap: '24pt' }, [
                 L.row({ justify: 'between' }, [
                     L.text({ fontSize: '8pt', color: '#888888' }, ['ACME CORP']),
-                    L.text({ fontSize: '22pt', bold: 'true' }, ['Project Proposal']),
+                    L.text({ fontSize: '22pt', bold: true }, ['Project Proposal']),
                 ]),
                 L.divider({ thickness: 'xs' }),
-                L.text({ fontSize: '13pt', bold: 'true' }, ['Scope of Work']),
+                L.text({ fontSize: '13pt', bold: true }, ['Scope of Work']),
                 L.row({ gap: '12pt', align: 'start' }, [
                     L.text({ color: '#888888', width: '24pt' }, ['01']),
                     L.text({ width: 'fill' }, ['Discovery & Research']),

package/dist/L.d.ts

@@ -32,19 +32,24 @@ export declare const L: Readonly<{
     document: (attrs: import("./kit").DocumentAttr | null, nodes?: import("./kit").LpdfSectionNode[]) => PdfDocument;
     section: (attrs: import("./kit").SectionAttr | null, nodes?: import("./kit").LpdfSectionChild[]) => import("./kit").LpdfSectionNode;
     layout: (attrs: import("./attrs").LayoutAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./kit").LpdfLayoutBlock;
+    markdown: (attrs: import("./attrs").MarkdownAttr | null, nodes?: (import("./markdown").LpdfMarkdownStylesNode | import("./markdown").LpdfMarkdownContentNode)[]) => import("./markdown").LpdfMarkdownNode;
     assets: (attrs: DocumentAssets) => DocumentAssets;
     tokens: (attrs: DocumentTokens) => DocumentTokens;
     column: (attrs: import("./attrs").ColumnAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
     row: (attrs: import("./attrs").RowAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
     grid: (attrs: import("./attrs").GridAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
+    list: (attrs: import("./attrs").ListAttr | null, nodes?: import("./layout").LpdfLiNode[]) => import("./layout").LpdfListNode;
+    li: (attrs: import("./attrs").LiAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfLiNode;
     frame: (attrs: import("./attrs").FrameAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
     link: (attrs: import("./attrs").LinkAttr, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
     table: (attrs: import("./attrs").TableAttr, nodes?: (import("./layout").LpdfTheadNode | import("./layout").LpdfTrNode)[]) => import("./layout").LpdfTableNode;
     thead: (attrs: import("./attrs").TheadAttr | null, nodes?: import("./layout").LpdfTdNode[]) => import("./layout").LpdfTheadNode;
     tr: (attrs: import("./attrs").TrAttr | null, nodes?: import("./layout").LpdfTdNode[]) => import("./layout").LpdfTrNode;
     td: (attrs: import("./attrs").TdAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfTdNode;
-    text: (attrs: import("./attrs").TextAttr | null, nodes?: (string | import("./layout").LpdfSpanNode | import("./layout").LpdfFnNode)[]) => import("./layout").LpdfTextNode;
+    text: (attrs: import("./attrs").TextAttr | null, nodes?: (string | import("./layout").LpdfSpanNode | import("./layout").LpdfCodeSpanNode | import("./layout").LpdfFnNode)[]) => import("./layout").LpdfTextNode;
+    code: (attrs: import("./attrs").CodeAttr | null, nodes?: (string | import("./layout").LpdfSpanNode)[]) => import("./layout").LpdfCodeNode;
     span: (attrs: import("./attrs").SpanAttr | null, nodes?: string[]) => import("./layout").LpdfSpanNode;
+    codeSpan: (attrs: import("./attrs").CodeSpanAttr | null, nodes?: string[]) => import("./layout").LpdfCodeSpanNode;
     fn: (attrs: null, nodes?: (string | import("./layout").LpdfSpanNode)[]) => import("./layout").LpdfFnNode;
     divider: (attrs?: import("./attrs").DividerAttr | null) => import("./layout").LpdfDividerNode;
     img: (attrs: import("./attrs").ImgAttr) => import("./layout").LpdfImgNode;
@@ -59,7 +64,7 @@ export declare const L: Readonly<{
     ellipse: (attrs: import("./attrs").EllipseAttr) => import("./canvas").LpdfCanvasEllipseNode;
     circle: (attrs: import("./attrs").CircleAttr) => import("./canvas").LpdfCanvasCircleNode;
     path: (attrs: import("./attrs").PathAttr) => import("./canvas").LpdfCanvasPathNode;
-    textAt: (attrs: import("./attrs").TextAtAttr, nodes?: (string | import("./layout").LpdfSpanNode)[]) => import("./canvas").LpdfCanvasTextAtNode;
+    textAt: (attrs: import("./attrs").TextAtAttr, nodes?: (string | import("./layout").LpdfSpanNode | import("./layout").LpdfCodeSpanNode)[]) => import("./canvas").LpdfCanvasTextAtNode;
     imgAt: (attrs: import("./attrs").ImgAtAttr) => import("./canvas").LpdfCanvasImgAtNode;
     barcodeAt: (attrs: import("./attrs").BarcodeAtAttr) => import("./canvas").LpdfCanvasBarcodeAtNode;
 }>;

package/dist/L.js

@@ -4,6 +4,7 @@ exports.L = exports.NoAttr = void 0;
 const kit_1 = require("./kit");
 const layout_1 = require("./layout");
 const canvas_1 = require("./canvas");
+const markdown_1 = require("./markdown");
 const engine_1 = require("./engine");
 const kit_to_xml_1 = require("./kit-to-xml");
 /** Pass as `attrs` when a node has no attributes. Equivalent to `null`. */
@@ -39,12 +40,15 @@ exports.L = Object.freeze({
     document: kit_1.LpdfKit.document,
     section: kit_1.LpdfKit.section,
     layout: kit_1.LpdfKit.layout,
+    markdown: markdown_1.LpdfMarkdown.markdown,
     assets: (attrs) => attrs,
     tokens: (attrs) => attrs,
     // ── Layout ────────────────────────────────────────────────────────────────
     column: layout_1.LpdfLayout.column,
     row: layout_1.LpdfLayout.row,
     grid: layout_1.LpdfLayout.grid,
+    list: layout_1.LpdfLayout.list,
+    li: layout_1.LpdfLayout.li,
     frame: layout_1.LpdfLayout.frame,
     link: layout_1.LpdfLayout.link,
     table: layout_1.LpdfLayout.table,
@@ -52,7 +56,9 @@ exports.L = Object.freeze({
     tr: layout_1.LpdfLayout.tr,
     td: layout_1.LpdfLayout.td,
     text: layout_1.LpdfLayout.text,
+    code: layout_1.LpdfLayout.code,
     span: layout_1.LpdfLayout.span,
+    codeSpan: layout_1.LpdfLayout.codeSpan,
     fn: layout_1.LpdfLayout.fn,
     divider: layout_1.LpdfLayout.divider,
     img: layout_1.LpdfLayout.img,

package/dist/_shared.d.ts

@@ -9,6 +9,7 @@ export interface RenderOptions {
      * Optional ISO 8601 creation timestamp (e.g. `"2024-06-01T12:00:00"`).
      * When provided, written as `/CreationDate` in the PDF info dictionary.
      * Omitting this keeps builds reproducible (no embedded timestamp).
+     * Required for a document whose `output` asks for `pdfa`, which writes it as both dates of the file.
      */
     createdOn?: string;
     /**
@@ -17,10 +18,48 @@ export interface RenderOptions {
      * Only applies when `input` is an XML string.
      */
     data?: Record<string, unknown> | null;
+    /**
+     * The password a reader asks for before showing the PDF, for a document that asks for encryption in its
+     * `output`. Leave it out, or pass `''`, for a PDF anyone can open, which only the `allow` of the `output`
+     * restricts.
+     */
+    userPassword?: string;
+    /**
+     * The password that opens the PDF with every permission. A document that asks for encryption in its `output`
+     * renders only with it, or with `skipEncryption`; a document that doesn't ask for encryption refuses it, so a
+     * file never goes out unencrypted while you believe it is locked.
+     */
+    ownerPassword?: string;
+    /**
+     * Renders a document that asks for encryption unencrypted, for a render that cannot have the passwords, such as
+     * a preview. Not together with the passwords.
+     */
+    skipEncryption?: boolean;
 }
+/**
+ * The arguments of the engine's render calls after the document: the passwords and `skipEncryption` as given,
+ * and, when there is a password, 32 bytes from the platform's secure generator for AES-256 to cut its key, salts
+ * and IVs from, fresh for each render.
+ */
+export declare function encryptionArguments(options: RenderOptions, randomBytes: (count: number) => Uint8Array): [string | null, string | null, boolean, Uint8Array];
+/** The value of an attribute in a document tree: a string, a number or a boolean, as the schema types it. */
+export type AttrValue = string | number | boolean;
 /**
  * The attributes of an element: an attribute object's own properties, with each camelCase name
- * written as the schema's kebab-case one (`fontSize` as `font-size`) and each value as a string.
- * Properties that are `undefined` are left out.
+ * written as the schema's kebab-case one (`fontSize` as `font-size`) and each value as it is given:
+ * `bold: true` and `cols: 3` stay a boolean and a number. The engine refuses a value of the wrong
+ * type, such as `cols: '3'` from plain JavaScript, when it renders. A `NaN` or an infinity, which
+ * JSON can't hold, is refused here with a `RangeError`. Properties that are `undefined` are left out.
+ *
+ * @throws {RangeError} when a value is a number that isn't finite.
+ */
+export declare function buildAttrs(options: object | null | undefined): Record<string, AttrValue>;
+/**
+ * Refuses a number a document can't hold, `NaN` or an infinity, naming where it is. JSON has no such number:
+ * `JSON.stringify` writes it as `null`, which the engine takes as an attribute that isn't there.
+ *
+ * @throws {RangeError} when `value` is a number that isn't finite.
  */
-export declare function buildAttrs(options: object | null | undefined): Record<string, string>;
+export declare function assertFinite(name: string, value: unknown): void;
+/** Refuses a number that isn't finite anywhere in `value`, an object or a list, named by its path from `name`. */
+export declare function assertFiniteIn(name: string, value: unknown): void;

package/dist/_shared.js

@@ -3,18 +3,67 @@
  * Shared types used by both the Node.js and browser entry points.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptionArguments = encryptionArguments;
 exports.buildAttrs = buildAttrs;
+exports.assertFinite = assertFinite;
+exports.assertFiniteIn = assertFiniteIn;
+/** The random bytes AES-256 needs from the host, one 256-bit key's worth. The engine makes none itself. */
+const ENTROPY_BYTES = 32;
+/**
+ * The arguments of the engine's render calls after the document: the passwords and `skipEncryption` as given,
+ * and, when there is a password, 32 bytes from the platform's secure generator for AES-256 to cut its key, salts
+ * and IVs from, fresh for each render.
+ */
+function encryptionArguments(options, randomBytes) {
+    const hasPassword = options.userPassword !== undefined || options.ownerPassword !== undefined;
+    return [
+        options.userPassword ?? null,
+        options.ownerPassword ?? null,
+        options.skipEncryption ?? false,
+        hasPassword ? randomBytes(ENTROPY_BYTES) : new Uint8Array(0),
+    ];
+}
 /**
  * The attributes of an element: an attribute object's own properties, with each camelCase name
- * written as the schema's kebab-case one (`fontSize` as `font-size`) and each value as a string.
- * Properties that are `undefined` are left out.
+ * written as the schema's kebab-case one (`fontSize` as `font-size`) and each value as it is given:
+ * `bold: true` and `cols: 3` stay a boolean and a number. The engine refuses a value of the wrong
+ * type, such as `cols: '3'` from plain JavaScript, when it renders. A `NaN` or an infinity, which
+ * JSON can't hold, is refused here with a `RangeError`. Properties that are `undefined` are left out.
+ *
+ * @throws {RangeError} when a value is a number that isn't finite.
  */
 function buildAttrs(options) {
     const result = {};
     for (const [key, value] of Object.entries(options ?? {})) {
         if (value !== undefined && value !== null) {
-            result[key.replace(/[A-Z]/g, c => '-' + c.toLowerCase())] = String(value);
+            const name = key.replace(/[A-Z]/g, c => '-' + c.toLowerCase());
+            assertFinite(name, value);
+            result[name] = value;
         }
     }
     return result;
 }
+/**
+ * Refuses a number a document can't hold, `NaN` or an infinity, naming where it is. JSON has no such number:
+ * `JSON.stringify` writes it as `null`, which the engine takes as an attribute that isn't there.
+ *
+ * @throws {RangeError} when `value` is a number that isn't finite.
+ */
+function assertFinite(name, value) {
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new RangeError(`${name} must be a finite number, not ${value}`);
+    }
+}
+/** Refuses a number that isn't finite anywhere in `value`, an object or a list, named by its path from `name`. */
+function assertFiniteIn(name, value) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertFiniteIn(`${name}[${index}]`, item));
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const [key, item] of Object.entries(value))
+            assertFiniteIn(`${name}.${key}`, item);
+    }
+    else {
+        assertFinite(name, value);
+    }
+}