idml 0.6.1 → 0.7.0

data/TODO.pdf/99-table-column-widths.md

@@ -0,0 +1,44 @@
+# TODO PDF 99: Table column widths from ColumnAttributes
+
+## Status: DONE — Table now models `column_count` and
+`single_column_width`; SchemaLayout uses SingleColumnWidth when
+declared, else falls back to even division. (IDML has no separate
+ColumnAttributes element — column widths live on Table directly
+when uniform.)
+
+## Problem
+
+`TableRenderer::SchemaLayout#cell_w` divides the table width evenly
+across all columns:
+
+```ruby
+def cell_w
+  box[:width] / [col_count, 1].max
+end
+```
+
+Real IDML documents declare per-column widths via the
+`ColumnAttributes` child of `Table` (with `SingleColumnWidth`
+attributes). The renderer ignores these, producing visually wrong
+tables whenever columns aren't equal-width.
+
+## What needs to happen
+
+1. Verify `Elements::Table` exposes the `column_attributes`
+   collection (add it if missing).
+2. `SchemaLayout` reads each `ColumnAttributes#single_column_width`
+   and computes a cumulative column-x table.
+3. `cell_x(col)` looks up the cumulative position; `cell_w(col)`
+   uses the actual width for that column.
+4. Falls back to even division when `ColumnAttributes` is absent.
+
+## Acceptance criteria
+
+- [ ] Table with two columns, widths 100pt and 200pt, renders cells
+      at the correct x positions and widths.
+- [ ] Table without ColumnAttributes renders as today (even division).
+- [ ] Spanning cells (ColumnSpan) cover the correct cumulative width.
+
+## Dependencies
+
+- TODO 98 (spans interact with column widths).

data/TODO.pdf/README.md

@@ -5,17 +5,14 @@ without InDesign Server. The pipeline has three layers:
 
 1. **Text engine** (TODOs 01–05): a pure-Ruby text layout engine
    that takes styled text runs + frame geometry and produces
-   positioned glyphs. Uses font metrics from .ttf/.otf files.
-
+   positioned glyphs. Uses font metrics via pdfrb's typed Fonts API.
 2. **PDF content stream** (TODOs 06–10): maps IDML page items
-   (shapes, text, colors, images) to PDF content-stream operators
-   using pdfrb's Document/Canvas API.
-
+   (shapes, text, colors, images) to pdfrb's Canvas API.
 3. **Pipeline** (TODOs 11–13): ties the text engine and PDF
    output together. IDML Package → typed model → render plan →
    pdfrb Document → PDF file.
 
-The text engine is intentionally IDML-agnostic: it works on
-styled text runs and frame geometry, not IDML-specific types.
-This makes it reusable (e.g., for generating PDFs from scratch
-or from other layout formats).
+All entries below are functionally DONE (basic CJK in TODO 13 is
+the only PARTIAL — vertical writing mode, kinsoku, ruby, and
+tate-chu-yoko remain stretch goals). Each file carries a
+`## Status:` header with a brief implementation summary.

data/idml.gemspec

@@ -29,8 +29,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "bigdecimal"
+  spec.add_dependency "logger"
   spec.add_dependency "lutaml-model", "~> 0.8.18"
-  spec.add_dependency "pdfrb"
+  spec.add_dependency "pdfrb", "~> 0.7"
   spec.add_dependency "rubyzip"
   spec.add_dependency "thor"
 

data/lib/idml/elements/table.rb

@@ -2,10 +2,16 @@
 
 module Idml
   module Elements
-    # `<Table>` — a table page item. Carries geometry attributes and a
-    # collection of TableRow children. The table's width and height are
-    # typically derived from PathPointArray anchors, but rendered here
-    # using the ItemTransform + a bounding-box approximation.
+    # `<Table>` — a table page item. Carries geometry, body/header
+    # row counts, column layout, and border styling. Two child
+    # collections hold the table's content:
+    #
+    # - `row` — schema-faithful `<Row>` siblings (real IDML).
+    # - `cell` — schema-faithful `<Cell>` siblings (real IDML).
+    # - `table_row` — legacy nested `<TableRow><TableCell>` form
+    #   (synthetic test fixture only; see TODO 84).
+    #
+    # The renderer auto-detects which layout is present.
     class Table < Lutaml::Model::Serializable
       attribute :self_attr, :string
       attribute :name, :string
@@ -15,6 +21,28 @@ module Idml
       attribute :fill_color, :string
       attribute :stroke_color, :string
       attribute :stroke_weight, :float
