medical-form-printer 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -97,6 +97,66 @@ interface TableColumn {
97
97
  /** Options (for select type) */
98
98
  options?: string[];
99
99
  }
100
+ /**
101
+ * Header cell configuration for multi-row table headers
102
+ *
103
+ * @since next
104
+ * @description
105
+ * Defines a single cell in a table header row, supporting colspan and rowspan
106
+ * for creating complex nested header structures.
107
+ *
108
+ * @example
109
+ * ```typescript
110
+ * const cell: HeaderCell = {
111
+ * text: 'Blood Pressure (mmHg)',
112
+ * colspan: 2, // Spans 2 columns
113
+ * rowspan: 1 // Default, spans 1 row
114
+ * }
115
+ * ```
116
+ */
117
+ interface HeaderCell {
118
+ /** Header cell text content */
119
+ text: string;
120
+ /**
121
+ * Number of columns this cell spans (default: 1)
122
+ * @default 1
123
+ */
124
+ colspan?: number;
125
+ /**
126
+ * Number of rows this cell spans (default: 1)
127
+ * @default 1
128
+ */
129
+ rowspan?: number;
130
+ /** Cell width (e.g., '100px', '20%') */
131
+ width?: string;
132
+ /**
133
+ * Associated data column field name (used for bottom-level header cells)
134
+ * Links this header cell to a specific data column for alignment
135
+ */
136
+ field?: string;
137
+ }
138
+ /**
139
+ * Header row configuration for multi-row table headers
140
+ *
141
+ * @since next
142
+ * @description
143
+ * Defines a single row in a multi-row table header structure.
144
+ * Each row contains an array of header cells.
145
+ *
146
+ * @example
147
+ * ```typescript
148
+ * const row: HeaderRow = {
149
+ * cells: [
150
+ * { text: 'Date', rowspan: 2 },
151
+ * { text: 'Blood Pressure', colspan: 2 }
152
+ * ]
153
+ * }
154
+ * ```
155
+ */
156
+ interface HeaderRow {
157
+ /** Array of header cells in this row */
158
+ cells: HeaderCell[];
159
+ }
100
160
  /** Table configuration */
