idml 0.10.2 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40262a683342f0a9308e33ab2cce4a8bcf6b803288d6a0bc3ece3d2b376c6761
-  data.tar.gz: 78cb5495d1d9b72d5e850c6d25c8cd594622d6484476ea61a1ff239df41e9e99
+  metadata.gz: 79a78b04b80af7bc0018d4fde7500d164d8bc8b587a425c2fba89c5be19a7bb8
+  data.tar.gz: 0b835730671e71723e043372530b1fbb6765029c50da2025315408dd2caf4fa7
 SHA512:
-  metadata.gz: b10228f8870d90e1a66f8fb9b621a26951db4a71e155a3f28165c22a3e9c44b53e7dbc17916ec4b5db0f49987403e4e645e5f0872a79cb0fe591881ff6f9caca
-  data.tar.gz: d4904d3ef2a6d0b1c4dfcd497597042fcedee1b5c3c1643ff892ac867e7b4c3f0881419a906527e5f1705a64292c8c5c5e06ae8af774b8ce725f81c8bcf9ff92
+  metadata.gz: 3f79b3ee1dbe8a3d5cb01346f55935196e10d21ca3cd7d477132aaedafc200df0880179b568b8c071d5dbce62e77b2fe6275fdedb1a6d8fbbeb868f61b16a70f
+  data.tar.gz: 5d556bd0f53b5817051dd5ae419fab76c4e91534e3ff0f1415ff5e22fc10949743f2e6fb5992d0c2a669ea5e8aa4e3e2c20ebac7ddfe8ae991495267cd5a2671

data/TODO.pdf/133-keep-windows.md

@@ -0,0 +1,22 @@
+# TODO PDF 133: Partial keep windows (KeepFirstLines / KeepLastLines)
+
+## Status: COMPLETE — implemented 2026-08-24
+
+## What was done
+
+- `StyleResolver::Paragraph` carries `keep_first_lines` /
+  `keep_last_lines` from the PSR.
+- `consume_paragraphs` defers the whole paragraph when it cannot
+  fully fit AND either window binds, approximated by measured line
+  counts (TextEngine::Measurement height ÷ leading):
+  - KeepFirstLines=N defers when fewer than N lines fit the
+    remaining space.
+  - KeepLastLines=N defers when the overflow tail for the next
+    frame would strand fewer than N lines.
+
+## Known limitations
+
+- Line counts are estimates (pre-measured shape/wrap); runs whose
+  mid-paragraph wrap differs from the estimate may defer one line
+  early or late.
+- Not applied in vertical writing mode.

data/TODO.pdf/134-table-row-flow.md

@@ -0,0 +1,45 @@
+# TODO PDF 134: Table row flow across chained frames (design)
+
+## Status: COMPLETE — implemented 2026-08-24
+
+## Problem
+
+Tables render within a single frame box (TableRenderer#
+render_in_box). A table taller than its frame overflows invisibly;
+continuation frames do not receive the remaining rows, and header
+rows never repeat (HeaderRowCount).
+
+## Design
+
+1. `TableRenderer.render_schema_faithful` gains `start_row:` and a
+   frame-bottom clip: rows render while the row's bottom edge
+   stays above the limit; the first row crossing it stops the walk
+   and the renderer returns `next_start_row` (nil when the table
+   completed).
+2. Header repeat: for continuation calls (start_row > 0) with
+   HeaderRowCount > 0, re-emit header rows at the top of the
+   continuation area and reduce its available height accordingly.
+3. State threading: `StoryChainController::State` gains
+   `tables_remaining` — an array of [table, start_row] pairs.
+   `render_inline_tables` consumes the chain head's story tables
+   plus any carried-over remainders, appending unfinished pairs
+   back for the next frame.
+4. Footer rows (FooterRowCount) stay with the table's final chunk.
+
+## Implementation notes (2026-08-24)
+
+Delivered per the design above: `render_in_box` takes `start_row:`
+and `bottom_limit:`, renders whole rows while their bottom edge
+stays above the limit, re-emits HeaderRowCount header rows on
+continuations, and returns the next unrendered row (nil when
+complete). `StoryChainController::State` carries `tables_remaining`
+([table, start_row] pairs); `render_inline_tables` renders fresh
+story tables on chain heads plus carried remainders, storing
+unfinished tables back for the next frame. `fresh_state` now keeps
+table-only stories alive (previously a story with no paragraphs
+produced a nil state and its tables never rendered).
+
+Known limitations: row-spanning cells break at frame boundaries
+(a span cell crossing the limit renders at its start frame only);
+footer rows render with their chunk (no forced keep-with-end);
+multi-column frames flow tables across the full box width.