+
+      # Schema-faithful layout attributes (from Table_Object in
+      # Stories/Story.rnc). The renderer consults these to compute
+      # column widths and to clip body/header/footer regions.
+      attribute :header_row_count, :integer
+      attribute :footer_row_count, :integer
+      attribute :body_row_count, :integer
+      attribute :column_count, :integer
+      attribute :single_column_width, :float
+      attribute :table_direction, :string
+
+      # Outer-border strokes (TopBorderStrokeWeight, etc.). Useful
+      # when the renderer draws the table's bounding rectangle.
+      attribute :top_border_stroke_weight, :float
+      attribute :top_border_stroke_color, :string
+      attribute :left_border_stroke_weight, :float
+      attribute :left_border_stroke_color, :string
+      attribute :bottom_border_stroke_weight, :float
+      attribute :bottom_border_stroke_color, :string
+      attribute :right_border_stroke_weight, :float
+      attribute :right_border_stroke_color, :string
+
       attribute :table_row, Idml::Elements::TableRow, collection: true
       attribute :cell, Idml::Elements::Cell, collection: true
       attribute :row, Idml::Elements::Row, collection: true
@@ -30,6 +58,22 @@ module Idml
         map_attribute "FillColor", to: :fill_color
         map_attribute "StrokeColor", to: :stroke_color
         map_attribute "StrokeWeight", to: :stroke_weight
+        map_attribute "HeaderRowCount", to: :header_row_count
+        map_attribute "FooterRowCount", to: :footer_row_count
+        map_attribute "BodyRowCount", to: :body_row_count
+        map_attribute "ColumnCount", to: :column_count
+        map_attribute "SingleColumnWidth", to: :single_column_width
+        map_attribute "TableDirection", to: :table_direction
+        map_attribute "TopBorderStrokeWeight", to: :top_border_stroke_weight
+        map_attribute "TopBorderStrokeColor", to: :top_border_stroke_color
+        map_attribute "LeftBorderStrokeWeight", to: :left_border_stroke_weight
+        map_attribute "LeftBorderStrokeColor", to: :left_border_stroke_color
+        map_attribute "BottomBorderStrokeWeight",
+                      to: :bottom_border_stroke_weight
+        map_attribute "BottomBorderStrokeColor",
+                      to: :bottom_border_stroke_color
+        map_attribute "RightBorderStrokeWeight", to: :right_border_stroke_weight
+        map_attribute "RightBorderStrokeColor", to: :right_border_stroke_color
         map_element "TableRow", to: :table_row
         map_element "Cell", to: :cell
         map_element "Row", to: :row

