@lpdfio/lpdf 0.25.0 → 0.27.0

package/README.md

@@ -19,19 +19,19 @@ const { L, NoAttr } = require('@lpdfio/lpdf')
 
 const engine = L.engine()
 
-const doc = L.document({ size: 'letter', margin: '48pt' }, [
+const doc = L.document({ size: 'letter' }, [
     L.section(NoAttr, [
-        L.layout(NoAttr, [
-            L.stack({ gap: '24pt' }, [
-                L.split(NoAttr, [
+        L.layout({ margin: '48pt' }, [
+            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.divider({ thickness: 'xs' }),
                 L.text({ fontSize: '13pt', bold: 'true' }, ['Scope of Work']),
-                L.flank({ gap: '12pt', align: 'start' }, [
+                L.row({ gap: '12pt', align: 'start' }, [
                     L.text({ color: '#888888', width: '24pt' }, ['01']),
-                    L.text(NoAttr, ['Discovery & Research']),
+                    L.text({ width: 'fill' }, ['Discovery & Research']),
                 ]),
             ]),
         ]),

package/dist/L.d.ts

@@ -5,7 +5,7 @@ export declare const NoAttr: null;
 /**
  * Unified lpdf facade.
  *
- * All document, layout, and canvas factory methods are available as flat
+ * All document, layout, and layer factory methods are available as flat
  * properties on this object. Construction-time configuration is handled via
  * `L.engine()`.
  *
@@ -30,15 +30,12 @@ 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("./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;
+    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;
     assets: (attrs: DocumentAssets) => DocumentAssets;
     tokens: (attrs: DocumentTokens) => DocumentTokens;
-    stack: (attrs: import("./attrs").StackAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
-    flank: (attrs: import("./attrs").FlankAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
-    split: (attrs: import("./attrs").SplitAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
-    cluster: (attrs: import("./attrs").ClusterAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
+    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;
     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;
@@ -60,6 +57,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").CanvasTextAttr, nodes?: (string | import("./layout").LpdfSpanNode)[]) => import("./canvas").LpdfCanvasTextNode;
-    imgAt: (attrs: import("./attrs").CanvasImgAttr) => import("./canvas").LpdfCanvasImgNode;
+    textAt: (attrs: import("./attrs").TextAtAttr, nodes?: (string | import("./layout").LpdfSpanNode)[]) => import("./canvas").LpdfCanvasTextAtNode;
+    imgAt: (attrs: import("./attrs").ImgAtAttr) => import("./canvas").LpdfCanvasImgAtNode;
+    barcodeAt: (attrs: import("./attrs").BarcodeAtAttr) => import("./canvas").LpdfCanvasBarcodeAtNode;
 }>;

package/dist/L.js

@@ -11,7 +11,7 @@ exports.NoAttr = null;
 /**
  * Unified lpdf facade.
  *
- * All document, layout, and canvas factory methods are available as flat
+ * All document, layout, and layer factory methods are available as flat
  * properties on this object. Construction-time configuration is handled via
  * `L.engine()`.
  *
@@ -39,14 +39,11 @@ exports.L = Object.freeze({
     document: kit_1.LpdfKit.document,
     section: kit_1.LpdfKit.section,
     layout: kit_1.LpdfKit.layout,
-    canvas: kit_1.LpdfKit.canvas,
     assets: (attrs) => attrs,
     tokens: (attrs) => attrs,
     // ── Layout ────────────────────────────────────────────────────────────────
-    stack: layout_1.LpdfLayout.stack,
-    flank: layout_1.LpdfLayout.flank,
-    split: layout_1.LpdfLayout.split,
-    cluster: layout_1.LpdfLayout.cluster,
+    column: layout_1.LpdfLayout.column,
+    row: layout_1.LpdfLayout.row,
     grid: layout_1.LpdfLayout.grid,
     frame: layout_1.LpdfLayout.frame,
     link: layout_1.LpdfLayout.link,
@@ -62,7 +59,7 @@ exports.L = Object.freeze({
     region: layout_1.LpdfLayout.region,
     field: layout_1.LpdfLayout.field,
     bookmark: layout_1.LpdfLayout.bookmark,
-    // ── Canvas ────────────────────────────────────────────────────────────────
+    // ── Layers ────────────────────────────────────────────────────────────────
     layer: canvas_1.LpdfCanvas.layer,
     rect: canvas_1.LpdfCanvas.rect,
     line: canvas_1.LpdfCanvas.line,
@@ -71,4 +68,5 @@ exports.L = Object.freeze({
     path: canvas_1.LpdfCanvas.path,
     textAt: canvas_1.LpdfCanvas.textAt,
     imgAt: canvas_1.LpdfCanvas.imgAt,
+    barcodeAt: canvas_1.LpdfCanvas.barcodeAt,
 });

package/dist/attrs.d.ts

@@ -2,7 +2,7 @@
  * Places children top to bottom, each at the full width, with gap between them. Can split across
  * pages between children.
  */
-export interface StackAttr {
+export interface ColumnAttr {
     font?: string;
     fontSize?: string;
     gap?: string;
@@ -33,55 +33,20 @@ export interface StackAttr {
     debug?: string;
     align?: string;
     justify?: string;
-    width?: string;
-}
-/**
- * One row where the children keep their own width except one, which fills the rest. By default the
- * last child fills; set end to true and the first fills. Never splits across pages.
- */
-export interface FlankAttr {
-    font?: string;
-    fontSize?: string;
-    gap?: string;
-    /**
-     * Space between the edge of the box and its content, written like CSS: one value for all sides,
-     * two for top-bottom and left-right, three for top, left-right and bottom, four for top, right,
-     * bottom and left.
-     */
-    padding?: string;
-    /**
-     * Height of the box. Leave it out to size to the content. A length fixes it; fill takes what is
-     * left after its siblings (shared equally if several use fill); full takes all the height
-     * available. Any of these stops the box splitting across pages.
-     */
-    height?: string;
-    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.
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
      */
-    paginate?: string;
-    debug?: string;
-    align?: string;
-    /**
-     * false (the default): every child but the last keeps its own width at the left, and the last
-     * fills the rest. true: the first child fills, and the others keep their own width at the right.
-     */
-    end?: string;
     width?: string;
 }
 /**
- * Two children side by side; any further children are ignored. By default each keeps its own width,
- * the first at the left edge and the second at the right. With equal set to true they take half the
- * width each. Never splits across pages.
+ * Children side by side, continuing on the next line when they run out of width. A child with width
+ * set to fill takes what its line leaves; justify set to between puts a line's first child at the
+ * left edge, its last at the right and the others evenly between. Splits across pages between
+ * lines.
  */
-export interface SplitAttr {
+export interface RowAttr {
     font?: string;
     fontSize?: string;
     gap?: string;
@@ -111,48 +76,12 @@ export interface SplitAttr {
     paginate?: string;
     debug?: string;
     align?: string;
+    justify?: string;
     /**
-     * false (the default): each child keeps its own width, the first at the left edge and the second
-     * at the right edge. true: the two children share the width in equal halves.
-     */
-    equal?: string;
-    width?: string;
-}
-/**
- * A row that wraps: children sit side by side, and continue on the next line when they run out of
- * width. Splits across pages between lines.
- */
-export interface ClusterAttr {
-    font?: string;
-    fontSize?: string;
-    gap?: string;
-    /**
-     * Space between the edge of the box and its content, written like CSS: one value for all sides,
-     * two for top-bottom and left-right, three for top, left-right and bottom, four for top, right,
-     * bottom and left.
-     */
-    padding?: string;
-    /**
-     * Height of the box. Leave it out to size to the content. A length fixes it; fill takes what is
-     * left after its siblings (shared equally if several use fill); full takes all the height
-     * available. Any of these stops the box splitting across pages.
-     */
-    height?: string;
-    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.
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
      */
-    paginate?: string;
-    debug?: string;
-    align?: string;
-    justify?: string;
     width?: string;
 }
 /**
@@ -188,6 +117,11 @@ export interface GridAttr {
      */
     paginate?: string;
     debug?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
     width?: string;
     colWidth?: string;
     cols?: string;
@@ -224,6 +158,11 @@ export interface FrameAttr {
      */
     paginate?: string;
     debug?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
     width?: string;
 }
 /**
@@ -236,6 +175,11 @@ export interface LinkAttr {
      */
     href: string;
     gap?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
     width?: string;
     height?: string;
     debug?: string;
@@ -247,6 +191,12 @@ export interface DividerAttr {
     direction?: string;
     color?: string;
     thickness?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
+    width?: string;
     debug?: string;
 }
 /**
@@ -265,11 +215,20 @@ export interface SpanAttr {
     strike?: string;
 }
 /**
- * Attributes of the `img` element.
+ * An image. It is never stretched. With only a width or a height, the other follows the image's
+ * proportions. With both, they are a maximum: the image takes the largest size that fits in them,
+ * and its box becomes that size, which the parent's align places. To put images of different shapes
+ * in slots of one size, wrap each in a frame of that size. With neither, the image has its natural
+ * size.
  */
 export interface ImgAttr {
     name: string;
     height?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
     width?: string;
     font?: string;
     fontSize?: string;
@@ -282,18 +241,34 @@ export interface ImgAttr {
     debug?: string;
 }
 /**
- * Attributes of the `barcode` element.
+ * A QR code, a Code 128 or an EAN-13. It is never stretched. With only a width or a height, the
+ * other follows the barcode's proportions. With both, they are a maximum: the barcode takes the
+ * largest size that fits in them, and its box becomes that size, which the parent's align places.
+ * To put barcodes in slots of one size, wrap each in a frame of that size.
  */
 export interface BarcodeAttr {
     type: string;
     data: string;
-    size?: string;
-    width?: string;
+    /**
+     * Height of the whole barcode, with the digits of hrt inside it: they take the bottom 12pt and
+     * the bars the rest. A barcode is never stretched. With only a height, the width follows the
+     * barcode's proportions. With both width and height, they are a maximum: the barcode takes the
+     * largest size that fits in them, and its box becomes that size. A QR code is square, so it takes
+     * the smaller of the two. Without a size, a code128 is as wide as its bars at 1pt per module and
+     * its bars are 40pt high, and an ean13 is the standard symbol, 0.33mm per module and bars 22.85mm
+     * high. The digits of hrt add 12pt to either.
+     */
     height?: string;
     ec?: string;
     hrt?: string;
     color?: string;
     background?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
+    width?: string;
     paginate?: string;
     debug?: string;
 }
@@ -312,6 +287,11 @@ export interface TextAttr {
     bold?: string;
     color?: string;
     align?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
     width?: string;
     /**
      * The fewest lines of the text that may stand alone at the top of the next page when it splits.
@@ -390,6 +370,11 @@ export interface TableAttr {
     gap?: string;
     padding?: string;
     background?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
     width?: string;
     height?: string;
     paginate?: string;
@@ -410,6 +395,11 @@ export interface FieldAttr {
     readonly?: string;
     maxLen?: string;
     actionUrl?: string;
+    /**
+     * Width of the element. A length fixes it. fill, in a row, takes the width its line leaves after
+     * the other children, shared equally if several on the line use fill, and never moves to the next
+     * line; in a column it takes the full width.
+     */
     width?: string;
     height?: string;
     background?: string;
@@ -457,21 +447,32 @@ export interface RegionAttr {
     debug?: string;
 }
 /**
- * Groups canvas shapes and sets what applies to all of them: which pages they appear on, opacity,
- * transform and clip. Layers cannot be nested.
+ * Draws shapes, text, images and barcodes at exact positions on the page, independent of the
+ * flowing layout: watermarks, stamps, page furniture. Coordinates start at the top left corner of
+ * the whole page, not inside the layout's margin, and y grows downward. A layer before the
+ * section's layout paints under it, and one after paints over it. It sets what applies to all of
+ * its content: which pages it appears on, opacity, transform and clip. Layers cannot be nested.
  */
 export interface LayerAttr {
     page?: string;
+    /**
+     * How opaque everything in the layer is, from 0 to 1. To fade one element, put it in a layer of
+     * its own.
+     */
     opacity?: string;
     transform?: string;
+    /**
+     * A rectangle that cuts off what the layer draws outside it: x y w h, in points from the top left
+     * corner of the page.
+     */
     clip?: string;
 }
 /**
- * Attributes of the `rect` element on the canvas.
+ * Attributes of the `rect` element in a layer.
  */
 export interface RectAttr {
-    w: string;
-    h: string;
+    width: string;
+    height: string;
     x?: string;
     y?: string;
     anchor?: string;
@@ -480,39 +481,56 @@ export interface RectAttr {
     stroke?: string;
     strokeWidth?: string;
     strokeDash?: string;
-    opacity?: string;
 }
 /**
- * Attributes of the `circle` element on the canvas.
+ * Attributes of the `circle` element in a layer.
  */
 export interface CircleAttr {
     r: string;
-    cx?: string;
-    cy?: string;
+    /**
+     * Where the circle's box goes, the square of side 2r around it: its left edge, or with anchor, an
+     * offset from that point of the page, where the box's matching point goes. The centre is r
+     * further in.
+     */
+    x?: string;
+    /**
+     * Where the circle's box goes, the square of side 2r around it: its top edge, or with anchor, an
+     * offset from that point of the page, where the box's matching point goes. The centre is r
+     * further in.
+     */
+    y?: string;
     anchor?: string;
     fill?: string;
     stroke?: string;
     strokeWidth?: string;
     strokeDash?: string;
-    opacity?: string;
 }
 /**
- * Attributes of the `ellipse` element on the canvas.
+ * Attributes of the `ellipse` element in a layer.
  */
 export interface EllipseAttr {
     rx: string;
     ry: string;
-    cx?: string;
-    cy?: string;
+    /**
+     * Where the ellipse's box goes, 2rx wide and 2ry high around it: its left edge, or with anchor,
+     * an offset from that point of the page, where the box's matching point goes. The centre is rx
+     * further in.
+     */
+    x?: string;
+    /**
+     * Where the ellipse's box goes, 2rx wide and 2ry high around it: its top edge, or with anchor, an
+     * offset from that point of the page, where the box's matching point goes. The centre is ry
+     * further in.
+     */
+    y?: string;
     anchor?: string;
     fill?: string;
     stroke?: string;
     strokeWidth?: string;
     strokeDash?: string;
-    opacity?: string;
 }
 /**
- * Attributes of the `line` element on the canvas.
+ * Attributes of the `line` element in a layer.
  */
 export interface LineAttr {
     x1: string;
@@ -525,7 +543,7 @@ export interface LineAttr {
     lineCap?: string;
 }
 /**
- * Attributes of the `path` element on the canvas.
+ * Attributes of the `path` element in a layer.
  */
 export interface PathAttr {
     d: string;
@@ -535,33 +553,104 @@ export interface PathAttr {
     strokeWidth?: string;
     strokeDash?: string;
     lineCap?: string;
-    opacity?: string;
 }
 /**
- * Text at an exact position on the page: either x and y, or an anchor with optional offsets.
+ * Text at a fixed place on the page. It is the text of the layout, with the same defaults: the
+ * document's font or Helvetica, 11pt and the text colour. It is one line unless told otherwise;
+ * give width to cut it off at a width or to wrap it with max-lines. x and y place its box: the
+ * top-left corner, or with anchor, an offset from that point of the page, where the box's matching
+ * point goes. {page} and {pages} in it count within the section, and a text that comes from data
+ * belongs in the layout, since a longer text loses its end here without a warning.
  */
-export interface CanvasTextAttr {
+export interface TextAtAttr {
     x?: string;
     y?: string;
     anchor?: string;
-    font?: string;
     fontSize?: string;
+    font?: string;
+    /**
+     * Use the bold face of the font. It applies to the 14 built-in fonts: Helvetica becomes
+     * Helvetica-Bold, Times-Roman becomes Times-Bold, Courier becomes Courier-Bold, and the oblique
+     * and italic faces their bold forms. A custom font has no bold face to pick, so name one in font.
+     */
+    bold?: string;
     color?: string;
     align?: string;
-    w?: string;
+    /**
+     * Width of the box. Without it the text is one line of the width its characters need, and align
+     * has no effect; a long text runs on past the edge of the page, which cuts it off, but stays in
+     * the PDF. With it, a line past the width is cut off at it, or ends in an ellipsis with ellipsis,
+     * and max-lines above 1 wraps the text within it.
+     */
+    width?: string;
+    /**
+     * The most lines drawn, 1 by default. Above 1 it needs a width to wrap at, and wraps the text
+     * within it; only whole lines are drawn, and the rest of the text is dropped.
+     */
+    maxLines?: string;
+    /**
+     * End the last line drawn in an ellipsis when the text does not fit its width and max-lines. Off
+     * by default: the line is cut off at the width.
+     */
+    ellipsis?: string;
+    /** The distance between lines, as a factor of the font size. Default 1.2. */
     lineHeight?: string;
-    opacity?: string;
 }
 /**
- * Attributes of the `img` element on the canvas.
+ * An image at a fixed place on the page. It needs width or height, and the other follows the
+ * image's proportions. With both, they are a maximum: the image takes the largest size that fits in
+ * them, and its box becomes that size, so an anchor places the image itself. x and y place its box:
+ * the top-left corner, or with anchor, an offset from that point of the page, where the box's
+ * matching point goes.
  */
-export interface CanvasImgAttr {
+export interface ImgAtAttr {
     name: string;
-    w: string;
-    h: string;
     x?: string;
     y?: string;
     anchor?: string;
+    width?: string;
+    height?: string;
+}
+/**
+ * A barcode at a fixed place on the page. It needs width or height, and the other follows the
+ * barcode's proportions. With both, they are a maximum: the barcode takes the largest size that
+ * fits in them, and its box becomes that size, so an anchor places the barcode itself. x and y
+ * place its box: the top-left corner, or with anchor, an offset from that point of the page, where
+ * the box's matching point goes.
+ */
+export interface BarcodeAtAttr {
+    type: string;
+    data: string;
+    /**
+     * Height of the whole barcode, with the digits of hrt inside it: they take the bottom 12pt and
+     * the bars the rest. A barcode is never stretched. With only a height, the width follows the
+     * barcode's proportions. With both width and height, they are a maximum: the barcode takes the
+     * largest size that fits in them, and its box becomes that size. A QR code is square, so it takes
+     * the smaller of the two. Without a size, a code128 is as wide as its bars at 1pt per module and
+     * its bars are 40pt high, and an ean13 is the standard symbol, 0.33mm per module and bars 22.85mm
+     * high. The digits of hrt add 12pt to either.
+     */
+    height?: string;
+    ec?: string;
+    hrt?: string;
+    color?: string;
+    background?: string;
+    x?: string;
+    y?: string;
+    anchor?: string;
+    width?: string;
+}
+/**
+ * The flowing content of a section. Elements stack down the page, and a new page starts when one
+ * runs out of room. Put headers and footers in a region, which sits outside the flow.
+ */
+export interface LayoutAttr {
+    /**
+     * The space between the page edges and the flowing content and its regions: one value for all
+     * four sides, or two to four in the order top, right, bottom, left. Defaults to 36pt. Layers
+     * ignore it and measure from the page edges.
+     */
+    margin?: string;
 }
 /**
  * Declares a font that text can be set in by name, with the font attribute. A built-in PDF font is

package/dist/browser.js

@@ -119,7 +119,7 @@ var LpdfEngine = class {
     }
   }
   /**
-   * Render a JSON kit-tree or canvas-tree document to PDF bytes.
+   * Render a JSON kit-tree document to PDF bytes.
    *
    * This is the JSON counterpart of `render_pdf`. The Node adapter uses it
    * when an `LpdfDocument` Kit tree is passed to `renderPdf()`, avoiding an

package/dist/canvas.d.ts

@@ -1,4 +1,4 @@
-import type { RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, CanvasTextAttr, CanvasImgAttr, LayerAttr } from './attrs';
+import type { RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, TextAtAttr, ImgAtAttr, BarcodeAtAttr, LayerAttr } from './attrs';
 import type { LpdfSpanNode } from './layout';
 /**
  * Builds the `transform` string of a layer. `String(CanvasTransform.rotate(45))` is
@@ -41,16 +41,20 @@ export interface LpdfCanvasPathNode {
     type: 'path';
     attrs: Record<string, string>;
 }
-export interface LpdfCanvasTextNode {
-    type: 'text';
+export interface LpdfCanvasTextAtNode {
+    type: 'text-at';
     attrs: Record<string, string>;
     nodes: (string | LpdfSpanNode)[];
 }
-export interface LpdfCanvasImgNode {
-    type: 'img';
+export interface LpdfCanvasImgAtNode {
+    type: 'img-at';
     attrs: Record<string, string>;
 }
-export type LpdfCanvasPrimitiveNode = LpdfCanvasRectNode | LpdfCanvasLineNode | LpdfCanvasEllipseNode | LpdfCanvasCircleNode | LpdfCanvasPathNode | LpdfCanvasTextNode | LpdfCanvasImgNode;
+export interface LpdfCanvasBarcodeAtNode {
+    type: 'barcode-at';
+    attrs: Record<string, string>;
+}
+export type LpdfCanvasPrimitiveNode = LpdfCanvasRectNode | LpdfCanvasLineNode | LpdfCanvasEllipseNode | LpdfCanvasCircleNode | LpdfCanvasPathNode | LpdfCanvasTextAtNode | LpdfCanvasImgAtNode | LpdfCanvasBarcodeAtNode;
 export interface LpdfCanvasLayerNode {
     type: 'layer';
     attrs: Record<string, string>;
@@ -61,8 +65,9 @@ declare function line(attrs: LineAttr): LpdfCanvasLineNode;
 declare function ellipse(attrs: EllipseAttr): LpdfCanvasEllipseNode;
 declare function circle(attrs: CircleAttr): LpdfCanvasCircleNode;
 declare function path(attrs: PathAttr): LpdfCanvasPathNode;
-declare function textAt(attrs: CanvasTextAttr, nodes?: (string | LpdfSpanNode)[]): LpdfCanvasTextNode;
-declare function imgAt(attrs: CanvasImgAttr): LpdfCanvasImgNode;
+declare function textAt(attrs: TextAtAttr, nodes?: (string | LpdfSpanNode)[]): LpdfCanvasTextAtNode;
+declare function imgAt(attrs: ImgAtAttr): LpdfCanvasImgAtNode;
+declare function barcodeAt(attrs: BarcodeAtAttr): LpdfCanvasBarcodeAtNode;
 declare function layer(attrs: LayerAttr | null, nodes?: LpdfCanvasPrimitiveNode[]): LpdfCanvasLayerNode;
 export declare const LpdfCanvas: Readonly<{
     rect: typeof rect;
@@ -72,6 +77,7 @@ export declare const LpdfCanvas: Readonly<{
     path: typeof path;
     textAt: typeof textAt;
     imgAt: typeof imgAt;
+    barcodeAt: typeof barcodeAt;
     layer: typeof layer;
 }>;
 export {};

package/dist/canvas.js

@@ -67,10 +67,13 @@ function path(attrs) {
     return { type: 'path', attrs: (0, _shared_1.buildAttrs)(attrs) };
 }
 function textAt(attrs, nodes = []) {
-    return { type: 'text', attrs: (0, _shared_1.buildAttrs)(attrs), nodes };
+    return { type: 'text-at', attrs: (0, _shared_1.buildAttrs)(attrs), nodes };
 }
 function imgAt(attrs) {
-    return { type: 'img', attrs: (0, _shared_1.buildAttrs)(attrs) };
+    return { type: 'img-at', attrs: (0, _shared_1.buildAttrs)(attrs) };
+}
+function barcodeAt(attrs) {
+    return { type: 'barcode-at', attrs: (0, _shared_1.buildAttrs)(attrs) };
 }
 function layer(attrs, nodes = []) {
     return { type: 'layer', attrs: (0, _shared_1.buildAttrs)(attrs), nodes };
@@ -83,5 +86,6 @@ exports.LpdfCanvas = Object.freeze({
     path,
     textAt,
     imgAt,
+    barcodeAt,
     layer,
 });

package/dist/index.d.ts

@@ -2,9 +2,9 @@ export { PdfEngine, LpdfRenderError } from './engine';
 export type { EncryptPermissions, EncryptOptions } from './engine';
 export type { RenderOptions, EngineOptions } from './_shared';
 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, BookmarkAttr, LayerAttr, RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, CanvasTextAttr, CanvasImgAttr, FontAttr, ImageAttr, } from './attrs';
+export type { PdfDocument, LpdfSectionNode, LpdfSectionChild, LpdfLayoutBlock, DocumentTokens, DocumentAssets, DocumentMeta, SectionAttr, DocumentAttr, } from './kit';
+export type { ColumnAttr, RowAttr, GridAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, SpanAttr, DividerAttr, ImgAttr, BarcodeAttr, RegionAttr, FieldAttr, BookmarkAttr, LayerAttr, RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, TextAtAttr, ImgAtAttr, BarcodeAtAttr, FontAttr, ImageAttr, LayoutAttr, } 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 type { LpdfCanvasLayerNode, LpdfCanvasPrimitiveNode, LpdfCanvasRectNode, LpdfCanvasLineNode, LpdfCanvasEllipseNode, LpdfCanvasCircleNode, LpdfCanvasPathNode, LpdfCanvasTextAtNode, LpdfCanvasImgAtNode, LpdfCanvasBarcodeAtNode, } from './canvas';
 export { L, NoAttr } from './L';

package/dist/index.js

@@ -13,7 +13,7 @@ Object.defineProperty(exports, "Orientation", { enumerable: true, get: function
 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 ──────────────────────────────────────────────────────────────
+// ── Layer types ───────────────────────────────────────────────────────────────
 var canvas_1 = require("./canvas");
 Object.defineProperty(exports, "CanvasTransform", { enumerable: true, get: function () { return canvas_1.CanvasTransform; } });
 // ── Facade ────────────────────────────────────────────────────────────────────

package/dist/kit.d.ts

@@ -1,31 +1,27 @@
 /**
  * LpdfKit — document skeleton assembly.
  *
- * Assembles sections (containing layout and canvas blocks) into a document
- * tree ready for `LpdfEngine.renderPdf()` or `kitToXml()`.
+ * Assembles sections (layers and a layout) into a document tree ready for
+ * `PdfEngine.render()` or `L.toXml()`. A section holds layers, then at most
+ * one layout, then layers: the layers before the layout paint under it, and
+ * the layers after it paint over it.
  *
  * @example
  * ```ts
- * import { LpdfEngine, LpdfKit, LpdfLayout, LpdfCanvas } from 'lpdf';
+ * import { L, NoAttr } from '@lpdfio/lpdf';
  *
- * const doc = LpdfKit.document({
- *   sections: [
- *     LpdfKit.section({
- *       nodes: [
- *         LpdfKit.canvas([ LpdfCanvas.layer([ LpdfCanvas.rect(0, 0, 595, 842) ]) ]),
- *         LpdfKit.layout([ LpdfLayout.text(['Hello']) ]),
- *       ],
- *       options: { size: 'a4', margin: '28pt' },
- *     }),
- *   ],
- *   options: { meta: { title: 'My Doc' } },
- * });
- * const bytes = await new LpdfEngine(key).renderPdf(doc);
+ * const doc = L.document({ meta: { title: 'My Doc' } }, [
+ *   L.section({ size: 'a4' }, [
+ *     L.layer(NoAttr, [ L.rect({ x: '0pt', y: '0pt', width: '595pt', height: '842pt', fill: '#f5f5f5' }) ]),
+ *     L.layout({ margin: '28pt' }, [ L.text(NoAttr, ['Hello']) ]),
+ *   ]),
+ * ]);
+ * const bytes = await L.engine().setLicenseKey(key).render(doc);
  * ```
  */
 import type { LpdfBookmarkNode, LpdfNode } from './layout';
 import type { LpdfCanvasLayerNode } from './canvas';
-import type { FontAttr, ImageAttr } from './attrs';
+import type { FontAttr, ImageAttr, LayoutAttr } from './attrs';
 export interface DocumentTokens {
     colors?: Record<string, string>;
     space?: Record<string, string>;
@@ -53,7 +49,6 @@ export interface DocumentMeta {
 export interface SectionAttr {
     size?: string;
     orientation?: string;
-    margin?: string;
     background?: string;
     title?: string;
     debug?: string;
@@ -63,7 +58,6 @@ export interface SectionAttr {
 export interface DocumentAttr {
     size?: string;
     orientation?: string;
-    margin?: string;
     background?: string;
     font?: string;
     assets?: DocumentAssets;
@@ -74,31 +68,30 @@ export interface DocumentAttr {
 /** A layout block — wraps an ordered list of layout nodes. */
 export interface LpdfLayoutBlock {
     type: 'layout';
+    attrs: Record<string, string>;
     nodes: LpdfNode[];
 }
-/** A canvas block — wraps an ordered list of canvas layers. */
-export interface LpdfCanvasBlock {
-    type: 'canvas';
-    nodes: LpdfCanvasLayerNode[];
-}
 export interface LpdfSectionNode {
     type: 'section';
     attrs: Record<string, string>;
-    nodes: (LpdfBookmarkNode | LpdfLayoutBlock | LpdfCanvasBlock)[];
+    nodes: LpdfSectionChild[];
 }
+/**
+ * What a section holds: a bookmark first, then layers, then at most one layout, then layers. Layers before
+ * the layout paint under it, and layers after it paint over it.
+ */
+export type LpdfSectionChild = LpdfBookmarkNode | LpdfCanvasLayerNode | LpdfLayoutBlock;
 export interface PdfDocument {
     version: 1;
     type: 'document';
     attrs: Record<string, unknown>;
     nodes: LpdfSectionNode[];
 }
-declare function layout(_attrs: null, nodes?: LpdfNode[]): LpdfLayoutBlock;
-declare function canvas(_attrs: null, layers?: LpdfCanvasLayerNode[]): LpdfCanvasBlock;
-declare function section(attrs: SectionAttr | null, nodes?: (LpdfBookmarkNode | LpdfLayoutBlock | LpdfCanvasBlock)[]): LpdfSectionNode;
+declare function layout(attrs: LayoutAttr | null, nodes?: LpdfNode[]): LpdfLayoutBlock;
+declare function section(attrs: SectionAttr | null, nodes?: LpdfSectionChild[]): LpdfSectionNode;
 declare function document(attrs: DocumentAttr | null, nodes?: LpdfSectionNode[]): PdfDocument;
 export declare const LpdfKit: Readonly<{
     layout: typeof layout;
-    canvas: typeof canvas;
     section: typeof section;
     document: typeof document;
 }>;

package/dist/kit.js

@@ -2,37 +2,30 @@
 /**
  * LpdfKit — document skeleton assembly.
  *
- * Assembles sections (containing layout and canvas blocks) into a document
- * tree ready for `LpdfEngine.renderPdf()` or `kitToXml()`.
+ * Assembles sections (layers and a layout) into a document tree ready for
+ * `PdfEngine.render()` or `L.toXml()`. A section holds layers, then at most
+ * one layout, then layers: the layers before the layout paint under it, and
+ * the layers after it paint over it.
  *
  * @example
  * ```ts
- * import { LpdfEngine, LpdfKit, LpdfLayout, LpdfCanvas } from 'lpdf';
+ * import { L, NoAttr } from '@lpdfio/lpdf';
  *
- * const doc = LpdfKit.document({
- *   sections: [
- *     LpdfKit.section({
- *       nodes: [
- *         LpdfKit.canvas([ LpdfCanvas.layer([ LpdfCanvas.rect(0, 0, 595, 842) ]) ]),
- *         LpdfKit.layout([ LpdfLayout.text(['Hello']) ]),
- *       ],
- *       options: { size: 'a4', margin: '28pt' },
- *     }),
- *   ],
- *   options: { meta: { title: 'My Doc' } },
- * });
- * const bytes = await new LpdfEngine(key).renderPdf(doc);
+ * const doc = L.document({ meta: { title: 'My Doc' } }, [
+ *   L.section({ size: 'a4' }, [
+ *     L.layer(NoAttr, [ L.rect({ x: '0pt', y: '0pt', width: '595pt', height: '842pt', fill: '#f5f5f5' }) ]),
+ *     L.layout({ margin: '28pt' }, [ L.text(NoAttr, ['Hello']) ]),
+ *   ]),
+ * ]);
+ * const bytes = await L.engine().setLicenseKey(key).render(doc);
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LpdfKit = void 0;
 const _shared_1 = require("./_shared");
 // ── Factory functions ─────────────────────────────────────────────────────────
-function layout(_attrs, nodes = []) {
-    return { type: 'layout', nodes };
-}
-function canvas(_attrs, layers = []) {
-    return { type: 'canvas', nodes: layers };
+function layout(attrs, nodes = []) {
+    return { type: 'layout', attrs: (0, _shared_1.buildAttrs)(attrs), nodes };
 }
 function section(attrs, nodes = []) {
     return {
@@ -64,7 +57,6 @@ function document(attrs, nodes = []) {
 // ── LpdfKit export ────────────────────────────────────────────────────────────
 exports.LpdfKit = Object.freeze({
     layout,
-    canvas,
     section,
     document,
 });

package/dist/layout.d.ts

@@ -1,11 +1,11 @@
-import type { StackAttr, FlankAttr, SplitAttr, ClusterAttr, GridAttr, FrameAttr, LinkAttr, TableAttr, TheadAttr, TrAttr, TdAttr, TextAttr, SpanAttr, DividerAttr, ImgAttr, BarcodeAttr, FieldAttr, RegionAttr, BookmarkAttr } from './attrs';
+import type { ColumnAttr, RowAttr, 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>;
     nodes: string[];
 }
 export interface LpdfContainerNode {
-    type: 'stack' | 'flank' | 'split' | 'cluster' | 'grid' | 'frame' | 'link';
+    type: 'column' | 'row' | 'grid' | 'frame' | 'link';
     attrs: Record<string, string>;
     nodes: LpdfNode[];
 }
@@ -61,10 +61,8 @@ export interface LpdfBookmarkNode {
     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;
-declare function cluster(attrs: ClusterAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
+declare function column(attrs: ColumnAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
+declare function row(attrs: RowAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
 declare function grid(attrs: GridAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
 declare function frame(attrs: FrameAttr | null, nodes?: LpdfNode[]): LpdfContainerNode;
 declare function link(attrs: LinkAttr, nodes?: LpdfNode[]): LpdfContainerNode;
@@ -85,10 +83,8 @@ declare function field(attrs: FieldAttr): LpdfFieldNode;
  */
 declare function bookmark(attrs: BookmarkAttr): LpdfBookmarkNode;
 export declare const LpdfLayout: Readonly<{
-    stack: typeof stack;
-    flank: typeof flank;
-    split: typeof split;
-    cluster: typeof cluster;
+    column: typeof column;
+    row: typeof row;
     grid: typeof grid;
     frame: typeof frame;
     link: typeof link;

package/dist/layout.js

@@ -7,17 +7,11 @@ function makeContainer(type, attrs, nodes) {
     return { type, attrs: (0, _shared_1.buildAttrs)(attrs), nodes };
 }
 // ── LpdfLayout factory ────────────────────────────────────────────────────────
-function stack(attrs, nodes = []) {
-    return makeContainer('stack', attrs, nodes);
+function column(attrs, nodes = []) {
+    return makeContainer('column', attrs, nodes);
 }
-function flank(attrs, nodes = []) {
-    return makeContainer('flank', attrs, nodes);
-}
-function split(attrs, nodes = []) {
-    return makeContainer('split', attrs, nodes);
-}
-function cluster(attrs, nodes = []) {
-    return makeContainer('cluster', attrs, nodes);
+function row(attrs, nodes = []) {
+    return makeContainer('row', attrs, nodes);
 }
 function grid(attrs, nodes = []) {
     return makeContainer('grid', attrs, nodes);
@@ -69,10 +63,8 @@ function bookmark(attrs) {
     return { type: 'bookmark', attrs: (0, _shared_1.buildAttrs)(attrs) };
 }
 exports.LpdfLayout = Object.freeze({
-    stack,
-    flank,
-    split,
-    cluster,
+    column,
+    row,
     grid,
     frame,
     link,

package/dist/wasm/lpdf-web.js

@@ -120,7 +120,7 @@ export class LpdfEngine {
         }
     }
     /**
-     * Render a JSON kit-tree or canvas-tree document to PDF bytes.
+     * Render a JSON kit-tree document to PDF bytes.
      *
      * This is the JSON counterpart of `render_pdf`. The Node adapter uses it
      * when an `LpdfDocument` Kit tree is passed to `renderPdf()`, avoiding an

package/dist/wasm/lpdf.js

@@ -120,7 +120,7 @@ class LpdfEngine {
         }
     }
     /**
-     * Render a JSON kit-tree or canvas-tree document to PDF bytes.
+     * Render a JSON kit-tree document to PDF bytes.
      *
      * This is the JSON counterpart of `render_pdf`. The Node adapter uses it
      * when an `LpdfDocument` Kit tree is passed to `renderPdf()`, avoiding an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpdfio/lpdf",
-  "version": "0.25.0",
+  "version": "0.27.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",