data/TODO.pdf/61-known-limitations.md

@@ -15,9 +15,9 @@ this list reflects the current state.
   MaximumGlyphScaling stretches as the last resort (TODO 129);
   MinimumGlyphScaling compression and ToBinding / RTL binding
   alignment are not applied.
-- **Keep options**: whole-paragraph KeepAllLinesTogether (TODO
-  123) and KeepWithNext (TODO 127) are honored; partial keep
-  windows (KeepFirstLines / KeepLastLines) are not.
+- **Keep options**: KeepAllLinesTogether (TODO 123), KeepWithNext
+  (TODO 127), and the KeepFirstLines / KeepLastLines windows
+  (TODO 133, line-count approximation) are honored.
 - **First baseline**: AscentOffset and FixedHeight are honored
   (TODO 128); CapHeight / XHeight approximate as leading.
 - **StartParagraph** breaks act at frame/column granularity — no
@@ -42,8 +42,9 @@ this list reflects the current state.
   footnote text.
 - **Anchored objects** render at stored geometry; AnchorType
   text-reflow is not simulated.
-- **Tables** do not span frames (no repeated header rows); diagonal
-  cell strokes are modeled but not drawn.
+- **Tables** flow across chained frames with repeated header rows
+  (TODO 134); row-spanning cells break at frame boundaries and
+  diagonal cell strokes are modeled but not drawn.
 - **Inline anchored objects / footnotes inside table cells** are
   not handled.
 

data/lib/idml/render/renderers/table_renderer.rb

@@ -48,16 +48,30 @@ module Idml
         # render Tables inlined in a story — real IDML Tables
         # have no own geometry, so the containing TextFrame's
         # bounds stand in for the Table's bounds.
-        def self.render_in_box(canvas, table, box, context)
+        # Renders the table within `box`. When `bottom_limit` is
+        # given, rows stop at the limit and the next unrendered row
+        # index is returned (nil when the table completed) — the
+        # caller threads it into the next frame of the chain via
+        # `start_row`, which also re-emits HeaderRowCount header
+        # rows above the continuation.
+        def self.render_in_box(canvas, table, box, context, start_row: 0,
+                                                     bottom_limit: nil)
           return if table.visible == false
+          return nil if schema_faithful?(table) &&
+            start_row >= table.row.length
 
+          next_row = nil
           canvas.save_graphics_state do
-            if schema_faithful?(table)
-              render_schema_faithful(canvas, table, box, context)
-            else
-              render_legacy(canvas, table, box, context)
-            end
-          end
+            next_row = if schema_faithful?(table)
+                         render_schema_faithful(canvas, table, box, context,
+                                                start_row: start_row,
+                                                bottom_limit: bottom_limit)
+                       else
+                         render_legacy(canvas, table, box, context)
+                         nil
+                       end
+          end
+          next_row
         end
 
         def self.schema_faithful?(table)
@@ -68,20 +82,70 @@ module Idml
         # Real IDML: Table > {Cell, Row} siblings. Cell Name is
         # "col:row". Row count from `row` collection; column count
         # derived from `column_count` attribute or max col + 1.
-        def self.render_schema_faithful(canvas, table, box, context)
+        def self.render_schema_faithful(canvas, table, box, context,
+                                        start_row: 0, bottom_limit: nil)
           layout = SchemaLayout.new(table: table, box: box)
-          layout.each_cell do |cell_x, cell_y, cell_w, cell_h, cell,
-                               col_idx, row_idx|
+          rendered, next_row = visible_row_range(
+            layout, table, start_row, bottom_limit
+          )
+          rendered.each do |row_idx|
+            render_row(canvas, table, layout, box, row_idx, context)
+          end
+          next_row
+        end
+        private_class_method :render_schema_faithful
+
+        def self.render_row(canvas, table, layout, _box, row_idx, context)
+          layout.each_cell_in_row(row_idx) do |cell_x, cell_y, cell_w,
+                                              cell_h, cell, col_idx|
             render_band_background(canvas, cell, layout, col_idx, row_idx,
                                    cell_x, cell_y, cell_w, cell_h, context)
-            render_cell_background(canvas, cell, cell_x, cell_y, cell_w, cell_h,
-                                   context)
+            render_cell_background(canvas, cell, cell_x, cell_y, cell_w,
+                                   cell_h, context)
             render_cell_border(canvas, cell, table, cell_x, cell_y,
                                cell_w, cell_h, context)
             render_cell_text(canvas, cell, cell_x, cell_y, cell_h, context)
           end
         end