data/lib/idml/render/character_style.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Applies character-level styling from a `StyleResolver::StyledRun`
+    # around a text-emitting block. Centralizes the IDML → PDF mapping
+    # for run-level visual properties (text color, underline rule,
+    # strike-through rule, capitalization, super/subscript position).
+    #
+    # Used by `TextFrameRenderer` so character-level effects live in
+    # one place (DRY). The block typically calls `canvas.text` (or
+    # `canvas.text_rich`); this helper sets the surrounding graphics
+    # state and emits the rule lines after the block returns.
+    module CharacterStyle
+      UNDERLINE_THICKNESS_FACTOR = 0.05
+      UNDERLINE_DROP_FACTOR = 0.10
+      STRIKE_THICKNESS_FACTOR = 0.05
+      STRIKE_RISE_FACTOR = 0.25
+
+      # Yields with the run's fill color applied, then draws underline
+      # and/or strike-through rules above/below the text baseline.
+      # `x`, `y`, `width`, `size` describe the line's geometry so the
+      # rules can be positioned correctly.
+      def self.apply(canvas, run, context, x:, y:, width:, size:)
+        apply_fill_color(canvas, run, context)
+        yield
+        draw_underline(canvas, run, x, y, width, size)
+        draw_strike_through(canvas, run, x, y, width, size)
+      end
+
+      # Transforms the text per the CSR's Capitalization attribute.
+      # AllCaps/SmallCaps → uppercase (true small-caps would require
+      # an OpenType feature; deferred). Other values pass through.
+      def self.transform_text(text, capitalization)
+        return text unless %w[AllCaps SmallCaps].include?(capitalization)
+
+        text.upcase
+      end
+
+      # Returns `[font_size, baseline_offset]` for the CSR's Position
+      # attribute. Superscript/subscript shrink the font and shift
+      # the baseline. Normal / nil returns the size unchanged.
+      def self.position_scale(position, font_size)
+        case position
+        when "Superscript" then [font_size * 0.583, font_size * 0.333]
+        when "Subscript" then [font_size * 0.583, -font_size * 0.0833]
+        else [font_size, 0.0]
+        end
+      end
+
+      def self.apply_fill_color(canvas, run, context)
+        return unless run.fill_color
+        return if run.fill_color == "Color/None"
+
+        color = context.color_resolver&.resolve(run.fill_color)
+        return unless color
+
+        canvas.fill_color(ColorHelper.to_canvas(color))
+      end
+      private_class_method :apply_fill_color
+
+      def self.draw_underline(canvas, run, x, y, width, size)
+        return unless run.underline
+
+        thickness = rule_thickness(run.underline_weight, size,
+                                   UNDERLINE_THICKNESS_FACTOR)
+        drop = rule_offset(run.underline_offset, size,
+                           UNDERLINE_DROP_FACTOR)
+        canvas.rectangle(x, y - drop, width, thickness)
+        canvas.fill
+      end
+      private_class_method :draw_underline
+
+      def self.draw_strike_through(canvas, run, x, y, width, size)
+        return unless run.strike_thru
+
+        thickness = rule_thickness(run.strike_through_weight, size,
+                                   STRIKE_THICKNESS_FACTOR)
+        rise = rule_offset(run.strike_through_offset, size,
+                           STRIKE_RISE_FACTOR)
+        canvas.rectangle(x, y + rise - thickness, width, thickness)
+        canvas.fill
+      end
+      private_class_method :draw_strike_through
+
+      def self.rule_thickness(declared, size, factor)
+        declared&.positive? ? declared : (size * factor)
+      end
+      private_class_method :rule_thickness
+
+      def self.rule_offset(declared, size, factor)
+        return size * factor unless declared
+        return size * factor if declared.zero?
+
+        declared
+      end
+      private_class_method :rule_offset
+    end
+  end
+end

data/lib/idml/render/font_setup.rb

@@ -66,6 +66,15 @@ module Idml
         map
       end
 
+      # True if at least one non-missing font declared in the
+      # document can be located on disk. Lets callers (and tests)
+      # gate font-embedding assertions on the document's fonts
+      # actually being installed, rather than silently falling
+      # back to the default.
+      def font_resolvable?
+        !resolve_document_font_path.nil?
+      end
+
       def resource_for_family(writer, family)
         path = find_font_file(family)
         return DEFAULT_FONT unless path

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

@@ -4,9 +4,8 @@ module Idml
   module Render
     module Renderers
       # Renders an IDML Table. Draws the cell grid via rectangle
-      # ops, then renders inline text in each cell via
-      # `canvas.text_rich`. Cells with no text render as empty
-      # rectangles.
+      # ops, then renders inline text in each cell. Cells with no
+      # text render as empty rectangles.
       #
       # Two table layouts are supported:
       #
@@ -19,9 +18,20 @@ module Idml
       #      `table_cell` collection. Nested structure.
       #
       # The renderer auto-detects which layout is present.
+      #
+      # Honors per-cell:
+      # - `fill_color` / `fill_tint` — background fill before stroke.
+      # - `top_inset` / `left_inset` / `bottom_inset` / `right_inset`
+      #   — text insets (replaces fixed `INSET = 4.0`).
+      # - `vertical_justification` — Top / Center / Bottom / Justify.
+      # - `paragraph_style_range` → typed runs (per-run font + size).
+      #
+      # Honors per-table:
+      # - `single_column_width` — overrides the even-division default
+      #   for column widths.
       class TableRenderer
         DEFAULT_SIZE = 10.0
-        INSET = 4.0
+        DEFAULT_INSET = 4.0
 
         def self.render(canvas, context)
           table = context.item
@@ -57,17 +67,42 @@ module Idml
 
         # Real IDML: Table > {Cell, Row} siblings. Cell Name is
         # "col:row". Row count from `row` collection; column count
-        # derived from max col + 1 across cells.
+        # derived from `column_count` attribute or max col + 1.
         def self.render_schema_faithful(canvas, table, box, context)
           layout = SchemaLayout.new(table: table, box: box)
           layout.each_cell do |cell_x, cell_y, cell_w, cell_h, cell|
-            canvas.rectangle(cell_x, cell_y, cell_w, cell_h)
-            canvas.stroke
+            render_cell_background(canvas, cell, cell_x, cell_y, cell_w, cell_h,
+                                   context)
+            render_cell_border(canvas, cell_x, cell_y, cell_w, cell_h)
             render_cell_text(canvas, cell, cell_x, cell_y, cell_h, context)
           end
         end
         private_class_method :render_schema_faithful
 
