idml 0.10.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13770ed8937eeed41a40bd223bb8caadc833da870858d691caa0e1806058c286
-  data.tar.gz: dec0fe8f24c1aaa8258ecf18506560b1e0793bd7d4ebe56bf361dc1a69ff736a
+  metadata.gz: e7360c896ca2b95a5fa92dd030c71e3170b0f26039f5b48938f3ba038405bc46
+  data.tar.gz: 1ce5fccd66f88f3dc5a25289e844cdfd99b391279f8bf8f659d74de9488c866e
 SHA512:
-  metadata.gz: '0394efac9722c854cd4e8c2771d0ec494aaa8d3b50ca6ea471bbe8f5f44daf62a1f1bd4d12031ee9d59b0d7b6c5f65f5378db661d5a110d056734958369a870e'
-  data.tar.gz: 07d3a9492ea5a41819f4fe0353176671307ad7263feedeb909bd08f8284eb79b84df0fef0057db1d089a3a02ff7d255459ea2e232e5c929d3d1ffccc70685e81
+  metadata.gz: e9aaaa8864f60931ebf50be726503f2b9db6313135262aa6d740d6fda4e06a57b03b8970aaaa87eddcd29a82e562cf0bd0ee56df227c2729782f276bca447e06
+  data.tar.gz: b4a07f57002002cc027fb1459b9524107f1fc309a1d34cbb23575416054488589e355b4bc0a548ee59f6d69e50225dc2a8a021f4848007d9f04820b3925af778

data/TODO.pdf/114-text-wrap-around-shapes.md

@@ -1,6 +1,8 @@
 # TODO PDF 114: Text wrap around shapes (TextWrapPreference)
 
-## Status: DONE for BoundingBox mode — `Render::TextWrapResolver` computes
+## Status: COMPLETE for BoundingBoxTextWrap + Contour (Contour and
+the schema-spelling enum fix landed 2026-08-23 as TODO 130; Inverse
+mode remains open) — `Render::TextWrapResolver` computes
 wrap contours from page items declaring TextWrapPreference with
 TextWrapMode != "None". SpreadRenderer builds the resolver and passes
 it via RenderContext. TextFrameRenderer's `text_wrap_overlap` queries

data/TODO.pdf/130-contour-text-wrap.md

@@ -0,0 +1,38 @@
+# TODO PDF 130: Shape-mode (Contour) text wrap
+
+## Status: COMPLETE — implemented 2026-08-23
+
+## Problem
+
+Two gaps in the text wrap (TODO 114):
+
+1. The TextWrapMode dispatch compared against "BoundingBox" — the
+   schema enum (TextWrapModes_EnumValue in datatype.rnc) spells it
+   "BoundingBoxTextWrap", so REAL documents never matched any mode
+   and text never wrapped.
+2. Contour mode (text following the item's actual shape) was not
+   implemented at all.
+
+## What was done
+
+- Enum fix: BoundingBoxTextWrap accepted (legacy "BoundingBox"
+  spelling kept for the synthetic fixtures); JumpObjectTextWrap /
+  NextColumnTextWrap approximate as the bounding box (the per-run
+  width reduction already pushes text past the object);
+  Contour gets real contour following.
+- `Render::WrapContour`: flattens the item's PathGeometry (Bézier
+  segments sampled at 8 steps, ItemTransform applied, y flipped)
+  into PDF-space polygons — one per subpath, so compound paths
+  with holes work via even-odd ray casting at the text band's
+  midline. The overlap intervals expand by the TextWrapOffset
+  bounds (`Properties > TextWrapOffset`, now modeled on
+  TextWrapPreference via TypedValue) and clip to the frame.
+- `TextWrapResolver` dispatches per mode; overlap_width handles
+  both the box rect and polygon shapes.
+
+## Known limitations
+
+- Band coverage samples the midline (sub-half-line-height notches
+  are missed); offsets expand intervals uniformly rather than
+  offsetting the polygon geometrically; Inverse mode is not
+  implemented (falls back to no wrap).

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

@@ -22,8 +22,9 @@ this list reflects the current state.
   (TODO 128); CapHeight / XHeight approximate as leading.
 - **StartParagraph** breaks act at frame/column granularity — no
   odd/even page parity.
