@lpdfio/lpdf 0.27.0 → 0.28.1

package/README.md

@@ -41,6 +41,12 @@ const doc = L.document({ size: 'letter' }, [
 engine.render(doc).then((pdf) => require('node:fs').writeFileSync('proposal.pdf', pdf))
 ```
 
+An ES module or a TypeScript file imports the same names, and gets the same classes:
+
+```js
+import { L, NoAttr } from '@lpdfio/lpdf'
+```
+
 ## Requirements
 
 - Node.js 20+

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
@@ -287,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
@@ -306,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;
 }
@@ -315,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,
@@ -331,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
@@ -429,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 {
     /**
@@ -451,7 +601,8 @@ export interface RegionAttr {
  * 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.
+ * 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;
@@ -466,6 +617,19 @@ export interface LayerAttr {
      * 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 in a layer.
@@ -481,6 +645,13 @@ export interface RectAttr {
     stroke?: string;
     strokeWidth?: string;
     strokeDash?: 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 in a layer.
@@ -504,6 +675,13 @@ export interface CircleAttr {
     stroke?: string;
     strokeWidth?: string;
     strokeDash?: 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 in a layer.
@@ -528,6 +706,13 @@ export interface EllipseAttr {
     stroke?: string;
     strokeWidth?: string;
     strokeDash?: 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 in a layer.
@@ -577,24 +762,31 @@ export interface TextAtAttr {
     color?: string;
     align?: 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.
+     * 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.
      */
-    width?: string;
+    lineHeight?: 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.
+     * 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 the text does not fit its width and max-lines. Off
-     * by default: the line is cut off at the width.
+     * 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;
-    /** The distance between lines, as a factor of the font size. Default 1.2. */
-    lineHeight?: 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;
 }
 /**
  * An image at a fixed place on the page. It needs width or height, and the other follows the

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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, LpdfSectionChild, LpdfLayoutBlock, DocumentTokens, DocumentAssets, DocumentMeta, SectionAttr, DocumentAttr, } from './kit';
+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';

package/dist/kit.d.ts

@@ -22,14 +22,33 @@
 import type { LpdfBookmarkNode, LpdfNode } from './layout';
 import type { LpdfCanvasLayerNode } from './canvas';
 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

package/dist/kit.js

@@ -42,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;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@lpdfio/lpdf",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "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",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     },
     "./browser": {
       "import": "./dist/browser.js",
@@ -18,7 +19,7 @@
     "build": "tsc && node build-browser.mjs && node -e \"require('node:fs').cpSync('./wasm', './dist/wasm', {recursive:true})\"",
     "build:node": "tsc",
     "build:browser": "node build-browser.mjs",
-    "test": "node --test test/render.test.mjs"
+    "test": "node --test test/render.test.mjs test/package-entry.test.mjs"
   },
   "author": "lpdf.io",
   "homepage": "https://lpdf.io",