@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/api/text.d.ts

@@ -1,17 +1,73 @@
-import { TextElement, TextSegment } from "../elements/text-element";
-import { ColorInput } from "./color";
+import { TextElement, TextRole, TextSegment, type VerticalTextAlign } from "../elements/text-element.js";
+import { TextOverflow } from "../text/line-breaker.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;
+    /** Draw a line under the text. Its position and thickness come from the font, not from a guess.
+     *  A `Link` is NOT underlined automatically - say so if you want it. */
+    underline?: boolean;
+    /** Draw a line through the text, at half its x-height (where a browser puts it). */
+    strikethrough?: boolean;
+    /** Let the underline step around descenders, like a browser (`text-decoration-skip-ink`). Needs an
+     *  EMBEDDED font - the standard-14 outlines live in the viewer, so we cannot see where their ink
+     *  is. Asking for it with a standard font is an error, not a silent no-op. */
+    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;
+    /** Internal jump target - the `name` of an `Anchor` elsewhere in the document (like `href`, but a
+     *  same-document /GoTo instead of a URL). Use for a clickable table of contents / cross-reference. */
+    to?: string;
 }
 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
+     *  natural line height (`ascent + descent + lineGap`), like CSS `line-height: normal` - which is
+     *  what you want for body copy. `1` gives exactly one em, which most faces overflow slightly. */
+    lineHeight?: number;
+    /** Accessibility role for the tagged structure tree (only when rendered with `accessible`): a heading
+     *  level `"h1"`..`"h6"` or `"p"` (default). Purely semantic - it does not change the visual style. */
+    role?: TextRole;
 }
 /**
  * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each
@@ -26,3 +82,33 @@ export declare function span(text: string, style?: TextStyle): TextSegment;
 export declare function Text(content: string | TextSegment[], opts?: TextOptions): TextElement;
 /** `Text` with body-paragraph defaults (same options; a separate name reads as intent). */
 export declare function Paragraph(content: string | TextSegment[], opts?: TextOptions): TextElement;
