@lpdfio/lpdf 0.26.0 → 0.28.0

package/README.md

@@ -19,9 +19,9 @@ 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.layout({ margin: '48pt' }, [
             L.column({ gap: '24pt' }, [
                 L.row({ justify: 'between' }, [
                     L.text({ fontSize: '8pt', color: '#888888' }, ['ACME CORP']),

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,9 +30,8 @@ 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;
     column: (attrs: import("./attrs").ColumnAttr | null, nodes?: import("./layout").LpdfNode[]) => import("./layout").LpdfContainerNode;
@@ -58,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,7 +39,6 @@ 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 ────────────────────────────────────────────────────────────────
@@ -60,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,
@@ -69,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

@@ -5,6 +5,12 @@
 export interface ColumnAttr {
     font?: string;
     fontSize?: string;
+    /**
+     * The color of the text inside the box. A text that sets no color of its own takes the nearest
+     * box's, and the text token when no box sets one. A divider or a barcode in the box keeps its own
+     * color.
+     */
+    color?: string;
     gap?: string;
     /**
      * Space between the edge of the box and its content, written like CSS: one value for all sides,
@@ -21,6 +27,21 @@ export interface ColumnAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * How opaque the box and everything in it is, from 0 to 1. The box is faded as one, so children
+     * that overlap do not show through each other, and a box inside a faded box is faded further: 0.5
+     * inside 0.5 is drawn at 0.25. A form field in the box is not faded. Default 1.
+     */
+    opacity?: string;
+    /**
+     * A hard-edged shadow: a copy of the box, moved right and down by the first two lengths (negative
+     * is left and up) and filled with the color, drawn under the box with the same radius. An opacity
+     * from 0 to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur.
+     * The shadow takes no room in the layout, so it can run into the margin or a neighbor, and the
+     * siblings after the box are drawn over it. A box with no background shows the shadow only
+     * outside it. The box's own opacity fades the box and its shadow together.
+     */
+    shadow?: 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
@@ -49,6 +70,12 @@ export interface ColumnAttr {
 export interface RowAttr {
     font?: string;
     fontSize?: string;
+    /**
+     * The color of the text inside the box. A text that sets no color of its own takes the nearest
+     * box's, and the text token when no box sets one. A divider or a barcode in the box keeps its own
+     * color.
+     */
+    color?: string;
     gap?: string;
     /**
      * Space between the edge of the box and its content, written like CSS: one value for all sides,
@@ -65,6 +92,21 @@ export interface RowAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * How opaque the box and everything in it is, from 0 to 1. The box is faded as one, so children
+     * that overlap do not show through each other, and a box inside a faded box is faded further: 0.5
+     * inside 0.5 is drawn at 0.25. A form field in the box is not faded. Default 1.
+     */
+    opacity?: string;
+    /**
+     * A hard-edged shadow: a copy of the box, moved right and down by the first two lengths (negative
+     * is left and up) and filled with the color, drawn under the box with the same radius. An opacity
+     * from 0 to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur.
+     * The shadow takes no room in the layout, so it can run into the margin or a neighbor, and the
+     * siblings after the box are drawn over it. A box with no background shows the shadow only
+     * outside it. The box's own opacity fades the box and its shadow together.
+     */
+    shadow?: 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
@@ -91,6 +133,12 @@ export interface RowAttr {
 export interface GridAttr {
     font?: string;
     fontSize?: string;
+    /**
+     * The color of the text inside the box. A text that sets no color of its own takes the nearest
+     * box's, and the text token when no box sets one. A divider or a barcode in the box keeps its own
+     * color.
+     */
+    color?: string;
     gap?: string;
     /**
      * Space between the edge of the box and its content, written like CSS: one value for all sides,
@@ -107,6 +155,21 @@ export interface GridAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * How opaque the box and everything in it is, from 0 to 1. The box is faded as one, so children
+     * that overlap do not show through each other, and a box inside a faded box is faded further: 0.5
+     * inside 0.5 is drawn at 0.25. A form field in the box is not faded. Default 1.
+     */
+    opacity?: string;
+    /**
+     * A hard-edged shadow: a copy of the box, moved right and down by the first two lengths (negative
+     * is left and up) and filled with the color, drawn under the box with the same radius. An opacity
+     * from 0 to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur.
+     * The shadow takes no room in the layout, so it can run into the margin or a neighbor, and the
+     * siblings after the box are drawn over it. A box with no background shows the shadow only
+     * outside it. The box's own opacity fades the box and its shadow together.
+     */
+    shadow?: 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
@@ -133,6 +196,12 @@ export interface GridAttr {
 export interface FrameAttr {
     font?: string;
     fontSize?: string;
+    /**
+     * The color of the text inside the box. A text that sets no color of its own takes the nearest
+     * box's, and the text token when no box sets one. A divider or a barcode in the box keeps its own
+     * color.
+     */
+    color?: 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,
@@ -148,6 +217,21 @@ export interface FrameAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * How opaque the box and everything in it is, from 0 to 1. The box is faded as one, so children
+     * that overlap do not show through each other, and a box inside a faded box is faded further: 0.5
+     * inside 0.5 is drawn at 0.25. A form field in the box is not faded. Default 1.
+     */
+    opacity?: string;
+    /**
+     * A hard-edged shadow: a copy of the box, moved right and down by the first two lengths (negative
+     * is left and up) and filled with the color, drawn under the box with the same radius. An opacity
+     * from 0 to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur.
+     * The shadow takes no room in the layout, so it can run into the margin or a neighbor, and the
+     * siblings after the box are drawn over it. A box with no background shows the shadow only
+     * outside it. The box's own opacity fades the box and its shadow together.
+     */
+    shadow?: 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
@@ -215,7 +299,11 @@ 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;
@@ -237,23 +325,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 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.
+     * 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.
      */
-    width?: string;
     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;
 }
@@ -272,6 +371,25 @@ export interface TextAttr {
     bold?: string;
     color?: string;
     align?: string;
+    /**
+     * The distance between lines, as a factor of the font size: a number above 0, such as 1.5, or a
+     * name from the line-height row of the tokens. Default 1.2, which is the token m.
+     */
+    lineHeight?: string;
+    /**
+     * The most lines drawn. Only whole lines are drawn, and the rest of the text is dropped. A text
+     * in the layout has no cap by default and wraps at the width it has; the lines it drops take no
+     * room, and a text that splits across pages keeps the cap across them. A text-at is one line by
+     * default, and above 1 needs a width to wrap within.
+     */
+    maxLines?: string;
+    /**
+     * End the last line drawn in an ellipsis when max-lines drops text, shortened to fit the width.
+     * Off by default: the text stops at the end of a line. A text-at also ends a line in one when it
+     * is cut off at its width. A text in the layout without max-lines is never cut, so there it has
+     * no effect.
+     */
+    ellipsis?: 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
@@ -291,6 +409,31 @@ export interface TextAttr {
      * where the lines fit.
      */
     orphans?: string;
+    /**
+     * Records the words of this text under a name as the pages are filled, so a text with capture-ref
+     * in a header or a footer can show them. Put it on a heading in the flow. The page that holds the
+     * text counts it, the words above it on that page included, and a text that splits across pages
+     * is recorded on the page where it starts. A text cannot have both capture and capture-ref.
+     */
+    capture?: string;
+    /**
+     * Shows what was captured under this name, as of the page the text is drawn on, in place of words
+     * of its own. Put it in a region. It takes the lines it may use, one unless max-lines says more,
+     * whatever it shows, so a header or a footer does not grow with its value; a longer value is cut,
+     * and ends in dots with ellipsis. On a page where nothing was captured it shows the latest value
+     * of an earlier page of the section, and capture-fallback before any.
+     */
+    captureRef?: string;
+    /**
+     * Which of the texts captured under the name on this page the text shows: the first or the last.
+     * Default last. Only for a text with capture-ref.
+     */
+    captureMode?: string;
+    /**
+     * What the text shows until something has been captured in the section. Default: nothing. Only
+     * for a text with capture-ref.
+     */
+    captureFallback?: string;
     paginate?: string;
     debug?: string;
 }
@@ -300,6 +443,12 @@ export interface TextAttr {
 export interface TdAttr {
     font?: string;
     fontSize?: string;
+    /**
+     * The color of the text inside the box. A text that sets no color of its own takes the nearest
+     * box's, and the text token when no box sets one. A divider or a barcode in the box keeps its own
+     * color.
+     */
+    color?: string;
     gap?: string;
     /**
      * Space between the edge of the box and its content, written like CSS: one value for all sides,
@@ -316,6 +465,21 @@ export interface TdAttr {
     background?: string;
     border?: string;
     radius?: string;
+    /**
+     * How opaque the box and everything in it is, from 0 to 1. The box is faded as one, so children
+     * that overlap do not show through each other, and a box inside a faded box is faded further: 0.5
+     * inside 0.5 is drawn at 0.25. A form field in the box is not faded. Default 1.
+     */
+    opacity?: string;
+    /**
+     * A hard-edged shadow: a copy of the box, moved right and down by the first two lengths (negative
+     * is left and up) and filled with the color, drawn under the box with the same radius. An opacity
+     * from 0 to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur.
+     * The shadow takes no room in the layout, so it can run into the margin or a neighbor, and the
+     * siblings after the box are drawn over it. A box with no background shows the shadow only
+     * outside it. The box's own opacity fades the box and its shadow together.
+     */
+    shadow?: 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
@@ -414,8 +578,9 @@ export interface BookmarkAttr {
 }
 /**
  * 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,
- * and one per pin on a page.
+ * footers. It reserves that space on every page it appears on. Only allowed directly inside layout.
+ * Where it is written among the flow does not matter: pin chooses the edge, and regions on one edge
+ * stack in the order written.
  */
 export interface RegionAttr {
     /**
@@ -432,21 +597,46 @@ 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, and the font, size and color
+ * of its text. 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;
+    /**
+     * The font of the text-at in the layer that sets none of its own. Defaults to the font of the
+     * document.
+     */
+    font?: string;
+    /**
+     * The size of the text-at in the layer that sets none of its own. Defaults to 11pt.
+     */
+    fontSize?: string;
+    /**
+     * The color of the text-at in the layer that sets none of its own. Defaults to the text token.
+     */
+    color?: 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;
@@ -455,39 +645,77 @@ export interface RectAttr {
     stroke?: string;
     strokeWidth?: string;
     strokeDash?: string;
-    opacity?: string;
+    /**
+     * A hard-edged shadow: a copy of the shape, moved right and down by the first two lengths
+     * (negative is left and up) and filled with the color, drawn under the shape. An opacity from 0
+     * to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur. A shape
+     * with no fill shows the shadow only outside it.
+     */
+    shadow?: 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;
+    /**
+     * A hard-edged shadow: a copy of the shape, moved right and down by the first two lengths
+     * (negative is left and up) and filled with the color, drawn under the shape. An opacity from 0
+     * to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur. A shape
+     * with no fill shows the shadow only outside it.
+     */
+    shadow?: 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;
+    /**
+     * A hard-edged shadow: a copy of the shape, moved right and down by the first two lengths
+     * (negative is left and up) and filled with the color, drawn under the shape. An opacity from 0
+     * to 1 after the color fades the shadow alone: "2pt 3pt #000000 0.2". There is no blur. A shape
+     * with no fill shows the shadow only outside it.
+     */
+    shadow?: string;
 }
 /**
- * Attributes of the `line` element on the canvas.
+ * Attributes of the `line` element in a layer.
  */
 export interface LineAttr {
     x1: string;
@@ -500,7 +728,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;
@@ -510,33 +738,111 @@ 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;
+    /**
+     * The distance between lines, as a factor of the font size: a number above 0, such as 1.5, or a
+     * name from the line-height row of the tokens. Default 1.2, which is the token m.
+     */
     lineHeight?: string;
-    opacity?: string;
+    /**
+     * The most lines drawn. Only whole lines are drawn, and the rest of the text is dropped. A text
+     * in the layout has no cap by default and wraps at the width it has; the lines it drops take no
+     * room, and a text that splits across pages keeps the cap across them. A text-at is one line by
+     * default, and above 1 needs a width to wrap within.
+     */
+    maxLines?: string;
+    /**
+     * End the last line drawn in an ellipsis when max-lines drops text, shortened to fit the width.
+     * Off by default: the text stops at the end of a line. A text-at also ends a line in one when it
+     * is cut off at its width. A text in the layout without max-lines is never cut, so there it has
+     * no effect.
+     */
+    ellipsis?: 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;
 }
 /**
- * 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 { ColumnAttr, RowAttr, 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, GradientToken, GradientStop, 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,39 +1,54 @@
 /**
  * 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';
+/** One color of a gradient: `color` is hex or a color token, at an `offset` from `'0%'` to `'100%'`. */
+export interface GradientStop {
+    offset: string;
+    color: string;
+}
+/**
+ * A gradient of the tokens, which a background or a fill uses as `gradient:name`. Give `from` and `to` for two
+ * colors, or `stops` for more. `angle` is the direction of a linear gradient in degrees: 0 runs top to bottom
+ * and 90 left to right. A radial gradient runs from the center of the box out to its farthest corner.
+ */
+export interface GradientToken {
+    type: 'linear' | 'radial';
+    from?: string;
+    to?: string;
+    angle?: number | string;
+    stops?: GradientStop[];
+}
 export interface DocumentTokens {
     colors?: Record<string, string>;
+    gradients?: Record<string, GradientToken>;
     space?: Record<string, string>;
     grid?: Record<string, string>;
     border?: Record<string, string>;
     radius?: Record<string, string>;
     width?: Record<string, string>;
     textSize?: Record<string, string>;
+    lineHeight?: Record<string, string>;
 }
 /**
  * The fonts and images the document declares, as the `assets` element of the XML does. A font or image
@@ -53,7 +68,6 @@ export interface DocumentMeta {
 export interface SectionAttr {
     size?: string;
     orientation?: string;
-    margin?: string;
     background?: string;
     title?: string;
     debug?: string;
@@ -63,7 +77,6 @@ export interface SectionAttr {
 export interface DocumentAttr {
     size?: string;
     orientation?: string;
-    margin?: string;
     background?: string;
     font?: string;
     assets?: DocumentAssets;
@@ -74,31 +87,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 {
@@ -49,8 +42,12 @@ function document(attrs, nodes = []) {
     if (assets !== undefined)
         attrsObj['assets'] = assets;
     if (tokens !== undefined) {
-        const { textSize, ...rest } = tokens;
-        attrsObj['tokens'] = textSize !== undefined ? { 'text-size': textSize, ...rest } : rest;
+        const { textSize, lineHeight, ...rest } = tokens;
+        attrsObj['tokens'] = {
+            ...rest,
+            ...(textSize !== undefined ? { 'text-size': textSize } : {}),
+            ...(lineHeight !== undefined ? { 'line-height': lineHeight } : {}),
+        };
     }
     if (meta !== undefined)
         attrsObj['meta'] = meta;
@@ -64,7 +61,6 @@ function document(attrs, nodes = []) {
 // ── LpdfKit export ────────────────────────────────────────────────────────────
 exports.LpdfKit = Object.freeze({
     layout,
-    canvas,
     section,
     document,
 });

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.26.0",
+  "version": "0.28.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",