+        def self.render_cell_background(canvas, cell, x, y, w, h, context)
+          color = cell_fill_color(cell, context)
+          return unless color
+
+          canvas.fill_color(ColorHelper.to_canvas(color))
+          canvas.rectangle(x, y, w, h)
+          canvas.fill
+        end
+        private_class_method :render_cell_background
+
+        def self.render_cell_border(canvas, x, y, w, h)
+          canvas.rectangle(x, y, w, h)
+          canvas.stroke
+        end
+        private_class_method :render_cell_border
+
+        def self.cell_fill_color(cell, context)
+          return nil unless cell.fill_color
+          return nil if cell.fill_color == "Color/None"
+
+          context.color_resolver&.resolve(cell.fill_color)
+        end
+        private_class_method :cell_fill_color
+
         # Legacy: Table > TableRow > TableCell nested.
         def self.render_legacy(canvas, table, box, context)
           return if table.table_row.empty?
@@ -93,33 +128,122 @@ module Idml
         private_class_method :render_legacy
 
         def self.render_cell_text(canvas, cell, x, y, height, context)
+          runs = cell_text_runs(cell, context)
+          return if runs.empty?
+
+          insets = cell_insets(cell)
+          baseline = vertical_baseline(y, height, insets, cell)
+          canvas.text_rich(runs, at: [x + insets[:left], baseline])
+        end
+        private_class_method :render_cell_text
+
+        # Builds pdfrb runs from the cell's typed PSR/CSR children.
+        # Walks ParagraphStyleRange → CharacterStyleRange → Content
+        # so each run carries its own font + size (per-cell CSR
+        # styling). Falls back to a single DEFAULT_SIZE run when
+        # the cell has no typed paragraphs (legacy TableCell).
+        def self.cell_text_runs(cell, context)
+          psr = typed_paragraphs(cell)
+          return default_text_runs(cell, context) if psr.empty?
+
+          psr.flat_map { |paragraph| paragraph_runs(paragraph, context) }
+        end
+        private_class_method :cell_text_runs
+
+        def self.paragraph_runs(paragraph, context)
+          paragraph.character_style_range.filter_map do |csr|
+            text = csr.text_content
+            next if text.nil? || text.empty?
+
+            {
+              text: text,
+              font: context.font_ps_name,
+              size: csr.point_size || DEFAULT_SIZE,
+            }
+          end
+        end
+        private_class_method :paragraph_runs
+
+        # Real IDML `Cell` exposes paragraph_style_range; the legacy
+        # `TableCell` (synthetic fixture only) doesn't, so we treat
+        # it as having no typed paragraphs and fall through to the
+        # default_text_runs path.
+        def self.typed_paragraphs(cell)
+          return [] unless cell.is_a?(Idml::Elements::Cell)
+
+          cell.paragraph_style_range
+        end
+        private_class_method :typed_paragraphs
+
+        def self.default_text_runs(cell, context)
           text = cell.text_content
-          return if text.nil? || text.empty?
+          return [] if text.nil? || text.empty?
 