101
161
  interface TableConfig$1 {
102
162
  /** Column configuration */
@@ -105,6 +165,27 @@ interface TableConfig$1 {
105
165
  dataField: string;
106
166
  /** Whether to show row numbers */
107
167
  showRowNumber?: boolean;
168
+ /**
169
+ * Multi-row header configuration (optional)
170
+ *
171
+ * @since next
172
+ * @description
173
+ * When provided, enables complex multi-row header structures with
174
+ * colspan and rowspan support. Takes priority over generating
175
+ * headers from the columns configuration.
176
+ *
177
+ * When not provided, a single-row header is generated from the
178
+ * columns configuration for backward compatibility.
179
+ *
180
+ * @example
181
+ * ```typescript
182
+ * headerRows: [
183
+ * { cells: [{ text: 'Date', rowspan: 2 }, { text: 'Blood Pressure', colspan: 2 }] },
184
+ * { cells: [{ text: 'Systolic' }, { text: 'Diastolic' }] }
185
+ * ]
186
+ * ```
187
+ */
188
+ headerRows?: HeaderRow[];
108
189
  }
109
190
  /** Checkbox option */
110
191
  interface CheckboxOption {
@@ -275,6 +356,8 @@ interface PrintSchema {
275
356
  pageSize: PageSize;
276
357
  /** Page orientation */
277
358
  orientation: PageOrientation;
359
+ /** Base unit for scaling (default: 1, e.g., 0.95 = 5% smaller, 1.1 = 10% larger) */
360
+ baseUnit?: number;
278
361
  /** Header configuration */
279
362
  header: PrintHeader;
280
363
  /** Section list */
@@ -708,6 +791,32 @@ declare function each<T>(items: T[] | undefined | null, renderer: (item: T, inde
708
791
  /**
709
792
  * @fileoverview HTML Rendering Core
710
793
  * @module renderer/html-renderer
794
+ * @version 2.1.0
795
+ * @author Kiro
796
+ * @created 2024-04-07
797
+ * @modified 2026-01-04
798
+ *
799
+ * @description
800
+ * Core HTML rendering module for medical form print output.
801
+ * Generates complete HTML documents with embedded CSS styles,
802
+ * ready for printing or PDF generation.
803
+ *
804
+ * Features:
805
+ * - Schema-driven rendering with PrintSchema configuration
806
+ * - Per-template baseUnit scaling support
807
+ * - Watermark support
808
+ * - Custom theme configuration
809
+ *
810
+ * @dependencies
811
+ * - ../types/print-schema - Print configuration types
812
+ * - ../types/options - Render options types
813
+ * - ../styles - CSS generation and theme system
814
+ * - ./section-renderers - Section-specific renderers
815
+ * - ../utils - Utility functions
816
+ *
817
+ * @usedBy
818
+ * - ../index.ts - Library main entry
819
+ * - ../node.ts - Node.js PDF generation entry
711
820
  */
712
821
 
713
822
  /**
@@ -815,7 +924,10 @@ declare function renderToIsolatedFragment(schema: PrintSchema, data: FormData, o
815
924
  /**
816
925
  * @fileoverview Section renderer registry
817
926
  * @module renderer/section-renderers
818
- * @modified 2024-04-06
927
+ * @version 1.1.0
928
+ * @author Kiro
929
+ * @created 2024-04-06
930
+ * @modified 2026-01-05
819
931
  */
820
932
 
821
933
  /**
@@ -2554,20 +2666,113 @@ declare function formatValue(value: unknown, type?: string, options?: {
2554
2666
  */
2555
2667
  declare function isChecked(values: unknown, optionValue: unknown): boolean;
2556
2668
 
2669
+ /**
2670
+ * @fileoverview Pagination related type definitions
2671
+ * @module pagination/types
2672
+ * @version 1.1.0
2673
+ * @author Kiro
2674
+ * @created 2026-01-03
2675
+ * @modified 2026-01-04
2676
+ *
2677
+ * @description
2678
+ * Defines all types for the smart pagination module, including:
2679
+ * - Page dimension configuration
2680
+ * - Measurable content items
2681
+ * - Pagination results
2682
+ * - Overflow field configuration
2683
+ * - Pagination configuration
2684
+ * - Overflow text i18n configuration
2685
+ *
2686
+ * @requirements
2687
+ * - 9.1: Calculate page breaks based on measured content height
2688
+ * - 9.5: Support configurable page sizes
2689
+ * - 9.7: Support pre-measuring content height
2690
+ * - 5.1: Support i18n for overflow text
2691
+ *
2692
+ * @usedBy
2693
+ * - ./page-dimensions.ts - Page dimension configuration
2694
+ * - ./page-break-calculator.ts - Core pagination algorithm
2695
+ * - ./overflow-handler.ts - Overflow field handling
2696
+ * - ./paginated-renderer.ts - Paginated renderer
2697
+ * - ./index.ts - Module entry
2698
+ */
2699
+ /**
2700
+ * Pagination module default configuration
2701
+ */
2702
+ declare const PAGINATION_DEFAULTS: {
2703
+ /** Maximum characters for overflow field first page */
2704
+ readonly OVERFLOW_FIRST_LINE_CHARS: 60;
2705
+ /** Minimum table row height estimate (mm) */
2706
+ readonly MIN_ROW_HEIGHT: 8;
2707
+ /** Default DPI (dots per inch), standard screen DPI is 96 */
2708
+ readonly DPI: 96;
2709
+ /** 1 inch = 25.4 millimeters */
2710
+ readonly MM_PER_INCH: 25.4;
2711
+ /** Default margins (mm) */
2712
+ readonly MARGIN: {
2713
+ readonly TOP: 8;
2714
+ readonly BOTTOM: 8;
2715
+ readonly LEFT: 10;
2716
+ readonly RIGHT: 10;
2717
+ };
2718
+ };
2557
2719
  /** @deprecated Use PAGINATION_DEFAULTS.DPI instead */
2558
2720
  declare const DEFAULT_DPI: 96;
2559
2721
  /** @deprecated Use PAGINATION_DEFAULTS.MM_PER_INCH instead */
2560
2722
  declare const MM_PER_INCH: 25.4;
2561
2723
  /**
2562
2724
  * Measurable content item type enum
2725
+ *
2726
+ * ## Page Structure and Item Types
2727
+ *
2728
+ * ```
2729
+ * ┌─────────────────────────────────────┐
2730
+ * │ Header │ → type: 'header'
2731
+ * │ Hospital, Department, Title │
2732
+ * ├─────────────────────────────────────┤
2733
+ * │ Body │
2734
+ * │ - info-grid, checkbox-grid │ → type: 'section'
2735
+ * │ - table header │ → type: 'table-header'
2736
+ * │ - table rows │ → type: 'table-row'
2737
+ * │ - notes-section │ → type: 'footer' (!)
2738
+ * ├─────────────────────────────────────┤
2739
+ * │ Footer │
2740
+ * │ - Signature Area │ → type: 'signature'
2741
+ * │ - Page Number + Notes │ → type: 'footer'
2742
+ * └─────────────────────────────────────┘
2743
+ * ```
2744
+ *
2745
+ * ## Type Definitions
2746
+ *
2747
+ * - **header**: Page header (.print-header), contains hospital/department/title
2748
+ * - **section**: Content sections like info-grid, checkbox-grid
2749
+ * - **table-header**: Table header row (thead)
2750
+ * - **table-row**: Table body row (tbody tr)
2751
+ * - **signature**: Signature area (.signature-area), separate from footer
2752
+ * - **footer**: Page footer (.print-footer) containing page number and notes,
2753
+ * also includes notes-section elements
2754
+ *
2755
+ * ## Important: Signature vs Footer
2756
+ *
2757
+ * Signature area has its own type 'signature', NOT 'footer'.
2758
+ * This allows different pagination behavior:
2759
+ * - Footer (page number): Always shown on each page
2760
+ * - Signature: Configurable via signatureOnEachPage (true/false)
2761
+ *
2563
2762
  * @requirements 9.1 - Identify different types of content items
2564
2763
  */
2565
2764
  declare const MEASURABLE_ITEM_TYPES: {
2765
+ /** Page header with hospital, department, title */
2566
2766
  readonly HEADER: "header";
2767
+ /** Content section (info-grid, checkbox-grid, etc.) */
2567
2768
  readonly SECTION: "section";
2769
+ /** Table header row */
2568
2770
  readonly TABLE_HEADER: "table-header";
2771
+ /** Table body row */
2569
2772
  readonly TABLE_ROW: "table-row";
2773
+ /** Signature area (separate from footer, has own pagination rules) */
2570
2774
  readonly SIGNATURE: "signature";
2775
+ /** Page footer with page number and notes */
2571
2776
  readonly FOOTER: "footer";
2572
2777
  };
2573
2778
  /**
@@ -2593,6 +2798,11 @@ interface PageDimensions {
2593
2798
  /** Right margin (mm) */
2594
2799
  marginRight: number;
2595
2800
  }
2801
+ /**
2802
+ * Page size preset names
2803
+ * @requirements 3.1 - Support A4, A5, 16K page sizes
2804
+ */
2805
+ type PageSizePreset = '16K' | 'A4' | 'A5';
2596
2806
  /**
2597
2807
  * Measurable content item
2598
2808
  * @requirements 9.7 - Support pre-measuring content height
@@ -2746,11 +2956,43 @@ interface PageBreakOptions {
2746
2956
  footerHeight?: number;
2747
2957
  /** Whether to repeat table headers, default true */
2748
2958
  repeatTableHeaders?: boolean;
2959
+ /**
2960
+ * Extra height to reserve on the last page only (px), default 0
2961
+ * Used for signature area when signatureOnEachPage is false
2962
+ */
2963
+ lastPageExtraHeight?: number;
2964
+ }
2965
+ /**
2966
+ * Overflow text configuration for internationalization
2967
+ * Configures user-visible text for overflow field pagination
2968
+ *
2969
+ * @requirements 5.1 - Support i18n for overflow text
2970
+ *
2971
+ * @example
2972
+ * // Use Chinese (default)
2973
+ * const config = { overflowText: DEFAULT_OVERFLOW_TEXT }
2974
+ *
2975
+ * // Use English
2976
+ * const config = { overflowText: ENGLISH_OVERFLOW_TEXT }
2977
+ */
2978
+ interface OverflowTextConfig {
2979
+ /** Continuation marker on first page, e.g., "(续见附页)" */
2980
+ seeNextMarker: string;
2981
+ /** Label suffix on continuation page, e.g., "(续)" */
2982
+ continuationSuffix: string;
2983
+ /** Page title suffix for continuation pages, e.g., "(续)" */
2984
+ pageTitleSuffix: string;
2749
2985
  }
2750
2986
  /**
2751
- * Page size preset name
2987
+ * Default overflow text configuration (Chinese)
2988
+ * @requirements 5.1 - Default Chinese text
2752
2989
  */
2753
- type PageSizePreset = '16K' | 'A4' | 'A5';
2990
+ declare const DEFAULT_OVERFLOW_TEXT: OverflowTextConfig;
2991
+ /**
2992
+ * English overflow text configuration
2993
+ * @requirements 5.1 - English text option
2994
+ */
2995
+ declare const ENGLISH_OVERFLOW_TEXT: OverflowTextConfig;
2754
2996
 
2755
2997
  /**
2756
2998
  * @fileoverview Page dimension configuration and unit conversion
@@ -2946,6 +3188,7 @@ declare function buildTableHeaderMap(items: MeasurableItem[]): Map<string, Measu
2946
3188
  * 3. Ensure table rows are not split (move entire row to next page)
2947
3189
  * 4. Continuation pages need to repeat corresponding table headers (Requirements 9.3)
2948
3190
  * 5. Reserve header height during calculation (Requirements 9.6)
3191
+ * 6. Reserve extra height on last page for signature (when lastPageExtraHeight is set)
2949
3192
  *
2950
3193
  * @param items - All measurable content items
2951
3194
  * @param options - Page break calculation options
@@ -2999,11 +3242,11 @@ declare function getPageContentHeight(page: PageContent, items: MeasurableItem[]
2999
3242
  * - 9.7: Support overflow field pagination
3000
3243
  *
3001
3244
  * @dependencies
3002
- * - ./types.ts - Type definitions
3245
+ * - ../../types.ts - Type definitions
3003
3246
  *
3004
3247
  * @usedBy
3005
3248
  * - ./index.ts - Module entry
3006
- * - ../renderer/paginated-renderer.ts - Paginated renderer (to be implemented)
3249
+ * - ../../paginated-renderer.ts - Paginated renderer
3007
3250
  */
3008
3251
 
3009
3252
  /**
@@ -3092,13 +3335,742 @@ declare function processOverflowFields(data: Record<string, unknown>, configs: O
3092
3335
  */
3093
3336
  declare function hasAnyOverflowContent(data: Record<string, unknown>, configs: OverflowFieldConfig[]): boolean;
3094
3337
 
3338
+ /**
3339
+ * @fileoverview Overflow field pagination rendering
3340
+ * @module pagination/overflow-pagination
3341
+ * @version 1.0.0
3342
+ * @author Kiro
3343
+ * @created 2026-01-04
3344
+ * @modified 2026-01-04
3345
+ *
3346
+ * @description
3347
+ * Handles overflow field pagination rendering logic:
3348
+ * - Identifies sections containing overflow fields
3349
+ * - First page displays truncated content + continuation marker (red "see next page")
3350
+ * - Continuation pages display remaining content with field label + "(continued)" suffix
3351
+ * - Integrates with existing pagination features
3352
+ *
3353
+ * @requirements
3354
+ * - 1.1: Identify sections containing overflow fields
3355
+ * - 1.2: Support info-grid sections with overflow fields
3356
+ * - 1.3: Support multiple overflow fields
3357
+ * - 2.1: Render truncated content on first page
3358
+ * - 2.2: Append continuation marker when there is overflow content
3359
+ * - 3.1: Render remaining content on continuation pages
3360
+ * - 3.2: Display field label with continuation suffix
3361
+ *
3362
+ * @dependencies
3363
+ * - ./overflow-handler.ts - Overflow field processing core logic
3364
+ * - ../../types.ts - Type definitions
3365
+ * - ../../../types/print-schema.ts - PrintSection types
3366
+ *
3367
+ * @usedBy
3368
+ * - ../../paginated-renderer.ts - Paginated renderer
3369
+ */
3370
+
3371
+ /** Class name generator function type */
3372
+ type ClassNameFn = (name: string) => string;
3373
+ /**
3374
+ * Overflow field render context
3375
+ * Contains all information needed to render overflow fields
3376
+ */
3377
+ interface OverflowRenderContext {
3378
+ /** Overflow field processing result */
3379
+ result: OverflowFieldResult;
3380
+ /** Field label (for continuation page display) */
3381
+ fieldLabel: string;
3382
+ /** Whether this is the first page */
3383
+ isFirstPage: boolean;
3384
+ }
3385
+ /** CSS class names for overflow field rendering */
3386
+ declare const OVERFLOW_CSS_CLASSES: {
3387
+ /** First page truncated content container */
3388
+ readonly OVERFLOW_FIRST_LINE: "overflow-first-line";
3389
+ /** Continuation page content container */
3390
+ readonly OVERFLOW_CONTINUATION: "overflow-continuation";
3391
+ /** "see next page" marker (red color) */
3392
+ readonly SEE_NEXT: "see-next";
3393
+ /** Field label on continuation page */
3394
+ readonly OVERFLOW_LABEL: "overflow-label";
3395
+ /** Overflow content (preserves whitespace) */
3396
+ readonly OVERFLOW_CONTENT: "overflow-content";
3397
+ };
3398
+ /**
3399
+ * Check if a section contains overflow fields
3400
+ *
3401
+ * @param section - PrintSection to check
3402
+ * @param overflowFields - List of overflow field names
3403
+ * @returns Whether section contains any overflow field
3404
+ *
3405
+ * @requirements 1.1, 1.2 - Identify sections containing overflow fields
3406
+ *
3407
+ * @example
3408
+ * const isOverflow = isOverflowSection(section, ['nursingPoints'])
3409
+ */
3410
+ declare function isOverflowSection(section: PrintSection, overflowFields: string[]): boolean;
3411
+ /**
3412
+ * Find the label for an overflow field from section configuration
3413
+ *
3414
+ * @param section - PrintSection containing the field
3415
+ * @param fieldName - Field name to find
3416
+ * @returns Field label, or fieldName if not found
3417
+ *
3418
+ * @requirements 1.2 - Extract field label from info-grid configuration
3419
+ *
3420
+ * @example
3421
+ * const label = findOverflowFieldLabel(section, 'nursingPoints')
3422
+ * // Returns: "Nursing Points (add attachment if needed)"
3423
+ */
3424
+ declare function findOverflowFieldLabel(section: PrintSection, fieldName: string): string;
3425
+ /**
3426
+ * Find overflow field cell from section
3427
+ *
3428
+ * @param section - PrintSection to search
3429
+ * @param fieldName - Field name to find
3430
+ * @returns InfoGridCell if found, undefined otherwise
3431
+ */
3432
+ declare function findOverflowFieldCell(section: PrintSection, fieldName: string): InfoGridCell | undefined;
3433
+ /**
3434
+ * Extract overflow field configurations from PaginationConfig
3435
+ *
3436
+ * @param paginationConfig - Pagination configuration
3437
+ * @returns Array of overflow field configurations
3438
+ *
3439
+ * @requirements 1.3 - Support multiple overflow fields
3440
+ *
3441
+ * @example
3442
+ * const configs = getOverflowFieldsFromConfig(schema.pagination)
3443
+ */
3444
+ declare function getOverflowFieldsFromConfig(paginationConfig?: PaginationConfig): OverflowFieldConfig[];
3445
+ /**
3446
+ * Get overflow field names from PaginationConfig
3447
+ *
3448
+ * @param paginationConfig - Pagination configuration
3449
+ * @returns Array of overflow field names
3450
+ */
3451
+ declare function getOverflowFieldNames(paginationConfig?: PaginationConfig): string[];
3452
+ /**
3453
+ * Render overflow field content for first page
3454
+ * Displays truncated content with red "(see next page)" marker when there is overflow
3455
+ *
3456
+ * @param value - Field value
3457
+ * @param maxChars - Maximum characters to display
3458
+ * @param textConfig - Overflow text configuration for i18n
3459
+ * @param cls - Class name generator function
3460
+ * @returns Rendered HTML string
3461
+ *
3462
+ * @requirements 2.1, 2.2, 2.3, 2.4 - First page overflow rendering
3463
+ *
3464
+ * @example
3465
+ * // Output: "1. Breastfeeding guidance <span class="see-next">(see next page)</span>"
3466
+ * renderOverflowFirstLine(value, 60, DEFAULT_OVERFLOW_TEXT, cls)
3467
+ */
3468
+ declare function renderOverflowFirstLine(value: unknown, maxChars: number, textConfig: OverflowTextConfig, cls: ClassNameFn): string;
3469
+ /**
3470
+ * Render overflow field content for continuation page
3471
+ * Displays field label with "(continued)" suffix and remaining content
3472
+ *
3473
+ * @param result - Overflow field processing result
3474
+ * @param fieldLabel - Field label (e.g., "Nursing Points (add attachment if needed)")
3475
+ * @param textConfig - Overflow text configuration for i18n
3476
+ * @param cls - Class name generator function
3477
+ * @returns Rendered HTML string
3478
+ *
3479
+ * @requirements 3.1, 3.2, 3.3, 3.4 - Continuation page overflow rendering
3480
+ *
3481
+ * @example
3482
+ * // Output:
3483
+ * // <div class="overflow-continuation">
3484
+ * // <div class="overflow-label">Nursing Points (continued):</div>
3485
+ * // <div class="overflow-content">2. Umbilical care, keep dry\n3. Jaundice monitoring...</div>
3486
+ * // </div>
3487
+ */
3488
+ declare function renderOverflowContinuation(result: OverflowFieldResult, fieldLabel: string, textConfig: OverflowTextConfig, cls: ClassNameFn): string;
3489
+ /**
3490
+ * Merge overflow text configuration with defaults
3491
+ *
3492
+ * @param config - Partial overflow text configuration
3493
+ * @returns Complete overflow text configuration
3494
+ */
3495
+ declare function mergeOverflowTextConfig(config?: Partial<OverflowTextConfig>): OverflowTextConfig;
3496
+ /**
3497
+ * Overflow continuation page render context
3498
+ */
3499
+ interface OverflowContinuationPageContext {
3500
+ /** Page number for this continuation page */
3501
+ pageNumber: number;
3502
+ /** Total pages (including this continuation page) */
3503
+ totalPages: number;
3504
+ /** Form title */
3505
+ title: string;
3506
+ /** Hospital name */
3507
+ hospital?: string;
3508
+ /** Department name */
3509
+ department?: string;
3510
+ /** Overflow field results with labels */
3511
+ overflowFields: Array<{
3512
+ result: OverflowFieldResult;
3513
+ label: string;
3514
+ }>;
3515
+ /** Overflow text configuration */
3516
+ textConfig: OverflowTextConfig;
3517
+ /** Whether to show signature area */
3518
+ showSignature?: boolean;
3519
+ /** Signature HTML (pre-rendered) */
3520
+ signatureHtml?: string;
3521
+ /** Page number format */
3522
+ pageNumberFormat?: string;
3523
+ }
3524
+ /**
3525
+ * Render complete overflow continuation page
3526
+ * Includes header (with "(continued)" suffix), overflow content, optional signature, and footer
3527
+ *
3528
+ * @param ctx - Continuation page context
3529
+ * @param cls - Class name generator function
3530
+ * @param pageSize - Page size class (e.g., "16k", "a4")
3531
+ * @param orientation - Page orientation (e.g., "portrait", "landscape")
3532
+ * @returns Rendered page HTML
3533
+ *
3534
+ * @requirements 3.1, 4.2, 4.3 - Continuation page rendering
3535
+ *
3536
+ * @example
3537
+ * const pageHtml = renderOverflowContinuationPage(ctx, cls, '16k', 'portrait')
3538
+ */
3539
+ declare function renderOverflowContinuationPage(ctx: OverflowContinuationPageContext, cls: ClassNameFn, pageSize?: string, orientation?: string): string;
3540
+ /**
3541
+ * Check if any overflow fields have continuation content
3542
+ *
3543
+ * @param overflowFields - Array of overflow field results
3544
+ * @returns Whether any field has continuation content
3545
+ */
3546
+ declare function hasAnyContinuationContent(overflowFields: Array<{
3547
+ result: OverflowFieldResult;
3548
+ }>): boolean;
3549
+
3550
+ /**
3551
+ * @fileoverview Pagination strategy interface and context
3552
+ * @module pagination/strategies/pagination-strategy
3553
+ * @version 1.0.0
3554
+ * @author Kiro
3555
+ * @created 2026-01-04
3556
+ * @modified 2026-01-04
3557
+ *
3558
+ * @description
3559
+ * Defines the unified pagination strategy interface and context class.
3560
+ * Implements the Strategy pattern for different pagination approaches:
3561
+ * - Smart pagination (table-based measurement)
3562
+ * - Overflow pagination (long text field handling)
3563
+ *
3564
+ * @requirements
3565
+ * - 1.1: Define unified PaginationStrategy interface
3566
+ * - 1.2: Interface has name property
3567
+ * - 1.3: Interface has shouldApply method
3568
+ * - 1.4: Interface has render method
3569
+ * - 4.1: PaginationContext accepts strategies in constructor
3570
+ * - 4.2: Context provides getApplicableStrategies method
3571
+ * - 4.3: Context provides render method
3572
+ * - 4.4: Context executes applicable strategies
3573
+ *
3574
+ * @dependencies
3575
+ * - ../../types/print-schema - PrintSchema and FormData types
3576
+ * - ../types - PaginationConfig and related types
3577
+ *
3578
+ * @usedBy
3579
+ * - ./smart/smart-pagination-strategy.ts - Smart pagination strategy
3580
+ * - ./overflow/overflow-pagination-strategy.ts - Overflow pagination strategy
3581
+ * - ../paginated-renderer.ts - Main pagination renderer
3582
+ */
3583
+
3584
+ /**
3585
+ * Extended PrintSchema with pagination configuration
3586
+ * @requirements 1.1 - Support pagination configuration in schema
3587
+ */
3588
+ interface PrintSchemaWithPagination extends PrintSchema {
3589
+ /** Pagination configuration */
3590
+ pagination?: PaginationConfig;
3591
+ }
3592
+ /**
3593
+ * Pagination render options
3594
+ * @requirements 1.4 - Render method options parameter
3595
+ */
3596
+ interface PaginationRenderOptions {
3597
+ /** Whether to render in isolated mode (with CSS namespace) */
3598
+ isolated?: boolean;
3599
+ /** Pre-measured content items for smart pagination */
3600
+ measuredItems?: MeasurableItem[];
3601
+ /** Overflow text configuration for i18n */
3602
+ textConfig?: Partial<OverflowTextConfig>;
3603
+ }
3604
+ /**
3605
+ * Pagination strategy interface
3606
+ * Defines unified API for different pagination approaches
3607
+ *
3608
+ * @requirements 1.1, 1.2, 1.3, 1.4 - Unified pagination strategy interface
3609
+ *
3610
+ * @example
3611
+ * class MyPaginationStrategy implements PaginationStrategy {
3612
+ * readonly name = 'my-strategy'
3613
+ *
3614
+ * shouldApply(schema: PrintSchemaWithPagination): boolean {
3615
+ * return schema.pagination?.myStrategy?.enabled === true
3616
+ * }
3617
+ *
3618
+ * render(schema: PrintSchemaWithPagination, data: FormData, options?: PaginationRenderOptions): string {
3619
+ * // Implementation here
3620
+ * return '<div>Rendered content</div>'
3621
+ * }
3622
+ * }
3623
+ */
3624
+ interface PaginationStrategy {
3625
+ /**
3626
+ * Strategy name identifier
3627
+ * @requirements 1.2 - Interface has name property
3628
+ */
3629
+ readonly name: string;
3630
+ /**
3631
+ * Check if this strategy should be applied to the given schema
3632
+ * @param schema - Print schema with pagination configuration
3633
+ * @returns Whether this strategy applies
3634
+ * @requirements 1.3 - Interface has shouldApply method
3635
+ */
3636
+ shouldApply(schema: PrintSchemaWithPagination): boolean;
3637
+ /**
3638
+ * Render paginated content using this strategy
3639
+ * @param schema - Print schema with pagination configuration
3640
+ * @param data - Form data to render
3641
+ * @param options - Render options
3642
+ * @returns Rendered HTML string
3643
+ * @requirements 1.4 - Interface has render method
3644
+ */
3645
+ render(schema: PrintSchemaWithPagination, data: FormData, options?: PaginationRenderOptions): string;
3646
+ }
3647
+ /**
3648
+ * Pagination context class
3649
+ * Manages strategy selection and execution using the Strategy pattern
3650
+ *
3651
+ * @requirements 4.1, 4.2, 4.3, 4.4 - Strategy context implementation
3652
+ *
3653
+ * @example
3654
+ * const strategies = [new SmartPaginationStrategy(), new OverflowPaginationStrategy()]
3655
+ * const context = new PaginationContext(strategies)
3656
+ *
3657
+ * const applicableStrategies = context.getApplicableStrategies(schema)
3658
+ * const html = context.render(schema, data, options)
3659
+ */
3660
+ declare class PaginationContext {
3661
+ private strategies;
3662
+ /**
3663
+ * Create pagination context with strategies
3664
+ * @param strategies - Array of pagination strategies
3665
+ * @requirements 4.1 - Context accepts strategies in constructor
3666
+ */
3667
+ constructor(strategies: PaginationStrategy[]);
3668
+ /**
3669
+ * Get strategies that apply to the given schema
3670
+ * @param schema - Print schema with pagination configuration
3671
+ * @returns Array of applicable strategies
3672
+ * @requirements 4.2 - Context provides getApplicableStrategies method
3673
+ */
3674
+ getApplicableStrategies(schema: PrintSchemaWithPagination): PaginationStrategy[];
3675
+ /**
3676
+ * Render content using applicable strategies
3677
+ * Uses the first applicable strategy, falls back to non-paginated rendering if none apply
3678
+ * @param schema - Print schema with pagination configuration
3679
+ * @param data - Form data to render
3680
+ * @param options - Render options
3681
+ * @returns Rendered HTML string
3682
+ * @requirements 4.3, 4.4 - Context provides render method and executes strategies
3683
+ */
3684
+ render(schema: PrintSchemaWithPagination, data: FormData, options?: PaginationRenderOptions): string;
3685
+ /**
3686
+ * Add a strategy to the context
3687
+ * @param strategy - Strategy to add
3688
+ */
3689
+ addStrategy(strategy: PaginationStrategy): void;
3690
+ /**
3691
+ * Remove a strategy from the context
3692
+ * @param strategyName - Name of strategy to remove
3693
+ * @returns Whether strategy was found and removed
3694
+ */
3695
+ removeStrategy(strategyName: string): boolean;
3696
+ /**
3697
+ * Get all registered strategies
3698
+ * @returns Array of all strategies
3699
+ */
3700
+ getAllStrategies(): readonly PaginationStrategy[];
3701
+ /**
3702
+ * Get strategy by name
3703
+ * @param name - Strategy name
3704
+ * @returns Strategy if found, undefined otherwise
3705
+ */
3706
+ getStrategy(name: string): PaginationStrategy | undefined;
3707
+ }
3708
+
3709
+ /**
3710
+ * @fileoverview Measurement strategy interface (GoF Strategy Pattern)
3711
+ * @module pagination/strategies/smart/measurement-strategy
3712
+ * @version 1.4.0
3713
+ * @author Kiro
3714
+ * @created 2026-01-05
3715
+ * @modified 2026-01-05
3716
+ *
3717
+ * @description
3718
+ * Defines the MeasurementStrategy interface for decoupling measurement logic
3719
+ * from pagination logic. This follows the GoF Strategy Pattern to allow
3720
+ * different measurement implementations (e.g., DOM-based measurement).
3721
+ *
3722
+ * @requirements
3723
+ * - 1.1: Define MeasurementStrategy interface with measure method
3724
+ * - 1.2: Interface supports DOM-based measurement implementation
3725
+ *
3726
+ * @dependencies
3727
+ * - ../pagination-strategy - PrintSchemaWithPagination type
3728
+ * - ../../../types/print-schema - FormData type
3729
+ * - ../../types - MeasurableItem type
3730
+ *
3731
+ * @usedBy
3732
+ * - ./dom-measurement-strategy.ts - DOM measurement implementation
3733
+ * - ./smart-pagination-strategy.ts - Smart pagination strategy
3734
+ */
3735
+
3736
+ /**
3737
+ * Measurement configuration options
3738
+ * Provides parameters needed for content measurement
3739
+ *
3740
+ * @requirements 1.1 - Configuration for measurement strategy
3741
+ */
3742
+ interface MeasurementConfig {
3743
+ /**
3744
+ * Minimum row height in millimeters (for fallback estimation)
3745
+ * Used when actual measurement is not possible
3746
+ * @default 8
3747
+ */
3748
+ minRowHeight: number;
3749
+ /**
3750
+ * Available page height in pixels
3751
+ * Used to determine content fitting and page breaks
3752
+ */
3753
+ pageHeight: number;
3754
+ }
3755
+ /**
3756
+ * Measurement strategy interface (GoF Strategy Pattern)
3757
+ *
3758
+ * Defines a unified interface for measuring content heights.
3759
+ * Implementations can provide different measurement approaches:
3760
+ * - DOM-based measurement (browser environment)
3761
+ * - Estimation-based measurement (fallback)
3762
+ *
3763
+ * @requirements 1.1, 1.2 - Unified measurement interface supporting DOM-based implementation
3764
+ *
3765
+ * @example
3766
+ * ```typescript
3767
+ * class DomMeasurementStrategy implements MeasurementStrategy {
3768
+ * measure(schema, data, config): MeasurableItem[] {
3769
+ * // Render to hidden container and measure actual heights
3770
+ * return measuredItems
3771
+ * }
3772
+ * }
3773
+ *
3774
+ * // Usage with SmartPaginationStrategy
3775
+ * const strategy = new SmartPaginationStrategy(new DomMeasurementStrategy())
3776
+ * ```
3777
+ */
3778
+ interface MeasurementStrategy {
3779
+ /**
3780
+ * Measure content and return measurable items with heights
3781
+ *
3782
+ * Implementations should:
3783
+ * 1. Analyze the schema to identify measurable content
3784
+ * 2. Use the data to determine actual content (e.g., table row count)
3785
+ * 3. Measure or estimate heights for each content item
3786
+ * 4. Return an array of MeasurableItem objects
3787
+ *
3788
+ * For table sections, implementations should create:
3789
+ * - One item for the table header
3790
+ * - One item for each data row
3791
+ *
3792
+ * @param schema - Print schema with pagination configuration
3793
+ * @param data - Form data containing actual content (e.g., table rows)
3794
+ * @param config - Measurement configuration options
3795
+ * @returns Array of measurable items with heights in pixels
3796
+ *
3797
+ * @throws Error if measurement cannot be performed (e.g., non-browser environment for DOM strategy)
3798
+ *
3799
+ * @requirements 1.1 - measure method signature
3800
+ * @requirements 1.2 - Support DOM-based measurement
3801
+ */
3802
+ measure(schema: PrintSchemaWithPagination, data: FormData, config: MeasurementConfig): MeasurableItem[];
3803
+ }
3804
+
3805
+ /**
3806
+ * @fileoverview Smart pagination strategy adapter
3807
+ * @module pagination/strategies/smart/smart-pagination-strategy
3808
+ * @version 1.4.0
3809
+ * @author Kiro
3810
+ * @created 2026-01-04
3811
+ * @modified 2026-01-05
3812
+ *
3813
+ * @description
3814
+ * Smart pagination strategy adapter that wraps the existing page-break-calculator logic.
3815
+ * Implements the PaginationStrategy interface for table-based measurement pagination.
3816
+ * Delegates to existing calculatePageBreaks function without modifying the algorithm.
3817
+ *
3818
+ * Uses GoF Strategy Pattern for measurement logic - accepts a MeasurementStrategy
3819
+ * via dependency injection, defaulting to DomMeasurementStrategy for browser-based
3820
+ * DOM measurement.
3821
+ *
3822
+ * @requirements
3823
+ * - 1.3: SmartPaginationStrategy uses MeasurementStrategy for content measurement
3824
+ * - 2.1: Create SmartPaginationStrategy in strategies/smart/
3825
+ * - 2.3: Implement PaginationStrategy interface
3826
+ * - 2.4: Delegate to existing calculatePageBreaks and renderPaginatedHtml
3827
+ * - 2.5: shouldApply checks pagination.smartPagination.enabled === true
3828
+ * - 4.1, 4.2, 4.3, 4.4: Pass correct measurement data to pagination algorithm
3829
+ * - 5.1, 5.2, 5.3, 5.4: Deprecate estimateItems method
3830
+ *
3831
+ * @dependencies
3832
+ * - ../pagination-strategy - PaginationStrategy interface
3833
+ * - ./page-break-calculator - Existing smart pagination algorithm
3834
+ * - ./measurement-strategy - MeasurementStrategy interface
3835
+ * - ./dom-measurement-strategy - Default DOM measurement implementation
3836
+ * - ../../paginated-renderer - Paginated HTML renderer
3837
+ * - ../../types - Type definitions
3838
+ *
3839
+ * @usedBy
3840
+ * - ../index.ts - Strategy exports
3841
+ * - ../../paginated-renderer.ts - Main pagination renderer
3842
+ */
3843
+
3844
+ /**
3845
+ * Smart pagination strategy adapter
3846
+ * Wraps existing smart pagination logic in strategy interface
3847
+ *
3848
+ * Uses GoF Strategy Pattern for measurement - accepts a MeasurementStrategy
3849
+ * via constructor injection, defaulting to DomMeasurementStrategy.
3850
+ *
3851
+ * @requirements 1.3, 2.1, 2.3, 2.4, 2.5, 4.1, 4.2, 4.3, 4.4 - Smart pagination strategy implementation
3852
+ *
3853
+ * @example
3854
+ * // Default usage with DomMeasurementStrategy
3855
+ * const strategy = new SmartPaginationStrategy()
3856
+ * if (strategy.shouldApply(schema)) {
3857
+ * const html = strategy.render(schema, data, options)
3858
+ * }
3859
+ *
3860
+ * @example
3861
+ * // Custom measurement strategy
3862
+ * const customStrategy = new SmartPaginationStrategy(myCustomMeasurementStrategy)
3863
+ */
3864
+ declare class SmartPaginationStrategy implements PaginationStrategy {
3865
+ /**
3866
+ * Strategy name identifier
3867
+ * @requirements 2.1 - Strategy name
3868
+ */
3869
+ readonly name = "smart-pagination";
3870
+ /**
3871
+ * Measurement strategy for content measurement (GoF Strategy Pattern)
3872
+ * @requirements 1.3 - Use MeasurementStrategy for content measurement
3873
+ */
3874
+ private measurementStrategy;
3875
+ /**
3876
+ * Constructor with optional measurement strategy injection
3877
+ * @param measurementStrategy - Custom measurement strategy (defaults to DomMeasurementStrategy)
3878
+ * @requirements 1.3 - Dependency injection for measurement strategy
3879
+ */
3880
+ constructor(measurementStrategy?: MeasurementStrategy);
3881
+ /**
3882
+ * Check if smart pagination should be applied
3883
+ * @param schema - Print schema with pagination configuration
3884
+ * @returns Whether smart pagination is enabled
3885
+ * @requirements 2.5 - shouldApply checks smartPagination.enabled
3886
+ */
3887
+ shouldApply(schema: PrintSchemaWithPagination): boolean;
3888
+ /**
3889
+ * Render content using smart pagination
3890
+ * Delegates to existing calculatePageBreaks and renderPaginatedHtml functions
3891
+ * Uses injected measurement strategy for DOM measurement
3892
+ * @param schema - Print schema with pagination configuration
3893
+ * @param data - Form data to render
3894
+ * @param options - Render options
3895
+ * @returns Rendered HTML string
3896
+ * @requirements 1.3, 2.3, 2.4, 3.1, 3.2, 4.1, 4.2, 4.3, 4.4 - Delegate to existing functions with correct measurement data
3897
+ */
3898
+ render(schema: PrintSchemaWithPagination, data: FormData, options?: PaginationRenderOptions): string;
3899
+ /**
3900
+ * Extract header height from measured items
3901
+ * Finds the item with type 'header' and returns its height
3902
+ * @param items - All measured items
3903
+ * @returns Header height in pixels, or 0 if no header item found
3904
+ * @requirements 1.1, 1.2, 1.4 - Extract header height from measured results
3905
+ */
3906
+ private extractHeaderHeight;
3907
+ /**
3908
+ * Extract footer height from measured items
3909
+ * Only includes 'footer' type items. Signature height is handled separately
3910
+ * based on signatureOnEachPage configuration.
3911
+ * @param items - All measured items
3912
+ * @returns Footer height in pixels, or 0 if no footer items found
3913
+ * @requirements 2.1, 2.2, 2.4 - Extract footer height from measured results
3914
+ */
3915
+ private extractFooterHeight;
3916
+ /**
3917
+ * Extract signature height from measured items
3918
+ * @param items - All measured items
3919
+ * @returns Signature height in pixels, or 0 if no signature items found
3920
+ */
3921
+ private extractSignatureHeight;
3922
+ /**
3923
+ * Filter content items for pagination calculation
3924
+ * Excludes header, footer, and signature items - only keeps section and table items
3925
+ * @param items - All measured items
3926
+ * @returns Array containing only section, table-header, and table-row items
3927
+ * @requirements 4.1, 4.2, 4.3, 4.4 - Filter non-content items from pagination
3928
+ */
3929
+ private filterContentItems;
3930
+ /**
3931
+ * Get page height for pagination calculation
3932
+ * @param _schema - Print schema (unused in current implementation)
3933
+ * @returns Page height in pixels
3934
+ */
3935
+ private getPageHeight;
3936
+ /**
3937
+ * Estimate measurable items when not provided
3938
+ * Creates basic section items for each schema section
3939
+ *
3940
+ * @deprecated Since v1.4.0. Use DomMeasurementStrategy instead.
3941
+ * This method only provides rough estimates and does not measure actual DOM heights.
3942
+ * The method is no longer used internally - SmartPaginationStrategy now uses
3943
+ * MeasurementStrategy (default: DomMeasurementStrategy) for accurate DOM-based measurement.
3944
+ * Will be removed in v2.0.0.
3945
+ *
3946
+ * @see {@link DomMeasurementStrategy} - For accurate DOM-based measurement
3947
+ * @see {@link MeasurementStrategy} - Interface for custom measurement strategies
3948
+ *
3949
+ * @param schema - Print schema
3950
+ * @returns Estimated measurable items (inaccurate)
3951
+ * @requirements 5.1, 5.2, 5.3, 5.4 - Deprecated method with annotations
3952
+ */
3953
+ private estimateItems;
3954
+ }
3955
+
3956
+ /**
3957
+ * @fileoverview Overflow pagination strategy adapter
3958
+ * @module pagination/strategies/overflow/overflow-pagination-strategy
3959
+ * @version 1.0.0
3960
+ * @author Kiro
3961
+ * @created 2026-01-04
3962
+ * @modified 2026-01-04
3963
+ *
3964
+ * @description
3965
+ * Overflow pagination strategy adapter that wraps the existing overflow-handler logic.
3966
+ * Implements the PaginationStrategy interface for long text field pagination.
3967
+ * Delegates to existing processOverflowFields and renderPaginatedHtml functions.
3968
+ *
3969
+ * @requirements
3970
+ * - 3.1: Create OverflowPaginationStrategy in strategies/overflow/
3971
+ * - 3.3: Implement PaginationStrategy interface
3972
+ * - 3.4: Delegate to existing renderPaginatedHtml with overflow config
3973
+ * - 3.5: shouldApply checks pagination.overflow.fields has items
3974
+ *
3975
+ * @dependencies
3976
+ * - ../pagination-strategy - PaginationStrategy interface
3977
+ * - ./overflow-handler - Existing overflow field processing
3978
+ * - ../../paginated-renderer - Paginated HTML renderer
3979
+ * - ../../types - Type definitions
3980
+ *
3981
+ * @usedBy
3982
+ * - ../index.ts - Strategy exports
3983
+ * - ../../paginated-renderer.ts - Main pagination renderer
3984
+ */
3985
+
3986
+ /**
3987
+ * Overflow pagination strategy adapter
3988
+ * Wraps existing overflow field processing logic in strategy interface
3989
+ *
3990
+ * @requirements 3.1, 3.3, 3.4, 3.5 - Overflow pagination strategy implementation
3991
+ *
3992
+ * @example
3993
+ * const strategy = new OverflowPaginationStrategy()
3994
+ * if (strategy.shouldApply(schema)) {
3995
+ * const html = strategy.render(schema, data, options)
3996
+ * }
3997
+ */
3998
+ declare class OverflowPaginationStrategy implements PaginationStrategy {
3999
+ /**
4000
+ * Strategy name identifier
4001
+ * @requirements 3.1 - Strategy name
4002
+ */
4003
+ readonly name = "overflow-pagination";
4004
+ /**
4005
+ * Check if overflow pagination should be applied
4006
+ * @param schema - Print schema with pagination configuration
4007
+ * @returns Whether overflow pagination is configured
4008
+ * @requirements 3.5 - shouldApply checks pagination.overflow.fields has items
4009
+ */
4010
+ shouldApply(schema: PrintSchemaWithPagination): boolean;
4011
+ /**
4012
+ * Render content using overflow pagination
4013
+ * Delegates to existing renderPaginatedHtml with overflow configuration
4014
+ * @param schema - Print schema with pagination configuration
4015
+ * @param data - Form data to render
4016
+ * @param options - Render options
4017
+ * @returns Rendered HTML string
4018
+ * @requirements 3.4 - Delegate to existing renderPaginatedHtml with overflow config
4019
+ */
4020
+ render(schema: PrintSchemaWithPagination, data: FormData, options?: PaginationRenderOptions): string;
4021
+ /**
4022
+ * Create single page result for overflow pagination
4023
+ * Overflow pagination uses a single logical page, with continuation pages handled separately
4024
+ * @returns Single page break result
4025
+ */
4026
+ private createSinglePageResult;
4027
+ /**
4028
+ * Merge overflow text configuration with defaults
4029
+ * @param config - Partial overflow text configuration
4030
+ * @returns Complete overflow text configuration
4031
+ */
4032
+ private mergeOverflowTextConfig;
4033
+ }
4034
+
4035
+ /**
4036
+ * @fileoverview Pagination strategies main exports
4037
+ * @module pagination/strategies
4038
+ * @version 1.0.0
4039
+ * @author Kiro
4040
+ * @created 2026-01-04
4041
+ * @modified 2026-01-04
4042
+ *
4043
+ * @description
4044
+ * Main export file for all pagination strategies and related utilities.
4045
+ * Provides unified access to the strategy pattern implementation.
4046
+ *
4047
+ * @requirements
4048
+ * - 5.3: Export all strategies and context
4049
+ * - 5.3: Export createDefaultPaginationContext factory
4050
+ *
4051
+ * @usedBy
4052
+ * - ../index.ts - Pagination module main export
4053
+ * - ../paginated-renderer.ts - Pagination renderer
4054
+ */
4055
+
4056
+ /**
4057
+ * Create default pagination context with built-in strategies
4058
+ * @returns PaginationContext with SmartPaginationStrategy and OverflowPaginationStrategy
4059
+ * @requirements 5.3 - Export createDefaultPaginationContext factory
4060
+ *
4061
+ * @example
4062
+ * const context = createDefaultPaginationContext()
4063
+ * const html = context.render(schema, data, options)
4064
+ */
4065
+ declare function createDefaultPaginationContext(): PaginationContext;
4066
+
3095
4067
  /**
3096
4068
  * @fileoverview Paginated renderer
3097
4069
  * @module pagination/paginated-renderer
3098
- * @version 1.1.0
4070
+ * @version 1.3.0
3099
4071
  * @author Kiro
3100
4072
  * @created 2026-01-02
3101
- * @modified 2026-01-03
4073
+ * @modified 2026-01-05
3102
4074
  *
3103
4075
  * @description
3104
4076
  * Renders pagination results to multi-page HTML, each page independent and printable.
@@ -3108,6 +4080,7 @@ declare function hasAnyOverflowContent(data: Record<string, unknown>, configs: O
3108
4080
  * - Footer rendering on each page (page number display)
3109
4081
  * - Automatic table header insertion on continuation pages
3110
4082
  * - CSS pagination rules
4083
+ * - Overflow field pagination with i18n support
3111
4084
  *
3112
4085
  * @requirements
3113
4086
  * - 11.1: Render each page as independent .print-page element
@@ -3116,6 +4089,7 @@ declare function hasAnyOverflowContent(data: Record<string, unknown>, configs: O
3116
4089
  * - 11.4: Add "(continued)" marker to continuation page titles
3117
4090
  * - 11.5: Support CSS page-break rules
3118
4091
  * - 11.6: Maintain consistent styles across pages
4092
+ * - 5.1: Support i18n for overflow text
3119
4093
  *
3120
4094
  * @dependencies
3121
4095
  * - ./types.ts - Type definitions
@@ -3154,6 +4128,17 @@ interface PaginatedRenderConfig {
3154
4128
  * @default false
3155
4129
  */
3156
4130
  isolated?: boolean;
4131
+ /**
4132
+ * Overflow text configuration for i18n support
4133
+ * Configures user-visible text for overflow field pagination
4134
+ * @default DEFAULT_OVERFLOW_TEXT (Chinese)
4135
+ *
4136
+ * @example
4137
+ * // Use English text
4138
+ * import { ENGLISH_OVERFLOW_TEXT } from 'medical-form-printer'
4139
+ * config: { overflowText: ENGLISH_OVERFLOW_TEXT }
4140
+ */
4141
+ overflowText?: Partial<OverflowTextConfig>;
3157
4142
  }
3158
4143
  /**
3159
4144
  * Paginated render context
@@ -3180,6 +4165,37 @@ declare const DEFAULT_PAGINATED_RENDER_CONFIG: Required<PaginatedRenderConfig>;
3180
4165
  * Render paginated HTML
3181
4166
  * @requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6
3182
4167
  * @requirements 3.1, 4.2 - CSS isolation and font embedding (isolation mode)
4168
+ * @requirements 2.1, 2.2, 3.1, 3.2 - Overflow field pagination
4169
+ *
4170
+ * @deprecated Since v1.3.0. Will be removed in v2.0.0.
4171
+ * Use the strategy pattern API instead for better maintainability and extensibility.
4172
+ *
4173
+ * @see {@link createDefaultPaginationContext} - Factory for automatic strategy selection
4174
+ * @see {@link SmartPaginationStrategy} - Table-based smart pagination
4175
+ * @see {@link OverflowPaginationStrategy} - Long text field overflow handling
4176
+ *
4177
+ * @migration
4178
+ * ```typescript
4179
+ * // ❌ Before (deprecated)
4180
+ * import { renderPaginatedHtml, calculatePageBreaks } from 'medical-print-renderer'
4181
+ * const pageBreakResult = calculatePageBreaks(items, options)
4182
+ * const html = renderPaginatedHtml({
4183
+ * schema, data, pageBreakResult, measuredItems: items,
4184
+ * config: { isolated: true }
4185
+ * })
4186
+ *
4187
+ * // ✅ After (recommended) - Option 1: Automatic strategy selection
4188
+ * import { createDefaultPaginationContext } from 'medical-print-renderer'
4189
+ * const context = createDefaultPaginationContext()
4190
+ * const html = context.render(schema, data, { isolated: true })
4191
+ *
4192
+ * // ✅ After (recommended) - Option 2: Direct strategy usage
4193
+ * import { SmartPaginationStrategy } from 'medical-print-renderer'
4194
+ * const strategy = new SmartPaginationStrategy()
4195
+ * if (strategy.shouldApply(schema)) {
4196
+ * const html = strategy.render(schema, data, { isolated: true })
4197
+ * }
4198
+ * ```
3183
4199
  *
3184
4200
  * @param context - Paginated render context
3185
4201
  * @returns Complete paginated HTML string
@@ -3203,17 +4219,45 @@ declare const DEFAULT_PAGINATED_RENDER_CONFIG: Required<PaginatedRenderConfig>;
3203
4219
  * measuredItems: items,
3204
4220
  * config: { isolated: true }
3205
4221
  * })
4222
+ *
4223
+ * @example
4224
+ * // With overflow field pagination (Chinese text)
4225
+ * const html = renderPaginatedHtml({
4226
+ * schema: printSchemaWithOverflow,
4227
+ * data: formDataWithLongText,
4228
+ * pageBreakResult: result,
4229
+ * measuredItems: items,
4230
+ * })
4231
+ *
4232
+ * @example
4233
+ * // With overflow field pagination (English text)
4234
+ * import { ENGLISH_OVERFLOW_TEXT } from 'medical-form-printer'
4235
+ * const html = renderPaginatedHtml({
4236
+ * schema: printSchemaWithOverflow,
4237
+ * data: formDataWithLongText,
4238
+ * pageBreakResult: result,
4239
+ * measuredItems: items,
4240
+ * config: { overflowText: ENGLISH_OVERFLOW_TEXT }
4241
+ * })
3206
4242
  */
3207
4243
  declare function renderPaginatedHtml(context: PaginatedRenderContext): string;
3208
4244
  /**
3209
4245
  * Generate pagination-related CSS rules
3210
4246
  * @requirements 11.5, 11.6 - CSS page-break rules
4247
+ * @requirements 5.1, 5.2, 5.3, 5.4 - Overflow field CSS styles
3211
4248
  * @param isolated - Whether to enable isolation mode (class names have mpr- prefix)
3212
4249
  */
3213
4250
  declare function generatePaginationCss(isolated?: boolean): string;
3214
4251
  /**
3215
4252
  * Simplified paginated render function
3216
4253
  * For scenarios where pagination result is already available
4254
+ *
4255
+ * @deprecated Use the strategy pattern API instead:
4256
+ * ```typescript
4257
+ * import { createDefaultPaginationContext } from 'medical-print-renderer'
4258
+ * const context = createDefaultPaginationContext()
4259
+ * const html = context.render(schema, data, { isolated: true })
4260
+ * ```
3217
4261
  */
3218
4262
  declare function renderPaginatedHtmlSimple(schema: PrintSchema, data: FormData, pageBreakResult: PageBreakResult, measuredItems: MeasurableItem[], options?: RenderOptions, config?: PaginatedRenderConfig): string;
3219
4263
  /**
@@ -3224,10 +4268,10 @@ declare function createRenderConfigFromPaginationConfig(paginationConfig?: Pagin
3224
4268
  /**
3225
4269
  * @fileoverview Pagination module entry point
3226
4270
  * @module pagination
3227
- * @version 1.0.0
4271
+ * @version 1.1.0
3228
4272
  * @author Kiro
3229
4273
  * @created 2026-01-03
3230
- * @modified 2026-01-03
4274
+ * @modified 2026-01-04
3231
4275
  *
3232
4276
  * @description
3233
4277
  * Exports all pagination-related types and functions:
@@ -3235,9 +4279,11 @@ declare function createRenderConfigFromPaginationConfig(paginationConfig?: Pagin
3235
4279
  * - Page size configuration
3236
4280
  * - Pagination algorithm
3237
4281
  * - Overflow field handling
4282
+ * - Strategy pattern interface and context
3238
4283
  *
3239
4284
  * @requirements
3240
4285
  * - 9.1: Calculate page breaks based on measured content height
4286
+ * - 1.5: Export strategy interface and context
3241
4287
  *
3242
4288
  * @usedBy
3243
4289
  * - ../index.ts - Library main entry
@@ -3248,12 +4294,26 @@ declare function createRenderConfigFromPaginationConfig(paginationConfig?: Pagin
3248
4294
  * Print pagination utility function collection
3249
4295
  * Provides Vue Composable-like API style
3250
4296
  *
3251
- * @param dimensions - Page size configuration, default 16K
3252
- * @returns Pagination utility functions
4297
+ * @deprecated Since v1.3.0. Will be removed in v2.0.0.
4298
+ * Use the strategy pattern API instead for better maintainability.
3253
4299
  *
3254
- * @example
4300
+ * @see {@link createDefaultPaginationContext} - Recommended replacement
4301
+ * @see {@link SmartPaginationStrategy} - For table-based pagination
4302
+ *
4303
+ * @migration
4304
+ * ```typescript
4305
+ * // ❌ Before (deprecated)
3255
4306
  * const { calculateBreaks, usableHeight } = usePrintPagination()
3256
4307
  * const result = calculateBreaks(measuredItems, usableHeight)
4308
+ *
4309
+ * // ✅ After (recommended)
4310
+ * import { createDefaultPaginationContext } from 'medical-print-renderer'
4311
+ * const context = createDefaultPaginationContext()
4312
+ * const html = context.render(schema, data, { isolated: true })
4313
+ * ```
4314
+ *
4315
+ * @param dimensions - Page size configuration, default 16K
4316
+ * @returns Pagination utility functions
3257
4317
  */
3258
4318
  declare function usePrintPagination(dimensions?: PageDimensions): {
3259
4319
  /** Page size configuration */
@@ -3270,4 +4330,4 @@ declare function usePrintPagination(dimensions?: PageDimensions): {
3270
4330
  pxToMm: typeof pxToMm;
3271
4331
  };
3272
4332
 
3273
- export { AbstractPageRenderer, CSS_NAMESPACE, type CellType, type CheckboxGridConfig, type CheckboxOption, type ColorConfig, type ColumnConfig, ContainerSection, DEFAULT_BASE_UNIT, DEFAULT_DPI, DEFAULT_PAGINATED_RENDER_CONFIG, type DateFormatOptions, FONT_FAMILY, FONT_STYLE, FONT_WEIGHT, type FieldInfo, type FontConfig, FontLoadError, type FontLoadOptions, type FontSizeConfig, type FooterConfig, type FormData, FormDataTraverser, type FormDataVisitor, FormatVisitor, type Formatter, type FormatterConfig, FormatterFactory, type FreeTextConfig, type HeaderConfig, HtmlBuilder, HtmlElementBuilder, ISOLATION_ROOT_CLASS, type InfoGridCell, type InfoGridConfig, type InfoGridRow, type InlineStyleMap, type IsolatedRenderOptions, LeafSection, MM_PER_INCH, type MeasurableItem, type MeasurableItemType, type MeasureResult, MeasureVisitor, type MergeDocumentItem, type MergeOptions, type NotesConfig, type OverflowFieldConfig, type OverflowFieldResult, PAGE_16K, PAGE_A4, PAGE_A5, PAGE_PRESETS, type PageBreakOptions, type PageBreakResult, PageBuilder, type PageConfig, type PageContent, type PageDimensions, type PageFooterConfig, type PageHeaderConfig, type PageOrientation, type PageRenderContext, type PageSize, PaginatedPageRenderer, type PaginatedRenderConfig, type PaginatedRenderContext, type PaginationConfig, type PdfOptions, type PrintFooter, type PrintHeader, type PrintSchema, type PrintSection, type RenderOptions, type RendererCreator, SIZE_MULTIPLIERS, type ScaledThemeConfig, type SectionComponent, type SectionConfig, type SectionRenderStrategy, type SectionRenderer, SectionRendererFactory, SectionTreeTraverser, type SectionType, type SignatureConfig, type SignatureField, SinglePageRenderer, type SizeMultipliers, type SmartPaginationConfig, type SpacingConfig, StrategyContext, type StyleObject, TableBuilder, type TableColumn, type TableConfig$1 as TableConfig, type Theme, UNIT_CONVERSIONS, type Unit, type ValidationResult, ValidationVisitor, type WatermarkOptions, buildTableHeaderMap, calculatePageBreaks, calculatePageBreaksSimple, calculateUsableHeight, calculateUsableHeightMm, calculateUsableWidth, calculateUsableWidthMm, clamp, convertFromMm, convertToMm, createDefaultStrategyContext, createFormDataTraverser, createFormatVisitor, createInlineStyles, createMeasureVisitor, createOverflowFieldConfig, createOverflowFieldConfigs, createPageDimensions, createPaginatedPageRenderer, createRenderConfigFromPaginationConfig, createScaledTheme, createSectionComponent, createSectionTree, createSinglePageRenderer, createThemeWithBaseUnit, createValidationVisitor, defaultColors, defaultFonts, defaultInlineStyles, defaultMultipliers, defaultScaledConfig, defaultTheme, div, each, escapeAttr, escapeHtml, extractWatermarkOptions, findTableHeader, footer, formatBoolean, formatDate, formatNumber, formatPadding, formatSize, formatValue, fragment, generateCss, generateIsolatedCss, generatePaginationCss, getDefaultFormatterFactory, getDefaultSectionRendererFactory, getFontCss, getFontDataUrl, getNamespacedClass, getOverflowFieldConfig, getOverflowFirstLine, getOverflowRest, getPageContentHeight, getPageDimensions, getPageStyles, getSectionRenderer, h, h1, hasAnyOverflowContent, hasOverflowContent, header, isChecked, isFontLoaded, isOverflowField, main, mergeStyles, mergeTheme, mmToPt, mmToPx, namespaceClass, namespaceClasses, normalizeOpacity, p, processOverflowFields, ptToMm, pxToMm, registerSectionRenderer, renderPaginatedHtml, renderPaginatedHtmlSimple, renderSectionTree, renderToHtml, renderToIsolatedFragment, renderToIsolatedHtml, renderWatermarkHtml, scaleValue, span, styleToString, table, tbody, td, th, thead, tr, usePrintPagination, validatePageBreakResult, waitForFonts, when };
4333
+ export { AbstractPageRenderer, CSS_NAMESPACE, type CellType, type CheckboxGridConfig, type CheckboxOption, type ColorConfig, type ColumnConfig, ContainerSection, DEFAULT_BASE_UNIT, DEFAULT_DPI, DEFAULT_OVERFLOW_TEXT, DEFAULT_PAGINATED_RENDER_CONFIG, type DateFormatOptions, ENGLISH_OVERFLOW_TEXT, FONT_FAMILY, FONT_STYLE, FONT_WEIGHT, type FieldInfo, type FontConfig, FontLoadError, type FontLoadOptions, type FontSizeConfig, type FooterConfig, type FormData, FormDataTraverser, type FormDataVisitor, FormatVisitor, type Formatter, type FormatterConfig, FormatterFactory, type FreeTextConfig, type HeaderConfig, HtmlBuilder, HtmlElementBuilder, ISOLATION_ROOT_CLASS, type InfoGridCell, type InfoGridConfig, type InfoGridRow, type InlineStyleMap, type IsolatedRenderOptions, LeafSection, MEASURABLE_ITEM_TYPES, MM_PER_INCH, type MeasurableItem, type MeasurableItemType, type MeasureResult, MeasureVisitor, type MergeDocumentItem, type MergeOptions, type NotesConfig, OVERFLOW_CSS_CLASSES, type OverflowContinuationPageContext, type OverflowFieldConfig, type OverflowFieldResult, OverflowPaginationStrategy, type OverflowRenderContext, type OverflowTextConfig, PAGE_16K, PAGE_A4, PAGE_A5, PAGE_PRESETS, PAGINATION_DEFAULTS, type PageBreakOptions, type PageBreakResult, PageBuilder, type PageConfig, type PageContent, type PageDimensions, type PageFooterConfig, type PageHeaderConfig, type PageOrientation, type PageRenderContext, type PageSize, PaginatedPageRenderer, type PaginatedRenderConfig, type PaginatedRenderContext, type PaginationConfig, PaginationContext, type PaginationRenderOptions, type PaginationStrategy, type PdfOptions, type PrintFooter, type PrintHeader, type PrintSchema, type PrintSchemaWithPagination, type PrintSection, type RenderOptions, type RendererCreator, SIZE_MULTIPLIERS, type ScaledThemeConfig, type SectionComponent, type SectionConfig, type SectionRenderStrategy, type SectionRenderer, SectionRendererFactory, SectionTreeTraverser, type SectionType, type SignatureConfig, type SignatureField, SinglePageRenderer, type SizeMultipliers, type SmartPaginationConfig, SmartPaginationStrategy, type SpacingConfig, StrategyContext, type StyleObject, TableBuilder, type TableColumn, type TableConfig$1 as TableConfig, type Theme, UNIT_CONVERSIONS, type Unit, type ValidationResult, ValidationVisitor, type WatermarkOptions, buildTableHeaderMap, calculatePageBreaks, calculatePageBreaksSimple, calculateUsableHeight, calculateUsableHeightMm, calculateUsableWidth, calculateUsableWidthMm, clamp, convertFromMm, convertToMm, createDefaultPaginationContext, createDefaultStrategyContext, createFormDataTraverser, createFormatVisitor, createInlineStyles, createMeasureVisitor, createOverflowFieldConfig, createOverflowFieldConfigs, createPageDimensions, createPaginatedPageRenderer, createRenderConfigFromPaginationConfig, createScaledTheme, createSectionComponent, createSectionTree, createSinglePageRenderer, createThemeWithBaseUnit, createValidationVisitor, defaultColors, defaultFonts, defaultInlineStyles, defaultMultipliers, defaultScaledConfig, defaultTheme, div, each, escapeAttr, escapeHtml, extractWatermarkOptions, findOverflowFieldCell, findOverflowFieldLabel, findTableHeader, footer, formatBoolean, formatDate, formatNumber, formatPadding, formatSize, formatValue, fragment, generateCss, generateIsolatedCss, generatePaginationCss, getDefaultFormatterFactory, getDefaultSectionRendererFactory, getFontCss, getFontDataUrl, getNamespacedClass, getOverflowFieldConfig, getOverflowFieldNames, getOverflowFieldsFromConfig, getOverflowFirstLine, getOverflowRest, getPageContentHeight, getPageDimensions, getPageStyles, getSectionRenderer, h, h1, hasAnyContinuationContent, hasAnyOverflowContent, hasOverflowContent, header, isChecked, isFontLoaded, isOverflowField, isOverflowSection, main, mergeOverflowTextConfig, mergeStyles, mergeTheme, mmToPt, mmToPx, namespaceClass, namespaceClasses, normalizeOpacity, p, processOverflowFields, ptToMm, pxToMm, registerSectionRenderer, renderOverflowContinuation, renderOverflowContinuationPage, renderOverflowFirstLine, renderPaginatedHtml, renderPaginatedHtmlSimple, renderSectionTree, renderToHtml, renderToIsolatedFragment, renderToIsolatedHtml, renderWatermarkHtml, scaleValue, span, styleToString, table, tbody, td, th, thead, tr, usePrintPagination, validatePageBreakResult, waitForFonts, when };