pdfmkr/dist/api/text.d.ts

Generate PDF documents from JavaScript objects

import type { Color } from './colors.ts';
/**
 * Deprecated. Use `TextSpan` instead.
 */
export type Text = string | TextSpan | TextSpan[];
/**
 * A span of text with optional text properties. Nested spans can be
 * used to apply different text properties to different parts of a
 * text.
 */
export type TextSpan = {
    text: string | TextSpan | (string | TextSpan)[];
} & TextProps;
/**
 * Creates a span of text with the given text and properties.
 *
 * @param text The text to display in this span.
 * @param props Optional properties for the span.
 */
export declare function span(text: string | TextSpan | (string | TextSpan)[], props?: TextProps): TextSpan;
/**
 * Creates a span of text with the given text and a bold font weight.
 *
 * @param text The text to display in bold.
 */
export declare function bold(text: string | TextSpan | (string | TextSpan)[]): TextSpan;
/**
 * Creates a span of text with the given text and an italic font style.
 *
 * @param text The text to display in italics.
 */
export declare function italic(text: string | TextSpan | (string | TextSpan)[]): TextSpan;
/**
 * The font weight is an integer between 0 and 1000. The keywords
 * `normal` (400) and `bold` (700) are also supported.
 */
export type FontWeight = number | 'normal' | 'bold';
/**
 * The font style selects a normal, italic, or oblique font face from
 * the font family. Italic fonts are usually cursive in nature and
 * oblique fonts are usually sloped versions of the regular font.
 */
export type FontStyle = 'normal' | 'italic' | 'oblique';
/**
 * Text properties that can be applied to a text.
 */
export type TextProps = {
    /**
     * The name of the font to use. If not specified, the first registered
     * font that matches the other font properties will be used.
     */
    fontFamily?: string;
    /**
     * The font style to use.
     */
    fontStyle?: FontStyle;
    /**
     * The font weight to use.
     */
    fontWeight?: FontWeight;
    /**
     * The font size in pt.
     */
    fontSize?: number;
    /**
     * The line height as a factor of the text height. The text height is
     * derived from the font's vertical metrics (ascent, descent, and line
     * gap). Values greater than `1` increase the spacing between lines,
     * values less than `1` decrease it. Defaults to `1`.
     */
    lineHeight?: number;
    /**
     * The text color.
     */
    color?: Color;
    /**
     * A link target. When this property is present, the corresponding text will be rendered as a
     * link to the given target. The target can either be a URL or a reference to an anchor in the
     * document. An internal reference starts with a hash sign (`#`), followed by the `id` of an
     * element in the document.
     */
    link?: string;
    /**
     * A vertical offset in pt that shifts the text baseline up (if the value is positive) or down
     * (if negative). Shifting the baseline can be useful for superscripts and subscripts.
     * This setting does not affect the line height.
     */
    rise?: number;
    /**
     * The character spacing in pt. Positive values increase the space between characters, negative
     * values decrease it.
     */
    letterSpacing?: number;
    /**
     * Controls kerning (pair-wise spacing adjustments between specific glyphs).
     * When set to `normal` (the default), the kerning information in the font is applied.
     * When set to `none`, kerning is disabled.
     */
    fontKerning?: 'normal' | 'none';
    /**
     * Controls ligatures and contextual alternates.
     * When set to `normal` (the default), standard ligatures and contextual alternates defined
     * in the font are enabled.
     * When set to `none`, all ligatures and contextual alternates are disabled.
     */
    fontVariantLigatures?: 'normal' | 'none';
    /**
     * Low-level control over OpenType font features.
     * Each key is a four-character OpenType feature tag (e.g. `smcp`, `tnum`), and the value
     * enables (`true`) or disables (`false`) that feature.
     *
     * The `fontKerning` and `fontVariantLigatures` properties should be preferred over this one.
     * The settings from `fontKerning` and `fontVariantLigatures` take precedence over entries
     * in `fontFeatureSettings`.
     */
    fontFeatureSettings?: Record<string, boolean>;
    /**
     * The language of this text, expressed as a BCP 47 tag (e.g. `'en'`,
     * `'tr'`, `'sr'`, `'ar'`).
     *
     * The language may influence text shaping in fonts that provide
     * language-specific typographic behavior. For example, some fonts
     * adjust glyph forms for Turkish or Serbian.
     *
     * If not set, the parent's language is used, or the document’s
     * default language if none of the ancestors specify a language.
     */
    language?: string;
};