-        private_class_method :render_schema_faithful
+        private_class_method :render_row
+
+        # [rows_to_render, next_unrendered_row]: header rows
+        # re-emit on continuations (start_row > 0) with
+        # HeaderRowCount; body rows run from start_row until the
+        # frame bottom limit clips one.
+        def self.visible_row_range(layout, table, start_row, bottom_limit)
+          rows = continuation_header_rows(table, start_row) +
+            body_rows_within(layout, table, start_row, bottom_limit)
+          [rows, next_unrendered(layout, table, start_row, bottom_limit)]
+        end
+        private_class_method :visible_row_range
+
+        def self.continuation_header_rows(table, start_row)
+          return [] if start_row.zero?
+
+          (table.header_row_count || 0).times.to_a
+        end
+        private_class_method :continuation_header_rows
+
+        def self.body_rows_within(layout, table, start_row, bottom_limit)
+          body_rows = (start_row...table.row.length).to_a
+          return body_rows if bottom_limit.nil?
+
+          body_rows.take_while do |row_idx|
+            layout.row_bottom_y(row_idx) >= bottom_limit
+          end
+        end
+        private_class_method :body_rows_within
+
+        def self.next_unrendered(layout, table, start_row, bottom_limit)
+          last = start_row + body_rows_within(
+            layout, table, start_row, bottom_limit
+          ).length - 1
+          return nil if last >= table.row.length - 1
+
+          last + 1
+        end
+        private_class_method :next_unrendered
 
         # Table-level alternating band fill behind a cell. An
         # explicit Cell FillColor wins; Color/None bands and zero
@@ -384,6 +448,27 @@ module Idml
             table.row
           end
 
+          # Cells whose START row is `row` (cells spanning from an
+          # earlier row render there, not here).
+          def each_cell_in_row(row)
+            col_count.times do |col_idx|
+              cell = cell_at(col_idx, row)
+              next unless cell
+              next unless cell.col_row.nil? || cell.col_row.last == row
+
+              col_span = cell.column_span || 1
+              row_span = cell.row_span || 1
+              yield cell_x(col_idx), cell_y(row, col_span, row_span),
+                    cell_w(col_idx, col_span), cell_h(row, row_span),
+                    cell, col_idx
+            end
+          end
+
+          # The bottom y of a row's band (PDF coords).
+          def row_bottom_y(row)
+            box[:y] + total_height - cumulative_height(row + 1)
+          end
+
           # Table-level alternating band fill for a cell position:
           # [color_name, tint] or nil. Row banding by default; column
           # banding when ColumnFillsPriority is true or rows are

data/lib/idml/render/renderers/text_frame_renderer.rb

@@ -35,10 +35,10 @@ module Idml
           return unless story
 
           box = frame_box(frame, context.page_height)
-          render_inline_tables(canvas, story, box, context)
+          state = initial_chain_state(frame, story, context)
+          render_inline_tables(canvas, story, box, context, state)
           render_anchored_objects(canvas, story, context)
 
-          state = initial_chain_state(frame, story, context)
           return unless state
 
           vertical = vertical_story?(story)
@@ -77,13 +77,15 @@ module Idml
                    style_lookup: context.style_lookup,
                    footnote_option: Footnote.option(context.package)
           )
-          return nil if paragraphs.empty?
+          tables = tables_in_story(story).map { |table| [table, 0] }
+          return nil if paragraphs.empty? && tables.empty?
 
           StoryChainController::State.new(
             paragraphs: paragraphs,
             current_paragraph: nil,
             runs_remaining: [],
             char_cursor: 0,
+            tables_remaining: tables,
           )
         end
         private_class_method :fresh_state
@@ -94,12 +96,20 @@ module Idml
         # so the containing TextFrame's box stands in. Synthetic
         # spread-level Tables dispatch separately via
         # PageItemRenderer.
-        def self.render_inline_tables(canvas, story, box, context)
-          tables = tables_in_story(story)
-          return if tables.empty?
-
-          tables.each do |table|
-            TableRenderer.render_in_box(canvas, table, box, context)
+        # Renders the story's inline tables — fresh ones for a
+        # chain head, carried-over remainders for continuation
+        # frames — clipped to the frame bottom; unfinished tables
+        # stay in the chain state for the next frame (TODO 134).
+        def self.render_inline_tables(canvas, _story, box, context, state)
+          pairs = state ? state.tables_remaining.to_a : []
+          return if pairs.empty?
+
+          state.tables_remaining = pairs.filter_map do |table, start_row|
+            next_row = TableRenderer.render_in_box(
+              canvas, table, box, context,
+              start_row: start_row, bottom_limit: box[:y]
+            )
+            next_row ? [table, next_row] : nil
           end
         end
         private_class_method :render_inline_tables
