@jasy/pdf 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/api/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./gradient.js";
+export * from "./font-url.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";
@@ -7,4 +9,5 @@ export * from "./content.js";
 export * from "./page-builder.js";
 export * from "./structure.js";
 export * from "./table.js";
+export * from "./forms.js";
 export * from "./descriptor.js";

package/dist/api/index.js

@@ -3,6 +3,8 @@
 // core classes stay untouched and remain exported for power users.
 export * from "./color.js";
 export * from "./insets.js";
+export * from "./gradient.js";
+export * from "./font-url.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";
@@ -10,4 +12,5 @@ export * from "./content.js";
 export * from "./page-builder.js";
 export * from "./structure.js";
 export * from "./table.js";
+export * from "./forms.js";
 export * from "./descriptor.js";

package/dist/api/insets.d.ts

@@ -1,16 +1,23 @@
+import { SizeInput } from "./dimension.js";
+import type { EdgeSpecs } from "../layout/insets.js";
 /**
- * Spacing input for padding / margin (locked design §3). Units are PDF points. Every form
- * normalizes to the engine's `[top, right, bottom, left]` via `toEdges`, so you can reach
+ * Spacing input for padding / margin (locked design §3). Points, or a percentage string like `"5%"`.
+ * Every form normalizes to the engine's `[top, right, bottom, left]` via `toEdges`, so you can reach
  * for whichever shape fits and never think about the engine order.
+ *
+ * **A percentage resolves against the available WIDTH - on all four sides, top and bottom included.**
+ * That is the CSS rule, and Yoga's, so react-pdf behaves the same. It reads as wrong the first time and
+ * is what makes `padding-bottom: 56.25%` a 16:9 box on the web. A percentage needs a bounded width; in
+ * an unbounded region it resolves to 0, the same no-op a percentage SIZE gives there.
  */
-export type Insets = number | {
-    x?: number;
-    y?: number;
+export type Insets = SizeInput | {
+    x?: SizeInput;
+    y?: SizeInput;
 } | {
-    top?: number;
-    right?: number;
-    bottom?: number;
-    left?: number;
-} | [number, number, number, number];
-/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
-export declare function toEdges(i: Insets): [number, number, number, number];
+    top?: SizeInput;
+    right?: SizeInput;
+    bottom?: SizeInput;
+    left?: SizeInput;
+} | [SizeInput, SizeInput, SizeInput, SizeInput];
+/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`, percentages still unresolved. */
+export declare function toEdges(i: Insets): EdgeSpecs;

package/dist/api/insets.js

@@ -1,17 +1,28 @@
-/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`. */
+import { toDimension } from "./dimension.js";
+// A fixed side stays a plain NUMBER, so the output is unchanged for every input that was legal before
+// this file learned percentages - `toEdges` is publicly exported and did not need to break.
+const spec = (v) => {
+    if (v === undefined)
+        return 0;
+    const d = toDimension(v);
+    return d.points ?? { factor: d.factor };
+};
+/** Normalizes any `Insets` to the engine's `[top, right, bottom, left]`, percentages still unresolved. */
 export function toEdges(i) {
-    if (typeof i === "number")
-        return [i, i, i, i];
+    if (typeof i === "number" || typeof i === "string") {
+        const s = spec(i);
+        return [s, s, s, s];
+    }
     if (Array.isArray(i))
-        return i;
+        return [spec(i[0]), spec(i[1]), spec(i[2]), spec(i[3])];
     // Axis form ({x, y}) and per-side form ({top,...}) are both all-optional objects (TS
     // can't discriminate them), so read through one shape: an axis key present picks the
     // axis interpretation (an empty object is all-zero either way).
     const o = i;
     if (o.x !== undefined || o.y !== undefined) {
-        const x = o.x ?? 0;
-        const y = o.y ?? 0;
+        const x = spec(o.x);
+        const y = spec(o.y);
         return [y, x, y, x];
     }
-    return [o.top ?? 0, o.right ?? 0, o.bottom ?? 0, o.left ?? 0];
+    return [spec(o.top), spec(o.right), spec(o.bottom), spec(o.left)];
 }

