Content API¶

namespace NextPDF\Core\Content;

final class TextRenderer

/**
 * 在指定位置渲染文字。
 *
 * @param non-empty-string           $text      文字內容
 * @param Position                   $position  起始位置（mm）
 * @param positive-int|float         $fontSize  字型大小（pt）
 * @param non-empty-string           $fontName  字型別名（需已在 FontRegistry 註冊）
 * @param Color                      $color     文字顏色（預設黑色）
 * @param 'left'|'center'|'right'    $alignment 對齊方式
 * @param float|null                 $maxWidth  最大寬度（mm），超出自動換行
 * @param float                      $lineHeight 行高倍數（1.0 = 單行間距）
 * @param 'ltr'|'rtl'|'auto'        $direction 文字方向
 * @param non-empty-string|null      $language  BCP 47 語言標記（影響 BiDi）
 * @param float                      $letterSpacing 字母間距（mm）
 * @param list<non-empty-string>     $openTypeFeatures OpenType 特性
 * @param HyphenationPatterns|null   $hyphenation 斷詞規則
 * @param StructureElement|null      $structureElement 無障礙結構元素
 * @throws FontNotFoundException
 * @throws TextRenderingException
 */
public function write(
    string                $text,
    Position              $position,
    float                 $fontSize        = 12.0,
    string                $fontName        = 'Helvetica',
    Color                 $color           = Color::BLACK,
    string                $alignment       = 'left',
    ?float                $maxWidth        = null,
    float                 $lineHeight      = 1.2,
    string                $direction       = 'auto',
    ?string               $language        = null,
    float                 $letterSpacing   = 0.0,
    array                 $openTypeFeatures = [],
    ?HyphenationPatterns  $hyphenation     = null,
    ?StructureElement     $structureElement = null,
): TextBounds

/**
 * 渲染多行文字區塊（段落）。
 *
 * @param non-empty-string $text    可包含 \n 的多行文字
 * @param Rectangle        $bounds  文字區域（超出邊界自動截斷）
 * @return TextFlowResult
 */
public function writeParagraph(
    string    $text,
    Rectangle $bounds,
    float     $fontSize   = 12.0,
    string    $fontName   = 'Helvetica',
    Color     $color      = Color::BLACK,
    string    $alignment  = 'justified',
    float     $lineHeight = 1.5,
    string    $direction  = 'auto',
    ?string   $language   = null,
): TextFlowResult

/**
 * 登記文字預處理器（在渲染前攔截並轉換文字）。
 * 敏感文字應在此階段處理，確保不進入 PDF 串流。
 */
public function registerPreprocessor(TextPreprocessorInterface $preprocessor): void

final readonly class TextBounds
{
    public float $x;
    public float $y;
    public float $width;
    public float $height;
    public float $baselineY;  // 基線位置（適用對齊後續元素）
    public int   $renderedLineCount;
}

final readonly class TextFlowResult
{
    public TextBounds $bounds;
    public bool       $truncated;   // 是否因超出邊界而截斷
    public string     $remainingText;  // 未渲染的剩餘文字
}

namespace NextPDF\Core\Content;

final class HyphenationPatterns

/**
 * 載入指定語言的預設斷詞規則。
 *
 * @param non-empty-string $locale BCP 47 語言標記，如 'de-DE'、'fr-FR'
 * @throws UnsupportedLocaleException
 */
public static function forLanguage(string $locale): self

/**
 * 從自訂 .pat 檔案載入斷詞規則。
 *
 * @param non-empty-string $path .pat 檔案的絕對路徑
 */
public static function fromFile(string $path): self

/**
 * 為文字套用斷詞，回傳插入軟連字符（U+00AD）的結果。
 *
 * @param non-empty-string $text
 * @return non-empty-string
 */
public function hyphenate(string $text): string

/** 支援的語言列表 */
public static function supportedLocales(): list<non-empty-string>

namespace NextPDF\Core\Contracts;

interface TextPreprocessorInterface
{
    /**
     * 在文字渲染前進行預處理。
     * 回傳處理後的文字，或 null 表示完全省略此文字（Redaction）。
     *
     * @param non-empty-string $text
     * @param array<string, mixed> $context 渲染上下文（fontSize、fontName 等）
     */
    public function process(string $text, array $context): ?string;

    /** 預處理器優先順序（數字越小越先執行）*/
    public function priority(): int;
}