@lpdfio/lpdf 0.23.0 → 0.25.0

package/dist/L.d.ts

@@ -30,7 +30,7 @@ export declare const L: Readonly<{
     /** Convert a `PdfDocument` tree to an lpdf XML string. */
     toXml: (doc: PdfDocument) => string;
     document: (attrs: import("./kit").DocumentAttr | null, nodes?: import("./kit").LpdfSectionNode[]) => PdfDocument;
-    section: (attrs: import("./kit").SectionAttr | null, nodes?: (import("./kit").LpdfLayoutBlock | import("./kit").LpdfCanvasBlock)[]) => import("./kit").LpdfSectionNode;
+    section: (attrs: import("./kit").SectionAttr | null, nodes?: (import("./layout").LpdfBookmarkNode | import("./kit").LpdfLayoutBlock | import("./kit").LpdfCanvasBlock)[]) => import("./kit").LpdfSectionNode;
     layout: (_attrs: null, nodes?: import("./layout").LpdfNode[]) => import("./kit").LpdfLayoutBlock;
     canvas: (_attrs: null, layers?: import("./canvas").LpdfCanvasLayerNode[]) => import("./kit").LpdfCanvasBlock;
     assets: (attrs: DocumentAssets) => DocumentAssets;
@@ -53,6 +53,7 @@ export declare const L: Readonly<{
     barcode: (attrs: import("./attrs").BarcodeAttr) => import("./layout").LpdfBarcodeNode;
     region: (attrs: import("./attrs").RegionAttr, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfRegionNode;
     field: (attrs: import("./attrs").FieldAttr) => import("./layout").LpdfFieldNode;
+    bookmark: (attrs: import("./attrs").BookmarkAttr) => import("./layout").LpdfBookmarkNode;
     layer: (attrs: import("./attrs").LayerAttr | null, nodes?: import("./canvas").LpdfCanvasPrimitiveNode[]) => import("./canvas").LpdfCanvasLayerNode;
     rect: (attrs: import("./attrs").RectAttr) => import("./canvas").LpdfCanvasRectNode;
     line: (attrs: import("./attrs").LineAttr) => import("./canvas").LpdfCanvasLineNode;

package/dist/L.js

@@ -61,6 +61,7 @@ exports.L = Object.freeze({
     barcode: layout_1.LpdfLayout.barcode,
     region: layout_1.LpdfLayout.region,
     field: layout_1.LpdfLayout.field,
+    bookmark: layout_1.LpdfLayout.bookmark,
     // ── Canvas ────────────────────────────────────────────────────────────────
     layer: canvas_1.LpdfCanvas.layer,
     rect: canvas_1.LpdfCanvas.rect,

package/dist/attrs.d.ts

@@ -21,6 +21,15 @@ export interface StackAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * Where the box falls in the page flow. no: never split the box, and move it whole to the next
+     * page when it does not fit. break-before: start it on a new page. break-after: start the next
+     * sibling on a new page. keep-next: keep it on one page with the sibling that follows, moving
+     * both to the next page if that sibling would not fit. break-before, break-after and keep-next
+     * take effect on the children of layout; on a box inside another box they are not applied. no
+     * applies at any depth.
+     */
+    paginate?: string;
     debug?: string;
     align?: string;
     justify?: string;
@@ -49,6 +58,15 @@ export interface FlankAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * Where the box falls in the page flow. no: never split the box, and move it whole to the next
+     * page when it does not fit. break-before: start it on a new page. break-after: start the next
+     * sibling on a new page. keep-next: keep it on one page with the sibling that follows, moving
+     * both to the next page if that sibling would not fit. break-before, break-after and keep-next
+     * take effect on the children of layout; on a box inside another box they are not applied. no
+     * applies at any depth.
+     */
+    paginate?: string;
     debug?: string;
     align?: string;
     /**
@@ -82,6 +100,15 @@ export interface SplitAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * Where the box falls in the page flow. no: never split the box, and move it whole to the next
+     * page when it does not fit. break-before: start it on a new page. break-after: start the next
+     * sibling on a new page. keep-next: keep it on one page with the sibling that follows, moving
+     * both to the next page if that sibling would not fit. break-before, break-after and keep-next
+     * take effect on the children of layout; on a box inside another box they are not applied. no
+     * applies at any depth.
+     */
+    paginate?: string;
     debug?: string;
     align?: string;
     /**
@@ -114,6 +141,15 @@ export interface ClusterAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * Where the box falls in the page flow. no: never split the box, and move it whole to the next
+     * page when it does not fit. break-before: start it on a new page. break-after: start the next
+     * sibling on a new page. keep-next: keep it on one page with the sibling that follows, moving
+     * both to the next page if that sibling would not fit. break-before, break-after and keep-next
+     * take effect on the children of layout; on a box inside another box they are not applied. no
+     * applies at any depth.
+     */
+    paginate?: string;
     debug?: string;
     align?: string;
     justify?: string;
@@ -142,6 +178,15 @@ export interface GridAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * Where the box falls in the page flow. no: never split the box, and move it whole to the next
+     * page when it does not fit. break-before: start it on a new page. break-after: start the next
+     * sibling on a new page. keep-next: keep it on one page with the sibling that follows, moving
+     * both to the next page if that sibling would not fit. break-before, break-after and keep-next
+     * take effect on the children of layout; on a box inside another box they are not applied. no
+     * applies at any depth.
+     */
+    paginate?: string;
     debug?: string;
     width?: string;
     colWidth?: string;
@@ -169,6 +214,15 @@ export interface FrameAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * Where the box falls in the page flow. no: never split the box, and move it whole to the next
+     * page when it does not fit. break-before: start it on a new page. break-after: start the next
+     * sibling on a new page. keep-next: keep it on one page with the sibling that follows, moving
+     * both to the next page if that sibling would not fit. break-before, break-after and keep-next
+     * take effect on the children of layout; on a box inside another box they are not applied. no
+     * applies at any depth.
+     */
+    paginate?: string;
     debug?: string;
     width?: string;
 }
@@ -176,6 +230,10 @@ export interface FrameAttr {
  * Attributes of the `link` element.
  */
 export interface LinkAttr {
+    /**
+     * Where the link goes: a URL, or #id to jump to the bookmark with that id. In an entry of a table
+     * of contents, # alone jumps to that entry's bookmark.
+     */
     href: string;
     gap?: string;
     width?: string;
@@ -198,6 +256,10 @@ export interface SpanAttr {
     font?: string;
     bold?: string;
     color?: string;
+    /**
+     * Makes the span a link: a URL, or #id to jump to the bookmark with that id. In an entry of a
+     * table of contents, # alone jumps to that entry's bookmark.
+     */
     href?: string;
     underline?: string;
     strike?: string;
@@ -216,6 +278,7 @@ export interface ImgAttr {
     background?: string;
     border?: string;
     radius?: string;
+    paginate?: string;
     debug?: string;
 }
 /**
@@ -231,6 +294,7 @@ export interface BarcodeAttr {
     hrt?: string;
     color?: string;
     background?: string;
+    paginate?: string;
     debug?: string;
 }
 /**
@@ -249,6 +313,20 @@ export interface TextAttr {
     color?: string;
     align?: string;
     width?: string;
+    /**
+     * The fewest lines of the text that may stand alone at the top of the next page when it splits.
+     * Default 2. If fewer would be left, lines move from the first page to the next; 1 turns the
+     * protection off.
+     */
+    widows?: string;
+    /**
+     * The fewest lines of the text that may stand alone at the bottom of a page when it splits.
+     * Default 2. If fewer would fit, the whole text moves to the next page; 1 turns the protection
+     * off. When no split can keep both widows and orphans, even on an empty page, the text splits
+     * where the lines fit.
+     */
+    orphans?: string;
+    paginate?: string;
     debug?: string;
 }
 /**
@@ -273,6 +351,15 @@ export interface TdAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * Where the box falls in the page flow. no: never split the box, and move it whole to the next
+     * page when it does not fit. break-before: start it on a new page. break-after: start the next
+     * sibling on a new page. keep-next: keep it on one page with the sibling that follows, moving
+     * both to the next page if that sibling would not fit. break-before, break-after and keep-next
+     * take effect on the children of layout; on a box inside another box they are not applied. no
+     * applies at any depth.
+     */
+    paginate?: string;
     debug?: string;
     align?: string;
     valign?: string;
@@ -305,6 +392,7 @@ export interface TableAttr {
     background?: string;
     width?: string;
     height?: string;
+    paginate?: string;
     debug?: string;
 }
 /**
@@ -328,6 +416,27 @@ export interface FieldAttr {
     border?: string;
     debug?: string;
 }
+/**
+ * An entry of the PDF's outline, the bookmark panel of a viewer, and a target for links with
+ * href="#id". It draws nothing and marks the element that follows it, so it is never left at the
+ * bottom of a page apart from that element. Directly inside a section, it marks the section's first
+ * page.
+ */
+export interface BookmarkAttr {
+    /** The text of the entry, in the outline and in a table of contents. */
+    label: string;
+    /**
+     * Depth in the outline, 1 to 6. Defaults to 1. An entry nests under the closest entry before it
+     * with a lower level.
+     */
+    level?: string;
+    /**
+     * The name links use to jump here, as href="#id". Leave it out to make it from the label:
+     * lowercase, with other characters than letters and digits turned into hyphens, and -2, -3 added
+     * when an earlier bookmark has it. Two bookmarks may not have the same id.
+     */
+    id?: string;
+}
 /**
  * Pins content to the top or bottom edge of pages, outside the normal flow, for headers and
  * footers. It reserves that space on every page it appears on. Only allowed directly inside layout,

package/dist/browser.js

@@ -410,6 +410,9 @@ var Orientation = {
   Portrait: "portrait",
   Landscape: "landscape"
 };
+var SectionType = {
+  Toc: "toc"
+};
 var BuiltinFont = {
   Courier: "Courier",
   CourierBold: "Courier-Bold",
@@ -491,5 +494,6 @@ export {
   Orientation,
   PageScope,
   Pin,
+  SectionType,
   initLpdf
 };

package/dist/constants.d.ts

@@ -21,6 +21,11 @@ export declare const Orientation: {
     readonly Landscape: "landscape";
 };
 export type Orientation = (typeof Orientation)[keyof typeof Orientation];
+/** The values of the `type` attribute of a section. */
+export declare const SectionType: {
+    readonly Toc: "toc";
+};
+export type SectionType = (typeof SectionType)[keyof typeof SectionType];
 /** The values of the `core` attribute of a font: the built-in PDF fonts, which need no file. */
 export declare const BuiltinFont: {
     readonly Courier: "Courier";

package/dist/constants.js

@@ -2,7 +2,7 @@
 // Generated from lpdf.xsd by scripts/gen-sdk-api.mjs.
 // Do not edit: change the schema and run `make gen-sdk-api`.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PageScope = exports.BuiltinFont = exports.Orientation = exports.Pin = exports.FieldType = void 0;
+exports.PageScope = exports.BuiltinFont = exports.SectionType = exports.Orientation = exports.Pin = exports.FieldType = void 0;
 /** The values of the `type` attribute of a field. */
 exports.FieldType = {
     Text: 'text',
@@ -23,6 +23,10 @@ exports.Orientation = {
     Portrait: 'portrait',
     Landscape: 'landscape',
 };
+/** The values of the `type` attribute of a section. */
+exports.SectionType = {
+    Toc: 'toc',
+};
 /** The values of the `core` attribute of a font: the built-in PDF fonts, which need no file. */
 exports.BuiltinFont = {
     Courier: 'Courier',

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { PdfEngine, LpdfRenderError } from './engine';
 export type { EncryptPermissions, EncryptOptions } from './engine';
 export type { RenderOptions, EngineOptions } from './_shared';
-export { FieldType, Pin, Orientation, BuiltinFont, PageScope } from './constants';
+export { FieldType, Pin, Orientation, SectionType, BuiltinFont, PageScope } from './constants';
 export type { PdfDocument, LpdfSectionNode, LpdfLayoutBlock, LpdfCanvasBlock, DocumentTokens, DocumentAssets, DocumentMeta, SectionAttr, DocumentAttr, } from './kit';
-export type { StackAttr, FlankAttr, SplitAttr, ClusterAttr, GridAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, SpanAttr, DividerAttr, ImgAttr, BarcodeAttr, RegionAttr, FieldAttr, LayerAttr, RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, CanvasTextAttr, CanvasImgAttr, FontAttr, ImageAttr, } from './attrs';
-export type { LpdfNode, LpdfContainerNode, LpdfTextNode, LpdfSpanNode, LpdfDividerNode, LpdfImgNode, LpdfBarcodeNode, LpdfTableNode, LpdfTheadNode, LpdfTrNode, LpdfTdNode, LpdfRegionNode, LpdfFieldNode, } from './layout';
+export type { StackAttr, FlankAttr, SplitAttr, ClusterAttr, GridAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, SpanAttr, DividerAttr, ImgAttr, BarcodeAttr, RegionAttr, FieldAttr, BookmarkAttr, LayerAttr, RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, CanvasTextAttr, CanvasImgAttr, FontAttr, ImageAttr, } from './attrs';
+export type { LpdfNode, LpdfContainerNode, LpdfTextNode, LpdfSpanNode, LpdfDividerNode, LpdfImgNode, LpdfBarcodeNode, LpdfTableNode, LpdfTheadNode, LpdfTrNode, LpdfTdNode, LpdfRegionNode, LpdfFieldNode, LpdfBookmarkNode, } from './layout';
 export { CanvasTransform } from './canvas';
 export type { LpdfCanvasLayerNode, LpdfCanvasPrimitiveNode, LpdfCanvasRectNode, LpdfCanvasLineNode, LpdfCanvasEllipseNode, LpdfCanvasCircleNode, LpdfCanvasPathNode, LpdfCanvasTextNode, LpdfCanvasImgNode, } from './canvas';
 export { L, NoAttr } from './L';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoAttr = exports.L = exports.CanvasTransform = exports.PageScope = exports.BuiltinFont = exports.Orientation = exports.Pin = exports.FieldType = exports.LpdfRenderError = exports.PdfEngine = void 0;
+exports.NoAttr = exports.L = exports.CanvasTransform = exports.PageScope = exports.BuiltinFont = exports.SectionType = exports.Orientation = exports.Pin = exports.FieldType = exports.LpdfRenderError = exports.PdfEngine = void 0;
 // ── Engine ────────────────────────────────────────────────────────────────────
 var engine_1 = require("./engine");
 Object.defineProperty(exports, "PdfEngine", { enumerable: true, get: function () { return engine_1.PdfEngine; } });
@@ -10,6 +10,7 @@ var constants_1 = require("./constants");
 Object.defineProperty(exports, "FieldType", { enumerable: true, get: function () { return constants_1.FieldType; } });
 Object.defineProperty(exports, "Pin", { enumerable: true, get: function () { return constants_1.Pin; } });
 Object.defineProperty(exports, "Orientation", { enumerable: true, get: function () { return constants_1.Orientation; } });
+Object.defineProperty(exports, "SectionType", { enumerable: true, get: function () { return constants_1.SectionType; } });
 Object.defineProperty(exports, "BuiltinFont", { enumerable: true, get: function () { return constants_1.BuiltinFont; } });
 Object.defineProperty(exports, "PageScope", { enumerable: true, get: function () { return constants_1.PageScope; } });
 // ── Canvas types ──────────────────────────────────────────────────────────────

package/dist/kit.d.ts

@@ -23,7 +23,7 @@
  * const bytes = await new LpdfEngine(key).renderPdf(doc);
  * ```
  */
-import type { LpdfNode } from './layout';
+import type { LpdfBookmarkNode, LpdfNode } from './layout';
 import type { LpdfCanvasLayerNode } from './canvas';
 import type { FontAttr, ImageAttr } from './attrs';
 export interface DocumentTokens {
@@ -57,6 +57,8 @@ export interface SectionAttr {
     background?: string;
     title?: string;
     debug?: string;
+    type?: string;
+    tocIndentStep?: string;
 }
 export interface DocumentAttr {
     size?: string;
@@ -82,7 +84,7 @@ export interface LpdfCanvasBlock {
 export interface LpdfSectionNode {
     type: 'section';
     attrs: Record<string, string>;
-    nodes: (LpdfLayoutBlock | LpdfCanvasBlock)[];
+    nodes: (LpdfBookmarkNode | LpdfLayoutBlock | LpdfCanvasBlock)[];
 }
 export interface PdfDocument {
     version: 1;
@@ -92,7 +94,7 @@ export interface PdfDocument {
 }
 declare function layout(_attrs: null, nodes?: LpdfNode[]): LpdfLayoutBlock;
 declare function canvas(_attrs: null, layers?: LpdfCanvasLayerNode[]): LpdfCanvasBlock;
-declare function section(attrs: SectionAttr | null, nodes?: (LpdfLayoutBlock | LpdfCanvasBlock)[]): LpdfSectionNode;
+declare function section(attrs: SectionAttr | null, nodes?: (LpdfBookmarkNode | LpdfLayoutBlock | LpdfCanvasBlock)[]): LpdfSectionNode;
 declare function document(attrs: DocumentAttr | null, nodes?: LpdfSectionNode[]): PdfDocument;
 export declare const LpdfKit: Readonly<{
     layout: typeof layout;

package/dist/layout.d.ts

@@ -1,4 +1,4 @@
-import type { StackAttr, FlankAttr, SplitAttr, ClusterAttr, GridAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, SpanAttr, DividerAttr, ImgAttr, BarcodeAttr, FieldAttr, RegionAttr } from './attrs';
+import type { StackAttr, FlankAttr, SplitAttr, ClusterAttr, GridAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, SpanAttr, DividerAttr, ImgAttr, BarcodeAttr, FieldAttr, RegionAttr, BookmarkAttr } from './attrs';
 export interface LpdfSpanNode {
     type: 'span';
     attrs: Record<string, string>;
@@ -55,7 +55,12 @@ export interface LpdfFieldNode {
     type: 'field';
     attrs: Record<string, string>;
 }
-export type LpdfNode = LpdfContainerNode | LpdfTextNode | LpdfDividerNode | LpdfTableNode | LpdfImgNode | LpdfBarcodeNode | LpdfRegionNode | LpdfFieldNode;
+/** An outline entry and link target that marks the node after it; it draws nothing. */
+export interface LpdfBookmarkNode {
+    type: 'bookmark';
+    attrs: Record<string, string>;
+}
+export type LpdfNode = LpdfContainerNode | LpdfTextNode | LpdfDividerNode | LpdfTableNode | LpdfImgNode | LpdfBarcodeNode | LpdfRegionNode | LpdfFieldNode | LpdfBookmarkNode;
 declare function stack(attrs: StackAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
 declare function flank(attrs: FlankAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
 declare function split(attrs: SplitAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
@@ -74,6 +79,11 @@ declare function img(attrs: ImgAttr): LpdfImgNode;
 declare function barcode(attrs: BarcodeAttr): LpdfBarcodeNode;
 declare function region(attrs: RegionAttr, nodes?: LpdfNode[]): LpdfRegionNode;
 declare function field(attrs: FieldAttr): LpdfFieldNode;
+/**
+ * An entry of the PDF's outline and a target for `href: '#id'` links. It marks the node that follows it
+ * in the same list; directly in a section's nodes, it marks the section's first page.
+ */
+declare function bookmark(attrs: BookmarkAttr): LpdfBookmarkNode;
 export declare const LpdfLayout: Readonly<{
     stack: typeof stack;
     flank: typeof flank;
@@ -93,5 +103,6 @@ export declare const LpdfLayout: Readonly<{
     td: typeof td;
     region: typeof region;
     field: typeof field;
+    bookmark: typeof bookmark;
 }>;
 export {};

package/dist/layout.js

@@ -61,6 +61,13 @@ function region(attrs, nodes = []) {
 function field(attrs) {
     return { type: 'field', attrs: (0, _shared_1.buildAttrs)(attrs) };
 }
+/**
+ * An entry of the PDF's outline and a target for `href: '#id'` links. It marks the node that follows it
+ * in the same list; directly in a section's nodes, it marks the section's first page.
+ */
+function bookmark(attrs) {
+    return { type: 'bookmark', attrs: (0, _shared_1.buildAttrs)(attrs) };
+}
 exports.LpdfLayout = Object.freeze({
     stack,
     flank,
@@ -80,4 +87,5 @@ exports.LpdfLayout = Object.freeze({
     td,
     region,
     field,
+    bookmark,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpdfio/lpdf",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Node.js SDK for Lpdf — PDF as Code on every platform. You describe a document as code or XML. Lpdf renders a compact, pixel-perfect PDF — identical across platforms.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",