package/dist/api/layout.d.ts

@@ -11,10 +11,11 @@ import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { PDFElement } from "../elements/pdf-element.js";
 import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
 import { ColorInput } from "./color.js";
+import { type GradientInput } from "./gradient.js";
 import { Insets } from "./insets.js";
-import { SizeInput } from "./dimension.js";
+import { BoundsInput, SizeInput, RadiusInput } from "./dimension.js";
 /** Options shared by the `Column` and `Row` stacks (locked §4). */
-export interface StackOptions {
+export interface StackOptions extends BoundsInput {
     /** Space inserted between children, in points. */
     gap?: number;
     /** Distribution along the main axis (CSS `justify-content`): start (default) · center · end ·
@@ -35,6 +36,13 @@ export interface StackOptions {
     /** Try to keep this stack on one page (CSS `break-inside: avoid`). If it does not fit here but would
      *  fit on a fresh page, it moves there whole; if it is taller than a whole page, it splits anyway. */
     keepTogether?: boolean;
+    /** Lay the children out backwards along the axis (CSS `row-reverse` / `column-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap: wrap`). The `gap`
+     *  is used BETWEEN the lines as well as between the items. */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). Default `start`. */
+    alignContent?: MainAlign;
 }
 /** A vertical stack. `Column(children)` or `Column(opts, children)`. */
 export declare function Column(children: PDFElement[]): PDFElement;
@@ -50,7 +58,7 @@ export declare function Row(opts: StackOptions, children: PDFElement[]): PDFElem
  */
 export declare function keepTogether(children: PDFElement[]): KeepTogetherElement;
 /** A bordered / filled box that wraps its children (locked §4). */