-- **Text wrap** (TODO 114): BoundingBox mode only; Shape contour
-  following and Inverse mode are not implemented.
+- **Text wrap**: BoundingBoxTextWrap and Contour modes render
+  (TODO 130); JumpObject/NextColumn approximate as the box;
+  Inverse mode is not implemented.
 
 ### CJK
 - **Mojikumi**: CJK/Latin auto script spacing is applied (TODO

data/lib/idml/elements/properties.rb

@@ -16,6 +16,7 @@ module Idml
       attribute :rule_below_color, Idml::Elements::TypedValue
       attribute :paragraph_shading_color, Idml::Elements::TypedValue
       attribute :paragraph_border_color, Idml::Elements::TypedValue
+      attribute :text_wrap_offset, Idml::Elements::TypedValue
       attribute :paragraph_border_gap_color, Idml::Elements::TypedValue
 
       xml do
@@ -26,6 +27,7 @@ module Idml
         map_element "RuleBelowColor", to: :rule_below_color
         map_element "ParagraphShadingColor", to: :paragraph_shading_color
         map_element "ParagraphBorderColor", to: :paragraph_border_color
+        map_element "TextWrapOffset", to: :text_wrap_offset
         map_element "ParagraphBorderGapColor", to: :paragraph_border_gap_color
       end
 

data/lib/idml/elements/text_wrap_preference.rb

@@ -11,6 +11,7 @@ module Idml
       attribute :apply_to_master_page_only, :boolean
       attribute :text_wrap_side, :string
       attribute :text_wrap_mode, :string
+      attribute :properties, Idml::Elements::Properties, collection: true
 
       xml do
         root "TextWrapPreference"
@@ -18,6 +19,7 @@ module Idml
         map_attribute "ApplyToMasterPageOnly", to: :apply_to_master_page_only
         map_attribute "TextWrapSide", to: :text_wrap_side
         map_attribute "TextWrapMode", to: :text_wrap_mode
+        map_element "Properties", to: :properties
       end
     end
   end

data/lib/idml/render/text_wrap_resolver.rb

@@ -43,17 +43,36 @@ module Idml
       # Returns 0.0 when there's no overlap.
       def overlap_width(line_y, line_height, frame_x, frame_right)
         @contours.sum do |contour|
-          overlap = line_overlap(contour, line_y, line_height,
-                                 frame_x, frame_right)
-          overlap[:width]
+          if contour.is_a?(WrapContour::Shape)
+            WrapContour.overlap_width(contour, line_y, line_height,
+                                      frame_x, frame_right)
+          else
+            line_overlap(contour, line_y, line_height,
+                         frame_x, frame_right)[:width]
+          end
         end
       end
 
+      # The wrap shape for an item: a bounding-box rectangle
+      # (BoundingBoxTextWrap — the legacy "BoundingBox" spelling is
+      # also accepted from early synthetic fixtures) or a flattened
+      # PathGeometry polygon (Contour mode). JumpObject /
+      # NextColumn modes approximate as the bounding box (the
+      # per-run width reduction already pushes text past the
+      # object).
       def self.contour_for(item, page_height)
         pref = wrap_preference(item)
         return nil unless pref
-        return nil unless bounding_box_mode?(pref)
 
+        if contour_mode?(pref)
+          WrapContour.shape(item, pref, page_height)
+        else
+          box_contour(item, page_height)
+        end
+      end
+      private_class_method :contour_for
+
+      def self.box_contour(item, page_height)
         bounds = item.geometric_bounds
         return nil unless bounds
 
@@ -64,7 +83,7 @@ module Idml
           width: rect[:width], height: rect[:height]
         )
       end
-      private_class_method :contour_for
+      private_class_method :box_contour
 
       # Page item types that can declare TextWrapPreference per the
       # Spread schema. Used to guard the attribute read — querying
@@ -95,10 +114,10 @@ module Idml
       end
       private_class_method :wrappable?
 
-      def self.bounding_box_mode?(pref)
-        pref.text_wrap_mode == "BoundingBox"
+      def self.contour_mode?(pref)
+        pref.text_wrap_mode == "Contour"
       end