+/** The inheritable text defaults a `Document` can set, using the same option names as `Text`.
+ *  Unset fields stay out so they keep inheriting. */
+export interface TextDefaults {
+    size?: number;
+    /** 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" | "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. */
+export declare function toTextStyleOverride(opts: TextDefaults): Partial<ResolvedTextStyle>;

package/dist/api/text.js

@@ -1,42 +1,67 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.span = span;
-exports.Text = Text;
-exports.Paragraph = Paragraph;
-const text_element_1 = require("../elements/text-element");
-const pdf_element_1 = require("../elements/pdf-element");
-const pdf_object_manager_1 = require("../utils/pdf-object-manager");
-const color_1 = require("./color");
-/** Body-text default size when none is given (matches the engine default font). */
-const DEFAULT_SIZE = 12;
+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";
 /** bold + italic → the single engine `FontStyle`. */
 function toFontStyle(bold, italic) {
     if (bold && italic)
-        return pdf_object_manager_1.FontStyle.BoldItalic;
+        return FontStyle.BoldItalic;
     if (bold)
-        return pdf_object_manager_1.FontStyle.Bold;
+        return FontStyle.Bold;
     if (italic)
-        return pdf_object_manager_1.FontStyle.Italic;
-    return pdf_object_manager_1.FontStyle.Normal;
+        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: pdf_element_1.HorizontalAlignment.left,
-    center: pdf_element_1.HorizontalAlignment.center,
-    right: pdf_element_1.HorizontalAlignment.right,
+    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
+ * height deep in layout - notably `Document({ size: "A4" })`, where `"A4"` is the PAGE size and belongs
+ * on `Page`, not a font size. `undefined` passes through (unset = inherit the cascade).
+ */
+function toFontSize(size) {
+    if (size === undefined)
+        return undefined;
+    if (typeof size !== "number" || !Number.isFinite(size) || size <= 0) {
+        // Quote a string so "A4" reads as a string; show a bare number/NaN as-is (JSON turns NaN into null).
+        const shown = typeof size === "string" ? JSON.stringify(size) : String(size);
+        // The Page-vs-font-size mix-up only happens with a string like "A4"; for a plain bad number
+        // (NaN, negative, 0) the hint would just be noise, so keep the message generic there.
+        const hint = typeof size === "string"
+            ? ` Note: the page size goes on Page({ size: "A4" }), not on Document or Text.`
+            : "";
+        throw new Error(`Invalid font size ${shown} (expected a positive number of points).${hint}`);
+    }
+    return size;
+}
 /**
  * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each
  * field overrides the enclosing `Text`'s defaults for just this run; omitted fields inherit.
  */
-function span(text, style = {}) {
+export function span(text, style = {}) {
     return {
         content: text,
-        fontSize: style.size,
-        fontFamily: style.font,
+        fontSize: toFontSize(style.size),
+        fontFamily: primaryFont(style.font),
+        fontFallback: fallbackFonts(style.font),
         fontStyle: style.bold !== undefined || style.italic !== undefined
             ? toFontStyle(style.bold, style.italic)
             : undefined,
-        fontColor: style.color !== undefined ? (0, color_1.toColor)(style.color) : undefined,
+        fontColor: style.color !== undefined ? toColor(style.color) : undefined,
+        underline: style.underline,
+        strikethrough: style.strikethrough,
+        letterSpacing: style.letterSpacing,
+        verticalAlign: style.verticalAlign,
+        href: style.href,
+        dest: style.to,
     };
 }
 /**
@@ -44,18 +69,78 @@ function span(text, style = {}) {
  * options set the defaults (size/font/style/color) that any spans inherit, plus the
  * text-internal `align`.
  */
-function Text(content, opts = {}) {
-    var _a;
-    return new text_element_1.TextElement({
-        content,
-        fontSize: (_a = opts.size) !== null && _a !== void 0 ? _a : DEFAULT_SIZE,
-        fontFamily: opts.font,
-        fontStyle: toFontStyle(opts.bold, opts.italic),
-        color: opts.color !== undefined ? (0, color_1.toColor)(opts.color) : undefined,
+export function Text(content, opts = {}) {
+    // A plain string given an `href`/`to` becomes a single link span, so `Text("jasy.dev", { href })` (or
+    // `{ to }`) is a whole-text link (inline links use `span(...)`). This routes through the styled-segment
+    // path, which lays a single default-font segment out identically - only the /Link annotation is added.
+    const isLink = opts.href !== undefined || opts.to !== undefined;
+    const body = typeof content === "string" && isLink ? [span(content, opts)] : content;
+    // Unset properties are left undefined so they inherit the cascaded TextStyle (Document default /
+    // built-in). Only bold/italic that the caller actually set become an explicit FontStyle.
+    return new TextElement({
+        content: body,
+        fontSize: toFontSize(opts.size),
+        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,
     });
 }
 /** `Text` with body-paragraph defaults (same options; a separate name reads as intent). */
-function Paragraph(content, opts = {}) {
+export function Paragraph(content, opts = {}) {
     return Text(content, opts);
 }
+/** Maps the `Text`-style option names onto a partial engine `ResolvedTextStyle` (only the set
+ *  fields), for seeding the inheritance cascade. */
+export function toTextStyleOverride(opts) {
+    const style = {};
+    if (opts.size !== undefined)
+        style.fontSize = toFontSize(opts.size);
+    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);
+    }
+    if (opts.color !== undefined)
+        style.color = toColor(opts.color);
+    if (opts.align !== undefined)
+        style.textAlignment = ALIGN[opts.align];
+    if (opts.lineHeight !== undefined)
+        style.lineHeight = opts.lineHeight;
+    if (opts.underline !== undefined)
+        style.underline = opts.underline;
+    if (opts.strikethrough !== undefined)
+        style.strikethrough = opts.strikethrough;
+    if (opts.skipInk !== undefined)
+        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/assets/font-data.d.ts

@@ -0,0 +1,2 @@
+export declare const STANDARD_AFM: Record<string, string>;
+export declare const AGL: string;