@@ -1029,6 +1039,8 @@ module Idml
                                                cursor_y, bottom_limit)
 
           keep_all_lines_break?(paragraph, layout_frame, font,
+                                cursor_y, bottom_limit) ||
+            keep_windows_break?(paragraph, layout_frame, font,
                                 cursor_y, bottom_limit)
         end
         private_class_method :paragraph_deferred?
@@ -1049,6 +1061,52 @@ module Idml
         end
         private_class_method :keep_all_lines_break?
 
+        # Partial keep windows, approximated by measured line
+        # counts: KeepFirstLines defers when fewer than N lines
+        # fit; KeepLastLines defers when the overflow tail for the
+        # next frame would strand fewer than N lines.
+        def self.keep_windows_break?(paragraph, layout_frame, font,
+                                     cursor_y, bottom_limit)
+          return false unless paragraph.keep_first_lines ||
+            paragraph.keep_last_lines
+
+          wrap_width = TextEngine::VerticalLayout.wrap_width(
+            layout_frame, paragraph.right_indent || 0
+          )
+          height = TextEngine::Measurement.paragraph_height(
+            paragraph, font, wrap_width
+          )
+          return false if (cursor_y - height) >= bottom_limit
+
+          leading = first_paragraph_leading_for(paragraph)
+          lines_fit = [((cursor_y - bottom_limit) / leading).floor, 0].max
+          first_window_break?(paragraph, lines_fit) ||
+            last_window_break?(paragraph, lines_fit, height, leading)
+        end
+        private_class_method :keep_windows_break?
+
+        def self.first_window_break?(paragraph, lines_fit)
+          paragraph.keep_first_lines &&
+            lines_fit < paragraph.keep_first_lines
+        end
+        private_class_method :first_window_break?
+
+        def self.last_window_break?(paragraph, lines_fit, height, leading)
+          return false unless paragraph.keep_last_lines
+
+          total_lines = [(height / leading).ceil, 1].max
+          lines_fit.positive? &&
+            (total_lines - lines_fit) < paragraph.keep_last_lines
+        end
+        private_class_method :last_window_break?
+
+        def self.first_paragraph_leading_for(paragraph)
+          size = paragraph.runs.first&.point_size || DEFAULT_SIZE
+          TextEngine::VerticalLayout.leading_for(paragraph.auto_leading,
+                                                 size)
+        end
+        private_class_method :first_paragraph_leading_for
+
         # KeepWithNext: this paragraph defers when the next
         # paragraph is forced to the next frame, or when the next
         # paragraph's first line would not fit after this one.

data/lib/idml/render/story_chain_controller.rb

@@ -28,6 +28,9 @@ module Idml
         # Vertical-writing path: columns already consumed when the
         # paragraph chain continues into the next frame.
         :column_offset,
+        # Frame-spanning tables: [table, start_row] pairs still to
+        # render (TODO 134).
+        :tables_remaining,
         keyword_init: true,
       )
 

data/lib/idml/render/style_resolver.rb

@@ -75,9 +75,12 @@ module Idml
         # Widow/orphan control: KeepAllLinesTogether pushes the whole
         # paragraph to the next frame when it cannot fully fit;
         # KeepWithNext binds this paragraph to the next paragraph's
-        # first line.
+        # first line; KeepFirstLines / KeepLastLines are partial
+        # keep windows (approximated via measured line counts).
         :keep_all_lines_together,
         :keep_with_next,
+        :keep_first_lines,
+        :keep_last_lines,
         :bullets_and_numbering_list_type,
         :bullet_character_value,
         :bullets_text_after,
@@ -216,6 +219,10 @@ module Idml
             ),
             keep_with_next: resolve_attr(style_lookup, psr,
                                          :keep_with_next),
+            keep_first_lines: resolve_attr(style_lookup, psr,
+                                           :keep_first_lines),
+            keep_last_lines: resolve_attr(style_lookup, psr,
+                                          :keep_last_lines),
             drop_cap_lines: resolve_attr(style_lookup, psr, :drop_cap_lines),
             drop_cap_characters: resolve_attr(style_lookup, psr,
                                               :drop_cap_characters),

data/lib/idml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Idml
-  VERSION = "0.10.2"
+  VERSION = "0.10.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.10.3
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-23 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -192,6 +192,8 @@ files:
 - TODO.pdf/130-contour-text-wrap.md
 - TODO.pdf/131-inverse-wrap.md
 - TODO.pdf/132-line-end-compression.md
+- TODO.pdf/133-keep-windows.md
+- TODO.pdf/134-table-row-flow.md
 - TODO.pdf/14-page-item-element-models.md
 - TODO.pdf/15-wire-spread-children.md
 - TODO.pdf/16-typed-model-pipeline.md