-      private_class_method :bounding_box_mode?
+      private_class_method :contour_mode?
 
       def line_overlap(contour, line_y, line_height, frame_x, frame_right)
         return { width: 0.0 } unless y_overlap?(contour, line_y, line_height)

data/lib/idml/render/wrap_contour.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Shape-mode text wrap: builds a PDF-space polygon from a page
+    # item's PathGeometry (Bézier segments flattened at a fixed
+    # resolution) and measures the horizontal overlap of a text
+    # line's band with the polygon, expanded by the wrap offsets.
+    # Band coverage uses even-odd ray casting at the band's
+    # midline, so compound paths with holes wrap correctly.
+    module WrapContour
+      FLATTEN_STEPS = 8
+
+      # A wrap shape: flattened polygons (one per subpath) plus the
+      # TextWrapOffset bounds.
+      Shape = Struct.new(:polygons, :offset, keyword_init: true)
+
+      # Builds the wrap shape for an item's PathGeometry and wrap
+      # preference. Returns nil when the item has no geometry.
+      def self.shape(item, pref, page_height)
+        polygons = polygons_for(item, page_height)
+        return nil if polygons.empty?
+
+        Shape.new(polygons: polygons, offset: wrap_offset(pref))
+      end
+
+      def self.polygons_for(item, page_height)
+        transform = Geometry.parse_transform(item.item_transform)
+        paths = item.properties.flat_map do |props|
+          props.path_geometry.flat_map(&:geometry_path_type)
+        end
+        paths.filter_map do |path|
+          points = flatten_path(path, transform, page_height)
+          points.length >= 3 ? points : nil
+        end
+      end
+      private_class_method :polygons_for
+
+      # Flattens one subpath's Bézier segments into line segments
+      # in PDF space (ItemTransform applied, y flipped).
+      def self.flatten_path(path, transform, page_height)
+        anchors = path.points
+        return [] if anchors.length < 2
+
+        open = path.path_open == true
+        segments = open ? anchors.length - 1 : anchors.length
+        points = [pdf_point(anchors.first, transform, page_height)]
+        segments.times do |index|
+          from = anchors[index]
+          to = anchors[(index + 1) % anchors.length]
+          append_segment(points, from, to, transform, page_height)
+        end
+        points
+      end
+      private_class_method :flatten_path
+
+      def self.append_segment(points, from, to, transform, page_height)
+        c1 = pair_or_nil(from, :right_direction, transform, page_height)
+        c2 = pair_or_nil(to, :left_direction, transform, page_height)
+        start = points.last
+        if c1.nil? && c2.nil?
+          points << pdf_point(to, transform, page_height)
+          return
+        end
+
+        c1 ||= start
+        c2 ||= pdf_point(to, transform, page_height)
+        (1..FLATTEN_STEPS).each do |step|
+          t = step.to_f / FLATTEN_STEPS
+          points << bezier_point(start, c1, c2,
+                                 pdf_point(to, transform, page_height), t)
+        end
+      end
+      private_class_method :append_segment
+
+      def self.bezier_point(p0, p1, p2, p3, t)
+        u = 1 - t
+        w0 = u * u * u
+        w1 = 3 * u * u * t
+        w2 = 3 * u * t * t
+        w3 = t * t * t
+        [
+          (w0 * p0[0]) + (w1 * p1[0]) + (w2 * p2[0]) + (w3 * p3[0]),
+          (w0 * p0[1]) + (w1 * p1[1]) + (w2 * p2[1]) + (w3 * p3[1]),
+        ]
+      end
+      private_class_method :bezier_point
+
+      def self.pair_or_nil(point, direction_attr, transform, page_height)
+        raw = point.public_send(direction_attr)
+        raw = nil if raw && raw.strip.empty?
+        raw && pdf_pair(raw, transform, page_height)
+      end
+      private_class_method :pair_or_nil
+
+      def self.pdf_point(point, transform, page_height)
+        pdf_pair(point.anchor, transform, page_height)
+      end
+      private_class_method :pdf_point
+
+      def self.pdf_pair(raw, transform, page_height)
+        x, y = raw.to_s.split(/\s+/).map(&:to_f)
+        tx, ty = Geometry.apply_transform(transform, x, y)
+        [tx, page_height - ty]
+      end
+      private_class_method :pdf_pair
+
+      # The wrap offsets from Properties > TextWrapOffset
+      # ("top left bottom right"); zero when absent.
+      def self.wrap_offset(pref)
+        raw = pref.properties.first&.text_wrap_offset&.value
+        parts = raw.to_s.split(/\s+/).map(&:to_f)
+        return [0.0, 0.0] if parts.length < 4
+
+        [parts[1], parts[3]] # left, right
+      end
+      private_class_method :wrap_offset
+
+      # Total horizontal overlap of the text line's band with the
+      # shape, expanded by the offsets and clipped to the frame.
+      def self.overlap_width(shape, line_y, line_height, frame_x,
+                             frame_right)
+        mid_y = line_y + (line_height / 2.0)
+        width = shape.polygons.sum do |polygon|
+          polygon_overlap(polygon, mid_y, shape.offset)
+        end
+        clip_width(width, frame_x, frame_right)
+      end
+
+      # Even-odd intervals at mid_y expanded by [left, right]
+      # offsets, summed (separate subpaths sum; the common case is
+      # one polygon).
+      def self.polygon_overlap(polygon, mid_y, offset)
+        crossings = edge_crossings(ring(polygon), mid_y).sort
+        return 0.0 if crossings.length < 2
+
+        left, right = offset
+        crossings.each_slice(2).sum do |entry_x, exit_x|
+          (exit_x + right) - (entry_x - left)
+        end
+      end
+      private_class_method :polygon_overlap
+
+      # Closes the polygon ring (each_cons alone misses the
+      # last→first edge).
+      def self.ring(polygon)
+        polygon + [polygon.first]
+      end
+      private_class_method :ring
+
+      def self.edge_crossings(points, mid_y)
+        points.each_cons(2).filter_map do |(x1, y1), (x2, y2)|
+          next unless crosses_midline?(y1, y2, mid_y)
+
+          t = (mid_y - y1) / (y2 - y1)
+          x1 + (t * (x2 - x1))
+        end
+      end
+      private_class_method :edge_crossings
+
+      def self.crosses_midline?(y1, y2, mid_y)
+        (y1 <= mid_y && y2 > mid_y) || (y2 <= mid_y && y1 > mid_y)
+      end
+      private_class_method :crosses_midline?
+
+      def self.clip_width(width, frame_x, frame_right)
+        [width, frame_right - frame_x].min
+      end
+      private_class_method :clip_width
+    end
+  end
+end