-export interface BoxOptions {
+export interface BoxOptions extends BoundsInput {
     /** Border (stroke) color. A box has a border only when `border` or `borderWidth` is set. */
     border?: ColorInput;
     /** Per-side border colors - override/add to `border`. Any of these makes the box draw
@@ -62,8 +70,8 @@ export interface BoxOptions {
     borderLeft?: ColorInput;
     /** Border thickness in points (default 1 when a border is present). */
     borderWidth?: number;
-    /** Background fill color. */
-    bg?: ColorInput;
+    /** Background: a colour, or a gradient from `linearGradient()` / `radialGradient()`. */
+    bg?: ColorInput | GradientInput;
     /** Inner padding between the border and the children. */
     padding?: Insets;
     /** Size on each axis: a number of points (fixed) or a percentage string like `"50%"` (a fraction
@@ -72,7 +80,7 @@ export interface BoxOptions {
     width?: SizeInput;
     height?: SizeInput;
     /** Corner radius in points. */
-    radius?: number;
+    radius?: RadiusInput;
     /** Make this box a positioning frame: `Positioned` children placed inside it resolve their
      *  offsets against this box (CSS `position: relative`). */
     relative?: boolean;
@@ -173,6 +181,12 @@ export declare function PageBreak(): PageBreakElement;
 export interface ExpandedOptions {
     /** Share of the leftover space vs other flex children (default 1). */
     flex?: number;
+    /**
+     * Main-axis size reserved BEFORE the leftover is shared out (CSS `flex-basis`): points, or a
+     * percentage of what the line offers its items. The child ends up with `basis + its share of the
+     * rest`, so `flexBasis: 120` with `flex: 0` is simply a fixed 120pt slot. Default 0.
+     */
+    flexBasis?: SizeInput;
 }
 /**
  * Makes a child fill the leftover space along the stack's main axis (height in a Column,

package/dist/api/layout.js

@@ -12,14 +12,21 @@ import { AnchorElement } from "../elements/layout/anchor-element.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
 import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { toColor } from "./color.js";
+import { isGradientInput } from "./gradient.js";
 import { toEdges } from "./insets.js";
-import { toDimension } from "./dimension.js";
+import { toBounds, toDimension, toRadius, } from "./dimension.js";
 import { splitArgs } from "./args.js";
 /** Splits `StackOptions` width/height into the fixed points + fraction the stack elements expect. */
 function stackSize(opts) {
     const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
     const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
-    return { width: w?.points, height: h?.points, widthFactor: w?.factor, heightFactor: h?.factor };
+    return {
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+    };
 }
 // The public default for `cross` is `start` (locked §5) - i.e. don't stretch a child unless
 // asked. The engine default is `stretch`; the factory sets the friendlier public one.
@@ -33,6 +40,9 @@ export function Column(a, b) {
         gap: opts.gap,
         main: opts.justify, // undefined → engine default `start` (matches §5)
         cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
         breakBefore: opts.breakBefore,
         breakAfter: opts.breakAfter,
         ...stackSize(opts),
@@ -45,6 +55,9 @@ export function Row(a, b) {
         gap: opts.gap,
         main: opts.justify,
         cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
         breakBefore: opts.breakBefore,
         breakAfter: opts.breakAfter,
         ...stackSize(opts),
@@ -53,7 +66,12 @@ export function Row(a, b) {
 /** Wraps `element` in a `keepTogether` group when the `keepTogether` option is set; otherwise returns it
  *  unchanged (byte-identical). Shared by the `Box`/`Column`/`Row` prop shortcut. */
 function maybeKeepTogether(opts, element) {
-    return opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+    // alignSelf and order go on the OUTERMOST element - that is the one the surrounding stack places.
+    const wrapped = opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+    return wrapped
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
 }
 /**
  * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
@@ -92,13 +110,14 @@ export function Box(a, b) {
         y: 0,
         children: content,
         color: opts.border !== undefined ? toColor(opts.border) : undefined,
-        backgroundColor: opts.bg !== undefined ? toColor(opts.bg) : undefined,
+        backgroundColor: opts.bg === undefined ? undefined : isGradientInput(opts.bg) ? opts.bg : toColor(opts.bg),
         borderWidth: hasBorder ? (opts.borderWidth ?? 1) : 0,
         width: w?.points,
         height: h?.points,
         widthFactor: w?.factor,
         heightFactor: h?.factor,
-        radius: opts.radius,
+        ...toBounds(opts),
+        radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
         sideBorders: hasPerSide
             ? {
                 top: side(opts.borderTop),
@@ -201,5 +220,11 @@ export function Expanded(a, b) {
     const isOptsForm = b !== undefined;
     const opts = (isOptsForm ? a : {});
     const child = (isOptsForm ? b : a);
-    return new ExpandedElement({ flex: opts.flex ?? 1, child });
+    const basis = opts.flexBasis !== undefined ? toDimension(opts.flexBasis) : undefined;
+    return new ExpandedElement({
+        flex: opts.flex ?? 1,
+        basis: basis?.points,
+        basisFactor: basis?.factor,
+        child,
+    });
 }

package/dist/api/page-builder.d.ts

@@ -16,6 +16,10 @@ export type { PageInfo };
  * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
  * `pageCount` is the document total; `pageSize` is the media box in points.
  *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
  * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
@@ -30,3 +34,7 @@ export interface PageNumberOptions extends TextOptions {
 export declare function PageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
 /** The document's total page count as text. Sugar for `PageBuilder`. */
 export declare function PageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export declare function SubPageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export declare function SubPageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;

package/dist/api/page-builder.js

@@ -14,6 +14,10 @@ import { Text } from "./text.js";
  * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
  * `pageCount` is the document total; `pageSize` is the media box in points.
  *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
  * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
@@ -30,3 +34,11 @@ export function PageNumber({ offset = 0, ...style } = {}) {
 export function PageCount({ offset = 0, ...style } = {}) {
     return PageBuilder(({ pageCount }) => Text(String(pageCount + offset), style));
 }
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export function SubPageNumber({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageNumber }) => Text(String(subPageNumber + offset), style));
+}
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export function SubPageCount({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageTotalPages }) => Text(String(subPageTotalPages + offset), style));
+}

package/dist/api/structure.d.ts

@@ -7,6 +7,7 @@ import { PageSize } from "../constants/page-sizes.js";
 import { type EncryptOptions } from "../crypto/security-handler.js";
 export type { EncryptOptions, Permissions } from "../crypto/security-handler.js";
 import { StackOptions } from "./layout.js";
+import { type UrlFontSource } from "./font-url.js";
 import { Insets } from "./insets.js";
 import { TextDefaults } from "./text.js";
 /** A custom page size. Use the `mm()` helper for millimetres, or pass points directly. */
@@ -78,6 +79,10 @@ export interface JasyDocument extends PDFDocumentElement {
      *  path (read now, on Node), raw bytes, or a styled family. Re-adding a name overwrites it.
      *  A registered font that no `Text` actually uses is dropped at render and costs nothing. */
     addFont(name: string, source: FontSource): this;
+    /** The same, from a URL. Async because the fetch happens NOW, exactly as `addFont` reads a path
+     *  now - so a broken link fails where you asked for the font, not inside a later render.
+     *  `await doc.addFontFromUrl("Inter", "https://…/Inter-Regular.ttf")`, or a styled family of URLs. */
+    addFontFromUrl(name: string, source: UrlFontSource): Promise<this>;
     /** The names of the registered fonts. */
     getFonts(): string[];
     /** Whether a font is registered under `name`. */
@@ -137,6 +142,12 @@ export interface RenderOptions {
      *  embedded `GPOS` Type 2, so every font path kerns. Set `false` to opt out (byte-identical to the
      *  pre-kerning output). Verified against headless Chrome and measured == drawn to the thousandth. */
     kerning?: boolean;
+    /** Bake a form field's VALUE into its own appearance stream (`/AP`) - ON by default. Baked values
+     *  render identically in every viewer and in print, and are what flattening (later) draws from. Set
+     *  `false` to leave text and choice values to the viewer instead (`/NeedAppearances`, what
+     *  react-pdf/pdfkit always do). Checkboxes, radios, buttons and signature boxes always carry their
+     *  own appearance either way - there is no value to defer. Only meaningful with form fields present. */
+    fieldAppearances?: boolean;
     /** What to do when content is taller than a page and cannot break: `"error"` throws (default),
      *  `"warn"` logs and clips, `"ignore"` clips silently. It is always clipped either way. */
     onOverflow?: OverflowPolicy;

package/dist/api/structure.js

@@ -2,7 +2,8 @@ import { readFileBytes } from "../platform/node-fs.js";
 import { PDFDocumentElement } from "../elements/pdf-document-element.js";
 import { PageElement } from "../elements/page-element.js";
 import { DefaultTextStyleElement } from "../elements/layout/default-text-style-element.js";
-import { PageSize } from "../constants/page-sizes.js";
+import { PageSize, pageFormats } from "../constants/page-sizes.js";
+import { resolveEdges } from "../layout/insets.js";
 import { Orientation } from "../renderer/pdf-config.js";
 import { PDFDocument } from "../renderer/pdf-document-class.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
@@ -10,6 +11,7 @@ import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
 import { createSecurityHandler } from "../crypto/security-handler.js";
 import { uaXmp } from "../utils/ua-xmp.js";
 import { Column } from "./layout.js";
+import { loadFontFromUrl } from "./font-url.js";
 import { toEdges } from "./insets.js";
 import { toTextStyleOverride } from "./text.js";
 const MM_TO_PT = 72 / 25.4; // 1 mm in PDF points
@@ -38,10 +40,16 @@ export function Page(a, b) {
     const isOpts = !Array.isArray(a);
     const opts = (isOpts ? a : {});
     const children = (isOpts ? (b ?? []) : a);
-    const [top, right, bottom, left] = toEdges(opts.margin ?? DEFAULT_MARGIN);
+    const size = resolveSize(opts.size);
+    const landscape = opts.orientation === "landscape";
+    // A percentage margin resolves against the page WIDTH (see `Insets`), which is known right here -
+    // the page is the one box whose geometry does not depend on a parent.
+    const [w, h] = size.customSize ?? pageFormats[size.pageSize ?? PageSize.A4];
+    const pageWidth = landscape ? h : w;
+    const [top, right, bottom, left] = resolveEdges(toEdges(opts.margin ?? DEFAULT_MARGIN), pageWidth);
     const config = {
-        ...resolveSize(opts.size),
-        orientation: opts.orientation === "landscape" ? Orientation.landscape : Orientation.portrait,
+        ...size,
+        orientation: landscape ? Orientation.landscape : Orientation.portrait,
         margin: { top, right, bottom, left },
     };
     return new PageElement({
@@ -93,6 +101,10 @@ export function Document(a, b) {
         registry.set(name, resolveFontSource(source));
         return doc;
     };
+    doc.addFontFromUrl = async (name, source) => {
+        registry.set(name, await loadFontFromUrl(source));
+        return doc;
+    };
     doc.getFonts = () => [...registry.keys()];
     doc.hasFont = (name) => registry.has(name);
     return doc;
@@ -138,6 +150,7 @@ export async function renderPdf(doc, options) {
             om.setCompress(options?.compress !== false); // FlateDecode streams by default
             om.setOverflowPolicy(options?.onOverflow ?? "error");
             om.setKerning(options?.kerning !== false); // on by default (experimental); `kerning:false` opts out
+            om.acroform.setBakeAppearances(options?.fieldAppearances !== false); // baked unless opted out
             for (const [name, value] of Object.entries(fonts)) {
                 if (isFontBytes(value)) {
                     om.registerCustomFont(name, value);

package/dist/api/text.d.ts

@@ -1,13 +1,16 @@
-import { TextElement, TextRole, TextSegment } from "../elements/text-element.js";
+import { TextElement, TextRole, TextSegment, type VerticalTextAlign } from "../elements/text-element.js";
 import { TextOverflow } from "../text/line-breaker.js";
-import { ResolvedTextStyle } from "../text/text-style.js";
+import type { Direction } from "../text/bidi.js";
+import { ResolvedTextStyle, type TextTransform } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
 export type { TextOverflow };
 /** Text styling shared by `Text`, `Paragraph` and `span`. `bold`/`italic` are booleans
  *  (locked §7.3) and combine into one engine `FontStyle`. */
 export interface TextStyle {
     size?: number;
-    font?: string;
+    /** Font family, or a STACK: each code point is drawn by the first family in the list that has a
+     *  glyph for it, so `["Inter", "NotoSansCJK"]` sets mixed-script text without splitting it by hand. */
+    font?: string | string[];
     bold?: boolean;
     italic?: boolean;
     color?: ColorInput;
@@ -22,6 +25,19 @@ export interface TextStyle {
     skipInk?: boolean;
     /** Extra space after every glyph, in points (CSS `letter-spacing`). Negative tightens. Default 0. */
     letterSpacing?: number;
+    /** Base writing direction (CSS `direction`): `"rtl"` starts the line on the right, for Hebrew or
+     *  Arabic. Mixed text is reordered per Unicode UAX #9 either way, so Hebrew inside an `ltr`
+     *  paragraph already comes out right - this decides where the LINE starts. */
+    direction?: Direction;
+    /** CSS `text-transform`: recase the text. `capitalize` upper-cases the first letter of each word. */
+    textTransform?: TextTransform;
+    /** CSS `word-spacing`, in points: extra advance at every space. Negative tightens. */
+    wordSpacing?: number;
+    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
+    textIndent?: number;
+    /** CSS `vertical-align` for a SPAN: raises a footnote marker or lowers an index. It shifts the
+     *  baseline only - pass a smaller `size` too if you want the browser's `<sup>` look. */
+    verticalAlign?: VerticalTextAlign;
     /** External URL - makes this run an inline hyperlink (a /Link annotation over its glyphs). On a
      *  `span` it links just that run; on a whole `Text` (plain string) it links the whole text. */
     href?: string;
@@ -31,10 +47,18 @@ export interface TextStyle {
 }
 export interface TextOptions extends TextStyle {
     /** Text-internal alignment (left/center/right) - independent of a parent's `cross` (§5). */
-    align?: "left" | "center" | "right";
+    align?: "left" | "center" | "right" | "justify";
     /** Cap the number of wrapped lines (default: unlimited - the text grows down as far as it needs,
      *  paginating onto the next page). Needs a bounded width (a Column/Expanded/`Box({ width })`). */
     maxLines?: number;
+    /**
+     * Minimum lines that must stay behind at a page break (CSS `orphans`), and minimum that must carry
+     * over (CSS `widows`). Both default to 2, the CSS initial value: a single line stranded at the foot of
+     * a page - or alone at the top of the next - reads as a mistake. Set both to 1 to switch the protection
+     * off and let a paragraph break wherever the page ends.
+     */
+    orphans?: number;
+    widows?: number;
     /** What happens past `maxLines`: `"clip"` (default) cuts hard, `"ellipsis"` ends with "…". */
     overflow?: TextOverflow;
     /** Line-height multiplier: each line is `size * lineHeight` tall. Unset means the font's own
@@ -62,16 +86,28 @@ export declare function Paragraph(content: string | TextSegment[], opts?: TextOp
  *  Unset fields stay out so they keep inheriting. */
 export interface TextDefaults {
     size?: number;
-    font?: string;
+    /** Font family, or a STACK: each code point is drawn by the first family in the list that has a
+     *  glyph for it, so `["Inter", "NotoSansCJK"]` sets mixed-script text without splitting it by hand. */
+    font?: string | string[];
     bold?: boolean;
     italic?: boolean;
     color?: ColorInput;
-    align?: "left" | "center" | "right";
+    align?: "left" | "center" | "right" | "justify";
     lineHeight?: number;
     underline?: boolean;
     strikethrough?: boolean;
     skipInk?: boolean;
     letterSpacing?: number;
+    /** Base writing direction (CSS `direction`): `"rtl"` starts the line on the right, for Hebrew or
+     *  Arabic. Mixed text is reordered per Unicode UAX #9 either way, so Hebrew inside an `ltr`
+     *  paragraph already comes out right - this decides where the LINE starts. */
+    direction?: Direction;
+    /** CSS `text-transform`: recase the text. `capitalize` upper-cases the first letter of each word. */
+    textTransform?: TextTransform;
+    /** CSS `word-spacing`, in points: extra advance at every space. Negative tightens. */
+    wordSpacing?: number;
+    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
+    textIndent?: number;
 }
 /** Maps the `Text`-style option names onto a partial engine `ResolvedTextStyle` (only the set
  *  fields), for seeding the inheritance cascade. */

package/dist/api/text.js

@@ -1,4 +1,4 @@
-import { TextElement } from "../elements/text-element.js";
+import { TextElement, } from "../elements/text-element.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import { toColor } from "./color.js";
@@ -12,10 +12,15 @@ function toFontStyle(bold, italic) {
         return FontStyle.Italic;
     return FontStyle.Normal;
 }
+/** The family a run starts in - the first of a stack, or the single name given. */
+const primaryFont = (font) => Array.isArray(font) ? font[0] : font;
+/** The rest of the stack, tried in order for a code point the first family cannot draw. */
+const fallbackFonts = (font) => Array.isArray(font) ? font.slice(1) : undefined;
 const ALIGN = {
     left: HorizontalAlignment.left,
     center: HorizontalAlignment.center,
     right: HorizontalAlignment.right,
+    justify: HorizontalAlignment.justify,
 };
 /**
  * Validates a font `size` (a number of points). Rejects anything that would silently become a NaN
@@ -45,7 +50,8 @@ export function span(text, style = {}) {
     return {
         content: text,
         fontSize: toFontSize(style.size),
-        fontFamily: style.font,
+        fontFamily: primaryFont(style.font),
+        fontFallback: fallbackFonts(style.font),
         fontStyle: style.bold !== undefined || style.italic !== undefined
             ? toFontStyle(style.bold, style.italic)
             : undefined,
@@ -53,6 +59,7 @@ export function span(text, style = {}) {
         underline: style.underline,
         strikethrough: style.strikethrough,
         letterSpacing: style.letterSpacing,
+        verticalAlign: style.verticalAlign,
         href: style.href,
         dest: style.to,
     };
@@ -73,19 +80,26 @@ export function Text(content, opts = {}) {
     return new TextElement({
         content: body,
         fontSize: toFontSize(opts.size),
-        fontFamily: opts.font,
+        fontFamily: primaryFont(opts.font),
+        fontFallback: fallbackFonts(opts.font),
         fontStyle: opts.bold !== undefined || opts.italic !== undefined
             ? toFontStyle(opts.bold, opts.italic)
             : undefined,
         color: opts.color !== undefined ? toColor(opts.color) : undefined,
         textAlignment: opts.align ? ALIGN[opts.align] : undefined,
         maxLines: opts.maxLines,
+        orphans: opts.orphans,
+        widows: opts.widows,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
         underline: opts.underline,
         strikethrough: opts.strikethrough,
         skipInk: opts.skipInk,
         letterSpacing: opts.letterSpacing,
+        direction: opts.direction,
+        textTransform: opts.textTransform,
+        wordSpacing: opts.wordSpacing,
+        textIndent: opts.textIndent,
         role: opts.role,
     });
 }
@@ -99,8 +113,10 @@ export function toTextStyleOverride(opts) {
     const style = {};
     if (opts.size !== undefined)
         style.fontSize = toFontSize(opts.size);
-    if (opts.font !== undefined)
-        style.fontFamily = opts.font;
+    if (opts.font !== undefined) {
+        style.fontFamily = primaryFont(opts.font);
+        style.fontFallback = fallbackFonts(opts.font);
+    }
     if (opts.bold !== undefined || opts.italic !== undefined) {
         style.fontStyle = toFontStyle(opts.bold, opts.italic);
     }
@@ -118,5 +134,13 @@ export function toTextStyleOverride(opts) {
         style.skipInk = opts.skipInk;
     if (opts.letterSpacing !== undefined)
         style.letterSpacing = opts.letterSpacing;
+    if (opts.direction !== undefined)
+        style.direction = opts.direction;
+    if (opts.textTransform !== undefined)
+        style.textTransform = opts.textTransform;
+    if (opts.wordSpacing !== undefined)
+        style.wordSpacing = opts.wordSpacing;
+    if (opts.textIndent !== undefined)
+        style.textIndent = opts.textIndent;
     return style;
 }

package/dist/crypto/legacy-handler.d.ts

@@ -0,0 +1,43 @@
+import type { SecurityHandler } from "./security-handler.js";
+/** RC4. Not available in WebCrypto - for good reasons - so it is written out here, for reading only. */
+declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
+/** What the `/Encrypt` dictionary tells us, already parsed by the reader. */
+export interface LegacyEncryptInfo {
+    revision: number;
+    /** `/Length` in BITS (default 40). */
+    keyBits: number;
+    o: Uint8Array;
+    u: Uint8Array;
+    /** `/P`, the permission flags, as the signed 32-bit value the algorithm feeds in. */
+    permissions: number;
+    /** The first string of the document `/ID`. */
+    id: Uint8Array;
+    encryptMetadata: boolean;
+    /** True when the crypt filter is AESV2 rather than RC4. */
+    aes: boolean;
+}
+export declare class StandardLegacy implements SecurityHandler {
+    private readonly fileKey;
+    private readonly aes;
+    private constructor();
+    readonly canEncrypt = false;
+    encryptDict(): string;
+    encrypt(): Promise<Uint8Array>;
+    decrypt(data: Uint8Array, ref?: {
+        num: number;
+        gen: number;
+    }): Promise<Uint8Array>;
+    /**
+     * Algorithm 1: every object is enciphered with its own key, derived from the file key plus the
+     * object's number and generation. Miss this and every single object decrypts to noise.
+     */
+    private objectKey;
+    /**
+     * Open a legacy-encrypted document: derive the file key from the password (algorithm 2), then CHECK it
+     * against `/U` (algorithm 6) so a wrong password is rejected rather than silently producing noise.
+     */
+    static open(password: string, info: LegacyEncryptInfo): SecurityHandler;
+    /** Algorithm 6: rebuild what `/U` must look like for this key and compare. */
+    private static passwordMatches;
+}
+export { rc4 };