-          runs = [{
+          [{
             text: text,
             font: context.font_ps_name,
             size: DEFAULT_SIZE,
           }]
-          baseline = y + (height / 2)
-          canvas.text_rich(runs, at: [x + INSET, baseline])
         end
-        private_class_method :render_cell_text
+        private_class_method :default_text_runs
+
+        # Cell insets: prefer typed TextTopInset/Left/Bottom/Right,
+        # fall back to DEFAULT_INSET for any that are missing.
+        def self.cell_insets(cell)
+          {
+            top: cell.top_inset || DEFAULT_INSET,
+            bottom: cell.bottom_inset || DEFAULT_INSET,
+            left: cell.left_inset || DEFAULT_INSET,
+            right: cell.right_inset || DEFAULT_INSET,
+          }
+        end
+        private_class_method :cell_insets
+
+        # Vertical baseline for the cell's first text line, per the
+        # cell's VerticalJustification. IDML values: TopAlign,
+        # CenterAlign, BottomAlign, JustifyAlign. Default: CenterAlign
+        # (legacy behavior).
+        def self.vertical_baseline(y, height, insets, cell)
+          case cell.vertical_justification
+          when "TopAlign"
+            y + height - insets[:top]
+          when "BottomAlign"
+            y + insets[:bottom]
+          else # CenterAlign, JustifyAlign, nil
+            y + (height / 2)
+          end
+        end
+        private_class_method :vertical_baseline
 
         # Computes per-cell rects for the schema-faithful layout.
         # Row heights come from `Row#single_row_height` when present,
         # else fall back to evenly-divided table height. Column
-        # widths are evenly divided (precise column widths would
-        # require ColumnAttributes lookup, deferred).
+        # widths come from `Table#single_column_width` when present
+        # (uniform columns only — per-column widths would require
+        # ColumnAttributes, which IDML doesn't model separately),
+        # else divide evenly.
+        #
+        # Honors `Cell#column_span` and `Cell#row_span`: a spanning
+        # cell covers multiple grid positions and is rendered once
+        # at its top-left corner with the merged rect. Cells covered
+        # by another cell's span are skipped.
         SchemaLayout = Struct.new(:table, :box, keyword_init: true) do
           def each_cell
+            covered = Set.new
+
             row_count.times do |row_idx|
               col_count.times do |col_idx|
+                next if covered.include?([col_idx, row_idx])
+
                 cell = cell_at(col_idx, row_idx)
                 next unless cell
 
-                yield cell_x(col_idx), cell_y(row_idx), cell_w, cell_h(row_idx),
-                      cell
+                col_span = cell.column_span || 1
+                row_span = cell.row_span || 1
+                mark_covered(covered, col_idx, row_idx, col_span, row_span)
+
+                yield cell_x(col_idx), cell_y(row_idx, col_span, row_span),
+                      cell_w(col_span), cell_h(row_idx, row_span), cell
               end
             end
           end
@@ -130,11 +254,16 @@ module Idml
 
           def col_count
             @col_count ||= begin
-              max_col = cells.filter_map(&:col_row).map(&:first).max || 0
-              max_col + 1
+              declared = table.column_count
+              declared&.positive? ? declared : derived_col_count
             end
           end
 
+          def derived_col_count
+            max_col = cells.filter_map(&:col_row).map(&:first).max || 0
+            max_col + 1
+          end
+
           def rows
             table.row
           end
@@ -147,20 +276,52 @@ module Idml
             cells.find { |c| c.col_row == [col, row] }
           end
 
+          def mark_covered(covered, col, row, col_span, row_span)
+            col_span.times do |dc|
+              row_span.times do |dr|
+                covered << [col + dc, row + dr]
+              end
+            end
+          end
+          private :mark_covered
+
           def cell_x(col)
-            box[:x] + (col * cell_w)
+            box[:x] + (col * per_col_width)
           end
 
-          def cell_y(row)
-            box[:y] + total_height - cumulative_height(row) - cell_h(row)
+          # PDF-coordinate bottom y of the cell's rectangle. For a
+          # row_spanning cell, this is the bottom edge of the last
+          # spanned row. PDF rectangle takes (x, y_bottom, w, h).
+          def cell_y(row, _col_span, row_span)
+            last_row = row + row_span - 1
+            box[:y] + total_height - cumulative_height(last_row + 1)
           end
 
-          def cell_w
-            box[:width] / [col_count, 1].max
+          # Width covered by `span` columns starting at the cell's col.
+          def cell_w(span)
+            per_col_width * (span || 1)
           end
 
-          def cell_h(row_idx)
-            row_heights[row_idx] || (box[:height] / [row_count, 1].max)
+          # Total height covered by `span` rows starting at `row_idx`.
+          def cell_h(row_idx, span)
+            (span || 1).times.sum { |i| row_height(row_idx + i) }
+          end
+
+          def per_col_width
+            return @per_col_width if @per_col_width
+
+            declared = table.single_column_width
+            @per_col_width = if declared&.positive?
+                               declared
+                             else
+                               box[:width] / [col_count, 1].max
+                             end
+          end
+
+          def row_height(idx)
+            return 0.0 unless idx.between?(0, row_count - 1)
+
+            row_heights[idx] || (box[:height] / [row_count, 1].max)
           end
 
           def row_heights
@@ -171,11 +332,11 @@ module Idml
           end
 
           def total_height
-            @total_height ||= row_count.times.sum { |i| cell_h(i) }
+            @total_height ||= row_count.times.sum { |i| row_height(i) }
           end
 
           def cumulative_height(up_to_row)
-            up_to_row.times.sum { |i| cell_h(i) }
+            up_to_row.times.sum { |i| row_height(i) }
           end
         end
         private_constant :SchemaLayout