data/lib/idml/render.rb

@@ -25,6 +25,7 @@ module Idml
     autoload :Footnote,            "#{__dir__}/render/footnote"
     autoload :ShapePaint,          "#{__dir__}/render/shape_paint"
     autoload :Contour,             "#{__dir__}/render/contour"
+    autoload :WrapContour,         "#{__dir__}/render/wrap_contour"
     autoload :Placement,           "#{__dir__}/render/placement"
     autoload :ImageCollector,      "#{__dir__}/render/image_collector"
     autoload :StructureTracker,    "#{__dir__}/render/structure_tracker"

data/lib/idml/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.1
 platform: ruby
 authors:
 - Ribose
@@ -189,6 +189,7 @@ files:
 - TODO.pdf/128-first-baseline-offset.md
 - TODO.pdf/129-justification-glyph-scaling.md
 - TODO.pdf/13-cjk-text-layout.md
+- TODO.pdf/130-contour-text-wrap.md
 - TODO.pdf/14-page-item-element-models.md
 - TODO.pdf/15-wire-spread-children.md
 - TODO.pdf/16-typed-model-pipeline.md
@@ -497,6 +498,7 @@ files:
 - lib/idml/render/style_lookup.rb
 - lib/idml/render/style_resolver.rb
 - lib/idml/render/text_wrap_resolver.rb
+- lib/idml/render/wrap_contour.rb
 - lib/idml/text_engine.rb
 - lib/idml/text_engine/cjk_layout.rb
 - lib/idml/text_engine/justifier.rb